cursedbelt-server 1.0.0

package/dist/server/storage/files/adapter.js

@@ -0,0 +1,203 @@
+import { isBrowserRenderableImage } from '../imageThumbnail';
+/** Build the image→GalleryPhoto mapper shared by the photo source and the mixed media source.
+ * The primary image is served by the file byte route (fileUrls); the grid thumbnail + HEIC
+ * display derivative by the type-agnostic poster route (mediaUrls) when ingest produced one. */
+function createFileToPhoto(cfg) {
+    return async (ctx, file) => {
+        if (file.fileType !== 'image')
+            return null;
+        const { url } = await cfg.fileUrls.build(ctx, file.id, file.mime);
+        const media = file.hasThumbnail ? await cfg.mediaUrls.build(ctx, cfg.id, file.id) : null;
+        const thumbnailUrl = media?.posterUrl;
+        const displayUrl = media && !isBrowserRenderableImage(file.mime) ? media.displayUrl : undefined;
+        return {
+            id: file.id,
+            type: 'image',
+            url,
+            thumbnailUrl,
+            displayUrl,
+            name: file.name,
+            sizeBytes: file.size,
+            mimeType: file.mime,
+            tags: file.tags,
+            createdAt: file.createdAt,
+            favorite: file.favorite,
+        };
+    };
+}
+// ── FileCatalogue → media seam ────────────────────────────────────────────────────
+// The catalogue is the ONE source of truth for a user's binaries. The video gallery is not a
+// separate store — it is a video-filtered VIEW over the catalogue. These two adapters are the
+// seam: `createFileToPlayable` turns a video FileRecord into the player's PlayableVideo (URLs
+// baked server-side via the shared token/serve infra), and `createCatalogueVideoSource` exposes
+// the catalogue as a `MediaSource` so the existing `mountMediaRoutes` + gallery serve it
+// unchanged. Because the serve routes address bytes by (owner, videoId) through the shared
+// keyspace, a catalogue video is served by the same routes regardless of `sourceId`.
+/** Resolve a video FileRecord to a PlayableVideo with tokenised URLs. Non-video ⇒ null. */
+export function createFileToPlayable(urls, sourceId) {
+    return async (ctx, file) => {
+        if (file.fileType !== 'video')
+            return null;
+        const u = await urls.build(ctx, sourceId, file.id);
+        return {
+            id: file.id,
+            name: file.name,
+            streamUrl: u.streamUrl,
+            hlsUrl: file.hasHls ? u.hlsUrl : undefined,
+            posterUrl: file.hasThumbnail ? u.posterUrl : undefined,
+            vttUrl: file.hasSprites ? u.vttUrl : undefined,
+            spriteUrl: file.hasSprites ? u.spriteUrl : undefined,
+            durationSeconds: file.durationSeconds,
+            tags: file.tags,
+            processingStatus: file.processingStatus,
+            processingProgress: file.processingProgress,
+        };
+    };
+}
+/** Expose a FileCatalogue as a video-only `MediaSource` — the gallery is a view, not a store. */
+export function createCatalogueVideoSource(cfg) {
+    const toPlayable = createFileToPlayable(cfg.urls, cfg.id);
+    return {
+        id: cfg.id,
+        title: cfg.title,
+        async list(ctx, opts) {
+            const page = await cfg.catalogue.list(ctx, {
+                type: 'video',
+                tag: opts.tag,
+                query: opts.query,
+                cursor: opts.cursor,
+                limit: opts.limit,
+                sort: opts.sort,
+            });
+            const items = await Promise.all(page.items.map((f) => toPlayable(ctx, f)));
+            return { items: items.filter((v) => v !== null), nextCursor: page.nextCursor };
+        },
+        async resolve(ctx, videoId) {
+            const file = await cfg.catalogue.get(ctx, videoId);
+            return file ? toPlayable(ctx, file) : null;
+        },
+        async tags(ctx) {
+            return (await cfg.catalogue.tagFacets(ctx)).map((f) => f.tag);
+        },
+        async ingest(ctx, upload) {
+            const file = await cfg.catalogue.ingest(ctx, upload);
+            const playable = await toPlayable(ctx, file);
+            if (!playable)
+                throw new Error('gallery ingest expects a video file');
+            return playable;
+        },
+        async remove(ctx, videoId) {
+            await cfg.catalogue.trash(ctx, videoId);
+        },
+        async recordView(ctx, videoId) {
+            await cfg.catalogue.recordView(ctx, videoId);
+        },
+    };
+}
+// ── Photo view ────────────────────────────────────────────────────────────────────
+// The photo gallery is the image-filtered sibling of the video view: same catalogue, same
+// token/serve infra. The primary image is served by the file byte route (fileUrls) and the grid
+// thumbnail by the type-agnostic poster route (mediaUrls) when the ingest thumbnailer produced
+// one — so a PhotoSource needs BOTH URL builders.
+/** Expose a FileCatalogue as an image-only `PhotoSource` — a view, not a store. */
+export function createCataloguePhotoSource(cfg) {
+    const toPhoto = createFileToPhoto(cfg);
+    return {
+        id: cfg.id,
+        title: cfg.title,
+        async list(ctx, opts) {
+            const page = await cfg.catalogue.list(ctx, {
+                type: 'image',
+                tag: opts.tag,
+                query: opts.query,
+                cursor: opts.cursor,
+                limit: opts.limit,
+                sort: opts.sort,
+            });
+            const items = await Promise.all(page.items.map((f) => toPhoto(ctx, f)));
+            return { items: items.filter((p) => p !== null), nextCursor: page.nextCursor };
+        },
+        async resolve(ctx, photoId) {
+            const file = await cfg.catalogue.get(ctx, photoId);
+            return file ? toPhoto(ctx, file) : null;
+        },
+        async tags(ctx) {
+            return (await cfg.catalogue.tagFacets(ctx)).map((f) => f.tag);
+        },
+        async ingest(ctx, upload) {
+            if (!upload.mime.startsWith('image/')) {
+                throw new Error('photo ingest expects an image file');
+            }
+            const file = await cfg.catalogue.ingest(ctx, upload);
+            const photo = await toPhoto(ctx, file);
+            if (!photo)
+                throw new Error('photo ingest expects an image file');
+            return photo;
+        },
+        async remove(ctx, photoId) {
+            await cfg.catalogue.trash(ctx, photoId);
+        },
+        async recordView(ctx, photoId) {
+            await cfg.catalogue.recordView(ctx, photoId);
+        },
+    };
+}
+// ── Mixed media view ───────────────────────────────────────────────────────────────
+// A combined gallery lists BOTH photos and videos from the one catalogue. This adapter
+// reuses the same two mappers (`createFileToPlayable`, `createFileToPhoto`) so a mixed
+// item renders identically to its single-type sibling — it just tags each with
+// `mediaKind` for the UI to pick a tile/stage. It needs BOTH URL builders (video streams
+// + image bytes/poster). A `kind` filter maps to the catalogue's `type`; `all` lists
+// untyped and keeps only image|video (dropping docs/audio the mixed gallery can't show).
+/** Expose a FileCatalogue as a `MediaGallerySource` — photos + videos in one feed.
+ * Videos are tokenised under `videoSourceId` (must match the registered video source so
+ * `mountMediaRoutes` serves their streams); photo posters/thumbnails under this source's `id`. */
+export function createCatalogueMediaSource(cfg) {
+    const toPlayable = createFileToPlayable(cfg.urls, cfg.videoSourceId ?? cfg.id);
+    const toPhoto = createFileToPhoto({ id: cfg.id, fileUrls: cfg.fileUrls, mediaUrls: cfg.urls });
+    const toMedia = async (ctx, file) => {
+        if (file.fileType === 'video') {
+            const v = await toPlayable(ctx, file);
+            return v ? { ...v, mediaKind: 'video' } : null;
+        }
+        if (file.fileType === 'image') {
+            const p = await toPhoto(ctx, file);
+            return p ? { ...p, mediaKind: 'photo' } : null;
+        }
+        return null;
+    };
+    return {
+        id: cfg.id,
+        title: cfg.title,
+        async list(ctx, opts) {
+            // `all` ⇒ no catalogue type filter, then drop non-image/video below.
+            const type = opts.kind === 'image' ? 'image' : opts.kind === 'video' ? 'video' : undefined;
+            const page = await cfg.catalogue.list(ctx, {
+                type,
+                tag: opts.tag,
+                query: opts.query,
+                cursor: opts.cursor,
+                limit: opts.limit,
+                sort: opts.sort,
+            });
+            const items = await Promise.all(page.items.map((f) => toMedia(ctx, f)));
+            return {
+                items: items.filter((m) => m !== null),
+                nextCursor: page.nextCursor,
+            };
+        },
+        async resolve(ctx, itemId) {
+            const file = await cfg.catalogue.get(ctx, itemId);
+            return file ? toMedia(ctx, file) : null;
+        },
+        async tags(ctx) {
+            return (await cfg.catalogue.tagFacets(ctx)).map((f) => f.tag);
+        },
+        async remove(ctx, itemId) {
+            await cfg.catalogue.trash(ctx, itemId);
+        },
+        async recordView(ctx, itemId) {
+            await cfg.catalogue.recordView(ctx, itemId);
+        },
+    };
+}

