gradyzhuo/swift-kurrentdb

This system is a Swift client library for the KurrentDB event sourcing platform, providing a comprehensive API for interacting with the database's v2 gRPC services. It enables developers to manage streams, persistent subscriptions, projections, and user accounts, while also offering administrative controls for cluster topology, node operations, and server monitoring. The library supports advanced features like multi-stream batch appends, configurable retry policies, and per-call authentication, all structured around a target-scoped, protocol-based architecture.

42 changes.

The codebase underwent a major architectural overhaul, renaming the project to KurrentDB and replacing the legacy EventStoreDB client with a new, protocol-based gRPC abstraction layer. This period focused on implementing comprehensive APIs for streams, persistent subscriptions, projections, and user management, supported by extensive new test coverage and cluster discovery features.

14 changes.

This period focused on introducing the KurrentDB v2 API with new gRPC services for streams, schema registry, and system administration. The client library was expanded to support projections, user management, and cluster operations, while a V1 compatibility layer was added for backward compatibility. Additionally, local development environments and comprehensive test coverage were established to support the new features.

Introduces a new Gossip.Read usecase that exposes a public API to retrieve the current cluster members as a list of MemberInfo objects. This enables clients to discover and monitor the state of the KurrentDB cluster via the Gossip service.

Sources/KurrentDB/Gossip/Usecase · high confidence

A new \ListForAll\ usecase has been added to the PersistentSubscriptions API, enabling users to retrieve a list of all persistent subscriptions or filter by a specific stream. This change introduces the \ListForAll\ struct which implements the \Usecase\ protocol, supporting both \allSubscriptions\ and \stream\-based filtering via the \ListFilter\ enum. This allows clients to query subscription metadata directly through the KurrentDB client interface.

Sources/KurrentDB/PersistentSubscriptions/Usecase/All · high confidence

A new Monitoring.Stats usecase has been added to the KurrentDB client, enabling users to retrieve periodic snapshots of server statistics via a server-streaming RPC. The Stats struct accepts configuration for metadata inclusion and refresh intervals, returning a stream of Response objects containing key-value pairs of server metrics.

Sources/KurrentDB/Monitoring/Usecase · high confidence

The KurrentDB client now exposes Usecases for several new Operations RPCs: MergeIndexes, ResignNode, RestartPersistentSubscriptions, SetNodePriority, Shutdown, StartScavenge, and StopScavenge. Each struct implements the Usecase protocol with a methodDescriptor and name, enabling the client to invoke these maintenance and cluster-management endpoints directly.

Sources/KurrentDB/Operations/Usecase · medium confidence

New Swift extension files are added to the KurrentDB client to map internal settings objects to gRPC request messages. Specifically, \EventStore\_Client\_PersistentSubscriptions+Additions.swift\ provides static methods to convert \PersistentSubscription.CreateSettings\ and \PersistentSubscription.UpdateSettings\ into their corresponding gRPC \Settings\ messages, handling fields such as checkpoint counts, subscriber limits, buffer sizes, and timeout values. Additionally, \ReadEvent+Additions.swift\ introduces an initializer for \ReadEvent\ that constructs the object from an underlying service message, mapping recorded events, linked events, and commit positions.

Sources/KurrentDB/PersistentSubscriptions/Additions · medium confidence

A new V1 compatibility layer is introduced in the Sources/KurrentDB\_V1 directory, providing convenience methods for stream, projection, persistent subscription, user, and system operations. These methods wrap the new target-based API (e.g., client.streams(of:), client.projections(of:)) and are marked as deprecated, encouraging users to migrate to the newer API.

_Sources/KurrentDB\V1 · high confidence

Users can now discover the current state of the KurrentDB cluster by calling \KurrentDBClient.readCluster()\. This new API queries the Gossip protocol to retrieve a list of all known cluster members, including each node's unique ID, health status, HTTP endpoint, and lifecycle state (e.g., leader, follower, read-only replica). The returned \MemberInfo\ array is sorted by node preference priority, allowing applications to identify the active leader or healthy replicas for routing decisions.

Sources/KurrentDB/Gossip · high confidence

