// STRYKE-MONGO — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

stryke-mongo is one of the opt-in connector packages in the stryke ecosystem. MongoDB client for stryke. CRUD, aggregation, index admin against any MongoDB 5.0+ standalone, replica set, or sharded cluster. The official mongodb Rust driver ships as a Rust cdylib that stryke dlopens in-process on first use Mongo.

The official mongodb Rust crate pulls in tokio, rustls, a DNS resolver, and the BSON stack. Ships once as an opt-in package.

The public surface decomposes as: 71 direct FFI symbols (authoritative list in [ffi].exports of stryke.toml) plus 4 pure-stryke composites (find_stream, exists, find_value, collection_exists) built over the primitives. Of those, a large fraction are connection-free — URI/namespace parsing, 5 validators, 9 ObjectId helpers, and 13 query/filter builders that emit ready-to-use MongoDB documents with no client at all.

~ARCHITECTURE

In-process cdylib design: the stryke side is a thin .stk wrapper that calls FFI symbols on the dlopen'd library. No subprocess, no pipe — calls return on the same thread that made them.

$WHY OPT-IN (NOT BUILTIN)

The official mongodb Rust crate pulls in tokio, rustls, a DNS resolver, and the BSON stack. Ships once as an opt-in package.

The trade-off is intentional. The core stryke binary stays under ~40 MB precisely because each connector ships separately. Daily-driver work (one-liners, awk replacement, data scripting) doesn't need MongoDB drivers, AWS SDKs, or Spark Connect bindings linked in.

&FFI ENVELOPE

JSON in / JSON out across the FFI boundary. Each Mongo::* wrapper serializes its args to a JSON dict and calls the matching mongo__* symbol on the dlopen'd cdylib; the cdylib returns a JSON CString the wrapper parses. catch_unwind on every call converts panics to JSON errors. The returned CString is freed via the cdylib-exported stryke_free_cstring, wired automatically by rust_ffi::load_cdylib. BSON values round-trip via MongoDB relaxed extended JSON.

# request shape (built by the .stk wrapper)
{"<arg>": ...}

# response shape
{"result": ...}            # success — per-fn shape
{"error": "<msg>"}        # failure — wrapper die()s with the message

BSON values cross the boundary as MongoDB relaxed extended JSON, so non-JSON types round-trip cleanly: ObjectId as {"$oid": …}, DateTime as {"$date": …}, Decimal128 as {"$numberDecimal": …}, Binary as {"$binary": {base64, subType}}, Regex as {"$regularExpression": {pattern, options}}, Timestamp as {"$timestamp": {t, i}}. The same wrappers can be passed back through filters/updates and are re-parsed to real BSON before the wire.

@DEPENDENCIES

The cdylib links the official driver and the async stack; panic = "abort", lto = "thin", strip = true, codegen-units = 1 in the release profile. Pulled in only by this package — never by core stryke.

/SCOPE

The full per-function reference (read/write/findAndModify/aggregation/admin/pure-helpers/query-builders, with signatures and option lists) is on the Docs page; the README's "Why this is a package" + "API reference" sections are the upstream source of truth. The package is intentionally narrower than the underlying driver — the goal is "useful from a shell pipeline", not "complete API coverage". Not-yet-shipped: Change Streams, multi-doc transactions, bulk_write, GridFS (see the Docs roadmap).

#PROJECT METADATA