Runtime identity, daemon staleness and compatibility diagnostics.
Canonical protocol numbers, headers, handshake parsing and the pure compatibility
verdict live in com.blockether.vis.contract.gateway. This namespace contributes
the release/build identity of the running process and the concrete client/server
adapters that combine it with that contract.
Runtime identity, daemon staleness and compatibility diagnostics. Canonical protocol numbers, headers, handshake parsing and the pure compatibility verdict live in `com.blockether.vis.contract.gateway`. This namespace contributes the release/build identity of the running process and the concrete client/server adapters that combine it with that contract.
(build-id)WHICH CODE this process is running, as an opaque identity - never an order, and
nil when this build cannot say. It answers the question a release version cannot:
two dev runs, or two builds of the same VIS_VERSION, are the same build only
when they came from the same commit.
One value across both distributions, because a daemon is replaced by whichever
client finds it and the two halves need not be the same shape:
native/uberjar the commit stamped into vis/BUILD at build time
source (JVM) the short HEAD sha of the checkout it loaded from
Computed ONCE per process ON PURPOSE: a daemon must keep advertising the build it LOADED, not whatever is on disk minutes later, or nothing would ever look stale.
WHICH CODE this process is running, as an opaque identity - never an order, and nil when this build cannot say. It answers the question a release version cannot: two `dev` runs, or two builds of the same VIS_VERSION, are the same build only when they came from the same commit. One value across both distributions, because a daemon is replaced by whichever client finds it and the two halves need not be the same shape: native/uberjar the commit stamped into `vis/BUILD` at build time source (JVM) the short `HEAD` sha of the checkout it loaded from Computed ONCE per process ON PURPOSE: a daemon must keep advertising the build it LOADED, not whatever is on disk minutes later, or nothing would ever look stale.
(client-headers client-name)Headers every Vis client stamps on a gateway request.
Headers every Vis client stamps on a gateway request.
(client-verdict client-name gateway-handshake)A client's judgement of the gateway it just probed, given that gateway's
ENGINE handshake map (the [[contract/wire->handshake]] of its advertised protocol
block; nil/all-nil = a gateway too old to advertise one). client-name names
this client in the rendered copy.
A client's judgement of the gateway it just probed, given that gateway's ENGINE handshake map (the [[contract/wire->handshake]] of its advertised `protocol` block; nil/all-nil = a gateway too old to advertise one). `client-name` names this client in the rendered copy.
(explain {:keys [reason gateway-protocol gateway-min-client client-protocol
client-min-gateway client-name]})Human copy for a verdict: a title, one plain-language summary, and ORDERED remedy steps. One writer for every surface (terminal panel, gateway 426 body, companion screen) so the wording never drifts between them.
Human copy for a verdict: a title, one plain-language summary, and ORDERED remedy steps. One writer for every surface (terminal panel, gateway 426 body, companion screen) so the wording never drifts between them.
(gateway-verdict request)The gateway's own judgement of one inbound request: [[contract/verdict]] with this build filled in as the gateway half.
The gateway's own judgement of one inbound request: [[contract/verdict]] with this build filled in as the gateway half.
(handshake)What THIS build advertises on health, status and capabilities responses.
What THIS build advertises on health, status and capabilities responses.
(incompatible-ex verdict-map)The ex-info a client throws when it refuses to drive an incompatible
gateway. Carries :vis/user-error (so the top-level CLI prints it clean and
exits 2) plus :vis/panel, the pre-rendered panel-lines screen.
The ex-info a client throws when it refuses to drive an incompatible gateway. Carries `:vis/user-error` (so the top-level CLI prints it clean and exits 2) plus `:vis/panel`, the pre-rendered [[panel-lines]] screen.
(newer-release? a b)True when release a is STRICTLY newer than release b, compared segment by
segment as numbers (0.1.10 > 0.1.9) with the shorter one zero-padded, so
0.2 and 0.2.0 are the same release rather than being ranked by length.
A version without order - dev, a checkout, nil, anything [[version-parts]]
cannot read - is neither newer nor older. That is deliberate: it makes the
comparison one-directional and total, so a source build never decides that a
released daemon is stale and two builds can never bounce each other in turn.
True when release `a` is STRICTLY newer than release `b`, compared segment by segment as numbers (`0.1.10` > `0.1.9`) with the shorter one zero-padded, so `0.2` and `0.2.0` are the same release rather than being ranked by length. A version without order - `dev`, a checkout, nil, anything [[version-parts]] cannot read - is neither newer nor older. That is deliberate: it makes the comparison one-directional and total, so a source build never decides that a released daemon is stale and two builds can never bounce each other in turn.
(panel-lines {:keys [gateway-protocol gateway-min-client gateway-version
client-protocol client-min-gateway client-version
client-name upgrade]
:as v})The terminal SCREEN for an incompatible peer: a boxed, colour-free panel of plain lines. Returned as data (never printed here) so the CLI, the TUI, and tests all render the exact same block.
The terminal SCREEN for an incompatible peer: a boxed, colour-free panel of plain lines. Returned as data (never printed here) so the CLI, the TUI, and tests all render the exact same block.
(release-sha)Full commit of the loaded Vis build, with its build-time dirty suffix, or nil. This is provenance, not a version or a claim that a development build was released.
Full commit of the loaded Vis build, with its build-time dirty suffix, or nil. This is provenance, not a version or a claim that a development build was released.
(release-version)Human release version of this build: the vis/VERSION resource written at
build time from the repo-root VIS_VERSION, verbatim (0.1.28), else
dev. Ordered ONLY for staleness (newer-release?) - never for
compatibility, which is [[contract/protocol-version]]'s job alone.
Human release version of this build: the `vis/VERSION` resource written at build time from the repo-root VIS_VERSION, verbatim (`0.1.28`), else `dev`. Ordered ONLY for staleness ([[newer-release?]]) - never for compatibility, which is [[contract/protocol-version]]'s job alone.
(request->client request)Read the client's advertised protocol from a Ring request's normalized headers.
Read the client's advertised protocol from a Ring request's normalized headers.
(superseded? {:keys [our-version their-version our-build their-build]})True when a peer running their-version / their-build is running code THIS
build replaces. The two inputs answer different questions and are consulted in
that order:
version an ORDER (newer-release?). A strictly newer peer is never
replaced, so an old client can never downgrade a fresh daemon.
build an IDENTITY, and only where the versions carry no order between them
(dev against dev, or the same VIS_VERSION built twice). Different
commit means different code; an unknown build on either side means
no verdict at all.
Identity is symmetric where an order is not, so acting on it MUST be bounded by
the caller - client/bounce-stale-daemon! replaces a daemon at most once per
process, which turns the worst case into one restart instead of two builds
trading a daemon back and forth.
True when a peer running `their-version` / `their-build` is running code THIS
build replaces. The two inputs answer different questions and are consulted in
that order:
version an ORDER ([[newer-release?]]). A strictly newer peer is never
replaced, so an old client can never downgrade a fresh daemon.
build an IDENTITY, and only where the versions carry no order between them
(`dev` against `dev`, or the same VIS_VERSION built twice). Different
commit means different code; an unknown build on either side means
no verdict at all.
Identity is symmetric where an order is not, so acting on it MUST be bounded by
the caller - `client/bounce-stale-daemon!` replaces a daemon at most once per
process, which turns the worst case into one restart instead of two builds
trading a daemon back and forth.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |