sliftutils 1.7.32 → 1.7.34

package/storage/remoteStorage/storageController.ts

@@ -10,39 +10,27 @@ import { timeInMinute } from "socket-function/src/misc";
 import { getCommonName, getPublicIdentifier, getOwnMachineId, verify, verifyMachineIdForPublicKey } from "../../misc/https/certs";
 import { ArchiveFileInfo, ArchivesConfig, ArchivesSyncStatus, IMMUTABLE_CACHE_TIME } from "../IArchives";
 import { ROUTING_FILE } from "./remoteConfig";
-import { getTakeoverStamp } from "./deployTakeover";
 import {
     getStorageServerConfig, getTrust, getRequests, getLoadedBucket, writeBucketFile,
     deleteBucketFile, assertWritesAllowed, assertMutable, LoadedBucket,
-    getBucketConfig, listAccountBuckets, ServerBucketInfo,
+    getBucketConfig, listAccountBuckets, ServerBucketInfo, clearAccountWriteStats,
+    getActiveBucket, activateBucket, ActiveBucketInfo,
 } from "./storageServerState";
 import { StorageClientController } from "./storageClientController";
 
-// The remote storage server's API. Authentication uses certs.ts machine identities: a client
-// proves it owns its machine key by signing a timestamped token (bound to this server, so tokens
-// can't be replayed elsewhere), and the server then trusts that connection as that machineId.
-// Access to an account is granted to specific machineIds, via a command line command run on the
-// storage machine (see storageServer.ts).
-//
-// There is no bucket-creation API: a bucket exists iff its routing config (ROUTING_FILE) exists,
-// and writing that file creates or reconfigures the bucket (see storageServerState.ts). Reads of
-// nonexistent buckets return undefined / empty, same as reads of nonexistent files.
-
 export const REMOTE_STORAGE_CLASS_GUID = "RemoteStorageController-b7e42a91";
 export const STORAGE_AUTH_PURPOSE = "remoteStorage-auth-1";
-// Error markers, so clients can identify these failures inside error messages
 export const STORAGE_NOT_AUTHENTICATED = "REMOTE_STORAGE_NOT_AUTHENTICATED_cf2f7b1e";
 export const STORAGE_ACCESS_DENIED = "REMOTE_STORAGE_ACCESS_DENIED_9d81a4c0";
 
 const AUTH_TIME_WINDOW = timeInMinute * 10;
