feat: declarative #[http_client] HTTP-interface client (26.6.28)

[ancongui]

What

A Spring Boot parity increment (26.6.28): the declarative HTTP-interface client — the highest single value lever from the 16-area parity-gap analysis (it lifts the REST/HTTP-clients area, the lowest at ~60%, off the floor).

#[http_client] is the analog of Spring 6's @HttpExchange (the modern OpenFeign replacement). Annotate a trait of methods with the same verb attributes a #[rest_controller] uses, and the macro generates a <Trait>Impl that issues the requests over a WebClient — the mirror image of a controller.

#[http_client(path = "/api/v1/orders", name = "orders", bean)]
pub trait OrdersClient {
    #[get("/:id")]
    async fn get_order(&self, id: String) -> Result<Order, ClientError>;
    #[get("/")]
    async fn list(&self, status: String, page: Option<u32>) -> Result<Vec<Order>, ClientError>;
    #[post("/")]
    async fn create(&self, #[header("X-Tenant")] tenant: String, order: CreateOrder) -> Result<Order, ClientError>;
    #[delete("/:id")]
    async fn cancel(&self, id: String) -> Result<(), ClientError>;   // 204 -> ()
    #[get("/stream")]
    fn stream(&self) -> Flux<Order>;
}
let api = OrdersClientImpl::new("https://orders.svc");

• Verbs: #[get("/path")]/#[post]/#[put]/#[delete]/#[patch] + generic #[request(method=…)]. Path vars use the framework's :id syntax (same as the server macro); {id} is a compile error.
• Binding needs no attributes in the common case: name-matched :var → path variable, lone non-scalar arg on a body verb → JSON body, the rest → query params (Option omits, Vec repeats). Override with #[path]/#[query("k")]/#[header("X")]/#[body]. Every :var must bind exactly once.
• Returns: async fn -> Result<T, ClientError> (default), Result<T, E: From<ClientError>>, non-async Mono<T>/Flux<T>, WebClientResponse escape hatch.
• DI: #[http_client(… bean)] registers <Trait>Impl as a @Service + binds dyn Trait, so #[autowired] Arc<dyn Trait> resolves (the Feign-client payoff).

Process

• Designed via a scored 3-proposal judge panel (Spring-faithful / firefly-consistent / ergonomic-minimal anchors) synthesized into one spec; two flagged API decisions (:id path syntax, <Trait>Impl naming) confirmed by the maintainer.
• Adversarially reviewed — the review caught a real runtime footgun: an Option/Vec path variable compiled and produced …/Some(x) / …/None URLs; it's now a compile error. Also fixed: custom-method body-inference + a runtime panic on a malformed #[request(method=…)], an object-safety gap under bean, and macro hygiene (mixed_site() for generated locals).

Tests

• In-process axum round-trip (real wire behavior): path-var encode (a/b→a%2Fb), Option query omission, header, JSON body, Vec decode, 204→(), 404→ClientError::Problem.is_not_found(), NDJSON Flux, empty-body→Ok(None) fold, custom-error map_err, and DI dyn Trait resolution.
• 15 trybuild compile-fail cases locking clean diagnostics ({id} syntax, two verbs, double #[body], ambiguous body, unbound :var, Option path var, missing &self, async-Mono, assoc-type under bean, #[request] missing method, …).
• Reuses the server #[rest_controller] verb grammar (MappingAttr/VERBS/join_path → pub(crate), no code moved) so client and server can't drift.

make ci green: 317 suites, 4503 tests, 0 failed. Book: a "declarative client" section in 13-http-clients.md.

Follows the rollback-rules increment (#29) on the parity roadmap.