effectus

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2026 License: MIT Imports: 1 Imported by: 0

README

Effectus

Effectus logo

Documentation · Getting started · Releases

Effectus is a typed rule compiler and execution runtime. It compiles .eff and .effx sources into checked protobuf IR.

The production daemon uses one durable execution engine for HTTP, Kafka, generated gRPC, and recovery work.

What Effectus provides

  • Static checks for fact paths, verb arguments, result bindings, and declared types
  • Deterministic checked artifacts and content digests
  • Immutable runtime generations with atomic activation
  • Durable admission, execution, recovery, and saga state in PostgreSQL
  • HTTP, Kafka, generated gRPC, CDC, SQL, S3, Iceberg, AMQP, Redis, and file adapters
  • JSON and signed OCI extension bundles
  • A status API, web UI, metrics, health probes, and a Helm chart

Execution boundary

Effectus controls internal admission and execution state. It does not make an external service transactional.

External destinations must enforce the supplied idempotency key or fencing token. Compensation is recovery work, not an ACID rollback.

Read Runtime Guarantees before you use Effectus in production.

Install

Download prebuilt binaries, checksums, SBOMs, and signatures from the latest release.

Build from source when you need the examples or development tools:

git clone https://github.com/josephjohncox/effectus.git
cd effectus
git checkout v0.3.0
just build
export PATH="$PWD/bin:$PATH"

Follow the checked walkthrough to start PostgreSQL, compile a bundle, run effectusd, and submit facts.

Integrate Effectus

Use the embedded package when a Go service must run checked rules in process. Use effectusd for durable cross-service workflows.

Run the embedded order example:

cd examples
go run ./embedded_orders

Run the standalone daemon and business executor stack:

examples/standalone_executor/scripts/run.sh

Read the Integration Guide for both deployment models and the HTTP executor contract.

Compile rules

Define fact types and verb contracts, then write a rule:

rule "HighRiskLargeTxn" {
  when { transaction.amount > 1000 }
  then { FlagFraud(orderId: transaction.id) }
}

Create a bundle:

go run ./cmd/effectusc bundle \
  --name flow-ui-demo \
  --version 1.0.0 \
  --schema-dir examples/flow_ui_demo/schema \
  --verb-dir examples/flow_ui_demo/verbs \
  --verbschema examples/flow_ui_demo/schema/flow_verbs.json \
  --rules-dir examples/flow_ui_demo/rules \
  --output out/flow-ui-demo-bundle.json

The compiler checks each source file before it writes the bundle. Production generations contain checked first-order IR, not Go callbacks.

Run the daemon

Effectusd requires PostgreSQL for durable workflow state:

EFFECTUS_API_TOKEN="replace-me" \
EFFECTUS_POSTGRES_DSN="postgres://effectus:password@db/effectus?sslmode=require" \
  effectusd --bundle out/flow-ui-demo-bundle.json --extensions-dir examples/flow_ui_demo/extensions --http-addr :8080

Open http://localhost:8080/ui. Use /healthz for liveness and /readyz for readiness. To execute the repository's tested cold-start path, run just ui-demo-smoke.

Use environment variables or Kubernetes Secrets for credentials. Effectusd rejects secret command-line flags.

Deploy an OCI bundle

Production OCI references must use a digest. The daemon also requires an operator-provided signature verifier.

EFFECTUS_API_TOKEN="replace-me" \
EFFECTUS_POSTGRES_DSN="postgres://effectus:password@db/effectus?sslmode=require" \
  effectusd \
  --oci-ref ghcr.io/acme/rules@sha256:BUNDLE_DIGEST \
  --oci-signature-verifier /usr/local/bin/effectus-verify-oci

Deploy a new digest to publish a new generation. Effectusd does not poll mutable OCI tags.

Extend Effectus

Production effectusd supports checked HTTP, gRPC, stream, Kafka, and OCI-resolved executors. It rejects in-process Go plugins.

A Go application can use the checked embedded facade with invocation-aware handlers. Its default ledger and outbox are process-local.

Read the Integration Guide for library mode. Read Extension System for daemon executor targets.

Documentation

