Wiggle — Onboarding & Configuration Reference§

Everything a new contributor or operator needs: what Wiggle is, how to get it running, how to author workflows, and every configuration option in one place.

• New to the code? Read §1–§4.
• Writing a workflow? §5.
• Deploying / tuning? §6 (the full config reference) and §7.

1. What Wiggle is§

A durable, cellular state-machine platform. You describe a process as a graph with a java.util.stream-style DSL; a server runs it as a durable state machine (tokens over the graph) that survives crashes and resumes where it left off; workers pull work when they have capacity and run the step logic. Its distinctive move is cellular: a namespace becomes a cell — its own database and its own cluster — and an optional coordinator shards work across cells with directory-free routing and zero-migration rebalancing. See README.md for the elevator pitch and docs/local-execution.md for the execution-mode deep dive.

Core properties: durable (survives restarts), exactly-once dispatch and at-least-once execution, pull-based workers (no inbound connectivity), content-addressed immutable definitions, multi-node clustering over a shared database, and cellular sharding — a namespace is a cell with its own database and cluster, placed by consistent hashing over epochs and rebalanced by drain/retire (a single cluster runs unchanged without a coordinator). Under a coordinator each node sets an explicit cell id (WIGGLE_CELL_ID), and a namespace becomes resolvable only after an epoch names its cells (wiggle open-epoch) — until then it is not-ready by design (no implicit cell). See docs/sharding-and-epochs.md.

2. Getting the code§

git clone https://github.com/hadielmougy/wiggle.git
cd wiggle
./gradlew build          # compiles everything and runs the test suite

Prerequisites:

• JDK 21+ (the Gradle toolchain pins language level 21).
• The Gradle wrapper is committed (./gradlew); no local Gradle needed. If it's ever missing, regenerate once with gradle wrapper --gradle-version 8.10.
• Docker only for the Postgres cluster demos (§4.3); nothing else needs it.

Dev loop:

./gradlew build                        # full build + tests
./gradlew check                        # tests only (JUnit)
./gradlew :tests:run                   # the conformance scenarios, framework-free, no network
./gradlew :module:test --tests "Foo"   # a single test class

Branch off main, keep changes focused, and run ./gradlew check before pushing. Schema changes go through the migration runner (§7.4), never by editing an already-released migration.

3. Modules§

Published under group io.github.hadielmougy, version 2.1.8 (the runnable dist module is not published). The server core is database-agnostic; it builds its store from an injected StorageFactory and the backend is selected from the URL scheme (§7.2).

4. Running it§

4.1 Single node (in-memory) — dev default§

./gradlew :dist:run                          # gRPC on :8080, in-memory store
./gradlew :example:run                          # embedded server + worker + a few orders, one JVM

4.2 Server + workers as separate processes§

./gradlew :dist:run                                  # terminal 1
./gradlew :example:runWorker                            # terminal 2 (WIGGLE_URL=localhost:8080)
./gradlew :example:submitOrders -Pcount=20             # terminal 3

4.3 A cluster on Postgres§

docker compose up -d postgres        # Postgres on :5433 (see docker-compose.yml)
scripts/cluster.sh 20                 # three server nodes, two workers, one Postgres

# or on Kubernetes (kind):
scripts/kind-up.sh 3                   # 3 server pods + Postgres at localhost:30080
scripts/run-workers.sh 5 20            # 5 local workers, then submit 20 orders
scripts/kind-down.sh                   # tear down

4.4 As a container (Docker)§

The Dockerfile builds one image for every role (WIGGLE_ROLE=cell ∣ coordinator ∣ console, every storage backend bundled, picked from the URL scheme); it reads the same env vars as the JAR (§6). TLS is set the same way — WIGGLE_TLS_KEYSTORE + a mounted keystore.

# run the released image: an in-memory server (gRPC :8080, /healthz probe optional)
docker run --rm -p 8080:8080 hadielmougy/wiggle:2.1.8

# the ops console against it (same image, different role) → http://localhost:8090
docker run --rm -p 8090:8090 -e WIGGLE_ROLE=console -e WIGGLE_URL=host.docker.internal:8080 \
  -e WIGGLE_DASHBOARD_PASSWORD=change-me hadielmougy/wiggle:2.1.8

