Struct HttpIngress 

pub struct HttpIngress<R = ()> { /* private fields */ }

HTTP Ingress Circuit Builder.

Wires HTTP inputs to Ranvier Circuits. This is NOT a web server—it’s a circuit wiring tool.

Ingress is part of Schematic (separate layer: Ingress → Circuit → Egress)

Implementations

impl<R> HttpIngress<R>

where R: ResourceRequirement + Clone + Send + Sync + 'static,

pub fn new() -> Self

Create a new empty HttpIngress builder.

pub fn bind(self, addr: impl Into<String>) -> Self

Set the bind address for the server.

pub fn on_start<F>(self, callback: F) -> Self

where F: Fn() + Send + Sync + 'static,

Register a lifecycle callback invoked when the server starts listening.

pub fn on_shutdown<F>(self, callback: F) -> Self

where F: Fn() + Send + Sync + 'static,

Register a lifecycle callback invoked after graceful shutdown completes.

pub fn graceful_shutdown(self, timeout: Duration) -> Self

Configure graceful shutdown timeout for in-flight request draining.

pub fn layer<L>(self, layer: L) -> Self

where L: Layer<BoxCloneService<Request<Incoming>, HttpResponse, Infallible>> + Clone + Send + Sync + 'static, L::Service: Service<Request<Incoming>, Response = HttpResponse, Error = Infallible> + Clone + Send + 'static, <L::Service as Service<Request<Incoming>>>::Future: Send + 'static,

Add a global Tower layer to the ingress service stack.

Layers execute in LIFO order on the request path: the last layer added is the first to receive the request.

pub fn timeout_layer(self, timeout: Duration) -> Self

Add built-in timeout middleware that returns 408 Request Timeout when the inner service call exceeds timeout.

pub fn request_id_layer(self) -> Self

Add built-in request-id middleware.

Ensures x-request-id exists on request and response headers.

pub fn bus_injector<F>(self, injector: F) -> Self

where F: Fn(&Request<Incoming>, &mut Bus) + Send + Sync + 'static,

Register a request-context injector executed before each circuit run.

Use this to bridge adapter-layer context (request extensions/headers) into explicit Bus resources consumed by Transitions.

pub fn route_descriptors(&self) -> Vec<HttpRouteDescriptor>

Export route metadata snapshot for external tooling.

pub fn serve_dir( self, route_prefix: impl Into<String>, directory: impl Into<String>, ) -> Self

Mount a static directory under a path prefix.

Example: .serve_dir("/static", "./public").

pub fn spa_fallback(self, file_path: impl Into<String>) -> Self

Configure SPA fallback file for unmatched GET/HEAD routes.

Example: .spa_fallback("./public/index.html").

pub fn static_cache_control(self, cache_control: impl Into<String>) -> Self

Override default Cache-Control for static responses.

pub fn compression_layer(self) -> Self

Add gzip/brotli response compression via tower-http::CompressionLayer.

pub fn ws<H, Fut>(self, path: impl Into<String>, handler: H) -> Self

where H: Fn(WebSocketConnection, Arc<R>, Bus) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Register a WebSocket upgrade endpoint and session handler.

The handler receives:

1. a WebSocketConnection implementing EventSource/EventSink,
2. shared resources (Arc<R>),
3. a connection-scoped Bus with request injectors + WebSocketSessionContext.

pub fn health_endpoint(self, path: impl Into<String>) -> Self

Enable built-in health endpoint at the given path.

The endpoint returns JSON with status and check results. If no checks are registered, status is always ok.

pub fn health_check<F, Fut, Err>( self, name: impl Into<String>, check: F, ) -> Self

