cursedbelt-server 1.0.0

package/src/server/storage/s3ObjectStore.ts

@@ -0,0 +1,239 @@
+/**
+ * `createS3ObjectStore` — the SAAS profile's binary tier (08 §1b, 01 §2.5).
+ *
+ * The companion to `createFsObjectStore` (cwip): same `ObjectStore` contract,
+ * different issuer. Everything above this line — `AssetService`, the asset
+ * mixin, the client — is written against the interface, so switching profiles
+ * swaps this factory in and changes nothing else. That is the whole reason the
+ * local store bothers to sign its URLs.
+ *
+ * Built on `Bun.S3Client`, which ships in the runtime cursedbelt already
+ * requires — no `aws-sdk`, no transitive credential-chain surprises. Works
+ * against S3, R2, MinIO or any other S3-compatible endpoint.
+ *
+ * Three things this does that a naive `PutObject` wrapper does not:
+ *
+ *   * **Streams through a multipart writer.** A 4GB upload is fed part-by-part
+ *     (default 8MiB) straight from the request stream. Nothing buffers the
+ *     object, so request memory is O(part), not O(file).
+ *   * **Aborts the multipart on failure.** `NetworkSink.end(error)` tells Bun to
+ *     abort rather than complete the upload; an abandoned multipart otherwise
+ *     accrues storage cost that never appears in a bucket listing — an invisible
+ *     bill, which is the worst kind.
+ *   * **Presigns for real.** `signedUrl` returns a genuine presigned GET so the
+ *     bytes leave via the CDN/edge, not through the app process. The asset
+ *     mixin's bytes routes stay as the fallback for private/derived content.
+ *
+ * Credentials are OPTIONS, never `process.env`: the host resolves them from
+ * GuardEngine secrets or its deploy environment (01 §3.3) and injects them, so
+ * this module has no ambient authority and a test can hand it a fake client.
+ */
+import { assertObjectKey } from 'cwip/storage';
+import type { ObjectStat, ObjectStore } from 'cwip/storage';
+import { AppError } from '../errors';
+
+/**
+ * The slice of `Bun.S3File` this store uses.
+ *
+ * Declared structurally rather than imported as `Bun.S3File` so the contract
+ * suite can drive BOTH implementations against an in-process fake bucket. A
+ * store whose only proof is "it compiles against the real SDK types" is a store
+ * whose behavior has never been tested.
+ */
+export interface S3ObjectHandle {
+  stream(): ReadableStream<Uint8Array>;
+  writer(options?: { partSize?: number; queueSize?: number; retry?: number }): S3ObjectWriter;
+  exists(): Promise<boolean>;
+  stat(): Promise<{ size: number; type?: string; lastModified?: Date; etag?: string }>;
+  delete(): Promise<void>;
+  presign(options?: { expiresIn?: number; method?: 'GET' }): string;
+}
+
+export interface S3ObjectWriter {
+  write(chunk: Uint8Array): number | Promise<number>;
+  /** Passing an error aborts the multipart upload instead of completing it. */
+  end(error?: Error): number | Promise<number>;
+}
+
+export interface S3ClientLike {
+  file(key: string, options?: { type?: string }): S3ObjectHandle;
+}
+
+export interface S3ObjectStoreOptions {
+  /** Pre-built client. Supply this OR the credential fields below. */
+  client?: S3ClientLike;
+  bucket?: string;
+  /** e.g. `https://<account>.r2.cloudflarestorage.com`. */
+  endpoint?: string;
+  region?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+  /**
+   * Namespace every key under this prefix, so ONE bucket can host many apps
+   * without collisions. Tenant scoping stays in the key shape (`<tenant>/<file>`)
+   * — the prefix is deployment topology, not a security boundary.
+   */
+  keyPrefix?: string;
+  /** Multipart part size. Default 8MiB. */
+  partSize?: number;
+  /** Default presigned-URL lifetime in seconds. */
+  defaultExpiresInSeconds?: number;
+  /** Ceiling on a caller-requested lifetime. */
+  maxExpiresInSeconds?: number;
+}
+
+const DEFAULT_PART_SIZE = 8 * 1024 * 1024;
+const DEFAULT_EXPIRES_IN_SECONDS = 300;
+const MAX_EXPIRES_IN_SECONDS = 86_400;
+
+/** `Bun.S3Client` typed down to the slice we use; Bun ships it natively. */
+type BunWithS3 = { S3Client: new (options: Record<string, unknown>) => S3ClientLike };
+
+const buildClient = (options: S3ObjectStoreOptions): S3ClientLike => {
+  if (options.client) return options.client;
+  if (!options.bucket)
+    throw new AppError('createS3ObjectStore needs either a `client` or a `bucket` (plus credentials).', {
+      code: 'OBJECT_STORE_MISCONFIGURED',
+      status: 500,
+      category: 'storage',
+      isOperational: false,
+    });
+  const S3Client = (Bun as unknown as BunWithS3).S3Client;
+  if (typeof S3Client !== 'function')
+    throw new AppError('This Bun runtime has no S3Client; pass a `client` implementing the S3 subset instead.', {
+      code: 'OBJECT_STORE_MISCONFIGURED',
+      status: 500,
+      category: 'storage',
+      isOperational: false,
+    });
+  return new S3Client({
+    bucket: options.bucket,
+    endpoint: options.endpoint,
+    region: options.region,
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    sessionToken: options.sessionToken,
+  });
+};
+
+export function createS3ObjectStore(options: S3ObjectStoreOptions): ObjectStore {
+  const client = buildClient(options);
+  const partSize = options.partSize ?? DEFAULT_PART_SIZE;
+  const defaultExpiry = options.defaultExpiresInSeconds ?? DEFAULT_EXPIRES_IN_SECONDS;
+  const maxExpiry = options.maxExpiresInSeconds ?? MAX_EXPIRES_IN_SECONDS;
+  const prefix = options.keyPrefix ? `${options.keyPrefix.replace(/^\/+|\/+$/g, '')}/` : '';
+
+  /**
+   * The SAME key whitelist the fs store enforces.
+   *
+   * S3 has no directories, so traversal is not the risk here — divergence is. A
+   * key that one profile accepts and the other refuses turns a profile switch
+   * into a data-loss migration, so both stores validate identically and the
+   * contract suite asserts it.
+   */
+  const physical = (key: string): string => {
+    assertObjectKey(key);
+    return `${prefix}${key}`;
+  };
+
+  const statOf = async (key: string): Promise<ObjectStat | null> => {
+    const handle = client.file(physical(key));
+    try {
+      const info = await handle.stat();
+      return {
+        key,
+        size: info.size,
+        contentType: info.type,
+        modifiedAt: (info.lastModified ?? new Date()).toISOString(),
+      };
+    } catch (error) {
+      if (isNotFound(error)) return null;
+      throw error;
+    }
+  };
+
+  return {
+    async put(key, body, putOptions): Promise<ObjectStat> {
+      const contentType = putOptions?.contentType;
+      const handle = client.file(physical(key), contentType ? { type: contentType } : undefined);
+      const writer = handle.writer({ partSize });
+      const reader = body.getReader();
+      let size = 0;
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          if (value.byteLength === 0) continue;
+          await writer.write(value);
+          size += value.byteLength;
+        }
+        await writer.end();
+      } catch (error) {
+        // Abort, don't complete. Best-effort: if the abort itself fails there is
+        // nothing further this process can do, and swallowing it would mask the
+        // ORIGINAL upload failure, which is the one worth reporting.
+        await Promise.resolve(writer.end(error instanceof Error ? error : new Error(String(error)))).catch(() => {});
+        throw error;
+      } finally {
+        reader.releaseLock();
+      }
+      return { key, size, contentType, modifiedAt: new Date().toISOString() };
+    },
+
+    async get(key): Promise<ReadableStream<Uint8Array> | null> {
+      const handle = client.file(physical(key));
+      if (!(await handle.exists())) return null;
+      try {
+        return handle.stream();
+      } catch (error) {
+        // Raced with a delete between `exists` and `stream` — a missing object
+        // is `null`, not a 500.
+        if (isNotFound(error)) return null;
+        throw error;
+      }
+    },
+
+    stat: statOf,
+
+    async delete(key): Promise<boolean> {
+      const existed = (await statOf(key)) !== null;
+      try {
+        await client.file(physical(key)).delete();
+      } catch (error) {
+        if (!isNotFound(error)) throw error;
+      }
+      return existed;
+    },
+
+    async signedUrl(key, urlOptions): Promise<string> {
+      const requested = urlOptions?.expiresInSeconds ?? defaultExpiry;
+      if (!Number.isFinite(requested) || requested <= 0)
+        throw new AppError(`Signed-url lifetime for '${key}' must be a positive number of seconds.`, {
+          code: 'OBJECT_KEY_INVALID',
+          status: 400,
+          category: 'storage',
+          context: { key, requested },
+        });
+      return client
+        .file(physical(key))
+        .presign({ expiresIn: Math.min(Math.floor(requested), maxExpiry), method: 'GET' });
+    },
+  };
+}
+
+/**
+ * Is this the store telling us the object is not there?
+ *
+ * S3-compatible endpoints disagree on the shape (`NoSuchKey`, `NotFound`, a
+ * bare 404), and Bun surfaces its own `code`. Matching all of them keeps a
+ * missing object a `null` on every backend rather than a 500 on MinIO and a
+ * `null` on R2.
+ */
+const isNotFound = (error: unknown): boolean => {
+  if (!error || typeof error !== 'object') return false;
+  const candidate = error as { code?: unknown; name?: unknown; status?: unknown; statusCode?: unknown };
+  const code = String(candidate.code ?? candidate.name ?? '');
+  if (/NoSuchKey|NotFound|ENOENT|ERR_S3_FILE_NOT_FOUND/i.test(code)) return true;
+  return candidate.status === 404 || candidate.statusCode === 404;
+};

