@mdbase-dev/connect 0.1.0-beta.100

package/dist/file-transfer-internals.js

@@ -0,0 +1,228 @@
+import { MdbaseConnectError, connectError } from "./errors.js";
+import { IncrementalSha256 } from "./file-sha256.js";
+import { MAX_TRANSIENT_CHUNK_ATTEMPTS, waitForTransientChunkRetry } from "./transient-retry.js";
+const HASH_CHUNK_BYTES = 1024 * 1024;
+const DEFAULT_CONCURRENCY = 4;
+const MAX_CONCURRENCY = 8;
+export const MAX_OBJECT_ATTEMPTS = 3;
+export const MAX_BUFFERED_DOWNLOAD_BYTES = 64 * 1024 * 1024;
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+export const SHA256_DIGEST = /^sha256:[0-9a-f]{64}$/u;
+export async function hashBlob(blob, signal, progress) {
+    const hash = new IncrementalSha256();
+    for (let offset = 0; offset < blob.size; offset += HASH_CHUNK_BYTES) {
+        throwIfAborted(signal);
+        const chunk = new Uint8Array(await blob.slice(offset, offset + HASH_CHUNK_BYTES).arrayBuffer());
+        hash.update(chunk);
+        progress(Math.min(blob.size, offset + chunk.byteLength));
+    }
+    if (blob.size === 0)
+        progress(0);
+    return hash.digestHex();
+}
+export function sourceBlob(source, mediaType) {
+    if (source instanceof Blob) {
+        return mediaType && mediaType !== source.type
+            ? source.slice(0, source.size, mediaType)
+            : source;
+    }
+    if (source instanceof ArrayBuffer)
+        return new Blob([source], { type: mediaType });
+    const copy = new Uint8Array(source.byteLength);
+    copy.set(new Uint8Array(source.buffer, source.byteOffset, source.byteLength));
+    return new Blob([copy.buffer], { type: mediaType });
+}
+export function uploadBodyLength(body) {
+    return body instanceof Blob ? body.size : body.byteLength;
+}
+export async function uploadBodyBytes(body) {
+    return body instanceof Blob
+        ? new Uint8Array(await body.arrayBuffer())
+        : body;
+}
+export function validConcurrency(value = DEFAULT_CONCURRENCY) {
+    if (!Number.isInteger(value) || value < 1 || value > MAX_CONCURRENCY) {
+        throw connectError("invalid_request", `File concurrency must be between 1 and ${MAX_CONCURRENCY}.`);
+    }
+    return value;
+}
+export function validPageSize(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 1_000) {
+        throw connectError("invalid_request", "File page size must be between 1 and 1000.");
+    }
+    return value;
+}
+export function requireTransferSession(session, transferId, direction) {
+    if (session.protocol_version !== 1
+        || session.type !== "file_transfer"
+        || session.transfer_id !== transferId
+        || session.direction !== direction
+        || !Number.isSafeInteger(session.total_size)
+        || session.total_size < 0
+        || !Array.isArray(session.received)
+        || !validTransferStrategy(session)) {
+        throw connectError("invalid_operation_response", "The authority returned an invalid file transfer session.");
+    }
+    const partSize = session.strategy.kind === "framed_chunks"
+        ? session.strategy.chunk_size
+        : session.strategy.kind === "object_put"
+            ? Math.max(1, session.total_size)
+            : session.strategy.part_size;
+    const partCount = session.strategy.kind === "object_put"
+        ? 1
+        : Math.ceil(session.total_size / partSize);
+    if (new Set(session.received).size !== session.received.length
+        || session.received.some((index) => !Number.isSafeInteger(index) || index < 0 || index >= partCount)) {
+        throw connectError("invalid_operation_response", "The authority returned invalid transfer progress.");
+    }
+    const uploadedParts = session.uploaded_parts ?? [];
+    if (!Array.isArray(uploadedParts)
+        || uploadedParts.some((part, index) => !Number.isSafeInteger(part?.part_number)
+            || part.part_number < 1
+            || part.part_number > partCount
+            || typeof part.etag !== "string"
+            || part.etag.length === 0
+            || part.etag.length > 255
+            || (index > 0 && uploadedParts[index - 1].part_number >= part.part_number))
+        || (session.strategy.kind === "object_multipart"
+            ? uploadedParts.length !== session.received.length
+                || uploadedParts.some((part, index) => part.part_number - 1 !== session.received[index])
+            : uploadedParts.length !== 0)) {
+        throw connectError("invalid_operation_response", "The authority returned invalid uploaded part receipts.");
+    }
+}
+export function requireTransferStatus(status, session) {
+    const partSize = session.strategy.kind === "framed_chunks"
+        ? session.strategy.chunk_size
+        : session.strategy.kind === "object_put"
+            ? Math.max(1, session.total_size)
+            : session.strategy.part_size;
+    const partCount = session.strategy.kind === "object_put"
+        ? 1
+        : Math.ceil(session.total_size / partSize);
+    if (status?.protocol_version !== 1
+        || status.type !== "file_transfer_status"
+        || status.transfer_id !== session.transfer_id
+        || !["open", "committed", "aborted", "expired"].includes(status.state)
+        || !Array.isArray(status.received)
+        || new Set(status.received).size !== status.received.length
+        || status.received.some((index) => !Number.isSafeInteger(index) || index < 0 || index >= partCount)
+        || !Number.isSafeInteger(status.received_bytes)
+        || status.received_bytes < 0
+        || status.received_bytes > session.total_size
+        || status.received.reduce((total, index) => total + chunkLength(session.total_size, partSize, index), 0) !== status.received_bytes) {
+        throw connectError("invalid_operation_response", "The authority returned invalid transfer status.");
+    }
+    const uploadedParts = status.uploaded_parts;
+    if (!Array.isArray(uploadedParts)
+        || uploadedParts.some((part, index) => !Number.isSafeInteger(part?.part_number)
+            || part.part_number < 1
+            || part.part_number > partCount
+            || typeof part.etag !== "string"
+            || part.etag.length === 0
+            || part.etag.length > 255
+            || (index > 0 && uploadedParts[index - 1].part_number >= part.part_number))
+        || (session.strategy.kind === "object_multipart"
+            ? uploadedParts.length !== status.received.length
+                || uploadedParts.some((part, index) => part.part_number - 1 !== status.received[index])
+            : uploadedParts.length !== 0)) {
+        throw connectError("invalid_operation_response", "The authority returned invalid uploaded part status.");
+    }
+}
+function validTransferStrategy(session) {
+    if (session.strategy.kind === "framed_chunks") {
+        return session.protection === "grant_aead_v1"
+            && Number.isSafeInteger(session.strategy.chunk_size)
+            && session.strategy.chunk_size > 0;
+    }
+    if (session.protection !== "transport_tls")
+        return false;
+    if (session.strategy.kind === "object_put")
+        return true;
+    return Number.isSafeInteger(session.strategy.part_size) && session.strategy.part_size > 0;
+}
+export function chunkLength(totalSize, partSize, index) {
+    return Math.min(partSize, Math.max(0, totalSize - index * partSize));
+}
+export async function retryChunk(work, signal) {
+    for (let attempt = 1; attempt <= MAX_TRANSIENT_CHUNK_ATTEMPTS; attempt += 1) {
+        throwIfAborted(signal);
+        try {
+            return await work();
+        }
+        catch (error) {
+            if (signal?.aborted
+                || attempt === MAX_TRANSIENT_CHUNK_ATTEMPTS
+                || (error instanceof MdbaseConnectError && !error.retryable))
+                throw error;
+            await waitForTransientChunkRetry(attempt, signal);
+        }
+    }
+    throw new Error("Unreachable file chunk retry state.");
+}
+export function requirePreparedPart(part, transferId, partIndex, offset, contentLength, method) {
+    let url;
+    try {
+        url = new URL(part.url);
+    }
+    catch {
+        throw connectError("invalid_operation_response", "The authority returned an invalid object URL.");
+    }
+    if (part.protocol_version !== 1
+        || part.type !== "file_part"
+        || part.transfer_id !== transferId
+        || part.part_index !== partIndex
+        || part.offset !== offset
+        || part.content_length !== contentLength
+        || part.method.toUpperCase() !== method
+        || url.protocol !== "https:"
+            && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]", "::1"].includes(url.hostname))
+        || url.username
+        || url.password) {
+        throw connectError("invalid_operation_response", "The authority returned an invalid prepared file part.");
+    }
+}
+export function browserObjectHeaders(headers) {
+    const result = new Headers();
+    for (const [name, value] of Object.entries(headers)) {
+        if (["host", "content-length"].includes(name.toLowerCase()))
+            continue;
+        result.set(name, value);
+    }
+    return result;
+}
+export async function mapConcurrent(count, concurrency, work) {
+    const results = new Array(count);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(count, concurrency) }, async () => {
+        while (next < count) {
+            const index = next;
+            next += 1;
+            results[index] = await work(index);
+        }
+    }));
+    return results;
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw connectError("operation_cancelled", "The file transfer was cancelled.", {
+            operationOutcome: "not_sent",
+            cause: signal.reason
+        });
+    }
+}
+export function normalizeFileError(error) {
+    if (error instanceof MdbaseConnectError)
+        return error;
+    if (typeof DOMException !== "undefined"
+        && error instanceof DOMException
+        && error.name === "AbortError") {
+        return connectError("operation_cancelled", "The file transfer was cancelled.", {
+            operationOutcome: "not_sent",
+            cause: error
+        });
+    }
+    return connectError("temporarily_unavailable", "The file transfer could not be completed.", {
+        cause: error
+    });
+}

