How asmodeus14/chronostack works
ChronoStack is a Docker Compose test-clock system. A user starts an isolated copy of a Compose project, advances its shared virtual clock, and verifies time-dependent behavior through service probes, job triggers and barriers; YAML scenarios can add faults and assertions and produce reports. The controller writes the shared clock page, which virtualized processes read, while the CLI coordinates the run. The README documents additional simulated-user, MCP and host-native Node capabilities. Some subsystem internals were not sampled, so links for those branches rely on README statements.
Main entry points: main.rs ChronoStack CLI · src/engine.rs Simulated users · src/engine.rs Advance engine · scenario.rs Scenario runner
Components 26
CLI orchestration
- ChronoStack CLI
crates/cli/src/main.rs - Compose copy
crates/core/src/compose.rs - Session state
crates/cli/src/session.rs - Run configuration
crates/cli/src/config.rs - Advance engine
crates/cli/src/engine.rs - Controller client
crates/cli/src/client.rs
Virtual clock
- Clock controller
crates/clockd/src/server.rs - Shared clock page
crates/clockd/src/clock.rs - Event log
crates/clockd/src/events.rs - Clock virtualization
shim/chronoclock.c
Jobs and verification
- Triggers and barriers
crates/cli/src/engine.rs - Clock probes
crates/cli/src/probe.rs
Scenarios and faults
- Fault control
crates/clockd/src/faults.rs - HTTP fault proxy
crates/clockd/src/proxy.rs - Scenario runner
crates/cli/src/scenario.rs - Run reports
crates/cli/src/report.rs
Testing extensions
- Simulated users
crates/users/src/engine.rs - Journey validation
crates/users/src/model.rs - Cohort arrivals
crates/users/src/arrival.rs - Journey templates
crates/users/src/template.rs - Seeded randomness
crates/users/src/rng.rs - Latency metrics
crates/users/src/histogram.rs - MCP tools
crates/cli/src/mcp.rs - Host-native Node
sdk/node/index.js
Other components
- Engineer
- Compose services
Connections 29
- Engineer → ChronoStack CLI: runs commands
- ChronoStack CLI → Compose copy: creates isolated copy
- ChronoStack CLI → Session state: stores session
crates/cli/src/main.rs - ChronoStack CLI → Run configuration: loads settings
crates/cli/src/main.rs - ChronoStack CLI → Advance engine: invokes advance
crates/cli/src/main.rs - Advance engine → Controller client: controls clock
crates/cli/src/engine.rs - Controller client → Clock controller: calls API
crates/cli/src/client.rs - Clock controller → Shared clock page: writes clock
crates/clockd/src/server.rs - Clock controller → Event log: records changes
crates/clockd/src/server.rs - Shared clock page → Clock virtualization: shares virtual time
- Clock virtualization → Compose services: virtualizes wall time
- Advance engine → Triggers and barriers: runs due work
crates/cli/src/engine.rs - Triggers and barriers → Compose services: triggers and waits
- Advance engine → Clock probes: probes services
crates/cli/src/engine.rs - Clock probes → Compose services: checks virtual time
- ChronoStack CLI → Scenario runner: runs scenarios
crates/cli/src/main.rs - Scenario runner → Advance engine: advances time
crates/cli/src/scenario.rs - Scenario runner → Fault control: sets scheduled faults
crates/cli/src/scenario.rs - Fault control → HTTP fault proxy: controls outages
crates/clockd/src/server.rs - HTTP fault proxy → Compose services: intercepts HTTP
- Scenario runner → Run reports: produces reports
crates/cli/src/scenario.rs - ChronoStack CLI → Simulated users: runs cohorts
- Simulated users → Journey validation: validates journeys
crates/users/src/engine.rs - Simulated users → Cohort arrivals: schedules arrivals
crates/users/src/engine.rs - Simulated users → Journey templates: renders steps
crates/users/src/engine.rs - Simulated users → Seeded randomness: draws seeded choices
crates/users/src/engine.rs - Simulated users → Latency metrics: records latency
crates/users/src/engine.rs - ChronoStack CLI → MCP tools: serves tools
crates/cli/src/main.rs - Host-native Node → Shared clock page: reads shared clock