@proteinjs/db-file 1.8.3 → 1.9.0

package/src/FileVariantMaker.ts

@@ -0,0 +1,84 @@
+import { Loadable, SourceRepository } from '@proteinjs/reflection';
+import { File } from './tables/FileTable';
+
+/**
+ * The kinds of derived File a file can carry — each a seat on the row (`File.preview`,
+ * `File.stage`) with one lifecycle: made once, named on the row, dropped when the original's
+ * bytes change, deleted with the original, readable by whoever can read the original.
+ */
+export type FileVariantKind = 'preview' | 'stage';
+
+export const FILE_VARIANT_KINDS: readonly FileVariantKind[] = ['preview', 'stage'];
+
+/** What the maker hands back for a variant: the bytes, their type, and the facts a consumer renders from without loading them. */
+export interface FileVariant {
+  bytes: Buffer;
+  type: string;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * How a derived File of a File is made — ONE owner for "a variant of this file's bytes".
+ *
+ * The library owns the seat on the row, the lifecycle and the access rule for every variant
+ * (`FileStorage.deriveVariants` at ingest, `FileStorage.getVariant` on the read path); the one
+ * package that knows the file's format registers how the variant's bytes are made — a picture's
+ * 512 px thumbnail (`preview`) and its 1600 px rendition for the stage (`stage`) are two answers
+ * of the same maker, never two mechanisms. Dependency direction is the
+ * {@link FileReachabilityResolver} / {@link FileCopyForOthers} pattern: the interface here, the
+ * implementation above, discovered through the SourceRepository. With no maker registered no
+ * variant is ever made and every consumer draws the original.
+ */
+export interface FileVariantMaker extends Loadable {
+  /**
+   * Whether a variant of this kind is made of this file at all — decided from the row alone,
+   * never from its bytes (a document, a clip, a picture already small enough cost no read). True
+   * means {@link make} is called once with the original's bytes and its answer is stored.
+   */
+  appliesTo(file: File, kind: FileVariantKind): boolean;
+  /** The variant, made from the original's bytes. Throws when it cannot be made — nothing is stored, the consumer draws the original. */
+  make(file: File, bytes: Buffer, kind: FileVariantKind): Promise<FileVariant>;
+}
+
+export const getFileVariantMaker = (): FileVariantMaker | undefined =>
+  SourceRepository.get().object<FileVariantMaker>('@proteinjs/db-file/FileVariantMaker');
+
+/**
+ * What a derivation becomes when the registered maker could not make the variant of these
+ * bytes: nothing is stored. Thrown by `FileStorage` in place of whatever the maker threw (the
+ * maker's own one-line reason kept as `reason`), so the ingest door can report it to the caller
+ * holding the bytes and the read path can tell it from a failure of the store or the database
+ * (and serve the file itself). Read by shape ({@link FileVariantNotMade.is}), like
+ * `FileCopyRefused`, so it holds across duplicate copies of this package.
+ */
+export class FileVariantNotMade extends Error {
+  private static readonly NAME = 'FileVariantNotMade';
+  /** Free text that reaches a message is one line and bounded. */
+  private static readonly MAX_REASON_CHARS = 300;
+  readonly fileId: string;
+  readonly kind: FileVariantKind;
+  readonly reason: string;
+
+  constructor(fileId: string, kind: FileVariantKind, cause: unknown) {
+    const reason = FileVariantNotMade.plain(cause);
+    super(`No ${kind} variant could be made of file ${fileId}${reason ? `: ${reason}` : ''}`);
+    this.name = FileVariantNotMade.NAME;
+    Object.setPrototypeOf(this, FileVariantNotMade.prototype);
+    this.fileId = fileId;
+    this.kind = kind;
+    this.reason = reason;
+  }
+
+  static is(error: unknown): error is FileVariantNotMade {
+    return (error as { name?: unknown } | null | undefined)?.name === FileVariantNotMade.NAME;
+  }
+
+  private static plain(cause: unknown): string {
+    const message = cause instanceof Error ? cause.message : typeof cause === 'string' ? cause : '';
+    const line = message.replace(/\s+/g, ' ').trim();
+    return line.length > FileVariantNotMade.MAX_REASON_CHARS
+      ? `${line.slice(0, FileVariantNotMade.MAX_REASON_CHARS)}…`
+      : line;
+  }
+}

package/src/routes/FileResponder.ts

@@ -0,0 +1,85 @@
+import { File } from '../tables/FileTable';
+import { FileStorage } from '../FileStorage';
+import { FileStorageError } from '../FileStorageError';
+import { ServiceRefusal } from '@proteinjs/service';
+import { resolveByteRange } from './byteRange';
+
+/** The express members the file routes touch — typed narrowly so the routes and their tests agree. */
+export type FileRequest = { params: Record<string, string>; headers?: { range?: string } };
+export type FileResponse = {
+  status(code: number): { send(body: unknown): unknown };
+  send(body: unknown): unknown;
+  setHeader(name: string, value: string): void;
+  redirect(status: number, url: string): void;
+};
+
+/**
+ * THE ONE SERVING PATH for a file's bytes — `GET /file/:id` and `GET /file/:id/variant/:kind`
+ * answer through it, so a variant is served exactly as any File is. Two shapes:
+ *
+ * - **302 redirect** to a short-lived signed URL when the driver's store has an external URL
+ *   space (GCS). The app URL stays the one stable reference every `<img>`/`<video>`/chip uses;
+ *   the client follows the redirect and reads the store directly — native Range/206 for video
+ *   seeking, real caching, bytes never transit the app server. The redirect itself is cached
+ *   briefly (client-private, well under the signed TTL) so repeated loads reuse one URL.
+ * - **Proxy** for drivers with no external URL space (`DbFileStorageDriver`): the interface's
+ *   base64 is decoded so every mime — binary or text — serves its true bytes, and HTTP Range
+ *   is honored (206/416 via {@link resolveByteRange}) so a `<video>` can SEEK against a
+ *   proxy-served blob — streaming parity with the signed-URL path instead of download-then-watch.
+ *
+ * WHICH bytes is `FileStorage`'s decision (`getSignedUrl` / `getFileData` substitute the copy
+ * for others for anyone but the owner); the headers are the row's (its name and type). The
+ * route decided existence and access before calling here (`FileStorage.getFile`).
+ */
+export class FileResponder {
+  /** Serve `file` (a row the caller may read) to `response`; every failure shape mapped to its status. */
+  static async serve(file: File, request: FileRequest, response: FileResponse): Promise<void> {
+    const fileStorage = new FileStorage();
+    try {
+      const signedUrl = await fileStorage.getSignedUrl(file.id);
+      if (signedUrl) {
+        response.setHeader('Cache-Control', 'private, max-age=300');
+        response.redirect(302, signedUrl);
+        return;
+      }
+
+      const bytes = Buffer.from(await fileStorage.getFileData(file.id), 'base64');
+      const safeFilename = encodeURIComponent(file.name);
+      response.setHeader('Content-Disposition', `inline; filename="${safeFilename}"`);
+      response.setHeader('Content-Type', file.type);
+      response.setHeader('Accept-Ranges', 'bytes');
+      const range = resolveByteRange(request.headers?.range, bytes.length);
+      if (range === 'unsatisfiable') {
+        response.setHeader('Content-Range', `bytes */${bytes.length}`);
+        response.status(416).send('Range Not Satisfiable');
+        return;
+      }
+      if (range) {
+        response.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${bytes.length}`);
+        response.status(206).send(bytes.subarray(range.start, range.end + 1));
+        return;
+      }
+      response.send(bytes);
+    } catch (error) {
+      FileResponder.fail(file.id, error, response);
+    }
+  }
+
+  /** The failure shapes a file read has: bytes missing behind a row (404), a refusal (its status, 404), anything else (500, logged). */
+  static fail(fileId: string, error: unknown, response: FileResponse): void {
+    if (FileStorageError.isNotFound(error)) {
+      // The row is there and its bytes are not: the same answer as a row that is not there.
+      response.status(404).send('File not found');
+      return;
+    }
+    if (ServiceRefusal.is(error)) {
+      // A deliberate refusal, not a failure — a file no copy can be made of is not there for anyone
+      // but its owner (`FileStorage` answers every door the same 404 and keeps the maker's reason in
+      // its own WARN). The same words as a row the caller cannot read; quiet, and never a 500.
+      response.status(error.status).send('File not found');
+      return;
+    }
+    console.error(`Error fetching file (${fileId}):`, error);
+    response.status(500).send('Internal Server Error');
+  }
+}

package/src/routes/getFile.ts

@@ -1,23 +1,15 @@
 import { Route } from '@proteinjs/server-api';
 import { getFileStorage } from '../FileStorage';
 import { UserAuth } from '@proteinjs/user';
-import { resolveByteRange } from './byteRange';
+import { FileResponder } from './FileResponder';
 
 /**
  * Serves a file's bytes. Auth first: logged-in, then the `FileStorage.getFile` row read as the
- * access decision — the caller's SCOPED read, else the shared-content reachability leg
- * (`FileReachabilityResolver`: the caller may read a file when they may read a row that
- * references it, e.g. a shared thought's media node). Then one of two serving paths:
- *
- * - **302 redirect** to a short-lived signed URL when the driver's store has an external URL
- *   space (GCS). The app URL stays the one stable reference every `<img>`/`<video>`/chip uses;
- *   the client follows the redirect and reads the store directly — native Range/206 for video
- *   seeking, real caching, bytes never transit the app server. The redirect itself is cached
- *   briefly (client-private, well under the signed TTL) so repeated loads reuse one URL.
- * - **Proxy** for drivers with no external URL space (`DbFileStorageDriver`): the interface's
- *   base64 is decoded so every mime — binary or text — serves its true bytes, and HTTP Range
- *   is honored (206/416 via {@link resolveByteRange}) so a `<video>` can SEEK against a
- *   proxy-served blob — streaming parity with the signed-URL path instead of download-then-watch.
+ * access decision — the caller's SCOPED read, else a variant's original, else the shared-content
+ * reachability leg (`FileReachabilityResolver`: the caller may read a file when they may read a
+ * row that references it, e.g. a shared thought's media node). Then {@link FileResponder} — the
+ * one serving path (a 302 to a signed URL, or the proxy with Range) every file route answers
+ * through.
  */
 export const getFile: Route = {
   path: '/file/:id',
@@ -29,43 +21,16 @@ export const getFile: Route = {
     }
 
     const fileId = request.params.id;
-    const fileStorage = getFileStorage();
     try {
       // The file row decides existence (a scoped-or-reachable read, so it is also the access check).
-      const file = await fileStorage.getFile(fileId);
+      const file = await getFileStorage().getFile(fileId);
       if (!file) {
         response.status(404).send('File not found');
         return;
       }
-
-      const signedUrl = await fileStorage.getSignedUrl(fileId);
-      if (signedUrl) {
-        response.setHeader('Cache-Control', 'private, max-age=300');
-        response.redirect(302, signedUrl);
-        return;
-      }
-
-      const fileDataBase64 = await fileStorage.getFileData(fileId);
-      const bytes = Buffer.from(fileDataBase64, 'base64');
-      const safeFilename = encodeURIComponent(file.name);
-      response.setHeader('Content-Disposition', `inline; filename="${safeFilename}"`);
-      response.setHeader('Content-Type', file.type);
-      response.setHeader('Accept-Ranges', 'bytes');
-      const range = resolveByteRange(request.headers?.range, bytes.length);
-      if (range === 'unsatisfiable') {
-        response.setHeader('Content-Range', `bytes */${bytes.length}`);
-        response.status(416).send('Range Not Satisfiable');
-        return;
-      }
-      if (range) {
-        response.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${bytes.length}`);
-        response.status(206).send(bytes.subarray(range.start, range.end + 1));
-        return;
-      }
-      response.send(bytes);
+      await FileResponder.serve(file, request, response);
     } catch (error) {
-      console.error(`Error fetching file (${fileId}):`, error);
-      response.status(500).send('Internal Server Error');
+      FileResponder.fail(fileId, error, response);
     }
   },
 };

