igniter 0.4.0 → 0.4.5

data/docs/SERVER_V1.md

@@ -0,0 +1,313 @@
+# igniter-server v1
+
+igniter-server turns any Igniter contract into an HTTP service. Multiple server nodes can call
+each other using the `remote:` DSL, enabling distributed multi-node architectures with
+compile-time validated cross-node contracts.
+
+## Quick Start
+
+### Ruby API
+
+```ruby
+require "igniter/server"
+
+class ScoringContract < Igniter::Contract
+  define do
+    input :value
+    compute :score, depends_on: :value, call: ->(value:) { value * 1.5 }
+    output :score
+  end
+end
+
+Igniter::Server.configure do |c|
+  c.host = "0.0.0.0"
+  c.port = 4567
+  c.register "ScoringContract", ScoringContract
+end
+
+Igniter::Server.start  # blocking
+```
+
+### CLI
+
+```bash
+# Start server, loading contracts from a file
+igniter-server start --port 4567 --require ./contracts.rb
+
+# With a config block for additional setup
+igniter-server start --port 4567 --require ./contracts.rb --config ./server_config.rb
+```
+
+### Rack / Puma (production)
+
+```ruby
+# config.ru
+require "igniter/server"
+require_relative "contracts"
+
+Igniter::Server.configure do |c|
+  c.register "ScoringContract", ScoringContract
+  c.store = Igniter::Runtime::Stores::MemoryStore.new
+end
+
+run Igniter::Server.rack_app
+```
+
+```bash
+bundle exec puma config.ru -p 4567
+```
+
+---
+
+## Configuration
+
+```ruby
+Igniter::Server.configure do |c|
+  c.host = "0.0.0.0"          # bind address (default: "0.0.0.0")
+  c.port = 4567                # TCP port (default: 4567)
+  c.store = my_store           # execution store for distributed contracts
+  c.register "Name", MyClass   # register a contract
+  c.contracts = {              # bulk registration
+    "ContractA" => ContractA,
+    "ContractB" => ContractB
+  }
+end
+```
+
+Reset configuration (useful in tests):
+
+```ruby
+Igniter::Server.reset!
+```
+
+---
+
+## REST API Reference
+
+All responses use `Content-Type: application/json`.
+
+### `POST /v1/contracts/:name/execute`
+
+Execute a contract synchronously. For distributed contracts (`correlate_by`), this is
+equivalent to `Contract.start` and returns a `pending` response.
+
+**Request body:**
+```json
+{ "inputs": { "value": 42 } }
+```
+
+**Responses:**
+
+```json
+// Succeeded
+{ "execution_id": "uuid", "status": "succeeded", "outputs": { "score": 63.0 } }
+
+// Failed node
+{ "execution_id": "uuid", "status": "failed",
+  "error": { "type": "Igniter::ResolutionError", "message": "...", "node": "score" } }
+
+// Pending (distributed contract waiting for events)
+{ "execution_id": "uuid", "status": "pending", "waiting_for": ["data_received"] }
+```
+
+**HTTP status codes:** `200` for all execution outcomes (including failed), `404` if contract
+not registered, `422` for Igniter errors, `500` for unexpected errors.
+
+---
+
+### `POST /v1/contracts/:name/events`
+
+Deliver an event to a distributed contract execution.
+
+**Request body:**
+```json
+{
+  "event":       "data_received",
+  "correlation": { "request_id": "r1" },
+  "payload":     { "data": "value" }
+}
+```
+
+**Response:** same shape as `/execute`.
+
+---
+
+### `GET /v1/executions/:id`
+
+Poll the status of a previously started execution.
+
+**Response:**
+```json
+{ "execution_id": "uuid", "status": "pending", "waiting_for": ["data_received"] }
+```
+
+Returns `404` if the execution is not found in the configured store.
+
+---
+
+### `GET /v1/health`
+
+Health check endpoint.
+
+**Response:**
+```json
+{
+  "status":    "ok",
+  "contracts": ["ScoringContract", "PipelineContract"],
+  "store":     "MemoryStore",
+  "pending":   3
+}
+```
+
+---
+
+### `GET /v1/contracts`
+
+List registered contracts with their input and output names.
+
+**Response:**
+```json
+[
+  { "name": "ScoringContract", "inputs": ["value"], "outputs": ["score"] }
+]
+```
+
+---
+
+## `remote:` DSL — Cross-Node Contract Composition
+
+Call a contract on a remote igniter-server as a node inside a local graph:
+
+```ruby
+require "igniter/server"
+
+class OrchestratorContract < Igniter::Contract
+  define do
+    input :data
+
+    # Calls ScoringContract on a remote node over HTTP
+    remote :scored,
+           contract: "ScoringContract",
+           node:     "http://scoring-service:4568",
+           inputs:   { value: :data },
+           timeout:  10   # seconds (default: 30)
+
+    compute :label, depends_on: :scored do |scored:|
+      scored[:score] > 50 ? "high" : "low"
+    end
+
+    output :label
+  end
+end
+```
+
+The `remote:` node is validated at compile time:
+- `node:` must start with `http://` or `https://`
+- `contract:` must be a non-empty string
+- All keys in `inputs:` must reference nodes that exist in the local graph
+
+At runtime, if the remote service is unreachable or the remote contract fails,
+an `Igniter::ResolutionError` is raised and propagates like any other node failure.
+
+**Note:** `require "igniter/server"` is required to load `Igniter::Server::Client`.
+Without it, any contract with a `remote:` node will raise at resolution time.
+
+---
+
+## HTTP Client
+
+Use `Igniter::Server::Client` directly to call a remote service from application code:
+
+```ruby
+require "igniter/server"
+
+client = Igniter::Server::Client.new("http://localhost:4568", timeout: 30)
+
+# Execute a contract
+response = client.execute("ScoringContract", inputs: { value: 42 })
+# => { status: :succeeded, execution_id: "uuid", outputs: { score: 63.0 } }
+
+# Deliver an event
+client.deliver_event("LeadWorkflow",
+  event:       "data_received",
+  correlation: { request_id: "r1" },
+  payload:     { value: "hello" })
+
+# Poll execution status
+client.status("uuid")
+# => { status: :pending, waiting_for: ["data_received"] }
+
+# Health check
+client.health
+# => { status: "ok", contracts: [...], pending: 0 }
+```
+
+Errors:
+- `Igniter::Server::Client::ConnectionError` — network unreachable (wraps `Errno::ECONNREFUSED`, `SocketError`, etc.)
+- `Igniter::Server::Client::RemoteError` — HTTP 4xx/5xx response from the server
+
+---
+
+## Multi-Node Architecture
+
+```
+┌──────────────────────────┐         ┌──────────────────────────┐
+│  Orchestrator  :4567     │         │  Scoring Service  :4568  │
+│                          │         │                          │
+│  OrchestratorContract    │         │  ScoringContract         │
+│    remote :scored,   ────┼──HTTP──▶│  POST /v1/contracts/     │
+│      node: "…:4568"      │         │       ScoringContract/   │
+│                          │◀────────┤       execute            │
+│  contract.result.label   │         │  ← { status, outputs }   │
+└──────────────────────────┘         └──────────────────────────┘
+```
+
+Each node is an independent Ruby process. The orchestrator's graph is validated
+at load time — if `ScoringContract`'s URL is malformed, it fails at compile time,
+not at the first HTTP call.
+
+---
+
+## Security
+
+igniter-server ships with no built-in authentication. For production deployments:
+
+- Place the server behind a reverse proxy (nginx, Caddy, AWS ALB) that handles TLS and auth
+- Use network-level access controls (VPC, security groups, firewall rules)
+- Add Rack middleware for API key validation when using `rack_app`
+
+Example with Rack middleware:
+
+```ruby
+# config.ru
+require "igniter/server"
+
+app = Igniter::Server.rack_app
+
+auth_app = ->(env) {
+  return [401, {}, ["Unauthorized"]] unless env["HTTP_X_API_KEY"] == ENV["API_KEY"]
+  app.call(env)
+}
+
+run auth_app
+```
+
+---
+
+## Store Configuration
+
+For stateless contracts (no `await` or `correlate_by`), the default `MemoryStore` is fine.
+
+For distributed contracts that survive process restarts, use an external store:
+
+```ruby
+Igniter::Server.configure do |c|
+  # Redis (requires redis gem)
+  c.store = Igniter::Runtime::Stores::RedisStore.new(ENV["REDIS_URL"])
+
+  # ActiveRecord (requires Rails + activerecord gem)
+  c.store = Igniter::Runtime::Stores::ActiveRecordStore.new
+end
+```
+
+See [Store Adapters](STORE_ADAPTERS.md) for full reference.

