experimental-a2 0.23.0 → 0.24.0

package/docs/contract/03-sessions.mdx

@@ -23,6 +23,57 @@ serve millions of order sessions through the same server and consumers.
 Collections, joins, search, and constraints across many records belong in
 [your database](#sessions-and-your-database).
 
+## Appending from what you read
+
+```ts server/expire-order.ts
+import { A2Error } from 'experimental-a2'
+import { ordersServer } from './orders'
+
+export async function expireOrder({ orderId, seenIndex, requestId }: {
+  orderId: string
+  seenIndex: number
+  requestId: string // the client's id for this request, the same on each retry
+}) {
+  // here's where you'd do auth, or any other checks
+  try {
+    return await ordersServer.session(orderId).append.ifLastIndex(seenIndex, {
+      id: requestId,
+      type: 'expired',
+      payload: {},
+    })
+  } catch (err) {
+    if (err instanceof A2Error && err.code === 'LAST_INDEX_MISMATCH') {
+      // the order changed after it was read: read it again and decide again
+      return null
+    }
+    throw err
+  }
+}
+```
+
+`session.append.ifLastIndex(index, ...events)` appends only while `index` is
+still the session's head, the index of its last event. Pass the head your
+decision was based on: `session.state()` returns it with the state, and an
+append returns each event's index.
+
+The store checks the head in the same atomic step as the write, so of two
+callers that read the same head, at most one lands. The other gets an `A2Error`
+with code `LAST_INDEX_MISMATCH` and nothing written; its `err.details` is
+`{ index }`, the head the store found. Any event moves the head, not only the
+ones your check is about, so a busy session refuses more often.
+
+Give each event an id that is unique to this writer's decision and the same on
+each of its retries, such as an id the client generates for the request. A
+batch whose ids are all in the session already returns its rows whatever the
+head is now, so a retry after a lost response gets the events it wrote. Ids
+built from the index alone are shared by every writer that read it, so they
+fit only when each of those writers would append the same events: otherwise a
+writer whose events happen to match another's gets that writer's rows back as
+its own.
+
+A [clear](#clearing-a-session) moves the head to its marker, so an index read
+before it never matches after it.
+
 ## Clearing a session
 
 ```ts server/clear-order.ts

package/docs/reference/02-server.mdx

@@ -300,7 +300,11 @@ interface A2Store {
   append(
     sessionId: string,
     events: AppendEvent[],
-    options?: { originIndex?: number; consumers?: readonly StoreConsumer[] },
+    options?: {
+      originIndex?: number
+      ifLastIndex?: number
+      consumers?: readonly StoreConsumer[]
+    },
   ): Promise<StoreAppendResult>
 
   cursors(sessionId: string): Promise<StoredCursor[]>
@@ -386,7 +390,7 @@ other consumer is neither pending nor claimed. Omitted, every cursor counts.
 
 | Method | Atomic effect |
 | --- | --- |
-| `append` | Write a consecutive batch. Each event's `targets` start work: a lane target queues the event in that consumer's lane cursor, a null lane creates a cursor for that event alone. Each log consumer in `consumers` whose types the batch carries gets its cursor created (at the start of the log with `backfill`, otherwise just before the batch) or, when idle, a head. Report pending work for the served consumers as `hasPending`. An event with a `cause` commits only while that cursor's head is `cause.index`, `cause.attempt` is its latest attempt, and it isn't dead-lettered; otherwise throw `SUPERSEDED_ATTEMPT`. The check serializes against a concurrent claim, after the idempotent-replay path. |
+| `append` | Write a consecutive batch. Each event's `targets` start work: a lane target queues the event in that consumer's lane cursor, a null lane creates a cursor for that event alone. Each log consumer in `consumers` whose types the batch carries gets its cursor created (at the start of the log with `backfill`, otherwise just before the batch) or, when idle, a head. Report pending work for the served consumers as `hasPending`. An event with a `cause` commits only while that cursor's head is `cause.index`, `cause.attempt` is its latest attempt, and it isn't dead-lettered; otherwise throw `SUPERSEDED_ATTEMPT`. The check serializes against a concurrent claim, after the idempotent-replay path. With `ifLastIndex`, write only while the session's head, its last index including a clear marker, is that index; otherwise throw `LAST_INDEX_MISMATCH` with `details: { index }`, the head. Check it last, after the replay path and both fences, in the same atomic step. Under `ifLastIndex`, ids that conflict (mixed, or not matching their rows) throw `LAST_INDEX_MISMATCH` instead of `PARTIAL_DUPLICATE_BATCH` when the head isn't `ifLastIndex`, read in the same step as the ids. |
 | `cursors` | List every log and lane cursor, and every concurrent cursor that still has a head, by consumer, then lane, with concurrent cursors last by head. Lane and concurrent cursors whose work lies at or below the latest clear marker are not listed. |
 | `claimAvailable` | Claim every eligible head of the served consumers, in event order, then by consumer. A claim records its holder, expiry, timestamps, and next `attemptCount`. Taking over a lapsed claim, one its holder never completed or failed, adds one to `failureCount`; when that reaches `maxFailures`, dead-letter the head instead of claiming it: advance `attemptCount` to fence the lapsed attempt, leave `lastFailedAttempt` unchanged, and return it with `failedAt` set. Excluded heads stay unclaimed and keep blocking their lane. A claim may report `head`, the session's head when the claim was made. |
 | `renewClaims` | Extend the listed live claims the holder still owns. `renewed` lists those; `superseded` lists claims whose head a newer attempt took, or whose cursor moved past it. An expired claim no successor took is in neither and may still complete; renewal never revives it. |
@@ -548,6 +552,40 @@ scheduler instead of starting an inline drain. See
   runs inside an active drain, where its immediate and returned children
   become eligible, so it has no `dispatch`.
 
+### `session.append.ifLastIndex(index, ...events)`
+
+```ts
+session.append.ifLastIndex(
+  index: number,
+  ...events: Array<{ type: string; payload: unknown; id?: string }>
+): Promise<Event[]>
+```
+
+Commits the same atomic batch as `session.append`, only while `index` is still
+the session's head: the index of its last event. See
+[Appending from what you read](/contract/sessions#appending-from-what-you-read).
+
+- The store checks the head in the same atomic step as the write, so of two
+  writers that read the same head, at most one lands.
+- When the head is anything else, nothing is written and nothing runs: it
+  throws an `A2Error` with code `LAST_INDEX_MISMATCH`, and `details` is
+  `{ index }`, the head the store found.
+- A batch whose ids are all in the session already returns its rows, whatever
+  the head is now. Give each event an id unique to this writer's decision and
+  stable across its retries, such as a request id the client generates. Ids
+  built from `index` alone are shared by every writer that read it, so they
+  fit only when each of them would append the same events.
+- Ids that conflict with committed events, in a batch that mixes them with
+  fresh ones or doesn't match the rows they name, throw `LAST_INDEX_MISMATCH`
+  once the head has moved past `index`, as when another writer's batch took
+  them first. While the head is still `index`, they throw
+  `PARTIAL_DUPLICATE_BATCH`.
+- A clear's marker is the head after it, so an index read before a clear never
+  matches after it.
+- `index` is a non-negative safe integer, and the batch has at least one
+  event; otherwise it throws a `TypeError` before writing.
+- Exists only on a server session's top-level append, like `dispatch`.
+
 ### `session.schedule(name, timing, ...events)`
 
 ```ts
@@ -811,8 +849,10 @@ client to resume there. See [State](/contract/state).
   only when later committed events are intentionally part of the decision.
 - A numeric `through` is an inclusive, non-negative safe integer;
   `through: 0` returns the reducer's initial state.
-- A latest read and a following append are not atomic. See
-  [State](/contract/state#reducers) for joins that converge.
+- A read and a following append are not atomic. To append only if nothing has
+  landed since the read, pass its `index` to
+  [`session.append.ifLastIndex`](#sessionappendiflastindexindex-events). In a
+  consumer, see [State](/contract/state#reducers) for joins that converge.
 - Never runs consumers or waits for pending work. Snapshot write-back
   uses platform `waitUntil`, and its failures never fail the completed read:
   they go to `a2.snapshot` telemetry or the default console sink, without

package/docs/reference/06-errors.mdx

@@ -42,6 +42,7 @@ export async function POST(req: Request) {
 | `PARTIAL_DUPLICATE_BATCH` | a batch mixes already-appended and fresh events, or contains the same id twice. Event ids are unique per session, so an id used in another session never conflicts. Always a caller bug; nothing was written | no |
 | `SUPERSEDED_ATTEMPT` | a consumer's append or clear comes from an attempt that a recovery claim or a session clear replaced; nothing was written. Also the abort reason on that attempt's `ctx.signal` | no |
 | `SESSION_CLEARED` | a state read reaches below the latest clear, a consumer reads state past a clear of its event, or an actor call is cleared before it receives its answer | no |
+| `LAST_INDEX_MISMATCH` | [`session.append.ifLastIndex()`](/reference/server#sessionappendiflastindexindex-events) found another head, including when another batch took its ids after the index it read; nothing was written. `details` is `{ index }`, the head it found. Read again and decide again; an identical retry would fail the same way | no |
 | `CLAIM_EXPIRED` | never thrown; only the `ctx.signal` abort reason when the attempt's lease lapsed without renewal (assumed loss, decided locally, not proof) | no |
 | `CONSUMER_DEAD_LETTERED` | `session.consume()` reached an event that dead-lettered for that consumer. Resolve it with `session.redrive()`, then consume again | no |
 | `STORE_UNAVAILABLE` | the store backend failed; nothing was written. The original error is the `cause` | **yes** |

package/examples/playground/app/a2slack/consumers/search.ts

@@ -10,7 +10,7 @@ import { deleteDocument, putDocument, setDocumentText } from '../search-index'
 
 export const searchIndex = consumer({
   contract: workspace,
-  name: 'a2slack-search-v1',
+  name: 'a2slack-search-v2',
   types: ['message.posted', 'message.edited', 'message.deleted'],
   lane: 'search',
   backfill: true,

package/examples/playground/app/a2slack/db/migrations/0005_a2slack_feed_v2.sql

@@ -0,0 +1,7 @@
+-- a2slack-feed-v2 fills these from the start of the log it reads.
+TRUNCATE "a2slack_channels", "a2slack_messages", "a2slack_reactions", "a2slack_notifications", "a2slack_reads";--> statement-breakpoint
+-- a2slack-feed's position counts an earlier log. Pinned at the top, it claims
+-- no more events, so a deployment still running it writes no rows the new
+-- feed would then collide with.
+INSERT INTO "a2slack_positions" ("consumer", "log_index") VALUES ('a2slack-feed', 9007199254740991)
+ON CONFLICT ("consumer") DO UPDATE SET "log_index" = excluded."log_index";