# Runtime Bootstrap Keeper

> Runtime Bootstrap Keeper is an Agent Skill for development published in the discord-php/DiscordPHP repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Maintain Discord.php runtime bootstrapping, startup options, event loop, gateway connection, reconnection, member chunking, cache configuration, and process lifecycle. Use when touching Discord.php, startup wiring, intents, or root repositories.

- Skill name: `runtime-bootstrap-keeper`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/discord-php/DiscordPHP/blob/HEAD/.agents/skills/runtime-bootstrap-keeper/SKILL.md
- Repository: discord-php/DiscordPHP (1,082 GitHub stars when collected)

## SKILL.md

# Skill: runtime-bootstrap-keeper

Use this skill when work touches `src/Discord/Discord.php`, startup options, loop setup, cache configuration, gateway connection behavior, readiness, member chunking, reconnect logic, or root repositories.

This is not generic PHP skill. This is the orchestrator-lifecycle guard. Load it when changing how the client boots, what dependencies it wires, how it connects to Discord's gateway, or how it reaches the ready state.

## Goal

Keep `Discord` as the single bootstrapping orchestrator:

- resolves all user-facing options centrally through `OptionsResolver`
- wires infrastructural dependencies once during construction
- connects to the gateway eagerly from the constructor
- delegates loop start to a one-liner `run()` method
- maintains lifecycle flags that the rest of the system depends on
- owns root repositories as long-lived properties on the `Client` part
- manages the ready flow: guild backfill → member chunking → init emission

## Read in this order

1. `src/Discord/Discord.php` — the entire orchestrator
2. `src/Discord/WebSockets/Handlers.php` — handler registry for gateway events
3. `src/Discord/WebSockets/Event.php` — event constant definitions
4. `src/Discord/Factory/Factory.php` — part/repository factory, created once here
5. `src/Discord/Parts/User/Client.php` — the `Client` part that holds root repos
6. `README.md` — public-facing construction examples
7. `guide/basics.rst` — user-facing lifecycle guide

Do not start by reading individual event classes. Understand the wiring in `Discord.php` first, then follow references outward.

## Core contract

`Discord` is the application entry point. It is not a service class, not a controller, not a request handler. It is a long-running CLI process orchestrator built on ReactPHP. The entire class rests on these guarantees:

- `__construct()` does real work: resolves options, creates HTTP client, creates Factory, creates `Client` part, registers handlers, and calls `connectWs()` to open the gateway
- `run()` only starts the ReactPHP event loop — it must stay a one-liner
- the class assumes CLI SAPI — a web-server warning is logged if `php_sapi_name()` is not `cli` or `micro`
- `Factory` is created exactly once and shared across the entire system
- root repositories (`guilds`, `users`, `private_channels`, `emojis`, `sounds`, `sticker_packs`, `lobbies`) live on the `Client` part, proxied through `Discord::__get()`

If a change violates any of these, the runtime becomes unpredictable.

## Options and intent resolution

All user-facing configuration is resolved in `resolveOptions()` using Symfony's `OptionsResolver`. This is the single normalization point for the entire client.

### Key options

| Option | Type | Default | Purpose |
| --- | --- | --- | --- |
| `token` | string | required | Bot authentication token |
| `loop` | `LoopInterface` | `Loop::get()` | ReactPHP event loop |
| `logger` | `LoggerInterface\|null` | Monolog stdout | PSR-3 logger |
| `intents` | `array\|int` | `Intents::getDefaultIntents()` | Gateway intents bitmask |
| `loadAllMembers` | `bool\|array` | `false` | Enable member chunking for all or specific guild IDs |
| `disabledEvents` | `array` | `[]` | Event names to skip in handler registry |
| `storeMessages` | `bool` | `false` | Whether to cache messages |
| `retrieveBans` | `bool\|array` | `false` | Whether to fetch bans on guild create |
| `cache` | `array\|CacheConfig\|CacheInterface` | `[AbstractRepository::class => null]` | Cache backend for repositories |
| `collection` | `string` | `Collection::class` | Collection class implementing `ExCollectionInterface` |
| `useTransportCompression` | `bool` | `true` | zlib-stream transport compression |
| `usePayloadCompression` | `bool` | `true` | Per-payload compression |
| `socket_options` | `array` | `[]` | Passed to React socket connector |
| `large_threshold` | `int\|null` | `null` | Guild member threshold for "large" guilds |
| `presence` | `array\|null` | `null` | Initial presence payload |