The library introduces several new Swift extensions to the \KurrentDB\ core module to improve client-side functionality. These include a \StreamIdentifier\ conversion helper, a \UUID\ serialization method for the EventStore client, and a \GRPCClient\ convenience initializer that automatically configures HTTP/2 transport from node settings. Additionally, the update adds a \Metadata\ extension to build request headers with support for per-call authentication overrides, utility methods to load TLS certificate sources from the application bundle, and a string parser for connection strings.

Sources/KurrentDB/Core/Additions · high confidence

New docker-compose files (docker-compose.yaml and docker-compose.eventstore.yaml) and environment variable files (vars.env, vars.eventstore.env) are added to the server directory. These files define 3-node cluster setups for KurrentDB and EventStoreDB respectively, each with TLS certificate generation, health checks, and volume mounts for data persistence. This enables local development and testing of clustered database instances.

server · high confidence

The KurrentDB client now exposes new use cases for managing projection states, including ContinuousCreate, OneTimeCreate, and TransientCreate for different projection lifecycles, alongside Disable, Enable, Reset, RestartSubsystem, Result, State, and Update operations. This expands the API to support full projection management, allowing users to create, modify, query, and control the status of projections directly through the client.

Sources/KurrentDB/Projections/Usecase · high confidence

The library now exposes the full set of persistent subscription operations for both the \$all\ stream and specific named streams. This includes creating, updating, deleting, and retrieving information about subscriptions, as well as reading events and replaying parked events. Each operation is implemented as a dedicated use case struct (e.g., \PersistentSubscriptions.AllStream.Create\, \PersistentSubscriptions.SpecifiedStream.Read\) that wraps the underlying gRPC client calls, providing a consistent and typed API for managing persistent subscriptions.

Sources/KurrentDB/PersistentSubscriptions/Usecase/AllStream · high confidence

The KurrentDB client now exposes new public APIs for managing persistent subscriptions. Users can retrieve subscription metadata via \GetInfo\, and handle event processing outcomes with \Ack\ (positive acknowledgement) and \Nack\ (negative acknowledgement) which support actions like park, retry, skip, or stop. Additionally, a \RestartSubsystem\ use case is added to restart the persistent subscription subsystem. These changes implement the underlying Usecase protocol methods for these operations.

Sources/KurrentDB/PersistentSubscriptions/Usecase · high confidence

Users can now access a new Monitoring API on the KurrentDB client to stream real-time server statistics. The \KurrentDBClient\ exposes a \monitoring\ property and a \stats()\ method that returns an async stream of \Stats/Response\ snapshots. The \Monitoring\ class handles the gRPC communication and supports per-call authentication overrides via the \authenticated(\_:)\ method, allowing callers to specify credentials for individual monitoring calls.

Sources/KurrentDB/Monitoring · high confidence

The library now includes a \ServerFeatures\ client that queries the KurrentDB server to retrieve a list of supported gRPC methods and the server version. This enables the client to detect whether specific API features (such as \AppendSession\ or \EventRecord\) are supported by the connected server, allowing for safer interactions with different server versions.

Sources/KurrentDB/ServerFeatures · high confidence

The KurrentDB client now supports a complete set of user management operations. Users can create new accounts, update profile details, change or reset passwords, enable or disable accounts, and retrieve user details. These new use cases are implemented as gRPC calls within the KurrentDB module, providing a consistent API for administrative user tasks.

Sources/KurrentDB/Users/Usecase · high confidence

The proto directory now includes comprehensive protocol buffer definitions for the KurrentDB v2 API, introducing new gRPC services for Streams and Schema Registry management. The Streams API adds \AppendSession\ and \AppendRecords\ RPCs for multi-stream batch appends and cross-stream consistency checks, alongside detailed error codes for stream states (e.g., \STREAM\_NOT\_FOUND\, \STREAM\_REVISION\_CONFLICT\). The Registry API introduces \SchemaRegistryService\ with RPCs for managing schema groups, schemas, and compatibility checks, including validation and bulk registration capabilities. Additionally, the \kurrent.rpc\ package defines a standardized \ServerError\ enum and \ErrorMetadata\ annotation system for consistent error handling across all Kurrent services. Existing v1 protos have been reorganized under \proto/kurrentdb/v1/\ with updated Java package namespaces.

