fedipod-server 0.6.0 → 0.8.0

package/README.md

@@ -10,10 +10,32 @@ client at the pod's own address. Signing up is the only way an account is
 made, and opting out is the only way one ends.
 
 With nothing configured beyond the defaults, installing the component changes
-nothing about how the server serves pods.
+nothing about how the server serves pods. All pods, whether or not they opt-in
+to being a Fediverse account, behave as Solid pods.
 
 ![A pod and its agent, both inside one Solid server](fedipod-server.svg)
 
+## Requirements
+
+A pod here becomes an address other Fediverse servers talk to and a Mastodon
+app connects to. That asks things of the server it lives on. Check these
+before installing: a server that does not meet them cannot offer accounts, and
+sign-up refuses rather than half-working.
+
+- **Community Solid Server 7.**
+- **Pods on subdomains.** Each account answers on its own pod's address, so
+  every pod needs a host to itself. A server that puts its pods on paths of
+  one shared host cannot offer accounts at all.
+- **A single worker.** Run the server as one copy of itself — `--workers 1`,
+  which is the default. With more, it still serves pods normally, but no pod
+  can be an account: sign-up is refused, and an account set up earlier goes on
+  posting and receiving while no longer answering its owner's apps.
+- **Storage that survives a restart.** Sign-ups are recorded in the server's
+  own storage. On a memory backend every account is forgotten when the server
+  stops.
+- **A directory on disk.** Each account keeps its signing key and its door
+  secret there. Sign-up will not start without one.
+
 ## Install
 
 ```
@@ -129,11 +151,6 @@ belong to the identity, so pod resources at those names — a container called
 They stay in the pod and in its listings. Every other path is the pod, exactly
 as before.
 
-**Run one worker.** A delivery is picked up the moment it lands only in a
-single-worker server. With `--workers` above one the inbox is swept on the
-timer instead, and the server says so at startup. Sign-up requires a
-single worker outright, and says so when refused.
-
 ## How sign-up works
 
 A pod owner opens the `/run` page, signs in with their pod,
@@ -144,8 +161,11 @@ POST /api/agent
 {"action": "opt-in", "podBase": "https://mei.example.org/"}
 ```
 
-The request carries a Solid-OIDC token; the WebID it proves must live under
-the pod being claimed. The reply carries the identity's door secret, shown
+The request carries a Solid-OIDC token. Where the pod's server names an owner,
+the token must prove that owner. Where it names none, the WebID the token
+proves must live under the pod being claimed.
+
+The reply carries the identity's door secret, shown
 that once and never again — losing it is not fatal, because opting in again
 mints a fresh one and retires the old, with no restart and no dropped
 connections. `{"action": "opt-out", "podBase": "https://mei.example.org/"}`,

package/config/server.json

@@ -49,6 +49,17 @@
         }
       ]
     },
+    {
+      "comment": "Claiming the identities' routes in every process that answers requests. The identities themselves run in one process — with workers, the primary — but a worker that had claimed nothing would hand an identity's client API to plain pod serving instead of saying it cannot be reached.",
+      "@id": "urn:solid-server:default:WorkerParallelInitializer",
+      "@type": "ParallelHandler",
+      "handlers": [
+        {
+          "@type": "InitializableHandler",
+          "initializable": { "@id": "urn:fedipod:server:Handler" }
+        }
+      ]
+    },
     {
       "comment": "Insert the handler into the routing waterfall just before the LDP catch-all, so it claims only the front routes and everything else stays normal CSS. OverrideListInsertBefore is available in componentsjs 5.x (which CSS 7 uses).",
       "@type": "Override",

package/dist/claims.js

@@ -6,11 +6,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claims = claims;
 exports.agentClaims = agentClaims;
-const FRONT_PATHS = new Set(['/', '/signup', '/new-account', '/run',
+const FRONT_PATHS = new Set(['/', '/signup', '/new-account', '/run', '/admin',
     '/.well-known/webfinger', '/api/handle', '/api/attach', '/api/agent',
-    // What the two pages load: the sign-in library both use, and the installer
-    // the signup page hands every new user.
-    '/solid-client-authn.bundle.js', '/install']);
+    '/api/roster', '/api/revoke',
+    // What the pages load: the sign-in library the /run and /admin pages use, and
+    // the installer the signup page hands every new user.
+    '/solid-oidc-client.js', '/install']);
 function claims(input, frontHost) {
     if (!input.host || !frontHost)
         return false;

package/dist/components/context.jsonld

@@ -32,6 +32,9 @@
           "args_runPage": {
             "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_runPage"
           },
+          "args_adminPage": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_adminPage"
+          },
           "args_agentDataDir": {
             "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentDataDir"
           },
@@ -83,6 +86,9 @@
           "runPage": {
             "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_runPage"
           },
+          "adminPage": {
+            "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_adminPage"
+          },
           "agentDataDir": {
             "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentDataDir"
           },

package/dist/directory.d.ts

@@ -19,6 +19,17 @@ export interface Directory {
     lookup(handle: string): Promise<DirectoryRecord | null>;
     putDirectory(handle: string, record: DirectoryRecord): Promise<void>;
 }
+/**
+ * The row an identity this server runs should have in the door's directory,
+ * or null to leave what is already there alone.
+ *
+ * A row an owner made by attaching is theirs, and is never touched. A row this
+ * server wrote for this same pod is corrected when it still names the pod root
+ * rather than the identity's own tree — the place the door writes deliveries
+ * and the agent watches. The secret rides across the correction, because a
+ * gateway holding it has to go on working.
+ */
+export declare function frontRow(existing: DirectoryRecord | null, next: DirectoryRecord, podBase: string): DirectoryRecord | null;
 export declare function makeDirectory(io: IO, containerUrl: string): Directory;
 /** A pod whose owner opted in at runtime. The door secret is never in the row. */
 export interface AgentRegistryRecord {

package/dist/directory.js

@@ -3,6 +3,7 @@
 // read and written through a minimal IO shape { read, write } so it tests
 // without a running CSS. store-css.ts supplies the real IO over a ResourceStore.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.frontRow = frontRow;
 exports.makeDirectory = makeDirectory;
 exports.makeAgentRegistry = makeAgentRegistry;
 exports.makeStorePodPut = makeStorePodPut;
@@ -31,6 +32,24 @@ function jsonTable(io, containerUrl) {
         },
     };
 }
