mirror of https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git synced 2026-11-13 18:40:50 +08:00

Files

T

Daniel Norman d8f363ca99 Replace API version checks with feature detection

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

2026-10-29 18:32:03 +01:00

4.6 KiB

Raw Blame History

httpd API changes

Breaking changes to the httpd API that are between expand and contract. ADR 0001 has the rules.

When a change expands, add a section under its release, newest first, and add its removals to the table.
When a release bumps the major, set the target date in ## Support. Its ## API changes notes come from its sections and from the server removals.
When code is removed, delete its row. When a change has no rows left, delete its section.

Support

Explorer supports httpd 0.28.0 and newer, set by minimumSupportedVersion in http-client/lib/compat.ts. No target dates are set yet.

Removals

When	Side	Change	Remove
Explorer drops httpd 0.26	Client	Stats endpoints	`getCommitCountBySha` and `getDiffStats` in `http-client/lib/repo.ts`
Explorer drops httpd 0.30	Client	API at `/api`	`/api/v1` in `http-client/lib/fetcher.ts`, `apiBase` in `workers/open-graph/index.js`, and in the tests under `tests/visual/desktop/` and `tests/e2e/`
Explorer drops httpd 0.30	Client	Repo facts	`legacyMetaSchema`, `crefsPayloadSchema` and `legacyRepoFields` in `http-client/lib/compat.ts`; `normalizeRepo` in `workers/open-graph/index.js`
Explorer drops httpd 0.30	Client	Release scope	`legacyReleasesQuery`, `legacyScopeReleases` and `legacyHasOtherReleases` in `http-client/lib/compat.ts`
Explorer drops httpd 0.30	Client	Release support	`releasesSupported` in `http-client/lib/compat.ts`
Major after client switch	Server	API at `/api`	The `/v1` nest in `crates/radicle-httpd/src/api.rs`
A major release	Server	Repo facts	Legacy `meta` and `head` in `crates/radicle-httpd/src/api.rs`
A major release	Server	Release scope	`allAuthors` in `crates/radicle-httpd/src/api/query.rs`

Next release

API at `/api`

Added: httpd serves the API at /api, and still at /api/v1.
Changed in place: the API root reports path as /api. The old index at /api, which only linked to /v1, is gone. No client reads either.
Read by: client, Open Graph worker. Both call /api/v1 until explorer drops httpd 0.30, because older httpd serves only that path. So httpd keeps /v1 until the first major release after they switch.

Repo facts

Added: cobs, with the release buckets, and a qualified defaultBranch, outside the project payload. The legacy meta (counts and head) stays inside it.
Changed in place: meta.releases counts delegate plus other, not every release object. When httpd cannot count, it leaves the field out instead of sending 0. Older clients parse both, because the field was always optional.
Changed in place: only repos/:rid sends the release buckets and meta.releases. Repo lists leave both out, because counting reads every release of each repo.
Read by: client, Open Graph worker.

Release scope

Added: the releases query takes scope (trusted or untrusted). allAuthors stays.
Read by: client.

Release support

Added: /info reports httpd.releases, whether httpd was built with release support. Without it, a repo with no release count could be a node without releases or a count that failed.
Read by: client. On older httpd, it reads a release count as support.

Version

Removed: apiVersion in the API root. The client no longer checks it, and released clients do not read it.
Added: the client reads version in the API root, and warns on nodes older than minimumSupportedVersion.
This is a removal, so the release bumps the major.

0.27.0

Stats endpoints

Added: stats/commits/:sha and diff/:base/:oid/stats. The client falls back to the tree stats and the full diff.
Read by: client.

4.6 KiB Raw Blame History