proto · high confidence

A new offline benchmark target has been introduced to measure the performance of core library components. The suite includes benchmarks for creating EventData instances (both raw data and Codable models), parsing ClientSettings from connection strings, constructing Stream and Read options, and creating StreamIdentifiers. This allows users to track performance changes in these specific areas.

Benchmarks · high confidence

Added .spi.yml to configure Swift Package Index documentation generation for the KurrentDB target using Swift 6.0, and .swiftformat to enforce Swift 6 coding standards. Added AGENTS.md and CLAUDE.md to provide repository guidelines, development commands, and architecture details for AI assistants and developers. Added BENCHMARKS.md with offline performance results for client-side code paths. Added CONTRIBUTING.md with guidelines for the project. Added Licence file. Updated .gitignore to exclude Package.resolved and Claude-related files.

(repo-wide) · high confidence

New Swift source files are introduced to expose projection creation and listing capabilities for every supported mode: Any, Continuous, One-Time, and Transient. Users can now create projections via the \create\ method (with optional configuration for continuous mode) and retrieve statistics via the \list\ method, each tailored to the specific projection lifecycle and target type.

Sources/KurrentDB/Projections/API · high confidence

Added the primary client entry point \KurrentDBClient\ and its \KurrentDBClientProtocol\ abstraction. The client manages connection settings, an internal event loop group, and a node selector for cluster discovery. The protocol enables dependency injection and test doubles by exposing typed interfaces for streams, persistent subscriptions, users, and server operations.

Sources/KurrentDB · high confidence

Users can now explicitly define starting points for reading streams and events using the new PositionCursor and RevisionCursor enums. PositionCursor allows specifying commit and prepare log positions for the $all stream, while RevisionCursor enables starting from a specific event revision number for named streams. Both enums support 'start' (beginning), 'end' (most recent), and 'specified' (explicit position) cases, providing clearer and more flexible cursor management for data retrieval.

Sources/KurrentDB/Core/Cursor · high confidence

Adds new Swift types for working with KurrentDB streams, including \StreamIdentifier\ for naming and encoding, \StreamMetadata\ for configuring retention and access control, \StreamPosition\ for tracking commit and prepare offsets, \StreamRevision\ for optimistic concurrency rules, and \StreamSelector\ for targeting specific or all streams. These types provide the foundational data structures for stream operations in the KurrentDB client.

Sources/KurrentDB/Core/Stream · high confidence

The KurrentDB client now exposes a new \Operations\ interface that is scoped to specific administrative targets (\.system\, \.node\, \.scavenge\, and \.activeScavenge\). This allows users to access distinct sets of server administration methods—such as \mergeIndexes()\, \resignNode()\, and \startScavenge()\—based on the chosen target. Additionally, the interface supports per-call authentication overrides via the \authenticated(\_:)\ method, enabling temporary credential changes for specific calls without altering the global client settings.

Sources/KurrentDB/Operations · high confidence

Adds a new \Users\ service to the KurrentDB client, enabling creation, retrieval, and modification of user accounts. Users can now create accounts with specific groups, and perform profile updates, password changes, and enable/disable operations on individual users or across the cluster.

Sources/KurrentDB/Users · high confidence

The client now supports configurable retry policies and node caching for cluster connections. A new \OperationRetryPolicy\ struct allows users to define retry behavior (attempts, delays, backoff, jitter) for node failures. The \NodeSelector\ component caches the best available cluster node for a duration specified by \ClientSettings.nodeCacheTTL\, invalidating the cache on node failures to trigger re-discovery. Additionally, a \StreamFilter\ struct (renamed from \SubscriptionFilter\) provides a builder-style API for filtering events by stream name or event type, and a \Direction\ enum is added for stream traversal.

Sources/KurrentDB/Core · high confidence