+/**
+ * The row an identity this server runs should have in the door's directory,
+ * or null to leave what is already there alone.
+ *
+ * A row an owner made by attaching is theirs, and is never touched. A row this
+ * server wrote for this same pod is corrected when it still names the pod root
+ * rather than the identity's own tree — the place the door writes deliveries
+ * and the agent watches. The secret rides across the correction, because a
+ * gateway holding it has to go on working.
+ */
+function frontRow(existing, next, podBase) {
+    if (!existing)
+        return next;
+    const ours = existing.inboxOnly === true && existing.podHome === podBase;
+    if (!ours || existing.podHome === next.podHome)
+        return null;
+    return { ...existing, podHome: next.podHome, actorUrl: next.actorUrl };
+}
 function makeDirectory(io, containerUrl) {
     const table = jsonTable(io, containerUrl);
     return {

package/dist/handler.d.ts

@@ -18,6 +18,8 @@ export interface FediPodServerArgs {
     signupPage?: string;
     /** The run-your-identity page HTML served at /run. */
     runPage?: string;
+    /** The accounts-roster page HTML served at /admin. */
+    adminPage?: string;
     /** Directory holding each agent identity's signing key and log. Required when runtime opt-in is on. */
     agentDataDir?: string;
     /** Path from a pod's base to the owner's WebID. */
@@ -41,6 +43,9 @@ export interface FediPodServerArgs {
 interface EmbeddedIdentity {
     handle: string;
     host: string;
+    /** Where the identity's own tree begins on its pod, and the actor inside it. */
+    podHome: string;
+    actorUrl: string;
     surface: {
         handler: (req: unknown, res: unknown) => Promise<void>;
         streaming?: unknown;
@@ -91,11 +96,22 @@ export declare class FediPodServerHandler extends HttpHandler implements Initial
      * When this server is also the door, give a running identity a
      * @handle@<frontHost> address: one inbox-only directory row so the
      * shared-domain handle resolves and the door can take verified delivery for
-     * it. Written once — a manual attach or an earlier boot wins. The identity
-     * keeps its own actor ids on the pod; nothing is moved.
+     * it. The row names the identity's own tree, which is where its inbox and
+     * its actor are — the door writes deliveries there and the agent watches
+     * that container. A row written by an attach belongs to its owner and is
+     * left alone; one this server wrote itself is corrected. The identity keeps
+     * its own ids on the pod; nothing is moved.
      */
     private frontIdentity;
     canHandle({ request }: HttpHandlerInput): Promise<void>;
+    /**
+     * Whether identities run in this process. They run in one: the lease admits
+     * a single drainer, and the state each one holds is in memory. With workers,
+     * that process is the primary — which serves no requests, so every process
+     * still has to know which hosts belong to an identity even though only one
+     * of them can answer for it.
+     */
+    private runsIdentities;
     /** The running identity answering on a host, if it has finished starting. */
     surfaceFor(host?: string): EmbeddedIdentity | undefined;
     /**

package/dist/handler.js

@@ -134,11 +134,12 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
     async initialize() {
         if (!this.registry)
             return;
+        const runs = this.runsIdentities();
         // The stock CSS CLI installs no signal handlers, so a SIGTERM (systemd
         // stop, docker stop, Ctrl+C) killed the process with agent state
         // unflushed and the lease held for its whole TTL. Flush first, bounded,
         // then re-raise so the process still dies the way it was asked to.
-        if (!this.onSignal) {
+        if (runs && !this.onSignal) {
             this.onSignal = (signal) => {
                 const timeout = new Promise((resolve) => { setTimeout(resolve, 5_000).unref?.(); });
                 void Promise.race([this.finalize(), timeout]).then(() => {
@@ -148,13 +149,14 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
             process.once('SIGTERM', this.onSignal);
             process.once('SIGINT', this.onSignal);
         }
-        // The agent runs in the primary process, and a write made by a worker
-        // raises its change event there — so with workers the inbox is swept on the
-        // timer rather than the moment a delivery lands. Everything still works; it
-        // is just slower, and worth saying rather than leaving to be discovered.
-        if (this.args.clusterManager && !this.args.clusterManager.isSingleThreaded()) {
-            this.logger.warn('FediPod agent is running in a multi-worker server: deliveries are picked up by the '
-                + 'inbox sweep instead of as they arrive. Run with --workers 1 for immediate delivery.');
+        // Identities run in the primary, and requests are answered by the workers,
+        // so with more than one worker an identity federates but cannot be reached:
+        // its client API, its owner pages and its live feed are in a process no
+        // request arrives at. Said once, by the process that has them.
+        if (runs && this.args.clusterManager && !this.args.clusterManager.isSingleThreaded()) {
+            this.logger.warn('FediPod is running in a multi-worker server. Deliveries are picked up by the inbox '
+                + 'sweep rather than as they land, and no identity can answer its client API, its live feed or its '
+                + "owner's pages while requests are served by other processes. Run with --workers 1.");
         }
         // Awaited, and BEFORE the server listens: a pod whose owner opted in must
         // have its routes claimed from the first request after a restart, never
@@ -184,10 +186,16 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
         catch (e) {
             this.logger.error(`could not read the opt-in registry — opted-in identities are absent this boot: ${e.message}`);
         }
-        if (pods.length > 0)
-            this.logger.info(`FediPod agent enabled for ${pods.length} opted-in pod(s)`);
-        for (const pod of pods)
-            void this.startIdentity(pod);
+        if (pods.length > 0) {
+            this.logger.info(runs
+                ? `FediPod agent enabled for ${pods.length} opted-in pod(s)`
+                : `FediPod claimed the routes of ${pods.length} opted-in pod(s); they are run elsewhere`);
+        }
+        // Claimed everywhere, run in one place. A process that does not run them
+        // must still not let a pod answer for a path that belongs to an identity.
+        if (runs)
+            for (const pod of pods)
+                void this.startIdentity(pod);
     }
     /** Stop every identity: timers cleared, state written, lease let go. */
     async finalize() {
@@ -267,22 +275,29 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
      * When this server is also the door, give a running identity a
      * @handle@<frontHost> address: one inbox-only directory row so the
      * shared-domain handle resolves and the door can take verified delivery for
-     * it. Written once — a manual attach or an earlier boot wins. The identity
-     * keeps its own actor ids on the pod; nothing is moved.
+     * it. The row names the identity's own tree, which is where its inbox and
+     * its actor are — the door writes deliveries there and the agent watches
+     * that container. A row written by an attach belongs to its owner and is
+     * left alone; one this server wrote itself is corrected. The identity keeps
+     * its own ids on the pod; nothing is moved.
      */
     async frontIdentity(podBase, identity) {
-        const { handle } = identity;
+        const { handle, podHome, actorUrl } = identity;
         try {
-            if (await this.dir.lookup(handle))
-                return;
-            const kind = identity.agent?.store?.getConfig?.()?.kind === 'group' ? 'group' : 'person';
-            await this.dir.putDirectory(handle, {
-                handle, podHome: podBase, actorUrl: `${podBase}ap/actor`, kind,
+            const existing = await this.dir.lookup(handle);
+            const row = (0, directory_1.frontRow)(existing, {
+                handle, podHome, actorUrl,
+                kind: identity.agent?.store?.getConfig?.()?.kind === 'group' ? 'group' : 'person',
                 gatewayWebId: this.args.gatewayWebId ?? null,
                 hmacSecret: (0, node_crypto_1.randomBytes)(32).toString('base64'),
                 inboxOnly: true,
-            });
-            this.logger.info(`FediPod: @${handle}@${this.frontHost} now resolves to ${podBase}`);
+            }, podBase);
+            if (!row)
+                return;
+            await this.dir.putDirectory(handle, row);
+            this.logger.info(existing
+                ? `FediPod: the door's record of @${handle} now names ${podHome}`
+                : `FediPod: @${handle}@${this.frontHost} now resolves to ${podBase}`);
         }
         catch (e) {
             this.logger.warn(`FediPod: could not front @${handle}: ${e.message}`);
@@ -300,6 +315,17 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
             return;
         throw new Error('not a gateway route'); // reject → CSS's LDP handler takes it
     }
+    /**
+     * Whether identities run in this process. They run in one: the lease admits
+     * a single drainer, and the state each one holds is in memory. With workers,
+     * that process is the primary — which serves no requests, so every process
+     * still has to know which hosts belong to an identity even though only one
+     * of them can answer for it.
+     */
+    runsIdentities() {
+        const cluster = this.args.clusterManager;
+        return !cluster || cluster.isSingleThreaded() || cluster.isPrimary();
+    }
     /** The running identity answering on a host, if it has finished starting. */
     surfaceFor(host) {
         return this.surfaces.get(String(host ?? '').toLowerCase());
@@ -379,8 +405,16 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
         if (this.agentHosts.has(host)) {
             const identity = this.surfaces.get(host);
             if (!identity) {
-                // Claimed, but its identity is not up yet. Saying so is better than
-                // letting the pod answer for a route that is about to stop being pod.
+                // Claimed, but nothing here can answer for it. Saying which of the two
+                // reasons it is beats letting the pod answer for a route that is not
+                // the pod's, and beats telling a client to try again when trying again
+                // will reach another process just as unable to help.
+                if (!this.runsIdentities()) {
+                    response.writeHead(503, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'this identity is not reachable on a server running more '
+                            + 'than one worker: it runs in the process that serves no requests. Run with --workers 1.' }));
+                    return;
+                }
                 response.writeHead(503, { 'content-type': 'application/json', 'retry-after': '5' });
                 response.end(JSON.stringify({ error: 'this identity is still starting' }));
                 return;
@@ -406,9 +440,11 @@ class FediPodServerHandler extends community_server_1.HttpHandler {
             offersPods: !!this.args.offersPods,
             signupPage: this.args.signupPage || webFile('new-account.html'),
             runPage: this.args.runPage || webFile('run.html'),
-            // Both pages load the sign-in library, and the signup page hands out the
-            // installer command; without these the pages render but cannot be used.
-            authBundle: webFile('solid-client-authn.bundle.js'),
+            adminPage: this.args.adminPage || webFile('admin.html'),
+            // The /run and /admin pages load the sign-in library, and the signup page
+            // hands out the installer command; without these the pages render but
+            // cannot be used.
+            authBundle: webFile('solid-oidc-client.js'),
             installScript: webFile('install.sh'),
             lookup: (h) => this.dir.lookup(h),
             putDirectory: (h, rec) => this.dir.putDirectory(h, rec),

package/dist/handler.jsonld

@@ -95,6 +95,19 @@
           },
           "comment": "The run-your-identity page HTML served at /run."
         },
+        {
+          "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_adminPage",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "The accounts-roster page HTML served at /admin."
+        },
         {
           "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_agentDataDir",
           "range": {
@@ -311,6 +324,10 @@
           "@id": "fps:dist/handler.jsonld#FediPodServerHandler__member_canHandle",
           "memberFieldName": "canHandle"
         },
+        {
+          "@id": "fps:dist/handler.jsonld#FediPodServerHandler__member_runsIdentities",
+          "memberFieldName": "runsIdentities"
+        },
         {
           "@id": "fps:dist/handler.jsonld#FediPodServerHandler__member_surfaceFor",
           "memberFieldName": "surfaceFor"
@@ -380,6 +397,12 @@
                 "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_runPage"
               }
             },
+            {
+              "keyRaw": "adminPage",
+              "value": {
+                "@id": "fps:dist/handler.jsonld#FediPodServerHandler_args_adminPage"
+              }
+            },
             {
               "keyRaw": "agentDataDir",
               "value": {
@@ -476,6 +499,10 @@
           "@id": "fps:dist/handler.jsonld#FediPodServerArgs__member_runPage",
           "memberFieldName": "runPage"
         },
+        {
+          "@id": "fps:dist/handler.jsonld#FediPodServerArgs__member_adminPage",
+          "memberFieldName": "adminPage"
+        },
         {
           "@id": "fps:dist/handler.jsonld#FediPodServerArgs__member_agentDataDir",
           "memberFieldName": "agentDataDir"