# a complete stack: server + Postgres + console with login, durable volume, no TLS
docker compose -f docker-compose.full.yml up -d      # → http://localhost:8090 (admin / change-me)

# build locally / publish multi-arch
docker build -t wiggle .
scripts/docker-release.sh                             # buildx amd64+arm64, pushes to a registry

The image is the control plane (+ optional console role) only; run workers as separate processes against :8080 (your app on wiggle-client, or ./gradlew :example:runWorker).

4.5 Handy scripts§

4.6 Gradle tasks§

5. Authoring workflows§

A definition is pure topology — named nodes and their wiring, no logic and no context type. build() returns a Blueprint (just the graph):

Blueprint orders = Workflow.define("order-fulfilment")
        .step("validate")
        .gate("in-stock")
        .fork(
                Branch.of("payment",  s -> s.step("authorise", RetryPolicy.exponential(5, ofMillis(100)))
                                            .step("capture")),
                Branch.of("shipping", s -> s.step("reserve")
                                            .sleep("await", ofMillis(300))
                                            .step("label")))
        .combine("merge")   // fork always rejoins at a mandatory combine
        .step("notify")
        .build();

The step logic is a separate class annotated @Handlers("<workflow-name>"), bound on a worker by name. Each method whose name matches a step (case/style-insensitive, so inStock serves in-stock) is a handler; its signature defines the step — one parameter is the input (decoded from JSON), a boolean return is a gate, void is an effect, any other return is a task whose value becomes the next context (types may change from step to step, like Stream.map):

@Handlers("order-fulfilment")
class OrderHandlers {
    public Order   validate(Order o)  { return o.withStatus("VALIDATED"); }
    public boolean inStock(Order o)   { return o.quantity() > 0; }        // gate
    public Order   authorise(Order o) { return o.withPaymentRef(auth(o)); }
    public Order   capture(Order o)   { return o.log("captured"); }
    public Order   reserve(Order o)   { return o.withShipmentRef(reserve(o)); }
    public Order   label(Order o)     { return o.withTrackingLabel(print(o)); }
    public Order   notify(Order o)    { return o.withStatus("FULFILLED"); }
}

