@friggframework/core 2.0.0--canary.622.16ee19d.0 → 2.0.0--canary.622.faffe5f.0

package/telemetry/usage-rollup-singleton.js

@@ -1,7 +1,7 @@
 const { createUsageRollupSubscriber } = require('./usage-rollup-subscriber');
 
 /**
- * Process-wide usage-rollup subscriber (ADR-011 P9). Built once per cold start,
+ * Process-wide usage-rollup subscriber. Built once per cold start,
  * subscribed to the telemetry singleton's bus, and reused across invocations.
  * Returns null when usage is disabled (no integration declares Definition.usage)
  * or when the app definition can't be loaded — the handler then skips the flush.

package/telemetry/usage-rollup-subscriber.js

@@ -3,8 +3,8 @@ const { computeUsageWindows } = require('./usage-windows');
 const WEBHOOK_EVENT_NAMES = new Set(['ON_WEBHOOK']);
 
 /**
- * Framework auto-signal metric names → the canonical usage key they feed
- * (ADR-011 §3). Resolvers receive (attributes, context) and may return null to
+ * Framework auto-signal metric names → the canonical usage key they feed.
+ * Resolvers receive (attributes, context) and may return null to
  * decline. Handler invocations map by event: USER_ACTION → user_actions; the
  * DB-connected `ON_WEBHOOK` queue dispatch → webhooks.received (per-integration,
  * and where a durable write is actually possible — the HTTP receipt handler is
@@ -22,7 +22,7 @@ const METRIC_TO_CANONICAL = {
 };
 
 /**
- * The built-in usage-rollup subscriber (ADR-011 Decision 7). Subscribes to the
+ * The built-in usage-rollup subscriber. Subscribes to the
  * telemetry event bus and folds *declared* counters (canonical or custom) into
  * the durable usage store. It buffers within an invocation and writes on
  * `flush()` (no timers — Lambda-safe), or drops the buffer on `discard()` for an

package/telemetry/usage-windows.js

@@ -1,5 +1,5 @@
 /**
- * Compute the rollup window keys a usage event falls into (ADR-011 §4).
+ * Compute the rollup window keys a usage event falls into.
  * Windows are UTC and prefixed by their granularity so the store can filter a
  * series by bucket (`window startsWith 'day:'`).
  *

package/usage/README.md

@@ -46,7 +46,9 @@ class UsageRepositoryInterface {
 - **`series`** aggregates across integration instances (`groupBy(window) + sum`)
   and range-filters on the window key. Requires an `integrationType`.
 
-> **DocumentDB:** the adapter currently inherits the Mongo (Prisma) implementation
-> and is **not yet verified** against a real DocumentDB cluster (every other
-> DocumentDB adapter in this repo needed raw commands). Verify before relying on
-> it in production.
+> **DocumentDB:** the adapter overrides increment/totals/series with raw commands
+> (`$runCommandRaw`: a `$inc` upsert via `documentdb-utils.updateOne`, and a
+> cursor-drained `$aggregate` `$group/$sum`) — matching every other DocumentDB
+> adapter, since Prisma's Mongo engine emits upsert/groupBy shapes DocumentDB
+> rejects and cursor reads truncate at ~101 docs. Command shapes are unit-tested;
+> run an end-to-end check against a real cluster before GA.

package/usage/repositories/usage-repository-documentdb.js

@@ -1,15 +1,199 @@
+const { prisma } = require('../../database/prisma');
+const { updateOne } = require('../../database/documentdb-utils');
 const { UsageRepositoryMongo } = require('./usage-repository-mongo');
 
+const COLLECTION = 'UsageCounter';
+const DRAIN_BATCH_SIZE = 1000;
+const MAX_BATCHES = 100000;
+const VALID_GROUP_BY = new Set(['integrationType', 'metric']);
+const VALID_BUCKETS = new Set(['day', 'hour']);
+
 /**
- * DocumentDB usage store. Inherits the Mongo (Prisma) implementation — the
- * UsageCounter operations are plain upsert/groupBy/findMany with no encrypted
- * fields, so no `$runCommandRaw` variant is needed.
- *
- * TODO(verify): confirm Prisma `upsert` with `{ value: { increment } }` and
- * `groupBy._sum` behave correctly against a real DocumentDB cluster before GA
- * (ADR-011 open question). If DocumentDB rejects the native upsert, add a
- * raw-command override here only.
+ * DocumentDB usage store. Amazon DocumentDB does not accept the command shapes
+ * Prisma's Mongo engine emits for `upsert({ update: { value: { increment } } })`
+ * and `groupBy({ _sum })`, and cursor reads truncate at ~101 docs — so, like
+ * every other DocumentDB adapter in this repo, these operations are issued as
+ * raw commands (`$runCommandRaw`) via the validated documentdb-utils helpers and
+ * a drained aggregate cursor. No timestamps are managed: totals/series filter on
+ * the window KEY (not write-time), so createdAt/updatedAt are unnecessary here.
  */
