v0.1.1

[GianIac]

This is v0.1.1 !!!

What's in here

Here is what v0.1.1 represents as a whole:

Wire Protocol & Versioning

• Explicit protocol_version field in Hello / HelloAck, bumped to 4
• Structured wire errors (WireError): ProtocolMismatch, OpRejected, RateLimited, NotAuthorized, Internal
• New MessageKind::Error variant; protocol mismatch now sends WireError::ProtocolMismatch when possible before closing, instead of dropping the socket silently
• New WireRetryPolicy enum (#[non_exhaustive]) describing per-error reconnect semantics (fatal, retry, retry-after, request-fatal)
• E2E test: previous release binary (v0.1.0) + current binary reject incompatible protocol versions without exchanging ops
• Documented compatibility matrix: same version accepted, mismatches rejected

Reconnect Loop Backoff

• Backoff is now differentiated by error type, not by "any failure"
• WireError::RateLimited { retry_after_ms } honored, bounded by the configured reconnect max delay, without growing exponential backoff
• Fatal wire errors (ProtocolMismatch, NotAuthorized) stop automatic reconnect for that configured peer with a warn! log
• Retryable errors keep the normal exponential backoff
• PeerReconnectState::stop() + guarded loop: a stopped peer is never retried until reset
• Overflow-safe deadline arithmetic: Duration::MAX retry-after no longer panics

Schema & Migration

• Magic number + version header in every sled table: __nx/schema/<table>
• Legacy migration v0 -> v1: validates existing records without rewriting payloads
• Generic step registry for sequential N -> N+1 upgrades
• Structured record migrations are now scoped: a record step may only mutate its own source key in the source namespace (no silent sibling writes or deletes)
• Fixture-based migration test generated from the v0.1.0 tag

Offline Migration CLI

• New command: nx migrate --datastore-path ./nx-data
• Configurable batch limits: --max-records, --max-bytes (default 4MiB, resolved from a single source of truth)
• Missing-datastore case handled as a proper MigrationError::MissingDatastore { path } instead of an ad-hoc CLI bail
• Documented in the CLI reference alongside nx run and nx config

sync_manager Refactor

• Monolithic sync_manager.rs split into sync_manager/ submodules
• OpApplier trait per CRDT family
• E2E tests split per CRDT family under tests/e2e/
• The sync_manager split itself was intended to be behavior-preserving; the later roadmap items in this release (versioning, migration, typed wire errors) did change public API, wire protocol and CLI surface

Crate Versions Pinned

• Every internal crate is now referenced by explicit version = "0.1.1" alongside its path, across the workspace and all examples
• cargo package --workspace --no-verify --offline now passes
• Makes packaging, downstream consumption and any future crates.io release straightforward

Docs

• New design pages: Wire Versioning and Schema Versioning
• New WireError semantics table (retry policy + meaning per variant) in nx-net reference
• Gossip Protocol compatibility table updated for protocol 4 and the new Error frame
• CLI reference updated with nx migrate
• Roadmap updated: the entire v0.1.1 block (Split, Wire Versioning, Schema Versioning, Typed Error Frames) is now closed
• A few crate reference pages still mention the old monolithic sync_manager.rs; they will be cleaned up in a follow-up docs pass

---

What this changes

v0.1.0 was the first stable line for non-critical workloads.

v0.1.1 answers a different question: what happens the day you actually need
to upgrade a running cluster ?

• The wire contract is now explicit: peers on different protocol versions refuse each other with a structured error, not a crash and not silent drift.
• The persistence layer is now explicit: every sled table carries a magic number and a version, and a documented step registry can move it forward one version at a time.
• The reconnect loop is now honest: a fatal wire error stops trying, a rate-limit is honored, a transient error keeps backing off exponentially. No more "everything looks the same when things are actually broken".
• The migration path is now runnable offline: nx migrate can be pointed at a stopped datastore and produce a valid, upgraded one, in bounded batches, without ever starting a node.

The closing criterion for v0.1.1 on the roadmap was:

sync_manager.rs no longer exists as a single file.
A cluster with a 0.1.1 node and a 0.1.0 node refuses the connection with
a clear, versioned error, not with a crash.

Both hold as of this release.

---

Upgrade notes

From v0.1.1-rc.1
Drop-in. Same wire protocol (4), same on-disk schema, same CLI surface.
Only visible source break: WireRetryPolicy is now #[non_exhaustive]; if you
were matching on it exhaustively, add a _ arm.

From v0.1.0
Wire protocol goes 2 -> 4. v0.1.0 and v0.1.1 nodes will not talk to each
other. Upgrade the whole cluster.

On-disk schema is versioned starting from this line. Before starting a
v0.1.1 node on a v0.1.0 datastore:

1. Stop any process using the datastore.
2. Back up the datastore directory.
3. Run:

nx migrate --datastore-path ./your-nx-data

4. Start the v0.1.1 node against the migrated datastore.

The migration is bounded (--max-records, --max-bytes) and resumable.

---

What is next

v0.1.2 - Performance & Profiling.

The roadmap for v0.1.2 is already published: automatic profiling, per-module
CPU/memory metrics, and a regression gate in CI so any PR that worsens sync
p99 latency, throughput or RSS above the configured budget gets blocked
automatically.

---

Thank you !! :)

---

This discussion was created from the release v0.1.1.