x-openapi-flow 1.4.3 → 1.5.0

package/lib/runtime-guard/express.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const { createRuntimeFlowGuard, toErrorPayload } = require("./core");
+
+function resolveExpressOperationId(req) {
+  if (req && req.openapi && req.openapi.operationId) {
+    return req.openapi.operationId;
+  }
+
+  if (req && req.operation && req.operation.operationId) {
+    return req.operation.operationId;
+  }
+
+  return null;
+}
+
+function defaultExpressPath(req) {
+  if (!req) {
+    return "/";
+  }
+
+  if (typeof req.path === "string") {
+    return req.path;
+  }
+
+  if (typeof req.originalUrl === "string") {
+    return req.originalUrl.split("?")[0];
+  }
+
+  if (typeof req.url === "string") {
+    return req.url.split("?")[0];
+  }
+
+  return "/";
+}
+
+function createExpressFlowGuard(options = {}) {
+  const guard = createRuntimeFlowGuard({
+    ...options,
+    resolveOperationId: options.resolveOperationId || ((context) => resolveExpressOperationId(context.req)),
+  });
+
+  return async function xOpenApiFlowExpressGuard(req, res, next) {
+    try {
+      await guard.enforce({
+        req,
+        res,
+        method: req && req.method,
+        path: defaultExpressPath(req),
+        params: (req && req.params) || {},
+      });
+      return next();
+    } catch (error) {
+      const payload = {
+        error: toErrorPayload(error),
+      };
+
+      const statusCode = (error && error.statusCode) || 500;
+      if (res && typeof res.status === "function" && typeof res.json === "function") {
+        return res.status(statusCode).json(payload);
+      }
+
+      return next(error);
+    }
+  };
+}
+
+module.exports = {
+  createExpressFlowGuard,
+};

package/lib/runtime-guard/fastify.js

@@ -0,0 +1,65 @@
+"use strict";
+
+const { createRuntimeFlowGuard, toErrorPayload } = require("./core");
+
+function resolveFastifyOperationId(request) {
+  const routeConfig = request
+    && request.routeOptions
+    && request.routeOptions.config;
+
+  if (routeConfig && typeof routeConfig.operationId === "string") {
+    return routeConfig.operationId;
+  }
+
+  return null;
+}
+
+function defaultFastifyPath(request) {
+  if (!request) {
+    return "/";
+  }
+
+  if (request.routeOptions && request.routeOptions.url) {
+    return request.routeOptions.url;
+  }
+
+  if (typeof request.routerPath === "string") {
+    return request.routerPath;
+  }
+
+  if (typeof request.url === "string") {
+    return request.url.split("?")[0];
+  }
+
+  return "/";
+}
+
+function createFastifyFlowGuard(options = {}) {
+  const guard = createRuntimeFlowGuard({
+    ...options,
+    resolveOperationId: options.resolveOperationId || ((context) => resolveFastifyOperationId(context.req)),
+  });
+
+  return async function xOpenApiFlowFastifyGuard(request, reply) {
+    try {
+      await guard.enforce({
+        req: request,
+        reply,
+        method: request && request.method,
+        path: defaultFastifyPath(request),
+        params: (request && request.params) || {},
+      });
+    } catch (error) {
+      const statusCode = (error && error.statusCode) || 500;
+      return reply.code(statusCode).send({
+        error: toErrorPayload(error),
+      });
+    }
+
+    return undefined;
+  };
+}
+
+module.exports = {
+  createFastifyFlowGuard,
+};

package/lib/runtime-guard/index.js

@@ -0,0 +1,15 @@
+"use strict";
+
+const { createRuntimeFlowGuard, RuntimeFlowGuard, toErrorPayload } = require("./core");
+const { createExpressFlowGuard } = require("./express");
+const { createFastifyFlowGuard } = require("./fastify");
+const { FlowGuardError } = require("./errors");
+
+module.exports = {
+  createRuntimeFlowGuard,
+  RuntimeFlowGuard,
+  createExpressFlowGuard,
+  createFastifyFlowGuard,
+  FlowGuardError,
+  toErrorPayload,
+};