Read the published documentation or browse the Markdown files in this repository.

Develop

just build
just test
just lint

Use just --list to show all repository tasks. See CONTRIBUTING.md for contribution rules.

License

Effectus uses the MIT license. See LICENSE.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Invoke 

func Invoke(ctx context.Context, executor Executor, effect Effect) (interface{}, error)

Invoke executes an effect through the context-aware API when available.

func InvokeContext 

func InvokeContext(ctx context.Context, executor ContextExecutor, effect Effect) (interface{}, error)

InvokeContext executes an effect using an executor that only implements the context-aware contract. It does not require the deprecated Executor.Do method.

Types

type Compiler 

type Compiler interface {
	// CompileFile compiles a rule file to a Spec
	CompileFile(path string, schema SchemaInfo) (Spec, error)
}

Compiler is the interface implemented by both list and flow compilers

type ContextExecutor 

type ContextExecutor interface {
	DoContext(ctx context.Context, effect Effect) (result interface{}, err error)
}

ContextExecutor executes effects with cancellation and deadline propagation.

type Effect 

type Effect struct {
	Verb    string
	Payload interface{}
}

Effect represents a verb and its payload

type Executor 

type Executor interface {
	// Do executes an effect without cancellation support.
	// Deprecated: production executors should also implement ContextExecutor.
	Do(effect Effect) (result interface{}, err error)
}

Executor handles execution of effects

type Facts 

type Facts interface {
	// Get returns the value at the given path, or nil if not found
	Get(path string) (interface{}, bool)

	// Schema returns schema information about the facts
	Schema() SchemaInfo
}

Facts represents the structured input data for rules

type SchemaInfo 

type SchemaInfo interface {
	// ValidatePath checks if a path is valid according to the schema
	ValidatePath(path string) bool
}

SchemaInfo provides metadata about the fact schema

type Spec 

type Spec interface {

	// Name returns the name of the spec
	GetName() string

	// RequiredFacts returns the list of fact paths required by this spec
	RequiredFacts() []string

	// Execute runs the specification with the given facts and executor
	Execute(ctx context.Context, facts Facts, ex Executor) error
}

Spec is the interface implemented by both list.Spec and flow.Spec

Source Files

View all Source files

Directories

Path Synopsis
amqp
bufschema
files
grpc
http
iceberg
kafka
mysql
postgres
redis
s3
sql
cmd
effectusc command
effectusd command
cmd/effectusd/main.go
 cmd/effectusd/main.go
test command
Package common provides shared execution interfaces and utilities
 Package common provides shared execution interfaces and utilities
Package embedded provides a small checked-runtime facade for Go applications.
 Package embedded provides a small checked-runtime facade for Go applications.
Package executorhttp adapts an Effectus HTTP verb target to a Go handler.
 Package executorhttp adapts an Effectus HTTP verb target to a Go handler.
flow/executor.go
 flow/executor.go
gen
effectus/v1
internal
safetar
schemasources
testutils
Package invocation defines metadata that must cross every external effect boundary.
 Package invocation defines metadata that must cross every external effect boundary.
Package ir defines Effectus's callback-free, checked execution representation.
 Package ir defines Effectus's callback-free, checked execution representation.
list/executor.go
 list/executor.go
internal/db
Package schema provides saga transaction management with capability-based locking
 Package schema provides saga transaction management with capability-based locking
capability
expression
Package expression defines the narrow contracts used by expression clients.
 Package expression defines the narrow contracts used by expression clients.
fencing
Package fencing defines resource leases that issue fencing tokens.
 Package fencing defines resource leases that issue fencing tokens.
ledger
Package ledger defines durable execution admission and recovery contracts without database or queue implementations.
 Package ledger defines durable execution admission and recovery contracts without database or queue implementations.
types
Package types provides the unified type system for Effectus
 Package types provides the unified type system for Effectus
verb
Package verb provides definitions and utilities for effect verbs
 Package verb provides definitions and utilities for effect verbs
workflow
Package workflow defines durable saga and outbox contracts without storage implementations.
 Package workflow defines durable saga and outbox contracts without storage implementations.
unified/bundle.go
 unified/bundle.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.