#moonasgi

flowchart LR
  net["native async<br/>(sockets, TLS, HTTP/1.1, HTTP/2)"] --> cat["mooncat<br/>(ASGI server)"]
  cat -->|"Scope / Receive / Send"| asgi(["**moonasgi**<br/>SEAM"])
  asgi --> api["moonapi"]
  asgi --> gql["moongql"]
  asgi --> zero["moonzero"]
  asgi --> mcp["moonmcp"]

#The contract

pub enum Scope {
  Http(HttpScope)
  WebSocket(WebSocketScope)
  Lifespan(LifespanScope)
}

pub type Receive = async () -> Event          // pull the next inbound event
pub type Send    = async (Event) -> Unit      // push an outbound event
pub type AsgiApp = async (Scope, Receive, Send) -> Unit

pub type Handler    = (Request) -> Response
pub type Middleware = (Handler) -> Handler

#TestClient

let client = TestClient::new(handler)          // or ::from_stream / ::from_app
let r = client.post("/echo", body=b"payload")
assert_eq(r.status, 200)
assert_eq(r.text(), "payload")

#Testing an async application

let client = @testing.Client::new(app)
client.lifespan(() => {                         // startup, body, shutdown
  let r = client.post("/items", body=b"{}")
  assert_eq(r.status, 201)
  client.websocket(path="/chat", subprotocols=["v1"], ws => {
    ws.send_text("hi")
    assert_eq(ws.receive_text(), "hi")
  })                                            // closes with 1000, waits for the app
})

@testing.communicate(app, scope, c => {
  c.send(HttpRequest(body=b"", more_body=false))
  assert_true(c.receive() is HttpResponseStart(status=200, ..))
  assert_true(c.receive_nothing())
  c.wait()
})

#WebSocket

let client = TestClient::new(handler)
let session = client.websocket(
  path="/chat",
  handler=WebSocketHandler::echo(subprotocol="chat"),
  send=[Text("hello"), Binary(b"\x01\x02")],
)
assert_eq(session.accepted, true)
assert_eq(session.subprotocol, Some("chat"))
assert_eq(session.texts(), ["hello"])

#Lifespan

let app = LifespanHandler::new(
  on_startup=fn(scope) {
    scope.state["db_pool"] = Json::string("pool://greet")   // seeded in place
    Complete
  },
)
let out = run_lifespan(app, Lifespan(scope), [LifespanStartup])
assert_eq(out == [LifespanStartupComplete], true)

#Scope-aware core

run_http_scoped(fn(scope, body) {
  let prefix = scope.state.get("greeting_prefix")  // lifespan-seeded
  [HttpResponseStart(status=200, headers=[], trailers=false),
   HttpResponseBody(body, more_body=false)]
}, Http(scope), inbound)

#HTTP/2 and HTTP/3

let scope = HttpScope::from_h2_headers([
  (":method", "POST"), (":scheme", "https"),
  (":authority", "example.test"), (":path", "/items?page=2"),
  ("content-type", "application/json"),
])
// -> Ok: http_method="POST", scheme="https", path="/items",
//        query_string=b"page=2", headers=[("host","example.test"), ...]

#Conformance

let report = run_conformance()
assert_eq(report.ok(), true)

let bad = [HttpResponseBody(body=b"x", more_body=false)]  // no start
assert_eq(validate_events(scope, bad) == Some(BodyBeforeStart), true)

#Extensions & streaming

• http.response.trailers — StreamingResponse.trailers; lowered to HttpResponseStart{trailers: true} + a terminating HttpResponseTrailers.
• http.response.push — HttpResponsePush{path, headers}.
• http.response.pathsend — HttpResponsePathSend{path}.
• http.response.zerocopysend — HttpResponseZeroCopySend{fd, offset, count, more_body}; captured by the TestClient as TestResponse.zerocopysend.
• http.response.early_hint — HttpResponseEarlyHint{links}; StreamingResponse.early_hints, lowered to 103 Early Hints messages ahead of the response.
• http.response.debug — HttpResponseDebug{info}; an out-of-band info payload with no protocol meaning, valid anywhere in the response.
• websocket.http.response — WebSocketHttpResponseStart / WebSocketHttpResponseBody, to deny a handshake with a full HTTP response.
• tls — TlsExtension carried on the scope's extensions.

#Compliance matrix

#Middleware

let app = @mid.stack(
  [
    @mid.ServerErrors::new(),                          // outermost
    @mid.TrustedHosts::new(hosts=["example.com", "*.example.com"]),
    @mid.Cors::new(origins=["https://app.example.com"], methods=["GET", "POST"]),
    @mid.gzip,
    @mid.Wrap(inner => my_timing(inner)),
  ],
  framework_app,
)

#Several applications behind one

let app = @dispatch.mount(
  [("/api", api_app), ("/mcp", mcp_app)],
  fallback=site_app,
)
let by_host = @dispatch.hosts([("docs.example.com", docs_app)], fallback=app)

#Synchronous applications

let legacy : @wsgi.WsgiApp = (environ, start) => {
  ignore(start("200 OK", [("Content-Type", "text/plain")]))
  ["hello from ", environ.path_info].iter().map(s => @utf8.encode(s))
}
let app = @wsgi.to_asgi(legacy)

#Consumed by

#Design

• The seam has no dependencies. spec and the root are pure types plus a small sugar layer; the transport lives in the mooncat adapter. Three packages bring one in, which is why each is a package of its own: mid uses moonzip for gzip, and testing and dispatch use moonbitlang/async for its event loop.
• A closed connection says so. A server raises spec.Closed from send once the connection has closed, so an application that keeps sending learns it and stops.
• Faithful, not approximate. This is a complete transliteration of ASGI 3.0 into MoonBit idiom — the typed Scope/Event shape is the dialect, not a subset.

#Status

#License