sliftutils 1.7.32 → 1.7.33

package/storage/FileFolderAPI.tsx

@@ -39,10 +39,7 @@ const USE_INDEXED_DB = false;
 // How often a worker rechecks the pointer IndexedDB for a granted handle when none is available yet.
 const WORKER_POLL_INTERVAL_MS = 60 * 1000;
 
-// These mirror the subset of the native FileSystemFileHandle / FileSystemDirectoryHandle API we use, so
-// the native browser handles, the Node handles, and the remote handles are all interchangeable — and
-// code written against the native handle (e.g. a recursive walk over `handle.entries()`) works on any of
-// them. kind/name and entries() are part of that contract.
+// These mirror the subset of the native FileSystemFileHandle / FileSystemDirectoryHandle API we use, so the native browser handles, the Node handles, and the remote handles are all interchangeable — and code written against the native handle (e.g. a recursive walk over `handle.entries()`) works on any of them. kind/name and entries() are part of that contract.
 export type FileWrapper = {
     readonly kind: "file";
     readonly name: string;
@@ -59,19 +56,15 @@ export type FileWrapper = {
         write(value: Buffer): Promise<void>;
         close(): Promise<void>;
     }>;
-    // Returns a URL for the file's bytes, usable in <video>/<img>/fetch. Optional — the native browser
-    // FileSystemFileHandle has no such method, so prefer the getFileURL() helper, which falls back to a
-    // blob: URL via createObjectURL for native handles. Always release it with disposeFileURL when done.
+    // Returns a URL for the file's bytes, usable in <video>/<img>/fetch. Optional — the native browser FileSystemFileHandle has no such method, so prefer the getFileURL() helper, which falls back to a blob: URL via createObjectURL for native handles. Always release it with disposeFileURL when done.
     getURL?(): Promise<string>;
 };
 export type DirectoryWrapper = {
     readonly kind: "directory";
     readonly name: string;
-    // Full path from the storage root, for diagnostics/logging (the native handle doesn't expose paths,
-    // so it's optional). e.g. "bulkDatabases2/myCollection".
+    // Full path from the storage root, for diagnostics/logging (the native handle doesn't expose paths, so it's optional). e.g. "bulkDatabases2/myCollection".
     readonly fullPath?: string;
-    // True when this storage is served over the network (a remote server) rather than a local disk, so
-    // callers can adapt for the higher latency/cost (local/native handles leave it undefined = false).
+    // True when this storage is served over the network (a remote server) rather than a local disk, so callers can adapt for the higher latency/cost (local/native handles leave it undefined = false).
     readonly isRemote?: boolean;
     removeEntry(key: string, options?: { recursive?: boolean }): Promise<void>;
     getFileHandle(key: string, options?: { create?: boolean }): Promise<FileWrapper>;
@@ -107,8 +100,7 @@ export function setStorageRootOverride(handle: FileSystemDirectoryHandle | undef
 }
 
 // ---- remote (server) storage config ----
-// Instead of a local folder, the user can point at a remoteFileServer.js instance (URL + password).
-// When configured, getFileStorageNested2 serves everything from that server. Persisted in localStorage.
+// Instead of a local folder, the user can point at a remoteFileServer.js instance (URL + password). When configured, getFileStorageNested2 serves everything from that server. Persisted in localStorage.
 type RemoteConfig = { url: string; password: string };
 function remoteConfigKey() { return getFileAPIKey() + ":remote"; }
 function loadRemoteConfig(): RemoteConfig | undefined {
@@ -122,8 +114,7 @@ function loadRemoteConfig(): RemoteConfig | undefined {
 }
 function saveRemoteConfig(c: RemoteConfig) { localStorage.setItem(remoteConfigKey(), JSON.stringify(c)); }
 
-// The server is always HTTPS on the filehoster's default port, so the user only needs to type the host
-// (e.g. "65.109.93.113"). We strip any scheme/path they include and default the port if omitted.
+// The server is always HTTPS on the filehoster's default port, so the user only needs to type the host (e.g. "65.109.93.113"). We strip any scheme/path they include and default the port if omitted.
 const DEFAULT_REMOTE_PORT = 8787; // matches remoteFileServer.js's default
 function normalizeServerUrl(raw: string): string {
     let s = raw.trim().replace(/^\w+:\/\//, "").replace(/\/.*$/, "");
@@ -160,11 +151,7 @@ class DirectoryPrompter extends preact.Component {
     }
 }
 
-// "Connect to a server" option for the directory prompt: collapses to a button, expands to address +
-// password fields. On connect it ACTUALLY connects (testRemoteConnection); only on success does it
-// persist the config and call onConnected, so the caller (getDirectoryHandle) resolves with a working
-// remote handle. Failures are shown to the user (and logged, without the password), never swallowed.
-// `initial` pre-fills + expands the form (used to retry a remembered server that stopped working).
+// "Connect to a server" option for the directory prompt: collapses to a button, expands to address + password fields. On connect it ACTUALLY connects (testRemoteConnection); only on success does it persist the config and call onConnected, so the caller (getDirectoryHandle) resolves with a working remote handle. Failures are shown to the user (and logged, without the password), never swallowed. `initial` pre-fills + expands the form (used to retry a remembered server that stopped working).
 @observer
 class ServerConnectForm extends preact.Component<{ onConnected: (config: RemoteConfig) => void; initial?: RemoteConfig }> {
     private obs = observable({
@@ -193,8 +180,7 @@ class ServerConnectForm extends preact.Component<{ onConnected: (config: RemoteC
                 s.error = "The server rejected that password.";
                 console.error("Remote connect: unauthorized for", url);
             } else {
-                // Got nothing back — usually the self-signed certificate isn't trusted yet, but show the
-                // actual error too so a wrong address / down server / CORS issue is diagnosable.
+                // Got nothing back — usually the self-signed certificate isn't trusted yet, but show the actual error too so a wrong address / down server / CORS issue is diagnosable.
                 s.needsCert = true;
                 s.error = "Couldn't reach the server: " + result.error;
                 console.error("Remote connect: unreachable", url, "-", result.error);
@@ -343,9 +329,7 @@ export class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
             // Create the file
             await fs.promises.writeFile(filePath, Buffer.alloc(0));
         } else if (!exists) {
-            // Tag as ENOENT so readWithRetry treats it as a genuinely-missing file (return undefined now)
-            // rather than a transient read failure to retry 6× with backoff — missing files are normal
-            // (a concurrent merge deletes a file mid-read), and retrying them is catastrophically slow.
+            // Tag as ENOENT so readWithRetry treats it as a genuinely-missing file (return undefined now) rather than a transient read failure to retry 6× with backoff — missing files are normal (a concurrent merge deletes a file mid-read), and retrying them is catastrophically slow.
             const err = new Error(`File not found: ${filePath}`) as Error & { code?: string };
             err.code = "ENOENT";
             throw err;
@@ -387,9 +371,7 @@ export class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
 }
 
 
-// When set, getDirectoryHandle skips every prompt + remote check and serves from the browser's Origin
-// Private File System (OPFS). One named subfolder is "current" per fileAPIKey; pickPrivateFolder /
-// resetStorageLocation switch which one. Set this in app startup BEFORE the first getDirectoryHandle.
+// When set, getDirectoryHandle skips every prompt + remote check and serves from the browser's Origin Private File System (OPFS). One named subfolder is "current" per fileAPIKey; pickPrivateFolder / resetStorageLocation switch which one. Set this in app startup BEFORE the first getDirectoryHandle.
 let opfsEnabled = false;
 const OPFS_FOLDERS_DIR = "folders";
 const OPFS_DEFAULT_FOLDER = "default";
@@ -401,14 +383,12 @@ function setCurrentOpfsFolder(name: string): void {
     localStorage.setItem(opfsCurrentKey(), name);
 }
 
-// Switches getDirectoryHandle to the Origin Private File System. No directory picker, no permission
-// prompt, no remote server check. Persists nothing — call on every app start before reading storage.
+// Switches getDirectoryHandle to the Origin Private File System. No directory picker, no permission prompt, no remote server check. Persists nothing — call on every app start before reading storage.
 export function usePrivateFileSystem(): void {
     opfsEnabled = true;
 }
 
-// Whether the OPFS branch is in effect (so other callers can adapt — e.g. skip the "find data subdir"
-// hack in getFileStorageNested2 since OPFS is always a clean root we own end-to-end).
+// Whether the OPFS branch is in effect (so other callers can adapt — e.g. skip the "find data subdir" hack in getFileStorageNested2 since OPFS is always a clean root we own end-to-end).
 export function isPrivateFileSystemActive(): boolean {
     return opfsEnabled;
 }
@@ -431,9 +411,7 @@ async function getCurrentOpfsHandle(): Promise<DirectoryWrapper> {
     return folder as unknown as DirectoryWrapper;
 }
 
-// All previously-used OPFS subfolders under this fileAPIKey, sorted alphabetically (timestamp-named
-// auto-generated folders therefore sort chronologically). Use this to surface a list, then call
-// pickPrivateFolder(name) to switch.
+// All previously-used OPFS subfolders under this fileAPIKey, sorted alphabetically (timestamp-named auto-generated folders therefore sort chronologically). Use this to surface a list, then call pickPrivateFolder(name) to switch.
 export async function listPrivateFolders(): Promise<string[]> {
     if (!navigator.storage?.getDirectory) return [];
     let folders: FileSystemDirectoryHandle;
@@ -445,17 +423,13 @@ export async function listPrivateFolders(): Promise<string[]> {
     return names.sort();
 }
 
-// Switch to a specific OPFS subfolder and reload so getDirectoryHandle re-resolves to it. The folder
-// is created if it doesn't exist yet.
+// Switch to a specific OPFS subfolder and reload so getDirectoryHandle re-resolves to it. The folder is created if it doesn't exist yet.
 export function pickPrivateFolder(name: string): void {
     setCurrentOpfsFolder(name);
     window.location.reload();
 }
 
-// Returns the directory handle to use — local (Node / picked folder) OR a remote server, both as the
-// same DirectoryWrapper, so callers don't know or care which it is. A remembered server is VERIFIED
-// (we actually connect) before use; if it no longer works we re-prompt, just like a local folder whose
-// permission was lost. Blocks until ready (or the user dismisses, which rejects).
+// Returns the directory handle to use — local (Node / picked folder) OR a remote server, both as the same DirectoryWrapper, so callers don't know or care which it is. A remembered server is VERIFIED (we actually connect) before use; if it no longer works we re-prompt, just like a local folder whose permission was lost. Blocks until ready (or the user dismisses, which rejects).
 export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Promise<DirectoryWrapper> {
     // An injected root (e.g. a Web Worker handed the handle by its owning window)
     // short-circuits the whole interactive resolution — no picker, no DOM, no
@@ -463,12 +437,7 @@ export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Prom
     if (storageRootOverride) {
         return storageRootOverride as unknown as DirectoryWrapper;
     }
-    // A worker can't show the picker (no DOM / no user activation) and can't read localStorage, but
-    // it CAN open the pointer IndexedDB the main-thread picker persists to. Poll it for a handle
-    // whose permission is already granted; the owning window may also postMessage a handle in
-    // mid-poll (checked each iteration). This has to come before the isNode branch: typesafecss's
-    // isNode() returns true in workers (window is undefined), so a worker would otherwise fall into
-    // the Node branch and try to use fs/path.
+    // A worker can't show the picker (no DOM / no user activation) and can't read localStorage, but it CAN open the pointer IndexedDB the main-thread picker persists to. Poll it for a handle whose permission is already granted; the owning window may also postMessage a handle in mid-poll (checked each iteration). This has to come before the isNode branch: typesafecss's isNode() returns true in workers (window is undefined), so a worker would otherwise fall into the Node branch and try to use fs/path.
     if ("WorkerGlobalScope" in globalThis) {
         while (true) {
             if (storageRootOverride) return storageRootOverride as unknown as DirectoryWrapper;
@@ -512,8 +481,7 @@ export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Prom
             }
         };
         const onConnected = (config: RemoteConfig) => { saveRemoteConfig(config); resolveHandle(getRemoteHandle(config)); };
-        // The three options, rendered fresh each time. If a saved server just failed, pre-fill + expand
-        // the connect form so the user can retry or fix it.
+        // The three options, rendered fresh each time. If a saved server just failed, pre-fill + expand the connect form so the user can retry or fix it.
         const renderOptions = () => (
             <>
                 <button className={css.fontSize(40).pad2(80, 40)} onClick={pickLocal}>Pick Data Directory</button>
@@ -523,8 +491,7 @@ export const getDirectoryHandle = lazy(async function getDirectoryHandle(): Prom
             </>
         );
 
-        // A previously-picked local folder: try to restore it (may need a click). Skipped when a saved
-        // server failed — that user wants the server, so go straight to the (pre-filled) prompt.
+        // A previously-picked local folder: try to restore it (may need a click). Skipped when a saved server failed — that user wants the server, so go straight to the (pre-filled) prompt.
         const storedId = !savedRemote && localStorage.getItem(getFileAPIKey());
         if (storedId) {
             let doneLoad = false;
@@ -582,8 +549,7 @@ export const getFileStorageNested2 = cache(async function getFileStorage(pathStr
         base = new NodeJSDirectoryHandleWrapper(path.resolve("./data/"));
     } else {
         base = await getDirectoryHandle();
-        // Skip the "find data subdir" hack under OPFS — that's for picked directories where the user
-        // might have selected a folder with unrelated files; OPFS is a clean root we own end-to-end.
+        // Skip the "find data subdir" hack under OPFS — that's for picked directories where the user might have selected a folder with unrelated files; OPFS is a clean root we own end-to-end.
         if (!opfsEnabled) {
             let dirs: string[] = [];
             let alls: string[] = [];
@@ -614,8 +580,7 @@ export const getFileStorage = lazy(async function getFileStorage(): Promise<File
 });
 export function resetStorageLocation() {
     if (opfsEnabled) {
-        // Don't delete previous folder — listPrivateFolders / pickPrivateFolder still need it. Just point
-        // "current" at a fresh timestamp-named one so the next reload starts clean.
+        // Don't delete previous folder — listPrivateFolders / pickPrivateFolder still need it. Just point "current" at a fresh timestamp-named one so the next reload starts clean.
         setCurrentOpfsFolder(new Date().toISOString().replace(/[:.]/g, "-"));
         window.location.reload();
         return;
@@ -634,8 +599,7 @@ export type NestedFileStorage = {
 
 export type FileStorage = IStorageRaw & {
     folder: NestedFileStorage;
-    // Mirrors DirectoryWrapper.isRemote: true when this storage is served over the network. Lets callers
-    // (e.g. BulkDatabase2, which skips automatic compaction over the network by default) adapt.
+    // Mirrors DirectoryWrapper.isRemote: true when this storage is served over the network. Lets callers (e.g. BulkDatabase2, which skips automatic compaction over the network by default) adapt.
     isRemote?: boolean;
 };
 
@@ -671,8 +635,7 @@ async function fixedGetFileHandle(config: {
     return await config.handle.getFileHandle(config.key, { create: true });
 }
 
-// A file that genuinely does not exist. We must NOT retry these, otherwise reading many missing
-// files (a common pattern) gets catastrophically slow.
+// A file that genuinely does not exist. We must NOT retry these, otherwise reading many missing files (a common pattern) gets catastrophically slow.
 function isMissingError(error: unknown): boolean {
     let name = (error as { name?: string })?.name;
     let code = (error as { code?: string })?.code;
@@ -681,10 +644,7 @@ function isMissingError(error: unknown): boolean {
 
 const MAX_READ_RETRIES = 6;
 
-// The browser File System Access API can transiently fail reads under heavy load (it appears to
-// throttle when a page issues many reads at once). Those failures surface as errors OTHER than
-// "not found", so we retry them with backoff. A real missing file (NotFoundError / ENOENT) returns
-// undefined immediately with no retry.
+// The browser File System Access API can transiently fail reads under heavy load (it appears to throttle when a page issues many reads at once). Those failures surface as errors OTHER than "not found", so we retry them with backoff. A real missing file (NotFoundError / ENOENT) returns undefined immediately with no retry.
 async function readWithRetry<T>(label: string, key: string, read: () => Promise<T>): Promise<T | undefined> {
     let backoff = 25;
     for (let attempt = 0; ; attempt++) {
@@ -724,8 +684,7 @@ function wrapHandleFiles(handle: DirectoryWrapper): IStorageRaw {
                 const file = await handle.getFileHandle(key);
                 const fileContent = await file.getFile();
                 const arrayBuffer = await fileContent.arrayBuffer();
-                // Under load the FS Access API can resolve with a truncated buffer and no error.
-                //  Treat a short read as transient so readWithRetry retries it.
+                // Under load the FS Access API can resolve with a truncated buffer and no error. Treat a short read as transient so readWithRetry retries it.
                 if (arrayBuffer.byteLength !== fileContent.size) {
                     throw Object.assign(new Error(`Short read: got ${arrayBuffer.byteLength} of ${fileContent.size} bytes`), { name: "ShortReadError" });
                 }
@@ -749,8 +708,7 @@ function wrapHandleFiles(handle: DirectoryWrapper): IStorageRaw {
 
         async append(key: string, value: Buffer): Promise<void> {
             await appendQueue(key)(async () => {
-                // NOTE: Interesting point. Chrome doesn't optimize this to be an append, and instead
-                //  rewrites the entire file.
+                // NOTE: Interesting point. Chrome doesn't optimize this to be an append, and instead rewrites the entire file.
                 const file = await fixedGetFileHandle({ handle, key, create: true });
                 const writable = await file.createWritable({ keepExistingData: true });
                 let offset = (await file.getFile()).size;
@@ -837,10 +795,7 @@ export function wrapHandle(handle: DirectoryWrapper): FileStorage {
     };
 }
 
-// Returns a URL for a file's bytes, ready to drop into <video>/<img>/fetch. A native (local) file becomes
-// an in-memory blob: URL; a remote file becomes an https URL into the server's range-capable /media
-// endpoint (auth token in the query, since a media element can't send headers). Both support HTTP range /
-// seeking. ALWAYS hand the result to disposeFileURL when finished — for blob: URLs that frees memory.
+// Returns a URL for a file's bytes, ready to drop into <video>/<img>/fetch. A native (local) file becomes an in-memory blob: URL; a remote file becomes an https URL into the server's range-capable /media endpoint (auth token in the query, since a media element can't send headers). Both support HTTP range / seeking. ALWAYS hand the result to disposeFileURL when finished — for blob: URLs that frees memory.
 export async function getFileURL(file: FileWrapper): Promise<string> {
     if (file.getURL) return file.getURL();
     // Native FileSystemFileHandle (or any Blob-backed file): a blob: URL over the File itself.
@@ -848,16 +803,14 @@ export async function getFileURL(file: FileWrapper): Promise<string> {
     return URL.createObjectURL(f as unknown as Blob);
 }
 
-// Releases a URL from getFileURL. blob: URLs leak until the document is gone unless revoked; https/file:
-// URLs need no cleanup, so this is a no-op for them.
+// Releases a URL from getFileURL. blob: URLs leak until the document is gone unless revoked; https/file: URLs need no cleanup, so this is a no-op for them.
 export function disposeFileURL(url: string): void {
     if (url.startsWith("blob:")) {
         try { URL.revokeObjectURL(url); } catch { /* not in a browser, or already revoked */ }
     }
 }
 
-// A StorageFactory backed by a remote server (path -> FileStorage), for code that injects its own
-// storage into BulkDatabase2 rather than going through the directory prompt.
+// A StorageFactory backed by a remote server (path -> FileStorage), for code that injects its own storage into BulkDatabase2 rather than going through the directory prompt.
 export function getRemoteFileStorageFactory(url: string, password: string, options?: RemoteOptions): (pathStr: string) => Promise<FileStorage> {
     const root = getRemoteDirectoryHandle(url, password, options);
     return async (pathStr: string) => {

package/storage/IArchives.d.ts

@@ -28,11 +28,12 @@ export type CommonConfig = {
     validWindow: [number, number];
     /** Sharding: the fraction of the key space this source handles, as [start, end) over [0, 1) (keys are routed by getRoute in remoteConfig.ts). Defaults to FULL_ROUTE (unsharded). At every point in time the sources' routes must fully cover [0, 1), or some keys could never be read. */
     route?: [number, number];
+    /** Set on entries injected into the in-memory config by an overlay (a deploy switchover's alternate-port window). Never written to disk: resolveIntermediateSources strips these and rejoins the windows around them, which is also how a client tells whether an update is a real configuration change or just an overlay. */
+    intermediate?: boolean;
 };
 export type HostedConfig = CommonConfig & {
     type: "remote";
     url: string;
-    accountName?: string;
     public?: boolean;
     fast?: boolean;
     writeDelay?: number;
@@ -104,8 +105,7 @@ export type ArchivesSyncStatus = {
 };
 export interface IArchives {
     getDebugName(): string;
-    /** Whether writes would be accepted (credentials exist, the account trusts this machine, etc).
-     *  Checked without writing anything. */
+    /** Whether writes would be accepted (credentials exist, the account trusts this machine, etc). Checked without writing anything. */
     hasWriteAccess(): Promise<boolean>;
     get(fileName: string, config?: {
         range?: {

package/storage/IArchives.ts

@@ -1,14 +1,11 @@
 module.allowclient = true;
 
-// The important operations of an archive bucket (extracted from ArchivesBackblaze), so other
-// backends (e.g. our own remote storage server) can be used interchangeably.
+// The important operations of an archive bucket (extracted from ArchivesBackblaze), so other backends (e.g. our own remote storage server) can be used interchangeably.
 
-// A write may not be stamped more than this far in the future, or clock skew between machines
-// would let a bad timestamp block writes for a long time.
+// A write may not be stamped more than this far in the future, or clock skew between machines would let a bad timestamp block writes for a long time.
 export const MAX_LAST_MODIFIED_FUTURE = 15 * 60 * 1000;
 
-// How long browsers may cache files from immutable buckets (the Cache-Control max-age), shared by
-// every hosting path (backblaze bucket settings and our own storage server's HTTP route)
+// How long browsers may cache files from immutable buckets (the Cache-Control max-age), shared by every hosting path (backblaze bucket settings and our own storage server's HTTP route)
 export const IMMUTABLE_CACHE_TIME = 86400 * 1000;
 export function assertValidLastModified(lastModified: number): void {
     let max = Date.now() + MAX_LAST_MODIFIED_FUTURE;
@@ -46,6 +43,8 @@ export type CommonConfig = {
     validWindow: [number, number];
     /** Sharding: the fraction of the key space this source handles, as [start, end) over [0, 1) (keys are routed by getRoute in remoteConfig.ts). Defaults to FULL_ROUTE (unsharded). At every point in time the sources' routes must fully cover [0, 1), or some keys could never be read. */
     route?: [number, number];
+    /** Set on entries injected into the in-memory config by an overlay (a deploy switchover's alternate-port window). Never written to disk: resolveIntermediateSources strips these and rejoins the windows around them, which is also how a client tells whether an update is a real configuration change or just an overlay. */
+    intermediate?: boolean;
 };
 
 export type HostedConfig = CommonConfig & {
@@ -56,16 +55,12 @@ export type HostedConfig = CommonConfig & {
     url: string;
 
     // NOTE: Authentication is handled by cert.ts, via having your machine trusted to access this account. 
-    accountName?: string;
 
     public?: boolean;
-    // Fast mode: the server acknowledges writes once they are in memory, flushing to disk after
-    // writeDelay (default 5 minutes) and coalescing writes to the same file. A server crash loses
-    // writes that haven't flushed yet.
+    // Fast mode: the server acknowledges writes once they are in memory, flushing to disk after writeDelay (default 5 minutes) and coalescing writes to the same file. A server crash loses writes that haven't flushed yet.
     fast?: boolean;
     writeDelay?: number;
-    // The bucket is served straight from the server's disk, with no index — so no fast writes and
-    // no getChangesAfter/getSyncStatus.
+    // The bucket is served straight from the server's disk, with no index — so no fast writes and no getChangesAfter/getSyncStatus.
     rawDisk?: boolean;
     // Writes to paths that already exist are disallowed (deletes still work).
     immutable?: boolean;
@@ -81,9 +76,7 @@ export type BackblazeConfig = CommonConfig & {
     // NOTE: This isn't enforced on the backblaze level, so this is just a client-side guarantee. This can change how we cache files.
     //  - Backblaze does support immutability. However, apparently, once we enable it on a bucket, we can't disable it, which is really bad, as it means if our code could ever enable it and we accidentally enable it on an important bucket, we essentially just bricked that bucket. So we should never write any code that ever tries to use backblaze to make things immutable. 
     immutable?: boolean;
-    // CORS origins allowed to consume the bucket's files in a browser. Not a security boundary
-    // (access is gated by the API key / signed URLs, neither of which rides in cookies) - it only
-    // controls which sites' in-page JavaScript can read responses. Defaults to any HTTPS origin.
+    // CORS origins allowed to consume the bucket's files in a browser. Not a security boundary (access is gated by the API key / signed URLs, neither of which rides in cookies) - it only controls which sites' in-page JavaScript can read responses. Defaults to any HTTPS origin.
     allowedOrigins?: string[];
 
     // NOTE: We will access the api key from getSecret, see backblaze.ts for the specific keys.
@@ -95,16 +88,12 @@ export const FULL_VALID_WINDOW: [number, number] = [0, Number.MAX_SAFE_INTEGER];
 
 
 
-// createTime is a misnomer kept for compatibility — it is really the LAST-WRITE time, same as
-// getInfo's writeTime. Neither Backblaze nor our remote storage tracks a distinct creation date:
-// each write stamps a fresh timestamp on the current version, so both fields are just "when the
-// bytes served by get() were most recently written".
+// createTime is a misnomer kept for compatibility — it is really the LAST-WRITE time, same as getInfo's writeTime. Neither Backblaze nor our remote storage tracks a distinct creation date: each write stamps a fresh timestamp on the current version, so both fields are just "when the bytes served by get() were most recently written".
 export type ArchiveFileInfo = { path: string; createTime: number; size: number };
 
 // An in-progress background synchronization task (see ArchivesConfig.syncing)
 export type SyncActivity = {
-    // A metadata scan is a single listing call, so it has no incremental progress - just that it's
-    // running and since when. A full sync knows its exact file/byte progress.
+    // A metadata scan is a single listing call, so it has no incremental progress - just that it's running and since when. A full sync knows its exact file/byte progress.
     type: "metadataScan" | "fullSync";
     sourceDebugName: string;
     startTime: number;
@@ -117,14 +106,11 @@ export type SyncActivity = {
 export type ArchivesConfig = {
     // Whether getChangesAfter is implemented (fast change polling, instead of full rescans)
     supportsChangesAfter?: boolean;
-    // The bucket's full routing config (ROUTING_FILE). Absent for sources that don't have one (a
-    // bare disk source, or a bucket that doesn't exist yet).
+    // The bucket's full routing config (ROUTING_FILE). Absent for sources that don't have one (a bare disk source, or a bucket that doesn't exist yet).
     remoteConfig?: RemoteConfig;
-    // Live index totals (tombstones excluded), kept up to date in memory on every mutation and
-    // recomputed on load - so any drift heals on restart
+    // Live index totals (tombstones excluded), kept up to date in memory on every mutation and recomputed on load - so any drift heals on restart
     index?: { fileCount: number; byteCount: number };
-    // The same totals broken down by which source currently holds each file's bytes (the first
-    // entry is the server's own disk)
+    // The same totals broken down by which source currently holds each file's bytes (the first entry is the server's own disk)
     indexSources?: { debugName: string; fileCount: number; byteCount: number }[];
     // The server's configured readerDiskLimit, when it runs as a bounded read cache
     readerDiskLimit?: number;
@@ -135,41 +121,27 @@ export type ArchivesConfig = {
 // A synchronization source of a BlobStore (which synchronizes an index + local cache from them)
 export type ArchivesSource = {
     source: IArchives;
-    // From the source's CommonConfig. Values with write times outside the window are ignored when
-    // scanning, and once its end is past (see windowAcceptsWrites) the source stops
-    // receiving writes entirely - still scanned (it holds the authoritative data for its window),
-    // it just stops growing.
+    // From the source's CommonConfig. Values with write times outside the window are ignored when scanning, and once its end is past (see windowAcceptsWrites) the source stops receiving writes entirely - still scanned (it holds the authoritative data for its window), it just stops growing.
     validWindow: [number, number];
-    // From the source's CommonConfig (intersected with the owning store's own route): only keys
-    // routing into [start, end) are accepted from this source's scans and sent to it in
-    // writes/reconciliation. The routing file is exempt - config flows everywhere. Absent = all keys.
+    // From the source's CommonConfig (intersected with the owning store's own route): only keys routing into [start, end) are accepted from this source's scans and sent to it in writes/reconciliation. The routing file is exempt - config flows everywhere. Absent = all keys.
     route?: [number, number];
     // From the source's CommonConfig; see there.
     noFullSync?: boolean;
-    // Stable identity of the underlying endpoint (its config with windows/routes stripped) - how
-    // BlobStore.updateSources recognizes a source across config changes so it can update it in
-    // place instead of removing and re-adding it
+    // Stable identity of the underlying endpoint (its config with windows/routes stripped) - how BlobStore.updateSources recognizes a source across config changes so it can update it in place instead of removing and re-adding it
     identity?: string;
 };
 
-// Error marker a server includes when a freshly-stamped write reaches it outside its valid windows
-// (the client resolved its target, then time crossed a window boundary before the write landed).
-// Clients detect this marker and re-resolve the currently-valid source, retrying ONCE - boundaries
-// are far apart, so hitting it twice in one attempt means something is actually wrong.
+// Error marker a server includes when a freshly-stamped write reaches it outside its valid windows (the client resolved its target, then time crossed a window boundary before the write landed). Clients detect this marker and re-resolve the currently-valid source, retrying ONCE - boundaries are far apart, so hitting it twice in one attempt means something is actually wrong.
 export const STORAGE_WRONG_VALID_WINDOW = "REMOTE_STORAGE_WRONG_VALID_WINDOW_a7c1f04e";
 
-// Error marker a server includes when a freshly-stamped write's key routes outside the shards this
-// server handles (the client's config disagrees with the server's - clients re-resolve once)
+// Error marker a server includes when a freshly-stamped write's key routes outside the shards this server handles (the client's config disagrees with the server's - clients re-resolve once)
 export const STORAGE_WRONG_ROUTE = "REMOTE_STORAGE_WRONG_ROUTE_c94d2e17";
 
 export const FULL_ROUTE: [number, number] = [0, 1];
 
-// A key containing this sentinel doesn't have a fixed shard: setVariableShard picks the (lowest
-// latency, up) write shard, appends "_<value in the shard's route>" directly after the sentinel,
-// and returns the materialized key. getRoute treats that suffix as a complete route override.
+// A key containing this sentinel doesn't have a fixed shard: setVariableShard picks the (lowest latency, up) write shard, appends "_<value in the shard's route>" directly after the sentinel, and returns the materialized key. getRoute treats that suffix as a complete route override.
 export const VARIABLE_SHARD = "VARIABLE_SHARD_f0234jfah08fgyhfgyssdds83nmp";
-// No grace past the end: a window boundary is a hard handoff (clients retry a rejected write
-// against the newly-valid source, so leniency here would only desynchronize the handoff)
+// No grace past the end: a window boundary is a hard handoff (clients retry a rejected write against the newly-valid source, so leniency here would only desynchronize the handoff)
 export function windowAcceptsWrites(validWindow: [number, number] | undefined): boolean {
     if (!validWindow) return true;
     return validWindow[1] > Date.now();
@@ -194,8 +166,7 @@ export type ArchivesSyncStatus = {
 
 export interface IArchives {
     getDebugName(): string;
-    /** Whether writes would be accepted (credentials exist, the account trusts this machine, etc).
-     *  Checked without writing anything. */
+    /** Whether writes would be accepted (credentials exist, the account trusts this machine, etc). Checked without writing anything. */
     hasWriteAccess(): Promise<boolean>;
     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>;

package/storage/IStorage.ts

@@ -25,12 +25,10 @@ export type IStorage<T> = {
     // Allows watching for when the storage detects and underlying changes, and resyncs all of it's data (which might 
     watchResync?: (callback: () => void) => void;
 };
-// NOTE: In the file system some characters are disallowed, and some characters do special things
-//  (/ makes a folder). And there are even more rules, such as lengths per folder, etc, etc.
+// NOTE: In the file system some characters are disallowed, and some characters do special things (/ makes a folder). And there are even more rules, such as lengths per folder, etc, etc.
 export type IStorageRaw = {
     get(key: string): Promise<Buffer | undefined>;
-    // Reads bytes in the range [start, end) (end is exclusive, clamped to the file size).
-    //  Returns undefined if the file doesn't exist.
+    // Reads bytes in the range [start, end) (end is exclusive, clamped to the file size). Returns undefined if the file doesn't exist.
     getRange(key: string, config: { start: number; end: number }): Promise<Buffer | undefined>;
     // May or may not be efficient in the underlying storage
     append(key: string, value: Buffer): Promise<void>;

package/storage/PendingManager.tsx

@@ -22,8 +22,7 @@ export function hasPending(): boolean {
     return Object.keys(watchState.pending).length > 0;
 }
 
-// NOTE: This not only prevents render overload, but also means any pending that are < this
-//  delay don't show up (which is useful to reduce unnecessary pending messages).
+// NOTE: This not only prevents render overload, but also means any pending that are < this delay don't show up (which is useful to reduce unnecessary pending messages).
 const setPendingBase = throttleFunction(500, function setPendingBase() {
     for (let [group, message] of pendingCache) {
 
@@ -38,7 +37,7 @@ const setPendingBase = throttleFunction(500, function setPendingBase() {
             }
             delete watchState.pending[group];
         } else {
-            //console.log("setPending", group, message);
+            // console.log("setPending", group, message);
             if (!(group in watchState.pending)) {
                 pendingLastSets.set(group, Date.now());
             }

package/storage/TransactionStorage.ts

@@ -13,27 +13,20 @@ import { runInfinitePoll } from "socket-function/src/batching";
 //      - Zip individual large values
 //      - Stores a transaction log
 //          - Transaction log has a header, which is JSON, for things such as "zipped"
-//          - Transaction log uses length prefixed values, with a special 8 bytes to denote the end,
-//              and 8 for the start.
-//          - When transaction log is iterated on, if the bytes at the end (using the length prefix)
-//              don't match the end bytes OR the start bytes are wrong, we skip the start bytes,
-//              and iterating until we find new start bytes that match our special bytes. Then we try
-//              to read these values.
+//          - Transaction log uses length prefixed values, with a special 8 bytes to denote the end, and 8 for the start.
+//          - When transaction log is iterated on, if the bytes at the end (using the length prefix) don't match the end bytes OR the start bytes are wrong, we skip the start bytes, and iterating until we find new start bytes that match our special bytes. Then we try to read these values.
 //          - Each transaction entry has a byte for flags, one bit which denotes if the value is zipped or not.
 //      - Compresses the log after there are 3X entries than keys (and > 100)
 //          - Both dedupe keys, and zip
 //      - Assumes all files in rawStorage ending with .tx are transaction logs
 //      - Names files like `${generation}.tx`
-//          - When compressing, we increment the generation, and write to a new file, and delete
-//              any generations that are older than the new one
+//          - When compressing, we increment the generation, and write to a new file, and delete any generations that are older than the new one
 //          - On reading, we read from all generation files that exist, in case some are corrupted
 //      - On load, loads in all transaction logs, and stores all values in a Map<string, Buffer>
 //      - On writes immediately updates the in memory Map, and then writes to the transaction log
 //      - Caches the last transaction file name in memory
-//      - Makes sure all file system writes (but not Map updates) are done with fileLockSection,
-//          so they never overlap.
-//      - Buffers pending appends in memory, so they can written all at once (after the first one
-//          is blocking in fileLockSection).
+//      - Makes sure all file system writes (but not Map updates) are done with fileLockSection, so they never overlap.
+//      - Buffers pending appends in memory, so they can written all at once (after the first one is blocking in fileLockSection).
 
 UPDATE now we use chunks, because append is too slow.
 
@@ -93,9 +86,7 @@ export class TransactionStorage implements IStorage<Buffer> {
         private rawStorage: IStorageRaw,
         private debugName: string,
         private writeDelay = WRITE_DELAY,
-        // When set, we poll the underlying storage and reload if another process/tab writes new
-        // chunk files. Off by default, as it costs a periodic disk scan and most collections are
-        // only written by a single process.
+        // When set, we poll the underlying storage and reload if another process/tab writes new chunk files. Off by default, as it costs a periodic disk scan and most collections are only written by a single process.
         private resyncFromDisk = false
     ) {
         TransactionStorage.allStorage.push(this);
@@ -241,7 +232,7 @@ export class TransactionStorage implements IStorage<Buffer> {
     private updatePendingAppends = throttleFunction(100, async () => {
         let appendCount = this.pendingAppends.length + this.extraAppends;
         let group = `Transaction (${this.debugName})`;
-        //console.log(`Update pending appends ${group}: ${appendCount}`);
+        // console.log(`Update pending appends ${group}: ${appendCount}`);
         if (!appendCount) {
             setPending(group, "");
             return;
@@ -322,7 +313,7 @@ export class TransactionStorage implements IStorage<Buffer> {
         const fullFile = await this.rawStorage.get(filename);
         if (!fullFile) return [];
         if (fullFile.length < 4) {
-            //console.error(`Transaction in ${this.debugName} file ${filename} is too small, skipping`);
+            // console.error(`Transaction in ${this.debugName} file ${filename} is too small, skipping`);
             return [];
         }
         size.value += fullFile.length;
@@ -549,8 +540,7 @@ export class TransactionStorage implements IStorage<Buffer> {
             existingDiskEntries = existingDiskEntries.filter(x => x.endsWith(CHUNK_EXT));
             let compressNow = force || (
                 this.entryCount > 100 && this.entryCount > this.cache.size * 3
-                // NOTE: This compress check breaks down if we only have very large values, but... those
-                //  don't work ANYWAYS (it is better to use one file per value instead).
+                // NOTE: This compress check breaks down if we only have very large values, but... those don't work ANYWAYS (it is better to use one file per value instead).
                 //  - Maybe we should throw, or at least warn, on sets of value > 1MB,
                 //      at which point they should just use a file per value
                 || existingDiskEntries.length > Math.max(10, Math.ceil(this.entryCount / 1000))
@@ -559,8 +549,7 @@ export class TransactionStorage implements IStorage<Buffer> {
             if (!compressNow) return;
             console.log(`Compressing ${this.debugName} transaction log, ${this.entryCount} entries, ${this.cache.size} keys`);
 
-            // Load off disk, in case there are other writes. We still race with them, but at least
-            //  this reduces the race condition considerably
+            // Load off disk, in case there are other writes. We still race with them, but at least this reduces the race condition considerably
             existingDiskEntries = await this.loadAllTransactions();
 
             this.entryCount = this.cache.size;
@@ -598,9 +587,7 @@ export class TransactionStorage implements IStorage<Buffer> {
                 }
             }
 
-            // This is the ONLY time we can delete old files, as we know for sure the new file has all of our data.
-            //  Any future readers won't know this, unless they write it themselves (or unless they audit it against
-            //      the other generations, which is annoying).
+            // This is the ONLY time we can delete old files, as we know for sure the new file has all of our data. Any future readers won't know this, unless they write it themselves (or unless they audit it against the other generations, which is annoying).
             for (const file of existingDiskEntries) {
                 await this.rawStorage.remove(file);
                 this.diskFiles.delete(file);