@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/permissions.ts

@@ -0,0 +1,417 @@
+/**
+ * Permission calculation from explicit guild, member, role and channel data.
+ * Invariant: Results are checks for the supplied data, never action authorization, and Fluxer stays authoritative.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import * as Effect from "effect/Effect"
+import { isThreadChannel } from "#sdk/channels"
+import type { ChannelOperationFailure, GuildChannel, PermissionOverwrite } from "#sdk/channels"
+import type { GuildOperationFailure, GuildOperationOptions } from "#sdk/guilds"
+import { GuildOperationError, Permissions } from "#sdk/guilds"
+import { composedStepFacts } from "#sdk/api-errors"
+import type { PermissionInput, PermissionTarget } from "#sdk/permissions"
+import { channelFetch } from "./channels.js"
+import type { ClientOwner } from "./client.js"
+import { guildFetch, memberFetch, roleList } from "./guilds.js"
+import { identifier, record } from "./decode/primitives.js"
+import { readCaller, suspendInput, suspendMarked } from "./defects.js"
+import { InputValidationFailure, inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+
+const allPermissions = (1n << 64n) - 1n
+const administrator = 1n << 3n
+
+const unsigned64 = (value: unknown): value is bigint =>
+    typeof value === "bigint" && value >= 0n && value <= allPermissions
+
+const inputFailure = (operation: "permissions.calculate" | "permissions.fetch", failure: InputValidationFailure) =>
+    new GuildOperationError({ operation, reason: "input", outcome: "notDispatched", inputValidation: failure.detail })
+
+const timeoutFailure = () =>
+    new GuildOperationError({ operation: "permissions.fetch", reason: "timeout", outcome: "notDispatched" })
+
+interface ValidatedInput {
+    readonly guild: PermissionGuild
+    readonly member: PermissionMember
+    readonly roles: ReadonlyMap<string, PermissionRole>
+    /** The target channel, or a thread's parent channel when inThread is set */
+    readonly channel: PermissionChannel | undefined
+    readonly inThread: boolean
+}
+
+interface PermissionGuild {
+    readonly id: string
+    readonly ownerId: string
+}
+
+interface PermissionMember {
+    readonly guildId: string
+    readonly userId: string
+    readonly roleIds: readonly string[]
+}
+
+interface PermissionRole {
+    readonly id: string
+    readonly guildId: string
+    readonly permissions: bigint
+}
+
+interface PermissionChannel {
+    readonly id: string
+    readonly guildId: string
+    readonly permissionOverwrites: readonly PermissionOverwrite[]
+}
+
+interface ValidatedTarget {
+    readonly guildId: string
+    readonly userId: string
+    readonly channelId: string | undefined
+}
+
+// Each validator reads a caller field once, so the validated value is the one calculated
+
+function validateMember(value: unknown, guildId: string): PermissionMember | undefined {
+    if (!record(value) || value.guildId !== guildId) return undefined
+    const userId = value.userId
+    const roleInput = value.roleIds
+    if (!identifier(userId) || !Array.isArray(roleInput)) return undefined
+    const roleIds: string[] = []
+    const seen = new Set<string>()
+    for (const roleId of roleInput) {
+        if (!identifier(roleId) || roleId === guildId || seen.has(roleId)) return undefined
+        seen.add(roleId)
+        roleIds.push(roleId)
+    }
+    return { guildId, userId, roleIds }
+}
+
+function validateRoles(
+    value: unknown,
+    guildId: string,
+    member: PermissionMember,
+): ReadonlyMap<string, PermissionRole> | undefined {
+    if (!Array.isArray(value)) return undefined
+    const roles = new Map<string, PermissionRole>()
+    for (const role of value) {
+        if (!record(role) || role.guildId !== guildId) return undefined
+        const id = role.id
+        const permissions = role.permissions
+        if (!identifier(id) || !unsigned64(permissions) || roles.has(id)) return undefined
+        roles.set(id, { id, guildId, permissions })
+    }
+    if (!roles.has(guildId) || member.roleIds.some((roleId) => !roles.has(roleId))) return undefined
+    return roles
+}
+
+function decodeOverwrite(value: unknown, seen: Set<string>): PermissionOverwrite | undefined {
+    if (!record(value)) return undefined
+    const id = value.id
+    const type = value.type
+    const allow = value.allow
+    const deny = value.deny
+    if (!identifier(id) || (type !== "role" && type !== "member") || !unsigned64(allow) || !unsigned64(deny))
+        return undefined
+    const key = `${type}:${id}`
+    if (seen.has(key)) return undefined
+    seen.add(key)
+    return { id, type, allow, deny }
+}
+
+function validateChannel(value: unknown, guildId: string): PermissionChannel | undefined {
+    if (!record(value) || value.guildId !== guildId) return undefined
+    const id = value.id
+    if (!identifier(id) || !("permissionOverwrites" in value)) return undefined
+    const overwrites = value.permissionOverwrites
+    if (!Array.isArray(overwrites)) return undefined
+    const seen = new Set<string>()
+    const decoded: PermissionOverwrite[] = []
+    for (const overwrite of overwrites) {
+        const valid = decodeOverwrite(overwrite, seen)
+        if (!valid) return undefined
+        decoded.push(valid)
+    }
+    return { id, guildId, permissionOverwrites: decoded }
+}
+
+/** The parent channel ID of a thread in the guild, or undefined when the thread's guild or IDs are invalid */
+function threadParentId(value: unknown, guildId: string): string | undefined {
+    if (!record(value) || value.guildId !== guildId || !identifier(value.id)) return undefined
+    const parentId = value.parentId
+    return identifier(parentId) ? parentId : undefined
+}
+
+function validateChannels(
+    channelInput: unknown,
+    parentInput: unknown,
+    guildId: string,
+): Pick<ValidatedInput, "channel" | "inThread"> | InputValidationFailure {
+    if (channelInput === undefined || !isThreadChannel(channelInput as GuildChannel)) {
+        if (parentInput !== undefined)
+            return inputValidationFailure(
+                "input.parentChannel",
+                "relationship",
+                "Permission parentChannel is supported only when channel is a thread",
+            )
+        if (channelInput === undefined) return { channel: undefined, inThread: false }
+        const channel = validateChannel(channelInput, guildId)
+        if (!channel)
+            return inputValidationFailure(
+                "input.channel",
+                "format",
+                "Permission channel must match the guild and contain unique valid role or member overwrites",
+            )
+        return { channel, inThread: false }
+    }
+    // A thread has no overwrites of its own, so Fluxer calculates its permissions in the parent channel
+    const parentId = threadParentId(channelInput, guildId)
+    if (parentId === undefined)
+        return inputValidationFailure(
+            "input.channel",
+            "format",
+            "Permission thread must match the guild and contain decimal thread and parent channel IDs",
+        )
+    if (parentInput === undefined)
+        return inputValidationFailure(
+            "input.parentChannel",
+            "required",
+            "Permission parentChannel is required when channel is a thread, because a thread takes its parent's permissions",
+        )
+    const parent = validateChannel(parentInput, guildId)
+    if (!parent)
+        return inputValidationFailure(
+            "input.parentChannel",
+            "format",
+            "Permission parentChannel must match the guild and contain unique valid role or member overwrites",
+        )
+    if (parent.id !== parentId)
+        return inputValidationFailure(
+            "input.parentChannel",
+            "relationship",
+            "Permission parentChannel must be the channel that the thread's parentId names",
+        )
+    return { channel: parent, inThread: true }
+}
+
+function validateInput(value: unknown): ValidatedInput | InputValidationFailure {
+    if (!record(value)) return inputValidationFailure("input", "type", "Permission input must be an object")
+    const guildInput = value.guild
+    if (!record(guildInput)) return inputValidationFailure("input.guild", "type", "Permission guild must be an object")
+    const guildId = guildInput.id
+    if (!identifier(guildId))
+        return inputValidationFailure("input.guild.id", "format", "Permission guild ID must be a decimal string")
+    const ownerId = guildInput.ownerId
+    if (!identifier(ownerId))
+        return inputValidationFailure(
+            "input.guild.ownerId",
+            "format",
+            "Permission guild owner ID must be a decimal string",
+        )
+    const guild: PermissionGuild = { id: guildId, ownerId }
+    const member = validateMember(value.member, guild.id)
+    if (!member)
+        return inputValidationFailure(
+            "input.member",
+            "format",
+            "Permission member must match the guild and contain a decimal user ID and unique non-default role IDs",
+        )
+    const roles = validateRoles(value.roles, guild.id, member)
+    if (!roles)
+        return inputValidationFailure(
+            "input.roles[]",
+            "format",
+            "Permission roles must be unique same-guild roles with unsigned 64-bit permissions and cover the member roles",
+        )
+    const channels = validateChannels(value.channel, value.parentChannel, guild.id)
+    if (channels instanceof InputValidationFailure) return channels
+    return { guild, member, roles, ...channels }
+}
+
+function applyOverwrite(permissions: bigint, overwrite: PermissionOverwrite): bigint {
+    return (permissions & ~overwrite.deny) | overwrite.allow
+}
+
+/** Fluxer's thread rule: SendMessages in a thread follows SendMessagesInThreads in its parent, whichever way it is set */
+function threadPermissions(parentPermissions: bigint): bigint {
+    const withoutSend = parentPermissions & ~Permissions.SendMessages
+    return (parentPermissions & Permissions.SendMessagesInThreads) === Permissions.SendMessagesInThreads
+        ? withoutSend | Permissions.SendMessages
+        : withoutSend
+}
+
+function calculate(input: ValidatedInput): bigint {
+    const { guild, member, roles, channel, inThread } = input
+    if (member.userId === guild.ownerId) return allPermissions
+
+    let permissions = roles.get(guild.id)!.permissions
+    for (const roleId of member.roleIds) permissions |= roles.get(roleId)!.permissions
+    if ((permissions & administrator) === administrator) return allPermissions
+    if (!channel) return permissions
+
+    const overwrites = channel.permissionOverwrites!
+    for (const overwrite of overwrites)
+        if (overwrite.type === "role" && overwrite.id === guild.id) permissions = applyOverwrite(permissions, overwrite)
+
+    let roleAllow = 0n
+    let roleDeny = 0n
+    const memberRoles = new Set(member.roleIds)
+    for (const overwrite of overwrites)
+        if (overwrite.type === "role" && memberRoles.has(overwrite.id)) {
+            roleAllow |= overwrite.allow
+            roleDeny |= overwrite.deny
+        }
+    permissions = (permissions & ~roleDeny) | roleAllow
+
+    for (const overwrite of overwrites)
+        if (overwrite.type === "member" && overwrite.id === member.userId)
+            permissions = applyOverwrite(permissions, overwrite)
+
+    return inThread ? threadPermissions(permissions) : permissions
+}
+
+/**
+ * Calculates Fluxer's raw guild, explicit-channel or thread permission bitfield from one validated local snapshot.
+ * A thread is calculated in its parent channel, matching upstream threadViewPermissions in
+ * packages/constants/src/ThreadPermissionUtils.ts at 4749eb7f
+ */
+export function calculatePermissions(input: PermissionInput): Effect.Effect<bigint, GuildOperationError> {
+    // Only reading the caller input is marked, so a fault in the calculation stays an SDK fault
+    return suspendMarked(() => {
+        const validated = readCaller(() => validateInput(input))
+        return validated instanceof InputValidationFailure
+            ? Effect.fail(inputFailure("permissions.calculate", validated))
+            : Effect.succeed(calculate(validated))
+    })
+}
+
+function validateTarget(value: unknown): ValidatedTarget | InputValidationFailure {
+    if (!record(value)) return inputValidationFailure("target", "type", "Permission target must be an object")
+    const unsupported = unsupportedKeyFailure(
+        value,
+        ["guildId", "userId", "channelId"],
+        "target",
+        "the permission target",
+    )
+    if (unsupported) return unsupported
+    const guildId = value.guildId
+    if (!identifier(guildId))
+        return inputValidationFailure("target.guildId", "format", "Guild IDs must be decimal strings")
+    const userId = value.userId
+    if (!identifier(userId))
+        return inputValidationFailure("target.userId", "format", "User IDs must be decimal strings")
+    const channelId = value.channelId
+    if (channelId !== undefined && !identifier(channelId))
+        return inputValidationFailure("target.channelId", "format", "Channel IDs must be decimal strings")
+    return { guildId, userId, channelId }
+}
+
+function validateOptions(value: unknown): GuildOperationOptions | InputValidationFailure {
+    if (value === undefined) return {}
+    if (!record(value)) return inputValidationFailure("options", "type", "Permission fetch options must be an object")
+    const unsupported = unsupportedKeyFailure(value, ["timeoutMs", "signal"], "options", "the permission fetch options")
+    if (unsupported) return unsupported
+    const signal = value.signal
+    if (
+        signal !== undefined &&
+        (!record(signal) ||
+            typeof signal.aborted !== "boolean" ||
+            typeof signal.addEventListener !== "function" ||
+            typeof signal.removeEventListener !== "function")
+    )
+        return inputValidationFailure("options.signal", "type", "Permission fetch signal must be an AbortSignal")
+    const timeoutMs = value.timeoutMs
+    if (
+        timeoutMs !== undefined &&
+        (typeof timeoutMs !== "number" ||
+            !Number.isSafeInteger(timeoutMs) ||
+            timeoutMs <= 0 ||
+            timeoutMs > 2_147_483_647)
+    )
+        return inputValidationFailure(
+            "options.timeoutMs",
+            "range",
+            "Permission fetch timeout must be an integer from 1 through 2,147,483,647 ms",
+        )
+    // Keep only the validated timeout: The requests use their own remaining deadlines
+    return timeoutMs === undefined ? {} : { timeoutMs }
+}
+
+function remainingOptions(deadline: number, now: () => number): GuildOperationOptions | undefined {
+    const remaining = Math.floor(deadline - now())
+    return remaining > 0 ? { timeoutMs: remaining } : undefined
+}
+
+function remoteCalculationFailure(error: GuildOperationError): GuildOperationError {
+    return new GuildOperationError({
+        operation: "permissions.fetch",
+        reason: error.reason === "input" ? "response" : error.reason,
+        outcome: error.outcome,
+        status: error.status,
+        retryAfterMs: error.retryAfterMs,
+        apiError: error.apiError,
+        ...composedStepFacts(error),
+    })
+}
+
+/**
+ * Fetches independent guild, member, role, and optional channel observations, then calculates their raw bitfield.
+ * A thread channel adds a read of its parent channel, whose permissions the thread takes
+ *
+ * This always reads remotely without consulting local caches. Its deadline covers the whole composition, but the
+ * resulting observations are not transactional and do not establish access, hierarchy, timeouts, or action success
+ */
+export function fetchPermissions(
+    owner: Pick<ClientOwner, "guild" | "channel" | "logical"> & { readonly defaultTimeoutMs?: number },
+    target: PermissionTarget,
+    options?: GuildOperationOptions,
+): Effect.Effect<bigint, GuildOperationFailure | ChannelOperationFailure> {
+    // Reading and validating the caller target and options is marked as application input
+    return suspendInput(() => {
+        const targetSnapshot = validateTarget(target)
+        if (targetSnapshot instanceof InputValidationFailure)
+            return Effect.fail(inputFailure("permissions.fetch", targetSnapshot))
+        const validatedOptions = validateOptions(options)
+        if (validatedOptions instanceof InputValidationFailure)
+            return Effect.fail(inputFailure("permissions.fetch", validatedOptions))
+        const timedOut = () => Effect.fail(timeoutFailure())
+        return Effect.gen(function* () {
+            const now = () => owner.logical.now()
+            const deadline = now() + (validatedOptions.timeoutMs ?? owner.defaultTimeoutMs ?? 30_000)
+            const requestOptions = () => remainingOptions(deadline, now)
+            const guildOptions = requestOptions()
+            if (!guildOptions) return yield* timedOut()
+            const guild = yield* owner.guild("guilds.fetch", () => guildFetch(targetSnapshot.guildId), guildOptions)
+
+            const memberOptions = requestOptions()
+            if (!memberOptions) return yield* timedOut()
+            const member = yield* owner.guild("members.fetch", () => memberFetch(targetSnapshot), memberOptions)
+
+            const roleOptions = requestOptions()
+            if (!roleOptions) return yield* timedOut()
+            const roles = yield* owner.guild("roles.fetchAll", () => roleList(targetSnapshot.guildId), roleOptions)
+
+            let channel: GuildChannel | undefined
+            const channelId = targetSnapshot.channelId
+            if (channelId !== undefined) {
+                const channelOptions = requestOptions()
+                if (!channelOptions) return yield* timedOut()
+                channel = yield* owner.channel("channels.fetch", () => channelFetch(channelId), channelOptions)
+            }
+
+            // A thread takes its permissions from its parent channel, read under the same deadline
+            let parentChannel: GuildChannel | undefined
+            if (isThreadChannel(channel)) {
+                const parentId = channel.parentId
+                const parentOptions = requestOptions()
+                if (!parentOptions) return yield* timedOut()
+                parentChannel = yield* owner.channel("channels.fetch", () => channelFetch(parentId), parentOptions)
+            }
+
+            return yield* calculatePermissions({
+                guild,
+                member,
+                roles,
+                ...(channel === undefined ? {} : { channel }),
+                ...(parentChannel === undefined ? {} : { parentChannel }),
+            }).pipe(Effect.mapError(remoteCalculationFailure))
+        })
+    })
+}

