@omega.js/backend 0.1.0

package/dist/manager/helpers/context/index.js

@@ -0,0 +1,228 @@
+/**
+ * RouteContext — the per-request context every route/event/cron handler receives
+ * as `ctx` (successor to BackendAssistant, renamed cp263).
+ *
+ * One instance wraps one request/response exchange (or one trigger invocation
+ * without a res): parsed request data, logging, authentication, and the
+ * response door (respond/redirect/report) with the omega-properties header +
+ * status-code semantics.
+ *
+ * One concern per module: wiring here, everything else mixed in from siblings.
+ */
+
+const os = require('os');
+const path = require('path');
+const _ = require('lodash');
+const uuid = require('uuid');
+
+const logging = require('./logging.js');
+const respond = require('./respond.js');
+const authenticate = require('./authenticate.js');
+const parse = require('./parse.js');
+const { getClient } = require('./client-info.js');
+
+function RouteContext() {
+  const self = this;
+
+  self.meta = {};
+  self.initialized = false;
+
+  return self;
+}
+
+RouteContext.prototype.init = function (ref, options) {
+  const self = this;
+
+  // Set options
+  options = options || {};
+  options.accept = options.accept || 'json';
+  options.showOptionsLog = typeof options.showOptionsLog !== 'undefined' ? options.showOptionsLog : false;
+  options.optionsLogString = typeof options.optionsLogString !== 'undefined' ? options.optionsLogString : '\n\n\n\n\n';
+  options.fileSavePath = options.fileSavePath || process.env.npm_package_name || '';
+
+  // Set now
+  const now = new Date();
+
+  // Attached libraries - used in report()/respond()
+  self.analytics = null;
+  self.usage = null;
+  self.settings = null;
+  self.schema = null;
+
+  // Set ref FIRST so self.Manager is available below — meta.environment forwards to the
+  // Manager's canonical getEnvironment() (the Manager is the SSOT), so the Manager ref must
+  // be wired before we resolve the environment.
+  ref = ref || {};
+
+  // A context has no independent identity — it's a request-scoped face for its Manager,
+  // and forwards environment/url resolution to it. A Manager ref is REQUIRED; constructing
+  // one without it is a programming error (use Manager.RouteContext(), which injects it).
+  if (!ref.Manager || typeof ref.Manager.getEnvironment !== 'function') {
+    throw new Error('RouteContext.init(): a Manager reference is required (ref.Manager). Construct via Manager.RouteContext() so it is injected automatically.');
+  }
+
+  self.ref = {};
+  self.ref.req = ref.req || {};
+  self.ref.res = ref.res || {};
+  self.ref.admin = ref.admin || {};
+  self.ref.functions = ref.functions || {};
+  self.ref.Manager = ref.Manager;
+  self.Manager = self.ref.Manager;
+
+  // Set meta
+  self.meta = {};
+
+  self.meta.startTime = {};
+  self.meta.startTime.timestamp = now.toISOString();
+  self.meta.startTime.timestampUNIX = Math.round((now.getTime()) / 1000);
+
+  // Outside a function invocation (CLI lane, internal helpers) the module is the manager core.
+  self.meta.name = options.functionName || process.env.FUNCTION_TARGET || 'manager';
+  self.meta.environment = options.environment || self.getEnvironment();
+  self.meta.type = options.functionType || process.env.FUNCTION_SIGNATURE_TYPE || 'unknown';
+
+  // Set ID
+  try {
+    const headers = self?.ref?.req.headers || {};
+
+    self.id = headers['function-execution-id']
+      || headers['X-Cloud-Trace-Context']
+      || self.Manager.Utilities().randomId();
+  } catch {
+    self.id = now.getTime();
+  }
+
+  // Set tag
+  self.tag = `${self.meta.name}/${self.id}`;
+
+  // Set logger prefix
+  self.logPrefix = '';
+
+  // Set stuff about request
+  self.request = {};
+  self.request.referrer = self.ref.req.headers?.referrer || self.ref.req.headers?.referer || '';
+  self.request.method = self.ref.req.method || undefined;
+
+  // Set geolocation + client data from headers (client-info.js owns the header vocabulary)
+  const client = getClient(self.ref.req.headers, self.ref.req);
+
+  self.request.geolocation = {
+    ip: client.ip,
+    continent: client.continent,
+    country: client.country,
+    region: client.region,
+    city: client.city,
+    latitude: client.latitude,
+    longitude: client.longitude,
+  };
+
+  self.request.client = {
+    userAgent: client.userAgent,
+    language: client.language,
+    platform: client.platform,
+    mobile: client.mobile,
+    url: client.url,
+  };
+
+  // Set request type
+  if (
+    self.ref.req.xhr || (self.ref.req?.headers?.accept || '').includes('json')
+    || (self.ref.req?.headers?.['content-type'] || '').includes('json')
+  ) {
+    self.request.type = 'ajax';
+  } else {
+    self.request.type = 'form';
+  }
+  self.request.url = parse.tryUrl(self);
+  self.request.path = self.ref.req.path || '';
+  self.request.user = self.Manager.User({}).properties;
+  self.request.user.authenticated = false;
+
+  // Set body and query
+  if (options.accept === 'json') {
+    self.request.body = parse.tryParse(self.ref.req.body || '{}');
+    self.request.query = parse.tryParse(self.ref.req.query || '{}');
+  }
+
+  // Set headers
+  self.request.headers = self.ref.req.headers || {};
+
+  // Merge data
+  self.request.data = _.merge({}, self.request.body, self.request.query);
+
+  // Set multipart data
+  self.request.multipartData = {
+    fields: {},
+    files: {},
+  };
+
+  // Constants
+  self.constant = {};
+  self.constant.pastTime = {};
+  self.constant.pastTime.timestamp = '1999-01-01T00:00:00Z';
+  self.constant.pastTime.timestampUNIX = 915148800;
+
+  // Visual request separator in dev logs
+  if (
+    (self.isDevelopment())
+    && ((self.request.method !== 'OPTIONS') || (self.request.method === 'OPTIONS' && options.showOptionsLog))
+    && (self.request.method !== 'undefined')
+  ) {
+    console.log(options.optionsLogString);
+  }
+
+  // Set tmpdir
+  self.tmpdir = path.resolve(os.tmpdir(), options.fileSavePath, uuid.v4());
+
+  // Set initialized
+  self.initialized = true;
+
+  return self;
+};
+
+// Environment helpers — the Manager is the SINGLE SOURCE OF TRUTH (see index.js). The
+// context is a request-scoped face for its Manager and FORWARDS these straight through,
+// so request handlers can call `ctx.getEnvironment()` / `ctx.isTesting()` and get exactly
+// the same answer as `Manager.getEnvironment()`. No duplicated env-var logic lives here.
+//
+// Returns exactly ONE of 'development' | 'testing' | 'production' (mutually exclusive,
+// testing wins). isDevelopment() is NOT true in testing; isProduction() is a real positive
+// check (never `!isDevelopment()`). Gate "anything non-production" with `!isProduction()`
+// or `isDevelopment() || isTesting()` intentionally.
+RouteContext.prototype.getEnvironment = function () {
+  return this.Manager.getEnvironment();
+};
+
+RouteContext.prototype.isDevelopment = function () {
+  return this.Manager.isDevelopment();
+};
+
+RouteContext.prototype.isProduction = function () {
+  return this.Manager.isProduction();
+};
+
+RouteContext.prototype.isTesting = function () {
+  return this.Manager.isTesting();
+};
+
+// The account this request is acting as. The usage counter used to be able to
+// answer a DIFFERENT one (the retired `setUser()` proxy-billing swap), which is
+// why this read used to prefer it; the counter now only ever holds the
+// authenticated account, so the request is the one home
+// ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)).
+RouteContext.prototype.getUser = function () {
+  const self = this;
+
+  return self.request.user;
+};
+
+// Mix in the concern modules
+Object.assign(
+  RouteContext.prototype,
+  logging.methods,
+  respond.methods,
+  authenticate.methods,
+  parse.methods,
+);
+
+module.exports = RouteContext;

