Module cursor 

Stateless cursor-affinity envelope (docs/03 §6).

A scroll / PIT cursor is bound to the one physical cluster that created it, so every follow-up request must reach that same cluster. In a fleet the create and the continue may land on different proxy instances, so a binding kept in one instance’s memory is invisible to the others.

This module makes the binding travel with the cursor instead of living in a shared store: on create the proxy wraps the upstream cursor id together with its cluster into a signed token the client echoes back; on continue any instance recovers the cluster from the token alone, no shared state, no replication lag, no read-after-write race. The upstream id is carried verbatim as the payload (we never need spare room inside it), and the proxy strips the envelope before talking upstream, so OpenSearch never sees it.

The signature binds the cluster to this cursor: a client cannot redirect a cursor to another cluster (the tag would not verify), and a tampered token fails closed to “unresolvable cursor”, never a wrong-cluster dispatch.

Traits

CursorSigner

Signs the cluster↔cursor binding. The concrete HMAC implementation (behind the build’s crypto provider) lives in the binary; this seam keeps the codec pure and lets tests inject a deterministic signer.

Functions

unwrap

Recovers (cluster, upstream cursor) from a token produced by wrap, or None if it is malformed or its signature does not verify (fail-closed, a bad token is never routed anywhere).

wrap

Wraps cursor (the upstream scroll/PIT id) with cluster into a signed, self-describing token for the client. Format {cluster_hex}.{tag_hex}.{cursor}, the cursor verbatim (it is base64, so it never contains the . delimiter).