feat: support typed in-process WIP clients without HTTP

This commit is contained in:
2026-10-16 05:26:11 +09:00
parent 53fa44da26
commit eb92878e3c
9 changed files with 1725 additions and 154 deletions
+41
View File
@@ -1,5 +1,46 @@
# Structured Interface reference and scope publication migration
## Transport-independent Client API
The default `wip-client` feature set still exposes the HTTP-compatible
`wip_client::Client` and `PreparedRequest`. Its constructor takes state and wire
limits, sessions canonicalize HTTP endpoints, and `complete` consumes an HTTP
response. Existing TUI and native HTTP consumers need no source migration; the
wire contract is unchanged.
For an in-process Host (including Client and Host in one WASM module), disable
default features and use `wip_client::direct::{Client, Request, Response}`:
```toml
wip-client = { version = "0.2.0", default-features = false }
```
- `direct::Client::new(ClientLimits)` takes no wire limits.
- `open_session(worldspace_identity, SecurityContext)` accepts an opaque identity,
not a URL. Issue a separate identity per Worldspace view/Host lifetime and a
separate security identity whenever authorization context changes. Direct and
canonical HTTP session identities cannot alias each other's cache.
- Preparation methods retain their names and arguments. Their result is
`direct::PreparedRequest { id, request: Request }`, with `Observe`,
`FetchInterface`, and `CallOperation` variants containing Protocol request DTOs.
- Route that exact DTO to the session's Host/security context; mark calls
dispatched before invoking the Host. Complete with the original `id` and the
matching `Response` variant containing `Result<Protocol DTO, ProtocolError>`.
No HTTP request, response, JSON codec, or artificial endpoint is needed.
- Direct responses undergo the same semantic validation and state transitions
as HTTP responses. Wrong interactions and invalid results are rejected;
invalid call responses retain an unknown execution outcome. Retrievals may
be explicitly refreshed, but operations are never automatically retried.
- `ClientLimits` still bounds cache, sessions, in-flight requests, and history.
HTTP status/envelope checks and byte/JSON nesting limits belong to the optional
HTTP adapter. An embedding application owns DTO allocation/execution budgets.
The `direct` module API documentation contains a runnable typed example. Run
`cargo test -p wip-client --no-default-features` to exercise the core without an
HTTP dependency; ordinary `cargo test -p wip-client` also runs unchanged HTTP
regressions and direct/HTTP state parity tests.
The 0.2.0 API/wire change follows `wip-reference` canonical Core Model,
Protocol and WIP over HTTP at `6086f3c5ef10aa1464ce9c824750d7f667217bfd`.
It replaces the earlier opaque Interface reference contract; HTTP routes and