# Migrating from 0.4 to 0.5
kode-bridge 0.5 replaces `interprocess` with a small transport layer backed by
Tokio Unix domain sockets and Windows named pipes. The HTTP-over-IPC wire
format, normal client and server constructors, request builders, routing, pool
behavior, and streaming formats are unchanged.
## Requirements
Update the dependency and toolchain together:
```toml
[dependencies]
kode-bridge = "0.5"
```
- The minimum supported Rust version is 1.87.
- The default feature remains `client`.
- Use `features = ["server"]` for server-only applications and
`features = ["full"]` when both sides are needed.
## Necessary API changes
Version 0.4 exposed three types owned by `interprocess`. Version 0.5 replaces
only those boundaries with kode-bridge-owned types.
| `with_listener_options(interprocess::...::ListenerOptions)` | `with_listener_options(kode_bridge::ListenerOptions)` | Import and construct `kode_bridge::ListenerOptions`. |
| `ConnectionPool::{new, with_default_config}(Name)` | The same methods accepting `kode_bridge::Endpoint` | Validate the path once with `Endpoint::new(path)?`. |
| `PooledConnection::{stream, into_stream}` returning `LocalSocketStream` | The same methods returning `kode_bridge::IpcStream` | Remove explicit `LocalSocketStream` annotations. `IpcStream` implements Tokio `AsyncRead` and `AsyncWrite`, including vectored writes. |
Direct pool construction now uses an `Endpoint`:
```rust
use kode_bridge::{
pool::{ConnectionPool, PoolConfig},
Endpoint,
};
let endpoint = Endpoint::new("/tmp/service.sock")?;
let pool = ConnectionPool::new(endpoint, PoolConfig::default());
```
Most applications only use `IpcHttpClient::new`, `IpcStreamClient::new`,
`IpcHttpServer::new`, or `IpcStreamServer::new`; those constructors still
accept a path and do not require an explicit `Endpoint`.
## Endpoint rules
Use a platform-appropriate endpoint:
```rust
#[cfg(unix)]
let endpoint = "/tmp/service.sock";
#[cfg(windows)]
let endpoint = r"\\.\pipe\service";
```
- Unix endpoints are file-system paths and cannot contain an interior NUL.
- Windows endpoints must use `\\HOST\pipe\NAME`; normal local endpoints use
`\\.\pipe\NAME`.
- Endpoint validation now happens when the client, server, or `Endpoint` is
constructed.
## Listener configuration
The convenience builders retain their 0.4 call shape:
```rust
#[cfg(unix)]
let server = IpcHttpServer::new("/tmp/service.sock")?
.with_listener_mode(0o640);
#[cfg(windows)]
let server = IpcHttpServer::new(r"\\.\pipe\service")?
.with_listener_security_descriptor("D:(A;;GA;;;WD)");
```
For advanced Unix listener behavior:
```rust
#[cfg(unix)]
let options = kode_bridge::ListenerOptions::new()
.reclaim_name(true)
.try_overwrite(true)
.max_spin_time(std::time::Duration::from_millis(100));
```
Important behavior:
- `reclaim_name(true)` remains the default and removes the listener's own Unix
socket path on drop.
- Stale Unix sockets are not replaced unless `try_overwrite(true)` is set.
- Overwrite refuses regular files and listeners that still accept connections.
- Unix compare-and-delete cannot be made atomic with the safe standard-library
APIs used here. Put production sockets in a trusted parent directory.
- Custom Unix mode is applied after bind and before listen on Linux and macOS.
- HTTP request handlers receive the accepted connection's kernel-reported Unix
UID/GID through `RequestContext::client_info.peer_credentials`. Connections
are rejected if those credentials cannot be read.
- Windows named pipes reject remote clients. A configured SDDL descriptor is
applied to every pipe instance.
- Invalid Windows SDDL retains the 0.4 builder behavior and panics during
configuration. Validate untrusted SDDL before passing it to the builder.
## Behavior preserved by the new transport
- HTTP request and response bytes, headers, methods, and JSON handling
- Client request timeouts and retry boundaries
- Pool reuse, invalidation, preheating, and per-connection request limits
- Unix listener cleanup and explicit stale-path policy
- Windows pipe-busy retry, 512-byte pipe buffers, and flush-on-drop delivery
- HTTP-style streaming client parsing and newline-delimited stream-server frames
## Identity hooks restored in 0.5.1
The `0.5.1` release restores the identity hooks used by privileged services:
```rust
let config = kode_bridge::ClientConfig {
require_windows_server_system: false,
#[cfg(windows)]
windows_server_pid_verifier: Some(verify_registered_service_pid),
..Default::default()
};
```
On Windows the verifier receives the PID reported by the newly opened named
pipe handle. It runs once for each physical connection before that connection
is returned to the caller or pool. Pool reuse does not repeat verification;
discarding and reconnecting does. `require_windows_server_system` applies the
library's LocalSystem token check and can be used independently of a custom
verifier.
This restoration changes complete public struct literals. `ClientConfig`
literals must include `require_windows_server_system` and, on Windows,
`windows_server_pid_verifier`, or use `..Default::default()`. `ClientInfo`
literals must include `peer_credentials: PeerCredentials::default()` when no
kernel identity is available (for example, in unit-test fixtures).
`IpcStreamClient` and `IpcStreamServer` are not a matched pair in 0.5:
`IpcStreamClient` consumes an HTTP-style streaming response, while
`IpcStreamServer` broadcasts raw newline-delimited messages. This is existing
behavior, not a transport migration change.
## Verification checklist
After updating:
```bash
cargo check --all-features
cargo test --all-features
cargo doc --all-features --no-deps
```
Applications that directly used one of the three replaced public types should
also compile their own public API or downstream fixture.
To compare performance on the same host and toolchain:
```bash
cargo bench --all-features --bench bench_version
cargo bench --all-features --bench ipc_transport
```
Do not compare Criterion results from different hosts or shared CI runners as
if they were a controlled before/after measurement.