@reprova/sdk 0.4.0 → 0.6.0

package/dist/cjs/mongoSchemaReporter.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoSchemaReporter = void 0;
+const mongoose_js_1 = require("./mongoose.js");
+const httpFetch_js_1 = require("./httpFetch.js");
+// Periodically re-scans a live Mongoose instance's model registry and
+// reports the discovered model->collection map plus every ref: edge found,
+// so the control plane can hand the agent a reference-edge map at
+// plan-build time (MongoDB has no FK catalog for the agent to introspect
+// itself — see mongo_schema.go's handler doc comment). Unlike
+// DistributionDriftReporter (accumulates external .record() deltas since
+// its last flush), this reporter is self-driven: it re-derives the current
+// schema shape itself on each tick and only POSTs when that shape actually
+// changed, since schema shape is near-static and re-sending an unchanged
+// report every tick for the life of a long-running process would be pure
+// waste.
+const WARN_INTERVAL_MS = 60_000;
+const DEFAULT_INTERVAL_MS = 60_000;
+class MongoSchemaReporter {
+    timer = null;
+    lastSentJSON = null;
+    lastWarnAt = 0;
+    endpoint;
+    apiKey;
+    intervalMs;
+    mongooseInstance;
+    constructor(opts) {
+        this.endpoint = opts.endpoint;
+        this.apiKey = opts.apiKey;
+        this.intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.mongooseInstance = opts.mongooseInstance;
+    }
+    start() {
+        void this.tick(); // report the current shape immediately, don't wait a full interval for the first report
+        this.timer = setInterval(() => void this.tick(), this.intervalMs);
+        if (this.timer.unref)
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    // Exposed for tests and for an explicit "report now" call after a
+    // dynamic model registration; start()/the timer call this on their own.
+    async tick() {
+        let discovered;
+        try {
+            discovered = (0, mongoose_js_1.discoverMongooseSchema)(this.mongooseInstance);
+        }
+        catch {
+            return; // never let introspection failure break the host app
+        }
+        if (discovered.models.length === 0 && discovered.edges.length === 0)
+            return;
+        const json = JSON.stringify(discovered);
+        if (json === this.lastSentJSON)
+            return; // schema shape unchanged since last report
+        try {
+            const res = await (0, httpFetch_js_1.httpFetch)(this.endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'X-Reprova-Key': this.apiKey },
+                body: JSON.stringify({ models: discovered.models, edges: discovered.edges }),
+            });
+            if (res.ok) {
+                this.lastSentJSON = json;
+            }
+            else {
+                this.warnOnce(`reprova: mongo schema report returned ${res.status}`);
+            }
+        }
+        catch (err) {
+            this.warnOnce(`reprova: mongo schema report error: ${err.message}`);
+        }
+    }
+    warnOnce(msg) {
+        const now = Date.now();
+        if (now - this.lastWarnAt > WARN_INTERVAL_MS) {
+            this.lastWarnAt = now;
+            console.warn(msg);
+        }
+    }
+}
+exports.MongoSchemaReporter = MongoSchemaReporter;

package/dist/cjs/mongoose.js

