sliftutils 1.7.12 → 1.7.14

package/storage/remoteStorage/ArchivesUrl.ts

@@ -1,5 +1,6 @@
 module.allowclient = true;
 
+import { httpsRequest, HttpsResponseInfo } from "socket-function/src/https";
 import { IArchives, ArchiveFileInfo, ArchivesConfig } from "../IArchives";
 import { buildFileUrl } from "./remoteConfig";
 
@@ -30,25 +31,28 @@ export class ArchivesUrl implements IArchives {
         if (range) {
             headers["Range"] = `bytes=${range.start}-${range.end - 1}`;
         }
-        let response = await fetch(url, { headers });
-        if (response.status === 404) return undefined;
-        if (!response.ok) {
-            throw new Error(`Read of ${url} failed: ${response.status} ${response.statusText}`);
+        let response: HttpsResponseInfo = { headers: {} };
+        let data: Buffer;
+        try {
+            data = await httpsRequest(url, undefined, "GET", false, { headers, outResponse: response });
+        } catch (e) {
+            // httpsRequest throws on any non-2xx; a missing file is a normal absent result, not an error.
+            if (response.statusCode === 404) return undefined;
+            throw e;
         }
-        let data = Buffer.from(await response.arrayBuffer());
         // A real 206 only returns the requested slice, so the full size lives in Content-Range's total.
         let size = data.length;
-        let contentRange = response.headers.get("content-range");
+        let contentRange = response.headers["content-range"];
         let total = contentRange && Number(contentRange.split("/")[1]);
         if (total && Number.isFinite(total)) {
             size = total;
         }
         // Servers that don't support ranges return the full file with a 200 (ours serves real
         // 206s, but backblaze friendly URLs and proxies may not)
-        if (range && response.status === 200) {
+        if (range && response.statusCode === 200) {
             data = data.subarray(Math.min(range.start, data.length), Math.min(range.end, data.length));
         }
-        let lastModified = response.headers.get("last-modified");
+        let lastModified = response.headers["last-modified"];
         let writeTime = lastModified && new Date(lastModified).getTime() || 0;
         return { data, writeTime, size };
     }
@@ -57,7 +61,7 @@ export class ArchivesUrl implements IArchives {
         return result && { writeTime: result.writeTime, size: result.size } || undefined;
     }
 
-    public async set(fileName: string, data: Buffer, config?: { lastModified?: number }): Promise<void> {
+    public async set(fileName: string, data: Buffer, config?: { lastModified?: number }): Promise<string> {
         throw this.readOnlyError("set");
     }
     public async del(fileName: string): Promise<void> {

package/storage/remoteStorage/blobStore.d.ts

@@ -24,7 +24,7 @@ export type IBucketStore = {
         writeTime: number;
         size: number;
     } | undefined>;
-    set(fileName: string, data: Buffer, config?: WriteConfig): Promise<void>;
+    set(fileName: string, data: Buffer, config?: WriteConfig): Promise<string>;
     del(fileName: string, config?: WriteConfig): Promise<void>;
     getInfo(fileName: string): Promise<{
         writeTime: number;
@@ -70,6 +70,7 @@ export declare class BlobStore implements IBucketStore {
     constructor(folder: string, sources: ArchivesSource[], config?: {
         onIndexChanged?: ((key: string) => void) | undefined;
         readerDiskLimit?: number | undefined;
+        getFlushDeadline?: (() => number | undefined) | undefined;
     } | undefined);
     private stopped;
     private index;
@@ -92,6 +93,9 @@ export declare class BlobStore implements IBucketStore {
     private countEntry;
     private setIndexEntry;
     private deleteIndexEntry;
+    /** Rescans our own disk's metadata into the index - used around deploy switchovers, where the
+     *  other process wrote files to the shared folder that our index hasn't seen. */
+    rescanBase(): Promise<void>;
     /** The cheap always-current totals plus any in-progress background synchronization. */
     getSyncProgress(): {
         index: {
@@ -144,7 +148,7 @@ export declare class BlobStore implements IBucketStore {
         size: number;
     } | undefined>;
     private cacheRead;
-    set(key: string, data: Buffer, config?: WriteConfig): Promise<void>;
+    set(key: string, data: Buffer, config?: WriteConfig): Promise<string>;
     del(key: string, config?: WriteConfig): Promise<void>;
     private getWritableSources;
     private writeToSources;

package/storage/remoteStorage/blobStore.ts

@@ -2,7 +2,7 @@ import path from "path";
 import { lazy } from "socket-function/src/caching";
 import { runInfinitePoll, delay } from "socket-function/src/batching";
 import { timeInMinute, sort, promiseObj } from "socket-function/src/misc";
-import { formatNumber } from "socket-function/src/formatting/format";
+import { formatNumber, formatTime } from "socket-function/src/formatting/format";
 import {
     IArchives, ArchiveFileInfo, ArchivesSource, ArchivesSyncStatus, assertValidLastModified,
     windowAcceptsWrites, SyncActivity,
@@ -44,6 +44,9 @@ const DISK_LIMIT_CHECK_INTERVAL = 1000 * 60;
 // Full syncs download this many files concurrently (high-latency sources like backblaze would
 // otherwise crawl one round-trip at a time)
 const FULL_SYNC_PARALLEL = 8;
+// A full sync running longer than this is console.errored (and again every interval after), so a
+// sync that will take days is loud instead of a quiet console.log every minute
+const FULL_SYNC_SLOW_ERROR_INTERVAL = 1000 * 60 * 60;
 
 export type WriteConfig = {
     // Resolve once the write is in memory; flush to the sources after writeDelay, coalescing
@@ -60,7 +63,7 @@ export type WriteConfig = {
 export type IBucketStore = {
     get(fileName: string, config?: { range?: { start: number; end: number } }): Promise<Buffer | undefined>;
     get2(fileName: string, config?: { range?: { start: number; end: number } }): Promise<{ data: Buffer; writeTime: number; size: number } | undefined>;
-    set(fileName: string, data: Buffer, config?: WriteConfig): Promise<void>;
+    set(fileName: string, data: Buffer, config?: WriteConfig): Promise<string>;
     del(fileName: string, config?: WriteConfig): Promise<void>;
     getInfo(fileName: string): Promise<{ writeTime: number; size: number } | undefined>;
     findInfo(prefix: string, config?: { shallow?: boolean; type?: "files" | "folders" }): Promise<ArchiveFileInfo[]>;
@@ -127,6 +130,10 @@ export class BlobStore implements IBucketStore {
             onIndexChanged?: (key: string) => void;
             // LRU-bound the disk (base source) to this many bytes; see CommonConfig.readerDiskLimit
             readerDiskLimit?: number;
+            // Deploy takeover: fast-write flush delays never extend past this time, and after it
+            // fast writes flush immediately (nothing may sit in memory when the write window
+            // transfers to the successor process)
+            getFlushDeadline?: () => number | undefined;
         }
     ) { }
 
@@ -231,6 +238,13 @@ export class BlobStore implements IBucketStore {
         this.dirty.set(key, undefined);
     }
 
+    /** Rescans our own disk's metadata into the index - used around deploy switchovers, where the
+     *  other process wrote files to the shared folder that our index hasn't seen. */
+    public async rescanBase(): Promise<void> {
+        await this.init();
+        await this.scanSource(0);
+    }
+
     /** The cheap always-current totals plus any in-progress background synchronization. */
     public getSyncProgress(): {
         index: { fileCount: number; byteCount: number };
@@ -478,6 +492,20 @@ export class BlobStore implements IBucketStore {
         };
         let progressTimer = setInterval(logProgress, SYNC_PROGRESS_LOG_INTERVAL);
         (progressTimer as { unref?: () => void }).unref?.();
+        let slowErrorTimer = setInterval(() => {
+            let elapsed = Date.now() - activity.startTime;
+            let doneFiles = activity.doneFiles || 0;
+            let doneBytes = activity.doneBytes || 0;
+            let bytesPerSecond = doneBytes / (elapsed / 1000);
+            let remainingBytes = totalBytes - doneBytes;
+            let etaText = "unknown (no bytes transferred yet)";
+            if (bytesPerSecond > 0) {
+                let remainingMs = remainingBytes / bytesPerSecond * 1000;
+                etaText = `${formatTime(remainingMs)} remaining, completing around ${new Date(Date.now() + remainingMs).toISOString()}`;
+            }
+            console.error(`Full sync from ${source.getDebugName()} (store ${this.folder}) has been running for ${formatTime(elapsed)}: ${doneFiles}/${pending.length} files (${(doneFiles / pending.length * 100).toFixed(1)}%), ${formatNumber(doneBytes)}B/${formatNumber(totalBytes)}B (${(totalBytes && doneBytes / totalBytes * 100 || 100).toFixed(1)}%), ${formatNumber(bytesPerSecond)}B/s. Estimated ${etaText}.`);
+        }, FULL_SYNC_SLOW_ERROR_INTERVAL);
+        (slowErrorTimer as { unref?: () => void }).unref?.();
         try {
             let nextIndex = 0;
             let failed = false;
@@ -509,6 +537,7 @@ export class BlobStore implements IBucketStore {
             await Promise.all(workers);
         } finally {
             clearInterval(progressTimer);
+            clearInterval(slowErrorTimer);
             this.syncActivities.delete(activity);
             // A sync slow enough to have logged progress also logs its completion
             if (progressLogged) {
@@ -627,7 +656,7 @@ export class BlobStore implements IBucketStore {
         this.setIndexEntry(key, { writeTime: result.writeTime, size: result.data.length, source: 0 });
     }
 
-    public async set(key: string, data: Buffer, config?: WriteConfig): Promise<void> {
+    public async set(key: string, data: Buffer, config?: WriteConfig): Promise<string> {
         await this.init();
         let lastModified = config?.lastModified;
         if (lastModified) {
@@ -636,16 +665,27 @@ export class BlobStore implements IBucketStore {
             let entry = this.mem.get(key);
             let currentTime = overlayEntry && overlayEntry.t || entry && entry.writeTime || 0;
             // An older write never overwrites a newer one (see IArchives.set)
-            if (lastModified < currentTime) return;
+            if (lastModified < currentTime) return key;
         }
         let writeTime = lastModified || Date.now();
         if (config?.fast) {
             let writeDelay = config.writeDelay || DEFAULT_FAST_WRITE_DELAY;
-            this.overlay.set(key, { data, t: writeTime, flushAt: Date.now() + writeDelay });
-            return;
+            let flushAt = Date.now() + writeDelay;
+            let deadline = this.config?.getFlushDeadline?.();
+            if (deadline !== undefined) {
+                if (Date.now() >= deadline) {
+                    this.overlay.delete(key);
+                    await this.writeToSources(key, data, writeTime);
+                    return key;
+                }
+                flushAt = Math.min(flushAt, deadline);
+            }
+            this.overlay.set(key, { data, t: writeTime, flushAt });
+            return key;
         }
         this.overlay.delete(key);
         await this.writeToSources(key, data, writeTime);
+        return key;
     }
 
     public async del(key: string, config?: WriteConfig): Promise<void> {

package/storage/remoteStorage/createArchives.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { IArchives, RemoteConfig, RemoteConfigBase, HostedConfig, BackblazeConfig, ArchiveFileInfo, ArchivesConfig, ArchivesSyncStatus } from "../IArchives";
+import { ServerBucketInfo } from "./storageServerState";
 export declare function createApiArchives(source: HostedConfig | BackblazeConfig): IArchives;
 export declare class ArchivesChain implements IArchives {
     private configured;
@@ -16,9 +17,14 @@ export declare class ArchivesChain implements IArchives {
     private init;
     private buildSources;
     private startConfigPoll;
+    private configRefreshInFlight;
+    private refreshActiveConfig;
+    private fetchLatestConfig;
     private checkForNewConfig;
     private run;
     private runWrite;
+    private lastConfigRefresh;
+    private prepareWrongTargetRetry;
     private request;
     waitingForAccess(): Promise<{
         link: string;
@@ -61,20 +67,14 @@ export declare class ArchivesChain implements IArchives {
     /** True only when EVERY write-receiving source would accept our writes (partial write access
      *  desynchronizes sources, so it counts as no access). */
     hasWriteAccess(): Promise<boolean>;
-    private assertNotBareVariableShard;
+    /** Returns the full key written. Plain keys come back unchanged; keys containing VARIABLE_SHARD
+     *  are automatically materialized (a shard value is picked and embedded, see setVariableShard)
+     *  and the caller needs the returned key to ever read the value back. */
     set(fileName: string, data: Buffer, config?: {
         lastModified?: number;
-    }): Promise<void>;
-    del(fileName: string): Promise<void>;
-    /** Writes a key containing the VARIABLE_SHARD sentinel: picks the lowest-latency up write
-     *  shard, materializes the key with a random value inside that shard's route, writes it, and
-     *  returns the FULL key actually written (the caller needs it to ever read the value back).
-     *  Unlike normal writes this CAN move to another shard when the preferred one is down (error +
-     *  socket down, same rule as reads) - each shard receives a different key, so write
-     *  consistency is preserved. */
-    setVariableShard(key: string, data: Buffer, config?: {
-        lastModified?: number;
     }): Promise<string>;
+    del(fileName: string): Promise<void>;
+    private setVariableShard;
     setLargeFile(config: {
         path: string;
         getNextData(): Promise<Buffer | undefined>;
@@ -83,3 +83,18 @@ export declare class ArchivesChain implements IArchives {
     dispose(): void;
 }
 export declare function createArchives(config: RemoteConfig | RemoteConfigBase): ArchivesChain;
+/** Every bucket an account has on one storage server - active and inactive - with each bucket's
+ *  configuration. One authenticated call (the normal trust system applies): no ArchivesChain, no
+ *  synchronization, and inactive buckets on the server stay inactive. Any URL addressing the
+ *  server works (a bucket routing URL, or just https://host:port). */
+export declare function listServerBuckets(config: {
+    url: string;
+    account: string;
+}): Promise<ServerBucketInfo[]>;
+/** Live info for one bucket given its routing URL (getConfig: routing config, index totals, disk
+ *  limit, in-progress synchronization). One authenticated call to that server - a light, safe
+ *  alternative to instantiating an ArchivesChain, which would start synchronization machinery. */
+export declare function getBucketInfo(config: {
+    url: string;
+    accountName?: string;
+}): Promise<ArchivesConfig>;

package/storage/remoteStorage/createArchives.ts

@@ -1,6 +1,7 @@
 module.allowclient = true;
 
 import { isNode, sort } from "socket-function/src/misc";
+import { delay } from "socket-function/src/batching";
 import {
     IArchives, RemoteConfig, RemoteConfigBase, HostedConfig, BackblazeConfig,
     ArchiveFileInfo, ArchivesConfig, ArchivesSyncStatus, WRITE_PAST_WINDOW_GRACE, STORAGE_WRONG_VALID_WINDOW,
@@ -11,9 +12,11 @@ import {
     normalizeRemoteConfig, normalizeSource, parseRoutingData, serializeRemoteConfig,
     getRoute, routeContains, parseVariableRoute,
 } from "./remoteConfig";
-import { ArchivesRemote } from "./ArchivesRemote";
+import { SocketFunction } from "socket-function/SocketFunction";
+import { ArchivesRemote, parseStorageUrl, authenticateStorage } from "./ArchivesRemote";
 import { ArchivesBackblaze } from "../backblaze";
-import { getStorageServerConfigOptional, getLocalArchives } from "./storageServerState";
+import { getStorageServerConfigOptional, getLocalArchives, ServerBucketInfo } from "./storageServerState";
+import { RemoteStorageController, STORAGE_NOT_AUTHENTICATED } from "./storageController";
 import { SourceWrapper, RETRY_START_DELAY, RETRY_MAX_DELAY, RETRY_GROWTH } from "./sourceWrapper";
 
 // Turns a RemoteConfig into a usable IArchives (createArchives). Initialization is lazy: on the
@@ -26,6 +29,13 @@ import { SourceWrapper, RETRY_START_DELAY, RETRY_MAX_DELAY, RETRY_GROWTH } from
 // rebuild the source list when it changed (reusing wrappers for unchanged sources).
 
 const CONFIG_POLL_INTERVAL = 5 * 60 * 1000;
+// Wrong-valid-window rejections within this distance of a known window boundary are just us racing
+// the boundary itself - waiting fixes them, no new config needed
+const WRONG_TARGET_BOUNDARY_WINDOW = 30 * 1000;
+const WRONG_TARGET_BOUNDARY_RETRY_DELAY = 15 * 1000;
+// Otherwise our config is stale; re-fetch it from the server, at most this often (when throttled,
+// retry with what we have)
+const CONFIG_REFRESH_THROTTLE = 30 * 1000;
 
 // The direct API IArchives for one source, with no URL-form fallback and no chaining. Used by the
 // storage server for its synchronization sources. Denied calls throw immediately (registering the
@@ -239,13 +249,39 @@ export class ArchivesChain implements IArchives {
     private startConfigPoll(): void {
         if (this.pollTimer || this.disposed) return;
         this.pollTimer = setInterval(() => {
-            void this.checkForNewConfig().catch((e: Error) => {
+            void this.refreshActiveConfig().catch((e: Error) => {
                 console.error(`Checking for a new storage routing config failed for ${this.getDebugName()}: ${e.stack ?? e}`);
             });
         }, CONFIG_POLL_INTERVAL);
         (this.pollTimer as { unref?: () => void }).unref?.();
     }
 
+    // Deduplicates concurrent refreshes (the poll timer and wrong-target write retries share this)
+    private configRefreshInFlight: Promise<void> | undefined;
+    private refreshActiveConfig(): Promise<void> {
+        if (!this.configRefreshInFlight) {
+            this.configRefreshInFlight = this.checkForNewConfig().finally(() => {
+                this.configRefreshInFlight = undefined;
+            });
+        }
+        return this.configRefreshInFlight;
+    }
+
+    // The latest config, as the server INTERPRETS it: getConfig carries in-memory overlays (deploy
+    // takeover remaps) that are deliberately never written into the routing file, so it's
+    // preferred over reading the raw file. URL-only chains fall back to the raw file.
+    private async fetchLatestConfig(state: ChainState): Promise<RemoteConfig | undefined> {
+        try {
+            let config = await this.run(state, { apiOnly: true }, archives => archives.getConfig());
+            if (config.remoteConfig) {
+                return normalizeRemoteConfig(config.remoteConfig);
+            }
+        } catch { }
+        let data = await this.run(state, {}, archives => archives.get(ROUTING_FILE));
+        if (!data) return undefined;
+        return parseRoutingData(data);
+    }
+
     private async checkForNewConfig(): Promise<void> {
         if (this.disposed || !this.statePromise) return;
         let state: ChainState;
@@ -255,9 +291,8 @@ export class ArchivesChain implements IArchives {
             // Init is failing; its own retry loop handles that
             return;
         }
-        let data = await this.run(state, {}, archives => archives.get(ROUTING_FILE));
-        if (!data) return;
-        let latest = parseRoutingData(data);
+        let latest = await this.fetchLatestConfig(state);
+        if (!latest) return;
         if (JSON.stringify(latest) === JSON.stringify(state.config)) return;
         console.log(`Storage routing config changed for ${this.getDebugName()}, rebuilding sources`);
         let oldByConfig = new Map(state.sources.map(source => [JSON.stringify(source.config), source]));
@@ -287,7 +322,7 @@ export class ArchivesChain implements IArchives {
     // an application error and throws as-is. A down source gets its background reconnect kicked.
     private async run<T>(state: ChainState, config: { apiOnly?: boolean; write?: boolean; route?: number }, run: (archives: IArchives) => Promise<T>): Promise<T> {
         if (config.write) {
-            return await this.runWrite(state, config.route, run);
+            return await this.runWrite(config.route, run);
         }
         let errors: string[] = [];
         for (let source of state.sources) {
@@ -322,10 +357,11 @@ export class ArchivesChain implements IArchives {
     // scatter its writes across the chain. (Reads fail over freely above: sources are synchronized
     // copies, so reading from any of them is safe.) The one retry is for a window boundary passing
     // (or a route disagreement) mid-write, which re-resolves the target rather than falling back.
-    private async runWrite<T>(state: ChainState, route: number | undefined, run: (archives: IArchives) => Promise<T>): Promise<T> {
+    private async runWrite<T>(route: number | undefined, run: (archives: IArchives) => Promise<T>): Promise<T> {
         let retriedWrongWindow = false;
         let retriedWrongRoute = false;
         while (true) {
+            let state = await this.getState();
             let target = state.sources.find(x => configAcceptsWrites(x.config) && (route === undefined || routeContains(x.config.route, route)));
             if (!target) {
                 throw new Error(`No source accepts writes for ${this.getDebugName()}${route !== undefined && ` (route ${route})` || ""} (every source is outside its valid window or outside the key's route)`);
@@ -340,10 +376,12 @@ export class ArchivesChain implements IArchives {
                 let message = String((e as Error).stack ?? e);
                 if (message.includes(STORAGE_WRONG_VALID_WINDOW) && !retriedWrongWindow) {
                     retriedWrongWindow = true;
+                    await this.prepareWrongTargetRetry(state, "window");
                     continue;
                 }
                 if (message.includes(STORAGE_WRONG_ROUTE) && !retriedWrongRoute) {
                     retriedWrongRoute = true;
+                    await this.prepareWrongTargetRetry(state, "route");
                     continue;
                 }
                 if (!target.isConnected()) {
@@ -354,6 +392,23 @@ export class ArchivesChain implements IArchives {
         }
     }
 
+    private lastConfigRefresh = 0;
+    // A wrong-target rejection means either we raced a window boundary (time fixes it) or our
+    // config is stale - e.g. a deploy-takeover remap that only exists in the server's memory
+    private async prepareWrongTargetRetry(state: ChainState, kind: "window" | "route"): Promise<void> {
+        if (kind === "window") {
+            let now = Date.now();
+            let nearBoundary = state.sources.some(source => source.config.validWindow.some(t => t > 0 && t < Number.MAX_SAFE_INTEGER && Math.abs(t - now) <= WRONG_TARGET_BOUNDARY_WINDOW));
+            if (nearBoundary) {
+                await delay(WRONG_TARGET_BOUNDARY_RETRY_DELAY);
+                return;
+            }
+        }
+        if (Date.now() - this.lastConfigRefresh < CONFIG_REFRESH_THROTTLE) return;
+        this.lastConfigRefresh = Date.now();
+        await this.refreshActiveConfig();
+    }
+
     private async request<T>(config: { apiOnly?: boolean; write?: boolean; route?: number }, run: (archives: IArchives) => Promise<T>): Promise<T> {
         let state = await this.getState();
         return await this.run(state, config, run);
@@ -494,33 +549,26 @@ export class ArchivesChain implements IArchives {
         return true;
     }
 
-    private assertNotBareVariableShard(fileName: string): void {
+    /** Returns the full key written. Plain keys come back unchanged; keys containing VARIABLE_SHARD
+     *  are automatically materialized (a shard value is picked and embedded, see setVariableShard)
+     *  and the caller needs the returned key to ever read the value back. */
+    public async set(fileName: string, data: Buffer, config?: { lastModified?: number }): Promise<string> {
         if (fileName.includes(VARIABLE_SHARD) && parseVariableRoute(fileName) === undefined) {
-            throw new Error(`Keys containing VARIABLE_SHARD must be written with setVariableShard, which materializes the shard value and returns the full key. Key: ${JSON.stringify(fileName)}`);
+            return await this.setVariableShard(fileName, data, config);
         }
-    }
-
-    public async set(fileName: string, data: Buffer, config?: { lastModified?: number }): Promise<void> {
-        this.assertNotBareVariableShard(fileName);
         await this.request({ write: true, route: getRoute(fileName) }, archives => archives.set(fileName, data, config));
+        return fileName;
     }
     public async del(fileName: string): Promise<void> {
         await this.request({ write: true, route: getRoute(fileName) }, archives => archives.del(fileName));
     }
 
-    /** Writes a key containing the VARIABLE_SHARD sentinel: picks the lowest-latency up write
-     *  shard, materializes the key with a random value inside that shard's route, writes it, and
-     *  returns the FULL key actually written (the caller needs it to ever read the value back).
-     *  Unlike normal writes this CAN move to another shard when the preferred one is down (error +
-     *  socket down, same rule as reads) - each shard receives a different key, so write
-     *  consistency is preserved. */
-    public async setVariableShard(key: string, data: Buffer, config?: { lastModified?: number }): Promise<string> {
-        if (!key.includes(VARIABLE_SHARD)) {
-            throw new Error(`Expected the key to contain the VARIABLE_SHARD sentinel, was ${JSON.stringify(key)}`);
-        }
-        if (parseVariableRoute(key) !== undefined) {
-            throw new Error(`The key already has a materialized shard value; write it with set instead. Key: ${JSON.stringify(key)}`);
-        }
+    // Writes a bare variable-shard key: picks the lowest-latency up write shard, materializes the
+    // key with a random value inside that shard's route, writes it, and returns the FULL key
+    // actually written. Unlike normal writes this CAN move to another shard when the preferred one
+    // is down (error + socket down, same rule as reads) - each shard receives a different key, so
+    // write consistency is preserved.
+    private async setVariableShard(key: string, data: Buffer, config?: { lastModified?: number }): Promise<string> {
         let state = await this.getState();
         // Per-shard write consistency still holds: within a route, only the FIRST source may take
         // writes - latency only picks WHICH shard the key materializes into
@@ -558,7 +606,9 @@ export class ArchivesChain implements IArchives {
     }
 
     public async setLargeFile(config: { path: string; getNextData(): Promise<Buffer | undefined> }): Promise<void> {
-        this.assertNotBareVariableShard(config.path);
+        if (config.path.includes(VARIABLE_SHARD) && parseVariableRoute(config.path) === undefined) {
+            throw new Error(`setLargeFile does not support VARIABLE_SHARD keys (there is no way to return the materialized key); write the file with set, or materialize the key yourself. Key: ${JSON.stringify(config.path)}`);
+        }
         let state = await this.getState();
         // Same consistency rule as runWrite: the first currently-valid source for the route, or nothing
         let route = getRoute(config.path);
@@ -610,3 +660,29 @@ export class ArchivesChain implements IArchives {
 export function createArchives(config: RemoteConfig | RemoteConfigBase): ArchivesChain {
     return new ArchivesChain(config);
 }
+
+/** Every bucket an account has on one storage server - active and inactive - with each bucket's
+ *  configuration. One authenticated call (the normal trust system applies): no ArchivesChain, no
+ *  synchronization, and inactive buckets on the server stay inactive. Any URL addressing the
+ *  server works (a bucket routing URL, or just https://host:port). */
+export async function listServerBuckets(config: { url: string; account: string }): Promise<ServerBucketInfo[]> {
+    SocketFunction.ENABLE_CLIENT_MODE = true;
+    let parsed = parseStorageUrl(config.url);
+    let nodeId = SocketFunction.connect({ address: parsed.address, port: parsed.port });
+    let controller = RemoteStorageController.nodes[nodeId];
+    try {
+        return await controller.listBuckets(config.account);
+    } catch (e) {
+        if (!String((e as Error).stack ?? e).includes(STORAGE_NOT_AUTHENTICATED)) throw e;
+        await authenticateStorage({ address: parsed.address, port: parsed.port, nodeId });
+        return await controller.listBuckets(config.account);
+    }
+}
+
+/** Live info for one bucket given its routing URL (getConfig: routing config, index totals, disk
+ *  limit, in-progress synchronization). One authenticated call to that server - a light, safe
+ *  alternative to instantiating an ArchivesChain, which would start synchronization machinery. */
+export async function getBucketInfo(config: { url: string; accountName?: string }): Promise<ArchivesConfig> {
+    let remote = new ArchivesRemote({ url: config.url, accountName: config.accountName, waitForAccess: false });
+    return await remote.getConfig();
+}

package/storage/remoteStorage/deployTakeover.d.ts

@@ -0,0 +1,24 @@
+import { RemoteConfig } from "../IArchives";
+export type TakeoverEvent = "remapChanged" | "diskScan";
+/** Starts the takeover machinery. Returns whether a deploy timeline exists - when it doesn't,
+ *  everything here stays inert (and the caller must NOT fall back to alternate ports, since a busy
+ *  port then means a real misconfiguration, not a deploy). */
+export declare function initDeployTakeover(config: {
+    domain: string;
+    mainPort: number;
+    storageFolder: string;
+}): Promise<boolean>;
+/** Called when we had to listen on an alternate port (the main port was still held by our
+ *  predecessor): registers it so the predecessor can route the middle overlap window to us. */
+export declare function registerAltPort(port: number): Promise<void>;
+export declare function onTakeoverEvent(listener: (event: TakeoverEvent) => void): void;
+/** The interpretation overlay: splits every source pointing at our domain+main port so the middle
+ *  of the deploy overlap points at the alternate port. Pure, in-memory only - the stored routing
+ *  config is never modified, and this must never be applied to data that gets persisted. */
+export declare function applyDeployRemap(routing: RemoteConfig): RemoteConfig;
+/** For the dying process: fast-write flush delays must never extend past this time, and after it
+ *  fast writes flush immediately - so nothing is left in memory when the write window transfers. */
+export declare function getFlushDeadline(): number | undefined;
+/** How long to wait between main-port acquisition attempts: tight around the predecessor's
+ *  scheduled death (when the port actually frees), relaxed otherwise. */
+export declare function getMainPortAcquireDelay(): number;