package/src/routes/getFileVariant.ts

@@ -0,0 +1,53 @@
+import { Route } from '@proteinjs/server-api';
+import { UserAuth } from '@proteinjs/user';
+import { FileStorage } from '../FileStorage';
+import { FILE_VARIANT_KINDS, FileVariantKind } from '../FileVariantMaker';
+import { FileResponder } from './FileResponder';
+
+/**
+ * Serves a file's VARIANT of a kind (`preview`, `stage`) — the one URL a surface that draws a
+ * variant asks by (a plain `<img src>`, an off-DOM warm-up), whether or not the file has it yet:
+ *
+ * - the variant the row names is served as any File is ({@link FileResponder} — a 302 to ITS
+ *   signed URL or the proxy, ITS headers; a non-owner is served ITS copy for others);
+ * - a file WITHOUT the variant derives it on this first request, once, through the registered
+ *   `FileVariantMaker` (`FileStorage.getVariant` — a file stored before the kind existed, or by a
+ *   producer that did not derive it; the row's word is decided in one transaction, so a second
+ *   request never re-derives);
+ * - a file the maker does not apply to (a clip, a picture already small), or no maker at all, is
+ *   served AS ITSELF — the consumer always gets a picture from this URL and never branches.
+ *
+ * Auth as `/file/:id`: logged-in, then the original's `getFile` read is the access decision (a
+ * variant is readable by whoever can read its original). A kind the library does not know is a
+ * 404, as a file that is not there.
+ */
+export const getFileVariant: Route = {
+  path: '/file/:id/variant/:kind',
+  method: 'get',
+  onRequest: async (request, response): Promise<void> => {
+    if (!UserAuth.isLoggedIn()) {
+      response.status(401).send('User not logged in');
+      return;
+    }
+
+    const fileId = request.params.id;
+    const kind = request.params.kind as FileVariantKind;
+    if (!FILE_VARIANT_KINDS.includes(kind)) {
+      response.status(404).send('File not found');
+      return;
+    }
+    try {
+      const fileStorage = new FileStorage();
+      // The variant first (its own access read of the original inside); the file itself only when
+      // none applies — so the common request costs one row read before the bytes.
+      const served = (await fileStorage.getVariant(fileId, kind)) ?? (await fileStorage.getFile(fileId));
+      if (!served) {
+        response.status(404).send('File not found');
+        return;
+      }
+      await FileResponder.serve(served, request, response);
+    } catch (error) {
+      FileResponder.fail(fileId, error, response);
+    }
+  },
+};

