Crate alux_http

Expand description

§alux-http

alux-http describes typed HTTP programs independently of a web framework.

The crate is a specification. It carries no interpreter and depends only on alux-ext: an HTTP surface is described here as first-order syntax plus the capability algebras an interpreter must witness. Domain specifications provide their own algebras and compose first-order operations into routes.

use alux_ext::{OperationAlg, ext};
use alux_http::{HttpApiAlg, HttpProgramBuilder, JsonOutAlg, http};
use core::future::Future;

/// A downstream specification owns its primitive domain meaning.
trait StatusAlg {
    type Status;

    fn status(&self) -> impl Future<Output = Self::Status> + Send;
    fn status_at(&self, id: u32) -> impl Future<Output = Self::Status> + Send;
}

/// Derived operations become first-order values that preserve their argument names.
#[ext(name = StatusOperationExt, defunc)]
impl<This> This
where
    This: StatusAlg,
{
    async fn status_current(&self) -> This::Status {
        self.status().await
    }

    async fn status_for_id(&self, id: u32) -> This::Status {
        self.status_at(id).await
    }
}

/// The route program is declared before any framework is chosen.
#[ext(name = StatusApiExt, defunc(via = http))]
impl<This> This
where
    This: HttpApiAlg + JsonOutAlg,
{
    fn status_api<Alg>(&self)
    where
        Alg: StatusAlg,
    {
        self.routes()
            .get("/status", self.op(Alg::status_current).json())
            .get("/status/:id", self.op(Alg::status_for_id).path::<u32>().json())
    }
}

struct App;

impl StatusAlg for App {
    type Status = u32;

    async fn status(&self) -> u32 {
        1
    }

    async fn status_at(&self, id: u32) -> u32 {
        id
    }
}

// The same program is constructible directly, without the convenience macro and without an
// interpreter, because a route program is an ordinary value.
let builder = HttpProgramBuilder;
let program = builder
    .routes()
    .get("/status", builder.op(StatusCurrentOperation::<App>::default()).json())
    .into_program();
let _nested = builder.routes().nest("/api", builder.program(program)).into_program();

// Argument names and order survive from the authored method into the program.
assert_eq!(<StatusForIdOperation<App> as OperationAlg>::ARG_NAMES, ["id"]);

A program declared this way compiles through any crate that witnesses its algebras:

alux-http-text describes the surface as documentation or metadata.
alux-http-poem compiles the same program into executable Poem routes.

Structs§

Auth: Marks an HTTP authentication input.
Body: Marks an HTTP request-body input.
Context: Marks an endpoint-context input.
Direct: Marks an input supplied directly by an interpreter.
Empty: Represents the empty route program.
Endpoint: Represents an endpoint without choosing an HTTP interpreter.
FileOut: Selects streamed-file output semantics.
Get: Identifies a GET endpoint declaration.
Header: Marks an HTTP header input.
HttpProgramBuilder: Constructs neutral HTTP route programs.
JsonOut: Selects JSON output semantics.
Merge: Represents the categorical coproduct of two route programs.
Named: Includes a separately named HTTP program in a route program.
Nest: Represents a route program nested below an HTTP path prefix.
Operation: Carries a typed operation declaration as first-order data.
Path: Marks an HTTP path input.
Post: Identifies a POST endpoint declaration.
Query: Marks an HTTP query input.
RouteProgram: Carries a typed route program during fluent composition.
Routes: Carries a fluent route composition over an interpreter.

Traits§

CompileRouteProgram: Compiles a first-order route program with a concrete interpreter.
FileOutAlg: Selects the converter used for streamed file API outputs.
HandlerAlg: Describes the capability to build typed handler endpoints.
HandlerEndpointAlg: Compiles a typed handler declaration supported by an interpreter.
HttpApiAlg: Combines the capabilities required to interpret a typed HTTP API.
HttpInputAlg: Describes the HTTP input roles chosen by an interpreter.
HttpProgramAlg: Interprets a named, defunctionalized HTTP program with Compiler.
HttpProgramExt: Compiles defunctionalized HTTP programs with an interpreter.
HttpRouteAlg: Combines the capabilities required to interpret HTTP route composition.
HttpSelectorAlg: Describes HTTP selectors independently of route composition.
InterpretInputsAlg: Maps neutral input roles to the input types selected by an interpreter.
JsonOutAlg: Selects the converter used for JSON API outputs.
OutputAlg: Transforms an inferred handler result into its portable API output.
OutputKindAlg: Resolves a portable output kind through an interpreter.
RouteAlg: Describes categorical construction and composition of routes.
RouteAlgExt: Provides fluent route composition on any RouteAlg.
SelectorAlg: Describes categorical composition of route selectors.
WithAlg: Describes type-level accumulation of one more input in a declaration’s product.

Functions§

append_path: Appends one normalized path segment to a composed absolute path.

Type Aliases§

WithEndpoint: Carries a route program with one additional typed endpoint.
WithInput: Carries an operation declaration with one additional typed input.

Attribute Macros§

http: Lowers extension methods into named, composable HTTP programs.

Crate alux_http

Crate alux_http Copy item path

§alux-http

Structs§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate alux_http