package/src/internal/pins.ts

@@ -0,0 +1,115 @@
+/**
+ * Pin pages, pin updates and pin queries.
+ * Invariant: Pin times and cursors are preserved as received or supplied, and pages must be in descending pin-time order.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { ChannelPinsUpdate, MessagePinsPage, MessagePin } from "#sdk/pins"
+import type { MessageCore } from "#sdk/messages"
+import type { MessageDecoder } from "./message-fields.js"
+import { inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+import { decodeMessage } from "./message.js"
+import { identifier, record } from "./decode/primitives.js"
+import { timestamp } from "./decode/timestamp.js"
+
+/** Compare validated pin timestamps by instant, retaining every fractional digit and normalizing timezone offsets */
+export function comparePinTimestamps(left: string, right: string): number {
+    const fraction = /\.(\d+)/
+    const leftFraction = fraction.exec(left)?.[1] ?? ""
+    const rightFraction = fraction.exec(right)?.[1] ?? ""
+    const seconds = Date.parse(left.replace(fraction, "")) - Date.parse(right.replace(fraction, ""))
+    if (seconds !== 0) return seconds
+    const length = Math.max(leftFraction.length, rightFraction.length)
+    const first = leftFraction.padEnd(length, "0")
+    const second = rightFraction.padEnd(length, "0")
+    return first < second ? -1 : first > second ? 1 : 0
+}
+
+export function encodePinsQuery(channel: unknown, query: unknown) {
+    const input = query === undefined ? {} : query
+    if (!identifier(channel))
+        return inputValidationFailure("channelId", "format", "Channel IDs must be decimal strings")
+    if (!record(input)) return inputValidationFailure("query", "type", "Pin query must be an object")
+    const unsupported = unsupportedKeyFailure(input, ["limit", "before"], "query", "the pin query")
+    if (unsupported) return unsupported
+    const limitInput = input.limit
+    const before = input.before
+    const limit = limitInput === undefined ? 50 : limitInput
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 50)
+        return inputValidationFailure("query.limit", "range", "Pin limit must be an integer from 1 through 50")
+    if (before !== undefined && !timestamp(before))
+        return inputValidationFailure(
+            "query.before",
+            "format",
+            "Pin cursor must be an ISO 8601 timestamp with timezone",
+        )
+    const params = new URLSearchParams({ limit: String(limit) })
+    if (before !== undefined) params.set("before", before)
+    return { limit, params }
+}
+
+export function decodePinsPage(
+    value: unknown,
+    channel: string,
+    query: { readonly limit: number; readonly params: URLSearchParams },
+): MessagePinsPage | undefined
+export function decodePinsPage<M extends MessageCore>(
+    value: unknown,
+    channel: string,
+    query: { readonly limit: number; readonly params: URLSearchParams },
+    decode: MessageDecoder<M>,
+): MessagePinsPage<M> | undefined
+export function decodePinsPage(
+    value: unknown,
+    channel: string,
+    query: { readonly limit: number; readonly params: URLSearchParams },
+    decode: MessageDecoder<MessageCore> = decodeMessage,
+): MessagePinsPage<MessageCore> | undefined {
+    if (
+        !record(value) ||
+        !Array.isArray(value.items) ||
+        value.items.length > query.limit ||
+        typeof value.has_more !== "boolean" ||
+        (value.has_more && !value.items.length)
+    )
+        return undefined
+    const items: MessagePin<MessageCore>[] = []
+    const ids = new Set<string>()
+    const before = query.params.get("before")
+    let previous = before
+    for (const item of value.items) {
+        if (!record(item) || !timestamp(item.pinned_at)) return undefined
+        const message = decode(item.message)
+        const time = item.pinned_at
+        if (
+            !message ||
+            message.channelId !== channel ||
+            (record(item.message) && item.message.pinned === false) ||
+            ids.has(message.id) ||
+            (previous !== null && comparePinTimestamps(time, previous) > 0)
+        )
+            return undefined
+        previous = time
+        ids.add(message.id)
+        items.push(Object.freeze({ message, pinnedAt: item.pinned_at }))
+    }
+    return Object.freeze({
+        items: Object.freeze(items),
+        hasMore: value.has_more,
+        nextBefore: value.has_more ? items.at(-1)!.pinnedAt : null,
+    })
+}
+
+export function decodePinsUpdate(value: unknown): ChannelPinsUpdate | undefined {
+    if (
+        !record(value) ||
+        !identifier(value.channel_id) ||
+        (value.guild_id !== undefined && !identifier(value.guild_id)) ||
+        (value.last_pin_timestamp !== null && !timestamp(value.last_pin_timestamp))
+    )
+        return undefined
+    return Object.freeze({
+        channelId: value.channel_id,
+        lastPinTimestamp: value.last_pin_timestamp,
+        ...(value.guild_id === undefined ? {} : { guildId: value.guild_id as string }),
+    })
+}