#moonapi

Moved on mooncakes from Lfan-ke/moonapi to moonbitstack/moonapi.

flowchart LR
  routes["typed routes<br/>App::get / post / …"] --> app["**moonapi** App"]
  app -->|"App::to_asgi()"| asgi(["moonasgi AsgiApp"])
  app -->|"App::openapi()"| spec["OpenAPI 2.0 / 3.0 / 3.1"]
  asgi --> cat["mooncat serves it"]

#Quickstart

async fn main {
  let app = @moonapi.App::new()
  app.get("/", _ctx => @moonapi.text(200, "Hello from moonapi!"))
  app.get("/users/:id", ctx => @moonapi.text(
    200,
    "user " + ctx.param("id").unwrap(),
  ), summary="fetch a user")
  app.post("/users", _ctx => @moonapi.text(201, "created"))

  // One set of routes, every mainstream spec version.
  println(app.openapi_json(version=OpenApi31)) // OpenAPI 3.1.0
  println(app.openapi_json(version=OpenApi30)) // OpenAPI 3.0.3
  println(app.openapi_json(version=Swagger20)) // Swagger 2.0

  @mooncat.serve(app.to_asgi(), port=12000) catch {
    err => println("stopped: \{err}")
  }
}

moon run src/main --target native
curl http://127.0.0.1:12000/users/233

#Packages

#What's here (v0)

