Files
radicle-explorer/explorer/http-client/lib/repo.ts
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

722 lines
16 KiB
TypeScript

import type { Fetcher, RequestOptions } from "./fetcher.js";
import { ResponseError } from "./fetcher.js";
import {
crefsPayloadSchema,
legacyHasOtherReleases,
legacyMetaSchema,
legacyReleasesQuery,
legacyRepoFields,
legacyScopeReleases,
} from "./compat.js";
import type { Commit, Commits } from "./repo/commit.js";
import type { Issue } from "./repo/issue.js";
import type { Patch } from "./repo/patch.js";
import type { Release } from "./repo/release.js";
import type { Author } from "./shared.js";
import type { ZodSchema } from "zod";
import {
array,
boolean,
literal,
number,
object,
optional,
record,
string,
union,
z,
} from "zod";
import {
commitHeaderSchema,
commitSchema,
commitsSchema,
diffBlobSchema,
diffSchema,
} from "./repo/commit.js";
import { issueSchema, issuesSchema } from "./repo/issue.js";
import { patchSchema, patchesSchema } from "./repo/patch.js";
import { releaseSchema, releasesSchema } from "./repo/release.js";
import { authorSchema } from "./shared.js";
export type PeerRefs = {
id: string;
alias?: string;
delegate: boolean;
refs: Record<string, string>;
};
const tagInfoSchema = object({
commit: string(),
tagger: object({
name: string(),
email: string(),
timestamp: number(),
}).optional(),
message: string().optional(),
});
export type TagInfo = z.infer<typeof tagInfoSchema>;
// Releases bucketed by whether a delegate created them and whether a trusted
// party redacted every artifact they carry. A release with no artifacts is not
// redacted.
const releaseCountsSchema = object({
delegate: number(),
delegateRedacted: number(),
other: number(),
otherRedacted: number(),
});
export type ReleaseCounts = z.infer<typeof releaseCountsSchema>;
// The two disjoint author scopes of the releases list: releases created by a
// delegate, or by anyone else.
export type ReleaseScope = "trusted" | "untrusted";
// Repository-level COB counts. Each is absent when the node cannot determine
// it — an unreadable COB cache, or a build without release support — so a
// missing count never reads as zero.
const cobCountsSchema = object({
patches: optional(
object({
open: number(),
draft: number(),
archived: number(),
merged: number(),
}),
),
issues: optional(
object({
open: number(),
closed: number(),
}),
),
releases: optional(releaseCountsSchema),
});
export type CobCounts = z.infer<typeof cobCountsSchema>;
export const repoSchema = object({
rid: string(),
payloads: object({
// Optional: a repo may declare its default branch in `xyz.radicle.crefs`
// instead, and carry no project payload at all.
"xyz.radicle.project": object({
data: object({
name: string(),
description: string(),
// Unqualified, unlike the top-level `defaultBranch`.
defaultBranch: string(),
}),
meta: legacyMetaSchema.optional(),
}).optional(),
"xyz.radicle.crefs": crefsPayloadSchema,
}),
cobs: optional(cobCountsSchema),
defaultBranch: optional(string()),
delegates: array(authorSchema),
threshold: number(),
visibility: union([
object({ type: literal("public") }),
object({ type: literal("private"), allow: optional(array(string())) }),
]),
seeding: number(),
refs: object({
tags: record(string(), tagInfoSchema),
refs: record(string(), string()),
}).optional(),
alias: string().optional(),
}).transform(repo => {
// Older httpd doesn't send `cobs`, so only a node without it needs the
// legacy fields. A newer node that leaves out `defaultBranch` has none.
if (repo.cobs === undefined) {
return {
...repo,
...legacyRepoFields(
repo.payloads["xyz.radicle.project"],
repo.payloads["xyz.radicle.crefs"],
repo.refs,
),
};
}
return {
...repo,
cobs: repo.cobs,
// The unredacted delegate releases, which the releases tab opens on.
// Absent when the node cannot count them, see `releasesSupported`.
releaseCount: repo.cobs.releases?.delegate,
};
});
const reposSchema = array(repoSchema);
export type Repo = z.infer<typeof repoSchema>;
const searchResultSchema = object({
rid: string(),
payloads: object({
"xyz.radicle.project": object({
name: string(),
description: string(),
defaultBranch: string(),
}).optional(),
}),
delegates: array(authorSchema),
seeds: number(),
});
const searchResultsSchema = array(searchResultSchema);
export type SearchResult = z.infer<typeof searchResultSchema>;
const activitySchema = object({
activity: array(number()),
});
export type Activity = z.infer<typeof activitySchema>;
const blobSchema = object({
binary: boolean(),
content: optional(string()),
name: string(),
path: string(),
lastCommit: commitHeaderSchema,
});
export type Blob = z.infer<typeof blobSchema>;
const treeEntrySchema = object({
path: string(),
name: string(),
oid: string(),
kind: union([literal("blob"), literal("tree"), literal("submodule")]),
});
export type TreeEntry = z.infer<typeof treeEntrySchema>;
const treeStatsSchema = object({
commits: number(),
branches: number(),
contributors: number(),
});
export type TreeStats = z.infer<typeof treeStatsSchema>;
const commitCountSchema = object({ commits: number() });
export type Tree = z.infer<typeof treeSchema>;
const treeSchema = object({
entries: array(treeEntrySchema),
lastCommit: commitHeaderSchema,
name: string(),
path: string(),
});
const remoteSchema = object({
id: string(),
alias: string().optional(),
delegate: boolean(),
heads: record(string(), string()),
refs: record(string(), string()).optional(),
});
export type Remote = z.infer<typeof remoteSchema>;
const remotesSchema = array(remoteSchema);
export type DiffResponse = z.infer<typeof diffResponseSchema>;
const diffResponseSchema = object({
commits: array(commitHeaderSchema),
diff: diffSchema,
files: record(string(), diffBlobSchema),
});
const diffStatsSchema = object({
filesChanged: number(),
insertions: number(),
deletions: number(),
});
export type DiffStats = z.infer<typeof diffStatsSchema>;
const statusSchema = union([
literal("started"),
literal("failed"),
literal("succeeded"),
]);
const runSchema = object({
runId: string(),
node: authorSchema,
status: statusSchema,
log: string(),
});
const jobSchema = object({
jobId: string(),
commit: string(),
runs: array(runSchema),
});
export type Job = z.infer<typeof jobSchema>;
const jobsSchema = array(jobSchema) satisfies ZodSchema<Job[]>;
export type RepoListQuery = {
page?: number;
perPage?: number;
show?: "pinned" | "all";
sort?: "rid" | "activity" | "seeding";
};
export class Client {
#fetcher: Fetcher;
public constructor(fetcher: Fetcher) {
this.#fetcher = fetcher;
}
public async getByDelegate(
delegateId: string,
query?: RepoListQuery,
options?: RequestOptions,
): Promise<Repo[]> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `delegates/${delegateId}/repos`,
query,
options,
},
reposSchema,
);
}
public async getByRid(rid: string, options?: RequestOptions): Promise<Repo> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}`,
options,
},
repoSchema,
);
}
public async getAll(
query?: RepoListQuery,
options?: RequestOptions,
): Promise<Repo[]> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: "repos",
query,
options,
},
reposSchema,
);
}
public async search(
query: string,
options?: RequestOptions,
): Promise<SearchResult[]> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: "repos/search",
query: { q: query },
options,
},
searchResultsSchema,
);
}
public async getActivity(
rid: string,
options?: RequestOptions,
): Promise<Activity> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/activity`,
options,
},
activitySchema,
);
}
public async getReadme(
rid: string,
sha: string,
options?: RequestOptions,
): Promise<Blob> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/readme/${sha}`,
options,
},
blobSchema,
);
}
public async getBlob(
rid: string,
sha: string,
path: string,
options?: RequestOptions,
): Promise<Blob> {
const blob = await this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/blob/${sha}/${path}`,
options,
},
blobSchema,
);
return blob;
}
public async getTree(
rid: string,
sha: string,
path?: string,
options?: RequestOptions,
): Promise<Tree> {
const tree = await this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/tree/${sha}/${path ?? ""}`,
options,
},
treeSchema,
);
return tree;
}
public async getTreeStatsBySha(
rid: string,
sha: string,
options?: RequestOptions,
): Promise<TreeStats> {
const tree = await this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/stats/tree/${sha}`,
options,
},
treeStatsSchema,
);
return tree;
}
public async getCommitCountBySha(
rid: string,
sha: string,
options?: RequestOptions,
): Promise<number> {
try {
const { commits } = await this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/stats/commits/${sha}`,
options,
},
commitCountSchema,
);
return commits;
} catch (error) {
// Compat: older httpd doesn't serve the commit-count endpoint, so fall
// back to the tree stats endpoint, which also returns the commit count.
// Client: remove when explorer drops httpd 0.26.
if (error instanceof ResponseError && error.status === 404) {
const stats = await this.getTreeStatsBySha(rid, sha, options);
return stats.commits;
}
throw error;
}
}
public async getAllRemotes(
rid: string,
options?: RequestOptions,
): Promise<Remote[]> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/remotes`,
options,
},
remotesSchema,
);
}
public async getRemoteByPeer(
rid: string,
peer: string,
options?: RequestOptions,
): Promise<Remote> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/remotes/${peer}`,
options,
},
remoteSchema,
);
}
public async getAllCommits(
rid: string,
query?: {
parent?: string;
since?: number;
until?: number;
page?: number;
perPage?: number;
},
options?: RequestOptions,
): Promise<Commits> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/commits`,
query,
options,
},
commitsSchema,
);
}
public async getCommitBySha(
rid: string,
sha: string,
options?: RequestOptions,
): Promise<Commit> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/commits/${sha}`,
options,
},
commitSchema,
);
}
public async getDiff(
rid: string,
revisionBase: string,
revisionOid: string,
options?: RequestOptions,
): Promise<DiffResponse> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/diff/${revisionBase}/${revisionOid}`,
options,
},
diffResponseSchema,
);
}
public async getDiffStats(
rid: string,
revisionBase: string,
revisionOid: string,
options?: RequestOptions,
): Promise<DiffStats> {
try {
return await this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/diff/${revisionBase}/${revisionOid}/stats`,
options,
},
diffStatsSchema,
);
} catch (error) {
// Compat: older httpd doesn't serve the diff-stats endpoint, so fall
// back to the full diff, which also carries the stats. Client: remove
// when explorer drops httpd 0.26.
if (error instanceof ResponseError && error.status === 404) {
const { diff } = await this.getDiff(
rid,
revisionBase,
revisionOid,
options,
);
return diff.stats;
}
throw error;
}
}
public async getJobsByCommit(
rid: string,
commit: string,
options?: RequestOptions,
): Promise<Job[]> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/jobs/${commit}`,
options,
},
jobsSchema,
);
}
public async getIssueById(
rid: string,
issueId: string,
options?: RequestOptions,
): Promise<Issue> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/issues/${issueId}`,
options,
},
issueSchema,
);
}
public async getAllIssues(
rid: string,
query?: {
page?: number;
perPage?: number;
status?: string;
},
options?: RequestOptions,
): Promise<Issue[]> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/issues`,
query,
options,
},
issuesSchema,
);
}
public async getPatchById(
rid: string,
patchId: string,
options?: RequestOptions,
): Promise<Patch> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/patches/${patchId}`,
options,
},
patchSchema,
);
}
public async getAllPatches(
rid: string,
query?: {
page?: number;
perPage?: number;
status?: string;
},
options?: RequestOptions,
): Promise<Patch[]> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/patches`,
query,
options,
},
patchesSchema,
);
}
public async getReleaseById(
rid: string,
releaseId: string,
options?: RequestOptions,
): Promise<Release> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/releases/${releaseId}`,
options,
},
releaseSchema,
);
}
public async getAllReleases(
rid: string,
query?: {
page?: number;
perPage?: number;
scope?: ReleaseScope;
showRedacted?: boolean;
},
options?: RequestOptions,
): Promise<Release[]> {
return this.#fetcher.fetchOk(
{
method: "GET",
path: `repos/${rid}/releases`,
query: { ...query, ...legacyReleasesQuery(query?.scope) },
options,
},
releasesSchema,
);
}
// One page of releases in an author scope, and whether more may follow.
// Takes the delegates as a promise too, so that the page can load
// alongside the repo.
public async getReleasesPage(
rid: string,
delegates: Author[] | Promise<Author[]>,
query: { scope: ReleaseScope; page: number; perPage: number },
options?: RequestOptions,
): Promise<{ releases: Release[]; morePages: boolean }> {
const [response, authors] = await Promise.all([
this.getAllReleases(rid, query, options),
delegates,
]);
return {
releases: legacyScopeReleases(response, authors, query.scope),
// Page on the response, as older nodes fill it with every author.
morePages: response.length === query.perPage,
};
}
// Whether anyone other than a delegate has a release that a user can see.
public async hasOtherReleases(
repo: Repo,
perPage: number,
options?: RequestOptions,
): Promise<boolean> {
const counts = repo.cobs?.releases;
if (counts) {
return counts.other > 0;
}
return legacyHasOtherReleases(
() =>
this.getAllReleases(
repo.rid,
{ scope: "untrusted", page: 0, perPage },
options,
),
repo.delegates,
perPage,
);
}
}