@rebasepro/server 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/storage/GCSStorageController.d.ts

@@ -5,7 +5,7 @@
  * optional peer dependency — users who don't need GCS never pay for the
  * import cost or need it installed.
  */
-import { StorageController, GCSStorageConfig } from "./types.js";
+import { StorageController, GCSStorageConfig, type StoredObjectInfo, type StoredObjectRange, type PutObjectOptions, type StoredObjectStream } from "./types.js";
 import { UploadFileProps, UploadFileResult, DownloadConfig, DownloadMetadata, StorageListResult } from "@rebasepro/types";
 /**
  * Google Cloud Storage implementation of `StorageController`.
@@ -24,7 +24,7 @@ export declare class GCSStorageController implements StorageController {
      * @see S3StorageController.knownBuckets
      */
     knownBuckets(): string[];
-    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    putObject({ file, key, metadata, bucket }: UploadFileProps, options?: PutObjectOptions): Promise<UploadFileResult>;
     /**
      * Read the object's metadata and nothing else — no signing.
      *
@@ -36,7 +36,51 @@ export declare class GCSStorageController implements StorageController {
      */
     getMetadata(key: string, bucket?: string): Promise<DownloadMetadata | null>;
     getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
+    /**
+     * The object's bytes, type and version — all three of ONE generation.
+     *
+     * Described first, then read pinned to the generation described, as
+     * {@link getObjectStream} reads. It used to download and then ask for the
+     * metadata: an overwrite between the two calls answered the old bytes
+     * under the new generation's `updated`, and that `lastModified` keys the
+     * routes' `ETag` and transform cache, so the stale bytes — or a rendition
+     * of them — were served as current. A pinned read of a generation replaced
+     * since it was described fails, and the object is described again.
+     */
     getObject(key: string, bucket?: string): Promise<File | null>;
