feat: support typed in-process WIP clients without HTTP
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user