package/dist/server/storage/files/catalogue.d.ts

@@ -0,0 +1,72 @@
+import type { Database } from 'bun:sqlite';
+import { type MediaCtx, type MediaStore } from '../types';
+import { type ProcessOptions, type ProcessResult } from '../videoProcessor';
+import { type FileCatalogue, type PrivateFileCatalogue } from './types';
+/** Swappable video ingest→derivatives implementation. The default runs ffmpeg
+ * locally ({@link processVideo}); a remote backend (binary-server) delegates
+ * the heavy work to the storage host instead — see binaryServerProcessing. */
+export type VideoProcessor = (opts: ProcessOptions) => Promise<ProcessResult>;
+/** Everything an image-derivative implementation needs to produce the grid
+ * thumbnail (posterKey, 512px JPEG) and — for formats browsers can't render —
+ * the full-size display JPEG (displayKey). */
+export type ImageDerivativesOptions = {
+    store: MediaStore;
+    workDir: string;
+    owner: string;
+    id: string;
+    mime: string;
+    /** Storage key of the uploaded original. */
+    binaryKey: string;
+    /** Where the 512px grid thumbnail JPEG goes. */
+    posterKey: string;
+    /** Where the full-size browser-safe JPEG goes (only when `needsDisplay`). */
+    displayKey: string;
+    /** True when the original's format isn't browser-renderable (HEIC/HEIF). */
+    needsDisplay: boolean;
+};
+/** Swappable image thumbnail/display derivative implementation (local sharp/
+ * ffmpeg by default; remote binary-server job when the bytes live there). */
+export type ImageDerivatives = (opts: ImageDerivativesOptions) => Promise<{
+    hasThumbnail: boolean;
+}>;
+export declare const fileBinaryKey: (owner: string, id: string) => string;
+/** Where a file's uploaded bytes must land for `registerUploaded` to find them: a video's raw
+ * source (fed to the transcode), else the primary binary. The chunked-upload path targets this key
+ * so an out-of-band upload lands exactly where the catalogue + serve routes expect it. */
+export declare const catalogueUploadKey: (owner: string, id: string, mime: string) => string;
+export type SqliteFileCatalogueOptions = {
+    db: Database;
+    store: MediaStore;
+    /** ffmpeg scratch dir for video processing. */
+    workDir: string;
+    /** HLS ladder heights for video ingest. */
+    ladderHeights?: number[];
+    /** Max transcode kicks per file (initial + recoverProcessing re-kicks) before the row is marked
+     * failed instead of re-kicked. Guards against a boot loop where the transcode itself kills the
+     * process (e.g. ffmpeg OOM on a small host) and every restart re-kicks the same job. Default 3. */
+    maxProcessingAttempts?: number;
+    /** Transcode uploaded videos into derivatives (faststart MP4 + HLS + poster + sprites).
+     * `false` skips ffmpeg entirely and marks videos ready to play raw (progressive Range) — the
+     * same graceful path as ffmpeg-unavailable. `'poster'` is the memory-constrained middle ground:
+     * skip the heavy HLS/re-encode ladder but still extract a cheap single-frame poster (grid gets
+     * thumbnails; raw source plays). Set `false`/`'poster'` on hosts where a full transcode can OOM
+     * the process. Default true. */
+    transcodeVideos?: boolean | 'poster';
+    /** Owner keyspace segment. Defaults to tenantId (a tenant-shared library). */
+    owner?: (ctx: MediaCtx) => string;
+    /** Injectable clock (tests). */
+    now?: () => number;
+    /** Per-row shuffle key generator for the `random` sort (a non-negative 31-bit int). Injectable
+     * for deterministic tests; defaults to a random 31-bit value per inserted file. */
+    randKey?: () => number;
+    /** Session shuffle-seed minter for the `random` sort's first page (a non-negative 31-bit int).
+     * Injectable for deterministic tests; defaults to a random 31-bit value. */
+    randomSeed?: () => number;
+    /** Video ingest→derivatives implementation (default: local ffmpeg via
+     * {@link processVideo}). Inject a remote one when the byte store is remote. */
+    videoProcessor?: VideoProcessor;
+    /** Image thumbnail/display derivative implementation (default: local sharp
+     * with ffmpeg fallback). Inject a remote one when the byte store is remote. */
+    imageDerivatives?: ImageDerivatives;
+};
+export declare function createSqliteFileCatalogue(opts: SqliteFileCatalogueOptions): FileCatalogue & PrivateFileCatalogue;