package/dist/files.d.ts

@@ -0,0 +1,115 @@
+import type { FileCapability, FileTransferSession } from "@mdbase-dev/connect-protocol";
+import { type FileSource } from "./file-transfer-internals.js";
+import type { ConnectRequestOptions } from "./operation-types.js";
+import { type ResolvedConnectTimeouts } from "./request-budget.js";
+export type MdbaseFileSource = FileSource;
+export interface CollectionFileDescriptor {
+    fileId: string;
+    path: string;
+    revision: string;
+    contentDigest: `sha256:${string}`;
+    size: number;
+    mediaType?: string;
+    mediaClass: import("@mdbase-dev/connect-protocol").FileMediaClass;
+    modifiedAt: string;
+}
+export interface MdbaseFileDeleteReceipt {
+    protocolVersion: 1;
+    type: "file_deleted";
+    mutationId: string;
+    fileId: string;
+    previousPath: string;
+    revision: string;
+}
+export interface MdbaseFileStreamSource {
+    /** Exact plaintext byte length. */
+    size: number;
+    /** SHA-256 commitment verified by both this client and the authority. */
+    contentDigest: `sha256:${string}`;
+    /**
+     * A one-shot byte source. Each yielded chunk must fit within the upload part
+     * size negotiated by the authority; ordinary browser and Node streams do.
+     */
+    stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+    mediaType?: string;
+}
+export interface MdbaseFileProgress {
+    phase: "hashing" | "uploading" | "downloading";
+    transferredBytes: number;
+    totalBytes: number;
+}
+export interface MdbaseFileListOptions extends ConnectRequestOptions {
+    folder?: string;
+    pageSize?: number;
+    /** Called while a cold or changed collection builds its verified binary index. */
+    onIndexing?: () => void;
+}
+export interface MdbaseFileUploadOptions extends ConnectRequestOptions {
+    mediaType?: string;
+    ifRevision?: string;
+    concurrency?: number;
+    /** Stable retry key. Reuse it after an ambiguous failure to resume or replay commit. */
+    transferId?: string;
+    onProgress?: (progress: MdbaseFileProgress) => void;
+}
+export type MdbaseFileStreamUploadOptions = Omit<MdbaseFileUploadOptions, "concurrency">;
+export interface MdbaseFileDownloadOptions extends ConnectRequestOptions {
+    concurrency?: number;
+    onProgress?: (progress: MdbaseFileProgress) => void;
+}
+export interface MdbaseFileMoveOptions extends ConnectRequestOptions {
+    ifRevision?: string;
+    /** Reuse after an ambiguous network failure to receive the original receipt. */
+    mutationId?: string;
+}
+export interface MdbaseFileDeleteOptions extends ConnectRequestOptions {
+    ifRevision?: string;
+    /** Reuse after an ambiguous network failure to receive the original receipt. */
+    mutationId?: string;
+}
+/** Internal transport seam used by direct and relayed encrypted chunk delivery. */
+export interface MdbaseFramedFileTransport {
+    uploadChunk(session: FileTransferSession, chunkIndex: number, bytes: Uint8Array, signal?: AbortSignal): Promise<void>;
+    downloadChunk(session: FileTransferSession, chunkIndex: number, signal?: AbortSignal): Promise<Uint8Array>;
+}
+/** Internal authenticated hosted-object delivery seam. */
+export interface MdbaseHostedFileTransport {
+    downloadPart(session: FileTransferSession, partIndex: number, expectedLength: number, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+}
+type ControlRequest = <Result>(method: "GET" | "POST" | "DELETE", path?: string, input?: unknown, signal?: AbortSignal) => Promise<Result>;
+/** Ergonomic facade over resumable, authority-specific file delivery. */
+export declare class MdbaseFileClient {
+    private readonly capability;
+    private readonly request;
+    private readonly framed?;
+    private readonly hosted?;
+    private readonly timeouts;
+    constructor(capability: () => FileCapability | null, request: ControlRequest, framed?: MdbaseFramedFileTransport | undefined, hosted?: MdbaseHostedFileTransport | undefined, timeouts?: ResolvedConnectTimeouts);
+    list(options?: MdbaseFileListOptions): AsyncGenerator<CollectionFileDescriptor>;
+    upload(path: string, source: MdbaseFileSource, options?: MdbaseFileUploadOptions): Promise<CollectionFileDescriptor>;
+    private uploadWithinBudget;
+    /**
+     * Upload a one-shot byte stream without accumulating multiple file parts.
+     * SDK memory is bounded by one assembled negotiated part plus at most one
+     * source chunk; a single-part upload may therefore hold the complete file.
+     * Reuse `transferId` with a newly opened source after an ambiguous failure.
+     */
+    uploadStream(path: string, source: MdbaseFileStreamSource, options?: MdbaseFileStreamUploadOptions): Promise<CollectionFileDescriptor>;
+    private uploadStreamWithinBudget;
+    private uploadKnownSource;
+    download(file: CollectionFileDescriptor, options?: MdbaseFileDownloadOptions): Promise<Blob>;
+    /** Download and verify a file with network backpressure and bounded buffering. */
+    downloadStream(file: CollectionFileDescriptor, options?: MdbaseFileDownloadOptions): Promise<ReadableStream<Uint8Array>>;
+    private openDownloadStream;
+    downloadBytes(file: CollectionFileDescriptor, options?: MdbaseFileDownloadOptions): Promise<Uint8Array>;
+    move(file: CollectionFileDescriptor, path: string, options?: MdbaseFileMoveOptions): Promise<CollectionFileDescriptor>;
+    private moveWithinBudget;
+    delete(file: CollectionFileDescriptor, options?: MdbaseFileDeleteOptions): Promise<MdbaseFileDeleteReceipt>;
+    private deleteWithinBudget;
+    private uploadPart;
+    private tryReplayUploadCommit;
+    private commitUpload;
+    private requireAction;
+    private abort;
+}
+export {};