Engine Functionality on Porch Documentation

Validation & Business Rules

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Engine enforces validation and business rules to ensure package revisions are created and modified correctly. These rules prevent invalid operations, enforce naming constraints, and maintain referential integrity across packages and revisions.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Validation & Business Rules │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Pre-Operation │ │ Constraint │ │
│ │ Validation │ ───> │ Enforcement │ │
│ │ │ │ │ │
│ │ • Lifecycle │ │ • Uniqueness │ │
│ │ • Tasks │ │ • Path Overlap │ │
│ │ • Resources │ │ • Clone Rules │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Optimistic │ │
│ │ Locking │ │
│ │ │ │
│ │ • Resource Ver │ │
│ │ • Conflict Det │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Lifecycle Validation

The Engine validates lifecycle values during package revision creation and updates:

Draft-Commit Workflow Orchestration

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Engine orchestrates a draft-commit workflow for all package revision modifications. This pattern ensures atomicity - either all changes succeed and are persisted, or none are. The workflow uses mutable drafts for changes and immutable package revisions for storage.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Draft-Commit Workflow Orchestration │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Draft Phase │ │ Commit Phase │ │
│ │ │ ───> │ │ │
│ │ • Open Draft │ │ • Close Draft │ │
│ │ • Apply Changes │ │ • Persist │ │
│ │ • Validate │ │ • Immutable │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ Rollback │ │
│ │ Mechanism │ │
│ │ │ │
│ │• Trigger On Error│ │
│ │• Does Cleanup │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Draft-Commit Pattern

The Engine uses a two-phase workflow for all package revision modifications:

Lifecycle Management

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Engine enforces a strict lifecycle state machine for package revisions that governs their mutability, visibility, and progression from draft to published state. The lifecycle system ensures that package revisions follow a controlled workflow from creation through approval to deployment, with appropriate constraints at each stage.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Lifecycle Management System │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ State Machine │ │ Validation │ │
│ │ │ ───> │ & Enforcement │ │
│ │ • Draft │ │ │ │
│ │ • Proposed │ │ • Creation │ │
│ │ • Published │ │ • Transition │ │
│ │ • Deletion │ │ • Mutation │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌──────────────────┐ │
│ │ State-Based │ │
│ │ Constraints │ │
│ │ │ │
│ │ • Mutability │ │
│ │ • Operations │ │
│ │ • Audit Trail │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Lifecycle State Machine

The lifecycle state machine defines four states that a package revision can be in:

Task Coordination

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Engine coordinates task execution by delegating to the Task Handler. Tasks represent operations that transform package content (init, clone, edit, upgrade, render). The Engine orchestrates when and how tasks are executed, while the Task Handler implements the actual transformations.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│ Task Coordination System │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Engine │ │ Task Handler │ │
│ │ Orchestration │ ───> │ Execution │ │
│ │ │ │ │ │
│ │ • When to Run │ │ • Init │ │
│ │ • Draft Mgmt │ │ • Clone │ │
│ │ • Error Handle │ │ • Edit │ │
│ └──────────────────┘ │ • Upgrade │ │
│ │ │ • Render │ │
│ │ └──────────────────┘ │
│ ↓ │ │
│ ┌──────────────────┐ ↓ │
│ │ Function │ ┌──────────────────┐ │
│ │ Runtime │ <─── │ Builtin Funcs │ │
│ │ │ │ │ │
│ │ • gRPC │ │ • set-namespace │ │
│ │ • Builtin │ │ • ensure-context│ │
│ └──────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘

Task Handler Integration

The Engine integrates with the Task Handler through three main operations: