# Configuration

Everything lives in `config/holler.php`. Most keys read a `HOLLER_*` env variable, so few apps need to publish the file. When you want to edit it:

```bash
php artisan vendor:publish --tag=holler-config
```

The settings that take a closure (who may call whom, names, avatars, ICE servers, video, the group size) are on `AppContext`, covered in [Calling](https://packstub.dev/docs/holler/calling).

## ICE servers (STUN / TURN)

What a call needs depends on where the two people are:

| The two people are | What the call needs | Set |
| --- | --- | --- |
| on the same network (an office, a VPN) | nothing | `HOLLER_STUN_URL=` (empty) if you want no outside server at all |
| on different networks, behind ordinary routers | a STUN server | nothing: this is the default |
| behind a strict NAT, a VPN or a corporate firewall | a TURN server | `HOLLER_TURN_URL` and a secret or a login |

So an intranet app runs with no outside service, the default covers most calls between homes and offices, and reaching everyone takes a TURN server, your own or a hosted one.

Two browsers need help to find a path to each other. A **STUN** server tells each one its public address, and for most calls that is enough: the media then goes straight from browser to browser. The package uses Google's public STUN server out of the box, free and without an account, so calls work right after the install:

```dotenv
HOLLER_STUN_URL=stun:stun.l.google.com:19302
```

Any other STUN server works the same way (`stun:stun.cloudflare.com:3478`, or your own), several can be listed with commas, and an empty value uses none. Public STUN servers come without a guarantee, so a production app that depends on calls usually runs its own beside the TURN server below (coturn does both).

Behind a strict NAT, a VPN or a corporate firewall no direct path exists, and the call needs a **TURN** relay that forwards the media. This is a minority of calls, but for the people on those networks it is every call. Point the package at a relay, your own [coturn](https://github.com/coturn/coturn) or a hosted service:

```dotenv
HOLLER_TURN_URL=turn:turn.example.com:3478,turns:turn.example.com:443?transport=tcp
HOLLER_TURN_SECRET=the-secret-coturn-shares-with-the-app
```

`HOLLER_TURN_URL` takes several addresses separated by commas. Listing a `turns:` address on port 443 over TCP beside the plain one is what gets a call through networks that only let web traffic out.

With `HOLLER_TURN_SECRET` every call gets a username and a credential that expire (after `HOLLER_TURN_TTL` seconds, 3600 by default), signed with the secret the TURN server shares with the app, so no long-lived password ever reaches a browser. It is coturn's `use-auth-secret` scheme:

```ini
# /etc/turnserver.conf
listening-port=3478
tls-listening-port=5349
realm=turn.example.com
use-auth-secret
static-auth-secret=the-secret-coturn-shares-with-the-app
cert=/etc/letsencrypt/live/turn.example.com/fullchain.pem
pkey=/etc/letsencrypt/live/turn.example.com/privkey.pem
```

A server with one fixed login takes `HOLLER_TURN_USERNAME` and `HOLLER_TURN_CREDENTIAL` instead of the secret.

A hosted TURN service (Cloudflare Realtime, Twilio, Metered and others) hands out short-lived credentials through its API. Ask for them in a closure and return what the browser should use:

```php
app(AppContext::class)->iceServersUsing(fn (): array => [
    ['urls' => 'stun:stun.example.com:3478'],
    ...Http::withToken(config('services.turn.token'))
        ->post(config('services.turn.url'), ['ttl' => 3600])
        ->throw()
        ->json('iceServers'),
]);
```

The browsers ask for the servers each time a call starts (the `ice-servers` route), never when the page loads: the closure runs per call, the credentials never sit in the page's HTML, and a tab left open all day still gets fresh ones. Any server in that list may carry `secret` (and `ttl`) instead of a username and credential, and is signed the same way; `Holler::turnCredentials($secret, $ttl)` returns the pair on its own.

ICE candidates show each side's network addresses to the other. To keep them private, send everything through your TURN server:

```dotenv
HOLLER_ICE_TRANSPORT_POLICY=relay
```

A TURN relay forwards packets it cannot decrypt (WebRTC media is encrypted end to end with DTLS-SRTP).

### Why Laravel cannot be the relay

The signaling (who calls whom, the offers and answers) goes through your Laravel routes. The audio and video cannot: a browser sends them over UDP or a long-lived socket, to the other browser or to a TURN server, and offers no way to send them through HTTP requests. A relay is therefore always a TURN server. [coturn](https://github.com/coturn/coturn) is one small daemon on any server with a public address, it answers STUN too, and with `HOLLER_TURN_SECRET` it is all the app needs.

### When a call does not connect

A call that rings and is answered but never shows the other person ends after `HOLLER_RECONNECT_TIMEOUT` with "Could not connect" on both sides: the browsers found no path to each other. The usual reasons:

- **No TURN server, and one side is on a strict network.** The browser console says so. Add a TURN server, with a `turns:` address on port 443 for the strictest networks.
- **A TURN server that refuses.** Wrong, expired or removed credentials look the same as no server at all. Open `chrome://webrtc-internals` (`about:webrtc` in Firefox) during a call and look for `icecandidateerror`: a code in the 400s means the server turned the login down, 701 means it could not be reached.
- **`HOLLER_ICE_TRANSPORT_POLICY=relay` without a working TURN server.** Every call then has to go through the relay, so none connects, also on one network. Remove the line or fix the server.

To check a TURN server on its own, set `HOLLER_ICE_TRANSPORT_POLICY=relay` for a moment and call between two tabs on your own machine: the call connects only when the relay works.

A call that connected and then ends with "Connection lost" had a path and lost it (a laptop that went to sleep, a network that dropped) for longer than the timeout. During a call a "Weak connection" badge on someone's picture means many packets to or from them are being lost or arrive late.

## Polling and timeouts

Every open window asks the server for incoming calls every 5 seconds and, while a call rings or runs, for signals every second; that poll is also the heartbeat that tells the other side you are still there. Hidden tabs without a call poll less often.

| Variable | Default | |
| --- | --- | --- |
| `HOLLER_POLL_IDLE` | 5000 | milliseconds between polls without a call |
| `HOLLER_POLL_ACTIVE` | 1000 | milliseconds between polls while a call rings or runs |
| `HOLLER_RING_TIMEOUT` | 45 | seconds before someone who does not answer is marked missed |
| `HOLLER_RECONNECT_TIMEOUT` | 15 | seconds a side may be away before that person is dropped from the call |
| `HOLLER_HOLD_TIMEOUT` | 120 | seconds a [call stays on hold](https://packstub.dev/docs/holler/calling#calls-on-hold) after its holder closed every window; 0 keeps it for good |
| `HOLLER_PEOPLE_SEARCH` | true | the [Add someone](https://packstub.dev/docs/holler/calling#who-can-be-found) search in the call window; the columns it searches are `search_columns` in the config file (`name` by default) |
| `HOLLER_MAX_PARTICIPANTS` | 4 | people on one call, the caller included |
| `HOLLER_VIDEO` | true | `false` makes every call a voice call |
| `HOLLER_POP_OUT` | true | the widget opens each call in a [window of its own](https://packstub.dev/docs/holler/the-widget#the-pop-out-window) |

The routes take whatever middleware you pass to `Holler::routes()`. Ringing and the people search are paced per person out of the box (see Limits); if you add a `throttle` of your own for the rest, keep in mind that a window polls once a second during a call.

## Limits

| Variable | Default | |
| --- | --- | --- |
| `HOLLER_RATE_LIMIT_CALLS` | 30 | how many times a minute one person may ring or add someone; past it the server answers 429; 0 turns the limit off |
| `HOLLER_RATE_LIMIT_PEOPLE` | 60 | how many times a minute one person may search for people to add; 0 turns the limit off |
| `HOLLER_MAX_SIGNAL_KB` | 64 | the largest signal the server relays, in KB (a session description is a few); 0 turns the check off |
| `HOLLER_MAX_PENDING_SIGNALS` | 500 | signals from one person that may wait unread on a call; past it the server answers 429; 0 turns the check off |

## Pruning

Signals are deleted once the other side's window has read them, and all of them when their call ends. `holler:prune` does the rest: it ends the calls everybody walked away from (nobody polls them any more, so nothing else would) and deletes ended calls older than `HOLLER_PRUNE_AFTER_DAYS` (90), with their participants. `HOLLER_PRUNE_AFTER_DAYS=null` keeps the call log forever.

```php
// routes/console.php
Schedule::command('holler:prune')->daily();
```

`--days=30` overrides the config for one run.

## Guards and databases

| Key | Default | |
| --- | --- | --- |
| `guard` | null | the guard people sign in with where calls happen; null for the default guard. The routes sit behind `auth:<guard>` and users are looked up through it |
| `connection` (`HOLLER_DB_CONNECTION`) | null | where the calls tables live; null for the default connection |

Calls are kept apart by guard: user 7 of `admin` is never rung for user 7 of `web`, even when both sign in to the same app. Under a database per tenant, set `HOLLER_DB_CONNECTION` to the central connection, so a call between two places meets in one table.

## Events and the call log

| Event | Carries | Fires when |
| --- | --- | --- |
| `CallStarted` | `call` | a call starts ringing |
| `CallAnswered` | `call` | the first person answers and the call becomes active |
| `ParticipantJoined` | `call`, `participant` | anyone answers |
| `ParticipantHeld` | `call`, `participant` | someone puts the call on hold |
| `ParticipantResumed` | `call`, `participant` | someone comes back to a call they put on hold |
| `ParticipantLeft` | `call`, `participant` | anyone hangs up, declines, is missed or is dropped |
| `CallEnded` | `call` | the call ends, for whatever reason |

The events live in `Packstub\Holler\Events`. A call log from `CallEnded`:

```php
use Packstub\Holler\Events\CallEnded;

Event::listen(CallEnded::class, function (CallEnded $event) {
    $event->call->caller_id;     // user ids as strings, so integer and UUID keys both fit
    $event->call->callee_id;     // the first person called
    $event->call->participants;  // everyone, with seat, status (joined, left, declined, missed, dropped) and times
    $event->call->end_reason;    // declined | cancelled | missed | hung_up | dropped, or what your code passed to Holler::end()
    $event->call->duration();    // seconds, null if never answered
});
```

`Packstub\Holler\Models\Call` is a plain Eloquent model over the `holler_calls` table (with `CallParticipant` and `CallSignal` beside it), ready for a page or a report of your own.
