# `WardrikHTTP`

Serves Wardrik's operations over HTTP.

Most apps use `Wardrik.HTTP`, which sets `:server` and `:sign_in` for you:

    children = [MyApp.AgentRuntime, {Wardrik.HTTP, wardrik: MyApp.AgentRuntime, port: 4000}]

Use `WardrikHTTP` directly to serve any `Wardrik.Server`:

    children = [{WardrikHTTP, server: {Wardrik, MyApp.AgentRuntime}, port: 4000}]

It's also a `Plug`, so your router can forward a path to it.

## Options

  * `:server` - required. `{module, name}`: the `Wardrik.Server` module, and the instance name
    it runs. Raises `ArgumentError` without it.
  * `:authenticator` - a `WardrikHTTP.Authenticator`, as `{module, config}`.
    `{WardrikHTTP.Bearer, []}` unless set.
  * `:sign_in` - `{module, function, args}` returning the `{plug, opts}` that serves sign-in
    pages, or `nil`. `nil` unless set.
  * `:keepalive` - milliseconds an idle event stream waits before sending a comment. `15_000`.

As a child, it also takes Bandit's options, like `:port` and `:ip`.

## Routes

| Route | Serves |
| --- | --- |
| each operation's route | every operation in `WardrikProtocol`, as JSON |
| the same, with `Accept: text/event-stream` | streaming operations, as server-sent events |
| `GET /v1/openapi.json` | the OpenAPI document |
| `GET /v1/workers` | the tool workers' WebSocket. See `WardrikHTTP.Worker`. |
| `POST /v1/channels/{channel}/{path}` | a chat app's request, relayed to the channel and back |
| `/oauth/*` | sign-in pages, from `:sign_in` |

`GET /v1/workers` returns `426` to a request with a valid token that isn't a WebSocket upgrade,
so a worker can check its token first.

Every response has a `request-id` header. It's the caller's own if the request sent one.

# `child_spec`

```elixir
@spec child_spec(keyword()) :: Supervisor.child_spec()
```

Returns a child spec that serves with Bandit. Options not listed above go to Bandit.

---

*Consult [api-reference.md](api-reference.md) for complete listing*