Integration-kit/template/server/core.js

// ── Everything this module reaches in core ─────────────────────────────────
//
// `ctx` arrives once, as an argument to `register()` (MODULE_API.md §2.3). The
// code beneath it — models, controllers, utilities — is ordinary Node that
// requires its dependencies at file scope, the way any Node file does. This file
// is what lets both of those be true at the same time.
//
// **Every export is a lazy accessor, not a stored reference, and that is the
// whole point.** A model writes
//
//     const { query } = require('../../core')
//
// at require time, which is before `register()` has been called and therefore
// before any `ctx` exists. Handing out `ctx.db.query` at that moment would hand
// out `undefined`, permanently, and the failure would surface much later as a
// TypeError inside a model with no clue pointing here. So each member resolves
// `ctx` when it is CALLED. Require order stops mattering for everything except
// `core.init()` itself, which `index.js` runs first.
//
// The same rule in the other direction: **never destructure off `ctx` at init
// time.** Core is free to hand over a getter — `ctx.site.baseUrl` is one — and a
// value captured once is a value that cannot change.
//
// If `ctx` is missing every accessor throws the same message. The only ways to
// reach one before `register()` are a require cycle or a test that forgot to call
// `init`, and both want naming rather than `undefined`.
//
// ── This file is a NARROWING, on purpose ───────────────────────────────────
//
// §2.3 lists everything core hands over. What is re-exported below is only what
// this module actually uses, which is the discipline worth copying: the file is
// then an honest statement of what your module depends on, and a test double for
// it (see `test/_fakes.js`) is a complete one. Add a member here when you reach
// for it — not in advance.

let ctx = null

function need() {
  if (!ctx) {
    throw new Error('examplegame: core accessed before register() — see server/core.js')
  }
  return ctx
}

/** Called once, first thing in `register()`. */
function init(value) {
  ctx = value
}

/** Test seam. Nothing in the module calls this; there is no de-registration. */
function _reset() {
  ctx = null
}

// A logger that can be taken at require time and used after `register()`.
//
// A file writes `const log = require('../core').logger('world')` at file scope,
// so the object returned has to exist before `ctx` does. It is a façade whose
// four methods each resolve the real logger when called. Core namespaces the
// output with your module id, so these come out as `[examplegame:world]`.
function logger(namespace) {
  const call = (level) => (message, meta) => need().log(namespace)[level](message, meta)
  return { error: call('error'), warn: call('warn'), info: call('info'), debug: call('debug') }
}

module.exports = {
  init,
  _reset,
  logger,

  // Shared server dependencies. Core owns exactly one express, as it owns
  // exactly one React on the client, and for the same reason: a second copy in
  // the process is a second Router prototype and a second set of `instanceof`
  // checks. A module could not resolve these for itself even if it were allowed
  // to — it lives outside core's `server/` (§7.2).
  get express() { return need().express },
  get validator() { return need().validator },

  // The database. `query(sql, params)` is what every `*.db.js` file uses; raw
  // parameterised SQL, no ORM, the same as core. `pool` is there for the rare
  // case that needs a connection it can hold (a streamed import, say).
  query: (...args) => need().db.query(...args),
  get pool() { return need().db.pool },

  // Read-only access to who is asking. Minting a session is core's job; a module
  // that needs an identity needs to *read* one.
  auth: { getUserFromRequest: (...args) => need().auth.getUserFromRequest(...args) },

  // Core's middleware, taken as values rather than wrapped: express stores the
  // function reference at mount time, so a wrapper is what would end up in the
  // stack. Routers are built inside `register()`, so `ctx` is set by then.
  get middleware() { return need().middleware },

  // Firing a declared event (MODULE_API.md §2.3). Wrapped as a call rather than
  // exposed as `get events()`, so that `require('../core').emit` taken at file
  // scope still resolves `ctx` at call time like everything else here.
  //
  // **It returns nothing, and in production it never throws at the caller.** The
  // emit is the end of this module's involvement: core validates the payload
  // against the declared contract, decides which rules match, resolves who they
  // reach and sends. A module cannot address a person, choose a channel or write
  // a subject line, and this seam is deliberately too narrow to try (§2.7).
  //
  // Outside production a bad payload throws here rather than being logged, which
  // is the point: you meet the mismatch in your own tests instead of in an
  // operator's log six weeks later.
  emit: (triggerId, envelope) => need().events.emit(triggerId, envelope),

  // Telling core the game restarted (MODULE_API.md §2.3, 1.10.0). The one thing
  // the event contract adds to `ctx`, and it is here for a reason worth carrying:
  // **core has no concept of the game being up.** It sees `{ ok: false, retry: true }`
  // and cannot tell a wedged sidecar from a shard that rebooted and lost every
  // creature an event spawned. Only this module knows, because only this module
  // watches the feed the boot id arrives on.
  //
  // Calling it asks core to sweep its resource ledger and put the question back
  // to this module's actions, as `reconcile({ runId, resources })`. Fire and
  // forget: it returns at once and the sweep happens on core's own time.
  //
  // See `boot.js` for the watch that calls it, and `config/eventActions.js` for
  // the answer. Named longer than the `ctx` member it wraps because this object
  // is flat — `core.emit` is already a little ambiguous and `core.reconcile()`
  // would be worse, since a module has more than one thing it could reconcile.
  reconcileEvents: () => need().events.reconcile(),

  // Deployment facts. `moduleRoot` is the absolute path to `modules/<id>/` — the
  // only correct way to find a file you shipped, because the working directory is
  // core's and the module's location is the loader's business.
  get moduleRoot() { return need().paths.moduleRoot },
  get moduleId() { return need().moduleId },
}