1# Chapter 18½: inside jev-client/src — four files and a folder of tests
2
3Small crate, one loop. Read the ports first, because the loop is written
4entirely in terms of them; then the loop; then what it returns when things
5go wrong.
6
7## The files, in reading order
8
91. **[lib.rs](lib.rs)**: the crate's doc comment and its public surface,
10   re-exported from the three modules: `Client`, `Answered`, `ClientError`,
11   and the port types.
122. **[ports.rs](ports.rs)**: the two traits a host implements and the values
13   that cross them.
14   - `Transport`: `admit(&request)` (optional; the default waits for
15     nothing), `send(request)`, `distrust_connection()`.
16   - `Runtime`: `now()`, `wall_clock()`, `sleep(d)`, `timeout(d, future)`,
17     `jitter()` (uniform in [0, 1)).
18   - `HttpRequest { headers, body }`, `HttpResponse { status, headers, body }`.
19   - `TransportError { kind, message }` and `TransportErrorKind`, each kind
20     documented with what the client does about it.
21   - `Observer` and `Event`, for counters and logs; `()` is the observer that
22     hears nothing.
23   - `Instant`, which is `web_time::Instant`: `std::time::Instant` itself on
24     native targets, and a `performance.now()` clock on
25     `wasm32-unknown-unknown`, where std's `Instant::now` panics and a Worker
26     could not implement `Runtime::now` at all.
273. **[client.rs](client.rs)**: `Client::new(transport, runtime, model,
28   api_key)`, `observed(observer)`, `model()`, and `ask(state, questions)`,
29   the retry loop (Chapter 18 draws it). `MAX_REDIALS` = 2 lives here. At the
30   bottom, `mod tests;` pulls in [client/tests.rs](client/tests.rs).
314. **[error.rs](error.rs)**: `ClientError` and its five variants,
32   `nothing_billed()` and `request_id()`. Its `Display` appends the attempt
33   count when there was more than one, and `[request <id>]` when a response
34   carried one.
355. **[client/](client/)**: the tests for the loop, Chapter 18¾.
36
37> **Aside.** Why is there a `client.rs` and a `client/` folder? That is how
38> Rust spells "this module has a child module in its own file". `client.rs`
39> says `mod tests;`, and the compiler looks for `client/tests.rs`. Nothing
40> else lives in the folder.
41
42## Try it
43
44```
45cargo test -p jev-client
46```
47
48## For the people who maintain it
49
50### In this folder
51
52| Path | What |
53| --- | --- |
54| [lib.rs](lib.rs) | Doc comment and re-exports. |
55| [ports.rs](ports.rs) | `Transport`, `Runtime`, `Observer`, `Event`, the request, response and error types, `Instant`. |
56| [client.rs](client.rs) | `Client` and the retry loop in `ask`. |
57| [error.rs](error.rs) | `ClientError`, `nothing_billed`, `request_id`. |
58| [client/](client/) | Virtual-time tests for `Client::ask`. |
59| [CLAUDE.md](CLAUDE.md) | Invariants for agents. |
60
61← Previous: [Chapter 18: jev-client](../) · Up: [jev-client](../) · Next: [Chapter 18¾: jev-client/src/client](client/) →