httpd: - Serve the API at /api, not only under /v1 - Keep serving it at /api/v1, without a redirect, until the first major release after explorer and the Open Graph worker switch to /api - Remove apiVersion: released explorers do not read it - Add `httpd.releases` to `/info`, set by the artifacts feature explorer: - Remove the API version check, its config and the unused compare-versions dependency - Keep the node version in a plain parse error message - Add `minimumSupportedVersion`, set to 0.28.0, and warn on nodes whose major is older, treating 0.y as the major before 1.0 - Do not warn on builds without a release number - Show a warning on the node page of an outdated node - Mark an outdated node in the seed picker on every page - Name the node version and the floor in parse errors - Drop the `/node` fallback for httpd without `/info`, which predates the floor - Check the status, not `ResponseError`, so the Open Graph worker can import compat without the fetcher - Name the httpd release each shim serves, not a date - Drop the mime shim for httpd 0.18.1 and the unused `lib/file.ts` - Read the node from `/info` in repo views - Pass the node and its features to repo views as one `node` param - Show the releases tab and pages when the node supports releases, and the counter only when there is a count - Read a release count as release support on older httpd - Test the flag and the fallback docs: - Restructure docs/api-changes.md: the supported versions, one table of removals, fixed fields per change, and a link to ADR 0001 for the rules - Say in ADR 0001 that each compat comment names what the other side does - Say in ADR 0001 when a capability needs a flag in /info tests: - Run e2e tests on httpd 0.30.0, above the floor, instead of 0.26.0 - Run the release tests on it too, so they cover the compat shims - Skip only those that need release counts per scope on it - Test a node without release support through a mocked `/info` flag, instead of an httpd that predates the floor
4.5 KiB
1. Expand and contract httpd API changes
Date: 2026-10-20
Status
Accepted
Context
Explorer is deployed continuously, and the public instance at radicle.network always runs the latest version. The seeds it reads (httpd instances) upgrade on their own schedule, so explorer often reads an older httpd. A change to a response can break explorer on those seeds, and the operator of a seed cannot tell why their node no longer loads.
Decision
One version. httpd uses semantic versions. The version covers the HTTP API,
the CLI and the config. A minor release adds, and a major release removes or
changes. Before 1.0, 0.y counts as the major, as in Cargo: a release that only
adds bumps 0.y.z to 0.y.(z+1), and a release that removes or changes bumps
it to 0.(y+1).0.
Supported releases. Explorer supports every httpd release from
minimumSupportedVersion in http-client/lib/compat.ts up to the latest. This
can span more than two majors, because before 1.0 each 0.y is a major.
Explorer warns about a node older than that. It does not warn about a version
that it cannot parse, such as pre-release or nix-<commit>. httpd does not
warn its operator at startup: it cannot know the floor of the explorer that
reads it.
The 3-month guideline. Explorer aims to support a major for at least three
months after the next major replaces it. The release that bumps the major writes
this target date in docs/api-changes.md, the only place that holds dates. When
the date comes, check which versions the seeds run, then raise
minimumSupportedVersion or move the date. You may raise it sooner, when few
seeds still run that major or when a fix needs it.
Expand, then contract. A breaking change ships in two steps:
- Expand, in a minor release: httpd adds the new fields next to the old ones, and keeps the old ones exactly as they were. The client reads the new fields and falls back to the old ones.
- Contract, in a later major release: httpd removes the old fields. It may not
remove a field or path that the explorer client or the Open Graph worker
(
workers/open-graph) still reads.
A security fix is the one exception: it may narrow an existing field in place, for example to stop it from sending data that an attacker can write. It must keep the field's type, so that older clients still parse it. Its release notes say which field changed and why.
One place for compatibility code. The client turns the responses of every
supported httpd release into one shape. Version-specific code lives in
http-client/lib/compat.ts. A fallback to an older endpoint stays in the client
method that calls that endpoint.
Name the side and the version in every removal. httpd and the client remove their compatibility code at different times, so each compat comment says what the other side does, which side it is on, and when it can go:
// Compat: older clients ... Server: remove in a major release.
// Compat: older httpd ... Client: remove when explorer drops httpd 0.30.
Track every change in one place. docs/api-changes.md lists each change
with its expand release, the consumers that read it, and its pending removals. A
release fills its ## API changes notes from this list.
Feature detection, not version checks. The client learns what a seed supports from the seed itself. It never branches on the httpd version, and uses that version only to warn about an unsupported node. The signal depends on the feature:
- A feature that every build has: a field that is present, or an endpoint that answers.
- A feature that a build or the config can turn off, such as search or releases:
a flag in
/info. A missing field is not this signal, because a field is also missing when httpd fails to compute it. The client must not hide a feature because of such a failure.
No version but httpd's. httpd does not report apiVersion, and serves the
API at /api, with no version in the path. When a path moves, the client cannot
tell from a response which path a seed has. So it keeps the old path until
explorer drops the last httpd release without the new one, and httpd serves the
old path until the first major release after that.
Forward compatibility
Explorer does not support httpd releases that are newer than itself, and it does not need to. Explorer and httpd live in one repository, and a patch that changes the API also updates the client. radicle.network deploys explorer continuously, so it is not older than a released httpd. A self-hosted explorer should track the latest version for the same reason.