@omega.js/backend 0.1.0

package/test/helpers/roles.test.js

@@ -0,0 +1,155 @@
+/**
+ * Test: helpers/roles.js — the role table
+ *
+ * Run: npx omega test backend:helpers/roles
+ *
+ * Roles.list() is the SSOT mapping a raw role string a brand hands the
+ * framework ('admin', 'mod', 'beta') onto a canonical role id. The table is
+ * a WIRE contract: an id that changes silently re-permissions every user
+ * carrying it, so both the id set and each entry's alias set are pinned.
+ *
+ * The entries' regexes carry the `g` flag, which makes `.test()` STATEFUL
+ * (lastIndex advances) — the hazard is pinned below so a caller that loops
+ * over the table cannot be surprised by it.
+ */
+const Roles = require('../../dist/manager/helpers/roles.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const roles = new Roles({ libraries: {} });
+
+// Match a raw input against the table the way a caller would — with a fresh,
+// stateless copy of each entry's regex.
+const idsMatching = (input) => roles.list()
+  .filter((role) => new RegExp(role.regex.source, 'i').test(input))
+  .map((role) => role.id);
+
+module.exports = defineCases({
+  description: 'Roles.list() role table',
+  type: 'group',
+
+  tests: [
+    // ─── The table ───
+
+    {
+      name: 'the-role-id-set-is-exactly-these-ten',
+      async run({ assert }) {
+        assert.deepEqual(roles.list().map((role) => role.id), [
+          'staff',
+          'admin',
+          'moderator',
+          'moderatorJr',
+          'blogger',
+          'developer',
+          'betaTester',
+          'serverBooster',
+          'og',
+          'vip',
+        ]);
+      },
+    },
+
+    {
+      name: 'every-entry-carries-an-id-name-and-regex',
+      async run({ assert }) {
+        for (const role of roles.list()) {
+          assert.equal(typeof role.id, 'string');
+          assert.equal(typeof role.name, 'string');
+          assert.equal(role.regex instanceof RegExp, true);
+        }
+      },
+    },
+
+    {
+      name: 'display-names-are-pinned',
+      async run({ assert }) {
+        const names = Object.fromEntries(roles.list().map((role) => [role.id, role.name]));
+
+        assert.equal(names.admin, 'Administrator');
+        assert.equal(names.moderatorJr, 'Jr. Moderator');
+        assert.equal(names.betaTester, 'Beta Tester');
+        assert.equal(names.serverBooster, 'Server Booster');
+        assert.equal(names.og, 'OG');
+        assert.equal(names.vip, 'VIP');
+      },
+    },
+
+    // ─── Alias resolution ───
+
+    {
+      name: 'canonical-spellings-match-their-own-role',
+      async run({ assert }) {
+        assert.deepEqual(idsMatching('staff'), ['staff']);
+        assert.deepEqual(idsMatching('administrator'), ['admin']);
+        assert.deepEqual(idsMatching('moderator'), ['moderator']);
+        assert.deepEqual(idsMatching('blogger'), ['blogger']);
+        assert.deepEqual(idsMatching('developer'), ['developer']);
+        assert.deepEqual(idsMatching('betatester'), ['betaTester']);
+        assert.deepEqual(idsMatching('serverbooster'), ['serverBooster']);
+        assert.deepEqual(idsMatching('og'), ['og']);
+      },
+    },
+
+    {
+      name: 'short-aliases-resolve-to-the-same-role',
+      async run({ assert }) {
+        assert.deepEqual(idsMatching('admin'), ['admin']);
+        assert.deepEqual(idsMatching('mod'), ['moderator']);
+        assert.deepEqual(idsMatching('modjr'), ['moderatorJr']);
+        assert.deepEqual(idsMatching('moderatorjr'), ['moderatorJr']);
+        assert.deepEqual(idsMatching('blog'), ['blogger']);
+        assert.deepEqual(idsMatching('dev'), ['developer']);
+        assert.deepEqual(idsMatching('beta'), ['betaTester']);
+        assert.deepEqual(idsMatching('booster'), ['serverBooster']);
+      },
+    },
+
+    {
+      name: 'matching-is-case-insensitive',
+      async run({ assert }) {
+        assert.deepEqual(idsMatching('ADMIN'), ['admin']);
+        assert.deepEqual(idsMatching('Moderator'), ['moderator']);
+        assert.deepEqual(idsMatching('VIP'), ['vip']);
+      },
+    },
+
+    {
+      name: 'unknown-and-near-miss-inputs-match-nothing',
+      async run({ assert }) {
+        assert.deepEqual(idsMatching('superuser'), []);
+        assert.deepEqual(idsMatching(''), []);
+        // Anchored on both ends — a longer word is not the role.
+        assert.deepEqual(idsMatching('administrators'), []);
+        assert.deepEqual(idsMatching('super-admin'), []);
+        assert.deepEqual(idsMatching('moderatorjrx'), []);
+      },
+    },
+
+    {
+      name: 'vip-is-deliberately-prefix-anchored-only',
+      async run({ assert }) {
+        // /(^vip)/ — unlike every other entry, vip has no trailing anchor.
+        assert.deepEqual(idsMatching('vip'), ['vip']);
+        assert.deepEqual(idsMatching('vip-plus'), ['vip']);
+        assert.deepEqual(idsMatching('super-vip'), []);
+      },
+    },
+
+    // ─── The `g`-flag hazard ───
+
+    {
+      name: 'the-table-regexes-are-stateful-so-callers-must-not-reuse-them',
+      async run({ assert }) {
+        const admin = roles.list().find((role) => role.id === 'admin');
+
+        // The SAME regex object alternates because `g` advances lastIndex.
+        assert.equal(admin.regex.test('admin'), true);
+        assert.equal(admin.regex.test('admin'), false, 'second call is a false negative');
+        assert.equal(admin.regex.lastIndex, 0, 'and the index resets after the miss');
+
+        // list() hands out a FRESH table each call, so a caller that re-reads
+        // the table (rather than caching an entry) never sees the drift.
+        assert.equal(roles.list().find((role) => role.id === 'admin').regex.lastIndex, 0);
+      },
+    },
+  ],
+});

package/test/helpers/route-context-debug-gate.test.js

@@ -0,0 +1,118 @@
+/**
+ * Test: `debug` is an opt-in level
+ * ([#230](https://github.com/Omega-JS-Stack/omega/issues/230)).
+ *
+ * Every other level writes unconditionally. `debug` writes NOTHING unless
+ * `OMEGA_DEBUG` is set in the environment — that is what makes "demote it to
+ * debug" a real reduction rather than a rename: nothing is deleted, it is one
+ * env var away.
+ *
+ * The only stand-in here is `console` (the sink the logger writes to); the ctx is
+ * a real one, built by Manager.RouteContext().
+ *
+ * Run: npx omega test framework:helpers/route-context-debug-gate
+ */
+
+// Record every console call the thunk makes, restoring console afterward.
+
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+function withConsoleRecorder(fn) {
+  const calls = { log: [], debug: [], warn: [], error: [] };
+  const original = { log: console.log, debug: console.debug, warn: console.warn, error: console.error };
+
+  console.log = (...args) => calls.log.push(args);
+  console.debug = (...args) => calls.debug.push(args);
+  console.warn = (...args) => calls.warn.push(args);
+  console.error = (...args) => calls.error.push(args);
+
+  try {
+    fn();
+    return calls;
+  } finally {
+    console.log = original.log;
+    console.debug = original.debug;
+    console.warn = original.warn;
+    console.error = original.error;
+  }
+}
+
+// Run the thunk with the debug switch in a known state. The logger reads it live
+// on every line, so flipping the var IS the switch.
+function withDebug(value, fn) {
+  const saved = process.env.OMEGA_DEBUG;
+
+  if (value === undefined) {
+    delete process.env.OMEGA_DEBUG;
+  } else {
+    process.env.OMEGA_DEBUG = value;
+  }
+
+  try {
+    return fn();
+  } finally {
+    if (saved === undefined) {
+      delete process.env.OMEGA_DEBUG;
+    } else {
+      process.env.OMEGA_DEBUG = saved;
+    }
+  }
+}
+
+module.exports = defineCases({
+  description: 'ctx.debug writes only when OMEGA_DEBUG is set',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'debug-is-silent-by-default',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({}, { functionName: 'debug-gate' });
+
+        const calls = withConsoleRecorder(() => {
+          withDebug(undefined, () => {
+            ctx.debug('a big payload', { secret: 'sauce' });
+          });
+        });
+
+        assert.equal(calls.debug.length, 0, 'a debug line must not reach console.debug by default');
+        assert.equal(calls.log.length, 0, 'a debug line must not fall through to console.log either');
+      },
+    },
+
+    {
+      name: 'debug-writes-when-omega-debug-is-set',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({}, { functionName: 'debug-gate' });
+
+        const calls = withConsoleRecorder(() => {
+          withDebug('1', () => {
+            ctx.debug('a big payload', { secret: 'sauce' });
+          });
+        });
+
+        assert.equal(calls.debug.length, 1, 'OMEGA_DEBUG should let the line through');
+        assert.equal(calls.debug[0][0].endsWith(`[@omega.js/backend:debug-gate] ${ctx.id}:`), true, calls.debug[0][0]);
+        assert.equal(calls.debug[0][1], 'a big payload', calls.debug[0][1]);
+      },
+    },
+
+    {
+      name: 'every-other-level-is-untouched-by-the-gate',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({}, { functionName: 'debug-gate' });
+
+        const calls = withConsoleRecorder(() => {
+          withDebug(undefined, () => {
+            ctx.log('log line');
+            ctx.warn('warn line');
+            ctx.error('error line');
+          });
+        });
+
+        assert.equal(calls.log.length, 1, 'ctx.log must still write with the debug gate closed');
+        assert.equal(calls.warn.length, 1, 'ctx.warn must still write with the debug gate closed');
+        assert.equal(calls.error.length, 1, 'ctx.error must still write with the debug gate closed');
+      },
+    },
+  ],
+});