Bind it on the worker with new Worker(client, "w").register(orders).handlers(new OrderHandlers()). A combine node (merge) must have an explicit handler — a method taking @Arm("branch") parameters (each branch's result) plus an optional @Context parameter (the pre-fork context), whose return is the COMPLETE post-join context. There is no implicit fold: a combine served by no worker fails its task, and keys the handler does not return do not survive the join.

5.1 Operations§

Every operation is topology only — it names a node; the matching @Handlers method supplies its logic.

step/effect/gate take an optional trailing RetryPolicy. The context type is not fixed by the definition — each handler picks the type it works in by its signature (a typed record, or a Map<String, Object> for raw JSON), and a method may return a different type than it takes.

Evolving a record's schema. A handler decodes the persisted JSON into its parameter type reflectively, so adding, renaming, or retyping a field silently defaults/loses data — or fails to decode — for instances already in flight (the workflow version hashes only the graph topology, not the context type). Opt into custom decoding with a @Decode method in the handler class: it takes the raw JSON (Map<String, Object>) and returns the current type, running instead of the default mapping wherever a step or combine parameter of that type is bound. It's the seam for schema-version upcasts or a bespoke codec:

@Handlers("order-fulfilment")
class OrderHandlers {
    @Decode
    public Order load(Map<String, Object> raw) {     // upcast an older shape to the current Order
        raw.putIfAbsent("currency", "USD");           // e.g. default a field added in a later version
        return RecordMapper.fromJson(raw, Order.class);
    }
    // ... step methods, which now receive the upcast Order ...
}

5.2 Running instances§

try (WiggleClient client = new WiggleClient("localhost:8080")) {
    String id = client.start(orders, Order.of(...));
    InstanceView v = client.awaitCompletion(id, Duration.ofSeconds(30));   // COMPLETED | FAILED | CANCELLED
    client.cancel(id, "reason");
}

6. Configuration reference§

6.1 How settings are supplied§

The server reads each setting from a system property first, then an environment variable, falling back to a default (ServerConfig.fromEnvironment()). So -Dwiggle.port=9090 and WIGGLE_PORT=9090 are equivalent. For the application distribution, pass JVM flags via the WIGGLE_OPTS (or JAVA_OPTS) environment variable that bin/wiggle honours.

The worker is configured programmatically via WorkerOptions (§6.5); the WIGGLE_* worker variables in §6.7 are conventions of the example WorkerMain, not the client library.

6.2 Server — core & storage§

6.3 Server — engine, cluster & housekeeping§

6.4 Execution modes§

Set per workflow in the DSL: Workflow.define(...).execution(ExecutionMode.LOCAL_SYNC). The mode is part of the definition's content hash, so an in-flight instance keeps the mode it started on.

.checkpoint() after a step forces LOCAL_ASYNC to commit it before continuing. Details and benchmark numbers: docs/local-execution.md.

6.5 Worker — WorkerOptions (programmatic)§

new Worker(client, "worker-1", WorkerOptions.defaults()
        .withConcurrency(16)
        .withLease(Duration.ofSeconds(30))
        .withLongPollWait(Duration.ofSeconds(10))
        .withLocalBatchSize(64));

6.6 Logging§

Wiggle logs through the JDK's System.Logger (routes to java.util.logging), so there's no logging dependency. See docs/ / deploy/logging.properties and:

Level mapping to java.util.logging: DEBUG→FINE, TRACE→FINER, INFO→INFO, WARNING→WARNING, ERROR→SEVERE. INFO is a clean lifecycle narrative (start/stop, membership, leader, registrations, failures, purges, lag warnings); DEBUG adds per-token/step/RPC detail.

6.7 Example worker & benchmark variables§

Conventions of the example module's WorkerMain / Benchmark (not the library):

The example workflows set their mode in code via .execution(...). To sweep modes without editing, change OrderFulfilment.blueprint() to call the provided mode() helper (reads WIGGLE_EXECUTION_MODE); the benchmark already reads it.

7. Operations§

7.1 The ops console (web UI)§

The web UI is the standalone ops console — the console module, a separate process that is a pure gRPC client (embedded Tomcat + servlets). Server/cell nodes serve no UI; a node's WIGGLE_DASHBOARD_PORT (default 0 = off) exposes only the /healthz probe for liveness/readiness checks.

One binary, two modes, chosen by env:

# direct mode: one cluster
WIGGLE_URL=localhost:8080 ./gradlew :console:run          # → http://localhost:8090

# coordinator mode: a whole sharded namespace (fan queries across its cells,
# route cancel/signal to the owning cell by instance id)
WIGGLE_COORDINATOR_URL=coordinator:8099 WIGGLE_NAMESPACE=orders ./gradlew :console:run

# or via the Docker image
WIGGLE_ROLE=console WIGGLE_URL=server:8080 …

The SPA (ClojureScript + Reagent, source in dashboard-ui/, compiled into the console jar) has four tabs: Instances (filter, search by instance id or correlation id, a live trace overlaying token status onto the workflow diagram, cancel, inline signal delivery), Workflows (render any compiled graph), Schedules (create/delete interval and cron schedules), and Signals. ./gradlew :console:build compiles the bundle automatically (needs Node; -PskipDashboard or a missing Node toolchain skips it). Dev loop: cd dashboard-ui && npx shadow-cljs watch app (hot reload on :8280, proxying /api to a console on :8090).

Auth. Set WIGGLE_DASHBOARD_PASSWORD to require login as the operator account (WIGGLE_DASHBOARD_USER, default admin). Optionally also set WIGGLE_DASHBOARD_VIEWER_PASSWORD for a read-only viewer account (WIGGLE_DASHBOARD_VIEWER_USER, default viewer): a viewer sees everything but any mutating call (cancel, signal, schedule — every non-GET /api/*) is rejected. Browsers get a /login form that sets an HttpOnly session cookie; programmatic clients can use HTTP Basic auth. Unset password = open access (warning at startup). Credentials travel cleartext over plain HTTP, so serve over TLS for anything exposed.

7.1a Transport security (TLS / mTLS)§

Opt-in and shared by the gRPC API and the console's HTTP. A keystore turns TLS on for both; a truststore additionally requires client certificates (mTLS on the server) and presents a client certificate (on a worker/client). Unset ⇒ plaintext for both. Stores are PKCS12 by default; a .jks path is loaded as JKS. Clients/workers read the same variables. TLS secures the channel and (with mTLS) authenticates the peer, but it is not authorization — any trusted peer may call any RPC; layer the console's login/Basic auth or an external gateway on top for role separation.

7.2 Storage backends§

No URL → in-memory (single node, dev/test). With one, the server builds its store from an injected StorageFactory — no ServiceLoader: the distribution's WiggleStorageFactory maps the URL scheme to a backend at runtime. The JDBC backends — PostgreSQL / H2 (wiggle-postgres), MySQL / MariaDB (wiggle-mysql), Oracle (wiggle-oracle), SQL Server (wiggle-sqlserver) — share one HikariCP-pooled, dialect-aware store (wiggle-jdbc). The dist module (the Docker image) bundles them all, so a single image serves any of jdbc:postgresql:, jdbc:h2:, jdbc:mysql: / jdbc:mariadb:, jdbc:oracle: or jdbc:sqlserver:. Another database is a new module — no engine change.

Embedding the server in your own JVM? Pass the factory explicitly, e.g. new WiggleServer(config, cfg -> new JdbcStorage(cfg.jdbcUrl(), cfg.jdbcUser(), cfg.jdbcPassword(), cfg.jdbcPoolSize(), new PostgresDialect())) — you depend only on the storage module(s) you use.

7.3 Signals, sub-workflows and schedules§

awaitSignal(name) parks an instance until the named signal arrives; no worker is held. Deliver via client.signal(instanceId, name, payload) (gRPC), the console's Signals tab, or POST /api/instances/{id}/signal/{name} (JSON body merges into the context). Optional deadline: awaitSignal(name, timeout) fails the instance on timeout; the three-arg form runs an escalation branch instead. Signals are not buffered -- an early delivery is a retryable conflict.

subWorkflow(name, workflow) runs a registered workflow as a child with the parent's context; its final context merges back, its failure/cancellation fails the parent, and cancelling the parent cascades to children.

Schedules fire a workflow on a fixed interval or a five-field cron expression (UTC), leader-driven and exactly-once per fire. From the client: client.createSchedule(workflow, Duration, context) / createCronSchedule(workflow, "0 3 * * *", context) / schedules() / deleteSchedule(id) (gRPC). Over HTTP: POST /api/schedules {"workflow", "everyMillis"|"cron", "context"?}, GET /api/schedules, DELETE /api/schedules/{id}. Creation is an upsert keyed on workflow name -- a workflow has at most one schedule, so calling create again from any number of client instances updates it in place rather than creating duplicates.

7.4 Schema migrations§

JdbcStorage runs a versioned, forward-only migration list on startup, tracked in wf_schema_version, under a cross-node advisory lock, atomic on Postgres. To evolve the schema, append a Migration(n, "name", sql) — never edit a released one; keep changes backward-compatible for rolling deploys. Tables: wf_definition, wf_graph_node, wf_graph_edge, wf_instance, wf_token, wf_node, wf_schema_version.

7.5 Queue-lag monitoring§

The leader watches whether the dispatchable backlog is draining fast enough (backlog vs cluster-wide completion rate) and logs a WARNING when it isn't — a sign of too few workers, a stuck worker pool, or a slow step. Tune with the two WIGGLE_QUEUE_LAG_* knobs (§6.3).

7.6 Benchmarking§

# in-memory (async ≈ sync, commits are free):
WIGGLE_EXECUTION_MODE=LOCAL_ASYNC ./gradlew :example:bench

# against Postgres (async wins — far fewer WAL fsyncs):
docker compose up -d postgres
WIGGLE_EXECUTION_MODE=LOCAL_ASYNC WIGGLE_JDBC_URL=jdbc:postgresql://localhost:5433/wiggle \
  WIGGLE_JDBC_USER=wiggle WIGGLE_JDBC_PASSWORD=wiggle ./gradlew :example:bench

8. Where to go deeper§

• README.md — overview, quick start, DSL walkthrough.
• docs/local-execution.md — execution modes, the wire protocol, the shared traversal seam, and the crash-replay contract per mode.
• RELEASING.md — publishing to Maven Central.
• proto/src/main/proto/wiggle.proto — the control-plane wire contract.