The library adds four new protocol definitions—StreamStream, StreamUnary, UnaryStream, and UnaryUnary—along with a foundational Usecase protocol. These changes provide a structured, type-safe interface for defining gRPC client interactions, supporting both streaming and unary call patterns. This refactor standardizes how use cases are implemented and invoked within the GRPC encapsulation layer.

Sources/GRPCEncapsulates/Usecase · high confidence

The GRPCEncapsulates module now provides a set of new protocols to standardize how gRPC requests and responses are built and processed. The \Buildable\ and \CommandOptions\ protocols enable a fluent, builder-style API for constructing messages, while \GRPCBridge\, \GRPCConcreteService\, and \GRPCServiceClient\ protocols define the underlying client and service interfaces. Additionally, \RequestBuildable\ and \ResponseHandlable\ protocols facilitate the creation of streaming and unary requests and the handling of responses, including a new \GoogleProtobufValueProtocol\ that allows native Swift types (like Int, String, Bool) to be easily converted to Protobuf values.

Sources/GRPCEncapsulates · high confidence

The Projections module now provides a new, target-scoped API for managing projections. Users can obtain a \Projections\ service instance via \client.projections(of:)\, \client.projections(name:)\, or \client.projections(system:)\, each scoped to a specific projection target. The new \Projections\ class supports per-call authentication overrides via the \authenticated(\_:)\ method, allowing temporary credential switching without modifying the global client settings. The API exposes methods for enabling, disabling, aborting, resetting, deleting, updating, and querying the state or results of projections, all typed to throw \KurrentError\.

Sources/KurrentDB/Projections · high confidence

The Streams module has been restructured to support multiple stream targets: single named streams, the global \$all\ stream, and projection streams. Users can now append to multiple streams in a single session via \AppendSession\, perform atomic multi-stream appends with consistency checks via \AppendRecords\, and pipeline non-atomic batch appends via \BatchAppend\. The API also adds \read\ and \subscribe\ methods for \$all\ and projection streams, and introduces \StreamEvent\ and \ConsistencyCheck\ types for these advanced operations.

Sources/KurrentDB/Streams · high confidence

The library introduces new types for configuring client connections and authentication. \ClientSettings\ now exposes properties for \nodeCacheTTL\, \discoveryInterval\, \maxDiscoveryAttempts\, and \operationRetryPolicy\, allowing users to control node caching and discovery behavior. The \Authentication\ enum supports three methods: username/password credentials, bearer tokens, and X.509 client certificates. Additionally, \Endpoint\ and \TopologyClusterMode\ types are added to define server addresses and cluster topologies (standalone, DNS-based, or seed-based discovery).

Sources/KurrentDB/Core/ClientSettings · high confidence

Added new parser classes for parsing connection strings, including URLSchemeParser, EndpointParser, QueryItemParser, and UserCredentialsParser, each implementing the ConnctionStringParser protocol to extract specific segments (scheme, host/port, query items, and credentials) from connection strings.

Sources/KurrentDB/Core/ClientSettings/Parser · high confidence

The error handling in KurrentDB has been expanded to support the v2 AppendRecords API. A new \consistencyViolation\ case has been added to \KurrentError\ to report multiple pre-commit consistency check failures from \AppendRecords\, including the failing stream, expected state, and actual state for each violation. Additionally, two new enums, \ExpectedRevisionOption\ and \CurrentRevisionOption\, have been introduced to represent revision expectations and current states, replacing the previous \WrongExpectedVersion\ error structure with a more detailed representation of version conflicts.

Sources/KurrentDB/Core/Error · high confidence

The library introduces new types to support the KurrentDB v2 API and dynamic consistency boundaries. \EventRecord\ replaces the legacy \EventData\ as the primary struct for preparing events, featuring a \Schema\ (format, name, id) and a \Buildable\ API for setting trace IDs, span IDs, and timestamps. \StreamEvent\ groups records for a single stream with an expected revision for optimistic concurrency. \ConsistencyCheck\ enables pre-commit assertions on stream state, supporting multi-stream batch appends via \AppendRecords\. \RecordedEvent\ and \ReadEvent\ provide structured access to read operations, including link resolution and commit positions. \ContentType\ and \EventData\ handle payload encoding and metadata.

