@toa.io/storages.mongodb 1.0.0-alpha.284 → 1.0.0-alpha.286

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/storages.mongodb",
-  "version": "1.0.0-alpha.284",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa MongoDB Storage Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -20,13 +20,13 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/conveyor": "1.0.0-alpha.283",
-    "@toa.io/core": "1.0.0-alpha.284",
-    "@toa.io/generic": "1.0.0-alpha.283",
-    "@toa.io/pointer": "1.0.0-alpha.283",
+    "@toa.io/conveyor": "1.0.0-alpha.286",
+    "@toa.io/core": "1.0.0-alpha.286",
+    "@toa.io/generic": "1.0.0-alpha.286",
+    "@toa.io/pointer": "1.0.0-alpha.286",
     "mongodb": "7.6.0",
-    "openspan": "1.0.0-alpha.277",
+    "openspan": "1.0.0-alpha.286",
     "saslprep": "1.0.3"
   },
-  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf"
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
 }

package/src/client.js

@@ -43,6 +43,15 @@ export class Client extends Connector {
    */
   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}
@@ -71,7 +80,7 @@ export class Client extends Connector {
    * @param {Locator} locator
    * @param {boolean} [publishes] whether this component publishes anything
    */
-  constructor (locator, publishes = false) {
+  constructor(locator, publishes = false) {
     super()
 
     this.locator = locator
@@ -84,7 +93,7 @@ export class Client extends Connector {
    * @override
    * @return {Promise<void>}
    */
-  async open () {
+  async open() {
     const urls = await this.resolveURLs()
     const dbname = this.resolveDB()
 
@@ -101,6 +110,7 @@ export class Client extends Connector {
 
     const db = this.instance.client.db(dbname)
 
+    this.db = db
     this.collection = await collection(db, this.name)
     this.transactional = await transactional(db)
 
@@ -108,8 +118,10 @@ export class Client extends Connector {
 
     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 })
+      console.warn(
+        'MongoDB is not a replica set; events are emitted inline, without an outbox',
+        { collection: this.name }
+      )
   }
 
   /**
@@ -122,9 +134,10 @@ export class Client extends Connector {
    * @param {(session: import('mongodb').ClientSession) => Promise<T>} fn
    * @return {Promise<T>}
    */
-  async transaction (fn) {
+  async transaction(fn) {
     return this.instance.client.withSession(async (session) =>
-      session.withTransaction(async () => fn(session)))
+      session.withTransaction(async () => fn(session))
+    )
   }
 
   /**
@@ -132,7 +145,7 @@ export class Client extends Connector {
    * @override
    * @return {Promise<void>}
    */
-  async close () {
+  async close() {
     const instance = await INSTANCES[this.key]
 
     instance.count--
@@ -148,7 +161,7 @@ export 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)
 
@@ -166,9 +179,11 @@ export class Client extends Connector {
    * @private
    * @return {Promise<string[]>}
    */
-  async resolveURLs () {
+  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 (process.env.TOA_DEV === '1') {
-      return ['mongodb://developer:secret@localhost']
+      return ['mongodb://developer:secret@localhost:31020']
     } else {
       return await resolve(ID, this.locator.id)
     }
@@ -178,7 +193,7 @@ export class Client extends Connector {
    * @private
    * @return {string}
    */
-  resolveDB () {
+  resolveDB() {
     if (process.env.TOA_CONTEXT !== undefined) {
       return process.env.TOA_CONTEXT
     }
@@ -191,14 +206,14 @@ export class Client extends Connector {
   }
 }
 
-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) {
+async function collection(db, name) {
   try {
     return await db.createCollection(name)
   } catch (e) {
@@ -208,7 +223,7 @@ async function collection (db, name) {
   }
 }
 
-async function transactional (db) {
+async function transactional(db) {
   try {
     const hello = await db.admin().command({ hello: 1 })
 

package/src/deployment.js

@@ -7,7 +7,7 @@ export const deployment = (instances, annotation) => {
   return { variables }
 }
 
-function createRequest (instance) {
+function createRequest(instance) {
   return {
     group: instance.locator.label,
     selectors: [instance.locator.id]

package/src/factory.js

@@ -2,7 +2,7 @@ import { Client } from './client.js'
 import { Storage } from './storage.js'
 
 export class Factory {
-  storage (locator, entity, options = {}) {
+  storage(locator, entity, options = {}) {
     const client = new Client(locator, options.outbox === true)
 
     return new Storage(client, entity)

package/src/migrations.js

@@ -0,0 +1,270 @@
+import { randomUUID } from 'node:crypto'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+import { console } from 'openspan'
+
+/**
+ * Applies a component's migrations to its collection, in the order they were declared, and
+ * records each one so that it is applied once for the database rather than once per replica.
+ *
+ * The record is also the lock: the row that says a migration ran is inserted before it runs,
+ * and MongoDB refuses the second insert of the same `_id`. Nothing else is needed to make the
+ * group agree, which is why this works where there is no Redis.
+ */
+export class Migrations {
+  /** @type {import('mongodb').Collection} */
+  #collection
+
+  /** @type {import('mongodb').Collection} */
+  #state
+
+  /** @type {Array<{ id: string, steps: object[] }>} */
+  #list
+
+  /**
+   * @param {import('mongodb').Db} db
+   * @param {import('mongodb').Collection} collection the entity's own
+   * @param {Array<{ id: string, steps: object[] }>} list
+   */
+  constructor(db, collection, list) {
+    this.#collection = collection
+    this.#state = db.collection(STATE)
+    this.#list = list
+  }
+
+  /**
+   * A migration is applied only after the one before it, because a later one is written
+   * against what an earlier one leaves behind.
+   */
+  async run() {
+    for (const migration of this.#list) await this.#apply(migration)
+  }
+
+  /** @private */
+  async #apply(migration) {
+    const id = `${this.#collection.collectionName}:${migration.id}`
+
+    while (true) {
+      if (await this.#claim(id)) return await this.#run(id, migration)
+
+      const row = await this.#state.findOne({ _id: id })
+
+      // removed between the claim and the read; whoever did that wants it applied again
+      if (row === null) continue
+
+      if (row.state === DONE) return
+
+      const stale = Date.now() - row.heartbeat.getTime() > LEASE
+
+      if (!stale) {
+        await sleep(POLL)
+
+        continue
+      }
+
+      console.warn('Taking over an abandoned migration', {
+        migration: id,
+        owner: row.owner,
+        heartbeat: row.heartbeat
+      })
+
+      if (await this.#steal(id, row.heartbeat)) return await this.#run(id, migration)
+    }
+  }
+
+  /**
+   * Writes the row that says this replica is applying the migration. Answers whether it won.
+   *
+   * @private
+   */
+  async #claim(id) {
+    try {
+      await this.#state.insertOne({
+        _id: id,
+        state: RUNNING,
+        owner: OWNER,
+        started: new Date(),
+        heartbeat: new Date()
+      })
+
+      return true
+    } catch (error) {
+      if (error.code === ERR_DUPLICATE_KEY) return false
+
+      throw error
+    }
+  }
+
+  /**
+   * Takes a claim whose owner stopped saying it was alive. The heartbeat it read is part of
+   * the criteria, so only one of several waiting replicas takes it.
+   *
+   * @private
+   */
+  async #steal(id, heartbeat) {
+    const result = await this.#state.updateOne(
+      { _id: id, state: RUNNING, heartbeat },
+      { $set: { owner: OWNER, heartbeat: new Date() } }
+    )
+
+    return result.modifiedCount === 1
+  }
+
+  /**
+   * Applies the steps and marks the migration done. A step that throws leaves the row as it
+   * is: the component does not start, and the next replica to reach a stale claim runs the
+   * migration again from its first step.
+   *
+   * @private
+   */
+  async #run(id, migration) {
+    console.info('Applying migration', { migration: id, steps: migration.steps.length })
+
+    const beat = setInterval(() => {
+      this.#state
+        .updateOne({ _id: id }, { $set: { heartbeat: new Date() } })
+        .catch((error) =>
+          console.warn('Migration heartbeat failed', { migration: id, error })
+        )
+    }, HEARTBEAT)
+
+    beat.unref?.()
+
+    try {
+      for (const step of migration.steps) await this.#step(id, step)
+
+      await this.#state.updateOne(
+        { _id: id },
+        { $set: { state: DONE, completed: new Date() } }
+      )
+    } finally {
+      clearInterval(beat)
+    }
+
+    console.info('Migration applied', { migration: id })
+  }
+
+  /** @private */
+  async #step(id, step) {
+    const verbs = Object.keys(step ?? {})
+
+    if (verbs.length !== 1 || !(verbs[0] in STEPS))
+      throw new Error(
+        `Migration '${id}' has a step that is not one of ` +
+          `${Object.keys(STEPS).join(', ')}: ${JSON.stringify(step)}`
+      )
+
+    await STEPS[verbs[0]](this.#collection, step[verbs[0]], id)
+  }
+}
+
+/**
+ * Creates the index the step declares. Where the name is held by an index of a different shape,
+ * that one is dropped: the declaration is what the component is to run against, and refusing
+ * to reconcile is what left a database diverged from its manifest before migrations existed.
+ */
+async function index(collection, { name, keys, ...rest }, id) {
+  if (name === undefined || keys === undefined)
+    throw new Error(`Migration '${id}' declares an index without a name or keys`)
+
+  const spec = Object.fromEntries(
+    Object.entries(keys).map(([field, direction]) => [
+      field,
+      DIRECTIONS[direction] ?? direction
+    ])
+  )
+
+  const options = { name }
+
+  for (const [key, value] of Object.entries(rest)) {
+    if (!(key in OPTIONS))
+      throw new Error(`Migration '${id}' declares an unknown index option '${key}'`)
+
+    options[OPTIONS[key]] = value
+  }
+
+  try {
+    await collection.createIndex(spec, options)
+  } catch (error) {
+    if (!CONFLICTS.includes(error.code)) throw error
+
+    console.info('Recreating an index whose declaration changed', { index: name })
+
+    await collection.dropIndex(name)
+    await collection.createIndex(spec, options)
+  }
+}
+
+async function dropIndex(collection, { name }, id) {
+  if (name === undefined)
+    throw new Error(`Migration '${id}' drops an index without a name`)
+
+  try {
+    await collection.dropIndex(name)
+  } catch (error) {
+    if (error.code !== ERR_INDEX_NOT_FOUND) throw error
+  }
+}
+
+async function update(collection, { filter, update: changeset }, id) {
+  if (changeset === undefined) throw new Error(`Migration '${id}' updates with nothing`)
+
+  const result = await collection.updateMany(filter ?? {}, changeset)
+
+  console.info('Migration updated records', {
+    migration: id,
+    records: result.modifiedCount
+  })
+}
+
+async function remove(collection, { filter }, id) {
+  if (filter === undefined)
+    throw new Error(
+      `Migration '${id}' deletes without a filter; pass {} to mean every record`
+    )
+
+  const result = await collection.deleteMany(filter)
+
+  console.info('Migration deleted records', {
+    migration: id,
+    records: result.deletedCount
+  })
+}
+
+const STEPS = { index, dropIndex, update, delete: remove }
+
+const DIRECTIONS = { asc: 1, desc: -1, hash: 'hashed' }
+
+/** what an index step may say, and what the driver calls it */
+const OPTIONS = {
+  unique: 'unique',
+  sparse: 'sparse',
+  partial: 'partialFilterExpression',
+  ttl: 'expireAfterSeconds'
+}
+
+/**
+ * A component's namespace may not be `system`, so this cannot be a component's own collection;
+ * and MongoDB reserves the `system.` prefix, with a dot, which this is not.
+ */
+export const STATE = 'system_migrations'
+
+const RUNNING = 'running'
+const DONE = 'done'
+
+/** how long a claim outlives its last heartbeat before another replica may take it */
+const LEASE = 30_000
+const HEARTBEAT = 5_000
+const POLL = 1_000
+
+/**
+ * Which process holds a claim, and nothing more: it is read by whoever takes an abandoned
+ * one over, and told to whoever reads the collection. Random, because there is no identity
+ * a process is guaranteed to have — a host name says nothing about two replicas on one
+ * machine, and a pid is reused.
+ */
+const OWNER = randomUUID()
+
+const ERR_DUPLICATE_KEY = 11000
+const ERR_INDEX_NOT_FOUND = 27
+const CONFLICTS = [85, 86] // IndexOptionsConflict, IndexKeySpecsConflict

package/src/outbox.js

@@ -12,18 +12,18 @@ export class Outbox {
 
   #retention
 
-  constructor (collection) {
+  constructor(collection) {
     this.#collection = collection
     this.#retention = retention()
   }
 
   /** @param {import('mongodb').ClientSession} session */
-  async insert (row, session) {
+  async insert(row, session) {
     await this.#collection.insertOne(to(row), { session })
   }
 
   /** @param {import('mongodb').ClientSession} session */
-  async insertMany (rows, session) {
+  async insertMany(rows, session) {
     if (rows.length === 0) return
 
     await this.#collection.insertMany(rows.map(to), { session })
@@ -37,7 +37,7 @@ export class Outbox {
    * the order rows were written and a page is never read twice within a cycle — which matters
    * because a row stays unpublished in the database until the cycle that sent it marks it.
    */
-  async pending (lanes, now, limit, after = undefined) {
+  async pending(lanes, now, limit, after = undefined) {
     const criteria = { lane: { $in: lanes }, published: false, pending: { $lte: now } }
 
     if (after !== undefined) criteria._id = { $gt: after }
@@ -55,18 +55,21 @@ export class Outbox {
    * One batched write for many events, which is why the ids are held in memory until the
    * tick rather than updated one by one.
    */
-  async settle (ids) {
+  async settle(ids) {
     if (ids.length === 0) return
 
-    await this.#collection.updateMany({ _id: { $in: ids } },
-      { $set: { published: true, publishedAt: new Date() } })
+    await this.#collection.updateMany(
+      { _id: { $in: ids } },
+      { $set: { published: true, publishedAt: new Date() } }
+    )
   }
 
   /**
-   * The entity collection's index management does not reach here, so this collection keeps
-   * its own — including pruning, or a later change leaves the old index behind forever.
+   * These are the runtime's indexes, not the component's, so they are declared here rather
+   * than in a migration a component would have to write — including pruning, or a later
+   * change leaves the old index behind forever.
    */
-  async index () {
+  async index() {
     const desired = {
       // holds only what is not published yet, so it stays at in-flight size
       outbox_pending: {
@@ -82,15 +85,54 @@ export class Outbox {
     }
 
     for (const { fields, options } of Object.values(desired))
-      await this.#collection.createIndex(fields, options)
-        .catch((e) => console.warn('MongoDB outbox index creation failed',
-          { collection: this.#collection.collectionName, name: options.name, error: e }))
+      await this.#index(fields, options)
 
     await this.#prune(Object.keys(desired))
   }
 
+  /**
+   * The name of an index here is fixed, so changing what it is made of — a retention that
+   * changes `expireAfterSeconds`, say — leaves that name held by an index of the old shape,
+   * which MongoDB refuses to overwrite. The old one is dropped and the declared one made.
+   *
+   * @private
+   */
+  async #index(fields, options) {
+    try {
+      await this.#collection.createIndex(fields, options)
+    } catch (e) {
+      if (!CONFLICTS.includes(e.code))
+        return console.warn('MongoDB outbox index creation failed', {
+          collection: this.#collection.collectionName,
+          name: options.name,
+          error: e
+        })
+
+      console.info('Recreating an outbox index whose declaration changed', {
+        collection: this.#collection.collectionName,
+        name: options.name
+      })
+
+      await this.#drop(options.name)
+      await this.#collection.createIndex(fields, options)
+    }
+  }
+
+  /**
+   * Concurrent replicas prune the same index, and losing that race is not an error.
+   *
+   * @private
+   */
+  async #drop(name) {
+    try {
+      await this.#collection.dropIndex(name)
+    } catch (e) {
+      if (e.code !== ERR_INDEX_NOT_FOUND) throw e
+    }
+  }
+
   /** @private */
-  async #prune (desired) {
+  async #prune(desired) {
     let current
 
     try {
@@ -105,17 +147,19 @@ export class Outbox {
 
     if (obsolete.length === 0) return
 
-    console.info('Removing obsolete outbox indexes',
-      { collection: this.#collection.collectionName, indexes: obsolete.join(', ') })
+    console.info('Removing obsolete outbox indexes', {
+      collection: this.#collection.collectionName,
+      indexes: obsolete.join(', ')
+    })
 
-    await Promise.all(obsolete.map((name) => this.#collection.dropIndex(name)))
+    await Promise.all(obsolete.map((name) => this.#drop(name)))
   }
 }
 
 const to = ({ id, ...rest }) => ({ _id: id, ...rest })
 const from = ({ _id, ...rest }) => ({ id: _id, ...rest })
 
-function retention () {
+function retention() {
   const value = Number(process.env.TOA_OUTBOX_RETENTION)
 
   return Number.isNaN(value) || value < 0 ? RETENTION : value
@@ -123,3 +167,6 @@ function retention () {
 
 /** seconds a published row is kept as a change log before the TTL monitor reaps it */
 const RETENTION = 86400
+
+const ERR_INDEX_NOT_FOUND = 27
+const CONFLICTS = [85, 86] // IndexOptionsConflict, IndexKeySpecsConflict

package/src/record.js

@@ -1,12 +1,11 @@
-export function to (entity) {
+export function to(entity) {
   const { id, ...rest } = entity
 
   return /** @type {toa.mongodb.Record} */ { _id: id, ...rest }
 }
 
-export function from (record) {
-  if (record === undefined || record === null)
-    return null
+export function from(record) {
+  if (record === undefined || record === null) return null
 
   const { _id, ...rest } = record