interceptor: reject a request from its head before the body is read

[iainmcgin]

Interceptors run after the request body is read (unary) or after a body reader has started (streaming), so the only way to reject a request before any body byte is read was Tower middleware, which cannot see the resolved Spec.

Interceptor::intercept_head(&self, head: &mut RequestHead<'_>) runs for every registered interceptor, in registration order, before the body is read or a reader starts, on unary, streaming, gRPC unary and Connect GET requests. The first Err is returned to the client in the protocol's error format and the body is never read: an HTTP/2 stream is reset and an HTTP/1.x connection is usually closed, as for a Tower rejection. The default accepts every request, so existing interceptors are unchanged.

async fn intercept_head(&self, head: &mut RequestHead<'_>) -> Result<(), ConnectError> {
    let token = head.header("authorization").and_then(|v| v.to_str().ok());
    let Some(caller) = token.and_then(|t| self.verify(t)) else {
        return Err(ConnectError::unauthenticated("missing or invalid token"));
    };
    head.extensions_mut().insert(Caller(caller));
    Ok(())
}

RequestHead::spec() is None for an unknown path. Values inserted with extensions_mut() reach later interceptors and the handler.

The head is &mut so an authentication check can pass the caller on; adding mutability later would break every implementor.

All head checks run before any intercept_unary or intercept_streaming, so they see the headers as they reached the service, not as an outer interceptor rewrote them, and an outer interceptor never sees a head rejection. The hook runs before the request deadline applies, so it has no time limit. The guide now lists intercept_head next to Tower middleware as a place for authentication.

Requests rejected for an unsupported method or unrecognized content type never reach interceptors, and their body is still drained under max_request_body_size and the request deadline. Each registered interceptor allocates one boxed future per request for this method, even if it does not override it.