Sources/KurrentDB/Core/Event · high confidence

The KurrentDB library introduces new Swift protocols and target structs to support cluster node management, scavenge operations, and system-wide administrative tasks. The \NodeControllable\ protocol and \NodeOperations\ struct enable management of the current cluster node's role and election priority. Scavenge operations are supported via the \ScavengeCreatable\ and \ScavengeControllable\ protocols, with corresponding \ScavengeOperations\ and \ActiveScavenge\ structs allowing users to start new scavenge operations or stop a running one. Additionally, the \SystemControllable\ protocol and \SystemOperations\ struct provide a target for system-wide administrative tasks such as shutdown, index merging, and subsystem restarts.

Sources/KurrentDB/Operations/Protocols, Sources/KurrentDB/Operations/Targets · high confidence

The KurrentDB client library introduces a set of new types to support persistent subscription operations. \PersistentSubscription.EventResult\ wraps delivered events with retry metadata, while \PersistentSubscription.ConnectionInfo\ and \PersistentSubscription.Measurement\ expose per-connection statistics and throughput metrics. Configuration is handled via \CreateSettings\ and \UpdateSettings\ structs, allowing users to define timeouts, buffer sizes, and consumer strategies. Additionally, \SystemConsumerStrategy\ defines how events are distributed among consumers (e.g., round-robin, pinned), and \StreamSelection\ specifies whether to read from the global \$all\ stream or a specific named stream.

Sources/KurrentDB/Core/PersistenSubscription · high confidence

A new script, single-to-cluster.sh, has been added to the scripts/transfer directory. It copies KurrentDB data from a single-node deployment into the node1 volume of a 3-node cluster. The script supports both Docker volumes and host paths as the source, handles ownership changes (uid/gid 1001:1001) to prevent permission errors, and recreates the truncate.chk file from chaser.chk to ensure proper cluster startup behavior.

scripts · high confidence

The \Sources/EventStoreDB\ directory has been cleared of numerous source files, including \ClientSettings\, \Cluster\, \Error\, \EventData\, \EventStoreDB\, and various \Stream\ operation files (e.g., \Append\, \Delete\, \Read\, \Tombstone\). This removal eliminates the previous internal client structure, likely as part of a broader refactoring to support the new KurrentDB API or a cleaner library architecture.

Sources/EventStoreDB · high confidence

The projection target types in the KurrentDB Projections module have been split into individual files for better organization. This includes new types such as AnyProjectionsTarget, NameTarget, OneTimeProjectionTarget, and others, each handling specific projection scopes like continuous, transient, or one-time projections. These changes improve code maintainability and clarity for developers working with projection targets.

Sources/KurrentDB/Projections/Target · high confidence

The client now discovers which gRPC methods the server supports via a new \GetSupportedMethods\ usecase. This enables runtime feature detection, allowing the client to verify server compatibility before invoking specific operations, and ensures that unsupported features are handled gracefully rather than failing with generic errors.

Sources/KurrentDB/ServerFeatures/Usecase · high confidence

The KurrentDB usecases now own and manage the gRPC connection lifecycle using explicit Task-based lifecycle management. This ensures that connection errors are properly observed and logged rather than being silently discarded, and the connection is gracefully shut down when the usecase completes. Additionally, the code now checks server feature support before performing requests, throwing an unsupported feature error if the server does not support the required method.

Sources/KurrentDB/Core/Additions/Usecase · medium confidence

The Projection module now exposes a new \Projection.Detail\ struct that provides runtime statistics and configuration details for a single projection, including processing time, version, epoch, effective name, in-progress counts, and checkpoint status. Additionally, \Projection.Status\ has been refactored from an \OptionSet\ to a \String\-backed composite type that parses slash-separated state names (e.g., "Running/Initial") and offers a \contains(\_:)\ method for checking specific states like \Running\, \Stopped\, \Faulted\, or \Completed\. The \Projection.Mode\ enum defines operational modes including \Any\, \Transient\, \Continuous\, and \OneTime\. These changes provide a more granular and structured way to inspect and interact with projection states and metadata in the KurrentDB client.

