@xeplr/workflow-engine 0.0.0-stage → 1.0.1

package/models/Workflow.js

@@ -0,0 +1,67 @@
+var { BaseModel } = require('@xeplr/db');
+
+// The document. Mounted through genericRoute as the parent of `steps` — one
+// POST /workflows/save writes the workflow and its whole step list in a
+// single transaction (see routes/index.js). Everything about a RUN of this
+// document — WorkflowRun, WorkflowStepRun, WorkflowResumeKey,
+// WorkflowRunEdge — is deliberately a separate model family, not part of
+// this hierarchy: a run is not something you edit by saving the workflow.
+
+class Workflow extends BaseModel {
+  static get tableName() { return 'workflows'; }
+  static get idColumn() { return 'id'; }
+
+  static get jsonSchema() {
+    return {
+      type: 'object',
+      required: ['id', 'name'],
+      properties: {
+        id: { type: 'string', maxLength: 25 },
+        name: { type: 'string', maxLength: 255 },
+        // A STABLE, AUTHOR-CHOSEN HANDLE, and only a FLOW has one. The flows
+        // facade addresses a flow by key in its URLs (GET /flows/:key), so the
+        // app that designs the screens refers to it by a name it chose rather
+        // than by an id this database minted. Null for every ordinary
+        // workflow — the builder finds those by id. See migrations/0013.
+        key: { type: ['string', 'null'], maxLength: 64 },
+        description: { type: ['string', 'null'], maxLength: 1000 },
+        // [{ name, type, required, default, description, order }]
+        params: { type: ['array', 'null'] },
+        // WHAT STARTS A RUN, as the designer recorded it — { kind, … }, one
+        // shape per kind (see migrations/0014). The engine does not arm
+        // anything from it yet; it is the intent the arming work will read.
+        trigger: { type: ['object', 'null'] },
+        status: { type: 'string', maxLength: 20 },
+        // WHAT THE BUILDER OFFERS, not what the engine does — 'workflow' (the
+        // action catalogue), 'jobs' (the job list), or 'screens' (a flow,
+        // designed in another app entirely through the /flows facade and
+        // read-only in this product's own builder). workflowRunner never reads
+        // it. See migrations/0012 and 0013.
+        kind: { type: 'string', enum: ['workflow', 'jobs', 'screens', 'job-chain'] },
+        isActive: { type: 'boolean' },
+        recordCreatedDate: { type: ['string', 'null'] },
+        recordModifiedDate: { type: ['string', 'null'] },
+        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
+        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
+      }
+    };
+  }
+
+  $beforeInsert() {
+    super.$beforeInsert();
+    if (!this.status) this.status = 'draft';
+  }
+
+  static get relationMappings() {
+    var WorkflowStep = require('./WorkflowStep');
+    return {
+      steps: {
+        relation: BaseModel.HasManyRelation,
+        modelClass: WorkflowStep,
+        join: { from: 'workflows.id', to: 'workflow_steps.workflowId' }
+      }
+    };
+  }
+}
+
+module.exports = Workflow;

package/models/WorkflowResumeKey.js

@@ -0,0 +1,32 @@
+var { BaseModel } = require('@xeplr/db');
+
+// The entire wait/resume mechanism lives behind this one table — see
+// 0007_workflow_resume_keys.sql for the reasoning. Nothing outside
+// lib/workflowRunner.js should query this model directly; the public surface
+// is workflowRunner.resumeByKey(key, output).
+
+class WorkflowResumeKey extends BaseModel {
+  static get tableName() { return 'workflow_resume_keys'; }
+  static get idColumn() { return 'id'; }
+
+  static get jsonSchema() {
+    return {
+      type: 'object',
+      required: ['id', 'runId', 'stepId', 'key'],
+      properties: {
+        id: { type: 'string', maxLength: 25 },
+        runId: { type: 'string', maxLength: 25 },
+        stepId: { type: 'string', maxLength: 25 },
+        key: { type: 'string', maxLength: 64 },
+        consumedDate: { type: ['string', 'null'] },
+        isActive: { type: 'boolean' },
+        recordCreatedDate: { type: ['string', 'null'] },
+        recordModifiedDate: { type: ['string', 'null'] },
+        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
+        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
+      }
+    };
+  }
+}
+
+module.exports = WorkflowResumeKey;

package/models/WorkflowRun.js

