diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7cd33e6a..ebef778f 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -77,6 +77,16 @@ jobs:
--health-timeout=5s
--health-retries=5
+ mongodb:
+ image: mongo:7
+ ports:
+ - 27017:27017
+ options: >-
+ --health-cmd="mongosh --eval 'db.runCommand({ ping: 1 })' || exit 1"
+ --health-interval=10s
+ --health-timeout=5s
+ --health-retries=5
+
env:
REAL_POSTGRES_HOST: localhost
REAL_POSTGRES_PORT: 5432
@@ -116,6 +126,12 @@ jobs:
REAL_CLICKHOUSE_DATABASE: testdb
REAL_CLICKHOUSE_SSL: "false"
+ REAL_MONGODB_HOST: localhost
+ REAL_MONGODB_PORT: 27017
+ REAL_MONGODB_DATABASE: testdb
+ REAL_MONGODB_URI: mongodb://localhost:27017/testdb
+ MONGO_TEST_URI: mongodb://localhost:27017
+
# SQLite — no env vars needed; tests use a temp file
steps:
@@ -154,6 +170,10 @@ jobs:
run: |
node bridge/scripts/seed-clickhouse.cjs
+ - name: Seed MongoDB database
+ run: |
+ node bridge/scripts/seed-mongodb.cjs
+
- name: Run tests
run: |
cd bridge
diff --git a/FEATURES.md b/FEATURES.md
index 888cc793..a36806cb 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -2,7 +2,7 @@
This document provides a comprehensive breakdown of all features and capabilities in RelWave. For installation and setup instructions, see the main [README](README.md).
-**Tech Stack:** Tauri + React 19 + TypeScript + Tailwind CSS + shadcn/ui + React Query + ReactFlow + Recharts + CodeMirror + better-sqlite3 + DuckDB + ClickHouse
+**Tech Stack:** Tauri + React 19 + TypeScript + Tailwind CSS + shadcn/ui + React Query + ReactFlow + Recharts + CodeMirror + better-sqlite3 + DuckDB + ClickHouse + MongoDB
---
@@ -31,6 +31,19 @@ This document provides a comprehensive breakdown of all features and capabilitie
| SQLite | Local file path | ✅ | ✅ | ✅ | ✅ | ✅ |
| DuckDB | Local file path | ✅ | ✅ | ✅ | ✅ | ✅ |
| ClickHouse | Host/port + SSL | ✅ | ✅ | ✅ | ✅ | ✅ |
+| MongoDB | URI / Host/port | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+### MongoDB-Specific Features
+
+- **Document & Analytical Engine** — powered by official `mongodb` Node driver (^6.21.0), verified on MongoDB 6.0 and 7.0
+- **Flexible Connection Topologies** — connect via Standalone (`mongodb://`), Replica Sets (`replicaSet=rs0`), and MongoDB Atlas (`mongodb+srv://`)
+- **Secure Credentials & TLS** — OS-keyring protected authentication (SCRAM-SHA-1, SCRAM-SHA-256) with full TLS/SSL certificate support
+- **MQL Workspace & Visual Aggregations** — interactive aggregation pipeline builder with stage reordering, stage previews, and live query cancellation
+- **Strict BSON Fidelity** — canonical EJSON serialization preserving ObjectId, Date, Decimal128, Long (64-bit int), and Binary data
+- **Schema Intelligence & Visual ERD** — probabilistic schema inference with stratified sampling, field type distribution charts, and automatic relationship detection (ObjectId refs, DBRefs, and embedded arrays)
+- **Streaming Bulk Operations** — chunked mutations, document imports, and streaming exports (JSON, NDJSON, CSV) with automatic 2-hour orphan purge
+- **Safe Schema & Document Migrations** — dry-run previews, mutex lock acquisition (`_relwave_migrations_lock`), and auto-generated rollback scripts
+- **Production Safety Controls** — read-only connection enforcement and safe MQL operator blacklisting (`$where`, `$function`, `$accumulator`, `$out`, `$merge`)
### ClickHouse-Specific Features
diff --git a/README.md b/README.md
index 0646fc6a..b7050898 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
_RelWave brings the power of native Git versioning, visual ER diagrams, and seamless schema management into one blazingly fast desktop application. Built for developers who demand more._
-[](https://github.com/Relwave/relwave-app/releases)
+[](https://github.com/Relwave/relwave-app/releases)
[](LICENSE)
[](https://github.com/Relwave/relwave-app/releases)
[](https://tauri.app/)
@@ -40,7 +40,7 @@ _RelWave brings the power of native Git versioning, visual ER diagrams, and seam
Native Core
- Direct connections via native drivers (PostgreSQL, MySQL, SQLite, DuckDB, ClickHouse). Zero browser overhead. Pure speed.
+ Direct connections via native drivers (PostgreSQL, MySQL, SQLite, DuckDB, ClickHouse, MongoDB). Zero browser overhead. Pure speed.
@@ -84,7 +84,7 @@ RelWave is built using a modern, high-performance tech stack ensuring both a but
- 
+
Powered by Tauri, React 19, and a high-speed Node.js Bridge.
@@ -133,7 +133,7 @@ RelWave uses a **three-layer bridge architecture**. React owns the user experien

-The request path is **React UI -> Tauri command -> Node.js JSON-RPC handler -> service -> database, Git, local storage, monitoring, or LLM provider**. Responses return through the same boundary in reverse. Long-running SQL queries additionally stream `query.result`, `query.progress`, and `query.done` notifications back to the React client. The Node.js bridge contains the database connectors (PostgreSQL, MySQL/MariaDB, SQLite, DuckDB, ClickHouse), Git service, AI services, monitoring services, project stores, credential access, and SSH tunnel handling.
+The request path is **React UI -> Tauri command -> Node.js JSON-RPC handler -> service -> database, Git, local storage, monitoring, or LLM provider**. Responses return through the same boundary in reverse. Long-running SQL queries additionally stream `query.result`, `query.progress`, and `query.done` notifications back to the React client. The Node.js bridge contains the database connectors (PostgreSQL, MySQL/MariaDB, SQLite, DuckDB, ClickHouse, MongoDB), Git service, AI services, monitoring services, project stores, credential access, and SSH tunnel handling.
diff --git a/bridge/__tests__/connectors/mongoAggregation.test.ts b/bridge/__tests__/connectors/mongoAggregation.test.ts
new file mode 100644
index 00000000..6e79573b
--- /dev/null
+++ b/bridge/__tests__/connectors/mongoAggregation.test.ts
@@ -0,0 +1,482 @@
+import { describe, expect, test, jest } from "@jest/globals";
+import { MongoClient } from "mongodb";
+import {
+ assertReadOnlyPipeline,
+ assertSafeExpressions,
+ mongoConnector,
+} from "../../src/connectors/mongo";
+import { MAX_AGG_STAGES, MAX_EXPRESSION_DEPTH } from "../../src/types/mongo";
+import type { EJSONDocument, MongoConfig } from "../../src/types/mongo";
+
+describe("assertReadOnlyPipeline & assertSafeExpressions", () => {
+ describe("Empty and basic valid pipelines", () => {
+ test("accepts empty pipeline [] without error", () => {
+ expect(() => assertReadOnlyPipeline([])).not.toThrow();
+ });
+
+ test("accepts standard read-only stages", () => {
+ const pipeline: EJSONDocument[] = [
+ { $match: { status: "active", age: { $gt: 18 } } },
+ { $project: { name: 1, email: 1, _id: 0 } },
+ { $sort: { createdAt: -1 } },
+ { $limit: 10 },
+ { $skip: 5 },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).not.toThrow();
+ });
+ });
+
+ describe("Rejection of top-level write stages", () => {
+ test("rejects $out with MONGO_WRITE_STAGE_FORBIDDEN", () => {
+ expect(() => assertReadOnlyPipeline([{ $out: "target_coll" }])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_WRITE_STAGE_FORBIDDEN",
+ message: "Stage '$out' is forbidden in read-only aggregation queries",
+ }),
+ );
+ });
+
+ test("rejects $merge with MONGO_WRITE_STAGE_FORBIDDEN", () => {
+ expect(() => assertReadOnlyPipeline([{ $merge: { into: "target_coll" } }])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_WRITE_STAGE_FORBIDDEN",
+ message: "Stage '$merge' is forbidden in read-only aggregation queries",
+ }),
+ );
+ });
+ });
+
+ describe("Rejection of nested write stages in sub-pipelines", () => {
+ test("rejects nested $out in $lookup.pipeline", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $lookup: {
+ from: "orders",
+ pipeline: [{ $out: "target" }],
+ as: "orders",
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_WRITE_STAGE_FORBIDDEN",
+ message: "Stage '$out' is forbidden in read-only aggregation queries",
+ }),
+ );
+ });
+
+ test("rejects nested $merge in $facet sub-pipelines", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $facet: {
+ categorizedByTags: [{ $match: { tags: "sale" } }],
+ categorizedByPrice: [{ $merge: { into: "output_coll" } }],
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_WRITE_STAGE_FORBIDDEN",
+ message: "Stage '$merge' is forbidden in read-only aggregation queries",
+ }),
+ );
+ });
+
+ test("rejects nested $out in $unionWith.pipeline", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $unionWith: {
+ coll: "archive",
+ pipeline: [{ $out: "archive_dump" }],
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_WRITE_STAGE_FORBIDDEN",
+ message: "Stage '$out' is forbidden in read-only aggregation queries",
+ }),
+ );
+ });
+ });
+
+ describe("Rejection of forbidden server-side JavaScript expression operators", () => {
+ test("rejects $function in expressions with MONGO_FORBIDDEN_OPERATOR", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $addFields: {
+ fn: {
+ $function: {
+ body: "function() { return 1; }",
+ args: [],
+ lang: "js",
+ },
+ },
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message:
+ "Operator '$function' is forbidden (server-side JavaScript execution is not permitted)",
+ }),
+ );
+ });
+
+ test("rejects $accumulator in $group stage with MONGO_FORBIDDEN_OPERATOR", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $group: {
+ _id: null,
+ custom: {
+ $accumulator: {
+ init: "function() { return 0; }",
+ accumulate: "function(s) { return s + 1; }",
+ },
+ },
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message:
+ "Operator '$accumulator' is forbidden (server-side JavaScript execution is not permitted)",
+ }),
+ );
+ });
+
+ test("rejects $where in $match stage with MONGO_FORBIDDEN_OPERATOR", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $match: {
+ $where: "this.credits === this.debits",
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message:
+ "Operator '$where' is forbidden (server-side JavaScript execution is not permitted)",
+ }),
+ );
+ });
+
+ test("rejects forbidden operators nested in $lookup sub-pipelines", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $lookup: {
+ from: "details",
+ pipeline: [
+ {
+ $match: {
+ $where: "this.active === true",
+ },
+ },
+ ],
+ as: "matched",
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message:
+ "Operator '$where' is forbidden (server-side JavaScript execution is not permitted)",
+ }),
+ );
+ });
+ });
+
+ describe("Validation of malformed stages and sub-pipelines", () => {
+ test("rejects non-array pipeline with MONGO_INVALID_PIPELINE", () => {
+ expect(() => assertReadOnlyPipeline("not an array" as any)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "Pipeline must be an array",
+ }),
+ );
+ });
+
+ test("rejects non-object stage with MONGO_INVALID_PIPELINE", () => {
+ expect(() => assertReadOnlyPipeline([null as any])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "Each pipeline stage must be a non-null object",
+ }),
+ );
+ expect(() => assertReadOnlyPipeline([[1, 2] as any])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "Each pipeline stage must be a non-null object",
+ }),
+ );
+ });
+
+ test("rejects stage with zero keys or multiple keys", () => {
+ expect(() => assertReadOnlyPipeline([{}])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "Each pipeline stage must have exactly one operator key",
+ }),
+ );
+ expect(() => assertReadOnlyPipeline([{ $match: {}, $sort: {} }])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "Each pipeline stage must have exactly one operator key",
+ }),
+ );
+ });
+
+ test("rejects stage key not starting with $", () => {
+ expect(() => assertReadOnlyPipeline([{ match: {} }])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "Invalid stage name 'match'; must begin with '$'",
+ }),
+ );
+ });
+
+ test("rejects non-array $lookup.pipeline", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $lookup: {
+ from: "orders",
+ pipeline: "invalid_string" as any,
+ as: "orders",
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "$lookup.pipeline must be an array",
+ }),
+ );
+ });
+
+ test("rejects non-array $unionWith.pipeline", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $unionWith: {
+ coll: "archive",
+ pipeline: { invalid: "obj" } as any,
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "$unionWith.pipeline must be an array",
+ }),
+ );
+ });
+
+ test("rejects non-array $facet sub-pipeline", () => {
+ const pipeline: EJSONDocument[] = [
+ {
+ $facet: {
+ invalidBranch: 12345 as any,
+ },
+ },
+ ];
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "$facet pipeline for 'invalidBranch' must be an array",
+ }),
+ );
+ });
+
+ test("rejects malformed $facet stage specifications", () => {
+ for (const badFacet of [[], "str", null]) {
+ expect(() => assertReadOnlyPipeline([{ $facet: badFacet as any }])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "$facet stage specification must be an object",
+ }),
+ );
+ }
+ expect(() => assertReadOnlyPipeline([{ $facet: { f: "not-array" } as any }])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_INVALID_PIPELINE",
+ message: "$facet pipeline for 'f' must be an array",
+ }),
+ );
+ });
+ });
+
+ describe("Nesting depth and resource limits", () => {
+ test("rejects pipeline exceeding MAX_AGG_STAGES (64)", () => {
+ const pipeline = Array.from({ length: 65 }, () => ({ $match: { a: 1 } }));
+ expect(() => assertReadOnlyPipeline(pipeline)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_LIMIT_EXCEEDED",
+ message: `Pipeline exceeds ${MAX_AGG_STAGES} stages`,
+ }),
+ );
+ });
+
+ test("rejects stage exceeding MAX_AGG_STAGE_SIZE_BYTES (16KB)", () => {
+ const largeStage = {
+ $match: {
+ data: "x".repeat(20 * 1024),
+ },
+ };
+ expect(() => assertReadOnlyPipeline([largeStage])).toThrow(
+ expect.objectContaining({
+ code: "MONGO_LIMIT_EXCEEDED",
+ }),
+ );
+ });
+
+ test("rejects expression nesting depth > 15 with MONGO_LIMIT_EXCEEDED", () => {
+ let nested: any = { value: 1 };
+ for (let i = 0; i <= MAX_EXPRESSION_DEPTH + 1; i++) {
+ nested = { child: nested };
+ }
+ expect(() => assertSafeExpressions(nested)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_LIMIT_EXCEEDED",
+ message: `Expression nesting exceeds maximum depth of ${MAX_EXPRESSION_DEPTH}`,
+ }),
+ );
+ });
+
+ test("rejects deeply nested sub-pipelines with MONGO_LIMIT_EXCEEDED", () => {
+ let inner: any = [{ $match: { final: true } }];
+ for (let i = 0; i < 16; i++) {
+ inner = [
+ {
+ $lookup: {
+ from: "coll",
+ pipeline: inner,
+ as: `as_${i}`,
+ },
+ },
+ ];
+ }
+ expect(() => assertReadOnlyPipeline(inner)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_LIMIT_EXCEEDED",
+ }),
+ );
+ });
+ });
+
+ describe("runAggregation bounded cursor iteration and option validation", () => {
+ const dummyConfig: MongoConfig = {
+ uri: "mongodb://localhost:27017/testdb",
+ database: "testdb",
+ };
+
+ test("rejects invalid maxTimeMS (0, negative, non-integer) with MONGO_VALIDATION_ERROR", async () => {
+ for (const badTimeout of [0, -100, 1.5, NaN, "fast" as any]) {
+ await expect(
+ mongoConnector.runAggregation(dummyConfig, {
+ collection: "orders",
+ pipeline: [],
+ options: { maxTimeMS: badTimeout },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "maxTimeMS must be a positive integer",
+ });
+ }
+ });
+
+ test("clamps maxTimeMS between 1 and 60000", async () => {
+ let capturedOptions: any;
+ const mockCursor = {
+ [Symbol.asyncIterator]: async function* () {},
+ close: jest.fn().mockImplementation(() => Promise.resolve()),
+ };
+ const mockCollection = {
+ aggregate: jest.fn().mockImplementation((_stages, options) => {
+ capturedOptions = options;
+ return mockCursor;
+ }),
+ };
+ jest.spyOn(MongoClient.prototype, "db").mockReturnValue({
+ collection: () => mockCollection,
+ } as any);
+
+ await mongoConnector.runAggregation(dummyConfig, {
+ collection: "orders",
+ pipeline: [],
+ options: { maxTimeMS: 999999 },
+ });
+ expect(capturedOptions.maxTimeMS).toBe(60000);
+
+ await mongoConnector.runAggregation(dummyConfig, {
+ collection: "orders",
+ pipeline: [],
+ options: { maxTimeMS: 25000 },
+ });
+ expect(capturedOptions.maxTimeMS).toBe(25000);
+ });
+
+ test("terminates iteration at 1,001 documents, throws MONGO_LIMIT_EXCEEDED, and closes cursor", async () => {
+ let iteratedCount = 0;
+ const mockCursor = {
+ [Symbol.asyncIterator]: async function* () {
+ for (let i = 1; i <= 1050; i++) {
+ iteratedCount++;
+ yield { _id: i, name: `doc_${i}` };
+ }
+ },
+ close: jest.fn().mockImplementation(() => Promise.resolve()),
+ };
+ const mockCollection = {
+ aggregate: jest.fn().mockReturnValue(mockCursor),
+ };
+ jest.spyOn(MongoClient.prototype, "db").mockReturnValue({
+ collection: () => mockCollection,
+ } as any);
+
+ await expect(
+ mongoConnector.runAggregation(dummyConfig, {
+ collection: "orders",
+ pipeline: [{ $match: {} }],
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_LIMIT_EXCEEDED",
+ message: "aggregation returned more than 1000 documents (max 1000); add a $limit stage",
+ });
+
+ expect(iteratedCount).toBe(1001);
+ expect(mockCursor.close).toHaveBeenCalledTimes(1);
+ });
+
+ test("passes validated allowDiskUse and batchSize options to driver cursor", async () => {
+ let capturedOptions: any;
+ const mockCursor = {
+ [Symbol.asyncIterator]: async function* () {
+ yield { _id: 1 };
+ },
+ close: jest.fn().mockImplementation(() => Promise.resolve()),
+ };
+ const mockCollection = {
+ aggregate: jest.fn().mockImplementation((_stages, options) => {
+ capturedOptions = options;
+ return mockCursor;
+ }),
+ };
+ jest.spyOn(MongoClient.prototype, "db").mockReturnValue({
+ collection: () => mockCollection,
+ } as any);
+
+ const res = await mongoConnector.runAggregation(dummyConfig, {
+ collection: "orders",
+ pipeline: [],
+ options: { allowDiskUse: true, batchSize: 50 },
+ });
+
+ expect(capturedOptions.allowDiskUse).toBe(true);
+ expect(capturedOptions.batchSize).toBe(50);
+ expect(res.documents).toHaveLength(1);
+ });
+ });
+});
diff --git a/bridge/__tests__/connectors/mongoBsonRoundTrip.test.ts b/bridge/__tests__/connectors/mongoBsonRoundTrip.test.ts
new file mode 100644
index 00000000..39ed2783
--- /dev/null
+++ b/bridge/__tests__/connectors/mongoBsonRoundTrip.test.ts
@@ -0,0 +1,284 @@
+import { describe, expect, test } from "@jest/globals";
+import { Binary } from "mongodb";
+import {
+ validateAndParseSubtype,
+ validateAndDecodeBase64,
+ mongoEJSONtoBSON,
+ serializeMongoValue,
+} from "../../src/connectors/mongoBson";
+
+describe("mongoBsonRoundTrip", () => {
+ describe("Supported Payload Shapes & Aliases", () => {
+ test("deserializes RelWave wire format { $binary: { base64, subtype } }", () => {
+ const ejson = { $binary: { base64: "aGVsbG8=", subtype: "00" } };
+ const bin = mongoEJSONtoBSON(ejson) as unknown as Binary;
+ expect(bin).toBeInstanceOf(Binary);
+ expect(Buffer.from(bin.value()).toString("utf8")).toBe("hello");
+ expect(bin.sub_type).toBe(0);
+ });
+
+ test("deserializes Canonical EJSON v2 format { $binary: { base64, subType } }", () => {
+ const ejson = { $binary: { base64: "aGVsbG8=", subType: "04" } };
+ const bin = mongoEJSONtoBSON(ejson) as unknown as Binary;
+ expect(bin).toBeInstanceOf(Binary);
+ expect(Buffer.from(bin.value()).toString("utf8")).toBe("hello");
+ expect(bin.sub_type).toBe(4);
+ });
+
+ test("deserializes MongoDB internal format { $binary: { $base64, $type } }", () => {
+ const ejson = { $binary: { $base64: "aGVsbG8=", $type: "05" } };
+ const bin = mongoEJSONtoBSON(ejson) as unknown as Binary;
+ expect(bin).toBeInstanceOf(Binary);
+ expect(Buffer.from(bin.value()).toString("utf8")).toBe("hello");
+ expect(bin.sub_type).toBe(5);
+ });
+
+ test("deserializes compatibility alias format { $binary: { base64, sub_type } }", () => {
+ const ejson = { $binary: { base64: "aGVsbG8=", sub_type: "80" } };
+ const bin = mongoEJSONtoBSON(ejson) as unknown as Binary;
+ expect(bin).toBeInstanceOf(Binary);
+ expect(Buffer.from(bin.value()).toString("utf8")).toBe("hello");
+ expect(bin.sub_type).toBe(128);
+ });
+
+ test("deserializes flat string shorthand { $binary: ' ' } with default subtype 0", () => {
+ const ejson = { $binary: "aGVsbG8=" };
+ const bin = mongoEJSONtoBSON(ejson) as unknown as Binary;
+ expect(bin).toBeInstanceOf(Binary);
+ expect(Buffer.from(bin.value()).toString("utf8")).toBe("hello");
+ expect(bin.sub_type).toBe(0);
+ });
+
+ test("accepts identical redundant aliases ({ base64: '...', $base64: '...' })", () => {
+ const ejson = {
+ $binary: {
+ base64: "aGVsbG8=",
+ $base64: "aGVsbG8=",
+ subtype: "00",
+ subType: "00",
+ $type: "00",
+ },
+ };
+ const bin = mongoEJSONtoBSON(ejson) as unknown as Binary;
+ expect(Buffer.from(bin.value()).toString("utf8")).toBe("hello");
+ expect(bin.sub_type).toBe(0);
+ });
+
+ test("rejects conflicting base64 aliases ({ base64: '...', $base64: '...' }) with TypeError", () => {
+ const ejson = {
+ $binary: {
+ base64: "aGVsbG8=",
+ $base64: "d29ybGQ=",
+ },
+ };
+ expect(() => mongoEJSONtoBSON(ejson)).toThrow(TypeError);
+ expect(() => mongoEJSONtoBSON(ejson)).toThrow(/conflicting base64 payload properties/i);
+ });
+
+ test("rejects conflicting subtype aliases ({ subtype: '00', subType: '04' }) with TypeError", () => {
+ const ejson = {
+ $binary: {
+ base64: "aGVsbG8=",
+ subtype: "00",
+ subType: "04",
+ },
+ };
+ expect(() => mongoEJSONtoBSON(ejson)).toThrow(TypeError);
+ expect(() => mongoEJSONtoBSON(ejson)).toThrow(/conflicting subtype payload properties/i);
+ });
+ });
+
+ describe("Strict Subtype Validation", () => {
+ test("parses valid numeric integer subtypes in range 0-255", () => {
+ expect(validateAndParseSubtype(0)).toBe(0);
+ expect(validateAndParseSubtype(4)).toBe(4);
+ expect(validateAndParseSubtype(128)).toBe(128);
+ expect(validateAndParseSubtype(255)).toBe(255);
+ });
+
+ test("parses valid hexadecimal string subtypes ('00', '04', '80', '0x04', 'a', 'FF')", () => {
+ expect(validateAndParseSubtype("00")).toBe(0);
+ expect(validateAndParseSubtype("04")).toBe(4);
+ expect(validateAndParseSubtype("0x04")).toBe(4);
+ expect(validateAndParseSubtype("0X04")).toBe(4);
+ expect(validateAndParseSubtype("80")).toBe(128);
+ expect(validateAndParseSubtype("a")).toBe(10);
+ expect(validateAndParseSubtype("FF")).toBe(255);
+ expect(validateAndParseSubtype("0xff")).toBe(255);
+ });
+
+ test("preserves full canonical subtype matrix (0x00-0x07, 0x80)", () => {
+ const matrix = [0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x80];
+ for (const st of matrix) {
+ expect(validateAndParseSubtype(st)).toBe(st);
+ expect(validateAndParseSubtype(st.toString(16).padStart(2, "0"))).toBe(st);
+ }
+ });
+
+ test("rejects negative numeric subtype (-1) with TypeError", () => {
+ expect(() => validateAndParseSubtype(-1)).toThrow(TypeError);
+ });
+
+ test("rejects fractional numeric subtype (4.5) with TypeError", () => {
+ expect(() => validateAndParseSubtype(4.5)).toThrow(TypeError);
+ });
+
+ test("rejects overflow numeric subtype (> 255) with TypeError", () => {
+ expect(() => validateAndParseSubtype(256)).toThrow(TypeError);
+ expect(() => validateAndParseSubtype(1000)).toThrow(TypeError);
+ });
+
+ test("rejects NaN, Infinity, -Infinity subtypes with TypeError", () => {
+ expect(() => validateAndParseSubtype(Number.NaN)).toThrow(TypeError);
+ expect(() => validateAndParseSubtype(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+ expect(() => validateAndParseSubtype(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+ });
+
+ test("rejects invalid hexadecimal string subtypes ('zz', '0x100', '-01') with TypeError", () => {
+ expect(() => validateAndParseSubtype("zz")).toThrow(TypeError);
+ expect(() => validateAndParseSubtype("0x100")).toThrow(TypeError);
+ expect(() => validateAndParseSubtype("-01")).toThrow(TypeError);
+ expect(() => validateAndParseSubtype("")).toThrow(TypeError);
+ });
+
+ test("never silently defaults an invalid subtype to zero", () => {
+ expect(() => validateAndParseSubtype(null)).toThrow(TypeError);
+ expect(() => validateAndParseSubtype({})).toThrow(TypeError);
+ expect(() => validateAndParseSubtype([])).toThrow(TypeError);
+ expect(() => validateAndParseSubtype(true)).toThrow(TypeError);
+ });
+ });
+
+ describe("Structural & Canonical Base64 Validation", () => {
+ test("accepts valid standard padded base64 string ('aGVsbG8=')", () => {
+ const buf = validateAndDecodeBase64("aGVsbG8=");
+ expect(buf.toString("utf8")).toBe("hello");
+ });
+
+ test("accepts valid unpadded base64 string ('aGVsbG8')", () => {
+ const buf = validateAndDecodeBase64("aGVsbG8");
+ expect(buf.toString("utf8")).toBe("hello");
+ });
+
+ test("accepts valid empty base64 string ('') and preserves zero-byte Binary", () => {
+ const buf = validateAndDecodeBase64("");
+ expect(buf.length).toBe(0);
+ const bin = mongoEJSONtoBSON({ $binary: { base64: "", subtype: 0 } }) as unknown as Binary;
+ expect(bin.length()).toBe(0);
+ expect(bin.value().length).toBe(0);
+ });
+
+ test("rejects base64 with invalid characters ('hello!world', 'abc$', spaces) with TypeError before decoding", () => {
+ expect(() => validateAndDecodeBase64("hello!world")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("abc$")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("aGVs bG8=")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("aGVsbG8=\n")).toThrow(TypeError);
+ });
+
+ test("rejects base64 with misplaced padding in middle ('a=b=', 'aG=sbG8=') with TypeError before decoding", () => {
+ expect(() => validateAndDecodeBase64("a=b=")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("aG=sbG8=")).toThrow(TypeError);
+ });
+
+ test("rejects base64 with excess padding (3+ equals: 'a===', '====', 'abc===') with TypeError before decoding", () => {
+ expect(() => validateAndDecodeBase64("a===")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("====")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("abc===")).toThrow(TypeError);
+ });
+
+ test("rejects base64 with characters after padding ('aGVsbG8=A', 'aA== ') with TypeError before decoding", () => {
+ expect(() => validateAndDecodeBase64("aGVsbG8=A")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("aA== ")).toThrow(TypeError);
+ });
+
+ test("rejects base64 with invalid padded length ('aG=', 'aGV=') with TypeError before decoding", () => {
+ expect(() => validateAndDecodeBase64("aG=")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("aG==")).toThrow(TypeError);
+ });
+
+ test("rejects truncated base64 (length % 4 === 1: 'a', 'abcde') with TypeError before decoding", () => {
+ expect(() => validateAndDecodeBase64("a")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("abcde")).toThrow(TypeError);
+ });
+
+ test("rejects non-canonical base64 with non-zero pad bits ('aB==') with TypeError via re-encoding validation", () => {
+ expect(() => validateAndDecodeBase64("aB==")).toThrow(TypeError);
+ expect(() => validateAndDecodeBase64("aB==")).toThrow(/non-canonical base64 encoding/i);
+ });
+ });
+
+ describe("Malformed Payload Safety", () => {
+ test("rejects null or non-record binary payload ({ $binary: null }, { $binary: 123 }) with TypeError", () => {
+ expect(() => mongoEJSONtoBSON({ $binary: null as any })).toThrow(TypeError);
+ expect(() => mongoEJSONtoBSON({ $binary: 123 as any })).toThrow(TypeError);
+ });
+
+ test("rejects empty dictionary payload ({ $binary: {} }) with TypeError", () => {
+ expect(() => mongoEJSONtoBSON({ $binary: {} })).toThrow(TypeError);
+ expect(() => mongoEJSONtoBSON({ $binary: {} })).toThrow(/missing base64 data/i);
+ });
+
+ test("never converts malformed input into an empty Binary", () => {
+ expect(() => mongoEJSONtoBSON({ $binary: { base64: "invalid!base64" } })).toThrow(TypeError);
+ expect(() =>
+ mongoEJSONtoBSON({ $binary: { base64: "aGVsbG8=", subtype: "invalid" } }),
+ ).toThrow(TypeError);
+ });
+ });
+
+ describe("Logical Payload Round-Trip Invariants", () => {
+ test("verifies logical payload bytes b.value(), length b.length(), and sub_type in forward direction", () => {
+ const raw = Buffer.from([0x01, 0x02, 0x03, 0x04, 0x05]);
+ const original = new Binary(raw, 2);
+
+ const serialized = serializeMongoValue(original) as {
+ $binary: { base64: string; subtype: string };
+ };
+ expect(serialized.$binary.base64).toBe(raw.toString("base64"));
+ expect(serialized.$binary.subtype).toBe("02");
+
+ const deserialized = mongoEJSONtoBSON(serialized) as unknown as Binary;
+ expect(deserialized.sub_type).toBe(original.sub_type);
+ expect(deserialized.length()).toBe(original.length());
+ expect(Buffer.from(deserialized.value()).equals(Buffer.from(original.value()))).toBe(true);
+ });
+
+ test("verifies logical payload bytes, length, and sub_type in reverse direction", () => {
+ const ejsonDoc = { $binary: { base64: "AQIDBA==", subType: "04" } };
+ const bin = mongoEJSONtoBSON(ejsonDoc) as unknown as Binary;
+
+ expect(bin.sub_type).toBe(4);
+ expect(bin.length()).toBe(4);
+ expect(Buffer.from(bin.value())).toEqual(Buffer.from([1, 2, 3, 4]));
+
+ const reSerialized = serializeMongoValue(bin) as {
+ $binary: { base64: string; subtype: string };
+ };
+ expect(reSerialized.$binary.base64).toBe("AQIDBA==");
+ expect(reSerialized.$binary.subtype).toBe("04");
+ });
+
+ test("losslessly preserves 16-byte UUIDs (subtype 0x04) and MD5 hashes (subtype 0x05) across round-trips", () => {
+ const uuidBytes = Buffer.from(
+ "c3ca6eaa-a103-49fe-a436-0ddb0e4b1eb6".replace(/-/g, ""),
+ "hex",
+ );
+ expect(uuidBytes.length).toBe(16);
+ const uuidBinary = new Binary(uuidBytes, 4);
+
+ const wireUuid = serializeMongoValue(uuidBinary) as any;
+ const deserializedUuid = mongoEJSONtoBSON(wireUuid) as unknown as Binary;
+ expect(deserializedUuid.sub_type).toBe(4);
+ expect(Buffer.from(deserializedUuid.value()).equals(uuidBytes)).toBe(true);
+
+ const md5Bytes = Buffer.from("098f6bcd4621d373cade4e832627b4f6", "hex");
+ expect(md5Bytes.length).toBe(16);
+ const md5Binary = new Binary(md5Bytes, 5);
+
+ const wireMd5 = serializeMongoValue(md5Binary) as any;
+ const deserializedMd5 = mongoEJSONtoBSON(wireMd5) as unknown as Binary;
+ expect(deserializedMd5.sub_type).toBe(5);
+ expect(Buffer.from(deserializedMd5.value()).equals(md5Bytes)).toBe(true);
+ });
+ });
+});
diff --git a/bridge/__tests__/connectors/mongoDocuments.test.ts b/bridge/__tests__/connectors/mongoDocuments.test.ts
new file mode 100644
index 00000000..82fe73c1
--- /dev/null
+++ b/bridge/__tests__/connectors/mongoDocuments.test.ts
@@ -0,0 +1,300 @@
+import { describe, expect, test } from "@jest/globals";
+import { ObjectId, Int32, Long } from "mongodb";
+import {
+ mongoEJSONtoBSON,
+ mongoBSONtoEJSON,
+ serializeMongoUpdateOperand,
+ serializeMongoPipelineStage,
+} from "../../src/connectors/mongoBson";
+import {
+ mongoConnector,
+ mongodbCache,
+ MongoApiError,
+ mapMongoError,
+ withMongoTimeout,
+ assertReadOnlyPipeline,
+} from "../../src/connectors/mongo";
+import type {
+ MongoConfig,
+ MongoFindRequest,
+ MongoSortSpec,
+ EJSONDocument,
+} from "../../src/types/mongo";
+import { QueryExecutor } from "../../src/services/queryExecutor";
+import { DBType } from "../../src/types";
+
+// ---------------------------------------------------------------------------
+// M2 unit tests — driver-free. Covers the EJSON<->BSON converters, the request
+// validation / limit guards (which reject before any driver call), the error
+// mapper, the client-side timeout wrapper, and the collection-scoped cache.
+// (docs/MONGODB_M2_SPEC.md §16.1)
+// ---------------------------------------------------------------------------
+
+describe("mongoBson EJSON round-trip", () => {
+ const cases: unknown[] = [
+ { $oid: "507f1f77bcf86cd799439011" },
+ { $date: "2024-01-01T00:00:00.000Z" },
+ { $numberInt: "123" },
+ { $numberLong: "9007199254740993" },
+ { $numberDecimal: "1.50" },
+ { $binary: { $type: "00", $base64: "aGVsbG8=" } },
+ { $regex: "ab+c", $options: "i" },
+ { $timestamp: { $t: "1", $i: "2" } },
+ {
+ name: "x",
+ tags: ["a", "b"],
+ nested: {
+ n: { $numberInt: "5" },
+ id: { $oid: "507f1f77bcf86cd799439011" },
+ },
+ },
+ "plain string",
+ 42,
+ 3.14,
+ true,
+ false,
+ null,
+ ];
+
+ test("mongoBSONtoEJSON(mongoEJSONtoBSON(x)) is structurally equal to x", () => {
+ for (const c of cases) {
+ expect(mongoBSONtoEJSON(mongoEJSONtoBSON(c as EJSONDocument))).toEqual(c);
+ }
+ });
+
+ test("a bare hex string stays a string; only $oid yields an ObjectId", () => {
+ const hex = "507f1f77bcf86cd799439011";
+ expect(mongoEJSONtoBSON({ v: hex }).v).toBe(hex);
+ expect(mongoEJSONtoBSON({ v: { $oid: hex } }).v).toBeInstanceOf(ObjectId);
+ });
+
+ test("unknown $-wrappers pass through unchanged", () => {
+ const input: EJSONDocument = { $unknownThing: "x" };
+ expect(mongoBSONtoEJSON(mongoEJSONtoBSON(input))).toEqual(input);
+ });
+
+ test("serializeMongoUpdateOperand preserves operator keys and resolves leaf values", () => {
+ const op = serializeMongoUpdateOperand({
+ $set: { name: "a", age: { $numberInt: "5" } },
+ $inc: { count: { $numberLong: "1" } },
+ });
+ expect(Object.keys(op).sort()).toEqual(["$inc", "$set"]);
+ const set = op.$set as Record;
+ const inc = op.$inc as Record;
+ expect(set.name).toBe("a");
+ expect(set.age).toBeInstanceOf(Int32);
+ expect(inc.count).toBeInstanceOf(Long);
+ });
+
+ test("serializeMongoPipelineStage resolves EJSON but does not inject $literal", () => {
+ const stage = serializeMongoPipelineStage({
+ $group: { _id: "$dept", avg: { $avg: "$salary" } },
+ });
+ expect(stage).toEqual({ $group: { _id: "$dept", avg: { $avg: "$salary" } } });
+ });
+});
+
+describe("M2 request validation (rejects before touching the driver)", () => {
+ const dummy: MongoConfig = { uri: "mongodb://localhost:27017/dummy", database: "dummy" };
+
+ test("findDocuments rejects a page beyond the maximum", async () => {
+ await expect(
+ mongoConnector.findDocuments(dummy, { collection: "c", page: 99 }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("findDocuments rejects a non-object filter", async () => {
+ for (const bad of ["str", 123, true, [1, 2]]) {
+ await expect(
+ mongoConnector.findDocuments(dummy, { collection: "c", filter: bad as any }),
+ ).rejects.toMatchObject({
+ code: "MONGO_INVALID_FILTER",
+ message: "filter must be an object",
+ });
+ }
+ });
+
+ test("findDocuments rejects an oversized filter", async () => {
+ const big: EJSONDocument = { big: "x".repeat(9000) };
+ await expect(
+ mongoConnector.findDocuments(dummy, { collection: "c", filter: big }),
+ ).rejects.toMatchObject({ code: "MONGO_LIMIT_EXCEEDED" });
+ });
+
+ test("findDocuments rejects an invalid sort direction", async () => {
+ const req: MongoFindRequest = {
+ collection: "c",
+ sort: { a: "SIDEWAYS" } as unknown as MongoSortSpec,
+ };
+ await expect(mongoConnector.findDocuments(dummy, req)).rejects.toMatchObject({
+ code: "MONGO_INVALID_FILTER",
+ });
+ });
+
+ test("findDocuments rejects a projection mixing inclusion and exclusion", async () => {
+ await expect(
+ mongoConnector.findDocuments(dummy, { collection: "c", projection: { a: 1, b: 0 } }),
+ ).rejects.toMatchObject({ code: "MONGO_INVALID_FILTER" });
+ });
+
+ test("updateDocument rejects an empty filter (bulk-op guard)", async () => {
+ await expect(
+ mongoConnector.updateDocument(dummy, {
+ collection: "c",
+ filter: {},
+ update: { $set: { a: 1 } },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_BULK_OP_FORBIDDEN" });
+ });
+
+ test("updateDocument rejects a non-operator (replacement) document", async () => {
+ await expect(
+ mongoConnector.updateDocument(dummy, {
+ collection: "c",
+ filter: { x: 1 },
+ update: { name: "a" },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_INVALID_UPDATE_OPERAND" });
+ });
+
+ test("deleteDocument rejects an empty filter (bulk-op guard)", async () => {
+ await expect(
+ mongoConnector.deleteDocument(dummy, { collection: "c", filter: {} }),
+ ).rejects.toMatchObject({ code: "MONGO_BULK_OP_FORBIDDEN" });
+ });
+
+ test("runAggregation accepts an empty pipeline without error", () => {
+ expect(() => assertReadOnlyPipeline([])).not.toThrow();
+ });
+
+ test("runAggregation rejects a write stage ($out)", async () => {
+ await expect(
+ mongoConnector.runAggregation(dummy, {
+ collection: "c",
+ pipeline: [{ $out: { coll: "x" } }],
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_WRITE_STAGE_FORBIDDEN" });
+ });
+
+ test("runAggregation rejects a pipeline over the stage cap", async () => {
+ const pipeline = Array.from({ length: 65 }, (): EJSONDocument => ({ $match: {} }));
+ await expect(
+ mongoConnector.runAggregation(dummy, { collection: "c", pipeline }),
+ ).rejects.toMatchObject({ code: "MONGO_LIMIT_EXCEEDED" });
+ });
+
+ test("insertDocument rejects a non-object document", async () => {
+ await expect(
+ mongoConnector.insertDocument(dummy, {
+ collection: "c",
+ document: [1, 2, 3] as unknown as EJSONDocument,
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+});
+
+describe("M2 error mapping", () => {
+ test("maps common MongoServerError shapes to stable codes", () => {
+ expect(mapMongoError({ name: "MongoServerError", codeName: "NamespaceNotFound" }).code).toBe(
+ "MONGO_NS_NOT_FOUND",
+ );
+ expect(mapMongoError({ name: "MongoServerError", code: 11000 }).code).toBe(
+ "MONGO_DUPLICATE_KEY",
+ );
+ expect(mapMongoError({ name: "MongoServerError", codeName: "AuthenticationFailed" }).code).toBe(
+ "MONGO_AUTH_ERROR",
+ );
+ expect(mapMongoError({ name: "MongoServerError", codeName: "MaxTimeMSExpired" }).code).toBe(
+ "MONGO_OPERATION_TIMEOUT",
+ );
+ });
+
+ test("maps a generic error to a connection error and passes through MongoApiError", () => {
+ expect(mapMongoError(new Error("boom")).code).toBe("MONGO_CONNECTION_ERROR");
+ const api = new MongoApiError("MONGO_BULK_OP_FORBIDDEN", "nope");
+ expect(mapMongoError(api)).toBe(api);
+ });
+});
+
+describe("M2 client-side timeout wrapper", () => {
+ test("passes through a fast result", async () => {
+ await expect(withMongoTimeout(1000, async () => 42)).resolves.toBe(42);
+ });
+
+ test("propagates a real error from the operation", async () => {
+ await expect(
+ withMongoTimeout(1000, async () => {
+ throw new Error("boom");
+ }),
+ ).rejects.toThrow("boom");
+ });
+
+ test("rejects with MONGO_OPERATION_TIMEOUT when the operation hangs", async () => {
+ const start = Date.now();
+ await expect(withMongoTimeout(30, () => new Promise(() => {}))).rejects.toMatchObject({
+ code: "MONGO_OPERATION_TIMEOUT",
+ name: "MongoApiError",
+ });
+ expect(Date.now() - start).toBeLessThan(1000);
+ });
+});
+
+describe("M2 collection-scoped cache", () => {
+ const cfg: MongoConfig = { uri: "mongodb://localhost:27017/cachetest", database: "cachetest" };
+
+ test("stores and reads collection stats and document pages, then evicts on clearCollectionCache", () => {
+ mongodbCache.setCollectionStats(cfg, "c", {
+ collection: "c",
+ count: 5,
+ sizeBytes: 100,
+ avgObjSize: 20,
+ });
+ expect(mongodbCache.getCollectionStats(cfg, "c")).toEqual({
+ collection: "c",
+ count: 5,
+ sizeBytes: 100,
+ avgObjSize: 20,
+ });
+ expect(mongodbCache.getCollectionStats(cfg, "other")).toBeNull();
+
+ mongodbCache.setDocumentPage(cfg, "key1", [{ a: 1 }]);
+ expect(mongodbCache.getDocumentPage(cfg, "key1")).toEqual([{ a: 1 }]);
+
+ mongodbCache.clearCollectionCache(cfg, "c");
+ expect(mongodbCache.getCollectionStats(cfg, "c")).toBeNull();
+ expect(mongodbCache.getDocumentPage(cfg, "key1")).toBeNull();
+ });
+
+ test("isolation: a different connection does not see another connection's pages", () => {
+ const other: MongoConfig = { uri: "mongodb://localhost:27017/other", database: "other" };
+ mongodbCache.setDocumentPage(cfg, "shared", [{ a: 1 }]);
+ expect(mongodbCache.getDocumentPage(other, "shared")).toBeNull();
+ expect(mongodbCache.getDocumentPage(cfg, "shared")).toEqual([{ a: 1 }]);
+ });
+});
+
+describe("M2 executor document-op routing (spec §12)", () => {
+ const executor = new QueryExecutor();
+ const cfg: MongoConfig = { uri: "mongodb://localhost:27017/dummy", database: "dummy" };
+
+ test("rejects document operations on a non-MongoDB connection with MONGO_UNSUPPORTED_OPERATION", async () => {
+ await expect(
+ executor.findDocuments(cfg, DBType.POSTGRES, { collection: "c" }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ await expect(
+ executor.insertDocument(cfg, DBType.MYSQL, { collection: "c", document: { a: 1 } }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ await expect(
+ executor.updateDocument(cfg, DBType.POSTGRES, { collection: "c", filter: {}, update: {} }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ await expect(
+ executor.deleteDocument(cfg, DBType.POSTGRES, { collection: "c", filter: {} }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ await expect(
+ executor.runAggregation(cfg, DBType.POSTGRES, {
+ collection: "c",
+ pipeline: [{ $match: {} }],
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ });
+});
diff --git a/bridge/__tests__/connectors/mongoInferSchema.test.ts b/bridge/__tests__/connectors/mongoInferSchema.test.ts
new file mode 100644
index 00000000..839286c4
--- /dev/null
+++ b/bridge/__tests__/connectors/mongoInferSchema.test.ts
@@ -0,0 +1,231 @@
+import { describe, expect, test } from "@jest/globals";
+import { ObjectId, Int32, Long, Decimal128, Binary, Timestamp } from "mongodb";
+import { bsonTypeOf, bsonNumericKind } from "../../src/connectors/mongoBson";
+import {
+ FieldAccumulator,
+ clampInferSampleSize,
+ clampInferMaxDepth,
+ mongodbCache,
+} from "../../src/connectors/mongo";
+import { QueryExecutor } from "../../src/services/queryExecutor";
+import { DBType } from "../../src/types";
+import type { MongoConfig } from "../../src/types/mongo";
+
+describe("M3 pure BSON type inference (bsonTypeOf / bsonNumericKind)", () => {
+ test("bsonTypeOf detects primitives, BSON types, and composites correctly", () => {
+ expect(bsonTypeOf(null)).toBe("null");
+ expect(bsonTypeOf(undefined)).toBe("undefined");
+ expect(bsonTypeOf("test")).toBe("string");
+ expect(bsonTypeOf(true)).toBe("bool");
+ expect(bsonTypeOf(false)).toBe("bool");
+ expect(bsonTypeOf(42)).toBe("number");
+ expect(bsonTypeOf(3.14)).toBe("number");
+ expect(bsonTypeOf(new Int32(100))).toBe("number");
+ expect(bsonTypeOf(new Long(9007199254740993n))).toBe("long");
+ expect(bsonTypeOf(new Decimal128("12.34"))).toBe("decimal");
+ expect(bsonTypeOf(new Timestamp({ t: 1, i: 2 }))).toBe("timestamp");
+ expect(bsonTypeOf(new Binary(Buffer.from("abc")))).toBe("binary");
+ expect(bsonTypeOf(Buffer.from("abc"))).toBe("binary");
+ expect(bsonTypeOf(new Uint8Array([1, 2, 3]))).toBe("binary");
+ expect(bsonTypeOf(new Date("2026-01-01T00:00:00.000Z"))).toBe("date");
+ expect(bsonTypeOf(new ObjectId("507f1f77bcf86cd799439011"))).toBe("objectId");
+ expect(bsonTypeOf([1, 2, 3])).toBe("array");
+ expect(bsonTypeOf({ a: 1, b: "hello" })).toBe("object");
+ expect(bsonTypeOf({ _bsontype: "UnknownSubtype" })).toBe("object");
+ });
+
+ test("bsonNumericKind identifies int and double accurately", () => {
+ expect(bsonNumericKind(new Int32(5))).toBe("int");
+ expect(bsonNumericKind(42)).toBe("int");
+ expect(bsonNumericKind(3.14)).toBe("double");
+ expect(bsonNumericKind({ _bsontype: "Double", valueOf: () => 5.5 })).toBe("double");
+ expect(bsonNumericKind("42")).toBeUndefined();
+ expect(bsonNumericKind(null)).toBeUndefined();
+ expect(bsonNumericKind(undefined)).toBeUndefined();
+ expect(bsonNumericKind(new Long(100n))).toBeUndefined();
+ });
+});
+
+describe("M3 clamping helpers", () => {
+ test("clampInferSampleSize clamps to [1, 1000] and defaults to 100", () => {
+ expect(clampInferSampleSize(undefined)).toBe(100);
+ expect(clampInferSampleSize(NaN)).toBe(100);
+ expect(clampInferSampleSize(0)).toBe(1);
+ expect(clampInferSampleSize(-10)).toBe(1);
+ expect(clampInferSampleSize(50)).toBe(50);
+ expect(clampInferSampleSize(2000)).toBe(1000);
+ });
+
+ test("clampInferMaxDepth clamps to [1, 16] and defaults to 8", () => {
+ expect(clampInferMaxDepth(undefined)).toBe(8);
+ expect(clampInferMaxDepth(NaN)).toBe(8);
+ expect(clampInferMaxDepth(0)).toBe(1);
+ expect(clampInferMaxDepth(-5)).toBe(1);
+ expect(clampInferMaxDepth(4)).toBe(4);
+ expect(clampInferMaxDepth(25)).toBe(16);
+ });
+});
+
+describe("FieldAccumulator (pure schema inference)", () => {
+ test("infers uniform flat documents correctly", () => {
+ const acc = new FieldAccumulator(2, 8);
+ acc.ingest({ _id: new ObjectId(), name: "Alice", age: 30 });
+ acc.ingest({ _id: new ObjectId(), name: "Bob", age: 25 });
+ const fields = acc.toFields();
+
+ expect(fields).toHaveLength(3);
+ const idField = fields.find((f) => f.path === "_id")!;
+ expect(idField.bsonType).toBe("objectId");
+ expect(idField.presencePct).toBe(100);
+ expect(idField.nullable).toBe(false);
+ expect(idField.optional).toBe(false);
+ expect(idField.depth).toBe(0);
+ expect(idField.typeConflicts).toHaveLength(0);
+
+ const nameField = fields.find((f) => f.path === "name")!;
+ expect(nameField.bsonType).toBe("string");
+ expect(nameField.presencePct).toBe(100);
+
+ const ageField = fields.find((f) => f.path === "age")!;
+ expect(ageField.bsonType).toBe("number");
+ expect(ageField.numericKinds).toEqual(["int"]);
+ });
+
+ test("tracks nested paths, depths, parentPath, and maxChildDepth", () => {
+ const acc = new FieldAccumulator(1, 8);
+ acc.ingest({
+ user: {
+ profile: {
+ bio: "Engineer",
+ },
+ },
+ });
+ const fields = acc.toFields();
+
+ const user = fields.find((f) => f.path === "user")!;
+ expect(user.depth).toBe(0);
+ expect(user.isNested).toBe(true);
+ expect(user.parentPath).toBeUndefined();
+ expect(user.maxChildDepth).toBe(2);
+
+ const profile = fields.find((f) => f.path === "user.profile")!;
+ expect(profile.depth).toBe(1);
+ expect(profile.isNested).toBe(true);
+ expect(profile.parentPath).toBe("user");
+ expect(profile.maxChildDepth).toBe(2);
+
+ const bio = fields.find((f) => f.path === "user.profile.bio")!;
+ expect(bio.depth).toBe(2);
+ expect(bio.isNested).toBe(false);
+ expect(bio.parentPath).toBe("user.profile");
+ expect(bio.bsonType).toBe("string");
+ });
+
+ test("handles arrays and distinct arrayElementTypes without emitting indexed subpaths", () => {
+ const acc = new FieldAccumulator(2, 8);
+ acc.ingest({ tags: ["red", "green"] });
+ acc.ingest({ tags: ["blue", 123] });
+ const fields = acc.toFields();
+
+ expect(fields.some((f) => f.path.startsWith("tags."))).toBe(false);
+
+ const tagsField = fields.find((f) => f.path === "tags")!;
+ expect(tagsField.isArray).toBe(true);
+ expect(tagsField.bsonType).toBe("array");
+ expect(tagsField.arrayElementTypes?.sort()).toEqual(["number", "string"]);
+ });
+
+ test("tracks mixed type conflicts with sorted counts and nullable/optional flags", () => {
+ const acc = new FieldAccumulator(4, 8);
+ acc.ingest({ score: 100 });
+ acc.ingest({ score: "N/A" });
+ acc.ingest({ score: "exempt" });
+ acc.ingest({ score: null });
+
+ const fields = acc.toFields();
+ const score = fields.find((f) => f.path === "score")!;
+
+ expect(score.nullable).toBe(true);
+ expect(score.nullCount).toBe(1);
+ expect(score.count).toBe(4);
+ expect(score.optional).toBe(false);
+ expect(score.presencePct).toBe(100);
+
+ expect(score.bsonType).toBe("string");
+ expect(score.typeConflicts.length).toBeGreaterThan(1);
+ expect(score.typeConflicts[0].bsonType).toBe("string");
+ expect(score.typeConflicts[0].count).toBe(2);
+ });
+
+ test("respects maxDepth and marks objects as truncated", () => {
+ const acc = new FieldAccumulator(1, 1);
+ acc.ingest({
+ level0: {
+ level1: {
+ level2: "deep",
+ },
+ },
+ });
+
+ const fields = acc.toFields();
+ expect(fields.find((f) => f.path === "level0.level1.level2")).toBeUndefined();
+ const l1 = fields.find((f) => f.path === "level0.level1")!;
+ expect(l1.depth).toBe(1);
+ expect(l1.truncated).toBe(true);
+ });
+});
+
+describe("M3 Cache Manager inferred schema integration", () => {
+ const dummyCfg: MongoConfig = {
+ uri: "mongodb://127.0.0.1:27017/test_db",
+ database: "test_db",
+ };
+
+ test("stores, retrieves, and invalidates inferred schema", () => {
+ const schemaPayload: any = {
+ collection: "users",
+ sampleSize: 10,
+ totalDocs: 100,
+ inferredAt: new Date().toISOString(),
+ fieldCount: 1,
+ nestedFieldCount: 0,
+ arrayFieldCount: 0,
+ fields: [],
+ sampleDocuments: [],
+ };
+
+ mongodbCache.setInferredSchema(dummyCfg, "users", 100, 8, schemaPayload);
+ const cached = mongodbCache.getInferredSchema(dummyCfg, "users", 100, 8);
+ expect(cached).toEqual(schemaPayload);
+
+ // Eviction on clearCollectionCache
+ mongodbCache.clearCollectionCache(dummyCfg, "users");
+ expect(mongodbCache.getInferredSchema(dummyCfg, "users", 100, 8)).toBeNull();
+
+ // Re-set and clearForConnection
+ mongodbCache.setInferredSchema(dummyCfg, "users", 100, 8, schemaPayload);
+ mongodbCache.clearForConnection(dummyCfg);
+ expect(mongodbCache.getInferredSchema(dummyCfg, "users", 100, 8)).toBeNull();
+
+ // Re-set and clearAll
+ mongodbCache.setInferredSchema(dummyCfg, "users", 100, 8, schemaPayload);
+ mongodbCache.clearAll();
+ expect(mongodbCache.getInferredSchema(dummyCfg, "users", 100, 8)).toBeNull();
+ });
+});
+
+describe("QueryExecutor M3 MongoDB guards", () => {
+ const executor = new QueryExecutor();
+
+ test("listCollections rejects non-MongoDB dbType", async () => {
+ await expect(executor.listCollections({} as any, DBType.POSTGRES)).rejects.toThrow(
+ "listCollections requires a MongoDB connection",
+ );
+ });
+
+ test("inferCollectionSchema rejects non-MongoDB dbType", async () => {
+ await expect(
+ executor.inferCollectionSchema({} as any, DBType.MYSQL, { collection: "users" }),
+ ).rejects.toThrow("inferCollectionSchema requires a MongoDB connection");
+ });
+});
diff --git a/bridge/__tests__/connectors/mongoMql.test.ts b/bridge/__tests__/connectors/mongoMql.test.ts
new file mode 100644
index 00000000..35759dd6
--- /dev/null
+++ b/bridge/__tests__/connectors/mongoMql.test.ts
@@ -0,0 +1,769 @@
+import { describe, expect, test, beforeEach, jest } from "@jest/globals";
+import { MongoClient } from "mongodb";
+import {
+ assertCollectionName,
+ clampMqlTimeout,
+ executeMql,
+ explainMql,
+ mongoConnector,
+} from "../../src/connectors/mongo";
+import { QueryExecutor } from "../../src/services/queryExecutor";
+import { DBType } from "../../src/types";
+import type {
+ MongoConfig,
+ MongoMqlExecuteRequest,
+ MongoExplainRequest,
+} from "../../src/types/mongo";
+
+describe("Mongo MQL Unit Tests (docs/MONGODB_M5_SPEC.md)", () => {
+ const dummyConfig: MongoConfig = {
+ uri: "mongodb://localhost:27017/testdb",
+ database: "testdb",
+ };
+
+ let mockCursorDocs: any[];
+ let mockCursor: any;
+ let mockCollection: any;
+
+ beforeEach(() => {
+ mockCursorDocs = [];
+ mockCursor = {
+ [Symbol.asyncIterator]: async function* () {
+ for (const doc of mockCursorDocs) {
+ yield doc;
+ }
+ },
+ close: jest.fn().mockImplementation(() => Promise.resolve()),
+ toArray: jest.fn().mockImplementation(() => Promise.resolve(mockCursorDocs)),
+ explain: jest.fn().mockImplementation((verbosity: string) =>
+ Promise.resolve({
+ queryPlanner: {
+ plannerVersion: 1,
+ namespace: "testdb.users",
+ indexFilterSet: false,
+ winningPlan: { stage: "COLLSCAN" },
+ },
+ executionStats:
+ verbosity !== "queryPlanner"
+ ? {
+ executionSuccess: true,
+ nReturned: 5,
+ executionTimeMillis: 2,
+ totalKeysExamined: 0,
+ totalDocsExamined: 5,
+ executionStages: { stage: "COLLSCAN" },
+ }
+ : undefined,
+ serverInfo: {
+ host: "localhost",
+ port: 27017,
+ version: "7.0.0",
+ },
+ }),
+ ),
+ sort: jest.fn().mockReturnThis(),
+ project: jest.fn().mockReturnThis(),
+ skip: jest.fn().mockReturnThis(),
+ limit: jest.fn().mockReturnThis(),
+ };
+
+ mockCollection = {
+ find: jest.fn().mockReturnValue(mockCursor),
+ aggregate: jest.fn().mockReturnValue(mockCursor),
+ countDocuments: jest.fn().mockImplementation(() => Promise.resolve(42)),
+ estimatedDocumentCount: jest.fn().mockImplementation(() => Promise.resolve(100)),
+ distinct: jest.fn().mockImplementation(() => Promise.resolve(["apple", "banana"])),
+ };
+
+ jest.spyOn(MongoClient.prototype, "db").mockReturnValue({
+ collection: () => mockCollection,
+ } as any);
+ });
+
+ describe("assertCollectionName", () => {
+ test("accepts valid collection names including dots, dashes, underscores, and numbers", () => {
+ expect(() => assertCollectionName("users")).not.toThrow();
+ expect(() => assertCollectionName("audit.events")).not.toThrow();
+ expect(() => assertCollectionName("logs.2026.10")).not.toThrow();
+ expect(() => assertCollectionName("2026_events")).not.toThrow();
+ expect(() => assertCollectionName("user-data")).not.toThrow();
+ expect(() => assertCollectionName("collection with spaces")).not.toThrow();
+ expect(() => assertCollectionName("a".repeat(120))).not.toThrow();
+ });
+
+ test("rejects empty or non-string collection names", () => {
+ expect(() => assertCollectionName("")).toThrow(
+ expect.objectContaining({ code: "MONGO_VALIDATION_ERROR" }),
+ );
+ expect(() => assertCollectionName(null)).toThrow(
+ expect.objectContaining({ code: "MONGO_VALIDATION_ERROR" }),
+ );
+ expect(() => assertCollectionName(undefined)).toThrow(
+ expect.objectContaining({ code: "MONGO_VALIDATION_ERROR" }),
+ );
+ expect(() => assertCollectionName(123)).toThrow(
+ expect.objectContaining({ code: "MONGO_VALIDATION_ERROR" }),
+ );
+ });
+
+ test("rejects collection names exceeding 120 bytes", () => {
+ expect(() => assertCollectionName("a".repeat(121))).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "collection name must not exceed 120 bytes",
+ }),
+ );
+ });
+
+ test("rejects collection names with null bytes or dollar signs", () => {
+ expect(() => assertCollectionName("audit\0events")).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "collection name must not contain '$' or null bytes",
+ }),
+ );
+ expect(() => assertCollectionName("my$collection")).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "collection name must not contain '$' or null bytes",
+ }),
+ );
+ });
+
+ test("rejects collection names starting with 'system.'", () => {
+ expect(() => assertCollectionName("system.views")).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "collection name must not start with 'system.'",
+ }),
+ );
+ expect(() => assertCollectionName("system.profile")).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "collection name must not start with 'system.'",
+ }),
+ );
+ });
+ });
+
+ describe("clampMqlTimeout", () => {
+ test("returns default when undefined or null", () => {
+ expect(clampMqlTimeout(undefined, 5000)).toBe(5000);
+ expect(clampMqlTimeout(null as any, 10000)).toBe(10000);
+ });
+
+ test("throws MONGO_VALIDATION_ERROR for non-integers, negative, or NaN", () => {
+ expect(() => clampMqlTimeout(0, 5000)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "maxTimeMS must be a positive integer",
+ }),
+ );
+ expect(() => clampMqlTimeout(-10, 5000)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "maxTimeMS must be a positive integer",
+ }),
+ );
+ expect(() => clampMqlTimeout(NaN, 5000)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "maxTimeMS must be a positive integer",
+ }),
+ );
+ expect(() => clampMqlTimeout(1.5, 5000)).toThrow(
+ expect.objectContaining({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "maxTimeMS must be a positive integer",
+ }),
+ );
+ });
+
+ test("clamps value between 1 and maxMs (default 60000)", () => {
+ expect(clampMqlTimeout(100, 5000)).toBe(100);
+ expect(clampMqlTimeout(50000, 5000)).toBe(50000);
+ expect(clampMqlTimeout(120000, 5000)).toBe(60000);
+ expect(clampMqlTimeout(80000, 5000, 30000)).toBe(30000);
+ });
+ });
+
+ describe("executeMql: Mutating operations guard", () => {
+ const mutatingOps = [
+ "insertOne",
+ "insertMany",
+ "updateOne",
+ "updateMany",
+ "replaceOne",
+ "deleteOne",
+ "deleteMany",
+ "drop",
+ "dropDatabase",
+ "rename",
+ "createIndex",
+ "dropIndex",
+ "bulkWrite",
+ "command",
+ "runCommand",
+ "eval",
+ ];
+
+ test.each(mutatingOps)("rejects mutating operation '%s'", async (op) => {
+ const req = {
+ collection: "users",
+ op: { operation: op, payload: {} },
+ } as any;
+
+ await expect(executeMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN_OPERATION",
+ message: `Operation '${op}' is forbidden in read-only query workspace. Use RelWave document mutation actions.`,
+ });
+ });
+ });
+
+ describe("executeMql: 'find' operation", () => {
+ test("rejects non-object filter with MONGO_INVALID_FILTER", async () => {
+ for (const badFilter of ["string", 123, true, [1, 2]]) {
+ await expect(
+ executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "find",
+ payload: { filter: badFilter as any },
+ },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_INVALID_FILTER",
+ message: "filter must be an object",
+ });
+ }
+ });
+
+ test("validates safe expressions and rejects $where in filter", async () => {
+ const req: MongoMqlExecuteRequest = {
+ collection: "users",
+ op: {
+ operation: "find",
+ payload: {
+ filter: { $where: "this.age > 21" },
+ },
+ },
+ };
+
+ await expect(executeMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message:
+ "Operator '$where' is forbidden (server-side JavaScript execution is not permitted)",
+ });
+ });
+
+ test("rejects negative skip", async () => {
+ const req: MongoMqlExecuteRequest = {
+ collection: "users",
+ op: {
+ operation: "find",
+ payload: {
+ filter: {},
+ skip: -5,
+ },
+ },
+ };
+
+ await expect(executeMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "skip must be a non-negative integer",
+ });
+ });
+
+ test("clamps limit between 1 and MAX_PAGE_SIZE (100) and defaults to 50", async () => {
+ // 1. Omitted limit -> defaults to 50
+ await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "find",
+ payload: { filter: {} },
+ },
+ });
+ expect(mockCollection.find).toHaveBeenCalledWith({}, expect.objectContaining({ limit: 50 }));
+
+ // 2. Limit 200 -> clamped to 100
+ await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "find",
+ payload: { filter: {}, limit: 200 },
+ },
+ });
+ expect(mockCollection.find).toHaveBeenCalledWith({}, expect.objectContaining({ limit: 100 }));
+
+ // 3. Limit 0 or negative -> defaults to 50
+ await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "find",
+ payload: { filter: {}, limit: -10 },
+ },
+ });
+ expect(mockCollection.find).toHaveBeenCalledWith({}, expect.objectContaining({ limit: 50 }));
+ });
+
+ test("executes find and converts results to EJSON", async () => {
+ mockCursor.toArray.mockResolvedValueOnce([{ _id: "123", name: "Alice", age: 30 }]);
+
+ const res = await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "find",
+ payload: {
+ filter: { name: "Alice" },
+ sort: { age: 1 },
+ skip: 10,
+ limit: 25,
+ },
+ },
+ });
+
+ expect(res.operation).toBe("find");
+ expect(res.collection).toBe("users");
+ expect((res as any).totalReturned).toBe(1);
+ expect((res as any).documents).toEqual([{ _id: "123", name: "Alice", age: 30 }]);
+ expect(typeof res.executionTimeMs).toBe("number");
+ });
+ });
+
+ describe("executeMql: 'aggregate' operation", () => {
+ test("rejects $out in pipeline", async () => {
+ const req: MongoMqlExecuteRequest = {
+ collection: "users",
+ op: {
+ operation: "aggregate",
+ payload: {
+ pipeline: [{ $out: "target" }],
+ },
+ },
+ };
+
+ await expect(executeMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_WRITE_STAGE_FORBIDDEN",
+ });
+ });
+
+ test("executes empty pipeline [] successfully", async () => {
+ mockCursorDocs = [{ _id: "doc1" }, { _id: "doc2" }];
+
+ const res = await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "aggregate",
+ payload: {
+ pipeline: [],
+ },
+ },
+ });
+
+ expect(res.operation).toBe("aggregate");
+ expect((res as any).stageCount).toBe(0);
+ expect((res as any).documents).toHaveLength(2);
+ expect(mockCursor.close).toHaveBeenCalledTimes(1);
+ });
+
+ test("terminates iteration at 1,001 documents, throws MONGO_LIMIT_EXCEEDED, and closes cursor", async () => {
+ let yieldedCount = 0;
+ mockCursor[Symbol.asyncIterator] = async function* () {
+ for (let i = 1; i <= 1050; i++) {
+ yieldedCount++;
+ yield { _id: `doc_${i}` };
+ }
+ };
+
+ await expect(
+ executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "aggregate",
+ payload: {
+ pipeline: [{ $match: {} }],
+ },
+ },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_LIMIT_EXCEEDED",
+ message: "aggregation returned more than 1000 documents (max 1000); add a $limit stage",
+ });
+
+ expect(yieldedCount).toBe(1001);
+ expect(mockCursor.close).toHaveBeenCalledTimes(1);
+ });
+
+ test("passes allowDiskUse and batchSize options to aggregate", async () => {
+ mockCursorDocs = [{ _id: 1 }];
+
+ await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "aggregate",
+ payload: {
+ pipeline: [],
+ allowDiskUse: true,
+ batchSize: 100,
+ },
+ },
+ });
+
+ expect(mockCollection.aggregate).toHaveBeenCalledWith(
+ [],
+ expect.objectContaining({
+ allowDiskUse: true,
+ batchSize: 100,
+ }),
+ );
+ });
+ });
+
+ describe("executeMql: 'countDocuments' operation", () => {
+ test("rejects non-object filter with MONGO_INVALID_FILTER", async () => {
+ for (const badFilter of ["string", 123, true, [1, 2]]) {
+ await expect(
+ executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "countDocuments",
+ payload: { filter: badFilter as any },
+ },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_INVALID_FILTER",
+ message: "filter must be an object",
+ });
+ }
+ });
+
+ test("rejects $function in filter", async () => {
+ const req: MongoMqlExecuteRequest = {
+ collection: "users",
+ op: {
+ operation: "countDocuments",
+ payload: {
+ filter: {
+ $function: { body: "function() {}", args: [], lang: "js" },
+ } as any,
+ },
+ },
+ };
+
+ await expect(executeMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ });
+ });
+
+ test("executes count with safe filter", async () => {
+ mockCollection.countDocuments.mockResolvedValueOnce(88);
+
+ const res = await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "countDocuments",
+ payload: {
+ filter: { active: true },
+ },
+ },
+ });
+
+ expect(res.operation).toBe("countDocuments");
+ expect((res as any).count).toBe(88);
+ });
+ });
+
+ describe("executeMql: 'estimatedDocumentCount' operation", () => {
+ test("accepts empty or undefined payload", async () => {
+ mockCollection.estimatedDocumentCount.mockResolvedValue(500);
+
+ const res1 = await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "estimatedDocumentCount",
+ },
+ });
+ expect((res1 as any).count).toBe(500);
+
+ const res2 = await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "estimatedDocumentCount",
+ payload: {},
+ },
+ });
+ expect((res2 as any).count).toBe(500);
+ });
+
+ test("rejects non-empty filter or non-object payload with MONGO_VALIDATION_ERROR", async () => {
+ for (const badPayload of [null, 123, "string", true, [1], { filter: {} }]) {
+ const req: MongoMqlExecuteRequest = {
+ collection: "users",
+ op: {
+ operation: "estimatedDocumentCount",
+ payload: badPayload as any,
+ },
+ };
+
+ await expect(executeMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message:
+ "estimatedDocumentCount does not accept a filter; payload must be empty or undefined. Use countDocuments for filtered counts.",
+ });
+ }
+ });
+
+ test("passes signal and timeout to estimatedDocumentCount", async () => {
+ mockCollection.estimatedDocumentCount.mockResolvedValueOnce(250);
+ await executeMql(dummyConfig, {
+ collection: "users",
+ op: { operation: "estimatedDocumentCount" },
+ options: { maxTimeMS: 5000 },
+ });
+ expect(mockCollection.estimatedDocumentCount).toHaveBeenCalledWith(
+ expect.objectContaining({
+ maxTimeMS: 5000,
+ signal: expect.any(Object),
+ }),
+ );
+ });
+ });
+
+ describe("executeMql: 'distinct' operation", () => {
+ test("rejects non-object filter with MONGO_INVALID_FILTER", async () => {
+ for (const badFilter of ["string", 123, true, [1, 2]]) {
+ await expect(
+ executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "distinct",
+ payload: { field: "category", filter: badFilter as any },
+ },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_INVALID_FILTER",
+ message: "filter must be an object",
+ });
+ }
+ });
+
+ test("passes signal and timeout to distinct", async () => {
+ mockCollection.distinct.mockResolvedValueOnce(["cat1", "cat2"]);
+ await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "distinct",
+ payload: { field: "category" },
+ },
+ options: { maxTimeMS: 4000 },
+ });
+ expect(mockCollection.distinct).toHaveBeenCalledWith(
+ "category",
+ {},
+ expect.objectContaining({
+ maxTimeMS: 4000,
+ signal: expect.any(Object),
+ }),
+ );
+ });
+
+ test("rejects missing or empty field", async () => {
+ await expect(
+ executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "distinct",
+ payload: { field: "" },
+ },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "field must be a non-empty string",
+ });
+
+ await expect(
+ executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "distinct",
+ payload: { field: " " },
+ },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "field must be a non-empty string",
+ });
+ });
+
+ test("caps distinct results at MAX_DISTINCT_VALUES (10000)", async () => {
+ const bigValues = Array.from({ length: 10050 }, (_, i) => `val_${i}`);
+ mockCollection.distinct.mockResolvedValueOnce(bigValues);
+
+ const res = await executeMql(dummyConfig, {
+ collection: "users",
+ op: {
+ operation: "distinct",
+ payload: { field: "category" },
+ },
+ });
+
+ expect(res.operation).toBe("distinct");
+ expect((res as any).values).toHaveLength(10000);
+ expect((res as any).count).toBe(10000);
+ });
+ });
+
+ describe("explainMql", () => {
+ test("rejects mutating target (e.g. insertOne)", async () => {
+ const req: MongoExplainRequest = {
+ collection: "users",
+ target: { operation: "insertOne" } as any,
+ };
+
+ await expect(explainMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN_OPERATION",
+ message: "Explain is only supported for 'find' and 'aggregate' operations",
+ });
+ });
+
+ test("rejects unsafe aggregate target containing $out", async () => {
+ const req: MongoExplainRequest = {
+ collection: "users",
+ target: {
+ operation: "aggregate",
+ pipeline: [{ $out: "dump" }],
+ },
+ };
+
+ await expect(explainMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_WRITE_STAGE_FORBIDDEN",
+ });
+ });
+
+ test("rejects non-object filter for find target with MONGO_INVALID_FILTER", async () => {
+ for (const badFilter of ["string", 123, true, [1, 2]]) {
+ await expect(
+ explainMql(dummyConfig, {
+ collection: "users",
+ target: {
+ operation: "find",
+ filter: badFilter as any,
+ },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_INVALID_FILTER",
+ message: "filter must be an object",
+ });
+ }
+ });
+
+ test("rejects unsafe find target containing $where", async () => {
+ const req: MongoExplainRequest = {
+ collection: "users",
+ target: {
+ operation: "find",
+ filter: { $where: "this.active" },
+ },
+ };
+
+ await expect(explainMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ });
+ });
+
+ test("rejects invalid verbosity", async () => {
+ const req: MongoExplainRequest = {
+ collection: "users",
+ verbosity: "unsupported" as any,
+ target: {
+ operation: "find",
+ filter: {},
+ },
+ };
+
+ await expect(explainMql(dummyConfig, req)).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Invalid explain verbosity 'unsupported'",
+ });
+ });
+
+ test("explains find and aggregate across supported verbosities", async () => {
+ for (const verbosity of ["queryPlanner", "executionStats", "allPlansExecution"] as const) {
+ const res = await explainMql(dummyConfig, {
+ collection: "users",
+ verbosity,
+ target: {
+ operation: "find",
+ filter: { status: "active" },
+ },
+ });
+
+ expect(res.operation).toBe("find");
+ expect(res.collection).toBe("users");
+ expect(res.queryPlanner).toBeDefined();
+ expect(res.rawExplain).toBeDefined();
+ }
+ });
+ });
+
+ describe("QueryExecutor MQL routing", () => {
+ const executor = new QueryExecutor();
+
+ test("rejects executeMql on Postgres with MONGO_UNSUPPORTED_OPERATION", async () => {
+ await expect(
+ executor.executeMql(dummyConfig, DBType.POSTGRES, {
+ collection: "users",
+ op: { operation: "find", payload: { filter: {} } },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_UNSUPPORTED_OPERATION",
+ });
+ });
+
+ test("rejects explainMql on MySQL with MONGO_UNSUPPORTED_OPERATION", async () => {
+ await expect(
+ executor.explainMql(dummyConfig, DBType.MYSQL, {
+ collection: "users",
+ target: { operation: "find", filter: {} },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_UNSUPPORTED_OPERATION",
+ });
+ });
+
+ test("routes executeMql and explainMql on DBType.MONGODB to mongoConnector", async () => {
+ const execSpy = jest.spyOn(mongoConnector, "executeMql").mockResolvedValueOnce({
+ operation: "find",
+ collection: "users",
+ documents: [],
+ totalReturned: 0,
+ executionTimeMs: 1,
+ });
+
+ const explainSpy = jest.spyOn(mongoConnector, "explainMql").mockResolvedValueOnce({
+ collection: "users",
+ operation: "find",
+ queryPlanner: {
+ plannerVersion: 1,
+ namespace: "testdb.users",
+ indexFilterSet: false,
+ winningPlan: {},
+ },
+ rawExplain: {},
+ executionTimeMs: 1,
+ });
+
+ await executor.executeMql(dummyConfig, DBType.MONGODB, {
+ collection: "users",
+ op: { operation: "find", payload: { filter: {} } },
+ });
+ expect(execSpy).toHaveBeenCalled();
+
+ await executor.explainMql(dummyConfig, DBType.MONGODB, {
+ collection: "users",
+ target: { operation: "find", filter: {} },
+ });
+ expect(explainSpy).toHaveBeenCalled();
+ });
+ });
+});
diff --git a/bridge/__tests__/connectors/mongoMutations.test.ts b/bridge/__tests__/connectors/mongoMutations.test.ts
new file mode 100644
index 00000000..f7024cb9
--- /dev/null
+++ b/bridge/__tests__/connectors/mongoMutations.test.ts
@@ -0,0 +1,266 @@
+import { describe, expect, test } from "@jest/globals";
+import {
+ assertNewCollectionName,
+ assertNoOperatorKeys,
+ mongoConnector,
+ mongodbCache,
+ MongoApiError,
+} from "../../src/connectors/mongo";
+import type { MongoConfig, EJSONDocument } from "../../src/types/mongo";
+import { QueryExecutor } from "../../src/services/queryExecutor";
+import { DBType } from "../../src/types";
+
+describe("assertNewCollectionName", () => {
+ test("accepts valid collection names", () => {
+ expect(() => assertNewCollectionName("users")).not.toThrow();
+ expect(() => assertNewCollectionName("user_accounts")).not.toThrow();
+ expect(() => assertNewCollectionName("orders-2026")).not.toThrow();
+ expect(() => assertNewCollectionName("_audit_log")).not.toThrow();
+ expect(() => assertNewCollectionName("A")).not.toThrow();
+ expect(() => assertNewCollectionName("a".repeat(120))).not.toThrow();
+ });
+
+ test("rejects non-string or empty name", () => {
+ expect(() => assertNewCollectionName("")).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName(null)).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName(undefined)).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName(123)).toThrow(MongoApiError);
+ });
+
+ test("rejects names longer than 120 chars", () => {
+ expect(() => assertNewCollectionName("a".repeat(121))).toThrow(MongoApiError);
+ });
+
+ test("rejects names with '$' or null bytes", () => {
+ expect(() => assertNewCollectionName("my$coll")).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName("coll\0name")).toThrow(MongoApiError);
+ });
+
+ test("rejects names starting with 'system.'", () => {
+ expect(() => assertNewCollectionName("system.views")).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName("system.profile")).toThrow(MongoApiError);
+ });
+
+ test("rejects names starting with numbers or containing invalid characters", () => {
+ expect(() => assertNewCollectionName("123users")).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName("-users")).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName("my.collection")).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName("my collection")).toThrow(MongoApiError);
+ expect(() => assertNewCollectionName("coll@test")).toThrow(MongoApiError);
+ });
+});
+
+describe("assertNoOperatorKeys", () => {
+ test("allows documents without top-level operator keys", () => {
+ expect(() => assertNoOperatorKeys({ name: "Alice", age: 30 })).not.toThrow();
+ expect(() => assertNoOperatorKeys({ _id: { $oid: "507f1f77bcf86cd799439011" } })).not.toThrow();
+ expect(() => assertNoOperatorKeys({})).not.toThrow();
+ });
+
+ test("throws MONGO_VALIDATION_ERROR if any top-level key starts with '$'", () => {
+ expect(() => assertNoOperatorKeys({ $set: { name: "Bob" } })).toThrow(
+ "replacement document must not contain top-level operator keys",
+ );
+ expect(() => assertNoOperatorKeys({ name: "Bob", $inc: { count: 1 } })).toThrow(
+ "replacement document must not contain top-level operator keys",
+ );
+ });
+});
+
+describe("M4 replaceDocument validation (rejects before driver)", () => {
+ const dummy: MongoConfig = { uri: "mongodb://localhost:27017/dummy", database: "dummy" };
+
+ test("rejects empty filter", async () => {
+ await expect(
+ mongoConnector.replaceDocument(dummy, {
+ collection: "users",
+ filter: {},
+ replacement: { name: "test" },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_BULK_OP_FORBIDDEN" });
+ });
+
+ test("rejects non-object replacement", async () => {
+ await expect(
+ mongoConnector.replaceDocument(dummy, {
+ collection: "users",
+ filter: { _id: "123" },
+ replacement: [1, 2, 3] as unknown as EJSONDocument,
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("rejects replacement with operator keys", async () => {
+ await expect(
+ mongoConnector.replaceDocument(dummy, {
+ collection: "users",
+ filter: { _id: "123" },
+ replacement: { $set: { a: 1 } },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("rejects changing _id between filter and replacement", async () => {
+ await expect(
+ mongoConnector.replaceDocument(dummy, {
+ collection: "users",
+ filter: { _id: { $oid: "507f1f77bcf86cd799439011" } },
+ replacement: { _id: { $oid: "507f1f77bcf86cd799439022" }, name: "New" },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Cannot change _id of a document",
+ });
+ });
+
+ test("rejects oversized replacement", async () => {
+ const huge = "x".repeat(17 * 1024 * 1024);
+ await expect(
+ mongoConnector.replaceDocument(dummy, {
+ collection: "users",
+ filter: { _id: "123" },
+ replacement: { data: huge },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_LIMIT_EXCEEDED" });
+ });
+});
+
+describe("M4 createCollection validation", () => {
+ const dummy: MongoConfig = { uri: "mongodb://localhost:27017/dummy", database: "dummy" };
+
+ test("rejects invalid collection name", async () => {
+ await expect(
+ mongoConnector.createCollection(dummy, { collection: "system.mycoll" }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+
+ await expect(
+ mongoConnector.createCollection(dummy, { collection: "invalid.name" }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("rejects capped collection without size or size < 4096", async () => {
+ await expect(
+ mongoConnector.createCollection(dummy, {
+ collection: "logs",
+ options: { capped: true } as any,
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+
+ await expect(
+ mongoConnector.createCollection(dummy, {
+ collection: "logs",
+ options: { capped: true, size: 2048 },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+
+ await expect(
+ mongoConnector.createCollection(dummy, {
+ collection: "logs",
+ options: { capped: true, size: 5000.5 },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("rejects capped collection with max <= 0 or non-integer", async () => {
+ await expect(
+ mongoConnector.createCollection(dummy, {
+ collection: "logs",
+ options: { capped: true, size: 8192, max: 0 },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+
+ await expect(
+ mongoConnector.createCollection(dummy, {
+ collection: "logs",
+ options: { capped: true, size: 8192, max: -5 },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+
+ await expect(
+ mongoConnector.createCollection(dummy, {
+ collection: "logs",
+ options: { capped: true, size: 8192, max: 10.5 },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+});
+
+describe("M4 dropCollection validation", () => {
+ const dummy: MongoConfig = { uri: "mongodb://localhost:27017/dummy", database: "dummy" };
+
+ test("rejects dropping system collection", async () => {
+ await expect(
+ mongoConnector.dropCollection(dummy, { collection: "system.views" }),
+ ).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN",
+ message: "Cannot drop system collection",
+ });
+
+ await expect(
+ mongoConnector.dropCollection(dummy, { collection: "system.profile" }),
+ ).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN",
+ message: "Cannot drop system collection",
+ });
+ });
+
+ test("rejects invalid collection name", async () => {
+ await expect(mongoConnector.dropCollection(dummy, { collection: "" })).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ });
+ });
+});
+
+describe("M4 cache invalidation", () => {
+ const cfg: MongoConfig = { uri: "mongodb://localhost:27017/cachedb", database: "cachedb" };
+
+ test("clearCollectionCache and flushConnection invalidate collection metadata and page cache", () => {
+ mongodbCache.setCollectionStats(cfg, "coll1", {
+ collection: "coll1",
+ count: 10,
+ sizeBytes: 200,
+ avgObjSize: 20,
+ });
+ mongodbCache.setDocumentPage(cfg, "p1", [{ doc: 1 }]);
+ mongodbCache.setTableList(cfg, [{ name: "coll1", type: "TABLE", schema: "cachedb" }]);
+
+ expect(mongodbCache.getCollectionStats(cfg, "coll1")).toBeDefined();
+ expect(mongodbCache.getDocumentPage(cfg, "p1")).toBeDefined();
+ expect(mongodbCache.getTableList(cfg)).toBeDefined();
+
+ mongodbCache.clearCollectionCache(cfg, "coll1");
+ expect(mongodbCache.getCollectionStats(cfg, "coll1")).toBeNull();
+ expect(mongodbCache.getDocumentPage(cfg, "p1")).toBeNull();
+ expect(mongodbCache.getTableList(cfg)).toBeDefined();
+
+ mongodbCache.flushConnection(cfg);
+ expect(mongodbCache.getTableList(cfg)).toBeNull();
+ });
+});
+
+describe("M4 QueryExecutor routing", () => {
+ const executor = new QueryExecutor();
+ const cfg: MongoConfig = { uri: "mongodb://localhost:27017/dummy", database: "dummy" };
+
+ test("rejects replaceDocument on non-MongoDB connection", async () => {
+ await expect(
+ executor.replaceDocument(cfg, DBType.POSTGRES, {
+ collection: "c",
+ filter: { a: 1 },
+ replacement: { a: 2 },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ });
+
+ test("rejects createCollection on non-MongoDB connection", async () => {
+ await expect(
+ executor.createCollection(cfg, DBType.POSTGRES, { collection: "c" }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ });
+
+ test("rejects dropCollection on non-MongoDB connection", async () => {
+ await expect(
+ executor.dropCollection(cfg, DBType.POSTGRES, { collection: "c" }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ });
+});
diff --git a/bridge/__tests__/connectors/mongoSecurity.test.ts b/bridge/__tests__/connectors/mongoSecurity.test.ts
new file mode 100644
index 00000000..386879d5
--- /dev/null
+++ b/bridge/__tests__/connectors/mongoSecurity.test.ts
@@ -0,0 +1,520 @@
+import { describe, expect, test, jest } from "@jest/globals";
+import {
+ assertSafeExpressions,
+ assertMongoNotReadOnly,
+ mongoConnector,
+ MongoApiError,
+} from "../../src/connectors/mongo";
+import type { MongoConfig } from "../../src/types/mongo";
+import { MongoBulkEngine, assertNotReadOnly } from "../../src/services/mongoBulkEngine";
+import { MigrationHandlers } from "../../src/handlers/migrationHandlers";
+import { DBType } from "../../src/types";
+
+describe("Mongo Security Test Suite", () => {
+ describe("assertSafeExpressions", () => {
+ test("throws on $where at top level", () => {
+ expect(() => {
+ assertSafeExpressions({ $where: "this.a > 3" });
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message: expect.stringContaining("Operator '$where' is forbidden"),
+ }),
+ );
+ });
+
+ test("throws on $where nested in objects", () => {
+ expect(() => {
+ assertSafeExpressions({
+ query: {
+ nested: {
+ $where: "function() { return true; }",
+ },
+ },
+ });
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message: expect.stringContaining("Operator '$where' is forbidden"),
+ }),
+ );
+ });
+
+ test("throws on $where nested in arrays", () => {
+ expect(() => {
+ assertSafeExpressions({
+ items: [{ field: "valid" }, { $where: "sleep(5000)" }],
+ });
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message: expect.stringContaining("Operator '$where' is forbidden"),
+ }),
+ );
+ });
+
+ test("throws on $function at top level and nested", () => {
+ expect(() => {
+ assertSafeExpressions({
+ $function: {
+ body: "function() { return 1; }",
+ args: [],
+ lang: "js",
+ },
+ });
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message: expect.stringContaining("Operator '$function' is forbidden"),
+ }),
+ );
+
+ expect(() => {
+ assertSafeExpressions({
+ $match: {
+ val: {
+ $function: {
+ body: "function(v) { return v > 10; }",
+ args: ["$val"],
+ lang: "js",
+ },
+ },
+ },
+ });
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message: expect.stringContaining("Operator '$function' is forbidden"),
+ }),
+ );
+ });
+
+ test("throws on $accumulator at top level and nested", () => {
+ expect(() => {
+ assertSafeExpressions({
+ $accumulator: {
+ init: "function() { return 0; }",
+ accumulate: "function(state, val) { return state + val; }",
+ accumulateArgs: ["$val"],
+ merge: "function(s1, s2) { return s1 + s2; }",
+ lang: "js",
+ },
+ });
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message: expect.stringContaining("Operator '$accumulator' is forbidden"),
+ }),
+ );
+
+ expect(() => {
+ assertSafeExpressions({
+ $group: {
+ _id: "$dept",
+ total: {
+ $accumulator: {
+ init: "function() { return 0; }",
+ accumulate: "function(s, v) { return s + v; }",
+ accumulateArgs: ["$salary"],
+ merge: "function(s1, s2) { return s1 + s2; }",
+ lang: "js",
+ },
+ },
+ },
+ });
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ message: expect.stringContaining("Operator '$accumulator' is forbidden"),
+ }),
+ );
+ });
+
+ test("permits standard operators and normal fields", () => {
+ expect(() => {
+ assertSafeExpressions({
+ $set: { status: "active", count: 10 },
+ $inc: { score: 5 },
+ $match: { age: { $gte: 18, $lte: 65 } },
+ $group: { _id: "$dept", total: { $sum: "$salary" } },
+ });
+ }).not.toThrow();
+
+ expect(() => {
+ assertSafeExpressions({
+ name: "Alice",
+ email: "alice@example.com",
+ profile: {
+ bio: "Engineer",
+ tags: ["typescript", "mongodb"],
+ },
+ scores: [95, 87, 92],
+ isActive: true,
+ count: null,
+ });
+ }).not.toThrow();
+ });
+
+ test("handles deep nesting (>20 levels without stack overflow)", () => {
+ let nested: any = { leaf: "value" };
+ for (let i = 0; i < 30; i++) {
+ nested = { child: nested };
+ }
+
+ // Must terminate gracefully with MONGO_LIMIT_EXCEEDED instead of RangeError (Call stack exceeded)
+ expect(() => {
+ assertSafeExpressions(nested);
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_LIMIT_EXCEEDED",
+ message: expect.stringContaining("Expression nesting exceeds maximum depth"),
+ }),
+ );
+
+ // Verify with nested arrays
+ let nestedArr: any = ["leaf"];
+ for (let i = 0; i < 30; i++) {
+ nestedArr = [nestedArr];
+ }
+
+ expect(() => {
+ assertSafeExpressions(nestedArr);
+ }).toThrow(
+ expect.objectContaining({
+ code: "MONGO_LIMIT_EXCEEDED",
+ }),
+ );
+ });
+ });
+
+ describe("assertMongoNotReadOnly", () => {
+ test("throws when conn.readonly: true", () => {
+ const conn: MongoConfig = { uri: "mongodb://localhost:27017/test", readonly: true };
+ expect(() => {
+ assertMongoNotReadOnly(conn, "insertDocument");
+ }).toThrow("Database is configured as read-only. 'insertDocument' is prohibited.");
+
+ try {
+ assertMongoNotReadOnly(conn, "testOp");
+ } catch (err: any) {
+ expect(err).toBeInstanceOf(MongoApiError);
+ expect(err.code).toBe("MONGO_READ_ONLY");
+ }
+ });
+
+ test("throws when (conn as any).readOnly: true", () => {
+ const conn = { uri: "mongodb://localhost:27017/test", readOnly: true } as any;
+ expect(() => {
+ assertMongoNotReadOnly(conn, "dropIndex");
+ }).toThrow("Database is configured as read-only. 'dropIndex' is prohibited.");
+ });
+
+ test("permits when conn.readonly is false or undefined", () => {
+ expect(() => {
+ assertMongoNotReadOnly(
+ { uri: "mongodb://localhost:27017/test", readonly: false },
+ "insertDocument",
+ );
+ }).not.toThrow();
+
+ expect(() => {
+ assertMongoNotReadOnly({ uri: "mongodb://localhost:27017/test" }, "insertDocument");
+ }).not.toThrow();
+ });
+
+ describe("rejects through connector mutating operations", () => {
+ const readOnlyConn: MongoConfig = {
+ uri: "mongodb://localhost:27017/test",
+ database: "test",
+ readonly: true,
+ };
+
+ test("insertDocument rejects", async () => {
+ await expect(
+ mongoConnector.insertDocument(readOnlyConn, {
+ collection: "users",
+ document: { name: "test" },
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'insertDocument' is prohibited.");
+ });
+
+ test("updateDocument rejects", async () => {
+ await expect(
+ mongoConnector.updateDocument(readOnlyConn, {
+ collection: "users",
+ filter: { name: "test" },
+ update: { $set: { age: 30 } },
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'updateDocument' is prohibited.");
+ });
+
+ test("replaceDocument rejects", async () => {
+ await expect(
+ mongoConnector.replaceDocument(readOnlyConn, {
+ collection: "users",
+ filter: { name: "test" },
+ replacement: { name: "test2", age: 31 },
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'replaceDocument' is prohibited.");
+ });
+
+ test("deleteDocument rejects", async () => {
+ await expect(
+ mongoConnector.deleteDocument(readOnlyConn, {
+ collection: "users",
+ filter: { name: "test" },
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'deleteDocument' is prohibited.");
+ });
+
+ test("createCollection rejects", async () => {
+ await expect(
+ mongoConnector.createCollection(readOnlyConn, {
+ collection: "new_users",
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'createCollection' is prohibited.");
+ });
+
+ test("dropCollection rejects", async () => {
+ await expect(
+ mongoConnector.dropCollection(readOnlyConn, {
+ collection: "users",
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'dropCollection' is prohibited.");
+ });
+
+ test("createIndexes rejects", async () => {
+ await expect(
+ mongoConnector.createIndexes(readOnlyConn, {
+ collection: "users",
+ key: { email: 1 },
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'createIndexes' is prohibited.");
+ });
+
+ test("dropIndex rejects", async () => {
+ await expect(
+ mongoConnector.dropIndex(readOnlyConn, {
+ collection: "users",
+ indexName: "idx_email",
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'dropIndex' is prohibited.");
+ });
+
+ test("hideIndex rejects", async () => {
+ await expect(
+ mongoConnector.hideIndex(readOnlyConn, {
+ collection: "users",
+ indexName: "idx_email",
+ hidden: true,
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'hideIndex' is prohibited.");
+ });
+ });
+ });
+
+ describe("Bulk engine mutations read-only rejection", () => {
+ test("assertNotReadOnly directly throws MONGO_READ_ONLY", () => {
+ expect(() => {
+ assertNotReadOnly({ readonly: true }, {});
+ }).toThrow("Database is in read-only mode");
+
+ expect(() => {
+ assertNotReadOnly({}, { readonly: true });
+ }).toThrow("Database is in read-only mode");
+
+ expect(() => {
+ assertNotReadOnly({ readOnly: true }, {});
+ }).toThrow("Database is in read-only mode");
+
+ expect(() => {
+ assertNotReadOnly({}, { readOnly: true });
+ }).toThrow("Database is in read-only mode");
+
+ expect(() => {
+ assertNotReadOnly({ readonly: false }, { readonly: false });
+ }).not.toThrow();
+ });
+
+ test("bulkInsert rejects when conn.readonly: true", async () => {
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "test_db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: true },
+ }),
+ } as any;
+ const engine = new MongoBulkEngine(mockDbService);
+
+ await expect(
+ engine.bulkInsert({
+ dbId: "test_db",
+ collection: "items",
+ documents: [{ x: 1 }],
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+
+ test("bulkUpdate rejects when conn.readonly: true", async () => {
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "test_db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: true },
+ }),
+ } as any;
+ const engine = new MongoBulkEngine(mockDbService);
+
+ await expect(
+ engine.bulkUpdate({
+ dbId: "test_db",
+ collection: "items",
+ filter: { x: 1 },
+ update: { $set: { y: 2 } },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+
+ test("bulkDelete rejects when conn.readonly: true", async () => {
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "test_db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: true },
+ }),
+ } as any;
+ const engine = new MongoBulkEngine(mockDbService);
+
+ await expect(
+ engine.bulkDelete({
+ dbId: "test_db",
+ collection: "items",
+ filter: { x: 1 },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+
+ test("importChunk rejects when conn.readonly: true", async () => {
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "test_db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: true },
+ }),
+ } as any;
+ const engine = new MongoBulkEngine(mockDbService);
+
+ // Create an active import operation in OpManager
+ const state = engine.opManager.createOperation("import", "test_db", "items", "json");
+
+ await expect(
+ engine.importChunk({
+ operationId: state.operation.operationId,
+ chunkIndex: 0,
+ isLastChunk: true,
+ payload: JSON.stringify([{ a: 1 }]),
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+ });
+
+ describe("Migration apply/rollback read-only rejection", () => {
+ test("applyMigration rejects when conn.readonly: true", async () => {
+ const mockRpc = { sendResponse: jest.fn(), sendError: jest.fn() };
+ const mockLogger = { info: jest.fn(), error: jest.fn(), warn: jest.fn() } as any;
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "test_db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: true },
+ }),
+ } as any;
+
+ const handlers = new MigrationHandlers(mockRpc as any, mockLogger, mockDbService, {} as any);
+
+ await handlers.handleApplyMigration({ dbId: "test_db", version: 1 }, 101);
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(101, {
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ expect(mockRpc.sendResponse).not.toHaveBeenCalled();
+ });
+
+ test("applyMigration rejects when db.readonly: true", async () => {
+ const mockRpc = { sendResponse: jest.fn(), sendError: jest.fn() };
+ const mockLogger = { info: jest.fn(), error: jest.fn(), warn: jest.fn() } as any;
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "test_db", readonly: true },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: false },
+ }),
+ } as any;
+
+ const handlers = new MigrationHandlers(mockRpc as any, mockLogger, mockDbService, {} as any);
+
+ await handlers.handleApplyMigration({ dbId: "test_db", version: 1 }, 102);
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(102, {
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+
+ test("rollbackMigration rejects when conn.readonly: true", async () => {
+ const mockRpc = { sendResponse: jest.fn(), sendError: jest.fn() };
+ const mockLogger = { info: jest.fn(), error: jest.fn(), warn: jest.fn() } as any;
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "test_db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: true },
+ }),
+ } as any;
+
+ const handlers = new MigrationHandlers(mockRpc as any, mockLogger, mockDbService, {} as any);
+
+ await handlers.handleRollbackMigration({ dbId: "test_db", version: 1 }, 201);
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(201, {
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ expect(mockRpc.sendResponse).not.toHaveBeenCalled();
+ });
+
+ test("rollbackMigration rejects when db.readonly: true", async () => {
+ const mockRpc = { sendResponse: jest.fn(), sendError: jest.fn() };
+ const mockLogger = { info: jest.fn(), error: jest.fn(), warn: jest.fn() } as any;
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "test_db", readonly: true },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: false },
+ }),
+ } as any;
+
+ const handlers = new MigrationHandlers(mockRpc as any, mockLogger, mockDbService, {} as any);
+
+ await handlers.handleRollbackMigration({ dbId: "test_db", version: 1 }, 202);
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(202, {
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+ });
+});
diff --git a/bridge/__tests__/connectors/mongodb.test.ts b/bridge/__tests__/connectors/mongodb.test.ts
new file mode 100644
index 00000000..f2e97345
--- /dev/null
+++ b/bridge/__tests__/connectors/mongodb.test.ts
@@ -0,0 +1,145 @@
+import { describe, expect, test, beforeAll, afterAll, jest } from "@jest/globals";
+import { MongoClient, ObjectId } from "mongodb";
+import * as mongoConnector from "../../src/connectors/mongo";
+import type { MongoConfig } from "../../src/types/mongo";
+
+const MONGO_HOST = process.env.REAL_MONGODB_HOST || "127.0.0.1";
+const MONGO_PORT = process.env.REAL_MONGODB_PORT || "27017";
+const MONGO_DB = process.env.REAL_MONGODB_DATABASE || "testdb";
+
+// Credential-free URI: the test mongo service runs without auth.
+const validConfig: MongoConfig = {
+ uri: process.env.REAL_MONGODB_URI || `mongodb://${MONGO_HOST}:${MONGO_PORT}/${MONGO_DB}`,
+ database: MONGO_DB,
+};
+
+// A closed local port with a short selection timeout → fast, deterministic failure.
+const invalidConfig: MongoConfig = {
+ uri: "mongodb://127.0.0.1:1/testdb?serverSelectionTimeoutMS=5000",
+ database: "testdb",
+};
+
+let seedClient: MongoClient | null = null;
+
+async function seedFixtures(): Promise {
+ seedClient = new MongoClient(validConfig.uri as string, {
+ serverSelectionTimeoutMS: 5000,
+ connectTimeoutMS: 5000,
+ });
+ await seedClient.connect();
+ const db = seedClient.db(MONGO_DB);
+
+ for (const name of ["users", "orders", "active_users_view"]) {
+ try {
+ await db.dropCollection(name);
+ } catch {
+ // may not exist
+ }
+ }
+
+ const userIds: ObjectId[] = [];
+ const userInsert = await db.collection("users").insertMany([
+ { name: "John Doe", email: "john@example.com", age: 30, active: true, createdAt: new Date() },
+ { name: "Jane Smith", email: "jane@example.com", age: 27, active: true, createdAt: new Date() },
+ { name: "Bob Lee", email: "bob@example.com", age: 45, active: false, createdAt: new Date() },
+ ]);
+ for (const id of Object.values(userInsert.insertedIds)) userIds.push(id);
+
+ await db.collection("orders").insertMany([
+ {
+ userId: userIds[0],
+ items: [
+ { sku: "ABC-1", qty: 2, price: 9.99 },
+ { sku: "XYZ-9", qty: 1, price: 19.5 },
+ ],
+ total: 39.48,
+ status: "placed",
+ orderedAt: new Date(),
+ },
+ {
+ userId: userIds[1],
+ items: [{ sku: "ABC-1", qty: 5, price: 9.99 }],
+ total: 49.95,
+ status: "shipped",
+ orderedAt: new Date(),
+ },
+ ]);
+
+ await db.command({
+ create: "active_users_view",
+ viewOn: "users",
+ pipeline: [{ $match: { active: true } }],
+ });
+}
+
+describe("MongoDB Connector", () => {
+ jest.setTimeout(30000);
+
+ beforeAll(async () => {
+ await seedFixtures();
+ });
+
+ afterAll(async () => {
+ await mongoConnector.closeAllMongoClients();
+ if (seedClient) {
+ await seedClient.close();
+ seedClient = null;
+ }
+ });
+
+ test("fails to connect with an invalid config", async () => {
+ const result = await mongoConnector.testConnection(invalidConfig);
+ expect(result.ok).toBe(false);
+ expect(result.status).toBe("disconnected");
+ });
+
+ test("connects with a valid config", async () => {
+ const result = await mongoConnector.testConnection(validConfig);
+ expect(result).toStrictEqual({
+ message: "Connection successful",
+ status: "connected",
+ ok: true,
+ });
+ });
+
+ test("lists collections (including a view)", async () => {
+ const collections = await mongoConnector.listCollections(validConfig);
+ expect(Array.isArray(collections)).toBe(true);
+ const byName = new Map(collections.map((c) => [c.name, c.type]));
+ expect(byName.get("users")).toBe("collection");
+ expect(byName.get("orders")).toBe("collection");
+ expect(byName.get("active_users_view")).toBe("view");
+ });
+
+ test("lists tables as the relational TableInfo adapter", async () => {
+ const tables = await mongoConnector.listTables(validConfig);
+ expect(Array.isArray(tables)).toBe(true);
+ const byName = new Map(tables.map((t) => [t.name, t.type]));
+ expect(byName.get("users")).toBe("BASE TABLE");
+ expect(byName.get("active_users_view")).toBe("VIEW");
+ expect(tables.every((t) => t.schema === MONGO_DB)).toBe(true);
+ });
+
+ test("returns database statistics", async () => {
+ const stats = await mongoConnector.getDBStats(validConfig);
+ expect(stats).toHaveProperty("total_tables");
+ expect(stats).toHaveProperty("total_rows");
+ expect(stats).toHaveProperty("total_db_size_mb");
+ expect(stats.total_tables).toBeGreaterThanOrEqual(2);
+ expect(stats.total_rows).toBeGreaterThanOrEqual(5);
+ });
+
+ test("returns a single pseudo-schema name", async () => {
+ const names = await mongoConnector.listSchemaNames(validConfig);
+ expect(Array.isArray(names)).toBe(true);
+ expect(names).toContain(MONGO_DB);
+ });
+
+ test("connectToDatabase returns collections as pseudo-schemas with no migrations", async () => {
+ const result = await mongoConnector.connectToDatabase(validConfig, "mongo-integration-id");
+ expect(result.baselined).toBe(false);
+ expect(result.schema.map((s) => s.name)).toContain("users");
+ expect(result.migrations.local).toEqual([]);
+ expect(result.migrations.applied).toEqual([]);
+ });
+});
diff --git a/bridge/__tests__/databaseService.mongo.test.ts b/bridge/__tests__/databaseService.mongo.test.ts
new file mode 100644
index 00000000..551e7a9e
--- /dev/null
+++ b/bridge/__tests__/databaseService.mongo.test.ts
@@ -0,0 +1,89 @@
+import { afterAll, beforeAll, describe, expect, test } from "@jest/globals";
+import fs from "fs/promises";
+import fsSync from "fs";
+import os from "os";
+import path from "path";
+
+// RELWAVE_HOME must be set BEFORE the databaseService (and its dbStore/config
+// singletons) are loaded, so point it at an isolated temp directory.
+const TEST_RELWAVE_HOME = path.join(os.tmpdir(), `mongo-db-service-test-${Date.now()}`);
+process.env.RELWAVE_HOME = TEST_RELWAVE_HOME;
+
+const { DatabaseService } = require("../src/services/databaseService");
+
+const { dbStoreInstance } = require("../src/services/dbStore");
+
+const SECRET = "sup3r-s3cret-pw";
+const createdIds: string[] = [];
+
+describe("DatabaseService MongoDB credential handling", () => {
+ const dbService = new DatabaseService();
+
+ beforeAll(async () => {
+ if (!fsSync.existsSync(TEST_RELWAVE_HOME)) {
+ await fs.mkdir(TEST_RELWAVE_HOME, { recursive: true });
+ }
+ });
+
+ afterAll(async () => {
+ for (const id of createdIds) {
+ try {
+ await dbService.deleteDatabase(id);
+ } catch {
+ // ignore
+ }
+ }
+ if (fsSync.existsSync(TEST_RELWAVE_HOME)) {
+ await fs.rm(TEST_RELWAVE_HOME, { recursive: true, force: true });
+ }
+ });
+
+ test("strips the embedded password from the persisted URI and AES-stores it", async () => {
+ const url = `mongodb://testuser:${SECRET}@localhost:27017/testdb`;
+ const res = await dbService.addDatabase({ name: "MongoCredDB", type: "mongodb", url });
+ createdIds.push(res.id);
+
+ expect(res.id).toBeDefined();
+
+ const meta = await dbService.getDatabase(res.id);
+ expect(meta?.type).toBe("mongodb");
+ // The persisted URI is sanitized — no plaintext password.
+ expect(meta?.url).toBe("mongodb://testuser@localhost:27017/testdb");
+ expect(meta?.url).not.toContain(SECRET);
+ expect(meta?.credentialId).toBeDefined();
+
+ // The password is retrievable through the encrypted credential store.
+ const pwd = meta ? await dbStoreInstance.getPasswordFor(meta) : null;
+ expect(pwd).toBe(SECRET);
+
+ // Byte-level scan of the persisted metadata finds no plaintext password.
+ const raw = await fs.readFile(path.join(TEST_RELWAVE_HOME, "databases.json"), "utf-8");
+ expect(raw).not.toContain(SECRET);
+ });
+
+ test("reconstructs the authenticated URI in memory at runtime, never persisting it", async () => {
+ const url = `mongodb://alice:${SECRET}@localhost:27017/proddb`;
+ const res = await dbService.addDatabase({ name: "MongoRuntimeDB", type: "mongodb", url });
+ createdIds.push(res.id);
+
+ const { conn, dbType } = await dbService.getDatabaseConnection(res.id);
+ expect(dbType).toBe("mongodb");
+ // Runtime config carries the password for the driver.
+ expect((conn as { uri?: string }).uri).toContain(SECRET);
+ expect((conn as { uri?: string }).uri).toContain("alice");
+
+ // But the persisted metadata keeps the sanitized URI.
+ const meta = await dbService.getDatabase(res.id);
+ expect(meta?.url).toBe("mongodb://alice@localhost:27017/proddb");
+ expect(meta?.url).not.toContain(SECRET);
+
+ const raw = await fs.readFile(path.join(TEST_RELWAVE_HOME, "databases.json"), "utf-8");
+ expect(raw).not.toContain(SECRET);
+ });
+
+ test("requires name and type for a MongoDB connection", async () => {
+ await expect(
+ dbService.addDatabase({ type: "mongodb", url: "mongodb://localhost/db" }),
+ ).rejects.toThrow("Missing required field: name");
+ });
+});
diff --git a/bridge/__tests__/handlers/migrationHandlers.mongo.test.ts b/bridge/__tests__/handlers/migrationHandlers.mongo.test.ts
new file mode 100644
index 00000000..af2afa52
--- /dev/null
+++ b/bridge/__tests__/handlers/migrationHandlers.mongo.test.ts
@@ -0,0 +1,216 @@
+import { describe, expect, test, beforeEach, jest } from "@jest/globals";
+import { MigrationHandlers } from "../../src/handlers/migrationHandlers";
+import { DBType } from "../../src/types";
+import { mongoMigrationEngine } from "../../src/services/mongoMigrationEngine";
+
+describe("MigrationHandlers MongoDB Unit Tests (bridge/src/handlers/migrationHandlers.ts)", () => {
+ let mockRpc: any;
+ let mockLogger: any;
+ let mockDbService: any;
+ let mockQueryExecutor: any;
+ let handlers: MigrationHandlers;
+
+ beforeEach(() => {
+ mockRpc = {
+ sendResponse: jest.fn(),
+ sendError: jest.fn(),
+ sendNotification: jest.fn(),
+ };
+ mockLogger = {
+ error: jest.fn(),
+ warn: jest.fn(),
+ info: jest.fn(),
+ debug: jest.fn(),
+ };
+ mockDbService = {
+ getDatabaseConnection: jest.fn().mockImplementation(() =>
+ Promise.resolve({
+ db: { id: "mongo-db-1" },
+ conn: { uri: "mongodb://localhost:27017/testdb", database: "testdb" },
+ dbType: DBType.MONGODB,
+ }),
+ ),
+ };
+ mockQueryExecutor = {
+ listSchemas: jest.fn(),
+ };
+
+ handlers = new MigrationHandlers(mockRpc, mockLogger, mockDbService, mockQueryExecutor);
+ });
+
+ describe("handleValidateMigration", () => {
+ test("rejects missing manifest with BAD_REQUEST", async () => {
+ await handlers.handleValidateMigration({}, 1);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(1, {
+ code: "BAD_REQUEST",
+ message: "Missing manifest",
+ });
+ });
+
+ test("validates manifest for MongoDB database", async () => {
+ const manifest: any = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "test_migration",
+ up: [{ type: "createCollection", collection: "test" }],
+ };
+
+ await handlers.handleValidateMigration({ dbId: "mongo-db-1", manifest }, 2);
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(
+ 2,
+ expect.objectContaining({
+ ok: true,
+ data: expect.objectContaining({ valid: true }),
+ }),
+ );
+ });
+ });
+
+ describe("handleListMigrations", () => {
+ test("rejects missing dbId with BAD_REQUEST", async () => {
+ await handlers.handleListMigrations({}, 1);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(1, {
+ code: "BAD_REQUEST",
+ message: "Missing dbId",
+ });
+ });
+
+ test("delegates to mongoMigrationEngine.listMigrations for mongodb dbType", async () => {
+ const spy = jest
+ .spyOn(mongoMigrationEngine, "listMigrations")
+ .mockImplementation(async () => ({
+ appliedMigrations: [],
+ pendingMigrations: [],
+ isLocked: false,
+ }));
+
+ await handlers.handleListMigrations({ dbId: "mongo-db-1", projectRoot: "/fake/root" }, 2);
+
+ expect(spy).toHaveBeenCalled();
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(
+ 2,
+ expect.objectContaining({
+ ok: true,
+ data: expect.objectContaining({ isLocked: false }),
+ }),
+ );
+ spy.mockRestore();
+ });
+ });
+
+ describe("handleGetMigrationStatus", () => {
+ test("delegates to mongoMigrationEngine.getMigrationStatus", async () => {
+ const spy = jest
+ .spyOn(mongoMigrationEngine, "getMigrationStatus")
+ .mockImplementation(async () => ({
+ lockStatus: { isLocked: false, isExpired: false },
+ pendingCount: 0,
+ }));
+
+ await handlers.handleGetMigrationStatus(
+ { dbId: "mongo-db-1", migrationId: "20261031120000" },
+ 3,
+ );
+
+ expect(spy).toHaveBeenCalled();
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(
+ 3,
+ expect.objectContaining({
+ ok: true,
+ data: expect.objectContaining({
+ lockStatus: { isLocked: false, isExpired: false },
+ }),
+ }),
+ );
+ spy.mockRestore();
+ });
+ });
+
+ describe("handleApplyMigration", () => {
+ test("rejects read-only MongoDB database", async () => {
+ mockDbService.getDatabaseConnection.mockImplementationOnce(() =>
+ Promise.resolve({
+ db: { id: "mongo-db-1", readOnly: true },
+ conn: { uri: "mongodb://localhost:27017/testdb", database: "testdb" },
+ dbType: DBType.MONGODB,
+ }),
+ );
+
+ await handlers.handleApplyMigration({ dbId: "mongo-db-1", version: "20261031120000" }, 4);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(4, {
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+
+ test("delegates apply to mongoMigrationEngine.applyMigration", async () => {
+ const spy = jest
+ .spyOn(mongoMigrationEngine, "applyMigration")
+ .mockImplementation(async () => ({
+ success: true,
+ appliedCount: 1,
+ results: [],
+ }));
+
+ await handlers.handleApplyMigration(
+ { dbId: "mongo-db-1", version: "20261031120000", projectRoot: "/fake/root" },
+ 5,
+ );
+
+ expect(spy).toHaveBeenCalled();
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(
+ 5,
+ expect.objectContaining({
+ ok: true,
+ data: expect.objectContaining({ success: true, appliedCount: 1 }),
+ }),
+ );
+ spy.mockRestore();
+ });
+ });
+
+ describe("handleRollbackMigration", () => {
+ test("rejects read-only MongoDB database", async () => {
+ mockDbService.getDatabaseConnection.mockImplementationOnce(() =>
+ Promise.resolve({
+ db: { id: "mongo-db-1", readOnly: true },
+ conn: { uri: "mongodb://localhost:27017/testdb", database: "testdb" },
+ dbType: DBType.MONGODB,
+ }),
+ );
+
+ await handlers.handleRollbackMigration({ dbId: "mongo-db-1", version: "20261031120000" }, 6);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(6, {
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+
+ test("delegates rollback to mongoMigrationEngine.rollbackMigration", async () => {
+ const spy = jest
+ .spyOn(mongoMigrationEngine, "rollbackMigration")
+ .mockImplementation(async () => ({
+ success: true,
+ version: "20261031120000",
+ status: "ROLLED_BACK",
+ executionTimeMs: 10,
+ stepsCompensated: 1,
+ }));
+
+ await handlers.handleRollbackMigration(
+ { dbId: "mongo-db-1", version: "20261031120000", projectRoot: "/fake/root" },
+ 7,
+ );
+
+ expect(spy).toHaveBeenCalled();
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(
+ 7,
+ expect.objectContaining({
+ ok: true,
+ data: expect.objectContaining({ status: "ROLLED_BACK", stepsCompensated: 1 }),
+ }),
+ );
+ spy.mockRestore();
+ });
+ });
+});
diff --git a/bridge/__tests__/handlers/mongoBulkHandlers.test.ts b/bridge/__tests__/handlers/mongoBulkHandlers.test.ts
new file mode 100644
index 00000000..fee05941
--- /dev/null
+++ b/bridge/__tests__/handlers/mongoBulkHandlers.test.ts
@@ -0,0 +1,328 @@
+import { describe, expect, test, beforeEach, jest } from "@jest/globals";
+import { MongoBulkHandlers } from "../../src/handlers/mongoBulkHandlers";
+import { MongoApiError } from "../../src/connectors/mongo";
+
+describe("MongoBulkHandlers JSON-RPC Dispatch & Parameter Validation Tests", () => {
+ let mockRpc: any;
+ let mockLogger: any;
+ let mockEngine: any;
+ let handlers: MongoBulkHandlers;
+
+ const validUuid = "12345678-1234-4234-8234-123456789abc";
+
+ beforeEach(() => {
+ mockRpc = {
+ sendResponse: jest.fn(),
+ sendError: jest.fn(),
+ };
+ mockLogger = {
+ error: jest.fn(),
+ info: jest.fn(),
+ warn: jest.fn(),
+ debug: jest.fn(),
+ };
+ mockEngine = {
+ importStart: jest.fn().mockResolvedValue({
+ operationId: validUuid,
+ status: "pending",
+ format: "json",
+ collection: "users",
+ }),
+ importChunk: jest.fn().mockResolvedValue({
+ operationId: validUuid,
+ chunkIndex: 0,
+ status: "in_progress",
+ insertedCount: 10,
+ failedCount: 0,
+ isComplete: false,
+ totalInserted: 10,
+ totalFailed: 0,
+ }),
+ exportStart: jest.fn().mockResolvedValue({
+ operationId: validUuid,
+ status: "pending",
+ collection: "orders",
+ format: "csv",
+ }),
+ getOperationStatus: jest.fn().mockResolvedValue({
+ operationId: validUuid,
+ type: "import",
+ status: "completed",
+ collection: "users",
+ format: "json",
+ processedDocuments: 10,
+ successfulDocuments: 10,
+ failedDocuments: 0,
+ }),
+ cancelOperation: jest.fn().mockResolvedValue({
+ operationId: validUuid,
+ status: "cancelled",
+ message: "Operation cancelled",
+ }),
+ cleanupOperation: jest.fn().mockResolvedValue({
+ operationId: validUuid,
+ success: true,
+ }),
+ exportSaveTo: jest.fn().mockResolvedValue({
+ operationId: validUuid,
+ destinationPath: "/abs/path/export.json",
+ bytesWritten: 1234,
+ success: true,
+ }),
+ bulkInsert: jest.fn().mockResolvedValue({
+ collection: "products",
+ insertedCount: 5,
+ failedCount: 0,
+ }),
+ bulkUpdate: jest.fn().mockResolvedValue({
+ collection: "products",
+ matchedCount: 5,
+ modifiedCount: 5,
+ }),
+ bulkDelete: jest.fn().mockResolvedValue({
+ collection: "products",
+ deletedCount: 2,
+ }),
+ };
+
+ handlers = new MongoBulkHandlers(mockRpc, mockLogger, mockEngine);
+ });
+
+ test("handleImportStart dispatches successfully and validates params", async () => {
+ await handlers.handleImportStart({ dbId: "db-1", collection: "users", format: "json" }, 1);
+ expect(mockEngine.importStart).toHaveBeenCalledWith({
+ dbId: "db-1",
+ collection: "users",
+ format: "json",
+ options: undefined,
+ });
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(1, {
+ ok: true,
+ data: expect.objectContaining({ operationId: validUuid }),
+ });
+
+ // Invalid format
+ await handlers.handleImportStart({ dbId: "db-1", collection: "users", format: "xml" }, 2);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(2, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("format must be 'json', 'ndjson', or 'csv'"),
+ });
+ });
+
+ test("handleImportChunk validates UUIDv4 and dispatches", async () => {
+ await handlers.handleImportChunk({ operationId: validUuid, chunkIndex: 0, payload: "[]" }, 3);
+ expect(mockEngine.importChunk).toHaveBeenCalledWith({
+ operationId: validUuid,
+ chunkIndex: 0,
+ isLastChunk: undefined,
+ payload: "[]",
+ });
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(3, {
+ ok: true,
+ data: expect.objectContaining({ chunkIndex: 0 }),
+ });
+
+ // Invalid operationId (path traversal attempt)
+ await handlers.handleImportChunk(
+ { operationId: "../malicious", chunkIndex: 0, payload: "[]" },
+ 4,
+ );
+ expect(mockRpc.sendError).toHaveBeenCalledWith(4, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("operationId must be a valid UUIDv4"),
+ });
+ });
+
+ test("handleExportStart validates params and dispatches", async () => {
+ await handlers.handleExportStart({ dbId: "db-1", collection: "orders", format: "csv" }, 5);
+ expect(mockEngine.exportStart).toHaveBeenCalled();
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(5, {
+ ok: true,
+ data: expect.objectContaining({ format: "csv" }),
+ });
+ });
+
+ test("handleGetOperationStatus, handleCancelOperation, and handleCleanupOperation validate operationId", async () => {
+ await handlers.handleGetOperationStatus({ operationId: validUuid }, 6);
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(6, {
+ ok: true,
+ data: expect.objectContaining({ operationId: validUuid }),
+ });
+
+ await handlers.handleCancelOperation({ operationId: validUuid }, 7);
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(7, {
+ ok: true,
+ data: expect.objectContaining({ status: "cancelled" }),
+ });
+
+ await handlers.handleCleanupOperation({ operationId: validUuid }, 8);
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(8, {
+ ok: true,
+ data: { operationId: validUuid, success: true },
+ });
+ });
+
+ test("handleBulkInsert, handleBulkUpdate, handleBulkDelete validate mutations", async () => {
+ await handlers.handleBulkInsert(
+ { dbId: "db-1", collection: "products", documents: [{ sku: "A" }] },
+ 9,
+ );
+ expect(mockEngine.bulkInsert).toHaveBeenCalled();
+
+ await handlers.handleBulkUpdate(
+ {
+ dbId: "db-1",
+ collection: "products",
+ filter: { sku: "A" },
+ update: { $set: { price: 10 } },
+ },
+ 10,
+ );
+ expect(mockEngine.bulkUpdate).toHaveBeenCalled();
+
+ await handlers.handleBulkDelete(
+ { dbId: "db-1", collection: "products", filter: { sku: "A" } },
+ 11,
+ );
+ expect(mockEngine.bulkDelete).toHaveBeenCalled();
+ });
+
+ test("propagates MongoApiError code and message correctly", async () => {
+ mockEngine.bulkInsert.mockRejectedValueOnce(
+ new MongoApiError("MONGO_READ_ONLY", "Database is in read-only mode"),
+ );
+
+ await handlers.handleBulkInsert(
+ { dbId: "db-1", collection: "products", documents: [{ sku: "A" }] },
+ 12,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(12, {
+ code: "MONGO_READ_ONLY",
+ message: "Database is in read-only mode",
+ });
+ });
+
+ describe("handleExportSaveTo", () => {
+ test("dispatches successfully with valid arguments", async () => {
+ await handlers.handleExportSaveTo(
+ {
+ operationId: validUuid,
+ destinationPath: "/abs/path/export.json",
+ options: { overwrite: true },
+ },
+ 13,
+ );
+
+ expect(mockEngine.exportSaveTo).toHaveBeenCalledWith({
+ operationId: validUuid,
+ destinationPath: "/abs/path/export.json",
+ options: { overwrite: true },
+ });
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(13, {
+ ok: true,
+ data: expect.objectContaining({
+ operationId: validUuid,
+ destinationPath: "/abs/path/export.json",
+ bytesWritten: 1234,
+ success: true,
+ }),
+ });
+ });
+
+ test("validates operationId is valid UUIDv4", async () => {
+ await handlers.handleExportSaveTo(
+ {
+ operationId: "invalid-uuid",
+ destinationPath: "/abs/path/export.json",
+ },
+ 14,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(14, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("operationId must be a valid UUIDv4"),
+ });
+ expect(mockEngine.exportSaveTo).not.toHaveBeenCalled();
+ });
+
+ test("validates destinationPath is non-empty string", async () => {
+ await handlers.handleExportSaveTo(
+ {
+ operationId: validUuid,
+ destinationPath: " ",
+ },
+ 15,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(15, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("destinationPath must be a non-empty string"),
+ });
+
+ await handlers.handleExportSaveTo(
+ {
+ operationId: validUuid,
+ destinationPath: null,
+ },
+ 16,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(16, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("destinationPath must be a non-empty string"),
+ });
+ });
+
+ test("validates options must be object", async () => {
+ await handlers.handleExportSaveTo(
+ {
+ operationId: validUuid,
+ destinationPath: "/abs/path/export.json",
+ options: "not-an-object",
+ },
+ 17,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(17, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("options must be an object"),
+ });
+ });
+
+ test("validates options.overwrite must be boolean", async () => {
+ await handlers.handleExportSaveTo(
+ {
+ operationId: validUuid,
+ destinationPath: "/abs/path/export.json",
+ options: { overwrite: "yes" as any },
+ },
+ 18,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(18, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("options.overwrite must be a boolean"),
+ });
+ });
+
+ test("propagates MongoApiError from engine", async () => {
+ mockEngine.exportSaveTo.mockRejectedValueOnce(
+ new MongoApiError("MONGO_FILE_EXISTS", "Destination file already exists"),
+ );
+
+ await handlers.handleExportSaveTo(
+ {
+ operationId: validUuid,
+ destinationPath: "/abs/path/export.json",
+ },
+ 19,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(19, {
+ code: "MONGO_FILE_EXISTS",
+ message: "Destination file already exists",
+ });
+ });
+ });
+});
diff --git a/bridge/__tests__/handlers/mongoRelationshipHandlers.test.ts b/bridge/__tests__/handlers/mongoRelationshipHandlers.test.ts
new file mode 100644
index 00000000..207e017f
--- /dev/null
+++ b/bridge/__tests__/handlers/mongoRelationshipHandlers.test.ts
@@ -0,0 +1,279 @@
+import { describe, expect, test, beforeEach, jest } from "@jest/globals";
+import { MongoRelationshipHandlers } from "../../src/handlers/mongoRelationshipHandlers";
+
+describe("MongoRelationshipHandlers Dispatch & Validation Tests (M7 Phase 1 Remediation)", () => {
+ let mockRpc: any;
+ let mockLogger: any;
+ let mockEngine: any;
+ let handlers: MongoRelationshipHandlers;
+
+ beforeEach(() => {
+ mockRpc = {
+ sendResponse: jest.fn(),
+ sendError: jest.fn(),
+ };
+ mockLogger = {
+ error: jest.fn(),
+ info: jest.fn(),
+ warn: jest.fn(),
+ debug: jest.fn(),
+ };
+ mockEngine = {
+ inferRelationships: jest.fn().mockResolvedValue({
+ relationships: [],
+ insufficientEvidence: [],
+ inferredAt: "2026-11-02T12:00:00.000Z",
+ collectionsScanned: 5,
+ }),
+ listRelationships: jest.fn().mockResolvedValue({
+ inferred: [],
+ confirmed: [],
+ rejectedIds: [],
+ manual: [],
+ insufficientEvidence: [],
+ }),
+ setRelationshipStatus: jest.fn().mockResolvedValue({
+ relationshipId: "test-rel",
+ status: "confirmed",
+ }),
+ saveRelationship: jest.fn().mockResolvedValue({
+ relationship: { id: "test-rel" },
+ }),
+ deleteRelationship: jest.fn().mockResolvedValue({
+ success: true,
+ relationshipId: "test-rel",
+ }),
+ };
+
+ handlers = new MongoRelationshipHandlers(mockRpc, mockLogger, mockEngine);
+ });
+
+ // =========================================================================
+ // 1. handleInfer
+ // =========================================================================
+ describe("handleInfer", () => {
+ test("dispatches infer successfully with valid params", async () => {
+ await handlers.handleInfer(
+ {
+ dbId: "mongo-1",
+ projectId: "proj-1",
+ collections: ["users", "orders"],
+ sampleSize: 50,
+ timeoutMs: 15000,
+ },
+ 1,
+ );
+ expect(mockEngine.inferRelationships).toHaveBeenCalledWith("mongo-1", {
+ projectId: "proj-1",
+ collections: ["users", "orders"],
+ sampleSize: 50,
+ timeoutMs: 15000,
+ maxCollections: undefined,
+ });
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(1, {
+ ok: true,
+ data: expect.objectContaining({ collectionsScanned: 5 }),
+ });
+ });
+
+ test("rejects missing or empty dbId with BAD_REQUEST", async () => {
+ await handlers.handleInfer({}, 2);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(2, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("Missing or invalid required parameter: dbId"),
+ });
+
+ await handlers.handleInfer({ dbId: " " }, 3);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(3, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("Missing or invalid required parameter: dbId"),
+ });
+ });
+
+ test("rejects invalid projectId with BAD_REQUEST", async () => {
+ await handlers.handleInfer({ dbId: "mongo-1", projectId: 123 }, 4);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(4, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("projectId must be a non-empty string"),
+ });
+
+ await handlers.handleInfer({ dbId: "mongo-1", projectId: " " }, 5);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(5, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("projectId must be a non-empty string"),
+ });
+ });
+
+ test("rejects invalid collections with BAD_REQUEST", async () => {
+ await handlers.handleInfer({ dbId: "mongo-1", collections: "not-array" }, 6);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(6, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("collections must be an array of non-empty strings"),
+ });
+
+ await handlers.handleInfer({ dbId: "mongo-1", collections: ["valid", ""] }, 7);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(7, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("collections must be an array of non-empty strings"),
+ });
+ });
+
+ test("rejects invalid sampleSize and timeoutMs", async () => {
+ await handlers.handleInfer({ dbId: "mongo-1", sampleSize: -10 }, 8);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(8, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("sampleSize must be a positive number"),
+ });
+
+ await handlers.handleInfer({ dbId: "mongo-1", timeoutMs: 0 }, 9);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(9, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("timeoutMs must be a positive number"),
+ });
+ });
+ });
+
+ // =========================================================================
+ // 2. handleList
+ // =========================================================================
+ describe("handleList", () => {
+ test("dispatches list successfully", async () => {
+ await handlers.handleList({ dbId: "mongo-1", projectId: "proj-1" }, 10);
+ expect(mockEngine.listRelationships).toHaveBeenCalledWith("mongo-1", "proj-1");
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(10, {
+ ok: true,
+ data: expect.objectContaining({ inferred: [] }),
+ });
+ });
+
+ test("rejects missing dbId or invalid projectId", async () => {
+ await handlers.handleList({}, 11);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(11, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("Missing or invalid required parameter: dbId"),
+ });
+
+ await handlers.handleList({ dbId: "mongo-1", projectId: "" }, 12);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(12, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("projectId must be a non-empty string"),
+ });
+ });
+ });
+
+ // =========================================================================
+ // 3. handleSetStatus
+ // =========================================================================
+ describe("handleSetStatus", () => {
+ test("confirms relationship status successfully", async () => {
+ await handlers.handleSetStatus(
+ { dbId: "mongo-1", relationshipId: "rel-1", status: "confirmed" },
+ 13,
+ );
+ expect(mockEngine.setRelationshipStatus).toHaveBeenCalledWith(
+ "mongo-1",
+ "rel-1",
+ "confirmed",
+ undefined,
+ );
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(13, {
+ ok: true,
+ data: { relationshipId: "test-rel", status: "confirmed" },
+ });
+ });
+
+ test("rejects invalid status", async () => {
+ await handlers.handleSetStatus(
+ { dbId: "mongo-1", relationshipId: "rel-1", status: "invalid_status" },
+ 14,
+ );
+ expect(mockRpc.sendError).toHaveBeenCalledWith(14, {
+ code: "BAD_REQUEST",
+ message: 'Parameter status must be either "confirmed" or "rejected"',
+ });
+ });
+
+ test("rejects missing relationshipId", async () => {
+ await handlers.handleSetStatus({ dbId: "mongo-1", status: "confirmed" }, 15);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(15, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("relationshipId"),
+ });
+ });
+ });
+
+ // =========================================================================
+ // 4. handleSave
+ // =========================================================================
+ describe("handleSave", () => {
+ test("saves relationship successfully with valid object", async () => {
+ const rel = {
+ id: "orders.user_id->users._id",
+ sourceCollection: "orders",
+ sourceField: "user_id",
+ targetCollection: "users",
+ targetField: "_id",
+ cardinality: "many-to-one",
+ };
+
+ await handlers.handleSave({ dbId: "mongo-1", relationship: rel }, 16);
+ expect(mockEngine.saveRelationship).toHaveBeenCalledWith("mongo-1", rel, undefined);
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(16, {
+ ok: true,
+ data: expect.objectContaining({ relationship: expect.any(Object) }),
+ });
+ });
+
+ test("rejects invalid cardinality", async () => {
+ const rel = {
+ id: "orders.user_id->users._id",
+ sourceCollection: "orders",
+ sourceField: "user_id",
+ targetCollection: "users",
+ targetField: "_id",
+ cardinality: "not-a-valid-cardinality",
+ };
+
+ await handlers.handleSave({ dbId: "mongo-1", relationship: rel }, 17);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(17, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("Invalid cardinality"),
+ });
+ });
+
+ test("rejects incomplete relationship object", async () => {
+ await handlers.handleSave(
+ { dbId: "mongo-1", relationship: { id: "rel-1", sourceCollection: "orders" } },
+ 18,
+ );
+ expect(mockRpc.sendError).toHaveBeenCalledWith(18, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining(
+ "Relationship object missing required non-empty string fields",
+ ),
+ });
+ });
+ });
+
+ // =========================================================================
+ // 5. handleDelete
+ // =========================================================================
+ describe("handleDelete", () => {
+ test("deletes relationship successfully", async () => {
+ await handlers.handleDelete({ dbId: "mongo-1", relationshipId: "rel-1" }, 19);
+ expect(mockEngine.deleteRelationship).toHaveBeenCalledWith("mongo-1", "rel-1", undefined);
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(19, {
+ ok: true,
+ data: { success: true, relationshipId: "test-rel" },
+ });
+ });
+
+ test("rejects missing relationshipId", async () => {
+ await handlers.handleDelete({ dbId: "mongo-1" }, 20);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(20, {
+ code: "BAD_REQUEST",
+ message: expect.stringContaining("relationshipId"),
+ });
+ });
+ });
+});
diff --git a/bridge/__tests__/handlers/queryHandlers.mql.test.ts b/bridge/__tests__/handlers/queryHandlers.mql.test.ts
new file mode 100644
index 00000000..74ec919d
--- /dev/null
+++ b/bridge/__tests__/handlers/queryHandlers.mql.test.ts
@@ -0,0 +1,296 @@
+import { describe, expect, test, beforeEach, jest } from "@jest/globals";
+import { QueryHandlers } from "../../src/handlers/queryHandlers";
+import { MongoApiError } from "../../src/connectors/mongo";
+import { DBType } from "../../src/types";
+
+describe("QueryHandlers MQL Unit Tests (bridge/src/handlers/queryHandlers.ts)", () => {
+ let mockRpc: any;
+ let mockLogger: any;
+ let mockSessions: any;
+ let mockDbService: any;
+ let mockQueryExecutor: any;
+ let handlers: QueryHandlers;
+
+ beforeEach(() => {
+ mockRpc = {
+ sendResponse: jest.fn(),
+ sendError: jest.fn(),
+ sendNotification: jest.fn(),
+ };
+ mockLogger = {
+ error: jest.fn(),
+ warn: jest.fn(),
+ info: jest.fn(),
+ debug: jest.fn(),
+ };
+ mockSessions = {
+ registerCancel: jest.fn(),
+ };
+ mockDbService = {
+ getDatabaseConnection: jest.fn().mockImplementation(() =>
+ Promise.resolve({
+ conn: { uri: "mongodb://localhost:27017/testdb", database: "testdb" },
+ dbType: DBType.MONGODB,
+ }),
+ ),
+ };
+ mockQueryExecutor = {
+ executeMql: jest.fn(),
+ explainMql: jest.fn(),
+ };
+
+ handlers = new QueryHandlers(
+ mockRpc,
+ mockLogger,
+ mockSessions,
+ mockDbService,
+ mockQueryExecutor,
+ );
+ });
+
+ describe("handleExecuteMql", () => {
+ test("rejects missing dbId with MONGO_VALIDATION_ERROR", async () => {
+ await handlers.handleExecuteMql(
+ { collection: "users", op: { operation: "find", payload: { filter: {} } } },
+ 1,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(1, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or op",
+ });
+ expect(mockQueryExecutor.executeMql).not.toHaveBeenCalled();
+ });
+
+ test("rejects missing collection with MONGO_VALIDATION_ERROR", async () => {
+ await handlers.handleExecuteMql(
+ { dbId: "conn-1", op: { operation: "find", payload: { filter: {} } } },
+ 2,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(2, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or op",
+ });
+ expect(mockQueryExecutor.executeMql).not.toHaveBeenCalled();
+ });
+
+ test("rejects missing op with MONGO_VALIDATION_ERROR", async () => {
+ await handlers.handleExecuteMql({ dbId: "conn-1", collection: "users" }, 3);
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(3, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or op",
+ });
+ expect(mockQueryExecutor.executeMql).not.toHaveBeenCalled();
+ });
+
+ test("handles database connection lookup failure via sendMongoError", async () => {
+ mockDbService.getDatabaseConnection.mockRejectedValueOnce(new Error("Connection not found"));
+
+ await handlers.handleExecuteMql(
+ {
+ dbId: "invalid-id",
+ collection: "users",
+ op: { operation: "find", payload: { filter: {} } },
+ },
+ 4,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(
+ 4,
+ expect.objectContaining({
+ code: "MONGO_CONNECTION_ERROR",
+ }),
+ );
+ expect(mockRpc.sendResponse).not.toHaveBeenCalled();
+ });
+
+ test("successfully dispatches executeMql and sends response", async () => {
+ const mockResult = {
+ operation: "find",
+ collection: "users",
+ documents: [{ _id: "1", name: "Alice" }],
+ totalReturned: 1,
+ executionTimeMs: 5,
+ };
+ mockQueryExecutor.executeMql.mockResolvedValueOnce(mockResult);
+
+ const params = {
+ dbId: "mongo-1",
+ collection: "users",
+ op: { operation: "find", payload: { filter: { name: "Alice" } } },
+ options: { maxTimeMS: 5000 },
+ };
+
+ await handlers.handleExecuteMql(params, 5);
+
+ expect(mockDbService.getDatabaseConnection).toHaveBeenCalledWith("mongo-1");
+ expect(mockQueryExecutor.executeMql).toHaveBeenCalledWith(
+ expect.objectContaining({ database: "testdb" }),
+ DBType.MONGODB,
+ {
+ collection: "users",
+ op: params.op,
+ options: params.options,
+ },
+ expect.any(Object),
+ );
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(5, {
+ ok: true,
+ data: mockResult,
+ });
+ });
+
+ test("forwards MongoApiError from queryExecutor to rpc.sendError", async () => {
+ mockQueryExecutor.executeMql.mockRejectedValueOnce(
+ new MongoApiError(
+ "MONGO_FORBIDDEN_OPERATION",
+ "Operation 'drop' is forbidden in read-only query workspace. Use RelWave document mutation actions.",
+ ),
+ );
+
+ await handlers.handleExecuteMql(
+ {
+ dbId: "mongo-1",
+ collection: "users",
+ op: { operation: "drop" as any },
+ },
+ 6,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(6, {
+ code: "MONGO_FORBIDDEN_OPERATION",
+ message:
+ "Operation 'drop' is forbidden in read-only query workspace. Use RelWave document mutation actions.",
+ });
+ expect(mockRpc.sendResponse).not.toHaveBeenCalled();
+ });
+ });
+
+ describe("handleExplainMql", () => {
+ test("rejects missing dbId with MONGO_VALIDATION_ERROR", async () => {
+ await handlers.handleExplainMql(
+ { collection: "users", target: { operation: "find", filter: {} } },
+ 11,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(11, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or target",
+ });
+ expect(mockQueryExecutor.explainMql).not.toHaveBeenCalled();
+ });
+
+ test("rejects missing collection with MONGO_VALIDATION_ERROR", async () => {
+ await handlers.handleExplainMql(
+ { dbId: "conn-1", target: { operation: "find", filter: {} } },
+ 12,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(12, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or target",
+ });
+ expect(mockQueryExecutor.explainMql).not.toHaveBeenCalled();
+ });
+
+ test("rejects missing target with MONGO_VALIDATION_ERROR", async () => {
+ await handlers.handleExplainMql({ dbId: "conn-1", collection: "users" }, 13);
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(13, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or target",
+ });
+ expect(mockQueryExecutor.explainMql).not.toHaveBeenCalled();
+ });
+
+ test("handles database lookup failure via sendMongoError", async () => {
+ mockDbService.getDatabaseConnection.mockRejectedValueOnce(new Error("Lookup failed"));
+
+ await handlers.handleExplainMql(
+ {
+ dbId: "invalid-id",
+ collection: "users",
+ target: { operation: "find", filter: {} },
+ },
+ 14,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(
+ 14,
+ expect.objectContaining({
+ code: "MONGO_CONNECTION_ERROR",
+ }),
+ );
+ expect(mockRpc.sendResponse).not.toHaveBeenCalled();
+ });
+
+ test("successfully dispatches explainMql and sends response", async () => {
+ const mockExplainResult = {
+ collection: "users",
+ operation: "find",
+ queryPlanner: {
+ plannerVersion: 1,
+ namespace: "testdb.users",
+ indexFilterSet: false,
+ winningPlan: { stage: "COLLSCAN" },
+ },
+ rawExplain: {},
+ executionTimeMs: 3,
+ };
+ mockQueryExecutor.explainMql.mockResolvedValueOnce(mockExplainResult);
+
+ const params = {
+ dbId: "mongo-1",
+ collection: "users",
+ target: { operation: "find", filter: { status: "active" } } as const,
+ verbosity: "queryPlanner" as const,
+ options: { maxTimeMS: 5000 },
+ };
+
+ await handlers.handleExplainMql(params, 15);
+
+ expect(mockDbService.getDatabaseConnection).toHaveBeenCalledWith("mongo-1");
+ expect(mockQueryExecutor.explainMql).toHaveBeenCalledWith(
+ expect.objectContaining({ database: "testdb" }),
+ DBType.MONGODB,
+ {
+ collection: "users",
+ target: params.target,
+ verbosity: params.verbosity,
+ options: params.options,
+ },
+ expect.any(Object),
+ );
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(15, {
+ ok: true,
+ data: mockExplainResult,
+ });
+ });
+
+ test("forwards MongoApiError from explainMql to rpc.sendError", async () => {
+ mockQueryExecutor.explainMql.mockRejectedValueOnce(
+ new MongoApiError(
+ "MONGO_WRITE_STAGE_FORBIDDEN",
+ "Stage '$out' is forbidden in read-only aggregation queries",
+ ),
+ );
+
+ await handlers.handleExplainMql(
+ {
+ dbId: "mongo-1",
+ collection: "users",
+ target: { operation: "aggregate", pipeline: [{ $out: "dump" }] },
+ },
+ 16,
+ );
+
+ expect(mockRpc.sendError).toHaveBeenCalledWith(16, {
+ code: "MONGO_WRITE_STAGE_FORBIDDEN",
+ message: "Stage '$out' is forbidden in read-only aggregation queries",
+ });
+ expect(mockRpc.sendResponse).not.toHaveBeenCalled();
+ });
+ });
+});
diff --git a/bridge/__tests__/integration/mongoDocuments.integration.test.ts b/bridge/__tests__/integration/mongoDocuments.integration.test.ts
new file mode 100644
index 00000000..1a9017b8
--- /dev/null
+++ b/bridge/__tests__/integration/mongoDocuments.integration.test.ts
@@ -0,0 +1,349 @@
+import { describe, expect, test, beforeAll, afterAll, jest } from "@jest/globals";
+import { MongoClient } from "mongodb";
+import { mongoConnector, collectionExists, closeAllMongoClients } from "../../src/connectors/mongo";
+import type { MongoConfig } from "../../src/types/mongo";
+
+// ---------------------------------------------------------------------------
+// M2 integration tests — require a live MongoDB. Uses a dedicated database so
+// it never collides with the M1 `testdb` fixtures. Skips cleanly when the
+// server is unreachable (spec §16.2).
+// ---------------------------------------------------------------------------
+
+const MONGO_HOST = process.env.REAL_MONGODB_HOST || "127.0.0.1";
+const MONGO_PORT = process.env.REAL_MONGODB_PORT || "27017";
+const MONGO_DB = process.env.REAL_MONGODB_DATABASE_M2 || "relwave_m2_it";
+
+const config: MongoConfig = {
+ uri: `mongodb://${MONGO_HOST}:${MONGO_PORT}/${MONGO_DB}`,
+ database: MONGO_DB,
+};
+
+let seedClient: MongoClient | null = null;
+let connected = false;
+
+beforeAll(async () => {
+ jest.setTimeout(60000);
+ try {
+ seedClient = new MongoClient(config.uri as string);
+ await seedClient.connect();
+ try {
+ await seedClient.db(MONGO_DB).dropDatabase();
+ } catch {
+ // ignore — may lack dropDatabase privilege; collections are dropped per-test
+ }
+ connected = true;
+ } catch {
+ connected = false;
+ console.warn(
+ `[mongoDocuments.integration] MongoDB not reachable at ${MONGO_HOST}:${MONGO_PORT}; skipping M2 integration tests.`,
+ );
+ }
+}, 60000);
+
+afterAll(async () => {
+ if (seedClient) {
+ try {
+ await seedClient.close();
+ } catch {
+ // ignore
+ }
+ seedClient = null;
+ }
+ await closeAllMongoClients();
+});
+
+describe("M2 findDocuments", () => {
+ test("round-trips ObjectId / int32 / int64 / decimal / date / nested types", async () => {
+ if (!connected) return;
+ const oid = new (await import("mongodb")).ObjectId();
+ const now = new Date("2024-01-01T00:00:00.000Z");
+ const res = await mongoConnector.insertDocument(config, {
+ collection: "rt",
+ document: {
+ _id: { $oid: oid.toHexString() },
+ name: "Alice",
+ age: { $numberInt: "30" },
+ score: { $numberDecimal: "9.50" },
+ big: { $numberLong: "9007199254740993" },
+ createdAt: { $date: now.toISOString() },
+ tags: ["a", "b"],
+ meta: { nested: true },
+ },
+ });
+ expect(res.insertedId).toEqual({ $oid: oid.toHexString() });
+ expect(res.document._id).toEqual({ $oid: oid.toHexString() });
+
+ const found = await mongoConnector.findDocuments(config, {
+ collection: "rt",
+ filter: { _id: { $oid: oid.toHexString() } },
+ });
+ expect(found.documents).toHaveLength(1);
+ const d = found.documents[0];
+ expect(d.name).toBe("Alice");
+ expect(d.age).toEqual({ $numberInt: "30" });
+ expect(d.score).toEqual({ $numberDecimal: "9.50" });
+ expect(d.big).toEqual({ $numberLong: "9007199254740993" });
+ expect(d.createdAt).toEqual({ $date: now.toISOString() });
+ expect(d.tags).toEqual(["a", "b"]);
+ expect(d.meta).toEqual({ nested: true });
+ });
+
+ test("filters with $in, $gt (typed), $regex and _id $oid", async () => {
+ if (!connected) return;
+ await mongoConnector.insertDocument(config, {
+ collection: "filt",
+ document: { tag: "red", n: { $numberInt: "10" }, name: "Alice" },
+ });
+ await mongoConnector.insertDocument(config, {
+ collection: "filt",
+ document: { tag: "blue", n: { $numberInt: "20" }, name: "Bob" },
+ });
+ await mongoConnector.insertDocument(config, {
+ collection: "filt",
+ document: { tag: "red", n: { $numberInt: "30" }, name: "Carol" },
+ });
+
+ const byIn = await mongoConnector.findDocuments(config, {
+ collection: "filt",
+ filter: { tag: { $in: ["red", "green"] } },
+ });
+ expect(byIn.total).toBe(2);
+
+ const byGt = await mongoConnector.findDocuments(config, {
+ collection: "filt",
+ filter: { n: { $gt: { $numberInt: "15" } } },
+ });
+ expect(byGt.total).toBe(2);
+
+ const byRegex = await mongoConnector.findDocuments(config, {
+ collection: "filt",
+ filter: { name: { $regex: "^A" } },
+ });
+ expect(byRegex.documents).toHaveLength(1);
+ expect(byRegex.documents[0].name).toBe("Alice");
+ });
+
+ test("paginates with total / totalPages / hasMore", async () => {
+ if (!connected) return;
+ for (let i = 0; i < 25; i++) {
+ await mongoConnector.insertDocument(config, {
+ collection: "page",
+ document: { idx: { $numberInt: String(i) } },
+ });
+ }
+ const p1 = await mongoConnector.findDocuments(config, {
+ collection: "page",
+ pageSize: 10,
+ page: 1,
+ sort: { idx: 1 },
+ });
+ expect(p1.total).toBe(25);
+ expect(p1.documents).toHaveLength(10);
+ expect(p1.totalPages).toBe(3);
+ expect(p1.hasMore).toBe(true);
+ expect(p1.documents[0].idx).toEqual({ $numberInt: "0" });
+
+ const p3 = await mongoConnector.findDocuments(config, {
+ collection: "page",
+ pageSize: 10,
+ page: 3,
+ sort: { idx: 1 },
+ });
+ expect(p3.documents).toHaveLength(5);
+ expect(p3.hasMore).toBe(false);
+ });
+
+ test("applies sort and projection", async () => {
+ if (!connected) return;
+ await mongoConnector.insertDocument(config, {
+ collection: "sp",
+ document: { k: "a", secret: "s1", val: { $numberInt: "3" } },
+ });
+ await mongoConnector.insertDocument(config, {
+ collection: "sp",
+ document: { k: "b", secret: "s2", val: { $numberInt: "1" } },
+ });
+ await mongoConnector.insertDocument(config, {
+ collection: "sp",
+ document: { k: "c", secret: "s3", val: { $numberInt: "2" } },
+ });
+
+ const res = await mongoConnector.findDocuments(config, {
+ collection: "sp",
+ sort: { val: 1 },
+ projection: { k: 1, _id: 0 },
+ });
+ expect(res.documents.map((d) => d.k)).toEqual(["b", "c", "a"]);
+ expect(res.documents[0]).not.toHaveProperty("secret");
+ expect(res.documents[0]).not.toHaveProperty("_id");
+ });
+});
+
+describe("M2 updateDocument", () => {
+ test("applies $set + $inc and returns the after-document", async () => {
+ if (!connected) return;
+ const ins = await mongoConnector.insertDocument(config, {
+ collection: "upd",
+ document: { name: "Bob", count: { $numberInt: "1" } },
+ });
+ const res = await mongoConnector.updateDocument(config, {
+ collection: "upd",
+ filter: { _id: ins.insertedId },
+ update: { $set: { name: "Bobby" }, $inc: { count: { $numberInt: "5" } } },
+ options: { returnDocument: "after" },
+ });
+ expect(res.matchedCount).toBe(1);
+ expect(res.modifiedCount).toBe(1);
+ expect(res.updatedDocument?.name).toBe("Bobby");
+ expect(res.updatedDocument?.count).toEqual({ $numberInt: "6" });
+ });
+
+ test("returnDocument=before returns the pre-update document and persists the change", async () => {
+ if (!connected) return;
+ const ins = await mongoConnector.insertDocument(config, {
+ collection: "updb",
+ document: { v: { $numberInt: "1" } },
+ });
+ const res = await mongoConnector.updateDocument(config, {
+ collection: "updb",
+ filter: { _id: ins.insertedId },
+ update: { $set: { v: { $numberInt: "2" } } },
+ options: { returnDocument: "before" },
+ });
+ expect(res.updatedDocument?.v).toEqual({ $numberInt: "1" });
+ const found = await mongoConnector.findDocuments(config, {
+ collection: "updb",
+ filter: { _id: ins.insertedId },
+ });
+ expect(found.documents[0].v).toEqual({ $numberInt: "2" });
+ });
+
+ test("upsert creates a document and reports upsertedId", async () => {
+ if (!connected) return;
+ const res = await mongoConnector.updateDocument(config, {
+ collection: "ups",
+ filter: { code: "XYZ" },
+ update: { $set: { val: 1 } },
+ options: { upsert: true },
+ });
+ expect(res.matchedCount).toBe(0);
+ expect(res.upsertedId).toBeDefined();
+ const found = await mongoConnector.findDocuments(config, {
+ collection: "ups",
+ filter: { code: "XYZ" },
+ });
+ expect(found.documents).toHaveLength(1);
+ });
+
+ test("multi updates every match", async () => {
+ if (!connected) return;
+ await mongoConnector.insertDocument(config, {
+ collection: "multiu",
+ document: { g: "a", n: { $numberInt: "0" } },
+ });
+ await mongoConnector.insertDocument(config, {
+ collection: "multiu",
+ document: { g: "a", n: { $numberInt: "0" } },
+ });
+ const res = await mongoConnector.updateDocument(config, {
+ collection: "multiu",
+ filter: { g: "a" },
+ update: { $set: { n: { $numberInt: "9" } } },
+ options: { multi: true },
+ });
+ expect(res.matchedCount).toBe(2);
+ expect(res.modifiedCount).toBe(2);
+ });
+});
+
+describe("M2 deleteDocument", () => {
+ test("removes a single document and reports deletedCount", async () => {
+ if (!connected) return;
+ const ins = await mongoConnector.insertDocument(config, {
+ collection: "dels",
+ document: { x: 1 },
+ });
+ const res = await mongoConnector.deleteDocument(config, {
+ collection: "dels",
+ filter: { _id: ins.insertedId },
+ });
+ expect(res.deletedCount).toBe(1);
+ const found = await mongoConnector.findDocuments(config, {
+ collection: "dels",
+ filter: { _id: ins.insertedId },
+ });
+ expect(found.documents).toHaveLength(0);
+ });
+
+ test("multi removes every match", async () => {
+ if (!connected) return;
+ await mongoConnector.insertDocument(config, { collection: "delm", document: { g: "z" } });
+ await mongoConnector.insertDocument(config, { collection: "delm", document: { g: "z" } });
+ const res = await mongoConnector.deleteDocument(config, {
+ collection: "delm",
+ filter: { g: "z" },
+ options: { multi: true },
+ });
+ expect(res.deletedCount).toBe(2);
+ });
+});
+
+describe("M2 runAggregation", () => {
+ test("groups by a field and computes an aggregate", async () => {
+ if (!connected) return;
+ await mongoConnector.insertDocument(config, {
+ collection: "agg",
+ document: { dept: "eng", salary: { $numberInt: "100" } },
+ });
+ await mongoConnector.insertDocument(config, {
+ collection: "agg",
+ document: { dept: "eng", salary: { $numberInt: "200" } },
+ });
+ await mongoConnector.insertDocument(config, {
+ collection: "agg",
+ document: { dept: "sales", salary: { $numberInt: "150" } },
+ });
+
+ const res = await mongoConnector.runAggregation(config, {
+ collection: "agg",
+ pipeline: [{ $group: { _id: "$dept", avg: { $avg: "$salary" } } }, { $sort: { _id: 1 } }],
+ });
+ expect(res.stageCount).toBe(2);
+ expect(res.documents).toHaveLength(2);
+ expect(res.documents[0]._id).toBe("eng");
+ expect(Number(res.documents[0].avg)).toBe(150);
+ });
+});
+
+describe("M2 cache + existence", () => {
+ test("document-page cache reflects a mutation after invalidation", async () => {
+ if (!connected) return;
+ const cacheConfig: MongoConfig = { ...config, cacheDocuments: true };
+ const ins = await mongoConnector.insertDocument(cacheConfig, {
+ collection: "cache",
+ document: { k: "v1" },
+ });
+ const q = { collection: "cache", filter: { _id: ins.insertedId } };
+ const first = await mongoConnector.findDocuments(cacheConfig, q);
+ expect(first.documents[0].k).toBe("v1");
+
+ // A mutation clears the collection cache, so the next read reflects v2.
+ await mongoConnector.updateDocument(cacheConfig, {
+ collection: "cache",
+ filter: { _id: ins.insertedId },
+ update: { $set: { k: "v2" } },
+ });
+ const second = await mongoConnector.findDocuments(cacheConfig, q);
+ expect(second.documents[0].k).toBe("v2");
+ });
+
+ test("collectionExists reports presence and absence", async () => {
+ if (!connected) return;
+ await mongoConnector.insertDocument(config, {
+ collection: "exists_check",
+ document: { a: 1 },
+ });
+ expect(await collectionExists(config, "exists_check")).toBe(true);
+ expect(await collectionExists(config, "nonexistent_xyz_123")).toBe(false);
+ });
+});
diff --git a/bridge/__tests__/integration/mongoInferSchema.integration.test.ts b/bridge/__tests__/integration/mongoInferSchema.integration.test.ts
new file mode 100644
index 00000000..9b182f8e
--- /dev/null
+++ b/bridge/__tests__/integration/mongoInferSchema.integration.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, test, beforeAll, afterAll } from "@jest/globals";
+import { MongoClient } from "mongodb";
+import { mongoConnector, closeAllMongoClients } from "../../src/connectors/mongo";
+import type { MongoConfig } from "../../src/types/mongo";
+
+const TEST_URI = process.env.MONGO_TEST_URI;
+const itLive = TEST_URI ? test : test.skip;
+
+describe("M3 MongoDB Schema Inference (Integration)", () => {
+ let client: MongoClient | null = null;
+ const dbName = "relwave_m3_infer_test";
+ let config: MongoConfig;
+
+ beforeAll(async () => {
+ if (!TEST_URI) return;
+ client = new MongoClient(TEST_URI);
+ await client.connect();
+ const db = client.db(dbName);
+ try {
+ await db.dropDatabase();
+ } catch {
+ // ignore drop errors
+ }
+
+ config = {
+ uri: TEST_URI,
+ database: dbName,
+ cacheDocuments: true,
+ };
+
+ // Seed flat collection
+ await db.collection("flat").insertMany([
+ { name: "Alpha", active: true, score: 10 },
+ { name: "Beta", active: false, score: 20 },
+ ]);
+
+ // Seed sparse and mixed collection
+ await db.collection("sparse_mixed").insertMany([
+ { title: "Item 1", meta: { color: "blue" }, tags: ["a", "b"] },
+ { title: "Item 2", meta: { color: "red", extra: 123 }, tags: ["c"], nullableField: null },
+ { title: 3, tags: [true, 1] },
+ ]);
+
+ // Seed empty collection
+ await db.createCollection("empty_col");
+ }, 30000);
+
+ afterAll(async () => {
+ if (client) {
+ try {
+ await client.db(dbName).dropDatabase();
+ await client.close();
+ } catch {
+ // ignore
+ }
+ }
+ await closeAllMongoClients();
+ });
+
+ itLive("listCollections returns seeded collections", async () => {
+ const collections = await mongoConnector.listCollections(config);
+ const names = collections.map((c) => c.name);
+ expect(names).toContain("flat");
+ expect(names).toContain("sparse_mixed");
+ expect(names).toContain("empty_col");
+ });
+
+ itLive("inferCollectionSchema infers flat uniform collection accurately", async () => {
+ const schema = await mongoConnector.inferCollectionSchema(config, {
+ collection: "flat",
+ sampleSize: 100,
+ });
+
+ expect(schema.collection).toBe("flat");
+ expect(schema.sampleSize).toBe(2);
+ expect(schema.totalDocs).toBe(2);
+ expect(schema.sampleDocuments.length).toBe(2);
+
+ const nameField = schema.fields.find((f) => f.path === "name")!;
+ expect(nameField.bsonType).toBe("string");
+ expect(nameField.presencePct).toBe(100);
+ expect(nameField.optional).toBe(false);
+ });
+
+ itLive("inferCollectionSchema infers sparse, mixed, and nested schemas", async () => {
+ const schema = await mongoConnector.inferCollectionSchema(config, {
+ collection: "sparse_mixed",
+ sampleSize: 100,
+ });
+
+ expect(schema.collection).toBe("sparse_mixed");
+ expect(schema.sampleSize).toBe(3);
+
+ const titleField = schema.fields.find((f) => f.path === "title")!;
+ expect(titleField.typeConflicts.length).toBeGreaterThan(0);
+
+ const tagsField = schema.fields.find((f) => f.path === "tags")!;
+ expect(tagsField.isArray).toBe(true);
+ expect(tagsField.arrayElementTypes?.length).toBeGreaterThanOrEqual(2);
+
+ const metaExtra = schema.fields.find((f) => f.path === "meta.extra")!;
+ expect(metaExtra.optional).toBe(true);
+ expect(metaExtra.depth).toBe(1);
+ expect(metaExtra.parentPath).toBe("meta");
+ });
+
+ itLive("inferCollectionSchema succeeds on empty collection", async () => {
+ const schema = await mongoConnector.inferCollectionSchema(config, {
+ collection: "empty_col",
+ sampleSize: 50,
+ });
+
+ expect(schema.collection).toBe("empty_col");
+ expect(schema.sampleSize).toBe(0);
+ expect(schema.totalDocs).toBe(0);
+ expect(schema.fields).toHaveLength(0);
+ expect(schema.sampleDocuments).toHaveLength(0);
+ });
+});
diff --git a/bridge/__tests__/integration/mongoMql.integration.test.ts b/bridge/__tests__/integration/mongoMql.integration.test.ts
new file mode 100644
index 00000000..55c0adda
--- /dev/null
+++ b/bridge/__tests__/integration/mongoMql.integration.test.ts
@@ -0,0 +1,176 @@
+import { describe, expect, test, beforeAll, afterAll } from "@jest/globals";
+import { MongoClient } from "mongodb";
+import { executeMql, explainMql, closeAllMongoClients } from "../../src/connectors/mongo";
+import type { MongoConfig } from "../../src/types/mongo";
+
+const mongoUri = process.env.MONGO_TEST_URI;
+const describeIntegration = mongoUri ? describe : describe.skip;
+
+describeIntegration("MongoDB M5 MQL Integration Tests (Live Server)", () => {
+ const dbName = "relwave_m5_it";
+ const config: MongoConfig = {
+ uri: mongoUri,
+ database: dbName,
+ };
+
+ let client: MongoClient | null = null;
+ const collectionName = "products";
+
+ beforeAll(async () => {
+ if (!mongoUri) return;
+ client = new MongoClient(mongoUri);
+ await client.connect();
+ const db = client.db(dbName);
+ try {
+ await db.collection(collectionName).drop();
+ } catch {
+ // ignore
+ }
+
+ await db.collection(collectionName).insertMany([
+ { sku: "ITEM-1", name: "Widget A", price: 10, category: "tools", stock: 100 },
+ { sku: "ITEM-2", name: "Widget B", price: 25, category: "tools", stock: 50 },
+ { sku: "ITEM-3", name: "Gadget C", price: 50, category: "electronics", stock: 20 },
+ { sku: "ITEM-4", name: "Gadget D", price: 100, category: "electronics", stock: 5 },
+ ]);
+ });
+
+ afterAll(async () => {
+ if (client) {
+ try {
+ await client.db(dbName).dropDatabase();
+ await client.close();
+ } catch {
+ // ignore
+ }
+ }
+ await closeAllMongoClients();
+ });
+
+ test("executes find with projection, sort, and limit", async () => {
+ const res = await executeMql(config, {
+ collection: collectionName,
+ op: {
+ operation: "find",
+ payload: {
+ filter: { category: "tools" },
+ projection: { sku: 1, name: 1, _id: 0 },
+ sort: { price: -1 },
+ limit: 10,
+ },
+ },
+ });
+
+ expect(res.operation).toBe("find");
+ if (res.operation === "find") {
+ expect(res.documents).toHaveLength(2);
+ expect((res.documents[0] as any).sku).toBe("ITEM-2");
+ expect((res.documents[1] as any).sku).toBe("ITEM-1");
+ }
+ });
+
+ test("executes aggregate with multi-stage pipeline", async () => {
+ const res = await executeMql(config, {
+ collection: collectionName,
+ op: {
+ operation: "aggregate",
+ payload: {
+ pipeline: [
+ { $group: { _id: "$category", totalStock: { $sum: "$stock" } } },
+ { $sort: { totalStock: -1 } },
+ ],
+ },
+ },
+ });
+
+ expect(res.operation).toBe("aggregate");
+ if (res.operation === "aggregate") {
+ expect(res.documents).toHaveLength(2);
+ expect((res.documents[0] as any)._id).toBe("tools");
+ expect((res.documents[0] as any).totalStock).toEqual({ $numberInt: "150" });
+ }
+ });
+
+ test("executes aggregate with empty pipeline []", async () => {
+ const res = await executeMql(config, {
+ collection: collectionName,
+ op: {
+ operation: "aggregate",
+ payload: {
+ pipeline: [],
+ },
+ },
+ });
+
+ expect(res.operation).toBe("aggregate");
+ if (res.operation === "aggregate") {
+ expect(res.documents).toHaveLength(4);
+ }
+ });
+
+ test("executes countDocuments and estimatedDocumentCount", async () => {
+ const filteredCountRes = await executeMql(config, {
+ collection: collectionName,
+ op: {
+ operation: "countDocuments",
+ payload: { filter: { category: "electronics" } },
+ },
+ });
+ if (filteredCountRes.operation === "countDocuments") {
+ expect(filteredCountRes.count).toBe(2);
+ }
+
+ const estCountRes = await executeMql(config, {
+ collection: collectionName,
+ op: {
+ operation: "estimatedDocumentCount",
+ },
+ });
+ if (estCountRes.operation === "estimatedDocumentCount") {
+ expect(estCountRes.count).toBeGreaterThanOrEqual(4);
+ }
+ });
+
+ test("executes distinct values", async () => {
+ const res = await executeMql(config, {
+ collection: collectionName,
+ op: {
+ operation: "distinct",
+ payload: { field: "category" },
+ },
+ });
+
+ expect(res.operation).toBe("distinct");
+ if (res.operation === "distinct") {
+ expect(res.values.sort()).toEqual(["electronics", "tools"]);
+ expect(res.count).toBe(2);
+ }
+ });
+
+ test("explains find and aggregate queries", async () => {
+ const findExplain = await explainMql(config, {
+ collection: collectionName,
+ target: {
+ operation: "find",
+ filter: { sku: "ITEM-1" },
+ },
+ verbosity: "executionStats",
+ });
+
+ expect(findExplain.operation).toBe("find");
+ expect(findExplain.queryPlanner).toBeDefined();
+ expect(findExplain.executionStats).toBeDefined();
+
+ const aggExplain = await explainMql(config, {
+ collection: collectionName,
+ target: {
+ operation: "aggregate",
+ pipeline: [{ $match: { category: "tools" } }],
+ },
+ verbosity: "queryPlanner",
+ });
+
+ expect(aggExplain.operation).toBe("aggregate");
+ expect(aggExplain.queryPlanner).toBeDefined();
+ });
+});
diff --git a/bridge/__tests__/integration/mongoMutations.integration.test.ts b/bridge/__tests__/integration/mongoMutations.integration.test.ts
new file mode 100644
index 00000000..826eeaef
--- /dev/null
+++ b/bridge/__tests__/integration/mongoMutations.integration.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, test, beforeAll, afterAll, jest } from "@jest/globals";
+import { MongoClient, ObjectId } from "mongodb";
+import { mongoConnector, closeAllMongoClients } from "../../src/connectors/mongo";
+import type { MongoConfig } from "../../src/types/mongo";
+
+const TEST_URI = process.env.MONGO_TEST_URI;
+const TEST_DB = "relwave_m4_it";
+
+const config: MongoConfig = {
+ uri: TEST_URI ? `${TEST_URI.replace(/\/$/, "")}/${TEST_DB}` : undefined,
+ database: TEST_DB,
+};
+
+let client: MongoClient | null = null;
+let connected = false;
+
+beforeAll(async () => {
+ jest.setTimeout(60000);
+ if (!TEST_URI) {
+ console.warn(
+ "[mongoMutations.integration] MONGO_TEST_URI not set; skipping M4 integration tests.",
+ );
+ return;
+ }
+ try {
+ client = new MongoClient(config.uri as string);
+ await client.connect();
+ try {
+ await client.db(TEST_DB).dropDatabase();
+ } catch {
+ // ignore
+ }
+ connected = true;
+ } catch {
+ connected = false;
+ console.warn(
+ `[mongoMutations.integration] MongoDB not reachable at ${TEST_URI}; skipping M4 integration tests.`,
+ );
+ }
+}, 60000);
+
+afterAll(async () => {
+ if (client) {
+ try {
+ await client.db(TEST_DB).dropDatabase();
+ await client.close();
+ } catch {
+ // ignore
+ }
+ client = null;
+ }
+ await closeAllMongoClients();
+});
+
+describe("M4 Mutations Lifecycle (Integration)", () => {
+ const collection = "test_m4_mutations";
+
+ test("creates a new collection explicitly", async () => {
+ if (!connected) return;
+ const res = await mongoConnector.createCollection(config, { collection });
+ expect(res.ok).toBe(true);
+ expect(res.collection).toBe(collection);
+
+ const list = await mongoConnector.listCollections(config);
+ expect(list.some((c) => c.name === collection)).toBe(true);
+ });
+
+ test("creates a capped collection with validated size", async () => {
+ if (!connected) return;
+ const cappedColl = "test_m4_capped";
+ const res = await mongoConnector.createCollection(config, {
+ collection: cappedColl,
+ options: { capped: true, size: 8192, max: 100 },
+ });
+ expect(res.ok).toBe(true);
+ expect(res.collection).toBe(cappedColl);
+
+ await mongoConnector.dropCollection(config, { collection: cappedColl });
+ });
+
+ test("replaces a document and updates cache", async () => {
+ if (!connected) return;
+ const oid = new ObjectId();
+ const originalDoc = {
+ _id: { $oid: oid.toHexString() },
+ title: "Initial Title",
+ version: { $numberInt: "1" },
+ tags: ["alpha", "beta"],
+ };
+
+ const inserted = await mongoConnector.insertDocument(config, {
+ collection,
+ document: originalDoc,
+ });
+ expect(inserted.insertedId).toEqual({ $oid: oid.toHexString() });
+
+ const replacement = {
+ _id: { $oid: oid.toHexString() },
+ title: "Replaced Title",
+ author: "Alice",
+ active: true,
+ };
+
+ const replaceRes = await mongoConnector.replaceDocument(config, {
+ collection,
+ filter: { _id: { $oid: oid.toHexString() } },
+ replacement,
+ options: { returnDocument: "after" },
+ });
+
+ expect(replaceRes.matchedCount).toBe(1);
+ expect(replaceRes.modifiedCount).toBe(1);
+ expect(replaceRes.updatedDocument?.title).toBe("Replaced Title");
+ expect(replaceRes.updatedDocument?.author).toBe("Alice");
+ expect(replaceRes.updatedDocument?.version).toBeUndefined();
+ expect(replaceRes.updatedDocument?.tags).toBeUndefined();
+
+ const found = await mongoConnector.findDocuments(config, {
+ collection,
+ filter: { _id: { $oid: oid.toHexString() } },
+ });
+ expect(found.documents).toHaveLength(1);
+ expect(found.documents[0].title).toBe("Replaced Title");
+ expect(found.documents[0].version).toBeUndefined();
+ });
+
+ test("rejects dropping system collection", async () => {
+ if (!connected) return;
+ await expect(
+ mongoConnector.dropCollection(config, { collection: "system.views" }),
+ ).rejects.toMatchObject({ code: "MONGO_FORBIDDEN" });
+ });
+
+ test("drops collection successfully", async () => {
+ if (!connected) return;
+ const dropRes = await mongoConnector.dropCollection(config, { collection });
+ expect(dropRes.ok).toBe(true);
+ expect(dropRes.collection).toBe(collection);
+
+ const list = await mongoConnector.listCollections(config);
+ expect(list.some((c) => c.name === collection)).toBe(false);
+ });
+});
diff --git a/bridge/__tests__/mongoBson.test.ts b/bridge/__tests__/mongoBson.test.ts
new file mode 100644
index 00000000..4514aebe
--- /dev/null
+++ b/bridge/__tests__/mongoBson.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, test } from "@jest/globals";
+import { ObjectId, Decimal128, Long, Timestamp, Int32, Binary } from "mongodb";
+import { serializeMongoValue, serializeMongoDocument } from "../src/connectors/mongoBson";
+
+describe("serializeMongoValue", () => {
+ test("passes primitives through unchanged", () => {
+ expect(serializeMongoValue(null)).toBeNull();
+ expect(serializeMongoValue(true)).toBe(true);
+ expect(serializeMongoValue(42)).toBe(42);
+ expect(serializeMongoValue("hi")).toBe("hi");
+ });
+
+ test("drops non-finite numbers to stay JSON-safe", () => {
+ expect(serializeMongoValue(Number.NaN)).toBeNull();
+ expect(serializeMongoValue(Number.POSITIVE_INFINITY)).toBeNull();
+ });
+
+ test("maps undefined to the wire convention", () => {
+ expect(serializeMongoValue(undefined)).toEqual({ $undefined: true });
+ });
+
+ test("recurses into arrays", () => {
+ expect(serializeMongoValue([1, "two", null])).toEqual([1, "two", null]);
+ });
+
+ test("serializes ObjectId, Date, Decimal128, Long, Timestamp", () => {
+ const oid = new ObjectId("507f1f77bcf86cd799439011");
+ expect(serializeMongoValue(oid)).toEqual({ $oid: "507f1f77bcf86cd799439011" });
+
+ const date = new Date("2020-01-02T03:04:05.000Z");
+ expect(serializeMongoValue(date)).toEqual({ $date: "2020-01-02T03:04:05.000Z" });
+
+ expect(serializeMongoValue(new Decimal128("123.45"))).toEqual({ $numberDecimal: "123.45" });
+
+ expect(serializeMongoValue(Long.fromNumber(42))).toEqual({ $numberLong: "42" });
+
+ const ts = new Timestamp({ t: 1234567890, i: 1 });
+ expect(serializeMongoValue(ts)).toEqual({ $timestamp: { t: 1234567890, i: 1 } });
+ });
+
+ test("flattens Int32 to a plain number", () => {
+ expect(serializeMongoValue(new Int32(7))).toBe(7);
+ expect(serializeMongoValue(new Int32(7)).constructor).toBe(Number);
+ });
+
+ test("serializes Binary and raw buffers to $binary", () => {
+ const bin = new Binary(Buffer.from("hello"));
+ const out = serializeMongoValue(bin) as { $binary: { base64: string; subtype: string } };
+ expect(out.$binary.base64).toBe(Buffer.from("hello").toString("base64"));
+ expect(out.$binary.subtype).toBe("00");
+
+ const bufOut = serializeMongoValue(Buffer.from("hi")) as {
+ $binary: { base64: string; subtype: string };
+ };
+ expect(bufOut.$binary.base64).toBe(Buffer.from("hi").toString("base64"));
+
+ const u8Out = serializeMongoValue(new Uint8Array([1, 2, 3])) as {
+ $binary: { base64: string; subtype: string };
+ };
+ expect(u8Out.$binary.base64).toBe(Buffer.from([1, 2, 3]).toString("base64"));
+ });
+
+ test("recurses through nested documents and arrays", () => {
+ const value = serializeMongoValue({
+ _id: new ObjectId("507f1f77bcf86cd799439011"),
+ nested: { when: new Date("2021-06-07T08:09:10.000Z"), tags: ["a", "b"] },
+ list: [1, { deep: true }],
+ });
+ expect(value).toEqual({
+ _id: { $oid: "507f1f77bcf86cd799439011" },
+ nested: { when: { $date: "2021-06-07T08:09:10.000Z" }, tags: ["a", "b"] },
+ list: [1, { deep: true }],
+ });
+ });
+
+ test("output is always JSON.stringify-safe", () => {
+ const value = serializeMongoValue({
+ _id: new ObjectId(),
+ when: new Date(),
+ big: Long.fromString("9007199254740993"),
+ dec: new Decimal128("3.14"),
+ raw: Buffer.from("bytes"),
+ missing: undefined,
+ deep: { arr: [new ObjectId(), new Date()] },
+ });
+ expect(() => JSON.stringify(value)).not.toThrow();
+ expect(JSON.parse(JSON.stringify(value))).toBeDefined();
+ });
+});
+
+describe("serializeMongoDocument", () => {
+ test("serializes a document and omits the internal _bsontype marker", () => {
+ const doc = {
+ _id: new ObjectId("507f1f77bcf86cd799439011"),
+ name: "test",
+ createdAt: new Date("2022-03-04T05:06:07.000Z"),
+ };
+ const out = serializeMongoDocument(doc);
+ expect(out).toEqual({
+ _id: { $oid: "507f1f77bcf86cd799439011" },
+ name: "test",
+ createdAt: { $date: "2022-03-04T05:06:07.000Z" },
+ });
+ expect(Object.keys(out)).not.toContain("_bsontype");
+ });
+});
diff --git a/bridge/__tests__/mongoBulkEngine.test.ts b/bridge/__tests__/mongoBulkEngine.test.ts
new file mode 100644
index 00000000..5af5a6af
--- /dev/null
+++ b/bridge/__tests__/mongoBulkEngine.test.ts
@@ -0,0 +1,1649 @@
+import { describe, expect, test, beforeEach, afterEach, jest } from "@jest/globals";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import * as mongoConnector from "../src/connectors/mongo";
+import {
+ BulkOperationManager,
+ MongoBulkEngine,
+ parseImportPayload,
+ parseCsv,
+ isValidUuidV4,
+ MAX_IMPORT_CHUNK_DOCS,
+ MAX_IMPORT_CHUNK_SIZE_BYTES,
+ MAX_BULK_INSERT_DOCS,
+ EXPORT_DIR,
+} from "../src/services/mongoBulkEngine";
+import { DBType } from "../src/types";
+
+describe("MongoDB M7 Phase 3: Bulk Operations Bridge Engine", () => {
+ let opManager: BulkOperationManager;
+ let engine: MongoBulkEngine;
+ let mockDbService: any;
+ let mockCollection: any;
+ let mockNativeDb: any;
+
+ beforeEach(() => {
+ opManager = new BulkOperationManager(60 * 60 * 1000); // 1-hour TTL
+
+ mockCollection = {
+ insertMany: jest.fn().mockResolvedValue({
+ insertedCount: 2,
+ insertedIds: { 0: "id1", 1: "id2" },
+ }),
+ updateMany: jest.fn().mockResolvedValue({
+ matchedCount: 5,
+ modifiedCount: 3,
+ upsertedId: null,
+ }),
+ deleteMany: jest.fn().mockResolvedValue({
+ deletedCount: 15,
+ }),
+ find: jest.fn(),
+ };
+
+ mockNativeDb = {
+ collection: jest.fn().mockReturnValue(mockCollection),
+ };
+
+ mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ db: { id: "test-db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test" },
+ dbType: DBType.MONGODB,
+ }),
+ acquireConnection: jest.fn().mockResolvedValue({
+ db: { id: "test-db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test" },
+ dbType: DBType.MONGODB,
+ release: jest.fn(),
+ }),
+ };
+
+ jest.spyOn(mongoConnector, "selectDb").mockReturnValue(mockNativeDb as any);
+
+ engine = new MongoBulkEngine(mockDbService, opManager);
+ jest.spyOn(engine, "getDb").mockResolvedValue({
+ db: { id: "test-db", readonly: false },
+ conn: { uri: "mongodb://localhost:27017/test" },
+ dbType: DBType.MONGODB,
+ nativeDb: mockNativeDb,
+ });
+ });
+
+ afterEach(() => {
+ opManager.dispose();
+ });
+
+ // =========================================================================
+ // 1. BulkOperationManager Lifecycle & State Machine
+ // =========================================================================
+ describe("BulkOperationManager", () => {
+ test("validates and generates valid UUIDv4 operationIds", () => {
+ const op = opManager.createOperation("import", "db-1", "users", "json");
+ expect(isValidUuidV4(op.operation.operationId)).toBe(true);
+ expect(op.operation.status).toBe("pending");
+ expect(op.operation.collection).toBe("users");
+ });
+
+ test("enforces safe state machine transitions", () => {
+ const op = opManager.createOperation("import", "db-1", "users", "json");
+ const id = op.operation.operationId;
+
+ // pending -> in_progress
+ opManager.transition(id, "in_progress");
+ expect(opManager.getOperation(id)?.operation.status).toBe("in_progress");
+
+ // in_progress -> completed
+ opManager.transition(id, "completed");
+ expect(opManager.getOperation(id)?.operation.status).toBe("completed");
+
+ // terminal state cannot transition again
+ expect(() => opManager.transition(id, "in_progress")).toThrow(
+ /Cannot transition terminal operation/,
+ );
+ });
+
+ test("handles cancellation and avoids concurrent cancellation races", () => {
+ const op = opManager.createOperation("export", "db-1", "orders", "json");
+ const id = op.operation.operationId;
+
+ const cancelRes = opManager.cancel(id);
+ expect(cancelRes.status).toBe("cancelled");
+ expect(op.controller.signal.aborted).toBe(true);
+
+ // Repeat cancel is idempotent and safe
+ const repeatCancel = opManager.cancel(id);
+ expect(repeatCancel.status).toBe("cancelled");
+ expect(repeatCancel.message).toContain("already cancelled");
+ });
+
+ test("rejects path traversal attempts in operationId", () => {
+ expect(() => opManager.getOperation("../etc/passwd")).toThrow(/Invalid operationId format/);
+ expect(() => opManager.cleanup("invalid-uuid\0")).toThrow(/Invalid operationId format/);
+ });
+
+ test("respects 1-hour TTL expiration", () => {
+ const shortTtlManager = new BulkOperationManager(10); // 10ms TTL
+ const op = shortTtlManager.createOperation("import", "db-1", "users", "json");
+ const id = op.operation.operationId;
+
+ return new Promise((resolve) => {
+ setTimeout(() => {
+ const fetched = shortTtlManager.getOperation(id);
+ expect(fetched).toBeNull();
+ shortTtlManager.dispose();
+ resolve();
+ }, 30);
+ });
+ });
+ });
+
+ // =========================================================================
+ // 2. Parsing, Limits & Prototype Pollution Defense
+ // =========================================================================
+ describe("Parsing & Payload Guards", () => {
+ test("parses JSON array format correctly", () => {
+ const payload = JSON.stringify([
+ { name: "Alice", age: 30 },
+ { name: "Bob", age: 25 },
+ ]);
+ const docs = parseImportPayload(payload, "json");
+ expect(docs).toHaveLength(2);
+ expect(docs[0].name).toBe("Alice");
+ });
+
+ test("rejects non-array JSON payloads", () => {
+ const payload = JSON.stringify({ name: "Alice" });
+ expect(() => parseImportPayload(payload, "json")).toThrow(/must be an array of documents/);
+ });
+
+ test("parses NDJSON format correctly", () => {
+ const payload = '{"name":"Alice","score":100}\n{"name":"Bob","score":85}\n';
+ const docs = parseImportPayload(payload, "ndjson");
+ expect(docs).toHaveLength(2);
+ expect(docs[1].score).toBe(85);
+ });
+
+ test("rejects malformed NDJSON lines", () => {
+ const payload = '{"name":"Alice"}\nINVALID_JSON_LINE\n';
+ expect(() => parseImportPayload(payload, "ndjson")).toThrow(/Invalid NDJSON at line 2/);
+ });
+
+ test("parses CSV with un-flattened dot notation, types, quotes, and newlines", () => {
+ const csv =
+ "user.name,user.age,active,notes\n" +
+ '"Smith, Alice",30,true,"Line 1\nLine 2"\n' +
+ "Bob,25,false,null\n";
+
+ const docs = parseCsv(csv);
+ expect(docs).toHaveLength(2);
+ expect(docs[0].user).toEqual({ name: "Smith, Alice", age: 30 });
+ expect(docs[0].active).toBe(true);
+ expect(docs[0].notes).toBe("Line 1\nLine 2");
+ expect(docs[1].user).toEqual({ name: "Bob", age: 25 });
+ expect(docs[1].active).toBe(false);
+ expect(docs[1].notes).toBeNull();
+ });
+
+ test("detects and rejects prototype pollution keys (__proto__, constructor)", () => {
+ const payloadWithProto = JSON.stringify([
+ { title: "Normal" },
+ JSON.parse('{"__proto__": {"admin": true}, "title": "Hacked"}'),
+ ]);
+ expect(() => parseImportPayload(payloadWithProto, "json")).toThrow(/Prototype pollution/);
+
+ const payloadWithConstructor = JSON.stringify([
+ { title: "Normal" },
+ { constructor: { name: "Evil" } },
+ ]);
+ expect(() => parseImportPayload(payloadWithConstructor, "json")).toThrow(
+ /Prototype pollution/,
+ );
+
+ const csvWithProto = "name,__proto__.isAdmin\nAlice,true\n";
+ expect(() => parseCsv(csvWithProto)).toThrow(/Prototype pollution/);
+ });
+
+ test("enforces chunk document limit (max 1,000 docs)", () => {
+ const oversizedArray = new Array(MAX_IMPORT_CHUNK_DOCS + 1).fill({ item: "test" });
+ expect(() => parseImportPayload(JSON.stringify(oversizedArray), "json")).toThrow(
+ /exceeds maximum limit of 1000 documents/,
+ );
+ });
+
+ test("enforces chunk payload size limit (max 4MB)", () => {
+ const largeDoc = "x".repeat(MAX_IMPORT_CHUNK_SIZE_BYTES + 10);
+ expect(() => parseImportPayload(largeDoc, "json")).toThrow(
+ /exceeds maximum limit of 4194304 bytes/,
+ );
+ });
+
+ test("blocks system collections (system.*)", async () => {
+ await expect(
+ engine.importStart({ dbId: "db-1", collection: "system.views", format: "json" }),
+ ).rejects.toThrow(/Operations on system collections are forbidden/);
+ });
+ });
+
+ // =========================================================================
+ // 3. Chunk Replay Protection & Write Batching
+ // =========================================================================
+ describe("Import Engine Write & Replay Protections", () => {
+ test("idempotently handles chunk replay without double insert", async () => {
+ const startRes = await engine.importStart({
+ dbId: "db-1",
+ collection: "items",
+ format: "json",
+ });
+ const opId = startRes.operationId;
+ const payload = JSON.stringify([{ id: 1 }, { id: 2 }]);
+
+ // First chunk invocation
+ const res1 = await engine.importChunk({
+ operationId: opId,
+ chunkIndex: 0,
+ payload,
+ });
+ expect(res1.insertedCount).toBe(2);
+ expect(mockCollection.insertMany).toHaveBeenCalledTimes(1);
+
+ // Replaying the exact same chunkIndex: must return cached response without insert
+ const res2 = await engine.importChunk({
+ operationId: opId,
+ chunkIndex: 0,
+ payload,
+ });
+ expect(res2.insertedCount).toBe(2);
+ expect(mockCollection.insertMany).toHaveBeenCalledTimes(1); // Not called again!
+ });
+
+ test("handles out-of-order chunks cleanly", async () => {
+ const startRes = await engine.importStart({
+ dbId: "db-1",
+ collection: "items",
+ format: "json",
+ });
+ const opId = startRes.operationId;
+
+ // Chunk 1 arrives before Chunk 0
+ const chunk1 = await engine.importChunk({
+ operationId: opId,
+ chunkIndex: 1,
+ isLastChunk: true,
+ payload: JSON.stringify([{ id: 3 }, { id: 4 }]),
+ });
+ expect(chunk1.isComplete).toBe(true);
+
+ // Chunk 0 arrives after
+ const chunk0 = await engine.importChunk({
+ operationId: opId,
+ chunkIndex: 0,
+ payload: JSON.stringify([{ id: 1 }, { id: 2 }]),
+ });
+ expect(chunk0.insertedCount).toBe(2);
+ expect(mockCollection.insertMany).toHaveBeenCalledTimes(2);
+ });
+
+ test("handles duplicate key partial failures with ordered: false", async () => {
+ mockCollection.insertMany.mockRejectedValueOnce({
+ name: "MongoBulkWriteError",
+ insertedCount: 1,
+ writeErrors: [
+ {
+ index: 1,
+ code: 11000,
+ errmsg:
+ "E11000 duplicate key error collection: test.items index: _id_ dup key: { _id: 2 }",
+ },
+ ],
+ });
+
+ const startRes = await engine.importStart({
+ dbId: "db-1",
+ collection: "items",
+ format: "json",
+ });
+
+ const chunkRes = await engine.importChunk({
+ operationId: startRes.operationId,
+ chunkIndex: 0,
+ payload: JSON.stringify([{ _id: 1 }, { _id: 2 }]),
+ });
+
+ expect(chunkRes.insertedCount).toBe(1);
+ expect(chunkRes.failedCount).toBe(1);
+ expect(chunkRes.errors).toHaveLength(1);
+ expect(chunkRes.errors![0].code).toBe("MONGO_DUPLICATE_KEY");
+ });
+
+ test("cancels active batch writes cleanly between batches", async () => {
+ const startRes = await engine.importStart({
+ dbId: "db-1",
+ collection: "items",
+ format: "json",
+ });
+ const opState = opManager.getOperation(startRes.operationId)!;
+
+ // Abort signal right before batch execution
+ opState.controller.abort();
+
+ await expect(
+ engine.importChunk({
+ operationId: startRes.operationId,
+ chunkIndex: 0,
+ payload: JSON.stringify([{ id: 1 }]),
+ }),
+ ).rejects.toThrow(/Operation was cancelled/);
+ });
+
+ test("enforces read-only database protection on import writes", async () => {
+ jest.spyOn(engine, "getDb").mockResolvedValueOnce({
+ db: { id: "readonly-db", readonly: true },
+ conn: { uri: "mongodb://localhost:27017/test", readonly: true },
+ dbType: DBType.MONGODB,
+ nativeDb: mockNativeDb,
+ });
+
+ await expect(
+ engine.importStart({ dbId: "readonly-db", collection: "items", format: "json" }),
+ ).rejects.toThrow(/Database is in read-only mode/);
+ });
+ });
+
+ // =========================================================================
+ // 4. Cursor Streaming Bulk Export (Zero .toArray())
+ // =========================================================================
+ describe("Export Engine Cursor Streaming", () => {
+ test("streams JSON array directly to file and closes cursor in all paths", async () => {
+ const mockCursorDocs = [
+ { _id: "1", name: "Alpha" },
+ { _id: "2", name: "Beta" },
+ ];
+ let cursorClosed = false;
+
+ const mockCursor = {
+ [Symbol.asyncIterator]: async function* () {
+ for (const doc of mockCursorDocs) {
+ yield doc;
+ }
+ },
+ batchSize: jest.fn().mockReturnThis(),
+ sort: jest.fn().mockReturnThis(),
+ project: jest.fn().mockReturnThis(),
+ limit: jest.fn().mockReturnThis(),
+ close: jest.fn().mockImplementation(async () => {
+ cursorClosed = true;
+ }),
+ };
+ mockCollection.find.mockReturnValue(mockCursor);
+
+ const res = await engine.exportStart({
+ dbId: "test-db",
+ collection: "items",
+ format: "json",
+ });
+
+ expect(res.operationId).toBeDefined();
+
+ // Wait for background stream pipeline to complete
+ for (let i = 0; i < 50; i++) {
+ const opStatus = await engine.getOperationStatus(res.operationId);
+ if (opStatus.status === "completed" || opStatus.status === "failed") break;
+ await new Promise((r) => setTimeout(r, 20));
+ }
+
+ const status = await engine.getOperationStatus(res.operationId);
+ expect(status.status).toBe("completed");
+ expect(status.successfulDocuments).toBe(2);
+ expect(cursorClosed).toBe(true);
+
+ // Verify temp file content
+ const filePath = path.join(EXPORT_DIR, `export-${res.operationId}.json`);
+ expect(fs.existsSync(filePath)).toBe(true);
+ const content = fs.readFileSync(filePath, "utf8");
+ expect(content).toContain('"_id":"1"');
+ expect(content).toContain('"_id":"2"');
+
+ // Cleanup
+ await engine.cleanupOperation(res.operationId);
+ expect(fs.existsSync(filePath)).toBe(false);
+ });
+
+ test("streams CSV with dot-notation flattening and escaping", async () => {
+ const mockCursorDocs = [
+ { _id: "101", user: { name: "Alice", location: "NYC" } },
+ { _id: "102", user: { name: "Bob", location: "SF, CA" } },
+ ];
+
+ const mockCursor = {
+ [Symbol.asyncIterator]: async function* () {
+ for (const doc of mockCursorDocs) {
+ yield doc;
+ }
+ },
+ batchSize: jest.fn().mockReturnThis(),
+ close: jest.fn().mockResolvedValue(undefined),
+ };
+ mockCollection.find.mockReturnValue(mockCursor);
+
+ const res = await engine.exportStart({
+ dbId: "test-db",
+ collection: "users",
+ format: "csv",
+ });
+
+ // Wait for background stream pipeline to complete
+ for (let i = 0; i < 50; i++) {
+ const opStatus = await engine.getOperationStatus(res.operationId);
+ if (opStatus.status === "completed" || opStatus.status === "failed") break;
+ await new Promise((r) => setTimeout(r, 20));
+ }
+
+ const filePath = path.join(EXPORT_DIR, `export-${res.operationId}.csv`);
+ expect(fs.existsSync(filePath)).toBe(true);
+ const csv = fs.readFileSync(filePath, "utf8");
+
+ expect(csv).toContain("_id,user.location,user.name");
+ expect(csv).toContain('"SF, CA"'); // Escaped comma
+
+ await engine.cleanupOperation(res.operationId);
+ });
+ });
+
+ // =========================================================================
+ // 5. Supporting Bulk Mutations
+ // =========================================================================
+ describe("Supporting Bulk Mutations", () => {
+ test("bulkInsert rejects > 5,000 documents and protects against prototype pollution", async () => {
+ const oversized = new Array(MAX_BULK_INSERT_DOCS + 1).fill({ a: 1 });
+ await expect(
+ engine.bulkInsert({ dbId: "test-db", collection: "items", documents: oversized }),
+ ).rejects.toThrow(/exceeds maximum allowed of 5000/);
+
+ const polluted = [{ normal: true }, JSON.parse('{"__proto__": {"admin": true}}')];
+ await expect(
+ engine.bulkInsert({ dbId: "test-db", collection: "items", documents: polluted }),
+ ).rejects.toThrow(/Prototype pollution/);
+ });
+
+ test("bulkUpdate enforces operator document ($) and restricts empty filter", async () => {
+ // Must start with $
+ await expect(
+ engine.bulkUpdate({
+ dbId: "test-db",
+ collection: "items",
+ filter: { status: "pending" },
+ update: { status: "processed" }, // Missing $set!
+ }),
+ ).rejects.toThrow(/top-level operators must begin with '\$'/);
+
+ // Empty filter without allowUnrestricted is forbidden
+ await expect(
+ engine.bulkUpdate({
+ dbId: "test-db",
+ collection: "items",
+ filter: {},
+ update: { $set: { status: "processed" } },
+ }),
+ ).rejects.toThrow(/allowUnrestricted: true/);
+
+ // Empty filter with allowUnrestricted emits advisory warning
+ const res = await engine.bulkUpdate({
+ dbId: "test-db",
+ collection: "items",
+ filter: {},
+ update: { $set: { status: "processed" } },
+ options: { allowUnrestricted: true },
+ });
+ expect(res.advisoryWarning).toContain("Unrestricted bulk update");
+ });
+
+ test("bulkDelete restricts empty filter and emits advisory warning when deletedCount > 100", async () => {
+ // Empty filter without allowUnrestricted is forbidden
+ await expect(
+ engine.bulkDelete({
+ dbId: "test-db",
+ collection: "items",
+ filter: {},
+ }),
+ ).rejects.toThrow(/allowUnrestricted: true/);
+
+ // Large delete count warning
+ mockCollection.deleteMany.mockResolvedValueOnce({ deletedCount: 150 });
+ const res = await engine.bulkDelete({
+ dbId: "test-db",
+ collection: "items",
+ filter: { obsolete: true },
+ });
+ expect(res.deletedCount).toBe(150);
+ expect(res.advisoryWarning).toContain(
+ "Broad delete operation affected more than 100 documents",
+ );
+ });
+ });
+
+ // =========================================================================
+ // 5. M7 Phase 4: Stage 1 Export Save-To & Staging Cleanup Tests
+ // =========================================================================
+ describe("M7 Phase 4: Stage 1 Export Save-To & Staging Cleanup", () => {
+ let testDestDir: string;
+ const createdExportFiles: string[] = [];
+
+ beforeEach(() => {
+ testDestDir = fs.mkdtempSync(path.join(os.tmpdir(), "relwave-test-dest-"));
+ });
+
+ afterEach(() => {
+ jest.restoreAllMocks();
+ try {
+ fs.rmSync(testDestDir, { recursive: true, force: true });
+ } catch {}
+ for (const f of createdExportFiles) {
+ try {
+ if (fs.existsSync(f)) fs.unlinkSync(f);
+ } catch {}
+ }
+ createdExportFiles.length = 0;
+ opManager.clearPendingStagingCleanups();
+ });
+
+ function createCompletedExport(format = "json", content = '{"test":123}') {
+ const state = opManager.createOperation("export", "test-db", "users", format as any);
+ const id = state.operation.operationId;
+ opManager.transition(id, "in_progress");
+
+ if (!fs.existsSync(EXPORT_DIR)) {
+ fs.mkdirSync(EXPORT_DIR, { recursive: true });
+ }
+ const sourceFilePath = path.join(EXPORT_DIR, `${id}.${format}`);
+ fs.writeFileSync(sourceFilePath, content, "utf8");
+ createdExportFiles.push(sourceFilePath);
+
+ state.operation.tempFilePath = sourceFilePath;
+ state.operation.fileSizeBytes = Buffer.byteLength(content, "utf8");
+ opManager.transition(id, "completed");
+
+ return { id, state, sourceFilePath };
+ }
+
+ // -----------------------------------------------------------------------
+ // Validation & Safety Checks
+ // -----------------------------------------------------------------------
+ describe("Validation & Safety Checks", () => {
+ test("rejects relative or whitespace destinationPath", async () => {
+ const { id } = createCompletedExport();
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: "relative/path.json" }),
+ ).rejects.toThrow(/destinationPath must be a non-empty absolute path/);
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: " " }),
+ ).rejects.toThrow(/destinationPath must be a non-empty absolute path/);
+ });
+
+ test("rejects non-existent or inaccessible parent directory", async () => {
+ const { id } = createCompletedExport();
+ const nonExistentDir = path.join(testDestDir, "does-not-exist", "export.json");
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: nonExistentDir }),
+ ).rejects.toThrow(/Parent directory does not exist or is not accessible/);
+ });
+
+ test("rejects non-export operations", async () => {
+ const importOp = opManager.createOperation("import", "test-db", "users", "json");
+ opManager.transition(importOp.operation.operationId, "in_progress");
+ opManager.transition(importOp.operation.operationId, "completed");
+
+ await expect(
+ engine.exportSaveTo({
+ operationId: importOp.operation.operationId,
+ destinationPath: path.join(testDestDir, "out.json"),
+ }),
+ ).rejects.toThrow(/Cannot save: operation is not an export/);
+ });
+
+ test("rejects non-completed export operations", async () => {
+ const state = opManager.createOperation("export", "test-db", "users", "json");
+ await expect(
+ engine.exportSaveTo({
+ operationId: state.operation.operationId,
+ destinationPath: path.join(testDestDir, "out.json"),
+ }),
+ ).rejects.toThrow(
+ /Cannot save export file: operation status is 'pending', expected 'completed'/,
+ );
+ });
+
+ test("rejects missing export source temporary file", async () => {
+ const { id, sourceFilePath } = createCompletedExport();
+ fs.unlinkSync(sourceFilePath);
+
+ await expect(
+ engine.exportSaveTo({
+ operationId: id,
+ destinationPath: path.join(testDestDir, "out.json"),
+ }),
+ ).rejects.toThrow(/Export source temporary file does not exist/);
+ });
+ });
+
+ // -----------------------------------------------------------------------
+ // Destination Inspection & Type Discrimination
+ // -----------------------------------------------------------------------
+ describe("Destination Inspection & Type Discrimination", () => {
+ test("proceeds when destination does not exist (ENOENT)", async () => {
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "new-file.json");
+
+ // Spy on link to simulate success
+ jest.spyOn(fs.promises, "link").mockImplementation(async (src, target) => {
+ fs.copyFileSync(src as string, target as string);
+ });
+
+ const res = await engine.exportSaveTo({ operationId: id, destinationPath: dest });
+ expect(res.success).toBe(true);
+ expect(res.destinationPath).toBe(path.normalize(dest));
+ expect(res.bytesWritten).toBeGreaterThan(0);
+ expect(res.warning).toBeUndefined();
+ });
+
+ test("rejects when destination inspection throws EACCES or EIO", async () => {
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "forbidden.json");
+
+ const lstatSpy = jest.spyOn(fs.promises, "lstat").mockImplementation(async (p) => {
+ if (p === path.normalize(dest)) {
+ const err: any = new Error("Permission denied");
+ err.code = "EACCES";
+ throw err;
+ }
+ return lstatSpy.getMockImplementation()!(p);
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(/Failed to inspect destination path \(EACCES\)/);
+ });
+
+ test("rejects when destination is an existing directory", async () => {
+ const { id } = createCompletedExport();
+ const dirDest = path.join(testDestDir, "sub-dir");
+ fs.mkdirSync(dirDest);
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dirDest }),
+ ).rejects.toThrow(
+ /Destination is an existing directory; cannot overwrite a directory with a file/,
+ );
+ });
+
+ test("rejects when destination is a special device", async () => {
+ const { id } = createCompletedExport();
+ const specialDest = path.join(testDestDir, "special-dev");
+
+ jest.spyOn(fs.promises, "lstat").mockImplementation(async (p) => {
+ if (p === path.normalize(specialDest)) {
+ return {
+ isFile: () => false,
+ isDirectory: () => false,
+ isFIFO: () => true,
+ isSocket: () => false,
+ isBlockDevice: () => false,
+ isCharacterDevice: () => false,
+ isSymbolicLink: () => false,
+ } as any;
+ }
+ return fs.lstatSync(p);
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: specialDest }),
+ ).rejects.toThrow(/Destination is a special device or socket/);
+ });
+
+ test("rejects existing destination when overwrite !== true", async () => {
+ const { id } = createCompletedExport();
+ const existingDest = path.join(testDestDir, "existing.json");
+ fs.writeFileSync(existingDest, "old content", "utf8");
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: existingDest }),
+ ).rejects.toThrow(/Destination file already exists/);
+ });
+
+ test("existing destination symlink with overwrite false throws MONGO_FILE_EXISTS", async () => {
+ const { id } = createCompletedExport();
+ const targetFile = path.join(testDestDir, "target-false.txt");
+ fs.writeFileSync(targetFile, "target data", "utf8");
+ const destSymlink = path.join(testDestDir, "link-to-target-false.json");
+
+ let realSymlinkCreated = false;
+ try {
+ fs.symlinkSync(targetFile, destSymlink, "file");
+ realSymlinkCreated = true;
+ } catch {}
+
+ if (!realSymlinkCreated) {
+ jest.spyOn(fs.promises, "lstat").mockImplementation(async (p) => {
+ if (p === path.normalize(destSymlink)) {
+ return {
+ isFile: () => false,
+ isDirectory: () => false,
+ isSymbolicLink: () => true,
+ isFIFO: () => false,
+ isSocket: () => false,
+ isBlockDevice: () => false,
+ isCharacterDevice: () => false,
+ } as any;
+ }
+ return fs.lstatSync(p);
+ });
+ }
+
+ await expect(
+ engine.exportSaveTo({
+ operationId: id,
+ destinationPath: destSymlink,
+ options: { overwrite: false },
+ }),
+ ).rejects.toThrow(/Destination file already exists/);
+
+ expect(fs.readFileSync(targetFile, "utf8")).toBe("target data");
+ });
+ });
+
+ // -----------------------------------------------------------------------
+ // Atomic Publication Commit & Decoupled Cleanup (overwrite: false)
+ // -----------------------------------------------------------------------
+ describe("Atomic Publication Commit & Decoupled Cleanup (overwrite: false)", () => {
+ test("hard-link publication succeeds with clean staging unlink", async () => {
+ const { id } = createCompletedExport("json", '{"a":1}');
+ const dest = path.join(testDestDir, "linked.json");
+
+ jest.spyOn(fs.promises, "link").mockImplementation(async (src, target) => {
+ fs.copyFileSync(src as string, target as string);
+ });
+
+ const res = await engine.exportSaveTo({ operationId: id, destinationPath: dest });
+ expect(res.success).toBe(true);
+ expect(res.warning).toBeUndefined();
+ expect(fs.existsSync(dest)).toBe(true);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("hard-link publication succeeds but post-publication staging unlink fails", async () => {
+ const { id, sourceFilePath } = createCompletedExport("json", '{"b":2}');
+ const dest = path.join(testDestDir, "linked-warn.json");
+
+ jest.spyOn(fs.promises, "link").mockImplementation(async (src, target) => {
+ fs.copyFileSync(src as string, target as string);
+ });
+
+ // Spy on unlink to fail on staging file
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ const err: any = new Error("Resource busy");
+ err.code = "EBUSY";
+ throw err;
+ }
+ return origUnlink(p);
+ });
+
+ const res = await engine.exportSaveTo({ operationId: id, destinationPath: dest });
+ expect(res.success).toBe(true);
+ expect(res.warning).toContain("queued for identity-verified retry cleanup");
+ expect(fs.existsSync(dest)).toBe(true);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ expect(fs.existsSync(sourceFilePath)).toBe(true); // source retained
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(1);
+ });
+
+ test("pre-publication link collision (EEXIST) throws MONGO_FILE_EXISTS and unlinks staging", async () => {
+ const { id, sourceFilePath } = createCompletedExport();
+ const dest = path.join(testDestDir, "collision.json");
+
+ let stagingPathUnlinked: string | null = null;
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ stagingPathUnlinked = p;
+ }
+ return origUnlink(p);
+ });
+
+ jest.spyOn(fs.promises, "link").mockImplementation(async () => {
+ const err: any = new Error("File exists");
+ err.code = "EEXIST";
+ throw err;
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(/Destination file already exists/);
+
+ expect(stagingPathUnlinked).not.toBeNull();
+ expect(fs.existsSync(sourceFilePath)).toBe(true); // source preserved
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("pre-publication link failure on confirmed unsupported filesystem (ENOSYS) throws MONGO_UNSUPPORTED_FILESYSTEM without copyFile fallback", async () => {
+ const { id, sourceFilePath } = createCompletedExport();
+ const dest = path.join(testDestDir, "unsupported.json");
+
+ jest.spyOn(fs.promises, "link").mockImplementation(async () => {
+ const err: any = new Error("Function not implemented");
+ err.code = "ENOSYS";
+ throw err;
+ });
+
+ const copyFileSpy = jest.spyOn(fs.promises, "copyFile");
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(
+ /The destination filesystem does not support atomic hard-link publication/,
+ );
+
+ expect(copyFileSpy).not.toHaveBeenCalled();
+ expect(fs.existsSync(dest)).toBe(false);
+ expect(fs.existsSync(sourceFilePath)).toBe(true);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("pre-publication link failure with EPERM or EACCES throws MONGO_SAVE_FAILED without claiming unsupported filesystem", async () => {
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "perm-denied.json");
+
+ jest.spyOn(fs.promises, "link").mockImplementation(async () => {
+ const err: any = new Error("Operation not permitted");
+ err.code = "EPERM";
+ throw err;
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(
+ /Permission denied or operation not permitted during hard-link publication \(EPERM\)/,
+ );
+ });
+
+ test("pre-publication link failure with EXDEV throws MONGO_SAVE_FAILED without claiming unsupported filesystem", async () => {
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "cross-dev.json");
+
+ jest.spyOn(fs.promises, "link").mockImplementation(async () => {
+ const err: any = new Error("Cross-device link");
+ err.code = "EXDEV";
+ throw err;
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(/Cross-device link error \(EXDEV\)/);
+ });
+
+ test("pre-publication link failure where staging cleanup fails preserves original link error and records identity", async () => {
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "double-fail.json");
+
+ jest.spyOn(fs.promises, "link").mockImplementation(async () => {
+ const err: any = new Error("File exists");
+ err.code = "EEXIST";
+ throw err;
+ });
+
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async () => {
+ const err: any = new Error("Access denied on unlink");
+ err.code = "EACCES";
+ throw err;
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(/Destination file already exists/);
+
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(1);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+ });
+
+ // -----------------------------------------------------------------------
+ // Atomic Replacement (overwrite: true)
+ // -----------------------------------------------------------------------
+ describe("Atomic Replacement (overwrite: true)", () => {
+ test("atomic rename replaces destination directly and skips staging unlink", async () => {
+ const { id } = createCompletedExport("json", '{"version":2}');
+ const dest = path.join(testDestDir, "overwrite-target.json");
+ fs.writeFileSync(dest, '{"version":1}', "utf8");
+
+ const unlinkSpy = jest.spyOn(fs.promises, "unlink");
+
+ const res = await engine.exportSaveTo({
+ operationId: id,
+ destinationPath: dest,
+ options: { overwrite: true },
+ });
+
+ expect(res.success).toBe(true);
+ expect(res.warning).toBeUndefined();
+ expect(fs.readFileSync(dest, "utf8")).toBe('{"version":2}');
+ // unlink should NOT be called for staging file because rename already consumed it
+ for (const call of unlinkSpy.mock.calls) {
+ expect(String(call[0])).not.toContain(".relwave-tmp-");
+ }
+ });
+
+ test("post-commit audit failure surfaces advisory warning without failing operation", async () => {
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "post-audit-warn.json");
+
+ // Make rename succeed, but post-commit lstat on dest return non-file
+ const realLstat = fs.promises.lstat;
+ let renameCommitted = false;
+ jest.spyOn(fs.promises, "rename").mockImplementation(async (src, target) => {
+ fs.copyFileSync(src as string, target as string);
+ fs.unlinkSync(src as string);
+ renameCommitted = true;
+ });
+
+ jest.spyOn(fs.promises, "lstat").mockImplementation(async (p) => {
+ if (renameCommitted && p === path.normalize(dest)) {
+ return {
+ isFile: () => false,
+ isDirectory: () => true,
+ isSymbolicLink: () => false,
+ } as any;
+ }
+ return realLstat(p);
+ });
+
+ const res = await engine.exportSaveTo({
+ operationId: id,
+ destinationPath: dest,
+ options: { overwrite: true },
+ });
+
+ expect(res.success).toBe(true);
+ expect(res.warning).toContain("post-commit audit detected unexpected file attributes");
+ });
+
+ test("pre-publication rename failure throws MONGO_SAVE_FAILED and unlinks staging", async () => {
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "rename-fail.json");
+
+ let stagingUnlinked = false;
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ stagingUnlinked = true;
+ }
+ return origUnlink(p);
+ });
+
+ jest.spyOn(fs.promises, "rename").mockImplementation(async () => {
+ const err: any = new Error("Device locked");
+ err.code = "EBUSY";
+ throw err;
+ });
+
+ await expect(
+ engine.exportSaveTo({
+ operationId: id,
+ destinationPath: dest,
+ options: { overwrite: true },
+ }),
+ ).rejects.toThrow(/Failed to atomically replace destination file \(EBUSY\)/);
+
+ expect(stagingUnlinked).toBe(true);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("existing destination symlink with overwrite true: rename replaces the symlink entry itself, while external target remains unchanged", async () => {
+ const { id } = createCompletedExport("json", '{"newData":true}');
+ const targetFile = path.join(testDestDir, "target-true.txt");
+ fs.writeFileSync(targetFile, "original target content", "utf8");
+ const destSymlink = path.join(testDestDir, "dest-symlink-true.json");
+
+ let realSymlinkCreated = false;
+ try {
+ fs.symlinkSync(targetFile, destSymlink, "file");
+ realSymlinkCreated = true;
+ } catch {}
+
+ if (realSymlinkCreated) {
+ const res = await engine.exportSaveTo({
+ operationId: id,
+ destinationPath: destSymlink,
+ options: { overwrite: true },
+ });
+ expect(res.success).toBe(true);
+ expect(fs.lstatSync(destSymlink).isSymbolicLink()).toBe(false);
+ expect(fs.readFileSync(destSymlink, "utf8")).toBe('{"newData":true}');
+ expect(fs.readFileSync(targetFile, "utf8")).toBe("original target content");
+ } else {
+ let renameTargetPassed: string | null = null;
+ jest.spyOn(fs.promises, "lstat").mockImplementation(async (p) => {
+ if (p === path.normalize(destSymlink)) {
+ return {
+ isFile: () => false,
+ isDirectory: () => false,
+ isSymbolicLink: () => true,
+ isFIFO: () => false,
+ isSocket: () => false,
+ isBlockDevice: () => false,
+ isCharacterDevice: () => false,
+ } as any;
+ }
+ return fs.lstatSync(p);
+ });
+ jest.spyOn(fs.promises, "rename").mockImplementation(async (src, target) => {
+ renameTargetPassed = target as string;
+ fs.copyFileSync(src as string, target as string);
+ fs.unlinkSync(src as string);
+ });
+
+ const res = await engine.exportSaveTo({
+ operationId: id,
+ destinationPath: destSymlink,
+ options: { overwrite: true },
+ });
+ expect(res.success).toBe(true);
+ expect(renameTargetPassed).toBe(path.normalize(destSymlink));
+ expect(fs.readFileSync(targetFile, "utf8")).toBe("original target content");
+ }
+ });
+
+ test("directory appearing between destination inspection and rename throws MONGO_SAVE_FAILED", async () => {
+ const { id, sourceFilePath } = createCompletedExport();
+ const dest = path.join(testDestDir, "race-dir-dest.json");
+
+ jest.spyOn(fs.promises, "rename").mockImplementation(async () => {
+ const err: any = new Error("Is a directory");
+ err.code = "EISDIR";
+ throw err;
+ });
+
+ let stagingUnlinked = false;
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ stagingUnlinked = true;
+ }
+ return origUnlink(p);
+ });
+
+ await expect(
+ engine.exportSaveTo({
+ operationId: id,
+ destinationPath: dest,
+ options: { overwrite: true },
+ }),
+ ).rejects.toThrow(/Failed to atomically replace destination file \(EISDIR\)/);
+
+ expect(stagingUnlinked).toBe(true);
+ expect(fs.existsSync(sourceFilePath)).toBe(true);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("post-commit audit lstat throwing an error returns success with an advisory warning", async () => {
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "audit-throw.json");
+
+ let renameCommitted = false;
+ jest.spyOn(fs.promises, "rename").mockImplementation(async (src, target) => {
+ fs.copyFileSync(src as string, target as string);
+ fs.unlinkSync(src as string);
+ renameCommitted = true;
+ });
+
+ const realLstat = fs.promises.lstat;
+ jest.spyOn(fs.promises, "lstat").mockImplementation(async (p) => {
+ if (renameCommitted && p === path.normalize(dest)) {
+ const err: any = new Error("Resource temporarily locked");
+ err.code = "EBUSY";
+ throw err;
+ }
+ return realLstat(p);
+ });
+
+ const res = await engine.exportSaveTo({
+ operationId: id,
+ destinationPath: dest,
+ options: { overwrite: true },
+ });
+
+ expect(res.success).toBe(true);
+ expect(res.warning).toContain("post-commit verification failed (EBUSY)");
+ expect(fs.existsSync(dest)).toBe(true);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+ });
+
+ // -----------------------------------------------------------------------
+ // Streaming Lifecycle & Staging Failure Handling
+ // -----------------------------------------------------------------------
+ describe("Streaming Lifecycle & Staging Failure Handling", () => {
+ test("stream failure followed by successful staging unlink", async () => {
+ const { id, sourceFilePath } = createCompletedExport();
+ const dest = path.join(testDestDir, "stream-fail-unlink-ok.json");
+
+ let stagingUnlinked = false;
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ stagingUnlinked = true;
+ }
+ return origUnlink(p);
+ });
+
+ jest.spyOn(fs, "createReadStream").mockImplementationOnce(() => {
+ throw new Error("Disk I/O error during read");
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(
+ /Failed to stream export data to staging file: Disk I\/O error during read/,
+ );
+
+ expect(stagingUnlinked).toBe(true);
+ expect(fs.existsSync(sourceFilePath)).toBe(true); // Source file preserved
+ expect(fs.existsSync(dest)).toBe(false); // Destination never published
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(0);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("stream failure followed by staging unlink failure and successful queue registration", async () => {
+ const { id, sourceFilePath } = createCompletedExport();
+ const dest = path.join(testDestDir, "stream-fail-unlink-fail.json");
+
+ jest.spyOn(fs, "createReadStream").mockImplementationOnce(() => {
+ throw new Error("Read stream broken pipe");
+ });
+
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ const err: any = new Error("File locked by process");
+ err.code = "EBUSY";
+ throw err;
+ }
+ return origUnlink(p);
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(/Failed to stream export data to staging file: Read stream broken pipe/);
+
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(1);
+ expect(fs.existsSync(sourceFilePath)).toBe(true);
+ expect(fs.existsSync(dest)).toBe(false);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("stream failure where identity capture also fails", async () => {
+ const { id, sourceFilePath } = createCompletedExport();
+ const dest = path.join(testDestDir, "stream-id-capture-fail.json");
+
+ jest.spyOn(fs, "createReadStream").mockImplementationOnce(() => {
+ throw new Error("Stream abort error");
+ });
+
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ const err: any = new Error("Unlink failed");
+ err.code = "EACCES";
+ throw err;
+ }
+ return origUnlink(p);
+ });
+
+ const origLstat = fs.promises.lstat;
+ jest.spyOn(fs.promises, "lstat").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ const err: any = new Error("Cannot lstat staging file");
+ err.code = "EPERM";
+ throw err;
+ }
+ return origLstat(p);
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(/Failed to stream export data to staging file: Stream abort error/);
+
+ // Identity capture failed -> registered with fail-closed identity (dev: 0, ino: 0)
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(1);
+ const entries = Array.from((opManager as any).pendingStagingCleanups.values()) as any[];
+ expect(entries[0].dev).toBe(0);
+ expect(entries[0].ino).toBe(0);
+
+ expect(fs.existsSync(sourceFilePath)).toBe(true);
+ expect(fs.existsSync(dest)).toBe(false);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("stream failure where cleanup queue capacity is exhausted", async () => {
+ const { id, sourceFilePath } = createCompletedExport();
+ const dest = path.join(testDestDir, "stream-queue-full.json");
+
+ // Fill queue to capacity (100)
+ for (let i = 0; i < 100; i++) {
+ opManager.recordPendingStagingCleanup(`/tmp/stream-full-${i}.tmp`);
+ }
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(100);
+
+ jest.spyOn(fs, "createReadStream").mockImplementationOnce(() => {
+ throw new Error("Premature stream EOF");
+ });
+
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ const err: any = new Error("Unlink failed");
+ err.code = "EBUSY";
+ throw err;
+ }
+ return origUnlink(p);
+ });
+
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: dest }),
+ ).rejects.toThrow(/Failed to stream export data to staging file: Premature stream EOF/);
+
+ // Queue refused 101st entry and retained capacity 100
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(100);
+ expect(fs.existsSync(sourceFilePath)).toBe(true);
+ expect(fs.existsSync(dest)).toBe(false);
+ expect(opManager.getOperation(id)?.isSaving).toBe(false);
+ });
+
+ test("every stream failure preserves the original error classification and releases the lock", async () => {
+ const { id, state, sourceFilePath } = createCompletedExport();
+ const dest = path.join(testDestDir, "stream-preserve-err.json");
+
+ jest.spyOn(fs, "createReadStream").mockImplementationOnce(() => {
+ throw new Error("Specific custom streaming corruption error");
+ });
+
+ let caughtErr: any;
+ try {
+ await engine.exportSaveTo({ operationId: id, destinationPath: dest });
+ } catch (e) {
+ caughtErr = e;
+ }
+
+ expect(caughtErr).toBeDefined();
+ expect(caughtErr.code).toBe("MONGO_SAVE_FAILED");
+ expect(caughtErr.message).toContain("Specific custom streaming corruption error");
+ expect(state.isSaving).toBe(false);
+ expect(fs.existsSync(sourceFilePath)).toBe(true);
+ });
+ });
+
+ // -----------------------------------------------------------------------
+ // Universal Mutex & Lock Release Across All Paths
+ // -----------------------------------------------------------------------
+ describe("Universal Mutex & Lock Release Across All Paths", () => {
+ test("rejects concurrent save while save is active", async () => {
+ const { id, state } = createCompletedExport();
+ state.isSaving = true;
+
+ await expect(
+ engine.exportSaveTo({
+ operationId: id,
+ destinationPath: path.join(testDestDir, "concurrent.json"),
+ }),
+ ).rejects.toThrow(/Another save operation is already in progress/);
+
+ state.isSaving = false;
+ });
+
+ test("active save blocks cancelOperation and cleanupOperation", () => {
+ const { id, state } = createCompletedExport();
+ state.isSaving = true;
+
+ expect(() => opManager.cancel(id)).toThrow(
+ /Cannot cancel an export operation that is currently saving/,
+ );
+
+ expect(() => opManager.cleanup(id)).toThrow(
+ /Cannot clean up an export operation that is currently saving/,
+ );
+
+ state.isSaving = false;
+ });
+
+ test("lock is released in finally across multiple failure paths", async () => {
+ const { id, state } = createCompletedExport();
+
+ // 1. Validation failure
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: "relative.json" }),
+ ).rejects.toThrow();
+ expect(state.isSaving ?? false).toBe(false);
+
+ // 2. Inspection failure
+ const badDest = path.join(testDestDir, "bad-dir");
+ fs.mkdirSync(badDest);
+ await expect(
+ engine.exportSaveTo({ operationId: id, destinationPath: badDest }),
+ ).rejects.toThrow();
+ expect(state.isSaving).toBe(false);
+
+ // 3. Link collision
+ jest.spyOn(fs.promises, "link").mockRejectedValueOnce({ code: "EEXIST" });
+ await expect(
+ engine.exportSaveTo({
+ operationId: id,
+ destinationPath: path.join(testDestDir, "link-fail.json"),
+ }),
+ ).rejects.toThrow();
+ expect(state.isSaving).toBe(false);
+
+ // 4. Stream error
+ jest.spyOn(fs, "createReadStream").mockImplementationOnce(() => {
+ throw new Error("Stream read error");
+ });
+ await expect(
+ engine.exportSaveTo({
+ operationId: id,
+ destinationPath: path.join(testDestDir, "stream-fail.json"),
+ }),
+ ).rejects.toThrow();
+ expect(state.isSaving).toBe(false);
+ });
+ });
+
+ // -----------------------------------------------------------------------
+ // Bounded Staging Cleanup Queue & Capacity Overflow
+ // -----------------------------------------------------------------------
+ describe("Bounded Staging Cleanup Queue & Capacity Overflow", () => {
+ test("records identity up to 100 entries and refuses beyond capacity", () => {
+ for (let i = 0; i < 100; i++) {
+ const tracked = opManager.recordPendingStagingCleanup(`/tmp/staging-${i}.tmp`);
+ expect(tracked).toBe(true);
+ }
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(100);
+
+ // 101st entry must be refused and return false
+ const overflowResult = opManager.recordPendingStagingCleanup("/tmp/staging-overflow.tmp");
+ expect(overflowResult).toBe(false);
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(100);
+ });
+
+ test("duplicate path registration is an idempotent no-op preserving authoritative identity", () => {
+ const initialIdentity = {
+ exactPath: "/tmp/staging-dup.tmp",
+ dev: 111,
+ ino: 222,
+ size: 500,
+ birthtimeMs: 12345,
+ registeredAt: 1000,
+ retryCount: 0,
+ };
+
+ const res1 = opManager.recordPendingStagingCleanup("/tmp/staging-dup.tmp", initialIdentity);
+ expect(res1).toBe(true);
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(1);
+
+ // Re-register with different metadata
+ const modifiedIdentity = {
+ exactPath: "/tmp/staging-dup.tmp",
+ dev: 999,
+ ino: 888,
+ size: 1000,
+ birthtimeMs: 54321,
+ registeredAt: 2000,
+ retryCount: 1,
+ };
+ const res2 = opManager.recordPendingStagingCleanup(
+ "/tmp/staging-dup.tmp",
+ modifiedIdentity,
+ );
+ expect(res2).toBe(true);
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(1);
+
+ // Original identity metadata MUST be preserved!
+ const recorded = opManager.getPendingStagingCleanup("/tmp/staging-dup.tmp");
+ expect(recorded?.dev).toBe(111);
+ expect(recorded?.ino).toBe(222);
+ expect(recorded?.size).toBe(500);
+ });
+
+ test("post-publication save surfaces distinct overflow warning when queue is at capacity", async () => {
+ // Fill queue to 100
+ for (let i = 0; i < 100; i++) {
+ opManager.recordPendingStagingCleanup(`/tmp/full-${i}.tmp`);
+ }
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(100);
+
+ const { id } = createCompletedExport();
+ const dest = path.join(testDestDir, "overflow-save.json");
+
+ jest.spyOn(fs.promises, "link").mockImplementation(async (src, target) => {
+ fs.copyFileSync(src as string, target as string);
+ });
+
+ // Fail staging unlink
+ const origUnlink = fs.promises.unlink;
+ jest.spyOn(fs.promises, "unlink").mockImplementation(async (p) => {
+ if (typeof p === "string" && p.includes(".relwave-tmp-")) {
+ const err: any = new Error("Busy");
+ err.code = "EBUSY";
+ throw err;
+ }
+ return origUnlink(p);
+ });
+
+ const res = await engine.exportSaveTo({ operationId: id, destinationPath: dest });
+ expect(res.success).toBe(true); // Publication committed!
+ expect(res.warning).toContain("cleanup queue is at capacity (100)");
+ expect(res.warning).toContain("untracked orphan");
+ });
+ });
+
+ // -----------------------------------------------------------------------
+ // Pre-Retry Identity Verification Loop (sweepExpired)
+ // -----------------------------------------------------------------------
+ describe("Pre-Retry Identity Verification Loop (sweepExpired)", () => {
+ test("safely unlinks and evicts file when identity matches", async () => {
+ const stagingFile = path.join(testDestDir, "staging-match.tmp");
+ fs.writeFileSync(stagingFile, "staging data", "utf8");
+ const st = fs.lstatSync(stagingFile);
+
+ opManager.recordPendingStagingCleanup(stagingFile, {
+ exactPath: stagingFile,
+ dev: st.dev,
+ ino: st.ino,
+ size: st.size,
+ registeredAt: Date.now(),
+ retryCount: 0,
+ });
+
+ await opManager.sweepExpired();
+ expect(fs.existsSync(stagingFile)).toBe(false);
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(0);
+ });
+
+ test("safely evicts absent file (ENOENT)", async () => {
+ const nonExistent = path.join(testDestDir, "absent.tmp");
+ opManager.recordPendingStagingCleanup(nonExistent, {
+ exactPath: nonExistent,
+ dev: 123,
+ ino: 456,
+ size: 100,
+ registeredAt: Date.now(),
+ retryCount: 0,
+ });
+
+ await opManager.sweepExpired();
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(0);
+ });
+
+ test("aborts unlinking, preserves file on disk, and evicts from tracking on identity mismatch", async () => {
+ const stagingFile = path.join(testDestDir, "staging-mismatch.tmp");
+ fs.writeFileSync(stagingFile, "real file", "utf8");
+ const st = fs.lstatSync(stagingFile);
+
+ opManager.recordPendingStagingCleanup(stagingFile, {
+ exactPath: stagingFile,
+ dev: st.dev,
+ ino: st.ino + 9999, // mismatched inode!
+ size: st.size,
+ registeredAt: Date.now(),
+ retryCount: 0,
+ });
+
+ await opManager.sweepExpired();
+ // File on disk MUST be untouched!
+ expect(fs.existsSync(stagingFile)).toBe(true);
+ expect(fs.readFileSync(stagingFile, "utf8")).toBe("real file");
+ // Evicted from automated tracking!
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(0);
+ });
+
+ test("aborts unlinking, preserves symlink on disk, and evicts from tracking on symlink detection", async () => {
+ const stagingFile = path.join(testDestDir, "staging-symlink.tmp");
+ const realTarget = path.join(testDestDir, "target.txt");
+ fs.writeFileSync(realTarget, "target content", "utf8");
+
+ // Mock lstat to report symlink
+ jest.spyOn(fs.promises, "lstat").mockImplementation(async (p) => {
+ if (p === stagingFile) {
+ return {
+ isFile: () => false,
+ isSymbolicLink: () => true,
+ isDirectory: () => false,
+ dev: 100,
+ ino: 200,
+ } as any;
+ }
+ return fs.lstatSync(p);
+ });
+
+ opManager.recordPendingStagingCleanup(stagingFile, {
+ exactPath: stagingFile,
+ dev: 100,
+ ino: 200,
+ size: 10,
+ registeredAt: Date.now(),
+ retryCount: 0,
+ });
+
+ await opManager.sweepExpired();
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(0);
+ });
+
+ test("fails closed when identity is unpopulated (dev: 0, ino: 0)", async () => {
+ const stagingFile = path.join(testDestDir, "staging-zero-id.tmp");
+ fs.writeFileSync(stagingFile, "content", "utf8");
+
+ opManager.recordPendingStagingCleanup(stagingFile, {
+ exactPath: stagingFile,
+ dev: 0,
+ ino: 0,
+ size: 7,
+ registeredAt: Date.now(),
+ retryCount: 0,
+ });
+
+ await opManager.sweepExpired();
+ expect(fs.existsSync(stagingFile)).toBe(true); // Untouched on disk
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(0); // Evicted from queue
+ });
+
+ test("evicts after 5 failed retry attempts", async () => {
+ const stagingFile = path.join(testDestDir, "staging-locked.tmp");
+ fs.writeFileSync(stagingFile, "locked", "utf8");
+ const st = fs.lstatSync(stagingFile);
+
+ opManager.recordPendingStagingCleanup(stagingFile, {
+ exactPath: stagingFile,
+ dev: st.dev,
+ ino: st.ino,
+ size: st.size,
+ registeredAt: Date.now(),
+ retryCount: 4, // 5th retry attempt
+ });
+
+ jest.spyOn(fs.promises, "unlink").mockRejectedValue(new Error("Still locked"));
+
+ await opManager.sweepExpired();
+ // After 5 retries, abandoned as untracked orphan
+ expect(opManager.getPendingStagingCleanupsCount()).toBe(0);
+ expect(fs.existsSync(stagingFile)).toBe(true);
+ });
+ });
+
+ // -----------------------------------------------------------------------
+ // Export Source Lifecycle & Sweep Coordination
+ // -----------------------------------------------------------------------
+ describe("Export Source Lifecycle & Sweep Coordination", () => {
+ test("sweepExpired skips unlinking while isSaving === true", async () => {
+ const { id, state, sourceFilePath } = createCompletedExport();
+ state.isSaving = true;
+
+ // Force expiration
+ state.operation.expiresAt = new Date(Date.now() - 1000).toISOString();
+
+ await opManager.sweepExpired();
+ expect(fs.existsSync(sourceFilePath)).toBe(true);
+ expect(opManager.getOperation(id)).not.toBeNull();
+
+ state.isSaving = false;
+ });
+
+ test("save completing after TTL expiry commits publication and triggers deferred source eviction", async () => {
+ const { id, state, sourceFilePath } = createCompletedExport("json", '{"expired":true}');
+ const dest = path.join(testDestDir, "expired-save.json");
+
+ // Expire during save while isSaving === true
+ jest.spyOn(fs.promises, "rename").mockImplementation(async (src, target) => {
+ state.operation.expiresAt = new Date(Date.now() - 1000).toISOString();
+ fs.copyFileSync(src as string, target as string);
+ fs.unlinkSync(src as string);
+ });
+
+ const res = await engine.exportSaveTo({
+ operationId: id,
+ destinationPath: dest,
+ options: { overwrite: true },
+ });
+
+ expect(res.success).toBe(true);
+ expect(fs.existsSync(dest)).toBe(true);
+ // Deferred cleanup unlinks source file
+ expect(fs.existsSync(sourceFilePath)).toBe(false);
+ // Operation evicted
+ expect(opManager.getOperation(id)).toBeNull();
+ });
+
+ test("cleanupOperation called after TTL eviction returns alreadyCleaned: true idempotently", async () => {
+ const randomId = "11111111-2222-4333-8444-555555555555";
+ const res = await engine.cleanupOperation(randomId);
+ expect(res.success).toBe(true);
+ expect(res.alreadyCleaned).toBe(true);
+ });
+
+ test("dispose() during an active save does not prematurely unlink the source", () => {
+ const { state, sourceFilePath } = createCompletedExport();
+ state.isSaving = true;
+
+ opManager.dispose();
+
+ // Source file MUST NOT be unlinked!
+ expect(fs.existsSync(sourceFilePath)).toBe(true);
+ // Active save protection is preserved, not forcibly reset
+ expect(state.isSaving).toBe(true);
+
+ state.isSaving = false;
+ });
+ });
+ });
+});
diff --git a/bridge/__tests__/mongoIndex.test.ts b/bridge/__tests__/mongoIndex.test.ts
new file mode 100644
index 00000000..d181c516
--- /dev/null
+++ b/bridge/__tests__/mongoIndex.test.ts
@@ -0,0 +1,1505 @@
+import { describe, expect, test, beforeEach, afterEach, jest } from "@jest/globals";
+import { MongoClient } from "mongodb";
+import {
+ evaluateIndexRedundancy,
+ mongoConnector,
+ MongoApiError,
+ mongodbCache,
+} from "../src/connectors/mongo";
+import { QueryExecutor } from "../src/services/queryExecutor";
+import { IndexHandlers } from "../src/handlers/indexHandlers";
+import { DBType } from "../src/types";
+import type { MongoConfig, MongoIndexDetails } from "../src/types/mongo";
+
+describe("MongoDB Index Management Unit Tests (M6 Spec §3, §9, §11)", () => {
+ const dummyConfig: MongoConfig = {
+ uri: "mongodb://localhost:27017/testdb",
+ database: "testdb",
+ };
+
+ // =========================================================================
+ // 1. evaluateIndexRedundancy
+ // =========================================================================
+ describe("evaluateIndexRedundancy", () => {
+ test("primary key index (_id_) is never marked redundant", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "_id_",
+ key: { _id: 1 },
+ sizeBytes: 4096,
+ unique: true,
+ sparse: false,
+ isIdIndex: true,
+ },
+ {
+ name: "compound_id",
+ key: { _id: 1, email: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated[0].isRedundant).toBe(false);
+ });
+
+ test("non-B-tree indexes (text, 2dsphere, hashed) are never covered by B-tree prefixes", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "text_idx",
+ key: { bio: "text" },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "geo_idx",
+ key: { location: "2dsphere" },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "hashed_idx",
+ key: { userId: "hashed" },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "compound_all",
+ key: { bio: 1, location: 1, userId: 1 },
+ sizeBytes: 12000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "text_idx")?.isRedundant).toBe(false);
+ expect(evaluated.find((i) => i.name === "geo_idx")?.isRedundant).toBe(false);
+ expect(evaluated.find((i) => i.name === "hashed_idx")?.isRedundant).toBe(false);
+ });
+
+ test("hidden compound index cannot make another index redundant", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_user",
+ key: { userId: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_user_status_hidden",
+ key: { userId: 1, status: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ hidden: true,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_user")?.isRedundant).toBe(false);
+ });
+
+ test("compound index covers single-field prefix and flags it as redundant", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_user",
+ key: { userId: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_user_status",
+ key: { userId: 1, status: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ const userIdx = evaluated.find((i) => i.name === "idx_user");
+ expect(userIdx?.isRedundant).toBe(true);
+ expect(userIdx?.redundantReason).toContain('compound index "idx_user_status"');
+ });
+
+ test("compound index covers shorter compound index with matching key order and directions", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_org_dept",
+ key: { orgId: 1, deptId: -1 },
+ sizeBytes: 6000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_org_dept_role",
+ key: { orgId: 1, deptId: -1, role: 1 },
+ sizeBytes: 10000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_org_dept")?.isRedundant).toBe(true);
+ });
+
+ test("compound index with different direction on second key does NOT make prefix redundant", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_org_dept",
+ key: { orgId: 1, deptId: 1 },
+ sizeBytes: 6000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_org_dept_role",
+ key: { orgId: 1, deptId: -1, role: 1 },
+ sizeBytes: 10000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_org_dept")?.isRedundant).toBe(false);
+ });
+
+ test("unique index is NEVER considered redundant with non-unique compound index", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_email_unique",
+ key: { email: 1 },
+ sizeBytes: 4096,
+ unique: true,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_email_created",
+ key: { email: 1, createdAt: -1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_email_unique")?.isRedundant).toBe(false);
+ });
+
+ test("non-sparse index is NOT redundant with sparse compound index", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_phone",
+ key: { phone: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_phone_name_sparse",
+ key: { phone: 1, name: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: true,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_phone")?.isRedundant).toBe(false);
+ });
+
+ test("sparse index IS redundant with non-sparse compound index", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_phone_sparse",
+ key: { phone: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: true,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_phone_name",
+ key: { phone: 1, name: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_phone_sparse")?.isRedundant).toBe(true);
+ });
+
+ test("differing partialFilterExpression prevents redundancy", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_active_users",
+ key: { userId: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ partialFilterExpression: { active: true },
+ },
+ {
+ name: "idx_verified_users",
+ key: { userId: 1, verified: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ partialFilterExpression: { verified: true },
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_active_users")?.isRedundant).toBe(false);
+ });
+
+ test("identical partialFilterExpression allows redundancy", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_active_user",
+ key: { userId: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ partialFilterExpression: { active: true },
+ },
+ {
+ name: "idx_active_user_date",
+ key: { userId: 1, date: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ partialFilterExpression: { active: true },
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_active_user")?.isRedundant).toBe(true);
+ });
+
+ test("differing collation prevents redundancy", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_name_ci",
+ key: { name: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ collation: { locale: "en", strength: 2 },
+ },
+ {
+ name: "idx_name_age_cs",
+ key: { name: 1, age: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ collation: { locale: "en", strength: 3 },
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_name_ci")?.isRedundant).toBe(false);
+ });
+
+ test("compound index with inverted directions (reverse traversal) covers compound prefix", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_rev_prefix",
+ key: { orgId: -1, deptId: 1 },
+ sizeBytes: 6000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_compound_full",
+ key: { orgId: 1, deptId: -1, role: 1 },
+ sizeBytes: 12000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_rev_prefix")?.isRedundant).toBe(true);
+ });
+
+ test("compound other index with special key (text, 2dsphere, hashed) cannot make B-tree prefix redundant", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_category",
+ key: { category: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_category_title_text",
+ key: { category: 1, title: "text" },
+ sizeBytes: 10000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_category_loc_geo",
+ key: { category: 1, loc: "2dsphere" },
+ sizeBytes: 10000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_category_id_hash",
+ key: { category: 1, id: "hashed" },
+ sizeBytes: 10000,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_category")?.isRedundant).toBe(false);
+ });
+
+ test("default collation (undefined) matches explicit simple collation ({ locale: 'simple' })", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_user_default_coll",
+ key: { user: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_user_age_simple_coll",
+ key: { user: 1, age: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ collation: { locale: "simple" },
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_user_default_coll")?.isRedundant).toBe(true);
+ });
+
+ test("default collation (undefined) does NOT match explicit non-simple collation ({ locale: 'en' })", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_user_default_coll",
+ key: { user: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_user_age_en_coll",
+ key: { user: 1, age: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ collation: { locale: "en", strength: 2 },
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_user_default_coll")?.isRedundant).toBe(false);
+ });
+
+ test("partialFilterExpression with differing key order is recognized as equivalent", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_partial_a",
+ key: { status: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ partialFilterExpression: { a: 1, b: 2 },
+ },
+ {
+ name: "idx_partial_b",
+ key: { status: 1, date: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ partialFilterExpression: { b: 2, a: 1 },
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_partial_a")?.isRedundant).toBe(true);
+ });
+
+ test("unique compound candidate does NOT cover shorter non-unique index (conservative constraint boundary)", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_email_non_unique",
+ key: { email: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_email_tenant_unique",
+ key: { email: 1, tenantId: 1 },
+ sizeBytes: 8192,
+ unique: true,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes);
+ expect(evaluated.find((i) => i.name === "idx_email_non_unique")?.isRedundant).toBe(false);
+ });
+
+ test("effective collation: collection default non-simple collation propagates and prevents false redundancy with simple index", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_name_inherited",
+ key: { name: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ // collation omitted: inherits collection default
+ },
+ {
+ name: "idx_name_age_simple",
+ key: { name: 1, age: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ collation: { locale: "simple" },
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes, {
+ collectionDefaultCollation: { locale: "fr", strength: 2 },
+ collectionCollationUnknown: false,
+ });
+ expect(evaluated.find((i) => i.name === "idx_name_inherited")?.isRedundant).toBe(false);
+ });
+
+ test("effective collation: both indexes inherit same collection default and allow redundancy", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_name_inherited",
+ key: { name: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_name_age_inherited",
+ key: { name: 1, age: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes, {
+ collectionDefaultCollation: { locale: "fr", strength: 2 },
+ collectionCollationUnknown: false,
+ });
+ expect(evaluated.find((i) => i.name === "idx_name_inherited")?.isRedundant).toBe(true);
+ });
+
+ test("effective collation: suppresses redundancy when collection collation metadata is unknown", () => {
+ const indexes: MongoIndexDetails[] = [
+ {
+ name: "idx_name_missing_coll",
+ key: { name: 1 },
+ sizeBytes: 4096,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ },
+ {
+ name: "idx_name_age_simple",
+ key: { name: 1, age: 1 },
+ sizeBytes: 8192,
+ unique: false,
+ sparse: false,
+ isIdIndex: false,
+ collation: { locale: "simple" },
+ },
+ ];
+ const evaluated = evaluateIndexRedundancy(indexes, {
+ collectionDefaultCollation: null,
+ collectionCollationUnknown: true, // metadata unavailable
+ });
+ expect(evaluated.find((i) => i.name === "idx_name_missing_coll")?.isRedundant).toBe(false);
+ });
+ });
+
+ // =========================================================================
+ // 2. MongoConnector Index Methods
+ // =========================================================================
+ describe("MongoConnector Index Methods", () => {
+ let mockDb: any;
+ let mockCollection: any;
+ let mockRawIndexes: any[];
+ let mockIndexSizes: Record;
+ let mockTotalIndexSize: number;
+ let mockStatsDocs: any[];
+ let dbSpy: any;
+
+ beforeEach(() => {
+ mockRawIndexes = [
+ { v: 2, key: { _id: 1 }, name: "_id_" },
+ { v: 2, key: { email: 1 }, name: "idx_email", unique: true },
+ { v: 2, key: { email: 1, name: 1 }, name: "idx_email_name" },
+ ];
+ mockIndexSizes = {
+ _id_: 4096,
+ idx_email: 8192,
+ idx_email_name: 12288,
+ };
+ mockTotalIndexSize = 24576;
+ mockStatsDocs = [
+ {
+ name: "idx_email",
+ key: { email: 1 },
+ host: "localhost:27017",
+ accesses: { ops: 50, since: new Date("2026-10-30T00:00:00.000Z") },
+ },
+ ];
+
+ mockCollection = {
+ listIndexes: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockImplementation(() => Promise.resolve(mockRawIndexes)),
+ }),
+ createIndex: jest
+ .fn()
+ .mockImplementation((_key: any, opts: any) =>
+ Promise.resolve(opts?.name || "idx_created"),
+ ),
+ dropIndex: jest.fn().mockImplementation((_name: any) => Promise.resolve({ ok: 1 })),
+ aggregate: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockImplementation(() => Promise.resolve(mockStatsDocs)),
+ }),
+ };
+
+ mockDb = {
+ collection: jest.fn().mockReturnValue(mockCollection),
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ name: "users", options: {} }]),
+ }),
+ command: jest.fn().mockImplementation((cmd: any) => {
+ if (cmd.collStats) {
+ return Promise.resolve({
+ indexSizes: mockIndexSizes,
+ totalIndexSize: mockTotalIndexSize,
+ });
+ }
+ if (cmd.collMod) {
+ return Promise.resolve({ ok: 1 });
+ }
+ return Promise.resolve({});
+ }),
+ };
+
+ dbSpy = jest.spyOn(MongoClient.prototype, "db").mockReturnValue(mockDb as any);
+ });
+
+ afterEach(() => {
+ dbSpy.mockRestore();
+ });
+
+ describe("listIndexes", () => {
+ test("rejects invalid collection name", async () => {
+ await expect(mongoConnector.listIndexes(dummyConfig, { collection: "" })).rejects.toThrow(
+ MongoApiError,
+ );
+ await expect(
+ mongoConnector.listIndexes(dummyConfig, { collection: "system.views" }),
+ ).rejects.toThrow(MongoApiError);
+ });
+
+ test("returns mapped indexes with sizes and redundancy flags", async () => {
+ const result = await mongoConnector.listIndexes(dummyConfig, { collection: "users" });
+ expect(result.collection).toBe("users");
+ expect(result.indexes).toHaveLength(3);
+ expect(result.totalSizeBytes).toBe(24576);
+
+ const idIdx = result.indexes.find((i) => i.name === "_id_");
+ expect(idIdx).toBeDefined();
+ expect(idIdx?.isIdIndex).toBe(true);
+ expect(idIdx?.sizeBytes).toBe(4096);
+ expect(idIdx?.isRedundant).toBe(false);
+
+ const emailIdx = result.indexes.find((i) => i.name === "idx_email");
+ expect(emailIdx?.unique).toBe(true);
+ expect(emailIdx?.sizeBytes).toBe(8192);
+ // Unique index is never redundant even though prefix matches
+ expect(emailIdx?.isRedundant).toBe(false);
+ });
+
+ test("handles NamespaceNotFound gracefully by returning empty indexes array", async () => {
+ mockCollection.listIndexes = jest.fn().mockReturnValue({
+ toArray: jest.fn().mockRejectedValue({
+ code: 26,
+ codeName: "NamespaceNotFound",
+ message: "ns not found",
+ }),
+ });
+
+ const result = await mongoConnector.listIndexes(dummyConfig, {
+ collection: "missing_coll",
+ });
+ expect(result.indexes).toEqual([]);
+ expect(result.totalSizeBytes).toBe(0);
+ });
+
+ test("handles collStats failure gracefully by defaulting sizes to 0", async () => {
+ mockDb.command = jest
+ .fn()
+ .mockRejectedValue(new Error("collStats not allowed on view"));
+
+ const result = await mongoConnector.listIndexes(dummyConfig, { collection: "users" });
+ expect(result.indexes).toHaveLength(3);
+ expect(result.totalSizeBytes).toBe(0);
+ expect(result.indexes[0].sizeBytes).toBe(0);
+ });
+ });
+
+ describe("createIndex", () => {
+ test("rejects when connection is read-only", async () => {
+ await expect(
+ mongoConnector.createIndex(
+ dummyConfig,
+ { collection: "users", key: { email: 1 } },
+ { readOnly: true },
+ ),
+ ).rejects.toMatchObject({ code: "MONGO_READ_ONLY" });
+ });
+
+ test("rejects invalid collection name", async () => {
+ await expect(
+ mongoConnector.createIndex(dummyConfig, { collection: "$invalid", key: { email: 1 } }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("rejects non-object or empty key", async () => {
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: null as unknown as any,
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ await expect(
+ mongoConnector.createIndex(dummyConfig, { collection: "users", key: {} }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("rejects invalid direction in key spec", async () => {
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { email: 2 as any },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("rejects invalid options (negative expireAfterSeconds, empty name)", async () => {
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { createdAt: 1 },
+ options: { expireAfterSeconds: -10 },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { email: 1 },
+ options: { name: " " },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("creates single, compound, and special index types forwarding driver options", async () => {
+ const clearCacheSpy = jest.spyOn(mongodbCache, "clearCollectionCache");
+
+ const res = await mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { email: 1, age: -1 },
+ options: {
+ name: "idx_custom_email_age",
+ unique: true,
+ sparse: true,
+ partialFilterExpression: { active: true },
+ collation: { locale: "en", strength: 2 },
+ hidden: false,
+ },
+ });
+
+ expect(res.success).toBe(true);
+ expect(res.indexName).toBe("idx_custom_email_age");
+ expect(res.executionTimeMs).toBeGreaterThanOrEqual(0);
+ expect(mockCollection.createIndex).toHaveBeenCalledWith(
+ { email: 1, age: -1 },
+ expect.objectContaining({
+ name: "idx_custom_email_age",
+ unique: true,
+ sparse: true,
+ partialFilterExpression: { active: true },
+ collation: { locale: "en", strength: 2 },
+ hidden: false,
+ }),
+ );
+ expect(clearCacheSpy).toHaveBeenCalledWith(dummyConfig, "users");
+ });
+
+ test("creates single-field TTL index", async () => {
+ const res = await mongoConnector.createIndex(dummyConfig, {
+ collection: "sessions",
+ key: { createdAt: 1 },
+ options: {
+ name: "idx_ttl",
+ expireAfterSeconds: 3600,
+ },
+ });
+ expect(res.success).toBe(true);
+ expect(mockCollection.createIndex).toHaveBeenCalledWith(
+ { createdAt: 1 },
+ expect.objectContaining({ expireAfterSeconds: 3600 }),
+ );
+ });
+
+ test("rejects compound TTL index with MONGO_VALIDATION_ERROR", async () => {
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "sessions",
+ key: { createdAt: 1, userId: 1 },
+ options: {
+ expireAfterSeconds: 3600,
+ },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("single field"),
+ });
+ });
+
+ test("supports special index directions: text, 2dsphere, hashed", async () => {
+ const textRes = await mongoConnector.createIndex(dummyConfig, {
+ collection: "articles",
+ key: { title: "text", body: "text" },
+ });
+ expect(textRes.success).toBe(true);
+
+ const geoRes = await mongoConnector.createIndex(dummyConfig, {
+ collection: "places",
+ key: { location: "2dsphere" },
+ });
+ expect(geoRes.success).toBe(true);
+
+ const hashRes = await mongoConnector.createIndex(dummyConfig, {
+ collection: "accounts",
+ key: { accountId: "hashed" },
+ });
+ expect(hashRes.success).toBe(true);
+ });
+
+ test("rejects illegal special index combinations with MONGO_VALIDATION_ERROR", async () => {
+ // Text + 2dsphere
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "items",
+ key: { title: "text", loc: "2dsphere" },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("text index with 2dsphere"),
+ });
+
+ // Text + hashed
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "items",
+ key: { title: "text", id: "hashed" },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("text index with 2dsphere or hashed"),
+ });
+
+ // 2dsphere + hashed
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "items",
+ key: { loc: "2dsphere", id: "hashed" },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("2dsphere index with hashed"),
+ });
+
+ // Multiple hashed
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "items",
+ key: { id1: "hashed", id2: "hashed" },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("more than one hashed key"),
+ });
+
+ // Text with unique
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "items",
+ key: { title: "text" },
+ options: { unique: true },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("Text indexes cannot enforce unique"),
+ });
+
+ // TTL on _id
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "items",
+ key: { _id: 1 },
+ options: { expireAfterSeconds: 60 },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("immutable primary key '_id'"),
+ });
+
+ // TTL on special key
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "items",
+ key: { title: "text" },
+ options: { expireAfterSeconds: 60 },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("special non-B-tree key types"),
+ });
+ });
+
+ test("rejects malformed partial filter expressions and collations", async () => {
+ // Malformed partialFilter (primitive)
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { email: 1 },
+ options: { partialFilterExpression: "not-an-object" as any },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("non-null object"),
+ });
+
+ // Malformed partialFilter (prohibited JS / $where)
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { email: 1 },
+ options: { partialFilterExpression: { $where: "sleep(1000)" } },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN_OPERATOR",
+ });
+
+ // Malformed collation (empty locale)
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { email: 1 },
+ options: { collation: { locale: " " } },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("collation.locale"),
+ });
+
+ // Malformed collation (invalid strength)
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { email: 1 },
+ options: { collation: { locale: "en", strength: 99 as any } },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("collation.strength"),
+ });
+ });
+
+ test("maps driver InvalidOptions on hidden: true to MONGO_UNSUPPORTED_OPERATION (< MongoDB 4.4)", async () => {
+ mockCollection.createIndex = jest.fn().mockRejectedValue({
+ code: 72,
+ codeName: "InvalidOptions",
+ message: "unrecognized option: hidden",
+ });
+
+ await expect(
+ mongoConnector.createIndex(dummyConfig, {
+ collection: "users",
+ key: { email: 1 },
+ options: { hidden: true },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_UNSUPPORTED_OPERATION",
+ message: expect.stringContaining("MongoDB 4.4"),
+ });
+ });
+
+ test("rejects when config.readonly is true even without options.readOnly", async () => {
+ const readOnlyConfig = { ...dummyConfig, readonly: true };
+ await expect(
+ mongoConnector.createIndex(readOnlyConfig, {
+ collection: "users",
+ key: { email: 1 },
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_READ_ONLY",
+ });
+ });
+ });
+
+ describe("dropIndex", () => {
+ test("rejects when connection is read-only", async () => {
+ await expect(
+ mongoConnector.dropIndex(
+ dummyConfig,
+ { collection: "users", indexName: "idx_email" },
+ { readOnly: true },
+ ),
+ ).rejects.toMatchObject({ code: "MONGO_READ_ONLY" });
+ });
+
+ test("strictly prevents dropping the immutable default primary key index _id_", async () => {
+ await expect(
+ mongoConnector.dropIndex(dummyConfig, { collection: "users", indexName: "_id_" }),
+ ).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN",
+ message: expect.stringContaining("_id_"),
+ });
+ expect(mockCollection.dropIndex).not.toHaveBeenCalled();
+ });
+
+ test("strictly prevents dropping wildcard '*' index with MONGO_FORBIDDEN", async () => {
+ await expect(
+ mongoConnector.dropIndex(dummyConfig, { collection: "users", indexName: "*" }),
+ ).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN",
+ message: expect.stringContaining("Wildcard"),
+ });
+ expect(mockCollection.dropIndex).not.toHaveBeenCalled();
+ });
+
+ test("rejects empty or whitespace indexName", async () => {
+ await expect(
+ mongoConnector.dropIndex(dummyConfig, { collection: "users", indexName: "" }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ await expect(
+ mongoConnector.dropIndex(dummyConfig, { collection: "users", indexName: " " }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("drops secondary index and clears caches", async () => {
+ const clearCacheSpy = jest.spyOn(mongodbCache, "clearCollectionCache");
+
+ const res = await mongoConnector.dropIndex(dummyConfig, {
+ collection: "users",
+ indexName: "idx_email",
+ });
+
+ expect(res.success).toBe(true);
+ expect(res.droppedIndexName).toBe("idx_email");
+ expect(res.executionTimeMs).toBeGreaterThanOrEqual(0);
+ expect(mockCollection.dropIndex).toHaveBeenCalledWith("idx_email", expect.any(Object));
+ expect(clearCacheSpy).toHaveBeenCalledWith(dummyConfig, "users");
+ });
+
+ test("maps driver IndexNotFound (code 27) to MONGO_NOT_FOUND", async () => {
+ mockCollection.dropIndex = jest.fn().mockRejectedValue({
+ code: 27,
+ codeName: "IndexNotFound",
+ message: "index not found with name [idx_missing]",
+ });
+
+ await expect(
+ mongoConnector.dropIndex(dummyConfig, {
+ collection: "users",
+ indexName: "idx_missing",
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_NOT_FOUND" });
+ });
+ });
+
+ describe("getIndexStats", () => {
+ test("rejects invalid collection name", async () => {
+ await expect(mongoConnector.getIndexStats(dummyConfig, { collection: "" })).rejects.toThrow(
+ MongoApiError,
+ );
+ });
+
+ test("aggregates $indexStats and maps results into stats items", async () => {
+ const res = await mongoConnector.getIndexStats(dummyConfig, { collection: "users" });
+ expect(res.collection).toBe("users");
+ expect(res.stats.idx_email).toBeDefined();
+ expect(res.stats.idx_email.ops).toBe(50);
+ expect(res.stats.idx_email.host).toBe("localhost:27017");
+ expect(res.stats.idx_email.since).toBe("2026-10-30T00:00:00.000Z");
+ expect(mockCollection.aggregate).toHaveBeenCalledWith(
+ [{ $indexStats: {} }],
+ expect.any(Object),
+ );
+ });
+
+ test("handles NamespaceNotFound by returning empty stats", async () => {
+ mockCollection.aggregate = jest.fn().mockReturnValue({
+ toArray: jest.fn().mockRejectedValue({ code: 26, codeName: "NamespaceNotFound" }),
+ });
+
+ const res = await mongoConnector.getIndexStats(dummyConfig, { collection: "missing" });
+ expect(res.stats).toEqual({});
+ });
+ });
+
+ describe("hideIndex", () => {
+ test("rejects when connection is read-only", async () => {
+ await expect(
+ mongoConnector.hideIndex(
+ dummyConfig,
+ { collection: "users", indexName: "idx_email", hidden: true },
+ { readOnly: true },
+ ),
+ ).rejects.toMatchObject({ code: "MONGO_READ_ONLY" });
+ });
+
+ test("rejects hiding the immutable default primary key index _id_", async () => {
+ await expect(
+ mongoConnector.hideIndex(dummyConfig, {
+ collection: "users",
+ indexName: "_id_",
+ hidden: true,
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_FORBIDDEN",
+ message: expect.stringContaining("_id_"),
+ });
+ expect(mockDb.command).not.toHaveBeenCalled();
+ });
+
+ test("rejects non-boolean hidden parameter", async () => {
+ await expect(
+ mongoConnector.hideIndex(dummyConfig, {
+ collection: "users",
+ indexName: "idx_email",
+ hidden: "yes" as any,
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_VALIDATION_ERROR" });
+ });
+
+ test("issues collMod command to toggle hidden status and clears caches", async () => {
+ const clearCacheSpy = jest.spyOn(mongodbCache, "clearCollectionCache");
+
+ const res = await mongoConnector.hideIndex(dummyConfig, {
+ collection: "users",
+ indexName: "idx_email",
+ hidden: true,
+ });
+
+ expect(res.success).toBe(true);
+ expect(res.indexName).toBe("idx_email");
+ expect(res.hidden).toBe(true);
+ expect(mockDb.command).toHaveBeenCalledWith({
+ collMod: "users",
+ index: {
+ name: "idx_email",
+ hidden: true,
+ },
+ });
+ expect(clearCacheSpy).toHaveBeenCalledWith(dummyConfig, "users");
+ });
+
+ test("maps IndexNotFound error to MONGO_NOT_FOUND", async () => {
+ mockDb.command = jest.fn().mockRejectedValue({
+ code: 27,
+ codeName: "IndexNotFound",
+ message: "cannot find index to hide",
+ });
+
+ await expect(
+ mongoConnector.hideIndex(dummyConfig, {
+ collection: "users",
+ indexName: "idx_missing",
+ hidden: false,
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_NOT_FOUND" });
+ });
+
+ test("maps unsupported collMod option (< MongoDB 4.4) to MONGO_UNSUPPORTED_OPERATION", async () => {
+ mockDb.command = jest.fn().mockRejectedValue({
+ code: 72,
+ codeName: "InvalidOptions",
+ message: "no option found to collMod: index",
+ });
+
+ await expect(
+ mongoConnector.hideIndex(dummyConfig, {
+ collection: "users",
+ indexName: "idx_email",
+ hidden: true,
+ }),
+ ).rejects.toMatchObject({
+ code: "MONGO_UNSUPPORTED_OPERATION",
+ message: expect.stringContaining("MongoDB 4.4"),
+ });
+ });
+ });
+ });
+
+ // =========================================================================
+ // 3. QueryExecutor Delegation & Type Check Tests
+ // =========================================================================
+ describe("QueryExecutor Index Delegation", () => {
+ let executor: QueryExecutor;
+
+ beforeEach(() => {
+ executor = new QueryExecutor();
+ });
+
+ test("throws MONGO_UNSUPPORTED_OPERATION when dbType is not MONGODB", async () => {
+ const nonMongoTypes = [DBType.POSTGRES, DBType.MYSQL, DBType.SQLITE, DBType.DUCKDB];
+
+ for (const t of nonMongoTypes) {
+ await expect(
+ executor.listIndexes(dummyConfig, t, { collection: "users" }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+
+ await expect(
+ executor.createIndex(dummyConfig, t, { collection: "users", key: { a: 1 } }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+
+ await expect(
+ executor.dropIndex(dummyConfig, t, { collection: "users", indexName: "idx_a" }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+
+ await expect(
+ executor.getIndexStats(dummyConfig, t, { collection: "users" }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+
+ await expect(
+ executor.hideIndex(dummyConfig, t, {
+ collection: "users",
+ indexName: "idx_a",
+ hidden: true,
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_UNSUPPORTED_OPERATION" });
+ }
+ });
+
+ test("delegates to mongoConnector when dbType is MONGODB", async () => {
+ const listSpy = jest
+ .spyOn(mongoConnector, "listIndexes")
+ .mockResolvedValueOnce({ collection: "users", indexes: [], totalSizeBytes: 0 });
+ const createSpy = jest
+ .spyOn(mongoConnector, "createIndex")
+ .mockResolvedValueOnce({ success: true, indexName: "idx_a", executionTimeMs: 5 });
+ const dropSpy = jest
+ .spyOn(mongoConnector, "dropIndex")
+ .mockResolvedValueOnce({ success: true, droppedIndexName: "idx_a", executionTimeMs: 5 });
+ const statsSpy = jest
+ .spyOn(mongoConnector, "getIndexStats")
+ .mockResolvedValueOnce({ collection: "users", stats: {} });
+ const hideSpy = jest
+ .spyOn(mongoConnector, "hideIndex")
+ .mockResolvedValueOnce({ success: true, indexName: "idx_a", hidden: true });
+
+ await executor.listIndexes(dummyConfig, DBType.MONGODB, { collection: "users" });
+ expect(listSpy).toHaveBeenCalledWith(dummyConfig, { collection: "users" });
+
+ await executor.createIndex(
+ dummyConfig,
+ DBType.MONGODB,
+ { collection: "users", key: { a: 1 } },
+ { readOnly: false },
+ );
+ expect(createSpy).toHaveBeenCalledWith(
+ dummyConfig,
+ { collection: "users", key: { a: 1 } },
+ { readOnly: false },
+ );
+
+ await executor.dropIndex(
+ dummyConfig,
+ DBType.MONGODB,
+ { collection: "users", indexName: "idx_a" },
+ { readOnly: false },
+ );
+ expect(dropSpy).toHaveBeenCalledWith(
+ dummyConfig,
+ { collection: "users", indexName: "idx_a" },
+ { readOnly: false },
+ );
+
+ await executor.getIndexStats(dummyConfig, DBType.MONGODB, { collection: "users" });
+ expect(statsSpy).toHaveBeenCalledWith(dummyConfig, { collection: "users" });
+
+ await executor.hideIndex(
+ dummyConfig,
+ DBType.MONGODB,
+ { collection: "users", indexName: "idx_a", hidden: true },
+ { readOnly: false },
+ );
+ expect(hideSpy).toHaveBeenCalledWith(
+ dummyConfig,
+ { collection: "users", indexName: "idx_a", hidden: true },
+ { readOnly: false },
+ );
+ });
+ });
+
+ // =========================================================================
+ // 4. IndexHandlers RPC Dispatch Tests
+ // =========================================================================
+ describe("IndexHandlers RPC Dispatch", () => {
+ let mockRpc: any;
+ let mockLogger: any;
+ let mockDbService: any;
+ let mockQueryExecutor: any;
+ let handlers: IndexHandlers;
+
+ beforeEach(() => {
+ mockRpc = {
+ sendResponse: jest.fn(),
+ sendError: jest.fn(),
+ };
+ mockLogger = {
+ error: jest.fn(),
+ warn: jest.fn(),
+ info: jest.fn(),
+ debug: jest.fn(),
+ };
+ mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ db: { id: "mongo-1", name: "testdb", readonly: false },
+ conn: dummyConfig,
+ dbType: DBType.MONGODB,
+ }),
+ withConnection: jest.fn().mockImplementation(async (dbId: string, fn: any) => {
+ const connInfo = await mockDbService.getDatabaseConnection(dbId);
+ return fn(connInfo.conn, connInfo.db, connInfo.dbType);
+ }),
+ };
+ mockQueryExecutor = {
+ listIndexes: jest.fn().mockResolvedValue({
+ collection: "users",
+ indexes: [],
+ totalSizeBytes: 0,
+ }),
+ createIndex: jest.fn().mockResolvedValue({
+ success: true,
+ indexName: "idx_test",
+ executionTimeMs: 10,
+ }),
+ dropIndex: jest.fn().mockResolvedValue({
+ success: true,
+ droppedIndexName: "idx_test",
+ executionTimeMs: 8,
+ }),
+ getIndexStats: jest.fn().mockResolvedValue({
+ collection: "users",
+ stats: {},
+ }),
+ hideIndex: jest.fn().mockResolvedValue({
+ success: true,
+ indexName: "idx_test",
+ hidden: true,
+ }),
+ };
+
+ handlers = new IndexHandlers(mockRpc, mockLogger, mockDbService, mockQueryExecutor);
+ });
+
+ test("handleListIndexes dispatches successfully", async () => {
+ await handlers.handleListIndexes({ dbId: "mongo-1", collection: "users" }, 1);
+ expect(mockQueryExecutor.listIndexes).toHaveBeenCalledWith(dummyConfig, DBType.MONGODB, {
+ collection: "users",
+ });
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(1, {
+ ok: true,
+ data: expect.objectContaining({ collection: "users" }),
+ });
+ });
+
+ test("handleListIndexes rejects missing dbId or collection", async () => {
+ await handlers.handleListIndexes({ collection: "users" }, 2);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(2, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId or collection",
+ });
+
+ await handlers.handleListIndexes({ dbId: "mongo-1" }, 3);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(3, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId or collection",
+ });
+ });
+
+ test("handleCreateIndex extracts readOnly and dispatches successfully", async () => {
+ await handlers.handleCreateIndex(
+ { dbId: "mongo-1", collection: "users", key: { email: 1 } },
+ 4,
+ );
+ expect(mockQueryExecutor.createIndex).toHaveBeenCalledWith(
+ dummyConfig,
+ DBType.MONGODB,
+ { collection: "users", key: { email: 1 }, options: undefined },
+ { readOnly: false },
+ );
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(4, {
+ ok: true,
+ data: expect.objectContaining({ success: true }),
+ });
+ });
+
+ test("handleCreateIndex extracts readOnly: true from db metadata", async () => {
+ mockDbService.getDatabaseConnection.mockResolvedValueOnce({
+ db: { id: "mongo-ro", name: "testdb", readonly: true },
+ conn: dummyConfig,
+ dbType: DBType.MONGODB,
+ });
+
+ await handlers.handleCreateIndex(
+ { dbId: "mongo-ro", collection: "users", key: { email: 1 } },
+ 5,
+ );
+ expect(mockQueryExecutor.createIndex).toHaveBeenCalledWith(
+ dummyConfig,
+ DBType.MONGODB,
+ { collection: "users", key: { email: 1 }, options: undefined },
+ { readOnly: true },
+ );
+ });
+
+ test("handleCreateIndex rejects missing parameters", async () => {
+ await handlers.handleCreateIndex({ dbId: "mongo-1", collection: "users" }, 6);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(6, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or key",
+ });
+ });
+
+ test("handleDropIndex dispatches successfully", async () => {
+ await handlers.handleDropIndex(
+ { dbId: "mongo-1", collection: "users", indexName: "idx_email" },
+ 7,
+ );
+ expect(mockQueryExecutor.dropIndex).toHaveBeenCalledWith(
+ dummyConfig,
+ DBType.MONGODB,
+ { collection: "users", indexName: "idx_email" },
+ { readOnly: false },
+ );
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(7, {
+ ok: true,
+ data: expect.objectContaining({ success: true }),
+ });
+ });
+
+ test("handleDropIndex rejects missing parameters", async () => {
+ await handlers.handleDropIndex({ dbId: "mongo-1", collection: "users" }, 8);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(8, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or indexName",
+ });
+ });
+
+ test("handleGetIndexStats dispatches successfully", async () => {
+ await handlers.handleGetIndexStats({ dbId: "mongo-1", collection: "users" }, 9);
+ expect(mockQueryExecutor.getIndexStats).toHaveBeenCalledWith(dummyConfig, DBType.MONGODB, {
+ collection: "users",
+ });
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(9, {
+ ok: true,
+ data: expect.objectContaining({ collection: "users" }),
+ });
+ });
+
+ test("handleHideIndex validates hidden boolean and dispatches successfully", async () => {
+ await handlers.handleHideIndex(
+ { dbId: "mongo-1", collection: "users", indexName: "idx_email", hidden: true },
+ 10,
+ );
+ expect(mockQueryExecutor.hideIndex).toHaveBeenCalledWith(
+ dummyConfig,
+ DBType.MONGODB,
+ { collection: "users", indexName: "idx_email", hidden: true },
+ { readOnly: false },
+ );
+ expect(mockRpc.sendResponse).toHaveBeenCalledWith(10, {
+ ok: true,
+ data: expect.objectContaining({ success: true, hidden: true }),
+ });
+ });
+
+ test("handleHideIndex rejects non-boolean hidden parameter", async () => {
+ await handlers.handleHideIndex(
+ { dbId: "mongo-1", collection: "users", indexName: "idx_email", hidden: "invalid" },
+ 11,
+ );
+ expect(mockRpc.sendError).toHaveBeenCalledWith(11, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: expect.stringContaining("hidden (must be a boolean)"),
+ });
+ });
+
+ test("maps errors using sendMongoError", async () => {
+ mockQueryExecutor.listIndexes.mockRejectedValueOnce(
+ new MongoApiError("MONGO_NOT_FOUND", "Collection does not exist"),
+ );
+
+ await handlers.handleListIndexes({ dbId: "mongo-1", collection: "missing" }, 12);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(12, {
+ code: "MONGO_NOT_FOUND",
+ message: "Collection does not exist",
+ });
+ expect(mockLogger.error).toHaveBeenCalled();
+ });
+ });
+});
diff --git a/bridge/__tests__/mongoMigrationEngine.test.ts b/bridge/__tests__/mongoMigrationEngine.test.ts
new file mode 100644
index 00000000..a3e73004
--- /dev/null
+++ b/bridge/__tests__/mongoMigrationEngine.test.ts
@@ -0,0 +1,1417 @@
+import { describe, expect, test, beforeEach, afterEach } from "@jest/globals";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { Db } from "mongodb";
+import {
+ validateManifest,
+ assertValidManifest,
+ computeManifestChecksum,
+ validateSafeFilePath,
+ listMigrations,
+ applyMigration,
+ rollbackMigration,
+ rebuildMigrationSummary,
+ getMigrationStatus,
+ compensateStep,
+ MAX_MANIFEST_SIZE_BYTES,
+ EVENTS_COLLECTION,
+ MIGRATIONS_COLLECTION,
+} from "../src/services/mongoMigrationEngine";
+import { LOCK_COLLECTION, LOCK_DOC_ID } from "../src/services/mongoMigrationLock";
+import { MongoApiError } from "../src/connectors/mongo";
+import {
+ MongoMigrationManifest,
+ MongoMigrationSummary,
+ MongoMigrationEvent,
+ MongoMigrationLockDoc,
+} from "../src/types/mongoMigration";
+
+/**
+ * Creates an in-memory mock MongoDB database for migration engine testing.
+ */
+function createMockEngineDb() {
+ const locks = new Map();
+ const summaries = new Map();
+ const events: MongoMigrationEvent[] = [];
+ const collectionsData = new Map();
+ const collectionsIndexes = new Map();
+ const collectionsOptions = new Map();
+
+ const getOrCreateCollData = (name: string) => {
+ if (!collectionsData.has(name)) collectionsData.set(name, []);
+ return collectionsData.get(name)!;
+ };
+
+ const getOrCreateCollIndexes = (name: string) => {
+ if (!collectionsIndexes.has(name)) {
+ collectionsIndexes.set(name, [{ name: "_id_", key: { _id: 1 }, v: 2 }]);
+ }
+ return collectionsIndexes.get(name)!;
+ };
+
+ const db: any = {
+ async createCollection(name: string, options?: any) {
+ if (collectionsData.has(name)) {
+ const err: any = new Error(`Collection ${name} already exists`);
+ err.code = 48;
+ throw err;
+ }
+ collectionsData.set(name, []);
+ collectionsOptions.set(name, options || {});
+ getOrCreateCollIndexes(name);
+ return { collectionName: name };
+ },
+
+ listCollections(filter?: any) {
+ return {
+ async toArray() {
+ const list: any[] = [];
+ for (const [name, options] of collectionsOptions.entries()) {
+ if (filter?.name && filter.name !== name) continue;
+ list.push({ name, options });
+ }
+ return list;
+ },
+ };
+ },
+
+ async command(cmd: any) {
+ if (cmd.collMod) {
+ const collName = cmd.collMod;
+ const currentOptions = collectionsOptions.get(collName) || {};
+ if (cmd.validator) currentOptions.validator = cmd.validator;
+ if (cmd.validationLevel) currentOptions.validationLevel = cmd.validationLevel;
+ if (cmd.validationAction) currentOptions.validationAction = cmd.validationAction;
+ collectionsOptions.set(collName, currentOptions);
+ return { ok: 1 };
+ }
+ return { ok: 1 };
+ },
+
+ collection(name: string) {
+ if (name === LOCK_COLLECTION) {
+ return {
+ async findOneAndUpdate(filter: any, update: any, options?: any) {
+ const existing = locks.get(LOCK_DOC_ID);
+ const now = new Date();
+
+ if (!existing) {
+ const fencingToken = update.$inc?.fencingToken || 1;
+ const newDoc: MongoMigrationLockDoc = {
+ _id: LOCK_DOC_ID,
+ ownerId: update.$set?.ownerId || null,
+ migrationId: update.$set?.migrationId || null,
+ acquiredAt: update.$set?.acquiredAt || now,
+ heartbeatAt: update.$set?.heartbeatAt || now,
+ expiresAt: update.$set?.expiresAt || new Date(now.getTime() + 60000),
+ fencingToken,
+ };
+ locks.set(LOCK_DOC_ID, newDoc);
+ return newDoc;
+ }
+
+ const ownerMatch = filter.$or?.some((cond: any) => {
+ if ("ownerId" in cond && cond.ownerId === existing.ownerId) return true;
+ if ("ownerId" in cond && cond.ownerId === null && existing.ownerId === null)
+ return true;
+ if (
+ cond.expiresAt?.$lt &&
+ existing.expiresAt &&
+ new Date(existing.expiresAt).getTime() < new Date(cond.expiresAt.$lt).getTime()
+ ) {
+ return true;
+ }
+ return false;
+ });
+
+ if (ownerMatch) {
+ const fencingToken = (existing.fencingToken || 0) + (update.$inc?.fencingToken || 1);
+ const updatedDoc: MongoMigrationLockDoc = {
+ ...existing,
+ ownerId:
+ update.$set?.ownerId !== undefined ? update.$set.ownerId : existing.ownerId,
+ migrationId:
+ update.$set?.migrationId !== undefined
+ ? update.$set.migrationId
+ : existing.migrationId,
+ acquiredAt: update.$set?.acquiredAt || now,
+ heartbeatAt: update.$set?.heartbeatAt || now,
+ expiresAt: update.$set?.expiresAt || existing.expiresAt,
+ fencingToken,
+ };
+ locks.set(LOCK_DOC_ID, updatedDoc);
+ return updatedDoc;
+ }
+
+ if (options?.upsert) {
+ const err: any = new Error("E11000 duplicate key error");
+ err.code = 11000;
+ throw err;
+ }
+ return null;
+ },
+
+ async findOne(filter: any) {
+ if (filter._id === LOCK_DOC_ID) {
+ const doc = locks.get(LOCK_DOC_ID);
+ if (!doc) return null;
+ if (filter.ownerId && doc.ownerId !== filter.ownerId) return null;
+ if (filter.fencingToken !== undefined && doc.fencingToken !== filter.fencingToken)
+ return null;
+ if (filter.expiresAt?.$gt) {
+ if (
+ !doc.expiresAt ||
+ new Date(doc.expiresAt).getTime() <= new Date(filter.expiresAt.$gt).getTime()
+ ) {
+ return null;
+ }
+ }
+ return { ...doc };
+ }
+ return null;
+ },
+
+ async updateOne(filter: any, update: any) {
+ const doc = locks.get(LOCK_DOC_ID);
+ if (!doc) return { matchedCount: 0, modifiedCount: 0 };
+ if (filter.ownerId && doc.ownerId !== filter.ownerId)
+ return { matchedCount: 0, modifiedCount: 0 };
+ if (filter.fencingToken !== undefined && doc.fencingToken !== filter.fencingToken) {
+ return { matchedCount: 0, modifiedCount: 0 };
+ }
+ if (filter.expiresAt?.$gt) {
+ if (
+ !doc.expiresAt ||
+ new Date(doc.expiresAt).getTime() <= new Date(filter.expiresAt.$gt).getTime()
+ ) {
+ return { matchedCount: 0, modifiedCount: 0 };
+ }
+ }
+ if (update.$set) Object.assign(doc, update.$set);
+ return { matchedCount: 1, modifiedCount: 1 };
+ },
+
+ async deleteOne(filter: any) {
+ const doc = locks.get(LOCK_DOC_ID);
+ if (!doc) return { deletedCount: 0 };
+ if (filter.ownerId && doc.ownerId !== filter.ownerId) return { deletedCount: 0 };
+ if (filter.fencingToken !== undefined && doc.fencingToken !== filter.fencingToken) {
+ return { deletedCount: 0 };
+ }
+ locks.delete(LOCK_DOC_ID);
+ return { deletedCount: 1 };
+ },
+ };
+ }
+
+ if (name === MIGRATIONS_COLLECTION) {
+ return {
+ async findOne(filter: any) {
+ if (filter._id) {
+ const doc = summaries.get(filter._id);
+ return doc ? { ...doc } : null;
+ }
+ return null;
+ },
+
+ find(filter: any = {}) {
+ let list = Array.from(summaries.values());
+ if (filter.status?.$ne) {
+ list = list.filter((s) => s.status !== filter.status.$ne);
+ } else if (filter.status) {
+ list = list.filter((s) => s.status === filter.status);
+ }
+ return {
+ sort(sortObj: any) {
+ if (sortObj._id === 1) {
+ list.sort((a, b) => a._id.localeCompare(b._id));
+ } else if (sortObj._id === -1) {
+ list.sort((a, b) => b._id.localeCompare(a._id));
+ }
+ return {
+ limit(n: number) {
+ list = list.slice(0, n);
+ return {
+ async toArray() {
+ return list.map((x) => ({ ...x }));
+ },
+ };
+ },
+ async toArray() {
+ return list.map((x) => ({ ...x }));
+ },
+ };
+ },
+ async toArray() {
+ return list.map((x) => ({ ...x }));
+ },
+ };
+ },
+
+ async updateOne(filter: any, update: any, options?: any) {
+ const id = filter._id;
+ let doc = summaries.get(id);
+ if (!doc && options?.upsert) {
+ doc = {
+ _id: id,
+ name: update.$set?.name || "",
+ checksum: update.$set?.checksum || "",
+ status: update.$set?.status || "PENDING",
+ startedAt: update.$set?.startedAt || new Date().toISOString(),
+ executedSteps: update.$set?.executedSteps || 0,
+ totalSteps: update.$set?.totalSteps || 0,
+ fencingToken: update.$set?.fencingToken || 1,
+ };
+ summaries.set(id, doc);
+ }
+ if (doc && update.$set) {
+ Object.assign(doc, update.$set);
+ }
+ return { matchedCount: doc ? 1 : 0, modifiedCount: 1 };
+ },
+
+ async replaceOne(filter: any, doc: any, _options?: any) {
+ summaries.set(filter._id, { ...doc });
+ return { matchedCount: 1, modifiedCount: 1 };
+ },
+
+ async countDocuments(filter: any = {}) {
+ let list = Array.from(summaries.values());
+ if (filter.status?.$ne) {
+ list = list.filter((s) => s.status !== filter.status.$ne);
+ }
+ return list.length;
+ },
+ };
+ }
+
+ if (name === EVENTS_COLLECTION) {
+ return {
+ async insertOne(doc: any) {
+ events.push({ ...doc });
+ return { insertedId: doc._id };
+ },
+
+ find(filter: any = {}) {
+ let list = events.filter((e) => {
+ if (filter.migrationId && e.migrationId !== filter.migrationId) return false;
+ return true;
+ });
+ return {
+ sort(sortObj: any) {
+ if (sortObj.attemptNumber !== undefined) {
+ list.sort((a, b) => {
+ if (a.attemptNumber !== b.attemptNumber) {
+ return sortObj.attemptNumber === 1
+ ? a.attemptNumber - b.attemptNumber
+ : b.attemptNumber - a.attemptNumber;
+ }
+ if (sortObj.sequenceNumber !== undefined) {
+ return sortObj.sequenceNumber === 1
+ ? (a.sequenceNumber || 0) - (b.sequenceNumber || 0)
+ : (b.sequenceNumber || 0) - (a.sequenceNumber || 0);
+ }
+ return 0;
+ });
+ } else if (sortObj.timestamp) {
+ list.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+ }
+ return {
+ limit(n: number) {
+ list = list.slice(0, n);
+ return {
+ async toArray() {
+ return list.map((x) => ({ ...x }));
+ },
+ };
+ },
+ async toArray() {
+ return list.map((x) => ({ ...x }));
+ },
+ };
+ },
+ async toArray() {
+ return list.map((x) => ({ ...x }));
+ },
+ };
+ },
+ };
+ }
+
+ // User collection mock
+ return {
+ async countDocuments(_filter: any = {}) {
+ const data = collectionsData.get(name);
+ return data ? data.length : 0;
+ },
+
+ async drop() {
+ if (!collectionsData.has(name) && !collectionsOptions.has(name)) {
+ const err: any = new Error(`Collection ${name} not found`);
+ err.code = 26;
+ throw err;
+ }
+ collectionsData.delete(name);
+ collectionsOptions.delete(name);
+ collectionsIndexes.delete(name);
+ return true;
+ },
+
+ async createIndex(key: any, options?: any) {
+ const idxs = getOrCreateCollIndexes(name);
+ const indexName =
+ options?.name ||
+ Object.entries(key)
+ .map(([k, v]) => `${k}_${v}`)
+ .join("_");
+ idxs.push({
+ name: indexName,
+ key,
+ ...options,
+ });
+ return indexName;
+ },
+
+ async dropIndex(indexName: string) {
+ const idxs = getOrCreateCollIndexes(name);
+ const idx = idxs.findIndex((i) => i.name === indexName);
+ if (idx === -1) {
+ const err: any = new Error(`Index ${indexName} not found`);
+ err.code = 27;
+ throw err;
+ }
+ idxs.splice(idx, 1);
+ return { ok: 1 };
+ },
+
+ async indexes() {
+ const idxs = getOrCreateCollIndexes(name);
+ return idxs.map((i) => ({ ...i }));
+ },
+
+ async updateMany(filter: any, update: any, _options?: any) {
+ const data = getOrCreateCollData(name);
+ let matched = 0;
+ for (const item of data) {
+ matched++;
+ if (update.$set) Object.assign(item, update.$set);
+ if (update.$unset) {
+ for (const k of Object.keys(update.$unset)) {
+ delete item[k];
+ }
+ }
+ }
+ return { matchedCount: matched, modifiedCount: matched };
+ },
+
+ async insertMany(docs: any[]) {
+ const data = getOrCreateCollData(name);
+ data.push(...docs);
+ return { insertedCount: docs.length };
+ },
+ };
+ },
+ };
+
+ return {
+ db: db as Db,
+ locks,
+ summaries,
+ events,
+ collectionsData,
+ collectionsIndexes,
+ collectionsOptions,
+ };
+}
+
+describe("mongoMigrationEngine Unit Tests (M6 Spec §4-§8)", () => {
+ let tempDir: string;
+ let mongoDir: string;
+ let mockEngine: ReturnType;
+
+ beforeEach(() => {
+ tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "relwave_engine_test_"));
+ mongoDir = path.join(tempDir, "migrations", "mongo");
+ fs.mkdirSync(mongoDir, { recursive: true });
+ mockEngine = createMockEngineDb();
+ });
+
+ afterEach(() => {
+ try {
+ fs.rmSync(tempDir, { recursive: true, force: true });
+ } catch {
+ // ignore
+ }
+ });
+
+ // =========================================================================
+ // 1. Manifest Validation & Security Sandbox
+ // =========================================================================
+ describe("Manifest Validation & AST Security", () => {
+ test("valid manifest with DDL and updateMany with down step passes validation", () => {
+ const manifest: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "setup_users",
+ up: [
+ { type: "createCollection", collection: "users" },
+ {
+ type: "createIndex",
+ collection: "users",
+ key: { email: 1 },
+ options: { unique: true },
+ },
+ {
+ type: "updateMany",
+ collection: "users",
+ filter: { active: { $exists: false } },
+ update: { $set: { active: true } },
+ },
+ ],
+ down: [
+ {
+ type: "updateMany",
+ collection: "users",
+ filter: { active: true },
+ update: { $unset: { active: "" } },
+ },
+ ],
+ };
+
+ const result = validateManifest(manifest);
+ expect(result.valid).toBe(true);
+ expect(result.errors).toHaveLength(0);
+ expect(result.stepsBreakdown.ddlCount).toBe(2);
+ expect(result.stepsBreakdown.dataTransformCount).toBe(1);
+ expect(result.stepsBreakdown.reversibleCount).toBe(3);
+ });
+
+ test("missing required manifest fields fails validation", () => {
+ const result = validateManifest({ id: "", up: [] });
+ expect(result.valid).toBe(false);
+ expect(result.errors.length).toBeGreaterThan(0);
+ });
+
+ test("checksum calculation normalizes CRLF and LF", () => {
+ const contentCRLF = '{\r\n "version": "1.0",\r\n "name": "test"\r\n}';
+ const contentLF = '{\n "version": "1.0",\n "name": "test"\n}';
+ expect(computeManifestChecksum(contentCRLF)).toBe(computeManifestChecksum(contentLF));
+ });
+
+ test("rejects deleteMany step permanently", () => {
+ const manifest: any = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "delete_test",
+ up: [{ type: "deleteMany", collection: "users", filter: { old: true } }],
+ };
+ const result = validateManifest(manifest);
+ expect(result.valid).toBe(false);
+ expect(result.errors[0]).toContain("deleteMany is permanently excluded");
+
+ expect(() => assertValidManifest(manifest)).toThrow(MongoApiError);
+ });
+
+ test("rejects forbidden expressions: $where, $function, $accumulator in updateMany", () => {
+ const whereManifest: any = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "where_test",
+ up: [
+ {
+ type: "updateMany",
+ collection: "users",
+ filter: { $where: "this.age > 21" },
+ update: { $set: { adult: true } },
+ },
+ ],
+ down: [
+ {
+ type: "updateMany",
+ collection: "users",
+ filter: { adult: true },
+ update: { $unset: { adult: "" } },
+ },
+ ],
+ };
+ const res = validateManifest(whereManifest);
+ expect(res.valid).toBe(false);
+ expect(res.errors.some((e) => e.includes("forbidden") && e.includes("$where"))).toBe(true);
+ expect(() => assertValidManifest(whereManifest)).toThrow(MongoApiError);
+
+ const funcManifest: any = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "func_test",
+ up: [
+ {
+ type: "updateMany",
+ collection: "users",
+ filter: { age: { $gt: 20 } },
+ update: { $set: { fn: { $function: { body: "function() { return 1; }" } } } },
+ },
+ ],
+ down: [
+ {
+ type: "updateMany",
+ collection: "users",
+ filter: {},
+ update: { $unset: { fn: "" } },
+ },
+ ],
+ };
+ expect(validateManifest(funcManifest).valid).toBe(false);
+ expect(() => assertValidManifest(funcManifest)).toThrow(MongoApiError);
+ });
+
+ test("dropCollection requires allowIrreversible: true", () => {
+ const badDrop: any = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "drop_test",
+ up: [{ type: "dropCollection", collection: "old_users" }],
+ };
+ const resBad = validateManifest(badDrop);
+ expect(resBad.valid).toBe(false);
+ expect(resBad.errors[0]).toContain("allowIrreversible: true");
+
+ const goodDrop: any = {
+ ...badDrop,
+ allowIrreversible: true,
+ };
+ expect(validateManifest(goodDrop).valid).toBe(true);
+ });
+
+ test("dropIndex rejects dropping immutable _id_ index", () => {
+ const dropIdManifest: any = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "drop_id_test",
+ up: [{ type: "dropIndex", collection: "users", indexName: "_id_" }],
+ };
+ const res = validateManifest(dropIdManifest);
+ expect(res.valid).toBe(false);
+ expect(res.errors[0]).toContain("cannot drop default _id_ index");
+ });
+
+ test("updateMany requires an author-provided down step", () => {
+ const noDownManifest: any = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "no_down_test",
+ up: [
+ {
+ type: "updateMany",
+ collection: "users",
+ filter: { active: false },
+ update: { $set: { active: true } },
+ },
+ ],
+ };
+ const res = validateManifest(noDownManifest);
+ expect(res.valid).toBe(false);
+ expect(res.errors[0]).toContain("requires an author-provided down step");
+ });
+ });
+
+ // =========================================================================
+ // 2. Filesystem Security: Path Traversal, Symlinks & Max Size
+ // =========================================================================
+ describe("Filesystem Security & Discovery", () => {
+ test("rejects path traversal containing '..' or null bytes", () => {
+ expect(() => validateSafeFilePath(path.join(mongoDir, "../secret.json"), mongoDir)).toThrow(
+ MongoApiError,
+ );
+
+ expect(() => validateSafeFilePath(path.join(mongoDir, "manifest\0.json"), mongoDir)).toThrow(
+ MongoApiError,
+ );
+ });
+
+ test("rejects files outside migration directory", () => {
+ const outsideFile = path.join(tempDir, "outside.mql.json");
+ fs.writeFileSync(outsideFile, "{}");
+
+ expect(() => validateSafeFilePath(outsideFile, mongoDir)).toThrow(MongoApiError);
+ });
+
+ test("rejects oversized manifests (>1MB)", async () => {
+ const bigFile = path.join(mongoDir, "20261031120000_huge.mql.json");
+ // Create a file > 1MB
+ const buffer = Buffer.alloc(MAX_MANIFEST_SIZE_BYTES + 10, "x");
+ fs.writeFileSync(bigFile, buffer);
+
+ await expect(applyMigration(mockEngine.db, tempDir, "20261031120000")).rejects.toThrow(
+ MongoApiError,
+ );
+
+ try {
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+ } catch (err: any) {
+ expect(err.code).toBe("MANIFEST_SIZE_EXCEEDED");
+ }
+ });
+
+ test("listMigrations discovers valid files and correctly reports pending", async () => {
+ const file1 = path.join(mongoDir, "20261031120000_init_users.mql.json");
+ const manifest1: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "init_users",
+ up: [{ type: "createCollection", collection: "users" }],
+ };
+ fs.writeFileSync(file1, JSON.stringify(manifest1, null, 2));
+
+ const listRes = await listMigrations(mockEngine.db, tempDir);
+ expect(listRes.pendingMigrations).toHaveLength(1);
+ expect(listRes.pendingMigrations[0].id).toBe("20261031120000");
+ expect(listRes.pendingMigrations[0].name).toBe("init_users");
+ expect(listRes.appliedMigrations).toHaveLength(0);
+ expect(listRes.isLocked).toBe(false);
+ });
+ });
+
+ // =========================================================================
+ // 3. Multi-Step Execution, Checkpoints & Journaling
+ // =========================================================================
+ describe("Multi-Step Execution & Checkpoints", () => {
+ test("applies multi-step migration and records per-step events and summary", async () => {
+ const file = path.join(mongoDir, "20261031120000_setup.mql.json");
+ const manifest: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "setup_app",
+ up: [
+ { type: "createCollection", collection: "users" },
+ {
+ type: "createIndex",
+ collection: "users",
+ key: { email: 1 },
+ options: { unique: true },
+ },
+ {
+ type: "setValidator",
+ collection: "users",
+ validator: { $jsonSchema: { bsonType: "object", required: ["email"] } },
+ },
+ ],
+ };
+ fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+
+ const res = await applyMigration(mockEngine.db, tempDir, "20261031120000");
+ expect(res.success).toBe(true);
+ expect(res.appliedCount).toBe(1);
+ expect(res.results[0].status).toBe("APPLIED");
+ expect(res.results[0].executedSteps).toBe(3);
+
+ // Verify materialized summary in _relwave_migrations
+ const summary = mockEngine.summaries.get("20261031120000");
+ expect(summary).toBeDefined();
+ expect(summary?.status).toBe("APPLIED");
+ expect(summary?.executedSteps).toBe(3);
+ expect(summary?.fencingToken).toBe(1);
+
+ // Verify events in _relwave_migration_events
+ const eventTypes = mockEngine.events.map((e) => e.eventType);
+ expect(eventTypes).toContain("VALIDATION_SUCCESS");
+ expect(eventTypes).toContain("LOCK_ACQUIRED");
+ expect(eventTypes).toContain("MIGRATION_START");
+ expect(eventTypes).toContain("STEP_START");
+ expect(eventTypes).toContain("STEP_COMPLETE");
+ expect(eventTypes).toContain("MIGRATION_APPLIED");
+ expect(eventTypes).toContain("LOCK_RELEASED");
+
+ // Verify lock was safely released
+ expect(mockEngine.locks.get(LOCK_DOC_ID)?.ownerId).toBeNull();
+ });
+
+ test("cannot re-apply an already applied migration", async () => {
+ const file = path.join(mongoDir, "20261031120000_setup.mql.json");
+ const manifest: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "setup",
+ up: [{ type: "createCollection", collection: "items" }],
+ };
+ fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+
+ await expect(applyMigration(mockEngine.db, tempDir, "20261031120000")).rejects.toThrow(
+ MongoApiError,
+ );
+
+ try {
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+ } catch (err: any) {
+ expect(err.code).toBe("MIGRATION_ALREADY_APPLIED");
+ }
+ });
+
+ test("rejects if manifest content was tampered with after applying (checksum mismatch)", async () => {
+ const file = path.join(mongoDir, "20261031120000_setup.mql.json");
+ const manifest: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "setup",
+ up: [{ type: "createCollection", collection: "items" }],
+ };
+ fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+
+ // Tamper with file
+ manifest.name = "tampered_name";
+ fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+
+ await expect(applyMigration(mockEngine.db, tempDir, "20261031120000")).rejects.toThrow(
+ MongoApiError,
+ );
+
+ try {
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+ } catch (err: any) {
+ expect(err.code).toBe("CHECKSUM_MISMATCH");
+ }
+ });
+ });
+
+ // =========================================================================
+ // 4. Failure Unwind & Reverse Compensation State Machine
+ // =========================================================================
+ describe("Failure Unwind & Reverse Compensation", () => {
+ test("intermediate step failure triggers reverse compensation -> ROLLED_BACK", async () => {
+ const file = path.join(mongoDir, "20261031120000_failing.mql.json");
+ const manifest: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "partial_fail",
+ up: [
+ { type: "createCollection", collection: "accounts" },
+ {
+ type: "createIndex",
+ collection: "accounts",
+ key: { username: 1 },
+ options: { name: "idx_user" },
+ },
+ // Step 3 will fail because collection "nonexistent" is missing for dropIndex
+ { type: "dropIndex", collection: "nonexistent_collection", indexName: "nonexistent_idx" },
+ ],
+ };
+ fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+
+ await expect(applyMigration(mockEngine.db, tempDir, "20261031120000")).rejects.toThrow();
+
+ // Check summary
+ const summary = mockEngine.summaries.get("20261031120000");
+ expect(summary?.status).toBe("ROLLED_BACK");
+
+ // Check events recorded reverse compensation
+ const eventTypes = mockEngine.events.map((e) => e.eventType);
+ expect(eventTypes).toContain("STEP_FAILED");
+ expect(eventTypes).toContain("COMPENSATION_START");
+ expect(eventTypes).toContain("COMPENSATION_COMPLETE");
+ expect(eventTypes).toContain("MIGRATION_ROLLED_BACK");
+
+ // Verify that step 1 (createCollection) was compensated by dropping collection
+ expect(mockEngine.collectionsData.has("accounts")).toBe(false);
+ // Verify lock was released
+ expect(mockEngine.locks.get(LOCK_DOC_ID)?.ownerId).toBeNull();
+ });
+
+ test("count-guarded createCollection compensation aborts when external data present -> FAILED_MANUAL_INTERVENTION_REQUIRED", async () => {
+ const file = path.join(mongoDir, "20261031120000_countguard.mql.json");
+ const manifest: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "count_guard_test",
+ up: [
+ { type: "createCollection", collection: "wallets" },
+ // Step 2 fails deliberately
+ { type: "dropIndex", collection: "missing_coll", indexName: "missing_idx" },
+ ],
+ };
+ fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+
+ // Hook into collection creation to simulate external data insertion before compensation
+ const originalCreateCollection = mockEngine.db.createCollection;
+ mockEngine.db.createCollection = async (name: string, options?: any) => {
+ const res = await originalCreateCollection.call(mockEngine.db, name, options);
+ if (name === "wallets") {
+ // Simulate concurrent insertion of an external document
+ mockEngine.collectionsData.get("wallets")!.push({ _id: "doc1", balance: 100 });
+ }
+ return res;
+ };
+
+ await expect(applyMigration(mockEngine.db, tempDir, "20261031120000")).rejects.toThrow();
+
+ // Summary must transition to FAILED_MANUAL_INTERVENTION_REQUIRED
+ const summary = mockEngine.summaries.get("20261031120000");
+ expect(summary?.status).toBe("FAILED_MANUAL_INTERVENTION_REQUIRED");
+
+ const eventTypes = mockEngine.events.map((e) => e.eventType);
+ expect(eventTypes).toContain("COMPENSATION_FAILED");
+ expect(eventTypes).toContain("MANUAL_INTERVENTION_REQUIRED");
+
+ // Wallets collection was NOT dropped (data preserved!)
+ expect(mockEngine.collectionsData.has("wallets")).toBe(true);
+ expect(mockEngine.collectionsData.get("wallets")!).toHaveLength(1);
+ });
+
+ test("pre-step fencing loss marks STEP_UNCERTAIN and halts execution immediately", async () => {
+ const file = path.join(mongoDir, "20261031120000_fencing.mql.json");
+ const manifest: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "fencing_loss_test",
+ up: [
+ { type: "createCollection", collection: "products" },
+ { type: "createIndex", collection: "products", key: { sku: 1 } },
+ ],
+ };
+ fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+
+ // Hook step 1 to simulate lock stolen by another client
+ const origCreateCollection = mockEngine.db.createCollection;
+ mockEngine.db.createCollection = async (name: string, options?: any) => {
+ const res = await origCreateCollection.call(mockEngine.db, name, options);
+ // Another client steals the lock and increments fencingToken
+ const lock = mockEngine.locks.get(LOCK_DOC_ID)!;
+ lock.ownerId = "client-B";
+ lock.fencingToken = lock.fencingToken + 1;
+ return res;
+ };
+
+ let thrownError: any;
+ try {
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+ } catch (err: any) {
+ thrownError = err;
+ }
+ expect(thrownError).toBeInstanceOf(MongoApiError);
+ expect(thrownError.code).toBe("LOCK_LOST_FENCING_VIOLATION");
+
+ const eventTypes = mockEngine.events.map((e) => e.eventType);
+ expect(eventTypes).toContain("STEP_UNCERTAIN");
+ expect(eventTypes).toContain("MANUAL_INTERVENTION_REQUIRED");
+
+ const summary = mockEngine.summaries.get("20261031120000");
+ expect(summary?.status).toBe("CRASHED_UNCERTAIN");
+ });
+ });
+
+ // =========================================================================
+ // 5. Rollback Method & Read-Only Checks
+ // =========================================================================
+ describe("Rollback & Read-Only Enforcement", () => {
+ test("rollback cleans up applied steps in reverse order", async () => {
+ const file = path.join(mongoDir, "20261031120000_rollback.mql.json");
+ const manifest: MongoMigrationManifest = {
+ version: "1.0",
+ id: "20261031120000",
+ name: "for_rollback",
+ up: [
+ { type: "createCollection", collection: "books" },
+ {
+ type: "createIndex",
+ collection: "books",
+ key: { isbn: 1 },
+ options: { name: "idx_isbn" },
+ },
+ ],
+ };
+ fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+ expect(mockEngine.collectionsData.has("books")).toBe(true);
+
+ const rollRes = await rollbackMigration(mockEngine.db, "20261031120000", tempDir);
+ expect(rollRes.success).toBe(true);
+ expect(rollRes.status).toBe("ROLLED_BACK");
+ expect(rollRes.stepsCompensated).toBe(2);
+
+ expect(mockEngine.collectionsData.has("books")).toBe(false);
+ const summary = mockEngine.summaries.get("20261031120000");
+ expect(summary?.status).toBe("ROLLED_BACK");
+ });
+
+ test("rejects apply and rollback on read-only database connections", async () => {
+ const file = path.join(mongoDir, "20261031120000_readonly.mql.json");
+ fs.writeFileSync(
+ file,
+ JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "ro_test",
+ up: [{ type: "createCollection", collection: "ro_coll" }],
+ }),
+ );
+
+ await expect(
+ applyMigration(mockEngine.db, tempDir, "20261031120000", { readOnly: true }),
+ ).rejects.toThrow(MongoApiError);
+
+ try {
+ await applyMigration(mockEngine.db, tempDir, "20261031120000", { readOnly: true });
+ } catch (err: any) {
+ expect(err.code).toBe("MONGO_READ_ONLY");
+ }
+
+ await expect(
+ rollbackMigration(mockEngine.db, "20261031120000", tempDir, { readOnly: true }),
+ ).rejects.toThrow(MongoApiError);
+
+ try {
+ await rollbackMigration(mockEngine.db, "20261031120000", tempDir, { readOnly: true });
+ } catch (err: any) {
+ expect(err.code).toBe("MONGO_READ_ONLY");
+ }
+ });
+ });
+
+ // =========================================================================
+ // 6. rebuildMigrationSummary Projection Rebuild
+ // =========================================================================
+ describe("rebuildMigrationSummary", () => {
+ test("rebuilds summary from event stream correctly after simulated crash", async () => {
+ const migrationId = "20261031120000";
+ // Simulate events recorded in _relwave_migration_events
+ mockEngine.events.push(
+ {
+ _id: `${migrationId}_meta_MIGRATION_START_1`,
+ eventId: "e1",
+ migrationId,
+ attemptId: "att1",
+ attemptNumber: 1,
+ sequenceNumber: 1,
+ eventType: "MIGRATION_START",
+ timestamp: "2026-10-31T12:00:00.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ },
+ {
+ _id: `${migrationId}_0_STEP_START_1`,
+ eventId: "e2",
+ migrationId,
+ attemptId: "att1",
+ attemptNumber: 1,
+ sequenceNumber: 2,
+ stepIndex: 0,
+ stepType: "createCollection",
+ eventType: "STEP_START",
+ timestamp: "2026-10-31T12:00:01.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ },
+ {
+ _id: `${migrationId}_0_STEP_COMPLETE_1`,
+ eventId: "e3",
+ migrationId,
+ attemptId: "att1",
+ attemptNumber: 1,
+ sequenceNumber: 3,
+ stepIndex: 0,
+ stepType: "createCollection",
+ eventType: "STEP_COMPLETE",
+ timestamp: "2026-10-31T12:00:02.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ metadata: { durationMs: 25 },
+ },
+ {
+ _id: `${migrationId}_meta_MIGRATION_APPLIED_1`,
+ eventId: "e4",
+ migrationId,
+ attemptId: "att1",
+ attemptNumber: 1,
+ sequenceNumber: 4,
+ eventType: "MIGRATION_APPLIED",
+ timestamp: "2026-10-31T12:00:03.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ },
+ );
+
+ // Rebuild summary
+ const rebuilt = await rebuildMigrationSummary(mockEngine.db, migrationId);
+ expect(rebuilt._id).toBe(migrationId);
+ expect(rebuilt.status).toBe("APPLIED");
+ expect(rebuilt.executedSteps).toBe(1);
+ expect(rebuilt.durationMs).toBe(25);
+ expect(rebuilt.fencingToken).toBe(1);
+ expect(rebuilt.appliedBy).toBe("worker-1");
+
+ const saved = mockEngine.summaries.get(migrationId);
+ expect(saved?.status).toBe("APPLIED");
+ });
+
+ test("detects dangling STEP_START as CRASHED_UNCERTAIN", async () => {
+ const migrationId = "20261031999999";
+ mockEngine.events.push(
+ {
+ _id: `${migrationId}_meta_MIGRATION_START_1`,
+ eventId: "e1",
+ migrationId,
+ attemptId: "att1",
+ attemptNumber: 1,
+ sequenceNumber: 1,
+ eventType: "MIGRATION_START",
+ timestamp: "2026-10-31T12:00:00.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ },
+ {
+ _id: `${migrationId}_0_STEP_START_1`,
+ eventId: "e2",
+ migrationId,
+ attemptId: "att1",
+ attemptNumber: 1,
+ sequenceNumber: 2,
+ stepIndex: 0,
+ stepType: "createIndex",
+ eventType: "STEP_START",
+ timestamp: "2026-10-31T12:00:01.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ },
+ );
+
+ const rebuilt = await rebuildMigrationSummary(mockEngine.db, migrationId);
+ expect(rebuilt.status).toBe("CRASHED_UNCERTAIN");
+ });
+
+ test("handles multiple attempts: failed attempt followed by successful attempt rebuilds to APPLIED", async () => {
+ const migrationId = "20261031888888";
+ // Attempt 1: Started and rolled back
+ mockEngine.events.push(
+ {
+ _id: `${migrationId}_a1_s1`,
+ eventId: "att1-e1",
+ migrationId,
+ attemptId: "att-1",
+ attemptNumber: 1,
+ sequenceNumber: 1,
+ eventType: "MIGRATION_START",
+ timestamp: "2026-10-31T12:00:00.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ },
+ {
+ _id: `${migrationId}_a1_s2`,
+ eventId: "att1-e2",
+ migrationId,
+ attemptId: "att-1",
+ attemptNumber: 1,
+ sequenceNumber: 2,
+ stepIndex: 0,
+ stepType: "createCollection",
+ eventType: "STEP_START",
+ timestamp: "2026-10-31T12:00:01.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ },
+ {
+ _id: `${migrationId}_a1_s3`,
+ eventId: "att1-e3",
+ migrationId,
+ attemptId: "att-1",
+ attemptNumber: 1,
+ sequenceNumber: 3,
+ stepIndex: 0,
+ stepType: "createCollection",
+ eventType: "STEP_FAILED",
+ timestamp: "2026-10-31T12:00:02.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ metadata: { error: { message: "Simulated failure in attempt 1" } },
+ },
+ {
+ _id: `${migrationId}_a1_s4`,
+ eventId: "att1-e4",
+ migrationId,
+ attemptId: "att-1",
+ attemptNumber: 1,
+ sequenceNumber: 4,
+ eventType: "MIGRATION_ROLLED_BACK",
+ timestamp: "2026-10-31T12:00:03.000Z",
+ lockOwnerId: "worker-1",
+ fencingToken: 1,
+ },
+ );
+
+ // Attempt 2: Succeeds
+ mockEngine.events.push(
+ {
+ _id: `${migrationId}_a2_s1`,
+ eventId: "att2-e1",
+ migrationId,
+ attemptId: "att-2",
+ attemptNumber: 2,
+ sequenceNumber: 1,
+ eventType: "MIGRATION_START",
+ timestamp: "2026-10-31T12:01:00.000Z",
+ lockOwnerId: "worker-2",
+ fencingToken: 2,
+ },
+ {
+ _id: `${migrationId}_a2_s2`,
+ eventId: "att2-e2",
+ migrationId,
+ attemptId: "att-2",
+ attemptNumber: 2,
+ sequenceNumber: 2,
+ stepIndex: 0,
+ stepType: "createCollection",
+ eventType: "STEP_START",
+ timestamp: "2026-10-31T12:01:01.000Z",
+ lockOwnerId: "worker-2",
+ fencingToken: 2,
+ },
+ {
+ _id: `${migrationId}_a2_s3`,
+ eventId: "att2-e3",
+ migrationId,
+ attemptId: "att-2",
+ attemptNumber: 2,
+ sequenceNumber: 3,
+ stepIndex: 0,
+ stepType: "createCollection",
+ eventType: "STEP_COMPLETE",
+ timestamp: "2026-10-31T12:01:02.000Z",
+ lockOwnerId: "worker-2",
+ fencingToken: 2,
+ metadata: { durationMs: 15 },
+ },
+ {
+ _id: `${migrationId}_a2_s4`,
+ eventId: "att2-e4",
+ migrationId,
+ attemptId: "att-2",
+ attemptNumber: 2,
+ sequenceNumber: 4,
+ eventType: "MIGRATION_APPLIED",
+ timestamp: "2026-10-31T12:01:03.000Z",
+ lockOwnerId: "worker-2",
+ fencingToken: 2,
+ },
+ );
+
+ const rebuilt = await rebuildMigrationSummary(mockEngine.db, migrationId, {
+ version: "1.0",
+ id: migrationId,
+ name: "multi_attempt_test",
+ up: [{ type: "createCollection", collection: "multi_coll" }],
+ });
+
+ expect(rebuilt.status).toBe("APPLIED");
+ expect(rebuilt.executedSteps).toBe(1);
+ expect(rebuilt.attemptNumber).toBe(2);
+ expect(rebuilt.attemptId).toBe("att-2");
+ expect(rebuilt.appliedBy).toBe("worker-2");
+ });
+ });
+
+ // =========================================================================
+ // 7. getMigrationStatus
+ // =========================================================================
+ describe("getMigrationStatus", () => {
+ test("returns summary, events, and lock status", async () => {
+ const file = path.join(mongoDir, "20261031120000_status.mql.json");
+ fs.writeFileSync(
+ file,
+ JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "status_test",
+ up: [{ type: "createCollection", collection: "status_coll" }],
+ }),
+ );
+
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+
+ const statusRes = await getMigrationStatus(mockEngine.db, "20261031120000");
+ expect(statusRes.migration?.status).toBe("APPLIED");
+ expect(statusRes.events?.length).toBeGreaterThan(0);
+ expect(statusRes.lockStatus.isLocked).toBe(false);
+ expect(statusRes.lastAppliedVersion).toBe("20261031120000");
+ });
+ });
+
+ // =========================================================================
+ // 8. Safety Audit Hardening & Compensation (Phase 3)
+ // =========================================================================
+ describe("Safety Audit Hardening & Compensation (Phase 3)", () => {
+ test("event journal assigns unique deterministic _id and monotonic sequenceNumber", async () => {
+ const file = path.join(mongoDir, "20261031120000_sequential_events.mql.json");
+ fs.writeFileSync(
+ file,
+ JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "sequential_events",
+ up: [
+ { type: "createCollection", collection: "seq_coll1" },
+ { type: "createCollection", collection: "seq_coll2" },
+ ],
+ }),
+ );
+
+ const res = await applyMigration(mockEngine.db, tempDir, "20261031120000");
+ expect(res.success).toBe(true);
+
+ const events = mockEngine.events.filter((e) => e.migrationId === "20261031120000");
+ expect(events.length).toBeGreaterThanOrEqual(4);
+
+ const seenIds = new Set();
+ let expectedSeq = 1;
+ for (const ev of events) {
+ expect(ev.sequenceNumber).toBe(expectedSeq);
+ expect(ev._id).toBe(`20261031120000_a1_s${expectedSeq}`);
+ expect(seenIds.has(ev._id)).toBe(false);
+ seenIds.add(ev._id);
+ expectedSeq++;
+ }
+ });
+
+ test("dry-run does not acquire lock or write events", async () => {
+ const file = path.join(mongoDir, "20261031120000_dry_run.mql.json");
+ fs.writeFileSync(
+ file,
+ JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "dry_run_test",
+ up: [{ type: "createCollection", collection: "dry_coll" }],
+ }),
+ );
+
+ const result = await applyMigration(mockEngine.db, tempDir, "20261031120000", {
+ dryRun: true,
+ });
+ expect(result.success).toBe(true);
+ expect(result.results[0].status).toBe("PENDING");
+
+ // Lock was not acquired
+ expect(mockEngine.locks.size).toBe(0);
+
+ // No events written
+ expect(mockEngine.events.length).toBe(0);
+
+ // No collection created
+ expect(mockEngine.collectionsData.has("dry_coll")).toBe(false);
+ });
+
+ test("compensation of createCollection halts when collection is non-empty", async () => {
+ const file = path.join(mongoDir, "20261031120000_guard_coll.mql.json");
+ fs.writeFileSync(
+ file,
+ JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "guard_coll_test",
+ up: [
+ { type: "createCollection", collection: "guard_coll" },
+ { type: "createCollection", collection: "failing_coll" },
+ ],
+ }),
+ );
+
+ const origCreateCollection = mockEngine.db.createCollection;
+ mockEngine.db.createCollection = async function (name: string, options?: any) {
+ if (name === "failing_coll") {
+ // Simulate user documents written to guard_coll before second step fails
+ mockEngine.collectionsData.get("guard_coll")!.push({ _id: 1, name: "external doc" });
+ throw new Error("Simulated failure on second step");
+ }
+ return origCreateCollection.call(this, name, options);
+ };
+
+ await expect(applyMigration(mockEngine.db, tempDir, "20261031120000")).rejects.toThrow(
+ "Simulated failure on second step",
+ );
+
+ const summary = mockEngine.summaries.get("20261031120000");
+ expect(summary?.status).toBe("FAILED_MANUAL_INTERVENTION_REQUIRED");
+ expect((summary?.error as any)?.message).toContain(
+ "contains 1 documents added after creation",
+ );
+
+ // guard_coll must NOT be dropped
+ expect(mockEngine.collectionsData.has("guard_coll")).toBe(true);
+ expect(mockEngine.collectionsData.get("guard_coll")?.length).toBe(1);
+ });
+
+ test("compensation of dropIndex throws when pre-state is missing and down block is absent", async () => {
+ await expect(
+ compensateStep(
+ mockEngine.db,
+ { type: "dropIndex", collection: "orders", indexName: "idx_custom" },
+ null, // missing preState
+ undefined, // no down block
+ ),
+ ).rejects.toThrow(MongoApiError);
+
+ try {
+ await compensateStep(
+ mockEngine.db,
+ { type: "dropIndex", collection: "orders", indexName: "idx_custom" },
+ null,
+ undefined,
+ );
+ } catch (err: any) {
+ expect(err.code).toBe("COMPENSATION_FAILED");
+ expect(err.message).toContain(
+ "pre-state missing and no matching createIndex found in down steps",
+ );
+ }
+ });
+
+ test("in-flight heartbeat loss causes pre-step fencing failure", async () => {
+ const file = path.join(mongoDir, "20261031120000_fencing_loss.mql.json");
+ fs.writeFileSync(
+ file,
+ JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "fencing_loss_test",
+ up: [
+ { type: "createCollection", collection: "fence_coll1" },
+ { type: "createCollection", collection: "fence_coll2" },
+ ],
+ }),
+ );
+
+ let step = 0;
+ const origCreateCollection = mockEngine.db.createCollection;
+ mockEngine.db.createCollection = async function (name: string, options?: any) {
+ step++;
+ const res = await origCreateCollection.call(this, name, options);
+ if (step === 1) {
+ // Lease stolen by another worker
+ const lockDoc = mockEngine.locks.get(LOCK_DOC_ID);
+ if (lockDoc) {
+ lockDoc.ownerId = "stealing-worker";
+ lockDoc.fencingToken = 99;
+ }
+ }
+ return res;
+ };
+
+ try {
+ await applyMigration(mockEngine.db, tempDir, "20261031120000");
+ expect(true).toBe(false); // should not reach
+ } catch (err: any) {
+ expect(err).toBeInstanceOf(MongoApiError);
+ expect(err.code).toBe("LOCK_LOST_FENCING_VIOLATION");
+ }
+
+ const summary = mockEngine.summaries.get("20261031120000");
+ expect(summary?.status).toBe("CRASHED_UNCERTAIN");
+
+ const events = mockEngine.events.filter((e) => e.migrationId === "20261031120000");
+ expect(events.some((e) => e.eventType === "STEP_UNCERTAIN")).toBe(true);
+ expect(events.some((e) => e.eventType === "MANUAL_INTERVENTION_REQUIRED")).toBe(true);
+ });
+ });
+});
diff --git a/bridge/__tests__/mongoMigrationLock.test.ts b/bridge/__tests__/mongoMigrationLock.test.ts
new file mode 100644
index 00000000..d963db8d
--- /dev/null
+++ b/bridge/__tests__/mongoMigrationLock.test.ts
@@ -0,0 +1,395 @@
+import { describe, expect, test, beforeEach } from "@jest/globals";
+import { Db } from "mongodb";
+import {
+ acquireLock,
+ renewLockHeartbeat,
+ releaseLock,
+ checkLockStatus,
+ verifyLock,
+ LOCK_COLLECTION,
+ LOCK_DOC_ID,
+} from "../src/services/mongoMigrationLock";
+import { MongoApiError } from "../src/connectors/mongo";
+import { MongoMigrationLockDoc } from "../src/types/mongoMigration";
+
+/**
+ * Creates an in-memory mock MongoDB Db for lock testing.
+ */
+function createMockLockDb(): { db: Db; store: Map } {
+ const store = new Map();
+
+ const collectionMock = {
+ async findOneAndUpdate(filter: any, update: any, options?: any) {
+ const existing = store.get(LOCK_DOC_ID);
+ const now = new Date();
+
+ if (!existing) {
+ // Document does not exist: upsert
+ const fencingToken = update.$inc?.fencingToken || 1;
+ const newDoc: MongoMigrationLockDoc = {
+ _id: LOCK_DOC_ID,
+ ownerId: update.$set?.ownerId || null,
+ migrationId: update.$set?.migrationId || null,
+ acquiredAt: update.$set?.acquiredAt || now,
+ heartbeatAt: update.$set?.heartbeatAt || now,
+ expiresAt: update.$set?.expiresAt || new Date(now.getTime() + 60000),
+ fencingToken,
+ };
+ store.set(LOCK_DOC_ID, newDoc);
+ return newDoc;
+ }
+
+ // Check filter condition
+ const ownerMatch = filter.$or?.some((cond: any) => {
+ if ("ownerId" in cond && cond.ownerId === existing.ownerId) return true;
+ if ("ownerId" in cond && cond.ownerId === null && existing.ownerId === null) return true;
+ if (
+ cond.expiresAt?.$lt &&
+ existing.expiresAt &&
+ new Date(existing.expiresAt).getTime() < new Date(cond.expiresAt.$lt).getTime()
+ ) {
+ return true;
+ }
+ return false;
+ });
+
+ if (ownerMatch) {
+ const fencingToken = (existing.fencingToken || 0) + (update.$inc?.fencingToken || 1);
+ const updatedDoc: MongoMigrationLockDoc = {
+ ...existing,
+ ownerId: update.$set?.ownerId !== undefined ? update.$set.ownerId : existing.ownerId,
+ migrationId:
+ update.$set?.migrationId !== undefined ? update.$set.migrationId : existing.migrationId,
+ acquiredAt: update.$set?.acquiredAt || now,
+ heartbeatAt: update.$set?.heartbeatAt || now,
+ expiresAt: update.$set?.expiresAt || existing.expiresAt,
+ fencingToken,
+ };
+ store.set(LOCK_DOC_ID, updatedDoc);
+ return updatedDoc;
+ }
+
+ // If document exists with _id: "migration_lock", but filter doesn't match and upsert: true,
+ // MongoDB throws E11000 duplicate key error.
+ if (options?.upsert) {
+ const err: any = new Error("E11000 duplicate key error collection");
+ err.code = 11000;
+ throw err;
+ }
+
+ return null;
+ },
+
+ async findOne(filter: any) {
+ if (filter._id === LOCK_DOC_ID) {
+ const doc = store.get(LOCK_DOC_ID);
+ if (!doc) return null;
+
+ if (filter.ownerId && doc.ownerId !== filter.ownerId) return null;
+ if (filter.fencingToken !== undefined && doc.fencingToken !== filter.fencingToken)
+ return null;
+ if (filter.expiresAt?.$gt) {
+ if (
+ !doc.expiresAt ||
+ new Date(doc.expiresAt).getTime() <= new Date(filter.expiresAt.$gt).getTime()
+ ) {
+ return null;
+ }
+ }
+ return { ...doc };
+ }
+ return null;
+ },
+
+ async updateOne(filter: any, update: any) {
+ const doc = store.get(LOCK_DOC_ID);
+ if (!doc) return { matchedCount: 0, modifiedCount: 0 };
+
+ if (filter.ownerId && doc.ownerId !== filter.ownerId)
+ return { matchedCount: 0, modifiedCount: 0 };
+ if (filter.fencingToken !== undefined && doc.fencingToken !== filter.fencingToken) {
+ return { matchedCount: 0, modifiedCount: 0 };
+ }
+ if (filter.expiresAt?.$gt) {
+ if (
+ !doc.expiresAt ||
+ new Date(doc.expiresAt).getTime() <= new Date(filter.expiresAt.$gt).getTime()
+ ) {
+ return { matchedCount: 0, modifiedCount: 0 };
+ }
+ }
+
+ if (update.$set) {
+ Object.assign(doc, update.$set);
+ }
+ return { matchedCount: 1, modifiedCount: 1 };
+ },
+
+ async deleteOne(filter: any) {
+ const doc = store.get(LOCK_DOC_ID);
+ if (!doc) return { deletedCount: 0 };
+
+ if (filter.ownerId && doc.ownerId !== filter.ownerId) return { deletedCount: 0 };
+ if (filter.fencingToken !== undefined && doc.fencingToken !== filter.fencingToken) {
+ return { deletedCount: 0 };
+ }
+
+ store.delete(LOCK_DOC_ID);
+ return { deletedCount: 1 };
+ },
+ };
+
+ const dbMock: any = {
+ collection(name: string) {
+ if (name === LOCK_COLLECTION) {
+ return collectionMock;
+ }
+ throw new Error(`Collection '${name}' not implemented in mock`);
+ },
+ };
+
+ return { db: dbMock, store };
+}
+
+describe("mongoMigrationLock Unit Tests (M6 Spec §6)", () => {
+ let mockDb: Db;
+ let store: Map;
+
+ beforeEach(() => {
+ const mock = createMockLockDb();
+ mockDb = mock.db;
+ store = mock.store;
+ });
+
+ test("acquires lock successfully when unheld", async () => {
+ const res = await acquireLock(mockDb, "client-A", "20261031120000", 60000);
+ expect(res.success).toBe(true);
+ expect(res.fencingToken).toBe(1);
+ expect(res.expiresAt.getTime()).toBeGreaterThan(Date.now());
+
+ const doc = store.get(LOCK_DOC_ID);
+ expect(doc?.ownerId).toBe("client-A");
+ expect(doc?.migrationId).toBe("20261031120000");
+ expect(doc?.fencingToken).toBe(1);
+ });
+
+ test("second client is blocked while lock is owned by an active lease", async () => {
+ await acquireLock(mockDb, "client-A", "20261031120000", 60000);
+
+ await expect(acquireLock(mockDb, "client-B", "20261031120000", 60000, 1)).rejects.toThrow(
+ MongoApiError,
+ );
+
+ try {
+ await acquireLock(mockDb, "client-B", "20261031120000", 60000, 1);
+ } catch (err: any) {
+ expect(err).toBeInstanceOf(MongoApiError);
+ expect(err.code).toBe("LOCK_ALREADY_HELD");
+ expect(err.message).toContain("Migration lock held by client-A");
+ }
+ });
+
+ test("retries on E11000 duplicate key error and acquires lock when released", async () => {
+ let callCount = 0;
+ const originalFindOneAndUpdate = (mockDb.collection(LOCK_COLLECTION) as any).findOneAndUpdate;
+
+ (mockDb.collection(LOCK_COLLECTION) as any).findOneAndUpdate = async function (...args: any[]) {
+ callCount++;
+ if (callCount === 1) {
+ const err: any = new Error("E11000 duplicate key error on concurrent upsert");
+ err.code = 11000;
+ throw err;
+ }
+ return originalFindOneAndUpdate.apply(this, args);
+ };
+
+ const res = await acquireLock(mockDb, "client-retry", "20261031120000", 60000, 3);
+ expect(res.success).toBe(true);
+ expect(res.fencingToken).toBe(1);
+ expect(callCount).toBe(2);
+ });
+
+ test("acquires lock after lease expires and increments fencing token", async () => {
+ // Client A acquires with expired lease in the past
+ store.set(LOCK_DOC_ID, {
+ _id: LOCK_DOC_ID,
+ ownerId: "stale-client",
+ fencingToken: 5,
+ acquiredAt: new Date(Date.now() - 100000),
+ heartbeatAt: new Date(Date.now() - 90000),
+ expiresAt: new Date(Date.now() - 30000), // Expired 30 seconds ago
+ migrationId: "20261031000000",
+ });
+
+ const res = await acquireLock(mockDb, "new-client", "20261031120000", 60000);
+ expect(res.success).toBe(true);
+ expect(res.fencingToken).toBe(6); // Incremented from 5 to 6
+
+ const doc = store.get(LOCK_DOC_ID);
+ expect(doc?.ownerId).toBe("new-client");
+ expect(doc?.fencingToken).toBe(6);
+ });
+
+ test("renews lock heartbeat for valid owner and fencing token", async () => {
+ const lock = await acquireLock(mockDb, "client-A", "20261031120000", 60000);
+ const initialExpires = lock.expiresAt;
+
+ // Small delay to ensure timestamp progression
+ await new Promise((r) => setTimeout(r, 10));
+
+ const renewed = await renewLockHeartbeat(mockDb, "client-A", lock.fencingToken, 120000);
+ expect(renewed).toBe(true);
+
+ const doc = store.get(LOCK_DOC_ID);
+ expect(new Date(doc!.expiresAt!).getTime()).toBeGreaterThan(initialExpires.getTime());
+
+ // Wrong owner cannot renew
+ const wrongOwnerRenewed = await renewLockHeartbeat(
+ mockDb,
+ "impostor",
+ lock.fencingToken,
+ 60000,
+ );
+ expect(wrongOwnerRenewed).toBe(false);
+
+ // Wrong fencing token cannot renew
+ const wrongTokenRenewed = await renewLockHeartbeat(
+ mockDb,
+ "client-A",
+ lock.fencingToken + 99,
+ 60000,
+ );
+ expect(wrongTokenRenewed).toBe(false);
+ });
+
+ test("releases lock conditionally matching owner and fencing token", async () => {
+ const lock = await acquireLock(mockDb, "client-A", "20261031120000", 60000);
+
+ // Impostor cannot release
+ const impostorRelease = await releaseLock(mockDb, "impostor", lock.fencingToken);
+ expect(impostorRelease).toBe(false);
+ expect(store.has(LOCK_DOC_ID)).toBe(true);
+
+ // Wrong fencing token cannot release
+ const wrongTokenRelease = await releaseLock(mockDb, "client-A", 999);
+ expect(wrongTokenRelease).toBe(false);
+ expect(store.has(LOCK_DOC_ID)).toBe(true);
+
+ // True owner releases cleanly (leaves doc, sets ownerId: null, preserves fencingToken)
+ const released = await releaseLock(mockDb, "client-A", lock.fencingToken);
+ expect(released).toBe(true);
+ expect(store.has(LOCK_DOC_ID)).toBe(true);
+ expect(store.get(LOCK_DOC_ID)?.ownerId).toBeNull();
+ expect(store.get(LOCK_DOC_ID)?.fencingToken).toBe(1);
+ expect(store.get(LOCK_DOC_ID)?.releasedAt).toBeDefined();
+ });
+
+ test("renewLockHeartbeat returns false and does not revive lease when expiresAt <= now", async () => {
+ const lock = await acquireLock(mockDb, "client-A", "20261031120000", 60000);
+
+ // Expire lease
+ store.get(LOCK_DOC_ID)!.expiresAt = new Date(Date.now() - 5000);
+
+ const renewed = await renewLockHeartbeat(mockDb, "client-A", lock.fencingToken, 60000);
+ expect(renewed).toBe(false);
+
+ // Ensure lease was not revived
+ const doc = store.get(LOCK_DOC_ID);
+ expect(new Date(doc!.expiresAt!).getTime()).toBeLessThan(Date.now());
+ });
+
+ test("releaseLock leaves document and preserves fencingToken monotonically across multiple sequential acquires", async () => {
+ // Token 1
+ const lock1 = await acquireLock(mockDb, "client-1", "m1", 60000);
+ expect(lock1.fencingToken).toBe(1);
+
+ const rel1 = await releaseLock(mockDb, "client-1", lock1.fencingToken);
+ expect(rel1).toBe(true);
+ expect(store.has(LOCK_DOC_ID)).toBe(true);
+ expect(store.get(LOCK_DOC_ID)?.ownerId).toBeNull();
+ expect(store.get(LOCK_DOC_ID)?.fencingToken).toBe(1);
+
+ // Token 2
+ const lock2 = await acquireLock(mockDb, "client-2", "m2", 60000);
+ expect(lock2.fencingToken).toBe(2);
+
+ const rel2 = await releaseLock(mockDb, "client-2", lock2.fencingToken);
+ expect(rel2).toBe(true);
+ expect(store.get(LOCK_DOC_ID)?.ownerId).toBeNull();
+ expect(store.get(LOCK_DOC_ID)?.fencingToken).toBe(2);
+
+ // Token 3
+ const lock3 = await acquireLock(mockDb, "client-3", "m3", 60000);
+ expect(lock3.fencingToken).toBe(3);
+
+ const rel3 = await releaseLock(mockDb, "client-3", lock3.fencingToken);
+ expect(rel3).toBe(true);
+ expect(store.get(LOCK_DOC_ID)?.ownerId).toBeNull();
+ expect(store.get(LOCK_DOC_ID)?.fencingToken).toBe(3);
+ });
+
+ test("previous owner cannot release newer owner's lock", async () => {
+ const lock1 = await acquireLock(mockDb, "client-1", "m1", 100);
+
+ // Expire lease and client-2 acquires lock2 with token 2
+ store.get(LOCK_DOC_ID)!.expiresAt = new Date(Date.now() - 1000);
+ const lock2 = await acquireLock(mockDb, "client-2", "m1", 60000);
+ expect(lock2.fencingToken).toBe(2);
+
+ // Client 1 cannot release with its old token
+ const client1Release = await releaseLock(mockDb, "client-1", lock1.fencingToken);
+ expect(client1Release).toBe(false);
+
+ // Client 1 cannot release even if it guesses lock2's token
+ const client1ReleaseToken2 = await releaseLock(mockDb, "client-1", lock2.fencingToken);
+ expect(client1ReleaseToken2).toBe(false);
+
+ // Lock remains held by client-2
+ const doc = store.get(LOCK_DOC_ID);
+ expect(doc?.ownerId).toBe("client-2");
+ expect(doc?.fencingToken).toBe(2);
+ });
+
+ test("verifies lock status and detects lock loss / stale token", async () => {
+ const lock = await acquireLock(mockDb, "client-A", "20261031120000", 60000);
+
+ // Active lease returns true
+ const valid = await verifyLock(mockDb, "client-A", lock.fencingToken);
+ expect(valid).toBe(true);
+
+ // Wrong owner returns false
+ const wrongOwner = await verifyLock(mockDb, "other", lock.fencingToken);
+ expect(wrongOwner).toBe(false);
+
+ // Stale fencing token returns false
+ const staleToken = await verifyLock(mockDb, "client-A", lock.fencingToken - 1);
+ expect(staleToken).toBe(false);
+
+ // Expired lease returns false
+ store.get(LOCK_DOC_ID)!.expiresAt = new Date(Date.now() - 1000);
+ const expired = await verifyLock(mockDb, "client-A", lock.fencingToken);
+ expect(expired).toBe(false);
+ });
+
+ test("checkLockStatus inspects without mutating document", async () => {
+ // When no lock document exists
+ const emptyStatus = await checkLockStatus(mockDb);
+ expect(emptyStatus.isLocked).toBe(false);
+ expect(emptyStatus.isExpired).toBe(false);
+
+ // When held by active client
+ await acquireLock(mockDb, "client-A", "20261031120000", 60000);
+ const heldStatus = await checkLockStatus(mockDb);
+ expect(heldStatus.isLocked).toBe(true);
+ expect(heldStatus.isExpired).toBe(false);
+ expect(heldStatus.ownerId).toBe("client-A");
+ expect(heldStatus.fencingToken).toBe(1);
+ expect(heldStatus.migrationId).toBe("20261031120000");
+
+ // When lease is expired
+ store.get(LOCK_DOC_ID)!.expiresAt = new Date(Date.now() - 5000);
+ const expiredStatus = await checkLockStatus(mockDb);
+ expect(expiredStatus.isLocked).toBe(false);
+ expect(expiredStatus.isExpired).toBe(true);
+ });
+});
diff --git a/bridge/__tests__/mongoRelationshipEngine.test.ts b/bridge/__tests__/mongoRelationshipEngine.test.ts
new file mode 100644
index 00000000..2b94dad4
--- /dev/null
+++ b/bridge/__tests__/mongoRelationshipEngine.test.ts
@@ -0,0 +1,631 @@
+import { describe, expect, test, beforeEach, jest } from "@jest/globals";
+import { ObjectId } from "mongodb";
+import { MongoRelationshipEngine } from "../src/services/mongoRelationshipEngine";
+import { MongoRelationshipsFile } from "../src/types/mongo";
+
+describe("MongoRelationshipEngine Unit & Heuristic Tests (M7 Phase 1 Remediation)", () => {
+ let engine: MongoRelationshipEngine;
+ let mockDbService: any;
+ let mockProjectStore: any;
+ let storedRelationships: MongoRelationshipsFile;
+
+ beforeEach(() => {
+ storedRelationships = {
+ version: 1,
+ databaseId: "test-db",
+ inferred: [],
+ confirmed: [],
+ rejectedIds: [],
+ manual: [],
+ insufficientEvidence: [],
+ updatedAt: new Date().toISOString(),
+ };
+
+ mockProjectStore = {
+ getMongoRelationships: jest.fn().mockImplementation(async () => storedRelationships),
+ saveMongoRelationships: jest.fn().mockImplementation(async (file: any) => {
+ storedRelationships = file;
+ }),
+ };
+
+ mockDbService = {
+ getDatabaseConnection: jest.fn(),
+ };
+
+ engine = new MongoRelationshipEngine(mockDbService, mockProjectStore);
+ });
+
+ describe("Candidate Name Derivation & Normalization", () => {
+ test("derives candidate collection names and normalizes ObjectIds", () => {
+ expect(engine.deriveCandidateCollectionNames("userId")).toEqual(
+ expect.arrayContaining(["user", "users"]),
+ );
+ expect(engine.deriveCandidateCollectionNames("items.productId")).toEqual(
+ expect.arrayContaining(["product", "products"]),
+ );
+ const oid = new ObjectId("507f1f77bcf86cd799439011");
+ expect(engine.normalizeIdValue(oid)).toBe("507f1f77bcf86cd799439011");
+ expect(engine.normalizeIdValue({ $oid: "507f1f77bcf86cd799439011" })).toBe(
+ "507f1f77bcf86cd799439011",
+ );
+ expect(engine.normalizeIdValue("507f1f77bcf86cd799439011")).toBe("507f1f77bcf86cd799439011");
+ });
+ });
+
+ describe("Embedded Subdocument Arrays & Dotted Paths (LOW-02)", () => {
+ test("extracts embedded subdocument array fields and filters out embedded _ids", () => {
+ const p1 = new ObjectId();
+ const docs = [
+ {
+ _id: new ObjectId(),
+ items: [
+ {
+ _id: new ObjectId(), // Embedded _id MUST be ignored
+ productId: p1,
+ title: "Widget",
+ },
+ ],
+ },
+ ];
+
+ const candidates = engine.extractCandidateFields(docs);
+ const paths = candidates.map((c) => c.sourcePath);
+
+ expect(paths).toContain("items.productId");
+ expect(paths).not.toContain("items._id");
+ expect(paths).not.toContain("_id");
+
+ // Verify extractFieldValue extracts from array of objects
+ const extracted = engine.extractFieldValue(docs[0], "items.productId");
+ expect(extracted).toEqual([p1]);
+ });
+ });
+
+ describe("Unique Index Cardinality Rigor (MED-01)", () => {
+ test("infers one-to-one only for ordinary single-field unique index", async () => {
+ const targetOid = new ObjectId();
+
+ const mockProfilesCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: targetOid }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ const mockUsersCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest
+ .fn()
+ .mockResolvedValue([{ _id: new ObjectId(), profile_id: targetOid }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([
+ { key: { profile_id: 1 }, unique: true }, // valid single-field unique
+ ]),
+ };
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ name: "users" }, { name: "profiles" }]),
+ }),
+ collection: jest.fn((colName: string) => {
+ if (colName === "users") return mockUsersCol;
+ if (colName === "profiles") return mockProfilesCol;
+ throw new Error(`Unknown col ${colName}`);
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ const res = await engine.inferRelationships("test-db");
+ const rel = res.relationships.find((r) => r.id === "users.profile_id->profiles._id")!;
+ expect(rel).toBeDefined();
+ expect(rel.cardinality).toBe("one-to-one");
+ expect(rel.evidence.hasUniqueIndexOnSource).toBe(true);
+ });
+
+ test("excludes sparse, partial, and compound unique indexes from one-to-one", async () => {
+ const targetOid = new ObjectId();
+
+ const mockTargetCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: targetOid }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ const mockSourceCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest
+ .fn()
+ .mockResolvedValue([{ _id: new ObjectId(), target_id: targetOid }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([
+ { key: { target_id: 1 }, unique: true, sparse: true }, // sparse -> excluded!
+ { key: { target_id: 1 }, unique: true, partialFilterExpression: { active: true } }, // partial -> excluded!
+ { key: { target_id: 1, tenant_id: 1 }, unique: true }, // compound -> excluded!
+ ]),
+ };
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ name: "sources" }, { name: "targets" }]),
+ }),
+ collection: jest.fn((colName: string) => {
+ if (colName === "sources") return mockSourceCol;
+ if (colName === "targets") return mockTargetCol;
+ throw new Error(`Unknown col ${colName}`);
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ const res = await engine.inferRelationships("test-db");
+ const rel = res.relationships.find((r) => r.id === "sources.target_id->targets._id")!;
+ expect(rel).toBeDefined();
+ expect(rel.cardinality).not.toBe("one-to-one"); // Must NOT be one-to-one
+ expect(rel.evidence.hasUniqueIndexOnSource).toBe(false);
+ });
+ });
+
+ describe("Insufficient Evidence Semantics (MED-02)", () => {
+ test("separates insufficient evidence (< 0.65) into diagnostic list", async () => {
+ const mockCodesCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: "non_hex_custom_1" }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ // Source field has matching name to "codes" (nameScore = 1.0) and generic string type (typeScore = 0.3)
+ // HitRatio = 0.50 (1/2 matched)
+ // Confidence = 0.55 * 0.5 + 0.25 * 1.0 + 0.20 * 0.3 = 0.275 + 0.25 + 0.06 = 0.585 (< 0.65)
+ const mockSourcesCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([
+ { _id: new ObjectId(), code_id: "non_hex_custom_1" },
+ { _id: new ObjectId(), code_id: "non_matching_value_123" },
+ ]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ name: "sources" }, { name: "codes" }]),
+ }),
+ collection: jest.fn((colName: string) => {
+ if (colName === "sources") return mockSourcesCol;
+ if (colName === "codes") return mockCodesCol;
+ throw new Error(`Unknown col ${colName}`);
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ const res = await engine.inferRelationships("test-db");
+ // Must not be in actionable relationships
+ expect(res.relationships.some((r) => r.sourceField === "code_id")).toBe(false);
+ // Must be in insufficientEvidence diagnostic list
+ const diag = res.insufficientEvidence.find((r) => r.sourceField === "code_id");
+ expect(diag).toBeDefined();
+ expect(diag?.cardinality).toBe("insufficient-evidence");
+ expect(diag?.confidence).toBeLessThan(0.65);
+ });
+ });
+
+ describe("Bounded Target Discovery & Collection Scoping (HIGH-01 / LOW-01)", () => {
+ test("does not query all unrelated collections when candidate name matches", async () => {
+ const u1 = new ObjectId();
+ const mockUsersCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: u1 }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+ const mockOrdersCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: new ObjectId(), userId: u1 }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+ const mockUnrelatedCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest
+ .fn()
+ .mockResolvedValue([
+ { name: "users" },
+ { name: "orders" },
+ { name: "logs" },
+ { name: "analytics" },
+ { name: "audit" },
+ ]),
+ }),
+ collection: jest.fn((colName: string) => {
+ if (colName === "users") return mockUsersCol;
+ if (colName === "orders") return mockOrdersCol;
+ return mockUnrelatedCol;
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ await engine.inferRelationships("test-db");
+
+ // logs, analytics, audit should NOT have target find queries for userId!
+ expect(mockUsersCol.find).toHaveBeenCalled();
+ });
+
+ test("scopes inference to requested collections when provided", async () => {
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest
+ .fn()
+ .mockResolvedValue([{ name: "users" }, { name: "orders" }, { name: "products" }]),
+ }),
+ collection: jest.fn().mockReturnValue({
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ const res = await engine.inferRelationships("test-db", {
+ collections: ["users", "orders"],
+ });
+
+ expect(res.collectionsScanned).toBe(2);
+ expect(mockDb.collection).not.toHaveBeenCalledWith("products");
+ });
+
+ test("does not query arbitrary collections when candidate has no matching target (LOW-REM-02)", async () => {
+ // Source collection has an externalId field (ends in Id), but no collection named externals/external exists
+ const mockSourcesCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest
+ .fn()
+ .mockResolvedValue([{ _id: new ObjectId(), externalId: new ObjectId() }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+ const mockProductsCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+ const mockOrdersCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest
+ .fn()
+ .mockResolvedValue([{ name: "sources" }, { name: "products" }, { name: "orders" }]),
+ }),
+ collection: jest.fn((colName: string) => {
+ if (colName === "sources") return mockSourcesCol;
+ if (colName === "products") return mockProductsCol;
+ if (colName === "orders") return mockOrdersCol;
+ throw new Error(`Unknown col ${colName}`);
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ const res = await engine.inferRelationships("test-db");
+
+ // Target collections should NOT be probed for externalId because neither products nor orders match "external"
+ expect(mockProductsCol.find).not.toHaveBeenCalledWith(
+ expect.objectContaining({ _id: expect.anything() }),
+ expect.anything(),
+ );
+ expect(mockOrdersCol.find).not.toHaveBeenCalledWith(
+ expect.objectContaining({ _id: expect.anything() }),
+ expect.anything(),
+ );
+ expect(res.relationships.length).toBe(0);
+ });
+
+ test("stops inference and reports timedOut when overall deadline is exceeded without persisting partial results (MED-REM-01)", async () => {
+ // Seed pre-existing stored relationships
+ const preExistingInferred = [
+ {
+ id: "orders.customer_id->customers._id",
+ sourceCollection: "orders",
+ sourceField: "customer_id",
+ targetCollection: "customers",
+ targetField: "_id",
+ cardinality: "many-to-one" as const,
+ confidence: 0.9,
+ evidence: {} as any,
+ status: "inferred" as const,
+ inferredAt: "2026-01-01T00:00:00.000Z",
+ },
+ ];
+ storedRelationships.inferred = [...preExistingInferred];
+ storedRelationships.insufficientEvidence = [
+ {
+ id: "orders.code->codes._id",
+ sourceCollection: "orders",
+ sourceField: "code",
+ targetCollection: "codes",
+ targetField: "_id",
+ cardinality: "insufficient-evidence" as const,
+ confidence: 0.4,
+ evidence: {} as any,
+ status: "inferred" as const,
+ inferredAt: "2026-01-01T00:00:00.000Z",
+ },
+ ];
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest
+ .fn()
+ .mockResolvedValue([{ name: "col_1" }, { name: "col_2" }, { name: "col_3" }]),
+ }),
+ collection: jest.fn().mockReturnValue({
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ // Force Date.now to simulate deadline expiry after first collection
+ let calls = 0;
+ const originalNow = Date.now;
+ jest.spyOn(Date, "now").mockImplementation(() => {
+ calls++;
+ return calls > 3 ? originalNow() + 100000 : originalNow();
+ });
+
+ const res = await engine.inferRelationships("test-db", { timeoutMs: 1000 });
+ expect(res.timedOut).toBe(true);
+
+ // Verify saveMongoRelationships was NOT called on timeout (MED-REM-01)
+ expect(mockProjectStore.saveMongoRelationships).not.toHaveBeenCalled();
+
+ // Verify stored relationships in memory remain untouched
+ expect(storedRelationships.inferred).toEqual(preExistingInferred);
+ expect(storedRelationships.insufficientEvidence?.length).toBe(1);
+
+ jest.spyOn(Date, "now").mockRestore();
+ });
+
+ test("passes exact sub-100ms remaining deadline to maxTimeMS (LOW-REM-01)", async () => {
+ let capturedMaxTimeMS: number | undefined;
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ name: "single_col" }]),
+ }),
+ collection: jest.fn().mockReturnValue({
+ find: jest.fn().mockImplementation((_filter: any, options: any) => {
+ capturedMaxTimeMS = options?.maxTimeMS;
+ return {
+ toArray: jest.fn().mockResolvedValue([]),
+ limit: jest.fn().mockReturnThis(),
+ };
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ const baseNow = 1000000;
+ let callCount = 0;
+ jest.spyOn(Date, "now").mockImplementation(() => {
+ callCount++;
+ // On collection loop (callCount >= 2), remaining time is 45ms (less than 100ms)
+ if (callCount >= 2) return baseNow + 1000 - 45;
+ return baseNow;
+ });
+
+ await engine.inferRelationships("test-db", { timeoutMs: 1000 });
+
+ // Must NOT be floored to 100; must be exact remaining 45ms
+ expect(capturedMaxTimeMS).toBe(45);
+
+ jest.spyOn(Date, "now").mockRestore();
+ });
+ });
+
+ describe("String Hex vs BSON ObjectId Normalization", () => {
+ test("matches target collection where _id is stored as 24-char hex string", async () => {
+ const hexId = "507f1f77bcf86cd799439011";
+
+ const mockCustomersCol = {
+ find: jest.fn().mockImplementation((filter: any) => {
+ // Verify that query filter contains both ObjectId and raw string
+ const values = filter?._id?.$in || [];
+ const hasStringMatch = values.includes(hexId);
+ return {
+ toArray: jest.fn().mockResolvedValue(hasStringMatch ? [{ _id: hexId }] : []),
+ limit: jest.fn().mockReturnThis(),
+ };
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ const mockInvoicesCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: new ObjectId(), customer_id: hexId }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ name: "customers" }, { name: "invoices" }]),
+ }),
+ collection: jest.fn((colName: string) => {
+ if (colName === "customers") return mockCustomersCol;
+ if (colName === "invoices") return mockInvoicesCol;
+ throw new Error(`Unknown col ${colName}`);
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ const res = await engine.inferRelationships("test-db");
+ const rel = res.relationships.find((r) => r.id === "invoices.customer_id->customers._id");
+ expect(rel).toBeDefined();
+ expect(rel?.evidence.hitRatio).toBe(1.0);
+ });
+ });
+
+ describe("Ambiguous Target Penalty", () => {
+ test("applies 0.30 ambiguity penalty when multiple targets match", async () => {
+ const sharedId = new ObjectId();
+
+ const mockColA = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: sharedId }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+ const mockColB = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: sharedId }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+ const mockSourceCol = {
+ find: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([{ _id: new ObjectId(), target_id: sharedId }]),
+ limit: jest.fn().mockReturnThis(),
+ }),
+ indexes: jest.fn().mockResolvedValue([]),
+ };
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest
+ .fn()
+ .mockResolvedValue([{ name: "source" }, { name: "target" }, { name: "targets" }]),
+ }),
+ collection: jest.fn((colName: string) => {
+ if (colName === "source") return mockSourceCol;
+ if (colName === "target") return mockColA;
+ if (colName === "targets") return mockColB;
+ throw new Error(`Unknown col ${colName}`);
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ // HitRatio = 1.0, TypeScore = 1.0, NameScore = 1.0 (both match "target" / "targets")
+ // Without penalty: 0.55 * 1 + 0.25 * 1 + 0.20 * 1 = 1.00
+ // With ambiguity penalty: 1.00 - 0.30 = 0.70
+ const res = await engine.inferRelationships("test-db");
+ expect(res.relationships.length).toBe(2);
+ expect(res.relationships[0].confidence).toBe(0.7);
+ expect(res.relationships[1].confidence).toBe(0.7);
+ });
+ });
+
+ describe("State Retention Across Refresh & CRUD", () => {
+ test("preserves confirmed, rejected, manual, and insufficient definitions", async () => {
+ storedRelationships = {
+ version: 1,
+ databaseId: "test-db",
+ inferred: [],
+ confirmed: [
+ {
+ id: "orders.customer_id->customers._id",
+ sourceCollection: "orders",
+ sourceField: "customer_id",
+ targetCollection: "customers",
+ targetField: "_id",
+ cardinality: "many-to-one",
+ createdAt: "2026-01-01T00:00:00.000Z",
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ },
+ ],
+ rejectedIds: ["orders.bad_id->products._id"],
+ manual: [],
+ insufficientEvidence: [],
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ };
+
+ const mockDb: any = {
+ listCollections: jest.fn().mockReturnValue({
+ toArray: jest.fn().mockResolvedValue([]),
+ }),
+ };
+ jest.spyOn(engine, "getDb").mockResolvedValue(mockDb);
+
+ await engine.inferRelationships("test-db");
+
+ expect(mockProjectStore.saveMongoRelationships).toHaveBeenCalledWith(
+ expect.objectContaining({
+ confirmed: expect.arrayContaining([
+ expect.objectContaining({ id: "orders.customer_id->customers._id" }),
+ ]),
+ rejectedIds: ["orders.bad_id->products._id"],
+ }),
+ undefined,
+ "test-db",
+ );
+ });
+
+ test("sets status and manages manual CRUD", async () => {
+ storedRelationships.inferred = [
+ {
+ id: "orders.user_id->users._id",
+ sourceCollection: "orders",
+ sourceField: "user_id",
+ targetCollection: "users",
+ targetField: "_id",
+ cardinality: "many-to-one",
+ confidence: 0.95,
+ evidence: {} as any,
+ status: "inferred",
+ inferredAt: new Date().toISOString(),
+ },
+ ];
+
+ const confRes = await engine.setRelationshipStatus(
+ "test-db",
+ "orders.user_id->users._id",
+ "confirmed",
+ );
+ expect(confRes.status).toBe("confirmed");
+ expect(storedRelationships.confirmed.length).toBe(1);
+
+ const rejRes = await engine.setRelationshipStatus(
+ "test-db",
+ "orders.user_id->users._id",
+ "rejected",
+ );
+ expect(rejRes.status).toBe("rejected");
+ expect(storedRelationships.rejectedIds).toContain("orders.user_id->users._id");
+ expect(storedRelationships.confirmed.length).toBe(0);
+ });
+ });
+});
diff --git a/bridge/__tests__/mongoUri.test.ts b/bridge/__tests__/mongoUri.test.ts
new file mode 100644
index 00000000..03a8c9c0
--- /dev/null
+++ b/bridge/__tests__/mongoUri.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, test } from "@jest/globals";
+import {
+ isMongoUri,
+ extractMongoCredentials,
+ sanitizeMongoUri,
+ injectMongoPassword,
+ normalizeMongoUriMeta,
+ splitMongoUriCredentials,
+ buildMongoConnectionUri,
+} from "../src/utils/mongoUri";
+
+describe("mongoUri", () => {
+ test("isMongoUri recognizes mongodb and mongodb+srv schemes", () => {
+ expect(isMongoUri("mongodb://localhost:27017")).toBe(true);
+ expect(isMongoUri("mongodb+srv://cluster/db")).toBe(true);
+ expect(isMongoUri("postgres://localhost")).toBe(false);
+ expect(isMongoUri(undefined)).toBe(false);
+ expect(isMongoUri("")).toBe(false);
+ });
+
+ test("extractMongoCredentials decodes percent-encoded credentials", () => {
+ const creds = extractMongoCredentials("mongodb://user:p%40ss%23word@localhost:27017/testdb");
+ expect(creds.user).toBe("user");
+ expect(creds.password).toBe("p@ss#word");
+ });
+
+ test("sanitizeMongoUri removes the password but keeps user and options", () => {
+ const sanitized = sanitizeMongoUri(
+ "mongodb://user:secret@localhost:27017/testdb?authSource=admin&replicaSet=rs0",
+ );
+ expect(sanitized).toBe("mongodb://user@localhost:27017/testdb?authSource=admin&replicaSet=rs0");
+ expect(sanitized).not.toContain("secret");
+ });
+
+ test("sanitizeMongoUri is idempotent and safe for SRV URIs", () => {
+ const srv = "mongodb+srv://alice:p%40ss%23word@cluster0.example.net/prod";
+ const s1 = sanitizeMongoUri(srv);
+ expect(s1).toBe("mongodb+srv://alice@cluster0.example.net/prod");
+ expect(sanitizeMongoUri(s1)).toBe(s1);
+ });
+
+ test("injectMongoPassword re-injects and round-trips to the original", () => {
+ const original = "mongodb://user:p%40ss@localhost:27017/testdb";
+ const sanitized = sanitizeMongoUri(original);
+ const reconstructed = injectMongoPassword(sanitized, "p@ss");
+ // decoded password is re-encoded identically
+ expect(decodeURIComponent(reconstructed)).toBe(decodeURIComponent(original));
+ expect(reconstructed).toContain("p%40ss");
+ });
+
+ test("injectMongoPassword without a username returns the URI unchanged", () => {
+ const uri = "mongodb://localhost:27017/testdb";
+ expect(injectMongoPassword(uri, "secret")).toBe(uri);
+ });
+
+ test("normalizeMongoUriMeta derives relational-meta fields", () => {
+ const meta = normalizeMongoUriMeta(
+ "mongodb://user:p%40ss%23word@example.net:27018/proddb?authSource=admin&replicaSet=rs0",
+ );
+ expect(meta.host).toBe("example.net");
+ expect(meta.port).toBe(27018);
+ expect(meta.user).toBe("user");
+ expect(meta.database).toBe("proddb");
+ expect(meta.authSource).toBe("admin");
+ expect(meta.replicaSet).toBe("rs0");
+ });
+
+ test("normalizeMongoUriMeta defaults port to 27017", () => {
+ const meta = normalizeMongoUriMeta("mongodb://localhost/testdb");
+ expect(meta.port).toBe(27017);
+ expect(meta.database).toBe("testdb");
+ });
+
+ test("splitMongoUriCredentials separates sanitized URI from the password", () => {
+ const parts = splitMongoUriCredentials("mongodb://u:p%40ss%23word@h:27017/db");
+ expect(parts.isMongoUri).toBe(true);
+ expect(parts.hasCredentials).toBe(true);
+ expect(parts.sanitizedUri).toBe("mongodb://u@h:27017/db");
+ expect(parts.password).toBe("p@ss#word");
+ });
+
+ test("splitMongoUriCredentials passes non-URI values through", () => {
+ const parts = splitMongoUriCredentials("not-a-uri");
+ expect(parts.isMongoUri).toBe(false);
+ expect(parts.hasCredentials).toBe(false);
+ expect(parts.sanitizedUri).toBe("not-a-uri");
+ });
+
+ test("buildMongoConnectionUri re-injects runtime password into a sanitized URI", () => {
+ const sanitized = "mongodb://testuser@127.0.0.1:27017/testdb";
+ const uri = buildMongoConnectionUri({ url: sanitized }, "runtime-pw");
+ expect(uri).toContain("testuser");
+ expect(decodeURIComponent(uri)).toContain("runtime-pw");
+ });
+
+ test("buildMongoConnectionUri leaves a passwordless sanitized URI untouched", () => {
+ const sanitized = "mongodb://127.0.0.1:27017/testdb";
+ expect(buildMongoConnectionUri({ url: sanitized }, null)).toBe(sanitized);
+ });
+
+ test("buildMongoConnectionUri composes from host/port/user/password", () => {
+ const uri = buildMongoConnectionUri(
+ { host: "localhost", port: 27017, user: "u", database: "db" },
+ "p@ss",
+ );
+ expect(uri).toBe("mongodb://u:p%40ss@localhost:27017/db");
+ });
+
+ test("buildMongoConnectionUri throws when neither uri nor host is present", () => {
+ expect(() => buildMongoConnectionUri({}, "pw")).toThrow(/requires a url/i);
+ });
+
+ test("parses multi-host replica set URI without throwing ERR_INVALID_URL", () => {
+ const uri =
+ "mongodb://user:secret@host1:27017,host2:27017,host3:27017/testdb?replicaSet=rs0&authSource=admin";
+ expect(() => extractMongoCredentials(uri)).not.toThrow();
+ const meta = normalizeMongoUriMeta(uri);
+ expect(meta.host).toBe("host1");
+ expect(meta.port).toBe(27017);
+ expect(meta.user).toBe("user");
+ expect(meta.database).toBe("testdb");
+ expect(meta.replicaSet).toBe("rs0");
+ expect(meta.authSource).toBe("admin");
+ });
+
+ test("multi-host credentials extraction and sanitization", () => {
+ const uri =
+ "mongodb://user:secret@host1:27017,host2:27017,host3:27017/testdb?replicaSet=rs0&authSource=admin";
+ const creds = extractMongoCredentials(uri);
+ expect(creds.user).toBe("user");
+ expect(creds.password).toBe("secret");
+
+ const sanitized = sanitizeMongoUri(uri);
+ expect(sanitized).toBe(
+ "mongodb://user@host1:27017,host2:27017,host3:27017/testdb?replicaSet=rs0&authSource=admin",
+ );
+ expect(sanitized).not.toContain("secret");
+ expect(sanitized).toContain("host1:27017,host2:27017,host3:27017");
+ expect(sanitized).toContain("replicaSet=rs0");
+ expect(sanitized).toContain("authSource=admin");
+ });
+
+ test("re-injects password into sanitized multi-host URI with buildMongoConnectionUri", () => {
+ const sanitized =
+ "mongodb://user@host1:27017,host2:27017,host3:27017/testdb?replicaSet=rs0&authSource=admin";
+ const reconstructed = buildMongoConnectionUri({ url: sanitized }, "secretPass");
+ expect(reconstructed).toBe(
+ "mongodb://user:secretPass@host1:27017,host2:27017,host3:27017/testdb?replicaSet=rs0&authSource=admin",
+ );
+ });
+});
diff --git a/bridge/__tests__/services/mongoBulkEngineCleanup.test.ts b/bridge/__tests__/services/mongoBulkEngineCleanup.test.ts
new file mode 100644
index 00000000..e03d0dca
--- /dev/null
+++ b/bridge/__tests__/services/mongoBulkEngineCleanup.test.ts
@@ -0,0 +1,219 @@
+import { describe, expect, test, beforeEach, afterEach } from "@jest/globals";
+import path from "path";
+import fs from "fs";
+import os from "os";
+import {
+ ExportCoordinationManager,
+ MongoBulkEngine,
+ EXPORT_ORPHAN_TTL_MS,
+} from "../../src/services/mongoBulkEngine";
+
+describe("MongoBulkEngine Export Orphan Cleanup & Coordination Suite (AUD-09)", () => {
+ let testExportDir: string;
+
+ beforeEach(async () => {
+ testExportDir = path.join(
+ os.tmpdir(),
+ `relwave-test-exports-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+ );
+ await fs.promises.mkdir(testExportDir, { recursive: true });
+ ExportCoordinationManager.resetForTesting();
+ });
+
+ afterEach(async () => {
+ ExportCoordinationManager.resetForTesting();
+ try {
+ await fs.promises.rm(testExportDir, { recursive: true, force: true });
+ } catch {
+ // safe cleanup
+ }
+ });
+
+ test("1. ExportCoordinationManager process-wide singleton identity", () => {
+ const inst1 = ExportCoordinationManager.getInstance();
+ const inst2 = ExportCoordinationManager.getInstance();
+ expect(inst1).toBe(inst2);
+
+ const _engineA = new MongoBulkEngine();
+ const _engineB = new MongoBulkEngine();
+ // Both engines interact with the same underlying singleton
+ expect(ExportCoordinationManager.getInstance()).toBe(inst1);
+ });
+
+ test("2. Cross-engine job protection: Active job registered in Engine A is protected from purge by Engine B even when > 2 hours old", async () => {
+ const manager = ExportCoordinationManager.getInstance();
+ const _engineA = new MongoBulkEngine();
+ const engineB = new MongoBulkEngine();
+
+ const jobId = "job-active-cross-engine-12345";
+ const filePath = path.join(testExportDir, `export-${jobId}.json`);
+
+ // Register job under Engine A / singleton
+ await manager.registerJobBeforeFileCreation(jobId, filePath);
+ await fs.promises.writeFile(filePath, '{"test": 1}');
+
+ // Set file mtime to 3 hours ago (> 2h threshold)
+ const threeHoursAgo = Date.now() - (EXPORT_ORPHAN_TTL_MS + 3600000);
+ await fs.promises.utimes(filePath, new Date(threeHoursAgo), new Date(threeHoursAgo));
+
+ // Engine B executes purge
+ const result = await engineB.purgeOrphanedExports(testExportDir);
+
+ expect(result.purged).toBe(0);
+ expect(result.skipped).toBe(1);
+ expect(fs.existsSync(filePath)).toBe(true);
+
+ // Unregister and purge again
+ await manager.unregisterJob(jobId);
+ const resultAfterUnregister = await engineB.purgeOrphanedExports(testExportDir);
+ expect(resultAfterUnregister.purged).toBe(1);
+ expect(fs.existsSync(filePath)).toBe(false);
+ });
+
+ test("3. Pre-creation registration under critical section prevents purge race", async () => {
+ const manager = ExportCoordinationManager.getInstance();
+ const jobId = "pre-reg-job-999";
+ const filePath = path.join(testExportDir, `export-${jobId}.tmp`);
+
+ // Register job BEFORE file creation
+ await manager.registerJobBeforeFileCreation(jobId, filePath);
+ expect(manager.isJobActive(jobId)).toBe(true);
+
+ // File is created
+ await fs.promises.writeFile(filePath, "pre-created data");
+
+ // Even if timestamp is artificially aged, active registry shield holds
+ const fourHoursAgo = Date.now() - EXPORT_ORPHAN_TTL_MS * 2;
+ await fs.promises.utimes(filePath, new Date(fourHoursAgo), new Date(fourHoursAgo));
+
+ const purgeResult = await manager.purgeOrphanedExportsAsync(testExportDir);
+ expect(purgeResult.purged).toBe(0);
+ expect(purgeResult.skipped).toBe(1);
+ expect(fs.existsSync(filePath)).toBe(true);
+
+ await manager.unregisterJob(jobId);
+ });
+
+ test("4. Two-hour TTL age boundary (Option A: 2 * 60 * 60 * 1000 ms)", async () => {
+ const manager = ExportCoordinationManager.getInstance();
+
+ const freshJobId = "fresh-job-uuid-111";
+ const staleJobId = "stale-job-uuid-222";
+
+ const freshFile = path.join(testExportDir, `export-${freshJobId}.json`);
+ const staleFile = path.join(testExportDir, `export-${staleJobId}.json`);
+
+ await fs.promises.writeFile(freshFile, "fresh export data");
+ await fs.promises.writeFile(staleFile, "stale export data");
+
+ const now = Date.now();
+ // Fresh: 1 hour ago (< 2h)
+ const oneHourAgo = now - 3600000;
+ await fs.promises.utimes(freshFile, new Date(oneHourAgo), new Date(oneHourAgo));
+
+ // Stale: 2 hours and 5 minutes ago (> 2h)
+ const twoHoursFiveMinAgo = now - (EXPORT_ORPHAN_TTL_MS + 300000);
+ await fs.promises.utimes(staleFile, new Date(twoHoursFiveMinAgo), new Date(twoHoursFiveMinAgo));
+
+ const result = await manager.purgeOrphanedExportsAsync(testExportDir);
+
+ expect(result.purged).toBe(1); // Only stale file purged
+ expect(result.skipped).toBe(1); // Fresh file skipped
+
+ expect(fs.existsSync(freshFile)).toBe(true);
+ expect(fs.existsSync(staleFile)).toBe(false);
+ });
+
+ test("5. Symlink rejection via lstat() protects target files", async () => {
+ const manager = ExportCoordinationManager.getInstance();
+
+ const targetFile = path.join(testExportDir, "important-target-data.json");
+ await fs.promises.writeFile(targetFile, "CRITICAL DATA NEVER TOUCH");
+
+ const symlinkPath = path.join(testExportDir, "export-symlink-target.json");
+
+ try {
+ await fs.promises.symlink(targetFile, symlinkPath);
+ } catch (err: any) {
+ // In some Windows environments without dev privileges, symlinks might require elevation
+ if (err.code === "EPERM") {
+ return; // skip if OS forbids symlink creation
+ }
+ throw err;
+ }
+
+ // Age the symlink target or symlink
+ const threeHoursAgo = Date.now() - (EXPORT_ORPHAN_TTL_MS + 3600000);
+ try {
+ await fs.promises.utimes(symlinkPath, new Date(threeHoursAgo), new Date(threeHoursAgo));
+ } catch {}
+
+ await manager.purgeOrphanedExportsAsync(testExportDir);
+
+ // Symlinks are skipped
+ expect(fs.existsSync(targetFile)).toBe(true);
+ expect(fs.existsSync(symlinkPath)).toBe(true);
+ });
+
+ test("6. Keyed per-directory mutex serializes concurrent purge sweeps", async () => {
+ const manager = ExportCoordinationManager.getInstance();
+ const executionOrder: string[] = [];
+
+ const p1 = manager.withDirLock(testExportDir, async () => {
+ executionOrder.push("p1_start");
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ executionOrder.push("p1_end");
+ });
+
+ const p2 = manager.withDirLock(testExportDir, async () => {
+ executionOrder.push("p2_start");
+ executionOrder.push("p2_end");
+ });
+
+ await Promise.all([p1, p2]);
+
+ expect(executionOrder).toEqual(["p1_start", "p1_end", "p2_start", "p2_end"]);
+ });
+
+ test("7. Strict export filename regex matching ignores unrelated files", async () => {
+ const manager = ExportCoordinationManager.getInstance();
+
+ const validExport1 = path.join(testExportDir, "export-abc-123.csv");
+ const validExport2 = path.join(testExportDir, "export-xyz_999.ndjson");
+ const validExport3 = path.join(testExportDir, "export-temp-session.tmp");
+ const invalidFile1 = path.join(testExportDir, "my-other-document.json");
+ const invalidFile2 = path.join(testExportDir, "export.json");
+ const invalidFile3 = path.join(testExportDir, "export-.csv");
+
+ await fs.promises.writeFile(validExport1, "1");
+ await fs.promises.writeFile(validExport2, "2");
+ await fs.promises.writeFile(validExport3, "3");
+ await fs.promises.writeFile(invalidFile1, "4");
+ await fs.promises.writeFile(invalidFile2, "5");
+ await fs.promises.writeFile(invalidFile3, "6");
+
+ const ancientTime = Date.now() - (EXPORT_ORPHAN_TTL_MS + 10000000);
+ for (const f of [
+ validExport1,
+ validExport2,
+ validExport3,
+ invalidFile1,
+ invalidFile2,
+ invalidFile3,
+ ]) {
+ await fs.promises.utimes(f, new Date(ancientTime), new Date(ancientTime));
+ }
+
+ const result = await manager.purgeOrphanedExportsAsync(testExportDir);
+
+ expect(result.purged).toBe(3); // only validExport 1, 2, 3
+ expect(result.skipped).toBe(3); // invalidFile 1, 2, 3 skipped
+
+ expect(fs.existsSync(validExport1)).toBe(false);
+ expect(fs.existsSync(validExport2)).toBe(false);
+ expect(fs.existsSync(validExport3)).toBe(false);
+ expect(fs.existsSync(invalidFile1)).toBe(true);
+ expect(fs.existsSync(invalidFile2)).toBe(true);
+ expect(fs.existsSync(invalidFile3)).toBe(true);
+ });
+});
diff --git a/bridge/__tests__/services/mongoConnectionLifecycle.test.ts b/bridge/__tests__/services/mongoConnectionLifecycle.test.ts
new file mode 100644
index 00000000..49c8bf91
--- /dev/null
+++ b/bridge/__tests__/services/mongoConnectionLifecycle.test.ts
@@ -0,0 +1,970 @@
+import { describe, expect, test, jest, beforeEach, afterEach } from "@jest/globals";
+import path from "path";
+import fs from "fs";
+import { MongoClient } from "mongodb";
+import {
+ getClientKey,
+ clientRegistry,
+ closingClients,
+ closeMongoClientByKey,
+ closeAllMongoClients,
+ forceDestroyMongoSockets,
+ getMongoClient,
+ testConnection,
+ setMongoShuttingDown,
+ mongoConnector,
+} from "../../src/connectors/mongo";
+import { ConnectionPool, PoolEntry } from "../../src/services/connectionPool";
+import { DatabaseService } from "../../src/services/databaseService";
+import { ConnectionBuilder } from "../../src/services/connectionBuilder";
+import { dbStoreInstance } from "../../src/services/dbStore";
+import { keyringServiceInstance } from "../../src/services/keyringService";
+import { MongoBulkEngine } from "../../src/services/mongoBulkEngine";
+import { MigrationHandlers } from "../../src/handlers/migrationHandlers";
+import { DBType } from "../../src/types";
+import { MongoConfig } from "../../src/types/mongo";
+
+function createDeferred() {
+ let resolve!: (value: T | PromiseLike) => void;
+ let reject!: (reason?: any) => void;
+ const promise = new Promise((res, rej) => {
+ resolve = res;
+ reject = rej;
+ });
+ return { promise, resolve, reject };
+}
+
+describe("MongoDB Connection Lifecycle & Concurrency Deterministic Test Suite", () => {
+ let dbService: DatabaseService;
+ let pool: ConnectionPool;
+
+ beforeEach(() => {
+ clientRegistry.clear();
+ closingClients.clear();
+ setMongoShuttingDown(false);
+
+ pool = new ConnectionPool();
+ dbService = new DatabaseService();
+ (dbService as any).connectionPool = pool;
+ jest.restoreAllMocks();
+ });
+
+ afterEach(async () => {
+ try {
+ pool.destroy();
+ } catch {}
+ clientRegistry.clear();
+ closingClients.clear();
+ setMongoShuttingDown(false);
+ jest.useRealTimers();
+ });
+
+ // ---------------------------------------------------------------------------
+ // 1. test_concurrent_callers_receive_distinct_leases_and_correct_active_count
+ // ---------------------------------------------------------------------------
+ test("1. test_concurrent_callers_receive_distinct_leases_and_correct_active_count", async () => {
+ const dbId = "test_db_1";
+ const barriers = Array.from({ length: 5 }, () => createDeferred());
+ let buildCount = 0;
+
+ const mockDb = {
+ id: dbId,
+ name: "TestDB",
+ type: "mongodb",
+ url: "mongodb://localhost:27017/testdb",
+ database: "testdb",
+ };
+
+ jest.spyOn(dbStoreInstance, "getDB").mockResolvedValue(mockDb as any);
+ jest.spyOn(dbStoreInstance, "getPasswordFor").mockResolvedValue(null as any);
+ jest.spyOn(ConnectionBuilder, "buildConnection").mockImplementation(async () => {
+ buildCount++;
+ return {
+ config: { uri: "mongodb://localhost:27017/testdb", database: "testdb" },
+ tunnel: undefined,
+ };
+ });
+
+ const callers = barriers.map((barrier, index) =>
+ dbService.withConnection(dbId, async (_conn, _db, _type) => {
+ await barrier.promise;
+ return index;
+ }),
+ );
+
+ // Yield to allow all 5 callers to acquire leases and pause at their barrier
+ await new Promise((r) => setImmediate(r));
+
+ expect(buildCount).toBe(1);
+ const poolEntries = (pool as any).pool as Map;
+ const entry = poolEntries.get(dbId);
+ expect(entry).toBeDefined();
+ expect(entry!.activeOperations).toBe(5);
+
+ // Release caller 1
+ barriers[0].resolve();
+ const result0 = await callers[0];
+ expect(result0).toBe(0);
+ expect(entry!.activeOperations).toBe(4);
+
+ // Invalidate profile while callers 2-5 are still holding their leases
+ await pool.invalidate(dbId);
+ expect(entry!.disposed).toBe(true);
+ const pendingDisposal = (pool as any).pendingDisposal as Set;
+ expect(pendingDisposal.has(entry!)).toBe(true);
+
+ const safeCloseSpy = jest.spyOn(pool, "safeCloseMongoClient");
+
+ // Release callers 2 to 5
+ barriers[1].resolve();
+ barriers[2].resolve();
+ barriers[3].resolve();
+ barriers[4].resolve();
+
+ await Promise.all(callers.slice(1));
+ expect(entry!.activeOperations).toBe(0);
+ expect(pendingDisposal.has(entry!)).toBe(false);
+
+ // Give microtask tick for deferred cleanup
+ await new Promise((r) => setImmediate(r));
+ expect(safeCloseSpy).toHaveBeenCalled();
+ });
+
+ // ---------------------------------------------------------------------------
+ // 2. test_identity_safe_inflight_promise_removal
+ // ---------------------------------------------------------------------------
+ test("2. test_identity_safe_inflight_promise_removal", async () => {
+ const dbId = "test_db_2";
+ const barrierA = createDeferred();
+ const barrierB = createDeferred();
+
+ const mockDb = {
+ id: dbId,
+ name: "TestDB",
+ type: "mongodb",
+ url: "mongodb://localhost:27017/testdb",
+ database: "testdb",
+ };
+
+ jest.spyOn(dbStoreInstance, "getDB").mockResolvedValue(mockDb as any);
+ jest.spyOn(dbStoreInstance, "getPasswordFor").mockResolvedValue(null as any);
+
+ let invocation = 0;
+ jest.spyOn(ConnectionBuilder, "buildConnection").mockImplementation(async () => {
+ invocation++;
+ if (invocation === 1) {
+ await barrierA.promise;
+ return { config: { uri: "mongodb://localhost:27017/testdb_a", database: "testdb" } };
+ } else {
+ await barrierB.promise;
+ return { config: { uri: "mongodb://localhost:27017/testdb_b", database: "testdb" } };
+ }
+ });
+
+ const inFlightMap = (dbService as any).inFlightConnections as Map>;
+
+ // Start Builder A
+ const builderAPromise = (dbService as any).ensureConnectionBuilt(dbId);
+ expect(inFlightMap.has(dbId)).toBe(true);
+ const promiseA = inFlightMap.get(dbId);
+
+ // Allow Builder A to progress past getDB and pause inside buildConnection
+ for (let i = 0; i < 5; i++) await new Promise((r) => setImmediate(r));
+ expect(invocation).toBe(1);
+
+ // Invalidate connection (bumps generation and clears inFlightConnections)
+ await dbService.invalidateConnection(dbId);
+ expect(inFlightMap.has(dbId)).toBe(false);
+
+ // Start Builder B
+ const builderBPromise = (dbService as any).ensureConnectionBuilt(dbId);
+ expect(inFlightMap.has(dbId)).toBe(true);
+ const promiseB = inFlightMap.get(dbId);
+ expect(promiseB).not.toBe(promiseA);
+
+ // Allow Builder B to progress past getDB and pause inside buildConnection
+ for (let i = 0; i < 5; i++) await new Promise((r) => setImmediate(r));
+ expect(invocation).toBe(2);
+
+ // Resolve Builder A
+ barrierA.resolve();
+ await expect(builderAPromise).rejects.toThrow(/Connection build aborted/);
+
+ // Identity safety check: Builder A settling must NOT have deleted Builder B's promise
+ expect(inFlightMap.get(dbId)).toBe(promiseB);
+
+ // Caller C joins Builder B without starting Builder C
+ const builderCPromise = (dbService as any).ensureConnectionBuilt(dbId);
+ expect(inFlightMap.get(dbId)).toBe(promiseB);
+ expect(invocation).toBe(2);
+
+ // Settle Builder B
+ barrierB.resolve();
+ await Promise.all([builderBPromise, builderCPromise]);
+
+ // Map is cleanly emptied after settle
+ expect(inFlightMap.has(dbId)).toBe(false);
+ });
+
+ // ---------------------------------------------------------------------------
+ // 3. test_new_profile_acquire_during_final_reference_cleanup
+ // ---------------------------------------------------------------------------
+ test("3. test_new_profile_acquire_during_final_reference_cleanup", async () => {
+ const clientKey = getClientKey({
+ uri: "mongodb://localhost:27017/shared_db",
+ database: "shared_db",
+ });
+ const closeBarrier = createDeferred();
+
+ const mockOldClient: any = {
+ close: jest.fn().mockImplementation(async () => {
+ await closeBarrier.promise;
+ }),
+ topology: { s: { servers: new Map() } },
+ };
+
+ clientRegistry.set(clientKey, { client: mockOldClient, state: "closing" });
+ const closePromise = closeMongoClientByKey(clientKey, { force: true });
+ closingClients.set(clientKey, closePromise);
+
+ let acquiredNewClient: MongoClient | undefined;
+ const acquirePromise = (async () => {
+ acquiredNewClient = await getMongoClient({
+ uri: "mongodb://localhost:27017/shared_db",
+ database: "shared_db",
+ });
+ })();
+
+ await new Promise((r) => setImmediate(r));
+ // Profile B is awaiting in-flight closure
+ expect(acquiredNewClient).toBeUndefined();
+
+ // Settle close barrier
+ closeBarrier.resolve();
+ await closePromise;
+ await acquirePromise;
+
+ expect(acquiredNewClient).toBeDefined();
+ expect(acquiredNewClient).not.toBe(mockOldClient);
+ expect(clientRegistry.get(clientKey)?.state).toBe("active");
+ });
+
+ // ---------------------------------------------------------------------------
+ // 4. test_single_flight_force_close_recovery_and_single_replacement_client
+ // ---------------------------------------------------------------------------
+ test("4. test_single_flight_force_close_recovery_and_single_replacement_client", async () => {
+ const cfg: MongoConfig = {
+ uri: "mongodb://localhost:27017/recovery_db",
+ database: "recovery_db",
+ };
+ const key = getClientKey(cfg);
+ const closeBarrier = createDeferred();
+
+ const mockFailedClient: any = {
+ close: jest.fn().mockImplementation(async () => {
+ await closeBarrier.promise;
+ }),
+ topology: { s: { servers: new Map() } },
+ };
+
+ clientRegistry.set(key, {
+ client: mockFailedClient,
+ state: "close_failed",
+ closeError: new Error("Previous hang"),
+ });
+
+ // Launch two concurrent callers
+ const caller1Promise = getMongoClient(cfg);
+ const caller2Promise = getMongoClient(cfg);
+
+ await new Promise((r) => setImmediate(r));
+
+ // Exactly one close call was dispatched
+ expect(mockFailedClient.close).toHaveBeenCalledTimes(1);
+
+ // Resolve close barrier
+ closeBarrier.resolve();
+
+ const [client1, client2] = await Promise.all([caller1Promise, caller2Promise]);
+
+ expect(client1).toBeDefined();
+ expect(client1).toBe(client2);
+ expect(clientRegistry.size).toBe(1);
+ expect(clientRegistry.get(key)?.state).toBe("active");
+
+ // Failure case: when force-close rejects, verify close_failed is preserved and zero replacement created
+ const unconfirmedClient: any = {
+ close: jest.fn().mockRejectedValue(new Error("Socket severance failed")),
+ topology: { s: { servers: "not-a-map" } },
+ };
+ clientRegistry.set(key, { client: unconfirmedClient, state: "close_failed" });
+
+ await expect(getMongoClient(cfg)).rejects.toThrow(
+ /prior client for key .* failed to force-close/,
+ );
+ expect(clientRegistry.get(key)?.state).toBe("close_failed");
+ });
+
+ // ---------------------------------------------------------------------------
+ // 5. test_dynamically_allocated_ssh_ports_and_lifecycle_interleaving
+ // ---------------------------------------------------------------------------
+ test("5. test_dynamically_allocated_ssh_ports_and_lifecycle_interleaving", async () => {
+ const dbA = {
+ id: "ssh_db_a",
+ name: "SSH_A",
+ type: "mongodb",
+ url: "mongodb://remote-server:27017/db_a",
+ database: "db_a",
+ ssh: { host: "bastion", port: 22, user: "tunnel", authMethod: "password" },
+ };
+ const dbB = {
+ id: "ssh_db_b",
+ name: "SSH_B",
+ type: "mongodb",
+ url: "mongodb://remote-server:27017/db_b",
+ database: "db_b",
+ ssh: { host: "bastion", port: 22, user: "tunnel", authMethod: "password" },
+ };
+
+ jest
+ .spyOn(dbStoreInstance, "getDB")
+ .mockImplementation(async (id) => (id === "ssh_db_a" ? dbA : dbB) as any);
+ jest.spyOn(dbStoreInstance, "getPasswordFor").mockResolvedValue(null as any);
+ jest.spyOn(keyringServiceInstance, "getCredential").mockResolvedValue("ssh_secret");
+
+ const mockTunnelA = { localPort: 54321, close: jest.fn() };
+ const mockTunnelB = { localPort: 54322, close: jest.fn() };
+
+ jest.spyOn(ConnectionBuilder, "buildConnection").mockImplementation(async (db: any) => {
+ const tunnel = db.id === "ssh_db_a" ? mockTunnelA : mockTunnelB;
+ return {
+ config: {
+ uri: `mongodb://127.0.0.1:${tunnel.localPort}/${db.database}`,
+ database: db.database,
+ },
+ tunnel,
+ };
+ });
+
+ const leaseA = await dbService.acquireConnection("ssh_db_a");
+ const leaseB = await dbService.acquireConnection("ssh_db_b");
+
+ const keyA = getClientKey(leaseA.conn);
+ const keyB = getClientKey(leaseB.conn);
+
+ expect(keyA).toContain("54321");
+ expect(keyB).toContain("54322");
+ expect(keyA).not.toBe(keyB);
+
+ leaseA.release();
+ leaseB.release();
+
+ // Interleaved cleanup: invalidating Profile A does NOT affect Profile B
+ await pool.invalidate("ssh_db_a");
+ expect(mockTunnelA.close).toHaveBeenCalled();
+ expect(mockTunnelB.close).not.toHaveBeenCalled();
+ expect(pool.get("ssh_db_b")).toBeDefined();
+ });
+
+ // ---------------------------------------------------------------------------
+ // 6. test_stale_builder_separate_tunnel_and_client_adoption_checks
+ // ---------------------------------------------------------------------------
+ describe("6. test_stale_builder_separate_tunnel_and_client_adoption_checks", () => {
+ test("Sub-scenario A: Same tunnel object adopted, unshared client", async () => {
+ const builtTunnel = { localPort: 50001, close: jest.fn() };
+ const builtConfig = { uri: "mongodb://127.0.0.1:50001/unshared_db", database: "unshared_db" };
+
+ // Adopted in pool under distinct profile
+ pool.set(
+ "other_profile",
+ { uri: "mongodb://127.0.0.1:50001/other_db", database: "other_db" },
+ DBType.MONGODB,
+ builtTunnel as any,
+ );
+
+ const safeCloseSpy = jest.spyOn(pool, "safeCloseMongoClient");
+
+ // Builder runs check 3 logic
+ const isTunnelAdopted = Array.from(pool.getAllEntries()).some(
+ (e) => e.tunnel === builtTunnel,
+ );
+ expect(isTunnelAdopted).toBe(true);
+ if (!isTunnelAdopted) builtTunnel.close();
+
+ await pool.safeCloseMongoClient(builtConfig);
+
+ expect(builtTunnel.close).not.toHaveBeenCalled();
+ expect(safeCloseSpy).toHaveBeenCalledWith(builtConfig);
+ });
+
+ test("Sub-scenario B: Similar endpoint, different tunnel object", async () => {
+ const builtTunnel = { localPort: 50002, close: jest.fn() };
+ const otherTunnel = { localPort: 50002, close: jest.fn() };
+
+ pool.set(
+ "other_profile",
+ { uri: "mongodb://127.0.0.1:50002/db", database: "db" },
+ DBType.MONGODB,
+ otherTunnel as any,
+ );
+
+ // Identity check: must be strict object equality
+ const isTunnelAdopted = Array.from(pool.getAllEntries()).some(
+ (e) => e.tunnel === builtTunnel,
+ );
+ expect(isTunnelAdopted).toBe(false);
+
+ if (!isTunnelAdopted) builtTunnel.close();
+
+ expect(builtTunnel.close).toHaveBeenCalled();
+ expect(otherTunnel.close).not.toHaveBeenCalled();
+ });
+
+ test("Sub-scenario C: Shared MongoClient, unshared tunnel", async () => {
+ const builtTunnel = { localPort: 50003, close: jest.fn() };
+ const sharedConfig = { uri: "mongodb://127.0.0.1:50003/shared_c", database: "shared_c" };
+
+ // Other profile shares clientKey but has different or no tunnel
+ pool.set("adopting_profile", sharedConfig, DBType.MONGODB, undefined);
+
+ const isTunnelAdopted = Array.from(pool.getAllEntries()).some(
+ (e) => e.tunnel === builtTunnel,
+ );
+ if (!isTunnelAdopted) builtTunnel.close();
+
+ const closeKeySpy = jest.spyOn(pool, "safeCloseMongoClient");
+ await pool.safeCloseMongoClient(sharedConfig);
+
+ expect(builtTunnel.close).toHaveBeenCalled();
+ expect(closeKeySpy).toHaveBeenCalled();
+ });
+
+ test("Sub-scenario D: Shared tunnel, unshared MongoClient", async () => {
+ const builtTunnel = { localPort: 50004, close: jest.fn() };
+ const unsharedConfig = {
+ uri: "mongodb://127.0.0.1:50004/distinct_d",
+ database: "distinct_d",
+ };
+
+ pool.set(
+ "tunnel_holder",
+ { uri: "mongodb://127.0.0.1:50004/holder_db", database: "holder_db" },
+ DBType.MONGODB,
+ builtTunnel as any,
+ );
+
+ const isTunnelAdopted = Array.from(pool.getAllEntries()).some(
+ (e) => e.tunnel === builtTunnel,
+ );
+ expect(isTunnelAdopted).toBe(true);
+ if (!isTunnelAdopted) builtTunnel.close();
+
+ await pool.safeCloseMongoClient(unsharedConfig);
+
+ expect(builtTunnel.close).not.toHaveBeenCalled();
+ });
+ });
+
+ // ---------------------------------------------------------------------------
+ // 7. test_fatal_error_invalidation_awaited_and_original_error_preserved
+ // ---------------------------------------------------------------------------
+ test("7. test_fatal_error_invalidation_awaited_and_original_error_preserved", async () => {
+ const dbId = "fatal_db";
+ const mockDb = {
+ id: dbId,
+ name: "FatalDB",
+ type: "mongodb",
+ url: "mongodb://localhost:27017/fatal",
+ database: "fatal",
+ };
+
+ jest.spyOn(dbStoreInstance, "getDB").mockResolvedValue(mockDb as any);
+ jest.spyOn(dbStoreInstance, "getPasswordFor").mockResolvedValue(null as any);
+ jest.spyOn(ConnectionBuilder, "buildConnection").mockResolvedValue({
+ config: { uri: "mongodb://localhost:27017/fatal", database: "fatal" },
+ });
+
+ const fatalError = new Error("connection reset by peer");
+ (fatalError as any).name = "MongoNetworkError";
+
+ const invalidateSpy = jest.spyOn(dbService, "invalidateConnection");
+
+ await expect(
+ dbService.withConnection(dbId, async () => {
+ throw fatalError;
+ }),
+ ).rejects.toThrow("connection reset by peer");
+
+ expect(invalidateSpy).toHaveBeenCalledWith(dbId);
+
+ // Verify when invalidation rejects, original error is still preserved
+ invalidateSpy.mockRejectedValueOnce(new Error("invalidation failure"));
+
+ await expect(
+ dbService.withConnection(dbId, async () => {
+ throw fatalError;
+ }),
+ ).rejects.toThrow("connection reset by peer");
+ });
+
+ // ---------------------------------------------------------------------------
+ // 8. test_non_settling_client_close_forced_socket_destruction_and_bounded_shutdown
+ // ---------------------------------------------------------------------------
+ test("8. test_non_settling_client_close_forced_socket_destruction_and_bounded_shutdown", async () => {
+ const key = "non_settling_key";
+ const mockSocket = {
+ destroyed: false,
+ destroy: jest.fn(() => {
+ mockSocket.destroyed = true;
+ }),
+ };
+
+ const mockClient: any = {
+ close: jest.fn(() => new Promise(() => {})), // Never settles
+ topology: {
+ s: {
+ servers: new Map([
+ ["server1", { pool: { connections: [{ socket: mockSocket }], checkedOut: new Set() } }],
+ ]),
+ },
+ },
+ };
+
+ clientRegistry.set(key, { client: mockClient, state: "active" });
+
+ const phase4Deadline = Date.now() + 50;
+ await closeAllMongoClients({ force: true, globalDeadline: phase4Deadline });
+
+ expect(mockSocket.destroy).toHaveBeenCalled();
+ expect(clientRegistry.has(key)).toBe(false); // destroy_confirmed deletes from registry
+ });
+
+ // ---------------------------------------------------------------------------
+ // 9. test_shutdown_escalates_inflight_normal_close_without_competing_operation
+ // ---------------------------------------------------------------------------
+ test("9. test_shutdown_escalates_inflight_normal_close_without_competing_operation", async () => {
+ const key = "escalation_key";
+ const mockSocket = {
+ destroyed: false,
+ destroy: jest.fn(() => {
+ mockSocket.destroyed = true;
+ }),
+ };
+
+ const ordinaryCloseBarrier = createDeferred();
+ const mockClient: any = {
+ close: jest.fn(async () => {
+ await ordinaryCloseBarrier.promise;
+ }),
+ topology: {
+ s: {
+ servers: new Map([
+ ["server1", { pool: { connections: [{ socket: mockSocket }], checkedOut: new Set() } }],
+ ]),
+ },
+ },
+ };
+
+ clientRegistry.set(key, { client: mockClient, state: "active" });
+
+ // Initiate ordinary close
+ const normalClosePromise = closeMongoClientByKey(key);
+
+ // Shutdown arrives while close is in-flight
+ const phase4Deadline = Date.now() + 40;
+ await closeAllMongoClients({ force: true, globalDeadline: phase4Deadline });
+
+ // Client.close was called exactly ONCE (no competing second call)
+ expect(mockClient.close).toHaveBeenCalledTimes(1);
+ expect(mockSocket.destroy).toHaveBeenCalled();
+ expect(clientRegistry.has(key)).toBe(false);
+
+ ordinaryCloseBarrier.resolve();
+ await normalClosePromise;
+ });
+
+ // ---------------------------------------------------------------------------
+ // 10. test_multiple_non_settling_clients_global_bounded_teardown
+ // ---------------------------------------------------------------------------
+ test("10. test_multiple_non_settling_clients_global_bounded_teardown", async () => {
+ const mockSockets: any[] = [];
+ for (let i = 0; i < 5; i++) {
+ const sock = {
+ destroyed: false,
+ destroy: jest.fn(function (this: any) {
+ this.destroyed = true;
+ }),
+ };
+ mockSockets.push(sock);
+
+ const client: any = {
+ close: jest.fn(() => new Promise(() => {})),
+ topology: {
+ s: {
+ servers: new Map([
+ [`server_${i}`, { pool: { connections: [{ socket: sock }], checkedOut: new Set() } }],
+ ]),
+ },
+ },
+ };
+
+ clientRegistry.set(`client_${i}`, { client, state: "active" });
+ }
+
+ const start = Date.now();
+ const phase4Deadline = start + 50;
+
+ await closeAllMongoClients({ force: true, globalDeadline: phase4Deadline });
+ const elapsed = Date.now() - start;
+
+ expect(elapsed).toBeLessThan(300); // Must be bounded globally, not 5 * 50ms serial
+ for (const sock of mockSockets) {
+ expect(sock.destroy).toHaveBeenCalled();
+ }
+ });
+
+ // ---------------------------------------------------------------------------
+ // 11. test_unconfirmed_socket_destruction_retains_registry_entry
+ // ---------------------------------------------------------------------------
+ test("11. test_unconfirmed_socket_destruction_retains_registry_entry", async () => {
+ const key = getClientKey({ uri: "mongodb://stubborn/db", database: "db" });
+
+ // Client whose socket destruction fails to observe .destroyed === true
+ const stubbornSocket = { destroyed: false, destroy: jest.fn() };
+ const mockClient: any = {
+ close: jest.fn().mockRejectedValue(new Error("Socket severance failed")),
+ topology: {
+ s: {
+ servers: new Map([
+ [
+ "server1",
+ { pool: { connections: [{ socket: stubbornSocket }], checkedOut: new Set() } },
+ ],
+ ]),
+ },
+ },
+ };
+
+ clientRegistry.set(key, { client: mockClient, state: "active" });
+
+ await expect(
+ closeMongoClientByKey(key, { force: true, globalDeadline: Date.now() + 100 }),
+ ).rejects.toThrow();
+
+ const entry = clientRegistry.get(key);
+ expect(entry).toBeDefined();
+ expect(entry?.state).toBe("close_failed");
+ expect(stubbornSocket.destroy).toHaveBeenCalled();
+
+ // Subsequent acquire rejects
+ await expect(
+ getMongoClient({ uri: "mongodb://stubborn/db", database: "db" } as any),
+ ).rejects.toThrow(/prior client for key .* failed to force-close/);
+ });
+
+ // ---------------------------------------------------------------------------
+ // 12. test_phase_4_cleanup_sync_bounded_to_200ms_before_forced_teardown
+ // ---------------------------------------------------------------------------
+ test("12. test_phase_4_cleanup_sync_bounded_to_200ms_before_forced_teardown", async () => {
+ jest.useFakeTimers();
+
+ const hangingCleanup = new Promise(() => {});
+ pool.getInProgressCleanups().add(hangingCleanup);
+
+ const shutdownPromise = (dbService as any).executePhase4Teardown();
+
+ // Advance 200ms
+ jest.advanceTimersByTime(200);
+ await Promise.resolve();
+
+ // Advance past phase 4 client close
+ jest.advanceTimersByTime(100);
+ await shutdownPromise;
+
+ expect(pool.isForcedTeardownInitiated).toBe(true);
+ jest.useRealTimers();
+ });
+
+ // ---------------------------------------------------------------------------
+ // 13. test_canonical_client_key_identity_across_sanitization_and_casing
+ // ---------------------------------------------------------------------------
+ test("13. test_canonical_client_key_identity_across_sanitization_and_casing", async () => {
+ const key1 = getClientKey({
+ uri: "mongodb://user:secret@localhost:27017/ProductionDB",
+ database: "ProductionDB",
+ });
+ const key2 = getClientKey({
+ uri: "mongodb://user@localhost:27017/ProductionDB",
+ database: " productiondb ",
+ });
+ const key3 = getClientKey({
+ uri: "mongodb://user:secret@localhost:27017/productiondb",
+ database: "productiondb",
+ });
+
+ expect(key1).toBe(key2);
+ expect(key2).toBe(key3);
+
+ const pingSpy = jest.spyOn(MongoClient.prototype, "db").mockReturnValue({
+ command: jest.fn().mockResolvedValue({ ok: 1 }),
+ } as any);
+
+ // Verify testConnection is completely transient and does not touch clientRegistry
+ const initialSize = clientRegistry.size;
+ await testConnection({ uri: "mongodb://localhost:27017/test", database: "test" });
+ expect(clientRegistry.size).toBe(initialSize);
+ pingSpy.mockRestore();
+ });
+
+ // ---------------------------------------------------------------------------
+ // 14. test_shutdown_blocks_resource_creation_after_credential_lookup
+ // ---------------------------------------------------------------------------
+ test("14. test_shutdown_blocks_resource_creation_after_credential_lookup", async () => {
+ const dbId = "shutdown_db_check2";
+ const keyringBarrier = createDeferred();
+
+ jest.spyOn(dbStoreInstance, "getDB").mockResolvedValue({
+ id: dbId,
+ name: "Check2DB",
+ type: "mongodb",
+ database: "check2",
+ ssh: { host: "bastion", authMethod: "password" },
+ } as any);
+ jest.spyOn(dbStoreInstance, "getPasswordFor").mockResolvedValue(null as any);
+ jest.spyOn(keyringServiceInstance, "getCredential").mockImplementation(async () => {
+ return keyringBarrier.promise;
+ });
+
+ const buildSpy = jest.spyOn(ConnectionBuilder, "buildConnection");
+
+ const buildPromise = (dbService as any).ensureConnectionBuilt(dbId);
+
+ // Trigger shutdown while waiting for keyring
+ (dbService as any).isShuttingDown = true;
+ keyringBarrier.resolve("pass");
+
+ await expect(buildPromise).rejects.toThrow(/Bridge is shutting down|Connection build aborted/);
+ expect(buildSpy).not.toHaveBeenCalled();
+ });
+
+ // ---------------------------------------------------------------------------
+ // 15. test_shutdown_1500ms_deadline_enforces_forced_teardown
+ // ---------------------------------------------------------------------------
+ test("15. test_shutdown_1500ms_deadline_enforces_forced_teardown", async () => {
+ jest.useFakeTimers();
+
+ const hangingBuilder = new Promise(() => {});
+ (dbService as any).activeBuilders.add(hangingBuilder);
+
+ const shutdownPromise = dbService.shutdown();
+
+ // Advance 1500ms for phase 3 drain
+ jest.advanceTimersByTime(1500);
+ await Promise.resolve();
+
+ // Advance 200ms for phase 4 cleanup sync
+ jest.advanceTimersByTime(200);
+ await Promise.resolve();
+
+ // Advance 100ms for phase 4 forced teardown
+ jest.advanceTimersByTime(100);
+ await shutdownPromise;
+
+ expect((dbService as any).isShuttingDown).toBe(true);
+ expect(pool.isForcedTeardownInitiated).toBe(true);
+ jest.useRealTimers();
+ });
+
+ // ---------------------------------------------------------------------------
+ // 16. test_all_invalidation_entry_points_advance_generation
+ // ---------------------------------------------------------------------------
+ test("16. test_all_invalidation_entry_points_advance_generation", async () => {
+ const dbId = "gen_db";
+ expect(dbService.getGeneration(dbId)).toBe(0);
+
+ // Invalidation 1: updateDatabase
+ jest.spyOn(dbStoreInstance, "updateDB").mockResolvedValue({} as any);
+ await dbService.updateDatabase(dbId, { name: "NewName" });
+ expect(dbService.getGeneration(dbId)).toBe(1);
+
+ // Invalidation 2: fatal error in withConnection
+ jest.spyOn(dbStoreInstance, "getDB").mockResolvedValue({ id: dbId, database: "test" } as any);
+ jest
+ .spyOn(ConnectionBuilder, "buildConnection")
+ .mockResolvedValue({ config: { database: "test" } });
+
+ const fatal = new Error("ECONNRESET");
+ (fatal as any).name = "MongoNetworkError";
+
+ await expect(
+ dbService.withConnection(dbId, async () => {
+ throw fatal;
+ }),
+ ).rejects.toThrow("ECONNRESET");
+ expect(dbService.getGeneration(dbId)).toBe(2);
+
+ // Invalidation 3: deleteDatabase
+ jest.spyOn(dbStoreInstance, "deleteDB").mockResolvedValue({ ok: true } as any);
+ jest.spyOn(keyringServiceInstance, "deleteCredential").mockResolvedValue();
+ await dbService.deleteDatabase(dbId);
+ expect(dbService.getGeneration(dbId)).toBe(3);
+ });
+
+ // ---------------------------------------------------------------------------
+ // 17. test_read_only_rejection_across_all_15_mutating_operations
+ // ---------------------------------------------------------------------------
+ test("17. test_read_only_rejection_across_all_15_mutating_operations", async () => {
+ const readOnlyConn: MongoConfig = {
+ uri: "mongodb://localhost:27017/ro_db",
+ database: "ro_db",
+ readonly: true,
+ };
+
+ // 1-9: Connector Guards in mongo.ts
+ await expect(
+ mongoConnector.insertDocument(readOnlyConn, { collection: "c", document: { a: 1 } }),
+ ).rejects.toThrow("Database is configured as read-only. 'insertDocument' is prohibited.");
+
+ await expect(
+ mongoConnector.updateDocument(readOnlyConn, {
+ collection: "c",
+ filter: { a: 1 },
+ update: { $set: { b: 2 } },
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'updateDocument' is prohibited.");
+
+ await expect(
+ mongoConnector.replaceDocument(readOnlyConn, {
+ collection: "c",
+ filter: { a: 1 },
+ replacement: { b: 2 },
+ }),
+ ).rejects.toThrow("Database is configured as read-only. 'replaceDocument' is prohibited.");
+
+ await expect(
+ mongoConnector.deleteDocument(readOnlyConn, { collection: "c", filter: { a: 1 } }),
+ ).rejects.toThrow("Database is configured as read-only. 'deleteDocument' is prohibited.");
+
+ await expect(
+ mongoConnector.createCollection(readOnlyConn, { collection: "c_new" }),
+ ).rejects.toThrow("Database is configured as read-only. 'createCollection' is prohibited.");
+
+ await expect(
+ mongoConnector.dropCollection(readOnlyConn, { collection: "c_old" }),
+ ).rejects.toThrow("Database is configured as read-only. 'dropCollection' is prohibited.");
+
+ await expect(
+ mongoConnector.createIndexes(readOnlyConn, { collection: "c", key: { a: 1 } }),
+ ).rejects.toThrow("Database is configured as read-only. 'createIndexes' is prohibited.");
+
+ await expect(
+ mongoConnector.dropIndex(readOnlyConn, { collection: "c", indexName: "idx_1" }),
+ ).rejects.toThrow("Database is configured as read-only. 'dropIndex' is prohibited.");
+
+ await expect(
+ mongoConnector.hideIndex(readOnlyConn, { collection: "c", indexName: "idx_1", hidden: true }),
+ ).rejects.toThrow("Database is configured as read-only. 'hideIndex' is prohibited.");
+
+ // 10-13: Bulk Engine Guards in mongoBulkEngine.ts
+ const mockDbService = {
+ getDatabaseConnection: jest.fn().mockResolvedValue({
+ dbType: DBType.MONGODB,
+ db: { id: "ro_bulk_db", readonly: true },
+ conn: readOnlyConn,
+ }),
+ } as any;
+ const bulkEngine = new MongoBulkEngine(mockDbService);
+
+ await expect(
+ bulkEngine.bulkInsert({ dbId: "ro_bulk_db", collection: "c", documents: [{ a: 1 }] }),
+ ).rejects.toMatchObject({ code: "MONGO_READ_ONLY" });
+
+ await expect(
+ bulkEngine.bulkUpdate({
+ dbId: "ro_bulk_db",
+ collection: "c",
+ filter: { a: 1 },
+ update: { $set: { b: 2 } },
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_READ_ONLY" });
+
+ await expect(
+ bulkEngine.bulkDelete({ dbId: "ro_bulk_db", collection: "c", filter: { a: 1 } }),
+ ).rejects.toMatchObject({ code: "MONGO_READ_ONLY" });
+
+ const opState = bulkEngine.opManager.createOperation("import", "ro_bulk_db", "c", "json");
+ await expect(
+ bulkEngine.importChunk({
+ operationId: opState.operation.operationId,
+ chunkIndex: 0,
+ isLastChunk: true,
+ payload: "[]",
+ }),
+ ).rejects.toMatchObject({ code: "MONGO_READ_ONLY" });
+
+ // 14-15: Migration Handler Guards in migrationHandlers.ts
+ const mockRpc = { sendResponse: jest.fn(), sendError: jest.fn() };
+ const mockLogger = { info: jest.fn(), error: jest.fn(), warn: jest.fn() } as any;
+ const migHandlers = new MigrationHandlers(mockRpc as any, mockLogger, mockDbService, {} as any);
+
+ await migHandlers.handleApplyMigration({ dbId: "ro_bulk_db", version: 1 }, 101);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(
+ 101,
+ expect.objectContaining({ code: "MONGO_READ_ONLY" }),
+ );
+
+ await migHandlers.handleRollbackMigration({ dbId: "ro_bulk_db", version: 1 }, 102);
+ expect(mockRpc.sendError).toHaveBeenCalledWith(
+ 102,
+ expect.objectContaining({ code: "MONGO_READ_ONLY" }),
+ );
+ });
+
+ // ---------------------------------------------------------------------------
+ // 18. test_implementation_time_driver_version_verification
+ // ---------------------------------------------------------------------------
+ test("18. test_implementation_time_driver_version_verification", async () => {
+ // 1. Check resolved mongodb version
+
+ const driverPackage = require("mongodb/package.json");
+ expect(driverPackage.version).toBe("6.21.0");
+
+ // 2. Check bridge/package.json specification
+ const pkgJsonPath = path.resolve(__dirname, "../../package.json");
+ const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+ expect(pkgJson.dependencies.mongodb).toMatch(/6\.21\.0/);
+
+ // 3. Runtime topology and connection pool structure assertion
+ const mockSocket = { destroyed: false, destroy: jest.fn() };
+ const serverMap = new Map();
+ const mockPool = {
+ connections: [{ socket: mockSocket }],
+ checkedOut: new Set(),
+ destroy: jest.fn(),
+ };
+ serverMap.set("node1", { pool: mockPool });
+
+ const client: any = new MongoClient("mongodb://localhost:27017/test");
+ // Attach simulated 6.21.0 topology structure
+ client.topology = {
+ s: {
+ servers: serverMap,
+ },
+ };
+
+ expect(client.topology.s.servers instanceof Map).toBe(true);
+ expect(mockPool.connections[0].socket).toBeDefined();
+
+ // Verify forceDestroyMongoSockets correctly processes standard 6.21.0 layout
+ const result = forceDestroyMongoSockets(client);
+ expect(result.status).toBe("destroy_requested");
+ expect(result.totalDiscoveredSockets).toBe(1);
+ expect(mockSocket.destroy).toHaveBeenCalled();
+
+ // Verify structural deviation throws explicit diagnostic error / unconfirmed status
+ const corruptClient: any = { topology: { s: { servers: "invalid_structure" } } };
+ const corruptResult = forceDestroyMongoSockets(corruptClient);
+ expect(corruptResult.status).toBe("unconfirmed");
+ expect(corruptResult.error?.message).toContain("Unexpected MongoDB driver topology structure");
+ });
+});
diff --git a/bridge/__tests__/services/mongoMigrationDrift.test.ts b/bridge/__tests__/services/mongoMigrationDrift.test.ts
new file mode 100644
index 00000000..fa6e0c80
--- /dev/null
+++ b/bridge/__tests__/services/mongoMigrationDrift.test.ts
@@ -0,0 +1,416 @@
+import { describe, expect, test, beforeEach, afterEach } from "@jest/globals";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { Db } from "mongodb";
+import {
+ computeManifestChecksum,
+ listMigrations,
+ MAX_MANIFEST_SIZE_BYTES,
+ MIGRATIONS_COLLECTION,
+} from "../../src/services/mongoMigrationEngine";
+import { LOCK_COLLECTION } from "../../src/services/mongoMigrationLock";
+import { MongoMigrationSummary } from "../../src/types/mongoMigration";
+
+function createDriftTestDb(summaries: MongoMigrationSummary[]) {
+ const summaryMap = new Map();
+ for (const s of summaries) {
+ summaryMap.set(s._id, { ...s });
+ }
+
+ const writeCalls: string[] = [];
+
+ const db: any = {
+ collection(name: string) {
+ if (name === LOCK_COLLECTION) {
+ return {
+ async findOne() {
+ return null; // No active lock
+ },
+ };
+ }
+
+ if (name === MIGRATIONS_COLLECTION) {
+ return {
+ find() {
+ return {
+ sort() {
+ return {
+ async toArray() {
+ return Array.from(summaryMap.values());
+ },
+ };
+ },
+ };
+ },
+ async updateOne() {
+ writeCalls.push("updateOne");
+ return { matchedCount: 1, modifiedCount: 1 };
+ },
+ async findOneAndUpdate() {
+ writeCalls.push("findOneAndUpdate");
+ return null;
+ },
+ async insertOne() {
+ writeCalls.push("insertOne");
+ return { insertedId: "test" };
+ },
+ async deleteOne() {
+ writeCalls.push("deleteOne");
+ return { deletedCount: 1 };
+ },
+ };
+ }
+
+ return {
+ find() {
+ return {
+ toArray: async () => [],
+ };
+ },
+ };
+ },
+ getWriteCalls: () => writeCalls,
+ };
+
+ return db;
+}
+
+describe("mongoMigrationDrift", () => {
+ let tempProjectRoot: string;
+ let migrationsDir: string;
+
+ beforeEach(() => {
+ tempProjectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "relwave-drift-"));
+ migrationsDir = path.join(tempProjectRoot, "migrations", "mongo");
+ fs.mkdirSync(migrationsDir, { recursive: true });
+ });
+
+ afterEach(() => {
+ try {
+ fs.rmSync(tempProjectRoot, { recursive: true, force: true });
+ } catch {
+ // Cleanup best effort
+ }
+ });
+
+ describe("Three-State Precedence & Drift Classification", () => {
+ test("Precedence 1: flags UNVERIFIABLE with MANIFEST_MISSING when applied migration has no on-disk file", async () => {
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Add Users Collection",
+ checksum: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ expect(res.appliedMigrations.length).toBe(1);
+ const applied = res.appliedMigrations[0];
+ expect(applied.driftStatus).toBe("UNVERIFIABLE");
+ expect(applied.drifted).toBe(false);
+ expect(applied.driftDetails?.reason).toBe("MANIFEST_MISSING");
+ expect(applied.driftDetails?.message).toContain("not found");
+ });
+
+ test("Precedence 2: flags UNVERIFIABLE with MANIFEST_PARSE_ERROR when multiple on-disk manifest files produce duplicate migration IDs", async () => {
+ const manifestContent = JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "Duplicate One",
+ up: [{ type: "createCollection", collection: "test" }],
+ });
+ fs.writeFileSync(
+ path.join(migrationsDir, "20261031120000_a.mql.json"),
+ manifestContent,
+ "utf8",
+ );
+ fs.writeFileSync(
+ path.join(migrationsDir, "20261031120000_b.mql.json"),
+ manifestContent,
+ "utf8",
+ );
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Duplicate Test",
+ checksum: computeManifestChecksum(manifestContent),
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ const applied = res.appliedMigrations[0];
+ expect(applied.driftStatus).toBe("UNVERIFIABLE");
+ expect(applied.drifted).toBe(false);
+ expect(applied.driftDetails?.reason).toBe("MANIFEST_PARSE_ERROR");
+ expect(applied.driftDetails?.message).toContain("Multiple manifest files");
+ expect(applied.driftDetails?.message).toContain("20261031120000_a.mql.json");
+ expect(applied.driftDetails?.message).toContain("20261031120000_b.mql.json");
+ expect(res.pendingMigrations.length).toBe(0);
+ });
+
+ test("Precedence 2: flags UNVERIFIABLE with MANIFEST_PARSE_ERROR when manifest exceeds 1MB without reading file content", async () => {
+ const filename = "20261031120000_oversized.mql.json";
+ const filePath = path.join(migrationsDir, filename);
+
+ const header = Buffer.from('{"version":"1.0","id":"20261031120000","name":"large","pad":"');
+ const footer = Buffer.from('"}');
+ const padSize = MAX_MANIFEST_SIZE_BYTES + 100 - header.length - footer.length;
+ const pad = Buffer.alloc(padSize, "x");
+ const fullContent = Buffer.concat([header, pad, footer]);
+ fs.writeFileSync(filePath, fullContent);
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Oversized Test",
+ checksum: "somehash",
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ const applied = res.appliedMigrations[0];
+ expect(applied.driftStatus).toBe("UNVERIFIABLE");
+ expect(applied.drifted).toBe(false);
+ expect(applied.driftDetails?.reason).toBe("MANIFEST_PARSE_ERROR");
+ expect(applied.driftDetails?.message).toContain("exceeds 1MB limit");
+ });
+
+ test("Precedence 2: flags UNVERIFIABLE with MANIFEST_PARSE_ERROR when on-disk manifest contains invalid JSON", async () => {
+ const filename = "20261031120000_corrupt.mql.json";
+ fs.writeFileSync(path.join(migrationsDir, filename), "{ corrupt json: not closed", "utf8");
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Corrupt Test",
+ checksum: "somehash",
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ const applied = res.appliedMigrations[0];
+ expect(applied.driftStatus).toBe("UNVERIFIABLE");
+ expect(applied.drifted).toBe(false);
+ expect(applied.driftDetails?.reason).toBe("MANIFEST_PARSE_ERROR");
+ expect(applied.driftDetails?.message).toContain("Failed to parse manifest JSON");
+ });
+
+ test("Precedence 2: associates corrupt JSON manifest with applied migration via filename-derived 14-digit timestamp ID", async () => {
+ const filename = "20261031154500_corrupt_manifest.mql.json";
+ fs.writeFileSync(path.join(migrationsDir, filename), "broken json syntax", "utf8");
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031154500",
+ name: "Corrupt Test Timestamp",
+ checksum: "hash123",
+ status: "APPLIED",
+ startedAt: "2026-10-31T15:45:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ const applied = res.appliedMigrations[0];
+ expect(applied._id).toBe("20261031154500");
+ expect(applied.driftStatus).toBe("UNVERIFIABLE");
+ expect(applied.driftDetails?.reason).toBe("MANIFEST_PARSE_ERROR");
+ });
+
+ test("Precedence 3: flags UNVERIFIABLE with RECORDED_CHECKSUM_MISSING when database record has empty checksum", async () => {
+ const manifestContent = JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "Legacy Migration",
+ up: [{ type: "createCollection", collection: "orders" }],
+ });
+ fs.writeFileSync(
+ path.join(migrationsDir, "20261031120000_orders.mql.json"),
+ manifestContent,
+ "utf8",
+ );
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Legacy Migration",
+ checksum: "", // Empty baseline checksum
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ const applied = res.appliedMigrations[0];
+ expect(applied.driftStatus).toBe("UNVERIFIABLE");
+ expect(applied.drifted).toBe(false);
+ expect(applied.driftDetails?.reason).toBe("RECORDED_CHECKSUM_MISSING");
+ expect(applied.driftDetails?.actualChecksum).toBe(computeManifestChecksum(manifestContent));
+ expect(applied.driftDetails?.message).toContain("no baseline checksum");
+ });
+
+ test("Precedence 4: flags VERIFIED with CHECKSUM_MATCH when on-disk manifest SHA-256 matches recorded checksum", async () => {
+ const manifestContent = JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "Verified Migration",
+ up: [{ type: "createCollection", collection: "users" }],
+ });
+ fs.writeFileSync(
+ path.join(migrationsDir, "20261031120000_users.mql.json"),
+ manifestContent,
+ "utf8",
+ );
+ const computedHash = computeManifestChecksum(manifestContent);
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Verified Migration",
+ checksum: computedHash,
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ const applied = res.appliedMigrations[0];
+ expect(applied.driftStatus).toBe("VERIFIED");
+ expect(applied.drifted).toBe(false);
+ expect(applied.driftDetails?.reason).toBe("CHECKSUM_MATCH");
+ expect(applied.driftDetails?.expectedChecksum).toBe(computedHash);
+ expect(applied.driftDetails?.actualChecksum).toBe(computedHash);
+ });
+
+ test("Precedence 5: flags DRIFTED with CHECKSUM_MISMATCH when on-disk manifest content has been altered", async () => {
+ const manifestContent = JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "Drifted Migration",
+ up: [{ type: "createCollection", collection: "altered" }],
+ });
+ fs.writeFileSync(
+ path.join(migrationsDir, "20261031120000_drifted.mql.json"),
+ manifestContent,
+ "utf8",
+ );
+ const onDiskHash = computeManifestChecksum(manifestContent);
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Drifted Migration",
+ checksum: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ const applied = res.appliedMigrations[0];
+ expect(applied.driftStatus).toBe("DRIFTED");
+ expect(applied.drifted).toBe(true);
+ expect(applied.driftDetails?.reason).toBe("CHECKSUM_MISMATCH");
+ expect(applied.driftDetails?.expectedChecksum).toBe(
+ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+ );
+ expect(applied.driftDetails?.actualChecksum).toBe(onDiskHash);
+ });
+ });
+
+ describe("Execution Semantics Immutability", () => {
+ test("does not modify recorded checksums or write to _relwave_migrations during listMigrations", async () => {
+ const manifestContent = JSON.stringify({
+ version: "1.0",
+ id: "20261031120000",
+ name: "Immutability Test",
+ up: [],
+ });
+ fs.writeFileSync(
+ path.join(migrationsDir, "20261031120000_immut.mql.json"),
+ manifestContent,
+ "utf8",
+ );
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Immutability Test",
+ checksum: "hash_differs_from_disk",
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 0,
+ totalSteps: 0,
+ fencingToken: 1,
+ },
+ ]);
+
+ await listMigrations(db as Db, tempProjectRoot);
+ expect(db.getWriteCalls().length).toBe(0);
+ });
+
+ test("does not change migration execution status from APPLIED", async () => {
+ const manifestContent = "altered content";
+ fs.writeFileSync(
+ path.join(migrationsDir, "20261031120000_status.mql.json"),
+ manifestContent,
+ "utf8",
+ );
+
+ const db = createDriftTestDb([
+ {
+ _id: "20261031120000",
+ name: "Status Test",
+ checksum: "oldhash",
+ status: "APPLIED",
+ startedAt: "2026-10-31T12:00:00Z",
+ executedSteps: 1,
+ totalSteps: 1,
+ fencingToken: 1,
+ },
+ ]);
+
+ const res = await listMigrations(db as Db, tempProjectRoot);
+ expect(res.appliedMigrations[0].status).toBe("APPLIED");
+ });
+
+ test("reuses identical computeManifestChecksum function and CRLF-normalization as apply-time path", () => {
+ const lfContent = '{\n "version": "1.0"\n}\n';
+ const crlfContent = '{\r\n "version": "1.0"\r\n}\r\n';
+ expect(computeManifestChecksum(lfContent)).toBe(computeManifestChecksum(crlfContent));
+ });
+ });
+});
diff --git a/bridge/__tests__/services/mongoQueryCancellation.test.ts b/bridge/__tests__/services/mongoQueryCancellation.test.ts
new file mode 100644
index 00000000..ec909713
--- /dev/null
+++ b/bridge/__tests__/services/mongoQueryCancellation.test.ts
@@ -0,0 +1,391 @@
+import { describe, expect, test, jest, beforeEach, afterEach } from "@jest/globals";
+import {
+ createDriverSettlementSignal,
+ ZombieOperationRegistry,
+ UnrecoverableZombieRegistry,
+ executeIndependentTeardown,
+ OperationLifecycleSupervisor,
+} from "../../src/handlers/queryHandlers";
+import { SessionManager } from "../../src/sessionManager";
+import { OperationLifecycleHandle, TeardownOutcome } from "../../src/types/mongo";
+
+function createDeferred() {
+ let resolve!: (value: T | PromiseLike) => void;
+ let reject!: (reason?: any) => void;
+ const promise = new Promise((res, rej) => {
+ resolve = res;
+ reject = rej;
+ });
+ return { promise, resolve, reject };
+}
+
+describe("MongoDB Stage 8 Phase 3 Query Cancellation & Lifecycle Supervision Suite", () => {
+ beforeEach(() => {
+ ZombieOperationRegistry.resetForTesting();
+ UnrecoverableZombieRegistry.resetForTesting();
+ jest.restoreAllMocks();
+ });
+
+ afterEach(() => {
+ ZombieOperationRegistry.resetForTesting();
+ UnrecoverableZombieRegistry.resetForTesting();
+ });
+
+ // -------------------------------------------------------------------------
+ // 1. Authoritative Lease-Release Invariant Tests
+ // -------------------------------------------------------------------------
+
+ test("1. Condition A: Natural driver settlement permits release, exactly once", () => {
+ let releaseCount = 0;
+ const { signal, markSettled } = createDriverSettlementSignal();
+ const handle: OperationLifecycleHandle = {
+ id: "op-1",
+ dbId: "db-1",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ const supervisor = new OperationLifecycleSupervisor(
+ handle,
+ () => {
+ releaseCount++;
+ },
+ {} as any,
+ { uri: "mongodb://localhost:27017", database: "testdb" },
+ );
+
+ // Prior to settlement, safeReleaseLease does nothing
+ supervisor.safeReleaseLease();
+ expect(releaseCount).toBe(0);
+ expect(handle.hasReleasedLease).toBeFalsy();
+
+ // Natural settlement occurs
+ markSettled("fulfilled");
+ expect(signal.isSettled).toBe(true);
+
+ supervisor.safeReleaseLease();
+ expect(releaseCount).toBe(1);
+ expect(handle.hasReleasedLease).toBe(true);
+ expect(handle.state).toBe("completed");
+
+ // Repeated calls are idempotent (exactly once)
+ supervisor.safeReleaseLease();
+ expect(releaseCount).toBe(1);
+ });
+
+ test("2. Condition B: Confirmed socket destruction must await actual driver settlement before releasing lease", async () => {
+ let releaseCount = 0;
+ const { signal, markSettled } = createDriverSettlementSignal();
+ const handle: OperationLifecycleHandle = {
+ id: "op-2",
+ dbId: "db-1",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ const mockDbService = {
+ connectionPool: { getActiveOperationsCount: () => 1 },
+ invalidateConnection: jest.fn().mockImplementation(() => Promise.resolve()),
+ };
+
+ const supervisor = new OperationLifecycleSupervisor(
+ handle,
+ () => {
+ releaseCount++;
+ },
+ mockDbService as any,
+ { uri: "mongodb://localhost:27017", database: "testdb" },
+ );
+
+ // Mock executeDebouncedTeardown to return destroy_confirmed
+ const registry = ZombieOperationRegistry.getInstance();
+ jest.spyOn(registry, "executeDebouncedTeardown").mockResolvedValue({
+ status: "destroy_confirmed",
+ invalidationSucceeded: true,
+ socketsDestroyed: 2,
+ durationMs: 15,
+ });
+
+ const teardownPromise = supervisor.runTeardownLoop("client-key-test");
+
+ // Sockets are confirmed destroyed, but driver promise has not settled yet!
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ expect(releaseCount).toBe(0);
+ expect(signal.isSettled).toBe(false);
+
+ // Driver promise rejects due to MongoNetworkError from severed socket
+ markSettled("rejected", new Error("MongoNetworkError: connection closed"));
+
+ await teardownPromise;
+ expect(releaseCount).toBe(1);
+ expect(handle.hasReleasedLease).toBe(true);
+ });
+
+ test("3. Strict Prohibitions: Failed teardown and shutdown handoff NEVER release lease", async () => {
+ let releaseCount = 0;
+ const { signal } = createDriverSettlementSignal();
+ const handle: OperationLifecycleHandle = {
+ id: "op-3",
+ dbId: "db-1",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ const supervisor = new OperationLifecycleSupervisor(
+ handle,
+ () => {
+ releaseCount++;
+ },
+ {} as any,
+ { uri: "mongodb://localhost:27017", database: "testdb" },
+ );
+
+ const registry = ZombieOperationRegistry.getInstance();
+
+ // 3a: Shutdown handoff
+ jest.spyOn(registry, "executeDebouncedTeardown").mockResolvedValueOnce({
+ status: "shutdown_handoff",
+ reason: "shutdown_adopted",
+ durationMs: 0,
+ });
+
+ await supervisor.runTeardownLoop("client-key-test");
+ expect(handle.state).toBe("shutdown_adopted");
+ expect(releaseCount).toBe(0);
+ expect(handle.hasReleasedLease).toBeFalsy();
+
+ // 3b: Unrecoverable failure
+ jest.spyOn(registry, "executeDebouncedTeardown").mockResolvedValue({
+ status: "unrecoverable_failure",
+ invalidationSucceeded: false,
+ totalAttempts: 3,
+ durationMs: 50,
+ });
+
+ await supervisor.runTeardownLoop("client-key-test");
+ expect(handle.state).toBe("unrecoverable_pinned");
+ expect(releaseCount).toBe(0);
+ expect(UnrecoverableZombieRegistry.getInstance().has("op-3")).toBe(true);
+ });
+
+ // -------------------------------------------------------------------------
+ // 2. Pre-Driver Cancellation Gates & Signal Racing Tests
+ // -------------------------------------------------------------------------
+
+ test("4. Pre-driver cancellation gate: Cancel before driver promise unwinds and releases lease", async () => {
+ let releaseCount = 0;
+ const { signal } = createDriverSettlementSignal();
+ const handle: OperationLifecycleHandle = {
+ id: "op-gate",
+ dbId: "db-gate",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ const supervisor = new OperationLifecycleSupervisor(
+ handle,
+ () => {
+ releaseCount++;
+ },
+ {} as any,
+ { uri: "mongodb://localhost:27017", database: "testdb" },
+ );
+
+ // Rejected outer promise prior to driver invocation
+ const outerRejection = Promise.reject(new Error("Pre-driver aborted"));
+
+ await supervisor.superviseTimeoutOrCancel(undefined, outerRejection);
+
+ expect(signal.isSettled).toBe(true);
+ expect(releaseCount).toBe(1);
+ expect(handle.hasReleasedLease).toBe(true);
+ });
+
+ test("5. Fast Pre-Check: Already settled driver returns status: driver_settled immediately", async () => {
+ const { signal, markSettled } = createDriverSettlementSignal();
+ markSettled("fulfilled");
+
+ const handle: OperationLifecycleHandle = {
+ id: "op-fast",
+ dbId: "db-fast",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ const outcome = await executeIndependentTeardown({} as any, "db-fast", {}, handle, 1, 3);
+
+ expect(outcome.status).toBe("driver_settled");
+ });
+
+ test("6. Invalidation racing: Driver settling during pool invalidation aborts teardown", async () => {
+ const { signal, markSettled } = createDriverSettlementSignal();
+ const handle: OperationLifecycleHandle = {
+ id: "op-inval-race",
+ dbId: "db-inval",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ const invalDeferred = createDeferred();
+ const mockDbService = {
+ invalidateConnection: jest.fn().mockReturnValue(invalDeferred.promise),
+ };
+
+ const teardownPromise = executeIndependentTeardown(
+ mockDbService as any,
+ "db-inval",
+ {},
+ handle,
+ 1,
+ 3,
+ );
+
+ // Driver settles while invalidation is in-flight
+ markSettled("fulfilled");
+ invalDeferred.resolve();
+
+ const outcome = await teardownPromise;
+ expect(outcome.status).toBe("driver_settled");
+ });
+
+ // -------------------------------------------------------------------------
+ // 3. Concurrency, Zombie Registry & Escalation
+ // -------------------------------------------------------------------------
+
+ test("7. Deadlock-free sole-op recovery: poolActiveOps <= 1 enters teardown immediately", async () => {
+ const { signal } = createDriverSettlementSignal();
+ const handle: OperationLifecycleHandle = {
+ id: "op-sole",
+ dbId: "db-sole",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ const mockDbService = {
+ connectionPool: { getActiveOperationsCount: () => 1 },
+ };
+
+ const supervisor = new OperationLifecycleSupervisor(handle, () => {}, mockDbService as any, {
+ uri: "mongodb://localhost:27017",
+ database: "testdb",
+ });
+
+ const teardownSpy = jest.spyOn(supervisor, "runTeardownLoop").mockResolvedValue();
+
+ const outerPromise = Promise.reject(new Error("Timeout")).catch(() => {});
+ const driverDeferred = createDeferred();
+
+ await supervisor.superviseTimeoutOrCancel(driverDeferred.promise, outerPromise as any, 10);
+
+ // Teardown should have been invoked immediately without registering a 60s zombie
+ expect(teardownSpy).toHaveBeenCalledTimes(1);
+ expect(ZombieOperationRegistry.getInstance().getZombiesForDb("db-sole")).toHaveLength(0);
+ });
+
+ test("8. Sibling concurrency: poolActiveOps > 1 pins zombie with active 60s escalation timer", async () => {
+ const { signal } = createDriverSettlementSignal();
+ const handle: OperationLifecycleHandle = {
+ id: "op-sibling",
+ dbId: "db-sibling",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ let escalated = false;
+ const registry = ZombieOperationRegistry.getInstance();
+ registry.registerZombie(handle, "client-key-sibling", () => {
+ escalated = true;
+ });
+
+ expect(handle.state).toBe("zombie_pinned");
+ expect(registry.getZombiesForDb("db-sibling")).toHaveLength(1);
+ expect(escalated).toBe(false);
+
+ // Unregister cancels the timer cleanly
+ registry.unregisterZombie(handle.id);
+ expect(registry.getZombiesForDb("db-sibling")).toHaveLength(0);
+ });
+
+ test("9. Shutdown handoff: snapshotAndDisarm disarms timers and snapshots in-flight teardowns", async () => {
+ const registry = ZombieOperationRegistry.getInstance();
+
+ const { signal } = createDriverSettlementSignal();
+ const handle: OperationLifecycleHandle = {
+ id: "op-shutdown",
+ dbId: "db-shutdown",
+ state: "running",
+ settlementSignal: signal,
+ };
+
+ registry.registerZombie(handle, "key-shut", () => {});
+ expect(registry.getZombiesForDb("db-shutdown")).toHaveLength(1);
+
+ // Mock an in-flight teardown
+ const inFlightOutcome: TeardownOutcome = {
+ status: "destroy_confirmed",
+ invalidationSucceeded: true,
+ socketsDestroyed: 1,
+ durationMs: 20,
+ };
+ registry.executeDebouncedTeardown("db-shutdown", "key-shut", async () => inFlightOutcome);
+
+ const adopted = registry.snapshotAndDisarm();
+ expect(adopted.length).toBeGreaterThanOrEqual(1);
+ expect(registry.getZombiesForDb("db-shutdown")).toHaveLength(0);
+
+ // Adoption with Promise.allSettled is rejection-safe
+ const results = await Promise.allSettled(adopted);
+ expect(results[0].status).toBe("fulfilled");
+ });
+
+ // -------------------------------------------------------------------------
+ // 4. SessionManager Synchronous Non-Blocking Cancel
+ // -------------------------------------------------------------------------
+
+ test("10. SessionManager synchronous non-blocking cancel and at-most-once callback", () => {
+ const sm = new SessionManager();
+ const sid = "sess-123";
+ sm.create(sid);
+
+ let callbackCount = 0;
+ sm.registerCancel(sid, () => {
+ callbackCount++;
+ });
+
+ // Synchronous cancel returns boolean
+ const res1 = sm.cancel(sid);
+ expect(res1).toBe(true);
+ expect(callbackCount).toBe(1);
+
+ // Repeated cancel is idempotent and does not dispatch duplicate callback
+ const res2 = sm.cancel(sid);
+ expect(res2).toBe(true);
+ expect(callbackCount).toBe(1);
+
+ // Unknown session returns false
+ const resUnknown = sm.cancel("unknown-session-id");
+ expect(resUnknown).toBe(false);
+
+ sm.destroy();
+ });
+
+ test("11. SessionManager post-registration cancel dispatch", () => {
+ const sm = new SessionManager();
+ const sid = "sess-early-cancel";
+ sm.create(sid);
+
+ // Cancel arrives before cancel callback is registered
+ const cancelled = sm.cancel(sid);
+ expect(cancelled).toBe(true);
+
+ let callbackFired = false;
+ sm.registerCancel(sid, () => {
+ callbackFired = true;
+ });
+
+ // Callback is dispatched immediately upon registration
+ expect(callbackFired).toBe(true);
+
+ sm.destroy();
+ });
+});
diff --git a/bridge/docker-compose.test.yml b/bridge/docker-compose.test.yml
index 190aab41..0b63e4c6 100644
--- a/bridge/docker-compose.test.yml
+++ b/bridge/docker-compose.test.yml
@@ -67,6 +67,19 @@ services:
timeout: 5s
retries: 5
+ mongodb:
+ image: mongo:7
+ environment:
+ # Runs without auth so the credential-free integration test can connect.
+ MONGO_INITDB_DATABASE: testdb
+ ports:
+ - "27017:27017"
+ healthcheck:
+ test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping')"]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+
ssh-server:
image: linuxserver/openssh-server
environment:
diff --git a/bridge/package.json b/bridge/package.json
index c2b36d48..3e615dfa 100644
--- a/bridge/package.json
+++ b/bridge/package.json
@@ -1,6 +1,6 @@
{
"name": "relwave-bridge",
- "version": "1.2.0",
+ "version": "1.3.0",
"type": "commonjs",
"main": "dist/index.cjs",
"scripts": {
@@ -30,6 +30,7 @@
"better-sqlite3": "^11.9.0",
"dotenv": "^17.2.3",
"groq-sdk": "^1.2.1",
+ "mongodb": "^6.21.0",
"mysql2": "^3.15.3",
"ollama": "^0.6.3",
"openai": "^6.41.0",
diff --git a/bridge/pnpm-lock.yaml b/bridge/pnpm-lock.yaml
index 47fc76ed..aec0cbca 100644
--- a/bridge/pnpm-lock.yaml
+++ b/bridge/pnpm-lock.yaml
@@ -44,6 +44,9 @@ importers:
groq-sdk:
specifier: ^1.2.1
version: 1.2.1
+ mongodb:
+ specifier: ^6.21.0
+ version: 6.21.0
mysql2:
specifier: ^3.15.3
version: 3.15.3
@@ -629,6 +632,9 @@ packages:
'@mistralai/mistralai@2.2.5':
resolution: {integrity: sha512-ATbWzKkNzNAZ+gtw9MI/c/ULTMG80tKUiRNIbQFfg4OP0uEZZpTfXZeBCNfs5Dq0uqMQ/tQWc4o6RRJQtMrpDA==}
+ '@mongodb-js/saslprep@1.6.1':
+ resolution: {integrity: sha512-D4CQtk9IwjCLAvCf1xvHEod3960q8XMUzfmdRU9qjUNlHnesGuTOvJcOTaPm9koZ1caUKA2aTbszZiAkcmSgmg==}
+
'@napi-rs/keyring-darwin-arm64@1.2.0':
resolution: {integrity: sha512-CA83rDeyONDADO25JLZsh3eHY8yTEtm/RS6ecPsY+1v+dSawzT9GywBMu2r6uOp1IEhQs/xAfxgybGAFr17lSA==}
engines: {node: '>= 10'}
@@ -799,6 +805,12 @@ packages:
'@types/strip-json-comments@0.0.30':
resolution: {integrity: sha512-7NQmHra/JILCd1QqpSzl8+mJRc8ZHz3uDm8YV1Ks9IhK0epEiTw8aIErbvH9PI+6XbqhyIQy3462nEsn7UVzjQ==}
+ '@types/webidl-conversions@7.0.3':
+ resolution: {integrity: sha512-CiJJvcRtIgzadHCYXw7dqEnMNRjhGZlYK05Mj9OyktqV8uVT8fD2BFOB7S1uwBE3Kj2Z+4UyPmFw/Ixgw/LAlA==}
+
+ '@types/whatwg-url@11.0.5':
+ resolution: {integrity: sha512-coYR071JRaHa+xoEvvYqvnIHaVqaYrLPbsufM9BF63HkwI5Lgmy2QR8Q5K/lYDYo5AK82wOvSOS0UsLTpTG7uQ==}
+
'@types/yargs-parser@21.0.3':
resolution: {integrity: sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ==}
@@ -1056,6 +1068,10 @@ packages:
bser@2.1.1:
resolution: {integrity: sha512-gQxTNE/GAfIIrmHLUE3oJyp5FO6HRBfhjnw4/wMmA63ZGDJnWBmgY/lyQBpnDUkGmAhbSe39tx2d/iTOAfglwQ==}
+ bson@6.10.4:
+ resolution: {integrity: sha512-WIsKqkSC0ABoBJuT1LEX+2HEvNmNKKgnTAyd0fL8qzK4SH2i9NXg+t08YtdZp/V9IZ33cxe3iV4yM0qg8lMQng==}
+ engines: {node: '>=16.20.1'}
+
buffer-from@1.1.2:
resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
@@ -1665,6 +1681,9 @@ packages:
makeerror@1.0.12:
resolution: {integrity: sha512-JmqCvUhmt43madlpFzG4BQzG2Z3m6tvQDNKdClZnO3VbIudJYmxsT0FNJMeiB2+JTSlTQTSbU8QdesVmwJcmLg==}
+ memory-pager@1.5.0:
+ resolution: {integrity: sha512-ZS4Bp4r/Zoeq6+NLJpP+0Zzm0pR8whtGPf1XExKLJBAczGMnSi3It14OiNCStjQjM6NU1okjQGSxgEZN8eBYKg==}
+
merge-stream@2.0.0:
resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
@@ -1702,6 +1721,36 @@ packages:
engines: {node: '>=10'}
hasBin: true
+ mongodb-connection-string-url@3.0.2:
+ resolution: {integrity: sha512-rMO7CGo/9BFwyZABcKAWL8UJwH/Kc2x0g72uhDWzG48URRax5TCIcJ7Rc3RZqffZzO/Gwff/jyKwCU9TN8gehA==}
+
+ mongodb@6.21.0:
+ resolution: {integrity: sha512-URyb/VXMjJ4da46OeSXg+puO39XH9DeQpWCslifrRn9JWugy0D+DvvBvkm2WxmHe61O/H19JM66p1z7RHVkZ6A==}
+ engines: {node: '>=16.20.1'}
+ peerDependencies:
+ '@aws-sdk/credential-providers': ^3.188.0
+ '@mongodb-js/zstd': ^1.1.0 || ^2.0.0
+ gcp-metadata: ^5.2.0
+ kerberos: ^2.0.1
+ mongodb-client-encryption: '>=6.0.0 <7'
+ snappy: ^7.3.2
+ socks: ^2.7.1
+ peerDependenciesMeta:
+ '@aws-sdk/credential-providers':
+ optional: true
+ '@mongodb-js/zstd':
+ optional: true
+ gcp-metadata:
+ optional: true
+ kerberos:
+ optional: true
+ mongodb-client-encryption:
+ optional: true
+ snappy:
+ optional: true
+ socks:
+ optional: true
+
ms@2.1.3:
resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
@@ -1944,6 +1993,10 @@ packages:
pump@3.0.4:
resolution: {integrity: sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==}
+ punycode@2.3.1:
+ resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
+ engines: {node: '>=6'}
+
pure-rand@7.0.1:
resolution: {integrity: sha512-oTUZM/NAZS8p7ANR3SHh30kXB+zK2r2BPcEn/awJIbOvq82WoMN4p62AWWp3Hhw50G0xMsw1mhIBLqHw64EcNQ==}
@@ -2057,6 +2110,9 @@ packages:
resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
engines: {node: '>=0.10.0'}
+ sparse-bitfield@3.0.3:
+ resolution: {integrity: sha512-kvzhi7vqKTfkh0PZU+2D2PIllw2ymqJKujUcyPMd9Y75Nv4nPbGJZXNhxsgdQab2BmlDct1YnfQCguEvHr7VsQ==}
+
split2@4.2.0:
resolution: {integrity: sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==}
engines: {node: '>= 10.x'}
@@ -2172,6 +2228,10 @@ packages:
tr46@0.0.3:
resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+ tr46@5.1.1:
+ resolution: {integrity: sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==}
+ engines: {node: '>=18'}
+
tree-kill@1.2.2:
resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
hasBin: true
@@ -2301,9 +2361,17 @@ packages:
webidl-conversions@3.0.1:
resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+ webidl-conversions@7.0.0:
+ resolution: {integrity: sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==}
+ engines: {node: '>=12'}
+
whatwg-fetch@3.6.20:
resolution: {integrity: sha512-EqhiFU6daOA8kpjOWTL0olhVOF3i7OrFzSYiGsEMB8GcXS+RrzauAERX65xMeNWVqxA6HXH2m69Z9LaKKdisfg==}
+ whatwg-url@14.2.0:
+ resolution: {integrity: sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==}
+ engines: {node: '>=18'}
+
whatwg-url@5.0.0:
resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
@@ -2959,6 +3027,10 @@ snapshots:
- bufferutil
- utf-8-validate
+ '@mongodb-js/saslprep@1.6.1':
+ dependencies:
+ sparse-bitfield: 3.0.3
+
'@napi-rs/keyring-darwin-arm64@1.2.0':
optional: true
@@ -3113,6 +3185,12 @@ snapshots:
'@types/strip-json-comments@0.0.30': {}
+ '@types/webidl-conversions@7.0.3': {}
+
+ '@types/whatwg-url@11.0.5':
+ dependencies:
+ '@types/webidl-conversions': 7.0.3
+
'@types/yargs-parser@21.0.3': {}
'@types/yargs@17.0.35':
@@ -3369,6 +3447,8 @@ snapshots:
dependencies:
node-int64: 0.4.0
+ bson@6.10.4: {}
+
buffer-from@1.1.2: {}
buffer@5.7.1:
@@ -4136,6 +4216,8 @@ snapshots:
dependencies:
tmpl: 1.0.5
+ memory-pager@1.5.0: {}
+
merge-stream@2.0.0: {}
micromatch@4.0.8:
@@ -4163,6 +4245,17 @@ snapshots:
mkdirp@1.0.4: {}
+ mongodb-connection-string-url@3.0.2:
+ dependencies:
+ '@types/whatwg-url': 11.0.5
+ whatwg-url: 14.2.0
+
+ mongodb@6.21.0:
+ dependencies:
+ '@mongodb-js/saslprep': 1.6.1
+ bson: 6.10.4
+ mongodb-connection-string-url: 3.0.2
+
ms@2.1.3: {}
multistream@4.1.0:
@@ -4392,6 +4485,8 @@ snapshots:
end-of-stream: 1.4.5
once: 1.4.0
+ punycode@2.3.1: {}
+
pure-rand@7.0.1: {}
quick-format-unescaped@4.0.4: {}
@@ -4496,6 +4591,10 @@ snapshots:
source-map@0.6.1: {}
+ sparse-bitfield@3.0.3:
+ dependencies:
+ memory-pager: 1.5.0
+
split2@4.2.0: {}
sprintf-js@1.0.3: {}
@@ -4618,6 +4717,10 @@ snapshots:
tr46@0.0.3: {}
+ tr46@5.1.1:
+ dependencies:
+ punycode: 2.3.1
+
tree-kill@1.2.2: {}
ts-algebra@2.0.0: {}
@@ -4758,8 +4861,15 @@ snapshots:
webidl-conversions@3.0.1: {}
+ webidl-conversions@7.0.0: {}
+
whatwg-fetch@3.6.20: {}
+ whatwg-url@14.2.0:
+ dependencies:
+ tr46: 5.1.1
+ webidl-conversions: 7.0.0
+
whatwg-url@5.0.0:
dependencies:
tr46: 0.0.3
diff --git a/bridge/scripts/seed-mongodb.cjs b/bridge/scripts/seed-mongodb.cjs
new file mode 100644
index 00000000..3435a891
--- /dev/null
+++ b/bridge/scripts/seed-mongodb.cjs
@@ -0,0 +1,150 @@
+/*
+ * Standalone MongoDB seed script (manual tool).
+ *
+ * Seeds the test database with a couple of collections plus a view so the
+ * MongoDB connector's listing/stats can be exercised:
+ * - users (flat documents)
+ * - orders (nested documents with an ObjectId reference + array + Date)
+ * - active_users_view (a view over users, to exercise VIEW detection)
+ *
+ * Run with: node scripts/seed-mongodb.cjs
+ * Reads REAL_MONGODB_* from .env (loaded via dotenv).
+ */
+
+const fs = require("dotenv");
+fs.config({ path: require("path").join(__dirname, "..", ".env") });
+
+const { MongoClient, ObjectId } = require("mongodb");
+
+function wait(ms) {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function seed() {
+ const host = process.env.REAL_MONGODB_HOST || "127.0.0.1";
+ const port = process.env.REAL_MONGODB_PORT || "27017";
+ const user = process.env.REAL_MONGODB_USER;
+ const password = process.env.REAL_MONGODB_PASSWORD;
+ const database = process.env.REAL_MONGODB_DATABASE || "testdb";
+
+ // Build candidate URIs: prefer explicit REAL_MONGODB_URI, then credentialed if provided, with unauthenticated fallback
+ const uris = [];
+ if (process.env.REAL_MONGODB_URI) {
+ uris.push(process.env.REAL_MONGODB_URI);
+ } else {
+ if (user && password) {
+ uris.push(
+ `mongodb://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}/${database}?authSource=admin`,
+ );
+ }
+ uris.push(`mongodb://${host}:${port}/${database}`);
+ }
+
+ let client = null;
+ let connected = false;
+
+ for (let attempt = 1; attempt <= 15; attempt++) {
+ for (const testUri of uris) {
+ try {
+ const candidateClient = new MongoClient(testUri, {
+ serverSelectionTimeoutMS: 2000,
+ connectTimeoutMS: 2000,
+ });
+ await candidateClient.connect();
+ await candidateClient.db(database).command({ ping: 1 });
+ client = candidateClient;
+ connected = true;
+ break;
+ } catch {
+ // try next URI candidate or retry
+ }
+ }
+ if (connected) break;
+ await wait(1000);
+ }
+
+ if (!connected || !client) {
+ throw new Error(`MongoDB at ${host}:${port} was not reachable after 15 attempts.`);
+ }
+
+ const db = client.db(database);
+
+ // Idempotent: drop existing fixtures first.
+ for (const name of ["users", "orders", "active_users_view"]) {
+ try {
+ await db.dropCollection(name);
+ } catch {
+ // may not exist
+ }
+ }
+
+ const userIds = [];
+ const users = [
+ {
+ _id: new ObjectId(),
+ name: "John Doe",
+ email: "john@example.com",
+ age: 30,
+ active: true,
+ createdAt: new Date(),
+ },
+ {
+ _id: new ObjectId(),
+ name: "Jane Smith",
+ email: "jane@example.com",
+ age: 27,
+ active: true,
+ createdAt: new Date(),
+ },
+ {
+ _id: new ObjectId(),
+ name: "Bob Lee",
+ email: "bob@example.com",
+ age: 45,
+ active: false,
+ createdAt: new Date(),
+ },
+ ];
+ const userInsert = await db.collection("users").insertMany(users);
+ for (const id of Object.values(userInsert.insertedIds)) {
+ userIds.push(id);
+ }
+
+ const orders = [
+ {
+ _id: new ObjectId(),
+ userId: userIds[0],
+ items: [
+ { sku: "ABC-1", qty: 2, price: 9.99 },
+ { sku: "XYZ-9", qty: 1, price: 19.5 },
+ ],
+ total: 39.48,
+ status: "placed",
+ orderedAt: new Date(),
+ },
+ {
+ _id: new ObjectId(),
+ userId: userIds[1],
+ items: [{ sku: "ABC-1", qty: 5, price: 9.99 }],
+ total: 49.95,
+ status: "shipped",
+ orderedAt: new Date(),
+ },
+ ];
+ await db.collection("orders").insertMany(orders);
+
+ // A view to exercise VIEW detection in listTables/listCollections.
+ await db.command({
+ create: "active_users_view",
+ viewOn: "users",
+ pipeline: [{ $match: { active: true } }],
+ });
+
+ await client.close();
+ console.log("MongoDB test database seeded successfully.");
+}
+
+seed().catch((err) => {
+ console.error("Failed to seed MongoDB:", err);
+ process.exit(1);
+});
diff --git a/bridge/src/connectors/mongo.ts b/bridge/src/connectors/mongo.ts
new file mode 100644
index 00000000..a137c55c
--- /dev/null
+++ b/bridge/src/connectors/mongo.ts
@@ -0,0 +1,3269 @@
+/**
+ * MongoDB connector (Milestone 1 foundation).
+ *
+ * Implements the connection / listing / statistics subset required to wire
+ * MongoDB into the existing structural connector registry:
+ * - client pool (per uri+database)
+ * - testConnection
+ * - listCollections (native, document-oriented)
+ * - listTables (relational compatibility adapter → TableInfo[])
+ * - getDBStats (→ DBStats)
+ * - listSchemaNames (single pseudo-schema)
+ * - connectToDatabase (minimal; no baseline, no schema_migrations)
+ * - mongodbCache (satisfies the `${dbType}Cache` naming convention)
+ *
+ * Document-native operations (findDocuments / insertDocument / updateDocument /
+ * deleteDocument / runAggregation / inferCollectionSchema) and the row/table
+ * compatibility adapters land in a later milestone. They are intentionally NOT
+ * stubbed here.
+ *
+ * Credentials never appear in logs or error messages: connection errors are
+ * sanitized and the raw config is never logged.
+ */
+
+import {
+ MongoClient,
+ Collection,
+ FindOptions,
+ AggregateOptions,
+ Document,
+ CreateIndexesOptions,
+ Db,
+ MongoClientOptions,
+} from "mongodb";
+import { sanitizeMongoUri } from "../utils/mongoUri";
+import { createHash } from "crypto";
+import {
+ CursorCloseOutcome,
+ MongoExecutionContext,
+ MongoConfig,
+ MongoCollectionInfo,
+ MongoCollectionStats,
+ MongoBsonType,
+ MongoInferSchemaRequest,
+ MongoCollectionSchema,
+ MongoInferredField,
+ EJSONDocument,
+ EJsonValue,
+ MongoFindRequest,
+ MongoFindResult,
+ MongoInsertRequest,
+ MongoInsertResult,
+ MongoUpdateRequest,
+ MongoUpdateResult,
+ MongoDeleteRequest,
+ MongoDeleteResult,
+ MongoReplaceRequest,
+ MongoReplaceResult,
+ MongoCreateCollectionRequest,
+ MongoCreateCollectionResult,
+ MongoDropCollectionRequest,
+ MongoDropCollectionResult,
+ MongoAggregationRequest,
+ MongoAggregationResult,
+ MongoSortSpec,
+ MongoProjection,
+ MongoPageCacheKey,
+ MongoFindOpPayload,
+ MongoAggregateOpPayload,
+ MongoCountOpPayload,
+ MongoDistinctOpPayload,
+ MongoMqlExecuteRequest,
+ MongoMqlExecuteResult,
+ MongoExplainRequest,
+ MongoExplainResult,
+ MongoIndexCollation,
+ MongoIndexDetails,
+ MongoIndexListRequest,
+ MongoIndexListResult,
+ MongoIndexCreateRequest,
+ MongoIndexCreateResult,
+ MongoIndexDropRequest,
+ MongoIndexDropResult,
+ MongoIndexStatsItem,
+ MongoIndexStatsRequest,
+ MongoIndexStatsResult,
+ MongoIndexHideRequest,
+ MongoIndexHideResult,
+ MAX_PAGE_SIZE,
+ MAX_PAGE,
+ DEFAULT_PAGE_SIZE,
+ MAX_FILTER_SIZE_BYTES,
+ MAX_SORT_FIELDS,
+ MAX_PROJECTION_FIELDS,
+ MAX_AGG_STAGES,
+ MAX_AGG_STAGE_SIZE_BYTES,
+ MAX_AGG_RESULTS,
+ MAX_DISTINCT_VALUES,
+ MAX_EXPRESSION_DEPTH,
+ MAX_DOCUMENT_SIZE_BYTES,
+ DEFAULT_OP_TIMEOUT_MS,
+ MAX_OP_TIMEOUT_MS,
+ MAX_SAMPLE_SIZE,
+ MAX_INFERENCE_DEPTH,
+ MAX_INFERRED_FIELDS,
+ DEFAULT_SAMPLE_SIZE,
+ DEFAULT_MAX_DEPTH,
+} from "../types/mongo";
+import { TableInfo, DBStats, SchemaInfo } from "../types/common";
+import { CacheEntry } from "../types/cache";
+import logger from "../services/logger";
+import {
+ serializeMongoDocument,
+ serializeMongoValue,
+ serializeMongoEJSONDocument,
+ serializeMongoFilter,
+ serializeMongoUpdateOperand,
+ serializeMongoPipelineStage,
+ mongoBSONtoEJSON,
+ bsonTypeOf,
+ bsonNumericKind,
+} from "./mongoBson";
+
+// ---------------------------------------------------------------------------
+// Error sanitization — decision #8: never expose credentials in errors/logs.
+// ---------------------------------------------------------------------------
+
+/** Redact any embedded credentials if a message ever echoes the connection URI. */
+export function safeMongoError(err: unknown): string {
+ const base = err instanceof Error ? err.message : String(err);
+ return base.replace(/(mongodb\+?srv?:\/\/)[^@\s]+@/gi, "$1@");
+}
+
+// ---------------------------------------------------------------------------
+// CACHING
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL = 30_000;
+const STATS_CACHE_TTL = 10_000;
+const DOC_PAGE_TTL = 5_000; // M2 opt-in document-page cache (spec §14)
+const SCHEMA_CACHE_TTL = 300_000; // M3 inferred schema cache (5 min, spec §4.4, §9)
+
+class MongoCacheManager {
+ private tableListCache = new Map>();
+ private dbStatsCache = new Map>();
+ // M2 collection-scoped caches (spec §14)
+ private collectionStatsCache = new Map>();
+ private docPageCache = new Map>();
+ // M3 inferred schema cache
+ private inferredSchemaCache = new Map<
+ string,
+ CacheEntry & { connHash: string; collection: string }
+ >();
+
+ private getConfigKey(cfg: MongoConfig): string {
+ return `${cfg.uri || ""}:${cfg.database || ""}`;
+ }
+
+ /** Credential-free connection identifier for M2 query-result cache keys (spec §15). */
+ private getConnHash(cfg: MongoConfig): string {
+ return createHash("sha256")
+ .update(cfg.uri || "")
+ .digest("hex");
+ }
+
+ private getSchemaCacheKey(
+ cfg: MongoConfig,
+ collection: string,
+ sampleSize: number,
+ maxDepth: number,
+ ): string {
+ return createHash("sha256")
+ .update(
+ `${this.getConnHash(cfg)}:${cfg.database || ""}:${collection}:${sampleSize}:${maxDepth}`,
+ )
+ .digest("hex");
+ }
+
+ private isValid(entry: CacheEntry | undefined): boolean {
+ return !!entry && Date.now() - entry.timestamp < entry.ttl;
+ }
+
+ getTableList(cfg: MongoConfig): TableInfo[] | null {
+ const entry = this.tableListCache.get(this.getConfigKey(cfg));
+ return this.isValid(entry) ? entry!.data : null;
+ }
+ setTableList(cfg: MongoConfig, data: TableInfo[]): void {
+ this.tableListCache.set(this.getConfigKey(cfg), {
+ data,
+ timestamp: Date.now(),
+ ttl: CACHE_TTL,
+ });
+ }
+
+ getDBStats(cfg: MongoConfig): DBStats | null {
+ const entry = this.dbStatsCache.get(this.getConfigKey(cfg));
+ return this.isValid(entry) ? entry!.data : null;
+ }
+ setDBStats(cfg: MongoConfig, data: DBStats): void {
+ this.dbStatsCache.set(this.getConfigKey(cfg), {
+ data,
+ timestamp: Date.now(),
+ ttl: STATS_CACHE_TTL,
+ });
+ }
+
+ // ---- M2: collection-scoped caches (spec §14 / D-M2-5) ----
+
+ getCollectionStats(cfg: MongoConfig, collection: string): MongoCollectionStats | null {
+ const entry = this.collectionStatsCache.get(`${this.getConfigKey(cfg)}:${collection}`);
+ return this.isValid(entry) ? entry!.data : null;
+ }
+ setCollectionStats(cfg: MongoConfig, collection: string, data: MongoCollectionStats): void {
+ this.collectionStatsCache.set(`${this.getConfigKey(cfg)}:${collection}`, {
+ data,
+ timestamp: Date.now(),
+ ttl: STATS_CACHE_TTL,
+ });
+ }
+
+ getDocumentPage(cfg: MongoConfig, key: MongoPageCacheKey): EJSONDocument[] | null {
+ const entry = this.docPageCache.get(`${this.getConnHash(cfg)}:${key}`);
+ return this.isValid(entry) ? entry!.data : null;
+ }
+ setDocumentPage(cfg: MongoConfig, key: MongoPageCacheKey, docs: EJSONDocument[]): void {
+ this.docPageCache.set(`${this.getConnHash(cfg)}:${key}`, {
+ data: docs,
+ timestamp: Date.now(),
+ ttl: DOC_PAGE_TTL,
+ });
+ }
+
+ getInferredSchema(
+ cfg: MongoConfig,
+ collection: string,
+ sampleSize: number,
+ maxDepth: number,
+ ): MongoCollectionSchema | null {
+ const key = this.getSchemaCacheKey(cfg, collection, sampleSize, maxDepth);
+ const entry = this.inferredSchemaCache.get(key);
+ return this.isValid(entry) ? entry!.data : null;
+ }
+
+ setInferredSchema(
+ cfg: MongoConfig,
+ collection: string,
+ sampleSize: number,
+ maxDepth: number,
+ data: MongoCollectionSchema,
+ ): void {
+ const key = this.getSchemaCacheKey(cfg, collection, sampleSize, maxDepth);
+ this.inferredSchemaCache.set(key, {
+ data,
+ timestamp: Date.now(),
+ ttl: SCHEMA_CACHE_TTL,
+ connHash: this.getConnHash(cfg),
+ collection,
+ });
+ }
+
+ /** Evict a collection's stats + all its cached document pages (called on mutation). */
+ clearCollectionCache(cfg: MongoConfig, collection: string): void {
+ this.collectionStatsCache.delete(`${this.getConfigKey(cfg)}:${collection}`);
+ const connHash = this.getConnHash(cfg);
+ for (const k of Array.from(this.docPageCache.keys())) {
+ if (k.startsWith(`${connHash}:`)) this.docPageCache.delete(k);
+ }
+ for (const [k, v] of Array.from(this.inferredSchemaCache.entries())) {
+ if (v.connHash === connHash && v.collection === collection) {
+ this.inferredSchemaCache.delete(k);
+ }
+ }
+ }
+
+ clearForConnection(cfg: MongoConfig): void {
+ const key = this.getConfigKey(cfg);
+ for (const [k] of this.tableListCache) {
+ if (k.startsWith(key)) this.tableListCache.delete(k);
+ }
+ this.dbStatsCache.delete(key);
+ for (const k of Array.from(this.collectionStatsCache.keys())) {
+ if (k.startsWith(key)) this.collectionStatsCache.delete(k);
+ }
+ const connHash = this.getConnHash(cfg);
+ for (const k of Array.from(this.docPageCache.keys())) {
+ if (k.startsWith(`${connHash}:`)) this.docPageCache.delete(k);
+ }
+ for (const [k, v] of Array.from(this.inferredSchemaCache.entries())) {
+ if (v.connHash === connHash) {
+ this.inferredSchemaCache.delete(k);
+ }
+ }
+ }
+
+ clearAll(): void {
+ this.tableListCache.clear();
+ this.dbStatsCache.clear();
+ this.collectionStatsCache.clear();
+ this.docPageCache.clear();
+ this.inferredSchemaCache.clear();
+ }
+
+ flushConnection(cfg: MongoConfig): void {
+ this.clearForConnection(cfg);
+ }
+}
+
+export const mongodbCache = new MongoCacheManager();
+
+// ---------------------------------------------------------------------------
+// CLIENT CONNECTION POOL
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// CANONICAL CLIENT KEY FUNCTION (Section 4.3)
+// ---------------------------------------------------------------------------
+
+export function getClientKey(cfg: { uri?: string; database?: string }): string {
+ const normalizedDb = (cfg.database || "").trim().toLowerCase();
+ if (!cfg.uri) {
+ return `::${normalizedDb}`;
+ }
+
+ try {
+ const raw = cfg.uri.trim();
+ const isSrv = raw.toLowerCase().startsWith("mongodb+srv://");
+ const scheme = isSrv ? "mongodb+srv" : "mongodb";
+ const prefix = isSrv ? "mongodb+srv://" : "mongodb://";
+ const rest = raw.slice(prefix.length);
+
+ const qIdx = rest.indexOf("?");
+ const hIdx = rest.indexOf("#");
+ let endIdx = rest.length;
+ if (qIdx !== -1) endIdx = qIdx;
+ if (hIdx !== -1 && (qIdx === -1 || hIdx < qIdx)) endIdx = hIdx;
+ const authAndPath = rest.slice(0, endIdx);
+
+ const slashIdx = authAndPath.indexOf("/");
+ const authority = slashIdx !== -1 ? authAndPath.slice(0, slashIdx) : authAndPath;
+
+ let userPart = "";
+ let hostsPart = authority;
+ const atIdx = authority.lastIndexOf("@");
+ if (atIdx !== -1) {
+ const creds = authority.slice(0, atIdx);
+ hostsPart = authority.slice(atIdx + 1);
+ const colonIdx = creds.indexOf(":");
+ const rawUser = colonIdx !== -1 ? creds.slice(0, colonIdx) : creds;
+ if (rawUser) {
+ userPart = `${encodeURIComponent(decodeURIComponent(rawUser))}@`;
+ }
+ }
+
+ const normalizedHosts = hostsPart
+ .split(",")
+ .map((hp) => {
+ const trimmed = hp.trim().toLowerCase();
+ if (!trimmed) return "";
+ if (isSrv) return trimmed;
+ if (trimmed.startsWith("[")) {
+ const closeBracket = trimmed.indexOf("]");
+ if (closeBracket !== -1) {
+ const h = trimmed.slice(0, closeBracket + 1);
+ const after = trimmed.slice(closeBracket + 1);
+ if (after.startsWith(":")) {
+ const p = parseInt(after.slice(1), 10);
+ return `${h}:${isNaN(p) ? 27017 : p}`;
+ }
+ return `${h}:27017`;
+ }
+ }
+ const lastColon = trimmed.lastIndexOf(":");
+ if (lastColon !== -1) {
+ const h = trimmed.slice(0, lastColon);
+ const p = trimmed.slice(lastColon + 1);
+ const portNum = parseInt(p, 10);
+ return `${h}:${isNaN(portNum) ? 27017 : portNum}`;
+ }
+ return `${trimmed}:27017`;
+ })
+ .filter(Boolean)
+ .join(",");
+
+ const normalizedUri = `${scheme}://${userPart}${normalizedHosts}`;
+ return `${normalizedUri}::${normalizedDb}`;
+ } catch {
+ const sanitizedUri = sanitizeMongoUri(cfg.uri);
+ return `${sanitizedUri}::${normalizedDb}`;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// ATOMIC SHARED MONGO CLIENT REGISTRY & LIFECYCLE (Section 5)
+// ---------------------------------------------------------------------------
+
+export type SocketTeardownStatus = "destroy_confirmed" | "destroy_requested" | "unconfirmed";
+
+export interface SocketDestructionResult {
+ status: SocketTeardownStatus;
+ destroyedSockets: number;
+ totalDiscoveredSockets: number;
+ error?: Error;
+}
+
+export interface ManagedMongoClient {
+ client: MongoClient;
+ state: "active" | "closing" | "close_failed" | "closed";
+ closeError?: Error;
+ closePromise?: Promise;
+}
+
+export const clientRegistry = new Map();
+export const closingClients = new Map>();
+
+let isMongoShuttingDown = false;
+export function setMongoShuttingDown(val: boolean): void {
+ isMongoShuttingDown = val;
+}
+
+export const DEFAULT_MONGO_CLIENT_OPTIONS: MongoClientOptions = {
+ connectTimeoutMS: 5000,
+ socketTimeoutMS: 30000,
+ serverSelectionTimeoutMS: 5000,
+ maxIdleTimeMS: 60000,
+ maxPoolSize: 20,
+};
+
+export function getDriverOptions(_cfg?: MongoConfig): MongoClientOptions {
+ return {
+ ...DEFAULT_MONGO_CLIENT_OPTIONS,
+ };
+}
+
+export function forceDestroyMongoSockets(client: MongoClient): SocketDestructionResult {
+ let destroyedSockets = 0;
+ try {
+ const topology = (client as any).topology;
+ if (!topology) {
+ return { status: "destroy_confirmed", destroyedSockets: 0, totalDiscoveredSockets: 0 };
+ }
+
+ const servers = topology.s?.servers;
+ if (!(servers instanceof Map)) {
+ return {
+ status: "unconfirmed",
+ destroyedSockets: 0,
+ totalDiscoveredSockets: 0,
+ error: new Error("Unexpected MongoDB driver topology structure: servers Map not found"),
+ };
+ }
+
+ if (servers.size === 0) {
+ return { status: "destroy_confirmed", destroyedSockets: 0, totalDiscoveredSockets: 0 };
+ }
+
+ const uniqueConns = new Set();
+ const uniqueSockets = new Set();
+
+ for (const server of servers.values()) {
+ const pool = server.pool || server.s?.pool;
+ if (pool) {
+ if (pool.connections && typeof pool.connections[Symbol.iterator] === "function") {
+ for (const conn of pool.connections) {
+ if (conn) uniqueConns.add(conn);
+ }
+ }
+ if (pool.checkedOut instanceof Set) {
+ for (const conn of pool.checkedOut) {
+ if (conn) uniqueConns.add(conn);
+ }
+ }
+ if (typeof pool.destroy === "function") {
+ try {
+ pool.destroy();
+ } catch {}
+ }
+ }
+ }
+
+ for (const conn of uniqueConns) {
+ if (conn?.socket && typeof conn.socket.destroy === "function") {
+ uniqueSockets.add(conn.socket);
+ }
+ }
+
+ if (uniqueSockets.size === 0) {
+ return { status: "destroy_confirmed", destroyedSockets: 0, totalDiscoveredSockets: 0 };
+ }
+
+ const totalDiscoveredSockets = uniqueSockets.size;
+ let allDestroyedObserved = true;
+
+ for (const socket of uniqueSockets) {
+ try {
+ if (!socket.destroyed) {
+ socket.destroy();
+ }
+ destroyedSockets++;
+ if (!socket.destroyed) {
+ allDestroyedObserved = false;
+ }
+ } catch (sockErr) {
+ allDestroyedObserved = false;
+ logger.warn({ sockErr }, "Failed invoking destroy on individual MongoDB socket");
+ }
+ }
+
+ if (allDestroyedObserved && destroyedSockets === totalDiscoveredSockets) {
+ return { status: "destroy_confirmed", destroyedSockets, totalDiscoveredSockets };
+ }
+
+ return { status: "destroy_requested", destroyedSockets, totalDiscoveredSockets };
+ } catch (err: any) {
+ logger.warn({ err: safeMongoError(err) }, "Error during forceDestroyMongoSockets traversal");
+ return { status: "unconfirmed", destroyedSockets, totalDiscoveredSockets: 0, error: err };
+ }
+}
+
+export function closeMongoClientByKey(
+ clientKey: string,
+ options?: { force?: boolean; timeoutMs?: number; globalDeadline?: number },
+): Promise {
+ const existingClose = closingClients.get(clientKey);
+ const entry = clientRegistry.get(clientKey);
+
+ if (!entry || entry.state === "closed") {
+ return Promise.resolve();
+ }
+
+ const remainingMs =
+ options?.globalDeadline !== undefined
+ ? Math.max(0, options.globalDeadline - Date.now())
+ : options?.timeoutMs !== undefined
+ ? options.timeoutMs
+ : options?.force
+ ? 100
+ : undefined;
+
+ if (existingClose) {
+ if (remainingMs === undefined) {
+ return existingClose;
+ }
+
+ return (async () => {
+ let timer: NodeJS.Timeout | undefined;
+ const timeoutPromise = new Promise((_, reject) => {
+ timer = setTimeout(() => reject(new Error("Close timeout")), remainingMs);
+ });
+
+ try {
+ await Promise.race([existingClose, timeoutPromise]);
+ } catch (err: any) {
+ logger.warn(
+ { clientKey, err: safeMongoError(err) },
+ "In-flight MongoClient close exceeded deadline; escalating to forced socket destruction",
+ );
+ const result = forceDestroyMongoSockets(entry.client);
+ if (result.status === "destroy_confirmed") {
+ entry.state = "closed";
+ entry.closeError = undefined;
+ clientRegistry.delete(clientKey);
+ } else {
+ entry.state = "close_failed";
+ entry.closeError =
+ result.error || new Error(`Forced socket destruction state: ${result.status}`);
+ logger.error(
+ { clientKey, status: result.status, err: safeMongoError(entry.closeError) },
+ "Forced socket destruction not confirmed; retaining MongoClient in close_failed state",
+ );
+ }
+ } finally {
+ if (timer) clearTimeout(timer);
+ }
+ })();
+ }
+
+ entry.state = "closing";
+
+ const closePromise = (async () => {
+ let timer: NodeJS.Timeout | undefined;
+ try {
+ const driverClosePromise = entry.client.close(options?.force);
+ if (remainingMs !== undefined) {
+ const timeoutPromise = new Promise((_, reject) => {
+ timer = setTimeout(() => reject(new Error("Close timeout")), remainingMs);
+ });
+ await Promise.race([driverClosePromise, timeoutPromise]);
+ } else {
+ await driverClosePromise;
+ }
+
+ entry.state = "closed";
+ entry.closeError = undefined;
+ clientRegistry.delete(clientKey);
+ } catch (err: any) {
+ logger.warn(
+ { clientKey, err: safeMongoError(err) },
+ "MongoClient.close() rejected or timed out; escalating to forced socket destruction",
+ );
+ const result = forceDestroyMongoSockets(entry.client);
+ if (result.status === "destroy_confirmed") {
+ entry.state = "closed";
+ entry.closeError = undefined;
+ clientRegistry.delete(clientKey);
+ } else {
+ entry.state = "close_failed";
+ entry.closeError = result.error || err;
+ logger.error(
+ { err: safeMongoError(entry.closeError), status: result.status, clientKey },
+ "Failed to confirm MongoClient socket destruction; retained in close_failed state for recovery/watchdog",
+ );
+ throw err;
+ }
+ } finally {
+ if (timer) clearTimeout(timer);
+ closingClients.delete(clientKey);
+ entry.closePromise = undefined;
+ }
+ })();
+
+ entry.closePromise = closePromise;
+ closingClients.set(clientKey, closePromise);
+ return closePromise;
+}
+
+export function closeMongoClient(cfg: MongoConfig): Promise {
+ return closeMongoClientByKey(getClientKey(cfg));
+}
+
+export async function closeAllMongoClients(options?: {
+ force?: boolean;
+ timeoutMs?: number;
+ globalDeadline?: number;
+}): Promise {
+ const globalDeadline = options?.globalDeadline ?? Date.now() + (options?.timeoutMs ?? 100);
+ const remainingBudget = Math.max(0, globalDeadline - Date.now());
+
+ let globalTimer: NodeJS.Timeout | undefined;
+ const globalTimeoutPromise = new Promise((resolve) => {
+ globalTimer = setTimeout(resolve, remainingBudget);
+ });
+
+ const keys = Array.from(clientRegistry.keys());
+ const batchClosePromise = Promise.allSettled(
+ keys.map((key) =>
+ closeMongoClientByKey(key, {
+ force: options?.force,
+ globalDeadline,
+ }),
+ ),
+ );
+
+ await Promise.race([batchClosePromise, globalTimeoutPromise]);
+ if (globalTimer) clearTimeout(globalTimer);
+
+ for (const [key, entry] of clientRegistry.entries()) {
+ if (entry.state !== "closed") {
+ const result = forceDestroyMongoSockets(entry.client);
+ if (result.status === "destroy_confirmed") {
+ entry.state = "closed";
+ entry.closeError = undefined;
+ clientRegistry.delete(key);
+ } else {
+ entry.state = "close_failed";
+ if (!entry.closeError) {
+ entry.closeError =
+ result.error || new Error(`Forced socket destruction state: ${result.status}`);
+ }
+ }
+ }
+ }
+}
+
+export function getMongoClientSync(cfg: MongoConfig): MongoClient {
+ if (isMongoShuttingDown) {
+ throw new Error("Bridge is shutting down: MongoClient creation rejected");
+ }
+
+ const key = getClientKey(cfg);
+ let entry = clientRegistry.get(key);
+
+ if (entry && entry.state === "close_failed") {
+ throw new Error(
+ `Cannot create MongoClient: prior client for key '${key}' failed to force-close (${entry.closeError?.message || entry.closeError}). Resource ownership retained in registry; manual recovery or bridge restart required.`,
+ );
+ }
+
+ if (entry && entry.state === "closing") {
+ throw new Error(`MongoClient for key '${key}' is currently closing.`);
+ }
+
+ if (entry && entry.state === "active") {
+ return entry.client;
+ }
+
+ if (!entry || entry.state === "closed") {
+ if (!cfg.uri) throw new Error("MongoDB connection requires a connection URI");
+ const client = new MongoClient(cfg.uri, getDriverOptions(cfg));
+ entry = { client, state: "active" };
+ clientRegistry.set(key, entry);
+ }
+
+ return entry.client;
+}
+
+export async function getMongoClient(cfg: MongoConfig): Promise {
+ if (isMongoShuttingDown) {
+ throw new Error("Bridge is shutting down: MongoClient creation rejected");
+ }
+
+ const key = getClientKey(cfg);
+
+ const pendingClose = closingClients.get(key);
+ if (pendingClose) {
+ try {
+ await pendingClose;
+ } catch {}
+ }
+
+ let entry = clientRegistry.get(key);
+ if (entry && entry.state === "close_failed") {
+ try {
+ await closeMongoClientByKey(key, { force: true, timeoutMs: 100 });
+ } catch (err: any) {
+ throw new Error(
+ `Cannot create MongoClient: prior client for key '${key}' failed to force-close (${err?.message || err}). Resource ownership retained in registry; manual recovery or bridge restart required.`,
+ );
+ }
+ entry = clientRegistry.get(key);
+ if (entry && entry.state === "close_failed") {
+ throw new Error(
+ `Cannot create MongoClient: prior client for key '${key}' failed to force-close. Resource ownership retained in registry; manual recovery or bridge restart required.`,
+ );
+ }
+ }
+
+ if (entry && entry.state === "active") {
+ return entry.client;
+ }
+
+ if (!entry || entry.state === "closed") {
+ if (!cfg.uri) throw new Error("MongoDB connection requires a connection URI");
+ const client = new MongoClient(cfg.uri, getDriverOptions(cfg));
+ entry = { client, state: "active" };
+ clientRegistry.set(key, entry);
+ }
+
+ return entry.client;
+}
+
+/** Select the target database, defaulting to the configured one. */
+export function selectDb(cfg: MongoConfig): Db {
+ const client = getMongoClientSync(cfg);
+ return (cfg.database ? client.db(cfg.database) : client.db()) as Db;
+}
+
+// ---------------------------------------------------------------------------
+// READ-ONLY & SAFE EXPRESSION GUARDS (Section 7 & 8)
+// ---------------------------------------------------------------------------
+
+export function assertMongoNotReadOnly(conn: MongoConfig, operation: string): void {
+ if (conn.readonly || (conn as any).readOnly) {
+ throw new MongoApiError(
+ "MONGO_READ_ONLY",
+ `Database is configured as read-only. '${operation}' is prohibited.`,
+ );
+ }
+}
+
+// ---------------------------------------------------------------------------
+// CORE CONNECTOR OPERATIONS (M1 subset)
+// ---------------------------------------------------------------------------
+
+export async function testConnection(
+ cfg: MongoConfig,
+): Promise<{ ok: boolean; message?: string; status: "connected" | "disconnected" }> {
+ if (!cfg.uri) {
+ return { ok: false, status: "disconnected", message: "Missing connection URI" };
+ }
+
+ const tempClient = new MongoClient(cfg.uri, getDriverOptions(cfg));
+ try {
+ const targetDb = cfg.database ? tempClient.db(cfg.database) : tempClient.db();
+ await targetDb.command({ ping: 1 });
+ return { ok: true, status: "connected", message: "Connection successful" };
+ } catch (err) {
+ return { ok: false, status: "disconnected", message: safeMongoError(err) };
+ } finally {
+ try {
+ await tempClient.close();
+ } catch {
+ // ignore
+ }
+ }
+}
+
+/** Native: list collections (and views) in the configured database. */
+export async function listCollections(cfg: MongoConfig): Promise {
+ const cached = mongodbCache.getTableList(cfg);
+ if (cached) {
+ // Derive collection info from the cached relational adapter view.
+ return cached.map((t) => ({ name: t.name, type: t.type === "VIEW" ? "view" : "collection" }));
+ }
+
+ const db = selectDb(cfg);
+ const infos = await db.listCollections({}, { nameOnly: true }).toArray();
+
+ const result: MongoCollectionInfo[] = infos.map((c) => {
+ const isView = c.type === "view";
+ return { name: c.name, type: isView ? "view" : "collection" };
+ });
+
+ // Prime the table-list cache from the native result.
+ mongodbCache.setTableList(
+ cfg,
+ result.map((c) => ({
+ schema: cfg.database || "default",
+ name: c.name,
+ type: c.type === "view" ? "VIEW" : "BASE TABLE",
+ })),
+ );
+ return result;
+}
+
+/**
+ * Relational compatibility adapter: map collections → `TableInfo[]` so the
+ * existing `db.listTables` RPC and schema tree keep working. The relational
+ * `schema` filter is ignored (Mongo is not schema-namespaced).
+ */
+export async function listTables(cfg: MongoConfig, _schema?: string): Promise {
+ const cached = mongodbCache.getTableList(cfg);
+ if (cached) return cached;
+
+ const collections = await listCollections(cfg);
+ const tables: TableInfo[] = collections.map((c) => ({
+ schema: cfg.database || "default",
+ name: c.name,
+ type: c.type === "view" ? "VIEW" : "BASE TABLE",
+ }));
+ mongodbCache.setTableList(cfg, tables);
+ return tables;
+}
+
+/** Basic database statistics mapped onto the shared `DBStats` shape. */
+export async function getDBStats(cfg: MongoConfig): Promise {
+ const cached = mongodbCache.getDBStats(cfg);
+ if (cached) return cached;
+
+ const db = selectDb(cfg);
+ const stats = await db.stats();
+
+ let total_tables = 0;
+ try {
+ const collInfos = await db.listCollections({}, { nameOnly: true }).toArray();
+ total_tables = collInfos.length;
+ } catch (err) {
+ logger.warn({ err: safeMongoError(err) }, "MongoDB countCollections failed");
+ }
+
+ const total_rows = typeof stats.objects === "number" ? stats.objects : 0;
+ const total_db_size_mb =
+ typeof stats.size === "number" ? Math.round((stats.size / (1024 * 1024)) * 100) / 100 : 0;
+
+ const result: DBStats = { total_tables, total_rows, total_db_size_mb };
+ mongodbCache.setDBStats(cfg, result);
+ return result;
+}
+
+/** Single pseudo-schema (the database name) for the existing `db.listSchemas`. */
+export async function listSchemaNames(cfg: MongoConfig): Promise {
+ return [cfg.database || "default"];
+}
+
+/**
+ * Minimal connect bootstrap. Returns collections as pseudo-schemas and empty
+ * migration lists. No baseline and no `schema_migrations` — MongoDB migrations
+ * are out of scope for this milestone.
+ */
+export async function connectToDatabase(
+ cfg: MongoConfig,
+ _connectionId: string,
+ _options?: { readOnly?: boolean },
+): Promise<{
+ baselined: boolean;
+ schema: SchemaInfo[];
+ migrations: { local: unknown[]; applied: unknown[] };
+}> {
+ const collections = await listCollections(cfg);
+ const schema: SchemaInfo[] = collections.map((c) => ({ name: c.name }));
+ return {
+ baselined: false,
+ schema,
+ migrations: { local: [], applied: [] },
+ };
+}
+
+// ===========================================================================
+// M2 — MongoDB Document Engine (findDocuments / insertDocument / updateDocument
+// / deleteDocument / runAggregation). See docs/MONGODB_M2_SPEC.md.
+//
+// Document-native operations, distinct from the M1 row/table compatibility
+// adapters above. They run through a small MongoConnector class so the
+// executor/handler layer has one typed surface to call (spec §13). Errors map to
+// the stable MongoApiError codes (spec §11) and never carry credentials (§15).
+// ===========================================================================
+
+/** Stable JSON encoding with sorted keys, for size measurement + cache keys. */
+function canonicalJSON(value: unknown): string {
+ const sortKeys = (v: unknown): unknown => {
+ if (v && typeof v === "object" && !Array.isArray(v)) {
+ const obj = v as Record;
+ const sorted: Record = {};
+ for (const k of Object.keys(obj).sort()) sorted[k] = sortKeys(obj[k]);
+ return sorted;
+ }
+ if (Array.isArray(v)) return v.map(sortKeys);
+ return v;
+ };
+ return JSON.stringify(sortKeys(value));
+}
+
+function jsonByteSize(value: unknown): number {
+ return Buffer.byteLength(canonicalJSON(value), "utf8");
+}
+
+/** Stable, credential-free error carrying a M2 error code (spec §11). */
+export class MongoApiError extends Error {
+ constructor(
+ public readonly code: string,
+ message: string,
+ ) {
+ super(message);
+ this.name = "MongoApiError";
+ }
+}
+
+export function assertCollectionName(collection: unknown): asserts collection is string {
+ if (typeof collection !== "string" || collection.length === 0) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "collection must be a non-empty string");
+ }
+ if (Buffer.byteLength(collection, "utf8") > 120) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "collection name must not exceed 120 bytes");
+ }
+ if (collection.includes("$") || collection.includes("\0")) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collection name must not contain '$' or null bytes",
+ );
+ }
+ if (collection.startsWith("system.")) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collection name must not start with 'system.'",
+ );
+ }
+}
+
+export function assertNewCollectionName(collection: unknown): asserts collection is string {
+ if (typeof collection !== "string" || collection.length === 0) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "collection must be a non-empty string");
+ }
+ if (collection.length > 120) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collection name must not exceed 120 characters",
+ );
+ }
+ if (collection.includes("$") || collection.includes("\0")) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collection name must not contain '$' or null bytes",
+ );
+ }
+ if (collection.startsWith("system.")) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collection name must not start with 'system.'",
+ );
+ }
+ const VALID_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+ if (!VALID_NAME_REGEX.test(collection)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ `collection name '${collection}' is invalid; must start with a letter or underscore and contain only alphanumeric, underscores, or hyphens`,
+ );
+ }
+}
+
+export function assertNoOperatorKeys(doc: Record): void {
+ for (const key of Object.keys(doc)) {
+ if (key.startsWith("$")) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "replacement document must not contain top-level operator keys",
+ );
+ }
+ }
+}
+
+function assertSize(value: unknown, max: number, what: string): void {
+ if (jsonByteSize(value) > max) {
+ throw new MongoApiError("MONGO_LIMIT_EXCEEDED", `${what} exceeds the ${max}-byte limit`);
+ }
+}
+
+function validateSort(sort: MongoSortSpec | undefined): Record | undefined {
+ if (sort === undefined || sort === null) return undefined;
+ if (typeof sort !== "object" || Array.isArray(sort)) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", "sort must be an object");
+ }
+ const entries = Object.entries(sort);
+ if (entries.length > MAX_SORT_FIELDS) {
+ throw new MongoApiError("MONGO_LIMIT_EXCEEDED", `sort exceeds ${MAX_SORT_FIELDS} fields`);
+ }
+ const out: Record = {};
+ for (const [field, dir] of entries) {
+ if (field.includes("$") || field.startsWith(".")) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", `invalid sort field '${field}'`);
+ }
+ if (dir === 1 || dir === "ASC") out[field] = 1;
+ else if (dir === -1 || dir === "DESC") out[field] = -1;
+ else throw new MongoApiError("MONGO_INVALID_FILTER", `invalid sort direction for '${field}'`);
+ }
+ return out;
+}
+
+function validateProjection(
+ projection: MongoProjection | undefined,
+): Record | undefined {
+ if (projection === undefined || projection === null) return undefined;
+ if (typeof projection !== "object" || Array.isArray(projection)) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", "projection must be an object");
+ }
+ const entries = Object.entries(projection);
+ if (entries.length > MAX_PROJECTION_FIELDS) {
+ throw new MongoApiError(
+ "MONGO_LIMIT_EXCEEDED",
+ `projection exceeds ${MAX_PROJECTION_FIELDS} fields`,
+ );
+ }
+ const includes: string[] = [];
+ const excludes: string[] = [];
+ const out: Record = {};
+ for (const [field, mode] of entries) {
+ if (mode === 1 || mode === true) {
+ out[field] = 1;
+ includes.push(field);
+ } else if (mode === 0 || mode === false) {
+ out[field] = 0;
+ excludes.push(field);
+ } else {
+ throw new MongoApiError("MONGO_INVALID_FILTER", `invalid projection mode for '${field}'`);
+ }
+ }
+ if (includes.length > 0 && excludes.filter((f) => f !== "_id").length > 0) {
+ throw new MongoApiError(
+ "MONGO_INVALID_FILTER",
+ "cannot mix inclusion and exclusion (except _id)",
+ );
+ }
+ return out;
+}
+
+function assertNonEmptyFilter(filter: EJSONDocument): void {
+ if (typeof filter !== "object" || filter === null || Array.isArray(filter)) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", "filter must be an object");
+ }
+ if (Object.keys(filter).length === 0) {
+ throw new MongoApiError(
+ "MONGO_BULK_OP_FORBIDDEN",
+ "update/delete requires a non-empty filter to prevent accidental whole-collection operations",
+ );
+ }
+}
+
+function assertOperatorDocument(update: EJSONDocument): void {
+ if (typeof update !== "object" || update === null || Array.isArray(update)) {
+ throw new MongoApiError("MONGO_INVALID_UPDATE_OPERAND", "update must be an operator document");
+ }
+ const keys = Object.keys(update);
+ if (keys.length === 0) {
+ throw new MongoApiError("MONGO_INVALID_UPDATE_OPERAND", "No update operators provided");
+ }
+ for (const key of keys) {
+ if (!key.startsWith("$")) {
+ throw new MongoApiError(
+ "MONGO_INVALID_UPDATE_OPERAND",
+ `'${key}' is not an update operator (full-document replacement is not supported)`,
+ );
+ }
+ }
+}
+
+export const FORBIDDEN_PIPELINE_STAGES = new Set(["$out", "$merge"]);
+export const FORBIDDEN_EXPRESSION_OPS = new Set(["$function", "$accumulator", "$where"]);
+
+/**
+ * Recursively scans an object or array for forbidden expression operators ($function, $accumulator, $where).
+ */
+export function assertSafeExpressions(value: unknown, depth = 0): void {
+ if (depth > MAX_EXPRESSION_DEPTH) {
+ throw new MongoApiError(
+ "MONGO_LIMIT_EXCEEDED",
+ `Expression nesting exceeds maximum depth of ${MAX_EXPRESSION_DEPTH}`,
+ );
+ }
+ if (!value || typeof value !== "object") return;
+
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ assertSafeExpressions(item, depth + 1);
+ }
+ return;
+ }
+
+ for (const [key, val] of Object.entries(value)) {
+ if (FORBIDDEN_EXPRESSION_OPS.has(key)) {
+ throw new MongoApiError(
+ "MONGO_FORBIDDEN_OPERATOR",
+ `Operator '${key}' is forbidden (server-side JavaScript execution is not permitted)`,
+ );
+ }
+ assertSafeExpressions(val, depth + 1);
+ }
+}
+
+/**
+ * Recursively validates aggregation pipeline stages and nested sub-pipelines.
+ * Permits empty pipelines aggregate([]) as valid read operations.
+ */
+export function assertReadOnlyPipeline(pipeline: unknown[], depth = 0): void {
+ if (depth > MAX_EXPRESSION_DEPTH) {
+ throw new MongoApiError(
+ "MONGO_LIMIT_EXCEEDED",
+ `Pipeline nesting exceeds maximum depth of ${MAX_EXPRESSION_DEPTH}`,
+ );
+ }
+ if (!Array.isArray(pipeline)) {
+ throw new MongoApiError("MONGO_INVALID_PIPELINE", "Pipeline must be an array");
+ }
+ // Empty pipeline is valid in MongoDB; returns all documents
+ if (pipeline.length === 0) {
+ return;
+ }
+ if (pipeline.length > MAX_AGG_STAGES) {
+ throw new MongoApiError("MONGO_LIMIT_EXCEEDED", `Pipeline exceeds ${MAX_AGG_STAGES} stages`);
+ }
+
+ for (const stage of pipeline) {
+ if (typeof stage !== "object" || stage === null || Array.isArray(stage)) {
+ throw new MongoApiError(
+ "MONGO_INVALID_PIPELINE",
+ "Each pipeline stage must be a non-null object",
+ );
+ }
+ const keys = Object.keys(stage);
+ if (keys.length !== 1) {
+ throw new MongoApiError(
+ "MONGO_INVALID_PIPELINE",
+ "Each pipeline stage must have exactly one operator key",
+ );
+ }
+ const stageName = keys[0];
+ if (!stageName.startsWith("$")) {
+ throw new MongoApiError(
+ "MONGO_INVALID_PIPELINE",
+ `Invalid stage name '${stageName}'; must begin with '$'`,
+ );
+ }
+ if (FORBIDDEN_PIPELINE_STAGES.has(stageName)) {
+ throw new MongoApiError(
+ "MONGO_WRITE_STAGE_FORBIDDEN",
+ `Stage '${stageName}' is forbidden in read-only aggregation queries`,
+ );
+ }
+
+ assertSize(stage, MAX_AGG_STAGE_SIZE_BYTES, `Pipeline stage ${stageName}`);
+
+ // Scan all expressions inside this stage for forbidden operators
+ const stageBody = (stage as Record)[stageName];
+ assertSafeExpressions(stageBody, depth + 1);
+
+ // Recurse into known nested sub-pipeline containers
+ if (
+ stageName === "$lookup" &&
+ stageBody &&
+ typeof stageBody === "object" &&
+ !Array.isArray(stageBody)
+ ) {
+ if (stageBody.pipeline !== undefined) {
+ if (!Array.isArray(stageBody.pipeline)) {
+ throw new MongoApiError("MONGO_INVALID_PIPELINE", "$lookup.pipeline must be an array");
+ }
+ assertReadOnlyPipeline(stageBody.pipeline, depth + 1);
+ }
+ }
+ if (
+ stageName === "$unionWith" &&
+ stageBody &&
+ typeof stageBody === "object" &&
+ !Array.isArray(stageBody)
+ ) {
+ if (stageBody.pipeline !== undefined) {
+ if (!Array.isArray(stageBody.pipeline)) {
+ throw new MongoApiError("MONGO_INVALID_PIPELINE", "$unionWith.pipeline must be an array");
+ }
+ assertReadOnlyPipeline(stageBody.pipeline, depth + 1);
+ }
+ }
+ if (stageName === "$facet") {
+ if (typeof stageBody !== "object" || stageBody === null || Array.isArray(stageBody)) {
+ throw new MongoApiError(
+ "MONGO_INVALID_PIPELINE",
+ "$facet stage specification must be an object",
+ );
+ }
+ for (const [facetName, facetPipeline] of Object.entries(stageBody)) {
+ if (!Array.isArray(facetPipeline)) {
+ throw new MongoApiError(
+ "MONGO_INVALID_PIPELINE",
+ `$facet pipeline for '${facetName}' must be an array`,
+ );
+ }
+ assertReadOnlyPipeline(facetPipeline as EJSONDocument[], depth + 1);
+ }
+ }
+ }
+}
+
+export function validatePipeline(pipeline: unknown[]): unknown[] {
+ assertReadOnlyPipeline(pipeline);
+ return pipeline;
+}
+
+export function clampMqlTimeout(ms: number | undefined, defaultMs: number, maxMs = 60000): number {
+ if (ms === undefined || ms === null) {
+ return defaultMs;
+ }
+ if (typeof ms !== "number" || !Number.isFinite(ms) || !Number.isInteger(ms) || ms <= 0) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "maxTimeMS must be a positive integer");
+ }
+ return Math.min(Math.max(1, ms), maxMs);
+}
+
+export const WHITELIST_READ_OPS = new Set([
+ "find",
+ "aggregate",
+ "countDocuments",
+ "estimatedDocumentCount",
+ "distinct",
+]);
+
+function clampPageSize(pageSize: number | undefined): number {
+ const n =
+ typeof pageSize === "number" && Number.isFinite(pageSize)
+ ? Math.floor(pageSize)
+ : DEFAULT_PAGE_SIZE;
+ if (n < 1) return 1;
+ if (n > MAX_PAGE_SIZE) return MAX_PAGE_SIZE;
+ return n;
+}
+
+function clampPage(page: number | undefined): number {
+ const n = typeof page === "number" && Number.isFinite(page) ? Math.floor(page) : 1;
+ return n < 1 ? 1 : n;
+}
+
+function clampTimeout(ms?: number): number {
+ const base = typeof ms === "number" && ms > 0 ? ms : DEFAULT_OP_TIMEOUT_MS;
+ return Math.min(base, MAX_OP_TIMEOUT_MS);
+}
+
+// ---- M3 Clamping Helpers (docs/MONGODB_M3_SPEC.md §4.4, §4.6) ----
+
+export function clampInferSampleSize(size?: number): number {
+ if (typeof size !== "number" || isNaN(size)) return DEFAULT_SAMPLE_SIZE;
+ return Math.min(Math.max(1, Math.floor(size)), MAX_SAMPLE_SIZE);
+}
+
+export function clampInferMaxDepth(depth?: number): number {
+ if (typeof depth !== "number" || isNaN(depth)) return DEFAULT_MAX_DEPTH;
+ return Math.min(Math.max(1, Math.floor(depth)), MAX_INFERENCE_DEPTH);
+}
+
+function isPlainRecord(v: unknown): v is Record {
+ return (
+ typeof v === "object" &&
+ v !== null &&
+ !Array.isArray(v) &&
+ !(v instanceof Date) &&
+ !Buffer.isBuffer(v) &&
+ !(v instanceof Uint8Array) &&
+ !(v as any)._bsontype
+ );
+}
+
+interface FieldAccumulatorStats {
+ path: string;
+ depth: number;
+ parentPath?: string;
+ isArray: boolean;
+ isNested: boolean;
+ count: number;
+ nullCount: number;
+ typeCounts: Map;
+ numericKinds: Set<"int" | "double">;
+ arrayElementTypes: Set;
+ sampleValue?: EJSONDocument | any;
+ maxChildDepth?: number;
+ truncated?: boolean;
+}
+
+/**
+ * Pure statistical accumulator over driver-native documents for schema inference.
+ * Never makes network or driver calls (docs/MONGODB_M3_SPEC.md §4.4).
+ */
+export class FieldAccumulator {
+ private fieldMap = new Map();
+
+ constructor(
+ public readonly sampleSize: number,
+ public readonly maxDepth: number,
+ ) {}
+
+ ingest(doc: Document | Record, parentPath = "", depth = 0): void {
+ if (!doc || typeof doc !== "object" || Array.isArray(doc)) return;
+
+ for (const [key, value] of Object.entries(doc)) {
+ if (key === "_bsontype") continue;
+
+ const path = parentPath ? `${parentPath}.${key}` : key;
+
+ if (!this.fieldMap.has(path)) {
+ if (this.fieldMap.size >= MAX_INFERRED_FIELDS) {
+ if (parentPath && this.fieldMap.has(parentPath)) {
+ this.fieldMap.get(parentPath)!.truncated = true;
+ }
+ continue;
+ }
+ this.fieldMap.set(path, {
+ path,
+ depth,
+ parentPath: parentPath || undefined,
+ isArray: false,
+ isNested: false,
+ count: 0,
+ nullCount: 0,
+ typeCounts: new Map(),
+ numericKinds: new Set<"int" | "double">(),
+ arrayElementTypes: new Set(),
+ });
+ }
+
+ const stats = this.fieldMap.get(path)!;
+
+ if (parentPath) {
+ let p: string | undefined = parentPath;
+ while (p) {
+ const ancestor = this.fieldMap.get(p);
+ if (ancestor) {
+ ancestor.maxChildDepth = Math.max(ancestor.maxChildDepth ?? 0, depth);
+ p = ancestor.parentPath;
+ } else {
+ break;
+ }
+ }
+ }
+
+ const bType = bsonTypeOf(value);
+ stats.typeCounts.set(bType, (stats.typeCounts.get(bType) || 0) + 1);
+
+ if (value !== undefined) {
+ stats.count++;
+ }
+ if (value === null) {
+ stats.nullCount++;
+ }
+
+ if (stats.sampleValue === undefined && value !== undefined && value !== null) {
+ stats.sampleValue = serializeMongoValue(value);
+ }
+
+ if (bType === "number") {
+ const numKind = bsonNumericKind(value);
+ if (numKind) {
+ stats.numericKinds.add(numKind);
+ }
+ }
+
+ if (Array.isArray(value)) {
+ stats.isArray = true;
+ for (const item of value) {
+ stats.arrayElementTypes.add(bsonTypeOf(item));
+ }
+ } else if (isPlainRecord(value)) {
+ stats.isNested = true;
+ if (depth < this.maxDepth) {
+ this.ingest(value, path, depth + 1);
+ } else {
+ stats.truncated = true;
+ }
+ }
+ }
+ }
+
+ toFields(): MongoInferredField[] {
+ const fields: MongoInferredField[] = [];
+
+ for (const stats of this.fieldMap.values()) {
+ const sortedTypes = Array.from(stats.typeCounts.entries()).sort((a, b) => {
+ if (b[1] !== a[1]) return b[1] - a[1];
+ if (a[0] === "null" || a[0] === "undefined") return 1;
+ if (b[0] === "null" || b[0] === "undefined") return -1;
+ return a[0].localeCompare(b[0]);
+ });
+
+ const dominantType = sortedTypes.length > 0 ? sortedTypes[0][0] : "null";
+ const types = sortedTypes.map(([t]) => t);
+
+ const typeConflicts =
+ types.length > 1 ? sortedTypes.map(([bsonType, count]) => ({ bsonType, count })) : [];
+
+ const presencePct =
+ this.sampleSize > 0 ? Math.round((stats.count / this.sampleSize) * 1000) / 10 : 0;
+
+ const field: MongoInferredField = {
+ path: stats.path,
+ bsonType: dominantType,
+ types,
+ numericKinds:
+ stats.numericKinds.size > 0
+ ? (Array.from(stats.numericKinds).sort() as Array<"int" | "double">)
+ : undefined,
+ depth: stats.depth,
+ parentPath: stats.parentPath,
+ isArray: stats.isArray,
+ isNested: stats.isNested,
+ count: stats.count,
+ nullCount: stats.nullCount,
+ sampleSize: this.sampleSize,
+ presencePct,
+ nullable: stats.nullCount > 0,
+ optional: stats.count < this.sampleSize,
+ typeConflicts,
+ arrayElementTypes: stats.isArray ? Array.from(stats.arrayElementTypes).sort() : undefined,
+ sampleValue: stats.sampleValue,
+ maxChildDepth: stats.maxChildDepth,
+ truncated: stats.truncated ? true : undefined,
+ };
+
+ fields.push(field);
+ }
+
+ fields.sort((a, b) => {
+ if (a.depth !== b.depth) return a.depth - b.depth;
+ return a.path.localeCompare(b.path);
+ });
+
+ return fields;
+ }
+}
+
+function isEmptyObject(obj: unknown): boolean {
+ return (
+ typeof obj === "object" && obj !== null && !Array.isArray(obj) && Object.keys(obj).length === 0
+ );
+}
+
+/**
+ * Run a driver operation under a client-side timeout. On expiry the in-flight
+ * driver promise is aborted and a MONGO_OPERATION_TIMEOUT error is thrown
+ * (spec §12). Mirrors the AbortController pattern of the SQL streamQueryCancelable.
+ */
+export function withMongoTimeout(
+ ms: number,
+ fn: (signal: AbortSignal) => Promise,
+): Promise {
+ const controller = new AbortController();
+ let timer: ReturnType | undefined;
+ const timeout = new Promise((_, reject) => {
+ timer = setTimeout(() => {
+ controller.abort();
+ reject(
+ new MongoApiError("MONGO_OPERATION_TIMEOUT", `MongoDB operation timed out after ${ms}ms`),
+ );
+ }, ms);
+ });
+ const run = (async () => {
+ try {
+ return await fn(controller.signal);
+ } finally {
+ if (timer) clearTimeout(timer);
+ }
+ })();
+ run.catch(() => {}); // avoid an unhandled rejection if the timeout wins the race
+ return Promise.race([run, timeout]);
+}
+
+/** Defensive: strip any credential fragments from an error message (spec §11/§15). */
+function stripCredentialTokens(message: string): string {
+ return message
+ .replace(/password[=:]\S+/gi, "password=")
+ .replace(/\bpasswd\b[=:]\S+/gi, "passwd=");
+}
+
+/** Map a driver error to a stable, credential-free M2 error (spec §11). */
+export function mapMongoError(err: unknown): MongoApiError {
+ if (err instanceof MongoApiError) return err;
+ const anyErr = err as { codeName?: string; code?: number; name?: string; message?: string };
+ const codeName = anyErr?.codeName;
+ const code = anyErr?.code;
+ let mapped: { code: string; message: string };
+ if (anyErr?.name === "MongoServerError") {
+ if (codeName === "NamespaceNotFound" || code === 26) {
+ mapped = { code: "MONGO_NS_NOT_FOUND", message: "Namespace not found" };
+ } else if (code === 11000 || code === 11001) {
+ mapped = { code: "MONGO_DUPLICATE_KEY", message: "Duplicate key" };
+ } else if (codeName === "AuthenticationFailed" || code === 18) {
+ mapped = { code: "MONGO_AUTH_ERROR", message: "Authentication failed" };
+ } else if (codeName === "MaxTimeMSExpired" || code === 50) {
+ mapped = { code: "MONGO_OPERATION_TIMEOUT", message: "Operation timed out" };
+ } else {
+ mapped = { code: "MONGO_UNKNOWN_ERROR", message: safeMongoError(anyErr?.message) };
+ }
+ } else {
+ mapped = { code: "MONGO_CONNECTION_ERROR", message: safeMongoError(err) };
+ }
+ return new MongoApiError(mapped.code, stripCredentialTokens(mapped.message));
+}
+
+function selectCollection(config: MongoConfig, collection: string): Collection {
+ return selectDb(config).collection(collection);
+}
+
+/** Whether a collection (or view) exists in the configured database. */
+export async function collectionExists(config: MongoConfig, collection: string): Promise {
+ const db = selectDb(config);
+ const infos = await db.listCollections({ name: collection }, { nameOnly: true }).toArray();
+ return infos.length > 0;
+}
+
+/** Credential-free cache key for a document page (spec §15). */
+function pageCacheKey(
+ collection: string,
+ filter: EJSONDocument,
+ sort: Record | undefined,
+ projection: Record | undefined,
+ page: number,
+ pageSize: number,
+): string {
+ const canonical = JSON.stringify([
+ collection,
+ filter,
+ sort ?? null,
+ projection ?? null,
+ page,
+ pageSize,
+ ]);
+ return createHash("sha256").update(canonical).digest("hex");
+}
+
+function buildFindResult(
+ collection: string,
+ documents: EJSONDocument[],
+ total: number,
+ page: number,
+ pageSize: number,
+): MongoFindResult {
+ const totalPages = total === 0 ? 0 : Math.ceil(total / pageSize);
+ return {
+ collection,
+ documents,
+ total,
+ page,
+ pageSize,
+ totalPages,
+ hasMore: page * pageSize < total,
+ };
+}
+
+/**
+ * BSON deserialization options that keep numeric/binary values in their typed
+ * form (int32 -> Int32, int64 -> Long, double -> Double, binary -> Binary)
+ * instead of promoting them to plain JS numbers. Without this the driver
+ * collapses every numeric BSON value to a JS number, so the EJSON converter
+ * could not emit $numberInt / $numberLong / $numberDouble and the documented
+ * round-trip (§7.1) would silently lose type information.
+ */
+const PRESERVE_BSON_TYPES = {
+ promoteValues: false,
+ promoteLongs: false,
+ promoteBuffers: false,
+} as const;
+
+export class MongoConnector {
+ async findDocuments(config: MongoConfig, req: MongoFindRequest): Promise {
+ assertCollectionName(req.collection);
+ const pageSize = clampPageSize(req.pageSize);
+ const page = clampPage(req.page);
+ if (page > MAX_PAGE) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ `page ${page} exceeds the maximum of ${MAX_PAGE} (use sort by _id + range for deeper pagination)`,
+ );
+ }
+ if (
+ req.filter !== undefined &&
+ (typeof req.filter !== "object" || req.filter === null || Array.isArray(req.filter))
+ ) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", "filter must be an object");
+ }
+ const filter: EJSONDocument = req.filter ?? {};
+ assertSize(filter, MAX_FILTER_SIZE_BYTES, "filter");
+ if (req.filter) assertSafeExpressions(req.filter);
+ const sort = validateSort(req.sort);
+ const projection = validateProjection(req.projection);
+ const bsonFilter = serializeMongoFilter(filter);
+ const skip = Math.max(0, (page - 1) * pageSize);
+
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+
+ const nativeDocs = await withMongoTimeout(timeout, async (signal) => {
+ const options: FindOptions & { signal?: AbortSignal } = {
+ signal,
+ maxTimeMS: timeout,
+ ...PRESERVE_BSON_TYPES,
+ };
+ if (sort) options.sort = sort;
+ if (projection) options.projection = projection;
+ const cursor = coll.find(bsonFilter, options).skip(skip).limit(pageSize);
+ return (await cursor.toArray()) as unknown[];
+ });
+
+ const total = isEmptyObject(filter)
+ ? await coll.estimatedDocumentCount({ maxTimeMS: timeout })
+ : await coll.countDocuments(bsonFilter, { maxTimeMS: timeout });
+
+ if (config.cacheDocuments) {
+ const key = pageCacheKey(req.collection, filter, sort, projection, page, pageSize);
+ const cached = mongodbCache.getDocumentPage(config, key);
+ if (cached) return buildFindResult(req.collection, cached, total, page, pageSize);
+ }
+
+ const documents = nativeDocs.map((d) => mongoBSONtoEJSON(d) as EJSONDocument);
+
+ if (config.cacheDocuments) {
+ const key = pageCacheKey(req.collection, filter, sort, projection, page, pageSize);
+ mongodbCache.setDocumentPage(config, key, documents);
+ }
+
+ return buildFindResult(req.collection, documents, total, page, pageSize);
+ }
+
+ async insertDocument(config: MongoConfig, req: MongoInsertRequest): Promise {
+ assertMongoNotReadOnly(config, "insertDocument");
+ assertCollectionName(req.collection);
+ if (typeof req.document !== "object" || req.document === null || Array.isArray(req.document)) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "document must be an object");
+ }
+ assertSize(req.document, MAX_DOCUMENT_SIZE_BYTES, "document");
+ assertSafeExpressions(req.document);
+ const doc = serializeMongoEJSONDocument(req.document);
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+
+ const res = await withMongoTimeout(timeout, () => coll.insertOne(doc, { maxTimeMS: timeout }));
+
+ const insertedId = mongoBSONtoEJSON(res.insertedId);
+ const echoed = mongoBSONtoEJSON({ ...doc, _id: res.insertedId }) as EJSONDocument;
+ mongodbCache.clearCollectionCache(config, req.collection);
+ return { collection: req.collection, insertedId, document: echoed };
+ }
+
+ async updateDocument(config: MongoConfig, req: MongoUpdateRequest): Promise {
+ assertMongoNotReadOnly(config, "updateDocument");
+ assertCollectionName(req.collection);
+ assertNonEmptyFilter(req.filter);
+ assertOperatorDocument(req.update);
+ assertSafeExpressions(req.filter);
+ assertSafeExpressions(req.update);
+ const bsonFilter = serializeMongoFilter(req.filter);
+ const bsonUpdate = serializeMongoUpdateOperand(req.update);
+ const multi = req.options?.multi ?? false;
+ const returnDocument = req.options?.returnDocument ?? "after";
+ const upsert = req.options?.upsert ?? false;
+ const arrayFilters = req.options?.arrayFilters
+ ? req.options.arrayFilters.map((f) => serializeMongoFilter(f))
+ : undefined;
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+
+ const result = await withMongoTimeout(timeout, async (signal) => {
+ let updatedDocument: EJSONDocument | undefined;
+ if (returnDocument === "before") {
+ const before = await coll.findOne(bsonFilter, {
+ signal,
+ maxTimeMS: timeout,
+ ...PRESERVE_BSON_TYPES,
+ });
+ updatedDocument = before ? (mongoBSONtoEJSON(before) as EJSONDocument) : undefined;
+ }
+ const updateOptions = {
+ maxTimeMS: timeout,
+ upsert,
+ arrayFilters,
+ };
+ const r = multi
+ ? await coll.updateMany(bsonFilter, bsonUpdate, updateOptions)
+ : await coll.updateOne(bsonFilter, bsonUpdate, updateOptions);
+ if (returnDocument !== "before") {
+ // Best-effort per spec §7.2: if the follow-up read fails, omit
+ // updatedDocument but still return the driver counts.
+ try {
+ const after = await coll.findOne(bsonFilter, {
+ signal,
+ maxTimeMS: timeout,
+ ...PRESERVE_BSON_TYPES,
+ });
+ updatedDocument = after ? (mongoBSONtoEJSON(after) as EJSONDocument) : undefined;
+ } catch (readErr) {
+ logger.warn(
+ { collection: req.collection, err: readErr },
+ "mongo updateDocument follow-up read failed; returning counts only",
+ );
+ }
+ }
+ return { r, updatedDocument };
+ });
+
+ const upsertedRaw = result.r.upsertedId;
+ const upsertedId =
+ upsertedRaw && Object.keys(upsertedRaw).length > 0
+ ? (mongoBSONtoEJSON(Object.values(upsertedRaw)[0]) as EJsonValue)
+ : undefined;
+
+ mongodbCache.clearCollectionCache(config, req.collection);
+ return {
+ collection: req.collection,
+ matchedCount: result.r.matchedCount,
+ modifiedCount: result.r.modifiedCount,
+ upsertedId,
+ updatedDocument: result.updatedDocument,
+ };
+ }
+
+ async replaceDocument(
+ config: MongoConfig,
+ req: MongoReplaceRequest,
+ ): Promise {
+ assertMongoNotReadOnly(config, "replaceDocument");
+ assertCollectionName(req.collection);
+ assertNonEmptyFilter(req.filter);
+ if (
+ typeof req.replacement !== "object" ||
+ req.replacement === null ||
+ Array.isArray(req.replacement)
+ ) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "replacement document must be an object");
+ }
+ assertNoOperatorKeys(req.replacement);
+ assertSize(req.replacement, MAX_DOCUMENT_SIZE_BYTES, "replacement");
+ assertSafeExpressions(req.filter);
+ assertSafeExpressions(req.replacement);
+
+ if (req.replacement._id !== undefined && req.filter._id !== undefined) {
+ if (canonicalJSON(req.replacement._id) !== canonicalJSON(req.filter._id)) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "Cannot change _id of a document");
+ }
+ }
+
+ const bsonFilter = serializeMongoFilter(req.filter);
+ const doc = serializeMongoEJSONDocument(req.replacement);
+ const upsert = req.options?.upsert ?? false;
+ const returnDocument = req.options?.returnDocument ?? "after";
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+
+ const result = await withMongoTimeout(timeout, async (signal) => {
+ let updatedDocument: EJSONDocument | undefined;
+ if (returnDocument === "before") {
+ const before = await coll.findOne(bsonFilter, {
+ signal,
+ maxTimeMS: timeout,
+ ...PRESERVE_BSON_TYPES,
+ });
+ updatedDocument = before ? (mongoBSONtoEJSON(before) as EJSONDocument) : undefined;
+ }
+ const replaceOptions = {
+ maxTimeMS: timeout,
+ upsert,
+ };
+ const r = await coll.replaceOne(bsonFilter, doc, replaceOptions);
+ if (returnDocument !== "before") {
+ try {
+ const after = await coll.findOne(bsonFilter, {
+ signal,
+ maxTimeMS: timeout,
+ ...PRESERVE_BSON_TYPES,
+ });
+ updatedDocument = after ? (mongoBSONtoEJSON(after) as EJSONDocument) : undefined;
+ } catch (readErr) {
+ logger.warn(
+ { collection: req.collection, err: readErr },
+ "mongo replaceDocument follow-up read failed; returning counts only",
+ );
+ }
+ }
+ return { r, updatedDocument };
+ });
+
+ const upsertedRaw = result.r.upsertedId;
+ const upsertedId =
+ upsertedRaw && Object.keys(upsertedRaw).length > 0
+ ? (mongoBSONtoEJSON(Object.values(upsertedRaw)[0]) as EJsonValue)
+ : upsertedRaw
+ ? (mongoBSONtoEJSON(upsertedRaw) as EJsonValue)
+ : undefined;
+
+ mongodbCache.clearCollectionCache(config, req.collection);
+ return {
+ collection: req.collection,
+ matchedCount: result.r.matchedCount,
+ modifiedCount: result.r.modifiedCount,
+ upsertedId,
+ updatedDocument: result.updatedDocument,
+ };
+ }
+
+ async deleteDocument(config: MongoConfig, req: MongoDeleteRequest): Promise {
+ assertMongoNotReadOnly(config, "deleteDocument");
+ assertCollectionName(req.collection);
+ assertNonEmptyFilter(req.filter);
+ assertSafeExpressions(req.filter);
+ const bsonFilter = serializeMongoFilter(req.filter);
+ const multi = req.options?.multi ?? false;
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+
+ const res = await withMongoTimeout(timeout, () =>
+ multi
+ ? coll.deleteMany(bsonFilter, { maxTimeMS: timeout })
+ : coll.deleteOne(bsonFilter, { maxTimeMS: timeout }),
+ );
+
+ logger.debug(
+ { collection: req.collection, deletedCount: res.deletedCount },
+ "mongo deleteDocument",
+ );
+ mongodbCache.clearCollectionCache(config, req.collection);
+ return { collection: req.collection, deletedCount: res.deletedCount };
+ }
+
+ async runAggregation(
+ config: MongoConfig,
+ req: MongoAggregationRequest,
+ ): Promise {
+ assertCollectionName(req.collection);
+ assertReadOnlyPipeline(req.pipeline);
+ if (req.pipeline) {
+ for (const stage of req.pipeline) {
+ assertSafeExpressions(stage);
+ }
+ }
+ const stages = (req.pipeline || []).map((stage) => serializeMongoPipelineStage(stage));
+ const timeout = clampMqlTimeout(req.options?.maxTimeMS, 10000, 60000);
+ const allowDiskUse =
+ typeof req.options?.allowDiskUse === "boolean" ? req.options.allowDiskUse : false;
+ const coll = selectCollection(config, req.collection);
+
+ const started = Date.now();
+ const nativeDocs: Document[] = [];
+ await withMongoTimeout(timeout, async (signal) => {
+ const options: AggregateOptions & { signal?: AbortSignal } = {
+ signal,
+ maxTimeMS: timeout,
+ allowDiskUse,
+ ...PRESERVE_BSON_TYPES,
+ };
+ if (
+ typeof req.options?.batchSize === "number" &&
+ Number.isInteger(req.options.batchSize) &&
+ req.options.batchSize > 0
+ ) {
+ options.batchSize = req.options.batchSize;
+ }
+ const cursor = coll.aggregate(stages, options);
+ try {
+ for await (const doc of cursor) {
+ nativeDocs.push(doc);
+ if (nativeDocs.length > MAX_AGG_RESULTS) {
+ throw new MongoApiError(
+ "MONGO_LIMIT_EXCEEDED",
+ `aggregation returned more than ${MAX_AGG_RESULTS} documents (max ${MAX_AGG_RESULTS}); add a $limit stage`,
+ );
+ }
+ }
+ } finally {
+ await cursor.close().catch(() => {});
+ }
+ });
+
+ const documents = nativeDocs.map((d) => mongoBSONtoEJSON(d) as EJSONDocument);
+ return {
+ collection: req.collection,
+ documents,
+ stageCount: stages.length,
+ executionTimeMs: Date.now() - started,
+ };
+ }
+
+ async executeMql(
+ config: MongoConfig,
+ req: MongoMqlExecuteRequest,
+ context?: MongoExecutionContext,
+ ): Promise {
+ return executeMql(config, req, context);
+ }
+
+ async explainMql(
+ config: MongoConfig,
+ req: MongoExplainRequest,
+ context?: MongoExecutionContext,
+ ): Promise {
+ return explainMql(config, req, context);
+ }
+
+ async listCollections(config: MongoConfig): Promise {
+ return listCollections(config);
+ }
+
+ async inferCollectionSchema(
+ config: MongoConfig,
+ req: MongoInferSchemaRequest,
+ ): Promise {
+ assertCollectionName(req.collection);
+ const sampleSize = clampInferSampleSize(req.sampleSize);
+ const maxDepth = clampInferMaxDepth(req.maxDepth);
+
+ const cached = mongodbCache.getInferredSchema(config, req.collection, sampleSize, maxDepth);
+ if (cached) {
+ return cached;
+ }
+
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+
+ const nativeDocs = (await withMongoTimeout(timeout, (signal) =>
+ coll
+ .find({}, { signal, maxTimeMS: timeout, limit: sampleSize, ...PRESERVE_BSON_TYPES })
+ .toArray(),
+ )) as Array>;
+
+ const actualSampleSize = nativeDocs.length;
+ const acc = new FieldAccumulator(actualSampleSize, maxDepth);
+ for (const doc of nativeDocs) {
+ acc.ingest(doc, "", 0);
+ }
+ const fields = acc.toFields();
+
+ let totalDocs = 0;
+ try {
+ totalDocs = await coll.estimatedDocumentCount({ maxTimeMS: timeout });
+ } catch {
+ try {
+ totalDocs = await coll.countDocuments({}, { maxTimeMS: timeout });
+ } catch {
+ totalDocs = actualSampleSize;
+ }
+ }
+
+ const sampleDocuments = nativeDocs
+ .slice(0, 5)
+ .map((d) => serializeMongoDocument(d as Document));
+
+ const schema: MongoCollectionSchema = {
+ collection: req.collection,
+ sampleSize: actualSampleSize,
+ totalDocs,
+ inferredAt: new Date().toISOString(),
+ fieldCount: fields.length,
+ nestedFieldCount: fields.filter((f) => f.depth > 0).length,
+ arrayFieldCount: fields.filter((f) => f.isArray).length,
+ fields,
+ sampleDocuments,
+ };
+
+ if (config.cacheDocuments !== false) {
+ mongodbCache.setInferredSchema(config, req.collection, sampleSize, maxDepth, schema);
+ }
+
+ return schema;
+ }
+
+ async createCollection(
+ config: MongoConfig,
+ req: MongoCreateCollectionRequest,
+ ): Promise {
+ assertMongoNotReadOnly(config, "createCollection");
+ assertNewCollectionName(req.collection);
+ if (req.options?.capped) {
+ const { size, max } = req.options;
+ if (typeof size !== "number" || !Number.isInteger(size) || size < 4096) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "Capped collection size must be an integer >= 4096 bytes",
+ );
+ }
+ if (max !== undefined && (typeof max !== "number" || !Number.isInteger(max) || max <= 0)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "Capped collection max must be a positive integer",
+ );
+ }
+ }
+ const db = selectDb(config);
+ const timeout = clampTimeout();
+ await withMongoTimeout(timeout, () => db.createCollection(req.collection, req.options as any));
+ mongodbCache.flushConnection(config);
+ return { ok: true, collection: req.collection };
+ }
+
+ async dropCollection(
+ config: MongoConfig,
+ req: MongoDropCollectionRequest,
+ ): Promise {
+ assertMongoNotReadOnly(config, "dropCollection");
+ if (typeof req.collection === "string" && req.collection.startsWith("system.")) {
+ throw new MongoApiError("MONGO_FORBIDDEN", "Cannot drop system collection");
+ }
+ assertCollectionName(req.collection);
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+ let dropped: boolean = true;
+ try {
+ dropped = await withMongoTimeout(timeout, () => coll.drop());
+ } catch (err: any) {
+ if (err?.codeName === "NamespaceNotFound" || err?.code === 26) {
+ throw new MongoApiError("MONGO_NOT_FOUND", `Collection '${req.collection}' does not exist`);
+ }
+ throw err;
+ }
+ if (dropped === false) {
+ throw new MongoApiError("MONGO_NOT_FOUND", `Collection '${req.collection}' does not exist`);
+ }
+ mongodbCache.clearCollectionCache(config, req.collection);
+ mongodbCache.flushConnection(config);
+ return { ok: true, collection: req.collection };
+ }
+
+ // ===========================================================================
+ // M6 — Secondary Index Management (docs/MONGODB_M6_SPEC.md §3, §9)
+ // ===========================================================================
+
+ async listIndexes(
+ config: MongoConfig,
+ req: MongoIndexListRequest,
+ ): Promise {
+ assertCollectionName(req.collection);
+ const coll = selectCollection(config, req.collection);
+ const db = selectDb(config);
+ const timeout = clampTimeout();
+
+ let rawIndexes: any[] = [];
+ try {
+ rawIndexes = await withMongoTimeout(timeout, () =>
+ coll.listIndexes({ maxTimeMS: timeout }).toArray(),
+ );
+ } catch (err: any) {
+ if (err?.codeName === "NamespaceNotFound" || err?.code === 26) {
+ return {
+ collection: req.collection,
+ indexes: [],
+ totalSizeBytes: 0,
+ };
+ }
+ throw err;
+ }
+
+ let indexSizes: Record = {};
+ let totalSizeBytes = 0;
+ try {
+ const stats = await withMongoTimeout(timeout, () =>
+ db.command({ collStats: req.collection }),
+ );
+ if (stats?.indexSizes && typeof stats.indexSizes === "object") {
+ indexSizes = stats.indexSizes;
+ }
+ if (typeof stats?.totalIndexSize === "number") {
+ totalSizeBytes = stats.totalIndexSize;
+ }
+ } catch {
+ // collStats is best-effort (e.g. Atlas / views / permissions)
+ }
+
+ if (totalSizeBytes === 0 && Object.keys(indexSizes).length > 0) {
+ totalSizeBytes = Object.values(indexSizes).reduce(
+ (sum, sz) => sum + (typeof sz === "number" ? sz : 0),
+ 0,
+ );
+ }
+
+ let defaultCollation: MongoIndexCollation | null = null;
+ let collectionCollationEstablished = false;
+ try {
+ const collInfos = await withMongoTimeout(timeout, () =>
+ db.listCollections({ name: req.collection }, { maxTimeMS: timeout }).toArray(),
+ );
+ if (collInfos.length > 0) {
+ collectionCollationEstablished = true;
+ defaultCollation = (collInfos[0] as any)?.options?.collation || null;
+ }
+ } catch {
+ // Best-effort: if listCollections fails, collectionCollationEstablished remains false
+ }
+
+ const indexDetailsList: MongoIndexDetails[] = rawIndexes.map((raw) => {
+ const isIdIndex = raw.name === "_id_";
+ const sizeBytes = typeof indexSizes[raw.name] === "number" ? indexSizes[raw.name] : 0;
+ return {
+ name: raw.name,
+ key: raw.key,
+ sizeBytes,
+ unique: raw.unique ?? (isIdIndex ? true : false),
+ sparse: raw.sparse ?? false,
+ isIdIndex,
+ expireAfterSeconds: raw.expireAfterSeconds,
+ partialFilterExpression: raw.partialFilterExpression
+ ? (mongoBSONtoEJSON(raw.partialFilterExpression) as EJSONDocument)
+ : undefined,
+ collation: raw.collation,
+ hidden: raw.hidden,
+ v: raw.v,
+ textIndexVersion: raw.textIndexVersion,
+ weights: raw.weights,
+ default_language: raw.default_language,
+ language_override: raw.language_override,
+ };
+ });
+
+ const evaluatedIndexes = evaluateIndexRedundancy(indexDetailsList, {
+ collectionDefaultCollation: defaultCollation,
+ collectionCollationUnknown: !collectionCollationEstablished,
+ });
+
+ return {
+ collection: req.collection,
+ indexes: evaluatedIndexes,
+ totalSizeBytes,
+ };
+ }
+
+ async createIndex(
+ config: MongoConfig,
+ req: MongoIndexCreateRequest,
+ options?: { readOnly?: boolean },
+ ): Promise {
+ assertMongoNotReadOnly(config, "createIndexes");
+ if (options?.readOnly) {
+ throw new MongoApiError(
+ "MONGO_READ_ONLY",
+ "Database is configured as read-only. 'createIndexes' is prohibited.",
+ );
+ }
+ assertCollectionName(req.collection);
+ if (typeof req.key !== "object" || req.key === null || Array.isArray(req.key)) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "key must be an object");
+ }
+ const keyEntries = Object.entries(req.key);
+ if (keyEntries.length === 0) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "key must contain at least one field");
+ }
+ const VALID_DIRECTIONS = new Set([1, -1, "text", "2dsphere", "hashed"]);
+ for (const [field, dir] of keyEntries) {
+ if (typeof field !== "string" || !field.trim()) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "key field name must be a non-empty string",
+ );
+ }
+ if (!VALID_DIRECTIONS.has(dir as any)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ `invalid direction for field '${field}': ${dir}`,
+ );
+ }
+ }
+
+ // Special index combination validation
+ const textFields = keyEntries.filter(([_, dir]) => dir === "text");
+ const geoFields = keyEntries.filter(([_, dir]) => dir === "2dsphere");
+ const hashedFields = keyEntries.filter(([_, dir]) => dir === "hashed");
+
+ if (textFields.length > 0 && (geoFields.length > 0 || hashedFields.length > 0)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "Cannot combine text index with 2dsphere or hashed keys",
+ );
+ }
+ if (geoFields.length > 0 && hashedFields.length > 0) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "Cannot combine 2dsphere index with hashed keys",
+ );
+ }
+ if (hashedFields.length > 1) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "A compound index cannot contain more than one hashed key",
+ );
+ }
+ if (textFields.length > 0 && req.options?.unique) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "Text indexes cannot enforce unique constraints",
+ );
+ }
+
+ if (req.options?.expireAfterSeconds !== undefined) {
+ if (
+ typeof req.options.expireAfterSeconds !== "number" ||
+ req.options.expireAfterSeconds < 0 ||
+ !Number.isFinite(req.options.expireAfterSeconds)
+ ) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "expireAfterSeconds must be a non-negative number",
+ );
+ }
+ if (keyEntries.length > 1) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "TTL index (expireAfterSeconds) can only be created on a single field",
+ );
+ }
+ if (keyEntries[0][0] === "_id") {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "Cannot create TTL index on immutable primary key '_id'",
+ );
+ }
+ if (textFields.length > 0 || geoFields.length > 0 || hashedFields.length > 0) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "TTL index cannot be created on special non-B-tree key types",
+ );
+ }
+ }
+
+ if (req.options?.name !== undefined) {
+ if (typeof req.options.name !== "string" || !req.options.name.trim()) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "index name must be a non-empty string");
+ }
+ }
+
+ if (req.options?.partialFilterExpression !== undefined) {
+ if (
+ typeof req.options.partialFilterExpression !== "object" ||
+ req.options.partialFilterExpression === null ||
+ Array.isArray(req.options.partialFilterExpression)
+ ) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "partialFilterExpression must be a non-null object",
+ );
+ }
+ assertSafeExpressions(req.options.partialFilterExpression);
+ assertSize(
+ req.options.partialFilterExpression,
+ MAX_FILTER_SIZE_BYTES,
+ "partialFilterExpression",
+ );
+ }
+
+ if (req.options?.collation !== undefined) {
+ if (
+ typeof req.options.collation !== "object" ||
+ req.options.collation === null ||
+ Array.isArray(req.options.collation)
+ ) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "collation must be a non-null object");
+ }
+ if (
+ typeof req.options.collation.locale !== "string" ||
+ !req.options.collation.locale.trim()
+ ) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collation.locale must be a non-empty string",
+ );
+ }
+ if (req.options.collation.strength !== undefined) {
+ const s = req.options.collation.strength;
+ if (![1, 2, 3, 4, 5].includes(s)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collation.strength must be an integer between 1 and 5",
+ );
+ }
+ }
+ if (req.options.collation.caseFirst !== undefined) {
+ if (!["upper", "lower", "off"].includes(req.options.collation.caseFirst)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collation.caseFirst must be 'upper', 'lower', or 'off'",
+ );
+ }
+ }
+ if (req.options.collation.alternate !== undefined) {
+ if (!["non-ignorable", "shifted"].includes(req.options.collation.alternate)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collation.alternate must be 'non-ignorable' or 'shifted'",
+ );
+ }
+ }
+ if (req.options.collation.maxVariable !== undefined) {
+ if (!["punct", "space"].includes(req.options.collation.maxVariable)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "collation.maxVariable must be 'punct' or 'space'",
+ );
+ }
+ }
+ }
+
+ const driverOptions: CreateIndexesOptions = {};
+ if (req.options?.name) driverOptions.name = req.options.name;
+ if (typeof req.options?.unique === "boolean") driverOptions.unique = req.options.unique;
+ if (typeof req.options?.sparse === "boolean") driverOptions.sparse = req.options.sparse;
+ if (typeof req.options?.expireAfterSeconds === "number") {
+ driverOptions.expireAfterSeconds = req.options.expireAfterSeconds;
+ }
+ if (req.options?.partialFilterExpression) {
+ driverOptions.partialFilterExpression = serializeMongoFilter(
+ req.options.partialFilterExpression,
+ );
+ }
+ if (req.options?.collation) driverOptions.collation = req.options.collation;
+ if (typeof req.options?.hidden === "boolean") driverOptions.hidden = req.options.hidden;
+ if (typeof req.options?.background === "boolean") {
+ (driverOptions as any).background = req.options.background;
+ }
+
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+ const started = Date.now();
+
+ let indexName: string;
+ try {
+ indexName = await withMongoTimeout(timeout, () =>
+ coll.createIndex(req.key as any, driverOptions),
+ );
+ } catch (err: any) {
+ if (
+ req.options?.hidden &&
+ (err?.codeName === "InvalidOptions" ||
+ err?.code === 72 ||
+ (typeof err?.message === "string" &&
+ (err.message.includes("hidden") ||
+ err.message.includes("unrecognized option") ||
+ err.message.includes("unknown option"))))
+ ) {
+ throw new MongoApiError(
+ "MONGO_UNSUPPORTED_OPERATION",
+ "Hidden indexes require MongoDB 4.4 or higher",
+ );
+ }
+ throw err;
+ }
+
+ mongodbCache.clearCollectionCache(config, req.collection);
+ mongodbCache.flushConnection(config);
+
+ return {
+ success: true,
+ indexName,
+ executionTimeMs: Date.now() - started,
+ };
+ }
+
+ async createIndexes(
+ config: MongoConfig,
+ req: MongoIndexCreateRequest,
+ options?: { readOnly?: boolean },
+ ): Promise {
+ return this.createIndex(config, req, options);
+ }
+
+ async dropIndex(
+ config: MongoConfig,
+ req: MongoIndexDropRequest,
+ options?: { readOnly?: boolean },
+ ): Promise {
+ assertMongoNotReadOnly(config, "dropIndex");
+ if (options?.readOnly) {
+ throw new MongoApiError(
+ "MONGO_READ_ONLY",
+ "Database is configured as read-only. 'dropIndex' is prohibited.",
+ );
+ }
+ assertCollectionName(req.collection);
+ if (typeof req.indexName !== "string" || !req.indexName.trim()) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "indexName must be a non-empty string");
+ }
+ if (req.indexName === "_id_" || req.indexName === "*") {
+ throw new MongoApiError(
+ "MONGO_FORBIDDEN",
+ req.indexName === "_id_"
+ ? "Cannot drop immutable default primary key index '_id_'"
+ : "Wildcard index drop '*' is forbidden",
+ );
+ }
+
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+ const started = Date.now();
+
+ try {
+ await withMongoTimeout(timeout, () => coll.dropIndex(req.indexName, { maxTimeMS: timeout }));
+ } catch (err: any) {
+ if (err?.codeName === "IndexNotFound" || err?.code === 27) {
+ throw new MongoApiError("MONGO_NOT_FOUND", `Index '${req.indexName}' not found`);
+ }
+ throw err;
+ }
+
+ mongodbCache.clearCollectionCache(config, req.collection);
+ mongodbCache.flushConnection(config);
+
+ return {
+ success: true,
+ droppedIndexName: req.indexName,
+ executionTimeMs: Date.now() - started,
+ };
+ }
+
+ async getIndexStats(
+ config: MongoConfig,
+ req: MongoIndexStatsRequest,
+ ): Promise {
+ assertCollectionName(req.collection);
+ const coll = selectCollection(config, req.collection);
+ const timeout = clampTimeout();
+
+ let nativeDocs: any[] = [];
+ try {
+ nativeDocs = await withMongoTimeout(timeout, () =>
+ coll.aggregate([{ $indexStats: {} }], { maxTimeMS: timeout }).toArray(),
+ );
+ } catch (err: any) {
+ if (err?.codeName === "NamespaceNotFound" || err?.code === 26) {
+ return {
+ collection: req.collection,
+ stats: {},
+ };
+ }
+ throw err;
+ }
+
+ const stats: Record = {};
+ for (const doc of nativeDocs) {
+ const name = doc.name;
+ if (!name) continue;
+ const ops =
+ typeof doc.accesses?.ops === "number" ? doc.accesses.ops : Number(doc.accesses?.ops || 0);
+ const since =
+ doc.accesses?.since instanceof Date
+ ? doc.accesses.since.toISOString()
+ : String(doc.accesses?.since || new Date().toISOString());
+
+ stats[name] = {
+ name,
+ key: doc.key,
+ ops,
+ since,
+ host: doc.host,
+ };
+ }
+
+ return {
+ collection: req.collection,
+ stats,
+ };
+ }
+
+ async hideIndex(
+ config: MongoConfig,
+ req: MongoIndexHideRequest,
+ options?: { readOnly?: boolean },
+ ): Promise {
+ assertMongoNotReadOnly(config, "hideIndex");
+ if (options?.readOnly) {
+ throw new MongoApiError(
+ "MONGO_READ_ONLY",
+ "Database is configured as read-only. 'hideIndex' is prohibited.",
+ );
+ }
+ assertCollectionName(req.collection);
+ if (typeof req.indexName !== "string" || !req.indexName.trim()) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "indexName must be a non-empty string");
+ }
+ if (req.indexName === "_id_") {
+ throw new MongoApiError("MONGO_FORBIDDEN", "Cannot hide default primary key index '_id_'");
+ }
+ if (typeof req.hidden !== "boolean") {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "hidden must be a boolean");
+ }
+
+ const db = selectDb(config);
+ const timeout = clampTimeout();
+
+ try {
+ await withMongoTimeout(timeout, () =>
+ db.command({
+ collMod: req.collection,
+ index: {
+ name: req.indexName,
+ hidden: req.hidden,
+ },
+ }),
+ );
+ } catch (err: any) {
+ if (err?.codeName === "IndexNotFound" || err?.code === 27) {
+ throw new MongoApiError("MONGO_NOT_FOUND", `Index '${req.indexName}' not found`);
+ }
+ if (
+ err?.codeName === "InvalidOptions" ||
+ err?.code === 72 ||
+ (typeof err?.message === "string" &&
+ (err.message.includes("no option found to collMod") ||
+ err.message.includes("unrecognized option") ||
+ err.message.includes("unknown option") ||
+ err.message.includes("index option not supported")))
+ ) {
+ throw new MongoApiError(
+ "MONGO_UNSUPPORTED_OPERATION",
+ "Hiding indexes requires MongoDB 4.4 or higher",
+ );
+ }
+ throw err;
+ }
+
+ mongodbCache.clearCollectionCache(config, req.collection);
+ mongodbCache.flushConnection(config);
+
+ return {
+ success: true,
+ indexName: req.indexName,
+ hidden: req.hidden,
+ };
+ }
+}
+
+/**
+ * Canonical comparison of collation specs.
+ * Missing collation, empty collation, or { locale: "simple" } represents default binary collation.
+ */
+function areCollationsEquivalent(
+ a?: MongoIndexCollation | null,
+ b?: MongoIndexCollation | null,
+): boolean {
+ const isSimpleA = !a || !a.locale || a.locale === "simple";
+ const isSimpleB = !b || !b.locale || b.locale === "simple";
+ if (isSimpleA && isSimpleB) return true;
+ if (isSimpleA !== isSimpleB) return false;
+
+ const nonNullA = a!;
+ const nonNullB = b!;
+ return (
+ nonNullA.locale === nonNullB.locale &&
+ (nonNullA.strength ?? 3) === (nonNullB.strength ?? 3) &&
+ Boolean(nonNullA.caseLevel) === Boolean(nonNullB.caseLevel) &&
+ (nonNullA.caseFirst ?? "off") === (nonNullB.caseFirst ?? "off") &&
+ Boolean(nonNullA.numericOrdering) === Boolean(nonNullB.numericOrdering) &&
+ (nonNullA.alternate ?? "non-ignorable") === (nonNullB.alternate ?? "non-ignorable") &&
+ (nonNullA.maxVariable ?? "punct") === (nonNullB.maxVariable ?? "punct") &&
+ Boolean(nonNullA.backwards) === Boolean(nonNullB.backwards)
+ );
+}
+
+/**
+ * Resolves effective collation for an index, accounting for collection-level defaults.
+ * Returns "UNKNOWN" if collection metadata is missing/unavailable and the index lacks explicit collation.
+ */
+function getEffectiveCollation(
+ idx: MongoIndexDetails,
+ collectionDefault?: MongoIndexCollation | null,
+ collectionCollationUnknown?: boolean,
+): MongoIndexCollation | null | "UNKNOWN" {
+ if (idx.collation) {
+ return idx.collation;
+ }
+ if (collectionCollationUnknown) {
+ return "UNKNOWN";
+ }
+ if (collectionDefault) {
+ return collectionDefault;
+ }
+ return { locale: "simple" };
+}
+
+/**
+ * Canonical comparison of partial filter expressions.
+ * Recursively sorts object keys for deterministic structural equality.
+ */
+function areFiltersEquivalent(a?: Record, b?: Record): boolean {
+ if (!a && !b) return true;
+ if (!a || !b) return false;
+
+ const normalize = (obj: any): any => {
+ if (obj === null || typeof obj !== "object") return obj;
+ if (Array.isArray(obj)) return obj.map(normalize);
+ const sortedKeys = Object.keys(obj).sort();
+ const result: Record = {};
+ for (const key of sortedKeys) {
+ result[key] = normalize(obj[key]);
+ }
+ return result;
+ };
+
+ return JSON.stringify(normalize(a)) === JSON.stringify(normalize(b));
+}
+
+export interface EvaluateRedundancyOptions {
+ collectionDefaultCollation?: MongoIndexCollation | null;
+ collectionCollationUnknown?: boolean;
+}
+
+/**
+ * Multi-dimensional redundant index detection (docs/MONGODB_M6_SPEC.md §9).
+ * Evaluates prefix matching, directional alignment (forward & reverse traversal),
+ * unique/sparse/partialFilter/collation/hidden dimensions.
+ */
+export function evaluateIndexRedundancy(
+ indexes: MongoIndexDetails[],
+ options?: EvaluateRedundancyOptions,
+): MongoIndexDetails[] {
+ return indexes.map((target) => {
+ // 1. Primary key index is never redundant
+ if (target.isIdIndex || target.name === "_id_") {
+ return { ...target, isRedundant: false };
+ }
+
+ // 2. Special non-B-tree index types (text, 2dsphere, hashed) on target are never covered by B-tree prefixes
+ const targetValues = Object.values(target.key);
+ if (
+ targetValues.some((v) => typeof v === "string" && ["text", "2dsphere", "hashed"].includes(v))
+ ) {
+ return { ...target, isRedundant: false };
+ }
+
+ const targetKeyEntries = Object.entries(target.key);
+
+ for (const other of indexes) {
+ if (other.name === target.name) continue;
+
+ // 3. Hidden indexes cannot be used by query planner; cannot make anything redundant
+ if (other.hidden) continue;
+
+ // 4. If other contains ANY special non-B-tree key (text, 2dsphere, hashed),
+ // it cannot safely cover a standard B-tree index (different execution plans & query restrictions)
+ const otherValues = Object.values(other.key);
+ if (
+ otherValues.some((v) => typeof v === "string" && ["text", "2dsphere", "hashed"].includes(v))
+ ) {
+ continue;
+ }
+
+ const otherKeyEntries = Object.entries(other.key);
+
+ // 5. Must be a strict prefix (fewer keys)
+ if (targetKeyEntries.length >= otherKeyEntries.length) continue;
+
+ // 6. Prefix match & direction consistency (supporting both forward and reverse traversal):
+ // Single-field prefix: B-tree can be traversed forward or backward for 1 or -1
+ // Multi-field prefix: all keys must match in sequence, and directions must be
+ // either ALL identical (forward) OR ALL inverted (reverse traversal).
+ let isPrefix = false;
+ if (targetKeyEntries.length === 1) {
+ isPrefix =
+ targetKeyEntries[0][0] === otherKeyEntries[0][0] &&
+ typeof otherKeyEntries[0][1] === "number";
+ } else {
+ const keysMatch = targetKeyEntries.every(
+ ([key], idx) => otherKeyEntries[idx] && otherKeyEntries[idx][0] === key,
+ );
+ if (keysMatch) {
+ const allIdentical = targetKeyEntries.every(
+ ([_, dir], idx) => otherKeyEntries[idx][1] === dir,
+ );
+ const allInverted = targetKeyEntries.every(
+ ([_, dir], idx) =>
+ typeof dir === "number" &&
+ typeof otherKeyEntries[idx][1] === "number" &&
+ (otherKeyEntries[idx][1] as number) === -1 * (dir as number),
+ );
+ isPrefix = allIdentical || allInverted;
+ }
+ }
+ if (!isPrefix) continue;
+
+ // 7. Unique Constraint Dimension:
+ // A unique target index is NEVER redundant with a compound index (must keep unique constraint).
+ // Furthermore, a unique compound index does NOT provide equivalent semantics to a non-unique
+ // shorter index (different constraint semantics, array/multikey restrictions, and distinct lifecycle).
+ if (target.unique || other.unique) continue;
+
+ // 8. Sparsity Dimension:
+ // A non-sparse target index cannot be covered by a sparse index (sparse omits docs).
+ if (!target.sparse && other.sparse) continue;
+
+ // 9. Partial Filter Expression Dimension:
+ // Both must have identical partial filter expressions (or neither).
+ if (!areFiltersEquivalent(target.partialFilterExpression, other.partialFilterExpression)) {
+ continue;
+ }
+
+ // 10. Collation Dimension:
+ // Establish effective collation taking collection defaults into account.
+ // If effective collation cannot be established, prefer suppressing redundancy over an unsafe recommendation.
+ const targetEffective = getEffectiveCollation(
+ target,
+ options?.collectionDefaultCollation,
+ options?.collectionCollationUnknown,
+ );
+ const otherEffective = getEffectiveCollation(
+ other,
+ options?.collectionDefaultCollation,
+ options?.collectionCollationUnknown,
+ );
+
+ if (targetEffective === "UNKNOWN" || otherEffective === "UNKNOWN") {
+ continue;
+ }
+
+ if (!areCollationsEquivalent(targetEffective, otherEffective)) {
+ continue;
+ }
+
+ // If all checks pass, target is genuinely redundant
+ return {
+ ...target,
+ isRedundant: true,
+ redundantReason: `Prefix is completely covered by compound index "${other.name}". Drops write overhead without sacrificing query plan optimality.`,
+ };
+ }
+
+ return { ...target, isRedundant: false };
+ });
+}
+
+export const mongoConnector = new MongoConnector();
+
+// ===========================================================================
+// Stage 8 Phase 3 — Cursor Close Helper with 2000ms Bound
+// ===========================================================================
+
+export async function initiateCursorClose(cursor: any): Promise {
+ const startedAt = Date.now();
+ if (!cursor || typeof cursor.close !== "function") {
+ return { status: "closed_confirmed", durationMs: 0 };
+ }
+ let timer: NodeJS.Timeout | undefined;
+ try {
+ const timeoutPromise = new Promise((_, reject) => {
+ timer = setTimeout(() => reject(new Error("Cursor close timeout")), 2000);
+ });
+ await Promise.race([cursor.close(), timeoutPromise]);
+ return { status: "closed_confirmed", durationMs: Date.now() - startedAt };
+ } catch (err: any) {
+ if (err?.message === "Cursor close timeout") {
+ return { status: "closed_timed_out", durationMs: Date.now() - startedAt };
+ }
+ return { status: "closed_failed", error: err, durationMs: Date.now() - startedAt };
+ } finally {
+ if (timer) clearTimeout(timer);
+ }
+}
+
+// ===========================================================================
+// M5 — MQL Query Workspace & Read-Only Engine (docs/MONGODB_M5_SPEC.md §3, §5)
+// ===========================================================================
+
+export async function executeMql(
+ config: MongoConfig,
+ req: MongoMqlExecuteRequest,
+ context?: MongoExecutionContext,
+): Promise {
+ // Gate 0: Entry check
+ context?.signal?.throwIfAborted();
+
+ const op = req?.op;
+ const opName = (op as any)?.operation;
+
+ if (!opName || !WHITELIST_READ_OPS.has(opName)) {
+ throw new MongoApiError(
+ "MONGO_FORBIDDEN_OPERATION",
+ `Operation '${opName || "unknown"}' is forbidden in read-only query workspace. Use RelWave document mutation actions.`,
+ );
+ }
+
+ assertCollectionName(req.collection);
+ // Gate 1: Pre-collection selection check
+ context?.signal?.throwIfAborted();
+ const coll = selectCollection(config, req.collection);
+ const started = Date.now();
+
+ switch (op.operation) {
+ case "find": {
+ const payload: MongoFindOpPayload = op.payload ?? { filter: {} };
+ if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "find payload must be an object");
+ }
+ if (
+ payload.filter !== undefined &&
+ (typeof payload.filter !== "object" ||
+ payload.filter === null ||
+ Array.isArray(payload.filter))
+ ) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", "filter must be an object");
+ }
+ const filter: EJSONDocument = payload.filter ?? {};
+ assertSafeExpressions(filter);
+ assertSize(filter, MAX_FILTER_SIZE_BYTES, "filter");
+
+ const sort = validateSort(payload.sort);
+ const projection = validateProjection(payload.projection);
+
+ if (payload.skip !== undefined) {
+ if (
+ typeof payload.skip !== "number" ||
+ !Number.isFinite(payload.skip) ||
+ !Number.isInteger(payload.skip) ||
+ payload.skip < 0
+ ) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "skip must be a non-negative integer");
+ }
+ }
+
+ let limit = DEFAULT_PAGE_SIZE;
+ if (typeof payload.limit === "number" && Number.isFinite(payload.limit)) {
+ const floored = Math.floor(payload.limit);
+ if (floored >= 1) {
+ limit = Math.min(floored, MAX_PAGE_SIZE);
+ }
+ }
+
+ const timeout = clampMqlTimeout(req.options?.maxTimeMS, 5000, 60000);
+
+ // Gate 2: Pre-serialization check
+ context?.signal?.throwIfAborted();
+ const bsonFilter = serializeMongoFilter(filter);
+
+ // Gate 3: Pre-driver invocation check
+ context?.signal?.throwIfAborted();
+
+ const nativeDocs = await withMongoTimeout(timeout, (signal) => {
+ signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+
+ const options: FindOptions & { signal?: AbortSignal } = {
+ signal,
+ maxTimeMS: timeout,
+ limit,
+ ...PRESERVE_BSON_TYPES,
+ };
+ if (sort) options.sort = sort;
+ if (projection) options.projection = projection;
+ if (payload.skip !== undefined) options.skip = payload.skip;
+
+ const cursor = coll.find(bsonFilter, options);
+
+ // Gate 4: Cursor creation check
+ if (signal.aborted || context?.signal?.aborted) {
+ initiateCursorClose(cursor);
+ if (signal.aborted) signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+ }
+
+ context?.onCursorCreated?.(cursor);
+
+ const driverPromise = cursor.toArray();
+ context?.onDriverPromiseCreated?.(driverPromise);
+
+ return driverPromise;
+ });
+
+ const documents = nativeDocs.map((d) => mongoBSONtoEJSON(d) as EJSONDocument);
+ return {
+ operation: "find",
+ collection: req.collection,
+ documents,
+ totalReturned: documents.length,
+ executionTimeMs: Date.now() - started,
+ };
+ }
+
+ case "aggregate": {
+ const payload: MongoAggregateOpPayload = op.payload;
+ if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "aggregate payload must be an object");
+ }
+ assertReadOnlyPipeline(payload.pipeline);
+ const stages = (payload.pipeline || []).map((stage) => serializeMongoPipelineStage(stage));
+ const timeout = clampMqlTimeout(req.options?.maxTimeMS, 10000, 60000);
+ const allowDiskUse = typeof payload.allowDiskUse === "boolean" ? payload.allowDiskUse : false;
+
+ // Gate 3: Pre-driver invocation check
+ context?.signal?.throwIfAborted();
+
+ const nativeDocs: Document[] = [];
+ await withMongoTimeout(timeout, async (signal) => {
+ signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+
+ const options: AggregateOptions & { signal?: AbortSignal } = {
+ signal,
+ maxTimeMS: timeout,
+ allowDiskUse,
+ ...PRESERVE_BSON_TYPES,
+ };
+ if (
+ typeof payload.batchSize === "number" &&
+ Number.isInteger(payload.batchSize) &&
+ payload.batchSize > 0
+ ) {
+ options.batchSize = payload.batchSize;
+ }
+ const cursor = coll.aggregate(stages, options);
+
+ if (signal.aborted || context?.signal?.aborted) {
+ initiateCursorClose(cursor);
+ if (signal.aborted) signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+ }
+
+ context?.onCursorCreated?.(cursor);
+
+ try {
+ const streamPromise = (async () => {
+ for await (const doc of cursor) {
+ signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+ nativeDocs.push(doc);
+ if (nativeDocs.length > MAX_AGG_RESULTS) {
+ throw new MongoApiError(
+ "MONGO_LIMIT_EXCEEDED",
+ `aggregation returned more than ${MAX_AGG_RESULTS} documents (max ${MAX_AGG_RESULTS}); add a $limit stage`,
+ );
+ }
+ }
+ })();
+ context?.onDriverPromiseCreated?.(streamPromise);
+ await streamPromise;
+ } finally {
+ await initiateCursorClose(cursor);
+ }
+ });
+
+ const documents = nativeDocs.map((d) => mongoBSONtoEJSON(d) as EJSONDocument);
+ return {
+ operation: "aggregate",
+ collection: req.collection,
+ documents,
+ stageCount: stages.length,
+ executionTimeMs: Date.now() - started,
+ };
+ }
+
+ case "countDocuments": {
+ const payload: MongoCountOpPayload = op.payload ?? {};
+ if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "countDocuments payload must be an object",
+ );
+ }
+ if (
+ payload.filter !== undefined &&
+ (typeof payload.filter !== "object" ||
+ payload.filter === null ||
+ Array.isArray(payload.filter))
+ ) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", "filter must be an object");
+ }
+ const filter: EJSONDocument = payload.filter ?? {};
+ assertSafeExpressions(filter);
+ assertSize(filter, MAX_FILTER_SIZE_BYTES, "filter");
+
+ if (payload.skip !== undefined) {
+ if (
+ typeof payload.skip !== "number" ||
+ !Number.isFinite(payload.skip) ||
+ !Number.isInteger(payload.skip) ||
+ payload.skip < 0
+ ) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "skip must be a non-negative integer");
+ }
+ }
+
+ if (payload.limit !== undefined) {
+ if (
+ typeof payload.limit !== "number" ||
+ !Number.isFinite(payload.limit) ||
+ !Number.isInteger(payload.limit) ||
+ payload.limit < 0
+ ) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "limit must be a non-negative integer");
+ }
+ }
+
+ const timeout = clampMqlTimeout(req.options?.maxTimeMS, 5000, 60000);
+
+ // Gate 2: Pre-serialization check
+ context?.signal?.throwIfAborted();
+ const bsonFilter = serializeMongoFilter(filter);
+
+ // Gate 3: Pre-driver invocation check
+ context?.signal?.throwIfAborted();
+
+ const count = await withMongoTimeout(timeout, (signal) => {
+ signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+
+ const options: { maxTimeMS?: number; signal?: AbortSignal; skip?: number; limit?: number } =
+ {
+ maxTimeMS: timeout,
+ signal,
+ };
+ if (payload.skip !== undefined) options.skip = payload.skip;
+ if (payload.limit !== undefined) options.limit = payload.limit;
+
+ const p = coll.countDocuments(bsonFilter, options);
+ context?.onDriverPromiseCreated?.(p);
+ return p;
+ });
+
+ return {
+ operation: "countDocuments",
+ collection: req.collection,
+ count,
+ executionTimeMs: Date.now() - started,
+ };
+ }
+
+ case "estimatedDocumentCount": {
+ if (
+ op.payload !== undefined &&
+ (typeof op.payload !== "object" ||
+ op.payload === null ||
+ Array.isArray(op.payload) ||
+ Object.keys(op.payload).length > 0)
+ ) {
+ throw new MongoApiError(
+ "MONGO_VALIDATION_ERROR",
+ "estimatedDocumentCount does not accept a filter; payload must be empty or undefined. Use countDocuments for filtered counts.",
+ );
+ }
+ const timeout = clampMqlTimeout(req.options?.maxTimeMS, 5000, 60000);
+
+ // Gate 3: Pre-driver invocation check
+ context?.signal?.throwIfAborted();
+
+ const count = await withMongoTimeout(timeout, (signal) => {
+ signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+
+ const p = coll.estimatedDocumentCount({ maxTimeMS: timeout, signal } as any);
+ context?.onDriverPromiseCreated?.(p);
+ return p;
+ });
+
+ return {
+ operation: "estimatedDocumentCount",
+ collection: req.collection,
+ count,
+ executionTimeMs: Date.now() - started,
+ };
+ }
+
+ case "distinct": {
+ const payload: MongoDistinctOpPayload = op.payload;
+ if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "distinct payload must be an object");
+ }
+ if (typeof payload.field !== "string" || payload.field.trim().length === 0) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "field must be a non-empty string");
+ }
+ if (
+ payload.filter !== undefined &&
+ (typeof payload.filter !== "object" ||
+ payload.filter === null ||
+ Array.isArray(payload.filter))
+ ) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", "filter must be an object");
+ }
+ const filter: EJSONDocument = payload.filter ?? {};
+ assertSafeExpressions(filter);
+ assertSize(filter, MAX_FILTER_SIZE_BYTES, "filter");
+
+ const timeout = clampMqlTimeout(req.options?.maxTimeMS, 5000, 60000);
+
+ // Gate 2: Pre-serialization check
+ context?.signal?.throwIfAborted();
+ const bsonFilter = serializeMongoFilter(filter);
+
+ // Gate 3: Pre-driver invocation check
+ context?.signal?.throwIfAborted();
+
+ let rawValues = await withMongoTimeout(timeout, (signal) => {
+ signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+
+ const p = coll.distinct(payload.field, bsonFilter, { maxTimeMS: timeout, signal } as any);
+ context?.onDriverPromiseCreated?.(p);
+ return p;
+ });
+
+ if (rawValues.length > MAX_DISTINCT_VALUES) {
+ rawValues = rawValues.slice(0, MAX_DISTINCT_VALUES);
+ }
+
+ const values = rawValues.map((v) => mongoBSONtoEJSON(v) as EJsonValue);
+ return {
+ operation: "distinct",
+ collection: req.collection,
+ field: payload.field,
+ values,
+ count: values.length,
+ executionTimeMs: Date.now() - started,
+ };
+ }
+ }
+}
+
+export async function explainMql(
+ config: MongoConfig,
+ req: MongoExplainRequest,
+ context?: MongoExecutionContext,
+): Promise {
+ context?.signal?.throwIfAborted();
+ const target = req?.target;
+ const op = (target as any)?.operation;
+
+ if (op !== "find" && op !== "aggregate") {
+ throw new MongoApiError(
+ "MONGO_FORBIDDEN_OPERATION",
+ "Explain is only supported for 'find' and 'aggregate' operations",
+ );
+ }
+
+ assertCollectionName(req.collection);
+ context?.signal?.throwIfAborted();
+ const coll = selectCollection(config, req.collection);
+
+ const verbosity = req.verbosity || "queryPlanner";
+ if (!["queryPlanner", "executionStats", "allPlansExecution"].includes(verbosity)) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", `Invalid explain verbosity '${verbosity}'`);
+ }
+
+ const defaultTimeout =
+ verbosity === "queryPlanner" ? 5000 : verbosity === "executionStats" ? 10000 : 15000;
+ const timeout = clampMqlTimeout(req.options?.maxTimeMS, defaultTimeout, 60000);
+ const started = Date.now();
+
+ let raw: any;
+ if (target.operation === "find") {
+ if (
+ target.filter !== undefined &&
+ (typeof target.filter !== "object" || target.filter === null || Array.isArray(target.filter))
+ ) {
+ throw new MongoApiError("MONGO_INVALID_FILTER", "filter must be an object");
+ }
+ const filter: EJSONDocument = target.filter ?? {};
+ assertSafeExpressions(filter);
+ assertSize(filter, MAX_FILTER_SIZE_BYTES, "filter");
+
+ const sort = validateSort(target.sort);
+ const projection = validateProjection(target.projection);
+
+ if (target.skip !== undefined) {
+ if (
+ typeof target.skip !== "number" ||
+ !Number.isFinite(target.skip) ||
+ !Number.isInteger(target.skip) ||
+ target.skip < 0
+ ) {
+ throw new MongoApiError("MONGO_VALIDATION_ERROR", "skip must be a non-negative integer");
+ }
+ }
+
+ context?.signal?.throwIfAborted();
+ const bsonFilter = serializeMongoFilter(filter);
+ const cursor = coll.find(bsonFilter, { maxTimeMS: timeout, ...PRESERVE_BSON_TYPES });
+ if (sort) cursor.sort(sort);
+ if (projection) cursor.project(projection);
+ if (target.skip !== undefined) cursor.skip(target.skip);
+ if (typeof target.limit === "number" && Number.isFinite(target.limit)) {
+ const floored = Math.floor(target.limit);
+ if (floored >= 1) cursor.limit(Math.min(floored, MAX_PAGE_SIZE));
+ }
+
+ context?.onCursorCreated?.(cursor);
+ raw = await withMongoTimeout(timeout, (signal) => {
+ signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+ const p = cursor.explain(verbosity);
+ context?.onDriverPromiseCreated?.(p);
+ return p;
+ });
+ } else {
+ // aggregate
+ assertReadOnlyPipeline(target.pipeline);
+ const stages = (target.pipeline || []).map((stage) => serializeMongoPipelineStage(stage));
+ context?.signal?.throwIfAborted();
+ const cursor = coll.aggregate(stages, {
+ maxTimeMS: timeout,
+ allowDiskUse: target.allowDiskUse ?? false,
+ ...PRESERVE_BSON_TYPES,
+ });
+
+ context?.onCursorCreated?.(cursor);
+ raw = await withMongoTimeout(timeout, (signal) => {
+ signal.throwIfAborted();
+ context?.signal?.throwIfAborted();
+ const p = cursor.explain(verbosity);
+ context?.onDriverPromiseCreated?.(p);
+ return p;
+ });
+ }
+
+ const rawObj = (raw || {}) as Record;
+ const queryPlanner = rawObj.queryPlanner || {
+ plannerVersion: 1,
+ namespace: `${config.database || ""}.${req.collection}`,
+ indexFilterSet: false,
+ winningPlan: rawObj.stages ? { stages: rawObj.stages } : rawObj.winningPlan || {},
+ };
+
+ const executionStats = rawObj.executionStats
+ ? {
+ executionSuccess: rawObj.executionStats.executionSuccess ?? true,
+ nReturned: rawObj.executionStats.nReturned ?? 0,
+ executionTimeMillis: rawObj.executionStats.executionTimeMillis ?? 0,
+ totalKeysExamined: rawObj.executionStats.totalKeysExamined ?? 0,
+ totalDocsExamined: rawObj.executionStats.totalDocsExamined ?? 0,
+ executionStages: rawObj.executionStats.executionStages || {},
+ allPlansExecution: rawObj.executionStats.allPlansExecution,
+ }
+ : undefined;
+
+ const serverInfo = rawObj.serverInfo
+ ? {
+ host: rawObj.serverInfo.host,
+ port: rawObj.serverInfo.port,
+ version: rawObj.serverInfo.version,
+ }
+ : undefined;
+
+ return {
+ collection: req.collection,
+ operation: target.operation,
+ queryPlanner,
+ executionStats,
+ serverInfo,
+ rawExplain: (mongoBSONtoEJSON(raw) as Record) || {},
+ executionTimeMs: Date.now() - started,
+ };
+}
diff --git a/bridge/src/connectors/mongoBson.ts b/bridge/src/connectors/mongoBson.ts
new file mode 100644
index 00000000..f1b251a4
--- /dev/null
+++ b/bridge/src/connectors/mongoBson.ts
@@ -0,0 +1,593 @@
+/**
+ * BSON-to-wire serializer for MongoDB documents.
+ *
+ * Converts a driver document into a lossless, JSON-safe `SerializedMongoDocument`
+ * that can travel over the newline-delimited JSON-RPC stdio channel. ObjectId,
+ * Decimal128, Long, Timestamp, Binary, and `undefined` are not JSON-representable
+ * and are mapped to MongoDB Extended JSON forms; plain primitives pass through.
+ *
+ * Type detection is by BSON `_bsontype` (stable across driver/bson versions) plus
+ * `instanceof Date` / `Buffer.isBuffer`, so this module is pure and unit-testable
+ * without a live driver. No value it returns fails `JSON.stringify`.
+ */
+
+import { ObjectId, Int32, Long, Decimal128, Binary, Timestamp } from "mongodb";
+import type { Document } from "mongodb";
+import type {
+ SerializedMongoDocument,
+ MongoWireValue,
+ MongoWireObject,
+ MongoWireBinary,
+ EJsonValue,
+ EJSONDocument,
+ MongoBsonType,
+} from "../types/mongo";
+
+type WithBsontype = { _bsontype?: string };
+
+/** Minimal structural views so we never touch `any`. */
+interface ObjectIdLike {
+ _bsontype: "ObjectId";
+ toHexString(): string;
+}
+interface Decimal128Like {
+ _bsontype: "Decimal128";
+ toString(): string;
+}
+interface LongLike {
+ _bsontype: "Long";
+ toString(): string;
+}
+interface TimestampLike {
+ _bsontype: "Timestamp";
+ t: number;
+ i: number;
+}
+interface IntLike {
+ _bsontype: "Int32" | "Double";
+ valueOf(): number;
+}
+interface BinaryLike {
+ _bsontype: "Binary";
+ buffer: Uint8Array;
+ sub_type?: number;
+}
+
+function toFiniteNumber(n: number): number | null {
+ return Number.isFinite(n) ? n : null;
+}
+
+function serializeBinary(value: BinaryLike): MongoWireBinary {
+ const buf = Buffer.isBuffer(value.buffer) ? value.buffer : Buffer.from(value.buffer);
+ const subtype = typeof value.sub_type === "number" ? value.sub_type : 0;
+ return {
+ $binary: {
+ base64: buf.toString("base64"),
+ subtype: subtype.toString(16).padStart(2, "0"),
+ },
+ };
+}
+
+/**
+ * Serialize a single BSON value into a JSON-safe wire value. Arrays and nested
+ * documents recurse.
+ */
+export function serializeMongoValue(value: unknown): MongoWireValue {
+ if (value === null) return null;
+
+ const kind = typeof value;
+ if (kind === "string" || kind === "boolean") {
+ return value as MongoWireValue;
+ }
+ if (kind === "number") {
+ return toFiniteNumber(value as number) as MongoWireValue;
+ }
+ if (kind === "undefined") {
+ return { $undefined: true };
+ }
+ if (Array.isArray(value)) {
+ return value.map((item) => serializeMongoValue(item));
+ }
+
+ const bsontype = (value as WithBsontype)._bsontype;
+ if (bsontype) {
+ switch (bsontype) {
+ case "ObjectId":
+ return { $oid: (value as ObjectIdLike).toHexString() };
+ case "Decimal128":
+ return { $numberDecimal: (value as Decimal128Like).toString() };
+ case "Long":
+ return { $numberLong: (value as LongLike).toString() };
+ case "Timestamp": {
+ const ts = value as TimestampLike;
+ return { $timestamp: { t: ts.t | 0, i: ts.i | 0 } };
+ }
+ case "Int32":
+ case "Double":
+ return toFiniteNumber((value as IntLike).valueOf()) as MongoWireValue;
+ case "Binary":
+ return serializeBinary(value as BinaryLike);
+ default:
+ // Unknown BSON subtype (e.g. DBRef) falls through to object serialization.
+ break;
+ }
+ }
+
+ if (value instanceof Date) {
+ return { $date: value.toISOString() };
+ }
+ if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+ return serializeBinary({ _bsontype: "Binary", buffer: value, sub_type: 0 });
+ }
+
+ if (kind === "object") {
+ const out: MongoWireObject = {};
+ for (const [key, item] of Object.entries(value as Record)) {
+ if (key === "_bsontype") continue;
+ out[key] = serializeMongoValue(item);
+ }
+ return out;
+ }
+
+ // functions / symbols / bigint are not representable on the wire.
+ return null;
+}
+
+/**
+ * Serialize a whole document. Own enumerable keys are serialized; the internal
+ * `_bsontype` marker is dropped.
+ */
+export function serializeMongoDocument(doc: Document): SerializedMongoDocument {
+ const out: SerializedMongoDocument = {};
+ for (const [key, item] of Object.entries(doc as Record)) {
+ if (key === "_bsontype") continue;
+ out[key] = serializeMongoValue(item);
+ }
+ return out;
+}
+
+// ===========================================================================
+// M3 — BSON Type Inference helpers (pure, docs/MONGODB_M3_SPEC.md §4.2)
+// ===========================================================================
+
+/**
+ * Determine the canonical BSON type of a value without requiring a live driver.
+ * Never throws; unknown BSON types fall back to "object".
+ */
+export function bsonTypeOf(value: unknown): MongoBsonType {
+ if (value === null) return "null";
+ if (value === undefined) return "undefined";
+
+ const kind = typeof value;
+ if (kind === "string") return "string";
+ if (kind === "boolean") return "bool";
+ if (kind === "number") return "number";
+
+ if (Array.isArray(value)) return "array";
+
+ const bsontype = (value as WithBsontype)?._bsontype;
+ if (bsontype) {
+ switch (bsontype) {
+ case "ObjectId":
+ return "objectId";
+ case "Int32":
+ case "Double":
+ return "number";
+ case "Long":
+ return "long";
+ case "Decimal128":
+ return "decimal";
+ case "Timestamp":
+ return "timestamp";
+ case "Binary":
+ return "binary";
+ default:
+ break;
+ }
+ }
+
+ if (value instanceof Date) return "date";
+ if (Buffer.isBuffer(value) || value instanceof Uint8Array) return "binary";
+
+ if (kind === "object") return "object";
+
+ return "object";
+}
+
+/**
+ * Determine the numeric kind ("int" | "double") for numeric values.
+ */
+export function bsonNumericKind(value: unknown): "int" | "double" | undefined {
+ const bsontype = (value as WithBsontype)?._bsontype;
+ if (bsontype === "Int32") return "int";
+ if (bsontype === "Double") return "double";
+ if (typeof value === "number") {
+ return Number.isInteger(value) ? "int" : "double";
+ }
+ return undefined;
+}
+
+// ===========================================================================
+// M2 — Extended JSON (EJSON) <-> driver-native conversion.
+//
+// serializeMongoValue/serializeMongoDocument above go driver-native -> wire/EJSON
+// using the driver's wire shapes for the JSON-RPC response channel. The M2
+// document engine needs the canonical EJSON v2 round-trip in BOTH directions
+// (docs/MONGODB_M2_SPEC.md §4.3): mongoEJSONtoBSON parses request inputs;
+// mongoBSONtoEJSON renders results so that mongoBSONtoEJSON(mongoEJSONtoBSON(x))
+// is structurally equal to x for the supported type set. Pure and unit-testable.
+// ===========================================================================
+
+const EJSON_WRAPPER_KEYS = new Set([
+ "$oid",
+ "$date",
+ "$numberInt",
+ "$numberLong",
+ "$numberDouble",
+ "$numberDecimal",
+ "$binary",
+ "$regex",
+ "$timestamp",
+ "$undefined",
+]);
+
+function isPlainRecord(value: unknown): value is Record {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** True when `value` is an EJSON object with exactly one known wrapper key. */
+function isEJSONWrapper(value: unknown): value is Record {
+ if (!isPlainRecord(value)) return false;
+ const keys = Object.keys(value);
+ return keys.length === 1 && EJSON_WRAPPER_KEYS.has(keys[0]);
+}
+
+/**
+ * Validates and normalizes BSON binary subtype.
+ * Subtype must be an integer between 0 and 255 (numeric or 1-2 character hex string).
+ */
+export function validateAndParseSubtype(rawSubtype: unknown): number {
+ if (typeof rawSubtype === "number") {
+ if (!Number.isSafeInteger(rawSubtype) || rawSubtype < 0 || rawSubtype > 255) {
+ throw new TypeError(
+ `Invalid EJSON $binary: subtype must be a safe integer between 0 and 255, received ${rawSubtype}`,
+ );
+ }
+ return rawSubtype;
+ }
+
+ if (typeof rawSubtype === "string") {
+ if (!/^(?:0x)?[0-9a-fA-F]{1,2}$/i.test(rawSubtype)) {
+ throw new TypeError(
+ `Invalid EJSON $binary: subtype must be a valid 1-2 digit hexadecimal string (0x00-0xFF), received '${rawSubtype}'`,
+ );
+ }
+ const cleanHex =
+ rawSubtype.startsWith("0x") || rawSubtype.startsWith("0X") ? rawSubtype.slice(2) : rawSubtype;
+ const val = parseInt(cleanHex, 16);
+ if (!Number.isSafeInteger(val) || val < 0 || val > 255) {
+ throw new TypeError(
+ `Invalid EJSON $binary: subtype must be between 0 and 255, received '${rawSubtype}'`,
+ );
+ }
+ return val;
+ }
+
+ throw new TypeError(
+ `Invalid EJSON $binary: subtype must be a number or hexadecimal string, received ${typeof rawSubtype}`,
+ );
+}
+
+/**
+ * Validates structural RFC 4648 Base64 syntax before decoding, and canonical
+ * post-decoding re-encoding (ensuring unused pad bits in the final quantum are zero).
+ */
+export function validateAndDecodeBase64(rawBase64: unknown): Buffer {
+ if (typeof rawBase64 !== "string") {
+ throw new TypeError(
+ `Invalid EJSON $binary: base64 payload must be a string, received ${typeof rawBase64}`,
+ );
+ }
+
+ if (rawBase64 === "") {
+ return Buffer.alloc(0);
+ }
+
+ // Reject truncated base64 (modulo 4 cannot be 1 in RFC 4648)
+ if (rawBase64.length % 4 === 1) {
+ throw new TypeError(
+ `Invalid EJSON $binary: invalid base64 length (${rawBase64.length}), modulo 4 cannot be 1`,
+ );
+ }
+
+ let paddedStr: string;
+
+ if (rawBase64.includes("=")) {
+ // Padded base64 must have total length divisible by 4
+ if (rawBase64.length % 4 !== 0) {
+ throw new TypeError(
+ `Invalid EJSON $binary: padded base64 length (${rawBase64.length}) must be a multiple of 4`,
+ );
+ }
+ // Must match valid padded base64 structure: blocks of 4 chars ending with == (preceded by 2 chars) or = (preceded by 3 chars)
+ const PADDED_BASE64_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)$/;
+ if (!PADDED_BASE64_REGEX.test(rawBase64)) {
+ throw new TypeError(
+ `Invalid EJSON $binary: invalid base64 padding or characters in '${rawBase64}'`,
+ );
+ }
+ paddedStr = rawBase64;
+ } else {
+ // Unpadded base64: characters must be strictly RFC 4648 alphabet without padding
+ if (!/^[A-Za-z0-9+/]+$/.test(rawBase64)) {
+ throw new TypeError(
+ `Invalid EJSON $binary: invalid characters in unpadded base64 '${rawBase64}'`,
+ );
+ }
+ const remainder = rawBase64.length % 4;
+ if (remainder === 2) {
+ paddedStr = rawBase64 + "==";
+ } else if (remainder === 3) {
+ paddedStr = rawBase64 + "=";
+ } else {
+ paddedStr = rawBase64;
+ }
+ }
+
+ const buf = Buffer.from(paddedStr, "base64");
+
+ // Canonical re-encoding validation post-decoding (unused pad bits must be zero)
+ if (buf.toString("base64") !== paddedStr) {
+ throw new TypeError(
+ "Invalid EJSON $binary: non-canonical base64 encoding (unused pad bits must be zero)",
+ );
+ }
+
+ return buf;
+}
+
+/**
+ * Recursively convert an EJSON value to driver-native BSON types. Resolves the
+ * EJSON v2 wrappers; plain JSON passes through; a bare 24-hex string stays a
+ * string (only $oid yields an ObjectId — spec §4.2 / D-M2-6); unknown $-wrappers
+ * are returned unchanged for the driver to handle.
+ */
+export function mongoEJSONtoBSON(doc: EJSONDocument): Record;
+export function mongoEJSONtoBSON(value: EJsonValue): unknown;
+export function mongoEJSONtoBSON(value: EJsonValue): unknown {
+ if (value === null || value === undefined) return value;
+
+ const kind = typeof value;
+ if (kind === "string" || kind === "boolean") {
+ return value;
+ }
+ if (kind === "number") {
+ return value;
+ }
+ if (Array.isArray(value)) {
+ return value.map((item) => mongoEJSONtoBSON(item));
+ }
+ if (kind === "bigint") {
+ return (value as unknown as bigint).toString();
+ }
+
+ if (isEJSONWrapper(value)) {
+ const key = Object.keys(value)[0];
+ const v = value as Record;
+ switch (key) {
+ case "$oid":
+ return new ObjectId(v["$oid"] as string);
+ case "$date": {
+ const d = v["$date"];
+ if (isPlainRecord(d) && typeof d["$numberLong"] === "string") {
+ return new Date(Long.fromString(d["$numberLong"]).toNumber());
+ }
+ return new Date(d as string);
+ }
+ case "$numberInt":
+ return new Int32(Number(v["$numberInt"]));
+ case "$numberLong":
+ return Long.fromString(v["$numberLong"] as string);
+ case "$numberDouble":
+ return Number(v["$numberDouble"] as string);
+ case "$numberDecimal":
+ return new Decimal128(v["$numberDecimal"] as string);
+ case "$binary": {
+ const b = v["$binary"];
+ if (typeof b === "string") {
+ const buf = validateAndDecodeBase64(b);
+ return new Binary(buf, 0);
+ }
+
+ if (isPlainRecord(b)) {
+ const base64Candidates: { key: string; val: unknown }[] = [];
+ if ("base64" in b && b.base64 !== undefined) {
+ base64Candidates.push({ key: "base64", val: b.base64 });
+ }
+ if ("$base64" in b && b.$base64 !== undefined) {
+ base64Candidates.push({ key: "$base64", val: b.$base64 });
+ }
+
+ if (base64Candidates.length === 0) {
+ throw new TypeError("Invalid EJSON $binary: missing base64 data");
+ }
+
+ // Validate EVERY defined candidate independently (a valid alias cannot conceal an invalid alias)
+ const decodedBuffers: Buffer[] = [];
+ for (const cand of base64Candidates) {
+ decodedBuffers.push(validateAndDecodeBase64(cand.val));
+ }
+
+ if (
+ base64Candidates.length === 2 &&
+ base64Candidates[0].val !== base64Candidates[1].val
+ ) {
+ throw new TypeError("Invalid EJSON $binary: conflicting base64 payload properties");
+ }
+
+ const selectedBuffer = decodedBuffers[0];
+
+ // Subtype candidates: subtype, subType, $type, sub_type
+ const subtypeCandidates: { key: string; val: unknown }[] = [];
+ for (const key of ["subtype", "subType", "$type", "sub_type"] as const) {
+ if (key in b && b[key] !== undefined) {
+ subtypeCandidates.push({ key, val: b[key] });
+ }
+ }
+
+ let selectedSubtype = 0;
+ if (subtypeCandidates.length > 0) {
+ const parsedSubtypes: number[] = [];
+ for (const cand of subtypeCandidates) {
+ parsedSubtypes.push(validateAndParseSubtype(cand.val));
+ }
+
+ const firstSubtype = parsedSubtypes[0];
+ for (let i = 1; i < parsedSubtypes.length; i++) {
+ if (parsedSubtypes[i] !== firstSubtype) {
+ throw new TypeError(
+ "Invalid EJSON $binary: conflicting subtype payload properties",
+ );
+ }
+ }
+ selectedSubtype = firstSubtype;
+ }
+
+ return new Binary(selectedBuffer, selectedSubtype);
+ }
+
+ throw new TypeError("Invalid EJSON $binary: missing base64 data");
+ }
+ case "$regex":
+ return new RegExp(v["$regex"] as string, (v["$options"] as string) || "");
+ case "$timestamp": {
+ const t = v["$timestamp"] as { $t?: string; $i?: string };
+ return new Timestamp({ t: Number(t["$t"] || 0), i: Number(t["$i"] || 0) });
+ }
+ case "$undefined":
+ return undefined;
+ default:
+ return value; // unreachable: isEJSONWrapper matched a known key
+ }
+ }
+
+ if (kind === "object") {
+ const out: Record = {};
+ for (const [k, item] of Object.entries(value as unknown as Record)) {
+ out[k] = mongoEJSONtoBSON(item as EJsonValue);
+ }
+ return out;
+ }
+ return value;
+}
+
+/**
+ * Convert a driver-native value to canonical EJSON v2 for the JSON-RPC response.
+ * Int32 -> $numberInt and Long -> $numberLong are preserved (so int types
+ * round-trip); Double -> plain JSON number (the accepted double normalization).
+ */
+export function mongoBSONtoEJSON(value: unknown): EJsonValue {
+ if (value === null || value === undefined) return null;
+
+ const kind = typeof value;
+ if (kind === "string" || kind === "boolean") {
+ return value as EJsonValue;
+ }
+ if (kind === "number") {
+ return toFiniteNumber(value as number) as EJsonValue;
+ }
+ if (kind === "bigint") {
+ return (value as bigint).toString() as EJsonValue;
+ }
+ if (Array.isArray(value)) {
+ return value.map((item) => mongoBSONtoEJSON(item));
+ }
+
+ if (value instanceof Date) {
+ return { $date: value.toISOString() };
+ }
+ if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+ const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);
+ return { $binary: { $type: "00", $base64: buf.toString("base64") } };
+ }
+
+ const bsontype = (value as WithBsontype)._bsontype;
+ if (bsontype) {
+ switch (bsontype) {
+ case "ObjectId":
+ return { $oid: (value as ObjectIdLike).toHexString() };
+ case "Decimal128":
+ return { $numberDecimal: (value as Decimal128Like).toString() };
+ case "Long":
+ return { $numberLong: (value as LongLike).toString() };
+ case "Timestamp": {
+ const ts = value as TimestampLike;
+ return { $timestamp: { $t: String(ts.t), $i: String(ts.i) } };
+ }
+ case "Int32":
+ return { $numberInt: String((value as IntLike).valueOf()) };
+ case "Double":
+ return toFiniteNumber((value as IntLike).valueOf()) as EJsonValue;
+ case "Binary": {
+ const b = value as BinaryLike;
+ const buf = Buffer.isBuffer(b.buffer) ? b.buffer : Buffer.from(b.buffer);
+ const subtype = typeof b.sub_type === "number" ? b.sub_type : 0;
+ return {
+ $binary: {
+ $type: subtype.toString(16).padStart(2, "0"),
+ $base64: buf.toString("base64"),
+ },
+ };
+ }
+ default:
+ break;
+ }
+ }
+
+ if (kind === "object") {
+ const out: EJSONDocument = {};
+ for (const [key, item] of Object.entries(value as Record)) {
+ if (key === "_bsontype") continue;
+ out[key] = mongoBSONtoEJSON(item);
+ }
+ return out;
+ }
+ return null;
+}
+
+/**
+ * Convert an insert document (EJSON) to driver-native form. Named distinctly
+ * from serializeMongoDocument (which goes the opposite direction) to avoid the
+ * name collision flagged during design.
+ */
+export function serializeMongoEJSONDocument(doc: EJSONDocument): Record {
+ return mongoEJSONtoBSON(doc);
+}
+
+/** Convert a query filter (EJSON) to driver-native form. */
+export function serializeMongoFilter(filter: EJSONDocument): Record {
+ return mongoEJSONtoBSON(filter);
+}
+
+/**
+ * Convert an update operator document (e.g. { $set: {...}, $inc: {...} }) to
+ * driver-native form. Operator KEYS are preserved verbatim; their leaf VALUES
+ * are resolved via mongoEJSONtoBSON. Never promotes a plain-field object to an
+ * operator document (the connector rejects those).
+ */
+export function serializeMongoUpdateOperand(update: EJSONDocument): Record {
+ const out: Record = {};
+ for (const [op, body] of Object.entries(update)) {
+ out[op] = mongoEJSONtoBSON(body as EJsonValue);
+ }
+ return out;
+}
+
+/**
+ * Convert one aggregation pipeline stage to driver-native form. Resolves EJSON
+ * wrappers but does NOT auto-$literal-wrap plain-object values — the caller is
+ * responsible for MQL expression structure (spec §5.6 / D-M2-4).
+ */
+export function serializeMongoPipelineStage(stage: EJSONDocument): Record {
+ return mongoEJSONtoBSON(stage);
+}
diff --git a/bridge/src/handlers/aiHandlers.ts b/bridge/src/handlers/aiHandlers.ts
index 65acd12b..219b1deb 100644
--- a/bridge/src/handlers/aiHandlers.ts
+++ b/bridge/src/handlers/aiHandlers.ts
@@ -20,7 +20,6 @@ import { buildSchemaAnalysisPrompt } from "../ai/prompts/schema-analysis";
import { buildQueryExplanationPrompt } from "../ai/prompts/query-explanation";
import { buildChartRecommendationPrompt } from "../ai/prompts/chart-recommendation";
import { parseChartRecommendation } from "../ai/prompts/chart-recommendation";
-import fs from "fs/promises";
import fsSync from "fs";
import { AI_SETTINGS_FILE, CONFIG_FOLDER, ensureDir } from "../utils/config";
diff --git a/bridge/src/handlers/databaseHandlers.ts b/bridge/src/handlers/databaseHandlers.ts
index 0fb13c02..c5676bdb 100644
--- a/bridge/src/handlers/databaseHandlers.ts
+++ b/bridge/src/handlers/databaseHandlers.ts
@@ -85,8 +85,9 @@ export class DatabaseHandlers {
});
}
- const { conn, dbType } = await this.dbService.getDatabaseConnection(dbId);
- const tables = await this.queryExecutor.listTables(conn, dbType, params.schema);
+ const tables = await this.dbService.withConnection(dbId, (conn, _db, dbType) =>
+ this.queryExecutor.listTables(conn, dbType, params.schema),
+ );
this.rpc.sendResponse(id, { ok: true, data: tables });
} catch (e: any) {
this.logger?.error({ e }, "db.listTables failed");
@@ -103,8 +104,9 @@ export class DatabaseHandlers {
message: "Missing id",
});
}
- const { conn, dbType } = await this.dbService.getDatabaseConnection(dbId);
- const schemas = await this.queryExecutor.listSchemaNames(conn, dbType);
+ const schemas = await this.dbService.withConnection(dbId, (conn, _db, dbType) =>
+ this.queryExecutor.listSchemaNames(conn, dbType),
+ );
this.rpc.sendResponse(id, { ok: true, data: schemas });
} catch (e: any) {
this.logger?.error({ e }, "db.listSchemas failed");
@@ -121,8 +123,9 @@ export class DatabaseHandlers {
message: "Missing id",
});
}
- const { conn, dbType } = await this.dbService.getDatabaseConnection(dbId);
- const dbSchema = await this.queryExecutor.listSchemas(conn, dbType);
+ const dbSchema = await this.dbService.withConnection(dbId, (conn, _db, dbType) =>
+ this.queryExecutor.listSchemas(conn, dbType),
+ );
this.rpc.sendResponse(id, { ok: true, data: dbSchema });
} catch (e: any) {
this.logger?.error({ e }, "db.getSchema failed");
@@ -171,13 +174,14 @@ export class DatabaseHandlers {
});
}
- let conn, dbType;
+ let result;
if (dbId) {
- const result = await this.dbService.getDatabaseConnection(dbId);
- conn = result.conn;
- dbType = result.dbType;
+ result = await this.dbService.withConnection(dbId, (conn, _db, dbType) =>
+ this.queryExecutor.testConnection(conn, dbType),
+ );
} else {
+ let dbType;
// Detect DB type from the raw connection object
if (connection.type?.toLowerCase().includes("mariadb")) {
dbType = "mariadb";
@@ -198,10 +202,10 @@ export class DatabaseHandlers {
connection.password ?? null,
dbType,
);
- conn = buildResult.config;
+ const conn = buildResult.config;
tunnelToClose = buildResult.tunnel;
+ result = await this.queryExecutor.testConnection(conn, dbType);
}
- const result = await this.queryExecutor.testConnection(conn, dbType);
this.rpc.sendResponse(id, { ok: true, data: result });
} catch (err: any) {
this.logger.error({ err }, "[Handler] testConnection error");
diff --git a/bridge/src/handlers/indexHandlers.ts b/bridge/src/handlers/indexHandlers.ts
new file mode 100644
index 00000000..2a996c0c
--- /dev/null
+++ b/bridge/src/handlers/indexHandlers.ts
@@ -0,0 +1,140 @@
+import { Logger } from "pino";
+import { Rpc } from "../types";
+import { DatabaseService } from "../services/databaseService";
+import { QueryExecutor } from "../services/queryExecutor";
+import { MongoApiError, mapMongoError } from "../connectors/mongo";
+
+export class IndexHandlers {
+ constructor(
+ private rpc: Rpc,
+ private logger: Logger,
+ private dbService: DatabaseService,
+ private queryExecutor: QueryExecutor,
+ ) {}
+
+ /** Map a MongoApiError (or driver error) to the stable error envelope. */
+ private sendMongoError(id: number | string, e: unknown): void {
+ const mapped =
+ e instanceof MongoApiError ? { code: e.code, message: e.message } : mapMongoError(e);
+ this.logger.error({ err: e, code: mapped.code }, "MongoDB index operation failed");
+ this.rpc.sendError(id, { code: mapped.code, message: mapped.message });
+ }
+
+ async handleListIndexes(params: any, id: number | string): Promise {
+ try {
+ const { dbId, collection } = params || {};
+ if (!dbId || !collection) {
+ return this.rpc.sendError(id, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId or collection",
+ });
+ }
+ const data = await this.dbService.withConnection(dbId, (conn, _db, dbType) =>
+ this.queryExecutor.listIndexes(conn, dbType, { collection }),
+ );
+ this.rpc.sendResponse(id, { ok: true, data });
+ } catch (e) {
+ this.sendMongoError(id, e);
+ }
+ }
+
+ async handleCreateIndex(params: any, id: number | string): Promise {
+ try {
+ const { dbId, collection, key, options } = params || {};
+ if (!dbId || !collection || !key) {
+ return this.rpc.sendError(id, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or key",
+ });
+ }
+ const data = await this.dbService.withConnection(dbId, (conn, db, dbType) => {
+ const readOnly = Boolean(
+ (db as any)?.readonly ||
+ (db as any)?.readOnly ||
+ (conn as any)?.readonly ||
+ (conn as any)?.readOnly,
+ );
+ return this.queryExecutor.createIndex(
+ conn,
+ dbType,
+ { collection, key, options },
+ { readOnly },
+ );
+ });
+ this.rpc.sendResponse(id, { ok: true, data });
+ } catch (e) {
+ this.sendMongoError(id, e);
+ }
+ }
+
+ async handleDropIndex(params: any, id: number | string): Promise {
+ try {
+ const { dbId, collection, indexName } = params || {};
+ if (!dbId || !collection || !indexName) {
+ return this.rpc.sendError(id, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId, collection, or indexName",
+ });
+ }
+ const data = await this.dbService.withConnection(dbId, (conn, db, dbType) => {
+ const readOnly = Boolean(
+ (db as any)?.readonly ||
+ (db as any)?.readOnly ||
+ (conn as any)?.readonly ||
+ (conn as any)?.readOnly,
+ );
+ return this.queryExecutor.dropIndex(conn, dbType, { collection, indexName }, { readOnly });
+ });
+ this.rpc.sendResponse(id, { ok: true, data });
+ } catch (e) {
+ this.sendMongoError(id, e);
+ }
+ }
+
+ async handleGetIndexStats(params: any, id: number | string): Promise {
+ try {
+ const { dbId, collection } = params || {};
+ if (!dbId || !collection) {
+ return this.rpc.sendError(id, {
+ code: "MONGO_VALIDATION_ERROR",
+ message: "Missing dbId or collection",
+ });
+ }
+ const data = await this.dbService.withConnection(dbId, (conn, _db, dbType) =>
+ this.queryExecutor.getIndexStats(conn, dbType, { collection }),
+ );
+ this.rpc.sendResponse(id, { ok: true, data });
+ } catch (e) {
+ this.sendMongoError(id, e);
+ }
+ }
+
+ async handleHideIndex(params: any, id: number | string): Promise |