# `SmolBox.Worker`
[🔗](https://github.com/hfiguera/smolbox/blob/v0.1.3/lib/smolbox/worker.ex#L1)

Trusted host configuration for a worker control endpoint.

Remote endpoints require HTTPS and a bearer token. Plain HTTP requires an
explicit loopback opt-in or a local Unix socket. TLS verification cannot be
disabled. Credentials are excluded from inspection and never enter job state.
This configuration does not attest to virtualization readiness or isolation.

# `t`

```elixir
@type t() :: %SmolBox.Worker{
  allow_insecure_loopback: boolean(),
  base_url: String.t(),
  ca_cert_file: String.t() | nil,
  connect_timeout_ms: pos_integer(),
  id: String.t(),
  max_request_bytes: pos_integer(),
  max_response_bytes: pos_integer(),
  operation_timeout_ms: pos_integer(),
  pool_timeout_ms: pos_integer(),
  receive_timeout_ms: pos_integer(),
  token: String.t() | nil,
  unix_socket: String.t() | nil
}
```

# `new`

```elixir
@spec new(term(), term(), term()) :: {:ok, t()} | {:error, SmolBox.Error.t()}
```

Validate a worker endpoint without making a network request.

`id` is a stable identifier of at most 64 ASCII letters, digits, dots, underscores
or hyphens, beginning with a letter/digit. `base_url` is the origin URL, such as
`https://worker.example`; do not append `/api/v1` or include credentials/query parameters.

| Option | Default | Meaning |
|---|---|---|
| `:token` | `nil` | Bearer token, required for HTTPS endpoints |
| `:ca_cert_file` | `nil` | Existing CA file; otherwise use the transport's default trust store |
| `:allow_insecure_loopback` | `false` | Explicitly permit local HTTP on `localhost`, `127.0.0.1`, or `::1` |
| `:unix_socket` | `nil` | Absolute local socket path, at most 100 bytes, with a loopback HTTP base URL |
| `:connect_timeout_ms` | `1000` | Connection budget |
| `:receive_timeout_ms` | `15_000` | Receive-idle budget |
| `:pool_timeout_ms` | `5000` | Connection-pool checkout budget |
| `:operation_timeout_ms` | `30_000` | Total client-operation budget, including streaming callbacks |
| `:max_request_bytes` | `1_048_576` | Encoded request body cap, at most 2 MiB |
| `:max_response_bytes` | `16_777_216` | Encoded response/stream cap, at most 32 MiB |

All budgets are positive and at most 900,000 ms. Byte caps are positive. HTTPS
always requires peer/hostname verification. The worker's own file-transfer cap
must be configured separately. Returns a typed `:validation` error for invalid
options. See [Low-level client](client.html) for transport examples.

## Example

    iex> {:ok, worker} = SmolBox.Worker.new("local", "http://127.0.0.1:19470", allow_insecure_loopback: true)
    iex> worker.operation_timeout_ms
    30_000

# `validate`

```elixir
@spec validate(term()) :: :ok | {:error, SmolBox.Error.t()}
```

Revalidate configuration before using credentials or starting network I/O.

---

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