RFC-055: client() — contract-driven callers as first-class trace actors

[avatar29A]

Implements RFC-055 — client(), a topology entity that turns an API contract into a named caller bound to a service interface, and makes that caller a first-class actor in the trace.

Closes #149.

Why

Faultbox already ingests contracts, but only to serve them: RFC-021 generates HTTP mock routes from OpenAPI, RFC-023 generates typed gRPC responses from a FileDescriptorSet. Both are callee-side. On the caller side every request is hand-assembled:

resp = courier.main.call(method = "/courier.v1.CourierService/GetOrder", body = '{"order_id": 42}')

Nothing checks the path, the verb, or that the field is order_id and not orderId. And every driver-initiated call is emitted as step_send with service = "test", so a scenario with a mobile client, a partner integration, and an admin tool renders as one undifferentiated lane. You can't ask "did the partner client see the error?"

This is the same drift problem RFC-021 identified for mocks, pointed the other way — plus a trace-clarity problem that only shows up once more than one logical caller exists.

What it looks like

orders  = service("orders", interface("public", "http", 8080), image = "orders:2.1")
courier = service("courier", interface("main", "grpc", 9090, spec = "./courier.pb"), image = "courier:1.4")

mobile   = client("mobile-app",   target = orders.public, openapi = "./orders.yaml", validate = "response")
gcourier = client("gRPC-Courier", target = courier.main)   # contract from interface(spec=)

def test_order_flow():
    o = mobile.create_order(body = {"item_id": "sku-1", "qty": 2})
    with fault(courier.main, grpc_faults.unavailable()):
        r = gcourier.get_order(order_id = o.data["id"])
        assert_true(not r.ok)

Three things beyond autogeneration

Clients are their own trace actors. Events carry service = <client name> — what the event log keys lanes and vector clocks on — so N logical callers show up as N participants. The test → client clock merge on the way out is load-bearing: without it the client's lane reads as an independent process spontaneously emitting requests.

Contract conformance becomes assertable. validate="response" checks each response against the schema declared for its status code. It deliberately does not raise — a contract violation under fault is usually the finding, not a harness error. An undeclared status counts as a violation, which is how the undocumented degraded path surfaces. From the poc run in this PR:

#3   mobile-app   client_call.orders         → mobile-app.get_order GET /orders/1001
#5   mobile-app   client_return.orders       ← mobile-app.get_order 200 (0ms)
#6   mobile-app   contract_violation.orders  Error at "/courier_eta": Value is not nullable

No assertion described the expected shape. validate="response" caught it against the contract the service publishes.

interface(spec=) is finally read. The kwarg has been parsed and stored since early versions with nothing consuming it. A client that declares no contract inherits it, choosing the loader by extension.

Shape of the change

Phase	What
1	internal/protocol/: client_contract.go (OperationTable, snake_case naming, collision detection, "did you mean" resolution), openapi_client.go (operation walk, request binding, request/response conformance), grpc_client.go (descriptor walk, dynamicpb encode, unary invoke, typed decode)
2	internal/star/: client.go (ClientVal, OperationVal, call path, before= hook, event emission), client_builtins.go (the builtin, contract resolution, name validation)
3	Downstream consumers that had step_send/step_recv hard-coded: report keep-set, app.js (ten inline checks → isCallEvent/isSendEvent/isRecvEvent), normalized trace, assertion-failure context, dotted event_type
4	faultbox inspect --clients, docs/spec-language.md, docs/cli-reference.md, poc/client-rfc055/

Reuses kin-openapi and google.golang.org/protobuf — both already required. No new dependencies.

Two fixes this surfaced

• mock_service(openapi=) resolved contract paths against the process CWD, not the spec directory, so "./api.yaml" only loaded when faultbox ran from the directory containing the spec. Now spec-relative, matching load_file(), build=, and client(). The poc example is what exposed it.
• events() filtered to four hard-coded types, so client events were invisible to the builtin users reach for first. Client types are now queryable; step_send/step_recv deliberately stay out — admitting them would silently change what events() returns for existing specs.

Testing

Full suite green, go vet clean. New coverage: contract naming and collisions, parameter partitioning, request binding and its error messages, response conformance, client spec-load validation, event emission and vector-clock merges, and the downstream-consumer migration.

Two tests specifically guard claims that are true by construction and would otherwise break silently under refactor: that clientAddr redirects to the proxy listener (the entire "faults apply to client calls unchanged" story rests on that one lookup), and that match.event(...) selects client events with no new syntax (RFC OQ-3 deferred the match.call() sugar on the strength of that property).

Two end-to-end loops drive the real RFC-021/023 mocks from the same contract the client was built from.

Not in this PR

Per the RFC's resolved questions: streaming RPCs (skipped when the table builds, rest of the descriptor set still loads), load generation (RFC-050's load() — the identity model is in place for it), request synthesis, contract formats beyond OpenAPI/proto, retry emulation, cookie jars. before= is HTTP-only.

Review follow-ups (addressed in this PR)

Four gaps called out after the first push, all now closed:

• Tutorial chapter 28 — the RFC's Phase 4 listed one and it hadn't been written. Placed in Part 3 next to the mock chapters it mirrors: ch18/19 generate the dependency you can't run, ch28 generates the caller that drives you.
• gRPC end-to-end through Starlark — every prior client test in internal/star was HTTP. client(descriptors=) → attribute call → client event is now covered, driving the typed mock and typed client from the same descriptor set, plus the failure shape (a gRPC status is an outcome on the Response, not a Go error).
• fault(<client>) diagnostics — returned a bare type mismatch. Now explains why a client has nothing to fault and shows both forms against the target it already knows. Same for fault_start().
• CHANGELOG correction — the events() entry claimed more than shipped. main's v0.14.1 had already removed the type gate from the where= path; what this PR adds is the dict-filter form.

Site docs also wired: README feature bullet + docs table, docs/index.md, tutorial README and part index, and a feature-manifest.md row (the manifest is authoritative — a feature without a row isn't claimed as supported). Plus a drive-by fix for a broken README link to a tutorial directory that hasn't existed under that name in a while.

Rebase note

main moved during development (v0.14.0 gVisor and v0.14.1 both shipped). Rebased clean. One conflict worth flagging: v0.14.1 independently fixed the events() gap, and better — it removed the type gate from the where= path entirely, since the lambda is the filter and pre-filtering had been silently hiding proxy, unmediated_io, and packet events from predicates that named them. I kept main's fix and narrowed mine to what it still adds: client types in the dict-filter path.

🤖 Generated with Claude Code