state-engine 0.1.0

Declarative state data management for multi-tenant, multi-service systems. Synchronizes process memory, KVS, and databases using 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/cache.yml
some-state:
  _state:
    type: integer
  _store:
    client: KVS
    key: "some"
  _load:
    client: DB
    table: some
    where: 'id=1' # Please update this '$(user.id)' to use this library effectively after.
    columns: 

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::{Manifest, State, Load};

// Initialize Manifest
let mut manifest = Manifest::new('./manifest');

// 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(&in_memory)
    .with_kvs_client(&mut kvs)
    .with_db_client(&db);

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

// Use state-engine
let user = state.get('some-state')?;

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, KVS, DB, ENV 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 (pure logic modules)
      dot_array_accessor.rs
      placeholder_resolver.rs
      log_format.rs

    manifest/         # Manifest impl
    state/            # State impl
    load/             # Load module (internal module)

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

    adapters/

    app/
      db/
      src/
      Cargo.toml
      Dockerfile
      docker-compose.yml

  tests/
    mocks/
    integration/

tests

39 unit tests, 49 intergeration tests and example application test 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