-class UsageRepositoryDocumentDB extends UsageRepositoryMongo {}
+class UsageRepositoryDocumentDB extends UsageRepositoryMongo {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async increment({ integrationId, integrationType, metric, window, value = 1 }) {
+        // Atomic upsert-increment: $inc creates the field at the increment value
+        // on insert; $setOnInsert stamps the identity on first write. The compound
+        // filter is the unique key, so concurrent writers converge on one row.
+        await updateOne(
+            this.prisma,
+            COLLECTION,
+            { integrationId, integrationType, metric, window },
+            {
+                $inc: { value },
+                $setOnInsert: {
+                    integrationId,
+                    integrationType,
+                    metric,
+                    window,
+                },
+            },
+            { upsert: true }
+        );
+    }
+
+    async totals({
+        metric,
+        groupBy = 'integrationType',
+        since,
+        bucket = 'day',
+    } = {}) {
+        if (!metric) {
+            throw new Error('totals requires a metric (units are per-metric)');
+        }
+        assertGroupBy(groupBy);
+        assertBucket(bucket);
+
+        // Single window granularity (day: OR hour:) — never sum across both.
+        // `since` bounds on the window KEY (mirrors series / the Prisma adapter).
+        const rows = await this._aggregateDrained([
+            {
+                $match: {
+                    metric,
+                    window: windowMatch(bucket, {
+                        gte: since ? windowKey(bucket, since) : undefined,
+                    }),
+                },
+            },
+            { $group: { _id: `$${groupBy}`, value: { $sum: '$value' } } },
+        ]);
+
+        return rows.map((row) => ({
+            [groupBy]: row._id,
+            value: toNumber(row.value),
+        }));
+    }
+
+    async series({ metric, integrationType, from, to, bucket = 'day' } = {}) {
+        assertBucket(bucket);
+        if (!integrationType) {
+            throw new Error('series requires an integrationType');
+        }
+
+        const rows = await this._aggregateDrained([
+            {
+                $match: {
+                    metric,
+                    integrationType,
+                    window: windowMatch(bucket, {
+                        gte: from ? windowKey(bucket, from) : undefined,
+                        lte: to ? windowKey(bucket, to) : undefined,
+                    }),
+                },
+            },
+            { $group: { _id: '$window', value: { $sum: '$value' } } },
+            { $sort: { _id: 1 } },
+        ]);
+
+        return rows.map((row) => ({
+            bucket: row._id,
+            value: toNumber(row.value),
+        }));
+    }
+
+    async _aggregateDrained(pipeline) {
+        const first = await this.prisma.$runCommandRaw({
+            aggregate: COLLECTION,
+            pipeline,
+            cursor: { batchSize: DRAIN_BATCH_SIZE },
+        });
+        return drainCursor(this.prisma, COLLECTION, first);
+    }
+}
+
+/** A `$match` window clause: prefix by granularity, optionally range-bounded. */
+function windowMatch(bucket, { gte, lte } = {}) {
+    const clause = { $regex: `^${bucket}:` };
+    if (gte) clause.$gte = gte;
+    if (lte) clause.$lte = lte;
+    return clause;
+}
+
+/** Window key for a date at a granularity (mirrors telemetry/usage-windows). */
+function windowKey(bucket, date) {
+    const iso = new Date(date).toISOString();
+    return `${bucket}:${bucket === 'hour' ? iso.slice(0, 13) : iso.slice(0, 10)}`;
+}
+
+/**
+ * Coerce an aggregate `$sum` result to a JS Number. Prisma $runCommandRaw returns
+ * extended JSON, so a 64-bit sum can arrive as { $numberLong: "..." } (or
+ * $numberInt/$numberDouble); counts never approach 2^53.
+ */
+function toNumber(value) {
+    if (value === null || value === undefined) return 0;
+    if (typeof value === 'number') return value;
+    if (typeof value === 'bigint') return Number(value);
+    if (typeof value === 'object') {
+        const raw =
+            value.$numberLong ?? value.$numberInt ?? value.$numberDouble;
+        if (raw !== undefined) return Number(raw);
+    }
+    return Number(value) || 0;
+}
+
+async function drainCursor(client, collection, firstResult) {
+    const cursor = firstResult?.cursor || {};
+    const docs = [...(cursor.firstBatch || [])];
+    let cursorId = cursor.id;
+    let batches = 0;
+
+    while (isCursorOpen(cursorId) && batches < MAX_BATCHES) {
+        batches += 1;
+        const next = await client.$runCommandRaw({
+            getMore: cursorId,
+            collection,
+            batchSize: DRAIN_BATCH_SIZE,
+        });
+        const nextCursor = next?.cursor || {};
+        const nextBatch = nextCursor.nextBatch || [];
+        docs.push(...nextBatch);
+        cursorId = nextCursor.id;
+        if (nextBatch.length === 0) break;
+    }
+    return docs;
+}
+
+function isCursorOpen(id) {
+    if (id === undefined || id === null) return false;
+    if (typeof id === 'number') return id !== 0;
+    if (typeof id === 'bigint') return id !== 0n;
+    if (typeof id === 'object' && id.$numberLong !== undefined) {
+        return id.$numberLong !== '0';
+    }
+    return String(id) !== '0';
+}
+
+function assertGroupBy(groupBy) {
+    if (!VALID_GROUP_BY.has(groupBy)) {
+        throw new Error(
+            `Invalid groupBy "${groupBy}". Allowed: ${[...VALID_GROUP_BY].join(
+                ', '
+            )}`
+        );
+    }
+}
+
+function assertBucket(bucket) {
+    if (!VALID_BUCKETS.has(bucket)) {
+        throw new Error(
+            `Invalid bucket "${bucket}". Allowed: ${[...VALID_BUCKETS].join(
+                ', '
+            )}`
+        );
+    }
+}
 
 module.exports = { UsageRepositoryDocumentDB };

