feat(congodb): implement CongoDB MongoDB wire-protocol compatible in-memory server and APIs

2026-01-31 11:33:11 +00:00
parent a01f4d83c0
commit fcc5a0e557
37 changed files with 11020 additions and 2693 deletions
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -8,3 +8,82 @@
 - This works in both Node.js and Deno environments
 - **Why:** Deno wraps CommonJS exports in a `default` property, so default imports are required
 - Fixed in version 2.0.13 (changed from `import * as mongoPlugin`)
+
+## CongoDB - MongoDB Wire Protocol Server
+
+### Architecture
+CongoDB implements the MongoDB binary wire protocol (OP_MSG, OP_QUERY) allowing official MongoDB drivers to connect directly.
+
+```
+Official MongoClient  →  TCP (wire protocol)  →  CongoServer  →  Engines  →  Storage
+     (mongodb npm)           OP_MSG/BSON            (port)
+```
+
+### Module Structure
+```
+ts/congodb/
+├── server/                   # Wire protocol server
+│   ├── CongoServer.ts        # TCP server, connection handling
+│   ├── WireProtocol.ts       # OP_MSG/OP_QUERY parsing & encoding
+│   ├── CommandRouter.ts      # Route commands to handlers
+│   └── handlers/             # Command implementations
+│       ├── HelloHandler.ts   # hello/isMaster handshake
+│       ├── FindHandler.ts    # find, getMore, killCursors, count, distinct
+│       ├── InsertHandler.ts  # insert
+│       ├── UpdateHandler.ts  # update, findAndModify
+│       ├── DeleteHandler.ts  # delete
+│       ├── AggregateHandler.ts # aggregate
+│       ├── IndexHandler.ts   # createIndexes, dropIndexes, listIndexes
+│       └── AdminHandler.ts   # ping, listDatabases, listCollections, etc.
+│
+├── engine/                   # Core logic (reused)
+│   ├── QueryEngine.ts        # Query filtering with mingo
+│   ├── UpdateEngine.ts       # Update operations
+│   ├── AggregationEngine.ts  # Aggregation pipelines
+│   ├── IndexEngine.ts        # Index management
+│   └── TransactionEngine.ts  # Transaction support
+│
+├── storage/                  # Storage layer
+│   ├── IStorageAdapter.ts    # Interface
+│   ├── MemoryStorageAdapter.ts
+│   └── FileStorageAdapter.ts
+│
+└── types/interfaces.ts       # Type definitions
+```
+
+### Usage Example
+```typescript
+import { CongoServer } from '@push.rocks/smartmongo/congodb';
+import { MongoClient } from 'mongodb';
+
+// Start server
+const server = new CongoServer({ port: 27117 });
+await server.start();
+
+// Connect with official MongoDB driver
+const client = new MongoClient('mongodb://127.0.0.1:27117', {
+  directConnection: true
+});
+await client.connect();
+
+// Use like any MongoDB instance
+const db = client.db('mydb');
+await db.collection('users').insertOne({ name: 'John' });
+const user = await db.collection('users').findOne({ name: 'John' });
+
+// Cleanup
+await client.close();
+await server.stop();
+```
+
+### Supported Commands
+- **Handshake**: hello, isMaster
+- **CRUD**: find, insert, update, delete, findAndModify, getMore, killCursors
+- **Aggregation**: aggregate, count, distinct
+- **Indexes**: createIndexes, dropIndexes, listIndexes
+- **Admin**: ping, listDatabases, listCollections, drop, dropDatabase, create, serverStatus, buildInfo
+
+### Notes
+- The old CongoClient/CongoDb/CongoCollection classes have been removed
+- Use the official `mongodb` npm package's MongoClient instead
+- Server supports MongoDB wire protocol versions 0-21 (MongoDB 3.6 through 7.0 compatible)