@mieweb/pulsevault 0.0.2 → 0.1.0

package/dist/storage/local.js

@@ -1,51 +1,101 @@
-import { FileStore } from "@tus/file-store";
-import fs from "node:fs/promises";
-import path from "node:path";
-const SIDECAR_NAME = ".pulsevault.json";
+import { FileStore } from '@tus/file-store';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 const SIDECAR_VERSION = 1;
+/** Hidden directory inside workspaceRoot that holds per-upload sidecar files. */
+const PULSEVAULT_META_DIR = '.pulsevault';
+/** Default cap on the in-memory metadata cache before evicting the oldest entry. */
+const DEFAULT_META_CACHE_LIMIT = 10_000;
+/** Map a file extension to the `Content-Type` the GET route should return. */
+function extToContentType(ext) {
+    switch (ext) {
+        case '.mp4':
+            return 'video/mp4';
+        case '.zip':
+            return 'application/zip';
+        case '.srt':
+            return 'application/x-subrip';
+        default:
+            return 'application/octet-stream';
+    }
+}
+/** Project a `Sidecar` into the shape kept in the in-memory cache. */
+function sidecarToCachedMeta(sidecar, ready) {
+    return {
+        ext: sidecar.ext,
+        ready,
+        kind: sidecar.kind ?? 'video',
+        relatedTo: sidecar.relatedTo,
+        checksum: sidecar.checksum,
+    };
+}
 export function createLocalStorage(opts) {
     const workspaceRoot = path.resolve(opts.workspaceDir);
     const datastore = new FileStore({ directory: workspaceRoot });
-    // Metadata cache keyed by videoid. Populated eagerly on reserve and lazily
-    // from the sidecar on cache-miss — so we never do a workspace-wide scan at
-    // boot and never do a per-request readdir on the GET hot path.
+    const metaCacheLimit = opts.metaCacheLimit ?? DEFAULT_META_CACHE_LIMIT;
+    // Metadata cache keyed by artifactId. Populated eagerly on reserve and
+    // lazily from the sidecar on cache-miss — so we never do a workspace-wide
+    // scan at boot and never do a per-request readdir on the GET hot path.
+    // Bounded with simple insertion-order eviction (a `Map` preserves insertion
+    // order, and re-setting a key moves it to the end) so a long-running server
+    // doesn't grow this unboundedly; a cache miss just costs an extra disk read.
     const metaCache = new Map();
-    const videoDir = (videoid) => path.join(workspaceRoot, videoid);
-    const sidecarPath = (videoid) => path.join(videoDir(videoid), SIDECAR_NAME);
-    const videoRelPath = (videoid, ext) => `video/${videoid}${ext}`;
-    const writeSidecar = async (videoid, sidecar) => {
+    const cacheSet = (artifactId, meta) => {
+        // Re-inserting moves the key to the end of iteration order, so eviction
+        // below always drops the actual least-recently-set entry.
+        metaCache.delete(artifactId);
+        metaCache.set(artifactId, meta);
+        if (metaCache.size > metaCacheLimit) {
+            const oldest = metaCache.keys().next().value;
+            if (oldest !== undefined)
+                metaCache.delete(oldest);
+        }
+    };
+    /** Absolute path to the hidden metadata directory. */
+    const sidecarDir = () => path.join(workspaceRoot, PULSEVAULT_META_DIR);
+    /** Absolute path to the sidecar JSON for a given artifactId. */
+    const sidecarPath = (artifactId) => path.join(sidecarDir(), `${artifactId}.json`);
+    /** Relative path (from workspaceRoot) to the artifact bytes. */
+    const artifactRelPath = (artifactId, kind, ext) => `${kind}/${artifactId}${ext}`;
+    const writeSidecar = async (artifactId, sidecar) => {
         // Atomic tmp + rename so a crash mid-write can never leave a truncated
         // JSON blob that `loadMeta` would then treat as corrupt.
-        const finalPath = sidecarPath(videoid);
+        const finalPath = sidecarPath(artifactId);
         const tmpPath = `${finalPath}.tmp`;
-        await fs.writeFile(tmpPath, JSON.stringify(sidecar), "utf8");
+        await fs.mkdir(sidecarDir(), { recursive: true });
+        await fs.writeFile(tmpPath, JSON.stringify(sidecar), 'utf8');
         await fs.rename(tmpPath, finalPath);
     };
-    const readSidecar = async (videoid) => {
+    const readSidecar = async (artifactId) => {
         let raw;
         try {
-            raw = await fs.readFile(sidecarPath(videoid), "utf8");
+            raw = await fs.readFile(sidecarPath(artifactId), 'utf8');
         }
         catch (err) {
-            if (err?.code === "ENOENT")
+            if (err?.code === 'ENOENT')
                 return null;
             throw err;
         }
         try {
             const parsed = JSON.parse(raw);
-            if (typeof parsed.ext !== "string")
+            if (typeof parsed.ext !== 'string')
                 return null;
-            if (typeof parsed.filename !== "string")
+            if (typeof parsed.filename !== 'string')
                 return null;
             // Older sidecars (pre-status) are treated as ready so an in-place
             // upgrade doesn't hide finalized uploads. New uploads always write a
             // `status` field explicitly.
-            const status = parsed.status === "uploading" ? "uploading" : "ready";
+            const status = parsed.status === 'uploading' ? 'uploading' : 'ready';
+            // Older sidecars without `kind` default to `"video"` — no migration.
+            const kind = parsed.kind === 'project' ? 'project' : parsed.kind === 'captions' ? 'captions' : 'video';
             return {
                 version: SIDECAR_VERSION,
                 ext: parsed.ext,
                 filename: parsed.filename,
                 status,
+                kind,
+                relatedTo: typeof parsed.relatedTo === 'string' ? parsed.relatedTo : undefined,
+                checksum: typeof parsed.checksum === 'string' ? parsed.checksum : undefined,
             };
         }
         catch {
@@ -54,104 +104,135 @@ export function createLocalStorage(opts) {
             return null;
         }
     };
-    const loadMeta = async (videoid) => {
-        const cached = metaCache.get(videoid);
+    const loadMeta = async (artifactId) => {
+        const cached = metaCache.get(artifactId);
         if (cached)
             return cached;
-        const sidecar = await readSidecar(videoid);
+        const sidecar = await readSidecar(artifactId);
         if (!sidecar)
             return null;
-        const meta = {
-            ext: sidecar.ext,
-            ready: sidecar.status === "ready",
-        };
-        metaCache.set(videoid, meta);
+        const meta = sidecarToCachedMeta(sidecar, sidecar.status === 'ready');
+        cacheSet(artifactId, meta);
         return meta;
     };
     const initialize = async () => {
-        await fs.mkdir(workspaceRoot, { recursive: true });
+        await fs.mkdir(sidecarDir(), { recursive: true });
+        // @tus/file-store creates `workspaceRoot` with mode 0777 if it doesn't already exist;
+        // tighten it so the upload tree isn't world-writable under a permissive umask.
+        await fs.chmod(workspaceRoot, 0o750).catch(() => { });
     };
-    const reserveUpload = async ({ videoid, filename, ext, }) => {
-        // Collision guard: if an upload (in-progress or ready) already exists
-        // for this videoid, refuse the new upload rather than letting
-        // @tus/file-store silently reset the metadata sidecar to offset 0 and
-        // overwrite the file chunk-by-chunk on subsequent PATCHes. Translates
-        // to HTTP 409 via @tus/server's error path.
-        const meta = await loadMeta(videoid);
-        if (meta) {
-            throw Object.assign(new Error(`videoid ${videoid} already has an upload`), { statusCode: 409, status_code: 409 });
-        }
-        const dir = videoDir(videoid);
-        await fs.mkdir(path.join(dir, "video"), { recursive: true });
-        await writeSidecar(videoid, {
+    const reserveUpload = async ({ artifactId, filename, ext, kind, relatedTo, checksum, }) => {
+        await fs.mkdir(path.join(workspaceRoot, kind), { recursive: true });
+        await fs.mkdir(sidecarDir(), { recursive: true });
+        const sidecar = {
             version: SIDECAR_VERSION,
             ext,
             filename,
-            status: "uploading",
-        });
-        metaCache.set(videoid, { ext, ready: false });
+            status: 'uploading',
+            kind,
+            relatedTo,
+            checksum,
+        };
+        // Collision guard: `wx` fails atomically with EEXIST if a sidecar already exists for
+        // this artifactId, rather than the previous read-then-write (`loadMeta` then
+        // `writeSidecar`) which left a window for two concurrent/retried requests to both pass
+        // the check before either had written — letting the second silently clobber the first's
+        // sidecar and race @tus/file-store's own offset tracking. Translates to HTTP 409 via
+        // @tus/server's error path, same as before.
+        try {
+            await fs.writeFile(sidecarPath(artifactId), JSON.stringify(sidecar), { flag: 'wx' });
+        }
+        catch (err) {
+            if (err?.code !== 'EEXIST')
+                throw err;
+            // A file already exists at this path, but `readSidecar` treats a malformed/corrupt
+            // one as absent (e.g. debris from a crash mid-write) — re-check before deciding this
+            // is a genuine collision rather than debris that's safe to overwrite.
+            const existing = await readSidecar(artifactId);
+            if (existing) {
+                throw Object.assign(new Error(`artifactId ${artifactId} already has an upload`), {
+                    statusCode: 409,
+                    status_code: 409,
+                });
+            }
+            await writeSidecar(artifactId, sidecar);
+        }
+        cacheSet(artifactId, { ext, ready: false, kind, relatedTo, checksum });
         // @tus/file-store joins this onto its configured `directory`, so the
-        // actual file lands at `<workspaceRoot>/<videoid>/video/<videoid><ext>`.
-        return `${videoid}/${videoRelPath(videoid, ext)}`;
+        // actual file lands at `<workspaceRoot>/<kind>/<artifactId><ext>`.
+        return artifactRelPath(artifactId, kind, ext);
     };
-    const resolve = async (videoid) => {
-        const meta = await loadMeta(videoid);
+    const resolve = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
         // Only serve ready uploads. In-progress uploads stay hidden — a client
         // GETting mid-upload would otherwise receive a truncated file.
         if (!meta || !meta.ready)
             return null;
-        const root = videoDir(videoid);
-        const relFile = videoRelPath(videoid, meta.ext);
+        const relFile = artifactRelPath(artifactId, meta.kind, meta.ext);
         try {
-            const stat = await fs.stat(path.join(root, relFile));
+            const stat = await fs.stat(path.join(workspaceRoot, relFile));
             if (!stat.isFile())
                 return null;
         }
         catch (err) {
-            if (err?.code === "ENOENT")
+            if (err?.code === 'ENOENT')
                 return null;
             throw err;
         }
-        return { kind: "stream", root, filename: relFile };
+        return {
+            kind: 'stream',
+            root: workspaceRoot,
+            filename: relFile,
+            contentType: extToContentType(meta.ext),
+        };
     };
-    const markReady = async (videoid) => {
-        const sidecar = await readSidecar(videoid);
+    const markReady = async (artifactId) => {
+        const sidecar = await readSidecar(artifactId);
         if (!sidecar) {
-            // No sidecar means no `reserveUpload` happened for this videoid — this
-            // is a contract violation by the caller, not a recoverable state.
-            throw new Error(`markReady: no sidecar for videoid ${videoid} (was reserveUpload called?)`);
+            // No sidecar means no `reserveUpload` happened for this artifactId —
+            // this is a contract violation by the caller, not a recoverable state.
+            throw new Error(`markReady: no sidecar for artifactId ${artifactId} (was reserveUpload called?)`);
         }
-        if (sidecar.status === "ready") {
+        if (sidecar.status === 'ready') {
             // Idempotent: already ready is fine, keep the cache consistent.
-            metaCache.set(videoid, { ext: sidecar.ext, ready: true });
+            cacheSet(artifactId, sidecarToCachedMeta(sidecar, true));
             return;
         }
-        await writeSidecar(videoid, { ...sidecar, status: "ready" });
-        metaCache.set(videoid, { ext: sidecar.ext, ready: true });
+        await writeSidecar(artifactId, { ...sidecar, status: 'ready' });
+        cacheSet(artifactId, sidecarToCachedMeta(sidecar, true));
     };
-    const remove = async (videoid) => {
-        const dir = videoDir(videoid);
-        // Drop from cache before the rm so a racing `resolve` that arrives after
-        // the rm but before the cache eviction can't hand back a stale path.
-        metaCache.delete(videoid);
-        try {
-            // Note: no `force: true` — we want ENOENT to surface so the caller
-            // (the DELETE route) can distinguish "removed something" from "nothing
-            // to remove" and return 204 vs 404 accordingly.
-            await fs.rm(dir, { recursive: true });
-            return true;
-        }
-        catch (err) {
-            if (err?.code === "ENOENT")
-                return false;
-            throw err;
-        }
+    const remove = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        // Drop from cache before rm so a racing `resolve` arriving after the
+        // rm but before cache eviction can't hand back a stale path.
+        metaCache.delete(artifactId);
+        if (!meta)
+            return false;
+        const artifactPath = path.join(workspaceRoot, meta.kind, `${artifactId}${meta.ext}`);
+        await Promise.all([
+            fs.rm(artifactPath, { force: true }),
+            fs.rm(`${artifactPath}.json`, { force: true }),
+            fs.rm(sidecarPath(artifactId), { force: true }),
+        ]);
+        return true;
     };
-    const getLocalPath = async (videoid) => {
-        const meta = await loadMeta(videoid);
+    const getLocalPath = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
         if (!meta)
             return null;
-        return path.join(workspaceRoot, videoid, "video", `${videoid}${meta.ext}`);
+        return path.join(workspaceRoot, meta.kind, `${artifactId}${meta.ext}`);
+    };
+    const getKind = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        return meta ? meta.kind : null;
+    };
+    const getRelatedTo = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        return meta?.relatedTo ?? null;
+    };
+    const getChecksum = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        return meta?.checksum ?? null;
     };
     return {
         datastore,
@@ -162,6 +243,9 @@ export function createLocalStorage(opts) {
         markReady,
         remove,
         getLocalPath,
+        getKind,
+        getRelatedTo,
+        getChecksum,
     };
 }
 //# sourceMappingURL=local.js.map

package/dist/storage/local.js.map

@@ -1 +1 @@
-{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/storage/local.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/storage/local.ts"],"names":[],"mappings":"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"}

package/dist/storage/s3.d.ts

@@ -0,0 +1,109 @@
+import type { S3ClientConfig } from '@aws-sdk/client-s3';
+import type { PulseVaultStorage, UploadKind } from './types.js';
+export type S3StorageOptions = {
+    /** Target bucket. Must already exist (the integrator provisions it). */
+    bucket: string;
+    /**
+     * Custom S3 endpoint. Set this for Cloudflare R2 or any S3-compatible store
+     * (e.g. `https://<account-id>.r2.cloudflarestorage.com`). Omit for AWS S3.
+     */
+    endpoint?: string;
+    /**
+     * AWS region. Required for AWS S3; for R2 use `"auto"`. When omitted and an
+     * `endpoint` is set this defaults to `"auto"`; otherwise the SDK resolves it
+     * from the environment.
+     */
+    region?: string;
+    /**
+     * Access key id. Optional — when both `accessKeyId` and `secretAccessKey`
+     * are omitted the AWS SDK default credential chain is used (env vars, IAM
+     * role, etc.). Never hard-code keys; read them from env in your app.
+     */
+    accessKeyId?: string;
+    /** Secret access key. See `accessKeyId`. */
+    secretAccessKey?: string;
+    /** Optional STS session token for temporary credentials. */
+    sessionToken?: string;
+    /**
+     * Use path-style addressing (`<endpoint>/<bucket>/<key>`) instead of
+     * virtual-host style. Defaults to `true` whenever a custom `endpoint` is set
+     * (R2 and most S3-compatible stores need it).
+     */
+    forcePathStyle?: boolean;
+    /** Presigned playback URL TTL in seconds. Defaults to 900 (15 minutes). */
+    presignTtlSeconds?: number;
+    /**
+     * Preferred multipart part size in bytes, forwarded to `@tus/s3-store`. Must
+     * be >= 5 MiB. When omitted, `@tus/s3-store` computes an optimal size.
+     */
+    partSize?: number;
+    /**
+     * Max number of entries kept in the in-memory metadata cache before the
+     * oldest (by insertion order) is evicted. A cache miss falls back to a
+     * bucket read, so eviction only costs an extra request, not correctness.
+     * Defaults to 10,000.
+     */
+    metaCacheLimit?: number;
+    /**
+     * Advanced escape hatch: extra `S3ClientConfig` fields merged into the
+     * client used for both playback presigning and the underlying TUS datastore
+     * (e.g. checksum flags for S3-compatible stores). Values here win over the
+     * fields derived from the options above.
+     */
+    clientConfig?: Partial<S3ClientConfig>;
+};
+/**
+ * S3 / Cloudflare R2 storage adapter. Uploads stream into the bucket via S3
+ * multipart upload (`@tus/s3-store`); playback is served by redirecting the
+ * client to a short-lived presigned GET URL, so bytes never flow back through
+ * the app server.
+ */
+export type S3Storage = PulseVaultStorage & {
+    /** The bucket this adapter writes to. */
+    readonly bucket: string;
+    /**
+     * Ranged GET of the first `n` bytes of a finalized upload, or `null` if the
+     * artifactId is unknown. Used by `createS3Mp4Sniffer` to validate the
+     * payload without downloading the whole object.
+     */
+    readHeader(artifactId: string, n: number): Promise<Buffer | null>;
+    /**
+     * Full GET of a finalized upload's bytes, or `null` if the artifactId is
+     * unknown. Used by `createS3ChecksumValidator` — unlike `readHeader`, this
+     * downloads the whole object, so it's only worth using for an explicit,
+     * opt-in integrity check, not on every upload by default.
+     */
+    readAll(artifactId: string): Promise<Buffer | null>;
+    /**
+     * Streams a finalized upload's bytes through a hash digest, returning the
+     * hex digest, or `null` if the artifactId is unknown. The streaming
+     * counterpart to `readAll` — used by `createS3ChecksumValidator` so
+     * checksum verification never has to hold an entire (potentially
+     * multi-gigabyte) object in memory as one `Buffer`.
+     */
+    digestAll(artifactId: string, algorithm: 'sha256' | 'sha1' | 'md5'): Promise<string | null>;
+    /** Artifact kind for a known artifactId, or `null`. Satisfies `getKind`. */
+    getKind(artifactId: string): Promise<UploadKind | null>;
+    /** Satisfies the optional `PulseVaultStorage.getRelatedTo` contract. */
+    getRelatedTo(artifactId: string): Promise<string | null>;
+    /** Satisfies the optional `PulseVaultStorage.getChecksum` contract. */
+    getChecksum(artifactId: string): Promise<string | null>;
+};
+/**
+ * Build an S3/R2-backed storage adapter.
+ *
+ * Async because it lazily imports the optional `@aws-sdk/*` and
+ * `@tus/s3-store` packages — `await` it before registering the plugin:
+ *
+ * ```ts
+ * const storage = await createS3Storage({
+ *   bucket: "pulse-videos",
+ *   endpoint: `https://${ACCOUNT}.r2.cloudflarestorage.com`,
+ *   accessKeyId: process.env.R2_ACCESS_KEY,
+ *   secretAccessKey: process.env.R2_SECRET_KEY,
+ * });
+ * await app.register(pulseVault, { storage, prefix: "/pulsevault", maxUploadSize: Infinity });
+ * ```
+ */
+export declare function createS3Storage(opts: S3StorageOptions): Promise<S3Storage>;
+//# sourceMappingURL=s3.d.ts.map

package/dist/storage/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/storage/s3.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAY,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAEV,iBAAiB,EAEjB,UAAU,EACX,MAAM,YAAY,CAAC;AAwEpB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,iBAAiB,GAAG;IAC1C,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpD;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5F,4EAA4E;IAC5E,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACxD,wEAAwE;IACxE,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzD,uEAAuE;IACvE,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACzD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAqVhF"}