@proteinjs/db-file 1.8.4 → 1.9.1

package/dist/src/routes/getFile.js

@@ -39,83 +39,47 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFile = void 0;
 var FileStorage_1 = require("../FileStorage");
 var user_1 = require("@proteinjs/user");
-var byteRange_1 = require("./byteRange");
+var FileResponder_1 = require("./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.
  */
 exports.getFile = {
     path: '/file/:id',
     method: 'get',
     onRequest: function (request, response) { return __awaiter(void 0, void 0, void 0, function () {
-        var fileId, fileStorage, file, signedUrl, fileDataBase64, bytes, safeFilename, range, error_1;
-        var _a;
-        return __generator(this, function (_b) {
-            switch (_b.label) {
+        var fileId, file, error_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
                 case 0:
                     if (!user_1.UserAuth.isLoggedIn()) {
                         response.status(401).send('User not logged in');
                         return [2 /*return*/];
                     }
                     fileId = request.params.id;
-                    fileStorage = (0, FileStorage_1.getFileStorage)();
-                    _b.label = 1;
+                    _a.label = 1;
                 case 1:
-                    _b.trys.push([1, 5, , 6]);
-                    return [4 /*yield*/, fileStorage.getFile(fileId)];
+                    _a.trys.push([1, 4, , 5]);
+                    return [4 /*yield*/, (0, FileStorage_1.getFileStorage)().getFile(fileId)];
                 case 2:
-                    file = _b.sent();
+                    file = _a.sent();
                     if (!file) {
                         response.status(404).send('File not found');
                         return [2 /*return*/];
                     }
-                    return [4 /*yield*/, fileStorage.getSignedUrl(fileId)];
+                    return [4 /*yield*/, FileResponder_1.FileResponder.serve(file, request, response)];
                 case 3:
-                    signedUrl = _b.sent();
-                    if (signedUrl) {
-                        response.setHeader('Cache-Control', 'private, max-age=300');
-                        response.redirect(302, signedUrl);
-                        return [2 /*return*/];
-                    }
-                    return [4 /*yield*/, fileStorage.getFileData(fileId)];
+                    _a.sent();
+                    return [3 /*break*/, 5];
                 case 4:
-                    fileDataBase64 = _b.sent();
-                    bytes = Buffer.from(fileDataBase64, 'base64');
-                    safeFilename = encodeURIComponent(file.name);
-                    response.setHeader('Content-Disposition', "inline; filename=\"".concat(safeFilename, "\""));
-                    response.setHeader('Content-Type', file.type);
-                    response.setHeader('Accept-Ranges', 'bytes');
-                    range = (0, byteRange_1.resolveByteRange)((_a = request.headers) === null || _a === void 0 ? void 0 : _a.range, bytes.length);
-                    if (range === 'unsatisfiable') {
-                        response.setHeader('Content-Range', "bytes */".concat(bytes.length));
-                        response.status(416).send('Range Not Satisfiable');
-                        return [2 /*return*/];
-                    }
-                    if (range) {
-                        response.setHeader('Content-Range', "bytes ".concat(range.start, "-").concat(range.end, "/").concat(bytes.length));
-                        response.status(206).send(bytes.subarray(range.start, range.end + 1));
-                        return [2 /*return*/];
-                    }
-                    response.send(bytes);
-                    return [3 /*break*/, 6];
-                case 5:
-                    error_1 = _b.sent();
-                    console.error("Error fetching file (".concat(fileId, "):"), error_1);
-                    response.status(500).send('Internal Server Error');
-                    return [3 /*break*/, 6];
-                case 6: return [2 /*return*/];
+                    error_1 = _a.sent();
+                    FileResponder_1.FileResponder.fail(fileId, error_1, response);
+                    return [3 /*break*/, 5];
+                case 5: return [2 /*return*/];
             }
         });
     }); },

package/dist/src/routes/getFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"getFile.js","sourceRoot":"","sources":["../../../src/routes/getFile.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,8CAAgD;AAChD,wCAA2C;AAC3C,yCAA+C;AAE/C;;;;;;;;;;;;;;;GAeG;AACU,QAAA,OAAO,GAAU;IAC5B,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,KAAK;IACb,SAAS,EAAE,UAAO,OAAO,EAAE,QAAQ;;;;;;oBACjC,IAAI,CAAC,eAAQ,CAAC,UAAU,EAAE,EAAE;wBAC1B,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;wBAChD,sBAAO;qBACR;oBAEK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC3B,WAAW,GAAG,IAAA,4BAAc,GAAE,CAAC;;;;oBAGtB,qBAAM,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAA;;oBAAxC,IAAI,GAAG,SAAiC;oBAC9C,IAAI,CAAC,IAAI,EAAE;wBACT,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;wBAC5C,sBAAO;qBACR;oBAEiB,qBAAM,WAAW,CAAC,YAAY,CAAC,MAAM,CAAC,EAAA;;oBAAlD,SAAS,GAAG,SAAsC;oBACxD,IAAI,SAAS,EAAE;wBACb,QAAQ,CAAC,SAAS,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC;wBAC5D,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;wBAClC,sBAAO;qBACR;oBAEsB,qBAAM,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,EAAA;;oBAAtD,cAAc,GAAG,SAAqC;oBACtD,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;oBAC9C,YAAY,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACnD,QAAQ,CAAC,SAAS,CAAC,qBAAqB,EAAE,6BAAqB,YAAY,OAAG,CAAC,CAAC;oBAChF,QAAQ,CAAC,SAAS,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;oBAC9C,QAAQ,CAAC,SAAS,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;oBACvC,KAAK,GAAG,IAAA,4BAAgB,EAAC,MAAA,OAAO,CAAC,OAAO,0CAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;oBACrE,IAAI,KAAK,KAAK,eAAe,EAAE;wBAC7B,QAAQ,CAAC,SAAS,CAAC,eAAe,EAAE,kBAAW,KAAK,CAAC,MAAM,CAAE,CAAC,CAAC;wBAC/D,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;wBACnD,sBAAO;qBACR;oBACD,IAAI,KAAK,EAAE;wBACT,QAAQ,CAAC,SAAS,CAAC,eAAe,EAAE,gBAAS,KAAK,CAAC,KAAK,cAAI,KAAK,CAAC,GAAG,cAAI,KAAK,CAAC,MAAM,CAAE,CAAC,CAAC;wBACzF,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;wBACtE,sBAAO;qBACR;oBACD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;;;oBAErB,OAAO,CAAC,KAAK,CAAC,+BAAwB,MAAM,OAAI,EAAE,OAAK,CAAC,CAAC;oBACzD,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;;;;;SAEtD;CACF,CAAC"}
+{"version":3,"file":"getFile.js","sourceRoot":"","sources":["../../../src/routes/getFile.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,8CAAgD;AAChD,wCAA2C;AAC3C,iDAAgD;AAEhD;;;;;;;GAOG;AACU,QAAA,OAAO,GAAU;IAC5B,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,KAAK;IACb,SAAS,EAAE,UAAO,OAAO,EAAE,QAAQ;;;;;oBACjC,IAAI,CAAC,eAAQ,CAAC,UAAU,EAAE,EAAE;wBAC1B,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;wBAChD,sBAAO;qBACR;oBAEK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;;;;oBAGlB,qBAAM,IAAA,4BAAc,GAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAAA;;oBAA7C,IAAI,GAAG,SAAsC;oBACnD,IAAI,CAAC,IAAI,EAAE;wBACT,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;wBAC5C,sBAAO;qBACR;oBACD,qBAAM,6BAAa,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAA;;oBAAlD,SAAkD,CAAC;;;;oBAEnD,6BAAa,CAAC,IAAI,CAAC,MAAM,EAAE,OAAK,EAAE,QAAQ,CAAC,CAAC;;;;;SAE/C;CACF,CAAC"}

package/dist/src/routes/getFileVariant.d.ts

@@ -0,0 +1,20 @@
+import { Route } from '@proteinjs/server-api';
+/**
+ * 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 declare const getFileVariant: Route;
+//# sourceMappingURL=getFileVariant.d.ts.map

package/dist/src/routes/getFileVariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFileVariant.d.ts","sourceRoot":"","sources":["../../../src/routes/getFileVariant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAM9C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,EAAE,KA6B5B,CAAC"}

package/dist/src/routes/getFileVariant.js

@@ -0,0 +1,112 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFileVariant = void 0;
+var user_1 = require("@proteinjs/user");
+var FileStorage_1 = require("../FileStorage");
+var FileVariantMaker_1 = require("../FileVariantMaker");
+var FileResponder_1 = require("./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.
+ */
+exports.getFileVariant = {
+    path: '/file/:id/variant/:kind',
+    method: 'get',
+    onRequest: function (request, response) { return __awaiter(void 0, void 0, void 0, function () {
+        var fileId, kind, fileStorage, served, _a, error_1;
+        var _b;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    if (!user_1.UserAuth.isLoggedIn()) {
+                        response.status(401).send('User not logged in');
+                        return [2 /*return*/];
+                    }
+                    fileId = request.params.id;
+                    kind = request.params.kind;
+                    if (!FileVariantMaker_1.FILE_VARIANT_KINDS.includes(kind)) {
+                        response.status(404).send('File not found');
+                        return [2 /*return*/];
+                    }
+                    _c.label = 1;
+                case 1:
+                    _c.trys.push([1, 7, , 8]);
+                    fileStorage = new FileStorage_1.FileStorage();
+                    return [4 /*yield*/, fileStorage.getVariant(fileId, kind)];
+                case 2:
+                    if (!((_b = (_c.sent())) !== null && _b !== void 0)) return [3 /*break*/, 3];
+                    _a = _b;
+                    return [3 /*break*/, 5];
+                case 3: return [4 /*yield*/, fileStorage.getFile(fileId)];
+                case 4:
+                    _a = (_c.sent());
+                    _c.label = 5;
+                case 5:
+                    served = _a;
+                    if (!served) {
+                        response.status(404).send('File not found');
+                        return [2 /*return*/];
+                    }
+                    return [4 /*yield*/, FileResponder_1.FileResponder.serve(served, request, response)];
+                case 6:
+                    _c.sent();
+                    return [3 /*break*/, 8];
+                case 7:
+                    error_1 = _c.sent();
+                    FileResponder_1.FileResponder.fail(fileId, error_1, response);
+                    return [3 /*break*/, 8];
+                case 8: return [2 /*return*/];
+            }
+        });
+    }); },
+};
+//# sourceMappingURL=getFileVariant.js.map

