Skip to main content

publish: Content from Server

AMPS returns a publish message to a client when a new message is published to AMPS that matches one of the subscriptions requested by the client. There are two ways that AMPS can generate publish messages:

  • Single-origin Messages - For subscriptions to topics where AMPS can identify a single source for a publish message, AMPS provides information from that publish message to the subscriber.

    This applies to subscriptions to unpersisted topics, SOW topics, and conflated topic replicas. This does not include subscriptions to views (or conflated topics based on views), since views provide the ability to join multiple topics and aggregate over multiple messages. For conflated topics, the header information provided is the information provided with the message published to the subscriber. For messages produced by delta publish, AMPS will use the information provided on the delta publish except as noted in the table below.

  • Synthetic Messages - In some cases, AMPS must provide a message that is constructed by the server. This happens for views, and for status messages from AMPS.

AMPS provides different values in the header fields depending on the origin of the publish message. For synthetic messages, AMPS does not provide information on the origin of the message, since there may be multiple sources of the message or, in the case of status messages, no external source. Likewise, AMPS does not provide a correlation_id, since that header is set by the publisher for a specific message.

Header Fields

The following table contains the header fields returned in a publish message. Notice that the wire format of the message may abbreviate these field names or encode them differently:

FieldDescription
cmd

Type of message.

Always publish, as encoded by the protocol.

topicThe topic the message was published to.
correlation_id

A publisher-provided string that is passed, verbatim, to subscribers.

If this header is not present, or the message is a synthetic message as described above, subscribers receive no value for the correlation_id.

The contents of this header must consist of characters that are legal in Base64 encoding.

For delta publishes, AMPS uses the correlation_id of the delta publish if one is present. If no correlation_id is present on the publish, AMPS uses the correlation_id of the existing message, if one is present.

If there is no correlation_id on the publish, and there is no correlation_id for the existing message, AMPS does not provide a correlation_id.

user_id

The user_id of the client that published the message.

An authentication module may choose whether to allow subscribers to receive this information.

sids

The set of subscription IDs that produced this message.

When a message matches multiple subscriptions, AMPS may produce a list of subscription IDs for all matching subscriptions.

This header is provided by AMPS. The AMPS Clients process this list and provide a single sub_id for each message provided to message handlers.

bookmarkThe bookmark assigned to this message, if the message was persisted to a transaction log.
timestamp

An ISO-8601 datetime that notes the time the message was processed by this instance of AMPS.

The header is included if the client requested a timestamp for the subscription. The value returned has microsecond resolution. Fractions of a second are represented as decimal values.

leaseperiodFor messages received from a queue, the ISO-8601 datetime that indicates when the lease expires.
msg_lenFor messages that contain a message body (message data), the length of the message body.
sow_keyIf the message was from a topic that uses a SOW, the message includes the sow_key that AMPS uses to uniquely identify the message within the SOW.