@@ -0,0 +1,64 @@
+var { BaseModel } = require('@xeplr/db');
+
+// One occurrence of a Workflow. Not part of the workflow document's
+// genericRoute hierarchy — a run is created and driven by lib/workflowRunner,
+// never hand-edited via a document save. Deliberately independent of
+// @xeplr/jobs' Job/JobOccurrence: a workflow ties multiple steps (and, later,
+// possibly jobs) together, but owns its own execution bookkeeping rather than
+// borrowing theirs.
+
+class WorkflowRun extends BaseModel {
+  static get tableName() { return 'workflow_runs'; }
+  static get idColumn() { return 'id'; }
+
+  static get jsonSchema() {
+    return {
+      type: 'object',
+      required: ['id', 'workflowId', 'status'],
+      properties: {
+        id: { type: 'string', maxLength: 25 },
+        workflowId: { type: 'string', maxLength: 25 },
+        status: { type: 'string', enum: ['queued', 'running', 'waiting', 'success', 'failed'] },
+        params: { type: ['object', 'null'] },
+        // Set only on a child run spawned by an 'each' transition — the one
+        // element this occurrence exists to process. See WorkflowRunEdge.
+        item: { type: ['object', 'null'] },
+        trigger: { type: ['string', 'null'], maxLength: 64 },
+        startedAt: { type: ['string', 'null'] },
+        finishedAt: { type: ['string', 'null'] },
+        durationMs: { type: ['integer', 'null'] },
+        error: { type: ['object', 'null'] },
+        isActive: { type: 'boolean' },
+        recordCreatedDate: { type: ['string', 'null'] },
+        recordModifiedDate: { type: ['string', 'null'] },
+        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
+        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
+      }
+    };
+  }
+
+  $beforeInsert() {
+    super.$beforeInsert();
+    if (!this.status) this.status = 'queued';
+    if (!this.trigger) this.trigger = 'manual';
+  }
+
+  static get relationMappings() {
+    var Workflow = require('./Workflow');
+    var WorkflowStepRun = require('./WorkflowStepRun');
+    return {
+      workflow: {
+        relation: BaseModel.BelongsToOneRelation,
+        modelClass: Workflow,
+        join: { from: 'workflow_runs.workflowId', to: 'workflows.id' }
+      },
+      stepRuns: {
+        relation: BaseModel.HasManyRelation,
+        modelClass: WorkflowStepRun,
+        join: { from: 'workflow_runs.id', to: 'workflow_step_runs.runId' }
+      }
+    };
+  }
+}
+
+module.exports = WorkflowRun;

package/models/WorkflowRunEdge.js

@@ -0,0 +1,49 @@
+var { BaseModel } = require('@xeplr/db');
+
+// The only place a run's family tree lives — see 0008_workflow_run_edges.sql.
+// workflow_steps stays flat; fan-out ancestry is entirely a run-time fact
+// recorded here, never something an authored step definition carries.
+
+class WorkflowRunEdge extends BaseModel {
+  static get tableName() { return 'workflow_run_edges'; }
+  static get idColumn() { return 'id'; }
+
+  static get jsonSchema() {
+    return {
+      type: 'object',
+      required: ['id', 'parentRunId', 'childRunId'],
+      properties: {
+        id: { type: 'string', maxLength: 25 },
+        parentRunId: { type: 'string', maxLength: 25 },
+        childRunId: { type: 'string', maxLength: 25 },
+        sourceStepKey: { type: ['string', 'null'], maxLength: 64 },
+        itemIndex: { type: ['integer', 'null'] },
+        itemKey: { type: ['string', 'null'], maxLength: 255 },
+        item: { type: ['object', 'null'] },
+        isActive: { type: 'boolean' },
+        recordCreatedDate: { type: ['string', 'null'] },
+        recordModifiedDate: { type: ['string', 'null'] },
+        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
+        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
+      }
+    };
+  }
+
+  static get relationMappings() {
+    var WorkflowRun = require('./WorkflowRun');
+    return {
+      parentRun: {
+        relation: BaseModel.BelongsToOneRelation,
+        modelClass: WorkflowRun,
+        join: { from: 'workflow_run_edges.parentRunId', to: 'workflow_runs.id' }
+      },
+      childRun: {
+        relation: BaseModel.BelongsToOneRelation,
+        modelClass: WorkflowRun,
+        join: { from: 'workflow_run_edges.childRunId', to: 'workflow_runs.id' }
+      }
+    };
+  }
+}
+
+module.exports = WorkflowRunEdge;

package/models/WorkflowStep.js

