src/contract.ts

Functions

Imports

It imports src/contract/base.ts, src/contract/content.ts, src/contract/media.ts, src/contract/mentions.ts. Imported by src/adapter.ts, src/admin/kit.ts, src/admin/media.ts, src/admin/mentions.ts, src/admin/posts.ts, src/client.ts, src/conformance.ts, src/index.ts, src/media.ts, src/server.ts, src/server/content.ts, src/server/http.ts, src/server/media.ts, src/server/mentions.ts, src/testing.ts.

Source

1// The contract between Carrel and a site: every request and response body, as zod schemas.
2//
3// A site and Carrel agree when their schema hashes match. The hash covers these schemas and the
4// route table, so any change to either is a new contract, and Carrel's health check sees it.
5
6import { z } from "zod";
7
8export { ChangeId, ContentId, SiteInfo, SortDir, Version } from "./contract/base.js";
9export * from "./contract/content.js";
10export * from "./contract/media.js";
11export * from "./contract/mentions.js";
12import { SiteInfo, Version } from "./contract/base.js";
13import {
14  ContentDeleteQuery,
15  ContentDeleteResult,
16  ContentDoc,
17  ContentList,
18  ContentSummary,
19  ContentTagsInput,
20  Diff,
21  DiffQuery,
22  ListQuery,
23  PreviewInput,
24  PublishInput,
25  Revision,
26  RevisionList,
27  RevisionSource,
28  SaveDraftInput,
29  ScheduleInput,
30  UnpublishInput,
31  WriteResult,
32} from "./contract/content.js";
33import {
34  MediaAltInput,
35  MediaBulkInput,
36  MediaBulkResult,
37  MediaDeleteQuery,
38  MediaDeleteResult,
39  MediaDetail,
40  MediaItem,
41  MediaLens,
42  MediaList,
43  MediaListQuery,
44  MediaTagsInput,
45  MediaTrashEmptyInput,
46  MediaTrashEmptyResult,
47  MediaTrashInput,
48  MediaUploadLimits,
49  MediaUploadQuery,
50  MediaUse,
51  MediaWriteResult,
52} from "./contract/media.js";
53import {
54  MentionDecideInput,
55  MentionDeleteQuery,
56  MentionDeleteResult,
57  MentionItem,
58  MentionList,
59  MentionListQuery,
60  MentionSweepInput,
61  MentionSweepResult,
62  MentionWriteResult,
63} from "./contract/mentions.js";
64
65export const PACKAGE_VERSION = "0.8.1";
66export const PREFIX = "/api/carrel/v1";
67
68export const Capabilities = z.object({
69  content: z.boolean(),
70  preview: z.boolean(),
71  media: z.boolean(),
72  inbox: z.boolean(),
73  insight: z.boolean(),
74  publications: z.boolean(),
75  /** Present when `media` is true (v0.2.0). Optional, so a v0.1.0 reader parses a v0.2.0 meta. */
76  mediaUpload: MediaUploadLimits.optional(),
77  /** True when the site can delete content (v0.3.0). Absent or false: `DELETE /content/:id` answers 501. */
78  contentDelete: z.boolean().optional(),
79  /** True when the site can edit a file's alt text after upload (v0.4.0). Absent or false: the alt route answers 501. */
80  mediaAlt: z.boolean().optional(),
81  /** True when the site keeps tags on files (v0.4.0). Absent or false: the tags route answers 501. */
82  mediaTags: z.boolean().optional(),
83  /** True when the site has a media trash: soft delete and restore (v0.4.0). Absent or false: those routes answer 501. */
84  mediaTrash: z.boolean().optional(),
85  /** True when the site keeps tags on posts and writes them through `PUT /content/:id/tags` (v0.6.0). Absent or false: that route answers 501. */
86  contentTags: z.boolean().optional(),
87  /** The media lenses the site answers (v0.6.0); with any of them it also sorts the media list. Absent: a lens answers 501. */
88  mediaLenses: z.array(MediaLens).optional(),
89  /** True when the site receives webmentions and lets Carrel moderate them (v0.5.0). Absent or false: every mentions route answers 501. */
90  mentions: z.boolean().optional(),
91  /** True when a decision can be taken back to pending (v0.6.0), the `reset` decision. Absent or false: a reset answers 501. */
92  mentionReset: z.boolean().optional(),
93});
94
95export const Meta = z.object({
96  api: z.literal("carrel-site-api"),
97  packageVersion: z.string(),
98  schemaHash: z.string().regex(/^[0-9a-f]{64}$/),
99  site: SiteInfo,
100  capabilities: Capabilities,
101});
102
103export const ErrorCode = z.enum([
104  "unauthorized",
105  "rate-limited",
106  "not-configured",
107  "unavailable",
108  "not-found",
109  "method-not-allowed",
110  "invalid",
111  "too-large",
112  "version-conflict",
113  "refused",
114  "not-implemented",
115  "internal",
116]);
117
118export const ErrorBody = z.object({
119  error: ErrorCode,
120  message: z.string(),
121  /** On version-conflict only: what the site holds now, or null when the id does not exist. */
122  currentVersion: Version.nullable().optional(),
123  /** On a refused media delete only (v0.2.0): every place the file is used. */
124  usedBy: z.array(MediaUse).optional(),
125});
126
127export type Capabilities = z.infer<typeof Capabilities>;
128export type Meta = z.infer<typeof Meta>;
129export type ErrorCode = z.infer<typeof ErrorCode>;
130export type ErrorBody = z.infer<typeof ErrorBody>;
131
132/**
133 * Every route, relative to PREFIX. Groups declared for later stages answer 501 until a site
134 * implements them, so a route's existence is part of the contract even before its body is. The
135 * media group arrived in v0.2.0; a site whose adapter has no `media` still answers it 501. v0.3.0
136 * adds the source at a revision and an optional content delete (501 when the adapter has none).
137 * v0.4.0 adds media writes, each optional per site (501 when the adapter lacks the method): alt
138 * text, tags, trash, restore and empty-trash, and one bulk route that applies any of them to many files.
139 * v0.5.0 adds the mentions group: list, decide, delete and sweep, answering 501 for a site whose
140 * adapter has no `mentions`.
141 */
142export const ROUTES = [
143  { group: "meta", method: "GET", path: "/meta", response: "Meta" },
144  { group: "content", method: "GET", path: "/content", query: "ListQuery", response: "ContentList" },
145  { group: "content", method: "GET", path: "/content/:id", response: "ContentDoc" },
146  { group: "content", method: "PUT", path: "/content/:id/draft", request: "SaveDraftInput", response: "WriteResult" },
147  { group: "content", method: "POST", path: "/content/:id/publish", request: "PublishInput", response: "WriteResult" },
148  { group: "content", method: "POST", path: "/content/:id/schedule", request: "ScheduleInput", response: "WriteResult" },
149  { group: "content", method: "POST", path: "/content/:id/unpublish", request: "UnpublishInput", response: "WriteResult" },
150  { group: "content", method: "GET", path: "/content/:id/revisions", response: "RevisionList" },
151  { group: "content", method: "GET", path: "/content/:id/diff", query: "DiffQuery", response: "Diff" },
152  { group: "content", method: "GET", path: "/content/:id/revisions/:version", response: "RevisionSource" },
153  { group: "content", method: "DELETE", path: "/content/:id", query: "ContentDeleteQuery", response: "ContentDeleteResult" },
154  { group: "content", method: "PUT", path: "/content/:id/tags", request: "ContentTagsInput", response: "WriteResult" },
155  { group: "preview", method: "POST", path: "/preview", request: "PreviewInput", response: "text/html" },
156  { group: "media", method: "GET", path: "/media", query: "MediaListQuery", response: "MediaList" },
157  { group: "media", method: "POST", path: "/media", query: "MediaUploadQuery", request: "the file's bytes", response: "MediaItem" },
158  { group: "media", method: "GET", path: "/media/:id", response: "MediaDetail" },
159  { group: "media", method: "DELETE", path: "/media/:id", query: "MediaDeleteQuery", response: "MediaDeleteResult" },
160  { group: "media", method: "PUT", path: "/media/:id/alt", request: "MediaAltInput", response: "MediaWriteResult" },
161  { group: "media", method: "PUT", path: "/media/:id/tags", request: "MediaTagsInput", response: "MediaWriteResult" },
162  { group: "media", method: "POST", path: "/media/:id/trash", request: "MediaTrashInput", response: "MediaWriteResult" },
163  { group: "media", method: "POST", path: "/media/:id/restore", request: "MediaTrashInput", response: "MediaWriteResult" },
164  { group: "media", method: "POST", path: "/media/trash/empty", request: "MediaTrashEmptyInput", response: "MediaTrashEmptyResult" },
165  { group: "media", method: "POST", path: "/media/bulk", request: "MediaBulkInput", response: "MediaBulkResult" },
166  { group: "mentions", method: "GET", path: "/mentions", query: "MentionListQuery", response: "MentionList" },
167  { group: "mentions", method: "POST", path: "/mentions/sweep", request: "MentionSweepInput", response: "MentionSweepResult" },
168  { group: "mentions", method: "POST", path: "/mentions/:id/decide", request: "MentionDecideInput", response: "MentionWriteResult" },
169  { group: "mentions", method: "DELETE", path: "/mentions/:id", query: "MentionDeleteQuery", response: "MentionDeleteResult" },
170  { group: "inbox", method: "*", path: "/inbox/*", response: "not-implemented" },
171  { group: "insight", method: "*", path: "/insight/*", response: "not-implemented" },
172  { group: "publications", method: "*", path: "/publications/*", response: "not-implemented" },
173] as const;
174
175const HASHED = {
176  Meta, ContentSummary, ContentDoc, ListQuery, ContentList, SaveDraftInput, PublishInput,
177  ScheduleInput, UnpublishInput, WriteResult, Revision, RevisionList, DiffQuery, Diff,
178  PreviewInput, ErrorBody, MediaItem, MediaDetail, MediaListQuery, MediaList, MediaUploadQuery,
179  MediaDeleteQuery, MediaDeleteResult, RevisionSource, ContentDeleteQuery, ContentDeleteResult,
180  MediaAltInput, MediaTagsInput, MediaTrashInput, MediaWriteResult, MediaBulkInput, MediaBulkResult,
181  MediaTrashEmptyInput, MediaTrashEmptyResult,
182  MentionItem, MentionListQuery, MentionList, MentionDecideInput, MentionWriteResult, MentionDeleteQuery,
183  MentionDeleteResult, MentionSweepInput, MentionSweepResult,
184  ContentTagsInput,
185};
186
187/** JSON with sorted keys, so the hash depends on the contract and not on property order. */
188function canonical(value: unknown): string {
189  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
190  if (value && typeof value === "object") {
191    const entries = Object.entries(value as Record<string, unknown>)
192      .filter(([, v]) => v !== undefined)
193      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
194    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
195  }
196  return JSON.stringify(value);
197}
198
199let cachedHash: Promise<string> | undefined;
200
201/** The SHA-256 of the contract: every schema as JSON Schema, plus the route table. */
202export function schemaHash(): Promise<string> {
203  cachedHash ??= (async () => {
204    const schemas = Object.fromEntries(
205      Object.entries(HASHED).map(([name, schema]) => [name, z.toJSONSchema(schema, { io: "input" })]),
206    );
207    const bytes = new TextEncoder().encode(canonical({ prefix: PREFIX, routes: ROUTES, schemas }));
208    const digest = await crypto.subtle.digest("SHA-256", bytes);
209    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
210  })();
211  return cachedHash;
212}