@omega.js/backend 0.1.0

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

@@ -0,0 +1,247 @@
+/**
+ * RouteContext response door — the ONE home of the wire contract.
+ *
+ * - respond(payload, options): the only sender. Objects go as JSON, 3xx codes
+ *   redirect, Error payloads (or 4xx/5xx codes) take the error path. Every
+ *   response carries the omega-properties header (code, tag, usage, schema).
+ * - redirect(url, options): respond() with a 302 default.
+ * - report(error, options): decorate + log + capture WITHOUT sending — the
+ *   error factory for throw/reject sites and res-less triggers. Returns the
+ *   decorated Error.
+ *
+ * Sentry rule (cp263, replaces the per-call options.sentry/options.log dance):
+ * server-fault errors (code >= 500) capture to Sentry automatically; client
+ * faults (4xx) never do. No per-call flags.
+ */
+
+const { redactResponseForLog } = require('../middleware.js');
+
+const methods = {
+  respond(response, options) {
+    const self = this;
+    const res = self.ref.res;
+
+    // If response is a promise, wait for it to resolve and then call respond again with the resolved value
+    if (response && typeof response.then === 'function') {
+      return response
+        .then((resolved) => self.respond(resolved, options))
+        .catch((error) => self.respond(error, options));
+    }
+
+    // Structural double-respond guard — a second respond() (e.g. a route that keeps running
+    // after an error path already responded) would crash with ERR_HTTP_HEADERS_SENT
+    if (res?.headersSent) {
+      self.warn('respond() called after a response was already sent — ignoring');
+      return;
+    }
+
+    // Set options
+    options = options || {};
+    options.code = typeof options.code === 'undefined'
+      ? 200
+      : options.code;
+
+    // log: false silences the success-path body log (large payloads like served
+    // HTML); the error path always logs
+    options.log = typeof options.log === 'undefined'
+      ? true
+      : options.log;
+
+    // Fix code
+    options.code = parseInt(options.code);
+
+    // Error path: an Error payload or an error code
+    const isErrorCode = isBetween(options.code, 400, 599);
+    if (
+      response instanceof Error
+      || isErrorCode
+    ) {
+      options.code = isErrorCode ? options.code : undefined;
+
+      return _sendError(self, response, options);
+    }
+
+    // Attach properties
+    attachHeaderProperties(self, options);
+
+    // Send response
+    res.status(options.code);
+
+    // Clear log prefix before sending
+    self.clearLogPrefix();
+
+    // Redirect
+    const isRedirect = isBetween(options.code, 300, 399);
+    if (isRedirect) {
+      if (options.log) {
+        self.log(`Redirecting (${options.code}):`, JSON.stringify(response));
+      }
+
+      return res.redirect(response);
+    }
+
+    if (options.log) {
+      self.log(`Sending response (${options.code}):`, JSON.stringify(redactResponseForLog(response)));
+    }
+
+    // If it is an object, send as json
+    if (
+      response
+      && typeof response === 'object'
+      && typeof res.json === 'function'
+    ) {
+      return res.json(response);
+    } else {
+      return res.send(response);
+    }
+  },
+
+  redirect(response, options) {
+    const self = this;
+
+    // Set options
+    options = options || {};
+    options.code = typeof options.code === 'undefined'
+      ? 302
+      : options.code;
+
+    return self.respond(response, options);
+  },
+
+  // Decorate + log + capture, WITHOUT sending. Returns the decorated Error, so
+  // throw/reject sites read naturally: `throw ctx.report('Bad settings', { code: 400 })`.
+  // Also the right call in res-less contexts (auth triggers, cron) — the response
+  // header attach inside is a no-op when there is no res.
+  report(e, options) {
+    const self = this;
+
+    // Set options
+    options = options || {};
+
+    // Code: default to 500, else the caller's option; the Error's own code wins
+    // over the default (but never over an explicit option)
+    const isCodeSet = typeof options.code !== 'undefined';
+    options.code = !isCodeSet
+      ? 500
+      : options.code;
+
+    // Construct error
+    const newError = e instanceof Error
+      ? e
+      : new Error(stringifyNonStrings(e));
+
+    // Fix code
+    options.code = isCodeSet ? options.code : newError.code || options.code;
+    options.code = parseInt(options.code);
+    options.code = isBetween(options.code, 400, 599) ? options.code : 500;
+
+    // Attach properties (response header when a res exists + onto the Error itself)
+    attachHeaderProperties(self, options, newError);
+
+    // Log: server faults as real errors, client faults as a warning line
+    if (isBetween(options.code, 500, 599)) {
+      self.error(newError);
+
+      // Server faults capture to Sentry automatically — one rule, no per-call flags
+      self.Manager.libraries.sentry?.captureException?.(newError);
+    } else {
+      self.log(`⚠️ Client error (${options.code}):`, newError.message, newError.stack);
+    }
+
+    return newError;
+  },
+};
+
+// Build the decorated error via report(), then send it (respond()'s error path)
+function _sendError(self, e, options) {
+  const res = self.ref.res;
+
+  const newError = self.report(e, options);
+
+  // Respond only if this context has a res (triggers do not) and nothing was sent yet
+  if (res?.status && !res.headersSent) {
+    let sendable = newError?.stack && options.stack
+      ? newError?.stack
+      : newError?.message;
+
+    // Set error
+    sendable = `${sendable || newError || 'Unknown error'}`;
+
+    // Attach tag
+    if (newError.tag) {
+      sendable = `${sendable} (${newError.tag})`;
+    }
+
+    // Clear log prefix before sending
+    self.clearLogPrefix();
+
+    // Log
+    self.log(`Sending response (${options.code}):`, JSON.stringify(redactResponseForLog(sendable)));
+
+    // Send response
+    res
+      .status(options.code)
+      .send(sendable);
+  }
+
+  return newError;
+}
+
+// The omega-properties header: code, tag, usage current+limits, schema, additional.
+// Rides EVERY response (success and error) and is exposed to browsers via
+// Access-Control-Expose-Headers; @omega.js/client's omega.request() consumes it.
+function attachHeaderProperties(self, options, error) {
+  // Create headers
+  const headers = {
+    code: options.code,
+    tag: self.tag,
+    // What the counter already KNOWS — never a read of its own. The counter is
+    // lazy ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)), so a
+    // route that counted nothing reports nothing, and this header builder
+    // stays synchronous.
+    usage: {
+      current: self.usage ? self.usage.counters() : {},
+      limits: self.usage ? self.usage.limits() : {},
+    },
+    schema: self.schema || {},
+    additional: options.additional || {},
+  };
+  const res = self.ref.res;
+
+  // Attach properties if this context has a res (it sometimes does not, like in auth().onCreate() triggers)
+  // and only if nothing was sent yet — setting a header after send crashes with ERR_HTTP_HEADERS_SENT
+  if (res?.header && res?.get && !res.headersSent) {
+    res.header('omega-properties', JSON.stringify(headers));
+
+    // Add omega-properties to Access-Control-Expose-Headers
+    const existingExposed = res.get('Access-Control-Expose-Headers') || '';
+
+    // If it does not exist, add it
+    if (!existingExposed.match(/omega-properties/i)) {
+      const newExposed = `${existingExposed}, omega-properties`.replace(/^, /, '');
+      res.header('Access-Control-Expose-Headers', newExposed);
+    }
+  }
+
+  // Attach properties to the error itself (callers read error.code etc.)
+  if (error) {
+    Object.keys(headers)
+    .forEach((item) => {
+      error[item] = headers[item];
+    });
+  }
+}
+
+function isBetween(value, min, max) {
+  return value >= min && value <= max;
+}
+
+function stringifyNonStrings(e) {
+  if (typeof e === 'string') {
+    return e;
+  } else {
+    return JSON.stringify(e);
+  }
+}
+
+module.exports = { methods };

