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\Aand\zto match the whole path. Without it, every path is accepted. deny_paths(*patterns)-
Rejects matching paths before
pathsis consulted. Deny patterns also match the lowercase path. pass_headers(:all_except_credentials)orpass_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
authorizationandx-api-keynever reach the upstream; useinjectto 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
requireblock must pass. timeout(seconds)-
Bounds each request to this host.
0disables 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.
Attributes
Public Class Methods
Source
# File lib/little_ghost/network/host_policy.rb, line 84 def initialize(&) raise PolicyError, "network host policy requires a definition block" unless block_given? definition = Definition.new definition.instance_exec(&) @rules = definition.rules.freeze @default = definition.default_rule raise PolicyError, "network host policy must declare at least one host or a default" if @rules.empty? && @default.nil? @authorizer = ->(request:) { authorize(request) } freeze end
Builds a policy from the host and default declarations in the block.
Public Instance Methods
Source
# File lib/little_ghost/network/host_policy.rb, line 140 def forward_headers rules = @rules.values + [@default].compact (rules.any? { |rule| rule.pass_headers.is_a?(Array) }) ? :all : [] end
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.
Source
# File lib/little_ghost/network/host_policy.rb, line 98 def hosts = @rules.keys
Exact host names with their own rule.
Source
# File lib/little_ghost/network/host_policy.rb, line 146 def mutation_headers rules = @rules.values + [@default].compact rules.reject { |rule| rule.injections.empty? }.flat_map(&:inject_headers).uniq.sort end
Header names an inject block may set on an upstream request.
# File lib/little_ghost/network/host_policy.rb, line 159 def network_policy(allow: [], facades: []) Sandbox::NetworkPolicy.new( mode: :allowlist, allow:, inspection: Array(allow).empty? ? :connect : :http, authorizer:, forward_headers:, mutation_headers:, timeouts:, facades: ) end
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.
Source
# File lib/little_ghost/network/host_policy.rb, line 134 def timeouts @rules.filter_map { |name, rule| [name, rule.timeout] unless rule.timeout.nil? }.to_h end
Per-host request timeouts in seconds, for hosts that declare one.