package/dist/manager/helpers/context/logging.js

@@ -0,0 +1,150 @@
+/**
+ * RouteContext logging — tagged, level-aware logging for one request.
+ *
+ * Every level in LOG_LEVELS becomes a ctx method (ctx.log/warn/error/info/debug/
+ * notice/critical/emergency). Console in any non-production environment; the
+ * Firebase Cloud logger in production for levels console lacks.
+ *
+ * `debug` is the ONE opt-in level ([#230](https://github.com/Omega-JS-Stack/omega/issues/230)):
+ * it writes nothing at all unless `OMEGA_DEBUG` is set in the environment. Nothing
+ * else reads a level switch — this is what lets a caller demote a fat payload
+ * (a full UserRecord, a raw webhook body) out of the normal run and still have it
+ * one env var away. Every other level is unconditional, as before.
+ *
+ * Every line opens with the ONE identity tag, `[@omega.js/backend:<module>]`
+ * ([#121](https://github.com/Omega-JS-Stack/omega/issues/121)) — the module
+ * segment is the invocation's function name, which the ctx already knows. The
+ * invocation id and any log prefix follow the tag.
+ *
+ * In PRODUCTION the tag stands alone: Cloud Logging stamps every entry, so a
+ * hand-written time would be a second one. Outside production nothing stamps a
+ * plain local run (dist scripts, node CLIs), so the line opens with a short local
+ * time bracket instead — `[HH:MM:SS] [@omega.js/backend:<module>] ...`, the same
+ * shape the devkit's build-time logger prints
+ * ([#130](https://github.com/Omega-JS-Stack/omega/issues/130)).
+ */
+
+const LOG_LEVELS = {
+  error: 'error',
+  warn: 'warn',
+  info: 'info',
+  debug: 'debug',
+  log: 'log',
+  notice: 'NOTICE',
+  critical: 'CRITICAL',
+  emergency: 'EMERGENCY',
+};
+
+// The ONE identity tag. The module segment is the function name the ctx resolved
+// at init (options.functionName || FUNCTION_TARGET || 'manager').
+function identityTag(ctx) {
+  return `[@omega.js/backend:${ctx.meta?.name || 'unnamed'}]`;
+}
+
+// The local time bracket that opens a line outside production, or '' in production
+// where Cloud Logging stamps the entry. The emulator is NOT carved out: its `>`
+// functions prefix carries no time (verified against live emulator output), so
+// emulator lines want the stamp like any other local run. This is the ONE place ctx
+// console output is built (wonderful-log writes to file only), so stamping here
+// covers every level.
+function localTimestamp(ctx) {
+  if (ctx.isProduction()) {
+    return '';
+  }
+
+  const time = new Date().toLocaleTimeString('en-US', {
+    hour12: false,
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+
+  return `[${time}] `;
+}
+
+// The debug switch, read LIVE on every line — a process that flips OMEGA_DEBUG
+// mid-run (the emulator's env sync, a test) gets the new answer immediately.
+function isDebugEnabled() {
+  return !!process.env.OMEGA_DEBUG;
+}
+
+const methods = {
+  _log() {
+    const self = this;
+    const logs = [...arguments];
+
+    // Opt-in level: a debug line is dropped whole (console AND wonderful-log)
+    // unless the switch is on. First thing, before any formatting work.
+    if (logs[0] === 'debug' && !isDebugEnabled()) {
+      return;
+    }
+
+    const prefix = self.logPrefix ? ` ${self.logPrefix}:` : ':';
+
+    // Prepend the local time bracket (outside production only), the identity tag,
+    // the invocation id, and the log prefix
+    logs.unshift(`${localTimestamp(self)}${identityTag(self)} ${self.id}${prefix}`);
+
+    // Get the log level
+    const level = logs[1];
+
+    // Pass along arguments to console.log
+    if (LOG_LEVELS[level]) {
+      logs.splice(1, 1);
+
+      // Determine how to log. Console for any non-production environment (development OR
+      // testing); the Firebase Cloud logger only in production.
+      if (level in console) {
+        console[level].apply(console, logs);
+      } else if (!self.isProduction()) {
+        console.log.apply(console, logs);
+      } else {
+        self.ref.functions.logger.write({
+          severity: LOG_LEVELS[level].toUpperCase(),
+          message: logs,
+        });
+      }
+
+      // Write with wonderful-log
+      if (self.Manager?.libraries?.logger?.[level]) {
+        self.Manager?.libraries?.logger?.[level](...logs);
+      }
+    } else {
+      console.log.apply(console, logs);
+    }
+  },
+
+  setLogPrefix(s) {
+    const self = this;
+
+    self.logPrefix = s;
+
+    return self;
+  },
+
+  clearLogPrefix() {
+    const self = this;
+
+    self.logPrefix = '';
+
+    return self;
+  },
+
+  getLogPrefix() {
+    return this.logPrefix;
+  },
+};
+
+// One method per level, defined ONCE at module load (the legacy constructor
+// re-defined these on every instantiation)
+Object.keys(LOG_LEVELS).forEach((level) => {
+  methods[level] = function () {
+    const self = this;
+    const args = Array.prototype.slice.call(arguments);
+
+    args.unshift(level);
+    self._log.apply(self, args);
+  };
+});
+
+module.exports = { methods, LOG_LEVELS };

package/dist/manager/helpers/context/parse.js

@@ -0,0 +1,160 @@
+/**
+ * RouteContext request parsing — tolerant JSON5 body/query parsing, request-URL
+ * reconstruction, and multipart/form-data uploads (busboy).
+ */
+
+const path = require('path');
+
+let JSON5;
+
+// Tolerant parse: JSON5 when it parses, the raw input otherwise
+function tryParse(input) {
+  JSON5 = JSON5 || require('json5');
+
+  try {
+    return JSON5.parse(input);
+  } catch (e) {
+    return input;
+  }
+}
+
+// Reconstruct the request's public URL. "req.originalUrl" does NOT carry the
+// path in all cases (like when calling https://us-central1-{id}.cloudfunctions.net/fn)
+function tryUrl(self) {
+  const req = self.ref.req;
+  const Manager = self.Manager;
+  const projectType = Manager?.options?.projectType;
+
+  try {
+    const protocol = req.protocol;
+    const host = req.get('host');
+    const forwardedHost = req.get('x-forwarded-host');
+    const reqPath = req.path;
+    const functionsUrl = Manager.getFunctionsUrl();
+
+    if (projectType === 'firebase') {
+      // Non-production (development OR testing) reconstructs the URL from the local
+      // functions URL; production uses the request host.
+      if (!self.isProduction()) {
+        return forwardedHost
+          ? `${protocol}://${forwardedHost}${reqPath}`
+          : `${functionsUrl}/${self.meta.name}`;
+      } else {
+        return forwardedHost
+          ? `${protocol}://${forwardedHost}${reqPath}`
+          : `${protocol}://${host}/${self.meta.name}`;
+      }
+    } else if (projectType === 'custom') {
+      return `${protocol}://${host}${reqPath}`;
+    }
+
+    return '';
+  } catch (e) {
+    return '';
+  }
+}
+
+const methods = {
+  /**
+   * Parses a 'multipart/form-data' upload request
+   * https://cloud.google.com/functions/docs/writing/http#multipart_data
+   */
+  parseMultipartFormData(options) {
+    const self = this;
+    return new Promise(function (resolve, reject) {
+      if (!self.initialized) {
+        return reject(new Error('Cannot run .parseMultipartFormData() until .init() has been called'));
+      }
+      const existingData = self.request.multipartData;
+      const getFields = existingData?.fields || {};
+      const getFiles = existingData?.files || {};
+
+      // If there are already fields or files, return them
+      if (Object.keys(getFields).length + Object.keys(getFiles).length > 0) {
+        return resolve(existingData);
+      }
+
+      // Set options
+      options = options || {};
+
+      // Set headers
+      const fs = require('fs');
+      const req = self.ref.req;
+
+      // Node.js doesn't have a built-in multipart/form-data parsing library.
+      // Instead, we can use the 'busboy' library from NPM to parse these requests.
+      const busboy = require('busboy');
+      const jetpack = require('fs-jetpack');
+
+      options.headers = options.headers || req.headers;
+      options.limits = options.limits || {};
+
+      // https://github.com/mscdex/busboy
+      const bb = busboy({
+        headers: options.headers,
+        limits: options.limits,
+      });
+
+      // This object will accumulate all the fields, keyed by their name
+      const fields = {};
+
+      // This object will accumulate all the uploaded files, keyed by their name.
+      const uploads = {};
+
+      // This code will process each non-file field in the form.
+      bb.on('field', (fieldname, val) => {
+        fields[fieldname] = val;
+      });
+
+      const fileWrites = [];
+
+      // This code will process each file uploaded.
+      bb.on('file', (fieldname, file, info) => {
+        // Note: os.tmpdir() points to an in-memory file system on GCF
+        // Thus, any files in it must fit in the instance's memory.
+        jetpack.dir(self.tmpdir);
+
+        const filename = info.filename;
+        const filepath = path.join(self.tmpdir, filename);
+        uploads[fieldname] = filepath;
+        const writeStream = fs.createWriteStream(filepath);
+        file.pipe(writeStream);
+
+        // File was processed by Busboy; wait for it to be written.
+        // Note: GCF may not persist saved files across invocations.
+        // Persistent files must be kept in other locations
+        // (such as Cloud Storage buckets).
+        const promise = new Promise((resolve, reject) => {
+          file.on('end', () => {
+            writeStream.end();
+          });
+          writeStream.on('finish', resolve);
+          writeStream.on('error', reject);
+        });
+        fileWrites.push(promise);
+      });
+
+      // Triggered once all uploaded files are processed by Busboy.
+      // We still need to wait for the disk writes (saves) to complete.
+      bb.on('finish', async () => {
+        await Promise.all(fileWrites);
+
+        self.request.multipartData = {
+          fields: fields,
+          files: uploads,
+        };
+
+        return resolve(self.request.multipartData);
+      });
+
+      // rawBody is present on GCF/Firebase requests; piping covers custom servers
+      if (req.rawBody) {
+        return bb.end(req.rawBody);
+      } else {
+        return req.pipe(bb);
+      }
+    });
+  },
+};
+
+module.exports = { methods, tryParse, tryUrl };