@@ -0,0 +1,335 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reprovaMongoosePlugin = reprovaMongoosePlugin;
+exports.instrumentAlreadyCompiledModels = instrumentAlreadyCompiledModels;
+exports.discoverMongooseSchema = discoverMongooseSchema;
+const context_js_1 = require("./context.js");
+const shape_js_1 = require("./shape.js");
+const SELECT_QUERY_OPS = ['find', 'findOne', 'count', 'countDocuments', 'distinct', 'estimatedDocumentCount'];
+const UPDATE_QUERY_OPS = ['updateOne', 'updateMany', 'findOneAndUpdate', 'findOneAndReplace'];
+const DELETE_QUERY_OPS = ['deleteOne', 'deleteMany', 'findOneAndDelete', 'findOneAndRemove', 'remove'];
+// _id(s) from a query/document result, whatever shape it happens to be
+// (array of docs, single doc, null, or a driver-level count/ack object with
+// no docs at all — idsOf simply yields nothing for the last case).
+function idsOf(value) {
+    if (!value)
+        return [];
+    const docs = Array.isArray(value) ? value : [value];
+    const ids = [];
+    for (const d of docs) {
+        const id = d?._id;
+        if (id !== undefined && id !== null)
+            ids.push(String(id));
+    }
+    return ids;
+}
+// updateMany/deleteMany/findOneAndUpdate-family results carry no document
+// ids at all (just {acknowledged, modifiedCount|deletedCount|matchedCount}
+// or a plain number for count()) — this is the bulk-op analog of
+// FootprintQuery.where_shape existing for "no concrete rows, but here's how
+// many and what shape of filter."
+function affectedCountOf(result) {
+    if (typeof result === 'number')
+        return result;
+    const r = result;
+    return r?.modifiedCount ?? r?.deletedCount ?? r?.matchedCount ?? 0;
+}
+// The MongoDB driver connection pool that Mongoose 5.x bundles dispatches a
+// query's response from inside the pooled connection's own socket callback
+// — whose AsyncLocalStorage context is fixed to whatever was ambient when
+// that connection was first used, not the context of whichever query is
+// currently awaiting a result on it. Confirmed empirically: a Mongoose
+// post-hook loses ALS context as soon as a single prior query has run
+// outside a captured request, which every real app does (background jobs,
+// startup queries, connection warmup) — so relying on contextStorage in the
+// post-hook alone silently drops footprints in production, not just in
+// contrived tests. Pre-hooks, by contrast, run synchronously on the
+// caller's own stack before any driver I/O, so they still see the correct
+// context. Capture it there and thread it through to the post-hook via a
+// WeakMap keyed on the query/document instance — Kareem (Mongoose's
+// middleware runner) preserves that same instance as `this` across pre and
+// post for one operation, so the lookup is exact, not a guess.
+const ctxByHost = new WeakMap();
+function captureCtx(host) {
+    const ctx = context_js_1.contextStorage.getStore();
+    if (ctx && host && typeof host === 'object')
+        ctxByHost.set(host, ctx);
+}
+function resolveCtx(host) {
+    return context_js_1.contextStorage.getStore() ?? (host && typeof host === 'object' ? ctxByHost.get(host) : undefined);
+}
+// Find-or-create the (collection, op) entry for this request and fold in
+// whatever this call learned — same merge-by-(table,op) pattern mikroorm.ts
+// uses, extended with a where_shape/count fallback for bulk ops that never
+// expose which specific documents they touched.
+function recordFootprint(ctx, collection, op, pks, affectedCount, whereShape) {
+    if (!ctx || !collection)
+        return;
+    let entry = ctx.footprint.find((f) => f.model === collection && f.op === op);
+    if (!entry) {
+        entry = { model: collection, op, pks: [], count: 0 };
+        ctx.footprint.push(entry);
+    }
+    for (const pk of pks)
+        if (!entry.pks.includes(pk))
+            entry.pks.push(pk);
+    entry.count = entry.pks.length > 0 ? entry.pks.length : Math.max(entry.count, affectedCount);
+    if (whereShape && !entry.where_shape)
+        entry.where_shape = whereShape;
+}
+function recordFromQuery(query, op, result) {
+    const ctx = resolveCtx(query);
+    const collection = query.model?.collection?.collectionName;
+    let whereShape;
+    try {
+        whereShape = query.getFilter ? (0, shape_js_1.shapeArgs)(query.getFilter()) : undefined;
+    }
+    catch {
+        /* filter introspection best-effort */
+    }
+    recordFootprint(ctx, collection, op, idsOf(result), affectedCountOf(result), whereShape);
+}
+// Whether a document was new AT THE TIME save() was called — snapshotted in
+// pre('save') because by the time post('save') runs, Mongoose has already
+// reset doc.isNew to false regardless of which case this was, so isNew
+// alone can't distinguish insert from update from inside the post hook.
+const wasNewByDoc = new WeakMap();
+// Installs Reprova's footprint hooks on a schema. Call BEFORE compiling any
+// model from it — e.g. `mongoose.plugin(reprovaMongoosePlugin)` once,
+// before any `mongoose.model(...)` calls, so every subsequently-compiled
+// model gets it. Registers plain functions, no decorators/classes needed.
+function reprovaMongoosePlugin(schema) {
+    for (const opName of SELECT_QUERY_OPS) {
+        schema.pre(opName, function () {
+            captureCtx(this);
+        });
+        schema.post(opName, function (result) {
+            try {
+                recordFromQuery(this, 'select', result);
+            }
+            catch {
+                /* never break the host query */
+            }
+        });
+    }
+    for (const opName of UPDATE_QUERY_OPS) {
+        schema.pre(opName, function () {
+            captureCtx(this);
+        });
+        schema.post(opName, function (result) {
+            try {
+                recordFromQuery(this, 'update', result);
+            }
+            catch {
+                /* never break the host query */
+            }
+        });
+    }
+    for (const opName of DELETE_QUERY_OPS) {
+        schema.pre(opName, function () {
+            captureCtx(this);
+        });
+        schema.post(opName, function (result) {
+            try {
+                recordFromQuery(this, 'delete', result);
+            }
+            catch {
+                /* never break the host query */
+            }
+        });
+    }
+    schema.pre('save', function () {
+        try {
+            wasNewByDoc.set(this, !!this.isNew);
+        }
+        catch {
+            /* never break the host save */
+        }
+        captureCtx(this);
+    });
+    schema.post('save', function () {
+        try {
+            const wasNew = wasNewByDoc.get(this) ?? !!this.isNew;
+            wasNewByDoc.delete(this);
+            recordFootprint(resolveCtx(this), this.collection?.collectionName, wasNew ? 'insert' : 'update', idsOf(this), 1);
+        }
+        catch {
+            /* never break the host save */
+        }
+    });
+    // insertMany's `this` is the shared Model, not a per-call instance, so it
+    // can't be used as the WeakMap key (concurrent calls would clobber each
+    // other's captured context) — the `docs` array IS per-call and Kareem
+    // passes the same reference to both hooks, so key on that instead.
+    schema.pre('insertMany', function (docs) {
+        captureCtx(docs);
+    });
+    schema.post('insertMany', function (docs) {
+        try {
+            const ids = idsOf(docs);
+            recordFootprint(resolveCtx(docs), this.collection?.collectionName, 'insert', ids, ids.length);
+        }
+        catch {
+            /* never break the host insertMany */
+        }
+    });
+}
+// --- Retroactive instrumentation for already-compiled models -------------
+//
+// `mongoose.plugin(reprovaMongoosePlugin)` only reaches schemas compiled
+// AFTER the call — confirmed empirically that Mongoose bakes its Kareem
+// hook chain in at `mongoose.model(...)` time, so `schema.pre/post` added
+// to an already-compiled model's schema afterward are simply never
+// consulted again. That ordering requirement forces apps whose own
+// bootstrap already compiles a model before Reprova can be wired in (e.g.
+// a multi-file loader architecture that connects Mongoose, compiles
+// models, THEN sets up the rest) to route `Reprova.init()` to wherever
+// runs earliest, rather than wherever's most natural.
+//
+// This covers that case by wrapping each already-compiled model's own
+// query/document methods directly instead of relying on schema hooks — a
+// plain method override works regardless of compile order. It also
+// sidesteps the pooled-connection ALS-loss problem the schema-hook path
+// needs the WeakMap for (see captureCtx/resolveCtx above): the context is
+// captured synchronously into a closure the instant the wrapped method is
+// called, before any driver I/O, so the `.then()` continuation always has
+// the right value on hand regardless of what AsyncLocalStorage does.
+//
+// Idempotent and safe to call repeatedly (e.g. instrumentMongoose() called
+// more than once) — already-patched models are skipped via `patchedModels`.
+const patchedModels = new WeakSet();
+function wrapQueryReturningMethod(model, methodName, op) {
+    const original = model[methodName];
+    if (typeof original !== 'function')
+        return;
+    model[methodName] = function (...args) {
+        const ctx = context_js_1.contextStorage.getStore();
+        const query = original.apply(this, args);
+        if (!query || typeof query.exec !== 'function')
+            return query;
+        const originalExec = query.exec.bind(query);
+        query.exec = (...execArgs) => originalExec(...execArgs).then((result) => {
+            try {
+                const collection = model.collection?.collectionName;
+                let whereShape;
+                try {
+                    whereShape = query.getFilter ? (0, shape_js_1.shapeArgs)(query.getFilter()) : undefined;
+                }
+                catch {
+                    /* filter introspection best-effort */
+                }
+                recordFootprint(ctx, collection, op, idsOf(result), affectedCountOf(result), whereShape);
+            }
+            catch {
+                /* never break the host query */
+            }
+            return result;
+        });
+        return query;
+    };
+}
+function patchCompiledModel(model) {
+    if (patchedModels.has(model))
+        return;
+    patchedModels.add(model);
+    for (const methodName of SELECT_QUERY_OPS)
+        wrapQueryReturningMethod(model, methodName, 'select');
+    for (const methodName of UPDATE_QUERY_OPS)
+        wrapQueryReturningMethod(model, methodName, 'update');
+    for (const methodName of DELETE_QUERY_OPS)
+        wrapQueryReturningMethod(model, methodName, 'delete');
+    const proto = model.prototype;
+    const originalSave = proto?.save;
+    if (proto && typeof originalSave === 'function') {
+        proto.save = function (...args) {
+            const ctx = context_js_1.contextStorage.getStore();
+            const wasNew = !!this.isNew;
+            return originalSave.apply(this, args).then((result) => {
+                try {
+                    recordFootprint(ctx, this.collection?.collectionName, wasNew ? 'insert' : 'update', idsOf(this), 1);
+                }
+                catch {
+                    /* never break the host save */
+                }
+                return result;
+            });
+        };
+    }
+    const originalInsertMany = model.insertMany;
+    if (typeof originalInsertMany === 'function') {
+        model.insertMany = function (...args) {
+            const ctx = context_js_1.contextStorage.getStore();
+            return originalInsertMany.apply(this, args).then((docs) => {
+                try {
+                    const ids = idsOf(docs);
+                    recordFootprint(ctx, model.collection?.collectionName, 'insert', ids, ids.length);
+                }
+                catch {
+                    /* never break the host insertMany */
+                }
+                return docs;
+            });
+        };
+    }
+}
+// Called once from Reprova.instrumentMongoose() alongside the plugin
+// registration above — covers every model that already exists on this
+// mongoose instance at that moment. Any model compiled AFTER this call is
+// still handled by reprovaMongoosePlugin via mongoose.plugin() as before.
+function instrumentAlreadyCompiledModels(mongooseInstance) {
+    let names = [];
+    try {
+        names = mongooseInstance.modelNames();
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        try {
+            patchCompiledModel(mongooseInstance.model(name));
+        }
+        catch {
+            /* one bad model shouldn't block instrumenting the rest */
+        }
+    }
+}
+function discoverMongooseSchema(mongooseInstance) {
+    const models = [];
+    const edges = [];
+    let names = [];
+    try {
+        names = mongooseInstance.modelNames();
+    }
+    catch {
+        return { models, edges };
+    }
+    for (const name of names) {
+        let model;
+        try {
+            model = mongooseInstance.model(name);
+        }
+        catch {
+            continue;
+        }
+        const collection = model.collection?.collectionName;
+        if (!collection)
+            continue;
+        models.push({ model: name, collection });
+        try {
+            model.schema.eachPath((pathName, schemaType) => {
+                // Direct ref: `{ type: Schema.Types.ObjectId, ref: 'X' }`. Array ref:
+                // `[{ type: Schema.Types.ObjectId, ref: 'X' }]` — Mongoose exposes
+                // the array element's own SchemaType (with its own `.options.ref`)
+                // via `.caster` on the array path's SchemaType.
+                const ref = schemaType?.options?.ref ?? schemaType?.caster?.options?.ref;
+                if (ref) {
+                    edges.push({ from_collection: collection, from_field: pathName, to_model: ref, array: !!schemaType?.caster });
+                }
+            });
+        }
+        catch {
+            /* schema introspection best-effort — one bad path shouldn't drop the whole model */
+        }
+    }
+    return { models, edges };
+}