package/test/helpers/route-context-logging.test.js

@@ -0,0 +1,214 @@
+/**
+ * Test: RouteContext logging — the ONE identity tag
+ * ([#121](https://github.com/Omega-JS-Stack/omega/issues/121)) and the local
+ * timestamp ([#130](https://github.com/Omega-JS-Stack/omega/issues/130)).
+ *
+ * Every ctx line opens with `[@omega.js/backend:<module>]`, where the module
+ * segment is the invocation's function name. The invocation id and any log
+ * prefix follow the tag.
+ *
+ * In production Cloud Logging stamps every entry, so the tag opens the line with
+ * no timestamp bracket. Outside production nothing stamps a plain local run, so a
+ * short `[HH:MM:SS]` bracket comes first — both branches are pinned below.
+ *
+ * The only stand-in here is `console` itself (the external sink the logger
+ * writes to); the ctx is a real one, built by Manager.RouteContext().
+ *
+ * Run: npx omega test backend:helpers/route-context-logging
+ */
+
+// Record every console call the thunk makes, restoring console afterward.
+
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+function withConsoleRecorder(fn) {
+  const calls = { log: [], error: [] };
+  const original = { log: console.log, error: console.error };
+
+  console.log = (...args) => calls.log.push(args);
+  console.error = (...args) => calls.error.push(args);
+
+  try {
+    return fn(calls);
+  } finally {
+    console.log = original.log;
+    console.error = original.error;
+  }
+}
+
+// Run the thunk with the environment resolving to production. getEnvironment() reads
+// these vars live on every call, so swapping them is the real switch — testing wins
+// over everything else, so it has to come off too.
+function withProductionEnvironment(fn) {
+  const original = {
+    OMEGA_TEST_MODE: process.env.OMEGA_TEST_MODE,
+    ENVIRONMENT: process.env.ENVIRONMENT,
+    TERM_PROGRAM: process.env.TERM_PROGRAM,
+    FUNCTIONS_EMULATOR: process.env.FUNCTIONS_EMULATOR,
+  };
+
+  delete process.env.OMEGA_TEST_MODE;
+  delete process.env.TERM_PROGRAM;
+  delete process.env.FUNCTIONS_EMULATOR;
+  process.env.ENVIRONMENT = 'production';
+
+  try {
+    return fn();
+  } finally {
+    Object.entries(original).forEach(([key, value]) => {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    });
+  }
+}
+
+// [HH:MM:SS] followed by the identity tag.
+const LOCAL_LINE = /^\[\d{2}:\d{2}:\d{2}\] \[@omega\.js\/backend:/;
+
+module.exports = defineCases({
+  description: 'ctx.log carries the [@omega.js/backend:<module>] identity tag',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'ctx-log-opens-with-the-identity-tag',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({}, { functionName: 'user-signup' });
+
+        const calls = withConsoleRecorder((recorded) => {
+          ctx.log('Created user');
+          return recorded;
+        });
+
+        assert.equal(calls.log[0][0].endsWith(`[@omega.js/backend:user-signup] ${ctx.id}:`), true, calls.log[0][0]);
+        assert.equal(calls.log[0][1], 'Created user');
+      },
+    },
+
+    {
+      name: 'outside-production-the-line-opens-with-a-local-timestamp',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({}, { functionName: 'user-signup' });
+
+        // The suite's own environment is non-production — that IS the local branch.
+        assert.equal(ctx.isProduction(), false, 'the suite must run outside production for this test');
+
+        const calls = withConsoleRecorder((recorded) => {
+          ctx.log('Created user');
+          return recorded;
+        });
+
+        const prefix = calls.log[0][0];
+
+        // Nothing stamps a plain local run, so the logger does it.
+        assert.equal(LOCAL_LINE.test(prefix), true, `local line should open with [HH:MM:SS] then the tag, got: ${prefix}`);
+        assert.equal(prefix.endsWith(`[@omega.js/backend:user-signup] ${ctx.id}:`), true, prefix);
+      },
+    },
+
+    {
+      name: 'in-production-the-tag-stands-alone-no-timestamp-bracket',
+      run: async ({ assert, Manager }) => {
+        const line = withProductionEnvironment(() => {
+          const ctx = Manager.RouteContext({}, { functionName: 'user-signup' });
+
+          assert.equal(ctx.isProduction(), true, 'the production branch was not reached');
+
+          const calls = withConsoleRecorder((recorded) => {
+            ctx.log('Created user');
+            return recorded;
+          });
+
+          return { prefix: calls.log[0][0], id: ctx.id };
+        });
+
+        // Cloud Logging stamps the entry; a hand-written time would be a second one.
+        assert.equal(line.prefix, `[@omega.js/backend:user-signup] ${line.id}:`, line.prefix);
+        assert.equal(/^\[\d{2}:\d{2}:\d{2}\]/.test(line.prefix), false, `production line carries a timestamp: ${line.prefix}`);
+        assert.equal(/^\[\d{4}-\d{2}-\d{2}T/.test(line.prefix), false, `production line carries a timestamp: ${line.prefix}`);
+      },
+    },
+
+    {
+      name: 'under-the-emulator-the-line-is-stamped-like-any-local-run',
+      run: async ({ assert, Manager }) => {
+        const saved = process.env.FUNCTIONS_EMULATOR;
+        const savedTestMode = process.env.OMEGA_TEST_MODE;
+        const savedEnvironment = process.env.ENVIRONMENT;
+        process.env.FUNCTIONS_EMULATOR = 'true';
+        // Drop the runner's test-mode flag AND its ENVIRONMENT so getEnvironment()
+        // genuinely resolves through the FUNCTIONS_EMULATOR branch — with either
+        // set, resolution short-circuits before the emulator check and this test
+        // would duplicate the local-run one.
+        delete process.env.OMEGA_TEST_MODE;
+        delete process.env.ENVIRONMENT;
+        try {
+          const ctx = Manager.RouteContext({}, { functionName: 'user-signup' });
+
+          // The emulator's `>` functions prefix carries no time, so emulator lines
+          // are stamped exactly like any other non-production run.
+          assert.equal(Manager.getEnvironment(), 'development', 'the emulator branch must resolve as development');
+
+          const calls = withConsoleRecorder((recorded) => {
+            ctx.log('Created user');
+            return recorded;
+          });
+
+          const prefix = calls.log[0][0];
+          assert.equal(LOCAL_LINE.test(prefix), true, `emulator line should open with [HH:MM:SS], got: ${prefix}`);
+          assert.equal(prefix.endsWith(`[@omega.js/backend:user-signup] ${ctx.id}:`), true, prefix);
+        } finally {
+          if (saved === undefined) {
+            delete process.env.FUNCTIONS_EMULATOR;
+          } else {
+            process.env.FUNCTIONS_EMULATOR = saved;
+          }
+          if (savedTestMode === undefined) {
+            delete process.env.OMEGA_TEST_MODE;
+          } else {
+            process.env.OMEGA_TEST_MODE = savedTestMode;
+          }
+          if (savedEnvironment === undefined) {
+            delete process.env.ENVIRONMENT;
+          } else {
+            process.env.ENVIRONMENT = savedEnvironment;
+          }
+        }
+      },
+    },
+
+    {
+      name: 'a-log-prefix-follows-the-tag',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({}, { functionName: 'cron' });
+
+        ctx.setLogPrefix('cron/daily()');
+
+        const calls = withConsoleRecorder((recorded) => {
+          ctx.log('Starting...');
+          return recorded;
+        });
+
+        assert.equal(calls.log[0][0].endsWith(`[@omega.js/backend:cron] ${ctx.id} cron/daily():`), true, calls.log[0][0]);
+      },
+    },
+
+    {
+      name: 'every-level-carries-the-same-tag',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({}, { functionName: 'user-signup' });
+
+        const calls = withConsoleRecorder((recorded) => {
+          ctx.error('Something broke');
+          return recorded;
+        });
+
+        assert.equal(calls.error[0][0].endsWith(`[@omega.js/backend:user-signup] ${ctx.id}:`), true, calls.error[0][0]);
+        assert.equal(LOCAL_LINE.test(calls.error[0][0]), true, `every level gets the local stamp: ${calls.error[0][0]}`);
+        assert.equal(calls.error[0][1], 'Something broke');
+      },
+    },
+  ],
+});

