class LittleGhost::Network::HostPolicy

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.