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:

Function Evaluation

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

Overview

Function evaluation is hosted by the Engine. porch-server runs the in-process pod evaluator and exposes it over FunctionEvaluator gRPC so the PackageRevision controller can use the same instance. The Engine chains builtin Go functions, the Function Runner executable evaluator (via gRPC exec_path), and the pod evaluator. The system uses a strategy pattern where different evaluators handle function execution in different ways (pod-based, executable, or chained), all conforming to a common interface.

Pod Lifecycle Management

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

Overview

Pod lifecycle management orchestrates the complete lifecycle of function execution pods from creation through caching, reuse, and eventual garbage collection. The system maintains a pool of ready-to-use pods for frequently executed functions while automatically cleaning up unused pods based on time-to-live policies.

The architecture consists of two primary components:

Pod Cache Manager - Central coordinator running in a single goroutine that manages the pod cache, handles evaluation requests, processes pod readiness notifications, and performs periodic garbage collection. Uses channels for all communication to eliminate mutex synchronization.

Image and Registry Management

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

Overview

The Engine pod evaluator manages container image metadata and registry authentication to optimize pod creation and support private registries. The system caches image metadata (digest and entrypoint) to avoid repeated registry calls, handles authentication for private registries using Docker config format, and supports TLS configuration for secure registry connections.

High-Level Architecture

┌──────────────────────────────────────────────────────────┐
│ Image and Registry Management │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Image │ │ Registry │ │
│ │ Metadata │ ───> │ Authentication │ │
│ │ Caching │ │ │ │
│ │ │ │ • Default │ │
│ │ • Digest │ │ • Custom Auth │ │
│ │ • Entrypoint │ │ • TLS Config │ │
│ │ • In-Memory │ │ │ │
│ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ ↓ │
│ ┌───────────────────┐ │
│ │ Secret │ │
│ │ Management │ │
│ │ │ │
│ │ • Creation │ │
│ │ • Synchronization│ │
│ │ • Pod Injection │ │
│ └───────────────────┘ │
└──────────────────────────────────────────────────────────┘

Image Metadata Caching

The pod manager caches image metadata to avoid repeated registry API calls during pod creation.