Skip to main content

Documentation Index

Fetch the complete documentation index at: https://s2.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Conditional appends coordinate writers against a durable stream. They let a writer append only when the stream is at an expected position or when the writer holds the expected fencing token. This is useful for single-writer systems that need safe failover. A replacement writer can inspect the stream, determine the next expected position, and use a conditional append to avoid writing against stale state.

​
Mechanisms

The append API supports two concurrency-control mechanisms:

​
Match sequence number

Specifying expected current state allows optimistic concurrency control. You can provide the sequence number that you expect S2 to assign to the first record in a batch as the match_seq_num. If it does not match, this will result in a 412 Precondition Failed status or corresponding SDK error type.
Conditional appends with an appropriate retry policy can be used to achieve “exactly-once” semantics.

​
Fencing tokens

Fencing is a form of pessimistic concurrency control. It is a cooperative mechanism, so an append that does not specify a fencing token will still be allowed. When an append does include a fencing_token and it does not match, this results in a 412 Precondition Failed status or corresponding SDK error type.
Setting the fencing token requires appending a fence command record.

​
Fencing example

Set a fencing token via the CLI: 
s2 fence s2://my-basin/my-stream "writer-1"
Subsequent appends that specify a token will be rejected if it doesn’t match: 
s2 append s2://my-basin/my-stream -f "writer-1"
Fencing tokens can be up to 36 UTF-8 bytes. An empty token clears the fence. Fencing is strongly consistent — once set, subsequent appends specifying a different token are immediately rejected.

​
Failure handling

Append condition failures return structured 412 error bodies that identify the current fencing token or assignable sequence number. In an append session, such a failure poisons the session. Establish a new session before continuing to write.

​
Ownership patterns

Conditional appends enforce write-side preconditions at S2. On the read side, any reader can ensure its knowledge of the stream is current by making a check-tail call. This round-trip can be avoided by a single logical owner of a stream using a lease. The lease itself may be modelled on top of the S2 stream by periodically appending application-level heartbeats identifying the current physical owner.
AWS MemoryDB is built on an internal replicated log primitive that offers conditional appends. See §4 of their paper.S2 exposes this kind of primitive as a serverless cloud resource, so applications can model many durable streams with independent logical owners, including agent sessions and multiplayer rooms.

​
See also

Appends

Understand append acknowledgements, batching, and durability.

Command records

See how S2 applies fence and trim directives from records.

Append condition failures

Inspect structured 412 responses for failed append preconditions.