kurrentdb

Sans-IO KurrentDB client primitives.

This module contains the transport-independent pieces shared by all KurrentDB backends: client configuration, gRPC status mapping, gRPC frame encoding, and the small protobuf encoder/decoder used by the operation modules.

Most applications will create a Client here and pass it to a runtime backend such as kurrentdb_erlang. The operation modules under kurrentdb/operation build typed requests and decode typed responses; the backend is responsible for actually sending the HTTP/2 gRPC requests.

let client = kurrentdb.new("localhost", 2113, kurrentdb.TlsDisabled)

Connection strings using the kurrentdb:// and esdb:// schemes can also be parsed with from_connection_string.

Types

Client

opaque

A KurrentDB endpoint and optional Basic Auth credentials.

Client is intentionally transport independent. It does not open sockets or own any runtime resources; it only contains enough information for operation modules to construct gRPC-over-HTTP requests.

pub opaque type Client

GrpcError

Domain-level gRPC and protobuf errors shared by operation decoders.

Backends typically wrap these errors in their own transport error type. Operation modules may map some variants to operation-specific errors, such as ReadStreamNotFound.

pub type GrpcError {
  DeadlineExceeded
  ReadStreamNotFound(String)
  AccessDenied
  Unavailable
  NotAuthenticated
  UnknownGrpcStatus(status: String, message: String)
  StreamDeleted(String)
  ProtobufDecodeError(
    expected: String,
    found: String,
    path: List(String),
  )
  ProtobufFieldNotFound(field_number: Int)
  IncompleteHeader
  CompressedMessage
  IncompleteMessage(expected_bytes: Int)
}

Constructors

```
DeadlineExceeded
```
gRPC status DEADLINE_EXCEEDED.
```
ReadStreamNotFound(String)
```
The server reported that a stream could not be found.
```
AccessDenied
```
gRPC status PERMISSION_DENIED.
```
Unavailable
```
gRPC status UNAVAILABLE.
```
NotAuthenticated
```
gRPC status UNAUTHENTICATED.
```
UnknownGrpcStatus(status: String, message: String)
```
A gRPC status not explicitly modelled by this package.
```
StreamDeleted(String)
```
The server reported that a stream has been tombstoned.

ProtobufDecodeError(
  expected: String,
  found: String,
  path: List(String),
)

A protobuf field had an unexpected shape or encoding.

ProtobufFieldNotFound(field_number: Int)

A required protobuf field was absent.

```
IncompleteHeader
```
A gRPC frame ended before the five byte header was complete.
```
CompressedMessage
```
The response used compressed gRPC messages, which are not supported.
```
IncompleteMessage(expected_bytes: Int)
```
A gRPC frame announced more bytes than were available.

Tls

Whether requests should be built for plain HTTP or HTTPS.

KurrentDB commonly runs with TLS enabled in production. Local development environments often disable TLS, especially when using the official Docker image without certificates.

pub type Tls {
  TlsDisabled
  TlsEnabled
}

Constructors

```
TlsDisabled
```
Use http:// when constructing requests.
```
TlsEnabled
```
Use https:// when constructing requests.

Values

from_connection_string

pub fn from_connection_string(
  connection_string: String,
) -> Result(Client, Nil)

Parse a KurrentDB connection string into a Client.

Supported schemes are kurrentdb:// and esdb://. The connection string must include a host and port. TLS is enabled by default and can be disabled with ?tls=false.

User info in the form user:password@ is converted to Basic Auth credentials. Malformed connection strings, unsupported schemes, missing host or port values, and unsupported tls query values return Error(Nil).

kurrentdb.from_connection_string("esdb://admin:changeit@localhost:2113?tls=false")

grpc_from_status

pub fn grpc_from_status(
  headers: List(#(String, String)),
  status: String,
) -> GrpcError

Convert a grpc-status value and response headers into a GrpcError.

The grpc-message header is used where KurrentDB puts useful diagnostic information, for example the stream name for not-found failures. Unknown status codes are preserved as UnknownGrpcStatus so callers can inspect the original status and message.

new

pub fn new(host: String, port: Int, tls: Tls) -> Client

Create a client without credentials.

The tls argument determines the scheme used by generated requests. Use TlsEnabled for HTTPS and TlsDisabled for HTTP.

let client = kurrentdb.new("localhost", 2113, kurrentdb.TlsDisabled)

new_with_credentials

pub fn new_with_credentials(
  host: String,
  port: Int,
  tls: Tls,
  credentials: option.Option(#(String, String)),
) -> Client

Create a client with optional Basic Auth credentials.

Credentials are encoded as an authorization: Basic ... header on every generated request. Pass None to build the same client as new.

let client =
  kurrentdb.new_with_credentials(
    "localhost",
    2113,
    kurrentdb.TlsEnabled,
    Some(#("admin", "changeit")),
  )