# 3. Publishing to AMPS

This section describes commands used to send data to AMPS.

Notice that, for topics in the state of the world, AMPS treats these commands as inserting a new message if one does not already exist, and updating the existing message if a message already exists.

For topics in the transaction log, each `publish` or `delta_publish` will store the current message in the transaction log, just as it would be delivered to subscribers.

## delta_publish

The `delta_publish` command is a way of publishing an incremental update to a record. If a client uses `delta_publish` to publish an update, AMPS first extracts the key fields from the record and does a look up for the record in the SOW. AMPS will then apply the update to the SOW record overwriting any field that has a newer value in the update and appending to the record any new fields that were not previously in the SOW record.

If `delta_publish` is used on a record that does not currently exist in the SOW or if it is used on a topic that does not have a SOW-topic store defined, then `delta_publish` will behave like a standard `publish` command.

A `delta_publish` is transparent to other clients and the merged record will be forwarded to matching subscriptions.

### Header Fields

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

Field | Description
--- | ---
`Command` | Command to be executed. Value: `delta_publish`
`Topic` | The SOW topic to publish the message to.
`AckType` | Acknowledgment type for the given command. Value is a comma separated list of one or more of the following: `none`, `received`, `processed`, `completed` or `stats`.
`CommandId` | If specified with an AMPS command which requests an acknowledgment message, all requested acknowledgment messages will contain the `CommandId` in the `ack` response header.
`Expiration` | An interval used to define the lifetime of a `delta_message` message. Time period is in seconds.
`Sequence` | A monotonically increasing number used to identify published messages in a high availability environment.
`CorrelationId` | A user-provided string that will be passed, verbatim, to subscribers. If this header is not present, subscribers receive no value for the `CorrelationId`. The contents of this header must consist of characters that are legal in Base64 encoding.
`SowKey` | 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.

Header fields used in a delta_publish

### Returns

For a `delta_publish` message, AMPS will send acknowledgment messages for the following `AckType` fields: `received`, `processed` and `persisted` along with a populated `Status` header field describing the acknowledgment.

The following table contains the acknowledgment messages that can be returned by a `delta_publish`.

In general, 60East recommends only requesting `persisted` acknowledgments for `delta_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 acknowledgement includes the steps acknowledged by the `processed` acknowledgement.
`persisted` | When AMPS returns an acknowledgment message of `persisted`, it guarantees that: 1. All downstream synchronous replications have acknowledged that the message(s) have been delivered to their respective SOW Topic(s). 2. When the publish message has been sent to all available downstream asynchronous replications. If no replication is configured for this topic, this acknowledgement applies only to local persistence. If no persistence is configured for this topic, this acknowledgement is still provided when requested.
`processed` | AMPS has processed the message(s) to be published to the SOW. Any errors which occur in the message will be returned to the client in this acknowledgment message. This includes processing entitlement checks, and parsing the message but does not guarantee that the message has been replicated or persisted.
`received` | The `delta_publish` message has been received.
`stats` | Not supported at this time.

Acknowledgment messages supported by delta_publish

### Errors

Any errors that occur during 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.

## publish

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
--- | ---
`Command` | Command to be executed. Value: `publish`.
`Topic` | The topic to publish the message to.
`AckType` | Acknowledgment type for the given command. Value is a comma separated list of one of more of the following: `none`, `received`, `persisted` or `processed`.
`CommandId` | 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.
`SequenceId` | A monotonically increasing identifier used in high availability configurations to determine message uniqueness across replicas.
`CorrelationId` | A user-provided string that will be passed, verbatim, to subscribers. If this header is not present, subscribers receive no value for the `CorrelationId`. The contents of this header must consist of characters that are legal in Base64 encoding.
`SowKey` | 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.

Header fields supported by publish

### 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: 1. All downstream synchronous replications have acknowledged that the message(s) have been delivered to their respective SOW Topic(s). 2. 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.
`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.

Acknowledgment messages supported by publish

### Errors

Any errors that occur during this command will be returned in the status of a `processed` acknowledgment and logged to the log file. Regardless of success or failure, the `processed` acknowledgment will be returned only if the request includes the `processed` in the `AckType` field.