Phase21 API Symmetry

[JustinKovacich]

Summary

Phase 21 is the API ergonomics pass that closes out 0.8.0 (audit was run in late April against 9b4b4c8; six sub-tasks shipped over the back half of phase development). It does not introduce new functionality — every change is about making the existing Client / Server / *Deps / transport surface easier to read, harder to misuse, and consistent between the two sides.

The motivating audit found five concrete frictions: (1) Client and Server had divergent generic-parameter orders that punished anyone maintaining bounds against both; (2) Server::new was an async fn returning Self, so callers had to remember to also spawn server.run() and server.announcement_loop() separately, and forgetting either was silent; (3) mid-tier Deps customization required hand-assembling the full struct literal even to swap one field; (4) the channel types
define_static_channels! needs were documented only in source comments and example code; (5) ServerConfig assembly was struct-literal only. All five are fixed.

The work is bundled into 0.8.0 because no v0.8.0 tag was ever cut and nothing was published, so the "breaking" framing in any
internal phase 21 commit is breaking against transient in-tree state nobody saw — the only baseline that matters externally is 0.7.0.

Headline API changes (vs. 0.7.0)

Server::new returns a tuple now — same shape as Client::new:

// Before (transient in-tree shape, never published):
let mut server = Server::new(config).await?;
let publisher = server.publisher();
tokio::spawn(server.announcement_loop()?);
tokio::spawn(async move { server.run().await });

// After:
let (_server, handles, run) = Server::new(config).await?;
let publisher = handles.publisher;
tokio::spawn(run);

The single returned run-future drives both the receive loop and the SD OfferService announcement loop concurrently via select. The dispatcher topology where a co-located Client emits the offers (used in examples/client_server) opts in via ServerConfig::with_announce(false) instead of "just don't call announcement_loop."

SubscriptionHandle::subscribe / unsubscribe are now GATs — SubscribeFuture<'a> / UnsubscribeFuture<'a> named associated types instead of RPIT. Lets Server::run declare + Send + 'static explicitly with for<'a> Sub::SubscribeFuture<'a>: Send bounds, so tokio::spawn-vs-!Send-handle mismatches surface at the library boundary instead of inside tokio::spawn's bound check.

Generic-parameter order aligned — Client<MessageDefinitions, F, Tm, R, I, Sp, C> and Server<F, Tm, R, Sub, H, Hsd, Hep> now share F/Tm/R in the same positions. Letter-collisions between Spawner (S on Client) and SubscriptionHandle (S on Server) resolved with Sp and Sub respectively.

Tokio-defaulted Deps builders — ClientDeps::tokio() / ServerDeps::tokio() produce a fully-defaulted bundle; chain with_factory / with_timer / with_e2e_registry / with_subscriptions / with_spawner / with_local_spawner to override individual fields without spelling the rest out.

ServerConfig fluent builder —
ServerConfig::new(svc, inst).with_interface(…).with_local_port(…).with_ttl(…).with_event_group(…).with_announce(…). Existing struct-literal route stays open; builder is the recommended path in docs.

Discoverable channel types — new ClientChannelTypes trait alias + client::channels rustdoc surface for the types define_static_channels! populates.

Smaller surface deletions

• Server::announcement_loop / announcement_loop_local removed (folded into the combined run-future).
• Server::set_local_port removed — vestigial; the constructor's bind-time back-fill already records the kernel-assigned port into
  config.local_port before Server::new returns, so post-construction mutation would lie to peers.
• announcement_loop_started: AtomicBool latch gone — single entry point makes the "started twice" failure mode structurally impossible.

Architectural cleanup

The receive loop, announcement loop, and SD-message handling are factored out of &self methods on Server into free async fns in src/server/runtime.rs. Server::run clones the cheap shared-handles into an async move so the returned future is independent of the &self borrow — that's what lets the constructor return (Server, ServerHandles, run-future) without aliasing the same struct.

Net diff for the run-loop work alone: −254 lines despite adding GATs, a new submodule, a behavioral test for with_announce(false) suppression, and the post-review fixes (cancel-safety SAFETY comment restored, ServerHandles re-exported, doctest examples switched from ignore to no_run).

Out of scope (parked)

