@toa.io/storages.mongodb 1.0.0-alpha.29 → 1.0.0-alpha.291

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
+
+### BREAKING CHANGES
+
+* a component that read `process.env.TOA_*` reads `context` instead;
+  `echo(input)` no longer substitutes from the environment; a bash operation sees no
+  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
+
+
+# [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/storages.mongodb
+
+
+
+
+
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
+
+### Features
+
+* **mongodb:** a migration says what it is doing ([a917a81](https://github.com/toa-io/toa/commit/a917a81fdc94eb23fd73182c0edf891e6b2df843))

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/storages.mongodb",
-  "version": "1.0.0-alpha.29",
+  "version": "1.0.0-alpha.291",
+  "type": "module",
   "description": "Toa MongoDB Storage Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -19,13 +20,13 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/console": "1.0.0-alpha.29",
-    "@toa.io/conveyor": "1.0.0-alpha.29",
-    "@toa.io/core": "1.0.0-alpha.29",
-    "@toa.io/generic": "1.0.0-alpha.29",
-    "@toa.io/pointer": "1.0.0-alpha.29",
-    "mongodb": "6.3.0",
+    "@toa.io/conveyor": "1.0.0-alpha.291",
+    "@toa.io/core": "1.0.0-alpha.291",
+    "@toa.io/generic": "1.0.0-alpha.291",
+    "@toa.io/pointer": "1.0.0-alpha.291",
+    "mongodb": "7.6.0",
+    "openspan": "1.0.0-alpha.286",
     "saslprep": "1.0.3"
   },
-  "gitHead": "186d0e17c12a9016b8076edf925963cbb32b9219"
+  "gitHead": "bcd8d8d07bd3e64fc826af8719472404662cc37f"
 }

package/readme.md

