src/testing.ts

Functions

Imports

It imports src/adapter.ts, src/contract.ts, src/frontmatter.ts. No module of this repo imports it.

Source

1// A reference adapter held in memory: what a conforming site does, small enough to read in one
2// sitting. Carrel's tests run against it, and the conformance suite is proven on it.
3
4import { MediaInUseError, NotFoundError, RefusedError, VersionConflictError, type MediaAdapter, type MentionsAdapter, type SiteAdapter } from "./adapter.js";
5import { joinSource, setTags as writeTags, splitSource, tagsOf } from "./frontmatter.js";
6import { LARGE_MEDIA_BYTES, MEDIA_LENSES } from "./contract.js";
7import type { ContentDoc, ContentStatus, ContentSummary, MediaLens, MediaItem, MediaUploadLimits, MediaUse, MentionItem, MentionStatus, Revision, SiteInfo, WriteResult } from "./contract.js";
8
9interface Stored {
10  doc: ContentDoc;
11  history: Array<{ revision: Revision; source: string }>;
12}
13
14export interface MemoryAdapterOptions {
15  site?: SiteInfo;
16  now?: () => Date;
17  /** The media group's limits, or false for a site with no media manager (a v0.1.0 site). */
18  media?: MediaUploadLimits | false;
19  /** false for a site whose adapter has no content delete (its route then answers 501). On by default. */
20  contentDelete?: boolean;
21  /** false for a site that keeps no post tags through the API (a v0.5.0 site): the tags route then answers 501. On by default. */
22  contentTags?: boolean;
23  /** false for a media manager with no alt, tag or trash writes (a v0.2.0 site): those routes then answer 501. On by default. */
24  mediaWrites?: boolean;
25  /** false for a media manager with no lenses and no sort (a v0.5.0 site): a lens then answers 501. On by default. */
26  mediaLenses?: boolean;
27  /** false for a mentions group that ignores q and targetId (a v0.5.0 site) and so echoes no `filtered`. On by default. */
28  mentionFilters?: boolean;
29  /** false for a site that does not receive webmentions (its routes then answer 501). On by default. */
30  mentions?: boolean;
31  /** false for a mentions group with no reset (a v0.5.0 site): a reset then answers 501. On by default. */
32  mentionReset?: boolean;
33}
34
35/** What the reference adapter's sweep keeps, like dustinedwards.info: failed rows 30 days, rejected rows 90. */
36const MEMORY_MENTION_RETENTION_DAYS = { failed: 30, rejected: 90 } as const;
37
38/** What the endpoint writes when a stranger sends a mention, for tests to seed the queue with. */
39export interface ReceivedMention {
40  sourceUrl: string;
41  targetId: string;
42  status?: MentionStatus;
43  authorName?: string | null;
44  authorUrl?: string | null;
45  excerpt?: string | null;
46  failureReason?: string | null;
47  receivedAt?: Date;
48}
49
50/** What the reference adapter accepts, like dustinedwards.info's own list, at a test-sized limit. */
51export const MEMORY_MEDIA_LIMITS: MediaUploadLimits = {
52  maxBytes: 5 * 1024 * 1024,
53  types: ["image/png", "image/jpeg", "image/gif", "image/webp", "image/avif", "image/svg+xml"],
54};
55
56const EXTENSIONS: Record<string, string> = {
57  "image/png": "png",
58  "image/jpeg": "jpg",
59  "image/gif": "gif",
60  "image/webp": "webp",
61  "image/avif": "avif",
62  "image/svg+xml": "svg",
63  "application/pdf": "pdf",
64};
65
66interface StoredMedia {
67  item: MediaItem;
68  bytes: Uint8Array;
69}
70
71/** The item with its tags (v0.6.0), where its frontmatter can hold them. */
72function withTags(doc: ContentDoc): ContentDoc {
73  const front = splitSource(doc.source).front;
74  return front !== null ? { ...doc, tags: tagsOf(front) } : doc;
75}
76
77/** A list row: the item without its source, with its version and tags. */
78function summaryOf(doc: ContentDoc): ContentSummary {
79  const { source: _s, format: _f, ...summary } = withTags(doc);
80  return summary;
81}
82
83function titleOf(source: string, id: string): string {
84  const front = source.match(/^---\r?\n[\s\S]*?^title:\s*["']?(.+?)["']?\s*$/m);
85  if (front) return front[1]!;
86  const heading = source.match(/^#\s+(.+)$/m);
87  return heading ? heading[1]!.trim() : id;
88}
89
90export function memoryAdapter(
91  options: MemoryAdapterOptions = {},
92): SiteAdapter & {
93  store: Map<string, Stored>;
94  mediaStore: Map<string, StoredMedia>;
95  deleted: string[];
96  deletedContent: string[];
97  mentionStore: Map<string, MentionItem>;
98  /** Targets whose cached page the adapter purged, one entry per write that purges. */
99  purged: string[];
100  /** Adds a mention as the site's endpoint would, and returns its id. */
101  receiveMention(fields: ReceivedMention): string;
102} {
103  const site = options.site ?? { id: "memory", name: "Memory site", origin: "https://memory.example" };
104  const now = options.now ?? (() => new Date());
105  const store = new Map<string, Stored>();
106  let counter = 0;
107
108  function expect(id: string, expectedVersion: string | null): Stored | undefined {
109    const current = store.get(id);
110    const held = current?.doc.version ?? null;
111    if (held !== expectedVersion) throw new VersionConflictError(held);
112    return current;
113  }
114
115  function commit(
116    id: string,
117    previous: Stored | undefined,
118    changes: { source?: string; status: ContentStatus; publishAt?: string | null },
119    changeId: string,
120    message: string,
121  ): WriteResult {
122    const at = now().toISOString();
123    const version = `v${++counter}`;
124    const source = changes.source ?? previous?.doc.source ?? "";
125    const wasPublished = previous?.doc.publishedAt ?? null;
126    const doc: ContentDoc = {
127      id,
128      kind: "post",
129      title: titleOf(source, id),
130      status: changes.status,
131      path: changes.status === "published" || wasPublished ? `/blog/${id}` : null,
132      publishAt: changes.publishAt ?? null,
133      publishedAt: changes.status === "published" ? (wasPublished ?? at) : wasPublished,
134      updatedAt: at,
135      format: "markdown",
136      source,
137      version,
138    };
139    const history = previous?.history ?? [];
140    history.unshift({ revision: { version, at, author: "carrel", message: `${message} [${changeId}]` }, source });
141    store.set(id, { doc, history });
142    return { id, version, status: doc.status, changeId };
143  }
144
145  function existing(id: string, expectedVersion: string): Stored {
146    const current = expect(id, expectedVersion);
147    if (!current) throw new NotFoundError();
148    return current;
149  }
150
151  const mediaStore = new Map<string, StoredMedia>();
152  const deleted: string[] = [];
153  const deletedContent: string[] = [];
154  let mediaCounter = 0;
155  let mediaVersion = 0;
156  const nextMediaVersion = () => `m${++mediaVersion}`;
157  const mediaWrites = options.mediaWrites !== false;
158
159  /** The stored file, or NotFoundError; a stale expectedVersion is VersionConflictError. */
160  function heldMedia(id: string, expectedVersion: string): StoredMedia {
161    const stored = mediaStore.get(id);
162    if (!stored) throw new NotFoundError("No such media.");
163    if (stored.item.version !== expectedVersion) throw new VersionConflictError(stored.item.version ?? null, "The file changed since it was loaded.");
164    return stored;
165  }
166
167  /** Every metadata write moves the version, so alt, tags and trash each count as a change. */
168  function touchMedia(stored: StoredMedia, changes: Partial<MediaItem>): { version: string } {
169    const version = nextMediaVersion();
170    stored.item = { ...stored.item, ...changes, version };
171    return { version };
172  }
173
174  /** The lenses, as the site would answer them: nothing uses it, it has no alt text, it is over the size line. */
175  const LENS: Record<MediaLens, (i: MediaItem) => boolean> = {
176    unattached: (i) => usesOf(i.id).length === 0,
177    "no-alt": (i) => i.alt.trim() === "",
178    large: (i) => i.bytes > LARGE_MEDIA_BYTES,
179  };
180
181  /** The site's reference check: every post whose source carries the file's URL, as the real site scans. */
182  function usesOf(id: string): MediaUse[] {
183    const url = `/media/${id}`;
184    const uses: MediaUse[] = [];
185    for (const { doc } of store.values()) {
186      const lines = doc.source.split("\n");
187      lines.forEach((line, i) => {
188        if (line.includes(url)) uses.push({ type: "post", id: doc.id, title: doc.title, detail: `line ${i + 1}` });
189      });
190    }
191    return uses;
192  }
193
194  const mediaAdapter: MediaAdapter | undefined =
195    options.media === false
196      ? undefined
197      : {
198          limits: options.media ?? MEMORY_MEDIA_LIMITS,
199          ...(options.mediaLenses === false ? {} : { lenses: MEDIA_LENSES }),
200          async list(query) {
201            const needle = query.q?.toLowerCase();
202            const lensed = options.mediaLenses !== false;
203            const all = [...mediaStore.values()]
204              .map((m) => m.item)
205              .filter((i) => (query.trashed === "only" ? Boolean(i.trashedAt) : !i.trashedAt))
206              .filter((i) => !query.tag || (i.tags ?? []).includes(query.tag))
207              .filter((i) => !needle || [i.id, i.filename ?? "", i.alt].some((t) => t.toLowerCase().includes(needle)))
208              .filter((i) => !lensed || !query.lens || LENS[query.lens](i))
209              .reverse();
210            // v0.6.0: sorted as asked, newest, largest or A to Z first unless dir says otherwise.
211            const sorted = lensed && query.sort ? { sort: query.sort, dir: query.dir ?? (query.sort === "name" ? "asc" : "desc") } : undefined;
212            if (sorted) {
213              const key = (i: MediaItem): string | number => (sorted.sort === "size" ? i.bytes : sorted.sort === "name" ? (i.filename ?? i.id).toLowerCase() : (i.uploadedAt ?? ""));
214              const order = [...all];
215              all.sort((a, b) => {
216                const [x, y] = [key(a), key(b)];
217                const by = typeof x === "number" ? x - (y as number) : x.localeCompare(y as string);
218                return (sorted.dir === "asc" ? 1 : -1) * by || order.indexOf(a) - order.indexOf(b);
219              });
220            }
221            const start = query.cursor ? Number(query.cursor) : 0;
222            const page = all.slice(start, start + query.limit);
223            return {
224              items: page,
225              nextCursor: start + query.limit < all.length ? String(start + query.limit) : null,
226              ...(lensed ? { total: all.length } : {}),
227              ...(sorted ? { sorted } : {}),
228            };
229          },
230          async get(id) {
231            const stored = mediaStore.get(id);
232            return stored ? { ...stored.item, usedBy: usesOf(id) } : null;
233          },
234          async upload(input) {
235            const base = input.filename.replace(/\.[^.]*$/, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "file";
236            const id = `uploads/${++mediaCounter}-${base}.${EXTENSIONS[input.contentType] ?? "bin"}`;
237            const item: MediaItem = {
238              id,
239              url: `/media/${id}`,
240              filename: input.filename,
241              contentType: input.contentType,
242              bytes: input.bytes.byteLength,
243              width: null,
244              height: null,
245              alt: input.alt,
246              uploadedAt: now().toISOString(),
247              deletable: true,
248              ...(mediaWrites ? { version: nextMediaVersion(), tags: [], trashedAt: null } : {}),
249            };
250            mediaStore.set(id, { item, bytes: input.bytes });
251            return item;
252          },
253          async delete(id) {
254            if (!mediaStore.has(id)) throw new NotFoundError("No such media.");
255            const uses = usesOf(id);
256            if (uses.length > 0) throw new MediaInUseError(uses);
257            mediaStore.delete(id);
258            deleted.push(id);
259          },
260          ...(mediaWrites
261            ? {
262                async setAlt(id: string, input: { alt: string; expectedVersion: string; changeId: string }) {
263                  return touchMedia(heldMedia(id, input.expectedVersion), { alt: input.alt });
264                },
265                async setTags(id: string, input: { tags: string[]; expectedVersion: string; changeId: string }) {
266                  return touchMedia(heldMedia(id, input.expectedVersion), { tags: input.tags });
267                },
268                async trash(id: string, input: { expectedVersion: string; changeId: string }) {
269                  return touchMedia(heldMedia(id, input.expectedVersion), { trashedAt: now().toISOString() });
270                },
271                async restore(id: string, input: { expectedVersion: string; changeId: string }) {
272                  return touchMedia(heldMedia(id, input.expectedVersion), { trashedAt: null });
273                },
274              }
275            : {}),
276        };
277
278  // ---------- mentions: what dustinedwards.info does, in memory
279
280  const mentionStore = new Map<string, MentionItem>();
281  const purged: string[] = [];
282  let mentionCounter = 0;
283  let mentionVersion = 0;
284  const DAY = 24 * 60 * 60 * 1000;
285  /** Same rule as the site: only a verified mention (pending, approved, rejected) takes a decision. */
286  const DECIDABLE: MentionStatus[] = ["pending", "approved", "rejected"];
287
288  function receiveMention(fields: ReceivedMention): string {
289    const id = String(++mentionCounter);
290    const status = fields.status ?? "pending";
291    const receivedAt = (fields.receivedAt ?? now()).toISOString();
292    mentionStore.set(id, {
293      id,
294      status,
295      sourceUrl: fields.sourceUrl,
296      targetId: fields.targetId,
297      authorName: fields.authorName ?? null,
298      authorUrl: fields.authorUrl ?? null,
299      excerpt: fields.excerpt ?? null,
300      failureReason: fields.failureReason ?? (status === "failed" ? "no-link" : null),
301      receivedAt,
302      verifiedAt: status === "unverified" ? null : receivedAt,
303      decidedAt: null,
304      version: `m${++mentionVersion}`,
305    });
306    return id;
307  }
308
309  function heldMention(id: string, expectedVersion: string): MentionItem {
310    const current = mentionStore.get(id);
311    if (!current) throw new NotFoundError("No such mention.");
312    if (current.version !== expectedVersion) throw new VersionConflictError(current.version);
313    return current;
314  }
315
316  function expiring(): { failed: MentionItem[]; rejected: MentionItem[] } {
317    const at = now().getTime();
318    const past = (status: "failed" | "rejected") =>
319      [...mentionStore.values()].filter(
320        (m) => m.status === status && Date.parse(m.receivedAt) < at - MEMORY_MENTION_RETENTION_DAYS[status] * DAY,
321      );
322    return { failed: past("failed"), rejected: past("rejected") };
323  }
324
325  const mentionsAdapter: MentionsAdapter | undefined =
326    options.mentions === false
327      ? undefined
328      : {
329          async list(query) {
330            const filters = options.mentionFilters !== false;
331            const needle = filters ? query.q?.toLowerCase() : undefined;
332            const all = [...mentionStore.values()]
333              .filter((m) => !query.status || m.status === query.status)
334              .filter((m) => !needle || [m.sourceUrl, m.authorName ?? "", m.excerpt ?? ""].some((t) => t.toLowerCase().includes(needle)))
335              .filter((m) => !filters || !query.targetId || m.targetId === query.targetId)
336              .sort((a, b) => Date.parse(b.receivedAt) - Date.parse(a.receivedAt) || Number(b.id) - Number(a.id));
337            const start = query.cursor ? Number(query.cursor) : 0;
338            const counts = { unverified: 0, pending: 0, approved: 0, rejected: 0, failed: 0 };
339            for (const m of mentionStore.values()) counts[m.status]++;
340            const soon = expiring();
341            return {
342              items: all.slice(start, start + query.limit),
343              nextCursor: start + query.limit < all.length ? String(start + query.limit) : null,
344              counts,
345              expiring: { failed: soon.failed.length, rejected: soon.rejected.length },
346              ...(filters && (query.q || query.targetId) ? { filtered: { ...(query.q ? { q: query.q } : {}), ...(query.targetId ? { targetId: query.targetId } : {}) } } : {}),
347            };
348          },
349          async decide(id, input) {
350            const current = heldMention(id, input.expectedVersion);
351            if (!DECIDABLE.includes(current.status)) {
352              throw new RefusedError(`A ${current.status} mention cannot be decided: only a verified mention can.`);
353            }
354            const next: MentionItem = {
355              ...current,
356              status: input.decision === "approve" ? "approved" : "rejected",
357              decidedAt: now().toISOString(),
358              version: `m${++mentionVersion}`,
359            };
360            mentionStore.set(id, next);
361            purged.push(current.targetId);
362            return { status: next.status, version: next.version, purged: true };
363          },
364          async reset(id, input) {
365            const current = heldMention(id, input.expectedVersion);
366            if (current.status !== "approved" && current.status !== "rejected") {
367              throw new RefusedError(`A ${current.status} mention has no decision to take back.`);
368            }
369            const next: MentionItem = { ...current, status: "pending", decidedAt: null, version: `m${++mentionVersion}` };
370            mentionStore.set(id, next);
371            purged.push(current.targetId);
372            return { status: next.status, version: next.version, purged: true };
373          },
374          async delete(id, input) {
375            const current = heldMention(id, input.expectedVersion);
376            mentionStore.delete(id);
377            purged.push(current.targetId);
378            return { purged: true };
379          },
380          async sweep() {
381            const gone = expiring();
382            for (const m of [...gone.failed, ...gone.rejected]) mentionStore.delete(m.id);
383            return { failed: gone.failed.length, rejected: gone.rejected.length };
384          },
385        };
386
387  // A v0.5.0 mentions group: no way back to pending.
388  if (mentionsAdapter && options.mentionReset === false) delete mentionsAdapter.reset;
389
390  return {
391    site,
392    mentionStore,
393    purged,
394    receiveMention,
395    ...(mentionsAdapter ? { mentions: mentionsAdapter } : {}),
396    store,
397    mediaStore,
398    deleted,
399    deletedContent,
400    ...(mediaAdapter ? { media: mediaAdapter } : {}),
401    content: {
402      async list(query) {
403        const needle = query.q?.toLowerCase();
404        const all = [...store.values()]
405          .map((s) => s.doc)
406          .filter((d) => !query.status || d.status === query.status)
407          .filter((d) => !needle || d.title.toLowerCase().includes(needle) || d.source.toLowerCase().includes(needle))
408          .sort((a, b) => a.id.localeCompare(b.id));
409        // v0.6.0: sorted as asked, newest first for the dates and A to Z for titles unless dir says otherwise.
410        const sorted = query.sort ? { sort: query.sort, dir: query.dir ?? (query.sort === "title" ? "asc" : "desc") } : undefined;
411        if (sorted) {
412          const key = (d: ContentDoc) => (sorted.sort === "title" ? d.title.toLowerCase() : sorted.sort === "published" ? (d.publishedAt ?? d.publishAt ?? "") : (d.updatedAt ?? ""));
413          all.sort((a, b) => (sorted.dir === "asc" ? 1 : -1) * key(a).localeCompare(key(b)) || a.id.localeCompare(b.id));
414        }
415        const start = query.cursor ? Number(query.cursor) : 0;
416        const page = all.slice(start, start + query.limit);
417        const next = start + query.limit < all.length ? String(start + query.limit) : null;
418        return {
419          items: page.map(summaryOf),
420          nextCursor: next,
421          total: all.length,
422          ...(sorted ? { sorted } : {}),
423        };
424      },
425      async get(id) {
426        const doc = store.get(id)?.doc;
427        return doc ? withTags(doc) : null;
428      },
429      async saveDraft(id, input) {
430        const previous = expect(id, input.expectedVersion);
431        const status = previous?.doc.status === "published" ? "published" : "draft";
432        return commit(id, previous, { source: input.source, status, publishAt: previous?.doc.publishAt }, input.changeId, "Save");
433      },
434      async publish(id, input) {
435        const previous = existing(id, input.expectedVersion);
436        return commit(id, previous, { source: input.source, status: "published" }, input.changeId, "Publish");
437      },
438      async schedule(id, input) {
439        const previous = existing(id, input.expectedVersion);
440        return commit(id, previous, { source: input.source, status: "scheduled", publishAt: input.publishAt }, input.changeId, "Schedule");
441      },
442      async unpublish(id, input) {
443        const previous = existing(id, input.expectedVersion);
444        return commit(id, previous, { status: "draft" }, input.changeId, "Unpublish");
445      },
446      async revisions(id) {
447        return store.get(id)?.history.map((h) => h.revision) ?? null;
448      },
449      async revisionSource(id, version) {
450        return store.get(id)?.history.find((h) => h.revision.version === version)?.source ?? null;
451      },
452      ...(options.contentTags === false
453        ? {}
454        : {
455            async setTags(id: string, input: { tags: string[]; expectedVersion: string; changeId: string }) {
456              if (!store.has(id)) throw new NotFoundError();
457              const previous = existing(id, input.expectedVersion);
458              const parts = splitSource(previous.doc.source);
459              if (parts.front === null) throw new RefusedError("This post has no frontmatter, so it has nowhere to keep tags.");
460              const source = joinSource({ ...parts, front: writeTags(parts.front, input.tags) });
461              return commit(id, previous, { source, status: previous.doc.status, publishAt: previous.doc.publishAt }, input.changeId, "Tags");
462            },
463          }),
464      ...(options.contentDelete === false
465        ? {}
466        : {
467            async delete(id: string, input: { expectedVersion: string; changeId: string }) {
468              if (!store.has(id)) throw new NotFoundError();
469              expect(id, input.expectedVersion);
470              store.delete(id);
471              deletedContent.push(id);
472            },
473          }),
474    },
475    preview: {
476      async render(input) {
477        const title = titleOf(input.source, input.id ?? "preview");
478        const escape = (s: string) => s.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
479        return `<!doctype html><html><head><title>${escape(title)}</title></head><body><pre>${escape(input.source)}</pre></body></html>`;
480      },
481    },
482  };
483}