@tumbaland/backend-core 1.24.0 → 1.26.0

package/dist/entitlements/reconcile.js

@@ -0,0 +1,297 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECONCILED_METERS = void 0;
+exports.reconcileUsageMeters = reconcileUsageMeters;
+exports.runUsageReconciliation = runUsageReconciliation;
+const mongoose_1 = __importDefault(require("mongoose"));
+const logger_1 = __importDefault(require("../logging/logger"));
+const UsageMeter_1 = require("./UsageMeter");
+/**
+ * Rebuild the cumulative usage meters from the data they describe.
+ *
+ * **Why this can exist at all:** every meter reconciled here is *derived*.
+ * `storageBytes` is the sum of photo sizes, `trackedTickers` the count of
+ * active symbols, `seats` the members of the groups a subject owns — in each
+ * case the underlying collection is the record and the counter is only a cache
+ * of it, kept hot because a quota check cannot afford the aggregation. So the
+ * counter can always be recomputed, and reconciliation is cache invalidation.
+ *
+ * `aiJobs` is deliberately absent, and its absence is the same rule read the
+ * other way: nothing records that a GPU job happened except the counter itself,
+ * so there is no truth to recompute it from. That is precisely why
+ * `consumeQuota` rolls its increment back on rejection rather than leaving it —
+ * a leaked increment on that meter is permanent, where here it is temporary.
+ *
+ * **On racing with live writes:** a `consumeQuota` landing between the
+ * aggregation and the write is lost. That is tolerable for exactly the reason
+ * above — the next run re-derives the same number from source and converges —
+ * so this is scheduled at a quiet hour rather than defended with a lock.
+ *
+ * Reads collections owned by other services through the raw driver rather than
+ * mongoose models. They are not this library's documents to model, every
+ * service shares one database, and going through the driver avoids registering
+ * a second model for a schema that already exists elsewhere.
+ */
+/** Meters whose value can be recomputed from source data. See the note above. */
+exports.RECONCILED_METERS = ['storageBytes', 'trackedTickers', 'seats'];
+const normalizeEmail = (value) => typeof value === 'string' && value.trim() ? value.trim().toLowerCase() : undefined;
+/**
+ * Whoever currently holds the `owner` role — that is what group-service
+ * authorizes against, and `updateMemberRole` can move it while `createdBy`
+ * stays as first written. Several owners resolve to the lowest email so that a
+ * re-run bills the same person twice rather than two people once.
+ */
+function groupOwner(group, warnings) {
+    const owners = (group.members ?? [])
+        .filter(m => m.role === 'owner')
+        .map(m => normalizeEmail(m.email))
+        .filter((e) => Boolean(e))
+        .sort();
+    if (owners.length === 1)
+        return owners[0];
+    if (owners.length === 0) {
+        const fallback = normalizeEmail(group.createdBy);
+        warnings.push(`group ${group._id} ("${group.name}") has no member with role 'owner'; billing to createdBy=${fallback ?? 'MISSING'}`);
+        return fallback;
+    }
+    warnings.push(`group ${group._id} ("${group.name}") has ${owners.length} owners (${owners.join(', ')}); billing to ${owners[0]}`);
+    return owners[0];
+}
+async function computeExpected() {
+    const db = mongoose_1.default.connection.db;
+    if (!db)
+        throw new Error('Cannot reconcile usage meters: no active database connection');
+    const warnings = [];
+    // Album.userId / TrackedTicker.userId hold `req.user.id`, which is the
+    // auth-service User._id as a string, while a meter's subjectId is an email.
+    // Nothing personal can be attributed without coming back through this map.
+    const users = await db.collection('users').find({}, { projection: { email: 1 } }).toArray();
+    const userIdToEmail = new Map();
+    for (const user of users) {
+        const email = normalizeEmail(user.email);
+        if (email)
+            userIdToEmail.set(String(user._id), email);
+    }
+    const groups = (await db.collection('groups').find({}).toArray());
+    const groupsById = new Map();
+    for (const group of groups) {
+        groupsById.set(String(group._id), {
+            doc: group,
+            owner: groupOwner(group, warnings),
+            deleted: group.deletedAt !== null && group.deletedAt !== undefined
+        });
+    }
+    const expected = new Map();
+    const bucket = (email) => {
+        let existing = expected.get(email);
+        if (!existing) {
+            existing = { storageBytes: 0, trackedTickers: new Set(), seats: new Set() };
+            expected.set(email, existing);
+        }
+        return existing;
+    };
+    // Every known user gets a bucket, so a user whose real usage is zero can
+    // still correct a stale non-zero counter back down.
+    for (const email of userIdToEmail.values())
+        bucket(email);
+    /**
+     * Group rows bill to the group owner: Family sells a pooled allowance, and
+     * charging the uploader would spend their personal free tier on it instead.
+     */
+    const subjectFor = (row, label) => {
+        const groupId = row.groupId ? String(row.groupId) : undefined;
+        if (groupId) {
+            const group = groupsById.get(groupId);
+            if (group?.owner)
+                return group.owner;
+            // The group is gone but its rows are not. The uploader is the only
+            // identity left, and dropping the bytes would understate real storage.
+            const uploader = userIdToEmail.get(String(row.userId));
+            warnings.push(`${label} ${row._id} references missing group ${groupId}; billing to uploader=${uploader ?? 'UNATTRIBUTED'}`);
+            return uploader;
+        }
+        const owner = userIdToEmail.get(String(row.userId));
+        if (!owner)
+            warnings.push(`${label} ${row._id} has userId=${row.userId}, which matches no user; UNATTRIBUTED`);
+        return owner;
+    };
+    // --- storageBytes ---------------------------------------------------------
+    // Summed from the photos themselves rather than from the denormalized
+    // Album.totalSize: that counter is what a drifting $inc would have corrupted,
+    // so reconciling against it would re-import the drift instead of fixing it.
+    const photoTotals = await db
+        .collection('photos')
+        .aggregate([{ $group: { _id: '$albumId', totalSize: { $sum: '$size' }, photoCount: { $sum: 1 } } }], { allowDiskUse: true })
+        .toArray();
+    const sizeByAlbum = new Map(photoTotals.map(row => [String(row._id), row.totalSize || 0]));
+    const albums = (await db
+        .collection('albums')
+        .find({}, { projection: { userId: 1, groupId: 1, totalSize: 1, name: 1 } })
+        .toArray());
+    const albumIds = new Set(albums.map(a => String(a._id)));
+    for (const album of albums) {
+        const realSize = sizeByAlbum.get(String(album._id)) ?? 0;
+        if ((album.totalSize ?? 0) !== realSize) {
+            warnings.push(`album ${album._id} ("${album.name}") totalSize=${album.totalSize} but photos sum to ${realSize}; ` +
+                `metering the photo sum. The album counter is left alone — it is album-service's to maintain, ` +
+                `and silently rewriting another service's denormalized field would hide the bug rather than surface it.`);
+        }
+        const subject = subjectFor(album, 'album');
+        if (subject)
+            bucket(subject).storageBytes += realSize;
+    }
+    for (const row of photoTotals) {
+        if (!albumIds.has(String(row._id))) {
+            warnings.push(`${row.photoCount} photo(s) totalling ${row.totalSize} B reference missing album ${row._id}; UNATTRIBUTED`);
+        }
+    }
+    // --- trackedTickers -------------------------------------------------------
+    // Distinct symbols, not rows: the daily Alpha Vantage spend this limit
+    // recovers is one call per distinct active symbol, however many rows hold it.
+    const tickers = (await db
+        .collection('trackedtickers')
+        .find({ isActive: true }, { projection: { userId: 1, groupId: 1, ticker: 1 } })
+        .toArray());
+    for (const ticker of tickers) {
+        const subject = subjectFor(ticker, 'trackedTicker');
+        if (subject && ticker.ticker)
+            bucket(subject).trackedTickers.add(String(ticker.ticker).toUpperCase());
+    }
+    // --- seats ----------------------------------------------------------------
+    // Distinct people across every live group the subject owns. Soft-deleted
+    // groups are skipped: unlike storage and tickers they cost nothing and grant
+    // nobody access, so charging for them would charge for nothing.
+    for (const { doc, owner, deleted } of groupsById.values()) {
+        if (deleted || !owner)
+            continue;
+        const seats = bucket(owner).seats;
+        for (const member of doc.members ?? []) {
+            const email = normalizeEmail(member.email);
+            if (email)
+                seats.add(email);
+        }
+    }
+    return { expected, warnings, scannedUsers: users.length };
+}
+/**
+ * Recompute every derived meter and, with `apply`, write back the ones that
+ * disagree.
+ *
+ * Idempotent: it computes absolute values and writes only differences, so a
+ * second run in a row is a no-op.
+ */
+async function reconcileUsageMeters(options = {}) {
+    const { apply = false, subject: only } = options;
+    const onlySubject = normalizeEmail(only);
+    const { expected, warnings, scannedUsers } = await computeExpected();
+    const current = await UsageMeter_1.UsageMeter.find({ meter: { $in: exports.RECONCILED_METERS }, period: 'ALL' }).lean();
+    const currentByKey = new Map(current.map(doc => [`${normalizeEmail(doc.subjectId)}::${doc.meter}`, doc]));
+    const subjects = Array.from(expected.keys())
+        .filter(email => !onlySubject || email === onlySubject)
+        .sort();
+    const changes = [];
+    const ops = [];
+    for (const subjectId of subjects) {
+        const counts = expected.get(subjectId);
+        const resolved = {
+            storageBytes: counts.storageBytes,
+            trackedTickers: counts.trackedTickers.size,
+            seats: counts.seats.size
+        };
+        for (const meter of exports.RECONCILED_METERS) {
+            const to = resolved[meter];
+            const existing = currentByKey.get(`${subjectId}::${meter}`);
+            const from = existing ? existing.count : null;
+            if (from === to)
+                continue;
+            // Never create a row just to say zero — absence already reads as zero
+            // everywhere. An *existing* row must still be corrected down to zero, or
+            // a stale count outlives the data it was counting.
+            if (from === null && to === 0)
+                continue;
+            changes.push({ subjectId, meter, from, to });
+            ops.push({
+                updateOne: {
+                    filter: { subjectId, meter, period: (0, UsageMeter_1.currentPeriod)(meter) },
+                    update: {
+                        $set: { count: to, updatedAt: new Date() },
+                        $setOnInsert: { subjectId, meter, period: (0, UsageMeter_1.currentPeriod)(meter), createdAt: new Date() }
+                    },
+                    upsert: true
+                }
+            });
+        }
+    }
+    // Meters for subjects the scan no longer recognizes — a removed user, or a
+    // subjectId written before an ownership change. Reported, never deleted: a
+    // reconciliation that silently drops billing state is worse than the drift.
+    const orphanedMeters = current
+        .filter(doc => !expected.has(normalizeEmail(doc.subjectId) ?? ''))
+        .map(doc => ({ subjectId: doc.subjectId, meter: doc.meter, count: doc.count }));
+    let written = 0;
+    if (apply && ops.length > 0) {
+        const result = await UsageMeter_1.UsageMeter.bulkWrite(ops);
+        written = result.modifiedCount + result.upsertedCount;
+    }
+    const expectedRecord = {};
+    for (const subjectId of subjects) {
+        const counts = expected.get(subjectId);
+        expectedRecord[subjectId] = {
+            storageBytes: counts.storageBytes,
+            trackedTickers: counts.trackedTickers.size,
+            seats: counts.seats.size
+        };
+    }
+    return {
+        applied: apply,
+        scannedUsers,
+        subjects: expected.size,
+        expected: expectedRecord,
+        changes,
+        written,
+        orphanedMeters,
+        warnings
+    };
+}
+/**
+ * Run a reconciliation and log the outcome. The scheduled entry point.
+ *
+ * Never throws: this runs from a cron callback with no caller to catch it, and
+ * an unhandled rejection there takes the process down over a housekeeping job.
+ */
+async function runUsageReconciliation() {
+    const startedAt = Date.now();
+    try {
+        const report = await reconcileUsageMeters({ apply: true });
+        // A correction is drift that already happened — the counter had gone wrong
+        // and users were being metered against a wrong number until this ran.
+        // Logged at `warn` so a persistent leak in consumeQuota/releaseQuota is
+        // visible as a recurring signal rather than buried in an info line.
+        const level = report.changes.length > 0 ? 'warn' : 'info';
+        logger_1.default[level]('entitlement.reconciled', {
+            event: 'entitlement.reconciled',
+            subjects: report.subjects,
+            corrected: report.changes.length,
+            written: report.written,
+            orphaned: report.orphanedMeters.length,
+            warnings: report.warnings.length,
+            durationMs: Date.now() - startedAt,
+            changes: report.changes.slice(0, 20)
+        });
+        for (const warning of report.warnings.slice(0, 20)) {
+            logger_1.default.warn('entitlement.reconcile_warning', { event: 'entitlement.reconcile_warning', detail: warning });
+        }
+        return report;
+    }
+    catch (err) {
+        logger_1.default.error('Usage meter reconciliation failed', {
+            error: err?.message,
+            durationMs: Date.now() - startedAt
+        });
+        return null;
+    }
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/entitlements/reconcile.js.map

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

package/dist/entitlements/types.d.ts

@@ -18,12 +18,4 @@ export interface Entitlements {
      */
     stale?: boolean;
 }
-/**
- * `off` — no metering, no blocking. `observe` — record usage and log what
- * would have been blocked, block nothing. `enforce` — block.
- *
- * Observe is the default because the configured limits start as guesses; two
- * weeks of `entitlement.would_block` volume is what turns them into numbers.
- */
-export type EntitlementsMode = 'off' | 'observe' | 'enforce';
 //# sourceMappingURL=types.d.ts.map

package/dist/entitlements/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entitlements/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entitlements/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}

