@minhvuong/pirate-storage-client 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @minhvuong/pirate-storage-client
+
+Browser uploader for the consumer-owned `@minhvuong/pirate-storage-server` endpoint.
+
+- file slicing below platform request-body limits
+- bounded parallel part uploads
+- whole-file SHA-256 before session creation or resume, so a same-name/size replacement is rejected
+- progress, active-request pause/resume, cancellation, and retry
+- resumable session IDs
+- confirmed rollback: `cancel()` surfaces cleanup failures instead of claiming success
+- optional separately-installed preview generators
+
+The browser never receives Discord credentials and never uploads directly to Discord.
+
+`pause()` aborts active browser multipart requests without aborting the durable session. The server
+finishes safely tracking any provider request already accepted; `resume()` reuses those journaled
+parts and sends only missing work. Once final manifest commit begins, the task is intentionally no
+longer pausable.

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import type { GeneratedPreview, PreviewGenerator, StorageReceipt } from "@minhvuong/pirate-storage";
+export interface ClientUploadResult<ServerData = unknown> {
+    receipt: StorageReceipt;
+    serverData: ServerData;
+}
+export interface ClientUploadProgress {
+    phase: "preview" | "hashing" | "uploading" | "finalizing";
+    uploadedBytes: number;
+    hashedBytes: number;
+    totalBytes: number;
+    completedParts: number;
+    totalParts: number;
+    percentage: number;
+}
+export interface CreateUploaderOptions {
+    endpoint?: string;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: typeof globalThis.fetch;
+    previewGenerators?: readonly PreviewGenerator[];
+}
+export interface ClientUploadOptions<Input = unknown> {
+    input?: Input;
+    sessionId?: string;
+    concurrency?: number;
+    retries?: number;
+    preview?: GeneratedPreview | false;
+    previewGenerator?: string | false;
+    onProgress?: (progress: ClientUploadProgress) => void;
+    onPreviewProgress?: (progress: {
+        stage: string;
+        percentage: number;
+    }) => void;
+}
+export interface UploadTask<Result> {
+    readonly done: Promise<Result>;
+    readonly sessionId?: string;
+    readonly state: "running" | "paused" | "failed" | "complete" | "cancelled";
+    pause(): void;
+    resume(): void;
+    cancel(): Promise<void>;
+    retryFailed(): Promise<Result>;
+}
+export declare class StorageUploader {
+    #private;
+    constructor(options?: CreateUploaderOptions);
+    createUpload<ServerData = unknown, Input = unknown>(route: string, file: File, options?: ClientUploadOptions<Input>): UploadTask<ClientUploadResult<ServerData>>;
+    uploadFiles<ServerData = unknown, Input = unknown>(route: string, files: readonly File[], options?: ClientUploadOptions<Input> & {
+        fileConcurrency?: number;
+    }): Promise<Array<ClientUploadResult<ServerData>>>;
+    uploadDirect<ServerData = unknown, Input = unknown>(route: string, file: File, options?: Pick<ClientUploadOptions<Input>, "input">): Promise<ClientUploadResult<ServerData>>;
+}
+export declare function createUploader(options?: CreateUploaderOptions): StorageUploader;

package/dist/index.js