### Intent folding

If `intents` is passed as an array of intent constants, `resolveOptions()` folds them into a single bitmask with bitwise OR. This happens once at resolution time — the rest of the system sees only the integer.

If `loadAllMembers` is enabled, the resolver enforces that `GUILD_MEMBERS` intent is included, throwing `IntentException` otherwise.

### Cache normalization

The `cache` option normalizer converts bare `CacheInterface` or `CacheConfig` values into the canonical `[AbstractRepository::class => $config]` array shape. The default `null` value means `LegacyCacheWrapper` (in-memory) is used. External cache backends are treated as experimental and logged as warnings.

## Construction vs run() lifecycle

### What `__construct()` does (in order)

1. Validates x86 GMP extension requirement
2. Calls `resolveOptions()` — all normalization and validation happens here
3. Stores `$token`, `$loop`, `$logger`, `$cacheConfig`, `$collectionClass`
4. Checks CLI SAPI — logs critical warning if web context detected
5. Creates `SocketConnector` and `Connector` (WebSocket factory)
6. Creates `Handlers` instance — the gateway event handler registry
7. Warns if critical events (`GUILD_CREATE`, `GUILD_DELETE`, `RESUMED`, `READY`, `GUILD_MEMBERS_CHUNK`) are in `disabledEvents`
8. Removes disabled event handlers from registry
9. Creates `Http` client with React driver
10. Creates `Factory` — the single part/repository factory for the system
11. Creates `Client` part via factory — this is where root repositories are born
12. Stores compression settings
13. Calls `connectWs()` — initiates the gateway connection

### What `run()` does

```php
public function run(): void
{
    $this->loop->run();
}
```

Nothing else. The loop was already wired during construction. `run()` simply unblocks the event loop. Do not add bootstrap logic here.

### Why this matters

The eager constructor means the system is fully wired before `run()` is called. User code that registers event listeners between `new Discord(...)` and `$discord->run()` works because the loop has not started yet but all infrastructure is ready. Moving connection logic to `run()` would break this contract.

## Gateway connection and reconnection

### `connectWs()`

Retrieves the gateway URL via `setGateway()`, then opens a WebSocket connection through `$this->wsFactory`. On success, calls `handleWsConnection()`. On failure, calls `handleWsConnectionFailed()` which retries after 5 seconds.

`setGateway()` calls the REST endpoint `Endpoint::GATEWAY_BOT` to get the gateway URL and session start limit. The URL is decorated with `v`, `encoding`, and optional `compress=zlib-stream` query parameters in `buildParams()`. If a `resume_gateway_url` was received from a prior READY, that is used instead.

### `handleWsConnection()`

Sets `$this->connected = true`, initializes the payload rate counter (120/60s limit with 5 reserved for heartbeats), and registers `message`, `close`, and `error` listeners on the WebSocket.

### `handleWsClose()`

Cancels heartbeat and payload timers. If `$this->closing` is true, returns silently. If the close code is a critical op code (checked via `Op::getCriticalCloseCodes()`), does not reconnect. Otherwise, sets `$reconnecting = true` and calls `connectWs()` after a 2-second delay.

### `handleHello()`

Received when the gateway connection is established. Calls `setupHeartbeat()` with the server-provided interval, then calls `identify()`.

### `identify()` vs `resume()`

`identify()` sends `OP_IDENTIFY` with token, properties, intents, shard info, and presence. `resume()` sends `OP_RESUME` with token, session ID, and last sequence number. The gateway decides which path to use after reconnection via `handleInvalidSession()`.

