Compatibility
What stays stable once nanocached reaches 1.0.0, and what does not. The project is still on 0.x, so this page describes the rules that take effect at 1.0.0; until then only the pre-1.0 rule applies.
Versioning
The server (nanocached-node, nanocached-proxy,
nanocached-discovery), the six SDKs and the framework adapters
are released together and carry the same version number, whether or not a
given component changed. Versions follow
semantic versioning: a breaking change
to anything on this page raises the major version, new
backward-compatible features raise the minor version, fixes raise the
patch version.
Client wire protocol: frozen
From 1.0.0 the client-facing wire protocol is frozen. Covered:
- every command a caching client sends —
A,G/S/D,g/s/d,c/F,i,t,k/x,m/o,y— together with the two membership queries SDKs send,LandQ; - every response and status those commands can produce, and the response tags capability.
Frozen means no 1.x release changes the syntax or the meaning of
anything above, and none removes it. A 1.x release may add a new
command, a new optional trailing token or a new status; an older node that
does not know the addition answers En\n and closes the
connection (a node before 0.4.8 closes it without a reply; see
namespaces), so a
client must not use a newer feature before every node has been
upgraded. Any other change to this protocol waits for a new major
version.
Not frozen: cluster-internal frames
The frames that only nodes, discovery servers and proxies exchange with each other — join, heartbeat, announce, migrate, cancel, complete, proxy announce, handoff and leave, node roster (see cluster-internal commands) — are versioned with the server and may change in any release, including a patch release. Run one server version across a cluster; a mixed-version cluster is only a transient rolling-upgrade state, in the order given under Upgrading a cluster (discovery first, then the nodes, then the proxies); a release’s changelog notes any exception to it.
SDK public API: all six SDKs
From 1.0.0 the public API of each of the Rust, Go, TypeScript, Python, Java and .NET SDKs is covered: the exported types, functions, methods, options and their documented behavior, and the error types and the conditions that raise them. A breaking change to any of them is released only as a new major version. Behavior that an SDK's documentation describes as a limit or as unspecified is not covered.
The framework adapters (Spring, Spring Boot starter, JCache, Django,
cache-manager, Keyv, and Nanocached.Caching for .NET) ship at the same version and follow the
same rule for their public API and configuration keys.
Within an SDK or adapter, these are not covered, whatever a README says about them, and may change in any release:
- tuning values and internal limits: the defaults of timeouts, cooldowns, thresholds and size limits, the number of background writes or hedged reads in flight, keys per frame, the size cap on a batch reply, retry counts and delays, the read-repair TTL and the keep-alive interval. The options that set them — name, unit, accepted range and meaning — are covered; their defaults are not, so set the ones you depend on explicitly. The changelog notes a changed default;
- text an SDK or adapter writes to standard error, the console or a log;
- anything an SDK hides from its own public documentation or names with
a leading underscore: Rust’s
#[doc(hidden)]items and the__test_hooksCargo feature, Python’s underscore-prefixed modules and names, and the like; - how an adapter behaves where it depends on a third-party framework (Spring, Django, cache-manager, Keyv, .NET dependency injection). The READMEs describe what was observed with the framework versions they name; a framework release can change it;
- the format in which an adapter stores a value (for example Django’s pickle, the .NET envelope, JSON). A release that changes one says so in the changelog; plan a rolling deploy accordingly.
No deprecation period
nanocached does not deprecate before it removes. There is no release that keeps an old form working alongside its replacement with a warning. A breaking change lands in a major release, takes effect there, and is recorded in the changelog of every affected component. Pin the major version you depend on; upgrading to the next major is the point at which you read the changelog.
Server binaries and images
Besides the wire protocol and the SDKs, three more things that deployments are written against are covered from 1.0.0: the command line of the server binaries, the operations endpoints and metrics, and the container images. The same rule applies to each: a breaking change waits for a new major version, and adding something is a minor change.
Command-line flags and environment variables
From 1.0.0 the command line of nanocached-node,
nanocached-proxy and nanocached-discovery is
covered, because deployment guides, container manifests and task
definitions are written against it:
- the name of every flag each binary lists in
--help, the syntax of its value and what it means; - the environment variable
NANOCACHED_AUTH_SECRET; - the defaults of
--hostand--port(127.0.0.1and 8356, 8357 and 8358 for node, discovery and proxy), since clients and health checks connect there; - the component names and
startofncd <component> start, which passes the rest of its arguments to that component unchanged.
Renaming or removing a flag, changing the syntax it accepts or what it means, and making an accepted value invalid are breaking changes and wait for a new major version; there is no deprecation period (see above). A minor release may add a flag or an environment variable.
Not covered, and free to change in any release:
- the defaults of limits, budgets and timeouts
(
--max-memory,--max-in-flight-bytes,--max-connections,--max-connections-per-ip,--drain-timeout,--liveness-timeout,--replication-factor). Set the ones your deployment depends on explicitly; the changelog notes a changed default; - the wording of
--help, log lines and error messages; NANOCACHED_SECRET, the proxy's old name forNANOCACHED_AUTH_SECRET. It is no longer read: a proxy that has only the old name set refuses to start and says so, rather than run without authentication. UseNANOCACHED_AUTH_SECRETon all three binaries;NANOCACHED_TRACE_PREFIX, which only a build with thetracefeature reads. The released images are built without it.
Operations endpoints and metrics
From 1.0.0 the operations endpoint that --metrics-port
turns on is covered, because probes, scrapers, dashboards and autoscaling
rules are built on it:
GET /healthz,GET /readyzandGET /metricson the node, the proxy and the discovery server, and the status codes of the two probes:200when the instance is healthy or ready,503when a ready check fails. What makes/readyzfail is the one given in What every deployment needs: a clustered node before it has adopted membership, a proxy before it has a node roster or once it is draining, a discovery server during its startup grace period;- the Prometheus text format (version 0.0.4) of
/metrics; - every metric the three binaries export: its name, its type
(counter or gauge), its label keys and what it counts. That includes the
namespacelabel of the per-namespace metrics and a counter’s reset to zero when the process restarts.
Removing or renaming a metric, changing its type, changing what it counts, and adding a label key to an existing metric (which splits a series that alert rules may select) are breaking changes and wait for a new major version. A minor release may add a metric. The set of label values (the namespaces present) follows the data and is not a compatibility matter.
Not covered: the text of the response bodies, the HELP lines
and the order of the lines in /metrics, and the unauthenticated
nature of the endpoint (keep it on an internal interface, as the guide
says).
Container images
The three images are
ghcr.io/nanocached/nanocached-node,
nanocached-proxy and nanocached-discovery. From
1.0.0 these are covered:
:X.Y.Znames that release and is never moved to a different one. This is the tag to pin. Re-running a failed release rebuilds the same version from the same source, so its digest can change then; pin by digest if you need the exact bytes;:latestis the newest stable release, moved for all three images together, and never a pre-release. It does not stay inside a major version: the release that moves it past 1.x is the first 2.0.0. Do not run:latestwhere a major upgrade must be a decision;- the platforms
linux/amd64andlinux/arm64; dropping one is a breaking change, adding one is not; - how an image starts: the entrypoint is that image’s own server
binary, so what follows the image name on a command line (or in
argsandcommandfields) is the flags covered above; the process runs as uid and gid 10001; the default arguments are--host 0.0.0.0; the ports are 8356 (node), 8357 (discovery) and 8358 (proxy).
A new major version may change any of those, and says so in the changelog. Not covered, and free to change in any release: the base image (its distribution, libc and version) and anything the guides do not rely on in it, such as a shell or other tools; where the binary and other files sit in the image; the working directory; the image’s labels and size.
Two more kinds of tag exist and carry no promise at all:
:main and :sha-<commit> are builds of
unreleased commits, for trying a change. Floating tags such as
:X or :X.Y do not exist; a minor release may add
them, but nothing here depends on that.
Not covered
tests/ and tools/
Nothing under the repository’s tests/ and
tools/ directories is covered, at any version: the E2E,
chaos and oracle scripts, the conformance harness, the
benchmarks and the copy of the capacity planner kept there. Their
arguments, environment variables, output formats and file layout may
change in any release, including a patch release. The scale-in scenarios
that Verifying a
deployment points to are examples of how the drain behaves, not an
interface to script against.
Before 1.0.0
On the 0.x line none of the above is promised. A breaking change may ship in any release, minor or patch, without a deprecation cycle; the Rust SDK's changelog lists the ones so far. Pin an exact version.