@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/gateway/frames.js

@@ -0,0 +1,121 @@
+/**
+ * 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";
+/** 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;
+const rejection = (value) => ({ rejected: true, ...value });
+/** Decode one received message into a frame, or reject it before any opcode handling */
+export function decodeFrame(data, binary) {
+    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.buffer, data.byteOffset, data.byteLength);
+    const bytes = buffer.byteLength;
+    let payload;
+    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,
+        body: "d" in payload ? payload.d : undefined,
+        payload: payload,
+        bytes,
+    };
+}
+/** Validate HELLO and return its heartbeat interval in milliseconds */
+export function readHello(body, receivedHello) {
+    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;
+}
+/** Validate that a dispatch arrived after HELLO with a non-negative sequence and a string type */
+export function readDispatchEnvelope(payload, receivedHello) {
+    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, state) {
+    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) ||
+                !Array.isArray(body.shard) ||
+                body.shard.length !== 2 ||
+                body.shard[0] !== shard[0] ||
+                body.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;
+}
+//# sourceMappingURL=frames.js.map

package/dist/internal/gateway/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../../src/internal/gateway/frames.ts"],"names":[],"mappings":"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"}

package/dist/internal/gateway/options.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 { type FrozenPresence } from "../presence.js";
+import { type FilterCacheKind } from "./event-dispatches.js";
+/** 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>;
+}
+/** Validate and copy the gateway option against the enabled cache categories */
+export declare function gatewayConfiguration(value: unknown, cacheKinds: readonly FilterCacheKind[]): GatewayConfiguration | ConfigurationError;
+//# sourceMappingURL=options.d.ts.map

package/dist/internal/gateway/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/internal/gateway/options.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAKhD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEnE,OAAO,EAAsD,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAQhH,iCAAiC;AACjC,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,WAAW,CAAA;IAClD,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAA;IAClD,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IAC7C,+FAA+F;IAC/F,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC/C;AAID,gFAAgF;AAChF,wBAAgB,oBAAoB,CAChC,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,SAAS,eAAe,EAAE,GACvC,oBAAoB,GAAG,kBAAkB,CAqC3C"}

package/dist/internal/gateway/options.js

@@ -0,0 +1,103 @@
+/**
+ * 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 } from "../presence.js";
+import { IdentifyFlag, maxIgnoredEvents } from "../protocol/gateway.js";
+import { automaticNeeds, cacheNeeds, protectedDispatchTypes } 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;
+const dispatchName = /^[A-Za-z0-9_]{1,64}$/;
+/** Validate and copy the gateway option against the enabled cache categories */
+export function gatewayConfiguration(value, cacheKinds) {
+    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;
+    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, cacheKinds) {
+    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();
+    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) {
+    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;
+}
+//# sourceMappingURL=options.js.map

package/dist/internal/gateway/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/internal/gateway/options.ts"],"names":[],"mappings":"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"}

package/dist/internal/gateway/session.d.ts

