feat(ringo-flow): HTTP mock server for webhook scenarios

[davidborzek]

What

A scriptable HTTP mock server for ringo-flow, for testing webhook-driven
telephony APIs: the system under test calls a webhook for a call and the
scenario answers with the actions to perform.

let hooks = mock_server();

hooks.on("POST", "/voice", |req| {
    if req.json("event") == "incoming_call" {
        json_response(#{ actions: [ #{ type: "answer" } ] })
    } else {
        json_response(#{ actions: [ #{ type: "hangup" } ] })
    }
});

http("PUT", env("API_URL") + "/config?webhook=" + hooks.url + "/voice");
a.dial(env("API_NUMBER"));

await_until(|| assert(hooks.request_count("/voice")).equals(1), "10s");
assert(hooks.last_request("/voice").json("event")).equals("incoming_call");

Details

• mock_server([#{port}]) — free port by default; runs on the shared tokio
  runtime, torn down at reset_sessions (per-scenario/-file isolation), and the
  serving task is awaited so the port is released before the next bind.
• Routes: respond (static) and on (Rhai-closure) responders. Match by exact
  path or regex("/calls/.*"), and by a method or any ("*" / omit it).
  Precedence: exact path > regex, exact method > any; re-registering a route
  replaces it in place (response staging).
• Inspection: request_count / last_request / requests, polled via the
  existing await_until — no second waiting mechanism. MockRequest exposes
  method / path / body / header / query / json.
• Helpers: json_response (map or array) and text_response.
• Responder failures are logged (and answered with a bare 500); the error text
  is never exposed over HTTP.

Testing

• Unit/roundtrip tests: static + dynamic responders, 404, request recording,
  regex + any-method routing, error-not-leaked, explicit-port release on teardown.
• cargo fmt --all --check, cargo clippy --all-targets, and
  cargo test -p ringo-flow -p ringo-core pass. Example
  examples/webhook-mock.rhai, README and generated docs updated.

🤖 Generated with Claude Code