package/lib/runtime-guard/model.js

@@ -0,0 +1,85 @@
+"use strict";
+
+const { createStateMachineAdapterModel, normalizePathTemplate, routeKey } = require("../openapi-state-machine-adapter");
+const { createStateMachineEngine } = require("../state-machine-engine");
+
+function buildPathRegex(pathTemplate) {
+  const escaped = normalizePathTemplate(pathTemplate)
+    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    .replace(/\\\{[^}]+\\\}/g, "[^/]+");
+
+  return new RegExp(`^${escaped}$`);
+}
+
+function indexOperations(operations) {
+  const byOperationId = new Map();
+  const byRouteKey = new Map();
+
+  for (const operation of operations) {
+    const indexed = {
+      ...operation,
+      incomingFromStates: new Set(),
+    };
+
+    byOperationId.set(indexed.operationId, indexed);
+    byRouteKey.set(indexed.routeKey, indexed);
+  }
+
+  // Build incoming transition map. Priority for explicit next_operation_id.
+  const machineTransitions = [];
+
+  for (const source of operations) {
+    for (const transition of source.transitions) {
+      if (transition.next_operation_id && byOperationId.has(transition.next_operation_id)) {
+        const targetByOperation = byOperationId.get(transition.next_operation_id);
+        targetByOperation.incomingFromStates.add(source.currentState);
+
+        machineTransitions.push({
+          from: source.currentState,
+          action: transition.next_operation_id,
+          to: targetByOperation.currentState,
+        });
+        continue;
+      }
+
+      // Fallback for flows without next_operation_id: map by target_state -> current_state.
+      if (!transition.target_state) {
+        continue;
+      }
+
+      for (const target of byOperationId.values()) {
+        if (target.currentState === transition.target_state) {
+          target.incomingFromStates.add(source.currentState);
+
+          machineTransitions.push({
+            from: source.currentState,
+            action: target.operationId,
+            to: target.currentState,
+          });
+        }
+      }
+    }
+  }
+
+  const stateMachine = createStateMachineEngine({
+    transitions: machineTransitions,
+  });
+
+  return {
+    operations: [...byOperationId.values()],
+    byOperationId,
+    byRouteKey,
+    stateMachine,
+  };
+}
+
+function loadRuntimeModel(options) {
+  const model = createStateMachineAdapterModel(options || {});
+  return indexOperations(model.operations);
+}
+
+module.exports = {
+  loadRuntimeModel,
+  normalizePathTemplate,
+  routeKey,
+};

package/lib/runtime-guard.js

@@ -0,0 +1,3 @@
+"use strict";
+
+module.exports = require("./runtime-guard/index.js");

package/lib/state-machine-engine.js

