Compatibility architecture
Это содержимое пока не доступно на вашем языке.
Chronacta persists committed events for years. Operators upgrade binaries, expand clusters, and integrate via gRPC/SDK. Without explicit compatibility rules, any storage tweak or proto field rename can corrupt data or break clients silently.
Cluster metadata, replication, export/import, and idempotency are part of the current product. Each persisted subsystem carries a format_version or equivalent constant.
Two compatibility surfaces
Section titled “Two compatibility surfaces”| Surface | Contract | Version carrier |
|---|---|---|
| Wire API | gRPC/protobuf stream.v1 |
Protobuf package + generated stubs |
| On-disk formats | Engine durability, backups, auxiliary stores | Per-file format_version / magic |
Wire and disk versions are independent. A server release may bump backup manifest version without changing gRPC package.
SemVer for product releases
Section titled “SemVer for product releases”v1.x— supported stable release line starting withv1.0.0.- A future major line may introduce breaking wire or disk changes.
- MAJOR — breaking wire or breaking disk (without backward read).
- MINOR — additive API, new optional features, backward-compatible disk.
- PATCH — bug fixes only; no format version bump.
Support window (v1.x): we support the current minor and one previous minor.
Git tag = release artifact identity. Binaries do not embed version yet; operators use tag + go build from tag (see release process).
gRPC / protobuf rules
Section titled “gRPC / protobuf rules”- All public RPCs live in
api/proto/stream/v1/. - Additive changes (new fields, new RPCs, new enum values with unknown handling) — allowed in
v1minor releases. - Breaking changes (rename/remove field, change semantics, delete RPC) — require new package
stream.v2and parallel registration period;v1deprecated for ≥1 minor. - Clients MUST ignore unknown proto fields (protobuf default).
- Error codes and messages are part of the contract; changing
FailedPrecondition→InvalidArgumentfor the same condition is breaking.
On-disk format inventory (current)
Section titled “On-disk format inventory (current)”| Component | Path / artifact | Version const | Bump policy |
|---|---|---|---|
| Event record | WAL / segments | record.FormatVersion = 1 |
New engine major; migration tool required |
| Backup archive | *.tar.gz manifest |
backup.FormatVersion = 1 |
Restore rejects unknown; export from old supported |
| Export JSONL | format_version field |
JSONLFormatVersion = 1 |
Import accepts N and N-1 |
| Export binary | header magic + version | BinaryFormatVersion = 1 |
Same as JSONL |
| Idempotency store | data/idempotency/keys.json |
idempotencyStoreVersion = 1 |
Rebuild or migrate offline |
| Schema registry | data/schemas/schemas.json |
registryVersion = 1 |
Forward-compatible JSON |
| Subscriptions | data/subscriptions/ |
storeVersion = 1 |
Offline migration |
| Projections | checkpoint envelope | StoreFormatVersion = 1 |
Rebuild path always available |
| Auth store | data/auth/ |
storeVersion = 1 |
Export users or migrate tool |
| Cluster metadata | data/cluster/cluster.json |
cluster.StoreVersion = 1 |
HA rolling upgrade doc |
| NATS checkpoint | bridge state file | checkpointVersion = 1 |
Replay from position |
Rule: bump version const → implement read path for previous version or document one-way migration + test.
Migration strategy
Section titled “Migration strategy”- Prefer backward-compatible reads — engine opens old segments if record layout unchanged.
- Offline migration — use the migration command and documented manual steps when a release requires it; never auto-delete WAL on startup.
- Projection rebuild — acceptable fallback for projection checkpoint format changes.
- Export/import — universal escape hatch between environments and major versions.
- Cluster — upgrade followers first; see HA rolling upgrade.
The server does not automatically rewrite data/ on startup.
Schema registry vs event store
Section titled “Schema registry vs event store”Schema compatibility modes (none, backward, forward, full) govern registration of new schema versions, not retroactive mutation of committed events. Committed payloads remain immutable.
SDK and CLI
Section titled “SDK and CLI”- CLI/SDK in repo track server
main/ release tag. - Supported skew: same minor required for production; patch skew tolerated (client older patch → server newer patch).
- Idempotency keys and expected-version semantics are stable across patch releases.