ice

Ice

A lightweight, zero-dependency rule engine with visual tree-based orchestration

Documentation · Live Demo · Getting Started · Changelog

中文

What is Ice?

Ice is a rule engine that takes a fundamentally different approach: rules are organized as trees, not chains or tables. Each node in the tree handles its own logic independently — modifying one node never creates cascading effects on others. Nodes communicate exclusively through a shared, thread-safe data context called Roam, rather than referencing each other directly.

The result is a system where business rules can be visually configured, hot-reloaded in seconds, and executed in-memory with sub-millisecond latency — all without requiring any database or middleware.

Key Features

How It Works

Rule Trees

Every rule in Ice is a tree composed of two types of nodes:

• Relation Nodes — control the execution flow (similar to logical operators)
• Leaf Nodes — contain your actual business logic

Relation Nodes (Control Flow)

Each type has a parallel variant (P_AND, P_ANY, P_ALL, P_NONE, P_TRUE) that executes children concurrently.

Leaf Nodes (Business Logic)

Roam (Data Context)

Roam is the thread-safe data container that flows through the entire rule tree. Nodes read input from and write output to Roam — they never reference each other directly. This is the key to node isolation.

Roam
├── put("uid", 12345)              // flat key-value
├── putDeep("user.level", "gold")  // nested key
├── get("uid")                     // → 12345
└── getDeep("user.level")          // → "gold"

• Thread-safe: Java ConcurrentHashMap / Go sync.RWMutex / Python threading.RLock
• Deep keys: putDeep("a.b.c", value) auto-creates nested structures
• Dynamic references: prefix a value with @ to resolve it from Roam at runtime (e.g., @uid reads roam.get("uid"))

Architecture

┌──────────────────────────────────────────────────────────────┐
│                   Shared Storage (ice-data/)                 │
│     ┌────────┐    ┌────────┐    ┌────────┐    ┌──────────┐  │
│     │ apps/  │    │ bases/ │    │ confs/ │    │ versions/│  │
│     └────────┘    └────────┘    └────────┘    └──────────┘  │
└──────────────────────────────────────────────────────────────┘
          ▲                                       ▲
          │ Write                                 │ Read (Poll)
          │                                       │
┌─────────┴─────────┐                 ┌───────────┴───────────┐
│    Ice Server      │                │      Ice Client       │
│                    │                │                       │
│  • Web UI          │                │  • Version polling    │
│  • Tree editor     │                │  • Hot reload         │
│  • Apply & publish │                │  • In-memory exec     │
│  • Mock debugging  │                │  • Mock execution     │
│                    │                │  • Fault tolerant     │
└────────────────────┘                └───────────────────────┘

Key design decisions:

• Server and Client are fully decoupled — if the Server goes down, Clients continue executing rules from their in-memory cache
• File-based communication — no network protocol between Server and Client, just a shared directory (ice-data/)
• Incremental updates — Client polls versions/ for changes and applies only the delta; falls back to full reload if incremental files are missing

Deployment Options

Quick Start

1. Deploy the Server

docker run -d --name ice-server -p 8121:8121 \
  -v ./ice-data:/app/ice-data waitmoon/ice-server:latest

Open http://localhost:8121 to access the Web UI.

2. Install the Client SDK

<dependency>
  <groupId>com.waitmoon.ice</groupId>
  <artifactId>ice-core</artifactId>
  <version>4.0.9</version>
</dependency>

go get github.com/zjn-zjn/ice/sdks/go

pip install ice-rules

3. Define Your Leaf Nodes

Leaf nodes are where your business logic lives. Here’s a simple ScoreFlow that checks if a value meets a threshold:

@Data
@EqualsAndHashCode(callSuper = true)
public class ScoreFlow extends BaseLeafFlow {

    private double score;
    private String key;

    @Override
    protected boolean doFlow(IceRoam roam) {
        Number value = roam.getDeep(key);
        if (value == null) {
            return false;
        }
        return value.doubleValue() >= score;
    }
}

type ScoreFlow struct {
    Score float64 `json:"score" ice:"name:Score Threshold,desc:Minimum score to pass"`
    Key   string  `json:"key" ice:"name:Roam Key,desc:Key to read from Roam"`
}

func (s *ScoreFlow) DoFlow(ctx context.Context, roam *icecontext.Roam) bool {
    value := roam.ValueDeep(s.Key).Float64Or(0)
    return value >= s.Score
}

ice.RegisterLeaf("com.example.ScoreFlow",
    &ice.LeafMeta{Name: "Score Check", Desc: "Check if score meets threshold"},
    func() any { return &ScoreFlow{} })

@ice.leaf("com.example.ScoreFlow", name="Score Check", desc="Check if score meets threshold")
class ScoreFlow:
    score: Annotated[float, IceField(name="Score Threshold")] = 0.0
    key: Annotated[str, IceField(name="Roam Key")] = ""

    def do_flow(self, roam: Roam) -> bool:
        value = roam.get_deep(self.key)
        if value is None:
            return False
        return float(value) >= self.score

4. Initialize the Client and Execute

// Initialize
IceFileClient client = new IceFileClient(1, "./ice-data", "com.your.package");
client.start();

// Execute
IceRoam roam = IceRoam.create();
roam.setId(1L);
roam.put("uid", 12345);
roam.put("score", 95.5);
Ice.syncProcess(roam);

// Initialize
client, _ := ice.NewClient(1, "./ice-data")
client.Start()
defer client.Destroy()

// Execute
roam := ice.NewRoam()
roam.SetId(1)
roam.Put("uid", 12345)
roam.Put("score", 95.5)
ice.SyncProcess(context.Background(), roam)

# Initialize
client = ice.FileClient(app=1, storage_path="./ice-data")
client.start()

# Execute
roam = ice.Roam.create()
roam.set_id(1)
roam.put("uid", 12345)
roam.put("score", 95.5)
ice.sync_process(roam)

5. Configure Rules in the Web UI

Open the Web UI → create a rule tree → arrange your nodes → click Apply. Changes take effect within seconds — no restart required.

Comparison with Traditional Rule Engines

Use Cases

Configuration Reference

Client Configuration

Server Configuration

Documentation

Guide

• Getting Started — Deploy, integrate, and run your first rule
• Core Concepts — Trees, nodes, Roam, and execution model
• Architecture — Design decisions and deployment patterns
• FAQ — Common questions and troubleshooting

Reference

• Node Types — All relation and leaf node types in detail
• Client Configuration — Full client parameter reference
• Server Configuration — Full server parameter reference
• Roam API — Data context API across all SDKs

SDK Guides

• Java SDK
• Go SDK
• Python SDK

Community

• GitHub Issues — Bug reports and feature requests
• GitHub Discussions — Questions and community discussions
• Live Demo — Try Ice without installing anything

Contributing

Contributions are welcome! Whether it’s bug reports, feature requests, documentation improvements, or code contributions — feel free to open an issue or submit a pull request.

License

Apache License 2.0