package/dist/src/routes/getFileVariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFileVariant.js","sourceRoot":"","sources":["../../../src/routes/getFileVariant.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,wCAA2C;AAC3C,8CAA6C;AAC7C,wDAA0E;AAC1E,iDAAgD;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,cAAc,GAAU;IACnC,IAAI,EAAE,yBAAyB;IAC/B,MAAM,EAAE,KAAK;IACb,SAAS,EAAE,UAAO,OAAO,EAAE,QAAQ;;;;;;oBACjC,IAAI,CAAC,eAAQ,CAAC,UAAU,EAAE,EAAE;wBAC1B,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;wBAChD,sBAAO;qBACR;oBAEK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC3B,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,IAAuB,CAAC;oBACpD,IAAI,CAAC,qCAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;wBACtC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;wBAC5C,sBAAO;qBACR;;;;oBAEO,WAAW,GAAG,IAAI,yBAAW,EAAE,CAAC;oBAGtB,qBAAM,WAAW,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,EAAA;;gCAA3C,CAAC,SAA0C,CAAC;;;wBAAK,qBAAM,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAA;;oBAAlC,KAAA,CAAC,SAAiC,CAAC,CAAA;;;oBAA5F,MAAM,KAAsF;oBAClG,IAAI,CAAC,MAAM,EAAE;wBACX,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;wBAC5C,sBAAO;qBACR;oBACD,qBAAM,6BAAa,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAA;;oBAApD,SAAoD,CAAC;;;;oBAErD,6BAAa,CAAC,IAAI,CAAC,MAAM,EAAE,OAAK,EAAE,QAAQ,CAAC,CAAC;;;;;SAE/C;CACF,CAAC"}

