# Class LittleGhost::Network::HostPolicy

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Network/HostPolicy.html

Declares which HTTPS requests each host accepts and which credentials the
gateway adds before forwarding them.

A HostPolicy turns a short Ruby description into the authorizer that an
inspecting gateway or a Facade consults for every request. Rules match exact
host names; a `default` rule covers any other host the network policy lets
through, and a host without a rule is denied.

    hosts = LittleGhost::Network::HostPolicy.new do
      host "api.example.com" do
        methods :post
        paths "/v1/answers", "/v1/answers/*"
        inject { |request| {"x-api-key" => ENV.fetch("HELP_CENTER_API_KEY")} }
        timeout 0
      end

      default do
        methods :get, :head
      end
    end

    hosts.authorizer.call(request:)  # => LittleGhost::Network::Decision

Inside `host` and `default` blocks:

`methods(*names)`
:   Accepts only these HTTP methods. Without it, every method is accepted.

`paths(*patterns)`
:   Accepts only matching paths. A String matches exactly, or as a prefix when
    it ends in `*`; a Regexp matches anywhere it applies, so anchor
    it with `\A` and `\z` to match the whole path.
    Without it, every path is accepted.

`deny_paths(*patterns)`
:   Rejects matching paths before `paths` is consulted. Deny patterns also
    match the lowercase path.

`pass_headers(:all_except_credentials)` or `pass_headers(*names)`
:   Chooses which client headers reach the upstream. The default passes every
    header except credentials. A name list removes every other header. Client
    credentials such as `authorization` and `x-api-key` never reach
    the upstream; use `inject` to supply them.

`inject(*names) { |request| headers }`
:   Adds the returned Hash of headers to the upstream request. Declare the
    names when the block sets anything other than a credential header from
    Network::CREDENTIAL_HEADERS.

`require { |request| condition }`
:   Rejects the request unless the block returns a truthy value. Every
    `require` block must pass.

`timeout(seconds)`
:   Bounds each request to this host. `0` disables the bound for streaming
    responses.

Paths are matched after the query string is removed and percent-encoding is
decoded. A path that still contains encoded characters after three rounds of
decoding, a backslash, a control character such as a NUL byte or line break,
an empty segment, or a `.` or `..` segment (including
one followed by `;` parameters) is rejected with status 400. When a
rule declares `methods`, method-override headers such as
`x-http-method-override` are removed and a request with a `_method`
query parameter is rejected.

Blocks run in the authorizer's process for every matching request, so they can
read a credential that changes over time. They must be thread-safe. A
HostPolicy never includes header values in errors or decision reasons; keep
credentials out of exception messages raised from your own blocks as well.

## Inheritance

`LittleGhost::Network::HostPolicy < Object`

## Attributes

<a id="attribute-i-authorizer"></a>
### `authorizer` (R)

Returns a callable `(request:) -> Decision` for
Sandbox::NetworkPolicy and AuthorizerServer.

## Class methods

<a id="method-c-new"></a>
### `.new`

```ruby
.new(&)
```

Builds a policy from the `host` and `default` declarations in the block.

## Instance methods

<a id="method-i-authorize"></a>
### `#authorize`

```ruby
#authorize(request)
```

Returns the Decision for one Network::Request.

Denials use status 403, or 400 for a path that cannot be matched safely.
Exceptions raised by `require` and `inject` blocks propagate; gateways turn
them into a 503 response.

<a id="method-i-forward_headers"></a>
### `#forward_headers`

```ruby
#forward_headers()
```

Returns `:all` when a rule needs to see every client header name to
remove the ones it does not pass, and otherwise an empty Array.

<a id="method-i-hosts"></a>
### `#hosts`

```ruby
#hosts()
```

Exact host names with their own rule.

<a id="method-i-mutation_headers"></a>
### `#mutation_headers`

```ruby
#mutation_headers()
```

Header names an `inject` block may set on an upstream request.

<a id="method-i-network_policy"></a>
### `#network_policy`

```ruby
#network_policy(allow: [], facades: [])
```

Builds a Sandbox::NetworkPolicy that applies this policy.

`allow` lists the `host:443` destinations a sandboxed process may
reach through the explicit proxy; those requests are inspected and authorized
by this policy. `facades` lists Network::Facade declarations whose requests
this policy also authorizes. A host can appear in this policy without
appearing in `allow`, which makes it reachable only through a facade.

<a id="method-i-timeouts"></a>
### `#timeouts`

```ruby
#timeouts()
```

Per-host request timeouts in seconds, for hosts that declare one.
