mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-13 18:40:50 +08:00
Daniel Norman
0dc1e557a5
Repos need not carry a `xyz.radicle.project` payload; the default branch can come from `xyz.radicle.crefs` alone. Such repos got no counts and no default branch, and failed schema validation in explorer, which broke the parse of a whole listing. httpd: - Add top-level `cobs` with issue, patch and bucketed release counts - Add top-level `defaultBranch`, qualified like the crefs payload - Omit a count the node cannot determine instead of reporting zero - Drop `head`: the tip is `refs[defaultBranch]` - Keep counts in the project payload for older clients until a major release - Keep the project payload when a COB read fails - Keep `meta.releases` a single count: delegate + other - Log and skip canonical ref rules and refs that fail to read, so one bad ref doesn't drop the default branch tip explorer: - Model `cobs` and `defaultBranch`, adapting older nodes to one shape - Resolve the default branch from the crefs HEAD on older nodes - Collect the shims for older httpd in http-client/lib/compat.ts, each naming the httpd release that the client can drop it with - Add `defaultBranchTip`, replacing `head`, with a fallback to the legacy `meta.head` - Make the project payload and its legacy meta optional - Fall back to the RID for the repo name, and show a placeholder for a missing name in repo cards and the header - Hide a counter instead of reading a missing count as zero - Fall back to a full-page check for "More" without counts - Add a `repo.sourceUnavailable` route for repos without a default branch or tip - Browse explicit revisions and offer the branch selector without a default branch - List these repos in repo grids and on the landing page - Say the node is older or built without releases - Scope release pages in the client, so views never call the shims - Read OG worker repos through the same compat shims - Share the repo name and default branch helpers with the OG worker CI: - Add check:open-graph, a wrangler deploy dry run - Run it in GitHub CI, Buildkite and check:ci - Install explorer's dependencies first: the worker resolves compat.ts imports, such as zod, from there Tests: - Test that a build without releases omits the count - Test that one failing rule keeps the others - Test the repo shape across httpd versions and the release shims - Test `hasMorePages` and `repoName` - Test repos without a project payload end to end
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# httpd API changes
|
|
|
|
Every breaking change to the httpd API ships in two steps, see
|
|
[ADR 0001](adr/0001-expand-and-contract-api-changes.md). Expand adds the new
|
|
shape next to the old one. Contract removes the old one later, on each side
|
|
separately. This file tracks each change from its expand release until both
|
|
sides have contracted.
|
|
|
|
One section per change, under the httpd release that expanded it, newest first.
|
|
Each section says what the expand added and who reads it, then lists the
|
|
contract: the code each side removes, and when it may go. Delete a contract line
|
|
when its code is gone. Delete the section when its contract list is empty. A
|
|
release fills its `## API changes` notes from the sections under its heading,
|
|
and a major release from every server line.
|
|
|
|
- **Client contract**: the explorer client (`http-client/`) and the Open Graph
|
|
worker (`workers/open-graph/`) may stop reading the old shape when explorer
|
|
drops the last httpd release without the new shape.
|
|
- **Server contract**: httpd may stop sending the old shape in a major release
|
|
after the expand.
|
|
|
|
## Expanded in the next release (unreleased)
|
|
|
|
### API at `/api`
|
|
|
|
Expand: httpd serves the API at `/api`, and still serves it at `/api/v1`. Read
|
|
by the explorer client and the Open Graph worker.
|
|
|
|
Contract:
|
|
|
|
- Client, when explorer drops httpd 0.30: switch to `/api` in
|
|
`http-client/lib/fetcher.ts`
|
|
- Client, when explorer drops httpd 0.30: `apiBase` in
|
|
`workers/open-graph/index.js`
|
|
- Client, when explorer drops httpd 0.30: the tests that match `/api/v1` in
|
|
`tests/visual/desktop/` and `tests/e2e/`
|
|
- Server, a major release after the client lines above: the `/v1` nest in
|
|
`crates/radicle-httpd/src/api.rs`
|
|
|
|
### Repo facts outside the project payload
|
|
|
|
Expand: `cobs`, `releaseCount` and a qualified `defaultBranch` move out of the
|
|
project payload. The legacy `meta` (counts and `head`) stays inside it. Only
|
|
`repos/:rid` sends the release counts: counting reads every release, so repo
|
|
lists leave them out. Read by the explorer client and the Open Graph worker.
|
|
|
|
Contract:
|
|
|
|
- Client, when explorer drops httpd 0.30: `legacyMetaSchema`,
|
|
`crefsPayloadSchema` and `legacyRepoFields` in `http-client/lib/compat.ts`
|
|
- Client, when explorer drops httpd 0.30: `normalizeRepo` in
|
|
`workers/open-graph/index.js`
|
|
- Server, a major release: legacy `meta` and `head` in
|
|
`crates/radicle-httpd/src/api.rs`
|
|
|
|
### Release scope
|
|
|
|
Expand: the releases query takes `scope` (`trusted` or `untrusted`), and the
|
|
repo reports release buckets. `allAuthors` stays. Read by the explorer client.
|
|
|
|
Contract:
|
|
|
|
- Client, when explorer drops httpd 0.30: `legacyReleasesQuery`,
|
|
`legacyScopeReleases` and `legacyHasOtherReleases` in
|
|
`http-client/lib/compat.ts`
|
|
- Server, a major release: `allAuthors` in
|
|
`crates/radicle-httpd/src/api/query.rs`
|
|
|
|
### Removed `apiVersion`
|
|
|
|
httpd no longer reports `apiVersion` in the API root, and explorer no longer
|
|
checks it. Explorer warns on nodes older than `minimumSupportedVersion` in
|
|
`http-client/lib/compat.ts`, from the `version` in the API root. Released
|
|
explorers do not read `apiVersion`. This is a removal, so the next release is a
|
|
major release.
|