package kurrentdb.protocol.v2.streams

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc AppendRecords (AppendRecordsRequest, AppendRecordsResponse)

  streams.proto:55

  Appends records to multiple streams atomically with cross-stream consistency checks. This is a unary RPC where the client sends all records and consistency checks in a single request and receives a single AppendRecordsResponse. Records can be interleaved across streams in any order and the global log preserves the exact sequence from the request. Consistency checks are decoupled from writes: a check can reference any stream, whether or not the request writes to it. This enables Dynamic Consistency Boundary (DCB) patterns where a decision depends on multiple streams but only produces events for a subset. Guarantees: - Atomicity: All writes succeed or all fail together - Ordering: Records maintain the exact send order in the global log - Cross-stream checks: Consistency checks can reference any stream On consistency check failure, no records are written and all failing checks are reported in the response so the client can refresh stale state in one round trip.

  message AppendRecordsRequest

  streams.proto:190

  * Request to append records to one or more streams atomically. All records are committed in a single transaction. Each record specifies its target stream via AppendRecord.stream. Consistency checks are evaluated before any records are written.

  • repeated AppendRecord records = 1

    The records to append. Records targeting the same stream maintain their order from this list.

  • repeated ConsistencyCheck checks = 2

    Optional consistency checks evaluated before commit. If any check fails, the entire transaction is aborted.

  message AppendRecordsResponse

  streams.proto:206

  * Response from a successful AppendRecords operation. Contains the resulting revision for each stream that was written to and the global commit position of the transaction.

  • repeated StreamRevision revisions = 1

    The resulting revision for each stream that received records. One entry per distinct stream written to, in no guaranteed order.

  • sint64 position = 2

    The global commit position of the last record written in this transaction. Can be used for read-your-writes consistency or progress tracking.

• rpc AppendSession (stream AppendRequest, AppendSessionResponse)

  streams.proto:33

  Appends records to multiple streams atomically within a single transaction. This is a client-streaming RPC where the client sends multiple AppendRequest messages (one per stream) and receives a single AppendSessionResponse upon commit. Guarantees: - Atomicity: All writes succeed or all fail together - Optimistic Concurrency: Expected revisions are validated for all streams before commit - Ordering: Records within each stream maintain send order Current Limitations: - Each stream can only appear once per session (no multiple appends to same stream) Example flow: 1. Client opens stream 2. Client sends AppendRequest for stream "orders" with 3 records 3. Client sends AppendRequest for stream "inventory" with 2 records 4. Client completes the stream 5. Server validates, commits, returns AppendSessionResponse with positions

  message AppendRequest

  streams.proto:58

  Represents the input for appending records to a specific stream.

  • string stream = 1

    The stream to append records to.

  • repeated AppendRecord records = 2

    The records to append to the stream.

  • optional sint64 expected_revision = 3

    The expected revision for optimistic concurrency control. Can be either: - A specific revision number (0, 1, 2, ...) - the stream must be at exactly this revision - An ExpectedRevisionConstants value (-4, -2, -1) for special semantics If omitted, defaults to EXPECTED_REVISION_CONSTANTS_ANY (-2).

  message AppendSessionResponse

  streams.proto:87

  • repeated AppendResponse output = 1

    The results of each append request in the session.

  • sint64 position = 2

    The global commit position of the last appended record in the session.

Record to be appended to a stream.

Used in: AppendRecordsRequest, AppendRequest

• optional string record_id = 1

  Unique identifier for this record (must be a valid UUID/GUID). If not provided, the server will generate a new one.

• map<string, google.protobuf.Value> properties = 2

  A collection of properties providing additional information about the record. Can contain user-defined or system propreties. System keys will be prefixed with "$" (e.g., "$timestamp"). User-defined keys MUST NOT start with "$". Common examples: User metadata: - "user-id": "12345" - "tenant": "acme-corp" - "source": "mobile-app" System metadata (with $ prefix): - "$trace-id": "4bf92f3577b34da6a3ce929d0e0e4736" // OpenTelemetry trace ID - "$span-id": "00f067aa0ba902b7" // OpenTelemetry span ID - "$timestamp": "2025-01-15T10:30:00.000Z" // ISO 8601 timestamp

