Struct ConnectError

Source

pub struct ConnectError {
    pub code: ErrorCode,
    pub message: Option<String>,
    pub details: Vec<ErrorDetail>,
    /* private fields */
}

Expand description

A ConnectRPC error.

Fields§

§code: ErrorCode

The error code.

§message: Option<String>

Human-readable error message.

§details: Vec<ErrorDetail>

Additional error details.

Implementations§

Source §

impl ConnectError

Source

pub fn new(code: ErrorCode, message: impl Into<String>) -> Self

Create a new error with the given code and message.

Source

pub fn with_headers(self, headers: HeaderMap) -> Self

Add response headers to be included in the error response.

Source

pub fn with_trailers(self, trailers: HeaderMap) -> Self

Add response trailers to be included in the error response.

Source

pub fn response_headers(&self) -> &HeaderMap

Borrow the response headers. Returns an empty map if none were set.

On an error returned by a client call, these are the headers the response arrived with. Every terminal error from a ServerStream carries them, whatever the protocol and whatever ended the stream.

Source

pub fn trailers(&self) -> &HeaderMap

Borrow the response trailers. Returns an empty map if none were set.

On an error returned by a client call, these are the trailing metadata the RPC ended with, populated whenever any was received — gRPC trailers or a Connect END_STREAM metadata object. The status-bearing gRPC trailers (grpc-status, grpc-message, grpc-status-details-bin) are excluded, because their content is this error’s code, message and details; ServerStream::trailers() reports the wire map verbatim if you need them.

Source

pub fn response_headers_mut(&mut self) -> &mut HeaderMap

Mutably borrow the response headers, allocating an empty map if none were set.

Source

pub fn trailers_mut(&mut self) -> &mut HeaderMap

Mutably borrow the response trailers, allocating an empty map if none were set.

Source

pub fn set_response_headers(&mut self, headers: HeaderMap)

Replace the response headers. An empty map is stored as None.

Source

pub fn set_trailers(&mut self, trailers: HeaderMap)

Replace the response trailers. An empty map is stored as None.

Source

pub fn with_http_status(self, status: StatusCode) -> Self

Set an HTTP status override for this error.

When set, this overrides the default HTTP status derived from the error code. This is useful for HTTP-level errors like 415 Unsupported Media Type.

Source

pub fn unsupported_media_type(message: impl Into<String>) -> Self

Create an error for unsupported media type (HTTP 415).

This is used when the client sends a content type that the server doesn’t support.

Source

pub fn method_not_allowed(message: impl Into<String>) -> Self

Create an error for method not allowed (HTTP 405).

This is used when the client uses an HTTP method other than POST.

Source

pub fn canceled(message: impl Into<String>) -> Self

Create a canceled error.

Source

pub fn unknown(message: impl Into<String>) -> Self

Create an unknown error.

Source

pub fn invalid_argument(message: impl Into<String>) -> Self

Create an invalid argument error.

Source

pub fn deadline_exceeded(message: impl Into<String>) -> Self

Create a deadline exceeded error.

Source

pub fn not_found(message: impl Into<String>) -> Self

Create a not found error.

Source

pub fn already_exists(message: impl Into<String>) -> Self

Create an already exists error.

Source

pub fn permission_denied(message: impl Into<String>) -> Self

Create a permission denied error.

Source

pub fn resource_exhausted(message: impl Into<String>) -> Self

Create a resource exhausted error.

Source

pub fn failed_precondition(message: impl Into<String>) -> Self

Create a failed precondition error.

Source

pub fn aborted(message: impl Into<String>) -> Self

Create an aborted error.

Source

pub fn out_of_range(message: impl Into<String>) -> Self

Create an out of range error.

Source

pub fn unimplemented(message: impl Into<String>) -> Self

Create an unimplemented error.

Source

pub fn internal(message: impl Into<String>) -> Self

Create an internal error.

Source

pub fn unavailable(message: impl Into<String>) -> Self

Create an unavailable error.

Source

pub fn data_loss(message: impl Into<String>) -> Self

Create a data loss error.

Source

pub fn unauthenticated(message: impl Into<String>) -> Self

Create an unauthenticated error.

Source

pub fn with_detail(self, detail: ErrorDetail) -> Self

Add an error detail.

Source

pub fn with_source( self, source: impl Into<Box<dyn Error + Send + Sync>>, ) -> Self

Attach the underlying cause, surfaced through Error::source.

Unlike message (which is sent over the wire and shown to callers), the source is local-only — useful for logging/observability without leaking internal detail to the client. It is never populated by decoding a ConnectError received over the wire (there is nothing to attach), only by local code that calls this method — so source() on an error a client parsed from a server response is always None. Accepts either a concrete error or an already-boxed one, so it composes with transport errors that are type-erased before reaching this call. Replaces any source attached by a previous call.

Source

pub fn http_status(&self) -> StatusCode

Get the HTTP status code for this error.

Returns the HTTP status override if set, otherwise derives it from the error code.

Source

pub fn to_json(&self) -> Bytes

Encode this error as JSON bytes.

Source §

impl ConnectError

Source

pub fn into_http_response( self, request_headers: &HeaderMap, ) -> Response<ConnectRpcBody>

Render this error as a complete HTTP response in the wire format matching the inbound request’s protocol.

This is the building block for tower::Layers that short-circuit a request (auth, rate limiting, validation) before it reaches ConnectRpcService. A layer cannot reuse the service’s internal error rendering, but still needs to produce a response that the calling client will decode as a structured error rather than a transport failure. Each protocol expects a different wire shape:

Connect unary (application/proto, application/json, or absent — Connect GET requests carry no request body or Content-Type): a non-200 HTTP status with a JSON error body. Connect unary error bodies are spec-required JSON regardless of the request codec.
Connect streaming (application/connect+{proto,json}): HTTP 200 with the error in an EndStreamResponse envelope.
gRPC / gRPC-Web (application/grpc*): HTTP 200 with grpc-status and grpc-message trailers (as HTTP/2 trailers for gRPC, encoded in the body for gRPC-Web).

The protocol is detected from request_headers via Protocol::detect. When detection fails — an unrecognized Content-Type, or none at all — the Connect unary JSON shape is used, which is the most universally parseable fallback.

gRPC and gRPC-Web use the same framed wire shape for unary and streaming calls, so the trailers-only response is always correct regardless of the method’s cardinality.

§Example

use connectrpc::ConnectError;

// Inside a tower::Service::call wrapping ConnectRpcService:
fn call(&mut self, req: http::Request<B>) -> Self::Future {
    if !self.is_authorized(&req) {
        let resp = ConnectError::permission_denied("access denied")
            .into_http_response(req.headers());
        return Box::pin(std::future::ready(Ok(resp)));
    }
    // ... call inner service ...
}