package/dist/src/routes/getFileVariantRoute.d.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 declare const getFileVariantRoute: {
+    path: (fileId: string, kind: FileVariantKind) => string;
+    method: string;
+};
+//# sourceMappingURL=getFileVariantRoute.d.ts.map

package/dist/src/routes/getFileVariantRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFileVariantRoute.d.ts","sourceRoot":"","sources":["../../../src/routes/getFileVariantRoute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,0JAA0J;AAC1J,eAAO,MAAM,mBAAmB;mBACf,MAAM,QAAQ,eAAe;;CAE7C,CAAC"}

package/dist/src/routes/getFileVariantRoute.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFileVariantRoute = void 0;
+/** 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). */
+exports.getFileVariantRoute = {
+    path: function (fileId, kind) { return "/file/".concat(fileId, "/variant/").concat(kind); },
+    method: 'get',
+};
+//# sourceMappingURL=getFileVariantRoute.js.map

package/dist/src/routes/getFileVariantRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFileVariantRoute.js","sourceRoot":"","sources":["../../../src/routes/getFileVariantRoute.ts"],"names":[],"mappings":";;;AAEA,0JAA0J;AAC7I,QAAA,mBAAmB,GAAG;IACjC,IAAI,EAAE,UAAC,MAAc,EAAE,IAAqB,IAAK,OAAA,gBAAS,MAAM,sBAAY,IAAI,CAAE,EAAjC,CAAiC;IAClF,MAAM,EAAE,KAAK;CACd,CAAC"}

