class LittleGhost::Network::AuthorizerServer
Answers Envoy’s headers-only external authorization requests on a Unix socket by calling a trusted authorizer.
EnvoyGateway starts one for each run that needs it. An application that supervises Envoy itself can run the server in a separate, less privileged process so credentials stay out of both the sandbox and Envoy:
hosts = LittleGhost::Network::HostPolicy.new do host("api.example.com") { inject { {"x-api-key" => ENV.fetch("HELP_CENTER_API_KEY")} } } end server = LittleGhost::Network::AuthorizerServer.new( socket_path: "/run/egress-private/authorizer.sock", authorizer: hosts.authorizer, mode: 0o660, peer_uids: [Etc.getpwnam("envoy").uid] ) stop_reader, stop_writer = IO.pipe Signal.trap("TERM") { stop_writer.write_nonblock(".", exception: false) } server.serve(stop_io: stop_reader)
authorizer receives request:, a Network::Request, and an optional run: keyword, and returns a Network::Decision. It may be called from several threads at once. An exception or any other return value denies the request with status 503; the response never includes the exception message.
Every allowed request also loses its Network::CREDENTIAL_HEADERS and forwarding headers unless the decision sets them.
The server answers only authorization requests that come from a listener in a configuration written by EnvoyGateway: Envoy prefixes each request path with the listener’s origin, which tells the server whether the destination comes from the inspected request’s Host or from a facade’s fixed upstream. Any other request is denied with status 503 without calling authorizer.
Attributes
Filesystem path of the listening socket.
Public Class Methods
# File lib/little_ghost/network/authorizer_server.rb, line 71 def initialize(socket_path:, authorizer:, run: nil, mode: 0o600, peer_uids: nil) @socket_path = socket_path @authorizer = authorizer @run = run @mode = Integer(mode) @peer_uids = peer_uids&.map { |uid| Integer(uid) }&.freeze @mutex = Mutex.new @clients = [] @workers = [] @stopping = false end
Builds a server for socket_path. mode sets the socket’s permission bits so a separate Envoy user can connect. The socket is created in a private directory, given mode, and then moved to socket_path, so it never has wider permissions; an existing socket, file, or symbolic link at socket_path is replaced. Keep socket_path in a directory that only Envoy and the authorizer can reach.
peer_uids lists the user IDs allowed to connect; connections from any other user are closed without a response. nil accepts any peer that can open the socket. Peer IDs are read in the authorizer’s own user namespace: when the authorizer runs inside a separate namespace, such as a Bubblewrap sandbox, unmapped peers appear as the overflow user, so rely on directory and group permissions instead.
Public Instance Methods
Source
# File lib/little_ghost/network/authorizer_server.rb, line 107 def close @stopping = true @server&.close unless @server&.closed? clients, workers = @mutex.synchronize { [@clients.dup, @workers.dup] } clients.each { |client| client.close unless client.closed? } workers.each do |worker| next if worker.join(SHUTDOWN_TIMEOUT) worker.kill worker.join end @thread&.join unless @thread == Thread.current remove_socket if @bound @bound = false nil end
Stops accepting, closes open connections, waits briefly for in-flight requests, and removes the socket. Calling close more than once is safe.
Source
# File lib/little_ghost/network/authorizer_server.rb, line 97 def serve(stop_io: nil) bind unless @server accept_loop(stop_io:) nil ensure close end
Binds the socket when needed and serves requests on the calling thread until stop_io becomes readable or close is called, then closes the server. Use it as the main loop of a standalone authorizer process.