Retry HTTP with an offline cassette
Retry a safe GET after a rate limit, with a finite attempt count and virtual time in tests.
Generated by cargo run -p agent_docs from compiler/examples/. Edit the example files, then regenerate.
Retry a safe GET after a rate limit, with a finite attempt count and virtual time in tests.
fetch declares HTTP, clock and random effects. Its policy retries only
RateLimited, at most three attempts, with exponential backoff and a one-second
retry deadline. Jitter is disabled for this example. It uses the policy's delays;
it does not interpret retry_after. The deadline bounds retry scheduling, not the
duration of an individual request. HttpError propagates immediately. Other HTTP
statuses remain responses for the caller to inspect.
The cassette returns 429 then 200 for the identical request. Http.recording is
wrapped by Http.scripted([]), so an exchange cannot fall through to the network,
even in recording mode. Clock.virtual advances without sleeping. Tests check
success after 100 ms, exhaustion after 300 ms, and immediate transport failure.
The harness uses test mode; the manifest grants no network or environment access.
Source project · harness mode: test.
From the repository root, with this checkout's sakura on PATH:
cd compiler/examples/http_retry
sakura check --json
sakura test --jsonManifest and permissions
[package]
name = "http_retry"
version = "0.1.0"
edition = "2026"
[permissions]Source and tests
src/main.sakura includes all required imports and tests.
// milestone: M3
// mode: test
// spec: design §17.145
import std/duration.{Duration}
import std/fs.{Fs}
import std/http.{Any, Http, RateLimited}
import std/path.{Path}
import std/response.{HttpError, Response, Status}
import std/retry
import std/retry.{Policy}
fn fetch() -> Response ! {Clock, Http, Random, Fail<HttpError | RateLimited>} {
let policy: Policy<HttpError | RateLimited> = Policy {
..retry.policy(
fn(err: HttpError | RateLimited) {
match err {
RateLimited { .. } => true,
HttpError { .. } => false,
}
},
3,
),
jitter: false,
deadline: Some(Duration.seconds(1)),
}
retry.retry(policy, fn() { Http.get(url"https://recipes.invalid/status") })
}
test "429 then success replays with a virtual backoff" {
with Fs.rooted(Test.fixtures()),
Http.scripted([]),
Http.recording(Path.of("status.jsonl")),
Clock.virtual() {
let response = fetch()
expect_eq(response.status, Status.from(200))
expect_eq(response.body, "ready")
expect_eq(Clock.monotonic(), Duration.millis(100))
}
}
test "three rejected attempts preserve RateLimited" {
with Http.scripted([(Any, Response.status(429, "busy"))]), Clock.virtual() {
expect_fails_with(fn() { fetch() }, fn(e) {
match e {
RateLimited { .. } => true,
_ => false,
}
})
expect_eq(Clock.monotonic(), Duration.millis(300))
}
}
test "a missing exchange does not reach a host or retry" {
with Http.scripted([]), Clock.virtual() {
expect_fails_with(fn() { fetch() }, fn(e) {
match e {
HttpError { .. } => true,
_ => false,
}
})
expect_eq(Clock.monotonic(), Duration.millis(0))
}
}tests/fixtures/README.md
# Synthetic cassette
Hand-authored request/response exchanges in the version 1 cassette format.
No live request, provider account, API key or recorded personal data was used.
Requests match method, URL, headers and body; secret headers are absent.
Tests install an empty scripted HTTP fallback, so a missing exchange fails offline.tests/fixtures/status.jsonl
{"schema_version":"1.0","kind":"cassette"}
{"method":"GET","url":"https://recipes.invalid/status","headers":[],"body":"","status":429,"response_headers":[],"response_body":"busy"}
{"method":"GET","url":"https://recipes.invalid/status","headers":[],"body":"","status":200,"response_headers":[],"response_body":"ready"}Compiler provenance and regeneration
These eight projects teach supported Sakura APIs on the JavaScript backend. Each
project is exercised offline by cargo test -p sakura_cli --test examples;
HTTP and LLM exchanges are synthetic committed cassettes, with no network or API keys.
Use Node 26 for execution, including its built-in SQLite implementation.
The initial API baseline is compiler revision
5cae349516c21714d90d36e87f1cfd6debe980c6.
CI reruns these projects against the compiler in the same checkout. Build that
checkout's CLI and run sakura --version and sakura prompt before adapting a recipe;
pre-alpha APIs can change. An installed skill's frontmatter records its compiler
version and build revision. These teaching examples are separate from the agent
evaluation tasks.
The source of each page is its example's recipe.md, sakura.toml,
src/main.sakura and fixture files. Run cargo run -p agent_docs from compiler/
to regenerate the cookbook and skill reference. Edit those sources, not the rendered pages.