@@ -0,0 +1,16 @@
+# MongoDB Storage
+
+## Tracing
+
+Commands are recorded as `client` spans within the trace of the current invocation,
+using the [driver command monitoring events](https://www.mongodb.com/docs/drivers/node/current/monitoring/command-monitoring/).
+
+Spans are named `{command} {collection}` and carry `db.*` attributes following the
+[OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/mongodb/):
+`db.system`, `db.namespace`, `db.collection.name`, `db.operation.name`.
+
+Commands executed outside of a sampled trace context (e.g. index management on startup)
+and internal driver commands (`hello`, `ping`, authentication) are not recorded.
+
+Monitoring is client-side only and does not affect the MongoDB server. Span recording
+adds no waiting to the query path: exporting is buffered and happens in the background.

package/src/client.js

@@ -1,28 +1,58 @@
-'use strict'
-
 /**
  * @typedef {import('mongodb').MongoClient} MongoClient
  * @typedef {{ count: number, client: MongoClient }} Instance
  * @typedef {import('@toa.io/core').Locator} Locator
  */
 
-const { Connector } = require('@toa.io/core')
-const { resolve } = require('@toa.io/pointer')
-const { ID } = require('./deployment')
-const { MongoClient } = require('mongodb')
+import { console } from 'openspan'
+import { environment } from '@toa.io/generic'
+import { Connector } from '@toa.io/core'
+import { resolve } from '@toa.io/pointer'
+import { ID } from './deployment.js'
+import { MongoClient } from 'mongodb'
 
 /**
  * @type {Record<string, Promise<Instance>>}
  */
 const INSTANCES = {}
 
-class Client extends Connector {
+export class Client extends Connector {
+  name
+
   /**
    * @public
    * @type {import('mongodb').Collection}
    */
   collection
 
+  /**
+   * The outbox rows of this component, absent unless something consumes its events. Created
+   * eagerly beside the entity collection, because a transaction cannot create a collection and
+   * an index build cannot run inside one.
+   *
+   * @public
+   * @type {import('mongodb').Collection | undefined}
+   */
+  outbox
+
+  /**
+   * Whether this deployment can run transactions at all. A standalone mongod cannot, and an
+   * outbox without atomicity is worse than none, so the storage falls back to inline emission.
+   *
+   * @public
+   * @type {boolean}
+   */
+  transactional = false
+
+  /**
+   * The database this component's collections live in, which is where the migration state
+   * is kept as well.
+   *
+   * @public
+   * @type {import('mongodb').Db}
+   */
+  db
+
   /**
    * @private
    * @type {Locator}
@@ -41,13 +71,22 @@ class Client extends Connector {
    */
   key
 
+  /**
+   * @private
+   * @type {boolean}
+   */
+  publishes
+
   /**
    * @param {Locator} locator
+   * @param {boolean} [publishes] whether this component publishes anything
    */
-  constructor (locator) {
+  constructor(locator, publishes = false) {
     super()
 
     this.locator = locator
+    this.name = locator.lowercase
+    this.publishes = publishes
   }
 
   /**
@@ -55,29 +94,51 @@ class Client extends Connector {
    * @override
    * @return {Promise<void>}
    */
-  async open () {
+  async open() {
     const urls = await this.resolveURLs()
     const dbname = this.resolveDB()
-    const collname = this.locator.lowercase
 
     this.key = getKey(dbname, urls)
 
-    INSTANCES[this.key] ??= this.createInstance(urls)
+    try {
+      INSTANCES[this.key] ??= this.createInstance(urls)
+    } catch (error) {
+      console.error('Failed to connect to MongoDB', { urls, error })
+    }
 
     this.instance = await INSTANCES[this.key]
     this.instance.count++
 
     const db = this.instance.client.db(dbname)
 
-    try {
-      this.collection = await db.createCollection(collname)
-    } catch (e) {
-      if (e.code !== ALREADY_EXISTS) {
-        throw e
-      }
+    this.db = db
+    this.collection = await collection(db, this.name)
+    this.transactional = await transactional(db)
 
-      this.collection = db.collection(collname)
-    }
+    if (!this.publishes) return
+
+    if (this.transactional) this.outbox = await collection(db, this.name + OUTBOX)
+    else
+      console.warn(
+        'MongoDB is not a replica set; events are emitted inline, without an outbox',
+        { collection: this.name }
+      )
+  }
+
+  /**
+   * Runs `fn` in a transaction and answers what it returned. The driver may call `fn` more
+   * than once, so it must not hold state of its own — an outbox row is built by the caller
+   * and reused, and a rolled back attempt leaves nothing behind.
+   *
+   * @public
+   * @template T
+   * @param {(session: import('mongodb').ClientSession) => Promise<T>} fn
+   * @return {Promise<T>}
+   */
+  async transaction(fn) {
+    return this.instance.client.withSession(async (session) =>
+      session.withTransaction(async () => fn(session))
+    )
   }
 
   /**
@@ -85,7 +146,7 @@ class Client extends Connector {
    * @override
    * @return {Promise<void>}
    */
-  async close () {
+  async close() {
     const instance = await INSTANCES[this.key]
 
     instance.count--
@@ -101,11 +162,11 @@ class Client extends Connector {
    * @param {string[]} urls
    * @return {Promise<Instance>}
    */
-  async createInstance (urls) {
+  async createInstance(urls) {
     const client = new MongoClient(urls.join(','), OPTIONS)
     const hosts = urls.map((str) => new URL(str).host)
 
-    console.info('Connecting to MongoDB:', hosts.join(', '))
+    console.info('Connecting to MongoDB', { address: hosts.join(', ') })
 
     await client.connect()
 
@@ -119,9 +180,11 @@ class Client extends Connector {
    * @private
    * @return {Promise<string[]>}
    */
-  async resolveURLs () {
-    if (process.env.TOA_DEV === '1') {
-      return ['mongodb://developer:secret@localhost']
+  async resolveURLs() {
+    // Toa's own development stack is not on the conventional ports: the applications built on
+    // Toa are, and they share the machine. See CONTRIBUTING.md.
+    if (environment.get('TOA_DEV') === '1') {
+      return ['mongodb://developer:secret@localhost:31020']
     } else {
       return await resolve(ID, this.locator.id)
     }
@@ -131,29 +194,55 @@ class Client extends Connector {
    * @private
    * @return {string}
    */
-  resolveDB () {
-    if (process.env.TOA_CONTEXT !== undefined) {
-      return process.env.TOA_CONTEXT
-    }
+  resolveDB() {
+    const context = environment.get('TOA_CONTEXT')
 
-    if (process.env.TOA_DEV === '1') {
-      return 'toa-dev'
-    }
+    if (context !== undefined) return context
+
+    if (environment.get('TOA_DEV') === '1') return 'toa-dev'
 
     throw new Error('Environment variable TOA_CONTEXT is not defined')
   }
 }
 
-function getKey (db, urls) {
+function getKey(db, urls) {
   return db + ':' + urls.sort().join(' ')
 }
 
+/**
+ * Concurrent pods race to create the same collection, and losing that race is not an error.
+ */
+async function collection(db, name) {
+  try {
+    return await db.createCollection(name)
+  } catch (e) {
+    if (e.code !== ALREADY_EXISTS) throw e
+
+    return db.collection(name)
+  }
+}
+
+async function transactional(db) {
+  try {
+    const hello = await db.admin().command({ hello: 1 })
+
+    return hello.setName !== undefined || hello.msg === 'isdbgrid'
+  } catch (e) {
+    console.warn('MongoDB transaction support could not be determined', { error: e })
+
+    return false
+  }
+}
+
+/**
+ * `monitorCommands` is deliberately absent. It makes the driver materialize every reply
+ * eagerly to populate the monitoring event (`CommandSucceededEvent`), which defeats the
+ * lazy per-document deserialization a cursor exists for — a 100-document batch is then
+ * deserialized twice. `Storage` times its own calls instead.
+ */
 const OPTIONS = {
-  ignoreUndefined: true,
-  connectTimeoutMS: 0,
-  serverSelectionTimeoutMS: 0
+  ignoreUndefined: true
 }
 
 const ALREADY_EXISTS = 48
-
-exports.Client = Client
+const OUTBOX = '_outbox'

package/src/deployment.js

@@ -1,22 +1,17 @@
-'use strict'
+import { createVariables } from '@toa.io/pointer'
 
-const { createVariables } = require('@toa.io/pointer')
-
-const deployment = (instances, annotation) => {
+export const deployment = (instances, annotation) => {
   const requests = instances.map((instance) => createRequest(instance))
   const variables = createVariables(ID, annotation, requests)
 
   return { variables }
 }
 
-function createRequest (instance) {
+function createRequest(instance) {
   return {
     group: instance.locator.label,
     selectors: [instance.locator.id]
   }
 }
 
-const ID = 'mongodb'
-
-exports.ID = ID
-exports.deployment = deployment
+export const ID = 'mongodb'

package/src/factory.js

@@ -1,16 +1,10 @@
-'use strict'
+import { Client } from './client.js'
+import { Storage } from './storage.js'
 
-const { Client } = require('./client')
-const { Collection } = require('./collection')
-const { Storage } = require('./storage')
+export class Factory {
+  storage(locator, entity, options = {}) {
+    const client = new Client(locator, options.outbox === true)
 
-class Factory {
-  storage (locator, entity) {
-    const client = new Client(locator)
-    const connection = new Collection(client)
-
-    return new Storage(connection, entity)
+    return new Storage(client, entity)
   }
 }
-
-exports.Factory = Factory

package/src/index.js

@@ -1,7 +1,2 @@
-'use strict'
-
-const { deployment } = require('./deployment')
-const { Factory } = require('./factory')
-
-exports.deployment = deployment
-exports.Factory = Factory
+export { deployment } from './deployment.js'
+export { Factory } from './factory.js'