mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-15 03:20:33 +08:00
Daniel Norman
d8f363ca99
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
83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# httpd API changes
|
|
|
|
Breaking changes to the httpd API that are between expand and contract.
|
|
[ADR 0001](adr/0001-expand-and-contract-api-changes.md) 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.
|