Repository navigation
·
3 commits
to main
since this release
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 shWindows (PowerShell):
$env:CHRONOSTACK_VERSION = "0.1.0-alpha.8"; irm https://github.com/Asmodeus14/ChronoStack/releases/download/v0.1.0-alpha.8/install.ps1 | iexHomebrew (macOS, Linux) or Scoop (Windows); both are updated a few minutes after this release is published:
brew install asmodeus14/tap/chronostackscoop bucket add chronostack https://github.com/Asmodeus14/scoop-bucket
scoop install chronostack/chronostackcrates.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,exposeand 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,initandconfig; 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:inchronostack.ymlpublishes chosen container ports of the copy on 127.0.0.1:app:3000on 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.upanddoctorshow the URLs (exposedindoctor --json). In HTTP triggers, barriers and scenariohttpsteps,service://app:3000/pathgoes to that port;chronostack.ymlis checked so such a URL names an exposed port.chronostack users run <file>andchronostack 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:httprequests withexpect(status, JSON values) andsave(JSON pointers into the response, used later as${name}),thinktimes,branch: {p}andrepeat. Every random choice comes from a seed (--seedorseed:), so a run can be repeated. Targets can beservice://URLs fromexpose:. The summary shows runs, failures and p50/p90/p99/max latency per step;--jsonand--junitwrite reports; a failed step exits with 6. Users run in real time for now, with thinks capped atmax_think(default 30s).- Simulated users on the virtual clock:
users: journeys.ymlin a scenario (or{ file, resolution }). Users arrive and think in virtual time from the scenario's start, sothink: 13dpasses in no real time. During eachadvancethe clock also stops wherever users are due: they act (up tomax_parallelat once), then the barriers must hold again, then time moves on. Due times are rounded up toresolution(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 everytrial.expiredwebhook delivered exactly once; withcompose.bug.ymlit fails on that check. The demo'schronostack.ymlexposesapi: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 fitsmcp.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_validateandusers_run(real-time journeys, limited by the newmcp.max_users, default 1000, and stopping themselves beforemcp.max_wall).scenario_runalso returns the run id and the users' outcomes. The new tools declare anoutputSchema. 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, thenscoop install chronostack/chronostack. The bucket is updated when a release is published. - Publishing to crates.io:
chronostack,chronostack-usersandchronostack-coreare published from each release's tag (cargo install chronostack@<version>), starting with this release. - Benchmark B3 (
bench/):chronostack users runwith 200 users against a local echo server, about 8,000–24,000 requests per second atmax_parallel32 on a laptop and GitHub's runners. Docs for simulated users: GUIDE section 8 anddocs/schema/journeys.schema.json.
Changed
- A CLI built from source in release mode (as
cargo installdoes) now uses the published controller image for its version,ghcr.io/asmodeus14/chronostack-clockd:<version>, instead of a locally builtchronostack/clockd:devit can't find. Debug builds still use the local image. Release downloads are unchanged (pinned by digest). chronostack updatealso refuses to replace a Scoop install and says to runscoop update chronostack, as it does for Homebrew.