@geekity/cms 0.3.0 → 0.4.0

package/dist/federation/records.d.ts

@@ -0,0 +1,223 @@
+import type { AdminStore, Follower, InboxActivity, NewFollower, NewInboxActivity } from '../admin/store.ts';
+/**
+ * The two things an ActivityPub site cannot regenerate, as files it publishes.
+ *
+ * decision-9 makes the filesystem the source of truth for everything durable,
+ * and for federation that is the followers and the log of what the inbox was
+ * told. Both live under `content/_data/federation/`, which puts them in git
+ * beside the posts, hands them to an Eleventy build of the same directory as
+ * `federation.followers` and `federation.inbox`, and leaves SQLite holding
+ * nothing but an index of them — one that is rebuilt from these files on every
+ * boot and may be deleted at rest.
+ *
+ * Two rules make that safe, and both live here so no handler has to remember
+ * them:
+ *
+ * - **The file first, the index inside the same step.** Every writer takes
+ *   {@link withFileLock} over the file it is about to change and writes the
+ *   index before it lets go, so a follow and an unfollow arriving together
+ *   cannot leave the index saying something the file does not. SQLite's
+ *   transactions used to cover this and cover nothing here any more.
+ * - **The index is derived, never told.** A row is built from a line of the
+ *   log by {@link inboxRowFrom} whether it is being written for the first time
+ *   or rebuilt at boot, so a rebuilt index cannot differ from the live one.
+ */
+/** Where the federation files live, relative to the content directory. */
+export declare const FEDERATION_DATA_DIRECTORY = "_data/federation";
+/** What a user's followers file is called, inside their own directory. */
+export declare const FOLLOWERS_FILE = "followers.json";
+/** The directory of monthly inbox logs, relative to the content directory. */
+export declare const INBOX_DIRECTORY = "_data/federation/inbox";
+/**
+ * The directory one user's federation files live in, relative to the content
+ * directory: `_data/federation/{username}`.
+ *
+ * decision-14 makes every user an actor, and an actor's followers are its own
+ * — an actor that was followed and forgotten simply stops hearing from the
+ * site — so the one file doc-4 had becomes one per user. The name is the
+ * username verbatim, because it is also the name in the actor's id and in the
+ * key files, and a directory nobody can match to a person would be worse than
+ * one with an unusual name in it.
+ *
+ * `inbox` is not a username: it is where the shared log lives, and
+ * `web/authors.ts` reserves the path for exactly that reason. A name that
+ * could climb out of the directory is refused rather than sanitised, because
+ * sanitising two different usernames into one directory would merge two
+ * people's followers.
+ */
+export declare function userDirectory(username: string): string;
+/** The absolute path of one user's `content/_data/federation/{username}/followers.json`. */
+export declare function followersFile(contentDir: string, username: string): string;
+/**
+ * Every user the content directory holds federation files for, sorted.
+ *
+ * Read from the directory rather than from `data/users.json`, because
+ * decision-9 makes the files the truth: a rebuilt database has to put back
+ * exactly what is on disk, including the followers of a user whose account was
+ * removed — deleting the account is not the same act as unfollowing everybody
+ * on their behalf, and only one of the two can be taken back.
+ */
+export declare function federatedUsernames(contentDir: string): string[];
+/** The absolute path of one site's `content/_data/federation/inbox`. */
+export declare function inboxDirectory(contentDir: string): string;
+/**
+ * The month an instant falls in, `yyyy-mm`, in UTC.
+ *
+ * UTC rather than the site's zone because the log is a record of what a server
+ * was told, not of a site's day: the name of a file that has been written must
+ * not move when somebody changes the `timezone` setting.
+ */
+export declare function inboxMonth(instant: string): string;
+/** The log file an activity that arrived at this instant belongs in. */
+export declare function inboxFile(contentDir: string, instant: string): string;
+/** What every writer here needs: the file it owns, and the index over it. */
+export interface FederationRecords {
+    /** The index the files are rebuilt into. */
+    readonly admin: AdminStore;
+    /** The content directory the files live under. */
+    readonly contentDir: string;
+}
+/**
+ * One user's followers, as their `followers.json` says them, oldest follow
+ * first.
+ *
+ * A missing file is an empty list, which is what a site nobody has followed
+ * yet has. Anything else that is not a list of deliverable followers throws,
+ * naming the file: this is read at boot to build the index, and a damaged file
+ * read as "no followers" would quietly unfollow everybody — the one thing
+ * doc-4 says an ActivityPub site can never take back.
+ */
+export declare function readFollowers(contentDir: string, username: string): Follower[];
+/**
+ * Record a follow of one user: append the follower to that user's file, or
+ * refresh the profile of one already there, and put the same thing in the
+ * index.
+ *
+ * Following twice is not two followers. The file is keyed by actor id exactly
+ * as the index is, and an actor already in it keeps its place and its original
+ * follow time — a repeated or redelivered `Follow` refreshes the name and the
+ * avatar and nothing else.
+ */
+export declare function addFollower(records: FederationRecords, username: string, follower: Omit<NewFollower, 'username'>): Promise<Follower>;
+/**
+ * Forget one of a user's followers: an `Undo(Follow)`, or an actor deleting
+ * itself.
+ *
+ * Returns whether anything was there to forget. The index is emptied of the
+ * actor whether or not the file held it, so a row left over from a file that
+ * was edited by hand cannot go on being delivered to.
+ */
+export declare function removeFollower(records: FederationRecords, username: string, actorId: string): Promise<boolean>;
+/**
+ * One line of the inbox log: an activity, and when the site was told it.
+ *
+ * The line is the activity's own compacted JSON-LD with `receivedAt` in front
+ * of it. That is the one thing the activity cannot say for itself — a peer
+ * publishes when a note was written, not when this server heard about it — and
+ * it is what the federation screen orders by, so an index rebuilt from the log
+ * would otherwise have to invent it.
+ */
+export interface InboxLine {
+    /** When the activity arrived, as an ISO 8601 instant. */
+    readonly receivedAt: string;
+    /**
+     * The user it was addressed to, or `null` for one delivered to the shared
+     * inbox without naming an actor of this site.
+     *
+     * decision-14 makes every user an actor, so "what the inbox was told" is no
+     * longer one question: a `Follow` is a follow *of somebody*, and a reply is
+     * a reply to somebody's post. The log stays one chronological record, as it
+     * is a record of what this server was told, and each line says whose it was.
+     */
+    readonly recipient: string | null;
+    /** The activity as compacted JSON-LD, exactly as it arrived. */
+    readonly json: string;
+}
+/**
+ * The whole inbox log, oldest month first and, within a month, in the order
+ * the activities arrived.
+ *
+ * Every month file under `content/_data/federation/inbox` is read; a file or a
+ * line that will not parse throws, naming the file. Fedify answers a throwing
+ * dispatcher by swallowing the throw, so a log this cannot read has to stop
+ * the boot rather than wait to be noticed through a request.
+ */
+export declare function readInboxLog(contentDir: string): InboxLine[];
+/**
+ * Record one inbound activity: append it to the month's log and index it.
+ *
+ * `json` is the activity as compacted JSON-LD, which is what the handler has
+ * and what doc-4 says to keep whole — nothing is picked out of it here beyond
+ * the columns the index pages and counts by, because what a later phase will
+ * want out of an activity is not knowable from here.
+ *
+ * An activity with no actor is dropped and nothing is written: Fedify has
+ * already refused anything whose signature does not match its actor, so one
+ * without an actor is malformed rather than anonymous. A redelivery of an
+ * activity the month already holds replaces its line where it stands, which is
+ * what the index's unique key on the activity id does to the row.
+ */
+export declare function appendInboxActivity(records: FederationRecords, json: string, options?: {
+    recipient?: string | null | undefined;
+    receivedAt?: string | undefined;
+}): Promise<InboxActivity | undefined>;
+/**
+ * One line of the log as the index row it makes, or `undefined` when it is not
+ * an activity the log keeps.
+ *
+ * This is the only place a row is derived, and the live append and the boot
+ * rebuild both go through it, so a row rebuilt from the log cannot say
+ * something different from the row the activity made when it arrived. Every
+ * column is read out of the JSON, so the file really is the whole story;
+ * `inReplyTo` is the one the store derives for itself, from this same JSON and
+ * by the same rule.
+ */
+export declare function inboxRowFrom(line: InboxLine): NewInboxActivity | undefined;
+/** What a rebuild put in the index. */
+export interface FederationIndexReport {
+    /** How many followers the files named, across every user. */
+    followers: number;
+    /** How many activities the log held. */
+    activities: number;
+}
+/**
+ * Rebuild the followers and inbox indexes from the files.
+ *
+ * This is what makes `data/geekity.db` disposable for federation (decision-9):
+ * the two tables hold nothing but what these files say, so every boot throws
+ * away what they hold and reads them again. That is also what makes editing
+ * `followers.json` by hand and restarting a supported thing to do, and why a
+ * database deleted at rest costs a site nothing.
+ *
+ * Exported so `geekity rebuild` can call the very function boot calls. It is
+ * synchronous because both callers are, and it reads before it writes: a file
+ * that will not parse throws with the file named and leaves the index exactly
+ * as it was, rather than emptying it and then failing.
+ */
+export declare function rebuildFederationIndexes(records: FederationRecords): FederationIndexReport;
+/**
+ * Write an older site's inbox rows out as files, once.
+ *
+ * Before decision-9 the table was the source rather than an index of one, so a
+ * site upgrading has rows that no file carries. The rule is the simple one the
+ * other decision-9 migrations use, and it is simple here because the log did
+ * not exist as a file at all before: a log that is already there wins outright
+ * and is not touched, and rows are written out only where there is none. The
+ * lines it writes name no recipient, because the site they came from had one
+ * actor and it is gone (decision-14).
+ *
+ * The site actor's followers are **not** migrated. decision-14 replaces one
+ * site actor with one actor per user, and there is no honest answer to which
+ * user inherited the followers of an account that no longer exists: a follow
+ * is an agreement with somebody, and handing it to whoever happens to have the
+ * lowest user id would be answering it for them. A site that federated as the
+ * site actor starts again as its users, and the old
+ * `content/_data/federation/followers.json` is left exactly where it is for an
+ * operator who wants to move rows into a user's file by hand.
+ *
+ * The table is not dropped, unlike `settings`, `actor_keys` and `users`: it
+ * stays as the index the rest of the CMS reads. {@link rebuildFederationIndexes}
+ * is what runs next and puts the files back into it.
+ */
+export declare function migrateFederationToFiles(records: FederationRecords): void;
+//# sourceMappingURL=records.d.ts.map

package/dist/federation/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/federation/records.ts"],"names":[],"mappings":"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"}