@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/gateway/frames.ts

@@ -0,0 +1,176 @@
+/**
+ * Inbound gateway frame decoding: Text frames to payloads, and HELLO, dispatch-envelope and READY validation.
+ * Invariant: Each accepted message is decoded once and keeps its received byte length for downstream admission.
+ * Binary frames, invalid JSON and envelopes missing required fields are protocol failures that name the field.
+ * Size rule: The socket enforces maxGatewayMessageBytes before decoding text or parsing JSON, including fragmented
+ * messages. This compatibility ceiling stays separate from Fluxer's outbound command limits, replay retention,
+ * subscription byte accounting and actual heap usage. Local size and UTF-8 rejections are terminal protocol failures,
+ * never transient network failures replayed through automatic recovery. Public limits and failure behavior are documented on the
+ * default and native Client and on ConnectionError. Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { Opcode } from "../protocol/gateway.js"
+import type { SocketData } from "../transport/index.js"
+
+/** Preserve the selected transport's 100 MiB compatibility ceiling explicitly.
+ * Fluxer's outbound-command and replay-retention limits do not bound live inbound messages
+ */
+export const maxGatewayMessageBytes = 100 * 1024 * 1024
+
+/** Largest heartbeat interval a timer can represent */
+const maximumHeartbeatIntervalMs = 2_147_483_647
+
+/** Safe facts about a rejected frame, recorded in ConnectionError details */
+export interface FrameRejection {
+    readonly rejected: true
+    readonly detail: string
+    readonly opcode?: number
+    readonly dispatch?: string
+    readonly field?: string
+}
+
+/** One decoded frame with an integer opcode */
+export interface Frame {
+    readonly rejected: false
+    readonly op: number
+    /** The frame's d field, or undefined when it has none */
+    readonly body: unknown
+    /** The whole decoded frame, used only for unsafe payload logging */
+    readonly payload: Readonly<Record<string, unknown>>
+    /** Received UTF-8 byte length of the message */
+    readonly bytes: number
+}
+
+const rejection = (value: Omit<FrameRejection, "rejected">): FrameRejection => ({ rejected: true, ...value })
+
+/** Decode one received message into a frame, or reject it before any opcode handling */
+export function decodeFrame(data: SocketData, binary: boolean): Frame | FrameRejection {
+    if (binary) return rejection({ detail: "received a binary frame" })
+    const buffer =
+        typeof data === "string"
+            ? Buffer.from(data, "utf8")
+            : Buffer.isBuffer(data)
+              ? data
+              : Array.isArray(data)
+                ? Buffer.concat(data)
+                : data instanceof ArrayBuffer
+                  ? Buffer.from(data)
+                  : Buffer.from(
+                        (data as Uint8Array).buffer,
+                        (data as Uint8Array).byteOffset,
+                        (data as Uint8Array).byteLength,
+                    )
+    const bytes = buffer.byteLength
+    let payload: unknown
+    try {
+        payload = JSON.parse(buffer.toString("utf8"))
+    } catch {
+        // allow-silent: The returned rejection becomes a recorded protocol failure for the invalid JSON frame
+        return rejection({ detail: "received a frame that is not valid JSON" })
+    }
+    if (typeof payload !== "object" || payload === null || !("op" in payload) || !Number.isInteger(payload.op))
+        return rejection({ detail: "received a frame without an integer opcode", field: "op" })
+    return {
+        rejected: false,
+        op: payload.op as number,
+        body: "d" in payload ? payload.d : undefined,
+        payload: payload as Readonly<Record<string, unknown>>,
+        bytes,
+    }
+}
+
+/** Validate HELLO and return its heartbeat interval in milliseconds */
+export function readHello(body: unknown, receivedHello: boolean): number | FrameRejection {
+    if (
+        receivedHello ||
+        typeof body !== "object" ||
+        body === null ||
+        !("heartbeat_interval" in body) ||
+        typeof body.heartbeat_interval !== "number" ||
+        !Number.isSafeInteger(body.heartbeat_interval) ||
+        body.heartbeat_interval <= 0 ||
+        body.heartbeat_interval > maximumHeartbeatIntervalMs
+    )
+        return rejection({
+            detail: receivedHello ? "received a second HELLO" : "received an invalid HELLO",
+            opcode: Opcode.hello,
+            field: receivedHello ? "op" : "d.heartbeat_interval",
+        })
+    return body.heartbeat_interval
+}
+
+/** A dispatch frame's sequence and type */
+export interface DispatchEnvelope {
+    readonly rejected: false
+    readonly sequence: number
+    readonly type: string
+}
+
+/** Validate that a dispatch arrived after HELLO with a non-negative sequence and a string type */
+export function readDispatchEnvelope(
+    payload: Readonly<Record<string, unknown>>,
+    receivedHello: boolean,
+): DispatchEnvelope | FrameRejection {
+    const sequence = payload.s
+    const type = payload.t
+    if (
+        !receivedHello ||
+        !("s" in payload) ||
+        typeof sequence !== "number" ||
+        !Number.isSafeInteger(sequence) ||
+        sequence < 0 ||
+        !("t" in payload) ||
+        typeof type !== "string"
+    )
+        return rejection({
+            detail: !receivedHello
+                ? "received a dispatch before HELLO"
+                : "received a dispatch without a valid sequence and type",
+            opcode: Opcode.dispatch,
+            field: !receivedHello ? "op" : !("s" in payload) || typeof sequence !== "number" ? "s" : "t",
+        })
+    return { rejected: false, sequence, type }
+}
+
+/** Validate READY for a fresh session and return its session ID.
+ * READY is invalid when a session is already ready or resuming, or when it names a different shard than requested
+ */
+export function readReady(
+    body: unknown,
+    state: {
+        readonly receivedReady: boolean
+        readonly resuming: boolean
+        readonly shard: readonly [number, number] | undefined
+    },
+): string | FrameRejection {
+    const { receivedReady, resuming, shard } = state
+    const sessionId =
+        typeof body === "object" &&
+        body !== null &&
+        "session_id" in body &&
+        typeof body.session_id === "string" &&
+        body.session_id
+            ? body.session_id
+            : undefined
+    if (
+        receivedReady ||
+        resuming ||
+        sessionId === undefined ||
+        (shard !== undefined &&
+            (!("shard" in (body as object)) ||
+                !Array.isArray((body as { shard: unknown }).shard) ||
+                (body as { shard: unknown[] }).shard.length !== 2 ||
+                (body as { shard: unknown[] }).shard[0] !== shard[0] ||
+                (body as { shard: unknown[] }).shard[1] !== shard[1]))
+    )
+        return rejection({
+            detail: receivedReady
+                ? "received a second READY"
+                : resuming
+                  ? "received READY while resuming"
+                  : "received an invalid READY",
+            opcode: Opcode.dispatch,
+            dispatch: "READY",
+            field: sessionId === undefined ? "d.session_id" : "d.shard",
+        })
+    return sessionId
+}