package/usage/repositories/usage-repository-interface.js

@@ -1,5 +1,5 @@
 /**
- * Port for the durable usage-counter store (ADR-011 Usage-Counter Contract §4).
+ * Port for the durable usage-counter store.
  *
  * The store is deliberately isolated (ADR-010 Decision 3): its fact rows carry
  * NO userId and NO foreign key to Integration, so a user-scoped query can never

package/usage/repositories/usage-repository-postgres.js

@@ -2,7 +2,7 @@ const { prisma } = require('../../database/prisma');
 const { UsageRepositoryInterface } = require('./usage-repository-interface');
 
 /**
- * Prisma-backed usage store (ADR-011 §4). This is the canonical implementation;
+ * Prisma-backed usage store. This is the canonical implementation;
  * because Prisma abstracts the underlying database, the Mongo and DocumentDB
  * adapters extend this class unchanged (see their files). All queries touch only
  * the isolated `UsageCounter` model — never user/integration-scoped tables.
@@ -34,17 +34,21 @@ class UsageRepositoryPostgres extends UsageRepositoryInterface {
             update: { value: { increment: value } },
         };
 
-        try {
-            await this.prisma.usageCounter.upsert(upsertArgs);
-        } catch (err) {
-            // Concurrent first-insert race: two workers both INSERT and one
-            // hits the unique constraint. Retry once — the row now exists so
-            // the retry takes the atomic UPDATE (increment) path.
-            if (err && err.code === 'P2002') {
+        // Concurrent first-insert race: two workers both INSERT and one hits the
+        // unique constraint (P2002). After the winner's insert the row exists, so
+        // a retry takes the atomic UPDATE (increment) path. Bounded so a
+        // pathological repeated race can't throw unexpectedly out of the public
+        // `recordUsageCounter` write; non-conflict errors surface immediately.
+        for (let attempt = 1; ; attempt++) {
+            try {
                 await this.prisma.usageCounter.upsert(upsertArgs);
                 return;
+            } catch (err) {
+                if (err && err.code === 'P2002' && attempt < MAX_UPSERT_ATTEMPTS) {
+                    continue;
+                }
+                throw err;
             }
-            throw err;
         }
     }
 
@@ -63,8 +67,11 @@ class UsageRepositoryPostgres extends UsageRepositoryInterface {
         // Filter to ONE window granularity — every event is written to both a
         // day: and an hour: row, so summing across granularities would double
         // (or worse) the true count.
+        // Bound `since` on the WINDOW key (mirrors series) — write-time
+        // updatedAt would misplace a late/redelivered increment for an earlier
+        // window, over- or under-counting the time-bounded total.
         const where = { metric, window: { startsWith: `${bucket}:` } };
-        if (since) where.updatedAt = { gte: since };
+        if (since) where.window.gte = windowKey(bucket, since);
 
         const groups = await this.prisma.usageCounter.groupBy({
             by: [groupBy],
@@ -72,9 +79,11 @@ class UsageRepositoryPostgres extends UsageRepositoryInterface {
             _sum: { value: true },
         });
 
+        // value is a BigInt column — coerce the sum to a JSON-safe Number
+        // (JSON.stringify throws on BigInt; counts never approach 2^53).
         return groups.map((group) => ({
             [groupBy]: group[groupBy],
-            value: group._sum?.value ?? 0,
+            value: Number(group._sum?.value ?? 0),
         }));
     }
 
@@ -103,11 +112,12 @@ class UsageRepositoryPostgres extends UsageRepositoryInterface {
 
         return groups.map((group) => ({
             bucket: group.window,
-            value: group._sum?.value ?? 0,
+            value: Number(group._sum?.value ?? 0),
         }));
     }
 }
 
+const MAX_UPSERT_ATTEMPTS = 3;
 const VALID_GROUP_BY = new Set(['integrationType', 'metric']);
 const VALID_BUCKETS = new Set(['day', 'hour']);
 

package/usage/tracked-metrics.js

@@ -2,7 +2,7 @@ const { isCanonicalCounter } = require('../telemetry/canonical-counters');
 
 /**
  * Compute the set of usage-counter keys the rollup should persist, from each
- * integration's `Definition.usage` opt-in (ADR-011 Usage-Counter Contract §2).
+ * integration's `Definition.usage` opt-in.
  * Declaring a canonical key opts into cross-type comparison + the rollup; custom
  * keys are tracked per integration type. Unknown canonical keys are dropped with
  * a warning (lazy validation, matching how Definition is treated elsewhere).