# `Quiver.Supervisor`
[🔗](https://github.com/edlontech/quiver/blob/main/lib/quiver/supervisor.ex#L21)

Named supervision tree for a Quiver HTTP client instance.

Starts a Registry for pool lookup and a DynamicSupervisor for pool processes.
Pool config rules are parsed eagerly via `Quiver.Config.validate_pool/1` and
stored in `:persistent_term`. All configuration is validated once at startup;
downstream pools and transports trust the pre-validated config.

## Options

  * `:name` - Atom identifying this instance (default: `Quiver.Pool`).
    Must be a compile-time atom; dynamic atom creation from user input
    will exhaust the atom table.

  * `:pools` - Map of origin patterns to pool configuration. Keys are URI
    strings, wildcard patterns (`"https://*.example.com"`), or `:default`.
    Rules are matched by specificity: exact > wildcard > default.

## Pool Configuration

* `:size` (`t:integer/0`) - Number of connections in the pool. The default value is `10`.

* `:checkout_timeout` (`t:integer/0`) - Max wait time in ms to acquire a connection. The default value is `5000`.

* `:idle_timeout` (`t:integer/0`) - Time in ms before idle connections are closed. The default value is `30000`.

* `:ping_interval` (`t:integer/0`) - Interval in ms to check connection health. The default value is `5000`.

* `:protocol` (`:auto` | `:http1` | `:http2`) - HTTP protocol version. :auto detects via ALPN negotiation. The default value is `:auto`.

* `:max_connections` (`t:integer/0`) - Max HTTP/2 connections per origin. The default value is `1`.

* `:connect_timeout` (`t:integer/0`) - TCP/TLS connect timeout in ms. The default value is `5000`.

* `:recv_timeout` (`t:integer/0`) - Socket receive timeout in ms. The default value is `15000`.

* `:buffer_size` (`t:integer/0`) - Socket receive buffer size in bytes. The default value is `8192`.

* `:verify` (`:verify_peer` | `:verify_none`) - TLS certificate verification mode. The default value is `:verify_peer`.

* `:cacerts` (`:default` | list of `t:term/0`) - CA certificates. :default uses OS store. The default value is `:default`.

* `:alpn_advertised_protocols` (list of `t:String.t/0`) - ALPN protocols to advertise during TLS. The default value is `[]`.

* `:proxy` (`t:keyword/0`)

## Examples

    # Using the default name:
    children = [{Quiver.Supervisor, pools: %{default: [size: 5]}}]

    # Using a custom name:
    children = [
      {Quiver.Supervisor,
       name: :my_client,
       pools: %{
         :default => [size: 5],
         "https://api.example.com" => [size: 25, protocol: :http2],
         "https://*.cdn.example.com" => [size: 50, connect_timeout: 10_000]
       }}
    ]

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `registry_name`

```elixir
@spec registry_name(atom()) :: atom()
```

Derives the Registry name for a Quiver instance.

# `start_link`

```elixir
@spec start_link(
  name: atom(),
  pools: %{optional(binary() | :default) => Quiver.Config.pool_opts()}
) ::
  Supervisor.on_start()
```

Starts a Quiver instance with the given pool configuration.

# `supervisor_name`

```elixir
@spec supervisor_name(atom()) :: atom()
```

Derives the DynamicSupervisor name for a Quiver instance.

---

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