English

Español

English

Español

Appearance

Sword's gRPC API ​

Sword exposes the types and attributes needed to implement gRPC controllers on top of the code generated by tonic. This is the reference for that API.

Attribute reference ​

Attribute #[controller] ​

rust
#[controller(kind = Controller::Grpc, service = UserGrpcServiceServer)]

Parameters

  • kind = Controller::Grpc: marks the struct as a gRPC controller.
  • service = UserGrpcServiceServer: tonic-generated server for the service it implements.

When to use it

  • On the struct that implements the tonic-generated service trait.

Attribute #[sword::grpc::async_trait] ​

rust
#[sword::grpc::async_trait]
impl UserGrpcService for UsersController { ... }

When to use it

  • On the implementation of the tonic-generated trait, to enable async methods in traits.

Base types ​

Type Request<T> ​

rust
pub use tonic::Request;

Returns

  • A tonic wrapper over the incoming request, with access to into_inner() (the message) and metadata().

When to use it

  • As the input type in service methods (for example Request<GetUserRequest>).

Type GrpcResult<T> ​

rust
pub type GrpcResult<T> = Result<Response<T>, Status>;

Returns

  • Ok(Response<T>) if the call resolves successfully.
  • Err(Status) if the call fails.

When to use it

  • As the return type of service methods.

Type GrpcStream<T> ​

rust
pub type GrpcStream<T> = Pin<Box<dyn Stream<Item = Result<T, Status>> + Send + 'static>>;

Returns

  • A boxed stream of T messages or Status errors.

When to use it

  • As the type of the associated stream in server streaming methods (Self::StreamUsersStream).

Type Status ​

rust
pub use tonic::Status;

Returns

  • The standard gRPC error tonic uses to communicate failures.

When to use it

  • To build errors directly or to convert domain errors with #[derive(GrpcError)]. See gRPC Error Handling.

Type GrpcStatus ​

rust
GrpcStatus::InvalidArgument()
    .message("invalid request")
    .bad_request("username", "username cannot be empty")
    .into() // -> tonic::Status

Returns

  • A tonic::Status builder that implements the Richer Error Model, with one constructor per status code (InvalidArgument(), NotFound(), ...) and chainable builders for standardized details.

When to use it

  • When you need to return an error response with structured details (bad_request, localized_message, error_info, retry_after, help, debug_info, precondition_failure, quota_failure, request_info, resource_info).

Notes

  • Requires the grpc-error-details feature.
  • Converts to tonic::Status with .into() or .build().
  • On the client, GrpcStatus::from_status(&status) rebuilds the status and reads the details with StatusExt. See Rich errors with GrpcStatus.

Method reference ​

Method GrpcResponse::message() ​

rust
pub fn message<T>(value: T) -> tonic::Response<T>

Returns

  • A Response<T> with a single message.

When to use it

  • In unary and client streaming methods to return a typed response.

Method GrpcResponse::stream() ​

rust
pub fn stream<T, S>(stream: S) -> tonic::Response<GrpcStream<T>>
where
    S: Stream<Item = Result<T, Status>> + Send + 'static,

Returns

  • A Response<GrpcStream<T>> wrapping a stream.

When to use it

  • In server streaming methods to return a sequence of messages.

Operational notes ​

  • GrpcResponse is a stateless struct: its methods are static constructors.
  • In server streaming methods, the generated trait defines an associated type (for example type StreamUsersStream) that must match GrpcStream<T>.
  • Request<T> and Response<T> are the tonic types re-exported by sword::grpc.