data/examples/README.md

@@ -199,6 +199,135 @@ status_route_branch=CallConnected
 child_collection_summary={:mode=>:collect, :total=>3, ...}
 ```
 
+### `order_pipeline.rb`
+
+Run:
+
+```bash
+ruby examples/order_pipeline.rb
+```
+
+Shows:
+
+- `guard` — abort early when a precondition is not met
+- `collection` — fan-out via `LineItemContract` per line item
+- `branch` — route to domestic or international shipping strategy
+- `export` — lift branch outputs (`shipping_cost`, `eta`) to the parent graph
+- end-to-end pipeline: items → subtotal → shipping → grand total
+
+Expected output shape:
+
+```text
+=== US Order ===
+items_summary={:mode=>:collect, :total=>3, :succeeded=>3, :failed=>0, :status=>:succeeded}
+order_subtotal=199.96
+shipping_cost=0.0
+eta=2-3 business days
+grand_total=199.96
+
+=== International Order (DE) ===
+shipping_cost=29.99
+eta=7-14 business days
+grand_total=229.95
+
+=== Out of Stock ===
+error=Order cannot be placed: items are out of stock
+```
+
+### `distributed_server.rb`
+
+Run:
+
+```bash
+ruby examples/distributed_server.rb
+```
+
+Shows:
+
+- `correlate_by` — tag a contract class with correlation keys
+- `Contract.start` — launch an execution that suspends at `await` nodes
+- `Contract.deliver_event` — resume a suspended execution with an event payload
+- `on_success` — callback that fires when the graph completes
+- full lifecycle: submit → screening event → manager event → decision
+
+Expected output shape:
+
+```text
+=== Step 1: Application submitted ===
+pending=true
+waiting_for=[:screening_completed]
+
+=== Step 2: Background screening completed ===
+still_pending=true
+
+=== Step 3: Manager review completed ===
+[callback] Decision reached: HIRED
+
+=== Final result ===
+success=true
+decision={:status=>:hired, :note=>"Excellent system design skills"}
+```
+
+### `llm/tool_use.rb`
+
+Run:
+
+```bash
+ruby examples/llm/tool_use.rb
+```
+
+Shows:
+
+- chained LLM compute nodes (`classify → assess priority → draft response`)
+- tool declaration with the class-level `tools` method
+- conversation context with `Igniter::LLM::Context` for multi-turn messages
+- mock provider so the example runs offline without an API key
+
+Expected output shape (with mock provider):
+
+```text
+=== Feedback Triage Pipeline ===
+category=category: bug_report
+priority=priority: high
+response=We have logged this issue and will address it in the next release.
+
+--- Diagnostics ---
+...
+```
+
+### `agents.rb`
+
+Run:
+
+```bash
+ruby examples/agents.rb
+```
+
+Shows:
+
+- `Igniter::Agent` — stateful message-driven actor with `on` handlers and `schedule` timers
+- `Igniter::Supervisor` — one_for_one supervision with restart budget
+- `Igniter::Registry` — thread-safe lookup by name
+- `Igniter::StreamLoop` — continuous contract tick-loop with hot-swap inputs
+
+Expected output shape:
+
+```text
+=== Supervised agents ===
+counter=8
+after_reset=10
+history=[10]
+
+=== Registry lookup ===
+named_counter=42
+
+=== Stream loop ===
+statuses_sample=[:alert, :normal]
+
+log_entries=1
+done=true
+```
+
 ## Validation
 
 These scripts are exercised by [example_scripts_spec.rb](/Users/alex/dev/hotfix/igniter/spec/igniter/example_scripts_spec.rb), so the documented commands and outputs stay aligned with the code.

data/examples/agents.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# Agents — stateful actors with supervision and continuous contract loops
+#
+# Demonstrates:
+#   - Igniter::Agent       — stateful message-driven actor
+#   - Igniter::Supervisor  — one_for_one supervision with restart budget
+#   - Igniter::Registry    — looking up agents by name
+#   - Igniter::StreamLoop  — continuous contract tick-loop
+#
+# Run: ruby examples/agents.rb
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+require "igniter/integrations/agents"
+
+# ── Contract used by the stream loop ─────────────────────────────────────────
+
+class ThresholdContract < Igniter::Contract
+  define do
+    input :value,     type: :numeric
+    input :threshold, type: :numeric
+
+    compute :status, depends_on: %i[value threshold] do |value:, threshold:|
+      value > threshold ? :alert : :normal
+    end
+
+    output :status
+  end
+end
+
+# ── Counter Agent ─────────────────────────────────────────────────────────────
+
+class CounterAgent < Igniter::Agent
+  initial_state counter: 0, history: []
+
+  on :increment do |state:, payload:, **|
+    by        = payload.fetch(:by, 1)
+    new_count = state[:counter] + by
+    state.merge(
+      counter: new_count,
+      history: (state[:history] + [new_count]).last(10)
+    )
+  end
+
+  on :reset do |state:, **|
+    state.merge(counter: 0, history: [])
+  end
+
+  # Returns the current count to sync callers
+  on :count do |state:, **|
+    state[:counter]
+  end
+
+  # Returns the last N history entries
+  on :history do |state:, payload:, **|
+    state[:history].last(payload.fetch(:n, 5))
+  end
+end
+
+# ── Logger Agent ──────────────────────────────────────────────────────────────
+
+class LoggerAgent < Igniter::Agent
+  initial_state entries: []
+
+  on :log do |state:, payload:, **|
+    ts    = Time.now.strftime("%H:%M:%S")
+    entry = "[#{ts}] #{payload[:message]}"
+    state.merge(entries: (state[:entries] + [entry]).last(100))
+  end
+
+  on :dump do |state:, **|
+    state[:entries]
+  end
+end
+
+# ── Supervisor ────────────────────────────────────────────────────────────────
+
+class AppSupervisor < Igniter::Supervisor
+  strategy     :one_for_one
+  max_restarts 3, within: 10
+
+  children do |c|
+    c.worker :counter, CounterAgent
+    c.worker :logger,  LoggerAgent
+  end
+end
+
+# ── Run: Supervised agents ────────────────────────────────────────────────────
+
+puts "=== Supervised agents ==="
+
+sup     = AppSupervisor.start
+counter = sup.child(:counter)
+logger  = sup.child(:logger)
+
+counter.send(:increment, by: 5)
+counter.send(:increment, by: 3)
+
+total = counter.call(:count)
+puts "counter=#{total}"
+
+logger.send(:log, message: "Counter reached #{total}")
+
+counter.send(:reset)
+counter.send(:increment, by: 10)
+
+new_total = counter.call(:count)
+puts "after_reset=#{new_total}"
+
+hist = counter.call(:history, { n: 5 })
+puts "history=#{hist.inspect}"
+
+# ── Run: Registry ─────────────────────────────────────────────────────────────
+
+puts "\n=== Registry lookup ==="
+
+named_ref = CounterAgent.start(name: :named_counter)
+Igniter::Registry.find(:named_counter).send(:increment, by: 42)
+puts "named_counter=#{named_ref.call(:count)}"
+named_ref.stop
+Igniter::Registry.unregister(:named_counter)
+
+# ── Run: StreamLoop ───────────────────────────────────────────────────────────
+
+puts "\n=== Stream loop ==="
+
+statuses = []
+
+stream = Igniter::StreamLoop.new(
+  contract: ThresholdContract,
+  tick_interval: 0.05,
+  inputs: { value: 20.0, threshold: 25.0 },
+  on_result: ->(result) { statuses << result.status }
+)
+
+stream.start
+sleep(0.15)                            # ~3 ticks at :normal
+stream.update_inputs(value: 30.0)
+sleep(0.15)                            # ~3 ticks at :alert
+stream.stop
+
+puts "statuses_sample=#{statuses.uniq.sort.inspect}"
+
+# ── Teardown ──────────────────────────────────────────────────────────────────
+
+log_entries = logger.call(:dump)
+puts "\nlog_entries=#{log_entries.size}"
+sup.stop
+puts "done=true"