@@ -0,0 +1,104 @@
+/**
+ * One uncompressed protocol-v1 gateway session: Socket lifetime, HELLO and heartbeat, authentication, sequence
+ * tracking and the attempt outcome the client's recovery loop classifies.
+ * Invariant: Readiness requires authentication and READY or RESUMED, not an open socket. The session owns its socket
+ * for the calling scope and always awaits its closure, with bounded graceful closure, then forced termination, and
+ * immediate termination for a pending handshake. Implements
+ * [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import type { EventMap, EventName } from "#sdk/events";
+import type { MessageCore } from "#sdk/messages";
+import * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import { type ConnectionFailure } from "#sdk/errors";
+import type { ClientLogger } from "../logging.js";
+import type { MessageDecoder } from "../message-fields.js";
+import type { CountGatewayOwner } from "../counts.js";
+import type { MemberChunkOwner } from "../member-chunks.js";
+import type { PresenceGatewayOwner } from "../presence.js";
+import { type SocketFactory } from "../transport/index.js";
+import { type IdentifyFields, type SubmitFailure } from "./commands.js";
+/** Resumable session state, shared across attempts of one shard and mutated by the session that owns it */
+export interface Session {
+    id: string | undefined;
+    sequence: number | null;
+    /** Paced send history persists across Resume attempts and is cleared before a fresh Identify */
+    commandSentAt?: number[];
+}
+/** Why an attempt ended, for log records. The public failure keeps only reviewed facts */
+export type AttemptEnd = "closed" | "heartbeatTimeout" | "reconnectRequested" | "invalidSession" | "network" | "sendFailed" | "protocol" | "timeout";
+/** Retry metadata is internal, not a promise that arbitrary consumer actions are repeatable */
+export declare class AttemptFailure {
+    readonly failure: ConnectionFailure;
+    readonly retry: boolean;
+    readonly resetSession: boolean;
+    readonly end: AttemptEnd;
+    /** WebSocket close code when the attempt ended with a gateway closure */
+    readonly closeCode?: number | undefined;
+    readonly _tag = "AttemptFailure";
+    constructor(failure: ConnectionFailure, retry: boolean, resetSession?: boolean, end?: AttemptEnd, 
+    /** WebSocket close code when the attempt ended with a gateway closure */
+    closeCode?: number | undefined);
+}
+/** Classify a gateway close through the reviewed close-code table. Unlisted codes enter recovery */
+export declare function classifyClose(code: number, resuming: boolean): AttemptFailure;
+/** Logging and malformed-dispatch policy for one shard's gateway session */
+export interface GatewayObserver {
+    readonly logger: ClientLogger;
+    readonly shardId: number;
+    /** The skip policy drops a known dispatch that fails decoding, terminate ends the session as a protocol failure */
+    readonly onMalformedDispatch: "skip" | "terminate";
+    /** Invalidate cached observations that a skipped dispatch could have changed */
+    readonly invalidate: (type: string, body: unknown) => void;
+}
+/** Everything one gateway attempt needs. Callbacks run synchronously on the socket's event turn */
+export interface GatewaySessionOptions<M extends MessageCore> {
+    readonly messageDecoder: MessageDecoder<M>;
+    /** Complete gateway URL, including the protocol version and encoding query */
+    readonly url: string;
+    readonly token: Redacted.Redacted<string>;
+    /** Resumed when it holds an ID and sequence, and updated by READY and each dispatch sequence */
+    readonly session: Session;
+    /** Budget for HELLO, authentication and READY or RESUMED together */
+    readonly timeoutMs: number;
+    /** Called once when the session is ready, after request owners are attached */
+    readonly onReady: (mode: "identify" | "resume") => void;
+    /** Heartbeat round trip in milliseconds, or null when the session stops having a current measurement */
+    readonly onLatency: (milliseconds: number | null) => void;
+    /** Called when a ready session ends with a retryable failure */
+    readonly onRecovering: () => void;
+    /** Deliver one decoded event with the received byte length of its frame */
+    readonly onDispatch: <K extends EventName>(event: K, message: EventMap<M>[K], bytes: number) => void;
+    /**
+     * Observe every accepted dispatch before decoding, including READY, RESUMED and types without a table entry.
+     * Called after envelope, readiness and sequence validation, and before the dispatch updates caches or reaches
+     * decoded-event subscribers
+     */
+    readonly onRaw?: ((type: string, sequence: number, body: unknown, bytes: number) => void) | undefined;
+    /** Optional Identify fields, read each time this session sends Identify */
+    readonly identifyFields?: (() => IdentifyFields) | undefined;
+    /** Lend the paced gateway.send path to the client once ready, and withdraw it when the session ends */
+    readonly application?: {
+        readonly attach: (submit: (op: number, d: unknown, sent?: () => void) => Effect.Effect<void, SubmitFailure>) => void;
+        readonly detach: () => void;
+    } | undefined;
+    /** Guild and channel cache intake for guild lifecycle and expression dispatches, when a resource cache is enabled */
+    readonly onGuild?: ((event: string, value: unknown) => void) | undefined;
+    readonly presence?: PresenceGatewayOwner | undefined;
+    readonly counts?: CountGatewayOwner | undefined;
+    readonly memberChunks?: Pick<MemberChunkOwner, "attach" | "detach" | "receive" | "rateLimited"> | undefined;
+    /** Shard ID and count sent with Identify and required in READY, when sharding is configured */
+    readonly shard?: readonly [number, number] | undefined;
+    /** Pace a fresh Identify send. Resume is never paced */
+    readonly identify?: ((send: () => void) => Effect.Effect<void, AttemptFailure>) | undefined;
+    /** Invite URL base from discovery, defaulting to the hosted instance */
+    readonly inviteBase?: string | undefined;
+    readonly observer?: GatewayObserver | undefined;
+    /** Socket implementation, defaulting to the selected ws transport */
+    readonly sockets?: SocketFactory | undefined;
+    /** Whether an interrupted attempt will save its session for a later client */
+    readonly preserveSessionOnInterrupt?: (() => boolean) | undefined;
+}
+/** Run one session in the calling Effect scope. It fails with the AttemptFailure that ended it and never succeeds */
+export declare const runGatewaySession: <M extends MessageCore>(options: GatewaySessionOptions<M>) => Effect.Effect<never, AttemptFailure, never>;
+//# sourceMappingURL=session.d.ts.map

package/dist/internal/gateway/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/internal/gateway/session.ts"],"names":[],"mappings":"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"}