package/src/routes/getFileVariantRoute.ts

@@ -0,0 +1,7 @@
+import type { FileVariantKind } from '../FileVariantMaker';
+
+/** The URL a surface asks a file's variant of a kind by — served by `GET /file/:id/variant/:kind` (the variant, or the file itself when none applies). */
+export const getFileVariantRoute = {
+  path: (fileId: string, kind: FileVariantKind) => `/file/${fileId}/variant/${kind}`,
+  method: 'get',
+};

package/src/tables/FileTable.ts

@@ -11,8 +11,41 @@ export interface File extends ScopedRecord {
    * Optional preview — another `File` (stored the same way, in GCS) used as a preview/thumbnail of
    * this file's content, e.g. a recording GIF's preview frame. A reference, not an inline blob, so
    * the bytes stay out of the DB row (consistent with the storage model); deleted with this file.
+   *
+   * A VARIANT — one of the derived Files of this file the {@link FileVariantMaker} seam makes
+   * (`preview`, `stage`): the same lifecycle for each — named here, made once (at ingest with the
+   * bytes in hand, or lazily on the first request through `FileStorage.getVariant`), dropped when
+   * this file's bytes change (`FileStorage.updateFileData`), deleted with this file (cascade), and
+   * readable by whoever can read this file (`variantOf`).
    */
-  preview?: Reference<File>;
+  preview?: Reference<File> | null;
+  /**
+   * The stage variant — a second derived `File` sized for the surface that shows the picture large
+   * but not full-screen (a 1600 px longest-edge rendition where the preview is a 512 px thumbnail):
+   * the same mechanism as `preview` in every respect (see there). Absent on files made before the
+   * seam or of a kind the maker does not apply to (a video, an animated picture); the first request
+   * derives it once. A viewer that wants every pixel keeps drawing the original.
+   */
+  stage?: Reference<File> | null;
+  /**
+   * For a variant (`preview`/`stage`) made by the seam: the File it was derived from. The
+   * variant's reachability is its original's — a reader who can read the original (their own
+   * scope, or a row the shared-content leg vouches for) can read the variant by its own id, even
+   * when no content row names the variant (a variant derived after the content was placed). Never
+   * set on a `copyForOthers` copy, whose own id is reachable by nobody but the owner. No cascade
+   * in either direction: the original's own reference (`preview`/`stage`) deletes the variant.
+   */
+  variantOf?: Reference<File> | null;
+  /**
+   * The copy of this file served to anyone who is not its owner — another `File` (the same
+   * store, the owner's scope), made ONCE by the registered {@link FileCopyForOthers} the first
+   * time a non-owner reads the bytes, named here so every later read serves it without remaking
+   * it. `null`/absent means no copy has been made yet: the next non-owner read makes one when the
+   * maker applies to this file, and serves the original when it does not. Dropped when the
+   * original's bytes change (`FileStorage.updateFileData`) and deleted with this file (cascade).
+   * The owner is never served it — their own scoped read serves the original.
+   */
+  copyForOthers?: Reference<File> | null;
   /**
    * Media metadata — generic file facts (an image/video's pixel dimensions, a video/audio
    * duration) every consumer needs to render without loading bytes, e.g. reserving a media box's
@@ -49,6 +82,21 @@ export interface File extends ScopedRecord {
    * an integrity fact. Absent for files written before the column existed.
    */
   contentHash?: string;
+  /**
+   * Producer attribution — HOW these bytes came to exist (e.g. a user upload, a browser
+   * capture, model generation, a rendered mockup). Same layer ruling as `width`/`height`:
+   * provenance is a generic file fact consumers need without a join — e.g. evidence surfaces
+   * that must refuse non-capture media as proof. Set by ingest paths that know their producer;
+   * absent for everything else. Values are the producing domain's vocabulary, not enumerated
+   * here.
+   */
+  origin?: string;
+  /**
+   * The id of the model that made the bytes, when a model did — `origin` names the KIND of
+   * producer, this names the one. Absent for every other producer. Read by a consumer that
+   * labels a made file with what made it, without a join.
+   */
+  originModel?: string;
 }
 
 export class FileTable extends Table<File> {
@@ -67,6 +115,12 @@ export class FileTable extends Table<File> {
     size: new IntegerColumn('size'),
     // Self-reference (the preview is itself a File). cascadeDelete: removing a file removes its preview.
     preview: new ReferenceColumn<File>('preview', FILE_TABLE_NAME, true),
+    // Self-reference (the stage variant is itself a File). cascadeDelete: removing a file removes its stage variant.
+    stage: new ReferenceColumn<File>('stage', FILE_TABLE_NAME, true),
+    // Self-reference (a variant names its original). No cascade: the original's own reference deletes the variant.
+    variantOf: new ReferenceColumn<File>('variant_of', FILE_TABLE_NAME, false),
+    // Self-reference (the copy is itself a File). cascadeDelete: removing a file removes the copy others were served.
+    copyForOthers: new ReferenceColumn<File>('copy_for_others', FILE_TABLE_NAME, true),
     width: new IntegerColumn('width'),
     height: new IntegerColumn('height'),
     durationMs: new IntegerColumn('duration_ms'),
@@ -80,6 +134,8 @@ export class FileTable extends Table<File> {
     licenseUrl: new StringColumn('license_url', {}, 'MAX'),
     attribution: new StringColumn('attribution', {}, 'MAX'),
     contentHash: new StringColumn('content_hash', {}, 64),
+    origin: new StringColumn('origin', undefined, 50),
+    originModel: new StringColumn('origin_model', undefined, 200),
   });
   // Dedup lookup path: find the caller's existing copy of these bytes (content_hash is only
   // ever queried per-user — createScopedIndex prefixes the scope column).

package/test/DbFileStorageDriverMissingBytes.test.ts

@@ -0,0 +1,85 @@
+import { QueryBuilderFactory, getDbAsSystem } from '@proteinjs/db';
+import { User } from '@proteinjs/user';
+import { File } from '../src/tables/FileTable';
+import { tables } from '../src/tables/tables';
+import { FileStorage } from '../src/FileStorage';
+import { FileStorageError } from '../src/FileStorageError';
+import { DbFileStorageDriver } from '../src/DbFileStorageDriver';
+import { FileTestEnvironment } from './FileTestEnvironment';
+
+/**
+ * The driver contract has one answer for bytes that are not there: the `not-found` code. An
+ * object store says it for a missing object; this driver's store is the chunk table, where
+ * "nothing stored" and "an empty file" both used to read as zero chunk rows and came back as `''`
+ * — so a caller could not tell a lost file from an empty one, and code that branched on the
+ * object store's error never ran against this driver.
+ */
+const testEnv = new FileTestEnvironment();
+const driver = new DbFileStorageDriver();
+let owner: User;
+
+beforeAll(async () => {
+  await testEnv.beforeAll();
+  testEnv.setDriver(driver);
+  owner = await testEnv.createUser({ name: 'File owner', email: 'missing-bytes-owner@test.local' });
+  testEnv.actAs(owner);
+});
+
+afterAll(async () => {
+  await testEnv.afterAll();
+});
+
+const chunkRows = async (fileId: string) =>
+  await getDbAsSystem().query(
+    tables.FileData,
+    new QueryBuilderFactory().getQueryBuilder(tables.FileData, { file: fileId })
+  );
+
+describe('DbFileStorageDriver reports bytes that are not there as not-found', () => {
+  it('a file row whose bytes are gone is not-found, not an empty string', async () => {
+    const bytes = Buffer.from('the bytes of a picture');
+    const file = await new FileStorage().createFile(
+      { name: 'holiday.jpg', type: 'image/jpeg', size: bytes.length } as File,
+      bytes.toString('base64')
+    );
+    await driver.deleteFile(file.id);
+
+    const failure = await driver.getFileData(file.id).catch((error) => error);
+
+    expect(FileStorageError.isNotFound(failure)).toBe(true);
+    expect(failure.message).toEqual(`getFileData failed for file ${file.id}: not-found`);
+  });
+
+  it('an id that names no file at all is not-found', async () => {
+    const failure = await driver.getFileData('no-such-file-id').catch((error) => error);
+
+    expect(FileStorageError.isNotFound(failure)).toBe(true);
+  });
+
+  it('an empty file is stored, and reads back as empty', async () => {
+    const file = await new FileStorage().createFile({ name: 'empty.txt', type: 'text/plain', size: 0 } as File, '');
+
+    expect(await chunkRows(file.id)).toHaveLength(1);
+    expect(await driver.getFileData(file.id)).toEqual('');
+  });
+
+  it('a file overwritten with nothing stays stored, whatever its row says about its size', async () => {
+    const bytes = Buffer.from('first');
+    const file = await new FileStorage().createFile(
+      { name: 'note.txt', type: 'text/plain', size: bytes.length } as File,
+      bytes.toString('base64')
+    );
+
+    await driver.updateFileData(file.id, '');
+
+    expect(await driver.getFileData(file.id)).toEqual('');
+  });
+
+  it('an empty file written before empty files had a chunk row still reads back as empty', async () => {
+    const file = await new FileStorage().createFile({ name: 'old-empty.txt', type: 'text/plain', size: 0 } as File, '');
+    await driver.deleteFile(file.id);
+    expect(await chunkRows(file.id)).toHaveLength(0);
+
+    expect(await driver.getFileData(file.id)).toEqual('');
+  });
+});

package/test/FileByteAccess.test.ts

@@ -1,5 +1,6 @@
 import { SourceRepository } from '@proteinjs/reflection';
 import { User } from '@proteinjs/user';
+import { ServiceRefusal } from '@proteinjs/service';
 import { File } from '../src/tables/FileTable';
 import { FileStorage } from '../src/FileStorage';
 import { DbFileStorageDriver } from '../src/DbFileStorageDriver';
@@ -95,7 +96,12 @@ describe('byte reads gate on the file-row read (the getFile decision)', () => {
     const file = await createOwnerFile('private-bytes.bin');
 
     testEnv.actAs(stranger);
-    await expect(new FileStorage().getFileData(file.id)).rejects.toThrow(`File not found: ${file.id}`);
+    const denial = await new FileStorage().getFileData(file.id).then(
+      () => undefined,
+      (error: unknown) => error
+    );
+    // The one answer a byte door gives: a 404 refusal, never the id (a file not there reads the same).
+    expect(ServiceRefusal.is(denial) && [denial.status, denial.message]).toEqual([404, 'File not found']);
   });
 
   it('a shared-content recipient (resolver-vouched) reads the bytes byte-identical', async () => {