cratestack_axum/rpc/
mod.rs

1//! Runtime primitives for the `transport rpc` generation style.
2//!
3//! See `docs/design/rpc-transport.md` for the full design. This module
4//! provides the binding-side surface that schemas with `transport rpc`
5//! generate against:
6//!
7//! - `POST /rpc/{op_id}` — unary calls. Body is the codec-encoded *input*
8//!   (no frame wrapper); response body is the codec-encoded *output* on
9//!   success, or an [`RpcErrorBody`] on error with HTTP status mapped via
10//!   [`CoolError::status_code`].
11//! - `POST /rpc/batch` — sequence of `RpcRequest` frames in, sequence of
12//!   `RpcResponseFrame` frames out in the same order. Per-frame errors
13//!   don't poison the batch.
14//!
15//! Subscriptions and streaming live on WebSocket and `application/cbor-seq`
16//! respectively; they are deferred to a follow-up patch.
17//!
18//! The macro emits the dispatch table and the `rpc_router` constructor.
19//! This crate provides the shared frame shapes, error mapping, and the
20//! `RPC_*_PATH` constants both sides agree on.
21
22mod batch;
23mod codec_helpers;
24mod error_encode;
25mod inputs;
26mod synthesize;
27mod util;
28
29#[cfg(test)]
30mod tests_error;
31#[cfg(test)]
32mod tests_frame;
33#[cfg(test)]
34mod tests_list;
35
36// Re-export the wire shapes from `cratestack-core::rpc`. Both the server
37// binding and every generated client agree on those shapes, and lifting
38// them into core means the client crates don't need to depend on axum.
39pub use cratestack_core::rpc::{
40    RPC_BATCH_PATH, RPC_UNARY_PATH, RpcErrorBody, RpcRequest, RpcResponseFrame,
41    cool_error_code_to_rpc_code, rpc_code,
42};
43
44pub use batch::response_to_frame;
45pub use codec_helpers::{decode_rpc_body, encode_rpc_value};
46pub use error_encode::{convert_handler_error_response, encode_rpc_error};
47pub use inputs::{RpcListInput, RpcListPredicate, RpcPkInput, RpcUpdateInput};
48pub use synthesize::synthesize_list_query;
49
50/// Codec/transport capabilities for every RPC binding route. Both unary
51/// and batch accept and emit CBOR or JSON, default CBOR; sequence
52/// responses (streaming) are not yet supported by this binding.
53///
54/// Used by `encode_transport_result_with_status_for` to negotiate
55/// response content type when the dispatcher synthesizes an error
56/// response or wraps a batch result.
57pub const RPC_BINDING_CAPABILITIES: cratestack_core::RouteTransportCapabilities =
58    cratestack_core::RouteTransportCapabilities {
59        request_types: &["application/cbor", "application/json"],
60        response_types: &["application/cbor", "application/json"],
61        default_response_type: "application/cbor",
62        supports_sequence_response: false,
63    };
cratestack_axum/rpc/mod.rs

cratestack_axum/rpc/
mod.rs
