mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-21 22:30:41 +08:00
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
722 lines
16 KiB
TypeScript
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,
|
|
);
|
|
}
|
|
}
|