@mdbase-dev/connect 0.1.0-beta.31 → 0.1.0-beta.33

package/dist/crypto.js

@@ -1,4 +1,4 @@
-import { ENCRYPTED_RELAY_PROTOCOL_VERSION, AUTHORITY_PROOF_DOMAIN, AUTHORITY_PROOF_HEADERS, AUTHORITY_PROOF_VERSION, RELAY_ENCRYPTION_SUITE, isConnectProblem } from "@mdbase-dev/connect-protocol";
+import { OPERATION_TRANSPORT_PROTOCOL_VERSION, GRANT_ENCRYPTION_PROTOCOL_VERSION, AUTHORITY_PROOF_DOMAIN, AUTHORITY_PROOF_HEADERS, AUTHORITY_PROOF_VERSION, RELAY_ENCRYPTION_SUITE, isConnectProblem } from "@mdbase-dev/connect-protocol";
 const DATABASE_NAME = "mdbase-connect-keys";
 const STORE_NAME = "grant-keys";
 const MAX_U64 = 18446744073709551615n;
@@ -272,7 +272,7 @@ function context(binding) {
     const value = binding.encryption;
     return [
         "mdbase-connect",
-        ENCRYPTED_RELAY_PROTOCOL_VERSION,
+        OPERATION_TRANSPORT_PROTOCOL_VERSION,
         value.suite,
         binding.grantId,
         binding.applicationId,
@@ -288,7 +288,7 @@ function aad(metadata, direction) {
 function envelopeMetadata(metadata) {
     const encryption = metadata.binding.encryption;
     return {
-        protocol_version: ENCRYPTED_RELAY_PROTOCOL_VERSION,
+        protocol_version: OPERATION_TRANSPORT_PROTOCOL_VERSION,
         suite: RELAY_ENCRYPTION_SUITE,
         request_id: metadata.requestId,
         grant_id: metadata.binding.grantId,
@@ -317,7 +317,7 @@ function sameEnvelopeMetadata(request, response) {
         && request.counter === response.counter;
 }
 export function validateGrantEncryption(encryption) {
-    if (encryption.protocol_version !== ENCRYPTED_RELAY_PROTOCOL_VERSION
+    if (encryption.protocol_version !== GRANT_ENCRYPTION_PROTOCOL_VERSION
         || encryption.suite !== RELAY_ENCRYPTION_SUITE
         || !Number.isSafeInteger(encryption.scope_epoch)
         || encryption.scope_epoch <= 0

package/dist/external-store.d.ts

@@ -0,0 +1,10 @@
+/** Minimal framework-neutral shape consumed by React's useSyncExternalStore. */
+export interface MdbaseExternalStore<Snapshot> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): Snapshot;
+}
+/**
+ * Adapt an existing SDK session without introducing another cache or state
+ * owner. The stable object can be passed directly to useSyncExternalStore.
+ */
+export declare function externalStore<Snapshot>(source: MdbaseExternalStore<Snapshot>): MdbaseExternalStore<Snapshot>;

package/dist/external-store.js

@@ -0,0 +1,10 @@
+/**
+ * Adapt an existing SDK session without introducing another cache or state
+ * owner. The stable object can be passed directly to useSyncExternalStore.
+ */
+export function externalStore(source) {
+    return {
+        subscribe: (listener) => source.subscribe(listener),
+        getSnapshot: () => source.getSnapshot()
+    };
+}

package/dist/file-transfer-internals.d.ts

@@ -0,0 +1,23 @@
+import type { FileTransferSession, FileTransferStatus, PreparedFilePart } from "@mdbase-dev/connect-protocol";
+import { MdbaseConnectError } from "./errors.js";
+export declare const MAX_OBJECT_ATTEMPTS = 3;
+export declare const MAX_BUFFERED_DOWNLOAD_BYTES: number;
+export declare const UUID: RegExp;
+export declare const SHA256_DIGEST: RegExp;
+export type FileSource = Blob | ArrayBuffer | ArrayBufferView;
+export type UploadPartBody = Blob | Uint8Array<ArrayBuffer>;
+export declare function hashBlob(blob: Blob, signal: AbortSignal | undefined, progress: (transferredBytes: number) => void): Promise<string>;
+export declare function sourceBlob(source: FileSource, mediaType?: string): Blob;
+export declare function uploadBodyLength(body: UploadPartBody): number;
+export declare function uploadBodyBytes(body: UploadPartBody): Promise<Uint8Array<ArrayBuffer>>;
+export declare function validConcurrency(value?: number): number;
+export declare function validPageSize(value: number): number;
+export declare function requireTransferSession(session: FileTransferSession, transferId: string, direction: "upload" | "download"): void;
+export declare function requireTransferStatus(status: FileTransferStatus, session: FileTransferSession): void;
+export declare function chunkLength(totalSize: number, partSize: number, index: number): number;
+export declare function retryChunk<Result>(work: () => Promise<Result>, signal?: AbortSignal): Promise<Result>;
+export declare function requirePreparedPart(part: PreparedFilePart, transferId: string, partIndex: number, offset: number, contentLength: number, method: "PUT"): void;
+export declare function browserObjectHeaders(headers: Record<string, string>): Headers;
+export declare function mapConcurrent<Result>(count: number, concurrency: number, work: (index: number) => Promise<Result>): Promise<Result[]>;
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export declare function normalizeFileError(error: unknown): MdbaseConnectError;

package/dist/file-transfer-internals.js

@@ -0,0 +1,224 @@
+import { MdbaseConnectError, connectError } from "./errors.js";
+import { IncrementalSha256 } from "./file-sha256.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_OBJECT_ATTEMPTS; attempt += 1) {
+        throwIfAborted(signal);
+        try {
+            return await work();
+        }
+        catch (error) {
+            if (signal?.aborted || attempt === MAX_OBJECT_ATTEMPTS)
+                throw error;
+        }
+    }
+    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

@@ -1,5 +1,26 @@
-import type { CollectionFileDescriptor, DeleteFileReceipt, FileCapability, FileTransferSession } from "@mdbase-dev/connect-protocol";
-export type MdbaseFileSource = Blob | ArrayBuffer | ArrayBufferView;
+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;
@@ -17,37 +38,32 @@ export interface MdbaseFileProgress {
     transferredBytes: number;
     totalBytes: number;
 }
-export interface MdbaseFileListOptions {
+export interface MdbaseFileListOptions extends ConnectRequestOptions {
     folder?: string;
     pageSize?: number;
-    signal?: AbortSignal;
 }
-export interface MdbaseFileUploadOptions {
+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;
-    signal?: AbortSignal;
     onProgress?: (progress: MdbaseFileProgress) => void;
 }
 export type MdbaseFileStreamUploadOptions = Omit<MdbaseFileUploadOptions, "concurrency">;
-export interface MdbaseFileDownloadOptions {
+export interface MdbaseFileDownloadOptions extends ConnectRequestOptions {
     concurrency?: number;
-    signal?: AbortSignal;
     onProgress?: (progress: MdbaseFileProgress) => void;
 }
-export interface MdbaseFileMoveOptions {
+export interface MdbaseFileMoveOptions extends ConnectRequestOptions {
     ifRevision?: string;
     /** Reuse after an ambiguous network failure to receive the original receipt. */
     mutationId?: string;
-    signal?: AbortSignal;
 }
-export interface MdbaseFileDeleteOptions {
+export interface MdbaseFileDeleteOptions extends ConnectRequestOptions {
     ifRevision?: string;
     /** Reuse after an ambiguous network failure to receive the original receipt. */
     mutationId?: string;
-    signal?: AbortSignal;
 }
 /** Internal transport seam used by direct and relayed encrypted chunk delivery. */
 export interface MdbaseFramedFileTransport {
@@ -65,9 +81,11 @@ export declare class MdbaseFileClient {
     private readonly request;
     private readonly framed?;
     private readonly hosted?;
-    constructor(capability: () => FileCapability | null, request: ControlRequest, framed?: MdbaseFramedFileTransport | undefined, hosted?: MdbaseHostedFileTransport | undefined);
+    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
@@ -75,13 +93,17 @@ export declare class MdbaseFileClient {
      * 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>;
-    delete(file: CollectionFileDescriptor, options?: MdbaseFileDeleteOptions): Promise<DeleteFileReceipt>;
+    private moveWithinBudget;
+    delete(file: CollectionFileDescriptor, options?: MdbaseFileDeleteOptions): Promise<MdbaseFileDeleteReceipt>;
+    private deleteWithinBudget;
     private uploadPart;
     private tryReplayUploadCommit;
     private commitUpload;