Skip to content

ChronoStack 0.1.0-alpha.8

Latest

Choose a tag to compare

@github-actions github-actions released this 21 Nov 05:53
· 3 commits to main since this release
ac8f6b3

ChronoStack 0.1.0-alpha.8 (pre-release): Stripe Test Clocks for your Docker Compose stack.

Install

Linux / macOS:

curl -fsSL https://github.com/Asmodeus14/ChronoStack/releases/download/v0.1.0-alpha.8/install.sh | CHRONOSTACK_VERSION=0.1.0-alpha.8 sh

Windows (PowerShell):

$env:CHRONOSTACK_VERSION = "0.1.0-alpha.8"; irm https://github.com/Asmodeus14/ChronoStack/releases/download/v0.1.0-alpha.8/install.ps1 | iex

Homebrew (macOS, Linux) or Scoop (Windows); both are updated a few minutes after this release is published:

brew install asmodeus14/tap/chronostack
scoop bucket add chronostack https://github.com/Asmodeus14/scoop-bucket
scoop install chronostack/chronostack

crates.io: cargo install chronostack@0.1.0-alpha.8.

The CLI pulls the matching controller image (ghcr.io/asmodeus14/chronostack-clockd:0.1.0-alpha.8, pinned by digest) on first chronostack up. Every file below is listed in SHA256SUMS; the SBOM is SPDX JSON.

Verified for this release

  • Automated: unit tests on Linux, Windows and macOS; end-to-end tests (M1–M4, init, shared mounts, expose and simulated users) on Linux x86_64 and arm64; a nightly check that simulated users on the virtual clock give the same timeline run after run; M1 and M2 with the native macOS CLI on an Intel macOS runner (Docker in a Linux VM); a smoke test that installs from these files on fresh Linux x86_64 and arm64 runners and runs the demo scenario; an install test on Apple-silicon and Intel macOS runners (installer, native binary, init and config; no Docker engine).
  • Manual checklist (not automated):
    • macOS on Apple silicon with a running Docker engine (Docker Desktop or OrbStack): not yet tested, see issue #5
    • Windows 11 + Docker Desktop (WSL2): tested by the maintainers during development

Changes

Added

  • expose: in chronostack.yml publishes chosen container ports of the copy on 127.0.0.1: app:3000 on a free port, or {service: app, port: 3000, host_port: 8080} on a fixed one. Nothing else is published, so the copy still runs next to your own stack. up and doctor show the URLs (exposed in doctor --json). In HTTP triggers, barriers and scenario http steps, service://app:3000/path goes to that port; chronostack.yml is checked so such a URL names an exposed port.
  • chronostack users run <file> and chronostack users validate <file>: simulated users. A journey file lists cohorts (how many users, when they arrive: evenly or Poisson over a window) and the steps each user takes: http requests with expect (status, JSON values) and save (JSON pointers into the response, used later as ${name}), think times, branch: {p} and repeat. Every random choice comes from a seed (--seed or seed:), so a run can be repeated. Targets can be service:// URLs from expose:. The summary shows runs, failures and p50/p90/p99/max latency per step; --json and --junit write reports; a failed step exits with 6. Users run in real time for now, with thinks capped at max_think (default 30s).
  • Simulated users on the virtual clock: users: journeys.yml in a scenario (or { file, resolution }). Users arrive and think in virtual time from the scenario's start, so think: 13d passes in no real time. During each advance the clock also stops wherever users are due: they act (up to max_parallel at once), then the barriers must hold again, then time moves on. Due times are rounded up to resolution (default 1m) and follow only the seed, so the same seed gives the same timeline of who did what when. The report adds a users table, the JSON report has the full timeline (users.timeline), JUnit gets a test case per journey step, and a failed user step fails the scenario. Users still mid-journey when the scenario ends are reported as stopped.
  • The demo has a cohort scenario (examples/saas-trial-demo/scenarios/cohort.yml): 20 trialists over 30 virtual days with a webhook outage. Every trialist must be downgraded and every trial.expired webhook delivered exactly once; with compose.bug.yml it fails on that check. The demo's chronostack.yml exposes api:3000. A nightly job runs a users scenario 10 times and requires one timeline, runs the demo cohort twice, and checks that the bug variant fails.
  • MCP: six more tools, 17 in all. env_inspect (services, triggers with schedules, barriers, proxy targets and exposed ports in one call), scenario_validate (a scenario's steps, how far it moves virtual time and its users, without running it, and whether it fits mcp.max_advance), report_get (a run's report by id or the latest), report_diff (whether the result, a step's status, user outcomes or the users' timeline changed between two runs), users_validate and users_run (real-time journeys, limited by the new mcp.max_users, default 1000, and stopping themselves before mcp.max_wall). scenario_run also returns the run id and the users' outcomes. The new tools declare an outputSchema. GUIDE section 10 has config for Claude Code, Cursor and Gemini CLI.
  • chronostack run <scenario> --check: validate a scenario and its users file and show its steps, how far virtual time will move and its users, without running it.
  • Scoop (Windows): scoop bucket add chronostack https://github.com/Asmodeus14/scoop-bucket, then scoop install chronostack/chronostack. The bucket is updated when a release is published.
  • Publishing to crates.io: chronostack, chronostack-users and chronostack-core are published from each release's tag (cargo install chronostack@<version>), starting with this release.
  • Benchmark B3 (bench/): chronostack users run with 200 users against a local echo server, about 8,000–24,000 requests per second at max_parallel 32 on a laptop and GitHub's runners. Docs for simulated users: GUIDE section 8 and docs/schema/journeys.schema.json.

Changed

  • A CLI built from source in release mode (as cargo install does) now uses the published controller image for its version, ghcr.io/asmodeus14/chronostack-clockd:<version>, instead of a locally built chronostack/clockd:dev it can't find. Debug builds still use the local image. Release downloads are unchanged (pinned by digest).
  • chronostack update also refuses to replace a Scoop install and says to run scoop update chronostack, as it does for Homebrew.