fedipod-bb 0.2.0

package/src/urls.mjs

@@ -0,0 +1,90 @@
+// urls.mjs — where a forum's documents live on its pod.
+//
+// A forum is one root holding a site actor and, under `c/`, one FediPod group
+// root per category. The group roots are `apUrls` verbatim, so every module
+// that publishes or drains a group works on a category unchanged; the forum
+// adds the topic documents beside them and one inbox above them.
+//
+// The root is this application's answer, stated here: the pod library refuses
+// to guess one, and a forum is one application.
+
+import crypto from 'node:crypto';
+import { apUrls } from 'fedipod/pod/urls.mjs';
+
+export const ROOT = 'fedipod-bb/';
+
+// A category's slug is its handle's local part and a container name: lower
+// case letters, digits and hyphens, starting with a letter or digit.
+export const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/u;
+export const isSlug = (s) => typeof s === 'string' && SLUG.test(s);
+
+// A topic's id on the pod: the month it opened and a slug of its title, which
+// keeps a category's topic container readable to a person listing it.
+export const TID = /^[0-9]{4}-[0-9]{2}-[a-z0-9][a-z0-9-]{0,78}$/u;
+export const isTid = (s) => typeof s === 'string' && TID.test(s);
+
+// The name a cached copy is filed under: a post's id is a URL and a URL is
+// not a file name, so the copy takes a digest of it.
+export const cacheKey = (postId) => crypto.createHash('sha256').update(String(postId)).digest('hex').slice(0, 16);
+
+// `front` and `handle`: a forum reachable through a Gateway. Its own actor
+// answers at `<front>/u/<handle>/`, each category at `<front>/u/<slug>/`,
+// and every advertised id is rewritten onto the pod at the transport's one
+// choke point (`toPod`). Without a front the ids are the pod's own.
+export function forumUrls(remotePod, root = ROOT, { publicBase = null, front = null, handle = null } = {}) {
+  const origin = front ? String(front).replace(/\/$/u, '') : null;
+  if (origin && !handle) throw new Error('forumUrls: a fronted forum needs its handle');
+  const site = apUrls(remotePod, root, { publicBase: publicBase || (origin ? `${origin}/u/${handle}/` : null) });
+  const face = site.actor.slice(0, -'ap/actor'.length);
+  site.front = origin;
+  site.categories = face + 'ap/categories';
+  site.administrators = face + 'ap/administrators';
+  // Everything the forum holds, newest first, across every category: what a
+  // reader arriving at the forum sees before they know its categories.
+  site.latest = face + 'ap/latest';
+  // The moderators' own container: the queue of reports and held posts,
+  // readable by the moderators' WebIDs and nobody else. Under the pod's own
+  // root, not the advertised face — nothing here is published.
+  site.mod = (remotePod.endsWith('/') ? remotePod : remotePod + '/') + (root.endsWith('/') ? root : root + '/') + 'mod/';
+  site.siteHtml = face + 'ap/site.html';
+  site.root = root.endsWith('/') ? root : root + '/';
+  site.category = (slug) => {
+    if (!isSlug(slug)) throw new Error(`forumUrls: not a category slug (${slug})`);
+    return categoryUrls(remotePod, site.root + 'c/' + slug + '/', {
+      publicBase: origin ? `${origin}/u/${slug}/` : (publicBase ? face + 'c/' + slug + '/' : null),
+      forumInbox: site.inbox,
+    });
+  };
+  return site;
+}
+
+// A category: a group root plus the topic documents. `forumInbox` is what
+// the category advertises as its inbox — deliveries to any category land in
+// the forum's one inbox, and the host routes them.
+export function categoryUrls(remotePod, root, { publicBase = null, forumInbox = null } = {}) {
+  const urls = apUrls(remotePod, root, { publicBase });
+  const face = urls.actor.slice(0, -'ap/actor'.length);
+  urls.forumInbox = forumInbox || urls.inbox;
+  // The category's topics, newest first, paged like an outbox: a head under
+  // ap/ and page documents beside it.
+  urls.topics = face + 'ap/topics';
+  urls.topicsPage = (n) => `${urls.topics}-${n}`;
+  // One topic: its head and its pages live in a public container, so a new
+  // page inherits the container's rule and needs none of its own.
+  urls.topicContainer = face + 'ap/topic/';
+  urls.topic = (tid) => {
+    if (!isTid(tid)) throw new Error(`categoryUrls: not a topic id (${tid})`);
+    return urls.topicContainer + tid;
+  };
+  urls.topicPage = (tid, n) => `${urls.topic(tid)}-${n}`;
+  // Readable copies of members' posts, for the website.
+  urls.cache = face + 'ap/cache/';
+  urls.cached = (postId) => urls.cache + cacheKey(postId);
+  // Who may read a members-only category: the collection an Add or a Remove
+  // names when someone is let in or out. Nothing is published there; it is a
+  // name to address, and the pod's own access rule is what enforces it.
+  urls.members = face + 'ap/members';
+  urls.categoryHtml = face + 'ap/index.html';
+  urls.topicHtml = (tid) => face + 'ap/t/' + tid + '.html';
+  return urls;
+}

package/src/wire.mjs

