@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/expiry-queue.ts

@@ -0,0 +1,148 @@
+/**
+ * Expiry ordering shared by the caches: A lazy-deletion heap and a timer rescheduled only when the earliest deadline changes.
+ * Invariant: Expiry never scans every retained entry on write.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { LogicalScheduler, LogicalTimer } from "./logical-scheduler.js"
+
+/** An entry with a fixed expiry deadline in the owning cache's clock units */
+export interface Expiring {
+    readonly expires: number
+}
+
+/** What the heap keeps of one entry: Its deadline and a weak identity, so the heap never retains a snapshot */
+interface Ticket<E extends Expiring> {
+    readonly expires: number
+    readonly entry: WeakRef<E>
+}
+
+/** A lazy-deletion min-heap of cache entries ordered by expiry deadline.
+ * Replaced or removed entries leave their tickets in the heap until a ticket reaches the top or a compaction rebuilds
+ * it, so writes cost O(log n) instead of scanning every retained entry. A ticket holds its entry weakly, so a replaced
+ * or removed snapshot is released as soon as its cache drops it
+ */
+export class ExpiryQueue<E extends Expiring> {
+    #heap: Ticket<E>[] = []
+
+    constructor(private readonly live: (entry: E) => boolean) {}
+
+    get size() {
+        return this.#heap.length
+    }
+
+    push(entry: E) {
+        this.#push({ expires: entry.expires, entry: new WeakRef(entry) })
+    }
+
+    #push(ticket: Ticket<E>) {
+        const heap = this.#heap
+        heap.push(ticket)
+        let index = heap.length - 1
+        while (index > 0) {
+            const parent = (index - 1) >> 1
+            if (heap[parent]!.expires <= ticket.expires) break
+            heap[index] = heap[parent]!
+            index = parent
+        }
+        heap[index] = ticket
+    }
+
+    #pop(): Ticket<E> {
+        const heap = this.#heap
+        const top = heap[0]!
+        const last = heap.pop()!
+        if (heap.length) {
+            let index = 0
+            const length = heap.length
+            while (true) {
+                const left = index * 2 + 1
+                if (left >= length) break
+                const right = left + 1
+                const child = right < length && heap[right]!.expires < heap[left]!.expires ? right : left
+                if (heap[child]!.expires >= last.expires) break
+                heap[index] = heap[child]!
+                index = child
+            }
+            heap[index] = last
+        }
+        return top
+    }
+
+    /** The entry of a ticket while its cache still holds it, or undefined once it was replaced or removed */
+    #entry(ticket: Ticket<E>): E | undefined {
+        const entry = ticket.entry.deref()
+        return entry !== undefined && this.live(entry) ? entry : undefined
+    }
+
+    /** Remove every live entry whose deadline has passed, in deadline order, stopping at the first unexpired entry */
+    purge(now: number, remove: (entry: E) => void) {
+        while (this.#heap.length) {
+            const top = this.#heap[0]!
+            const entry = this.#entry(top)
+            if (entry === undefined) this.#pop()
+            else if (top.expires <= now) {
+                this.#pop()
+                remove(entry)
+            } else break
+        }
+    }
+
+    /** Earliest live deadline, or undefined when no live entry expires */
+    next(): number | undefined {
+        while (this.#heap.length && this.#entry(this.#heap[0]!) === undefined) this.#pop()
+        return this.#heap[0]?.expires
+    }
+
+    /** Rebuild from live entries when stale tickets dominate, bounding retained tickets to a multiple of live entries */
+    compact(liveEntries: number) {
+        if (this.#heap.length <= liveEntries * 2 + 64) return
+        const live = this.#heap.filter((ticket) => this.#entry(ticket) !== undefined)
+        this.#heap = []
+        for (const ticket of live) this.#push(ticket)
+    }
+
+    clear() {
+        this.#heap = []
+    }
+}
+
+/** One cache's expiry timer, rescheduled only when its earliest deadline changes */
+export class ExpiryTimer {
+    #timer: ReturnType<typeof setTimeout> | LogicalTimer | undefined
+    #deadline: number | undefined
+
+    constructor(
+        private readonly owner: string,
+        private readonly now: () => number,
+        private readonly callback: () => void,
+        private readonly logical?: LogicalScheduler,
+    ) {}
+
+    /** Arm the timer for deadline, or cancel it for undefined. An unchanged deadline keeps the existing timer */
+    set(deadline: number | undefined) {
+        if (deadline === this.#deadline && (deadline === undefined || this.#timer !== undefined)) return
+        this.cancel()
+        if (deadline === undefined) return
+        this.#deadline = deadline
+        const run = () => {
+            this.#timer = undefined
+            this.#deadline = undefined
+            this.callback()
+        }
+        const delay = Math.min(2_147_483_647, Math.max(1, Math.ceil(deadline - this.now())))
+        if (this.logical) this.#timer = this.logical.set(run, delay, this.owner)
+        else {
+            const timer = setTimeout(run, delay)
+            timer.unref()
+            this.#timer = timer
+        }
+    }
+
+    cancel() {
+        if (this.#timer !== undefined)
+            if (this.logical) this.logical.clear(this.#timer as LogicalTimer)
+            else clearTimeout(this.#timer as ReturnType<typeof setTimeout>)
+        this.#timer = undefined
+        this.#deadline = undefined
+    }
+}

package/src/internal/expressions.ts

@@ -0,0 +1,415 @@
+/**
+ * Emoji and sticker operations and gateway expression updates.
+ * Invariant: An expression update is a changed collection, never an initial list or cache refill, and it invalidates the cache first.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type {
+    GuildEmoji,
+    GuildSticker,
+    ExpressionMetadata,
+    ExpressionReference,
+    ExpressionBatch,
+    ExpressionDeleteOptions,
+    ExpressionSourceGuild,
+} from "#sdk/expressions"
+import type { ModerationOptions } from "#sdk/guilds"
+import type { GuildRequest } from "./guilds.js"
+import { identifier, record } from "./decode/primitives.js"
+import { auditSettings } from "./moderation.js"
+import { InputValidationFailure, inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+import { normalizedText as text } from "./field-text.js"
+
+export type ExpressionKind = "emojis" | "stickers"
+export type ExpressionResources = { emojis: GuildEmoji; stickers: GuildSticker }
+export type ExpressionUpdate<K extends ExpressionKind> = Readonly<{
+    guildId: string
+    items: readonly ExpressionResources[K][]
+}>
+
+function snapshotArray(value: unknown, maximum: number): readonly unknown[] | undefined {
+    if (!Array.isArray(value)) return undefined
+    const count = value.length
+    if (count > maximum) return undefined
+    // oxlint-disable-next-line unicorn/no-new-array -- preallocates the counted length once, and the loop below assigns every index
+    const items = new Array<unknown>(count)
+    for (let index = 0; index < count; index++) items[index] = value[index]
+    return Object.freeze(items)
+}
+
+function decodeExpression<K extends ExpressionKind>(
+    kind: K,
+    value: unknown,
+    guildId: string,
+): ExpressionResources[K] | undefined {
+    if (
+        !record(value) ||
+        !identifier(value.id) ||
+        typeof value.name !== "string" ||
+        typeof value.animated !== "boolean"
+    )
+        return undefined
+    const base = { guildId, id: value.id, name: value.name, animated: value.animated }
+    if (kind === "emojis") return Object.freeze(base) as ExpressionResources[K]
+    if (
+        typeof value.description !== "string" ||
+        !Array.isArray(value.tags) ||
+        value.tags.length > 10 ||
+        !value.tags.every((tag) => typeof tag === "string")
+    )
+        return undefined
+    return Object.freeze({
+        ...base,
+        description: value.description,
+        tags: Object.freeze([...value.tags]),
+    }) as ExpressionResources[K]
+}
+
+/** Decode a complete guild expression collection, or undefined when any item is malformed or repeated */
+export function expressionItems<K extends ExpressionKind>(kind: K, value: unknown, guildId: string) {
+    if (!Array.isArray(value)) return undefined
+    const result: ExpressionResources[K][] = []
+    const ids = new Set<string>()
+    for (const item of value) {
+        const decoded = decodeExpression(kind, item, guildId)
+        if (!decoded || ids.has(decoded.id)) return undefined
+        ids.add(decoded.id)
+        result.push(decoded)
+    }
+    return Object.freeze(result)
+}
+
+/** Projects a full provider expression-update collection without retaining wire-only fields */
+export function decodeExpressionUpdate<K extends ExpressionKind>(
+    kind: K,
+    value: unknown,
+): ExpressionUpdate<K> | undefined {
+    if (!record(value) || !identifier(value.guild_id)) return undefined
+    const items = expressionItems(kind, value[kind], value.guild_id)
+    return items && Object.freeze({ guildId: value.guild_id, items })
+}
+
+export function expressionList<K extends ExpressionKind>(
+    kind: K,
+    guildId: string,
+): GuildRequest<readonly ExpressionResources[K][]> | InputValidationFailure {
+    if (!identifier(guildId)) return inputValidationFailure("guildId", "format", "Guild IDs must be decimal strings")
+    return {
+        guildId,
+        bucket: `guild:${kind}`,
+        path: `/guilds/${guildId}/${kind}`,
+        method: "GET",
+        status: 200,
+        cache: { selection: { kind, guildId }, replace: true },
+        decode: (value) => expressionItems(kind, value, guildId),
+    }
+}
+
+export function expressionMetadata(
+    kind: ExpressionKind,
+    id: string,
+): GuildRequest<ExpressionMetadata> | InputValidationFailure {
+    if (!identifier(id))
+        return inputValidationFailure("expressionId", "format", "Expression IDs must be decimal strings")
+    return {
+        guildId: id,
+        bucket: `${kind}:metadata`,
+        path: `/${kind}/${id}/metadata`,
+        method: "GET",
+        status: 200,
+        decode: (value) => {
+            if (
+                !record(value) ||
+                !identifier(value.guild_id) ||
+                value.id !== id ||
+                typeof value.allow_cloning !== "boolean"
+            )
+                return undefined
+            const base = decodeExpression("emojis", value, value.guild_id)
+            return base && Object.freeze({ ...base, allowCloning: value.allow_cloning })
+        },
+    }
+}
+
+function expressionFields(kind: ExpressionKind, create: boolean): readonly string[] {
+    return ["name", ...(create ? ["image"] : []), ...(kind === "stickers" ? ["description", "tags"] : [])]
+}
+
+function encode(kind: ExpressionKind, value: unknown, create: boolean, prefix = "") {
+    const path = (field: string) => (prefix ? `${prefix}.${field}` : field)
+    if (!record(value)) return inputValidationFailure(prefix || "input", "type", "Expression input must be an object")
+    const accepted = expressionFields(kind, create)
+    const unsupported = unsupportedKeyFailure(
+        value,
+        accepted,
+        prefix || "input",
+        `the ${kind === "emojis" ? "emoji" : "sticker"} input`,
+    )
+    if (unsupported) return unsupported
+    if (kind === "emojis" && !(typeof value.name === "string" && /^[A-Za-z0-9_]{2,32}$/.test(value.name)))
+        return inputValidationFailure(
+            path("name"),
+            "format",
+            "Emoji name must contain 2 through 32 ASCII letters, digits, or underscores",
+        )
+    if (kind === "stickers" && !text(value.name, 2, 30))
+        return inputValidationFailure(
+            path("name"),
+            "length",
+            "Sticker name must contain 2 through 30 UTF-16 code units after Fluxer's normalization",
+        )
+    if (create) {
+        if (typeof value.image !== "string" || value.image.length > 699_150)
+            return inputValidationFailure(
+                path("image"),
+                "size",
+                "Expression image must be a base64 string no longer than 699,150 UTF-16 code units",
+            )
+        const raw = value.image.replace(/^data:image\/[a-zA-Z0-9.+-]+(?:;[^,;=\s]+=[^,;\s]*)*;base64,/, "")
+        if (
+            !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(raw) ||
+            !raw.length ||
+            Buffer.byteLength(raw, "base64") > 524_288
+        )
+            return inputValidationFailure(
+                path("image"),
+                "format",
+                "Expression image must be valid base64 no larger than 524,288 bytes",
+            )
+    }
+    let tags: readonly string[] | undefined
+    if (kind === "stickers") {
+        if (value.description !== undefined && value.description !== null && !text(value.description, 1, 500))
+            return inputValidationFailure(
+                path("description"),
+                "length",
+                "Sticker description must be null or contain 1 through 500 UTF-16 code units after Fluxer's normalization",
+            )
+        const rawTags = value.tags
+        const snapshot = rawTags === undefined ? undefined : snapshotArray(rawTags, 10)
+        if (rawTags !== undefined && (!snapshot || !snapshot.every((tag) => text(tag, 1, 30))))
+            return inputValidationFailure(
+                path("tags[]"),
+                "format",
+                "Sticker tags must contain at most ten entries of 1 through 30 UTF-16 code units after Fluxer's normalization",
+            )
+        tags = snapshot as readonly string[] | undefined
+    }
+    return {
+        name: value.name,
+        ...(create ? { image: value.image } : {}),
+        ...(kind === "stickers" ? { description: value.description ?? null, tags: tags ?? [] } : {}),
+    }
+}
+
+export function expressionCreate<K extends ExpressionKind>(
+    kind: K,
+    guildId: string,
+    input: unknown,
+    options?: ModerationOptions,
+): GuildRequest<ExpressionResources[K]> | InputValidationFailure {
+    const base = expressionList(kind, guildId)
+    const body = encode(kind, input, true)
+    const audit = auditSettings(options)
+    if (base instanceof InputValidationFailure) return base
+    if (body instanceof InputValidationFailure) return body
+    if (audit instanceof InputValidationFailure) return audit
+    return {
+        ...base,
+        ...audit,
+        method: "POST",
+        json: JSON.stringify(body),
+        cache: { selection: { kind, guildId }, mutation: true },
+        decode: (value) => decodeExpression(kind, value, guildId),
+    }
+}
+
+export function expressionClone<K extends ExpressionKind>(
+    kind: K,
+    guildId: string,
+    sourceId: string,
+    options?: ModerationOptions,
+): GuildRequest<ExpressionResources[K]> | InputValidationFailure {
+    const base = expressionList(kind, guildId)
+    const audit = auditSettings(options)
+    if (base instanceof InputValidationFailure) return base
+    if (!identifier(sourceId))
+        return inputValidationFailure("sourceId", "format", "Source expression IDs must be decimal strings")
+    if (audit instanceof InputValidationFailure) return audit
+    return {
+        ...base,
+        ...audit,
+        method: "POST",
+        path: `${base.path}/clone`,
+        json: JSON.stringify({ [kind === "emojis" ? "source_emoji_id" : "source_sticker_id"]: sourceId }),
+        cache: { selection: { kind, guildId }, mutation: true },
+        decode: (value) => decodeExpression(kind, value, guildId),
+    }
+}
+
+export function expressionBatch<K extends ExpressionKind>(
+    kind: K,
+    guildId: string,
+    inputs: unknown,
+    options?: ModerationOptions,
+): GuildRequest<ExpressionBatch<ExpressionResources[K]>> | InputValidationFailure {
+    const base = expressionList(kind, guildId)
+    const audit = auditSettings(options)
+    if (base instanceof InputValidationFailure) return base
+    if (audit instanceof InputValidationFailure) return audit
+    const itemsInput = snapshotArray(inputs, 50)
+    if (!itemsInput && !Array.isArray(inputs))
+        return inputValidationFailure("inputs", "type", "Expression batch input must be an array")
+    if (!itemsInput || itemsInput.length < 1)
+        return inputValidationFailure("inputs", "length", "Expression batch input must contain 1 through 50 entries")
+    const items = itemsInput.map((item) => encode(kind, item, true, "inputs[]"))
+    const count = itemsInput.length
+    const failed = items.find((item): item is InputValidationFailure => item instanceof InputValidationFailure)
+    if (failed) return failed
+    return {
+        ...base,
+        ...audit,
+        method: "POST",
+        path: `${base.path}/bulk`,
+        json: JSON.stringify({ [kind]: items }),
+        cache: { selection: { kind, guildId }, mutation: true, batch: true },
+        decode: (value) => {
+            if (!record(value) || !Array.isArray(value.failed)) return undefined
+            const success = expressionItems(kind, value.success, guildId)
+            if (
+                !success ||
+                value.failed.some(
+                    (item) => !record(item) || typeof item.name !== "string" || typeof item.error !== "string",
+                )
+            )
+                return undefined
+            if (success.length + value.failed.length !== count) return undefined
+            return Object.freeze({
+                success,
+                failed: Object.freeze(value.failed.map((item) => Object.freeze({ name: item.name as string }))),
+            })
+        },
+    }
+}
+
+export function expressionEdit<K extends ExpressionKind>(
+    kind: K,
+    target: ExpressionReference,
+    input: unknown,
+    options?: ModerationOptions,
+): GuildRequest<ExpressionResources[K]> | InputValidationFailure {
+    if (!record(target)) return inputValidationFailure("target", "type", "Expression targets must be objects")
+    if (!identifier(target.id))
+        return inputValidationFailure("target.id", "format", "Expression IDs must be decimal strings")
+    const { id, guildId } = target
+    const base = expressionList(kind, target.guildId)
+    if (kind === "stickers") {
+        if (
+            !record(input) ||
+            !Object.hasOwn(input, "name") ||
+            !Object.hasOwn(input, "description") ||
+            !Object.hasOwn(input, "tags")
+        )
+            return inputValidationFailure("input", "required", "Sticker edit requires name, description, and tags")
+        const unsupported = unsupportedKeyFailure(
+            input,
+            ["name", "description", "tags", "guildId", "id", "animated"],
+            "input",
+            "the sticker edit",
+        )
+        if (unsupported) return unsupported
+        if (
+            (input.id !== undefined && input.id !== id) ||
+            (input.guildId !== undefined && input.guildId !== guildId) ||
+            (input.animated !== undefined && typeof input.animated !== "boolean")
+        )
+            return inputValidationFailure(
+                "input",
+                "relationship",
+                "Sticker snapshot fields must match the selected target",
+            )
+        if (input.description === undefined || input.tags === undefined)
+            return inputValidationFailure("input", "required", "Sticker edit requires description and tags")
+        input = { name: input.name, description: input.description === "" ? null : input.description, tags: input.tags }
+    }
+    const body = encode(kind, input, false)
+    const audit = auditSettings(options)
+    if (base instanceof InputValidationFailure) return base
+    if (body instanceof InputValidationFailure) return body
+    if (audit instanceof InputValidationFailure) return audit
+    return {
+        ...base,
+        ...audit,
+        method: "PATCH",
+        path: `${base.path}/${target.id}`,
+        json: JSON.stringify(body),
+        cache: { selection: { kind, guildId: target.guildId, id: target.id }, mutation: true },
+        decode: (value) => {
+            const result = decodeExpression(kind, value, guildId)
+            return result?.id === id ? result : undefined
+        },
+    }
+}
+
+export function expressionDelete(
+    kind: ExpressionKind,
+    target: ExpressionReference,
+    options?: ExpressionDeleteOptions,
+): GuildRequest<void> | InputValidationFailure {
+    if (!record(target)) return inputValidationFailure("target", "type", "Expression targets must be objects")
+    if (!identifier(target.id))
+        return inputValidationFailure("target.id", "format", "Expression IDs must be decimal strings")
+    const base = expressionList(kind, target.guildId)
+    const audit = auditSettings(options)
+    if (base instanceof InputValidationFailure) return base
+    if (audit instanceof InputValidationFailure) return audit
+    if (options?.purge !== undefined && typeof options.purge !== "boolean")
+        return inputValidationFailure("options.purge", "type", "Expression purge must be a boolean")
+    return {
+        ...base,
+        ...audit,
+        method: "DELETE",
+        path: `${base.path}/${target.id}?purge=${options?.purge === true}`,
+        status: 204,
+        cache: { selection: { kind, guildId: target.guildId, id: target.id }, mutation: true },
+        decode: () => undefined,
+    }
+}
+
+/** Upper bound for a source guild's badge list. Fluxer currently sends at most three badges */
+const maximumSourceFeatures = 64
+
+/** Reads the public presentation of an expression's source guild. Every documented field is required. The response
+ * carries nothing that ties it to the requested expression, so only its shape is checked. Unrecognized badge strings are
+ * retained unchanged, so a badge added by Fluxer does not fail the read, while a non-string entry is malformed
+ */
+export function expressionSource(
+    kind: ExpressionKind,
+    id: string,
+): GuildRequest<ExpressionSourceGuild> | InputValidationFailure {
+    if (!identifier(id))
+        return inputValidationFailure("expressionId", "format", "Expression IDs must be decimal strings")
+    return {
+        guildId: id,
+        bucket: `${kind}:source`,
+        path: `/${kind}/${id}/source`,
+        method: "GET",
+        status: 200,
+        decode: (value) => {
+            if (
+                !record(value) ||
+                !identifier(value.id) ||
+                typeof value.name !== "string" ||
+                (value.icon !== null && typeof value.icon !== "string")
+            )
+                return undefined
+            const features = snapshotArray(value.features, maximumSourceFeatures)
+            if (!features?.every((feature) => typeof feature === "string")) return undefined
+            return Object.freeze({
+                id: value.id,
+                name: value.name,
+                icon: value.icon,
+                features: features as readonly string[],
+            })
+        },
+    }
+}