Skip to content

Build a Cratis Chronicle client

Chronicle speaks gRPC. In theory that means any language with a gRPC implementation can talk to it. In practice, hand-rolling a client means solving the same handful of hard problems every client has to solve before it can do anything useful: generating strongly-typed bindings from the wire contract, exchanging credentials for a token and keeping that token fresh, discovering and load-balancing across a cluster of servers, reconnecting when a connection drops, and rejecting a server whose contract has drifted instead of silently sending it garbage.

None of that is domain logic. It’s the same plumbing whether the client ends up written in Go, Python, Rust, or Java — and it’s exactly the plumbing Chronicle’s own team has already built more than once, for TypeScript, Elixir, and Kotlin. This section is that experience written down as a checklist, so a new client doesn’t have to rediscover it one gap at a time.

Start with The checklist. It’s the whole section distilled into one page — work through it while you build, and come back to it whenever you’re not sure what’s left. The rest of the pages exist to explain the why behind each item.

The shape of every Chronicle client so far

Section titled “The shape of every Chronicle client so far”

Every client Chronicle has shipped follows the same layering, whether or not that was the plan going in:

Kernel .proto files
(Source/Kernel/Protobuf)

Generated contracts package
(published, one per language)

Idiomatic client
(the thing developers import)

Convenience / hosting packages
(optional — ASP.NET Core, Spring Boot, …)

  • The checklist — every item below, pulled into one page to work through.
  • Two ways to start — use the .proto files directly, or ask the Cratis team to generate and publish a contracts package for your language. Most clients so far took the second path.
  • Layering an idiomatic client — why the generated contracts are deliberately not the client developers use, and how a raw client and optional convenience packages sit on top of them.
  • Empty results and query failures — why collection results are never null, and why initialized payloads do not replace checking query success.
  • Authentication and bearer tokens — how a client turns connection-string credentials into a bearer token on every call, and keeps it fresh.
  • Clustering and the connection lifecycle — what a client has to implement to be a good citizen of a multi-server Chronicle cluster.
  • Connection string elements — the object model a client SDK typically wraps around the connection string grammar.
  • Documentation and snippets — how a new client repo’s Documentation/ folder plugs into the shared Chronicle docs site.

Before generating anything yourself, get in touch with the Cratis team. Chronicle’s release pipeline generates TypeScript, Elixir, and Kotlin contracts from the kernel’s .proto files and publishes them to npm, Hex, and Maven Central, version-locked to the kernel release. The Chronicle.Python repository also exists: its cratis-chronicle package depends on a generated contracts wheel attached to a Chronicle GitHub release, not a PyPI package. Python publishing in Chronicle’s release pipeline is disabled until PyPI trusted publishing and the protected GitHub environment are configured. See Two ways to start for the available distribution paths and how to discuss a contracts package for another language.