sliftutils 1.7.87 → 1.7.89

package/storage/remoteStorage/serverConfig.ts

@@ -100,7 +100,7 @@ export function addExtraListenPort(port: number): void {
 export function removeExtraListenPort(port: number): void {
     extraListenPorts.delete(port);
 }
-/** Whether address:port is this server process. The ONE self test - findSelfIndexes, createApiArchives, and SourceWrapper all consult it, so "is this me" cannot disagree between the routing plan and connection building: a URL that is us on an extra listen port must never become a network client to ourselves, which is how infinite self-request loops form. */
+/** Whether address:port is this server process, including its extra listen ports (a deploy switchover's alternate port is still us). Used to tell which config entries are OUR copy of a bucket - the stores we run - as opposed to peers we synchronize with. Talking to ourselves is not one of the things it prevents: a source that happens to be us is reached over the API like any other. */
 export function isOwnAddress(address: string, port: number): boolean {
     let config = getStorageServerConfigOptional();
     if (!config) return false;

package/storage/remoteStorage/sourceWrapper.ts

@@ -6,8 +6,7 @@ import { ROUTING_FILE, getBucketBaseUrl, parseHostedUrl, parseBackblazeUrl, pars
 import { ArchivesRemote } from "./ArchivesRemote";
 import { ArchivesUrl } from "./ArchivesUrl";
 import { ArchivesBackblaze } from "../backblaze";
-import { isOwnAddress } from "./serverConfig";
-import { getLocalArchives } from "./storageServerState";
+import { showCertTrustModal } from "./certTrustModal";
 
 export const RETRY_START_DELAY = 2 * 1000;
 export const RETRY_MAX_DELAY = 5 * 60 * 1000;
@@ -75,12 +74,7 @@ export class SourceWrapper {
             }
             return wrapper;
         }
-        let parsed = parseHostedUrl(config.url);
-        if (isNode() && isOwnAddress(parsed.address, parsed.port)) {
-            // A bucket hosted by our own process - use it directly instead of calling ourselves
-            wrapper.api = getLocalArchives(parsed.account, parsed.bucketName, config);
-            return wrapper;
-        }
+        // A bucket hosted by our own process is reached the same way as any other: over the API, to our own port
         wrapper.remote = new ArchivesRemote({ url: config.url, waitForAccess: false, sourceConfig: config });
         wrapper.api = wrapper.remote;
         if (config.public !== false) {
@@ -128,6 +122,8 @@ export class SourceWrapper {
         let now = Date.now();
         if (now >= this.cooldownUntil && this.isConnectionProblemWorthReporting()) {
             console.error(`Cannot connect to storage ${this.getDebugName()}; skipping it until ${new Date(now + SOURCE_FAILURE_COOLDOWN).toISOString()} (now ${new Date(now).toISOString()}) unless no other source can serve the request`);
+            // In a browser this is often an untrusted (self-signed) certificate the user hasn't accepted yet - offer them the trust flow (a no-op in Node, and shown at most once per server)
+            showCertTrustModal(this.config.url);
         }
         this.cooldownUntil = now + SOURCE_FAILURE_COOLDOWN;
         if (!this.background || this.reconnectRunning) return;

package/storage/remoteStorage/sourcesList.d.ts

@@ -8,8 +8,6 @@ export declare class SourcesList {
     private appendQueue;
     private load;
     getUrl(sourcesListIndex: number): string | undefined;
-    /** For a sourcesListIndex beyond our in-memory list (another process appended since we read): re-reads the file, at most once per RELOAD_THROTTLE. Returning undefined can therefore mean "throttled", not "definitely absent" - never treat it as proof the index is bogus. */
     getUrlReloading(sourcesListIndex: number): Promise<string | undefined>;
-    /** The sourcesListIndex of the url, appending it if it is new. Appends are serialized within this process; before each append the file is re-read, so appends by other processes are picked up instead of duplicated. */
     ensure(url: string): Promise<number>;
 }

package/storage/remoteStorage/sourcesList.ts

@@ -3,7 +3,6 @@ import path from "path";
 
 const RELOAD_THROTTLE = 5 * 1000;
 
-// The persistent identity behind IndexEntry.sourcesListIndex: an append-only file of source URLs / disk folder paths, one per line, where a URL's 0-based line number IS the sourcesListIndex the index persists. Because the file is only ever appended to, a line number means the same URL forever - across restarts and across processes sharing the folder. A torn append (crash mid-write) leaves an unterminated partial line; the next writer terminates it before appending, so the garbage line permanently occupies its index (harmless - it never matches a real URL) and every reader agrees on the numbering.
 export class SourcesList {
     constructor(private filePath: string) { }
     private urls: string[] = [];
@@ -37,7 +36,6 @@ export class SourcesList {
         return this.urls[sourcesListIndex];
     }
 
-    /** For a sourcesListIndex beyond our in-memory list (another process appended since we read): re-reads the file, at most once per RELOAD_THROTTLE. Returning undefined can therefore mean "throttled", not "definitely absent" - never treat it as proof the index is bogus. */
     public async getUrlReloading(sourcesListIndex: number): Promise<string | undefined> {
         if (sourcesListIndex < this.urls.length) return this.urls[sourcesListIndex];
         if (Date.now() - this.lastReload < RELOAD_THROTTLE) return undefined;
@@ -46,7 +44,6 @@ export class SourcesList {
         return this.urls[sourcesListIndex];
     }
 
-    /** The sourcesListIndex of the url, appending it if it is new. Appends are serialized within this process; before each append the file is re-read, so appends by other processes are picked up instead of duplicated. */
     public ensure(url: string): Promise<number> {
         if (url.includes("\n")) {
             throw new Error(`Source URLs cannot contain newlines (they are stored one per line): ${JSON.stringify(url)}`);

package/storage/remoteStorage/spec.md

@@ -14,6 +14,12 @@ If the client tries to do a write where the valid state is far enough away or th
 
 Storage routing JSON is only written to if we have write access and it's only written to on startup, it doesn't propagate. that way things don't revert without the developer intentionally rerunning it. 
 
+## A source's name is the storage; everything else about it is policy
+
+Every source entry carries a name, and that name is the storage it refers to: one folder on the server that holds it, one store, one index. Entries sharing a name (for the same account and bucket) ARE the same storage, however many there are and whatever their windows and routes say — and a request resolves to a store by that name alone, comparing nothing else. Windows and routes are policy layered on top: they decide WHEN a source is written to and WHICH KEYS it takes, and changing them never moves a byte, because they were never what said where the bytes live.
+
+This is why re-routing is safe and free. Previously the folder was derived from the route, so re-sharding renamed the storage under a running server and stranded whatever was in the old folder. Now the route can change as often as you like and the data does not move; if you want data in a different place, you say so by using a different name, which is a decision the developer makes deliberately. The flip side is that names must be treated as permanent identifiers: two unrelated entries sharing a name merge their data, and reusing a retired name hands the new entry the retired one's files. The server does exactly what the name says and does not try to guess.
+
 ## Redundancy, sharding, and deployment
 
 For redundancy, we can just have multiple different configurations that will satisfy the same request. The first one is the one that we write to. If that one's down, we don't do writes.
@@ -22,14 +28,16 @@ However, there's also sharding, where we have different route ranges that values
 
 The valid windows allow us to schedule deployments, so the nodes can switch over gracefully.
 
-## BulkDatabase2 index + our own disk as just another source
+## The index is a Map + a transaction log, and our own disk is just another source
 
-Each bucket's store keeps a BulkDatabase2 index of every file (path, write time, size, holding source), served from memory — existence checks and listings are extremely fast, never touching a source. The trick that keeps the index accurate: our own disk is not special-cased, it is simply the first synchronization source. The same scan/reconcile code that synchronizes remote sources also synchronizes the disk with the index, so the index self-heals from the same machinery instead of needing separate consistency logic.
+Each bucket's store keeps an index of every file (path, write time, size, holding source) as a plain in-memory Map, with an append-only transaction log behind it (LogMap) — one file, one record per set, delete or purge. Deletions live in a second map beside it, holding the time each key was deleted, so a tombstone is not a file with a size of zero that every listing, scan and count has to remember to skip: it is simply not among the files. That also makes expiring them a walk of the tombstones alone. The index takes the time of every change and refuses anything older than what it has, so ordering is decided in one place rather than at each of the paths a write can arrive by — and a write older than the deletion that removed a key cannot bring it back. Existence checks and the file count are Map operations, listings and totals are one pass over memory, and nothing reads a source to answer them. The log is only ever there to rebuild the Map on startup: it is replayed once, and rewritten from the Map whenever it has grown past a few records per surviving value, so rewriting the same keys forever cannot make it grow forever. Appends are coalesced, so a crash can lose the last moment of index changes — which is acceptable precisely because of the section above: a scan reconstructs anything the index is missing. The trick that keeps the index accurate: our own disk is not special-cased, it is simply the first synchronization source. The same scan/reconcile code that synchronizes remote sources also synchronizes the disk with the index, so the index self-heals from the same machinery instead of needing separate consistency logic.
 
 ## Metadata first, data second
 
 We have an index that says where our data is, which we load immediately. Therefore, we can start acting as the authority immediately. And then we do a fast sync based on all of our sources, one of them being a disk source, in order to update this. This means that almost all the time we are immediately ready, and if anything is out of sync, we'll find it as quickly as possible. The index and our syncs just synchronize which files exist, their write times, and their sizes, which is almost always sufficient to characterize a unique state, while being very fast, and supported for all sources (backblaze, etc).
 
+Being the authority means the index IS the answer: a key that is not in it does not exist here, and a read that misses it does nothing special — it does not go poke the sources, and it does not wait. Scans are what fill the index, on their own schedule. Listings are the one exception, and they wait for our own disk's first scan before answering: a single key coming back missing is a miss the caller can retry, but a listing that quietly omits half a folder looks like an answer and gets acted on. The gap this leaves is a store that comes up with files in its folder that its persisted index doesn't know about (another process wrote them), which stay invisible to reads until the disk scan reaches them — and that is fine, because valid windows hand over with notice: a node becomes the write target at a scheduled time, not the moment it starts, so it has finished scanning long before anyone is asking it for those files.
+
 ## Client writes are consistent; client reads are redundant
 
 Clients always write to the same node — the first source whose valid window is current — and if that node is down, the write FAILS rather than going to another node. A client having a network hiccup and wrongly deciding nodes are down must never scatter its writes across the chain; that would desynchronize the sources based on one client's flaky view of the network. Reads, by contrast, fail over freely across every redundant source: sources are synchronized copies, so reading from any of them is safe. Maximum read uptime, strictly consistent writes. (Write redundancy still exists — it just lives server-side: the receiving node fans writes out downstream and reconciliation heals anything missed, all ordered by the once-stamped write time.)
@@ -42,13 +50,19 @@ Machines authenticate with their certs.ts identity (proving ownership of their m
 
     This is our special file that stores the routing information. We write it directly to each node. The client side tries to keep an updated version of these (that's mentioned earlier And is how the client can keep up to date even if the client's code isn't up to date, As long as at least one of the sources is still alive).
 
-    IMPORTANTLY! This special file is never synchronized between different storage nodes. It's only directly written to, and it's only read off of our disk. It can be written to on any node. We don't take into account the valid state window or the shard. We still do take into account the write time, though, the latest write time wins. We only allow writes if version >= the previous version.
+    It is a file IN the store, and the store OWNS it: a store reads its own copy and configures itself from it - its routes, its windows, its flags, and which peers it synchronizes with. A store that has no copy is a complete, working store of just its own disk, valid always, for the whole key space, which is what lets a store exist before it has ever heard of a configuration.
+
+    It propagates by PULL, not push: beside the scan loops, every peer is asked for this one file every five minutes - far more often than a full rescan, because it is small and because it is the file that decides what everything else does. A copy with a greater version is written into our own store as an internal write, exactly like a scan storing anything else it pulled, and the store notices that file landing and re-configures itself. So an operator writing a config and a peer's copy arriving are the same event, and there is one mechanism instead of two. Older or equal versions are ignored, which is what stops a config from ever reverting.
+
+    It is exempt from every check a normal write passes - windows, routes, immutability, internal-write acceptance - because it is the file that DEFINES those things: judging it by the config it is about to replace is how a store gets stuck on a configuration it can never be told to leave. The write time still applies, latest wins.
 
 ## fast writes
 
     We support a flag that does fast writes, which will cause us to batch all the writes in memory, Returning from the set call immediately. This allows you to do many writes to the same file with very little disk I/O. This uses a configurable delay amount. You could set it to zero and then we just won't delay it at all, and we'll flush everything to the disk immediately away. 
 
-    The deploy system will tell us if it's intending to switch over a source, which we use to create a virtual valid state window in the middle that uses a different port. 
+    The delay is a wrapper around ONE source, not a buffer inside the store: a delayed source takes the write into memory, returns, collapses repeated writes to the same path, and serves its own pending writes to anything reading through it. So each source gets its own delay, passed in when it is built — our own disk and our own storage servers take a short one (cross-node redundancy should not wait minutes), an expensive external source like backblaze takes the full one. The store itself has no idea any of this is happening; it writes to its sources and updates its index, and the index records the write when it is accepted, not when it reaches storage.
+
+    The deploy system will tell us if it's intending to switch over a source, which we use to create a virtual valid state window in the middle that uses a different port. That port is only ever a second way to reach a source we already have, so we never scan it (its listing would be the listing we already get from that source) and we never record it as the holder of anything — index entries name the source it was split out of, which outlives it. 
 
     We look at the valid state windows and we make sure we never delay past the valid state window. In fact, if we are within five minutes of being invalid due to the valid state window, we flush the writes immediately. That way, when the next valid window starts running, the writes will be already on disk. 
 

package/storage/remoteStorage/storageController.d.ts

@@ -107,6 +107,13 @@ export declare const RemoteStorageController: import("socket-function/SocketFunc
         lastModified?: number;
         internal?: boolean;
     }) => Promise<void>;
+    move: (config: {
+        account: string;
+        bucketName: string;
+        fromPath: string;
+        toPath: string;
+        sourceConfig: SourceConfig;
+    }) => Promise<void>;
     getInfo: (config: {
         account: string;
         bucketName: string;
@@ -181,6 +188,9 @@ export declare const RemoteStorageController: import("socket-function/SocketFunc
         path: string;
         sourceConfig: SourceConfig;
         lastModified?: number;
+        forceSetImmutable?: boolean;
+        noChecks?: boolean;
+        internal?: boolean;
     }) => Promise<string>;
     uploadPart: (config: {
         uploadId: string;

package/storage/remoteStorage/storageController.ts

@@ -9,13 +9,13 @@ import { getCommonName, getPublicIdentifier, getOwnMachineId, verify, verifyMach
 import { ArchiveFileInfo, ArchivesConfig, ArchivesSyncStatus, FindConfig, SourceConfig, IMMUTABLE_CACHE_TIME } from "../IArchives";
 import { ROUTING_FILE, getRoute, routeContains } from "./remoteConfig";
 import {
-    getLoadedBucket, requireBucket, findBucketStore, readBucketInternal, queueRoutingConfigWrite,
+    getLoadedBucket, requireBucket, findBucketStore, readBucketInternal, writeRoutingConfig,
     getBucketConfig, bucketSyncStatus, bucketIndexTotals, LoadedStore, ActiveBucketInfo,
     listAccountBuckets, ServerBucketInfo, clearAccountWriteStats,
     getActiveBucket, activateBucket, getActiveBucketKeys,
 } from "./storageServerState";
 import { getStorageServerConfig, getTrust, getRequests, assertWritesAllowed } from "./serverConfig";
-import { IBucketStore } from "./blobStore";
+import { BlobStore } from "./blobStore";
 import { getRoutingFileResult } from "./bucketDisk";
 import { StorageClientController } from "./storageClientController";
 import { trackAccess, trackAccessCall, getAccessTotals, readAccessSummaries, clearAccountAccessStats, AccessTotals, AccessSummaryState } from "./accessStats";
@@ -291,7 +291,8 @@ class RemoteStorageControllerBase {
         // Copied because the wire hands us a plain Uint8Array view, not a real Buffer
         let data = Buffer.from(config.data);
         if (config.path === ROUTING_FILE) {
-            return await queueRoutingConfigWrite(config.account, config.bucketName, data, config);
+            // The store the caller selected owns this file: it applies it, enforces the version rule, and its peers pull it from there
+            return await writeRoutingConfig(config.account, config.bucketName, config.sourceConfig.name, data, config);
         }
         await withStore(config, store => store.set({ ...config, data }));
     }
@@ -302,6 +303,15 @@ class RemoteStorageControllerBase {
         await withStore(config, store => store.del(config));
     }
     @assertValidArgs
+    @trackAccessCall("move")
+    async move(config: { account: string; bucketName: string; fromPath: string; toPath: string; sourceConfig: SourceConfig }): Promise<void> {
+        assertWritesAllowed();
+        // assertValidArgs only knows the well-known `path` field, so the two paths of a move are validated here
+        assertValidPath(config.fromPath);
+        assertValidPath(config.toPath);
+        await withStore(config, store => store.move(config));
+    }
+    @assertValidArgs
     @trackAccessCall("getInfo")
     async getInfo(config: { account: string; bucketName: string; path: string; sourceConfig: SourceConfig; includeTombstones?: boolean }): Promise<{ writeTime: number; size: number } | undefined> {
         if (config.path === ROUTING_FILE) {
@@ -370,12 +380,14 @@ class RemoteStorageControllerBase {
     }
 
     @assertValidArgs
-    async startLargeFile(config: { account: string; bucketName: string; path: string; sourceConfig: SourceConfig; lastModified?: number }): Promise<string> {
+    async startLargeFile(config: { account: string; bucketName: string; path: string; sourceConfig: SourceConfig; lastModified?: number; forceSetImmutable?: boolean; noChecks?: boolean; internal?: boolean }): Promise<string> {
         assertWritesAllowed();
         let target = await findBucketStore(config.account, config.bucketName, config.sourceConfig);
-        let id = await target.store.startLargeUpload({ path: config.path, lastModified: config.lastModified });
-        // routeKey pins the upload's parts and finish to the same store the start picked (in-flight uploads survive a bucket rebuild: the part data lives in the store's folder, which a rebuilt store still sees)
-        largeUploadInfo.set(id, { account: config.account, bucketName: config.bucketName, path: config.path, lastModified: config.lastModified, routeKey: target.routeKey });
+        // The store validates the write here, before any bytes move (see BlobStore.startLargeUpload) - a large file is a set, and its SetConfig decides whether it is even allowed
+        let write = { path: config.path, lastModified: config.lastModified, forceSetImmutable: config.forceSetImmutable, noChecks: config.noChecks, internal: config.internal };
+        let id = await target.store.startLargeUpload(write);
+        // The store name pins the upload's parts and finish to the same store the start picked (in-flight uploads survive a bucket rebuild: the part data lives in that store's folder, which a rebuilt store still opens)
+        largeUploadInfo.set(id, { ...write, account: config.account, bucketName: config.bucketName, storeName: target.name });
         return id;
     }
     async uploadPart(config: { uploadId: string; data: Buffer }): Promise<void> {
@@ -392,7 +404,7 @@ class RemoteStorageControllerBase {
         if (!info) throw new Error(`Unknown large upload ${config.uploadId}`);
         largeUploadInfo.delete(config.uploadId);
         let target = await findUploadStore(info);
-        await target.store.finishLargeUpload({ id: config.uploadId, path: info.path, lastModified: info.lastModified });
+        await target.store.finishLargeUpload({ id: config.uploadId, path: info.path, lastModified: info.lastModified, forceSetImmutable: info.forceSetImmutable, noChecks: info.noChecks, internal: info.internal });
     }
     /** Best-effort cleanup: an upload whose bucket or store has since vanished has nothing left to cancel. */
     async cancelLargeFile(config: { uploadId: string }): Promise<void> {
@@ -401,8 +413,8 @@ class RemoteStorageControllerBase {
         largeUploadInfo.delete(config.uploadId);
         let bucket = await getLoadedBucket(info.account, info.bucketName);
         if (!bucket) return;
-        const routeKey = info.routeKey;
-        let target = bucket.stores.find(x => x.routeKey === routeKey);
+        const storeName = info.storeName;
+        let target = bucket.stores.find(x => x.name === storeName);
         if (!target) return;
         await target.store.cancelLargeUpload({ id: config.uploadId });
     }
@@ -442,7 +454,7 @@ class RemoteStorageControllerBase {
         let info: { writeTime: number; size: number } | undefined;
         if (filePath !== ROUTING_FILE) {
             let route = getRoute(filePath);
-            httpStore = bucket.stores.find(s => routeContains(s.route, route));
+            httpStore = bucket.stores.find(s => s.entries.some(e => routeContains(e.route, route)));
             info = httpStore && await httpStore.store.getInfo({ path: filePath }) || undefined;
         } else {
             info = await getRoutingFileResult(account, bucketName);
@@ -509,18 +521,18 @@ class RemoteStorageControllerBase {
 }
 
 /** The one resolution every data call does: the client's selected sourceConfig maps to exactly one store (loading the bucket - and so instantiating its stores - if needed), and fn runs on it. findBucketStore throws for missing buckets and unmatched configs. */
-async function withStore<T>(config: { account: string; bucketName: string; sourceConfig: SourceConfig }, fn: (store: IBucketStore) => Promise<T>): Promise<T> {
+async function withStore<T>(config: { account: string; bucketName: string; sourceConfig: SourceConfig }, fn: (store: BlobStore) => Promise<T>): Promise<T> {
     let target = await findBucketStore(config.account, config.bucketName, config.sourceConfig);
     return await fn(target.store);
 }
 
-const largeUploadInfo = new Map<string, { account: string; bucketName: string; path: string; lastModified?: number; routeKey: string }>();
+const largeUploadInfo = new Map<string, { account: string; bucketName: string; path: string; lastModified?: number; forceSetImmutable?: boolean; noChecks?: boolean; internal?: boolean; storeName: string }>();
 
-async function findUploadStore(info: { account: string; bucketName: string; routeKey: string }): Promise<LoadedStore> {
+async function findUploadStore(info: { account: string; bucketName: string; storeName: string }): Promise<LoadedStore> {
     let bucket = await requireBucket(info.account, info.bucketName);
-    let target = bucket.stores.find(x => x.routeKey === info.routeKey);
+    let target = bucket.stores.find(x => x.name === info.storeName);
     if (!target) {
-        throw new Error(`The store (route ${info.routeKey}) this upload targets no longer exists on bucket ${info.account}/${info.bucketName} (available: ${JSON.stringify(bucket.stores.map(x => x.routeKey))})`);
+        throw new Error(`The store ${JSON.stringify(info.storeName)} this upload targets no longer exists on bucket ${info.account}/${info.bucketName} (available: ${JSON.stringify(bucket.stores.map(x => x.name))})`);
     }
     return target;
 }
@@ -560,6 +572,7 @@ export const RemoteStorageController = SocketFunction.register(
         get2: { hooks: [accountAccess] },
         set: { hooks: [accountAccess] },
         del: { hooks: [accountAccess] },
+        move: { hooks: [accountAccess] },
         getInfo: { hooks: [accountAccess] },
         findInfo: { hooks: [accountAccess] },
         getChangesAfter2: { hooks: [accountAccess] },

package/storage/remoteStorage/storageServer.d.ts

@@ -3,5 +3,7 @@ export type HostStorageServerConfig = {
     url: string;
     folder: string;
     lowSpaceThresholdBytes?: number;
+    internal?: boolean;
+    selfSigned?: boolean;
 };
 export declare function hostStorageServer(config: HostStorageServerConfig): Promise<void>;

package/storage/remoteStorage/storageServer.ts

@@ -19,6 +19,22 @@ 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.
 const HARD_REJECT_FRACTION = 0.1;
 
+// This machine's LAN (internal) IPv4 - the address other machines on the same network reach us at. Used with --internal, where the ip-domain is based on the internal address instead of our public one.
+function getInternalIP(): string {
+    let candidates: string[] = [];
+    for (let addrs of Object.values(os.networkInterfaces())) {
+        for (let addr of addrs || []) {
+            if (addr.family !== "IPv4" || addr.internal) continue;
+            candidates.push(addr.address);
+        }
+    }
+    if (!candidates.length) {
+        throw new Error(`--internal was set, but no non-loopback IPv4 network interface was found to use as the internal address`);
+    }
+    // Prefer a private-range address (the actual LAN ip) over any other non-loopback interface
+    return candidates.find(ip => /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip)) || candidates[0];
+}
+
 // 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 = {
@@ -28,6 +44,10 @@ export type HostStorageServerConfig = {
     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.
     lowSpaceThresholdBytes?: number;
+    // LAN-only mode: do NOT forward ports (no UPnP/NAT mapping), and the ip-domain must be based on this machine's INTERNAL ipv4 (its LAN address) instead of its external ip. For a server other machines only reach over the local network.
+    internal?: boolean;
+    // Serve a self-signed TLS cert signed by this machine's CA, instead of obtaining a real (ACME/Cloudflare) certificate. For a domain we don't control DNS for. Clients trust it by trusting our CA, or by visiting the server once and accepting the certificate in the browser.
+    selfSigned?: boolean;
 };
 
 function formatBytes(bytes: number): string {
@@ -70,11 +90,12 @@ export async function hostStorageServer(config: HostStorageServerConfig): Promis
     let { url, folder } = config;
     let { address: domain, port } = parseStorageUrl(url);
     let rootDomain = domain.split(".").slice(-2).join(".");
-    let externalIP = (await getExternalIP()).trim();
+    // With --internal the ip-domain is based on our LAN address; otherwise on our external ip
+    let ip = config.internal ? getInternalIP() : (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.
-    let allowedDomains = [`127-0-0-1.${rootDomain}`, `${externalIP.replaceAll(".", "-")}.${rootDomain}`];
+    let allowedDomains = [`127-0-0-1.${rootDomain}`, `${ip.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}.`);
+        throw new Error(`The storage server domain is based on the machine's ${config.internal ? "INTERNAL (LAN)" : "external"} IP (the subdomain is the IP with dots replaced by dashes). Expected ${allowedDomains.join(" or ")}, was ${domain}. This machine's ${config.internal ? "internal" : "external"} IP is ${ip}.`);
     }
     await fsp.mkdir(folder, { recursive: true });
     let lowSpaceThreshold = config.lowSpaceThresholdBytes ?? DEFAULT_LOW_SPACE_THRESHOLD_BYTES;
@@ -82,7 +103,7 @@ export async function hostStorageServer(config: HostStorageServerConfig): Promis
         domain,
         port,
         rootDomain,
-        sshTarget: `${os.userInfo().username}@${externalIP}`,
+        sshTarget: `${os.userInfo().username}@${ip}`,
         serverCommand: `node ${getGrantAccessCliPath()} --url ${url}`,
         folder: path.resolve(folder),
     });
@@ -109,6 +130,9 @@ export async function hostStorageServer(config: HostStorageServerConfig): Promis
         domain,
         port,
         setDNSRecord: true,
+        publicIp: ip,
+        internal: config.internal,
+        selfSigned: config.selfSigned,
         portFallback: {
             getAcquireDelay: getMainPortAcquireDelay,
             onPortInUse: async () => {

package/storage/remoteStorage/storageServerCli.ts

@@ -1,5 +1,5 @@
 import { hostStorageServer } from "./storageServer";
-import { getArg } from "./cliArgs";
+import { getArg, getFlag } from "./cliArgs";
 
 // Hosts a storage server from the command line (via the storageserver bin, see package.json).
 
@@ -28,6 +28,10 @@ async function main() {
         url,
         folder,
         lowSpaceThresholdBytes,
+        // Do not forward ports, and base the ip-domain on our internal LAN ip instead of our external ip (for LAN-only servers behind a NAT we can't/won't open)
+        internal: getFlag("internal"),
+        // Serve a self-signed TLS cert signed by this machine's CA instead of getting a real (ACME) one - for servers without a Cloudflare-managed domain. Clients trust it by trusting the CA, or by visiting the server once and accepting the certificate.
+        selfSigned: getFlag("selfSigned"),
     });
 }
 

package/storage/remoteStorage/storageServerState.d.ts

@@ -1,29 +1,37 @@
 /// <reference types="node" />
 /// <reference types="node" />
-import { IBucketStore } from "./blobStore";
+import { BlobStore } from "./blobStore";
 import { RemoteConfig, HostedConfig, SourceConfig, IArchives, ArchivesConfig, ArchivesSyncStatus } from "../IArchives";
 import { BucketDiskInfo } from "./bucketDisk";
 import { SelfSummary } from "./storePlan";
+/**
+ * What this server HAS, as opposed to what any of it does. Four things, and nothing else:
+ *
+ * - the stores, by folder (getStore) - made once, and self-configuring from there
+ * - which of them a request means (findBucketStore), which is only ever a name
+ * - what exists on disk, for listings and for the pages that report it
+ *
+ * It decides nothing about routes, windows or peers - a store reads its own config and works that
+ * out itself (BlobStore.applyRoutingConfig) - and it schedules nothing: switchovers and the handovers
+ * they cause live in intermediateManagement.
+ */
 export type LoadedStore = {
-    routeKey: string;
-    route?: [number, number];
+    name: string;
     entries: HostedConfig[];
     folder: string;
-    store: IBucketStore;
+    store: BlobStore;
 };
 export type BucketState = {
     account: string;
     bucketName: string;
-    routing: RemoteConfig;
-    routingJSON: string;
+    routing?: RemoteConfig;
     selfEntries: HostedConfig[];
     self: SelfSummary | undefined;
     stores: LoadedStore[];
-    structureKey: string;
 };
 /** The loaded bucket, loading it (which instantiates its stores and starts their synchronization) if needed. A bucket that does not exist on this server throws - callers never see undefined buckets. */
 export declare function requireBucket(account: string, bucketName: string): Promise<BucketState>;
-/** The store serving a request: the config entry the CLIENT selected, matched against the bucket's own entries by identity EXCLUDING the valid window (see sourceMatchKey). The selection never validates - the store's own window/route checks throw if the caller is stale - so honoring a window mismatch here is exactly right. Throws when nothing matches, listing what is available. */
+/** The store serving a request: the one the client's selected entry NAMES. Nothing else is compared - not the window, not the route, not the flags - because the name is what says which storage this is, and everything else is policy the store itself applies to the request. A client a config version behind on some flag therefore still reaches the right store, which is the whole point of naming it. */
 export declare function findBucketStore(account: string, bucketName: string, sourceConfig: SourceConfig | undefined): Promise<LoadedStore>;
 /** Internal (store-to-store) reads skip store selection entirely: the caller is another store whose index says this MACHINE holds the bytes - the persisted holder identity is just a URL, which cannot name a store. Whichever store's folder has the newest copy answers. */
 export declare function readBucketInternal(account: string, bucketName: string, config: {
@@ -48,12 +56,25 @@ export declare function bucketIndexTotals(bucket: BucketState): Promise<{
         fileCount: number;
         byteCount: number;
     }[];
-} | undefined>;
+}>;
+/** The bucket states currently in memory - what the switchover machinery walks. Only what is loaded: loading a bucket starts its synchronization, and a bucket nothing has touched has no in-flight writes to hand over anyway. */
+export declare function getBucketStates(): BucketState[];
 /** A cached IArchives for a persisted source identity: a routing URL (hosted/backblaze) or a disk folder path - the form BlobStore's sources list stores. Configuration (valid windows, routes) decides WHEN a source should be used; for reading bytes the index says a source holds, the URL alone is enough - even for sources no longer in any config. */
 export declare function resolveSourceArchives(url: string): IArchives;
+export declare function getStore(account: string, bucketName: string, name: string): BlobStore;
 export declare function getLoadedBucket(account: string, bucketName: string): Promise<BucketState | undefined>;
-/** The routing-config write path - the ONE write that cannot go through a store (it is what CREATES the bucket and its stores). Serialized per bucket: concurrent config writes would race the version check. */
-export declare function queueRoutingConfigWrite(account: string, bucketName: string, data: Buffer, config?: {
+/** Re-reads the bucket off the disk, replacing the cached snapshot: what a routing-config write calls, because that write can CREATE a store (a new name gets a new folder) and the snapshot would keep answering with the stores it saw at load time. Existing stores are reused (getStore caches by folder), so this only picks up folder changes - it never restarts a store. */
+export declare function reloadBucket(account: string, bucketName: string): Promise<BucketState | undefined>;
+/**
+ * Writing the routing config is a write like any other: it goes into a store, and the store applies
+ * it to itself and lets its peers pull it. The only thing that happens here is picking WHICH store,
+ * because the writer names a source and a source names a store.
+ *
+ * In-flight switchover windows are re-injected first (see intermediateManagement): an operator's
+ * config knows nothing about a switchover that is happening right now, and writing it as-is would
+ * cancel it mid-flight.
+ */
+export declare function writeRoutingConfig(account: string, bucketName: string, name: string, data: Buffer, config?: {
     lastModified?: number;
 }): Promise<void>;
 /** Which buckets this process currently has loaded - what a deploy successor asks its predecessor for, so it activates exactly the buckets that are actually in use. */
@@ -61,13 +82,6 @@ export declare function getActiveBucketKeys(): {
     account: string;
     bucketName: string;
 }[];
-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 ServerBucketInfo = {
     bucketName: string;
     active: boolean;
@@ -82,8 +96,8 @@ export type ServerBucketInfo = {
 };
 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;
+    /** The routing config the bucket is RUNNING on, straight from memory - including switchover windows written since it loaded. Absent when none of its stores has one yet. */
+    routing?: RemoteConfig;
     /** Our own entries in that config, and their summarized current role (routes union + flags) */
     selfEntries: HostedConfig[];
     self?: SelfSummary;
@@ -104,4 +118,3 @@ export type BucketWriteStats = {
 };
 /** Zeroes the write statistics of every bucket in the account. */
 export declare function clearAccountWriteStats(account: string): number;
-export declare function getLocalArchives(account: string, bucketName: string, sourceConfig: SourceConfig): IArchives;