From 23ed3551cbef4557e42e270f62d5fc8cef3f59ba Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Sun, 23 Aug 2026 13:22:21 -0400 Subject: [PATCH 1/2] chore(client): keep branding independent Signed-off-by: Yordis Prieto --- README.md | 26 ++--- docs/.vuepress/configs/theme.ts | 5 +- .../.vuepress/public/Kurrent Logo - Black.svg | 26 ----- docs/.vuepress/public/Kurrent Logo - Plum.svg | 26 ----- .../.vuepress/public/Kurrent Logo - White.svg | 26 ----- docs/.vuepress/public/js/snippet.js | 86 -------------- docs/.vuepress/public/robots.txt | 2 - docs/api/appending-events.md | 16 +-- docs/api/authentication.md | 6 +- docs/api/delete-stream.md | 8 +- docs/api/getting-started.md | 40 +++---- docs/api/persistent-subscriptions.md | 2 +- docs/api/reading-events.md | 12 +- docs/api/subscriptions.md | 6 +- docs/package.json | 2 +- examples/user_certificates.rs | 2 +- trogon-eventstore/src/client.rs | 8 +- trogon-eventstore/src/grpc.rs | 45 +++----- trogon-eventstore/src/lib.rs | 12 +- trogon-eventstore/src/types.rs | 18 +-- trogon-eventstore/tests/api/streams.rs | 2 +- .../fixtures/connection_string/mockups.toml | 106 ------------------ 22 files changed, 96 insertions(+), 386 deletions(-) delete mode 100644 docs/.vuepress/public/Kurrent Logo - Black.svg delete mode 100644 docs/.vuepress/public/Kurrent Logo - Plum.svg delete mode 100644 docs/.vuepress/public/Kurrent Logo - White.svg delete mode 100644 docs/.vuepress/public/js/snippet.js diff --git a/README.md b/README.md index 656d34b..5de3443 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,15 @@ [Documentation](docs) -Community-maintained Rust gRPC client for TrogonEventStore, derived from the KurrentDB Rust client. +Community-maintained Rust gRPC client for TrogonEventStore. -[KurrentDB] is the event-native database, where business events are immutably stored and streamed. Designed for event-sourced, event-driven, and microservices architectures. +TrogonEventStore is an event-native database where business events are immutably stored and streamed. -## KurrentDB Server Compatibility +## Server compatibility This client is compatible with version `20.6.1` upwards and works on Linux, MacOS and Windows. -Server setup instructions can be found here [KurrentDB Docs], follow the docker setup for the simplest configuration. +Server setup instructions are available in the [TrogonEventStore repository]. ## Installation @@ -40,14 +40,14 @@ struct Foo { async fn main() -> Result<(), Box> { // Creates a client settings for a single node configuration. - let settings = "kurrentdb://admin:changeit@localhost:2113".parse()?; + let settings = "esdb://admin:changeit@localhost:2113".parse()?; let client = Client::new(settings)?; let payload = Foo { is_rust_a_nice_language: true, }; - // It is not mandatory to use JSON as a data format however KurrentDB + // It is not mandatory to use JSON as a data format, but TrogonEventStore // provides great additional value if you do so. let evt = EventData::json("language-poll", &payload)?; @@ -73,11 +73,11 @@ async fn main() -> Result<(), Box> { ## Support -Information on support can be found here: [KurrentDB Support] +Use [GitHub Discussions] for support questions. ## Documentation -Documentation for KurrentDB can be found here: [KurrentDB Docs] +Project documentation is maintained in this repository. Bear in mind that this client is not yet properly documented. We are working hard on a new version of the documentation. @@ -87,11 +87,7 @@ TrogonEventStore Rust Client is licensed under the Apache License 2.0. It is der ## Communities -- [Discuss](https://discuss.kurrent.io/) -- [Discord (Kurrent)](https://discord.gg/Phn9pmCw3t) +- [GitHub Discussions] -[KurrentDB]: https://kurrent.io/ -[KurrentDB rust gRPC]: https://developers.kurrent.io/clients/grpc/getting-started?codeLanguage=Rust -[KurrentDB Docs]: https://developers.kurrent.io/latest.html -[kurrent discuss]: https://discuss.kurrent.io/ -[KurrentDB Support]: https://kurrent.io/support/ +[GitHub Discussions]: https://github.com/TrogonStack/TrogonEventStore-Client-Rust/discussions +[TrogonEventStore repository]: https://github.com/TrogonStack/TrogonEventStore diff --git a/docs/.vuepress/configs/theme.ts b/docs/.vuepress/configs/theme.ts index 41aefcd..819cec2 100644 --- a/docs/.vuepress/configs/theme.ts +++ b/docs/.vuepress/configs/theme.ts @@ -1,13 +1,11 @@ import type {ThemeOptions} from "vuepress-theme-hope"; export const themeOptions: ThemeOptions = { - logo: "/Kurrent Logo - Plum.svg", - logoDark: "/Kurrent Logo - White.svg", docsDir: 'docs', editLink: false, lastUpdated: true, toc: true, - repo: "https://github.com/kurrent-io", + repo: "https://github.com/TrogonStack/TrogonEventStore-Client-Rust", repoLabel: "GitHub", repoDisplay: true, contributors: false, @@ -33,4 +31,3 @@ export const themeOptions: ThemeOptions = { } } } - diff --git a/docs/.vuepress/public/Kurrent Logo - Black.svg b/docs/.vuepress/public/Kurrent Logo - Black.svg deleted file mode 100644 index 6e2ea3b..0000000 --- a/docs/.vuepress/public/Kurrent Logo - Black.svg +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/.vuepress/public/Kurrent Logo - Plum.svg b/docs/.vuepress/public/Kurrent Logo - Plum.svg deleted file mode 100644 index ea6f869..0000000 --- a/docs/.vuepress/public/Kurrent Logo - Plum.svg +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/.vuepress/public/Kurrent Logo - White.svg b/docs/.vuepress/public/Kurrent Logo - White.svg deleted file mode 100644 index 739a8ce..0000000 --- a/docs/.vuepress/public/Kurrent Logo - White.svg +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/.vuepress/public/js/snippet.js b/docs/.vuepress/public/js/snippet.js deleted file mode 100644 index 14064ad..0000000 --- a/docs/.vuepress/public/js/snippet.js +++ /dev/null @@ -1,86 +0,0 @@ -!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep".split(" "),n=0;n -1) { - var c = document.querySelector("link[rel='canonical']"); - args.push({ - __t: "bpc", - c: c && c.getAttribute("href") || undefined, - p: location.pathname, - u: location.href, - s: location.search, - t: document.title, - r: document.referrer - }); - } - - args.unshift(e); - analytics.push(args); - return analytics; - }; - }; - - for (var i = 0; i < analytics.methods.length; i++) { - var key = analytics.methods[i]; - analytics[key] = analytics.factory(key); - } - - analytics.load = function (key, options) { - var t = document.createElement("script"); - t.type = "text/javascript"; - t.async = true; - t.setAttribute("data-global-segment-analytics-key", globalAnalyticsKey) - t.src = "https://cloud.kurrent.io/segment/ajs/REDACTED"; - - var first = document.getElementsByTagName("script")[0]; - first.parentNode.insertBefore(t, first); - analytics._loadOptions = options; - }; - analytics._writeKey = "REDACTED"; - analytics.SNIPPET_VERSION = "5.2.1"; - analytics.load("REDACTED"); -})(); diff --git a/docs/.vuepress/public/robots.txt b/docs/.vuepress/public/robots.txt index dbe84f0..d0eb1a1 100644 --- a/docs/.vuepress/public/robots.txt +++ b/docs/.vuepress/public/robots.txt @@ -11,5 +11,3 @@ Disallow: /codeql-analysis.yml Disallow: /package.json Disallow: /serve.js Disallow: /yarn.lock - -Sitemap: https://docs.kurrent.io/sitemap.xml diff --git a/docs/api/appending-events.md b/docs/api/appending-events.md index be66b27..4480721 100644 --- a/docs/api/appending-events.md +++ b/docs/api/appending-events.md @@ -4,7 +4,7 @@ order: 2 # Appending events -When you start working with KurrentDB, your application streams are empty. The first meaningful operation is to add one or more events to the database using this API. +When you start working with TrogonEventStore, your application streams are empty. The first meaningful operation is to add one or more events to the database using this API. ::: tip Check the [Getting Started](getting-started.md) guide to learn how to configure and use the client SDK. @@ -12,7 +12,7 @@ Check the [Getting Started](getting-started.md) guide to learn how to configure ## Append your first event -The simplest way to append an event to KurrentDB is to create an `EventData` object and call `append_to_stream` method. +The simplest way to append an event to TrogonEventStore is to create an `EventData` object and call `append_to_stream` method. ```rs{7-11} let data = OrderCreated { @@ -38,11 +38,11 @@ If you are new to Event Sourcing, please study the [Handling concurrency](#handl ## Working with EventData -Events appended to KurrentDB must be wrapped in an `EventData` object. This allows you to specify the event's content, the type of event, and whether it's in JSON format. In its simplest form, you need three arguments: **eventId**, **eventType**, and **eventData**. +Events appended to TrogonEventStore must be wrapped in an `EventData` object. This allows you to specify the event's content, the type of event, and whether it's in JSON format. In its simplest form, you need three arguments: **eventId**, **eventType**, and **eventData**. ### EventID -This takes the format of a `UUID` and is used to uniquely identify the event you are trying to append. If two events with the same `UUID` are appended to the same stream in quick succession, KurrentDB will only append one of the events to the stream. +This takes the format of a `UUID` and is used to uniquely identify the event you are trying to append. If two events with the same `UUID` are appended to the same stream in quick succession, TrogonEventStore will only append one of the events to the stream. For example, the following code will only append a single event: @@ -72,11 +72,11 @@ It is common to see the explicit event code type name used as the type as it mak ### Data -Representation of your event data. It is recommended that you store your events as JSON objects. This allows you to take advantage of all of KurrentDB's functionality, such as projections. That said, you can save events using whatever format suits your workflow. Eventually, the data will be stored as encoded bytes. +Representation of your event data. It is recommended that you store your events as JSON objects. This allows you to take advantage of all of TrogonEventStore's functionality, such as projections. That said, you can save events using whatever format suits your workflow. Eventually, the data will be stored as encoded bytes. ### Metadata -Storing additional information alongside your event that is part of the event itself is standard practice. This can be correlation IDs, timestamps, access information, etc. KurrentDB allows you to store a separate byte array containing this information to keep it separate. +Storing additional information alongside your event that is part of the event itself is standard practice. This can be correlation IDs, timestamps, access information, etc. TrogonEventStore allows you to store a separate byte array containing this information to keep it separate. ### ContentType @@ -84,7 +84,7 @@ The content type indicates whether the event is stored as JSON or binary format. ## Handling concurrency -When appending events to a stream, you can supply a *stream state*. Your client uses this to inform KurrentDB of the state or version you expect the stream to be in when appending an event. If the stream isn't in that state, an exception will be thrown. +When appending events to a stream, you can supply a *stream state*. Your client uses this to inform TrogonEventStore of the state or version you expect the stream to be in when appending an event. If the stream isn't in that state, an exception will be thrown. For example, if you try to append the same record twice, expecting both times that the stream doesn't exist, you will get an exception on the second: @@ -118,7 +118,7 @@ There are several available expected revision options: - `Exact` - Stream should be at specific revision This check can be used to implement optimistic concurrency. When retrieving a -stream from KurrentDB, note the current version number. When you save it back, +stream from TrogonEventStore, note the current version number. When you save it back, you can determine if somebody else has modified the record in the meantime. ```rs{8-13,22,36-38} diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 21aef88..a3ffed2 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -11,7 +11,7 @@ X.509 certificates are digital certificates that use the X.509 public key infras ## Prerequisites -1. KurrentDB 25.0 or greater, or EventStoreDB 24.10 or later. +1. TrogonEventStore, or EventStoreDB 24.10 or later. 2. A valid X.509 certificate configured on the Database. See [configuration steps](@server/security/user-authentication.html#user-x-509-certificates) for more details. ## Connect using an x.509 certificate @@ -32,6 +32,6 @@ The client supports the following parameters: To authenticate, include these two parameters in your connection string or constructor when initializing the client: ```rs -let settings = "kurrentdb://localhost:2113?tls=true&userCertFile={pathToCaFile}&userKeyFile={pathToKeyFile}".parse()?; +let settings = "esdb://localhost:2113?tls=true&userCertFile={pathToCaFile}&userKeyFile={pathToKeyFile}".parse()?; let client = Client::new(settings)?; -``` \ No newline at end of file +``` diff --git a/docs/api/delete-stream.md b/docs/api/delete-stream.md index dcd848d..d2f1724 100644 --- a/docs/api/delete-stream.md +++ b/docs/api/delete-stream.md @@ -4,15 +4,15 @@ order: 9 # Deleting Events -In KurrentDB, you can delete events and streams either partially or +In TrogonEventStore, you can delete events and streams either partially or completely. Settings like $maxAge and $maxCount help control how long events are kept or how many events are stored in a stream, but they won't delete the entire -stream. When you need to fully remove a stream, KurrentDB offers two +stream. When you need to fully remove a stream, TrogonEventStore offers two options: Soft Delete and Hard Delete. ## Soft delete -Soft delete in KurrentDB allows you to mark a stream for deletion without +Soft delete in TrogonEventStore allows you to mark a stream for deletion without completely removing it, so you can still add new events later. While you can do this through the UI, using code is often better for automating the process, handling many streams at once, or including custom rules. Code is especially @@ -35,7 +35,7 @@ process. The stream can still be reopened by appending new events. ## Hard delete -Hard delete in KurrentDB permanently removes a stream and its events. While +Hard delete in TrogonEventStore permanently removes a stream and its events. While you can use the HTTP API, code is often better for automating the process, managing multiple streams, and ensuring precise control. Code is especially useful when you need to integrate hard delete into larger workflows or apply diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md index 6cd0a88..cd956a5 100644 --- a/docs/api/getting-started.md +++ b/docs/api/getting-started.md @@ -4,8 +4,8 @@ order: 1 # Getting started -This guide will help you get started with KurrentDB in your Rust application. -It covers the basic steps to connect to KurrentDB, create events, append them +This guide will help you get started with TrogonEventStore in your Rust application. +It covers the basic steps to connect to TrogonEventStore, create events, append them to streams, and read them back. ## Required packages @@ -23,34 +23,34 @@ tokio = {version = "1.32.0", features = ["full"]} version = "4.0.0" ``` -## Connecting to KurrentDB +## Connecting to TrogonEventStore -To connect your application to KurrentDB, you need to configure and create a client instance. +To connect your application to TrogonEventStore, you need to configure and create a client instance. ::: tip Insecure clusters -The recommended way to connect to KurrentDB is using secure mode (which is -the default). However, if your KurrentDB instance is running in insecure +The recommended way to connect to TrogonEventStore is using secure mode (which is +the default). However, if your TrogonEventStore instance is running in insecure mode, you must explicitly set `tls=false` in your connection string or client configuration. ::: -KurrentDB uses connection strings to configure the client connection. The connection string supports two protocols: +TrogonEventStore uses connection strings to configure the client connection. The connection string supports two protocols: -- **`kurrentdb://`** - for connecting directly to specific node endpoints (single node or multi-node cluster with explicit endpoints) -- **`kurrentdb+discover://`** - for connecting using cluster discovery via DNS or gossip endpoints +- **`esdb://`** - for connecting directly to specific node endpoints (single node or multi-node cluster with explicit endpoints) +- **`esdb+discover://`** - for connecting using cluster discovery via DNS or gossip endpoints -When using `kurrentdb://`, you specify the exact endpoints to connect to. The client will connect directly to these endpoints. For multi-node clusters, you can specify multiple endpoints separated by commas, and the client will query each node's Gossip API to get cluster information, then picks a node based on the URI's node preference. +When using `esdb://`, you specify the exact endpoints to connect to. The client will connect directly to these endpoints. For multi-node clusters, you can specify multiple endpoints separated by commas, and the client will query each node's Gossip API to get cluster information, then picks a node based on the URI's node preference. -With `kurrentdb+discover://`, the client uses cluster discovery to find available nodes. This is particularly useful when you have a DNS A record pointing to cluster nodes or when you want the client to automatically discover the cluster topology. +With `esdb+discover://`, the client uses cluster discovery to find available nodes. This is particularly useful when you have a DNS A record pointing to cluster nodes or when you want the client to automatically discover the cluster topology. ::: info Gossip support -Since version 22.10, kurrentdb supports gossip on single-node deployments, so -`kurrentdb+discover://` can be used for any topology, including single-node setups. +Single-node deployments support gossip, so `esdb+discover://` can be used for any +topology, including single-node setups. ::: For cluster connections using discovery, use the following format: ``` -kurrentdb+discover://admin:changeit@cluster.dns.name:2113 +esdb+discover://admin:changeit@cluster.dns.name:2113 ``` Where `cluster.dns.name` is a DNS `A` record that points to all cluster nodes. @@ -58,13 +58,13 @@ Where `cluster.dns.name` is a DNS `A` record that points to all cluster nodes. For direct connections to specific endpoints, you can specify individual nodes: ``` -kurrentdb://admin:changeit@node1.dns.name:2113,node2.dns.name:2113,node3.dns.name:2113 +esdb://admin:changeit@node1.dns.name:2113,node2.dns.name:2113,node3.dns.name:2113 ``` Or for a single node: ``` -kurrentdb://admin:changeit@localhost:2113 +esdb://admin:changeit@localhost:2113 ``` There are a number of query parameters that can be used in the connection string to instruct the cluster how and where the connection should be established. All query parameters are optional. @@ -85,14 +85,14 @@ There are a number of query parameters that can be used in the connection string | `userCertFile` | String, file path | None | User certificate file for X.509 authentication. | | `userKeyFile` | String, file path | None | Key file for the user certificate used for X.509 authentication. | -When connecting to an insecure instance, specify `tls=false` parameter. For example, for a node running locally use `kurrentdb://localhost:2113?tls=false`. Note that usernames and passwords aren't provided there because insecure deployments don't support authentication and authorisation. +When connecting to an insecure instance, specify `tls=false` parameter. For example, for a node running locally use `esdb://localhost:2113?tls=false`. Note that usernames and passwords aren't provided there because insecure deployments don't support authentication and authorisation. ## Creating a client First, create a client and get it connected to the database. ```rs -let settings = "kurrentdb://localhost:2113?tls=false&tlsVerifyCert=false".parse()?; +let settings = "esdb://localhost:2113?tls=false&tlsVerifyCert=false".parse()?; let client = Client::new(settings)?; ``` @@ -100,7 +100,7 @@ The client instance can be used as a singleton across the whole application. It ## Creating an event -You can write anything to KurrentDB as events. The client needs a byte array as the event payload. Normally, you'd use a serialized object, and it's up to you to choose the serialization method. +You can write anything to TrogonEventStore as events. The client needs a byte array as the event payload. Normally, you'd use a serialized object, and it's up to you to choose the serialization method. The code snippet below creates an event object instance, serializes it, and adds it as a payload to the `EventData` structure, which the client can then write to the database. @@ -137,4 +137,4 @@ let mut stream = client.read_stream("order-123", &options).await?; while let Some(event) = stream.next().await? { // Handle the event } -``` \ No newline at end of file +``` diff --git a/docs/api/persistent-subscriptions.md b/docs/api/persistent-subscriptions.md index 3ac2983..7e7e129 100644 --- a/docs/api/persistent-subscriptions.md +++ b/docs/api/persistent-subscriptions.md @@ -166,7 +166,7 @@ resources. For use with an indexing projection such as the system `$by_category` projection. -KurrentDB inspects the event for its source stream id, hashing the id to one +TrogonEventStore inspects the event for its source stream id, hashing the id to one of 1024 buckets assigned to individual clients. When a client disconnects, its buckets are assigned to other clients. When a client connects, it is assigned some existing buckets. This naively attempts to maintain a balanced workload. diff --git a/docs/api/reading-events.md b/docs/api/reading-events.md index 8d79213..3960be7 100644 --- a/docs/api/reading-events.md +++ b/docs/api/reading-events.md @@ -4,16 +4,16 @@ order: 3 # Reading Events -KurrentDB provides two primary methods for reading events: reading from an +TrogonEventStore provides two primary methods for reading events: reading from an individual stream to retrieve events from a specific named stream, or reading from the `$all` stream to access all events across the entire event store. -Events in KurrentDB are organized within individual streams and use two +Events in TrogonEventStore are organized within individual streams and use two distinct positioning systems to track their location. The **revision number** is a 64-bit signed integer (`long`) that represents the sequential position of an event within its specific stream. Events are numbered starting from 0, with each new event receiving the next sequential revision number (0, 1, 2, 3...). The -**global position** represents the event's location in KurrentDB's global +**global position** represents the event's location in TrogonEventStore's global transaction log and consists of two coordinates: the `commit` position (where the transaction was committed in the log) and the `prepare` position (where the transaction was initially prepared). @@ -83,7 +83,7 @@ let options = ReadStreamOptions::default() #### resolveLinkTos -When using projections to create new events you can set whether the generated events are pointers to existing events. Setting this value to true will tell KurrentDB to return the event as well as the event linking to it. +When using projections to create new events you can set whether the generated events are pointers to existing events. Setting this value to true will tell TrogonEventStore to return the event as well as the event linking to it. ```rs let options = ReadAllOptions::default().resolve_link_tos(); @@ -200,7 +200,7 @@ let options = ReadAllOptions::default() #### resolveLinkTos -When using projections to create new events you can set whether the generated events are pointers to existing events. Setting this value to true will tell KurrentDB to return the event as well as the event linking to it. +When using projections to create new events you can set whether the generated events are pointers to existing events. Setting this value to true will tell TrogonEventStore to return the event as well as the event linking to it. ```rs let options = ReadAllOptions::default().resolve_link_tos(); @@ -231,7 +231,7 @@ Read one event backwards to find the last position in the `$all` stream. ### Handling system events -KurrentDB will also return system events when reading from the `$all` stream. In most cases you can ignore these events. +TrogonEventStore will also return system events when reading from the `$all` stream. In most cases you can ignore these events. All system events begin with `$` or `$$` and can be easily ignored by checking the `event_type` property. diff --git a/docs/api/subscriptions.md b/docs/api/subscriptions.md index 8197cbb..88990ca 100644 --- a/docs/api/subscriptions.md +++ b/docs/api/subscriptions.md @@ -113,7 +113,7 @@ let options = SubscribeToAllOptions::default().position(StreamPosition::End); ## Resolving link-to events -Link-to events point to events in other streams in KurrentDB. These are +Link-to events point to events in other streams in TrogonEventStore. These are generally created by projections such as the `$by_event_type` projection which links events of the same event type into the same stream. This makes it easier to look up all events of a specific type. @@ -223,7 +223,7 @@ let options = ## Server-side Filtering -KurrentDB allows you to filter events while subscribing to the `$all` stream to only receive the events you care about. You can filter by event type or stream name using a regular expression or a prefix. Server-side filtering is currently only available on the `$all` stream. +TrogonEventStore allows you to filter events while subscribing to the `$all` stream to only receive the events you care about. You can filter by event type or stream name using a regular expression or a prefix. Server-side filtering is currently only available on the `$all` stream. ::: tip Server-side filtering was introduced as a simpler alternative to projections. You should consider filtering before creating a projection to include the events you care about. @@ -296,7 +296,7 @@ A checkpoint is the position of an event in the `$all` stream to which your appl To create a checkpoint, store the event's commit or prepare position. ::: warning -If your database contains events created by the legacy TCP client using the [transaction feature](https://docs.kurrent.io/clients/tcp/dotnet/21.2/appending.html#transactions), you should store both the commit and prepare positions together as your checkpoint. +If your database contains events created by a legacy TCP client using transactions, you should store both the commit and prepare positions together as your checkpoint. ::: ### Updating checkpoints at regular intervals diff --git a/docs/package.json b/docs/package.json index 14f729c..286c97c 100644 --- a/docs/package.json +++ b/docs/package.json @@ -3,7 +3,7 @@ "version": "1.0.0", "private": true, "type": "module", - "author": "Kurrent Inc", + "author": "Straw Hat, LLC", "devDependencies": { "@babel/cli": "^7.24.8", "@babel/core": "^7.24.9", diff --git a/examples/user_certificates.rs b/examples/user_certificates.rs index 80c5a26..42ac2ac 100644 --- a/examples/user_certificates.rs +++ b/examples/user_certificates.rs @@ -11,7 +11,7 @@ type Result = std::result::Result>; pub async fn user_certificates() -> Result<()> { // region client-with-user-certificates - let settings = "kurrentdb://admin:changeit@{endpoint}?tls=true&userCertFile={pathToCaFile}&userKeyFile={pathToKeyFile}".parse()?; + let settings = "esdb://admin:changeit@{endpoint}?tls=true&userCertFile={pathToCaFile}&userKeyFile={pathToKeyFile}".parse()?; let client = Client::new(settings)?; // endregion client-with-user-certificates diff --git a/trogon-eventstore/src/client.rs b/trogon-eventstore/src/client.rs index df5022e..d45c02e 100644 --- a/trogon-eventstore/src/client.rs +++ b/trogon-eventstore/src/client.rs @@ -21,9 +21,9 @@ use crate::{ }; /// Represents a client to a single node. `Client` maintains a full duplex -/// communication to KurrentDB. +/// communication to TrogonEventStore. /// -/// Many threads can use a KurrentDB client at the same time +/// Many threads can use a TrogonEventStore client at the same time /// or a single thread can make many asynchronous requests. #[derive(Clone)] pub struct Client { @@ -32,12 +32,12 @@ pub struct Client { } impl Client { - /// Creates a gRPC client to a KurrentDB database. + /// Creates a gRPC client to a TrogonEventStore database. pub fn new(settings: ClientSettings) -> eyre::Result { Client::with_runtime_handle(tokio::runtime::Handle::current(), settings) } - /// Creates a gRPC client to a KurrentDB database using an existing tokio runtime. + /// Creates a gRPC client to a TrogonEventStore database using an existing tokio runtime. pub fn with_runtime_handle( handle: tokio::runtime::Handle, settings: ClientSettings, diff --git a/trogon-eventstore/src/grpc.rs b/trogon-eventstore/src/grpc.rs index 6c31044..6cc8711 100644 --- a/trogon-eventstore/src/grpc.rs +++ b/trogon-eventstore/src/grpc.rs @@ -1,6 +1,5 @@ use rustls::pki_types::pem::PemObject; use std::cmp::Ordering; -use std::collections::HashSet; use std::fmt::{Debug, Display}; use std::str::FromStr; use std::sync::Once; @@ -258,11 +257,11 @@ fn default_keep_alive_timeout() -> Duration { ClientSettings::default().keep_alive_timeout } -/// Gathers all the settings related to a gRPC client with a KurrentDB database. +/// Gathers all the settings related to a gRPC client with a TrogonEventStore database. /// `ClientSettings` can only be created when parsing a connection string. /// /// ``` -/// # use kurrent::ClientSettings; +/// # use trogon_eventstore::ClientSettings; /// # fn main() -> Result<(), Box> { /// let setts = "esdb://localhost:1234?tls=false".parse::()?; /// # Ok(()) @@ -273,7 +272,7 @@ fn default_keep_alive_timeout() -> Duration { /// For example, you can define a cluster-mode client based on a fixed set of gossip seeds: /// /// ``` -/// # use kurrent::ClientSettings; +/// # use trogon_eventstore::ClientSettings; /// # fn main() -> Result<(), Box> { /// let setts = "esdb://localhost:1111,localhost:2222,localhost:3333".parse::()?; /// # Ok(()) @@ -283,7 +282,7 @@ fn default_keep_alive_timeout() -> Duration { /// Same example except we are using DNS discovery this time. The client will perform SRV queries /// to resolve all the node associated to that domain: /// ``` -/// # use kurrent::ClientSettings; +/// # use trogon_eventstore::ClientSettings; /// # fn main() -> Result<(), Box> { /// let setts = "esdb+discover://mydomain:1234".parse::()?; /// # Ok(()) @@ -453,33 +452,23 @@ where } } -lazy_static::lazy_static! { - static ref SUPPORTED_PROTOCOLS: HashSet<&'static str> = { - let mut s = HashSet::new(); - s.insert("esdb"); - s.insert("esdb+discover"); - s.insert("kurrentdb"); - s.insert("kurrentdb+discover"); - s.insert("kurrent"); - s.insert("kurrent+discover"); - s.insert("kdb"); - s.insert("kdb+discover"); - s - }; -} +const DIRECT_CONNECTION_SCHEME: &str = "esdb"; +const DISCOVER_CONNECTION_SCHEME: &str = "esdb+discover"; fn parse_from_url( mut result: ClientSettings, url: Url, ) -> Result { - if !SUPPORTED_PROTOCOLS.contains(url.scheme()) { - return Err(ClientSettingsParseError { - message: format!("Unknown URL scheme: {}", url.scheme()), - error: None, - }); - } - - result.dns_discover = url.scheme().contains("+discover"); + result.dns_discover = match url.scheme() { + DIRECT_CONNECTION_SCHEME => false, + DISCOVER_CONNECTION_SCHEME => true, + scheme => { + return Err(ClientSettingsParseError { + message: format!("Unknown URL scheme: {scheme}"), + error: None, + }); + } + }; if !url.username().is_empty() { result.default_user_name = Some(Credentials::new( @@ -1264,7 +1253,7 @@ impl GrpcClient { pub(crate) fn handle_error(sender: &UnboundedSender, connection_id: Uuid, err: &crate::Error) { if let crate::Error::ServerError(status) = err { error!( - "Current selected KurrentDB node gone unavailable. Starting node selection process: {}", + "Current selected node became unavailable. Starting node selection process: {}", status ); diff --git a/trogon-eventstore/src/lib.rs b/trogon-eventstore/src/lib.rs index 373a3b5..defb09e 100755 --- a/trogon-eventstore/src/lib.rs +++ b/trogon-eventstore/src/lib.rs @@ -1,12 +1,12 @@ //! Community-maintained Rust gRPC client for TrogonEventStore. //! -//! [KurrentDB] is an open-source database built from the ground up for Event Sourcing, with Complex Event Processing in Javascript. +//! TrogonEventStore is an open-source database built for event sourcing. //! -//! ## KurrentDB Server Compatibility +//! ## Server compatibility //! This client is compatible with version `20.6.1` upwards and works on Linux, MacOS and Windows. //! //! -//! Server setup instructions can be found here [KurrentDB Docs], follow the docker setup for the simplest configuration. +//! Server setup instructions are available in the [TrogonEventStore repository]. //! //! # Example //! @@ -23,14 +23,14 @@ //! async fn main() -> Result<(), Box> { //! //! // Creates a client settings for a single node configuration. -//! let settings = "kurrentdb://admin:changeit@localhost:2113".parse()?; +//! let settings = "esdb://admin:changeit@localhost:2113".parse()?; //! let client = Client::new(settings)?; //! //! let payload = Foo { //! is_rust_a_nice_language: true, //! }; //! -//! // It is not mandatory to use JSON as a data format however KurrentDB +//! // It is not mandatory to use JSON as a data format, but TrogonEventStore //! // provides great additional value if you do so. //! let evt = EventData::json("language-poll", &payload)?; //! @@ -53,7 +53,7 @@ //! Ok(()) //! } //! ``` -//! [KurrentDB]: https://eventstore.com/ +//! [TrogonEventStore repository]: https://github.com/TrogonStack/TrogonEventStore //! [eventstoredb docs]: https://developers.eventstore.com/server/20.6/server/installation/ mod batch; mod client; diff --git a/trogon-eventstore/src/types.rs b/trogon-eventstore/src/types.rs index 9bd54b7..2f704d4 100755 --- a/trogon-eventstore/src/types.rs +++ b/trogon-eventstore/src/types.rs @@ -53,7 +53,7 @@ impl Credentials { } } -/// Authentication mode used when sending a request to KurrentDB. +/// Authentication mode used when sending a request to TrogonEventStore. /// /// Supports HTTP Basic auth (login + password) and Bearer token auth (e.g. an /// OAuth/OIDC access token). `Authentication` implements `From`, @@ -143,11 +143,11 @@ where /// Constants used for expected version control. /// The use of expected version can be a bit tricky especially when discussing -/// assurances given by the KurrentDB server. +/// assurances given by the TrogonEventStore server. /// -/// The KurrentDB server will assure idempotency for all operations using +/// The TrogonEventStore server will assure idempotency for all operations using /// any value in `StreamState` except `StreamState::Any`. When using -/// `StreamState::Any`, the KurrentDB server will do its best to assure +/// `StreamState::Any`, the TrogonEventStore server will do its best to assure /// idempotency but will not guarantee idempotency. #[derive(Copy, Clone, Debug, Eq, PartialEq)] pub enum StreamState { @@ -174,7 +174,7 @@ impl std::fmt::Display for StreamState { } /// A structure referring to a potential logical record position in the -/// KurrentDB transaction file. +/// TrogonEventStore transaction file. #[derive(Debug, Copy, Clone, PartialEq, Eq)] pub struct Position { /// Commit position of the record. @@ -738,7 +738,7 @@ impl<'de> Visitor<'de> for AclVisitor { type Value = Option; fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result { - write!(formatter, "a KurrentDB ACL") + write!(formatter, "a TrogonEventStore ACL") } fn visit_str(self, value: &str) -> std::result::Result @@ -940,7 +940,7 @@ impl<'de> Visitor<'de> for RolesVisitor { type Value = Option>; fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result { - write!(formatter, "a KurrentDB role or role list") + write!(formatter, "a TrogonEventStore role or role list") } fn visit_none(self) -> std::result::Result @@ -1457,7 +1457,7 @@ pub struct Endpoint { } #[derive(Error, Debug, Clone)] -/// KurrentDB command error. +/// TrogonEventStore command error. pub enum Error { #[error("Server-side error: {0}")] ServerError(String), @@ -1585,7 +1585,7 @@ impl Error { } #[derive(Error, Debug, Clone)] -/// KurrentDB command error. +/// TrogonEventStore command error. pub enum GrpcConnectionError { #[error("Max discovery attempt count reached. count: {0}")] MaxDiscoveryAttemptReached(usize), diff --git a/trogon-eventstore/tests/api/streams.rs b/trogon-eventstore/tests/api/streams.rs index bc094e5..080e249 100644 --- a/trogon-eventstore/tests/api/streams.rs +++ b/trogon-eventstore/tests/api/streams.rs @@ -47,7 +47,7 @@ async fn test_tick_date_conversion(client: &Client) -> trogon_eventstore::Result // We read all stream events by batch. async fn test_read_all_stream_events(client: &Client) -> trogon_eventstore::Result<()> { - // kurrent should always have "some" events in $all, since kurrent itself uses streams, ouroboros style. + // The server should always have some events in $all because it uses streams internally. let result = client.read_all(&Default::default()).await?.next().await?; assert!(result.is_some()); diff --git a/trogon-eventstore/tests/fixtures/connection_string/mockups.toml b/trogon-eventstore/tests/fixtures/connection_string/mockups.toml index 9eecba0..138cef0 100644 --- a/trogon-eventstore/tests/fixtures/connection_string/mockups.toml +++ b/trogon-eventstore/tests/fixtures/connection_string/mockups.toml @@ -444,109 +444,3 @@ keep_alive_timeout = 10_000 [[mockups.expected.hosts]] host = "localhost" port = 2_113 - -[[mockups]] -string = "kurrentdb://localhost" -[mockups.expected] -dns_discover = false -max_discover_attempts = 3 -discovery_interval = 500 -gossip_timeout = 3_000 -preference = "Leader" -secure = true -tls_verify_cert = true -keep_alive_interval = 10_000 -keep_alive_timeout = 10_000 -[[mockups.expected.hosts]] -host = "localhost" -port = 2_113 - -[[mockups]] -string = "kurrent://localhost" -[mockups.expected] -dns_discover = false -max_discover_attempts = 3 -discovery_interval = 500 -gossip_timeout = 3_000 -preference = "Leader" -secure = true -tls_verify_cert = true -keep_alive_interval = 10_000 -keep_alive_timeout = 10_000 -[[mockups.expected.hosts]] -host = "localhost" -port = 2_113 - -[[mockups]] -string = "kdb://localhost" -[mockups.expected] -dns_discover = false -max_discover_attempts = 3 -discovery_interval = 500 -gossip_timeout = 3_000 -preference = "Leader" -secure = true -tls_verify_cert = true -keep_alive_interval = 10_000 -keep_alive_timeout = 10_000 -[[mockups.expected.hosts]] -host = "localhost" -port = 2_113 - -[[mockups]] -string = "kurrentdb+discover://user:pass@host?nodePreference=follower&tlsVerifyCert=false" -[mockups.expected] -dns_discover = true -max_discover_attempts = 3 -discovery_interval = 500 -gossip_timeout = 3_000 -preference = "Follower" -secure = true -tls_verify_cert = false -keep_alive_interval = 10_000 -keep_alive_timeout = 10_000 -[mockups.expected.default_user_name] -login = "user" -password = "pass" -[[mockups.expected.hosts]] -host = "host" -port = 2_113 - -[[mockups]] -string = "kurrent+discover://user:pass@host?nodePreference=follower&tlsVerifyCert=false" -[mockups.expected] -dns_discover = true -max_discover_attempts = 3 -discovery_interval = 500 -gossip_timeout = 3_000 -preference = "Follower" -secure = true -tls_verify_cert = false -keep_alive_interval = 10_000 -keep_alive_timeout = 10_000 -[mockups.expected.default_user_name] -login = "user" -password = "pass" -[[mockups.expected.hosts]] -host = "host" -port = 2_113 - -[[mockups]] -string = "kdb+discover://user:pass@host?nodePreference=follower&tlsVerifyCert=false" -[mockups.expected] -dns_discover = true -max_discover_attempts = 3 -discovery_interval = 500 -gossip_timeout = 3_000 -preference = "Follower" -secure = true -tls_verify_cert = false -keep_alive_interval = 10_000 -keep_alive_timeout = 10_000 -[mockups.expected.default_user_name] -login = "user" -password = "pass" -[[mockups.expected.hosts]] -host = "host" -port = 2_113 - From 337b6c2a1a90cce5d35735aa6583323335229492 Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Sun, 23 Aug 2026 15:24:10 -0400 Subject: [PATCH 2/2] fix(docs): keep installation guidance usable Signed-off-by: Yordis Prieto --- docs/api/getting-started.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md index cd956a5..83c4707 100644 --- a/docs/api/getting-started.md +++ b/docs/api/getting-started.md @@ -19,8 +19,10 @@ serde = "1.0.188" futures = "0.3.28" tokio = {version = "1.32.0", features = ["full"]} -[dependencies.eventstore] -version = "4.0.0" +[dependencies.trogon-eventstore] +git = "https://github.com/TrogonStack/TrogonEventStore-Client-Rust" +tag = "trogon-eventstore@v0.1.0" +version = "0.1.0" ``` ## Connecting to TrogonEventStore @@ -49,7 +51,7 @@ topology, including single-node setups. For cluster connections using discovery, use the following format: -``` +```text esdb+discover://admin:changeit@cluster.dns.name:2113 ``` @@ -57,13 +59,13 @@ Where `cluster.dns.name` is a DNS `A` record that points to all cluster nodes. For direct connections to specific endpoints, you can specify individual nodes: -``` +```text esdb://admin:changeit@node1.dns.name:2113,node2.dns.name:2113,node3.dns.name:2113 ``` Or for a single node: -``` +```text esdb://admin:changeit@localhost:2113 ``` @@ -92,6 +94,8 @@ When connecting to an insecure instance, specify `tls=false` parameter. For exam First, create a client and get it connected to the database. ```rs +use trogon_eventstore::Client; + let settings = "esdb://localhost:2113?tls=false&tlsVerifyCert=false".parse()?; let client = Client::new(settings)?; ```