+    /**
+     * The bucket and key a call addresses: a `gs://` or `s3://` URL names its
+     * own bucket, anything else is a key in the given (or configured) bucket.
+     */
+    private resolveLocation;
+    /** The object's metadata and where it lives, or `null` when there is no such object. */
+    private locate;
+    /**
+     * The generation just described, so an overwrite between describing an
+     * object and reading it fails the read instead of sending the new bytes
+     * under the old size and version.
+     */
+    private pinnedFile;
+    /**
+     * An object stored gzip-encoded (`gsutil cp -z`) is decompressed on the way
+     * out, so its stored size is not the size served and a range of the one is
+     * not a range of the other. Such an object is read whole, as every object
+     * used to be; nothing this server writes is stored that way.
+     */
+    private readDecompressed;
+    /** See {@link StorageController.statObject}. One metadata request; no body is read. */
+    statObject(key: string, bucket?: string): Promise<StoredObjectInfo | null>;
+    /**
+     * See {@link StorageController.getObjectStream}. One metadata request, then
+     * a read of exactly the requested bytes, handed on as they arrive.
+     *
+     * The metadata comes first, not after the download as `getObject` has it:
+     * it is what pins the read to one generation.
+     */
+    getObjectStream(key: string, options?: {
+        bucket?: string;
+        range?: StoredObjectRange;
+    }): Promise<StoredObjectStream | null>;
     deleteObject(key: string, bucket?: string): Promise<void>;
     listObjects(prefix: string, options?: {
         bucket?: string;

package/dist/storage/LocalStorageController.d.ts

@@ -1,7 +1,7 @@
 /**
  * Local filesystem storage controller
  */
-import { StorageController, LocalStorageConfig } from "./types.js";
+import { StorageController, LocalStorageConfig, type StoredObjectInfo, type StoredObjectRange, type PutObjectOptions, type StoredObjectStream } from "./types.js";
 import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
 /**
  * Bucket used when a call names none.
@@ -10,6 +10,22 @@ import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult }
  * bare key lives.
  */
 export declare const DEFAULT_BUCKET = "default";
+/**
+ * Refuse a key that names one of local storage's own files rather than an
+ * object: the metadata beside an object, or a write in progress.
+ *
+ * Both live in the object namespace, beside the objects they serve. A key that
+ * names one used to be stored like any other, and so overwrote another
+ * object's metadata: uploading `a.png.metadata.json` changed the content type
+ * `a.png` is served with — the authorize hook asked about the one key while
+ * the other changed — and the uploader's own file vanished from listings and
+ * went with `a.png` when that was deleted. Read, it served the metadata.
+ *
+ * Local only: S3 and GCS keep metadata on the object, so every key there is
+ * an object. A 400, at every operation, because every one resolves its path
+ * through `getFullPath`.
+ */
+export declare function refuseLocalReservedKey(key: string): void;
 /**
  * Local filesystem storage implementation
  * Stores files in a directory structure: {basePath}/{bucket}/{path}
@@ -17,8 +33,26 @@ export declare const DEFAULT_BUCKET = "default";
 export declare class LocalStorageController implements StorageController {
     private config;
     private basePath;
+    /**
+     * Folder entries read by a listing's first page, for its continuation
+     * pages. Keyed by the folder's absolute path (bucket included). Not
+     * caller-scoped, because the entries are not: every caller of this method
+     * gets the same names, and the routes authorize the prefix before calling
+     * it. Insertion-ordered, so the first key is the oldest.
+     */
+    private readonly listingSnapshots;
     constructor(config: LocalStorageConfig);
     getType(): "local";
+    /**
+     * Whether the file system under the storage root folds case — macOS and
+     * Windows by default — so `Avatar.png` and `avatar.png` are one file here
+     * and two on S3, GCS or a Linux disk.
+     *
+     * Read by writing a probe file and asking for it in the other case. The
+     * root is created if it is not there yet; the probe is removed. `false`
+     * when the root cannot be written: nothing is known.
+     */
+    isCaseInsensitive(): Promise<boolean>;
     /**
      * The bucket directories that exist under the storage root, plus `default`.
      *
@@ -69,15 +103,46 @@ export declare class LocalStorageController implements StorageController {
      * Validate file before upload
      */
     private validateFile;
-    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    putObject({ file, key, metadata, bucket }: UploadFileProps, options?: PutObjectOptions): Promise<UploadFileResult>;
     getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
     getObject(key: string, bucket?: string): Promise<File | null>;
+    /** The file a read of `key` addresses — `getObject`'s resolution, `local://` URLs included. */
+    private readPath;
+    /** See {@link StorageController.statObject}. A `stat` and the metadata sidecar; the file is not read. */
+    statObject(key: string, bucket?: string): Promise<StoredObjectInfo | null>;
+    /**
+     * See {@link StorageController.getObjectStream}. The file — or only the
+     * requested range of it — read from disk a chunk at a time, opened on the
+     * first read.
+     */
+    getObjectStream(key: string, options?: {
+        bucket?: string;
+        range?: StoredObjectRange;
+    }): Promise<StoredObjectStream | null>;
     deleteObject(key: string, bucket?: string): Promise<void>;
     listObjects(prefix: string, options?: {
         bucket?: string;
         maxResults?: number;
         pageToken?: string;
     }): Promise<StorageListResult>;
+    /**
+     * A folder's entries for a listing page.
+     *
+     * A page token is an index into these entries, and every continuation
+     * page used to read the whole folder again to find its place: a folder of
+     * n entries listed in pages of p cost n/p full reads. A first page reads
+     * the folder and, when there is a next page, keeps the read; a
+     * continuation page indexes into it while all of these hold:
+     *
+     *  - the folder's mtime is the one read with it. Adding, removing or
+     *    renaming an entry changes it, which is the invalidation;
+     *  - it is under {@link LISTING_SNAPSHOT_TTL_MS} old;
+     *  - the folder had not changed in the {@link LISTING_SNAPSHOT_RACY_MS}
+     *    before the read. Otherwise it is not kept at all.
+     *
+     * A first page always reads the folder as it is.
+     */
+    private listingEntries;
     /**
      * Get the absolute filesystem path for serving files
      * Used by the storage routes to serve files directly

package/dist/storage/S3StorageController.d.ts

@@ -1,8 +1,8 @@
 /**
  * S3-compatible storage controller (works with AWS S3 and MinIO)
  */
-import { S3StorageConfig, StorageController } from "./types.js";
-import { DownloadConfig, StorageListResult, UploadFileProps, UploadFileResult } from "@rebasepro/types";
+import { S3StorageConfig, StorageController, type StoredObjectInfo, type StoredObjectRange, type PutObjectOptions, type StoredObjectStream } from "./types.js";
+import { DownloadConfig, DownloadMetadata, StorageListResult, UploadFileProps, UploadFileResult } from "@rebasepro/types";
 /**
  * S3-compatible storage implementation
  * Works with AWS S3 and MinIO (with forcePathStyle option)
@@ -34,13 +34,47 @@ export declare class S3StorageController implements StorageController {
      * Get the bucket name - either from parameter or config
      */
     private getBucket;
-    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    putObject({ file, key, metadata, bucket }: UploadFileProps, options?: PutObjectOptions): Promise<UploadFileResult>;
+    /**
+     * Upload a large file in parts, one part in memory at a time.
+     *
+     * Reading the whole file into one buffer held it twice over (the
+     * `arrayBuffer()`, then the SDK's view and the multipart parser's copy
+     * before it), and `PutObject` stops at 5 GB regardless. A slice of a
+     * `File` reads only that range — from disk, for the disk-backed files TUS
+     * and backups hand over — so memory is one part whatever the file's size.
+     * A failure aborts the upload: no partial object appears at the key, and
+     * no orphaned parts are kept (and billed).
+     */
+    private putMultipart;
     /**
      * Flatten nested metadata to string values (S3 requirement)
      */
     private flattenMetadata;
     getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
     getObject(key: string, bucket?: string): Promise<File | null>;
+    /**
+     * The bucket and key a call addresses: an `s3://` or `gs://` URL names its
+     * own bucket, anything else is a key in the given (or configured) bucket.
+     */
+    private resolveLocation;
+    /**
+     * See {@link StorageController.getMetadata}. One `HeadObject`. Without it,
+     * `GET /metadata/*` fell back to `getSignedUrl`, which signed a URL per
+     * call — ~134 µs of CPU — only for the route to throw it away.
+     */
+    getMetadata(key: string, bucket?: string): Promise<DownloadMetadata | null>;
+    /** See {@link StorageController.statObject}. One `HeadObject`; no body is read. */
+    statObject(key: string, bucket?: string): Promise<StoredObjectInfo | null>;
+    /**
+     * See {@link StorageController.getObjectStream}. One `GetObject`, with a
+     * `Range` when one is asked for, so only those bytes leave the bucket; the
+     * body is handed on as it arrives rather than collected first.
+     */
+    getObjectStream(key: string, options?: {
+        bucket?: string;
+        range?: StoredObjectRange;
+    }): Promise<StoredObjectStream | null>;
     deleteObject(key: string, bucket?: string): Promise<void>;
     listObjects(prefix: string, options?: {
         bucket?: string;

package/dist/storage/image-transform.d.ts

@@ -70,6 +70,11 @@ export declare const DECODABLE_FORMATS: Set<string>;
 export declare class UntransformableImageError extends Error {
     constructor(message: string);
 }
+/**
+ * The content type a transform with these options produces: its `format`, or
+ * WebP when it names none, as {@link transformImage} encodes it.
+ */
+export declare function transformContentType(options: ImageTransformOptions): string;
 /** Check whether a content type is a transformable image. */
 export declare function isTransformableImage(contentType: string): boolean;
 /**

package/dist/storage/maintenance-routes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `/admin/storage` — the routes behind `rebase storage orphans` and
+ * `rebase storage move`. Admin-only; the caller mounts them behind the admin
+ * gate (`database:read` to read, `database:write` to delete or move).
+ *
+ *   GET    /orphans?storageId=&olderThanHours=   objects no row names
+ *   DELETE /orphans?storageId=&olderThanHours=   delete them, found again first
+ *   POST   /move  { from, to, prefix?, cursor?, limit?, deleteSource? }
+ */
+import { Hono } from "hono";
+import type { CollectionConfig, DataDriver } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+import type { StorageController } from "./types.js";
+import type { StorageRegistry } from "./storage-registry.js";
+export interface StorageMaintenanceRoutesConfig {
+    registry?: StorageRegistry;
+    controller?: StorageController;
+    /** The collections whose rows are read for references, read per request. */
+    collections: () => readonly CollectionConfig[];
+    /** The unscoped driver serving a collection: every row, whoever wrote it. */
+    driverFor: (collection: CollectionConfig) => DataDriver | undefined;
+}
+export declare function createStorageMaintenanceRoutes(config: StorageMaintenanceRoutesConfig): Hono<HonoEnv>;

package/dist/storage/maintenance.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Storage maintenance: the objects a source holds that no row names
+ * (`rebase storage orphans`), and copying a folder of objects from one source
+ * to another (`rebase storage move`).
+ *
+ * Nothing deletes a stored file when its field is cleared, its file replaced or
+ * its row deleted — two rows may hold one key, so the panel cannot know a file
+ * is unused. What can know is a scan of every row against every object, which
+ * is what this is. It errs one way only: a string anywhere in any row that
+ * could name an object keeps that object, whichever source it is in and
+ * whichever property holds it. A file is reported only when nothing points at
+ * it at all.
+ */
+import type { CollectionConfig, DataDriver } from "@rebasepro/types";
+import type { StorageController } from "./types.js";
+/** One stored object, as a listing describes it. */
+export interface StoredObjectEntry {
+    key: string;
+    size?: number;
+    /** ISO 8601, when the source's listing says. */
+    updated?: string;
+}
+/** A request this module cannot act on: a bad cursor, a source that is not served. */
+export declare class InvalidMaintenanceRequestError extends Error {
+}
+/**
+ * The objects under a folder of a source, folder by folder, at most `limit` at
+ * a time. Hand the returned `cursor` back for the next ones; none means the
+ * walk is done. The internal `_rebase/` folder is not walked.
+ */
+export declare function walkObjects(controller: StorageController, options?: {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+}): Promise<{
+    objects: StoredObjectEntry[];
+    cursor?: string;
+}>;
+/**
+ * The keys one stored string could name an object by.
+ *
+ * A file field stores a bare key, a `local://`, `s3://` or `gs://` URL with the
+ * bucket, or — with `storeUrl` — a download URL; text stores
+ * `rebase-storage:` references, and from before those, download URLs. Each
+ * spelling yields the key it names, and a key under a leading `default/` is
+ * also read without it, as the routes read it.
+ */
+export declare function keysNamedBy(value: string): string[];
+/** A collection whose rows could not be read, and why. */
+export interface UnscannedCollection {
+    collection: string;
+    reason: string;
+}
+/**
+ * Remove from `keys` every key some row names.
+ *
+ * Every row of every collection is read — soft-deleted rows too, since a
+ * restore brings their files back — a page at a time, through the driver that
+ * serves the collection. What is left in `keys` afterwards is named by no row.
+ * A collection that could not be read is returned, and its rows count for
+ * nothing: a caller must not treat what is left as unused when any is.
+ */
+export declare function removeReferencedKeys(keys: Set<string>, collections: readonly CollectionConfig[], driverFor: (collection: CollectionConfig) => DataDriver | undefined, options?: {
+    pageSize?: number;
+}): Promise<{
+    scanned: string[];
+    unscanned: UnscannedCollection[];
+}>;
+/** What `findOrphans` found. */
+export interface OrphanReport {
+    /** Objects in the source, internal ones aside. */
+    objects: number;
+    /** Objects no row names and older than the grace period. */
+    orphans: StoredObjectEntry[];
+    /**
+     * Objects no row names but too new to call unused — an upload whose row
+     * has not been saved yet looks exactly like this — or of unknown age.
+     */
+    recent: number;
+    scanned: string[];
+    unscanned: UnscannedCollection[];
+}
+/**
+ * The objects of one source that no row names.
+ *
+ * @param olderThanMs an object written less long ago than this is not called
+ *        an orphan: the admin panel uploads a file before the row that names it
+ *        is saved. One whose age the listing does not say is not either.
+ */
+export declare function findOrphans(options: {
+    controller: StorageController;
+    collections: readonly CollectionConfig[];
+    driverFor: (collection: CollectionConfig) => DataDriver | undefined;
+    olderThanMs: number;
+    now?: number;
+}): Promise<OrphanReport>;
+/** What happened to one object in a move. */
+export interface MovedObject {
+    key: string;
+    outcome: "copied" | "exists" | "failed";
+    /** Whether the source's copy was deleted afterwards. */
+    deleted?: boolean;
+    error?: string;
+}
+/**
+ * Copy the objects under a folder of one source into another, under the same
+ * keys, `limit` objects per call. Hand the returned `cursor` back for the next
+ * ones; none means the folder is done.
+ *
+ * A key the target already holds at the same size is left alone, so a move
+ * that stopped half-way is resumed by running it again. With `deleteSource`,
+ * the source's copy is deleted once the target holds one of the same size.
+ * The copy is the server's own write: the target's upload limits, which say
+ * what a user may upload, do not apply to a file already accepted once.
+ */
+export declare function moveObjects(options: {
+    from: StorageController;
+    to: StorageController;
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+    deleteSource?: boolean;
+}): Promise<{
+    moved: MovedObject[];
+    cursor?: string;
+}>;

package/dist/storage/rendition-cache.d.ts

@@ -28,8 +28,15 @@ export interface DurableRendition {
     contentType: string;
 }
 export interface DurableRenditionCache {
-    /** The stored rendition for this cache key, or null. Never throws. */
-    get(controller: StorageController, cacheKey: string, bucket: string | undefined): Promise<DurableRendition | null>;
+    /**
+     * The stored rendition for this cache key, or null. Never throws.
+     *
+     * `contentType` is the type the transform produces
+     * (`transformContentType(options)`). The cache key carries the options,
+     * format included, so a key only ever holds a rendition of that type, and
+     * one read of that one object key answers the question.
+     */
+    get(controller: StorageController, cacheKey: string, bucket: string | undefined, contentType: string): Promise<DurableRendition | null>;
     /** Store a rendition. Never throws: a failed write is a slower cache. */
     put(controller: StorageController, cacheKey: string, bucket: string | undefined, rendition: DurableRendition): Promise<void>;
 }
@@ -43,13 +50,4 @@ export interface DurableRenditionCache {
  * is available to anyone auditing the prefix and to nothing on the hot path.
  */
 export declare function renditionKey(cacheKey: string, contentType: string): string;
-/**
- * A rendition's key when reading, where the content type is not yet known.
- *
- * Reads try the known extensions rather than storing an index: four `getObject`
- * calls at worst is still one round trip in the common case — the first
- * candidate is the format the request asked for — and an index is a second
- * thing to keep consistent with the objects it describes.
- */
-export declare function renditionKeyCandidates(cacheKey: string, preferred?: string): string[];
 export declare function createDurableRenditionCache(): DurableRenditionCache;

package/dist/storage/request-principals.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The two principals a storage read can be granted without a user: the reader
+ * of a declared-public object, and the bearer of a download token.
+ *
+ * `checkAuthorized` does not ask the `storageAuthorize` hook about either — the
+ * public prefix and the token are the authorization. That skip used to be
+ * decided on the principal's `uid` string (`"public"`, `"download-token"`), so
+ * any identity carrying that uid skipped the hook: a custom `AuthAdapter` whose
+ * `verifyRequest` returns `{ uid: "public" }` for a guest could then upload,
+ * delete and list anywhere, with the hook never asked.
+ *
+ * Each principal is now one object, set only by the middleware that granted
+ * it (`publicObjectAuth`, `fileTokenAuth`) and recognised by identity. An
+ * adapter builds a new object per request, so it can name the uid but never be
+ * the grant.
+ */
+/** The principal `publicObjectAuth` grants an anonymous read of a public object. */
+export declare const PUBLIC_OBJECT_PRINCIPAL: {
+    readonly uid: string;
+    readonly roles: string[];
+};
+/** The principal `fileTokenAuth` grants a read covered by a valid download token. */
+export declare const DOWNLOAD_TOKEN_PRINCIPAL: {
+    readonly uid: string;
+    readonly roles: string[];
+};
+/** Whether `user` is the grant `publicObjectAuth` made — the object, not the uid. */
+export declare function isPublicObjectGrant(user: unknown): boolean;
+/** Whether `user` is the grant `fileTokenAuth` made — the object, not the uid. */
+export declare function isDownloadTokenGrant(user: unknown): boolean;

package/dist/storage/routes.d.ts

@@ -142,6 +142,26 @@ export declare const DEFAULT_DOWNLOAD_TOKEN_TTL_SECONDS = 300;
  * file. A file that must be linked forever belongs under the public prefix.
  */
 export declare const MAX_DOWNLOAD_TOKEN_TTL_SECONDS: number;
+/** Most keys `POST /metadata` takes in one request. */
+export declare const DOWNLOAD_METADATA_BATCH_MAX = 100;
+/**
+ * What a storage request costs against the data rate limit: one, except a
+ * `POST /metadata` of N keys, which costs ⌈N/10⌉.
+ *
+ * One request per key let a page of thumbnails spend a hundred requests of a
+ * caller's allowance; one per batch would make a batch of a hundred keys a
+ * hundred times cheaper to scrape with than the route it replaces. A tenth
+ * keeps a budget against enumeration while a page of thumbnails costs ten.
+ * Read before the route runs (the limiter is ahead of it); the body is parsed
+ * once, and the route reads Hono's cached copy.
+ */
+export declare function storageRateLimitCost(c: {
+    req: {
+        method: string;
+        path: string;
+        json(): Promise<unknown>;
+    };
+}): Promise<number>;
 /**
  * Create storage REST API routes
  */

package/dist/storage/source-variables.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The variable that binds a declared object-store source's bucket on a
+ * deployment — `S3_BUCKET__MEDIA`, `GCS_BUCKET__ARCHIVE`, `S3_BUCKET` for the
+ * default source.
+ *
+ * One spelling for the three places that tell an operator to set it: the boot
+ * warning, the 501 a request to the unbound source answers, and `rebase
+ * status`. The 501 used to say "the media suffixed environment variables".
+ */
+export declare function storageBucketVariable(key: string, engine: string | undefined): string;

package/dist/storage/streams.d.ts

@@ -0,0 +1,42 @@
+/** Anything that hands over bytes a chunk at a time: a Node readable, an SDK body. */
+type ByteSource = AsyncIterable<Uint8Array>;
+/**
+ * A byte source as a web stream that reads a chunk only when the consumer asks
+ * for one, and releases the source when the consumer stops early.
+ *
+ * Pull-based with a zero high-water mark, so nothing is read ahead of the
+ * reader: a slow client holds one chunk, not a queue of them. A source given
+ * as a function is opened on the first read, which keeps a stream nobody reads
+ * — a `HEAD`, a 304 decided late — from holding a file descriptor or a
+ * connection open. Cancelling (a client that disconnects mid-download)
+ * returns the iterator, which destroys a Node stream and so closes its file or
+ * socket.
+ */
+export declare function webStreamFrom(source: ByteSource | (() => ByteSource)): ReadableStream<Uint8Array>;
+/**
+ * A file on disk, or an inclusive byte range of it, as a web stream. The file
+ * is opened on the first read; see {@link webStreamFrom}.
+ */
+export declare function fileWebStream(filePath: string, range?: {
+    start: number;
+    end: number;
+}): ReadableStream<Uint8Array>;
+/** A buffer already in memory as a web stream of views onto it, never copies. */
+export declare function bufferWebStream(bytes: Uint8Array, chunkSize?: number): ReadableStream<Uint8Array>;
+/**
+ * Read a stream into one buffer.
+ *
+ * For the one consumer that needs the whole object at once — an image decode.
+ * With the size known the bytes are copied once, into a buffer of that size,
+ * rather than collected and then concatenated (which holds them twice); a
+ * stream that turns out longer or shorter than announced still comes back
+ * whole and exact.
+ */
+export declare function readStreamFully(stream: ReadableStream<Uint8Array>, expectedSize?: number): Promise<Buffer>;
+/**
+ * The bytes of a buffer as a `Uint8Array` the response APIs accept, without
+ * copying them. `new Uint8Array(buffer)` copies; a view does not. Only a buffer
+ * over shared memory — which nothing here produces — is copied.
+ */
+export declare function bytesView(bytes: Uint8Array): Uint8Array<ArrayBuffer>;
+export {};

package/dist/storage/tus-handler.d.ts

@@ -11,12 +11,28 @@ import type { Context } from "hono";
 import type { StorageController } from "./types.js";
 import { type StorageRegistry } from "./storage-registry.js";
 import { type ResolveUploadConstraints, type ResolveUploadPathConstraints } from "./property-limits.js";
+/**
+ * The header a resumable upload's last `PATCH` answers with the stored object
+ * in — `{ key, bucket, storageUrl }`, the `data` of `POST /upload`, as
+ * URI-encoded JSON — so a client gets from the resumable path what it gets
+ * from the multipart one. `create` answers it with `on-complete`, which tells
+ * a client this server will, before it sends a byte.
+ */
+export declare const UPLOAD_RESULT_HEADER = "Rebase-Upload-Result";
 /**
  * TUS resumable upload handler.
  *
  * Each instance manages uploads for a single storage root. The
  * `storageController` is used to finalize completed uploads by
  * calling `putObject`.
+ *
+ * An upload lives in the upload directory, not in this process: its bytes in
+ * `<id>`, and what `create` decided about it in `<id>.json` beside them. Its
+ * offset is the length of the bytes file. So a restart — a rolling deploy —
+ * resumes an upload where it stopped instead of sending the client back to
+ * byte 0, and every process that shares the directory (one volume at
+ * `STORAGE_PATH`) serves every upload. The map below only remembers records
+ * already read.
  */
 export declare class TusHandler {
     private storageController?;
@@ -71,6 +87,12 @@ export declare class TusHandler {
      * `POST /upload` checks them.
      */
     private uploadPathConstraints?;
+    /**
+     * Upload records this process has read or written, by id. A cache of the
+     * `<id>.json` files: it never holds the offset (the bytes file's length
+     * does), and an upload another process finished or cancelled is noticed
+     * when its bytes file is gone.
+     */
     private uploads;
     private tusDir;
     private cleanupTimer?;
@@ -140,8 +162,18 @@ export declare class TusHandler {
     private ensureDir;
     /** Start periodic cleanup of stale uploads. */
     startCleanup(): void;
-    /** Remove uploads that have been idle for longer than UPLOAD_EXPIRY_MS. */
+    /**
+     * Remove uploads created more than {@link UPLOAD_EXPIRY_MS} ago.
+     *
+     * From the directory rather than from this process's memory, so an upload
+     * a crashed or replaced process abandoned is collected too. A record is
+     * written once, at creation, so its file's mtime is when the upload began;
+     * a bytes file with no record (left by an earlier version) is judged by
+     * its own.
+     */
     private cleanupStale;
+    /** The upload's bytes and record, gone; from every process, since they are files. */
+    private forget;
     /**
      * Parse the `Upload-Metadata` header.
      *
@@ -185,8 +217,20 @@ export declare class TusHandler {
      * the rest.
      */
     private ownedUpload;
+    /**
+     * The upload with this id: from this process's memory, or from its record
+     * in the upload directory — written by another process sharing it, or by
+     * this one before a restart. `null` when there is no such upload.
+     */
+    private lookup;
+    /**
+     * Bytes received so far: the length of the bytes file. `null` when it is
+     * gone — finished or cancelled by another process — and then this one
+     * forgets the upload too.
+     */
+    private offsetOf;
     /** `HEAD /tus/:id` — Query upload progress. */
-    head(c: Context, id: string): Response;
+    head(c: Context, id: string): Promise<Response>;
     /** `PATCH /tus/:id` — Write one chunk of an upload, at its offset. */
     patch(c: Context, id: string): Promise<Response>;
     /** `DELETE /tus/:id` — Cancel and remove an upload. */