@@ -0,0 +1,114 @@
+// wire.mjs — the forum's documents as other servers read them: a topic as a
+// context collection (FEP-7888), a category's topic list, the forum's
+// category and administrator lists, and the site actor. Every term is
+// ActivityStreams; the group actor a category publishes is FediPod's own.
+
+import { AS_CTX, pageItems, orderedCollection, actorDoc } from 'fedipod/core/wire.mjs';
+
+export const TOPIC_PAGE_SIZE = 20;
+export const TOPICS_PAGE_SIZE = 20;
+
+// ── a topic ────────────────────────────────────────────────────────────
+// The head is what a post's `context` names: the collection's owner is the
+// category (`attributedTo`), the audience is the category, and the pages
+// hold the posts in the order they were said. Oldest first: a thread is
+// read forwards, so `first` is page 1.
+export function topicHead({ id, name, category, total, pageCount, published, updated = null, closed = null }) {
+  const pages = Math.max(1, pageCount);
+  return {
+    '@context': AS_CTX,
+    id, type: 'OrderedCollection',
+    name,
+    attributedTo: category,
+    audience: category,
+    totalItems: total,
+    first: `${id}-1`,
+    last: `${id}-${pages}`,
+    published,
+    ...(updated ? { updated } : {}),
+    // Closed: this topic takes no more replies (AS2 `closed`).
+    ...(closed ? { closed } : {}),
+  };
+}
+
+// A page carries `prev` and `next` both ways. Writing page n+1 rewrites page
+// n once, to give it a `next`; nothing else on a sealed page ever changes.
+export function topicPage({ id, n, items, pageCount }) {
+  return {
+    '@context': AS_CTX,
+    id: `${id}-${n}`,
+    type: 'OrderedCollectionPage',
+    partOf: id,
+    ...(n > 1 ? { prev: `${id}-${n - 1}` } : {}),
+    ...(n < pageCount ? { next: `${id}-${n + 1}` } : {}),
+    orderedItems: items,
+  };
+}
+
+// Posts in the order they were said; the assignment is kept so a removed
+// post leaves its page one short rather than re-slicing every page after it.
+export function topicPaging(postIds, index = []) {
+  const byId = new Map();
+  for (const id of postIds) if (typeof id === 'string' && !byId.has(id)) byId.set(id, id);
+  return pageItems({ order: postIds, byId, index, pageSize: TOPIC_PAGE_SIZE });
+}
+
+// ── a category's topics ────────────────────────────────────────────────
+// Newest first, the way an outbox is read: `first` is the newest page and
+// `next` walks back in time. Pages are numbered from the oldest end so
+// opening a topic moves only the newest page.
+export function topicsHead({ id, category, total, pageCount }) {
+  const pages = Math.max(1, pageCount);
+  return {
+    '@context': AS_CTX,
+    id, type: 'OrderedCollection',
+    attributedTo: category,
+    totalItems: total,
+    first: `${id}-${pages}`,
+    last: `${id}-1`,
+  };
+}
+
+export function topicsPage({ id, n, items }) {
+  return {
+    '@context': AS_CTX,
+    id: `${id}-${n}`,
+    type: 'OrderedCollectionPage',
+    partOf: id,
+    orderedItems: [...items].reverse(),          // newest first within the page
+    ...(n > 1 ? { next: `${id}-${n - 1}` } : {}),
+  };
+}
+
+// `topicIds` oldest first, as the record keeps them.
+export function topicsPaging(topicIds, index = []) {
+  const byId = new Map();
+  for (const id of topicIds) if (typeof id === 'string' && !byId.has(id)) byId.set(id, id);
+  return pageItems({ order: topicIds, byId, index, pageSize: TOPICS_PAGE_SIZE });
+}
+
+// ── the forum ──────────────────────────────────────────────────────────
+export const categoriesCollection = (id, actorIds) => orderedCollection(id, actorIds);
+// Who may read a private category: the WebIDs its posts are written for. Its
+// readers are its items — nobody outside the list can read the list — and the
+// forum's own WebID is one of them, because the forum fetches every post back
+// from its author's pod before it carries it.
+export const membersCollection = (id, webIds) => orderedCollection(id, webIds);
+export const administratorsCollection = (id, actorIds) => orderedCollection(id, actorIds);
+// The latest posts: the forum's own copies of them, newest first. Its items
+// are the copies rather than the authors' ids, because one fetch of a copy
+// tells a reader everything — who wrote it, when, and which topic it is in.
+export const latestCollection = (id, copyUrls) => orderedCollection(id, copyUrls);
+
+// The forum's own actor: an Application, the service that speaks for the
+// site. Everything else is what any FediPod actor carries.
+export function siteActorDoc(opts) {
+  return actorDoc({ ...opts, kind: 'application' });
+}
+
+// ── a cached copy ──────────────────────────────────────────────────────
+// What a removed copy becomes: a Tombstone that says what it was, so a
+// reader landing on it knows a post stood here (FEP-4f05).
+export function cachedTombstone({ id, formerType = 'Note', deleted = new Date().toISOString() }) {
+  return { '@context': AS_CTX, id, type: 'Tombstone', formerType, deleted };
+}