publish command

The publish command is the primary way to insert messages into the AMPS processing stream. A publish command received by AMPS will be forwarded to other connected clients with matching subscriptions.

Depending on the server configuration, a publish command may also be used to update the State of the World, written to the transaction log, replicated to other instances, and so on.

In AMPS, the publisher is only responsible for delivering the message to AMPS reliably. The AMPS server configuration manages routing the message to subscribers, determining if the message should be persisted, updating any state that the message affects, and so on.

Header Fields

The following table contains the header fields available to a publish command.

Field	Description
cmd	Command to be executed. Value: publish
topic	The topic to publish the message to.
ack_type	Acknowledgment type for the given command. Value is a comma separated list of one of more of the following: none, received, persisted or processed.
cmd_id	If specified with an AMPS command requesting an acknowledgment message in response to the publish command, all requested acknowledgment messages will contain the CommandId in the response header.
expiration	An interval in seconds, used to define the lifetime of a publish message.
seq	A monotonically increasing identifier used in high availability configurations to determine message uniqueness across replicas.
correlation_id	A user-provided string that will be passed, verbatim, to subscribers. If this header is not present, subscribers receive no value for the correlation_id. The contents of this header must consist of characters that are legal in Base64 encoding.
sow_key	For SOW topics that use an explicit key, the SOW key to use for the message. The contents of this header must consist of characters that are legal in Base64 encoding.

Returns

A client which issues a publish can request a processed acknowledgment message; however this is not recommended as there is a significant performance overhead associated with this. The following table contains the AckType messages which can be returned by a publish.

In general, 60East recommends only requesting persisted acknowledgments for publish commands, since these acknowledgments can be conflated when commands succeed.

Acknowledgment	Description
none	No ack message is returned. This is the default behavior.
completed	AMPS has processed the message and, if necessary, enqueued the message for persistence and replication. This acknowledgment includes the steps acknowledged by the processed acknowledgment.
persisted	When AMPS returns an acknowledgment message of persisted, it guarantees that: All downstream synchronous replications have acknowledged that the message(s) have been delivered to their respective SOW Topic(s). When the publish message has been sent to all available downstream asynchronous replications. If no replication is configured for this topic, this acknowledgment applies only to local persistence. If no persistence is configured for this topic, this acknowledgment is still provided when requested. AMPS conflates successful persisted acknowledgments to acknowledge multiple publishes at once. In this case, the seq provided means that the message with that sequence number, and all previous messages from this publisher, have been acknowledged.
processed	AMPS has processed the publish message. Any errors which occur while processing will be returned to the client in this acknowledgment message. This includes processing entitlement checks, and parsing the message if parsing is necessary, but does not guarantee that the message has been replicated or persisted.
received	The publish message has been received.
stats	Not supported at this time.

Errors

Any errors that occur while processing this command will be returned in the status of a processed acknowledgment message and logged to the log file. Regardless of success or failure, the processed acknowledgment message will be returned only if requested by specifying processed in the AckType field.

Errors that occur during the processing command or after processing the command will be returned in the status of a persisted acknowledgment message if one is requested. This acknowledgment is returned at the point that the message can be considered safely persisted in AMPS. Notice that AMPS may conflate successful persisted acknowledgments for publishes. See the AMPS User Guide for details.