# Class LittleGhost::Network::AuthorizerServer

Documentation version: Edge

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

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`.

## Inheritance

`LittleGhost::Network::AuthorizerServer < Object`

## Attributes

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

Filesystem path of the listening socket.

## Class methods

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

```ruby
.new(socket_path:, authorizer:, run: nil, mode: 0o600, peer_uids: nil)
```

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.

## Instance methods

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

```ruby
#close()
```

Stops accepting, closes open connections, waits briefly for in-flight
requests, and removes the socket. Calling `close` more than once is safe.

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

```ruby
#serve(stop_io: nil)
```

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.

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

```ruby
#start()
```

Binds the socket and serves requests on a background thread. Returns `self`;
call #close to stop.
