@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/cache.js

@@ -0,0 +1,318 @@
+/**
+ * Optional message cache: Retained message observations, in-flight request guards and connection-gap invalidation.
+ * Invariant: Fluxer is the source of truth. Intake updates stored data from REST responses and gateway events before subscribers
+ * see them, retained data and conflict metadata stay bounded, and pre-gap observations are cleared even after session resumption.
+ * A gap on a guild with a known shard invalidates only that shard's data, private-conversation data belongs to shard zero, and
+ * unknown ownership stays conservative, including channel-only in-flight reads, without an unbounded channel-to-guild index.
+ * A deleted thread parent removes the messages of every channel in its guild that the channel cache cannot place, because
+ * Fluxer deletes the parent's threads without thread deletion events and messages do not record their thread's parent.
+ * Pre-gap requests neither repopulate invalid snapshots nor evict healthy post-gap observations on late completion. A callback
+ * that throws or returns an invalid value is reported with kind cache and the message IDs, and neither retention nor reporting
+ * failure changes a successful REST result or event delivery. Every applied store, removal and whole-cache clear is recorded
+ * to the client's change hub after it is applied, a replacement counting as one store. Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { isDeepStrictEqual } from "node:util";
+import { retentionAge } from "./retention-age.js";
+import { ExpiryQueue, ExpiryTimer } from "./expiry-queue.js";
+/**
+ * Whether an overlapping response describes the same message state as the retained snapshot.
+ * Fluxer omits guild_id from message HTTP responses while gateway events include it, so a guild ID present on only
+ * one side is unknown context rather than a conflicting change
+ */
+function sameObservation(retained, incoming) {
+    if (isDeepStrictEqual(retained, incoming))
+        return true;
+    if ((retained.guildId === undefined) === (incoming.guildId === undefined))
+        return false;
+    const { guildId: _retainedGuild, ...retainedState } = retained;
+    const { guildId: _incomingGuild, ...incomingState } = incoming;
+    return isDeepStrictEqual(retainedState, incomingState);
+}
+/** A message's cache change key: Its channel and message IDs */
+const changeKey = (message) => `${message.channelId}:${message.id}`;
+export const cacheStats = () => ({ hits: 0, misses: 0, evictions: { capacity: 0, expiry: 0 } });
+/** A diagnostic copy of the totals, which keep counting after it is taken */
+export const readStats = (stats) => ({ ...stats, evictions: { ...stats.evictions } });
+/** One client's retained observations and bounded in-flight guards, never a server-state replica */
+export class MessageCache {
+    settings;
+    report;
+    now;
+    changes;
+    #entries = new Map();
+    #requests = new Set();
+    #bytes = 0;
+    #generation = 0;
+    #expiry = new ExpiryQueue((entry) => this.#entries.get(entry.message.id) === entry);
+    #timer;
+    #closed = false;
+    #stats = cacheStats();
+    #limits;
+    constructor(settings, report, now, logical, changes) {
+        this.settings = settings;
+        this.report = report;
+        this.now = now;
+        this.changes = changes;
+        this.#timer = new ExpiryTimer("message cache", now, () => {
+            this.#purge();
+            this.#schedule();
+        }, logical);
+        this.#limits = settings && Object.freeze({ maxEntries: settings.maxEntries, maxBytes: settings.maxBytes });
+    }
+    get generation() {
+        return this.#generation;
+    }
+    diagnostics() {
+        this.#purge();
+        this.#schedule();
+        return {
+            configured: this.#limits !== undefined,
+            retainedEntries: this.#entries.size,
+            accountedBytes: this.#bytes,
+            maxEntries: this.#limits?.maxEntries ?? null,
+            maxBytes: this.#limits?.maxBytes ?? null,
+            ...readStats(this.#stats),
+        };
+    }
+    entries(limit) {
+        this.#purge();
+        this.#schedule();
+        const entries = [];
+        for (const entry of this.#entries.values()) {
+            entries.push(entry.message);
+            if (entries.length === limit)
+                break;
+        }
+        return Object.freeze(entries);
+    }
+    /** Release only this client's retained snapshots and block reads that began before this point from refilling them */
+    clear() {
+        if (this.#closed)
+            return;
+        this.gap();
+    }
+    get(target) {
+        const entry = this.#peek(target);
+        if (!entry) {
+            this.#stats.misses++;
+            return undefined;
+        }
+        this.#stats.hits++;
+        this.#entries.delete(target.id);
+        this.#entries.set(target.id, entry);
+        return entry.message;
+    }
+    #peek(target) {
+        const entry = this.#entries.get(target.id);
+        if (!entry || entry.message.channelId !== target.channelId)
+            return undefined;
+        if (entry.expires !== null && entry.expires <= this.now()) {
+            this.#remove(target);
+            this.#stats.evictions.expiry++;
+            return undefined;
+        }
+        return entry;
+    }
+    /** Remove one retained message, reporting the deletion unless the caller replaces it. Returns whether one was removed */
+    #remove(target, notify = true) {
+        const entry = this.#entries.get(target.id);
+        if (entry?.message.channelId !== target.channelId)
+            return false;
+        this.#entries.delete(target.id);
+        this.#bytes -= entry.bytes;
+        if (notify && this.changes?.active)
+            this.changes.record("messages", "delete", changeKey(entry.message));
+        return true;
+    }
+    #invalidate(target, except) {
+        for (const request of this.#requests)
+            if (request !== except &&
+                request.channel === target.channelId &&
+                (request.id === undefined || request.id === target.id))
+                request.invalid = true;
+    }
+    begin(channel, id, mutation, generation) {
+        const request = { channel, id, mutation, generation, invalid: generation !== this.#generation };
+        for (const other of this.#requests) {
+            if (other.channel !== channel || (id !== undefined && other.id !== undefined && id !== other.id))
+                continue;
+            if (mutation)
+                other.invalid = true;
+            if (other.mutation)
+                request.invalid = true;
+        }
+        this.#requests.add(request);
+        return request;
+    }
+    end(request) {
+        this.#requests.delete(request);
+    }
+    complete(request, messages) {
+        if (this.#closed || request.generation !== this.#generation)
+            return;
+        // Admit a history page oldest first so its newest members survive tight capacity limits
+        for (let index = messages.length - 1; index >= 0; index--) {
+            const message = messages[index];
+            if (request.invalid) {
+                const entry = this.#peek(message);
+                if (entry && !sameObservation(entry.message, message)) {
+                    this.#remove(message);
+                    this.#invalidate(message, request);
+                }
+            }
+            else
+                this.observe(message, request);
+        }
+        this.#schedule();
+    }
+    observe(message, request) {
+        if (this.#closed || !this.settings)
+            return;
+        this.#invalidate(message, request);
+        const resolved = retentionAge(this.settings.maxAgeMs ?? null, message, "message cache", "message");
+        if ("error" in resolved) {
+            this.#remove(message);
+            this.report(resolved.error, message);
+            this.#schedule();
+            return;
+        }
+        if (this.#closed || !this.settings)
+            return;
+        const age = resolved.age;
+        const bytes = age === 0 ? 0 : Buffer.byteLength(JSON.stringify(message));
+        // A replacement reports one set, while an older copy that the new one cannot replace reports a delete
+        const replaced = this.#remove(message, false);
+        if (age !== 0 && bytes <= this.settings.maxBytes) {
+            this.#purge();
+            while (this.#entries.size >= this.settings.maxEntries || this.#bytes > this.settings.maxBytes - bytes) {
+                const oldest = this.#entries.values().next().value;
+                this.#remove(oldest.message);
+                this.#stats.evictions.capacity++;
+            }
+            const entry = { message, bytes, expires: age === null ? null : this.now() + age };
+            this.#entries.set(message.id, entry);
+            this.#bytes += bytes;
+            if (entry.expires !== null)
+                this.#expiry.push(entry);
+            if (this.changes?.active)
+                this.changes.record("messages", "set", changeKey(message));
+        }
+        else if (replaced && this.changes?.active)
+            this.changes.record("messages", "delete", changeKey(message));
+        this.#schedule();
+    }
+    delete(target, except) {
+        if (this.#closed)
+            return;
+        this.#invalidate(target, except);
+        this.#remove(target);
+        this.#schedule();
+    }
+    /** Remove one message by ID when its channel is unknown, and block reads already in flight from restoring it */
+    deleteId(id) {
+        if (this.#closed)
+            return;
+        this.#generation++;
+        for (const request of this.#requests)
+            if (request.id === undefined || request.id === id)
+                request.invalid = true;
+        const entry = this.#entries.get(id);
+        if (entry)
+            this.#remove(entry.message);
+        this.#schedule();
+    }
+    deleteMany(channelId, ids) {
+        if (this.#closed)
+            return;
+        // Also block queued reads that have not registered their request guard yet
+        this.#generation++;
+        for (const id of ids)
+            this.delete({ channelId, id });
+    }
+    deleteAuthor(userId) {
+        if (this.#closed)
+            return;
+        this.#generation++;
+        for (const entry of this.#entries.values())
+            if (entry.message.author.id === userId)
+                this.delete(entry.message);
+    }
+    deleteChannel(channelId) {
+        if (this.#closed)
+            return;
+        // Queued REST calls have captured this generation but may not have registered a per-request guard yet
+        // Preserve other channel snapshots while conservatively blocking admission of pre-deletion responses
+        this.#generation++;
+        for (const request of this.#requests)
+            if (request.channel === channelId)
+                request.invalid = true;
+        for (const entry of this.#entries.values())
+            if (entry.message.channelId === channelId)
+                this.#remove(entry.message);
+        this.#schedule();
+    }
+    /**
+     * Remove the messages a deleted thread parent can have taken with its threads: Those in this guild, or without guild
+     * context, whose channel held does not place. Reads of such channels already in flight cannot restore them
+     */
+    deleteUnplaced(guildId, held) {
+        if (this.#closed)
+            return;
+        // Queued REST calls have captured this generation but may not have registered a per-request guard yet
+        this.#generation++;
+        for (const request of this.#requests)
+            if (!held(request.channel))
+                request.invalid = true;
+        for (const entry of this.#entries.values()) {
+            const message = entry.message;
+            if ((message.guildId === undefined || message.guildId === guildId) && !held(message.channelId))
+                this.#remove(message);
+        }
+        this.#schedule();
+    }
+    gap(affects) {
+        // Channel-only requests capture this generation before admission and retain it across retries
+        if (!affects || affects(undefined)) {
+            this.#generation++;
+            for (const request of this.#requests)
+                request.invalid = true;
+        }
+        if (!affects) {
+            const held = this.#entries.size > 0;
+            this.#entries.clear();
+            this.#bytes = 0;
+            this.#expiry.clear();
+            if (held && this.changes?.active)
+                this.changes.record("messages", "clear", null);
+        }
+        else {
+            for (const entry of this.#entries.values())
+                if (affects(entry.message.guildId))
+                    this.#remove(entry.message);
+        }
+        this.#schedule();
+    }
+    #purge() {
+        this.#expiry.purge(this.now(), (entry) => {
+            if (this.#remove(entry.message))
+                this.#stats.evictions.expiry++;
+        });
+    }
+    #schedule() {
+        if (this.#closed) {
+            this.#timer.cancel();
+            this.#expiry.clear();
+            return;
+        }
+        this.#expiry.compact(this.#entries.size);
+        this.#timer.set(this.#expiry.next());
+    }
+    close() {
+        this.#closed = true;
+        this.gap();
+        this.#requests.clear();
+        this.settings = undefined;
+        this.report = () => { };
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/internal/cache.js.map

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

package/dist/internal/calls.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Private-call and entrance-sound gateway decoders: CALL_CREATE, CALL_UPDATE, CALL_DELETE and ENTRANCE_SOUND_PLAY.
+ * Invariant: A decoder accepts the whole body or nothing, projects frozen camelCase copies, and drops the call voice-state
+ * routing fields region_id and server_id, which Fluxer requires clients to ignore. None of these events touch a cache.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { CallCreate, CallDelete, CallUpdate, EntranceSoundPlay } from "#sdk/events";
+/** CALL_UPDATE: The current ringing set, participants and region. Recipient and creation fields are not part of an update */
+export declare function decodeCallUpdate(value: unknown): CallUpdate | undefined;
+/** CALL_CREATE: Current call state plus the recipients and creation time that initial or recovered state carries */
+export declare function decodeCallCreate(value: unknown): CallCreate | undefined;
+/** CALL_DELETE: An absent unavailable flag means the call ended */
+export declare function decodeCallDelete(value: unknown): CallDelete | undefined;
+/** ENTRANCE_SOUND_PLAY: A null guild ID marks a private call */
+export declare function decodeEntranceSoundPlay(value: unknown): EntranceSoundPlay | undefined;
+//# sourceMappingURL=calls.d.ts.map

package/dist/internal/calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../../src/internal/calls.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAkB,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAwDxG,6HAA6H;AAC7H,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAGvE;AAED,oHAAoH;AACpH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAWvE;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAQvE;AAED,gEAAgE;AAChE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAwBrF"}

package/dist/internal/calls.js

@@ -0,0 +1,108 @@
+import { identifier, nonNegativeInteger, record } from "./decode/primitives.js";
+import { decodeVoiceState } from "./guilds.js";
+/** Stand-in server ID that lets the shared voice-state decoder validate a call entry, removed again after decoding */
+const callScope = "0";
+/**
+ * Decode one call participant with the shared voice-state rules. The entry's guild ID must be null or absent.
+ * A call has no community, so the member field is ignored rather than decoded against the stand-in server ID
+ */
+function decodeCallVoiceState(value) {
+    if (!record(value) || (value.guild_id !== undefined && value.guild_id !== null))
+        return undefined;
+    const state = decodeVoiceState({ ...value, guild_id: callScope, member: null });
+    if (!state)
+        return undefined;
+    const { guildId: _guildId, ...call } = state;
+    return Object.freeze(call);
+}
+/** A frozen copy of an array of decimal IDs, or undefined when any entry is not one */
+function identifiers(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const ids = [];
+    for (const item of value) {
+        if (!identifier(item))
+            return undefined;
+        ids.push(item);
+    }
+    return Object.freeze(ids);
+}
+function decodeCallState(value) {
+    if (!record(value) ||
+        !identifier(value.channel_id) ||
+        !identifier(value.message_id) ||
+        (value.region !== null && typeof value.region !== "string") ||
+        !Array.isArray(value.voice_states))
+        return undefined;
+    const ringingUserIds = identifiers(value.ringing);
+    if (!ringingUserIds)
+        return undefined;
+    const voiceStates = [];
+    for (const item of value.voice_states) {
+        const state = decodeCallVoiceState(item);
+        if (!state)
+            return undefined;
+        voiceStates.push(state);
+    }
+    return {
+        channelId: value.channel_id,
+        messageId: value.message_id,
+        region: value.region,
+        ringingUserIds,
+        voiceStates: Object.freeze(voiceStates),
+    };
+}
+/** CALL_UPDATE: The current ringing set, participants and region. Recipient and creation fields are not part of an update */
+export function decodeCallUpdate(value) {
+    const call = decodeCallState(value);
+    return call && Object.freeze(call);
+}
+/** CALL_CREATE: Current call state plus the recipients and creation time that initial or recovered state carries */
+export function decodeCallCreate(value) {
+    const call = decodeCallState(value);
+    if (!call || !record(value))
+        return undefined;
+    const recipientIds = value.recipients === undefined ? undefined : identifiers(value.recipients);
+    if (value.recipients !== undefined && !recipientIds)
+        return undefined;
+    if (value.created_at !== undefined && !nonNegativeInteger(value.created_at))
+        return undefined;
+    return Object.freeze({
+        ...call,
+        ...(recipientIds === undefined ? {} : { recipientIds }),
+        ...(typeof value.created_at === "number" ? { createdAtMs: value.created_at } : {}),
+    });
+}
+/** CALL_DELETE: An absent unavailable flag means the call ended */
+export function decodeCallDelete(value) {
+    if (!record(value) ||
+        !identifier(value.channel_id) ||
+        (value.unavailable !== undefined && typeof value.unavailable !== "boolean"))
+        return undefined;
+    return Object.freeze({ channelId: value.channel_id, unavailable: value.unavailable === true });
+}
+/** ENTRANCE_SOUND_PLAY: A null guild ID marks a private call */
+export function decodeEntranceSoundPlay(value) {
+    if (!record(value) ||
+        !identifier(value.user_id) ||
+        !identifier(value.channel_id) ||
+        (value.guild_id !== null && !identifier(value.guild_id)) ||
+        !identifier(value.sound_id) ||
+        typeof value.hash !== "string" ||
+        typeof value.url !== "string" ||
+        value.url.length === 0 ||
+        !nonNegativeInteger(value.duration_ms) ||
+        typeof value.content_type !== "string")
+        return undefined;
+    return Object.freeze({
+        userId: value.user_id,
+        channelId: value.channel_id,
+        guildId: value.guild_id,
+        soundId: value.sound_id,
+        hash: value.hash,
+        url: value.url,
+        durationMs: value.duration_ms,
+        contentType: value.content_type,
+    });
+}
+//# sourceMappingURL=calls.js.map

package/dist/internal/calls.js.map

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

package/dist/internal/channel-cache.d.ts

@@ -0,0 +1,69 @@
+import type { ResourceCacheSettings } from "#sdk/cache";
+import type { CacheDiagnostic } from "#sdk/client";
+import { type GuildChannel } from "#sdk/channels";
+import type { EventMap, EventName } from "#sdk/events";
+import type { LogicalScheduler } from "./logical-scheduler.js";
+import type { CacheChangeHub } from "./cache-changes.js";
+export type ChannelCacheRequest = {
+    readonly channelId?: string;
+    readonly guildId?: string;
+    readonly mutation?: boolean;
+    /** A complete, authoritative guild list that may reconcile absent channel snapshots */
+    readonly replace?: boolean;
+    /**
+     * Marks a mutation confined to the thread named by channelId, or to a new thread when channelId is absent. A thread
+     * has no descendants or sibling order, so the change affects no other channel snapshot
+     */
+    readonly thread?: boolean;
+};
+export type ChannelCacheGuard = ChannelCacheRequest & {
+    readonly generation: number;
+    invalid: boolean;
+    /** A scoped gateway gap made this read stale, so it must not evict a newer post-gap observation */
+    gapped: boolean;
+    success: boolean;
+};
+/** One client's bounded guild-channel observations and in-flight guards, never a guild inventory or permission authority */
+export declare class ChannelCache {
+    #private;
+    private readonly settings;
+    private readonly now;
+    readonly changes?: CacheChangeHub | undefined;
+    private readonly report;
+    constructor(settings: Required<ResourceCacheSettings>, now: () => number, logical?: LogicalScheduler, changes?: CacheChangeHub | undefined, report?: (error: unknown) => void);
+    get(channelId: string): GuildChannel | undefined;
+    /** Whether an unexpired observation of this channel is retained, without making it less likely to be removed */
+    holds(channelId: string): boolean;
+    diagnostics(): CacheDiagnostic;
+    entries(limit: number): readonly GuildChannel[];
+    /** Release all retained channels and invalidate requests that could otherwise reintroduce an earlier observation */
+    clear(): void;
+    /** Remove one channel and invalidate overlapping requests, including ID-only routes that could belong to it */
+    delete(channelId: string): void;
+    begin(request: ChannelCacheRequest): ChannelCacheGuard;
+    complete(guard: ChannelCacheGuard, result: unknown): void;
+    missing(guard: ChannelCacheGuard): void;
+    end(guard: ChannelCacheGuard, dispatched: boolean): void;
+    event(event: EventName, value: EventMap[EventName]): void;
+    /** Evict one thread, such as one whose cached membership of the bot is no longer current. An unknown guild matches any */
+    evictThread(threadId: string, guildId: string | undefined): void;
+    /**
+     * Evict the cached threads of the affected guilds once a shard resumed. Fluxer does not replay THREAD_LIST_SYNC,
+     * so a thread observed before the Resume completed may no longer be visible. Reads in flight for those guilds, and
+     * ID-only reads, which can name a thread, cannot store an answer that may predate the Resume
+     */
+    dropThreads(affects: (guildId: string | null | undefined) => boolean): void;
+    /**
+     * Apply a raw guild lifecycle body. GUILD_CREATE replaces the guild's channels and threads, decoding its threads one
+     * at a time, and the field paths of the threads it left out as malformed are returned for the caller to log
+     */
+    guildEvent(event: string, value: unknown): readonly string[];
+    gap(affects?: (guildId: string | null | undefined) => boolean): void;
+    /**
+     * Keep in-flight reads for the affected guilds from storing their responses after the gateway connection was lost,
+     * while retained channels stay. A successful Resume replays every missed dispatch, which keeps them current
+     */
+    pause(affects: (guildId: string | null | undefined) => boolean): void;
+    close(): void;
+}
+//# sourceMappingURL=channel-cache.d.ts.map

package/dist/internal/channel-cache.d.ts.map

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