# Class LittleGhost::Network::Facade

Documentation version: Edge

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

A plaintext listener that forwards every request to one HTTPS host.

A facade gives a client that honors a base URL, such as a command-line tool
pointed at `http://127.0.0.1:3130`, a way to reach exactly one
upstream without trusting a proxy certificate. The gateway originates TLS to
`upstream` and asks the policy's authorizer about every request before
forwarding it, so the authorizer can restrict methods and paths and replace a
placeholder credential with a real one. Responses stream back without
buffering.

    LittleGhost::Network::Facade.new(
      name: :help_center,
      upstream: "api.example.com",
      port: 3130,
      timeout: 0
    )

Exactly one of `port` or `socket` is required. `port` listens on
`127.0.0.1`; `socket` is an absolute Unix socket path that the
application makes reachable from the sandbox. `timeout` bounds each request in
seconds; `0` disables the bound for streaming responses, and `nil` uses the
policy's timeout for the upstream host or no bound.

Any process that can connect to the facade receives the credentials its
authorizer injects. Place a socket in a directory that only the intended
sandbox can reach, and use a port only when the sandbox has its own network
namespace.

## Inheritance

`LittleGhost::Network::Facade < Data.define(:name, :upstream, :port, :socket, :timeout)`

## Class methods

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

```ruby
.coerce(value)
```

Returns `value` unchanged or builds a facade from a Hash.

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

```ruby
.new(name:, upstream:, port: nil, socket: nil, timeout: nil)
```

Builds a normalized facade declaration.

## Instance methods

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

```ruby
#host()
```

The upstream DNS name without its port.

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

```ruby
#upstream_port()
```

The upstream TLS port.