package/dist/entitlements/usage.d.ts

@@ -7,7 +7,7 @@ export interface QuotaRequest {
     /** How much this request wants. Bytes for `storageBytes`, otherwise a count. */
     amount?: number;
     entitlements: Entitlements;
-    /** Attached to the observe-mode log line so a would-block can be traced to a route. */
+    /** Attached to the rejection log so a 402 can be traced back to a route. */
     route?: string;
 }
 /** Current count for one meter in its live period. */

package/dist/entitlements/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/entitlements/usage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAqC,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,YAAY,CAAC;IAC3B,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sDAAsD;AACtD,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAO9F;AAED,sFAAsF;AACtF,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAYvG;AA2BD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAejE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BnE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,EACf,MAAM,SAAI,EACV,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/entitlements/usage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAqC,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,YAAY,CAAC;IAC3B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sDAAsD;AACtD,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAO9F;AAED,sFAAsF;AACtF,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAYvG;AAiCD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CASjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,EACf,MAAM,SAAI,EACV,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/entitlements/usage.js

@@ -13,7 +13,6 @@ const logger_1 = __importDefault(require("../logging/logger"));
 const HttpError_1 = require("../errors/HttpError");
 const UsageMeter_1 = require("./UsageMeter");
 const definitions_1 = require("./definitions");