• optional SchemaInfo schema = 3

  Schema information for this record.

• bytes data = 4

  The record payload as raw bytes. The format specified in SchemaInfo determines how to interpret these bytes.

• string stream = 5

  Target stream for this record. Required for AppendRecords (each record specifies its own stream). Ignored for AppendSession (the stream is specified in AppendRequest).

Represents the outcome of an append operation.

Used in: AppendSessionResponse

• string stream = 1

  The stream to which records were appended.

• sint64 stream_revision = 2

  The actual/current revision of the stream after the append. This is the revision number of the last record written to this stream.

• optional sint64 position = 3

  The position of the last appended record in the global log.

* A pre-commit condition that must hold true for the transaction to succeed. Consistency checks are evaluated atomically before any records are written. If any check is violated, the entire transaction is aborted. Two types of checks are supported: stream state checks (validates a stream's revision or lifecycle state) and query predicates (evaluates a server-side expression).

Used in: AppendRecordsRequest

• oneof type

  • ConsistencyCheck.StreamStateCheck stream_state = 1

    Check that a stream is at a specific revision or lifecycle state.

* Asserts a stream is at a specific revision or lifecycle state before commit. The expected_state field accepts a specific revision number (>= 0) or a special state constant (e.g., -1 for NO_STREAM, -10 for DELETED). Evaluated using writability semantics: a soft-deleted stream is writable (appending restores it), but a tombstoned stream is never writable.

Used in: ConsistencyCheck

• string stream = 1

  The stream name.

• sint64 expected_state = 2

  The expected state of the stream (revision number or state constant).

Constants for expected revision validation in optimistic concurrency control. These can be used in the expected_revision field, or you can specify an actual revision number.

• EXPECTED_REVISION_CONSTANTS_SINGLE_EVENT = 0

  The stream must have exactly one event at revision 0. Used for scenarios requiring strict single-event semantics.

• EXPECTED_REVISION_CONSTANTS_NO_STREAM = -1

  The stream must not exist yet (first write to the stream). Fails if the stream already has events.

• EXPECTED_REVISION_CONSTANTS_ANY = -2

  Accept any current state of the stream (no optimistic concurrency check). The write will succeed regardless of the stream's current revision.

• EXPECTED_REVISION_CONSTANTS_EXISTS = -4

  The stream must exist (have at least one record). Fails if the stream doesn't exist yet.

Represents the data format of the schema.

Used in: SchemaInfo

• SCHEMA_FORMAT_UNSPECIFIED = 0

  Default value, should not be used.

• SCHEMA_FORMAT_JSON = 1

• SCHEMA_FORMAT_PROTOBUF = 2

• SCHEMA_FORMAT_AVRO = 3

• SCHEMA_FORMAT_BYTES = 4

Schema information for record validation and interpretation.

Used in: AppendRecord

• SchemaFormat format = 1

  The format of the data payload. Determines how the bytes in AppendRecord.data should be interpreted.

• string name = 2

  The schema name (replaces the legacy "event type" concept). Identifies what kind of data this record contains. Common naming formats: - Kebab-case: "order-placed", "customer-registered" - URN format: "urn:kurrentdb:events:order-placed:v1" - Dotted namespace: "Teams.Player.V1", "Orders.OrderPlaced.V2" - Reverse domain: "com.acme.orders.placed"

• optional string id = 3

  The identifier of the specific version of the schema that the record payload conforms to. This should match a registered schema version in the system. Not necessary when not enforcing schema validation.

* A specific revision of a stream. Used to represent stream positions for checkpoints, consistency checks, and head position tracking.

Used in: AppendRecordsResponse

• string stream = 1

  Stream name.

• sint64 revision = 2

  Revision within the stream.