package/dist/cjs/nest.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNestExceptionFilter = createNestExceptionFilter;
+exports.createNestContextInterceptor = createNestContextInterceptor;
+const stack_js_1 = require("./stack.js");
+// Nest's HttpException contract, detected structurally: anything with
+// getStatus() and getResponse() is treated as an intentional HTTP response
+// (a 404, a validation 400, ...) exactly like Nest's own default filter does.
+function isHttpExceptionLike(e) {
+    return (typeof e === 'object' &&
+        e !== null &&
+        typeof e.getStatus === 'function' &&
+        typeof e.getResponse === 'function');
+}
+function toError(exception) {
+    if (exception instanceof Error)
+        return exception;
+    return new Error(typeof exception === 'string' ? exception : JSON.stringify(exception));
+}
+// Express: res.status(n).json(body). Fastify: reply.status(n).send(body).
+// Both expose status(); the payload method is feature-detected. Guarded —
+// an exception filter must never itself throw.
+function sendJson(res, status, body) {
+    try {
+        const r = res;
+        if (typeof r.status !== 'function')
+            return;
+        const chained = r.status(status);
+        if (typeof chained.json === 'function')
+            chained.json(body);
+        else if (typeof chained.send === 'function')
+            chained.send(body);
+    }
+    catch {
+        /* never break the response path from inside the filter */
+    }
+}
+function createNestExceptionFilter(opts = {}) {
+    // Same activation rule as replayErrorHandler: the CLI sets REPROVA_REPLAY=1
+    // when it boots the app for replay; checked once at construction.
+    const replay = process.env.REPROVA_REPLAY === '1';
+    return {
+        catch(exception, host) {
+            const httpEx = isHttpExceptionLike(exception);
+            let status = 500;
+            if (httpEx) {
+                try {
+                    status = exception.getStatus();
+                }
+                catch {
+                    status = 500;
+                }
+            }
+            const res = host.switchToHttp().getResponse();
+            const err = toError(exception);
+            // Replay contract (only for server-side failures — intentional 4xx
+            // responses replay as themselves): emit the structured error the CLI's
+            // verdict comparison expects, via the SAME parseStack used at capture.
+            if (replay && status >= 500) {
+                sendJson(res, 500, {
+                    error: {
+                        type: err.constructor?.name ?? err.name ?? 'Error',
+                        message: err.message,
+                        stack: (0, stack_js_1.parseStack)(err),
+                    },
+                });
+                return;
+            }
+            // Capture server-side failures with the ORIGINAL exception. 4xx
+            // HttpExceptions are intentional control flow, exactly as Nest treats
+            // them — not captured (a silent 500 from elsewhere still gets the 5xx
+            // hook as backstop).
+            if (status >= 500 && opts.capture) {
+                try {
+                    opts.capture(err);
+                }
+                catch {
+                    /* capture must never break the response */
+                }
+            }
+            // Respond the way Nest's own BaseExceptionFilter would have.
+            if (httpEx) {
+                let body;
+                try {
+                    body = exception.getResponse();
+                }
+                catch {
+                    body = { statusCode: status, message: err.message };
+                }
+                sendJson(res, status, typeof body === 'string' ? { statusCode: status, message: body } : body);
+            }
+            else {
+                sendJson(res, 500, { statusCode: 500, message: 'Internal server error' });
+            }
+        },
+    };
+}
+function wrapSubscriptionWithContext(source, runInContext, ctx) {
+    if (!source || typeof source.subscribe !== 'function')
+        return source;
+    const obs = source;
+    const originalSubscribe = obs.subscribe.bind(obs);
+    obs.subscribe = (...args) => runInContext(ctx, () => originalSubscribe(...args));
+    return obs;
+}
+function createNestContextInterceptor(opts) {
+    return {
+        intercept(context, next) {
+            let req;
+            try {
+                req = context.switchToHttp().getRequest();
+            }
+            catch {
+                req = undefined;
+            }
+            let ctx;
+            try {
+                ctx = opts.resolveContext(req);
+            }
+            catch {
+                ctx = undefined;
+            }
+            if (!ctx)
+                return next.handle();
+            // next.handle() itself must be called exactly once — on failure here
+            // there is nothing safe to retry (a second call could re-invoke the
+            // controller method, double-executing whatever it does), so this is
+            // deliberately not wrapped in a try/catch that falls back to a bare
+            // next.handle(). Constructing the Observable is cheap/lazy (no pipe or
+            // controller work happens yet); the actual context wrap lives inside
+            // wrapSubscriptionWithContext, applied to whatever subscribes to it
+            // later, whenever that turns out to be.
+            return wrapSubscriptionWithContext(next.handle(), opts.runInContext, ctx);
+        },
+    };
+}