where F: Fn(Arc<R>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<(), Err>> + Send + 'static, Err: ToString + Send + 'static,

Register an async health check used by /health and /ready probes.

Err values are converted to strings and surfaced in the JSON response.

pub fn readiness_liveness( self, readiness_path: impl Into<String>, liveness_path: impl Into<String>, ) -> Self

Enable readiness/liveness probe separation with explicit paths.

pub fn readiness_liveness_default(self) -> Self

Enable readiness/liveness probes at /ready and /live.

pub fn route<Out, E>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug,

Register a route with GET method.

pub fn route_method<Out, E>( self, method: Method, path: impl Into<String>, circuit: Axon<(), Out, E, R>, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug,

Register a route with a specific HTTP method.

Example

Ranvier::http()
    .route_method(Method::POST, "/users", create_user_circuit)

pub fn route_method_with_error<Out, E, H>( self, method: Method, path: impl Into<String>, circuit: Axon<(), Out, E, R>, error_handler: H, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug, H: Fn(&E) -> HttpResponse + Send + Sync + 'static,

pub fn route_method_with_layer<Out, E, L>( self, method: Method, path: impl Into<String>, circuit: Axon<(), Out, E, R>, layer: L, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug, L: Layer<BoxCloneService<Request<Incoming>, HttpResponse, Infallible>> + Clone + Send + Sync + 'static, L::Service: Service<Request<Incoming>, Response = HttpResponse, Error = Infallible> + Clone + Send + 'static, <L::Service as Service<Request<Incoming>>>::Future: Send + 'static,

pub fn route_method_with_layer_override<Out, E, L>( self, method: Method, path: impl Into<String>, circuit: Axon<(), Out, E, R>, layer: L, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug, L: Layer<BoxCloneService<Request<Incoming>, HttpResponse, Infallible>> + Clone + Send + Sync + 'static, L::Service: Service<Request<Incoming>, Response = HttpResponse, Error = Infallible> + Clone + Send + 'static, <L::Service as Service<Request<Incoming>>>::Future: Send + 'static,

pub fn get<Out, E>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug,

pub fn get_with_error<Out, E, H>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, error_handler: H, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug, H: Fn(&E) -> HttpResponse + Send + Sync + 'static,

pub fn get_with_layer<Out, E, L>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, layer: L, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug, L: Layer<BoxCloneService<Request<Incoming>, HttpResponse, Infallible>> + Clone + Send + Sync + 'static, L::Service: Service<Request<Incoming>, Response = HttpResponse, Error = Infallible> + Clone + Send + 'static, <L::Service as Service<Request<Incoming>>>::Future: Send + 'static,

pub fn get_with_layer_override<Out, E, L>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, layer: L, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug, L: Layer<BoxCloneService<Request<Incoming>, HttpResponse, Infallible>> + Clone + Send + Sync + 'static, L::Service: Service<Request<Incoming>, Response = HttpResponse, Error = Infallible> + Clone + Send + 'static, <L::Service as Service<Request<Incoming>>>::Future: Send + 'static,

pub fn post<Out, E>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug,

pub fn put<Out, E>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug,

pub fn delete<Out, E>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug,

pub fn patch<Out, E>( self, path: impl Into<String>, circuit: Axon<(), Out, E, R>, ) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug,

pub fn fallback<Out, E>(self, circuit: Axon<(), Out, E, R>) -> Self

where Out: IntoResponse + Send + Sync + 'static, E: Send + 'static + Debug,

Set a fallback circuit for unmatched routes.

Example

let not_found = Axon::new("NotFound").then(|_| async { "404 Not Found" });
Ranvier::http()
    .route("/", home)
    .fallback(not_found)

pub async fn run(self, resources: R) -> Result<(), Box<dyn Error + Send + Sync>>

Run the HTTP server with required resources.

pub fn into_raw_service(self, resources: R) -> RawIngressService<R>

Convert to a raw Tower Service for integration with existing Tower stacks.

This is the “escape hatch” per Discussion 193:

“Raw API는 Flat API의 탈출구다.”

Example

let ingress = Ranvier::http()
    .bind(":3000")
    .route("/", circuit);

let raw_service = ingress.into_raw_service();
// Use raw_service with existing Tower infrastructure

Trait Implementations

impl<R> Default for HttpIngress<R>

where R: ResourceRequirement + Clone + Send + Sync + 'static,

fn default() -> Self

Returns the “default value” for a type.