+const ACCESS_CHECK_SLOW_TIME = 50;
 const MAX_SESSIONS = 100 * 1000;
 const MAX_REQUESTS_PER_IP = 50;
 
 export type AuthTokenData = {
     purpose: string;
     time: number;
-    // The address the client dialed. The port varies freely (deploy takeovers serve on alternate
-    // ports); only the domain is security-relevant, as it is what the cert binds to.
     server: string;
 };
 export type AuthToken = {
@@ -67,18 +55,10 @@ export type AccessState = {
     machineId: string;
     ip: string;
     hasAccess: boolean;
-    // A single ssh command, runnable from anywhere, that runs the grantAccess CLI on the storage
-    // machine to grant the caller's own pending request. Only set when the caller has a pending
-    // request (so an already-trusted caller has no need for it).
     grantAccessCommand?: string;
-    // Only the machines that ALREADY have access. Pending requests are NEVER listed here — showing
-    // them would let a trusted user accidentally approve a random request. Callers see pending
-    // requests only by explicitly typing an IP into listRequestsForIP.
     trustedMachines?: TrustRecord[];
 };
 
-// callerNodeId -> authenticated machineId. Connections are long-lived websockets, so a session
-// lasts until the connection drops (clients re-authenticate on reconnect).
 const sessions = new Map<string, string>();
 
 const CONTENT_TYPES: { [ext: string]: string } = {
@@ -100,15 +80,11 @@ function assertValidPath(path: string) {
     if (!path || path.startsWith("/") || path.endsWith("/") || path.includes("//") || path.includes("\\") || path.includes("\x00")) {
         throw new Error(`Invalid path ${JSON.stringify(path.slice(0, 200))}, paths cannot be empty, start or end with /, or contain //, backslashes, or null characters`);
     }
-    // Paths are one-to-one with files on disk, so . and .. segments would escape the store folder
     if (path.split("/").some(part => part === "." || part === "..")) {
         throw new Error(`Invalid path ${JSON.stringify(path.slice(0, 200))}, paths cannot contain . or .. segments`);
     }
 }
 
-// Every client pings us (immediately on connect, then continuously), so pings tell us exactly who
-// our currently-connected clients are. Client nodeIds never reconnect (a reconnect is a NEW
-// nodeId), so the disconnect callback fully cleans an entry up.
 const connectedClients = new Set<string>();
 function trackCaller(): void {
     let nodeId = SocketFunction.getCaller().nodeId;
@@ -119,15 +95,10 @@ function trackCaller(): void {
     });
 }
 
-/** Called by storageServerState the moment any routing config is applied - clients must never
- *  have to wait for a poll to learn the topology changed. */
 export function broadcastRoutingChanged(): void {
     console.log(`Broadcasting routing config change to ${connectedClients.size} connected clients`);
     for (let nodeId of [...connectedClients]) {
-        void StorageClientController.nodes[nodeId].routingConfigChanged().catch(() => {
-            // The client is gone (or too old to know the controller); the disconnect callback
-            // cleans the registry, nothing to do here
-        });
+        void StorageClientController.nodes[nodeId].routingConfigChanged().catch(() => { });
     }
 }
 
@@ -165,8 +136,6 @@ async function requireAccess(account: string): Promise<string> {
     return machineId;
 }
 
-// A single command, runnable from anywhere, that sshes into the storage machine and runs the
-// grantAccess CLI there
 function getGrantAccessCommand(requestId: string): string {
     let { sshTarget, serverCommand } = getStorageServerConfig();
     return `ssh ${sshTarget} '${serverCommand} --requestId ${requestId}'`;
@@ -179,23 +148,14 @@ async function getBucket(account: string, bucketName: string): Promise<LoadedBuc
 }
 
 class RemoteStorageControllerBase {
-    // Latency measurement (see SourceWrapper's pinging); no auth, it measures the transport. The
-    // takeover stamp piggybacks on it so every connected client learns of a deploy takeover
-    // within one ping interval. Pings also tell us who our clients ARE - the trackCaller
-    // registry is what routing-change broadcasts push to.
-    async ping(): Promise<{ takeover?: string }> {
+    async ping(): Promise<{}> {
         trackCaller();
-        return { takeover: getTakeoverStamp() };
+        return {};
     }
 
-    // Proves the caller owns the machine key for the machineId in its certificate. The signature
-    // must be fresh and bound to this server, so it cannot be replayed to (or from) other servers.
     async authenticate(token: AuthToken): Promise<{ machineId: string; ip: string }> {
         let { domain, port } = getStorageServerConfig();
         let caller = SocketFunction.getCaller();
-        // First establish that the signature signs the data exactly as the client sent it, THEN
-        // validate the data's fields. The two steps must never be mixed - reconstructing the
-        // payload from expectations conflates "is this signed" with "is this acceptable".
         verify(token.certPem, token.signature, token.data);
         let { purpose, time, server } = token.data;
         if (purpose !== STORAGE_AUTH_PURPOSE) {
@@ -204,8 +164,6 @@ class RemoteStorageControllerBase {
         if (Math.abs(Date.now() - time) > AUTH_TIME_WINDOW) {
             throw new Error(`Auth token time is too far from the server time (token ${time}, server ${Date.now()}, allowed drift ${AUTH_TIME_WINDOW}ms)`);
         }
-        // Clients sign the address they dialed. The port varies freely (deploy takeovers serve on
-        // alternate ports); the domain is the replay boundary, so only it must match us.
         let tokenDomain = server.split(":")[0];
         if (tokenDomain !== domain) {
             throw new Error(`Auth token is for server ${JSON.stringify(server)}, but this server is ${JSON.stringify(`${domain}:${port}`)}`);
@@ -223,8 +181,6 @@ class RemoteStorageControllerBase {
         return { machineId, ip: getCallerIP() };
     }
 
-    // Records that the calling machine wants access to an account. Requests are kept per requesting
-    // IP, so the storage machine's admin can list them with --listAccess <ip> and grant one.
     async requestAccess(account: string): Promise<{ machineId: string; ip: string; requestId: string; grantAccessCommand: string }> {
         assertValidName(account, "account");
         let machineId = getCallerMachineId();
@@ -275,20 +231,12 @@ class RemoteStorageControllerBase {
         return result;
     }
 
-    // Callable by any machine that has access to `account`. Returns pending access requests for the
-    // account that come from EXACTLY `ip`. Callers must type in an IP explicitly — the server never
-    // volunteers a list of requesting IPs, so a trusted user can't accidentally approve a random
-    // request from a machine they didn't mean to trust.
     async listRequestsForIP(account: string, ip: string): Promise<AccessRequest[]> {
         let requests = await getRequests();
         return (await requests.get(ip) || []).filter(x => x.account === account);
     }
 
-    // Callable by any machine that has access to the request's account (or by the storage-machine
-    // admin). Grants the requested access; the caller must supply the specific requestId, which they
-    // only get by explicitly looking up requests for a specific IP.
     async grantAccess(requestId: string): Promise<TrustRecord> {
-        // Must capture in the synchronous phase — SocketFunction.getCaller() only works before any await.
         let callerMachineId = getCallerMachineId();
         let trust = await getTrust();
         let requests = await getRequests();
@@ -311,9 +259,6 @@ class RemoteStorageControllerBase {
         throw new Error(`No access request found with id ${JSON.stringify(requestId)}. It may have already been granted or expired.`);
     }
 
-    // Admin (must be run from the storage machine itself, which shares the server's machineId).
-    // Only returns requests for the given IP, so you cannot accidentally grant a request from an
-    // IP you didn't explicitly type in.
     async adminListRequests(ip: string): Promise<AccessRequest[]> {
         let requests = await getRequests();
         return await requests.get(ip) || [];
@@ -350,8 +295,6 @@ class RemoteStorageControllerBase {
     async set(account: string, bucketName: string, path: string, data: Buffer, lastModified?: number): Promise<void> {
         assertValidName(bucketName, "bucket name");
         assertValidPath(path);
-        // Handles bucket creation (writes of ROUTING_FILE), reconfiguration, fast mode, and
-        // immutability — see storageServerState.ts
         await writeBucketFile(account, bucketName, path, Buffer.from(data), { lastModified });
     }
     async del(account: string, bucketName: string, path: string): Promise<void> {
@@ -370,7 +313,6 @@ class RemoteStorageControllerBase {
         if (!bucket) return [];
         return await bucket.store.findInfo(prefix, config);
     }
-    // Fast (served from the store's BulkDatabase2 index, not a scan) — see IArchives.getChangesAfter
     async getChangesAfter(account: string, bucketName: string, time: number): Promise<ArchiveFileInfo[]> {
         let bucket = await getBucket(account, bucketName);
         if (!bucket) return [];
@@ -381,17 +323,33 @@ class RemoteStorageControllerBase {
     }
     async getArchivesConfig(account: string, bucketName: string): Promise<ArchivesConfig> {
         let bucket = await getBucket(account, bucketName);
-        // Missing buckets say true, matching what they become once created (the default store type)
         if (!bucket) return { supportsChangesAfter: true };
         return getBucketConfig(bucket);
     }
-    /** Every bucket the account has on this host - active and inactive - with each bucket's
-     *  configuration. Inactive buckets stay inactive (their routing is read straight off disk). */
     async listBuckets(account: string): Promise<ServerBucketInfo[]> {
-        return await listAccountBuckets(account);
+        let start = Date.now();
+        try {
+            return await listAccountBuckets(account);
+        } finally {
+            // The access hook (and the storage it initializes) runs before this, so a large gap between this and the caller's timing is the hook
+            console.log(`listBuckets(${account}) call body took ${Date.now() - start}ms`);
+        }
+    }
+    /** The live, in-memory state of one bucket, or a string saying why it is unavailable. Answered without touching the disk, so it is cheap - but only works while the bucket is loaded here. */
+    async getActiveBucket(account: string, bucketName: string): Promise<ActiveBucketInfo | string> {
+        assertValidName(bucketName, "bucket name");
+        return await getActiveBucket(account, bucketName);
+    }
+    /** Loads a bucket that exists on this server into memory (starting its synchronization) and returns its live state, or a string saying why it could not be loaded. */
+    async activateBucket(account: string, bucketName: string): Promise<ActiveBucketInfo | string> {
+        assertValidName(bucketName, "bucket name");
+        return await activateBucket(account, bucketName);
+    }
+    /** Zeroes the write statistics listBuckets reports, for every bucket in the account. */
+    async clearWriteStats(account: string): Promise<{ clearedBuckets: number }> {
+        assertValidName(account, "account");
+        return { clearedBuckets: await clearAccountWriteStats(account) };
     }
-    /** Walks the whole index for exact totals (overall and per holding source) - more expensive
-     *  than the maintained counters that getArchivesConfig returns, but immune to counter drift. */
     async getIndexInfo(account: string, bucketName: string): Promise<{ fileCount: number; byteCount: number; sources: { debugName: string; fileCount: number; byteCount: number }[] } | undefined> {
         let bucket = await getBucket(account, bucketName);
         if (!bucket || !bucket.store.computeIndexTotals) return undefined;
@@ -408,7 +366,6 @@ class RemoteStorageControllerBase {
 
     async startLargeFile(account: string, bucketName: string, path: string): Promise<string> {
         assertWritesAllowed();
-        // Validates now, so the upload doesn't fail at the end
         assertValidPath(path);
         let bucket = await getBucket(account, bucketName);
         if (!bucket) {
@@ -445,11 +402,7 @@ class RemoteStorageControllerBase {
         await bucket.store.cancelLargeUpload(uploadId);
     }
 
-    // The server's single default HTTP route. /file/<account>/<bucketName>/<path> serves files from
-    // public buckets over plain GETs (see IArchives.getURL); every other path serves the access
-    // page (via RequireController.requireHTML — the path is the account name, see accessPage.tsx).
     async httpEntry(config?: { requireCalls?: string[]; cacheTime?: number }): Promise<Buffer> {
-        // Both are keyed by the current call and must be captured synchronously, before any await
         let caller = SocketFunction.getCaller();
         let request = getCurrentHTTPRequest();
         let pathname = new URL(request?.url || "/", "https://localhost").pathname;
@@ -476,8 +429,6 @@ class RemoteStorageControllerBase {
         if (!bucket.self?.public) {
             throw new Error(`Bucket ${account}/${bucketName} is not public, so its files cannot be read over plain URLs`);
         }
-        // The index answers existence + write time + size without touching any data, so
-        // If-Modified-Since and range validation cost nothing
         let info = await bucket.store.getInfo(filePath);
         if (!info || !info.size) {
             return setHTTPResultHeaders(Buffer.from(""), { status: "404" });
@@ -494,7 +445,6 @@ class RemoteStorageControllerBase {
         let ifModifiedSince = request?.headers["if-modified-since"];
         if (typeof ifModifiedSince === "string") {
             let since = new Date(ifModifiedSince).getTime();
-            // Last-Modified is served at 1 second resolution, so compare at that resolution
             if (since && Math.floor(info.writeTime / 1000) * 1000 <= since) {
                 return setHTTPResultHeaders(Buffer.from(""), { ...headers, status: "304" });
             }
@@ -502,7 +452,6 @@ class RemoteStorageControllerBase {
         let range: { start: number; end: number } | undefined;
         let rangeHeader = request?.headers["range"];
         if (typeof rangeHeader === "string") {
-            // Single-range form only (bytes=start-end / start- / -suffix); anything else serves the full file
             let match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader.trim());
             if (match && (match[1] || match[2])) {
                 let start: number;
@@ -534,14 +483,16 @@ class RemoteStorageControllerBase {
 
 const largeUploadInfo = new Map<string, { account: string; bucketName: string; path: string }>();
 
-// Access checks run as hooks on the register shape below, keyed off the call's arguments, so the
-// method bodies don't each repeat them
 const accountAccess: SocketFunctionHook = async (context) => {
+    let start = Date.now();
     await requireAccess(String(context.call.args[0]));
+    let duration = Date.now() - start;
+    if (duration > ACCESS_CHECK_SLOW_TIME) {
+        console.log(`Access check for ${context.call.functionName} took ${duration}ms`);
+    }
 };
 const uploadAccess: SocketFunctionHook = async (context) => {
     let info = largeUploadInfo.get(String(context.call.args[0]));
-    // Unknown upload ids are handled by the methods themselves (throw / no-op)
     if (!info) return;
     await requireAccess(info.account);
 };
@@ -571,6 +522,9 @@ export const RemoteStorageController = SocketFunction.register(
         getArchivesConfig: { hooks: [accountAccess] },
         getIndexInfo: { hooks: [accountAccess] },
         listBuckets: { hooks: [accountAccess] },
+        getActiveBucket: { hooks: [accountAccess] },
+        activateBucket: { hooks: [accountAccess] },
+        clearWriteStats: { hooks: [accountAccess] },
         getSyncStatus: { hooks: [accountAccess] },
         startLargeFile: { hooks: [accountAccess] },
         uploadPart: { hooks: [uploadAccess] },

package/storage/remoteStorage/storageServer.ts

@@ -6,34 +6,25 @@ import { getExternalIP } from "socket-function/src/networking";
 import { RequireController } from "socket-function/require/RequireController";
 import { hostServer } from "../../misc/https/hostServer";
 import { RemoteStorageController } from "./storageController";
-import { setStorageServerConfig, setWritesRejectedReason, addExtraListenPort } from "./storageServerState";
-import { initDeployTakeover, registerAltPort, getMainPortAcquireDelay } from "./deployTakeover";
+import { setStorageServerConfig, setWritesRejectedReason, addExtraListenPort, removeExtraListenPort } from "./storageServerState";
+import { detectDeployTakeover, setAltPort, getAltPortListenEnd, getMainPortAcquireDelay } from "./deployTakeover";
 import { parseStorageUrl } from "./ArchivesRemote";
 // Import browser code, so it is allowed to be required by the client
 import "./accessPage";
 
 const DEFAULT_LOW_SPACE_THRESHOLD_BYTES = 25 * 1024 ** 3;
 const DISK_SPACE_CHECK_INTERVAL_MS = 15 * 60 * 1000;
-// Below this fraction of the warn threshold, we start rejecting writes so the server itself doesn't
-// tip the machine into instability. Reads/deletes still work so users can free space.
+// Below this fraction of the warn threshold, we start rejecting writes so the server itself doesn't tip the machine into instability. Reads/deletes still work so users can free space.
 const HARD_REJECT_FRACTION = 0.1;
 
-// The remote storage server, as a library function: consumers call hostStorageServer() from their
-// own process to start hosting (or use the storageserver bin, see storageServerCli.ts). The
-// grantAccess.js bootstrap (next to this file) is what the access page's shown SSH command points at.
+// The remote storage server, as a library function: consumers call hostStorageServer() from their own process to start hosting (or use the storageserver bin, see storageServerCli.ts). The grantAccess.js bootstrap (next to this file) is what the access page's shown SSH command points at.
 
 export type HostStorageServerConfig = {
-    // Full URL of this storage server, e.g. "https://1-2-3-4.example.com:4444". The subdomain must
-    // be an ip domain - this machine's external IP with dashes, or 127-0-0-1 for local testing
-    // (see the validation in hostStorageServer). The domain and port are extracted from it (bucket
-    // routing URLs clients use look like
+    // Full URL of this storage server, e.g. "https://1-2-3-4.example.com:4444". The subdomain must be an ip domain - this machine's external IP with dashes, or 127-0-0-1 for local testing (see the validation in hostStorageServer). The domain and port are extracted from it (bucket routing URLs clients use look like
     // https://1-2-3-4.example.com:4444/file/<account>/<bucketName>/storage/storagerouting.json).
     url: string;
     folder: string;
-    // When free space on the folder's drive drops below this many bytes, the server console.errors
-    // every 15 minutes. Below 10% of it, the server also rejects write operations (creating files,
-    // large uploads, new buckets) — reads, findInfo, and deletes still work so the user can free
-    // space. Default 25 GiB.
+    // When free space on the folder's drive drops below this many bytes, the server console.errors every 15 minutes. Below 10% of it, the server also rejects write operations (creating files, large uploads, new buckets) — reads, findInfo, and deletes still work so the user can free space. Default 25 GiB.
     lowSpaceThresholdBytes?: number;
 };
 
@@ -68,9 +59,7 @@ async function checkDiskSpace(config: { folder: string; threshold: number }): Pr
     }
 }
 
-// Full path to the grantAccess CLI bootstrap that lives next to this file. The SSH command shown on
-// the access page invokes it via `node <path> ...` (found through __dirname so consumers don't have
-// to know where our source lives).
+// Full path to the grantAccess CLI bootstrap that lives next to this file. The SSH command shown on the access page invokes it via `node <path> ...` (found through __dirname so consumers don't have to know where our source lives).
 function getGrantAccessCliPath(): string {
     return path.join(__dirname, "grantAccess.js");
 }
@@ -80,9 +69,7 @@ export async function hostStorageServer(config: HostStorageServerConfig): Promis
     let { address: domain, port } = parseStorageUrl(url);
     let rootDomain = domain.split(".").slice(-2).join(".");
     let externalIP = (await getExternalIP()).trim();
-    // The subdomain must be an ip domain: the domain's A record points at exactly one machine, so a
-    // dynamic name would let the same script run on two servers and silently fight over it. Encoding
-    // the IP makes that mistake fail loudly - the wrong machine's domain just doesn't match.
+    // The subdomain must be an ip domain: the domain's A record points at exactly one machine, so a dynamic name would let the same script run on two servers and silently fight over it. Encoding the IP makes that mistake fail loudly - the wrong machine's domain just doesn't match.
     let allowedDomains = [`127-0-0-1.${rootDomain}`, `${externalIP.replaceAll(".", "-")}.${rootDomain}`];
     if (!allowedDomains.includes(domain)) {
         throw new Error(`The storage server domain is based on the machine's IP (the subdomain is the IP with dots replaced by dashes). Expected ${allowedDomains.join(" or ")}, was ${domain}. Your external IP is ${externalIP}.`);
@@ -101,17 +88,12 @@ export async function hostStorageServer(config: HostStorageServerConfig): Promis
     RequireController.allowAllNodeModules();
     SocketFunction.expose(RequireController);
     SocketFunction.expose(RemoteStorageController);
-    // Every HTTP path goes through httpEntry: /file/<account>/<bucketName>/... serves public
-    // bucket files, everything else serves the access page (the path is the account name, see
-    // accessPage.tsx).
-    // A full URL, so the page resolves modules from the origin root even when served at
-    // /accountName (a relative require would resolve inside the account path).
+    // Every HTTP path goes through httpEntry: /file/<account>/<bucketName>/... serves public bucket files, everything else serves the access page (the path is the account name, see accessPage.tsx). A full URL, so the page resolves modules from the origin root even when served at /accountName (a relative require would resolve inside the account path).
     SocketFunction.setDefaultHTTPCall(RemoteStorageController, "httpEntry", {
         requireCalls: [`https://${domain}:${port}/./storage/remoteStorage/accessPage.tsx`],
     });
 
-    // Initial check so a server starting under-limit immediately rejects writes; then keep checking
-    // every 15 minutes so recovery (freed disk space) is picked up automatically.
+    // Initial check so a server starting under-limit immediately rejects writes; then keep checking every 15 minutes so recovery (freed disk space) is picked up automatically.
     await checkDiskSpace({ folder, threshold: lowSpaceThreshold });
     let interval = setInterval(() => {
         void checkDiskSpace({ folder, threshold: lowSpaceThreshold })
@@ -119,21 +101,25 @@ export async function hostStorageServer(config: HostStorageServerConfig): Promis
     }, DISK_SPACE_CHECK_INTERVAL_MS);
     (interval as { unref?: () => void }).unref?.();
 
-    // Port fallback is always on: a busy port means listening on an alternate, registering it, and
-    // polling to take the real port. The deploy takeover machinery merely rides on top (tighter
-    // polling around a scheduled switchover, and the valid-window remap once a successor is known).
-    await initDeployTakeover({ domain, mainPort: port, storageFolder: path.resolve(folder) });
-
     await hostServer({
         domain,
         port,
         setDNSRecord: true,
         portFallback: {
             getAcquireDelay: getMainPortAcquireDelay,
+            onPortInUse: async () => {
+                await detectDeployTakeover();
+            },
             onListening: (listeningPort, isMainPort) => {
                 if (isMainPort) return;
                 addExtraListenPort(listeningPort);
-                void registerAltPort(listeningPort).catch((e: Error) => console.error(`Registering alternate port ${listeningPort} failed: ${e.stack ?? e}`));
+                setAltPort(listeningPort);
+                let listenEnd = getAltPortListenEnd();
+                let timer = setTimeout(() => {
+                    console.log(`Alternate port ${listeningPort} reached its end of life at ${new Date(listenEnd).toISOString()}; it no longer counts as one of our addresses (the socket itself stays bound, as the main-port relay forwards into it)`);
+                    removeExtraListenPort(listeningPort);
+                }, Math.max(0, listenEnd - Date.now()));
+                (timer as { unref?: () => void }).unref?.();
             },
         },
     });

package/storage/remoteStorage/storageServerState.d.ts

@@ -20,7 +20,16 @@ export declare function getWritesRejectedReason(): string | undefined;
 export declare function assertWritesAllowed(): void;
 export declare function getTrust(): Promise<IStorage<TrustRecord>>;
 export declare function getRequests(): Promise<IStorage<AccessRequest[]>>;
-/** Makes machineIds the complete trust list for the account: machines not in the list lose access, machines already trusted keep their existing record, and missing ones are added. */
+export type BucketWriteStats = {
+    /** Every set call the bucket accepted */
+    originalWrites: number;
+    originalBytes: number;
+    /** What actually reached the sources. Fast writes coalesce repeated writes to the same key, so this is lower than the original counts (and is what the disk actually did). */
+    flushedWrites: number;
+    flushedBytes: number;
+};
+/** Zeroes the write statistics of every bucket in the account, including counts not yet flushed. */
+export declare function clearAccountWriteStats(account: string): Promise<number>;
 export declare function setTrustedMachines(config: {
     account: string;
     machineIds: string[];
@@ -36,6 +45,7 @@ export type LoadedBucket = {
     structureKey: string;
 };
 export declare function addExtraListenPort(port: number): void;
+export declare function removeExtraListenPort(port: number): void;
 export declare function getLoadedBucket(account: string, bucketName: string): Promise<LoadedBucket | undefined>;
 export declare function assertMutable(bucket: LoadedBucket, filePath: string, writeTime: number): Promise<void>;
 export declare function writeBucketFile(account: string, bucketName: string, filePath: string, data: Buffer, config?: {
@@ -43,16 +53,42 @@ export declare function writeBucketFile(account: string, bucketName: string, fil
 }): Promise<void>;
 export declare function getBucketConfig(bucket: LoadedBucket): ArchivesConfig;
 export declare function rebuildAllLoadedBuckets(): Promise<void>;
+/** Started by deployTakeover once we are actually a deploy successor listening on an alternate port. Until then there are no switchover windows to write or expire, so nothing polls. */
+export declare const startIntermediateMaintenance: {
+    (): void;
+    reset(): void;
+    set(newValue: void): void;
+};
+export type BucketDiskInfo = {
+    totalBytes: number;
+    freeBytes: number;
+    usedBytes: number;
+};
 export type ServerBucketInfo = {
     bucketName: string;
     active: boolean;
+    /** Where the bucket's data lives on this server */
+    folder: string;
+    /** The drive that folder is on. Buckets sharing a drive report the same numbers. */
+    disk?: BucketDiskInfo;
+    diskError?: string;
+    writeStats?: BucketWriteStats;
     config?: ArchivesConfig;
     error?: string;
 };
-/** Every bucket the account has on this server, active or not, each with its configuration.
- *  Inactive buckets are inspected straight from disk WITHOUT loading them - loading would start
- *  their synchronization, and old invalid buckets must stay inert (their parse error is reported
- *  instead). */
+export type ActiveBucketInfo = {
+    folder: string;
+    /** The routing config the bucket is RUNNING on, straight from memory - including switchover windows written since it loaded */
+    routing: RemoteConfig;
+    /** Our own entries in that config, and the one currently valid */
+    selfEntries: HostedConfig[];
+    self?: HostedConfig;
+    config: ArchivesConfig;
+};
+/** The live in-memory state of ONE bucket, answered without touching the disk (no routing file read, no statfs, no stored write stats). Returns an error string when the bucket is not loaded here, which is the normal state for a bucket nothing has accessed since startup. */
+export declare function getActiveBucket(account: string, bucketName: string): Promise<ActiveBucketInfo | string>;
+/** Loads a bucket that exists on this server's disk into memory, which starts its synchronization and window timers, and returns its live state. Nothing is written and no other server is contacted - unlike building an ArchivesChain for it, which would probe every source and could write the routing config. Already-loaded buckets just return their state. */
+export declare function activateBucket(account: string, bucketName: string): Promise<ActiveBucketInfo | string>;
 export declare function listAccountBuckets(account: string): Promise<ServerBucketInfo[]>;
 export declare function deleteBucketFile(account: string, bucketName: string, filePath: string): Promise<void>;
 export declare function getLocalArchives(account: string, bucketName: string): IArchives;