fluxpro-engine 0.1.10

A feature-gated workflow and process engine
Documentation

FluxPro Engine

fluxpro-engine is a feature-gated workflow and process engine for Rust.

The package is intentionally self-contained and can be copied to or cloned as its own repository:

https://github.com/dimm-com-ua/fluxpro-engine

The default build contains only process models, commands, context values, and the service-handler contract. Enable only the integration layers an application needs:

  • db — PostgreSQL persistence through SQLx.
  • runtime — process execution and the asynchronous task runner (includes db).
  • api — Actix Web HTTP handlers (includes runtime).
  • admin — read and safely manage process definitions, instances, contexts, stage history, and queued tasks (includes db).
  • full — all backend integrations (kept compatible; does not enable the UI).
  • editor — Leptos process authoring and monitoring components (Rust 1.88+).
  • editor-csr, editor-hydrate, editor-ssr — editor plus the corresponding Leptos rendering mode. Choose one mode per build target.
[dependencies]
fluxpro-engine = "0.1"

# Or, for a service running the engine:
fluxpro-engine = { version = "0.1", features = ["runtime"] }

The crate has no dependency on the Lendiq application or its workspace crates.

Visual process editor

The editor module exports embeddable ProcessEditor and ProcessMonitor Leptos 0.8 components from this package:

fluxpro-engine = { version = "0.1.10", features = ["editor-csr"] }
use fluxpro_engine::editor::{EditorDocument, ProcessEditor, ProcessMonitor};

The editor provides drag-and-drop authoring, YAML import/export, layout, undo/redo, and live instance monitoring. Add admin to editor-ssr for the server-side administration adapter. Leptos and browser dependencies remain optional; the default and backend full builds do not enable them.

Documentation and examples

  • Node reference: all six node types, fields, routing, signals, timeouts, retries, lifecycle hooks, and current runtime limitations.
  • Runnable examples: JSON/YAML validation, a service handler, a PostgreSQL workflow, and HTTP integration.
  • Business workflow catalog: seven definitions and 23 executable scenarios for delivery, repairs, education, lending, retail, insurance, and subscriptions.
  • Loan lifecycle: scoring, funding, repayment schedules, daily accrual, payment reconciliation, and verified closure.
  • Architecture and documentation style: module responsibilities, persistence, queue execution, administration, and checks.

Validate a definition without a database:

cargo run --example validate_process
cargo run --features api --example validate_yaml

The approval workflow combines Start, ServiceTask, UserTask, Gateway, Wait, and End. Generate the complete Rust API reference with cargo doc --features full,migration-repair,editor-ssr --no-deps.

Version 0.1.10

Queue dequeue now selects from due tasks instead of probing every running instance. Stable statement-time cutoffs and new indexes reduce idle polling work while retaining instance locking, lease rechecks, and incident recovery priority. Migrations 8–10 each build one index concurrently outside a transaction; run the engine migrator before starting updated workers. Stored task JSON and service contracts remain compatible. See maintenance details.

This release also includes the pending Rust 1.85 backend compatibility fixes and release validation workflow improvements.

Publishing

The repository is released through GitHub Releases. After creating a release whose tag matches the crate version (0.1.10 or v0.1.10), the Publish workflow checks the tag and runs the complete CI workflow before publishing the package using the repository's CARGO_REGISTRY_TOKEN secret.

To validate a release locally:

cargo fmt --all -- --check
cargo test --features full,migration-repair,editor-ssr
cargo test --no-default-features
cargo test --features editor
cargo test --features editor-ssr
cargo check --features editor-csr --target wasm32-unknown-unknown --bins
cargo check --features editor-hydrate --target wasm32-unknown-unknown
cargo rustdoc --features full,migration-repair,editor-ssr --lib -- -D missing-docs -D rustdoc::broken_intra_doc_links -D rustdoc::invalid_rust_codeblocks
cargo package
cargo package --features editor-ssr,admin

With DATABASE_URL pointing to a disposable PostgreSQL database whose user can create test databases, also run all ignored integration tests:

cargo test --features full,migration-repair,editor-ssr -- --ignored --test-threads=4

The crate's Cargo.toml, source, migrations, fixtures, licenses, and CI files are all contained in this directory; no parent workspace files are required.

Database schema

All engine-owned tables live in the dedicated fluxpro PostgreSQL schema. Applications can apply the migrations embedded in the crate:

async fn migrate(pool: &sqlx::PgPool) -> Result<(), sqlx::migrate::MigrateError> {
    fluxpro_engine::migrations::migrate(pool).await
}

For legacy databases blocked by duplicate version identities in migration 7, enable migration-repair and use migrations::legacy_versions::{plan_legacy_versions, apply_legacy_version_plan}. This opt-in preview/apply API preserves definition UUIDs and instance bindings; ordinary migrations never choose an ambiguous identity automatically. See the repair procedure before upgrading.

The engine always uses explicitly qualified table names and does not modify or depend on the connection's search_path.

Administration

Enable admin to build an administration UI without coupling the engine to a web framework:

use fluxpro_engine::admin::{
    FluxproAdminService, PageRequest, ProcessInstanceFilter,
};

async fn list_instances(pool: sqlx::PgPool) -> Result<(), fluxpro_engine::admin::AdminError> {
    let admin = FluxproAdminService::new(pool);
    let instances = admin
        .list_process_instances(ProcessInstanceFilter::default(), PageRequest::default())
        .await?;
    println!("{} instances", instances.total);
    Ok(())
}

Administrative queue retry and cancellation only affect tasks that do not have a live lease. This prevents an operator action from racing an active worker.

Queue runner

The runtime runner uses an atomic PostgreSQL dequeue with FOR UPDATE SKIP LOCKED, so multiple application instances can compete for work without serializing or executing the same lease concurrently. Active workers renew their leases with a heartbeat; an abandoned lease is automatically available to another instance after task_lease_ms.

Tasks committed by a handler wake a runner in the same engine immediately. idle_backoff_ms remains the fallback polling interval for work committed by another application instance.

For reliable failover, keep heartbeat_interval_ms comfortably below task_lease_ms. The defaults are 20 seconds and 60 seconds respectively.

Durable transitions

Queued execution commits context, node/stage state, wait completion, successor tasks, and source-task acknowledgement in one PostgreSQL transaction. Lease and instance-revision checks reject stale attempts. A signal and a timeout can close a particular wait visit only once, including when the process revisits a node. Database failures retain the source task for recovery after lease expiry.

Host handlers execute outside the transaction, so external effects still need application idempotency. See recovery and migration details. Stop and drain all old runners before applying migrations 0006–0007.

Exhausted execution failures suspend the instance with a retained task and a saved incident. Inspect it with get_open_incident and explicitly resume that incident with resume_instance. Invalid routing expressions cannot select a fallback. Handler patches persist removals atomically. Only active, effective versions may start; published versions are immutable and (key, version) is unique. Signals accept an optional stable event_id for durable deduplication and wait_visit_id for targeting a particular wait visit. See the upgrade and recovery contract.