tyroute

    Typed request extraction, responses, and OpenAPI export for MoonBack.

    Download zip
    Version
    0.4.0
    License
    Apache-2.0
    Last updated
    2 days ago
    Downloads
    65

    #tyroute

    Typed requests, responses, and OpenAPI export for MoonBack.

    Handlers accept (Ctx, CustomRequest) and return CustomResponse. Implement FromRequest to extract and validate a complete request, and ToResponse to choose the HTTP status, headers, and body.

    See the handler API and the runnable example.

    #Development

    moon update moon fmt --check . example/serve.mbtx moon check --target wasm moon test --target wasm moon build example --target wasm moon check --target native moon test --target native moon build example --target native moon info

    Run the example with moon run example --target native, then visit http://127.0.0.1:3000/users/42?name=Alice or /openapi.json.

    FromRequest

    pub(open) trait FromRequest {
    async fn from_request(Request) -> Self
    }

    Convert request data into an application request value. Expected validation failures should be represented in Self, not raised.
    impl FromRequest for Unit

    ToResponse

    pub(open) trait ToResponse {
    fn to_response(Self) -> Response
    }

    Convert an application response value into an HTTP response.
    impl ToResponse for Unit

    ToSchema

    pub(open) trait ToSchema {
    fn to_schema(SchemaContext) ->
    Json

    }

    Describe a reusable component or route contract and collect its references.
    impl ToSchema for Unit

    OpenApiError

    pub suberror OpenApiError {
    InvalidPath(String)
    InvalidSchema(String)
    DuplicateOperation(String)
    }

    Request

    type Request

    An opaque wrapper exposing request data through forwarding methods.

    Request::headers

    Request::params

    fn Request::params(self : Request) -> Map[StringView, StringView]

    Response

    type Response

    Response::Response

    RouteSchema

    type RouteSchema[Req, Res]

    A request/response contract tied to the handler's types.

    Router

    type Router

    impl Extension for Router

    Router::Router

    fn Router::Router() -> Router

    Router::add

    fn[Ctx, Req : FromRequest, Res : ToResponse] Router::add(self : Router, path : String, meth :
    RequestMethod
    , handler : async (Ctx, Req) -> Res, ctx : Ctx, schema? : RouteSchema[Req, Res]) -> Unit

    Router::delete

    fn[Ctx, Req : FromRequest, Res : ToResponse] Router::delete(self : Router, path : String, handler : async (Ctx, Req) -> Res, ctx : Ctx, schema? : RouteSchema[Req, Res]) -> Unit

    Router::generate_openapi

    fn Router::generate_openapi(self : Router, title~ : String, version~ : String) ->
    Json
    raise OpenApiError

    Export routes and their optional contracts without invoking converters or handlers. Routes without a contract use an undocumented default response.

    Router::get

    fn[Ctx, Req : FromRequest, Res : ToResponse] Router::get(self : Router, path : String, handler : async (Ctx, Req) -> Res, ctx : Ctx, schema? : RouteSchema[Req, Res]) -> Unit

    Router::head

    fn[Ctx, Req : FromRequest, Res : ToResponse] Router::head(self : Router, path : String, handler : async (Ctx, Req) -> Res, ctx : Ctx, schema? : RouteSchema[Req, Res]) -> Unit

    Router::initialize

    async fn Router::initialize(self : Router, ctx :
    ModuleContext
    ) -> Unit

    Router::openapi

    fn Router::openapi(self : Router, url : String, title~ : String, version~ : String) -> Unit

    Configure an OpenAPI endpoint. MoonBack initialization generates the document and registers a GET route serving it as application/json.

    Router::patch

    fn[Ctx, Req : FromRequest, Res : ToResponse] Router::patch(self : Router, path : String, handler : async (Ctx, Req) -> Res, ctx : Ctx, schema? : RouteSchema[Req, Res]) -> Unit

    Router::post

    fn[Ctx, Req : FromRequest, Res : ToResponse] Router::post(self : Router, path : String, handler : async (Ctx, Req) -> Res, ctx : Ctx, schema? : RouteSchema[Req, Res]) -> Unit

    Router::put

    fn[Ctx, Req : FromRequest, Res : ToResponse] Router::put(self : Router, path : String, handler : async (Ctx, Req) -> Res, ctx : Ctx, schema? : RouteSchema[Req, Res]) -> Unit

    SchemaContext

    type SchemaContext

    Components collected while exporting one OpenAPI document.

    SchemaContext::ref

    fn[T : ToSchema] SchemaContext::ref(self : SchemaContext, name : String, _tag : Tag[T]) ->
    Json

    Return a local component reference, generating its definition only once. The tag selects the ToSchema implementation used for generation. Mark the reference before generation so recursive components terminate.

    Tag

    pub(all) enum Tag[T] {
    Tag
    }

    A type witness selecting the ToSchema implementation.

    inferred

    fn[Req : ToSchema, Res : ToSchema] inferred() -> RouteSchema[Req, Res]

    Select the handler types' schemas, generated during OpenAPI export.