gm-pantry 0.2.0 → 0.3.1

package/dist/hash.d.ts

@@ -0,0 +1,15 @@
+export interface HashOptions {
+    /** Called after every chunk with the bytes hashed so far. */
+    onProgress?: (bytes: number) => void;
+    signal?: AbortSignal;
+}
+export interface Hashed {
+    sha256: string;
+    size: number;
+}
+/** Hashes a stream chunk by chunk; memory use is one chunk, whatever the size. */
+export declare function hashStream(stream: ReadableStream<Uint8Array>, { onProgress, signal }?: HashOptions): Promise<Hashed>;
+/** Hashes a Blob or File (a 4 GB file works: it is read as a stream, never as one buffer). */
+export declare const hashBlob: (blob: Blob, options?: HashOptions) => Promise<Hashed>;
+/** Lowercase hex SHA-256 of bytes already in memory. */
+export declare function sha256Hex(bytes: BufferSource): Promise<string>;

package/dist/hash.js

@@ -0,0 +1,31 @@
+// Streaming SHA-256 for archives too big to buffer. Web Crypto has no incremental digest, so hash-wasm does the work.
+// Browser-safe: no Node APIs.
+import { createSHA256 } from "hash-wasm";
+/** Hashes a stream chunk by chunk; memory use is one chunk, whatever the size. */
+export async function hashStream(stream, { onProgress, signal } = {}) {
+    const hasher = await createSHA256();
+    const reader = stream.getReader();
+    let size = 0;
+    try {
+        for (;;) {
+            signal?.throwIfAborted();
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            hasher.update(value);
+            size += value.byteLength;
+            onProgress?.(size);
+        }
+    }
+    catch (e) {
+        await reader.cancel().catch(() => { });
+        throw e;
+    }
+    return { sha256: hasher.digest(), size };
+}
+/** Hashes a Blob or File (a 4 GB file works: it is read as a stream, never as one buffer). */
+export const hashBlob = (blob, options) => hashStream(blob.stream(), options);
+/** Lowercase hex SHA-256 of bytes already in memory. */
+export async function sha256Hex(bytes) {
+    return [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export { LIMITS, RepoError, isSecureUrl, parseRepo, parseShard, resolveUrl } fro
 export { loadRepo, type LoadOptions, type ShardCache } from "./load.ts";
 export { verifyArchive, type VerifyResult } from "./verify.ts";
 export { validateHosting, type Check, type HostingReport } from "./hosting.ts";
+export { hashBlob, hashStream, type HashOptions, type Hashed } from "./hash.ts";
+export { addVersion, emptyRepo, inlineShards, removeGame, removeVersion, serialize, slug, splitShards, updateGame, type GamePatch, type Json, type NewVersion, type SerializeOptions, type Serialized, } from "./builder.ts";

package/dist/index.js

@@ -2,3 +2,5 @@ export { LIMITS, RepoError, isSecureUrl, parseRepo, parseShard, resolveUrl } fro
 export { loadRepo } from "./load.js";
 export { verifyArchive } from "./verify.js";
 export { validateHosting } from "./hosting.js";
+export { hashBlob, hashStream } from "./hash.js";
+export { addVersion, emptyRepo, inlineShards, removeGame, removeVersion, serialize, slug, splitShards, updateGame, } from "./builder.js";

package/dist/s3.d.ts

@@ -0,0 +1,177 @@
+import type { Check } from "./hosting.ts";
+export interface S3Config {
+    endpoint: string;
+    region: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    /** Key prefix inside the bucket (the repo lives under it). */
+    prefix?: string;
+    /** `endpoint/bucket/key` instead of `bucket.endpoint/key`. Default: true unless the endpoint is amazonaws.com. */
+    forcePathStyle?: boolean;
+    /** Transport; defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Wait before the first retry of a failed part (doubles each time). Default 500. */
+    retryDelayMs?: number;
+}
+export declare class S3Error extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** repo.json changed under the publisher (or did not match the ETag it was loaded with). */
+export declare class ConflictError extends Error {
+}
+export interface UploadState {
+    uploadId: string;
+    size: number;
+    partSize: number;
+    parts: {
+        partNumber: number;
+        etag: string;
+    }[];
+}
+export interface PutOptions {
+    contentType?: string;
+    cacheControl?: string;
+    /** Stored as `x-amz-meta-<key>`. */
+    metadata?: Record<string, string>;
+    /** Only write when the current ETag matches. */
+    ifMatch?: string;
+    /** `"*"`: only write when the key does not exist. */
+    ifNoneMatch?: string;
+    signal?: AbortSignal;
+}
+export interface UploadOptions extends Omit<PutOptions, "ifMatch" | "ifNoneMatch"> {
+    /** Default 16 MiB; raised so the file fits in 10 000 parts, never below the 5 MiB S3 minimum. */
+    partSize?: number;
+    /** Parts in flight at once. Default 3. */
+    concurrency?: number;
+    onProgress?: (uploaded: number, total: number) => void;
+    /** Called after the upload is created and after every part: persist it, and pass it back as `resume` after a crash or abort. */
+    onState?: (state: UploadState) => void;
+    resume?: UploadState;
+}
+export declare const choosePartSize: (size: number, requested?: number) => number;
+export declare const contentTypeOf: (key: string) => string;
+export declare class S3Store {
+    private aws;
+    private fetchImpl;
+    private prefix;
+    config: S3Config;
+    constructor(config: S3Config);
+    /** The URL of a key under the prefix (`""` is the bucket itself). */
+    url(key?: string, query?: Record<string, string>): URL;
+    private send;
+    private meta;
+    putObject(key: string, body: string | Uint8Array | Blob, o?: PutOptions): Promise<{
+        etag: string;
+    }>;
+    /** The object's bytes and ETag, or undefined when it does not exist. */
+    getObject(key: string, signal?: AbortSignal): Promise<{
+        bytes: Uint8Array;
+        etag: string;
+    } | undefined>;
+    headObject(key: string, signal?: AbortSignal): Promise<{
+        etag: string;
+        size: number;
+        metadata: Record<string, string>;
+    } | undefined>;
+    deleteObject(key: string, signal?: AbortSignal): Promise<void>;
+    /** One page of keys under `sub` (relative to the store prefix). */
+    listKeys(sub?: string, maxKeys?: number): Promise<string[]>;
+    private createUpload;
+    /** Parts the service already holds for an upload; undefined when the upload no longer exists. */
+    private listParts;
+    abortUpload(key: string, uploadId: string): Promise<void>;
+    /** Multipart uploads started and never completed under `sub`. */
+    listUploads(sub?: string): Promise<{
+        key: string;
+        uploadId: string;
+    }[]>;
+    /** Aborts every incomplete multipart upload under `sub` (they are billed as storage until aborted). Returns how many. */
+    abortIncompleteUploads(sub?: string): Promise<number>;
+    /**
+     * Uploads a Blob or File: one PUT when it fits in a part, else a resumable multipart upload.
+     * Aborting through `signal` leaves the upload in place so `resume` can continue it; `abortUpload` discards it.
+     */
+    uploadFile(key: string, blob: Blob, o?: UploadOptions): Promise<{
+        etag: string;
+        multipart: boolean;
+    }>;
+    private uploadPart;
+    private retrying;
+    /** Reports, one check each, whether this key can list, write and delete. Distinguishes bad credentials, a missing bucket, a wrong region and missing permissions. */
+    testConnection(): Promise<{
+        ok: boolean;
+        checks: Check[];
+    }>;
+    /** PutBucketCors. Only usable where CORS is not enforced (Node, the CLI, a desktop app): a browser cannot call it before a CORS rule exists. Replaces the bucket's whole CORS configuration. */
+    setCors(origins?: string[]): Promise<void>;
+}
+export interface PublishInput {
+    /** The bytes of repo.json, from `serialize`. */
+    repoJson: string;
+    /** Shard files by repo-relative url, from `serialize`. */
+    shards: Map<string, string>;
+    /** Shards to delete once repo.json is live, from `serialize`; the ones the remote repo.json lists and the new one does not are added. */
+    orphans?: string[];
+}
+export interface PublishOptions {
+    /** Archives to upload before repo.json; `url` is the repo-relative url they are listed under. With `sha256` set, an archive the bucket already holds (same size and recorded hash) is skipped. */
+    archives?: {
+        url: string;
+        body: Blob;
+        sha256?: string;
+    }[];
+    /** The ETag of the repo.json this edit started from (what the caller loaded); null: there was none. Default: whatever is there now. */
+    ifMatch?: string | null;
+    upload?: Omit<UploadOptions, "resume" | "onState" | "onProgress" | "metadata" | "contentType">;
+    /** Persist and return the multipart state per archive url. */
+    resume?: (url: string) => UploadState | undefined;
+    onState?: (url: string, state: UploadState) => void;
+    onProgress?: (url: string, uploaded: number, total: number) => void;
+}
+export interface PublishResult {
+    uploaded: string[];
+    skipped: string[];
+    deleted: string[];
+    /** False: the service ignored conditional writes, so a concurrent publisher could have been overwritten (last writer wins). */
+    conditional: boolean;
+}
+/**
+ * Uploads archives and new shards first and repo.json last, so a reader never sees a repo.json that points at missing files;
+ * then deletes the shards nothing lists any more. repo.json is written with `If-Match` (or `If-None-Match: *`) where the service supports it.
+ */
+export declare function publishRepo(store: S3Store, input: PublishInput, o?: PublishOptions): Promise<PublishResult>;
+/** Ready-to-paste CORS configuration for the services that matter. `origin` is the web app that will publish ("*" for any). */
+export declare function corsSnippets(origin?: string): {
+    s3: {
+        json: string;
+        command: string;
+    };
+    r2: {
+        json: string;
+        wranglerJson: string;
+        command: string;
+    };
+    b2: {
+        json: string;
+        command: string;
+    };
+};
+export interface CorsReport {
+    ok: boolean;
+    checks: Check[];
+    snippets: ReturnType<typeof corsSnippets>;
+}
+/**
+ * What a browser needs from the bucket: repo.json readable with CORS, ETag exposed, Range, and a preflight that allows the PUT, POST and DELETE a publisher sends.
+ * `publicBaseUrl` is where the repo is served; the preflight goes to `opts.writeUrl` (the S3 API endpoint the browser uploads to) when that differs.
+ * Run from a browser to see exactly what the browser sees; run from Node, `origin` is sent as the Origin header.
+ */
+export declare function checkCors(publicBaseUrl: string, origin?: string, opts?: {
+    writeUrl?: string;
+    fetch?: typeof fetch;
+}): Promise<CorsReport>;