package/src/server/storage/sources.ts

@@ -0,0 +1,245 @@
+import type { PlayableVideo, ProcessingStatus } from 'cursedbelt-core/media';
+import type { StreamTokenService } from './streamToken';
+import {
+  fsMp4Key,
+  fsPosterKey,
+  fsSourceKey,
+  fsSpriteKey,
+  fsVttKey,
+  type MediaCtx,
+  type MediaSource,
+  type MediaStore,
+} from './types';
+import { processVideo } from './videoProcessor';
+
+// ── Media URL builder ───────────────────────────────────────────────────────────
+// Builds the path-embedded-token URLs the serve routes expect. One token per video authorizes
+// all its derivative URLs; carried as a leading `/s/<token>/` path segment so hls.js's relative
+// segment/playlist fetches inherit it (see streamToken.ts).
+//
+// SPLIT-ORIGIN: these URLs are built SERVER-SIDE and baked into the PlayableVideo the client
+// receives — the browser never derives a media URL from `window.location`. So `baseUrl` may be
+// ABSOLUTE (e.g. 'https://api.example.com/_media') to point media at an API subdomain / EC2 /
+// binary-server edge that differs from where the SPA is served (Cloudflare Pages). It is
+// intentionally SEPARATE from `mountMediaRoutes`' `basePath` (the on-server route mount, always
+// path-only): the two only need to share the same trailing path (e.g. '/_media'). For a
+// same-origin app, pass the plain path ('/_media'). When absolute (cross-origin), the media
+// routes must send CORS headers — pass `cors` to `mountMediaRoutes`.
+export interface MediaUrls {
+  build(
+    ctx: MediaCtx,
+    sourceId: string,
+    videoId: string,
+  ): Promise<{
+    streamUrl: string;
+    hlsUrl: string;
+    posterUrl: string;
+    displayUrl: string;
+    vttUrl: string;
+    spriteUrl: string;
+  }>;
+}
+
+export function createMediaUrls(opts: {
+  /** Public base for browser media URLs. Path-only ('/_media') for same-origin, or an absolute
+   * origin+path ('https://api.example.com/_media') for a split-origin deploy. Must share its
+   * trailing path with `mountMediaRoutes`' `basePath`. */
+  baseUrl: string;
+  token: StreamTokenService;
+  /** Owner keyspace segment for a request. Defaults to tenantId (a tenant-shared gallery). */
+  owner?: (ctx: MediaCtx) => string;
+}): MediaUrls {
+  const ownerOf = opts.owner ?? ((c: MediaCtx) => c.tenantId);
+  // Trim a trailing slash so 'https://api…/_media/' and '/_media' behave identically.
+  const base = opts.baseUrl.replace(/\/$/, '');
+  return {
+    async build(ctx, sourceId, videoId) {
+      const token = await opts.token.sign({ owner: ownerOf(ctx), sourceId, videoId });
+      const p = `${base}/s/${token}`;
+      return {
+        streamUrl: `${p}/media/${sourceId}/${videoId}`,
+        hlsUrl: `${p}/hls/${sourceId}/${videoId}/master.m3u8`,
+        posterUrl: `${p}/poster/${sourceId}/${videoId}`,
+        displayUrl: `${p}/display/${sourceId}/${videoId}`,
+        vttUrl: `${p}/sprite/${sourceId}/${videoId}/sprites.vtt`,
+        spriteUrl: `${p}/sprite/${sourceId}/${videoId}/sprites.jpg`,
+      };
+    },
+  };
+}
+
+// ── Source registry ───────────────────────────────────────────────────────────────
+export class SourceRegistry {
+  private sources = new Map<string, MediaSource>();
+  register(source: MediaSource): this {
+    this.sources.set(source.id, source);
+    return this;
+  }
+  get(id: string): MediaSource | undefined {
+    return this.sources.get(id);
+  }
+  list(): MediaSource[] {
+    return [...this.sources.values()];
+  }
+}
+
+// ── Disk-backed source ──────────────────────────────────────────────────────────
+// A MediaSource over a MediaStore: ingests uploads, runs the pipeline in the background, and
+// resolves videos to tokenised PlayableVideos. Metadata is held in memory keyed by tenant (an
+// app that needs persistence swaps this for a DB-backed MediaSource — cursedbelt-server/sqlite
+// — without touching consumers).
+type VideoMeta = {
+  id: string;
+  name: string;
+  tags: string[];
+  mime: string;
+  durationSeconds?: number;
+  status: ProcessingStatus;
+  progress: number;
+  hasHls: boolean;
+  hasSprite: boolean;
+  hasPoster: boolean;
+  createdAt: number;
+};
+
+export type DiskSource = MediaSource & {
+  /** Read current processing status (for the gallery's status poll / tests). */
+  status(ctx: MediaCtx, videoId: string): { status: ProcessingStatus; progress: number } | null;
+};
+
+export function createDiskSource(cfg: {
+  id: string;
+  title: string;
+  store: MediaStore;
+  /** ffmpeg scratch dir. */
+  workDir: string;
+  urls: MediaUrls;
+  /** Owner keyspace segment; defaults to tenantId. */
+  owner?: (ctx: MediaCtx) => string;
+  /** Injectable clock (tests). */
+  now?: () => number;
+}): DiskSource {
+  const ownerOf = cfg.owner ?? ((c: MediaCtx) => c.tenantId);
+  const now = cfg.now ?? (() => Date.now());
+  const byTenant = new Map<string, Map<string, VideoMeta>>();
+  const bucket = (ctx: MediaCtx) => {
+    let m = byTenant.get(ctx.tenantId);
+    if (!m) {
+      m = new Map();
+      byTenant.set(ctx.tenantId, m);
+    }
+    return m;
+  };
+
+  const toPlayable = async (ctx: MediaCtx, meta: VideoMeta): Promise<PlayableVideo> => {
+    const u = await cfg.urls.build(ctx, cfg.id, meta.id);
+    return {
+      id: meta.id,
+      name: meta.name,
+      streamUrl: u.streamUrl,
+      hlsUrl: meta.hasHls ? u.hlsUrl : undefined,
+      posterUrl: meta.hasPoster ? u.posterUrl : undefined,
+      vttUrl: meta.hasSprite ? u.vttUrl : undefined,
+      spriteUrl: meta.hasSprite ? u.spriteUrl : undefined,
+      durationSeconds: meta.durationSeconds,
+      tags: meta.tags,
+      processingStatus: meta.status,
+      processingProgress: meta.progress,
+    };
+  };
+
+  return {
+    id: cfg.id,
+    title: cfg.title,
+
+    async list(ctx, opts) {
+      const all = [...bucket(ctx).values()].sort((a, b) => b.createdAt - a.createdAt);
+      const q = opts.query?.trim().toLowerCase();
+      const filtered = all.filter(
+        (m) =>
+          (!opts.tag || m.tags.includes(opts.tag)) &&
+          (!q || m.name.toLowerCase().includes(q) || m.tags.some((t) => t.includes(q))),
+      );
+      const limit = opts.limit ?? 24;
+      const start = opts.cursor ? Number(opts.cursor) || 0 : 0;
+      const page = filtered.slice(start, start + limit);
+      const items = await Promise.all(page.map((m) => toPlayable(ctx, m)));
+      const next = start + limit;
+      return { items, nextCursor: next < filtered.length ? String(next) : undefined };
+    },
+
+    async resolve(ctx, videoId) {
+      const meta = bucket(ctx).get(videoId);
+      return meta ? toPlayable(ctx, meta) : null;
+    },
+
+    async tags(ctx) {
+      const set = new Set<string>();
+      for (const m of bucket(ctx).values()) {
+        for (const t of m.tags) set.add(t);
+      }
+      return [...set].sort();
+    },
+
+    async ingest(ctx, upload) {
+      const owner = ownerOf(ctx);
+      const id = crypto.randomUUID();
+      await cfg.store.putStream(fsSourceKey(owner, id), upload.body, upload.mime, {
+        contentLength: upload.size,
+      });
+      const meta: VideoMeta = {
+        id,
+        name: upload.name,
+        tags: [],
+        mime: upload.mime,
+        status: 'processing',
+        progress: 0,
+        hasHls: false,
+        hasSprite: false,
+        hasPoster: false,
+        createdAt: now(),
+      };
+      bucket(ctx).set(id, meta);
+
+      // Fire-and-forget the pipeline; the client polls status via the source's status()/list().
+      void processVideo({
+        store: cfg.store,
+        workDir: cfg.workDir,
+        owner,
+        id,
+        sourceKey: fsSourceKey(owner, id),
+        onProgress: (status, pct) => {
+          meta.status = status;
+          meta.progress = pct;
+        },
+      }).then((res) => {
+        meta.status = res.status;
+        meta.progress = res.status === 'ready' ? 100 : meta.progress;
+        meta.durationSeconds = res.durationSeconds || meta.durationSeconds;
+        meta.hasHls = res.hasHls;
+        meta.hasSprite = res.hasSprite;
+        meta.hasPoster = res.hasPoster;
+      });
+
+      return toPlayable(ctx, meta);
+    },
+
+    async remove(ctx, videoId) {
+      const owner = ownerOf(ctx);
+      await Promise.all([
+        cfg.store.remove(fsSourceKey(owner, videoId)),
+        cfg.store.remove(fsMp4Key(owner, videoId)),
+        cfg.store.remove(fsPosterKey(owner, videoId)),
+        cfg.store.remove(fsSpriteKey(owner, videoId)),
+        cfg.store.remove(fsVttKey(owner, videoId)),
+        cfg.store.removePrefix(`hls/${owner}/${videoId}`),
+      ]);
+      bucket(ctx).delete(videoId);
+    },
+
+    status(ctx, videoId) {
+      const meta = bucket(ctx).get(videoId);
+      return meta ? { status: meta.status, progress: meta.progress } : null;
+    },
+  };
+}