@xeplr/base-apis 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,35 @@
+# @xeplr/base-apis
+
+The service layer for a xeplr app: `createApp` wires an Express service, and
+`genericRoute` gives any model a full CRUD API. Composes with `@xeplr/db` and
+`@xeplr/auth`.
+
+## Setup
+
+1. Install `@xeplr/base-apis` (add `@xeplr/db`, `@xeplr/auth`, `dotenv`).
+2. Create a file env.required.js
+3. For anything
+3. Each API is by default guarded through Auth System. But you will need following variables in your env file for AUTH: AUTH_DB_NAME, AUTH_DB_CONNECTION_INFO_ENCRYPTED, AUTH_EXT_MIGRATIONS_DIR, AUTH_PORT. 
+4. The AUTH_EXT_MIGRATIONS_DIR is y
+
+Example:
+
+```bash
+var { resolveConfig, getConnection, bindModels } = require('@xeplr/db');
+
+async function setup() {
+  var dbName = process.env.DB_API || 'xeplr_bi';
+  await resolveConfig('api', process.env.BI_CONNECTION);   // one shared secret
+  var connection = getConnection(dbName, { connectionName: 'api' });
+  bindModels(connection);
+  return connection;
+}
+
+module.exports = setup();
+```
+
+4. Define models (extend `BaseModel`).
+5. Expose CRUD routes with `genericRoute`, one per resource.
+6. Create the service with `createApp` — mount routes, add auth middleware.
+7. Write migrations (schema + data) and run them.
+8. Start the app.

package/bin/check-env.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+// xeplr-check-env — build-time env validation. Reads the app's required list
+// and checks it against the environment. Same check createApp runs at startup.
+//
+//   xeplr-check-env                       # reads ./env.required.js
+//   xeplr-check-env --file ./env.list.js  # custom list module (exports string[])
+//
+// Reads process.env ONLY. The consuming app loads its .env (e.g. via dotenv-cli
+// in the npm script) — @xeplr/* packages never read .env files.
+
+var path = require('path');
+
+function argOf(name, fallback) {
+  var i = process.argv.indexOf('--' + name);
+  return (i !== -1 && process.argv[i + 1]) ? process.argv[i + 1] : fallback;
+}
+
+var file = argOf('file', './env.required.js');
+var required;
+try {
+  required = require(path.resolve(process.cwd(), file));
+} catch (err) {
+  console.error('xeplr-check-env: could not load required list "' + file + '": ' + err.message);
+  process.exit(1);
+}
+
+require('../lib/checkEnv')(required, { appName: argOf('name', 'check-env') });

package/express.js

@@ -3,6 +3,7 @@ var cors = require('cors');
 var cookieParser = require('cookie-parser');
 var path = require('path');
 var { createServer } = require('./lib/server');
+var checkEnv = require('./lib/checkEnv');
 var logs = require('@xeplr/logs');
 
 /**
@@ -12,6 +13,7 @@ var logs = require('@xeplr/logs');
  * @param {number|string} port       - Port or named pipe to listen on
  * @param {string}        appName    - Service name (used for debug namespace and console logs)
  * @param {object}        [options]  - Configuration options
+ * @param {string[]}      [options.requiredEnv]   - Mandatory env var names; missing ones abort startup
  * @param {object}        [options.routes]        - Route map: { '/path': router }
  * @param {Function[]}    [options.middleware]     - Middleware to apply before routes (e.g. authMiddleware)
  * @param {object}        [options.views]         - { engine: 'pug', dir: '/abs/path' }
@@ -36,6 +38,11 @@ var logs = require('@xeplr/logs');
  */
 function createApp(port, appName, options) {
   options = options || {};
+
+  // Fail fast if the app's mandatory env vars are missing (same check the
+  // xeplr-check-env build step runs — one implementation).
+  if (options.requiredEnv) checkEnv(options.requiredEnv, { appName: appName });
+
   var app = express();
 
   // ── Logger ──
@@ -114,6 +121,16 @@ function createApp(port, appName, options) {
     });
   }
 