### `handleInvalidSession()`

If the session is resumable (`$data->d` is true), attempts `resume()`. Otherwise, calls `identify()` after a 2-second delay.

### Heartbeat

`setupHeartbeat()` creates a periodic timer at the server-specified interval. Each `heartbeat()` call sends `OP_HEARTBEAT` with the current sequence number and starts a guard timer. If no `HEARTBEAT_ACK` arrives within one heartbeat interval, the connection is closed with code 1001, triggering reconnect.

## Ready flow

The ready sequence is the most delicate part of the bootstrap. It ensures all guilds are loaded and optionally chunked before userland code runs.

### Step 1: `handleReady()`

Receives the READY payload. If `$this->reconnecting` is true, it skips full re-parsing and just emits `reconnected`. Otherwise:

1. Stores `resume_gateway_url` for future reconnects
2. Fills the `Client` part with user data and stores `sessionId`
3. Iterates `content->guilds` and processes each through `GuildCreate::handle()`
4. Tracks unavailable guilds

If all guilds are immediately available, calls `ready()` directly. Otherwise, sets up temporary `GUILD_CREATE` and `GUILD_DELETE` listeners to track when unavailable guilds become available. A 60-second safety timer also triggers `ready()` as fallback.

### Step 2: `setupChunking()`

Called when all guilds are available. If `loadAllMembers` is false, calls `ready()` immediately. Otherwise, starts a periodic 5-second timer that calls `checkForChunks()`.

### Step 3: `checkForChunks()`

Drains the `$largeGuilds` array in batches of 50, sending `OP_REQUEST_GUILD_MEMBERS` for each. Guilds are added to `$largeGuilds` by `addLargeGuild()`, which is called from `GuildCreate` event handling. If `loadAllMembers` is an array of guild IDs, only those guilds are chunked.

### Step 4: `handleGuildMembersChunk()`

Processes incoming member chunk payloads, caching each `Member` into the guild's member repository and each `User` into the top-level user repository. When a guild's cached member count reaches its `member_count`, it is removed from `$largeSent`. When `$largeSent` is empty, `ready()` fires.

### Step 5: `ready()`

Guarded by `$emittedInit` — runs at most once. Initializes the voice manager if the class exists. Emits `init` (the primary ready event). Emits deprecated `ready` with a warning. Drains `$unparsedPackets` — dispatch events that arrived before init are processed here.

## Root repositories

Root repositories are not properties of `Discord` itself. They live on the `Client` part (`src/Discord/Parts/User/Client.php`), which defines `$repositories`:

- `guilds` → `GuildRepository`
- `users` → `UserRepository`
- `private_channels` → `PrivateChannelRepository`
- `emojis` → `EmojiRepository`
- `sounds` → `SoundRepository`
- `sticker_packs` → `StickerPackRepository`
- `lobbies` → `LobbyRepository`

`Discord::__get()` proxies all unknown property accesses to `$this->client`, so `$discord->guilds` resolves to `$this->client->guilds`. A small allowlist (`loop`, `options`, `logger`, `http`, `application_commands`) is intercepted before delegation.

These repositories are long-lived for the entire process lifetime. They are the system of record for cached Discord state.

## Factory and dependency wiring

`Factory` is created once in the constructor: `$this->factory = new Factory($this)`. It holds a reference back to the `Discord` instance and provides `part()` and `repository()` methods for typed construction.

The `Client` part is the first object the factory creates: `$this->client = $this->factory->part(Client::class, [])`. After that, all part and repository creation flows through this single factory instance.

Callers access the factory via `$discord->getFactory()` or the convenience `$discord->factory($class, $data, $created)` method. Do not create ad-hoc factory instances elsewhere — the system assumes one factory tied to one client.

## Cache configuration

The `cacheConfig` property is an array keyed by repository class names. `getCacheConfig($repository_class)` looks up the config for a specific repository class, falling back to `AbstractRepository::class` as the default key.