-const mode_1 = require("./mode");
 /** Current count for one meter in its live period. */
 async function getUsage(subjectId, meter, now) {
     const doc = await UsageMeter_1.UsageMeter.findOne({
@@ -47,9 +46,15 @@ function quotaError(req, used, limit) {
         upgradeTo: req.entitlements.upgradeTo
     });
 }
-function logWouldBlock(req, used, limit) {
-    logger_1.default.info('entitlement.would_block', {
-        event: 'entitlement.would_block',
+/**
+ * Every rejection is logged, not just thrown. The 402 reaches the user, but
+ * only this line reaches the operator — and the two questions worth asking of a
+ * paywall (which meter fires most, and how often it fires on a *stale* fallback
+ * rather than on real limits) are answerable from nothing else.
+ */
+function logBlocked(req, used, limit) {
+    logger_1.default.info('entitlement.blocked', {
+        event: 'entitlement.blocked',
         meter: req.meter,
         subjectId: req.subjectId,
         amount: req.amount ?? 1,
@@ -69,19 +74,13 @@ function logWouldBlock(req, used, limit) {
  * the underlying data. Use `consumeQuota` where the count is the only record.
  */
 async function checkQuota(req) {
-    const mode = (0, mode_1.getEntitlementsMode)();
-    if (mode === 'off')
-        return;
     const limit = req.entitlements.limits.meters[req.meter] ?? definitions_1.UNLIMITED;
     if (limit === definitions_1.UNLIMITED)
         return;
     const used = await getUsage(req.subjectId, req.meter);
     if ((0, definitions_1.fitsWithin)(limit, used, req.amount ?? 1))
         return;
-    if (mode === 'observe') {
-        logWouldBlock(req, used, limit);
-        return;
-    }
+    logBlocked(req, used, limit);
     throw quotaError(req, used, limit);
 }
 /**
@@ -99,9 +98,6 @@ async function checkQuota(req) {
  * who cannot upload despite being well under their limit.
  */
 async function consumeQuota(req) {
-    const mode = (0, mode_1.getEntitlementsMode)();
-    if (mode === 'off')
-        return;
     const amount = req.amount ?? 1;
     const limit = req.entitlements.limits.meters[req.meter] ?? definitions_1.UNLIMITED;
     const period = (0, UsageMeter_1.currentPeriod)(req.meter);
@@ -110,12 +106,7 @@ async function consumeQuota(req) {
     if (limit === definitions_1.UNLIMITED || usage.count <= limit)
         return;
     const usedBefore = usage.count - amount;
-    if (mode === 'observe') {
-        // Keep the increment: observe mode exists to measure real demand, and a
-        // rolled-back count would under-report exactly the users who matter.
-        logWouldBlock(req, usedBefore, limit);
-        return;
-    }
+    logBlocked(req, usedBefore, limit);
     await releaseQuota(subjectId, req.meter, amount);
     throw quotaError(req, usedBefore, limit);
 }

package/dist/entitlements/usage.js.map

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

package/dist/groups/client.d.ts

@@ -0,0 +1,27 @@
+export interface GroupOwner {
+    groupId: string;
+    ownerEmail: string;
+    memberCount: number;
+    /** Soft-deleted groups still resolve: their photos still occupy storage. */
+    deleted: boolean;
+    /** True when group-service could not be reached and nothing was resolved. */
+    stale?: boolean;
+}
+/**
+ * The group's owner, cached for {@link CACHE_TTL_MS}, or `null` when the group
+ * does not exist or group-service could not answer.
+ *
+ * Nothing negative is cached — neither a missing group nor a failure. A group
+ * that 404s is nearly always a caller passing a bad id, so caching it would
+ * spend memory on garbage, and caching a failure would keep billing the wrong
+ * subject for a minute after the outage ended.
+ */
+export declare function getGroupOwner(groupId: string): Promise<GroupOwner | null>;
+/**
+ * Drop a group's cached owner. Call after anything that moves the `owner` role,
+ * to collapse the window in which usage bills to the previous owner.
+ */
+export declare function invalidateGroupOwner(groupId: string): void;
+/** Empties the whole cache. Test seam, and a lever after a bulk ownership edit. */
+export declare function clearGroupOwnerCache(): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/groups/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/groups/client.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAyGD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAqB/E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C"}

package/dist/groups/client.js

@@ -0,0 +1,153 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGroupOwner = getGroupOwner;
+exports.invalidateGroupOwner = invalidateGroupOwner;
+exports.clearGroupOwnerCache = clearGroupOwnerCache;
+const logger_1 = __importDefault(require("../logging/logger"));
+/**
+ * Who a group's pooled usage bills to, read over the internal-service channel.
+ *
+ * The JWT carries `groups` — the ids a user belongs to — but never says who
+ * owns them, and no service outside group-service has the collection. So a
+ * chokepoint that needs the *quota subject* for a group album or a group ticker
+ * has to ask. See MONETIZATION.md's note on why that subject is the owner and
+ * not the uploader.
+ *
+ * Same 60s TTL as the entitlement client, for a weaker reason: ownership moves
+ * far more rarely than a plan does, so the cache could be much longer, but a
+ * stale owner bills the wrong person and one shared number is one fewer thing
+ * to reason about. The enforcement points are writes, so the traffic is low
+ * either way.
+ */
+const CACHE_TTL_MS = 60_000;
+/** Bounded so a service under enumeration can't grow the cache without limit. */
+const MAX_CACHE_ENTRIES = 5_000;
+const REQUEST_TIMEOUT_MS = 3_000;
+const cache = new Map();
+/**
+ * Concurrent callers for one group share a request — a burst of uploads into
+ * the same shared album is the expected shape of this traffic.
+ */
+const inFlight = new Map();
+function putInCache(groupId, value) {
+    if (cache.size >= MAX_CACHE_ENTRIES) {
+        // Map iterates in insertion order, so the first key is the oldest write.
+        const oldest = cache.keys().next();
+        if (!oldest.done)
+            cache.delete(oldest.value);
+    }
+    cache.set(groupId, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+/**
+ * Prefers the container-network address over the public hostname.
+ *
+ * `GROUP_API_URL` cannot simply be pointed inward: the frontend containers
+ * template that same variable into the `config.json` the *browser* downloads,
+ * so a Docker-internal value there breaks every group call in the UI. One
+ * variable genuinely has two consumers with incompatible needs, so this is the
+ * server-side half of it.
+ *
+ * Falling back to the public URL keeps local dev (where only `GROUP_API_URL` is
+ * set) and any un-migrated deployment working — it just takes the long way
+ * round, out through the proxy and back, carrying the internal token across the
+ * public edge.
+ */
+function internalGroupUrl() {
+    return process.env.GROUP_INTERNAL_URL || process.env.GROUP_API_URL;
+}
+async function fetchGroupOwner(groupId) {
+    const baseUrl = internalGroupUrl();
+    const token = process.env.INTERNAL_SERVICE_TOKEN;
+    const serviceId = process.env.SERVICE_NAME || 'unknown-service';
+    if (!baseUrl || !token) {
+        logger_1.default.error('Group owner lookup not configured', {
+            hasGroupApiUrl: Boolean(baseUrl),
+            hasInternalToken: Boolean(token)
+        });
+        return null;
+    }
+    try {
+        const response = await fetch(`${baseUrl}/internal/groups/${encodeURIComponent(groupId)}/owner`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-internal-token': token,
+                'x-service-id': serviceId
+            },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        });
+        // A 404 is an answer, not an outage: the group is gone. Distinguished from
+        // an unreachable service because the two want opposite handling — one is
+        // permanent and cacheable, the other must be retried on the next request.
+        if (response.status === 404) {
+            logger_1.default.warn('Group owner lookup found no such group', { groupId });
+            return null;
+        }
+        if (!response.ok) {
+            logger_1.default.error('Group owner lookup failed', { groupId, status: response.status });
+            return null;
+        }
+        const body = (await response.json());
+        if (!body.ownerEmail) {
+            logger_1.default.error('Group owner lookup returned no owner', { groupId });
+            return null;
+        }
+        return {
+            groupId: body.groupId ?? groupId,
+            ownerEmail: body.ownerEmail.trim().toLowerCase(),
+            memberCount: body.memberCount ?? 0,
+            deleted: body.deleted === true
+        };
+    }
+    catch (err) {
+        logger_1.default.error('Group owner lookup errored', { groupId, error: err?.message });
+        return null;
+    }
+}
+/**
+ * The group's owner, cached for {@link CACHE_TTL_MS}, or `null` when the group
+ * does not exist or group-service could not answer.
+ *
+ * Nothing negative is cached — neither a missing group nor a failure. A group
+ * that 404s is nearly always a caller passing a bad id, so caching it would
+ * spend memory on garbage, and caching a failure would keep billing the wrong
+ * subject for a minute after the outage ended.
+ */
+async function getGroupOwner(groupId) {
+    const key = String(groupId).trim();
+    if (!key)
+        return null;
+    const cached = cache.get(key);
+    if (cached && cached.expiresAt > Date.now())
+        return cached.value;
+    const pending = inFlight.get(key);
+    if (pending)
+        return pending;
+    const request = fetchGroupOwner(key)
+        .then(value => {
+        if (value)
+            putInCache(key, value);
+        return value;
+    })
+        .finally(() => {
+        inFlight.delete(key);
+    });
+    inFlight.set(key, request);
+    return request;
+}
+/**
+ * Drop a group's cached owner. Call after anything that moves the `owner` role,
+ * to collapse the window in which usage bills to the previous owner.
+ */
+function invalidateGroupOwner(groupId) {
+    cache.delete(String(groupId).trim());
+}
+/** Empties the whole cache. Test seam, and a lever after a bulk ownership edit. */
+function clearGroupOwnerCache() {
+    cache.clear();
+    inFlight.clear();
+}
+//# sourceMappingURL=client.js.map

package/dist/groups/client.js.map

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

package/dist/groups/index.d.ts

@@ -0,0 +1,5 @@
+export { getGroupOwner, invalidateGroupOwner, clearGroupOwnerCache } from './client';
+export type { GroupOwner } from './client';
+export { groupOwnerSubject } from './subject';
+export type { GroupIdResolver } from './subject';
+//# sourceMappingURL=index.d.ts.map