+  // ── SSE endpoint (server→client push) ──
+  // Enable with `sse: true` for the default '/events' path, or
+  // `sse: { path: '/api/events' }` for a custom one. Mounts AFTER the
+  // middleware chain, so any auth middleware you passed in still applies.
+  if (options.sse) {
+    var sseCfg = options.sse === true ? {} : options.sse;
+    var ssePath = sseCfg.path || '/events';
+    app.get(ssePath, require('./lib/sse').handler);
+  }
+
   // ── Routes ──
   if (options.routes) {
     Object.keys(options.routes).forEach(function(routePath) {

package/http.js

@@ -0,0 +1,15 @@
+const { createServer } = require('./lib/server');
+
+/**
+ * Create a plain Node HTTP server (no Express).
+ *
+ * @param {number|string} port    - Port or named pipe to listen on
+ * @param {string}        appName - Service name (debug namespace + console logs)
+ * @param {Function}      handler - Request handler: function(req, res)
+ * @returns {http.Server}
+ */
+function init(port, appName, handler) {
+  return createServer(handler, port, appName);
+}
+
+module.exports = { init };

package/index.js

@@ -1,10 +1,13 @@
 module.exports = {
   createApp: require('./express'),
   createHttpServer: require('./http'),
+  checkEnv: require('./lib/checkEnv'),
   genericRoute: require('./lib/genericRoute'),
   genericController: require('./lib/genericController'),
+  uploadRoute: require('./lib/uploadRoute'),
   runCluster: require('./lib/cluster').runCluster,
   broadcast: require('./lib/cluster').broadcast,
   isPrimary: require('./lib/cluster').isPrimary,
-  isWorker: require('./lib/cluster').isWorker
+  isWorker: require('./lib/cluster').isWorker,
+  sse: require('./lib/sse')
 };

package/lib/checkEnv.js

@@ -0,0 +1,36 @@
+// Validate that a required set of env vars is present. ONE implementation,
+// used two ways:
+//   • at startup — createApp({ requiredEnv: [...] }) runs it before booting
+//   • at build   — the `xeplr-check-env` CLI runs it against the same list
+// The app supplies the list; the framework owns the check.
+//
+//   checkEnv(['JWT_SECRET', 'XEPLR_BI_CONNECTION'], { appName: 'bi' })
+//
+// Options:
+//   appName  label in the message (default 'app')
+//   exit     process.exit(1) on failure (default true)  — set false to just return
+//   throw    throw instead of logging/exiting (default false)
+//   silent   suppress the success line (default false)
+
+function checkEnv(required, options) {
+  options = options || {};
+  required = required || [];
+  var appName = options.appName || 'app';
+
+  var missing = required.filter(function (v) { return !process.env[v]; });
+
+  if (missing.length > 0) {
+    var msg = '[' + appName + '] Missing required env vars:\n' +
+      missing.map(function (v) { return '  - ' + v; }).join('\n') +
+      '\n\n' + missing.length + ' env var(s) missing. Add them to your .env or CI secrets.';
+    if (options.throw) throw new Error(msg);
+    console.error('\n' + msg + '\n');
+    if (options.exit !== false) process.exit(1);
+    return { ok: false, missing: missing };
+  }
+
+  if (!options.silent) console.log('[' + appName + '] All required env vars present.');
+  return { ok: true, missing: [] };
+}
+
+module.exports = checkEnv;

package/lib/genericController.js

@@ -2,6 +2,50 @@ var { respond } = require('@xeplr/utils/lib/response');
 var { HTTP, STATUS } = require('@xeplr/utils/isomorphic');
 var { generateId } = require('@xeplr/utils/lib/helpers');
 
+/**
+ * Map an Objection / DB error to a clean, client-friendly HTTP response instead
+ * of a blanket 500. Matched by `err.name` (not instanceof) so it survives two
+ * copies of objection in a linked monorepo. Unknown errors still fall to 500.
+ *
+ *   ValidationError        → 422  { fields }   (jsonSchema: required/format/…)
+ *   UniqueViolationError   → 409  already exists
+ *   NotNullViolationError  → 400  <column> is required
+ *   ForeignKeyViolationError → 409 referenced record missing / in use
+ *   Check/DataError        → 400  invalid data
+ *   NotFoundError          → 404
+ */
+function sendError(req, res, err) {
+  if (req && req.log && req.log.error) req.log.error((err && err.message) || 'error', { stack: err && err.stack });
+
+  switch (err && err.name) {
+    case 'ValidationError':
+      return respond(res, HTTP.VALIDATION_ERROR, STATUS.VALIDATION_ERROR, 'validation_error', {
+        message: 'Validation failed', fields: err.data || {}
+      });
+    case 'UniqueViolationError':
+      return respond(res, HTTP.CONFLICT, STATUS.CONFLICT, 'conflict', {
+        message: 'A record with these values already exists', columns: err.columns
+      });
+    case 'NotNullViolationError':
+      return respond(res, HTTP.BAD_REQUEST, STATUS.BAD_REQUEST, 'bad_request', {
+        message: (err.column || 'A required field') + ' is required', column: err.column
+      });
+    case 'ForeignKeyViolationError':
+      return respond(res, HTTP.CONFLICT, STATUS.CONFLICT, 'conflict', {
+        message: 'A referenced record is missing or still in use'
+      });
+    case 'CheckViolationError':
+    case 'DataError':
+      return respond(res, HTTP.BAD_REQUEST, STATUS.BAD_REQUEST, 'bad_request', {
+        message: 'Invalid data for one or more fields'
+      });
+    case 'NotFoundError':
+      return respond(res, HTTP.NOT_FOUND, STATUS.NOT_FOUND, 'not_found');
+    default:
+      return respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+  }
+}
+
 /**
  * Generic CRUD controller.
  * Processes the changeset from xeplr-ui-table in a single transaction.
@@ -35,17 +79,45 @@ async function save(req, res, hierarchy) {
 
   var trx = await knex.transaction();
 
+  // Threaded onto every query in this save via .context(...) — lets a
+  // model's own Objection lifecycle hooks (e.g. $afterInsert(queryContext))
+  // know who made the request, without genericController needing to know
+  // anything about what a specific model does with that. { user: req.user }
+  // only (not the whole req) — keep this small and serializable-shaped.
+  //
+  // afterCommit: a hook that needs a side effect on ANOTHER connection (e.g.
+  // a cross-DB write — see xeplr-bi's Company.$afterInsert granting the
+  // creator access in the auth DB) must not run it inline: this trx hasn't
+  // committed yet, so a later entry in the same changeset failing would roll
+  // this row back while the other connection's write already landed —
+  // orphaned data pointing at a record that no longer exists. Instead the
+  // hook pushes a callback here; genericController drains it only once
+  // trx.commit() has actually succeeded. genericController itself stays
+  // generic — it never knows what a callback does, only that it's safe to
+  // run now.
+  var queryContext = req.user ? { user: req.user, afterCommit: [] } : { afterCommit: [] };
+
   try {
     for (var i = 0; i < changeSet.length; i++) {
-      var ids = await processEntry(changeSet[i], rootDef, trx);
+      var ids = await processEntry(changeSet[i], rootDef, trx, null, queryContext);
       updatedIds = updatedIds.concat(ids);
     }
 
     await trx.commit();
+
+    for (var c = 0; c < queryContext.afterCommit.length; c++) {
+      try {
+        await queryContext.afterCommit[c]();
+      } catch (err) {
+        if (req && req.log && req.log.error) req.log.error('afterCommit callback failed', { message: err.message, stack: err.stack });
+        else console.error('[genericController] afterCommit callback failed:', err.message);
+      }
+    }
+
     respond(res, HTTP.OK, STATUS.UPDATED, 'updated', { updatedIds: updatedIds });
   } catch (err) {
     await trx.rollback();
-    respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+    sendError(req, res, err);
   }
 }
 
@@ -55,15 +127,17 @@ async function save(req, res, hierarchy) {
  * @param {object} def        - Hierarchy definition { key, model, children, foreignKey }
  * @param {object} trx        - Knex transaction
  * @param {string} [parentId] - Parent record ID (set automatically for children)
+ * @param {object} [queryContext] - Passed to .context(...) on every query — see save()
  */
-async function processEntry(entry, def, trx, parentId) {
+async function processEntry(entry, def, trx, parentId, queryContext) {
   var Model = def.model;
   var children = def.children || [];
   var ids = [];
+  queryContext = queryContext || {};
 
   // ── SOFT DELETE ──
   if (entry.deleted === true) {
-    await Model.query(trx).findById(entry.id).patch({ isActive: false });
+    await Model.query(trx).context(queryContext).findById(entry.id).patch({ isActive: false });
     ids.push(entry.id);
     return ids;
   }
@@ -92,19 +166,24 @@ async function processEntry(entry, def, trx, parentId) {
 
   var recordId = ownFields.id;
 
-  // ── INSERT ──
+  // ── INSERT (no id provided) ──
   if (!recordId) {
     recordId = generateId();
     ownFields.id = recordId;
-    await Model.query(trx).insert(ownFields);
+    await Model.query(trx).context(queryContext).insert(ownFields);
     ids.push(recordId);
   } else {
-    // ── PATCH ──
-    var patchFields = Object.assign({}, ownFields);
-    delete patchFields.id;
-
-    if (Object.keys(patchFields).length > 0) {
-      await Model.query(trx).findById(recordId).patch(patchFields);
+    // ── UPSERT (id provided): patch if exists, else insert with given id ──
+    var existing = await Model.query(trx).findById(recordId);
+    if (existing) {
+      var patchFields = Object.assign({}, ownFields);
+      delete patchFields.id;
+      if (Object.keys(patchFields).length > 0) {
+        await Model.query(trx).context(queryContext).findById(recordId).patch(patchFields);
+      }
+      ids.push(recordId);
+    } else {
+      await Model.query(trx).context(queryContext).insert(ownFields);
       ids.push(recordId);
     }
   }
@@ -116,7 +195,7 @@ async function processEntry(entry, def, trx, parentId) {
     if (!childEntries || !Array.isArray(childEntries)) continue;
 
     for (var j = 0; j < childEntries.length; j++) {
-      var childIds = await processEntry(childEntries[j], cDef, trx, recordId);
+      var childIds = await processEntry(childEntries[j], cDef, trx, recordId, queryContext);
       ids = ids.concat(childIds);
     }
   }
@@ -147,7 +226,7 @@ async function deleteByIds(req, res, Model) {
     await Model.query().whereIn('id', ids).patch({ isActive: false });
     respond(res, HTTP.OK, STATUS.DELETED, 'deleted', { updatedIds: ids });
   } catch (err) {
-    respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+    sendError(req, res, err);
   }
 }
 
@@ -168,7 +247,7 @@ async function getById(req, res, Model, graph) {
 
     respond(res, HTTP.OK, STATUS.SUCCESS, 'success', { dataArray: [record] });
   } catch (err) {
-    respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+    sendError(req, res, err);
   }
 }
 
@@ -211,7 +290,7 @@ async function list(req, res, Model, graph) {
       respond(res, HTTP.OK, STATUS.SUCCESS, 'success', { dataArray: records });
     }
   } catch (err) {
-    respond(res, HTTP.SERVER_ERROR, STATUS.SERVER_ERROR, 'server_error', { error: err });
+    sendError(req, res, err);
   }
 }
 

package/lib/sse.js

@@ -0,0 +1,290 @@
+// Server-Sent Events (SSE) — one-way server → UI push over HTTP.
+// Cluster-aware from day one: publish() fans out locally AND across all
+// workers via the existing `broadcast()` primitive, so a completion event
+// fired on worker N reaches subscribers connected to worker M.
+//
+// Two handler variants:
+//
+//   sse.handler                     — legacy, unauthenticated.
+//                                     Kept for dev, tests, private networks.
+//                                     Do NOT expose on a public endpoint.
+//
+//   sse.createHandler({             — production. Requires a ticket.
+//     validateTicket,                 Owns auth-on-connect + per-topic auth.
+//     authorizeTopics?
+//   })
+//
+// PRODUCTION FLOW (with ticket auth):
+//   1. Client is authenticated by your normal auth layer (session cookie /
+//      JWT / whatever). Client POSTs to a ticket endpoint provided by
+//      xeplr-auth (or any provider) → gets a short-lived, single-use ticket.
+//   2. Client opens EventSource('/events?ticket=<tk>&topics=user:me:jobs').
+//   3. sse.createHandler calls validateTicket(tk):
+//        · returns { userId, scopes } on success
+//        · returns null on invalid / expired / already-consumed
+//   4. authorizeTopics(payload, requestedTopics) filters the requested
+//      topics against the ticket's scopes. Rewrites `user:me:*` →
+//      `user:<userId>:*`. Rejects out-of-scope.
+//   5. Only if any topics survive does the SSE connection open.
+//
+// AUTHORIZATION is where teams cut corners — the auth check on connect is
+// easy; the per-topic check is where users end up subscribing to
+// `user:other_user:jobs` and leaking data. Do NOT trust client-supplied
+// topics verbatim. The default authorizeTopics enforces sane rules; supply
+// your own only if you know why you're overriding.
+//
+// PUBLISH:
+//   sse.publish('user:42:jobs', { jobId, status });
+//   Cluster-aware: fires on this worker + relays to all others.
+//
+// CLIENT:
+//   var events = new EventSource('/events?ticket=<tk>&topics=user:me:jobs');
+//   events.onmessage = function(e) {
+//     var { topic, data } = JSON.parse(e.data);
+//     // ...
+//   };
+
+var cluster = require('cluster');
+var { broadcast } = require('./cluster');
+
+// topic → Set<res> — local subscribers on THIS worker/process
+var _subs = new Map();
+
+// How often to send a keep-alive comment (proxies close idle conns silently)
+var HEARTBEAT_MS = 25000;
+
+// Cluster message discriminator so we don't confuse other broadcasts
+var TAG = '__xeplrSse';
+
+/**
+ * Attach a Response to an authorized set of topics. This is the shared
+ * inner core — both the legacy `handler` and the auth'd `createHandler`
+ * call this after they've decided which topics the client gets.
+ *
+ * On disconnect, all subscriptions are cleaned up automatically.
+ */
+function attachStream(req, res, topics) {
+  res.setHeader('Content-Type',        'text/event-stream');
+  res.setHeader('Cache-Control',       'no-cache, no-transform');
+  res.setHeader('Connection',          'keep-alive');
+  res.setHeader('X-Accel-Buffering',   'no');       // nginx: don't buffer
+  res.flushHeaders();
+
+  topics.forEach(function(t) {
+    if (!_subs.has(t)) _subs.set(t, new Set());
+    _subs.get(t).add(res);
+  });
+
+  // Initial comment lets the client know the stream is open
+  res.write(': connected ' + Date.now() + '\n\n');
+
+  // Heartbeat — SSE comment lines are silently ignored by EventSource
+  var heartbeat = setInterval(function() {
+    try { res.write(': keepalive\n\n'); }
+    catch (_) { /* stream closed */ }
+  }, HEARTBEAT_MS);
+  if (heartbeat && heartbeat.unref) heartbeat.unref();
+
+  var cleanedUp = false;
+  function cleanup() {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    clearInterval(heartbeat);
+    topics.forEach(function(t) {
+      var set = _subs.get(t);
+      if (!set) return;
+      set.delete(res);
+      if (set.size === 0) _subs.delete(t);
+    });
+  }
+  req.on('close', cleanup);
+  res.on('close', cleanup);
+}
+
+function parseTopics(req) {
+  var topicsParam = (req.query && req.query.topics) || '';
+  return String(topicsParam).split(',').map(function(t) { return t.trim(); }).filter(Boolean);
+}
+
+/**
+ * LEGACY handler — no auth. Kept for tests + private networks.
+ * DO NOT expose on a public endpoint. Use createHandler() there.
+ */
+function handler(req, res) {
+  var topics = parseTopics(req);
+  if (topics.length === 0) {
+    return res.status(400).json({ error: 'topics query parameter required (e.g. ?topics=job:1,movement:2)' });
+  }
+  return attachStream(req, res, topics);
+}
+
+/**
+ * PRODUCTION handler factory. Requires a ticket. Returns an Express
+ * handler that:
+ *   1. Reads ?ticket=... from query
+ *   2. Calls opts.validateTicket(ticket) → { userId, scopes } | null
+ *   3. Calls opts.authorizeTopics(payload, requestedTopics) → allowed[]
+ *      (default policy: rewrite user:me:* → user:<uid>:*, enforce scopes)
+ *   4. Attaches the stream ONLY to the intersection
+ *
+ * @param {object}   opts
+ * @param {Function} opts.validateTicket    — async (ticket) => payload | null
+ * @param {Function} [opts.authorizeTopics] — (payload, requested[]) => allowed[]
+ * @returns {Function} Express handler
+ */
+function createHandler(opts) {
+  opts = opts || {};
+  if (typeof opts.validateTicket !== 'function') {
+    throw new Error('sse.createHandler: opts.validateTicket is required (pass ticketService.consumeTicket from xeplr-auth, or your own).');
+  }
+  var validateTicket  = opts.validateTicket;
+  var authorizeTopics = opts.authorizeTopics || defaultAuthorizeTopics;
+
+  return async function(req, res) {
+    var ticket = req.query && req.query.ticket;
+    if (!ticket) {
+      return res.status(401).json({ error: 'ticket query parameter required' });
+    }
+    var requested = parseTopics(req);
+    if (requested.length === 0) {
+      return res.status(400).json({ error: 'topics query parameter required (e.g. ?topics=user:me:jobs)' });
+    }
+
+    var payload;
+    try { payload = await validateTicket(ticket); }
+    catch (_) { return res.status(500).json({ error: 'ticket validation failed' }); }
+    if (!payload) return res.status(401).json({ error: 'invalid or expired ticket' });
+
+    var allowed;
+    try { allowed = authorizeTopics(payload, requested) || []; }
+    catch (_) { return res.status(500).json({ error: 'topic authorization failed' }); }
+    if (!allowed.length) {
+      return res.status(403).json({ error: 'no requested topics are authorized' });
+    }
+
+    return attachStream(req, res, allowed);
+  };
+}
+
+// ── default authorization policy ─────────────────────────────────────────
+//
+// Consumers pass a `scopes` array in the ticket payload. Scopes are glob
+// patterns; `user:me:*` is a well-known shorthand for "the authenticated
+// user's own namespace" and is rewritten to `user:<userId>:*`.
+//
+// Every requested topic must:
+//   · match at least ONE scope pattern (after rewrite), AND
+//   · if the topic starts with `user:`, the userId segment must match
+//     the authenticated user (defense in depth against a scope that
+//     accidentally allows `user:*:jobs`)
+//
+// Returns the allowed subset. Topics that fail either check are dropped
+// silently — the handler decides how to respond when the result is empty.
+function defaultAuthorizeTopics(payload, requested) {
+  var uid = String(payload && payload.userId);
+  if (!uid) return [];
+  var scopes = (payload && Array.isArray(payload.scopes) && payload.scopes.length)
+    ? payload.scopes
+    : ['user:me:*'];
+
+  var rewrittenScopes = scopes.map(function(s) {
+    return s.replace(/user:me:/g, 'user:' + uid + ':');
+  });
+
+  return requested
+    .map(function(t) { return t.replace(/^user:me:/, 'user:' + uid + ':'); })
+    .filter(function(t) {
+      // Never allow accessing another user's namespace, regardless of scope.
+      var m = t.match(/^user:([^:]+):/);
+      if (m && m[1] !== uid) return false;
+      return rewrittenScopes.some(function(scope) { return globMatch(scope, t); });
+    });
+}
+
+function globMatch(pattern, topic) {
+  var parts = pattern.split('*').map(escapeRegExp);
+  return new RegExp('^' + parts.join('.*') + '$').test(topic);
+}
+
+function escapeRegExp(s) { return s.replace(/[.+?^${}()|[\]\\]/g, '\\$&'); }
+
+/**
+ * Push an event to every subscriber of `topic`, on this worker AND across
+ * the cluster. Same API whether you're in a single-process app, a worker,
+ * or the primary.
+ */
+function publish(topic, data) {
+  publishLocal(topic, data);
+
+  if (cluster.isPrimary) {
+    // If workers exist, hand the event to each one. If they don't (single
+    // process), this loop is a no-op.
+    var workers = cluster.workers || {};
+    Object.keys(workers).forEach(function(id) {
+      var w = workers[id];
+      if (w && !w.isDead()) {
+        try { w.send(taggedMessage(topic, data)); } catch (_) {}
+      }
+    });
+  } else if (process.send) {
+    // In a worker: relay through the primary to all OTHER workers.
+    // (This process's local subscribers were already written above.)
+    broadcast(taggedMessage(topic, data));
+  }
+}
+
+// Fan out to LOCAL subscribers only. Used by both publish() and the
+// cluster-message receiver below.
+function publishLocal(topic, data) {
+  var set = _subs.get(topic);
+  if (!set || set.size === 0) return;
+  var payload = 'data: ' + JSON.stringify({ topic: topic, data: data }) + '\n\n';
+  set.forEach(function(res) {
+    try { res.write(payload); }
+    catch (_) { /* write failed — cleanup runs on close */ }
+  });
+}
+
+function taggedMessage(topic, data) {
+  var msg = { topic: topic, data: data };
+  msg[TAG] = true;
+  return msg;
+}
+
+// Install the cluster message receiver once at module load. Idempotent.
+// Runs in every worker (and harmlessly in single-process mode where
+// process.on('message') never fires without a parent).
+var _installed = false;
+function installReceiver() {
+  if (_installed) return;
+  _installed = true;
+  process.on('message', function(msg) {
+    if (msg && msg[TAG]) publishLocal(msg.topic, msg.data);
+  });
+}
+installReceiver();
+
+// ── test-only helpers ────────────────────────────────────────────────────
+function _reset() {
+  _subs.forEach(function(set) {
+    set.forEach(function(res) { try { res.end(); } catch (_) {} });
+  });
+  _subs.clear();
+}
+function _stats() {
+  var out = { topics: {}, totalConnections: 0 };
+  _subs.forEach(function(set, topic) {
+    out.topics[topic] = set.size;
+    out.totalConnections += set.size;
+  });
+  return out;
+}
+
+module.exports = {
+  handler:                 handler,           // legacy — unauthenticated
+  createHandler:           createHandler,     // production — ticket auth
+  defaultAuthorizeTopics:  defaultAuthorizeTopics,  // exported for reuse in custom policies
+  publish:                 publish,
+  _reset:                  _reset,
+  _stats:                  _stats
+};

package/lib/uploadRoute.js

@@ -0,0 +1,56 @@
+var express = require('express');
+var FileUploader = require('@xeplr/utils/lib/fileUploader');
+
+/**
+ * Generic "receive a file, hand back its path" route — product/app-agnostic.
+ * Every app that needs file upload (avatars, data imports, attachments, ...)
+ * mounts this once instead of hand-rolling multer wiring; whatever the app
+ * actually DOES with the file (parse it, load it into a DB, attach it to a
+ * record) is a separate, app-specific request made AFTER this one, using the
+ * returned filePath.
+ *
+ * Usage:
+ *   var { uploadRoute } = require('@xeplr/base-apis');
+ *   app.use('/uploads', uploadRoute({ destination: './uploads', auth: authMiddleware }));
+ *
+ * Generated route:
+ *   POST /  (multipart, field name options.fieldName, default "file")
+ *     → { filePath, fileName, originalName, size, mimetype }
+ *
+ * @param {object} [options]
+ * @param {string} [options.destination='./uploads'] - disk directory to store uploaded files
+ * @param {number} [options.maxSize=5MB]
+ * @param {string[]} [options.allowedTypes=['*']]
+ * @param {string} [options.fieldName='file']
+ * @param {Function|Function[]} [options.auth] - middleware(s) to run before the upload itself
+ * @returns {Router}
+ */
+function uploadRoute(options) {
+  options = options || {};
+  var router = express.Router();
+  var fieldName = options.fieldName || 'file';
+
+  var uploader = new FileUploader({
+    destination: options.destination,
+    maxSize: options.maxSize,
+    allowedTypes: options.allowedTypes
+  });
+
+  var auth = options.auth ? (Array.isArray(options.auth) ? options.auth : [options.auth]) : [];
+  var multerChain = uploader.single(fieldName);   // [authGuard(noop unless FileUploader's own auth set), multer, errorHandler]
+
+  router.post.apply(router, ['/'].concat(auth, multerChain, [function(req, res) {
+    if (!req.file) return res.status(400).json({ error: fieldName + ' is required' });
+    res.json({
+      filePath: req.file.path,
+      fileName: req.file.filename,
+      originalName: req.file.originalname,
+      size: req.file.size,
+      mimetype: req.file.mimetype
+    });
+  }]));
+
+  return router;
+}
+
+module.exports = uploadRoute;

package/package.json

@@ -1,22 +1,50 @@
 {
   "name": "@xeplr/base-apis",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Base API bootstrapper — Express and plain HTTP server factories with middleware injection",
   "main": "index.js",
-  "files": ["index.js", "lib/", "express.js"],
-  "keywords": ["express", "http", "api", "server", "bootstrap", "crud"],
+  "bin": {
+    "xeplr-check-env": "./bin/check-env.js"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "express.js",
+    "http.js",
+    "bin/"
+  ],
+  "keywords": [
+    "express",
+    "http",
+    "api",
+    "server",
+    "bootstrap",
+    "crud"
+  ],
   "author": "xeplr",
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/Xeplr/xeplr-base-apis" },
-  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-base-apis"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.6",
     "debug": "^4.4.3",
     "http-errors": "^2.0.1",
-    "@xeplr/logs": "^1.0.0"
+    "@xeplr/logs": "^1.0.0",
+    "@xeplr/utils": "^1.0.0"
   },
   "peerDependencies": {
-    "express": "^4.0.0 || ^5.0.0"
+    "express": "^4.0.0 || ^5.0.0",
+    "multer": "^1.4.5-lts.1"
+  },
+  "peerDependenciesMeta": {
+    "multer": {
+      "optional": true
+    }
   }
 }