Chronicle from Go
Experimental v0: minor releases may break APIs; pin the module version you test against. Companion guidance: Arc.Go and Fundamentals.Go.
This is a standalone event-store client, not an Arc HTTP framework. Use explicit registration rather than C# attributes or assembly discovery. Events are immutable facts represented by named structs; event-source identity is append metadata, not an event payload property.
Verified product sources
| Product | Source checked |
|---|---|
Chronicle.Go (github.com/cratis/chronicle.go) |
client.go, options.go, options_transport.go, registry.go, registry_projections.go, registry_readmodels.go, registry_reactors.go, eventsequences/sequence.go, internal/decision/decision.go, captures/service.go, captures/redaction.go, examples/getting-started/main.go, examples/projections/main.go |
Source and its parity document qualify supported behavior. A README that says observers, projections and automatic lifecycle recovery are absent is stale; those surfaces exist, but that does not mean whole-product parity.
Register and append
Install github.com/cratis/chronicle.go at your chosen release in a consumer module. This complete
package appends one event using local development defaults:
// Copyright (c) Cratis. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
package customers
import (
"context"
"errors"
chronicle "github.com/cratis/chronicle.go"
"github.com/cratis/chronicle.go/events"
)
// CustomerRegistered records a customer's display name.
type CustomerRegistered struct {
Name string `json:"name"`
}
// AppendCustomer uses a caller-bounded context and closes its owned client.
func AppendCustomer(ctx context.Context) (err error) {
registry := chronicle.NewRegistry()
if _, err = chronicle.RegisterEvent[CustomerRegistered](registry,
events.WithID("customer-registered")); err != nil {
return err
}
client, err := chronicle.NewClient(
chronicle.WithDevelopmentDefaults(), chronicle.WithRegistry(registry))
if err != nil {
return err
}
defer func() { err = errors.Join(err, client.Close()) }()
store, err := client.EventStore(ctx, "customers")
if err != nil {
return err
}
result, err := store.EventLog().Append(ctx, "customer-42",
CustomerRegistered{Name: "Ada"})
if err != nil {
return err // The write may have committed. Do not blindly retry.
}
return result.Err()
}
Registration errors and append outcomes are not optional checks. Append returns
both a transport error and a result; after transport success, result.Err() can
still report a rejection. A timeout/disconnect may hide a commit. Choose explicit
concurrency/idempotency semantics before retrying, never a generic write retry.
Use stable persisted event IDs and explicit json names for cross-language data.
For a runnable program and its observable append position, use the tagged getting-started example. This compileable package does not itself start a kernel or prove a successful append.
Connection and gRPC ownership
NewClientvalidates and freezes declarations without network I/O; it does not prove readiness.Dial(ctx, options...)also connects. Complete all registrations before construction; later changes do not mutate that client.WithDevelopmentDefaultsrelaxes TLS certificate verification for development; it is not a certificate whitelist. Production needs validated TLS and explicit production credentials.WithTLSaccepts TLS configuration; never use dev defaults as a production fix for a failed certificate.WithGRPCConnectionborrows agrpc.ClientConn; the caller owns and closes it. Follow the option's explicit-authentication requirement. Close the Chronicle client before its borrowed collaborators. Owned connections belong to the client.Closecancels and joins owned work. Handlers must honor cancellation; a boundedCloseContexttimeout means cleanup is incomplete, not successful. Keep short unary deadlines separate from long-lived subscriptions.WithOnConnected,WithOnDisconnectedandWithLoadBalancerare explicit lifecycle customization points.WithGRPCStatsHandlerborrows concurrent-safe, promptly returning callbacks for owned connections; it conflicts with a borrowed connection and does not authorize interceptors or retries.- For SDK contributors, generate protobuf contracts only from the authoritative inputs using the repository's pinned Buf recipe. Preserve metadata, field numbers, deadlines and checkpoint boundaries; never hand-edit generated contracts.
Read models and side effects
Read projection registration when populating a read model. Start with model-bound tags; use the fluent builder when that cannot express it, then a reducer for genuinely procedural state decisions. Do not mix model-bound mapping tags and fluent mappings for the same declaration.
RegisterReactorHandler(registry, id, func(context.Context, E) error) registers a
typed closure for a registered event. RegisterReactor explicitly registers a type;
its exported methods select events by parameter type, not by handler name. Optional
leading context and reactors.Delivery parameters carry cancellation and delivery
identity. delivery.ID() can key an external idempotency record; it is not an
exactly-once guarantee. Return supported follow-up events rather than manually
recreating effect dispatch; use projections for materialization, reactors for effects.
Requires Chronicle.Go 0.11.0 and kernel 19.70.0 for StartAtTail; check go list -m github.com/Cratis/Chronicle.Go and the server version, or retain catch-up behavior until both are upgraded.
Opt into reactors.StartAtTail() for a new side-effect reactor that must skip
history. It only changes first registration: existing positions are retained and
explicit replay still starts at the beginning. Older kernels ignore this option
and catch up history. observation.Service.FastForward and FastForwardResult
move an observer to the tail; this deliberate administrative skip is not recovery.
reactors.OnceOnly() excludes replay; it does not deduplicate failed-partition
recovery. Effects may repeat after errors, cleanup failures or reconnect. Keep them
idempotent. The kernel owns recovery/quarantine and progress; do not invent resume
positions or acknowledge before successful processing and cleanup. Read the
reactor guide
for exact effect, replay and registration-readiness limits.
Unsupported does not mean success
Requires Chronicle kernel 19.70.0 for the current Go decision-guard profile; check the server version or postpone the client upgrade.
Decision guards include compatibility preflight;
unsupported kernels return ErrUnsupported. Protected operations have their own
kernel capability gates; the client supports qualified protected revisions and
classified read-model replay routes, not every protected watch/profile.
Do not use the deprecated readmodels.DecisionProtectedModel or
DecisionProtectionMetadata compatibility hooks for new work.
Webhook source authorization cannot travel through the CDL-only capture transport.
Save/Validate refuse it with ErrUnsupported before dispatch. Capture credential
JSON import/export is also refused. Never serialize or log webhook credentials or
pretend a rejected configuration was applied.
Verify
- Compile against the released module without workspace/local replacements.
- Test rejection separately from transport error and ambiguous commit recovery.
- Use
chronicletestscenarios for event/read-model contracts within their supported profiles; pure decisions can use standardtestingdirectly. - Exercise registration, cancellation, reconnect, borrowed connections and joined cleanup against the pinned kernel before claiming runtime parity.
- Check the module's
go.modfor the Fundamentals.Go it requires; the separate concepts skill is not a required dependency upgrade.