@@ -0,0 +1,66 @@
+var { BaseModel } = require('@xeplr/db');
+
+class WorkflowStep extends BaseModel {
+  static get tableName() { return 'workflow_steps'; }
+  static get idColumn() { return 'id'; }
+
+  static get jsonSchema() {
+    return {
+      type: 'object',
+      required: ['id', 'workflowId', 'stepKey', 'actionName'],
+      properties: {
+        id: { type: 'string', maxLength: 25 },
+        workflowId: { type: 'string', maxLength: 25 },
+        stepKey: { type: 'string', maxLength: 64 },
+        name: { type: ['string', 'null'], maxLength: 255 },
+        actionName: { type: 'string', maxLength: 128 },
+        values: { type: ['object', 'null'] },
+        kind: { type: 'string', enum: ['auto', 'wait'] },
+        timeoutMs: { type: ['integer', 'null'] },
+        onError: { type: 'string', enum: ['stop', 'continue'] },
+        // [{ condition: expressionHandlerExpr|null, mode: 'single'|'each', target: stepKey|'end_success'|'end_failed' }]
+        transitions: { type: ['array', 'null'] },
+        joinStep: { type: ['string', 'null'], maxLength: 64 },
+        position: { type: 'integer' },
+        // { x, y } canvas pixels — where the builder draws this step. Purely
+        // visual; never read by workflowRunner. See migrations/0009.
+        layout: { type: ['object', 'null'] },
+        // An EXAMPLE of what this step returns, for the builder's field
+        // picker — never what it did return (that is on workflow_step_runs),
+        // and never read by workflowRunner. See migrations/0010.
+        sampleOutput: { type: ['object', 'null'] },
+        // What this step needs the CALLER to supply at run start:
+        // [{ name, type, required, default, description, order, sample? }] —
+        // the same field shape as an action's inputSchema. UNLIKE layout and
+        // sampleOutput, workflowRunner DOES read this: every step's
+        // declaration unions into the schema a run is validated against
+        // before any step executes. See migrations/0011.
+        params: { type: ['array', 'null'] },
+        isActive: { type: 'boolean' },
+        recordCreatedDate: { type: ['string', 'null'] },
+        recordModifiedDate: { type: ['string', 'null'] },
+        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
+        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
+      }
+    };
+  }
+
+  $beforeInsert() {
+    super.$beforeInsert();
+    if (!this.kind) this.kind = 'auto';
+    if (!this.onError) this.onError = 'stop';
+  }
+
+  static get relationMappings() {
+    var Workflow = require('./Workflow');
+    return {
+      workflow: {
+        relation: BaseModel.BelongsToOneRelation,
+        modelClass: Workflow,
+        join: { from: 'workflow_steps.workflowId', to: 'workflows.id' }
+      }
+    };
+  }
+}
+
+module.exports = WorkflowStep;

package/models/WorkflowStepRun.js

@@ -0,0 +1,49 @@
+var { BaseModel } = require('@xeplr/db');
+
+class WorkflowStepRun extends BaseModel {
+  static get tableName() { return 'workflow_step_runs'; }
+  static get idColumn() { return 'id'; }
+
+  static get jsonSchema() {
+    return {
+      type: 'object',
+      required: ['id', 'runId', 'status'],
+      properties: {
+        id: { type: 'string', maxLength: 25 },
+        runId: { type: 'string', maxLength: 25 },
+        stepId: { type: ['string', 'null'], maxLength: 25 },
+        stepKey: { type: ['string', 'null'], maxLength: 64 },
+        actionName: { type: ['string', 'null'], maxLength: 128 },
+        status: { type: 'string', enum: ['pending', 'running', 'waiting', 'success', 'failed', 'skipped'] },
+        input: { type: ['object', 'null'] },
+        output: { type: ['object', 'null'] },
+        error: { type: ['object', 'null'] },
+        durationMs: { type: ['integer', 'null'] },
+        position: { type: 'integer' },
+        isActive: { type: 'boolean' },
+        recordCreatedDate: { type: ['string', 'null'] },
+        recordModifiedDate: { type: ['string', 'null'] },
+        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
+        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
+      }
+    };
+  }
+
+  $beforeInsert() {
+    super.$beforeInsert();
+    if (!this.status) this.status = 'pending';
+  }
+
+  static get relationMappings() {
+    var WorkflowRun = require('./WorkflowRun');
+    return {
+      run: {
+        relation: BaseModel.BelongsToOneRelation,
+        modelClass: WorkflowRun,
+        join: { from: 'workflow_step_runs.runId', to: 'workflow_runs.id' }
+      }
+    };
+  }
+}
+
+module.exports = WorkflowStepRun;

package/models/Workspace.js

