tadpole/gateway/shard

One gateway connection, end to end: HELLO, heartbeats, identify or resume, close-code decisions, reconnect with backoff. The shard actor owns all protocol state — sequence, session id, heartbeat misses — so a transport can die without losing the session it will resume with. Decisions that do not need a socket are pure functions here, mirrored against the tables in tadpole/gateway. Stability: Growing.

Almost every bot meets this module through tadpole/bot. Come here directly to run a shard with your own event sink — a custom dispatcher, a test harness, a second consumer of lifecycle data.

When you reach for this

start gives back a subject; typed events flow to the subject you passed as events, and connection news to the lifecycle subject if you supplied one. Connection trouble is not a start failure: attempts retry with backoff and report through lifecycle instead.

ShardConfig, field by field

• token — the bot token, sent inside IDENTIFY and RESUME payloads.
• intents — the raw bitfield Discord expects in IDENTIFY. Build it with tadpole/intent and intent.to_int, not by hand.
• shard — #(shard_id, shard_count), Discord’s documented order. One shard this milestone: #(0, 1).
• url — the full gateway URL including version and encoding, e.g. wss://gateway.discord.gg/?v=10&encoding=json (bot.gleam’s constant). No default; the caller always names one. When READY names a resume_gateway_url, later resume reconnects dial that host instead, carrying this URL’s query parameters.
• lifecycle — Some(subject) to receive Lifecycle notices, None to run silent.

Lifecycle

• Connected — the websocket handshake succeeded; HELLO has not arrived, so identify/resume has not run.
• Disconnected(close_code, will_resume) — the connection closed. close_code is Discord’s code, or 1006 when the transport died without one. will_resume is the decision that follows.
• ConnectFailed(error) — one connect attempt failed; a retry is already scheduled. Expect this repeatedly during outages.

ShardMsg and the reconnect ladder

ShardMsg is the actor’s message type, public only because the subject’s type mentions it. Callers send Stop; every other variant (HeartbeatTick, Inbound, SocketClosed, TransportDown, ReconnectNow) is plumbing driven by timers and the transport. Stop closes the socket and stops the actor; it does not wait for Discord to acknowledge the close frame.

The close-code ladder, applied by next_action_on_close and tested against tadpole/gateway:

Heartbeat and zombie rules

HELLO carries the heartbeat interval — floored at 1s, and 45s if Discord’s HELLO is unreadable, so zombie detection keeps running. Each tick sends a HEARTBEAT carrying the last sequence number and re-arms itself; there is no separate timer process to supervise. Discord can also demand an immediate heartbeat (op 1, often around RESUME); the shard answers with the current sequence. A HEARTBEAT_ACK resets the miss counter; after gateway.max_missed_acks (3) missed ACKs the connection is a zombie and the shard reconnects fresh.

Reconnects wait gateway.backoff_ms(attempts): 1s, 2s, 4s, … capped at 60s, no jitter. HELLO resets the attempt counter.

Concurrency

One actor owns everything: session id, sequence, heartbeat counters, the connection, its timers. Nothing to lock.

• process.send to the shard, events, or lifecycle subject is safe from any process; sends are async and never block.
• The events subject can only be received by its owner — create it in the process that will read it.
• start blocks for at most one websocket handshake (~5s); after that everything is async.
• next_action_on_close and on_invalid_session are pure — safe to call anywhere, which is how tests pin the ladder.

Example

import gleam/erlang/process
import gleam/option.{Some}
import tadpole/gateway/shard
import tadpole/intent

// Illustrative — tadpole/bot wires exactly this.
pub fn run_shard(token: String) -> process.Subject(shard.ShardMsg) {
  let events = process.new_subject()
  let assert Ok(shard_subject) =
    shard.start(
      shard.ShardConfig(
        token: token,
        intents: intent.to_int(
          intent.new() |> intent.enable(intent.guild_messages),
        ),
        shard: #(0, 1),
        url: "wss://gateway.discord.gg/?v=10&encoding=json",
        lifecycle: None,
      ),
      events: events,
    )
  // Read `events` here; send shard.Stop to close.
  shard_subject
}

See also

• tadpole/gateway — the pure tables this actor applies
• tadpole/gateway/transport — the websocket under the actor
• tadpole/bot — the user-facing wiring of this module

pub type CloseAction {
  Resume
  IdentifyFresh
  GiveUp
}

pub type Lifecycle {
  Connected
  Disconnected(close_code: Int, will_resume: Bool)
  ConnectFailed(error: error.TadpoleError)
}

pub type ShardConfig {
  ShardConfig(
    token: String,
    intents: Int,
    shard: #(Int, Int),
    url: String,
    lifecycle: option.Option(process.Subject(Lifecycle)),
  )
}

pub type ShardMsg {
  HeartbeatTick
  Inbound(frame: frame.Frame)
  SocketClosed(close_code: Int)
  TransportDown
  ReconnectNow
  Stop
}

pub fn connect_url(
  config_url: String,
  resume_gateway_url: option.Option(String),
  resume_next: Bool,
) -> String

pub fn next_action_on_close(
  close_code: Int,
  has_session: Bool,
) -> CloseAction

pub fn on_invalid_session(resumable: Bool) -> CloseAction

pub fn start(
  config: ShardConfig,
  events events: process.Subject(events.Event),
) -> Result(process.Subject(ShardMsg), error.TadpoleError)