package/dist/src/tables/FileTable.d.ts

@@ -8,8 +8,43 @@ 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),
+     * readable by whoever can read this file (`variantOf`), and carrying this file's provenance
+     * ({@link FileTable.provenanceColumns}) — a rendition's provenance is its original's.
      */
-    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. Carries this
+     * file's provenance ({@link FileTable.provenanceColumns}), as every derived File does.
+     */
+    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
@@ -46,8 +81,36 @@ 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 declare class FileTable extends Table<File> {
+    /**
+     * The columns that are a file's PROVENANCE — where its bytes came from and under what terms: the
+     * producer (`origin`, `originModel`), the web source (`sourceUrl`, `sourcePageUrl`,
+     * `retrievedAt`) and the rights record (`license`, `licenseUrl`, `attribution`). ONE list, the
+     * table's own: every derived File the library makes of a file — a variant (`preview`, `stage`)
+     * and the copy for others — carries these from the row it was made from (`FileStorage` writes
+     * them at insert), so a consumer reads a rendition's provenance off the row it draws, without a
+     * join, and a row with none derives rows with none. A column that describes THE ROW'S OWN bytes
+     * (`size`, `contentHash`, the media dimensions) is not provenance and is never copied — the
+     * maker answers those. A new provenance column is added HERE with its column; nothing else
+     * names the list.
+     */
+    static readonly provenanceColumns: ReadonlyArray<keyof File>;
     name: string;
     auth: Table<File>['auth'];
     columns: {
@@ -59,7 +122,10 @@ export declare class FileTable extends Table<File> {
         name: import("@proteinjs/db").Column<string, any>;
         type: import("@proteinjs/db").Column<string, any>;
         size: import("@proteinjs/db").Column<number, any>;
-        preview: import("@proteinjs/db").Column<Reference<File> | undefined, any>;
+        preview: import("@proteinjs/db").Column<Reference<File> | null | undefined, any>;
+        stage: import("@proteinjs/db").Column<Reference<File> | null | undefined, any>;
+        variantOf: import("@proteinjs/db").Column<Reference<File> | null | undefined, any>;
+        copyForOthers: import("@proteinjs/db").Column<Reference<File> | null | undefined, any>;
         width: import("@proteinjs/db").Column<number | undefined, any>;
         height: import("@proteinjs/db").Column<number | undefined, any>;
         durationMs: import("@proteinjs/db").Column<number | undefined, any>;
@@ -70,6 +136,8 @@ export declare class FileTable extends Table<File> {
         licenseUrl: import("@proteinjs/db").Column<string | undefined, any>;
         attribution: import("@proteinjs/db").Column<string | undefined, any>;
         contentHash: import("@proteinjs/db").Column<string | undefined, any>;
+        origin: import("@proteinjs/db").Column<string | undefined, any>;
+        originModel: import("@proteinjs/db").Column<string | undefined, any>;
     } & {};
     indexes: {
         columns: (keyof File)[];

package/dist/src/tables/FileTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileTable.d.ts","sourceRoot":"","sources":["../../../src/tables/FileTable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAgD,SAAS,EAAc,MAAM,eAAe,CAAC;AAC3G,OAAO,EAAE,YAAY,EAA8C,MAAM,iBAAiB,CAAC;AAI3F,MAAM,WAAW,IAAK,SAAQ,YAAY;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,SAAU,SAAQ,KAAK,CAAC,IAAI,CAAC;IACjC,IAAI,SAAmB;IACvB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAO9B;IACK,OAAO;;;;;;;;;;;;;;;;;;;;WAmBX;IAGI,OAAO;;;QAA0F;CAGzG"}
+{"version":3,"file":"FileTable.d.ts","sourceRoot":"","sources":["../../../src/tables/FileTable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAgD,SAAS,EAAc,MAAM,eAAe,CAAC;AAC3G,OAAO,EAAE,YAAY,EAA8C,MAAM,iBAAiB,CAAC;AAI3F,MAAM,WAAW,IAAK,SAAQ,YAAY;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnC;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,SAAU,SAAQ,KAAK,CAAC,IAAI,CAAC;IACxC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,MAAM,IAAI,CAAC,CAS1D;IAEK,IAAI,SAAmB;IACvB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAO9B;IACK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;WA2BX;IAGI,OAAO;;;QAA0F;CAGzG"}

package/dist/src/tables/FileTable.js

@@ -38,6 +38,12 @@ var FileTable = /** @class */ (function (_super) {
             size: new db_1.IntegerColumn('size'),
             // Self-reference (the preview is itself a File). cascadeDelete: removing a file removes its preview.
             preview: new db_1.ReferenceColumn('preview', FILE_TABLE_NAME, true),
+            // Self-reference (the stage variant is itself a File). cascadeDelete: removing a file removes its stage variant.
+            stage: new db_1.ReferenceColumn('stage', FILE_TABLE_NAME, true),
+            // Self-reference (a variant names its original). No cascade: the original's own reference deletes the variant.
+            variantOf: new db_1.ReferenceColumn('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 db_1.ReferenceColumn('copy_for_others', FILE_TABLE_NAME, true),
             width: new db_1.IntegerColumn('width'),
             height: new db_1.IntegerColumn('height'),
             durationMs: new db_1.IntegerColumn('duration_ms'),
@@ -51,6 +57,8 @@ var FileTable = /** @class */ (function (_super) {
             licenseUrl: new db_1.StringColumn('license_url', {}, 'MAX'),
             attribution: new db_1.StringColumn('attribution', {}, 'MAX'),
             contentHash: new db_1.StringColumn('content_hash', {}, 64),
+            origin: new db_1.StringColumn('origin', undefined, 50),
+            originModel: new db_1.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).
@@ -59,6 +67,28 @@ var FileTable = /** @class */ (function (_super) {
         // No cascadeDeleteReferences for FileData: byte cleanup (FileData rows included) is owned by
         // FileStorageDriver.deleteFile, invoked for every file-row delete by FileStorageTableWatcher.
     }
+    /**
+     * The columns that are a file's PROVENANCE — where its bytes came from and under what terms: the
+     * producer (`origin`, `originModel`), the web source (`sourceUrl`, `sourcePageUrl`,
+     * `retrievedAt`) and the rights record (`license`, `licenseUrl`, `attribution`). ONE list, the
+     * table's own: every derived File the library makes of a file — a variant (`preview`, `stage`)
+     * and the copy for others — carries these from the row it was made from (`FileStorage` writes
+     * them at insert), so a consumer reads a rendition's provenance off the row it draws, without a
+     * join, and a row with none derives rows with none. A column that describes THE ROW'S OWN bytes
+     * (`size`, `contentHash`, the media dimensions) is not provenance and is never copied — the
+     * maker answers those. A new provenance column is added HERE with its column; nothing else
+     * names the list.
+     */
+    FileTable.provenanceColumns = [
+        'origin',
+        'originModel',
+        'sourceUrl',
+        'sourcePageUrl',
+        'retrievedAt',
+        'license',
+        'licenseUrl',
+        'attribution',
+    ];
     return FileTable;
 }(db_1.Table));
 exports.FileTable = FileTable;

package/dist/src/tables/FileTable.js.map

@@ -1 +1 @@
-{"version":3,"file":"FileTable.js","sourceRoot":"","sources":["../../../src/tables/FileTable.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAAA,oCAA2G;AAC3G,wCAA2F;AAE3F,IAAM,eAAe,GAAG,MAAM,CAAC;AAkD/B;IAA+B,6BAAW;IAA1C;QAAA,qEAmCC;QAlCQ,UAAI,GAAG,eAAe,CAAC;QACvB,UAAI,GAAwB;YACjC,EAAE,EAAE;gBACF,GAAG,EAAE,eAAe;aACrB;YACD,OAAO,EAAE;gBACP,GAAG,EAAE,eAAe;aACrB;SACF,CAAC;QACK,aAAO,GAAG,IAAA,8BAAuB,EAAO;YAC7C,IAAI,EAAE,IAAI,iBAAY,CAAC,MAAM,CAAC;YAC9B,IAAI,EAAE,IAAI,iBAAY,CAAC,MAAM,CAAC;YAC9B,IAAI,EAAE,IAAI,kBAAa,CAAC,MAAM,CAAC;YAC/B,qGAAqG;YACrG,OAAO,EAAE,IAAI,oBAAe,CAAO,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC;YACpE,KAAK,EAAE,IAAI,kBAAa,CAAC,OAAO,CAAC;YACjC,MAAM,EAAE,IAAI,kBAAa,CAAC,QAAQ,CAAC;YACnC,UAAU,EAAE,IAAI,kBAAa,CAAC,aAAa,CAAC;YAC5C,yFAAyF;YACzF,SAAS,EAAE,IAAI,iBAAY,CAAC,YAAY,EAAE,EAAE,EAAE,KAAK,CAAC;YACpD,aAAa,EAAE,IAAI,iBAAY,CAAC,iBAAiB,EAAE,EAAE,EAAE,KAAK,CAAC;YAC7D,WAAW,EAAE,IAAI,eAAU,CAAC,cAAc,CAAC;YAC3C,wFAAwF;YACxF,iEAAiE;YACjE,OAAO,EAAE,IAAI,iBAAY,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC;YAC5C,UAAU,EAAE,IAAI,iBAAY,CAAC,aAAa,EAAE,EAAE,EAAE,KAAK,CAAC;YACtD,WAAW,EAAE,IAAI,iBAAY,CAAC,aAAa,EAAE,EAAE,EAAE,KAAK,CAAC;YACvD,WAAW,EAAE,IAAI,iBAAY,CAAC,cAAc,EAAE,EAAE,EAAE,EAAE,CAAC;SACtD,CAAC,CAAC;QACH,0FAA0F;QAC1F,wEAAwE;QACjE,aAAO,GAAG,CAAC,IAAA,wBAAiB,EAAO,EAAE,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC,CAAC,CAAC;;QACxG,6FAA6F;QAC7F,8FAA8F;IAChG,CAAC;IAAD,gBAAC;AAAD,CAAC,AAnCD,CAA+B,UAAK,GAmCnC;AAnCY,8BAAS"}
+{"version":3,"file":"FileTable.js","sourceRoot":"","sources":["../../../src/tables/FileTable.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAAA,oCAA2G;AAC3G,wCAA2F;AAE3F,IAAM,eAAe,GAAG,MAAM,CAAC;AAoG/B;IAA+B,6BAAW;IAA1C;QAAA,qEAkEC;QA1CQ,UAAI,GAAG,eAAe,CAAC;QACvB,UAAI,GAAwB;YACjC,EAAE,EAAE;gBACF,GAAG,EAAE,eAAe;aACrB;YACD,OAAO,EAAE;gBACP,GAAG,EAAE,eAAe;aACrB;SACF,CAAC;QACK,aAAO,GAAG,IAAA,8BAAuB,EAAO;YAC7C,IAAI,EAAE,IAAI,iBAAY,CAAC,MAAM,CAAC;YAC9B,IAAI,EAAE,IAAI,iBAAY,CAAC,MAAM,CAAC;YAC9B,IAAI,EAAE,IAAI,kBAAa,CAAC,MAAM,CAAC;YAC/B,qGAAqG;YACrG,OAAO,EAAE,IAAI,oBAAe,CAAO,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC;YACpE,iHAAiH;YACjH,KAAK,EAAE,IAAI,oBAAe,CAAO,OAAO,EAAE,eAAe,EAAE,IAAI,CAAC;YAChE,+GAA+G;YAC/G,SAAS,EAAE,IAAI,oBAAe,CAAO,YAAY,EAAE,eAAe,EAAE,KAAK,CAAC;YAC1E,kHAAkH;YAClH,aAAa,EAAE,IAAI,oBAAe,CAAO,iBAAiB,EAAE,eAAe,EAAE,IAAI,CAAC;YAClF,KAAK,EAAE,IAAI,kBAAa,CAAC,OAAO,CAAC;YACjC,MAAM,EAAE,IAAI,kBAAa,CAAC,QAAQ,CAAC;YACnC,UAAU,EAAE,IAAI,kBAAa,CAAC,aAAa,CAAC;YAC5C,yFAAyF;YACzF,SAAS,EAAE,IAAI,iBAAY,CAAC,YAAY,EAAE,EAAE,EAAE,KAAK,CAAC;YACpD,aAAa,EAAE,IAAI,iBAAY,CAAC,iBAAiB,EAAE,EAAE,EAAE,KAAK,CAAC;YAC7D,WAAW,EAAE,IAAI,eAAU,CAAC,cAAc,CAAC;YAC3C,wFAAwF;YACxF,iEAAiE;YACjE,OAAO,EAAE,IAAI,iBAAY,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC;YAC5C,UAAU,EAAE,IAAI,iBAAY,CAAC,aAAa,EAAE,EAAE,EAAE,KAAK,CAAC;YACtD,WAAW,EAAE,IAAI,iBAAY,CAAC,aAAa,EAAE,EAAE,EAAE,KAAK,CAAC;YACvD,WAAW,EAAE,IAAI,iBAAY,CAAC,cAAc,EAAE,EAAE,EAAE,EAAE,CAAC;YACrD,MAAM,EAAE,IAAI,iBAAY,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,CAAC;YACjD,WAAW,EAAE,IAAI,iBAAY,CAAC,cAAc,EAAE,SAAS,EAAE,GAAG,CAAC;SAC9D,CAAC,CAAC;QACH,0FAA0F;QAC1F,wEAAwE;QACjE,aAAO,GAAG,CAAC,IAAA,wBAAiB,EAAO,EAAE,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC,CAAC,CAAC;;QACxG,6FAA6F;QAC7F,8FAA8F;IAChG,CAAC;IAjEC;;;;;;;;;;;OAWG;IACa,2BAAiB,GAA8B;QAC7D,QAAQ;QACR,aAAa;QACb,WAAW;QACX,eAAe;QACf,aAAa;QACb,SAAS;QACT,YAAY;QACZ,aAAa;KACd,AATgC,CAS/B;IA4CJ,gBAAC;CAAA,AAlED,CAA+B,UAAK,GAkEnC;AAlEY,8BAAS"}

package/dist/test/DbFileStorageDriverMissingBytes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=DbFileStorageDriverMissingBytes.test.d.ts.map

package/dist/test/DbFileStorageDriverMissingBytes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DbFileStorageDriverMissingBytes.test.d.ts","sourceRoot":"","sources":["../../test/DbFileStorageDriverMissingBytes.test.ts"],"names":[],"mappings":""}