Expand description
§alux-http-rocket
alux-http-rocket interprets an alux-http program as executable
Rocket routes.
use alux_http::HttpProgramExt;
use alux_http_rocket::RocketHandlerImpl;
let api = RocketHandlerImpl::new(App::new());
let rocket = api.compile_http(api.status_api::<App>()).mount(rocket::build());
rocket.launch().await?;Rocket requires every mounted route to have a method. An endpoint without a method therefore cannot be mounted. Rocket responses also borrow the request, so this interpreter builds the response value at the route boundary and returns it to Rocket.
§Accepting
Rocket binds its own listener inside launch and offers no way to hand it one, and no entry point that takes a single connection. The listener, the accept loop and the runtime are all internal, so nothing about serving can be driven from outside.
That shapes both ends of the lifecycle here. Starting learns that the address is serving from an on_liftoff fairing, because Rocket is the only thing that knows when it bound. Stopping goes through Shutdown::notify, because there is no listener to drop. Rocket also warns that it runs inside a custom runtime, which costs only its last-resort termination of a runaway task: its graceful and forced connection shutdown still apply.
Most of that is inherited. Rocket 0.5 builds on hyper 0.14, whose Server takes the listener and spawns each connection itself, and Rocket drives it through Server::builder. hyper 0.14 did expose a per-connection entry point in Http::serve_connection, so the closed loop was a choice rather than something forced, but once Server is the thing being driven there is no connection to reach and no task to wait on. hyper 1 split those apart again, which is what lets alux-http-hyper own the loop and hold every connection it accepts.
§Signals
This interpreter sets ctrlc: false and an empty signals set in Rocket’s ShutdownConfig, because whoever opened the server is the one who decides when it closes.
Left at its defaults, Rocket installs process-wide handlers and answers Ctrl-C and SIGTERM itself. An application built on alux-http never sees either, so its own shutdown never runs and kill or pkill appears to do nothing at all. Ending a server is what HttpServerAlg::close and HttpServerAlg::end are for, and a signal is the application’s to interpret.
§Logging
Rocket writes a launch banner and a line per request to stdout, at log_level normal in debug and critical in release. This crate sets it to off: what an application says is the application’s, and a benchmark reading its own output has nothing else in it.
§Closing
Closing and ending are one call here, because Rocket’s shutdown releases the address and drains connections together and cannot be asked for only the first. Both are Shutdown::notify followed by waiting for launch to return. How long that takes is set by two configuration values that read as one budget and are not:
grace is the drain. While it runs, each connection keeps serving normally, so a request in flight is still being answered. When it expires the connection is shut down whatever it was doing. This crate sets 5 seconds, the same drain the other interpretations state.
mercy begins where grace ends, and is not more time for the request. It bounds the orderly close of the socket, flushing what is pending and closing the write half, before the socket is dropped outright. This crate sets 0, because a connection whose request has just been abandoned has nothing left to flush.
Closing returns later than both, at grace + mercy + 1. The extra second is Rocket’s own, and its comment says why: hyper’s server future resolves before the responses it started have finished, so Rocket cannot observe when its connections are done. It waits the periods out, adds a buffer, and then checks whether every task has dropped its reference to the server. A failed check is the Shutdown failed: outstanding background I/O warning.
Interprets typed HTTP programs as executable Rocket routes.
Rocket states a method on every route and builds a response that borrows the request it answers, so this interpretation mounts one route per endpoint and states what an endpoint answers with as a value the route hands over.
Structs§
- Rocket
Answer - What one endpoint answers with, before Rocket builds a response from it.
- Rocket
Body Input - Marks a JSON value read from the request body.
- Rocket
Bytes Output - Renders a semantic result as a raw-byte answer.
- Rocket
Cookie Input - Marks a value read from the cookies a caller sent.
- Rocket
Empty Output - Renders a handler that returns nothing as an answer with no body.
- Rocket
Endpoint - Erases what one endpoint does with a request Rocket routed to it.
- Rocket
Error - States that an argument could not be read from where its role says it comes from.
- Rocket
File Output - Renders a semantic file result as a downloadable answer.
- Rocket
Form Input - Marks a form-encoded value read from the request body.
- Rocket
Handler Impl - Interprets typed HTTP programs as executable Rocket routes.
- Rocket
Head Input - Marks a value read from the headers the caller sent.
- Rocket
Header Input - Marks a value read from the headers a caller sent.
- Rocket
Header Output - Answers with a header the handler stated, beside the body it stated.
- Rocket
Html Output - Renders a semantic result as an HTML answer.
- Rocket
Json Output - Renders a semantic result as a JSON answer.
- Rocket
Multipart Input - Marks an argument read from a body arriving as parts.
- Rocket
Open - Carries an open Rocket server that is accepting requests.
- Rocket
Path Input - Marks a value read from the segments a path bound.
- Rocket
Query Input - Marks a value read from the query string.
- Rocket
RawBody Input - Marks the request body taken as it arrived.
- Rocket
Redirect Output - Renders a semantic location as a redirect.
- Rocket
Request - What one matched request states, as Rocket routed it.
- Rocket
Result Output - Answers with what a failure means when the handler failed, and with the body it states otherwise.
- Rocket
Route - Carries a composable collection of Rocket endpoints.
- Rocket
Route Impl - Interprets categorical route composition as native Rocket routing.
- Rocket
Selector - Carries route-selection meaning before it is mounted on Rocket.
- Rocket
Server - Serves a Rocket route at the address its setup names.
- Rocket
Status Output - Answers with the status an endpoint declared, around the body it already states.
- Rocket
Stream Output - Answers with a body produced over time.
- Rocket
Text Output - Renders a semantic result as a plain-text answer.
Enums§
- Rocket
Body - What an answer carries, which is either bytes already in hand or bytes still to come.
Traits§
- From
Captured Alg - Reads the handler argument a path’s captured segments state.
- From
Headers Alg - Reads the handler argument the headers state.
- From
RawAlg - Reads the handler argument a request body states, taken as it arrived.