package/src/internal/gateway/options.ts

@@ -0,0 +1,144 @@
+/**
+ * Gateway option validation: Malformed-dispatch policy and the Identify fields ignoredEvents, flags and presence.
+ * Invariant: Creation copies every value once, never sends an Identify Fluxer would close with 4002, and rejects an
+ * explicit ignored list that would leave an enabled cache stale or stop an SDK-owned request.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { ConfigurationError } from "#sdk/errors"
+import { InputValidationFailure } from "#sdk/input-validation"
+import { settingError } from "../client/configuration-fields.js"
+import { unsupportedKeyHint } from "../suggest.js"
+import { record } from "../decode/primitives.js"
+import { presenceInput, type FrozenPresence } from "../presence.js"
+import { IdentifyFlag, maxIgnoredEvents } from "../protocol/gateway.js"
+import { automaticNeeds, cacheNeeds, protectedDispatchTypes, type FilterCacheKind } from "./event-dispatches.js"
+
+/**
+ * Most UTF-8 bytes the encoded ignored_events array may take. Fluxer closes a client message above 4,096 bytes, and
+ * the rest of Identify (token, properties, shard and the largest presence) stays within the remaining 1,536 bytes
+ */
+const maxIgnoredEventsBytes = 2_560
+
+/** Validated gateway settings */
+export interface GatewayConfiguration {
+    readonly onMalformedDispatch: "skip" | "terminate"
+    /** Explicit upper-case deduplicated names, or auto for per-Identify derivation */
+    readonly ignoredEvents: readonly string[] | "auto"
+    /** Identify flags bitfield, zero when none is set */
+    readonly flags: number
+    /** Initial presence intent, seeded into the presence owner */
+    readonly presence: FrozenPresence | undefined
+    /** Dispatch types automatic filtering keeps for the enabled cache categories and SDK owners */
+    readonly automaticNeeds: ReadonlySet<string>
+}
+
+const dispatchName = /^[A-Za-z0-9_]{1,64}$/
+
+/** Validate and copy the gateway option against the enabled cache categories */
+export function gatewayConfiguration(
+    value: unknown,
+    cacheKinds: readonly FilterCacheKind[],
+): GatewayConfiguration | ConfigurationError {
+    const allowed = ["onMalformedDispatch", "ignoredEvents", "flags", "presence"]
+    if (value !== undefined && !record(value))
+        return new ConfigurationError("gateway", "Gateway settings must be an object")
+    const unsupported = value === undefined ? undefined : Object.keys(value).find((key) => !allowed.includes(key))
+    if (unsupported !== undefined)
+        return new ConfigurationError("gateway", `Unsupported gateway setting ${JSON.stringify(unsupported)}`, {
+            hint: unsupportedKeyHint(unsupported, allowed, "settings"),
+        })
+    const settings = value ?? {}
+    const onMalformedDispatch = settings.onMalformedDispatch ?? "skip"
+    if (onMalformedDispatch !== "skip" && onMalformedDispatch !== "terminate")
+        return new ConfigurationError(
+            "onMalformedDispatch",
+            'The option "gateway.onMalformedDispatch" must be "skip" or "terminate"',
+        )
+    const ignoredEvents = ignoredList(settings.ignoredEvents, cacheKinds)
+    if (ignoredEvents instanceof ConfigurationError) return ignoredEvents
+    const flags = flagBits(settings.flags)
+    if (flags instanceof ConfigurationError) return flags
+    let presence: FrozenPresence | undefined
+    const presenceSetting = settings.presence
+    if (presenceSetting !== undefined) {
+        const checked = presenceInput(presenceSetting)
+        if (checked instanceof InputValidationFailure)
+            return settingError("presence", `The option "gateway.presence" is invalid: ${checked.detail.explanation}`, {
+                hint: 'Pass a PresenceInput such as { status: "online" }',
+            })
+        presence = checked
+    }
+    return Object.freeze({
+        onMalformedDispatch,
+        ignoredEvents,
+        flags,
+        presence,
+        automaticNeeds: automaticNeeds(cacheKinds),
+    })
+}
+
+function ignoredList(
+    value: unknown,
+    cacheKinds: readonly FilterCacheKind[],
+): readonly string[] | "auto" | ConfigurationError {
+    if (value === undefined) return Object.freeze([])
+    if (value === "auto") return "auto"
+    if (!Array.isArray(value))
+        return settingError(
+            "ignoredEvents",
+            'The option "gateway.ignoredEvents" must be "auto" or an array of dispatch names',
+        )
+    if (value.length > maxIgnoredEvents)
+        return settingError("ignoredEvents", 'The option "gateway.ignoredEvents" can list at most 256 dispatch names')
+    const names = new Set<string>()
+    for (const name of Array.from(value)) {
+        if (typeof name !== "string" || !dispatchName.test(name))
+            return settingError(
+                "ignoredEvents",
+                'The option "gateway.ignoredEvents" must list dispatch names of 1 to 64 letters, digits and underscores, such as TYPING_START',
+            )
+        names.add(name.toUpperCase())
+    }
+    const needed = cacheNeeds(cacheKinds)
+    for (const name of names) {
+        if (protectedDispatchTypes.has(name))
+            return settingError(
+                "ignoredEvents",
+                `The SDK needs ${name} dispatches to run the connection or to answer its own gateway requests, so gateway.ignoredEvents cannot include ${name}`,
+                {
+                    hint: `Remove ${name} from gateway.ignoredEvents`,
+                },
+            )
+        if (needed.has(name))
+            return settingError(
+                "ignoredEvents",
+                `${name} dispatches keep enabled caches current (${cacheKinds
+                    .filter((kind) => cacheNeeds([kind]).has(name))
+                    .map((kind) => `cache.${kind}`)
+                    .join(", ")}), so gateway.ignoredEvents cannot include ${name}`,
+                {
+                    hint: `Remove ${name} from gateway.ignoredEvents, or turn off the cache that uses it in the cache option`,
+                },
+            )
+    }
+    const list = Object.freeze([...names])
+    if (Buffer.byteLength(JSON.stringify(list)) > maxIgnoredEventsBytes)
+        return settingError(
+            "ignoredEvents",
+            `The option "gateway.ignoredEvents" must encode to at most 2,560 bytes of JSON, so the session start message fits Fluxer's 4,096-byte limit`,
+        )
+    return list
+}
+
+function flagBits(value: unknown): number | ConfigurationError {
+    if (value === undefined) return 0
+    if (!record(value) || Object.keys(value).some((key) => key !== "debounceMessageReactions"))
+        return settingError(
+            "flags",
+            'The option "gateway.flags" must contain only the boolean debounceMessageReactions',
+        )
+    const debounce = value.debounceMessageReactions
+    if (debounce !== undefined && typeof debounce !== "boolean")
+        return settingError("flags", 'The option "gateway.flags.debounceMessageReactions" must be true or false')
+    return debounce === true ? IdentifyFlag.debounceMessageReactions : 0
+}