@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/reaction-collector.ts

@@ -0,0 +1,499 @@
+/**
+ * Reaction collector: Buffering, filters and terminal cleanup for reaction events.
+ * Invariant: The collector owns its queue, snapshots and scheduled work, and completion releases its client registration.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { ClientLogger } from "./logging.js"
+import { messageIds, primaryError, type FailureReporter } from "./failures.js"
+import * as Cause from "effect/Cause"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import type * as Fiber from "effect/Fiber"
+import type { ConnectionState, OperationOptions } from "#sdk/client"
+import {
+    CollectorError,
+    type CollectorFailure,
+    type ReactionCollectorOptions,
+    type CollectorRegistrationError,
+    type ReactionCollectorResult,
+} from "#sdk/collectors"
+import { ClientClosedError, ConfigurationError } from "#sdk/errors"
+import type { Message, MessageCore, MessageReference } from "#sdk/messages"
+import type { MessageReaction, MessageReactionBatch, ReactionEmojiInput } from "#sdk/reactions"
+import type { ClientOwner } from "./client.js"
+import { snapshotReference } from "./message.js"
+import { record } from "./decode/primitives.js"
+import { readCaller, readInput, suspendMarked, thrownCause } from "./defects.js"
+import { resolveReactionEmoji } from "./reactions.js"
+import { discardInvalidCallbackReturn } from "./invalid-callback-return.js"
+import { collectorBudgetMessage } from "./collector.js"
+import { unsupportedKeyHint } from "./suggest.js"
+import type { LogicalScheduler, LogicalTimer } from "./logical-scheduler.js"
+
+type Settings = Required<Omit<ReactionCollectorOptions, "filter" | "emoji" | "guildId" | "idleMs">> &
+    Pick<ReactionCollectorOptions, "filter" | "guildId"> & {
+        readonly emoji?: Exclude<ReturnType<typeof resolveReactionEmoji>, undefined>
+        readonly idleMs: number | undefined
+    } & OperationOptions
+
+const maximumGuildId = "18446744073709551615"
+
+function guildId(value: unknown): value is string {
+    return (
+        typeof value === "string" &&
+        /^[1-9][0-9]{0,19}$/.test(value) &&
+        (value.length < maximumGuildId.length || value <= maximumGuildId)
+    )
+}
+
+function settings(options: unknown, defaultApi: boolean): Settings | ConfigurationError {
+    const input = options === undefined ? {} : options
+    if (!record(input)) return new ConfigurationError("collectorOptions", "Collector options must be an object")
+    const result = {
+        maxReactions: 1,
+        maxBytes: 4_194_304,
+        timeoutMs: 30_000,
+        idleMs: undefined as number | undefined,
+        maxPendingMessages: 256,
+        maxPendingBytes: 4_194_304,
+    }
+    const supported = [
+        ...Object.keys(result),
+        "guildId",
+        "filter",
+        "emoji",
+        "onReaction",
+        ...(defaultApi ? ["signal"] : []),
+    ]
+    const unsupported = Object.keys(input).find((key) => !supported.includes(key))
+    if (unsupported !== undefined)
+        return new ConfigurationError(
+            "collectorOptions",
+            `Unsupported collector option ${JSON.stringify(unsupported)}`,
+            {
+                hint: unsupportedKeyHint(unsupported, supported),
+            },
+        )
+    for (const key of Object.keys(result) as (keyof typeof result)[]) {
+        const value = input[key]
+        if (value === undefined) continue
+        if (
+            typeof value !== "number" ||
+            !Number.isSafeInteger(value) ||
+            value <= 0 ||
+            ((key === "timeoutMs" || key === "idleMs") && value > 2_147_483_647)
+        )
+            return new ConfigurationError(key, collectorBudgetMessage(key))
+        result[key] = value
+    }
+    if (input.filter !== undefined && typeof input.filter !== "function")
+        return new ConfigurationError("filter", "Collector filter must be a function")
+    if (input.guildId !== undefined && !guildId(input.guildId))
+        return new ConfigurationError("guildId", "Guild ID must be a positive uint64 decimal string")
+    const emojiInput = input.emoji as ReactionEmojiInput | undefined
+    const emoji = emojiInput === undefined ? undefined : resolveReactionEmoji(emojiInput)
+    if (emojiInput !== undefined && emoji === undefined)
+        return new ConfigurationError(
+            "emoji",
+            "Collector emoji must be Unicode, custom emoji markup or an emoji identity",
+        )
+    if (input.onReaction !== undefined && typeof input.onReaction !== "function")
+        return new ConfigurationError("onReaction", 'The collector option "onReaction" must be a function')
+    const signal = input.signal
+    if (
+        signal !== undefined &&
+        (!record(signal) ||
+            typeof signal.aborted !== "boolean" ||
+            typeof signal.addEventListener !== "function" ||
+            typeof signal.removeEventListener !== "function")
+    )
+        return new ConfigurationError("signal", "Collector signal must be an AbortSignal")
+    return {
+        ...result,
+        ...(input.guildId === undefined ? {} : { guildId: input.guildId }),
+        ...(emoji === undefined ? {} : { emoji }),
+        ...(input.filter === undefined ? {} : { filter: input.filter as (message: MessageReaction) => boolean }),
+        ...(signal === undefined ? {} : { signal: signal as unknown as NonNullable<OperationOptions["signal"]> }),
+    }
+}
+
+/** One collection owns its queue, snapshots and scheduled work. Completion releases its client registration */
+export class ReactionCollector {
+    readonly closed = Deferred.makeUnsafe<ReactionCollectorResult, CollectorFailure>()
+    #active = true
+    #pending: { message: MessageReaction | MessageReactionBatch; bytes: number }[] = []
+    #pendingBytes = 0
+    #messages: MessageReaction[] = []
+    #bytes = 0
+    #timer: LogicalTimer | undefined
+    #drain: ReturnType<typeof setImmediate> | undefined
+    #release: (() => void) | undefined
+    #settings: Settings | undefined
+    readonly #deadline: number
+    #idleDeadline: number
+    #current: MessageReaction[] = []
+    #currentIndex = 0
+    #busy = false
+    #next = Deferred.makeUnsafe<MessageReaction>()
+    #worker: Fiber.Fiber<void> | undefined
+    #outcome: Exit.Exit<ReactionCollectorResult, CollectorFailure> | undefined
+    #untrack: (() => void) | undefined
+    #logger: ClientLogger | undefined
+    #failures: FailureReporter | undefined
+
+    owns(fiberId: number) {
+        return this.#worker?.id === fiberId
+    }
+
+    run<E, R, M extends MessageCore>(
+        owner: ClientOwner<M>,
+        handler: (reaction: MessageReaction) => Effect.Effect<unknown, E, R>,
+    ) {
+        const collector = this
+        return Effect.gen(function* () {
+            collector.#untrack = owner.trackReactionCollector(collector)
+            collector.#logger = owner.logging
+            collector.#failures = owner.failures
+            const work = Effect.gen(function* () {
+                while (collector.#active) {
+                    const reaction = yield* Deferred.await(collector.#next)
+                    collector.#next = Deferred.makeUnsafe<MessageReaction>()
+                    yield* Effect.scoped(Effect.suspend(() => handler(reaction))).pipe(
+                        Effect.catchCause((cause) =>
+                            !collector.#active && Cause.hasDies(cause)
+                                ? Effect.failCause(
+                                      Cause.fromReasons<never>(
+                                          cause.reasons.filter((reason) => reason._tag !== "Fail"),
+                                      ),
+                                  )
+                                : Effect.sync(() =>
+                                      collector.fail(collector.#handlerFailure(cause), { cause, item: reaction }),
+                                  ),
+                        ),
+                    )
+                    collector.#busy = false
+                    if (!collector.#active) return
+                    if (collector.#expired()) return
+                    if (collector.#messages.length === collector.#settings!.maxReactions) collector.#succeed("limit")
+                    else collector.#scheduleDrain()
+                }
+            }).pipe(
+                Effect.interruptible,
+                Effect.onExit((exit) => Effect.sync(() => collector.#workerFinished(exit))),
+            )
+            collector.#worker = yield* Effect.forkIn(work, owner.scope, { uninterruptible: true })
+        })
+    }
+
+    #handlerFailure(cause: Cause.Cause<unknown>) {
+        return new CollectorError("handler", null, null, { cause: primaryError(cause) })
+    }
+
+    #workerFinished(exit: Exit.Exit<void, unknown>) {
+        if (this.#active) this.stop()
+        this.#worker = undefined
+        if (Exit.isFailure(exit) && Cause.hasDies(exit.cause)) {
+            const cause = Cause.fromReasons<CollectorFailure>(
+                exit.cause.reasons.filter((reason) => reason._tag === "Die"),
+            )
+            this.#outcome = Exit.failCause(
+                Cause.combine(
+                    this.#outcome && Exit.isFailure(this.#outcome) ? this.#outcome.cause : Cause.empty,
+                    cause,
+                ),
+            )
+        }
+        this.#complete()
+    }
+
+    constructor(
+        settings: Settings,
+        private readonly logical: LogicalScheduler,
+        /** Also accept single removals, which reach filter and onReaction like additions. Not a public option */
+        private readonly removals = false,
+    ) {
+        this.#settings = settings
+        const now = this.#now()
+        this.#deadline = now + settings.timeoutMs
+        this.#idleDeadline = settings.idleMs === undefined ? Infinity : now + settings.idleMs
+    }
+
+    #now() {
+        return this.logical.now()
+    }
+
+    start<M extends MessageCore>(owner: ClientOwner<M>, target: MessageReference) {
+        // Filter failures need these even when no callback worker runs
+        this.#logger = owner.logging
+        this.#failures = owner.failures
+        const settings = this.#settings!
+        const signal = settings.signal
+        const abort = () => this.#finish(Exit.interrupt())
+        const shardId = settings.guildId === undefined ? undefined : owner.shardIdForGuild(settings.guildId)
+        const intake = owner.events.listenReactions(target, this.#offer.bind(this), shardId, this.removals)
+        let state: (() => void) | undefined
+        this.#release = () => {
+            intake()
+            state?.()
+            readCaller(() => signal?.removeEventListener("abort", abort))
+        }
+        try {
+            state =
+                settings.guildId === undefined
+                    ? owner.subscribe(this.#stateChanged.bind(this))
+                    : owner.subscribeGateway(settings.guildId, this.#stateChanged.bind(this))
+            if (!this.#active) state()
+            readCaller(() => signal?.addEventListener("abort", abort, { once: true }))
+            if (readCaller(() => signal?.aborted)) abort()
+            if (this.#active) this.#scheduleDeadline()
+        } catch (error) {
+            this.#finish(Exit.failCause(thrownCause(error)))
+            throw error
+        }
+    }
+
+    #stateChanged(state: ConnectionState) {
+        if (state === "Recovering" || state === "Disconnected") this.fail(new CollectorError("connectionLost"))
+        else if (state === "Closing" || state === "Closed") this.fail(new ClientClosedError())
+    }
+
+    #scheduleDeadline() {
+        this.#timer = this.logical.set(
+            () => {
+                this.#timer = undefined
+                this.#guard(() => {
+                    if (!this.#expired()) this.#scheduleDeadline()
+                })
+            },
+            Math.max(1, Math.ceil(Math.min(this.#deadline, this.#idleDeadline) - this.#now())),
+            "reaction collector",
+        )
+    }
+
+    #expired() {
+        if (this.#now() < Math.min(this.#deadline, this.#idleDeadline)) return false
+        this.#succeed(this.#idleDeadline < this.#deadline ? "idle" : "timeout")
+        return true
+    }
+
+    #guard(work: () => void) {
+        if (!this.#active) return
+        try {
+            work()
+        } catch (error) {
+            this.#finish(Exit.die(error))
+        }
+    }
+
+    #offer(message: MessageReaction | MessageReactionBatch, bytes: number) {
+        if (!this.#active) return
+        if (this.#busy && this.#messages.length === this.#settings!.maxReactions) {
+            // The collector is full and finishing its last callback, so later events cannot join the result
+            this.#logger?.drop(
+                { event: "collector" },
+                {
+                    level: "debug",
+                    category: "collectors",
+                    code: "collectors.dropped",
+                    message: "A full reaction collector ignored an event while its last callback finished",
+                },
+            )
+            return
+        }
+        try {
+            if (this.#expired()) return
+            const settings = this.#settings!
+            if (settings.guildId !== undefined && message.guildId !== undefined && message.guildId !== settings.guildId)
+                return
+            const limit =
+                this.#pending.length >= settings.maxPendingMessages
+                    ? "maxPendingMessages"
+                    : bytes > settings.maxPendingBytes - this.#pendingBytes
+                      ? "maxPendingBytes"
+                      : undefined
+            if (limit) return this.fail(new CollectorError("overflow", limit, settings[limit]))
+            this.#pending.push({ message, bytes })
+            this.#pendingBytes += bytes
+            this.#scheduleDrain()
+        } catch (error) {
+            this.#finish(Exit.die(error))
+        }
+    }
+
+    #scheduleDrain() {
+        if (this.#busy || !this.#active) return
+        // Do not create this callback inside offer: Retained error stacks can keep its closure and the offered payload alive
+        this.#drain ??= setImmediate(() => {
+            this.#drain = undefined
+            this.#guard(() => this.#consume())
+        })
+    }
+
+    #consume() {
+        while (this.#active && (this.#current.length || this.#pending.length)) {
+            if (this.#expired()) return
+            if (!this.#current.length) {
+                const { message: payload, bytes } = this.#pending.shift()!
+                this.#pendingBytes -= bytes
+                this.#current =
+                    "reactions" in payload
+                        ? payload.reactions.map((item) =>
+                              Object.freeze({
+                                  id: payload.id,
+                                  channelId: payload.channelId,
+                                  ...(payload.guildId === undefined ? {} : { guildId: payload.guildId }),
+                                  ...item,
+                              }),
+                          )
+                        : [payload]
+            }
+            while (this.#current.length) {
+                const message = this.#current[this.#currentIndex++]!
+                if (this.#currentIndex === this.#current.length) {
+                    this.#current = []
+                    this.#currentIndex = 0
+                }
+                if (this.#expired()) return
+                const emoji = this.#settings!.emoji
+                if (
+                    emoji !== undefined &&
+                    (typeof emoji === "string"
+                        ? message.emoji.id !== undefined || message.emoji.name !== emoji
+                        : message.emoji.id !== emoji.id)
+                )
+                    continue
+                let accepted: unknown
+                try {
+                    accepted = this.#settings!.filter ? this.#settings!.filter(message) : true
+                } catch (error) {
+                    return this.fail(new CollectorError("filter", null, null, { cause: error }), { item: message })
+                }
+                discardInvalidCallbackReturn(accepted)
+                if (!this.#active) return
+                if (this.#expired()) return
+                if (typeof accepted !== "boolean") return this.fail(new CollectorError("filter"), { item: message })
+                if (!accepted) continue
+                const size = Buffer.byteLength(JSON.stringify(message))
+                if (this.#expired()) return
+                if (size > this.#settings!.maxBytes - this.#bytes)
+                    return this.fail(new CollectorError("overflow", "maxBytes", this.#settings!.maxBytes))
+                this.#messages.push(message)
+                this.#bytes += size
+                // Renewal only moves the quiet deadline later. The existing timer rechecks it before completing
+                if (this.#settings!.idleMs !== undefined) this.#idleDeadline = this.#now() + this.#settings!.idleMs
+                if (this.#worker) {
+                    this.#busy = true
+                    Deferred.doneUnsafe(this.#next, Effect.succeed(message))
+                    return
+                }
+                if (this.#messages.length === this.#settings!.maxReactions) return this.#succeed("limit")
+            }
+        }
+    }
+
+    stop() {
+        this.#succeed("stopped")
+    }
+    /** End the collector with a failure. A failed application filter or callback is also reported with its original
+     * value through the client's onError, or logged at Error, while waitForClose still returns the CollectorError
+     */
+    fail(error: CollectorFailure, source?: { readonly cause?: Cause.Cause<unknown>; readonly item?: MessageReaction }) {
+        if (this.#active && error instanceof CollectorError && error.reason !== "connectionLost") {
+            if ((error.reason === "handler" || error.reason === "filter") && this.#failures) {
+                // The result keeps this error. Serializing its stack now releases the frames V8 captured with it, whose
+                // closures would otherwise keep the failed item and callbacks alive for as long as the result is held
+                void error.stack
+                this.#failures.report({
+                    kind: error.reason === "filter" ? "filter" : "collector",
+                    error: error.cause ?? error,
+                    cause: source?.cause,
+                    message: source?.item === undefined ? undefined : messageIds(source.item),
+                })
+            } else
+                this.#logger?.log({
+                    level: "warn",
+                    category: "collectors",
+                    code: "collectors.failed",
+                    message: `A reaction collector failed: ${error.message}`,
+                    fields: { reason: error.reason },
+                    error,
+                    origin: error.reason === "handler" || error.reason === "filter" ? "application" : "sdk",
+                })
+        }
+        this.#finish(Exit.fail(error))
+    }
+    #succeed(reason: ReactionCollectorResult["reason"]) {
+        if (this.#active)
+            this.#finish(Exit.succeed(Object.freeze({ reactions: Object.freeze(this.#messages), reason })))
+    }
+    #finish(outcome: Exit.Exit<ReactionCollectorResult, CollectorFailure>) {
+        if (!this.#active) return
+        this.#active = false
+        this.logical.clear(this.#timer)
+        if (this.#drain !== undefined) clearImmediate(this.#drain)
+        this.#timer = undefined
+        this.#drain = undefined
+        this.#pending = []
+        this.#current = []
+        this.#currentIndex = 0
+        this.#messages = []
+        this.#bytes = this.#pendingBytes = 0
+        this.#settings = undefined
+        const release = this.#release
+        this.#release = undefined
+        try {
+            release?.()
+        } catch (error) {
+            outcome = Exit.failCause(
+                Cause.combine(Exit.isFailure(outcome) ? outcome.cause : Cause.empty, thrownCause(error)),
+            )
+        }
+        this.#outcome = outcome
+        if (this.#worker) this.#worker.interruptUnsafe()
+        else this.#complete()
+    }
+    #complete() {
+        this.#untrack?.()
+        this.#untrack = undefined
+        this.#next = Deferred.makeUnsafe<MessageReaction>()
+        if (this.#outcome) Deferred.doneUnsafe(this.closed, this.#outcome)
+    }
+}
+
+export function collectReactions<E = never, R = never, M extends MessageCore = Message>(
+    owner: ClientOwner<M>,
+    target: MessageReference,
+    options?: ReactionCollectorOptions,
+    defaultApi = false,
+    handler?: (reaction: MessageReaction) => Effect.Effect<unknown, E, R>,
+    removals = false,
+): Effect.Effect<ReactionCollector, CollectorRegistrationError, R> {
+    return Effect.gen(function* () {
+        const message = yield* readInput(() => snapshotReference(target))
+        if (message === undefined)
+            return yield* Effect.fail(
+                new ConfigurationError("message", "Message reference must contain decimal id and channelId"),
+            )
+        const config = yield* readInput(() => settings(options, defaultApi))
+        if (config instanceof ConfigurationError) return yield* Effect.fail(config)
+        // Misuse is checked first. A closing client is a shutdown race, which the bindings return as a failed handle
+        if (owner.state === "Closing" || owner.state === "Closed") return yield* Effect.fail(new ClientClosedError())
+        if (yield* readInput(() => config.signal?.aborted)) return yield* Effect.interrupt
+        if (config.guildId === undefined) {
+            if (owner.state !== "Connected") return yield* Effect.fail(new CollectorError("notConnected"))
+        } else if (
+            owner.shardIdForGuild(config.guildId) === undefined ||
+            owner.gatewayState(config.guildId) !== "Connected"
+        )
+            return yield* Effect.fail(new CollectorError("notConnected"))
+        const collector = new ReactionCollector(config, owner.logical, removals)
+        if (handler) yield* collector.run(owner, handler)
+        // The caller signal methods are marked reads, so their throws are application faults
+        yield* suspendMarked(() => {
+            collector.start(owner, message)
+            return Effect.void
+        })
+        return collector
+    })
+}