• define_client_channels! convenience macro wrapping define_static_channels! (depends on whether we ship a default channel-pool
  profile someday).
• InterfaceHandle parallel on Server (server's offered endpoint is fixed at config per spec — symmetry-for-symmetry's-sake is wrong here).
• client::Error::InvalidUsage to mirror server's variant (no reported pain).
• Trait-surface architectural changes (TransportFactory, ChannelFactory, etc.).

Test plan

• cargo check --workspace --all-targets — clean, zero warnings.
• cargo test --features server-tokio,client-tokio,bare_metal --tests --lib -- --test-threads=1 — 518 lib + 5 embassy-net + 11
  client_server integration + 9 bare-metal/static-channels witnesses + 1 smoke, 543 passing, 3 ignored vsomeip docker-deps.
• cargo test --doc — 13 passed; the 1 remaining failure (src/lib.rs - transport (line 309)) is pre-existing on main, verified via git stash.
• Live-wire embassy-net loopback test (client_receives_server_sd_announcement) — passes, witnessing the new combined run-future drives announcements correctly through the embassy-net stack.
• Pre-existing parallel-test flake in tests/client_server.rs unchanged (still passes serially via --test-threads=1).
• examples/client_server adopts with_announce(false) for the dispatcher topology.
• examples/embassy_net_client and simple-someip-embassy-net/tests/loopback.rs use run_with_buffers with Box::leak'd static buffers (the !Send-friendly path).
• Behavioral negative test (with_announce_false_suppresses_offer_service) bound at 2.5s — listens on the SD multicast group and asserts no OfferService for the configured (SID, IID) is emitted.

[Copilot]

Pull request overview

Phase 21 finalizes the 0.8.0 API ergonomics/symmetry pass by reshaping the Server constructor/run surface to mirror Client, aligning generic ordering, and improving configurability + docs for static channels and deps bundles.

Changes:

• Reshapes Server::new* to return (Server, ServerHandles, run_future) and folds SD announcements into the combined run future (with ServerConfig::with_announce(false) to suppress).
• Promotes SubscriptionHandle::{subscribe,unsubscribe} return types to GATs (SubscribeFuture/UnsubscribeFuture) to make Send bounds explicit at the API boundary.
• Adds fluent builders (ServerConfig::with_*, ClientDeps::tokio()/ServerDeps::tokio() + with_*) and improves discoverability docs for static channel requirements.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/vsomeip_sd_compat.rs	Updates SD compatibility tests to spawn the new combined server run future.
tests/client_server.rs	Updates test helpers/call sites for new Server::new tuple return and config builder.
tests/bare_metal_server.rs	Migrates mock SubscriptionHandle impl to GAT futures; adapts to new server constructor return.
tests/bare_metal_e2e.rs	Same migration as above for the bare-metal E2E test harness.
src/static_channels/mod.rs	Adds rustdoc guidance pointing users to ClientChannelTypes requirements.
src/server/subscription_manager.rs	Introduces GATs on SubscriptionHandle + updates tokio/bare-metal impls accordingly.
src/server/sd_state.rs	Updates unit tests to use new ServerConfig builder API.
src/server/runtime.rs	New module extracting server runtime loops (recv, announce, SD handling) as free async fns.
src/server/mod.rs	Major server API reshape: new ServerHandles, ServerStorage rename, new run/run_with_buffers futures, fluent ServerConfig.
src/lib.rs	Updates public re-exports (ServerStorage) and documents intentional non-reexports on client channel types.
src/client/mod.rs	Adds ClientChannelTypes marker trait + tokio-defaulted ClientDeps and fluent builders; reorders deps generics.
simple-someip-embassy-net/tests/loopback.rs	Adapts embassy-net loopback tests to the new server run model and SubscriptionHandle GATs.
examples/embassy_net_client/src/main.rs	Updates embassy-net example to spawn server via run_with_buffers and new config builder.
examples/client_server/src/main.rs	Updates dispatcher-topology example to with_announce(false) and constructor-returned run future.
examples/bare_metal_server/src/main.rs	Updates bare-metal server example to spawn the combined run future.
CHANGELOG.md	Documents the 0.8.0 Phase 21 breaking changes and migration guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.