Default behavior: `null` config means `LegacyCacheWrapper` is used (in-memory `WeakMap`-backed cache). External cache backends (`React\Cache\CacheInterface`, `Psr\SimpleCache\CacheInterface`) are wrapped in `CacheConfig` and logged as experimental.

Per-repository cache configs can be set by passing an array keyed by repository class names in the `cache` option. This allows different repositories to use different cache backends.

## Logging and lifecycle flags

### Lifecycle flags

| Property | Type | Meaning |
| --- | --- | --- |
| `$connected` | `bool` | WebSocket is currently open |
| `$closing` | `bool` | Client is intentionally shutting down |
| `$reconnecting` | `bool` | Client is in reconnect cycle |
| `$emittedInit` | `bool` | `init` event has been emitted at least once |
| `$reconnectCount` | `int` | Number of reconnections since boot |
| `$seq` | `int` | Current gateway sequence number |
| `$sessionId` | `string` | Current gateway session ID |

These flags are checked across connection, dispatch, and close handlers. Changing their semantics or lifecycle ordering can silently break reconnection or event delivery.

### Logger

If no logger is provided, `resolveOptions()` creates a Monolog instance writing to stdout at Debug level with `LineFormatter`. The logger is stored on `$this->logger` and exposed via `getLogger()` and `__get('logger')`.

## Dispatch routing

`processWsMessage()` decodes JSON payloads and routes by opcode. `OP_DISPATCH` goes to `handleDispatch()`, which checks `Handlers` for a registered event class. If found, it instantiates the handler, runs `handle()` as a coroutine, and emits the event name with resolved data. If not found, it checks a static map of internal handlers (`VOICE_STATE_UPDATE`, `VOICE_SERVER_UPDATE`, `RESUMED`, `READY`, `GUILD_MEMBERS_CHUNK`).

Before `$emittedInit` is true, non-critical dispatch events are queued in `$unparsedPackets` rather than processed immediately. Only `GUILD_CREATE` and `GUILD_DELETE` are allowed through during the ready flow.

## Smells

Stop if you see:

- bootstrap logic added to `run()` instead of `__construct()`
- a second `Factory` instance created anywhere
- option validation scattered outside `resolveOptions()`
- intent bitmask manipulation after options are resolved
- `$emittedInit` checked or set from outside `Discord.php`
- critical events (`GUILD_CREATE`, `GUILD_DELETE`, `READY`, `GUILD_MEMBERS_CHUNK`) removed without understanding the ready flow
- synchronous blocking in production code paths (acceptable only in tests)
- web-framework concepts (request/response, middleware, controllers) in `Discord.php`
- reconnect logic that does not respect `Op::getCriticalCloseCodes()`
- cache config manipulation after construction
- root repositories created outside the `Client` part

## Checklist before commit

- `resolveOptions()` handles any new option with proper type, default, and normalization
- `__construct()` wiring order preserved — options first, then HTTP, then factory, then client, then connect
- `run()` remains a one-liner
- lifecycle flags (`$connected`, `$closing`, `$reconnecting`, `$emittedInit`) not repurposed
- ready flow sequence (guild backfill → chunking → init) not broken
- critical events not silently disabled
- `connectWs()` → `handleWsConnection()` → `handleHello()` → `identify()` chain intact
- heartbeat timer and ACK guard logic preserved
- `$unparsedPackets` drain in `ready()` still works
- reconnect path (`handleWsClose()` → delay → `connectWs()`) handles critical vs non-critical close codes
- tests/docs updated if public behavior changed

## Bottom line

`Discord.php` is the single eager orchestrator for a long-running CLI process. It resolves options once, wires dependencies once, connects to the gateway eagerly, and starts the loop on demand. Keep it centered on that job — do not turn it into a service locator, request handler, or lazy-boot framework.

---

Source: https://www.openparable.com/skill/development/runtime-bootstrap-keeper (OpenParable). Cite the canonical URL above.
