@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/testing/gateway.ts

@@ -0,0 +1,305 @@
+/**
+ * In-memory protocol-v1 gateway for test clients: Fake sockets shaped like ws sockets, the scripted handshake and dispatch delivery.
+ * Invariant: Every socket opens without I/O, receives HELLO after the SDK attaches its listeners, gets READY for Identify
+ * (with the requested shard pair) and RESUMED for Resume, and has every heartbeat acknowledged. Dispatches carry
+ * increasing sequence numbers per shard session. No timers run and closing the gateway closes every socket.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { EventEmitter } from "node:events"
+import { ClientClosedError, ConfigurationError } from "#sdk/errors"
+import type { WebSocketLike, WebSocketOptions } from "#sdk/rest"
+import { CloseCode, Opcode } from "../protocol/gateway.js"
+import { SocketState } from "../transport/index.js"
+import type { WireUser } from "./fixtures.js"
+import type { TestDisconnectOptions, TestEmitOptions, TestGatewayCommand } from "./types.js"
+
+interface ShardSession {
+    socket: FakeSocket | undefined
+    ready: boolean
+    sessionId: string
+    sequence: number
+    /** Identify filtering belongs to the retained session and survives Resume */
+    ignoredEvents: ReadonlySet<string>
+}
+
+/** A ws-compatible socket whose server side is the test gateway */
+class FakeSocket extends EventEmitter {
+    readyState: number = SocketState.open
+    shardId: number | null = null
+
+    constructor(private readonly gateway: TestGateway) {
+        super()
+    }
+
+    send(data: string, callback: (error?: Error) => void) {
+        if (this.readyState !== SocketState.open) {
+            queueMicrotask(() => callback(new Error("The test gateway socket is not open")))
+            return
+        }
+        queueMicrotask(() => callback())
+        this.gateway.receive(this, data)
+    }
+
+    close(code: number) {
+        this.#close(code)
+    }
+
+    terminate() {
+        this.#close(CloseCode.abnormal)
+    }
+
+    /** Deliver a frame synchronously, as one received text message */
+    deliver(frame: unknown) {
+        if (this.readyState !== SocketState.open) return
+        this.emit("message", Buffer.from(JSON.stringify(frame)), false)
+    }
+
+    /** Close from either side. The close event follows in a microtask, exactly once */
+    #close(code: number) {
+        if (this.readyState === SocketState.closing || this.readyState === SocketState.closed) return
+        this.readyState = SocketState.closing
+        this.gateway.detach(this)
+        queueMicrotask(() => {
+            this.readyState = SocketState.closed
+            this.emit("close", code, Buffer.alloc(0))
+        })
+    }
+
+    /** End the connection from the server side */
+    serverClose(code: number) {
+        this.#close(code)
+    }
+}
+
+/** Redact the token in Identify and Resume data before recording */
+function recordedData(op: number, d: unknown): unknown {
+    if ((op !== Opcode.identify && op !== Opcode.resume) || typeof d !== "object" || d === null) return d
+    return { ...d, token: "[redacted]" }
+}
+
+/**
+ * Fluxer exempts direct, here and everyone mentions from ignored MESSAGE_CREATE dispatches. Role-only mentions,
+ * own messages and DMs are not exempt in a production session. Pinned to session_dispatch:ignored_event_must_dispatch
+ * and session_passive:is_user_mentioned at fluxerapp/fluxer commit 841fb7af4174fc8fc025307776e87e7dba51a669
+ */
+function mentionedMessage(type: string, payload: unknown, userId: string): boolean {
+    if (type !== "MESSAGE_CREATE" || typeof payload !== "object" || payload === null) return false
+    const message = payload as { mention_everyone?: unknown; mention_here?: unknown; mentions?: unknown }
+    return (
+        message.mention_everyone === true ||
+        message.mention_here === true ||
+        (Array.isArray(message.mentions) &&
+            message.mentions.some(
+                (user: unknown) =>
+                    typeof user === "object" && user !== null && (user as { id?: unknown }).id === userId,
+            ))
+    )
+}
+
+/** Fluxer's shard for a guild ID under a shard count */
+function guildShard(guildId: string, totalShards: number): number {
+    return Number((BigInt(guildId) >> 22n) % BigInt(totalShards))
+}
+
+/** The scripted gateway shared by one test client's shards */
+export class TestGateway {
+    readonly #sockets = new Set<FakeSocket>()
+    readonly #shards = new Map<number, ShardSession>()
+    readonly #commands: TestGatewayCommand[] = []
+    #totalShards = 1
+    #sessions = 0
+    #closed = false
+
+    constructor(
+        private readonly settings: {
+            readonly user: WireUser
+            readonly heartbeatIntervalMs: number
+        },
+    ) {}
+
+    /** The socket factory passed to the client's transport option */
+    readonly webSocket = (_url: string, _options: WebSocketOptions): WebSocketLike => {
+        const socket = new FakeSocket(this)
+        if (this.#closed) {
+            // A socket requested after cleanup closes like a refused connection instead of reaching any network
+            socket.serverClose(CloseCode.abnormal)
+            return socket
+        }
+        this.#sockets.add(socket)
+        queueMicrotask(() =>
+            socket.deliver({ op: Opcode.hello, d: { heartbeat_interval: this.settings.heartbeatIntervalMs } }),
+        )
+        return socket
+    }
+
+    /** Commands received so far, in order */
+    commands(): readonly TestGatewayCommand[] {
+        return Object.freeze([...this.#commands])
+    }
+
+    /** Handle one command a client socket sent */
+    receive(socket: FakeSocket, data: string) {
+        let frame: { op?: unknown; d?: unknown }
+        try {
+            frame = JSON.parse(data) as { op?: unknown; d?: unknown }
+        } catch {
+            // allow-silent: A non-JSON command is an SDK defect the real gateway would answer with close code 4002
+            socket.serverClose(CloseCode.decodeError)
+            return
+        }
+        const op = typeof frame.op === "number" ? frame.op : -1
+        if (op === Opcode.identify) this.#identify(socket, frame.d)
+        else if (op === Opcode.resume) this.#resume(socket, frame.d)
+        this.#commands.push(Object.freeze({ shardId: socket.shardId, op, d: recordedData(op, frame.d) }))
+        if (op === Opcode.heartbeat) queueMicrotask(() => socket.deliver({ op: Opcode.heartbeatAck }))
+    }
+
+    #identify(socket: FakeSocket, d: unknown) {
+        const shard = (d as { shard?: unknown } | null)?.shard
+        const pair =
+            Array.isArray(shard) && shard.length === 2 && shard.every((value) => Number.isSafeInteger(value))
+                ? (shard as [number, number])
+                : undefined
+        const shardId = pair?.[0] ?? 0
+        this.#totalShards = pair?.[1] ?? 1
+        socket.shardId = shardId
+        const session: ShardSession = {
+            socket,
+            ready: false,
+            sessionId: `fixture-session-${shardId}-${++this.#sessions}`,
+            sequence: 1,
+            ignoredEvents: new Set((d as { ignored_events?: readonly string[] } | null)?.ignored_events ?? []),
+        }
+        this.#shards.set(shardId, session)
+        queueMicrotask(() => {
+            if (session.socket !== socket) return
+            // Ready first: The client can finish connecting and emit synchronously inside this delivery
+            session.ready = true
+            socket.deliver({
+                op: Opcode.dispatch,
+                s: 1,
+                t: "READY",
+                d: {
+                    session_id: session.sessionId,
+                    version: 1,
+                    user: this.settings.user,
+                    // No guilds list: Tests add communities later, so the connected record reports no count and no invite warning
+                    private_channels: [],
+                    presences: [],
+                    users: [],
+                    ...(pair ? { shard: pair } : {}),
+                },
+            })
+        })
+    }
+
+    #resume(socket: FakeSocket, d: unknown) {
+        const sessionId = (d as { session_id?: unknown } | null)?.session_id
+        const entry = [...this.#shards].find(([, session]) => session.sessionId === sessionId)
+        if (!entry) {
+            queueMicrotask(() => socket.deliver({ op: Opcode.invalidSession, d: false }))
+            return
+        }
+        const [shardId, session] = entry
+        socket.shardId = shardId
+        session.socket = socket
+        session.ready = false
+        queueMicrotask(() => {
+            if (session.socket !== socket) return
+            session.ready = true
+            socket.deliver({ op: Opcode.dispatch, s: ++session.sequence, t: "RESUMED", d: {} })
+        })
+    }
+
+    /** Forget a closing socket */
+    detach(socket: FakeSocket) {
+        this.#sockets.delete(socket)
+        for (const session of this.#shards.values())
+            if (session.socket === socket) {
+                session.socket = undefined
+                session.ready = false
+            }
+    }
+
+    #connected(shardId: number, operation: string): ShardSession & { socket: FakeSocket } {
+        if (this.#closed) throw new ClientClosedError()
+        const session = this.#shards.get(shardId)
+        if (!session?.ready || session.socket?.readyState !== SocketState.open)
+            throw new ConfigurationError(
+                "shardIds",
+                `Test gateway shard ${shardId} is not connected, so ${operation} cannot deliver to it`,
+                {
+                    hint: "Await ready() before emitting, and pass a shardId this client owns",
+                },
+            )
+        return session as ShardSession & { socket: FakeSocket }
+    }
+
+    /** Deliver one dispatch synchronously to a connected shard with the next sequence number */
+    emit(type: unknown, payload: unknown, options: TestEmitOptions | undefined) {
+        if (typeof type !== "string" || !/^[A-Z0-9_]+$/.test(type))
+            throw new ConfigurationError(
+                "event",
+                "Emitted dispatch types must be upper-case Fluxer dispatch names, such as MESSAGE_CREATE",
+            )
+        if (type === "READY" || type === "RESUMED")
+            throw new ConfigurationError("event", `The test gateway sends ${type} itself during the handshake`, {
+                hint: "Await ready() to connect, or use disconnect() to exercise a resume",
+            })
+        if (options !== undefined && (typeof options !== "object" || options === null))
+            throw new ConfigurationError("event", "Emit options must be an object")
+        const requested = options?.shardId
+        if (requested !== undefined && (!Number.isSafeInteger(requested) || requested < 0))
+            throw new ConfigurationError("shardIds", "Emit shardId must be a non-negative integer")
+        const guildId = (payload as { guild_id?: unknown } | null)?.guild_id
+        const shardId =
+            requested ??
+            (typeof guildId === "string" && /^[0-9]+$/.test(guildId) ? guildShard(guildId, this.#totalShards) : 0)
+        let text: string | undefined
+        try {
+            text = JSON.stringify(payload)
+        } catch (cause) {
+            throw new ConfigurationError("event", "Emitted payloads must be JSON-serializable wire data", { cause })
+        }
+        const session = this.#connected(shardId, `emit(${JSON.stringify(type)})`)
+        // MANY is generated from ADD after its ignored-event gate and bypasses filtering of the generated name
+        // (session_dispatch:flush_reaction_buffer and session_dispatch_voice:dispatch_reaction_add_many at the pinned commit)
+        const filteredType = type === "MESSAGE_REACTION_ADD_MANY" ? "MESSAGE_REACTION_ADD" : type
+        if (session.ignoredEvents.has(filteredType) && !mentionedMessage(type, payload, this.settings.user.id))
+            throw new ConfigurationError("event", `Fluxer would not send ${type} to this test gateway session`, {
+                hint: `Register the event handler before ready() when gateway.ignoredEvents is "auto", or remove ${filteredType} from the explicit gateway.ignoredEvents list (use [] to disable suppression). Create a new test client to apply these changes, since Resume keeps the session's filtering`,
+            })
+        session.sequence += 1
+        const frame = {
+            op: Opcode.dispatch,
+            s: session.sequence,
+            t: type,
+            ...(text === undefined ? {} : { d: payload }),
+        }
+        session.socket.deliver(frame)
+    }
+
+    /** Close one shard's current connection from the server side with a close code */
+    disconnect(options: TestDisconnectOptions | undefined) {
+        if (options !== undefined && (typeof options !== "object" || options === null))
+            throw new ConfigurationError("connection", "Disconnect options must be an object")
+        const shardId = options?.shardId ?? 0
+        const code = options?.code ?? CloseCode.unknownError
+        if (!Number.isSafeInteger(shardId) || shardId < 0)
+            throw new ConfigurationError("shardIds", "Disconnect shardId must be a non-negative integer")
+        if (!Number.isSafeInteger(code) || code < 1000 || code > 4999)
+            throw new ConfigurationError(
+                "connection",
+                "Disconnect code must be a WebSocket close code from 1000 through 4999",
+            )
+        this.#connected(shardId, "disconnect").socket.serverClose(code)
+    }
+
+    /** Close every remaining socket and refuse later connections. Returns how many sockets were still open */
+    close(): number {
+        this.#closed = true
+        const open = [...this.#sockets]
+        for (const socket of open) socket.serverClose(CloseCode.goingAway)
+        return open.length
+    }
+}

package/src/internal/testing/harness.ts

@@ -0,0 +1,328 @@
+/**
+ * Test client harness shared by the default and native testing entry points: Option handling, log capture and the
+ * in-memory transport pair.
+ * Invariant: A test client reaches no network. Its options always route HTTP and WebSocket traffic through the fake
+ * transport, its log records reach logs() and any caller sinks at the caller's level, its unhandled failures reach
+ * failures() and the shutdown check at any level, and closing the harness closes every fake socket and refuses later
+ * requests. This module has no Effect imports, so default declarations stay free of Effect.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+// Real timers even when a test fakes the global ones, so idle can count quiet event loop turns
+import { clearTimeout, setTimeout } from "node:timers"
+import { ClientClosedError, ConfigurationError } from "#sdk/errors"
+import type { LogCategory, LogRecord, LoggingOptions, LogSink, LogThreshold } from "#sdk/logging"
+import type { TransportOptions } from "#sdk/rest"
+import type { ClientDiagnostics } from "#sdk/client"
+import type { LogCode } from "../code-catalogue.js"
+import { clientOptionKeys } from "../configuration.js"
+import { unsupportedKeyHint } from "../suggest.js"
+import { createFixtures, fixtureToken, type Fixtures, type WireMessage } from "./fixtures.js"
+import { TestGateway } from "./gateway.js"
+import { TestHttp } from "./http.js"
+import { UnhandledTestFailuresError } from "./errors.js"
+import type { TestSayOptions, TestSettings, TestWaitOptions } from "./types.js"
+import { timedWait, waitTimeout } from "./wait.js"
+
+const defaultHeartbeatIntervalMs = 41_250
+const levels: readonly LogThreshold[] = ["trace", "debug", "info", "warn", "error", "fatal", "silent"]
+/** Consecutive quiet event loop turns after which idle treats the client as settled */
+const idleTurns = 3
+
+/**
+ * The work in progress that idle waits for: The client's diagnostics, its scheduled task runs in progress and its
+ * handler invocations, including received events still waiting for a handler that has not started
+ */
+export interface TestClientWork {
+    readonly diagnostics: ClientDiagnostics
+    readonly runningTasks: number
+    readonly pendingHandlers: number
+}
+
+/**
+ * Codes the failure reporter logs at Error for a handler, command, callback, scheduled task or onError hook failure, or
+ * a subscription stopped by overflow. The reported value can be any error, such as the Fluxer rejection of a failed
+ * reply a handler returned, so these records count whatever the error's origin
+ */
+const reportedFailureCodes: ReadonlySet<LogCode> = new Set<LogCode>([
+    "events.handlerFailed",
+    "events.hookFailed",
+    "events.overflow",
+    "commands.failed",
+    "collectors.callbackFailed",
+    "collectors.filterFailed",
+    "cleanup.progressFailed",
+    "cache.policyFailed",
+    "lifecycle.observerFailed",
+    "lifecycle.taskFailed",
+])
+
+/**
+ * Whether a record reports a failure no application code handled: A failure the reporter logged at Error because no
+ * onError hook took it, or another application callback failure logged at Error or Fatal. Failures of the test's own
+ * response handlers are excluded, because they deliberately simulate network errors
+ */
+function unhandledFailure(record: LogRecord): boolean {
+    if (record.level !== "error" && record.level !== "fatal") return false
+    if (reportedFailureCodes.has(record.code as LogCode)) return true
+    return record.error?.origin === "application" && !record.code.startsWith("testing.")
+}
+
+/** Whether a record at this level and category passes the caller's thresholds, as the SDK logger decides */
+function passes(logging: LoggingOptions | undefined, level: LogRecord["level"], category: LogCategory): boolean {
+    const threshold = logging?.categories?.[category] ?? logging?.level ?? "info"
+    return levels.indexOf(level) >= levels.indexOf(threshold)
+}
+
+/** Test settings that test clients accept besides the client options */
+const testSettingKeys = ["user", "heartbeatIntervalMs"]
+
+/**
+ * Reject option keys that a test client does not accept, before any client exists. Transport and instance get their
+ * own explanation, because the test client owns them. Any other unknown key gets createClient's closest-name hint,
+ * listing the client keys a test client accepts, the test settings and extraKeys, such as the runBot keys of createTestBot
+ */
+export function checkTestOptionKeys(options: object, extraKeys: readonly string[] = []): void {
+    const { transport, instance } = options as { transport?: unknown; instance?: unknown }
+    if (transport !== undefined || instance !== undefined)
+        throw new ConfigurationError(
+            "configuration",
+            "Test clients own the transport and instance options, so neither may be supplied",
+            { hint: "Remove transport and instance. Test clients always use hosted Fluxer endpoints in memory" },
+        )
+    const supported = [
+        ...clientOptionKeys.filter((key) => key !== "transport" && key !== "instance"),
+        ...testSettingKeys,
+        ...extraKeys,
+    ]
+    const unsupported = Object.keys(options).find(
+        (key) => !supported.includes(key) && key !== "transport" && key !== "instance",
+    )
+    if (unsupported !== undefined)
+        throw new ConfigurationError("configuration", `Unsupported option ${JSON.stringify(unsupported)}`, {
+            hint: unsupportedKeyHint(unsupported, supported),
+        })
+}
+
+/** The in-memory transport, records and fixtures owned by one test client */
+export class TestHarness {
+    readonly fixtures: Fixtures = createFixtures()
+    readonly http: TestHttp
+    readonly gateway: TestGateway
+    readonly #records: LogRecord[] = []
+    /** Every Error and Fatal record of the client, captured before its logging thresholds and deduplication */
+    readonly #errors: LogRecord[] = []
+    /** Unhandled failure records that failures() returned or shutdown already reported */
+    readonly #observed = new WeakSet<LogRecord>()
+    /** Pending idle waits, failed with ClientClosedError when the harness closes */
+    readonly #idleWaits = new Set<(error: unknown) => void>()
+    readonly #callerSinks: readonly LogSink[]
+    readonly #logging: LoggingOptions | undefined
+    #closed = false
+
+    constructor(options: object) {
+        if (typeof options !== "object" || options === null)
+            throw new ConfigurationError("configuration", "Test client options must be an object")
+        checkTestOptionKeys(options)
+        const { user, heartbeatIntervalMs = defaultHeartbeatIntervalMs } = options as TestSettings
+        if (
+            !Number.isSafeInteger(heartbeatIntervalMs) ||
+            heartbeatIntervalMs < 1 ||
+            heartbeatIntervalMs > 2_147_483_647
+        )
+            throw new ConfigurationError(
+                "configuration",
+                "Test heartbeatIntervalMs must be an integer from 1 through 2,147,483,647",
+            )
+        if (user !== undefined && (typeof user !== "object" || user === null || typeof user.id !== "string"))
+            throw new ConfigurationError("configuration", "Test user must be a wire user object with a string id")
+        const logging = (options as { logging?: unknown }).logging
+        this.#logging = typeof logging === "object" && logging !== null ? (logging as LoggingOptions) : undefined
+        const sink = this.#logging?.sink
+        this.#callerSinks = typeof sink === "function" ? [sink] : Array.isArray(sink) ? (sink as LogSink[]) : []
+        const bot = user ?? this.fixtures.botUser()
+        this.http = new TestHttp((record) => this.#record(record), { fixtures: this.fixtures, author: bot })
+        this.gateway = new TestGateway({ user: bot, heartbeatIntervalMs })
+    }
+
+    /** Client options with the fake transport, a default token and log capture added to the caller's settings */
+    clientOptions<O extends object>(options: O): O & { readonly token: string; readonly transport: TransportOptions } {
+        const { user: _, heartbeatIntervalMs: __, ...client } = options as O & TestSettings
+        const logging = (client as { logging?: unknown }).logging
+        const capture: LogSink = (record) => {
+            this.#records.push(record)
+        }
+        const sink = (logging as { sink?: unknown } | undefined)?.sink
+        return {
+            ...client,
+            token: (options as TestSettings).token ?? fixtureToken,
+            transport: { fetch: this.http.fetch, webSocket: this.gateway.webSocket },
+            // Malformed logging settings pass through unchanged, so client creation reports them as usual
+            logging:
+                logging === undefined
+                    ? { sink: capture }
+                    : typeof logging !== "object" || logging === null
+                      ? logging
+                      : {
+                            ...logging,
+                            sink:
+                                sink === undefined
+                                    ? capture
+                                    : typeof sink === "function"
+                                      ? [sink, capture]
+                                      : Array.isArray(sink) && sink.length > 0
+                                        ? [...(sink as unknown[]), capture]
+                                        : sink,
+                        },
+        } as O & { readonly token: string; readonly transport: TransportOptions }
+    }
+
+    /** Log records captured so far, in order */
+    logs(): readonly LogRecord[] {
+        return Object.freeze([...this.#records])
+    }
+
+    /**
+     * Record an Error or Fatal record of the client before its thresholds and deduplication. Each entry point sets
+     * this as the client logger's errorTap, so a quiet logging level cannot hide a failure from failures() or shutdown
+     */
+    readonly captureError = (record: LogRecord) => {
+        this.#errors.push(record)
+    }
+
+    /** Unhandled failure records so far, in order. Returning them marks them as observed by the test */
+    failures(): readonly LogRecord[] {
+        const failures = this.#errors.filter(unhandledFailure)
+        for (const record of failures) this.#observed.add(record)
+        return Object.freeze(failures)
+    }
+
+    /** Throw UnhandledTestFailuresError for unhandled failures the test has not observed, then mark them observed */
+    checkFailures() {
+        const unobserved = this.#errors.filter((record) => unhandledFailure(record) && !this.#observed.has(record))
+        if (unobserved.length === 0) return
+        for (const record of unobserved) this.#observed.add(record)
+        throw new UnhandledTestFailuresError(unobserved)
+    }
+
+    /**
+     * Resolve once the client has no running handler, scheduled task run, REST request or unanswered test request and
+     * produced no new log record, request or gateway command for several event loop turns. A scheduled task waiting for
+     * its time does not count, so a test advances its clock to run it
+     */
+    idle(work: () => TestClientWork, options: TestWaitOptions | undefined, signal?: AbortSignal): Promise<void> {
+        const timeoutMs = waitTimeout(options)
+        if (this.#closed) return Promise.reject(new ClientClosedError())
+        const busy = () => {
+            const {
+                diagnostics: { events, rest, gatewayRequests },
+                runningTasks,
+                pendingHandlers,
+            } = work()
+            return (
+                events.activeHandlers +
+                    pendingHandlers +
+                    rest.activeRequests +
+                    rest.queuedRequests +
+                    gatewayRequests.activeRequests +
+                    runningTasks >
+                0
+            )
+        }
+        const activity = () =>
+            `${this.#records.length}:${this.http.requests().length}:${this.gateway.commands().length}`
+        return timedWait<void>("idle", timeoutMs, signal, (settle) => {
+            let quiet = 0
+            let stalled = 0
+            let last = activity()
+            let timer: ReturnType<typeof setTimeout> | undefined
+            // Set by a global setImmediate callback, which Effect fibers also run on. A turn in which it did not run
+            // proves nothing, because fake timers that replace setImmediate stop every fiber, so it is never counted as quiet
+            let turned = false
+            const turn = () => {
+                turned = true
+            }
+            const fail = (error: unknown) => settle({ error })
+            // A zero-delay timer passes a whole event loop turn, including the immediate callbacks Effect fibers run on
+            const check = () => {
+                const now = activity()
+                quiet = turned && now === last && this.http.inFlight === 0 && !busy() ? quiet + 1 : 0
+                stalled = turned ? 0 : stalled + 1
+                last = now
+                if (quiet >= idleTurns) return settle({ value: undefined })
+                if (stalled >= idleTurns)
+                    return fail(
+                        new ConfigurationError("configuration", "Test idle cannot settle while setImmediate is faked", {
+                            hint: 'The SDK runs on setImmediate. Leave it real, for example vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] })',
+                        }),
+                    )
+                turned = false
+                globalThis.setImmediate(turn)
+                timer = setTimeout(check, 0)
+            }
+            globalThis.setImmediate(turn)
+            timer = setTimeout(check, 0)
+            this.#idleWaits.add(fail)
+            return () => {
+                clearTimeout(timer)
+                this.#idleWaits.delete(fail)
+            }
+        })
+    }
+
+    /**
+     * Deliver a MESSAGE_CREATE from a human author, wait until the client settles as idle does, then return the
+     * messages the client sent meanwhile. Misuse and emitting before ready throw synchronously, as idle and emit do
+     */
+    say(
+        work: () => TestClientWork,
+        content: string,
+        options: TestSayOptions | undefined,
+        signal?: AbortSignal,
+    ): Promise<readonly WireMessage[]> {
+        if (typeof content !== "string")
+            throw new ConfigurationError("configuration", "Test say content must be a string")
+        waitTimeout(options)
+        const overrides = options?.message
+        if (
+            overrides !== undefined &&
+            (typeof overrides !== "object" || overrides === null || Array.isArray(overrides))
+        )
+            throw new ConfigurationError("configuration", "Test say message overrides must be an object of wire fields")
+        if (this.#closed) return Promise.reject(new ClientClosedError())
+        const before = this.http.requests().length
+        this.gateway.emit("MESSAGE_CREATE", this.fixtures.message({ ...overrides, content }), undefined)
+        return this.idle(work, options, signal).then(() => this.http.sentMessages(this.http.requests().slice(before)))
+    }
+
+    /** Record a test transport event in logs() and in caller sinks, at the caller's thresholds */
+    #record(input: Omit<LogRecord, "time">) {
+        if (!passes(this.#logging, input.level, input.category)) return
+        const record: LogRecord = Object.freeze({ time: new Date().toISOString(), ...input })
+        this.#records.push(record)
+        for (const sink of this.#callerSinks) {
+            try {
+                sink(record)
+            } catch (error) {
+                // A failing caller sink stays visible in the test's own output, as it would for SDK records
+                console.error("Fluxerly test log sink failed:", error)
+            }
+        }
+    }
+
+    /** Close the fake transport after the client shut down. Reports sockets the client left open */
+    close() {
+        if (this.#closed) return
+        this.#closed = true
+        this.http.close()
+        for (const fail of this.#idleWaits) fail(new ClientClosedError())
+        const open = this.gateway.close()
+        if (open > 0)
+            this.#record({
+                level: "warn",
+                category: "lifecycle",
+                code: "testing.socketsLeftOpen",
+                message: `The test client left ${open} gateway ${open === 1 ? "socket" : "sockets"} open after shutdown, so the test transport closed ${open === 1 ? "it" : "them"}`,
+                fields: { sockets: open },
+            })
+    }
+}