Source: https://h2corn.monicz.dev/embedding/

# Embedding

The CLI (`h2corn module:app`) and the [`serve()`](https://h2corn.monicz.dev/api/server/#h2corn.serve "serve") function start the server as a top-level process. Use the [`Server`](https://h2corn.monicz.dev/api/server/#h2corn.Server "Server") class inside an existing [asyncio](https://docs.python.org/3/library/asyncio.html) event loop or test harness. Full signatures are in the [API reference](https://h2corn.monicz.dev/api/#api-reference).

## Inside an asyncio app

This self-contained example starts a loopback server on an available port, makes one request, and shuts down:

embedded.py

```python
import asyncio
from urllib.request import urlopen

from h2corn import Config, Receive, Scope, Send, Server


async def app(scope: Scope, receive: Receive, send: Send) -> None:
    assert scope['type'] == 'http'
    await send({'type': 'http.response.start', 'status': 200, 'headers': []})
    await send({'type': 'http.response.body', 'body': b'Hello, world!'})


async def main() -> None:
    server = Server(
        app,
        Config(bind=('127.0.0.1:0',), access_log=False, lifespan='off'),
    )
    serving = asyncio.create_task(server.serve())
    try:
        await server.wait_started()
        url = f'http://{server.addresses[0]}/'
        # Keep the event loop free to serve the synchronous client's request.
        with await asyncio.to_thread(urlopen, url, timeout=5) as response:  # ruff: ignore[suspicious-url-open-usage] - The URL is the local HTTP listener above.
            assert response.status == 200
            assert response.read() == b'Hello, world!'
            print(f'embedded request: {response.status}')
    finally:
        server.shutdown()
        await serving


asyncio.run(main())
```

Run it with `python embedded.py`; it prints `embedded request: 200`.

[`Server.serve()`](https://h2corn.monicz.dev/api/server/#h2corn.Server.serve "serve async") is an async function that runs until the server is asked to shut down. It runs one worker in the calling process; `serve()` runs several through the same multi-process supervisor as the CLI.

`Server.serve()` owns an in-process lifecycle, so it rejects a configuration that combines [`pid`](https://h2corn.monicz.dev/configuration/#option-pid) with [`user`](https://h2corn.monicz.dev/configuration/#option-user) or [`group`](https://h2corn.monicz.dev/configuration/#option-group): the pidfile and privilege change need one supervisor to own their ordering. On Unix, use `h2corn.serve()` or the CLI for that topology; their supervisor owns the pidfile and manages worker privilege changes.

## Knowing when the server is up

`serve()` runs until the server stops, so run it as a task when readiness is needed. `Server.wait_started()` resolves once the server is accepting requests:

partial readiness fragment

```python
serving = asyncio.create_task(server.serve())
await server.wait_started()
# Requests sent after readiness are accepted.
```

It resolves once the server is serving, not when the listeners open — those can be bound while lifespan startup is still running, and `wait_started()` stays pending through that. A failed bind, a failed lifespan startup, or a shutdown before readiness raises instead, to everyone waiting at the time. Only success is remembered; a wait begun after a failed attempt applies to the next `serve()` attempt.

Readiness is a fact about the process rather than about one event loop, so a `Server` driven from another thread's loop can still be awaited from yours.

## Binding to any free port

Bind port `0` and read the kernel-assigned address back from `Server.addresses` — ideal for test harnesses and service discovery:

partial embedding fragment

```python
server = Server(app, Config(bind=('127.0.0.1:0',)))
serving = asyncio.create_task(server.serve())
await server.wait_started()
print(server.addresses)  # runtime-assigned address
```

When several TCP listeners all bind port `0` (for example `0.0.0.0:0` plus `[::]:0`), they share one kernel-assigned port.

## Programmatic shutdown

Call [`shutdown()`](https://h2corn.monicz.dev/api/server/#h2corn.Server.shutdown "shutdown") from any thread or coroutine to request a graceful stop. It returns immediately; `serve()` owns the wait. Cooperative requests get up to [`timeout_graceful_shutdown`](https://h2corn.monicz.dev/configuration/#option-timeout_graceful_shutdown) seconds to finish, then cancellation and cleanup get the same budget again.

A synchronous Python call that blocks the event-loop thread cannot be preempted by an in-process deadline. If a request still holds the server after both drain periods, `serve()` raises `RuntimeError`; supervised workers are the option when a process-level hard-kill bound is required.

Requests that outlive the budget still own the application: lifespan shutdown waits for them, [`releasing`](https://h2corn.monicz.dev/api/server/#h2corn.Server.releasing "releasing property") stays true, and another `serve()` call made in that window raises `RuntimeError: this Server is still releasing a previous serve() call`.

Using the `hello.py` application from the [Quickstart](https://h2corn.monicz.dev/quickstart/#run-your-first-server):

shutdown.py (requires hello.py)

```python
import asyncio
from h2corn import Config, Server
from hello import app


async def main():
    server = Server(app, Config(bind=('127.0.0.1:8000',)))

    async def stop_when_ready():
        await server.wait_started()
        server.shutdown()

    await asyncio.gather(server.serve(), stop_when_ready())


asyncio.run(main())
```

## Lifecycle

One `serve()` call at a time, and a `Server` can be reused once that call has let go of everything it held.

- **Sequential reuse works.** After `shutdown()`, cancellation, or a startup failure — and after any straggling requests and lifespan shutdown have finished — the same `Server` can `serve()` again with fresh state.
- **Concurrent calls are rejected.** A second `serve()` while the first is still running, or still winding down, raises `RuntimeError: this Server already has an active serve() call` or `RuntimeError: this Server is still releasing a previous serve() call`. `releasing` distinguishes these states: it stays true after `serve()` returns until reuse is safe.
- **Cancellation drains gracefully.** Cancelling the task running `serve()` does not abort in-flight work — it starts the same bounded drain as `shutdown()`. The difference is what surfaces: cancellation always re-raises `CancelledError` once the drain finishes or its budget runs out, never the over-budget `RuntimeError`.
