append_to_stream

Build and decode append-to-stream requests.

This is a sans-IO operation module. request builds the gRPC request body for KurrentDB’s Streams/Append method and response decodes the HTTP response returned by a backend.

Runtime backends normally wrap this module with a higher level function, but it is public so alternative transports can reuse the request and response codecs.

Types

Append

Successful append result.

current_revision is the stream revision after the append completed. position is the commit/prepare position returned by KurrentDB when available.

pub type Append {
  Append(current_revision: Int, position: Position)
}

Constructors

Append(current_revision: Int, position: Position)

Configuration

opaque

Configuration for an append operation.

Use configure to create the default configuration and builder functions such as expected_revision to change individual options.

pub opaque type Configuration

Event

An event to be appended to a stream.

Events carry a UUID, event type, content type, event data, and optional custom metadata. Use json_event or binary_event to construct values.

pub type Event {
  Event(
    id: uuid.Uuid,
    type_: String,
    content_type: String,
    data: BitArray,
    metadata: BitArray,
  )
}

Constructors

Event(
  id: uuid.Uuid,
  type_: String,
  content_type: String,
  data: BitArray,
  metadata: BitArray,
)

ExpectedRevision

Expected stream revision used for optimistic concurrency checks.

KurrentDB rejects an append when the supplied expectation does not match the current stream state.

pub type ExpectedRevision {
  Revision(Int)
  NoStream
  Any
  StreamExists
}

Constructors

```
Revision(Int)
```
```
NoStream
```
```
Any
```
```
StreamExists
```

Position

Append position returned by KurrentDB.

pub type Position {
  NoPositionReturned
  Position(commit_position: Int, prepare_position: Int)
}

Constructors

```
NoPositionReturned
```

Position(commit_position: Int, prepare_position: Int)

ResponseError

Errors that can occur while decoding an append response.

pub type ResponseError {
  GrpcError(kurrentdb.GrpcError)
  EmptyResponse
  ManyResponses
  HttpStatus(Int)
  AppendWrongExpectedVersion
}

Constructors

```
GrpcError(kurrentdb.GrpcError)
```
```
EmptyResponse
```
```
ManyResponses
```
```
HttpStatus(Int)
```
```
AppendWrongExpectedVersion
```

Values

binary_event

pub fn binary_event(
  uuid id: uuid.Uuid,
  type_ type_: String,
  data data: BitArray,
) -> Event

Construct an Event with raw binary data and application/octet-stream content type.

Use this for non-JSON event payloads or when the payload is already encoded.

configure

pub fn configure() -> Configuration

Create append configuration with the default expected revision.

The default is Any, meaning KurrentDB will accept the append regardless of the stream’s current revision.

event_to_bitarray

pub fn event_to_bitarray(event: Event) -> BitArray

Encode an event as the protobuf message expected by Streams/Append.

This is exposed for transport authors and tests. Most applications should pass Event values to a backend append function instead.

expected_revision

pub fn expected_revision(
  config: Configuration,
  expected_revision: Int,
) -> Configuration

Set the expected stream revision for optimistic concurrency.

This helper sets the expectation to Revision(expected_revision).

json_event

pub fn json_event(
  uuid id: uuid.Uuid,
  event_type type_: String,
  data data: json.Json,
) -> Event

Construct an Event with JSON-encoded data and application/json content type.

The supplied JSON is encoded to UTF-8 bytes. The event type is stored in the KurrentDB metadata map under the type key.

metadata

pub fn metadata(event: Event, metadata: BitArray) -> Event

Attach custom metadata to an event.

Metadata is encoded as raw bytes in the event’s custom metadata field. This function replaces any existing custom metadata on the event.

request

pub fn request(
  client: kurrentdb.Client,
  stream stream: String,
  events events: List(Event),
  config config: Configuration,
) -> request.Request(BitArray)

Build a Streams/Append gRPC request.

The request contains one options message followed by one proposed-message protobuf message per event. The returned request is ready for a backend to send over HTTP/2.

response

pub fn response(
  response: response.Response(BitArray),
) -> Result(Append, ResponseError)

Decode an append response from a backend HTTP response.

A successful response returns the current stream revision and optional log position. gRPC status 10 is mapped to AppendWrongExpectedVersion.