<!-- Sema documentation — std.web
     Sema is a new AI-native, neurosymbolic programming language most models
     have not been trained on. Full corpus: https://sema.49.12.246.95.sslip.io/llms-full.txt
     Install language support: https://sema.49.12.246.95.sslip.io/install-skill/ -->

# std.web

> Reflected API reference for the Sema standard-library module std.web.

> Generated by `sema doc` from `stdlib/sema/web.sema`. Import with `from std.web import …`. For a narrative introduction see [std.web](/stdlib/web/).

# `web`

std.web — a tiny FastAPI-shaped HTTP layer over the native `http.serve` seam (§5.34).

Framework ergonomics without a framework: write handlers `(req) -> Response`,
register them on a `Router` by method + path (with `{param}` path segments), and
`serve`. The request is the native dict `{method, path, query, body, headers}`
(headers lowercased) plus a `params` dict of captured path segments. A handler
returns a `Response` built with the `ok`/`json_status`/`text`/`error` helpers.

    from std.web import router, get, post, serve, ok, error

    def health(req: dict) -&gt; Response !{}:
        return ok({"status": "ok"})

    def serve_api(port: int) -&gt; None !{net.listen}:
        app = router()
        get(app, "/healthz", health)
        post(app, "/search", search_handler)
        serve(app, port)

`serve`/`dispatch` carry the standard web effect envelope (net + model + fs +
clock + observe + ffi + env), so a handler may perform any of those; the caller
declares the same (or wider) row. A true `@get("/path")` decorator that registers
at load time needs a runtime hook (like `@provides`) and is a deferred SDK add —
explicit registration is the reliable, framework-free equivalent.

# `struct Response`

**Fields**

| field | type | descriptor |
|---|---|---|
| `status` | `int` |  |
| `content_type` | `str` |  |
| `headers` | `dict` |  |
| `body` | `str` |  |

# `struct Route`

**Fields**

| field | type | descriptor |
|---|---|---|
| `method` | `str` |  |
| `path` | `str` |  |
| `handler` | `any` |  |

# `struct Router`

**Fields**

| field | type | descriptor |
|---|---|---|
| `routes` | `list[Route]` |  |

# `def router`

```sema
def router() -> Router !{}
```

**Returns** `Router`

**Effects** `!{}`

# `def route`

```sema
def route(app: Router, method: str, path: str, handler: any) -> Router !{}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `method` | `str` |
| `path` | `str` |
| `handler` | `any` |

**Returns** `Router`

**Effects** `!{}`

# `def get`

```sema
def get(app: Router, path: str, handler: any) -> Router !{}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `path` | `str` |
| `handler` | `any` |

**Returns** `Router`

**Effects** `!{}`

# `def post`

```sema
def post(app: Router, path: str, handler: any) -> Router !{}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `path` | `str` |
| `handler` | `any` |

**Returns** `Router`

**Effects** `!{}`

# `def put`

```sema
def put(app: Router, path: str, handler: any) -> Router !{}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `path` | `str` |
| `handler` | `any` |

**Returns** `Router`

**Effects** `!{}`

# `def delete`

```sema
def delete(app: Router, path: str, handler: any) -> Router !{}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `path` | `str` |
| `handler` | `any` |

**Returns** `Router`

**Effects** `!{}`

# `def patch`

```sema
def patch(app: Router, path: str, handler: any) -> Router !{}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `path` | `str` |
| `handler` | `any` |

**Returns** `Router`

**Effects** `!{}`

# `def response`

```sema
def response(status: int, content_type: str, body: str) -> Response !{}
```

**Parameters**

| name | type |
|---|---|
| `status` | `int` |
| `content_type` | `str` |
| `body` | `str` |

**Returns** `Response`

**Effects** `!{}`

# `def ok`

```sema
def ok(obj: any) -> Response !{}
```

**Parameters**

| name | type |
|---|---|
| `obj` | `any` |

**Returns** `Response`

**Effects** `!{}`

# `def json_status`

```sema
def json_status(status: int, obj: any) -> Response !{}
```

**Parameters**

| name | type |
|---|---|
| `status` | `int` |
| `obj` | `any` |

**Returns** `Response`

**Effects** `!{}`

# `def text`

```sema
def text(body: str) -> Response !{}
```

**Parameters**

| name | type |
|---|---|
| `body` | `str` |

**Returns** `Response`

**Effects** `!{}`

# `def error`

```sema
def error(status: int, message: str) -> Response !{}
```

**Parameters**

| name | type |
|---|---|
| `status` | `int` |
| `message` | `str` |

**Returns** `Response`

**Effects** `!{}`

# `def header`

```sema
def header(r: Response, name: str, value: str) -> Response !{}
```

**Parameters**

| name | type |
|---|---|
| `r` | `Response` |
| `name` | `str` |
| `value` | `str` |

**Returns** `Response`

**Effects** `!{}`

# `def clean_path`

```sema
def clean_path(path: str) -> str !{}
```

**Parameters**

| name | type |
|---|---|
| `path` | `str` |

**Returns** `str`

**Effects** `!{}`

# `def match_path`

```sema
def match_path(pattern: str, actual: str) -> any !{}
```

**Parameters**

| name | type |
|---|---|
| `pattern` | `str` |
| `actual` | `str` |

**Returns** `any`

**Effects** `!{}`

# `def resp_dict`

```sema
def resp_dict(r: Response) -> dict !{}
```

**Parameters**

| name | type |
|---|---|
| `r` | `Response` |

**Returns** `dict`

**Effects** `!{}`

# `def dispatch`

```sema
def dispatch(app: Router, req: dict) -> dict !{net.connect, model.invoke, model.embed, fs.read, clock, observe.record, ffi.call, env.read}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `req` | `dict` |

**Returns** `dict`

**Effects** `!{net.connect, model.invoke, model.embed, fs.read, clock, observe.record, ffi.call, env.read}`

# `def serve`

```sema
def serve(app: Router, port: int) -> None !{net.listen, net.connect, model.invoke, model.embed, fs.read, clock, observe.record, ffi.call, env.read}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `port` | `int` |

**Returns** `None`

**Effects** `!{net.listen, net.connect, model.invoke, model.embed, fs.read, clock, observe.record, ffi.call, env.read}`

# `def serve_on`

```sema
def serve_on(app: Router, host: str, port: int) -> None !{net.listen, net.connect, model.invoke, model.embed, fs.read, clock, observe.record, ffi.call, env.read}
```

**Parameters**

| name | type |
|---|---|
| `app` | `Router` |
| `host` | `str` |
| `port` | `int` |

**Returns** `None`

**Effects** `!{net.listen, net.connect, model.invoke, model.embed, fs.read, clock, observe.record, ffi.call, env.read}`