fedipod-server 0.29.0 → 0.31.0

package/lib/core/intake/index.mjs

@@ -1,732 +0,0 @@
-// intake.mjs — drains the remote pod's public-append inbox and applies side
-// effects. Inbound authenticity: LDN bodies don't carry the delivery's
-// HTTP-Signature headers, so instead of verifying signatures we VERIFY BY
-// DEREFERENCING — re-fetch the claimed object/actor from its origin (signed
-// GET, so authorized-fetch instances answer) and trust only what the origin
-// itself serves.
-//
-// Failure policy: a REJECTED item (verification says no) goes to the
-// dead-letter store and leaves the inbox; a FAILING item (exception —
-// network, remote 5xx) stays in the inbox for the next drain, and moves to
-// the dead-letter store after MAX_ITEM_ATTEMPTS. Nothing is silently
-// destroyed.
-//
-// Wake-up: WebSocketChannel2023 push on the inbox container (probe P4), plus
-// a poll every POLL_MS as fallback, plus a drain at startup.
-//
-// This file is the drain and the dispatcher. What it does with an activity
-// once it has one is in the modules beside it — activity.mjs (what an activity
-// is), channel.mjs (the push socket), verify.mjs (what to believe),
-// activities.mjs (one handler per type), group.mjs (FEP-1b12), notes.mjs (a
-// note on its way in) — each a set of functions taking the Intake as their
-// first argument, reached here through one-line delegations so that every
-// caller, and every test that overrides a method, sees one object.
-
-import * as podInbox from '../../pod/inbox.mjs';
-import { readCapped } from '../../shared/safefetch.mjs';
-import { trimActivity, sameIdentity, sameOrigin, httpUrl, reactionOf, MAX_EMOJIS, MAX_ITEM_BYTES, MAX_FORWARDS_PER_DRAIN } from './activity.mjs';
-import * as channel from './channel.mjs';
-import * as verify from './verify.mjs';
-import * as group from './group.mjs';
-import * as activities from './activities.mjs';
-import * as notes from './notes.mjs';
-import { readLenient } from '../as2.mjs';
-import { checkShapes, describeShapeFailure } from '../shapes/index.mjs';
-export { isContentType, trimActivity, sameIdentity, sameOrigin, sameSocketOrigin, httpUrl, authorOf } from './activity.mjs';
-
-const POLL_MS = 2 * 60_000;      // fallback cadence when there is no push
-// With a live socket the poll is pure redundancy: it exists for the case where
-// push is down, so it slows right down while push is up.
-const POLL_PUSH_OK_MS = 10 * 60_000;
-// A container that times out will time out again in two minutes, and each
-// attempt holds one of the pod's workers for the full timeout. Sweeping stops
-// for a while instead, doubling up to half an hour.
-const DRAIN_COOLDOWN_MIN_MS = 2 * 60_000;
-const DRAIN_COOLDOWN_MAX_MS = 30 * 60_000;
-// Our DELETEs take the same container write lock as the deliveries arriving
-// into it — a gap between them keeps a sweep from convoying against inbound.
-const DELETE_GAP_MS = 150;
-const CHAIN_GAP_MS = 5_000;      // pause between chained backlog sweeps
-// How many handled items ride on one commit before they are deleted. Small
-// enough that a crash re-does little, large enough that a flood of fast
-// rejections does not become a pod write per item.
-const DELETE_BATCH = 10;
-const ORPHAN_RECEIPTS_PER_SWEEP = 20;   // strays from before receipts were deleted with their items
-// Attempt counts live in pod state, not in memory: a restart used to hand every
-// poison item five fresh tries, and under a crash loop that is unbounded.
-const ATTEMPTS_DOC = 'intake-attempts.json';
-const ATTEMPTS_TTL_MS = 7 * 24 * 60 * 60_000;
-const MAX_ITEM_ATTEMPTS = 5;
-const MAX_ITEMS_PER_DRAIN = 50;
-
-export class Intake {
-  // `ownerPost(activity, { raw, slug })` is the client-to-server dispatcher,
-  // for an item the Gateway's outbox door took on the owner's behalf.
-  constructor({ config, urls, remote, store, deliverer, publisher, log = console.log, lease = null, archive = null, push = true, pollSeconds = null, ownerPost = null }) {
-    Object.assign(this, { config, urls, remote, store, deliverer, publisher, log, lease, archive, push, pollSeconds, ownerPost });
-    this.serial = Date.now();
-    this.stopped = false;
-    // (attempt counts are kept in pod state — see _bumpAttempt)
-    this.lastDrain = null;
-    this._forwardBudget = MAX_FORWARDS_PER_DRAIN;
-    this.lastDrainAtMs = 0;
-    this.reconnectTries = 0;
-    this.drainCooldownUntil = 0;
-    this.drainFailures = 0;
-    this.wsState = 'never-connected';
-  }
-
-  // Draining is a destructive read — an item is gone from the pod once we
-  // DELETE it — so the result of handling it must be on disk first.
-  //
-  // This used to be skipped whenever the state and the inbox shared an origin,
-  // on the reasoning that a pod we cannot write to is a pod we cannot list
-  // either, so the drain never starts. That covers the pod being unreachable
-  // and nothing else: it does not cover a crash inside the 300ms debounce
-  // window, and it does not cover a pod that refuses a write while still
-  // serving reads and deletes — a quota, a 507, a 403 on one document. In
-  // either case every item drained since the last successful write is gone,
-  // and what goes is the mentions, replies, join requests and dead-letter
-  // records that nothing else can rebuild.
-  async _persisted() {
-    return this.store.commit();
-  }
-
-  _backOff(why) {
-    this.drainFailures++;
-    const capped = Math.min(DRAIN_COOLDOWN_MIN_MS * 2 ** (this.drainFailures - 1), DRAIN_COOLDOWN_MAX_MS);
-    this.drainCooldownUntil = Date.now() + Math.round(capped * (0.85 + Math.random() * 0.3));
-    this.log(`${why} — next sweep in ${Math.round(capped / 1000)}s`);
-  }
-
-  // Sweep cadence: a configured interval wins, otherwise a live push channel —
-  // a notification socket, or the store's own change events in-process — is
-  // what makes the fallback poll a slow one.
-  _pollMs() {
-    if (this.pollSeconds) return this.pollSeconds * 1000;
-    return this.wsState === 'open' || this.wsState === 'in-process' ? POLL_PUSH_OK_MS : POLL_MS;
-  }
-
-  async start() {
-    this.stopped = false;                     // restartable across demote/takeover cycles
-    await this.drain().catch(e => this.log(`drain: ${e.message}`));
-    const tick = () => {
-      this.pollTimer = setTimeout(() => {
-        this.drain().catch(e => this.log(`drain: ${e.message}`)).finally(() => { if (!this.stopped) tick(); });
-      }, Math.round(this._pollMs() * (0.85 + Math.random() * 0.3)));
-      this.pollTimer.unref?.();
-    };
-    tick();
-    // Embedded in the pod server, a notification socket back to that same
-    // server buys nothing — the store's own change events wake the drain.
-    if (this.push) this.subscribe().catch(e => this.log(`subscribe: ${e.message}`));
-    else this.wsState = 'in-process';
-  }
-
-  stop() { this.stopped = true; clearTimeout(this.pollTimer); clearTimeout(this.resubTimer); this.ws?.close(); }
-
-  // Attempt bookkeeping, persisted. Written only when an item fails, so a
-  // healthy inbox never touches this document.
-  _bumpAttempt(url, message) {
-    const all = this.store.read(ATTEMPTS_DOC, {});
-    const rec = all[url] || { n: 0 };
-    rec.n += 1;
-    rec.at = new Date().toISOString();
-    rec.last = String(message || '').slice(0, 200);
-    all[url] = rec;
-    this.store.write(ATTEMPTS_DOC, all);
-    return rec.n;
-  }
-
-  _clearAttempt(url) {
-    const all = this.store.read(ATTEMPTS_DOC, {});
-    if (!all[url]) return;
-    delete all[url];
-    this.store.write(ATTEMPTS_DOC, all);
-  }
-
-  // Items deleted long ago would otherwise accumulate here forever.
-  _pruneAttempts() {
-    const all = this.store.read(ATTEMPTS_DOC, {});
-    const cutoff = Date.now() - ATTEMPTS_TTL_MS;
-    let dropped = 0;
-    for (const [url, rec] of Object.entries(all)) {
-      if (!rec?.at || Date.parse(rec.at) < cutoff) { delete all[url]; dropped++; }
-    }
-    if (dropped) { this.store.write(ATTEMPTS_DOC, all); this.log(`pruned ${dropped} stale inbox attempt record(s)`); }
-  }
-
-  // --- drain + dispatch ---
-  // Serialized: push events, polls, and manual /drain calls can fire
-  // concurrently, and overlapping sweeps double-process items (observed as
-  // duplicate Accepts/timeline writes). One sweep at a time; callers that
-  // arrive mid-sweep get one follow-up sweep.
-  async drain() {
-    if (this._draining) { this._drainAgain = true; return this._draining; }
-    // Held for the whole sweep, released however it ends. The debounce cannot
-    // coalesce a drain — every handler awaits somebody else's server first — so
-    // the writes are left to the commit boundaries the drain already has. See
-    // PodStore.hold.
-    // Optional: this is a throughput hint, not part of the commit-before-delete
-    // invariant — commit() flushes whatever is pending either way — so a store
-    // that does not implement it behaves exactly as before.
-    this._inSweep = true;
-    // Fresh per sweep: the cap is on how much this drain may amplify, not a
-    // lifetime total (see _maybeForward).
-    this._forwardBudget = MAX_FORWARDS_PER_DRAIN;
-    this.store.hold?.();
-    this._draining = this._drainOnce().finally(async () => {
-      this._inSweep = false;
-      await this._publishPending();
-      this.store.release?.();
-      this._draining = null;
-      if (this._drainAgain) {
-        this._drainAgain = false;
-        // Paced, not immediate: chained sweeps put a ceiling on work per unit
-        // time, so a delivery flood cannot run the drain back-to-back.
-        const t = setTimeout(() => this.drain().catch(e => this.log(`drain: ${e.message}`)), CHAIN_GAP_MS);
-        t.unref?.();
-      }
-    });
-    return this._draining;
-  }
-
-  // Discard the content waiting in the inbox from before `before`, on the
-  // owner's say-so — the admin page asks, this does it. NOT a blind sweep:
-  // every item is read, because the type is the only thing that decides its
-  // fate and size does not predict it. A Follow, Undo, Accept or Delete is
-  // APPLIED whatever it weighs, so the follow graph stays correct and a post
-  // its author retracted still goes; only a Create is dropped. Judging by size
-  // instead saved one request per item and lost any control activity that
-  // happened to be large, silently and permanently.
-  //
-  // An item past the drain's own byte cap is deleted unread: it could not be
-  // handled if it were read, so there is nothing to lose by not reading it.
-  //
-  // `keepConcerning` narrows the discard to noise: every item is passed to
-  // handle(), which ingests a Create only when concernsUs passes — addressed to
-  // us, a mention, a reply to ours, or from someone we follow — and drops the
-  // rest.
-  async prune({ before, keepConcerning = false } = {}) {
-    const cutoff = Date.parse(before);
-    if (!Number.isFinite(cutoff)) throw new Error(`"${before}" is not a date`);
-    const all = await podInbox.list(this.remote, this.urls);
-    const older = all.filter(e => !e.url.endsWith('.keep')
-      && e.modified && Date.parse(e.modified) < cutoff);
-    const out = { considered: older.length, applied: 0, dropped: 0, discarded: 0, failed: 0 };
-
-    for (const item of older) {
-      try {
-        if (item.size > MAX_ITEM_BYTES) {
-          await podInbox.dropHandledItem(this.remote, item.url);   // unreadable by the drain either way
-          out.discarded++;
-        } else {
-          // Same rule as the drain: a read we could not make is not a Create to
-          // be dropped. readItem throws on anything but 404, so it counts as
-          // failed and stays for the next pass.
-          const got = await podInbox.readItem(this.remote, item.url, { maxBytes: MAX_ITEM_BYTES, readCapped });
-          const read = got.raw === null ? null : await readLenient(got.raw);
-          if (read?.degraded) this.log(`inbox item ${item.url} grounded to read: ${read.degraded}`);
-          const activity = read?.view ?? read?.doc ?? null;
-          // A Create is the content the owner just asked to be rid of. Anything
-          // else changes state and is applied exactly as a drain would.
-          if (keepConcerning) {
-            const rejection = activity ? await this.handle(activity) : 'unparsable JSON';
-            if (rejection) out.dropped++; else out.applied++;
-          } else if (activity && activity.type !== 'Create') {
-            await this.handle(activity);
-            out.applied++;
-          } else {
-            out.dropped++;
-          }
-          if (!await this._persisted()) {
-            this.log(`state not written — stopping the prune with ${older.length - out.applied - out.dropped - out.discarded} left`);
-            break;
-          }
-          await podInbox.dropHandledItem(this.remote, item.url);
-        }
-        this._clearAttempt(item.url);
-        await new Promise(r => setTimeout(r, DELETE_GAP_MS));
-      } catch (e) {
-        out.failed++;
-        this.log(`prune ${item.url}: ${e.message}`);
-      }
-    }
-    this.log(`pruned before ${before}: applied ${out.applied}, dropped ${out.dropped} `
-      + `small Create(s), discarded ${out.discarded} unread${out.failed ? `, ${out.failed} failed` : ''}`);
-    await this.store.flush();
-    // Adjust the measurement in place rather than kicking a drain to re-take
-    // it: an un-awaited drain would still be running when this returns, which
-    // races whoever called us. The poll picks the rest up soon enough.
-    const removed = out.applied + out.dropped + out.discarded;
-    if (this.inboxStats && removed) {
-      this.inboxStats = { ...this.inboxStats, count: Math.max(0, this.inboxStats.count - removed) };
-    }
-    return out;
-  }
-
-  // The sender's original bytes, kept after the activity was verified and
-  // applied and before the pod DELETE erases the only other copy. The filename
-  // is the content's own hash, so a re-delivered activity lands on the same
-  // file instead of duplicating. Best-effort history: a failed write logs and
-  // the drain goes on — mail must never stall on its own receipt. This is the
-  // one category of account data that lives only in the private half; the pod
-  // cannot rebuild it because the pod never kept it.
-  //
-  // The record is JSON-LD: a cnt:ContentAsText whose cnt:chars are the raw
-  // bytes, stamped prov:generatedAtTime / prov:wasDerivedFrom / as:actor —
-  // plain JSON to everything here, a graph to any RDF reader.
-  async _archive(sourceUrl, raw, activity) {
-    try {
-      if (!this.archive || this.store.getConfig()?.archiveInbox === false) return;
-      const { createHash } = await import('node:crypto');
-      const hash = createHash('sha256').update(raw).digest('hex').slice(0, 16);
-      const receivedAt = new Date().toISOString();
-      const rec = {
-        '@context': {
-          prov: 'http://www.w3.org/ns/prov#',
-          cnt: 'http://www.w3.org/2011/content#',
-          as: 'https://www.w3.org/ns/activitystreams#',
-          xsd: 'http://www.w3.org/2001/XMLSchema#',
-          receivedAt: { '@id': 'prov:generatedAtTime', '@type': 'xsd:dateTime' },
-          source: { '@id': 'prov:wasDerivedFrom', '@type': '@id' },
-          actor: { '@id': 'as:actor', '@type': '@id' },
-          raw: 'cnt:chars',
-        },
-        '@id': '',
-        '@type': 'cnt:ContentAsText',
-        receivedAt,
-        actor: typeof activity?.actor === 'string' ? activity.actor : activity?.actor?.id || null,
-        source: sourceUrl,
-        raw,
-      };
-      const w = await this.archive.write(`${receivedAt.slice(0, 7)}/${hash}.json`,
-        JSON.stringify(rec, null, 2), 'application/ld+json');
-      if (!w.ok) this.log(`inbox archive: ${w.why || 'write failed'}`);
-    } catch (e) {
-      this.log(`inbox archive: ${e.message}`);
-    }
-  }
-
-  async _drainOnce() {
-    const cooling = this.drainCooldownUntil - Date.now();
-    if (cooling > 0) {
-      this.log(`inbox sweep skipped — backing off for another ${Math.ceil(cooling / 1000)}s`);
-      return;
-    }
-    // Draining DELETES from the pod, so it must not run on a lease that has
-    // quietly expired. renewOnce notices at its own cadence — up to ~117s — and
-    // after the TTL another agent is entitled to start draining the same inbox.
-    if (this.lease && !this.lease.stillHeld()) {
-      this.log('lease is no longer held — not draining');
-      return;
-    }
-    this.lastDrain = new Date().toISOString();
-    this.lastDrainAtMs = Date.now();
-    // What a drain leaves behind may need acting on: a forum's queue of asks,
-    // which is filled here and emptied by whoever can vouch for them.
-    if (this.afterDrain) setTimeout(() => this.afterDrain(), 0);
-    this._pruneAttempts();
-    let all;
-    try {
-      all = await podInbox.list(this.remote, this.urls);
-      this.drainFailures = 0;
-    } catch (e) {
-      this._backOff(`inbox unreadable (${e.message})`);
-      return;
-    }
-    // What is waiting, measured from the listing we already fetched: no extra
-    // request, and it is what /status reports and what the admin page prompts
-    // on. The listing arrives oldest-first (lib/remote.mjs).
-    const real = all.filter(e => !e.url.endsWith('.keep'));
-    this.inboxStats = {
-      count: real.length,
-      bytes: real.reduce((n, e) => n + e.size, 0),
-      oldest: real[0]?.modified || null,
-      newest: real[real.length - 1]?.modified || null,
-      at: new Date().toISOString(),
-    };
-    // The inbox is public-Append: a flood must not turn one sweep into an
-    // unbounded run. But stopping there is why a backlog never cleared — 50
-    // items every two minutes does not converge on an agent that is only
-    // running while a laptop is open. So a sweep that made progress and left
-    // work behind goes straight round again.
-    const items = all.slice(0, MAX_ITEMS_PER_DRAIN);
-    if (all.length > items.length) this.log(`inbox has ${all.length} items — processing ${items.length} this sweep`);
-    let handled = 0;
-    // Deletes are batched behind ONE commit rather than a commit per item.
-    // Per-item, the 300ms debounce that coalesces a sweep's writes never gets
-    // to do its job: on a flood of fast rejections that is fifty writes of
-    // deadletter.json where one would do, and a flood is exactly when the pod
-    // should be asked for less rather than more.
-    const pending = [];
-    const withReceipt = new Set();   // items the listing showed a receipt beside
-    const flush = async () => {
-      if (!pending.length) return true;
-      // Written down before any of them leaves the mailbox. A failure here
-      // leaves them where they are: the next sweep sees them again, and a
-      // re-delivered activity is handled idempotently.
-      if (!await this._persisted()) {
-        this._backOff(`state not written — ${pending.length} item(s) left in the inbox`);
-        pending.length = 0;
-        return false;
-      }
-      for (const url of pending.splice(0)) {
-        if (!await podInbox.dropHandledItem(this.remote, url)) {
-          // Still in the mailbox. Handling is idempotent so seeing it again is
-          // harmless, but counting it would clear the attempt record and report
-          // progress that did not happen.
-          this.log(`inbox item ${url} was handled but NOT removed — it will be seen again`);
-          continue;
-        }
-        this._clearAttempt(url);
-        handled++;
-        // Its receipt goes with it. Left beside a deleted item, a receipt
-        // was one stray document per delivery, forever.
-        if (withReceipt.has(url)) await podInbox.dropReceiptBeside(this.remote, url);
-        await new Promise(r => setTimeout(r, DELETE_GAP_MS));
-      }
-      return true;
-    };
-
-    for (const { url, size, receipt: hasReceipt } of items) {
-      if (url.endsWith('.keep')) continue;
-      if (hasReceipt) withReceipt.add(url);
-      // The listing already carries every child's size, so this costs nothing
-      // to ask. An activity is a few kB; anything of this order is not one, and
-      // reading it with an unbounded res.text() buffers whatever a stranger
-      // chose to Append into memory.
-      // A cheap pre-filter only: listContainer coerces a missing posix:size to
-      // 0, so a pod that does not publish sizes would wave everything through.
-      // The real bound is readCapped on the body below.
-      if (size > MAX_ITEM_BYTES) {
-        this.store.addDeadLetter({ inboxUrl: url, reason: `oversized (${size} bytes)`, activity: null });
-        pending.push(url);
-        continue;
-      }
-      let activity = null;
-      try {
-        const got = await podInbox.readItem(this.remote, url, { maxBytes: MAX_ITEM_BYTES, readCapped });
-        // readItem carries the rule that matters here: a pod that would not
-        // GIVE us the item has told us nothing about it, so anything but a 404
-        // throws rather than reading as an empty body. Reading a 500 as empty
-        // made it "unparsable JSON" — a REJECTION, dead-lettered with both
-        // `activity` and `raw` null and then DELETEd, destroying a delivery on
-        // a transient fault with no record of what it had been.
-        const raw = got.raw;
-        // Read as JSON-LD, so a document whose terms are aliased means what it
-        // says. A document we cannot read that way is read the way it always
-        // was rather than lost, and the reason is logged.
-        const read = raw ? await readLenient(raw) : null;
-        if (read?.degraded) this.log(`inbox item ${url} grounded to read: ${read.degraded}`);
-        activity = read?.view ?? read?.doc ?? null;
-        // What the shapes make of it. This decides NOTHING — the activity is
-        // handled either way. It is written down so that which shapes fire on
-        // real traffic is a question with an answer, rather than a guess made
-        // in advance about implementations we have not met.
-        if (read?.graph) {
-          const failure = await checkShapes(read.graph);
-          if (failure) {
-            const said = describeShapeFailure(failure);
-            this.log(`inbox item ${url} does not fit its shape: ${said}`);
-            this.store.addDeadLetter({
-              inboxUrl: url, reason: `shape: ${said}`, shapeOnly: true, activity: trimActivity(activity),
-            });
-          }
-        }
-        // A gateway that verified this delivery left a receipt beside it. Read
-        // it only when a gateway is configured (no config → no fetch, so an
-        // install with no gateway pays nothing) and the listing showed one
-        // beside this item (`false` is a definite no; a listing that does not
-        // say leaves it to the read); a missing or HMAC-invalid receipt reads
-        // as null, which is exactly today's unverified behavior.
-        const receipt = activity && hasReceipt !== false ? await this._readReceipt(url) : null;
-        if (activity && this.gatewaySecret()) this._bumpGatewayStat(!!receipt?.verified);
-        // The owner's own post, taken at the outbox door: not mail to read
-        // but a write to make. Never archived or forwarded as if received.
-        const owned = activity && this.isOwnerPost(receipt);
-        const rejection = !activity ? 'unparsable JSON'
-          : owned ? await this.ownerPostFrom(activity, raw, receipt)
-            : await this.handle(activity, receipt);
-        if (!rejection && raw && !owned) await this._archive(url, raw, activity);
-        if (!rejection && !owned) await this._maybeForward(activity);    // §7.1.2, only what we accepted
-        if (rejection) {
-          this.store.addDeadLetter({
-            inboxUrl: url, reason: rejection, activity: trimActivity(activity),
-            ...(activity ? {} : { raw: raw?.slice(0, 2000) ?? null }),
-          });
-          this.log(`rejected (${rejection}) — dead-lettered: ${url}`);
-        }
-        pending.push(url);
-      } catch (e) {
-        const n = this._bumpAttempt(url, e.message);
-        this.log(`inbox item ${url} attempt ${n}/${MAX_ITEM_ATTEMPTS}: ${e.message}`);
-        if (n >= MAX_ITEM_ATTEMPTS) {
-          this.store.addDeadLetter({ inboxUrl: url, reason: `failed ${n}x: ${e.message}`, activity: trimActivity(activity) });
-          // The dead letter IS the record of this item — deleting before it is
-          // written down would lose the only evidence it ever arrived, so it
-          // goes through the same commit-then-delete batch as everything else.
-          pending.push(url);
-        }
-      }
-      if (pending.length >= DELETE_BATCH && !await flush()) return;
-    }
-    if (!await this._finishSweep(flush)) return;
-    // Receipts earlier drains left behind, a few per sweep until none remain.
-    for (const stray of podInbox.orphanReceipts(this.remote, this.urls).slice(0, ORPHAN_RECEIPTS_PER_SWEEP)) {
-      if (!await podInbox.dropStrayReceipt(this.remote, stray)) break;
-      await new Promise(r => setTimeout(r, DELETE_GAP_MS));
-    }
-    // Made progress and there is more waiting: go straight round rather than
-    // sleeping. Gated on progress so a sweep that achieved nothing — a
-    // cooldown, an unwritable store, poison at the head — cannot spin.
-    if (handled > 0 && all.length > items.length && !this.stopped) this._drainAgain = true;
-  }
-
-  // The end of a sweep: publish whatever the follow graph did ONCE, then flush.
-  //
-  // publishCollections used to run per handled item — every Follow, Undo,
-  // Accept, Reject, admit and eject — and each one is a full GET of the pod's
-  // followers collection plus a PUT of it. Fifty follows in a sweep were a
-  // hundred requests where two would do, and the answer they arrive at is the
-  // same either way, because it is built from contacts.json in memory.
-  async _finishSweep(flush) {
-    await this._publishPending();
-    return flush();
-  }
-
-  // Idempotent: it clears what it takes, so the drain's own exit path calling
-  // it again after a sweep that bailed early — an unwritable store, a delete
-  // that failed — is a no-op in the ordinary case and the difference between
-  // "published" and "waiting for a sweep that may never come" in the other.
-  async _publishPending() {
-    const want = this._republish;
-    this._republish = null;
-    if (!want) return;
-    try { await this.publisher.publishCollections(want); }
-    catch (e) { this.log(`publishing collections: ${e.message}`); }
-  }
-
-  // Ask for a collection to be republished at the end of this sweep. Outside a
-  // sweep there is no boundary to wait for, so it happens now.
-  async republish(which) {
-    if (!this._inSweep) return this.publisher.publishCollections(which);
-    this._republish = { ...(this._republish || {}), ...which };
-  }
-
-  sameOrigin(a, b) { return sameOrigin(a, b); }
-  // Overridable in tests the same way sameOrigin is.
-  sameIdentity(a, b) { return sameIdentity(a, b); }
-
-  async handle(activity, receipt = null) {   // eslint-disable-line no-unused-vars
-    const actor = typeof activity.actor === 'string' ? activity.actor : activity.actor?.id;
-    if (!actor) return 'no actor';
-    // An actor is a URL that can be dereferenced. Most arms here go on to fetch
-    // it, and safefetch refuses a bad scheme there — but Like and Announce on
-    // one of our own notes record a notification without dereferencing
-    // anything, so `javascript:` and `data:` reached the client as an account
-    // url. The store already guards avatars this way (safeUrl); actors were
-    // simply never put through it.
-    if (!httpUrl(actor)) return `actor is not an http(s) URL (${actor})`;
-    if (this.store.isBlocked(actor)) return `blocked sender (${actor})`;
-
-    // Whether the door vouched for this sender — read by the moderation queue
-    // just below as well as by the arms further down, so it is settled here,
-    // before its first use.
-    const trusted = this.receiptVouchesFor(receipt, actor)
-      && this.store.getConfig()?.gateway?.mode === 'trust';
-
-    // FEP-1b12 moderation from a LISTED moderator. A delivery proves nothing
-    // about its sender, which is why these are QUEUED for the operator rather
-    // than run on arrival — the queue is where a claimed moderator's word
-    // waits for the one person who can vouch for it. Everything else about
-    // the activity falls through to the ordinary arms.
-    if (this.config.kind === 'group'
-      && (this.config.moderators || []).includes(actor)
-      && this.isModerationAsk(activity)) {
-      return this.queueModeration(activity, actor, { trusted });
-    }
-
-    // `trusted` was settled above, before the moderation queue reads it. Why it
-    // is not simply `receipt.verified`: that says the door checked a signature
-    // and the signature was good; it does NOT say whose. The door reports the
-    // signing key's owner separately, in `receipt.actor`, and nothing here used
-    // to read it — so ANY valid fediverse signing key, over an activity whose
-    // `actor` field named someone else entirely, arrived as trusted. In trust
-    // mode that is one delivery to evict any of your followers, or to have a
-    // Follow naming a third party auto-accepted. See receiptVouchesFor, which
-    // also holds the keyId to the actor's origin: a key document is fetched
-    // from wherever its id points, so one hosted elsewhere that merely CLAIMS
-    // `owner: <you>` would otherwise bind.
-
-    switch (activity.type) {
-      case 'Follow': return this.onFollow(activity, actor, { trusted });
-      case 'Undo': return this.onUndo(activity, actor, { trusted });
-      case 'Create': return this.onCreate(activity, actor, { trusted });
-      case 'Accept': return this.onAccept(activity, actor, { trusted });
-      case 'QuoteRequest': return this.onQuoteRequest(activity, actor, { trusted });
-      case 'Like': case 'Announce': case 'EmojiReact': {
-        // FEP-1b12: a group Announces the member's whole Create, not the note.
-        // Without unwrapping we try to ingest a Create as if it were a Note and
-        // dead-letter every post a group ever carries — including our own.
-        const wrapped = activity.object;
-        // FEP-1b12: a group announces its moderation too. The one act a
-        // follower can honor without trusting anyone new is a Delete of a
-        // post that same group carried to us — the carrier unsaying its carry.
-        if (activity.type === 'Announce' && wrapped && typeof wrapped === 'object'
-          && wrapped.type === 'Delete') {
-          return this.onAnnouncedDelete(actor, wrapped);
-        }
-        const inner = (wrapped && typeof wrapped === 'object'
-          && (wrapped.type === 'Create' || wrapped.type === 'Update')) ? wrapped.object : wrapped;
-        const objectId = typeof inner === 'string' ? inner : inner?.id;
-        this.log(`${activity.type} from ${actor} on ${objectId}`);
-        // An emoji on one of our posts. Recorded the way a Like is — on the
-        // sender's word, nothing to dereference — with the emoji itself, and
-        // a custom emoji's image added to the post's own list so a client
-        // that draws reactions from there finds it. Anything else an
-        // EmojiReact names is not ours to notice.
-        const reaction = activity.type !== 'Announce' ? reactionOf(activity) : null;
-        if (reaction) {
-          if (!objectId || !objectId.startsWith(this.urls.notes)) return;
-          this.store.addNotification({
-            type: 'reaction', actor, noteId: objectId, emoji: reaction.emoji,
-            ...(reaction.url ? { url: reaction.url } : {}),
-            ...(this.known(actor) ? {} : { unverified: true }),
-          });
-          if (reaction.url) {
-            const s = this.store.getStatuses().find(x => x.noteId === objectId);
-            const shortcode = reaction.emoji.replace(/^:|:$/g, '');
-            if (s && !(s.emojis || []).some(e => e.shortcode === shortcode) && (s.emojis || []).length < MAX_EMOJIS) {
-              this.store.updateStatus(objectId, { emojis: [...(s.emojis || []), { shortcode, url: reaction.url }] });
-            }
-          }
-          return;
-        }
-        if (activity.type === 'EmojiReact') return;
-        if (objectId && objectId.startsWith(this.urls.notes)) {
-          // Nothing vouches for this actor: a Like carries no signature and,
-          // unlike a Create, has no object at the sender's origin to re-read.
-          // `known()` is answered from local state and costs nothing — a
-          // stranger's favourite is still recorded, it is just the first thing
-          // the cap evicts, so a flood cannot push out real history.
-          this.store.addNotification({
-            type: activity.type === 'Like' ? 'favourite' : 'reblog', actor, noteId: objectId,
-            ...(this.known(actor) ? {} : { unverified: true }),
-          });
-          return;
-        }
-        if (activity.type === 'Announce') return this.onAnnounce(activity, actor, objectId);
-        return;
-      }
-      case 'Delete': return this.onDelete(activity, actor);
-      case 'Update': return this.onUpdate(activity, actor);
-      case 'Reject': return this.onReject(activity, actor, { trusted });
-      case 'Move': return this.onMove(activity, actor);
-      case 'Add': case 'Remove': return this.onAddRemove(activity, actor);
-      case 'Block': return this.onBlock(activity, actor, { trusted });
-      case 'Flag': if (this.onReport) return this.onReport(activity, actor, { trusted }); return;
-      default: this.log(`ignored ${activity.type} from ${actor}`);
-    }
-  }
-
-  // channel.mjs
-  _reconnectDelay(...a) { return channel.reconnectDelay(this, ...a); }
-  subscribe(...a) { return channel.subscribe(this, ...a); }
-  _storageDescriptionUrl(...a) { return channel.storageDescriptionUrl(this, ...a); }
-  _subscribeOnce(...a) { return channel.subscribeOnce(this, ...a); }
-  _openSocket(...a) { return channel.openSocket(this, ...a); }
-
-  // verify.mjs
-  fetchAP(...a) { return verify.fetchAP(this, ...a); }
-  known(...a) { return verify.known(this, ...a); }
-  gatewaySecret(...a) { return verify.gatewaySecret(this, ...a); }
-  _bumpGatewayStat(...a) { return verify.bumpGatewayStat(this, ...a); }
-  _readReceipt(...a) { return verify.readReceipt(this, ...a); }
-
-  // A receipt the door stamped `c2s` for THIS actor, and only a receipt whose
-  // HMAC verified (readReceipt returns nothing else). A stranger appending an
-  // item that claims to be ours has no such receipt and is read as mail.
-  isOwnerPost(receipt) {
-    return !!(this.ownerPost && receipt?.verified && receipt.method === 'c2s' && receipt.actor === this.urls.actor);
-  }
-
-  // Publish what the owner posted at the door. The bytes as the client wrote
-  // them go to the dispatcher (an object stored as sent must be the client's
-  // document, not our reading of it); the graph is what it decides from.
-  // Returns null when published, else the reason it was not — a dead letter.
-  async ownerPostFrom(activity, raw, receipt) {
-    // The receipt names the body it vouches for; a body it does not name is
-    // not the owner's. A body already handled — a replayed request, or an item
-    // the pod would not let us delete — is not published twice.
-    const hash = raw ? await sha256Hex(raw) : null;
-    if (receipt.hash && receipt.hash !== hash) return 'owner post refused: the body is not the one its receipt names';
-    const seen = this.store.read('c2s-seen.json', []);
-    if (hash && seen.includes(hash)) {
-      this.log('owner post already handled — not published again');
-      return null;
-    }
-    let asSent = null;
-    try { asSent = raw ? JSON.parse(raw) : null; } catch { asSent = null; }
-    const r = await this.ownerPost(activity, { raw: asSent, slug: receipt.slug || null,
-      // What the door told the client this will be called, when it said.
-      ...(receipt.serial ? { serial: receipt.serial } : {}), ...(receipt.at ? { at: receipt.at } : {}) });
-    // Handled, one way or the other: a second sight of it changes nothing. A
-    // throw above is not handled, and is tried again.
-    if (hash) this.store.write('c2s-seen.json', [hash, ...this.store.read('c2s-seen.json', [])].slice(0, C2S_SEEN_MAX));
-    if (!r || r.status >= 300) {
-      const why = r?.body?.error || 'no reason was given';
-      // The door already answered the app "created"; the owner is the one
-      // left to tell.
-      await this.publisher.noteToSelf?.(`An app asked your account to publish ${article(activity.type)}, `
-        + `and your account refused it: ${why}. Nothing was sent.`)
-        .catch(e => this.log(`could not tell the owner their post was refused: ${e.message}`));
-      return `owner post refused (${r?.status || '?'}): ${why}`;
-    }
-    this.log(`owner post from the outbox door published: ${r.body?.object || r.body?.id || activity.type}`);
-    return null;
-  }
-  receiptVouchesFor(...a) { return verify.receiptVouchesFor(this, ...a); }
-  isGone(...a) { return verify.isGone(this, ...a); }
-
-  // group.mjs
-  isModerationAsk(...a) { return group.isModerationAsk(this, ...a); }
-  queueModeration(...a) { return group.queueModeration(this, ...a); }
-  amplify(...a) { return group.amplify(this, ...a); }
-  isCoMember(...a) { return group.isCoMember(this, ...a); }
-  collectionMembers(...a) { return group.collectionMembers(this, ...a); }
-  announceTargets(...a) { return group.announceTargets(this, ...a); }
-
-  // activities.mjs
-  onAddRemove(...a) { return activities.onAddRemove(this, ...a); }
-  onFollow(...a) { return activities.onFollow(this, ...a); }
-  onUndo(...a) { return activities.onUndo(this, ...a); }
-  onBlock(...a) { return activities.onBlock(this, ...a); }
-  onCreate(...a) { return activities.onCreate(this, ...a); }
-  onAnnouncedDelete(...a) { return activities.onAnnouncedDelete(this, ...a); }
-  onAnnounce(...a) { return activities.onAnnounce(this, ...a); }
-  onQuoteRequest(...a) { return activities.onQuoteRequest(this, ...a); }
-  quoteStateOf(...a) { return activities.quoteStateOf(this, ...a); }
-  onDelete(...a) { return activities.onDelete(this, ...a); }
-  onUpdate(...a) { return activities.onUpdate(this, ...a); }
-  onReject(...a) { return activities.onReject(this, ...a); }
-  onMove(...a) { return activities.onMove(this, ...a); }
-  onAccept(...a) { return activities.onAccept(this, ...a); }
-
-  // notes.mjs
-  concernsUs(...a) { return notes.concernsUs(this, ...a); }
-  _maybeForward(...a) { return notes.maybeForward(this, ...a); }
-  _referencesOurObject(...a) { return notes.referencesOurObject(this, ...a); }
-  ingestNote(...a) { return notes.ingestNote(this, ...a); }
-  forget(...a) { return notes.forget(this, ...a); }
-  retract(...a) { return notes.retract(this, ...a); }
-  addReply(...a) { return notes.addReply(this, ...a); }
-}
-
-// "a Like", "an Update": the kind of activity, as a sentence says it.
-const article = (type) => `${/^[AEIOU]/u.test(String(type)) ? 'an' : 'a'} ${type || 'post'}`;
-
-// Bodies the outbox door handed over that were handled, newest first.
-const C2S_SEEN_MAX = 500;
-const sha256Hex = async (text) => [...new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256',
-  new TextEncoder().encode(text)))].map(b => b.toString(16).padStart(2, '0')).join('');