package/test/helpers/route-context.test.js

@@ -0,0 +1,129 @@
+/**
+ * Test: RouteContext response door — report() + respond()'s one-door error path
+ *
+ * Covers the cp263 semantics:
+ *   - report(e, {code}) decorates WITHOUT sending: returns an Error carrying
+ *     code/tag/usage/schema, clamps codes into 400-599, works with no res
+ *     (trigger/cron contexts).
+ *   - The Sentry rule: server faults (>= 500) capture automatically; client
+ *     faults (4xx) never do. No per-call flags exist.
+ *   - respond(error) routes through the same machinery (one door) — the wire
+ *     side (status, body, omega-properties header) is pinned by the route
+ *     round-trip suites; this file pins the factory/capture semantics.
+ *
+ * Run: npx omega test backend:helpers/route-context
+ */
+
+// Run a thunk with a recording Sentry transport injected (the transport is the
+// external boundary — the seam the framework itself null-checks in production
+// when Sentry is disabled), restoring the original afterward.
+
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+function withSentryRecorder(Manager, fn) {
+  const captured = [];
+  const original = Manager.libraries.sentry;
+
+  Manager.libraries.sentry = { captureException: (e) => captured.push(e) };
+
+  try {
+    return fn(captured);
+  } finally {
+    Manager.libraries.sentry = original;
+  }
+}
+
+module.exports = defineCases({
+  description: 'RouteContext report() + one-door error semantics',
+  type: 'group',
+  tests: [
+    {
+      name: 'report-returns-decorated-error-without-sending',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({});
+
+        const error = ctx.report('Something broke', { code: 502 });
+
+        if (!(error instanceof Error)) assert.fail('report() must return an Error');
+        assert.equal(error.message, 'Something broke');
+        assert.equal(error.code, 502);
+        assert.equal(typeof error.tag, 'string');
+        assert.equal(typeof error.usage, 'object');
+      },
+    },
+    {
+      name: 'report-clamps-codes-into-error-range',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({});
+
+        assert.equal(ctx.report('x', { code: 200 }).code, 500);
+        assert.equal(ctx.report('x', { code: 999 }).code, 500);
+        assert.equal(ctx.report('x').code, 500);
+        assert.equal(ctx.report('x', { code: 429 }).code, 429);
+      },
+    },
+    {
+      name: 'report-preserves-an-existing-error-code-unless-overridden',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({});
+
+        const carried = Object.assign(new Error('carried'), { code: 404 });
+        assert.equal(ctx.report(carried).code, 404);
+
+        const overridden = Object.assign(new Error('overridden'), { code: 404 });
+        assert.equal(ctx.report(overridden, { code: 410 }).code, 410);
+      },
+    },
+    {
+      name: 'server-faults-capture-to-sentry-automatically',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({});
+
+        withSentryRecorder(Manager, (captured) => {
+          ctx.report('boom', { code: 500 });
+          assert.equal(captured.length, 1);
+          assert.equal(captured[0].message, 'boom');
+        });
+      },
+    },
+    {
+      name: 'client-faults-never-capture-to-sentry',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({});
+
+        withSentryRecorder(Manager, (captured) => {
+          ctx.report('bad input', { code: 400 });
+          ctx.report('limited', { code: 429 });
+          assert.equal(captured.length, 0);
+        });
+      },
+    },
+    {
+      name: 'report-survives-a-null-sentry-library',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({});
+        const original = Manager.libraries.sentry;
+
+        Manager.libraries.sentry = null;
+        try {
+          const error = ctx.report('no sentry wired', { code: 503 });
+          assert.equal(error.code, 503);
+        } finally {
+          Manager.libraries.sentry = original;
+        }
+      },
+    },
+    {
+      name: 'retired-surface-stays-retired',
+      run: async ({ assert, Manager }) => {
+        const ctx = Manager.RouteContext({});
+
+        assert.equal(ctx.errorify, undefined);
+        assert.equal(ctx.errorManager, undefined);
+        assert.equal(ctx.logProd, undefined);
+        assert.equal(ctx.parseRepo, undefined);
+        assert.equal(ctx.getHeaderIp, undefined);
+        assert.equal(Manager.Assistant, undefined);
+      },
+    },
+  ],
+});