state-engine

Declarative state data management system for a process. Structures state data on process and keeps it syncable using your store clients. It behaves as described in YAML DSL.

• Automates complex state lifecycles through developer-defined YAML manifests.

• Enables multi-tenant DB apps without junction tables.

• Built on a reimagined web architecture (see ## Background).

• also README(patch translation for ja-JP )

Version

Provided Functions

Why state-engine?

Before:

// Manual cache management
let cache_key = format!("user:{}", id);
let user = redis.get(&cache_key).or_else(|| {
    let user = db.query("SELECT * FROM users WHERE id=?", id)?;
    redis.set(&cache_key, &user, 3600);
    Some(user)
})?;

After:

let user = state.get("cache.user")?;

• ✅ Multi-tenant DB without junction tables
• ✅ Automatic KVS/DB synchronization
• ✅ No manual cache invalidation

Installation

# Cargo.toml
[dependencies]
state-engine = "0.1"

Quick Start

1. Write a yaml file.

# manifest/example.yml
session:
  user-key:
  _state:
    type: integer
  _store:
    client: InMemory
    key: "request-attributes-user-key"
  _load:
    client: InMemory
    key: "request-header-user-key"


user:
  _store:
    client: KVS
    key: "user:${example.session.user-key}"
  _load:
    client: Db
    table: "users"
    where: "id=${example.session.user-key}"
    map:
      name: "name"
  name:
    _state:
      type: string

2. Implement some Required Ports for your stores.

• "Db" and "Env" will be used only in Loading(Read).
• It's not essential to implement all *Client.

3. Initialize State with your adapters and use it.

use state_engine::{State, Load};

// Create adapter instances
let mut in_memory = InMemoryAdapter::new();
let mut kvs = KVSAdapter::new()?;
let db = DbAdapter::new()?;

// Build Load with adapters
let load = Load::new()
    .with_in_memory(&mut in_memory)
    .with_kvs_client(&mut kvs)
    .with_db_client(&db);

// Build State with adapters
let mut state = State::new("./manifest", load)
    .with_in_memory(&mut in_memory)
    .with_kvs_client(&mut kvs);

// Use state-engine
let user = state.get("example.user.name")?;

Full working example: examples/app/src/main.rs

Architecture

┌─────────────┐  ┌───────────────────┐
│ Application │  │ manifestDir/*.yml │
└──────┬──────┘  └───────────────────┘
       │ uses             ▲ read
       ▼                  │
┌─────────────────────────┴───────────┐
│     Provided Ports (Public API)     │
├─────────────────────────────────────┤
│                                     │
│      State    -->    Manifest       │
│                                     │
└───────┬─────────────────────────────┘
        │ depends on
        ▼
┌─────────────────────────────────────┐
│    Required Ports (App Adapters)    │
├─────────────────────────────────────┤
│    InMemory, Env, KVS, Db clients   │
└─────────────────────────────────────┘

see for details Architecture.md

tree

./
  README.md           # this file
  Cargo.toml
  docs/               # guide documents
    en/
      Architecture.md
      YAML-guide.md
    ja/
      README.md
      Architecture.md
      YAML-guide.md
  src/
    ports/            # library external interface traits
      provided.rs     # library provides
      required.rs     # Library requires

    common/           # library common mod
      bit.rs
      pool.rs
      parser.rs
      log_format.rs

    manifest.rs       # Manifest impl
    state.rs          # State impl
    store.rs          # Store internal mod
    load.rs           # Load internal mod

  examples/
    manifest/         # manifest YAML examples
      connection.yml  # sample 1
      cache.yml       # sample 2
      session.yml     # sample 3

    adapters/

    app/
      db/
      src/
        main.rs
        adapters.rs
        test_runner.rs   # inetegration tests 
      Cargo.toml
      Dockerfile
      docker-compose.yml

tests

unit tests, intergeration tests on example app (docker compose) passed

1. cargo test:

cargo test --features=logging -- --nocapture

2. example application test:

cd examples/app
docker compose up --build

Background

reimagined web architecture

• computer: A network-capable node in the system.
• server: A computer that serves human users.
• orchestrator: A computer responsible for internal system coordination and maintenance. (optional)
• database: A server that persists data without an inherent expiration and accepts CRUD operations.
• terminal: A server that provides a direct human-facing interface.
• conductor: A server that communicates independently with both a database and terminals, and maintains a synchronized state between them. (optional)

# terms relationship
computer:
  orchestrator:
  server:
    database:
    terminal:
    conductor:

License

MIT