@@ -0,0 +1,75 @@
+// Workspace — the second tenancy level, under a company. Plain CRUD record;
+// siloed access is granted per workspace in the auth DB. companyId is required
+// (a workspace always belongs to a company).
+//
+// Single MT level (mtLevels: 1) — a workspace row is scoped by its company
+// (mtId1) only. It doesn't have a meaningful mtId2 of its own (a workspace
+// isn't scoped "by workspace"); resources that live INSIDE a workspace
+// (workflows, runs) stay at the app's full registered level count (2: company
+// + workspace) via the default.
+var { BaseModel } = require('@xeplr/db');
+var { generateId } = require('@xeplr/utils/lib/helpers');
+
+// Cross-DB — see Company.js for the identical pattern this mirrors: a
+// CompanyAdmin's l1 grant does NOT imply l2 access (mtMembershipMiddleware
+// checks each configured level independently), so without this, entering a
+// just-created workspace 403s with "Not authorized for workspaceId ..." exactly
+// like an ungranted company did before Company.$afterInsert existed.
+function auth() { return require('../lib/auth'); }
+
+async function grantWorkspaceCreator(userId, workspaceId) {
+  var a = auth();
+  await a.ready();
+  var Role = a.model('Role');
+  var UserTenantsMapping = a.model('UserTenantsMapping');
+
+  var role = await Role.query().where({ name: 'Creator' }).first();
+  if (!role) return; // not seeded (yet) — skip rather than throw
+
+  var existing = await UserTenantsMapping.query()
+    .where({ userId: userId, level: 'l2', value: workspaceId }).first();
+  if (existing) return;
+
+  await UserTenantsMapping.query().insert({
+    id: generateId(),
+    userId: userId,
+    level: 'l2',
+    value: workspaceId,
+    roleId: role.id,
+    isActive: true
+  });
+}
+
+class Workspace extends BaseModel {
+  static get tableName() { return 'workspaces'; }
+  static get idColumn() { return 'id'; }
+  static get mtLevels() { return 1; }
+
+  static get jsonAttributes() { return ['tags']; }
+
+  static get jsonSchema() {
+    return BaseModel.schema({
+      required: ['companyId', 'name'],
+      properties: { tags: { type: ['array', 'null'] } }
+    });
+  }
+
+  // Deferred via queryContext.afterCommit — see Company.js's $afterInsert for
+  // why this can't grant inline.
+  async $afterInsert(queryContext) {
+    await super.$afterInsert(queryContext);
+    if (queryContext && queryContext.user && queryContext.user.id && Array.isArray(queryContext.afterCommit)) {
+      var userId = queryContext.user.id;
+      var workspaceId = this.id;
+      queryContext.afterCommit.push(async function() {
+        try {
+          await grantWorkspaceCreator(userId, workspaceId);
+        } catch (err) {
+          console.error('[Workspace] failed to grant Creator access to creator:', err.message);
+        }
+      });
+    }
+  }
+}
+
+module.exports = Workspace;

package/models/index.js

@@ -0,0 +1,25 @@
+// The domain models. Company and Workspace are the tenancy skeleton every
+// xeplr app starts from. Workflow/WorkflowStep are the document, mounted as a
+// genericRoute hierarchy in routes/index.js. WorkflowRun/WorkflowStepRun/
+// WorkflowResumeKey/WorkflowRunEdge are a separate family — an occurrence of
+// a workflow, driven by lib/workflowRunner, never hand-edited via a document
+// save.
+var Company = require('./Company');
+var Workspace = require('./Workspace');
+var Workflow = require('./Workflow');
+var WorkflowStep = require('./WorkflowStep');
+var WorkflowRun = require('./WorkflowRun');
+var WorkflowStepRun = require('./WorkflowStepRun');
+var WorkflowResumeKey = require('./WorkflowResumeKey');
+var WorkflowRunEdge = require('./WorkflowRunEdge');
+
+module.exports = {
+  Company: Company,
+  Workspace: Workspace,
+  Workflow: Workflow,
+  WorkflowStep: WorkflowStep,
+  WorkflowRun: WorkflowRun,
+  WorkflowStepRun: WorkflowStepRun,
+  WorkflowResumeKey: WorkflowResumeKey,
+  WorkflowRunEdge: WorkflowRunEdge
+};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@xeplr/workflow-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "license": "MIT",
+  "description": "The workflow engine — workflow's own database and tables, the action catalog, starting and resuming runs, and the flows facade. No HTTP: @xeplr/workflow-api puts the routes on top.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib/",
+    "models/",
+    "migrations/",
+    "migrations-tenants/",
+    "db/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/run.mjs"
+  },
+  "author": "xeplr",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-workflow-engine.git"
+  },
+  "peerDependencies": {
+    "@xeplr/actions": "^1.1.0",
+    "@xeplr/auth": "^1.0.0",
+    "@xeplr/db": "^1.0.0",
+    "@xeplr/expression-handler": "^2.0.0",
+    "@xeplr/schema-handler": "^1.0.0",
+    "@xeplr/utils": "^1.0.0"
+  },
+  "xeplr": {
+    "readsFromDisk": [
+      "migrations",
+      "migrations-tenants"
+    ]
+  },
+  "homepage": "https://github.com/Xeplr/xeplr-workflow-engine#readme",
+  "bugs": {
+    "url": "https://github.com/Xeplr/xeplr-workflow-engine/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@xeplr/jobs": "^2.3.0",
+    "knex": "^3.3.0"
+  }
+}