Sources/KurrentDB/Core/Projection · high confidence

The PersistentSubscriptions module has been refactored to use a target-based API where each operation is scoped to a specific stream or cluster-wide context. New factory methods on KurrentDBClient (allPersistentSubscriptions, persistentSubscriptions, persistentSubscriptions(filterGroup:), persistentSubscriptions(filterStream:)) provide access to the new API. The Subscription class now exposes lastRevision and lastPosition properties to track the last successfully received event, enabling callers to resume from a known position after a drop. Additionally, the API now supports per-call authentication overrides via the authenticated(\_:) method, allowing individual calls to use different credentials than the client-level default.

Sources/KurrentDB/PersistentSubscriptions · high confidence

The user target types have been split into separate files for better organization. This includes the introduction of the \UsersTarget\ marker protocol, along with specific target types \AllUsersTarget\ (for creating new accounts) and \SpecifiedUserTarget\ (for managing existing accounts). The \UserCreatable\ and \UserControllable\ protocols are now defined in their own files to clearly separate capabilities for account creation and user management operations.

Sources/KurrentDB/Users/Target · high confidence

The \_GRPCProtobufGenerated module has been renamed and its contents regenerated to sync with updated protocol buffer definitions. This includes new or updated Swift types for Google RPC codes, Kurrent server error codes (such as accessDenied, badRequest, notLeaderNode, and serverOverloaded), and Kurrent-specific metadata structures. Additionally, the generated client code for the event\_store.cluster.Gossip and event\_store.client.gossip.Gossip services has been updated to reflect the latest proto definitions, ensuring compatibility with the current API surface.

_Sources/\GRPCProtobufGenerated · medium confidence

Add OperationsTests for system and node operations; Added comprehensive test coverage for stream operations and multi-stream features; Added comprehensive tests for persistent subscription lifecycle and advanced operations; Added integration tests for KurrentDB projections; Added test resources for persistent subscriptions and streams; Added tests for cluster gossip and node state verification; Added tests for the Monitoring API; Added tests for user management operations; Added unit tests for the MockKurrentDBClient spy; Expanded test coverage for KurrentDB core components; Removed obsolete XCTest-based test files.

The package now requires Swift 6.0 and targets macOS 15, iOS 18, tvOS 18, watchOS 11, and visionOS 2. Dependencies have been updated to gRPC-Swift 2.0.0 (including grpc-swift-nio-transport and grpc-swift-protobuf), and the package name has changed from EventStoreDB to swift-kurrentdb, introducing a KurrentDB product and a KurrentDB\_V1 compatibility layer.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 62 → 62 (+0.0)
• Rubric changed (rubric-2026.08.18 → rubric-2026.08.19) — scores are not directly comparable.

• Code Health 100 → 100 (+0.0)
• Architecture 100 → 100 (+0.0)
• Maturity 65 → 65 (+0.0)
• Readiness 56 → 56 (+0.0)
• Security 51 → 51 (+0.0)
• Domain Modelling 100 → 100 (+0.0)
• Event Sourcing 100 → 100 (+0.0)

• The Install section mentions 2.1.0 as the target version but the latest release is v2.1.0, so it reads like a draft or older version. (docs/index.html)

• The API documentation update design spec begins and clips, so the detailed doc-comment rewrite rules (noun/verb start, no type-description sections for target types) are not visible. (docs/superpowers/specs/2026-04-23-api-docs-design.md)

• 6 commits — 3 feature/other, 3 fixes

• scripts/transfer — 4 commits
• Sources/KurrentDB — 1 commit
• server/docker-compose.yaml — 1 commit

• fix: [FIX] Don't require caughtUp as the second subscription message
• fix: [FIX] Persist KurrentDB data across container restarts in docker-compose
• fix: [UPD] Fix ownership and recreate truncate.chk after data migration
• change: [ADD] Script to migrate single-node data into cluster node1 volume
• change: [UPD] Allow single-to-cluster.sh to accept a host path as --source
• change: [UPD] Recreate truncate.chk before chowning target volume

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

gradyzhuo/swift-kurrentdb was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.