package/dist/manager/helpers/event-middleware.js

@@ -0,0 +1,109 @@
+/**
+ * EventMiddleware
+ * Used to handle middleware for event triggers (auth, firestore, cron)
+ *
+ * Usage in consumer projects:
+ *   exports.userOnCreate = functions
+ *     .firestore.document('users/{uid}')
+ *     .onCreate((snapshot, context) =>
+ *       Manager.EventMiddleware({ snapshot, context }).run('users/on-create')
+ *     );
+ *
+ * Handler location: functions/hooks/events/{name}.js
+ */
+
+function EventMiddleware(m, payload) {
+  const self = this;
+
+  self.Manager = m;
+  self.payload = payload;
+}
+
+EventMiddleware.prototype.run = function (handlerName, options) {
+  const self = this;
+
+  // Shortcuts
+  const Manager = self.Manager;
+  const payload = self.payload;
+
+  return new Promise(async function(resolve, reject) {
+    const ctx = Manager.RouteContext();
+    options = options || {};
+
+    // Resolve handler path
+    // If it's an absolute path, use it directly
+    // Otherwise, look in the consumer's hooks/events/ directory
+    let handlerPath;
+    if (handlerName.startsWith('/')) {
+      handlerPath = handlerName;
+    } else {
+      handlerPath = `${Manager.cwd}/events/${handlerName}.js`;
+    }
+
+    // Build context based on event type
+    const context = {
+      Manager,
+      ctx,
+      libraries: Manager.libraries,
+      // Event-specific properties (some may be undefined depending on event type)
+      user: payload.user,
+      context: payload.context,
+      change: payload.change,
+      snapshot: payload.snapshot,
+    };
+
+    // Load handler
+    let handler;
+    try {
+      handler = require(handlerPath);
+    } catch (e) {
+      // A handler that will not load is a server fault, so it goes through the
+      // SAME door a 5xx route does: report() logs it AND captures it to Sentry
+      // (#380). The require failure rides as the `cause`, keeping its own stack
+      // and code — Sentry's linked-errors integration follows the chain.
+      return reject(ctx.report(new Error(`EventMiddleware: Failed to load handler @ ${handlerPath}`, { cause: e })));
+    }
+
+    // Execute with hooks support
+    const name = ctx.meta.name;
+    const hook = Manager.handlers && Manager.handlers[name];
+
+    try {
+      // Pre hook
+      if (hook) {
+        await hook(context, 'pre');
+      }
+
+      // Main execution
+      const result = await handler(context);
+
+      // Post hook
+      if (hook) {
+        await hook(context, 'post');
+      }
+
+      return resolve(result);
+    } catch (e) {
+      // Re-throw a deliberate block untouched: it is the trigger's CLIENT fault,
+      // the 4xx lane that never captures. Exactly TWO shapes qualify — an
+      // HttpsError (its constructor always sets httpErrorCode, so that property
+      // IS how a real block is recognized) and an explicit NUMERIC 4xx code. A
+      // string `.code` (ENOENT, messaging/invalid-token) is a system error, not
+      // a block, and respond.js rules the same way: its parseInt turns a string
+      // code into NaN, which lands on the 500 lane and reports.
+      const code = parseInt(e.code);
+      if (e.httpErrorCode || (code >= 400 && code <= 499)) {
+        return reject(e);
+      }
+
+      // Anything else is a server fault: report() logs it AND captures it (#380).
+      // It decorates the SAME object in place (code/tag/usage land on the Error)
+      // and hands it back, so the rejection value the trigger sees is that one
+      // error — `e.code` reads report()'s 500 after capture. A trigger has no
+      // res, which report() handles — its header attach is a no-op there.
+      return reject(ctx.report(e));
+    }
+  });
+};
+
+module.exports = EventMiddleware;

package/dist/manager/helpers/metadata.js

@@ -0,0 +1,32 @@
+const moment = require('moment');
+const uuidv4 = require('uuid').v4;
+
+function Metadata(Manager, document) {
+  const self = this;
+
+  self.Manager = Manager;
+
+  self.document = document || {};
+
+  return self;
+}
+
+Metadata.prototype.set = function (metadata) {
+  const self = this;
+
+  const now = moment();
+
+  self.document = self.document || {};
+  self.document.metadata = self.document.metadata || {};
+
+  self.document.metadata.updated = self.document.metadata.updated || {};
+  self.document.metadata.updated.timestamp = now.toISOString();
+  self.document.metadata.updated.timestampUNIX = now.unix();
+  self.document.metadata.tag = metadata.tag || uuidv4();
+
+  self.Manager.ctx.log(`Metadata: #${self.document.metadata.tag}`);
+
+  return self.document.metadata;
+};
+
+module.exports = Metadata;