@@ -0,0 +1,393 @@
+// src/index.ts
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
+
+class MultipartUploadTask {
+  done;
+  #state = "running";
+  #sessionId;
+  #abortController = new AbortController;
+  #pauseController = new AbortController;
+  #pausable = true;
+  #resumeWaiters = [];
+  #execute;
+  #abortRemote;
+  constructor(execute, abortRemote) {
+    this.#execute = () => execute(this);
+    this.#abortRemote = abortRemote;
+    this.done = Promise.resolve().then(() => this.#run());
+  }
+  get sessionId() {
+    return this.#sessionId;
+  }
+  get state() {
+    return this.#state;
+  }
+  get signal() {
+    return this.#abortController.signal;
+  }
+  requestSignal() {
+    return AbortSignal.any([
+      this.#abortController.signal,
+      this.#pauseController.signal
+    ]);
+  }
+  setSessionId(value) {
+    this.#sessionId = value;
+  }
+  pause() {
+    if (this.#state !== "running" || !this.#pausable)
+      return;
+    this.#state = "paused";
+    this.#pauseController.abort(new UploadPausedError);
+  }
+  resume() {
+    if (this.#state !== "paused")
+      return;
+    this.#pauseController = new AbortController;
+    this.#state = "running";
+    for (const resolve of this.#resumeWaiters.splice(0))
+      resolve();
+  }
+  async waitIfPaused() {
+    if (this.#state !== "paused")
+      return;
+    await new Promise((resolve, reject) => {
+      this.#resumeWaiters.push(resolve);
+      this.signal.addEventListener("abort", () => reject(this.signal.reason), {
+        once: true
+      });
+    });
+  }
+  markFinalizing() {
+    this.#pausable = false;
+  }
+  async cancel() {
+    if (this.#state === "complete" || this.#state === "cancelled")
+      return;
+    this.#state = "cancelled";
+    this.#abortController.abort(new DOMException("Upload cancelled", "AbortError"));
+    for (const resolve of this.#resumeWaiters.splice(0))
+      resolve();
+    await this.#abortRemote();
+  }
+  async retryFailed() {
+    if (this.#state !== "failed")
+      return this.done;
+    this.#state = "running";
+    this.#abortController = new AbortController;
+    this.#pauseController = new AbortController;
+    this.#pausable = true;
+    return this.#run();
+  }
+  async#run() {
+    try {
+      const result = await this.#execute();
+      this.#state = "complete";
+      return result;
+    } catch (error) {
+      if (this.#state !== "cancelled")
+        this.#state = "failed";
+      throw error;
+    }
+  }
+}
+
+class StorageUploader {
+  #endpoint;
+  #headers;
+  #fetch;
+  #previewGenerators;
+  constructor(options = {}) {
+    this.#endpoint = (options.endpoint ?? "/api/storage").replace(/\/$/, "");
+    this.#headers = options.headers;
+    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.#previewGenerators = options.previewGenerators ?? [];
+  }
+  createUpload(route, file, options = {}) {
+    let task;
+    task = new MultipartUploadTask(() => this.#runMultipart(task, route, file, options), async () => {
+      if (!task.sessionId)
+        return;
+      const response = await this.#request(`${route}/multipart/${task.sessionId}`, {
+        method: "DELETE",
+        headers: inputHeader(options.input)
+      });
+      await ensureOk(response);
+    });
+    return task;
+  }
+  async uploadFiles(route, files, options = {}) {
+    const concurrency = positiveInteger(options.fileConcurrency ?? 2, "fileConcurrency");
+    const results = [];
+    results.length = files.length;
+    let cursor = 0;
+    await Promise.all(Array.from({ length: Math.min(concurrency, files.length) }, async () => {
+      while (cursor < files.length) {
+        const index = cursor++;
+        const file = files[index];
+        if (file)
+          results[index] = await this.createUpload(route, file, options).done;
+      }
+    }));
+    return results;
+  }
+  async uploadDirect(route, file, options = {}) {
+    const response = await this.#request(route, {
+      method: "POST",
+      headers: {
+        ...inputHeader(options.input),
+        "content-type": file.type || "application/octet-stream",
+        "x-storage-file-name": encodeURIComponent(file.name),
+        "x-storage-file-size": String(file.size)
+      },
+      body: file
+    });
+    return parseResponse(response);
+  }
+  async#runMultipart(task, route, file, options) {
+    const previewPromise = this.#preparePreview(file, options, task.signal);
+    const fileSha256 = await hashFile(file, task.signal, () => task.waitIfPaused(), (hashedBytes2) => {
+      options.onProgress?.({
+        phase: "hashing",
+        uploadedBytes: 0,
+        hashedBytes: hashedBytes2,
+        totalBytes: file.size,
+        completedParts: 0,
+        totalParts: 0,
+        percentage: Math.round(hashedBytes2 / file.size * 100)
+      });
+    });
+    let session;
+    if (task.sessionId ?? options.sessionId) {
+      const sessionId = task.sessionId ?? options.sessionId;
+      task.setSessionId(sessionId);
+      const response2 = await this.#request(`${route}/multipart/${sessionId}`, {
+        method: "GET",
+        headers: {
+          ...inputHeader(options.input),
+          "x-storage-file-sha256": fileSha256
+        },
+        signal: task.signal
+      });
+      session = await parseResponse(response2);
+      if (session.status === "complete" && session.result) {
+        return session.result;
+      }
+    } else {
+      const response2 = await this.#request(`${route}/multipart`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          file: {
+            name: file.name,
+            size: file.size,
+            contentType: file.type || "application/octet-stream",
+            sha256: fileSha256
+          },
+          input: options.input
+        }),
+        signal: task.signal
+      });
+      session = await parseResponse(response2);
+      task.setSessionId(session.sessionId);
+    }
+    const totalParts = Math.ceil(file.size / session.partSize);
+    const completed = new Set(session.completedParts);
+    const hashedBytes = file.size;
+    let uploadedBytes = [...completed].reduce((total, index) => total + Math.min(session.partSize, file.size - index * session.partSize), 0);
+    const concurrency = positiveInteger(options.concurrency ?? ("maxConcurrency" in session ? session.maxConcurrency ?? 3 : 3), "concurrency");
+    const retries = nonNegativeInteger(options.retries ?? 3, "retries");
+    const inFlight = new Set;
+    const allOperations = [];
+    const report = (phase) => {
+      options.onProgress?.({
+        phase,
+        uploadedBytes,
+        hashedBytes,
+        totalBytes: file.size,
+        completedParts: completed.size,
+        totalParts,
+        percentage: phase === "hashing" ? Math.round(Math.min(hashedBytes, file.size) / file.size * 100) : phase === "finalizing" ? 100 : Math.round(Math.min(uploadedBytes, file.size) / file.size * 100)
+      });
+    };
+    report("uploading");
+    for (let index = 0;index < totalParts; index += 1) {
+      await task.waitIfPaused();
+      task.signal.throwIfAborted();
+      const start = index * session.partSize;
+      const end = Math.min(file.size, start + session.partSize);
+      const bytes = new Uint8Array(await file.slice(start, end).arrayBuffer());
+      if (completed.has(index))
+        continue;
+      const operation = retryPart(async (signal) => {
+        await task.waitIfPaused();
+        const response2 = await this.#request(`${route}/multipart/${session.sessionId}/${index}`, {
+          method: "PUT",
+          headers: {
+            ...inputHeader(options.input),
+            "content-type": "application/octet-stream"
+          },
+          body: bytes,
+          signal
+        });
+        await ensureOk(response2);
+        completed.add(index);
+        uploadedBytes += bytes.byteLength;
+        report("uploading");
+      }, retries, task);
+      inFlight.add(operation);
+      allOperations.push(operation);
+      operation.then(() => inFlight.delete(operation), () => inFlight.delete(operation));
+      if (inFlight.size >= concurrency)
+        await Promise.race(inFlight);
+    }
+    await Promise.all(allOperations);
+    await task.waitIfPaused();
+    const preview = await previewPromise;
+    await task.waitIfPaused();
+    task.markFinalizing();
+    report("finalizing");
+    const headers = {
+      ...inputHeader(options.input),
+      "x-storage-file-name": encodeURIComponent(file.name),
+      "x-storage-file-sha256": fileSha256
+    };
+    let body;
+    if (preview) {
+      headers["content-type"] = preview.file.type;
+      headers["x-storage-preview-width"] = String(preview.width);
+      headers["x-storage-preview-height"] = String(preview.height);
+      body = preview.file;
+    }
+    const response = await this.#request(`${route}/multipart/${session.sessionId}/complete`, {
+      method: "POST",
+      headers,
+      body,
+      signal: task.signal
+    });
+    return parseResponse(response);
+  }
+  async#preparePreview(file, options, signal) {
+    if (options.preview === false || options.previewGenerator === false)
+      return;
+    if (options.preview)
+      return options.preview;
+    const source = {
+      name: file.name,
+      contentType: file.type || "application/octet-stream",
+      size: file.size,
+      stream: () => file.stream(),
+      blob: file
+    };
+    const generators = options.previewGenerator ? this.#previewGenerators.filter((generator) => generator.id === options.previewGenerator) : this.#previewGenerators;
+    for (const generator of generators) {
+      if (await generator.supports(source)) {
+        return generator.generate(source, {
+          signal,
+          onProgress: options.onPreviewProgress
+        });
+      }
+    }
+    return;
+  }
+  async#request(path, init) {
+    const common = typeof this.#headers === "function" ? await this.#headers() : this.#headers;
+    const headers = new Headers(common);
+    new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+    return this.#fetch(`${this.#endpoint}/${path}`, { ...init, headers });
+  }
+}
+async function hashFile(file, signal, waitIfPaused, onProgress) {
+  const hasher = sha256.create();
+  const hashChunkSize = 4 * 1024 * 1024;
+  let hashedBytes = 0;
+  for (let start = 0;start < file.size; start += hashChunkSize) {
+    await waitIfPaused();
+    signal.throwIfAborted();
+    const bytes = new Uint8Array(await file.slice(start, Math.min(file.size, start + hashChunkSize)).arrayBuffer());
+    hasher.update(bytes);
+    hashedBytes += bytes.byteLength;
+    onProgress(hashedBytes);
+  }
+  return bytesToHex(hasher.digest());
+}
+function createUploader(options = {}) {
+  return new StorageUploader(options);
+}
+async function retryPart(operation, retries, task) {
+  let lastError;
+  let failures = 0;
+  while (failures <= retries) {
+    await task.waitIfPaused();
+    task.signal.throwIfAborted();
+    const signal = task.requestSignal();
+    try {
+      return await operation(signal);
+    } catch (error) {
+      lastError = error;
+      if (task.signal.aborted)
+        break;
+      if (isUploadPaused(error) || signal.reason instanceof UploadPausedError) {
+        await task.waitIfPaused();
+        continue;
+      }
+      if (failures === retries)
+        break;
+      await abortableDelay(Math.min(250 * 2 ** failures, 2000), task.signal);
+      failures += 1;
+    }
+  }
+  throw lastError;
+}
+
+class UploadPausedError extends Error {
+  name = "UploadPausedError";
+  constructor() {
+    super("Upload paused");
+  }
+}
+function isUploadPaused(error) {
+  return error instanceof UploadPausedError || error instanceof Error && error.name === "UploadPausedError";
+}
+async function abortableDelay(ms, signal) {
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      reject(signal.reason);
+    }, { once: true });
+  });
+}
+function inputHeader(value) {
+  return value === undefined ? {} : { "x-storage-input": encodeURIComponent(JSON.stringify(value)) };
+}
+async function parseResponse(response) {
+  await ensureOk(response);
+  return response.json();
+}
+async function ensureOk(response) {
+  if (response.ok)
+    return;
+  let message = `Storage request failed (${response.status})`;
+  try {
+    const body = await response.clone().json();
+    if (body.error)
+      message = body.error;
+  } catch {}
+  throw new Error(message);
+}
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0)
+    throw new Error(`${name} must be positive`);
+  return value;
+}
+function nonNegativeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error(`${name} cannot be negative`);
+  return value;
+}
+export {
+  createUploader,
+  StorageUploader
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@minhvuong/pirate-storage-client",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target browser --packages external && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@minhvuong/pirate-storage": "workspace:*",
+    "@noble/hashes": "^2.0.1"
+  },
+  "devDependencies": {
+    "@minhvuong/pirate-storage-server": "workspace:*",
+    "@types/bun": "^1.3.10",
+    "typescript": "catalog:"
+  }
+}