src/adapter.ts

Functions

Imports

It imports src/contract.ts. Imported by src/index.ts, src/local.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// What each site implements. The package owns the route, the key, the rate limit and the shape of
2// every body; the adapter owns the site's storage, its rules and its render.
3
4import type {
5  Capabilities,
6  ContentDoc,
7  ContentList,
8  ListQuery,
9  MediaDetail,
10  MediaItem,
11  MediaList,
12  MediaLens,
13  MediaListQuery,
14  MediaUploadLimits,
15  MediaUse,
16  MentionList,
17  MentionListQuery,
18  MentionStatus,
19  PreviewInput,
20  PublishInput,
21  Revision,
22  SaveDraftInput,
23  ScheduleInput,
24  SiteInfo,
25  UnpublishInput,
26  WriteResult,
27} from "./contract.js";
28
29export interface ContentAdapter {
30  list(query: ListQuery): Promise<ContentList>;
31  /** null when the id does not exist. */
32  get(id: string): Promise<ContentDoc | null>;
33  /**
34   * Creates when expectedVersion is null and the id is free. Throws VersionConflictError when
35   * expectedVersion is not what the site holds, including a non-null version for a missing id.
36   */
37  saveDraft(id: string, input: SaveDraftInput): Promise<WriteResult>;
38  /** A first publish from Carrel's key is allowed (design decision 2): Carrel decides who triggers it. */
39  publish(id: string, input: PublishInput): Promise<WriteResult>;
40  schedule(id: string, input: ScheduleInput): Promise<WriteResult>;
41  /** Unpublish returns the item to draft. A delete is the separate, optional `delete` below. */
42  unpublish(id: string, input: UnpublishInput): Promise<WriteResult>;
43  /** Newest first. null when the id does not exist. */
44  revisions(id: string): Promise<Revision[] | null>;
45  /** The source as it was at a version; null when the id or the version does not exist. */
46  revisionSource(id: string, version: string): Promise<string | null>;
47  /**
48   * Optional (v0.3.0): deletes the item. Throws VersionConflictError when expectedVersion is not
49   * what the site holds, NotFoundError for a missing id, and RefusedError when the site's own rules
50   * refuse. A site without it answers `DELETE /content/:id` with 501. The write and whatever the
51   * site must do afterward (its cache purge, say) are one unit, so the site runs them together here.
52   */
53  delete?(id: string, input: { expectedVersion: string; changeId: string }): Promise<void>;
54  /**
55   * Optional (v0.6.0): sets the item's whole tag set, already unique, and returns the write like a
56   * save does. Throws VersionConflictError, NotFoundError (checked first, for a missing id) or
57   * RefusedError like the writes. A site without it answers `PUT /content/:id/tags` with 501.
58   */
59  setTags?(id: string, input: { tags: string[]; expectedVersion: string; changeId: string }): Promise<WriteResult>;
60}
61
62export interface PreviewAdapter {
63  /** The full page HTML, from the site's own route and pipeline, exactly as it would publish. */
64  render(input: PreviewInput): Promise<string>;
65}
66
67/** One upload, already checked by the package against the site's own limits and the file's bytes. */
68export interface MediaUpload {
69  bytes: Uint8Array;
70  /** One of the site's declared types, without parameters. */
71  contentType: string;
72  filename: string;
73  alt: string;
74  changeId: string;
75}
76
77/**
78 * The media group (v0.2.0). Files stay in the site's own storage and are served by the site; Carrel
79 * only lists, uploads and asks for deletes. The site's reference check decides every delete.
80 */
81export interface MediaAdapter {
82  /** What the site accepts. The package refuses any other type, and anything larger, unread. */
83  limits: MediaUploadLimits;
84  /**
85   * Optional (v0.6.0): the lenses `list` answers. A site that names any also sorts by `sort` and `dir`
86   * and says so in the answer's `sorted`. The package answers a lens not named here with 501.
87   */
88  lenses?: readonly MediaLens[];
89  list(query: MediaListQuery): Promise<MediaList>;
90  /** The file and every place it is used. null when the id does not exist. */
91  get(id: string): Promise<MediaDetail | null>;
92  upload(input: MediaUpload): Promise<MediaItem>;
93  /**
94   * Deletes the file. Throws MediaInUseError naming each use when the site's reference check finds
95   * one, NotFoundError for a missing id, and RefusedError when the check could not run: a delete the
96   * site could not check is never made.
97   */
98  delete(id: string, input: { changeId: string }): Promise<void>;
99  /**
100   * Optional (v0.4.0), each answering 501 when absent. Every one throws VersionConflictError when
101   * expectedVersion is not what the site holds, NotFoundError for a missing id and RefusedError when
102   * the site's own rules refuse, and returns the file's version after the write. A file's version
103   * identifies its editable metadata, so each write here moves it. The write and whatever must
104   * follow it (a cache purge) are one unit, run together in the method.
105   */
106  setAlt?(id: string, input: { alt: string; expectedVersion: string; changeId: string }): Promise<{ version: string }>;
107  /** `tags` is the whole set after the write, already in the contract's spelling. */
108  setTags?(id: string, input: { tags: string[]; expectedVersion: string; changeId: string }): Promise<{ version: string }>;
109  /** Soft delete: hides the file from list and removes nothing. Both trash and restore, or neither. */
110  trash?(id: string, input: { expectedVersion: string; changeId: string }): Promise<{ version: string }>;
111  restore?(id: string, input: { expectedVersion: string; changeId: string }): Promise<{ version: string }>;
112}
113
114/**
115 * The mentions group (v0.5.0), optional per site. Every write throws VersionConflictError when
116 * expectedVersion is not what the site holds, NotFoundError for a missing id and RefusedError when
117 * the site's own rules refuse. The write and the cache purge it needs are one unit, run together in
118 * the method, and the method reports whether the purge worked.
119 */
120export interface MentionsAdapter {
121  /** Newest first. `counts` and `expiring` cover the whole queue, not the page. */
122  list(query: MentionListQuery): Promise<MentionList>;
123  /** Approve or reject. Refuse (RefusedError) a mention that is not yet verified or that failed verification. */
124  decide(
125    id: string,
126    input: { decision: "approve" | "reject"; expectedVersion: string; changeId: string },
127  ): Promise<{ status: MentionStatus; version: string; purged: boolean | null }>;
128  /**
129   * Optional (v0.6.0): takes an approved or rejected mention back to pending, as it was before the
130   * decision, so a decision can be undone. Refuse (RefusedError) any other status. Absent: a reset answers 501.
131   */
132  reset?(
133    id: string,
134    input: { expectedVersion: string; changeId: string },
135  ): Promise<{ status: MentionStatus; version: string; purged: boolean | null }>;
136  /** Removes the only copy of what a stranger sent. */
137  delete(id: string, input: { expectedVersion: string; changeId: string }): Promise<{ purged: boolean | null }>;
138  /** Removes failed and rejected mentions past the site's retention windows, and reports how many. */
139  sweep(input: { changeId: string }): Promise<{ failed: number; rejected: number }>;
140}
141
142export interface SiteAdapter {
143  site: SiteInfo;
144  content: ContentAdapter;
145  preview: PreviewAdapter;
146  /** Absent on a site with no media manager: the media routes then answer 501, as in v0.1.0. */
147  media?: MediaAdapter;
148  /** Absent on a site that does not receive webmentions: the mentions routes then answer 501. */
149  mentions?: MentionsAdapter;
150}
151
152/**
153 * Stage 2 implemented content and preview; v0.2.0 adds media for a site whose adapter has it. The
154 * other groups answer 501 until their stage.
155 */
156export function capabilitiesOf(adapter: SiteAdapter): Capabilities {
157  return {
158    content: true,
159    preview: true,
160    media: Boolean(adapter.media),
161    inbox: false,
162    insight: false,
163    publications: false,
164    ...(adapter.media ? { mediaUpload: adapter.media.limits } : {}),
165    ...(adapter.content.delete ? { contentDelete: true } : {}),
166    ...(adapter.content.setTags ? { contentTags: true } : {}),
167    ...(adapter.media?.setAlt ? { mediaAlt: true } : {}),
168    ...(adapter.media?.lenses?.length ? { mediaLenses: [...adapter.media.lenses] } : {}),
169    ...(adapter.media?.setTags ? { mediaTags: true } : {}),
170    ...(adapter.media?.trash && adapter.media.restore ? { mediaTrash: true } : {}),
171    ...(adapter.mentions ? { mentions: true } : {}),
172    ...(adapter.mentions?.reset ? { mentionReset: true } : {}),
173  };
174}
175
176/** @deprecated Since v0.2.0 capabilities depend on the adapter: use capabilitiesOf(adapter). */
177export const CAPABILITIES: Capabilities = {
178  content: true,
179  preview: true,
180  media: false,
181  inbox: false,
182  insight: false,
183  publications: false,
184};
185
186/**
187 * A content version made from the fields that identify an item's own content: the first 32 hex
188 * characters of the SHA-256 of their JSON. For a site with no version column; pass the same fields,
189 * in the same order, on every read and write.
190 */
191export async function contentVersion(parts: readonly unknown[]): Promise<string> {
192  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(parts)));
193  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 32);
194}
195
196/** The expectedVersion on a write is not what the site holds. currentVersion null: no such id. */
197export class VersionConflictError extends Error {
198  constructor(readonly currentVersion: string | null, message = "The content changed since it was loaded.") {
199    super(message);
200    this.name = "VersionConflictError";
201  }
202}
203
204export class NotFoundError extends Error {
205  constructor(message = "No such content.") {
206    super(message);
207    this.name = "NotFoundError";
208  }
209}
210
211/** The site's reference check found the file in use: the delete is refused, naming every use. */
212export class MediaInUseError extends Error {
213  constructor(readonly usedBy: MediaUse[], message?: string) {
214    super(message ?? `The file is in use: ${describeUses(usedBy)}. Remove it from each first.`);
215    this.name = "MediaInUseError";
216  }
217}
218
219/** "Title (detail); Other (detail)", one entry per use, for the refusal a writer reads. */
220export function describeUses(uses: MediaUse[]): string {
221  return uses.map((u) => `${u.title || u.id} (${u.detail})`).join("; ");
222}
223
224/** The site's own rules refused the write, such as a render failure or a policy. Shown to the writer. */
225export class RefusedError extends Error {
226  constructor(message: string) {
227    super(message);
228    this.name = "RefusedError";
229  }
230}