@@ -0,0 +1,208 @@
+"use strict";
+
+function normalizeState(value) {
+  return value == null ? null : String(value);
+}
+
+function normalizeAction(value) {
+  return value == null ? null : String(value);
+}
+
+function validateDefinition(definition) {
+  const errors = [];
+
+  if (!definition || typeof definition !== "object") {
+    return {
+      ok: false,
+      errors: ["State machine definition must be an object."],
+    };
+  }
+
+  if (!Array.isArray(definition.transitions)) {
+    return {
+      ok: false,
+      errors: ["State machine definition requires a transitions array."],
+    };
+  }
+
+  for (let index = 0; index < definition.transitions.length; index += 1) {
+    const transition = definition.transitions[index];
+
+    if (!transition || typeof transition !== "object") {
+      errors.push(`Transition at index ${index} must be an object.`);
+      continue;
+    }
+
+    const from = normalizeState(transition.from);
+    const action = normalizeAction(transition.action);
+    const to = normalizeState(transition.to);
+
+    if (!from) {
+      errors.push(`Transition at index ${index} has invalid 'from' state.`);
+    }
+    if (!action) {
+      errors.push(`Transition at index ${index} has invalid 'action'.`);
+    }
+    if (!to) {
+      errors.push(`Transition at index ${index} has invalid 'to' state.`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+class StateMachineEngine {
+  constructor(definition) {
+    const validation = validateDefinition(definition);
+    if (!validation.ok) {
+      throw new Error(`Invalid state machine definition: ${validation.errors.join(" ")}`);
+    }
+
+    this._transitions = [];
+    this._states = new Set();
+    this._actionsByState = new Map();
+    this._nextStateByStateAndAction = new Map();
+
+    for (const transition of definition.transitions) {
+      const from = normalizeState(transition.from);
+      const action = normalizeAction(transition.action);
+      const to = normalizeState(transition.to);
+
+      const key = `${from}::${action}`;
+      const existing = this._nextStateByStateAndAction.get(key);
+      if (existing && existing !== to) {
+        throw new Error(
+          `Non-deterministic transition detected for state '${from}' and action '${action}': '${existing}' vs '${to}'.`
+        );
+      }
+
+      if (!existing) {
+        this._nextStateByStateAndAction.set(key, to);
+        this._transitions.push({ from, action, to });
+      }
+
+      if (!this._actionsByState.has(from)) {
+        this._actionsByState.set(from, new Set());
+      }
+      this._actionsByState.get(from).add(action);
+
+      this._states.add(from);
+      this._states.add(to);
+    }
+
+    this._transitions.sort((a, b) => {
+      if (a.from !== b.from) return a.from.localeCompare(b.from);
+      if (a.action !== b.action) return a.action.localeCompare(b.action);
+      return a.to.localeCompare(b.to);
+    });
+  }
+
+  canTransition(currentState, action) {
+    const from = normalizeState(currentState);
+    const op = normalizeAction(action);
+    if (!from || !op) {
+      return false;
+    }
+
+    return this._nextStateByStateAndAction.has(`${from}::${op}`);
+  }
+
+  getNextState(currentState, action) {
+    const from = normalizeState(currentState);
+    const op = normalizeAction(action);
+    if (!from || !op) {
+      return null;
+    }
+
+    return this._nextStateByStateAndAction.get(`${from}::${op}`) || null;
+  }
+
+  getAvailableActions(currentState) {
+    const from = normalizeState(currentState);
+    if (!from) {
+      return [];
+    }
+
+    const actions = this._actionsByState.get(from);
+    if (!actions) {
+      return [];
+    }
+
+    return [...actions].sort((a, b) => a.localeCompare(b));
+  }
+
+  validateFlow(options = {}) {
+    const actions = Array.isArray(options.actions) ? options.actions : [];
+    const startState = normalizeState(options.startState);
+
+    if (!startState) {
+      return {
+        ok: false,
+        error: {
+          code: "INVALID_START_STATE",
+          message: "startState is required.",
+          index: -1,
+        },
+      };
+    }
+
+    let currentState = startState;
+
+    for (let index = 0; index < actions.length; index += 1) {
+      const action = normalizeAction(actions[index]);
+      if (!action) {
+        return {
+          ok: false,
+          error: {
+            code: "INVALID_ACTION",
+            message: `Action at index ${index} is invalid.`,
+            index,
+            state: currentState,
+          },
+        };
+      }
+
+      if (!this.canTransition(currentState, action)) {
+        return {
+          ok: false,
+          error: {
+            code: "INVALID_TRANSITION",
+            message: `Cannot apply action '${action}' from state '${currentState}'.`,
+            index,
+            state: currentState,
+            action,
+            availableActions: this.getAvailableActions(currentState),
+          },
+        };
+      }
+
+      currentState = this.getNextState(currentState, action);
+    }
+
+    return {
+      ok: true,
+      finalState: currentState,
+    };
+  }
+
+  getTransitions() {
+    return this._transitions.map((transition) => ({ ...transition }));
+  }
+
+  getStates() {
+    return [...this._states].sort((a, b) => a.localeCompare(b));
+  }
+}
+
+function createStateMachineEngine(definition) {
+  return new StateMachineEngine(definition);
+}
+
+module.exports = {
+  StateMachineEngine,
+  createStateMachineEngine,
+  validateDefinition,
+};