• Routing — App::get/post/put/patch/delete/route, :param path segments extracted into Context::param, correct 404 (no path) vs 405 (path but not method). A route takes the operation arguments FastAPI's path operations take — summary, description, tags, deprecated, operation_id, status_code, responses, name, include_in_schema, and an openapi_extra fragment merged over the generated operation object — and App::url_for(name, params) resolves a named route back to its path (← url_path_for), mount prefix included.
• Routers — Router collects routes away from any application, and App::include_router(router, prefix=, tags=, security=, dependencies=, responses=, deprecated=, include_in_schema=) folds them in as the app's own (← FastAPI's APIRouter / include_router). The arguments given at the join reach every route in the group: tags, security requirements and dependencies lead the route's own, group responses are documented under it, and deprecated / include_in_schema mark or hide the whole set. A router is a value, so the same one can be included twice under different prefixes.
• Descriptor tree — a runtime Schema / Param / Endpoint tree (a one-first-class-value substitute for FastAPI's from-signature reflection) that a typed route carries. Walked once to (a) emit complete OpenAPI request/response body schemas — objects, arrays, scalars, required, nullable (type: [t, "null"] in 3.1, nullable in 3.0, x-nullable in 2.0), a Map[String, T] as additionalProperties, Any as the empty schema, a format such as binary, and defaults, with named models hoisted under components/schemas and referenced by $ref — and (b) drive request validation off the same tree. A Param carries the same constraints a Field does, plus a default and an alias, so a query parameter's bounds are both documented and enforced, and a 422 points at the name the client actually sent. User structs describe themselves with derive(ToJson) + a T::schema() associated function + a one-line ToSchema bridge (the mctl-friendly shape).
• Multi-version OpenAPI — App::openapi / openapi_json emit Swagger 2.0, OpenAPI 3.0.3, and OpenAPI 3.1.0 from the same routes and descriptors (3.x requestBody + components/schemas; 2.0 body-parameter + definitions), because a good FastAPI is not pinned to one spec version.
• Typed body extractors — Context::body[T] deserialises the JSON body into a derive(FromJson) struct; Context::body_validated[T] first checks it against the endpoint descriptor and returns either the built value or a FastAPI-shaped 422 error list — schema emission, validation, and deserialisation all off one descriptor.
• Dependency injection — a Container (provider registry + dependency_overrides) with request-scoped, one-shot resolution (per-request caching) and yield-style teardown run LIFO around the handler — the explicit MoonBit equivalent of FastAPI's Depends. App::depends(container.erase()) attaches one to the application, and any route builder takes dependencies=["key"] (← dependencies=[Depends(...)]): the keys resolve before the handler and are torn down after it, whatever the handler did. The teardown is handed the error that ended the request, so cleanup can tell a rollback from a commit.
• OAuth2 + JWT security — a /token password-grant endpoint issues an HS256 JWT (create_access_token), and an OAuth2PasswordBearer reads the Authorization: Bearer header, verifies the token, and enforces scopes: 401 on a missing or invalid/expired token, 403 when a valid token lacks a required scope. The token itself is mooncred's and the algorithms are mooncrypt's; moonapi names HS256 and hands over a key. alg: "none" cannot be expressed, the verifier's algorithm is the one that counts rather than the token's, and signatures compare in constant time — all of that is mooncred's to guarantee, and it does.
• Form & file extractors — Context::form parses both an application/x-www-form-urlencoded body (percent- and +-decoded) and a multipart/form-data body, splitting the boundary stream into fields and byte-exact uploads (filename + content-type + size + the part's own headers + raw bytes). Reading the body is moonhttp/form's, over moonmime and moonurl; a body is attacker-controlled and already buffered, so @moonmime.Limits bounds what one may spend — a thousand parts of a megabyte by default — and a body over either bound comes back as None, refused whole rather than truncated. Context::oauth2_password_form reads the OAuth2 password form off it.
• response_model — filter_response / json_model validate a handler's return value against a declared Schema and project it down to exactly the model's fields, so a route can hold a richer object internally than it exposes (an id, a password hash) and still emit only what it promised.
• Middleware & exception handlers — an outer middleware chain (App::middleware) with cors(...) (preflight + actual-request headers, configurable origins/methods/headers, credentials, exposed headers) and gzip(...) (moonzip's compressor), plus exception handlers (App::exception_handler): a handler raises an HttpException and the app maps it to a response, falling through to a built-in {"detail": ...} for HttpException and a 500 for anything else. App::add_status_handler(code, ...) swaps in a custom response for any error status — a routing 404 / 405 or a raised exception's status — so an app can serve its own error pages.
• Per-operation security — a route carries security=[SecurityRequirement::new(scheme, scopes=[...])], and every scheme shape has a guard: secure_oauth2, secure_oauth2_code, secure_bearer, secure_api_key (header / query / cookie), secure_basic, secure_digest, secure_openid. Each surfaces the scheme in the spec and registers the check that runs before the handler — 401 with the WWW-Authenticate challenge the scheme owes (a scoped bearer route names the scope it wanted), 403 on a missing scope or a rejected API key. Every one takes description= and auto_error= (with the flag off, the guard admits an anonymous caller and leaves the decision to the route). A bare add_security_scheme documents without enforcing (FastAPI's split between a scheme and a wired dependency).
• Background tasks — a background-aware route (App::route_bg) receives a BackgroundTasks queue; add_task defers work that the app runs, in order, after the response is sent (← FastAPI's BackgroundTasks), so a slow write never delays the client.
• Sub-application mounting — App::mount(prefix, subapp) composes routers: a request under prefix is routed by the sub-app with the prefix stripped (its own middleware, security, and background tasks apply), and the sub-app's routes and security schemes fold into the parent's merged OpenAPI document under the prefix. Mounts nest. App::mount_handler(prefix, handler) mounts a foreign moonasgi Handler the same way — a third-party component, or static files — which the app routes to but does not document.
• Streaming responses — App::stream(path, handler) / App::route_stream(verb, ...) register a route returning a moonasgi.StreamingResponse, whose chunks reach the client as separate body events — a client reads the first long before the last one exists. App::handle_with_stream is the chunk-level view a test reads. A middleware is typed buffered-in, buffered-out, so one that rewrites the body (gzip) collapses the reply to a single chunk rather than cutting new bytes at boundaries that no longer describe them.
• Server-Sent Events — moonhttp/sse frames an event per the WHATWG event-stream format (id / event / retry / multi-line data / : comments); sse_response is a text/event-stream stream of those frames, one chunk per event, so each dispatches on arrival. Hand it to App::stream. (An event stream delivered as one body is not an event stream — it is a file shaped like one.)
• WebSocket routes — App::websocket(path, handler) over the moonasgi WS SEAM. The handler drives a WebSocket (accept / receive / send / close); it's a synchronous core, so drive_websocket runs it against an in-memory frame queue in a test and App::to_asgi serves it over the async transport.
• Security schemes — the six OpenAPI shapes (OAuth2 password and authorization-code flows, HTTP bearer / basic / digest, an API key in a header / query / cookie, and OpenID Connect) are emitted in each dialect's form: components/securitySchemes in 3.x, securityDefinitions in 2.0, where an http scheme becomes the standard apiKey-in-Authorization workaround and OpenID Connect — which 2.0 cannot express — is left out rather than described as something it is not.
• Documentation UI — App::enable_docs() mounts /openapi.json, /docs and /redoc, all three with include_in_schema=false so turning documentation on does not change the document. swagger_ui() and redoc_ui() return the pages alone, for an app that serves them under its own paths or behind its own guard.
• Lifespan hooks — App::on_startup / App::on_shutdown (← FastAPI's lifespan), driven over the ASGI lifespan protocol. Startup in registration order, shutdown in reverse, so a resource is released before whatever opened it. App::lifespan_handler runs the same thing in-process, for a test with no socket.
• Responses — text, html, json and json_model helpers over moonasgi.Response, plus redirect(url, status=307) (← RedirectResponse; the URL is encoded over the characters a URI reserves for structure, so an already-encoded URL passes through and a smuggled CRLF cannot open a header) and file_response(content, filename=, media_type=, inline=) (← FileResponse: a media type guessed from the extension, Content-Length, and a Content-Disposition that falls back to RFC 6266's filename* when the name will not survive quoting). It takes bytes rather than a path because moonapi has no filesystem — the same app runs on wasm, js and native.
• Conditional and partial serving — Context::serve(content, ...) is file_response with the request weighed: 304 when the client's copy is current, 412 when a precondition fails, 206 for a range (one Content-Range, or multipart/byteranges for several), 416 for a range that is not there. This is what makes a download resumable. The entity-tags, the five precondition fields and the range arithmetic are moonhttp's conditional and range, so it is RFC 9110 §13 and §14 rather than a guess. Everything turns on etag=; left out, one is hashed from the content, which costs a pass over the body — pass @conditional.stamp(length~, modified~) for one stat's worth instead.
• Data URLs — data_response(url) serves what a data: URL carries, under the media type it names; data_url(content, media_type=) writes one. This is what canvas.toDataURL() and FileReader.readAsDataURL() hand back, and how a client posts an image inside a JSON field. Not a data URL yields None, so a handler tells "no picture" from "not a picture" without touching base64.
• Cookies — set_cookie(resp, name, value, max_age=, expires=, path=, domain=, secure=, http_only=, same_site=) and delete_cookie(...) (← response.set_cookie / delete_cookie). Each returns a new response carrying one more Set-Cookie, which is the correct wire shape: two cookies are two headers, never one folded field. expires is a @moondate.Moment, because an expiry is a moment and the format says how to write one; delete_cookie expires by both Max-Age=0 and the epoch. Context::cookie reads them back. The cookie itself — both headers, each read and written, and the stripping of the octets RFC 6265 forbids so a value cannot forge an attribute or open a header of its own — is moonhttp's cookie package, which a client uses from the other side.
• Status constants — the 63 HTTP_* and 15 WS_* names FastAPI re-exports from Starlette (HTTP_404_NOT_FOUND, WS_1008_POLICY_VIOLATION), so a route table shows a deliberate 307 rather than a bare number.
• One description, several uses — Schema::of_model(model, known=) takes a moonmodel description and gives back a schema, so the same declaration that produces the SQL columns in moonorm and the SDL in moongql drives validation and the OpenAPI document here. Written once, read four ways. A Ref is looked up in known; one that is missing, or that leads back into a model already being written, comes back in the second return value with the reason rather than being guessed at — a schema is a finite value, so a cycle cannot be one. Nothing else changes: the hand-written Schema tree is still there and still the shorter way to say something small.

#Configuration

ctx.query("tag")                                       // the preset bound
ctx.query("tag", limits=@moonurl.Limits::new(pairs=100000))
ctx.form(limits=@moonmime.Limits::new(part_size=8 << 20))  // an upload endpoint

@moonapi.create_access_token(sub, secret, now, extra={ "tenant": Json::string("acme") })
@moonapi.sse_response(events, headers=[("cache-control", "no-store")])
@moonapi.sse_response(events, space=false)

#Where a setting can arrive twice

#Design notes

• GZip is moonzip's, whose output zlib reads and whose reader takes what zlib writes. What lives here is the middleware around it: when to compress, and which headers to set.
• WebSocket handlers are a synchronous core: the same handler runs in a test and under a server. Because the core can't suspend on the async transport (MoonBit runs async only in an async context), the serving shell buffers the client's inbound frames, runs the handler, then emits its frames. Content and order are preserved — exact for echo, broadcast, and request-reply — but it doesn't interleave live per-frame with the client.

#Roadmap (transliterating FastAPI)

#License