@ovencord/rest 2.5.0

package/src/lib/utils/types.ts

@@ -0,0 +1,406 @@
+import type { Collection } from '@ovencord/collection';
+import type { Awaitable, RawFile } from '@ovencord/util';
+import type { IHandler } from '../interfaces/Handler.js';
+
+export interface RestEvents {
+	handlerSweep: [sweptHandlers: Collection<string, IHandler>];
+	hashSweep: [sweptHashes: Collection<string, HashData>];
+	invalidRequestWarning: [invalidRequestInfo: InvalidRequestWarningData];
+	rateLimited: [rateLimitInfo: RateLimitData];
+	response: [request: APIRequest, response: ResponseLike];
+	restDebug: [info: string];
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RestEventsMap extends RestEvents {}
+
+/**
+ * Options to be passed when creating the REST instance
+ */
+export interface RESTOptions {
+	/**
+	 * The agent to set globally
+	 *
+	 * @deprecated This property is deprecated and has no effect when using Bun native fetch.
+	 * It is kept for API compatibility but will always be `null`.
+	 */
+	agent: null;
+	/**
+	 * The base api path, without version
+	 *
+	 * @defaultValue `'https://discord.com/api'`
+	 */
+	api: string;
+	/**
+	 * The authorization prefix to use for requests, useful if you want to use
+	 * bearer tokens
+	 *
+	 * @defaultValue `'Bot'`
+	 */
+	authPrefix: 'Bearer' | 'Bot';
+	/**
+	 * The cdn path
+	 *
+	 * @defaultValue `'https://cdn.discordapp.com'`
+	 */
+	cdn: string;
+	/**
+	 * How many requests to allow sending per second (Infinity for unlimited, 50 for the standard global limit used by Discord)
+	 *
+	 * @defaultValue `50`
+	 */
+	globalRequestsPerSecond: number;
+	/**
+	 * The amount of time in milliseconds that passes between each hash sweep. (defaults to 1h)
+	 *
+	 * @defaultValue `3_600_000`
+	 */
+	handlerSweepInterval: number;
+	/**
+	 * The maximum amount of time a hash can exist in milliseconds without being hit with a request (defaults to 24h)
+	 *
+	 * @defaultValue `86_400_000`
+	 */
+	hashLifetime: number;
+	/**
+	 * The amount of time in milliseconds that passes between each hash sweep. (defaults to 4h)
+	 *
+	 * @defaultValue `14_400_000`
+	 */
+	hashSweepInterval: number;
+	/**
+	 * Additional headers to send for all API requests
+	 *
+	 * @defaultValue `{}`
+	 */
+	headers: Record<string, string>;
+	/**
+	 * The number of invalid REST requests (those that return 401, 403, or 429) in a 10 minute window between emitted warnings (0 for no warnings).
+	 * That is, if set to 500, warnings will be emitted at invalid request number 500, 1000, 1500, and so on.
+	 *
+	 * @defaultValue `0`
+	 */
+	invalidRequestWarningInterval: number;
+	/**
+	 * The method called to perform the actual HTTP request given a url and web `fetch` options
+	 * For example, to use global fetch, simply provide `makeRequest: fetch`
+	 */
+	makeRequest(url: string, init: RequestInit): Promise<ResponseLike>;
+	/**
+	 * The media proxy path
+	 *
+	 * @defaultValue `'https://media.discordapp.net'`
+	 */
+	mediaProxy: string;
+	/**
+	 * The extra offset to add to rate limits in milliseconds
+	 *
+	 * @defaultValue `50`
+	 */
+	offset: GetRateLimitOffsetFunction | number;
+	/**
+	 * Determines how rate limiting and pre-emptive throttling should be handled.
+	 * When an array of strings, each element is treated as a prefix for the request route
+	 * (e.g. `/channels` to match any route starting with `/channels` such as `/channels/:id/messages`)
+	 * for which to throw {@link RateLimitError}s. All other request routes will be queued normally
+	 *
+	 * @defaultValue `null`
+	 */
+	rejectOnRateLimit: RateLimitQueueFilter | string[] | null;
+	/**
+	 * The number of retries for errors with the 500 code, or errors
+	 * that timeout
+	 *
+	 * @defaultValue `3`
+	 */
+	retries: number;
+	/**
+	 * The time to exponentially add before retrying a 5xx or aborted request
+	 *
+	 * @defaultValue `0`
+	 */
+	retryBackoff: GetRetryBackoffFunction | number;
+	/**
+	 * The time to wait in milliseconds before a request is aborted
+	 *
+	 * @defaultValue `15_000`
+	 */
+	timeout: GetTimeoutFunction | number;
+	/**
+	 * Extra information to add to the user agent
+	 *
+	 * @defaultValue DefaultUserAgentAppendix
+	 */
+	userAgentAppendix: string;
+	/**
+	 * The version of the API to use
+	 *
+	 * @defaultValue `'10'`
+	 */
+	version: string;
+}
+
+/**
+ * Data emitted on `RESTEvents.RateLimited`
+ */
+export interface RateLimitData {
+	/**
+	 * Whether the rate limit that was reached was the global limit
+	 */
+	global: boolean;
+	/**
+	 * The bucket hash for this request
+	 */
+	hash: string;
+	/**
+	 * The amount of requests we can perform before locking requests
+	 */
+	limit: number;
+	/**
+	 * The major parameter of the route
+	 *
+	 * For example, in `/channels/x`, this will be `x`.
+	 * If there is no major parameter (e.g: `/bot/gateway`) this will be `global`.
+	 */
+	majorParameter: string;
+	/**
+	 * The HTTP method being performed
+	 */
+	method: string;
+	/**
+	 * The time, in milliseconds, that will need to pass before this specific request can be retried
+	 */
+	retryAfter: number;
+	/**
+	 * The route being hit in this request
+	 */
+	route: string;
+	/**
+	 * The scope of the rate limit that was hit.
+	 *
+	 * This can be `user` for rate limits that are per client, `global` for rate limits that affect all clients or `shared` for rate limits that
+	 * are shared per resource.
+	 */
+	scope: 'global' | 'shared' | 'user';
+	/**
+	 * The time, in milliseconds, that will need to pass before the sublimit lock for the route resets, and requests that fall under a sublimit
+	 * can be retried
+	 *
+	 * This is only present on certain sublimits, and `0` otherwise
+	 */
+	sublimitTimeout: number;
+	/**
+	 * The time, in milliseconds, until the route's request-lock is reset
+	 */
+	timeToReset: number;
+	/**
+	 * The full URL for this request
+	 */
+	url: string;
+}
+
+/**
+ * A function that determines whether the rate limit hit should throw an Error
+ */
+export type RateLimitQueueFilter = (rateLimitData: RateLimitData) => Awaitable<boolean>;
+
+/**
+ * A function that determines the rate limit offset for a given request.
+ */
+export type GetRateLimitOffsetFunction = (route: string) => number;
+
+/**
+ * A function that determines the backoff for a retry for a given request.
+ *
+ * @param route - The route that has encountered a server-side error
+ * @param statusCode - The status code received or `null` if aborted
+ * @param retryCount - The number of retries that have been attempted so far. The first call will be `0`
+ * @param requestBody - The body that was sent with the request
+ * @returns The delay for the current request or `null` to throw an error instead of retrying
+ */
+export type GetRetryBackoffFunction = (
+	route: string,
+	statusCode: number | null,
+	retryCount: number,
+	requestBody: unknown,
+) => number | null;
+
+/**
+ * A function that determines the timeout for a given request.
+ *
+ * @param route - The route that is being processed
+ * @param body - The body that will be sent with the request
+ */
+export type GetTimeoutFunction = (route: string, body: unknown) => number;
+
+export interface APIRequest {
+	/**
+	 * The data that was used to form the body of this request
+	 */
+	data: HandlerRequestData;
+	/**
+	 * The HTTP method used in this request
+	 */
+	method: string;
+	/**
+	 * Additional HTTP options for this request
+	 */
+	options: RequestInit;
+	/**
+	 * The full path used to make the request
+	 */
+	path: RouteLike;
+	/**
+	 * The number of times this request has been attempted
+	 */
+	retries: number;
+	/**
+	 * The API route identifying the ratelimit for this request
+	 */
+	route: string;
+}
+
+export interface ResponseLike extends Pick<
+	globalThis.Response,
+	'arrayBuffer' | 'bodyUsed' | 'headers' | 'json' | 'ok' | 'status' | 'statusText' | 'text'
+> {
+	body: ReadableStream | null;
+}
+
+export interface InvalidRequestWarningData {
+	/**
+	 * Number of invalid requests that have been made in the window
+	 */
+	count: number;
+	/**
+	 * Time in milliseconds remaining before the count resets
+	 */
+	remainingTime: number;
+}
+
+export type { RawFile } from '@ovencord/util';
+
+export interface AuthData {
+	/**
+	 * The authorization prefix to use for this request, useful if you use this with bearer tokens
+	 *
+	 * @defaultValue `REST.options.authPrefix`
+	 */
+	prefix?: 'Bearer' | 'Bot';
+	/**
+	 * The authorization token to use for this request
+	 */
+	token: string;
+}
+
+/**
+ * Represents possible data to be given to an endpoint
+ */
+export interface RequestData {
+	/**
+	 * Whether to append JSON data to form data instead of `payload_json` when sending files
+	 */
+	appendToFormData?: boolean;
+	/**
+	 * Alternate authorization data to use for this request only, or `false` to disable the Authorization header.
+	 * When making a request to a route that includes a token (such as interactions or webhooks), set to `false`
+	 * to avoid accidentally unsetting the instance token if a 401 is encountered.
+	 *
+	 * @defaultValue `true`
+	 */
+	auth?: AuthData | boolean | undefined;
+	/**
+	 * The body to send to this request.
+	 * If providing as BodyInit, set `passThroughBody: true`
+	 */
+	body?: BodyInit | unknown;
+	/**
+	 * The {@link https://undici.nodejs.org/#/docs/api/Agent | Agent} to use for the request.
+	 *
+	 * @deprecated This property is deprecated and has no effect when using Bun native fetch.
+	 * It is kept for API compatibility but will be ignored.
+	 */
+	dispatcher?: never;
+	/**
+	 * Files to be attached to this request
+	 */
+	files?: RawFile[] | undefined;
+	/**
+	 * Additional headers to add to this request
+	 */
+	headers?: Record<string, string>;
+	/**
+	 * Whether to pass-through the body property directly to `fetch()`.
+	 * <warn>This only applies when files is NOT present</warn>
+	 */
+	passThroughBody?: boolean;
+	/**
+	 * Query string parameters to append to the called endpoint
+	 */
+	query?: URLSearchParams;
+	/**
+	 * Reason to show in the audit logs
+	 */
+	reason?: string | undefined;
+	/**
+	 * The signal to abort the queue entry or the REST call, where applicable
+	 */
+	signal?: AbortSignal | undefined;
+	/**
+	 * If this request should be versioned
+	 *
+	 * @defaultValue `true`
+	 */
+	versioned?: boolean;
+}
+
+/**
+ * Possible headers for an API call
+ */
+export interface RequestHeaders {
+	Authorization?: string;
+	'User-Agent': string;
+	'X-Audit-Log-Reason'?: string;
+}
+
+/**
+ * Possible API methods to be used when doing requests
+ */
+export enum RequestMethod {
+	Delete = 'DELETE',
+	Get = 'GET',
+	Patch = 'PATCH',
+	Post = 'POST',
+	Put = 'PUT',
+}
+
+export type RouteLike = `/${string}`;
+
+/**
+ * Internal request options
+ */
+export interface InternalRequest extends RequestData {
+	fullRoute: RouteLike;
+	method: RequestMethod;
+}
+
+export interface HandlerRequestData extends Pick<InternalRequest, 'body' | 'files' | 'signal'> {
+	auth: boolean | string;
+}
+
+/**
+ * Parsed route data for an endpoint
+ */
+export interface RouteData {
+	bucketRoute: string;
+	majorParameter: string;
+	original: RouteLike;
+}
+
+/**
+ * Represents a hash and its associated fields
+ */
+export interface HashData {
+	lastAccess: number;
+	value: string;
+}

package/src/lib/utils/utils.ts

@@ -0,0 +1,248 @@
+import { createHash } from 'node:crypto';
+import type { RESTPatchAPIChannelJSONBody, Snowflake } from 'discord-api-types/v10';
+import type { REST } from '../REST.js';
+import { RateLimitError } from '../errors/RateLimitError.js';
+import { RequestMethod } from './types.js';
+import type {
+	GetRateLimitOffsetFunction,
+	GetRetryBackoffFunction,
+	GetTimeoutFunction,
+	RateLimitData,
+	ResponseLike,
+} from './types.js';
+
+function serializeSearchParam(value: unknown): string | null {
+	switch (typeof value) {
+		case 'string':
+			return value;
+		case 'number':
+		case 'bigint':
+		case 'boolean':
+			return value.toString();
+		case 'object':
+			if (value === null) return null;
+			if (value instanceof Date) {
+				return Number.isNaN(value.getTime()) ? null : value.toISOString();
+			}
+
+			if (typeof value.toString === 'function' && value.toString !== Object.prototype.toString) return value.toString();
+			return null;
+		default:
+			return null;
+	}
+}
+
+/**
+ * Creates and populates an URLSearchParams instance from an object, stripping
+ * out null and undefined values, while also coercing non-strings to strings.
+ *
+ * @param options - The options to use
+ * @returns A populated URLSearchParams instance
+ */
+export function makeURLSearchParams<OptionsType extends object>(options?: Readonly<OptionsType>) {
+	const params = new URLSearchParams();
+	if (!options) return params;
+
+	for (const [key, value] of Object.entries(options)) {
+		const serialized = serializeSearchParam(value);
+		if (serialized !== null) params.append(key, serialized);
+	}
+
+	return params;
+}
+
+/**
+ * Converts the response to usable data
+ *
+ * @param res - The fetch response
+ */
+export async function parseResponse(res: ResponseLike): Promise<unknown> {
+	if (res.headers.get('Content-Type')?.startsWith('application/json')) {
+		return res.json();
+	}
+
+	return res.arrayBuffer();
+}
+
+/**
+ * Check whether a request falls under a sublimit
+ *
+ * @param bucketRoute - The buckets route identifier
+ * @param body - The options provided as JSON data
+ * @param method - The HTTP method that will be used to make the request
+ * @returns Whether the request falls under a sublimit
+ */
+export function hasSublimit(bucketRoute: string, body?: unknown, method?: string): boolean {
+	// TODO: Update for new sublimits
+	// Currently known sublimits:
+	// Editing channel `name` or `topic`
+	if (bucketRoute === '/channels/:id') {
+		if (typeof body !== 'object' || body === null) return false;
+		// This should never be a POST body, but just in case
+		if (method !== RequestMethod.Patch) return false;
+		const castedBody = body as RESTPatchAPIChannelJSONBody;
+		return ['name', 'topic'].some((key) => Reflect.has(castedBody, key));
+	}
+
+	// If we are checking if a request has a sublimit on a route not checked above, sublimit all requests to avoid a flood of 429s
+	return true;
+}
+
+/**
+ * Check whether an error indicates that a retry can be attempted
+ *
+ * @param error - The error thrown by the network request
+ * @returns Whether the error indicates a retry should be attempted
+ */
+export function shouldRetry(error: Error & { code?: string }) {
+	// Retry for possible timed out requests
+	if (error.name === 'AbortError') return true;
+	// Downlevel ECONNRESET to retry as it may be recoverable
+	return ('code' in error && error.code === 'ECONNRESET') || error.message.includes('ECONNRESET');
+}
+
+/**
+ * Determines whether the request should be queued or whether a RateLimitError should be thrown
+ *
+ * @internal
+ */
+export async function onRateLimit(manager: REST, rateLimitData: RateLimitData) {
+	const { options } = manager;
+	if (!options.rejectOnRateLimit) return;
+
+	const shouldThrow =
+		typeof options.rejectOnRateLimit === 'function'
+			? await options.rejectOnRateLimit(rateLimitData)
+			: options.rejectOnRateLimit.some((route) => rateLimitData.route.startsWith(route.toLowerCase()));
+	if (shouldThrow) {
+		throw new RateLimitError(rateLimitData);
+	}
+}
+
+/**
+ * Calculates the default avatar index for a given user id.
+ *
+ * @param userId - The user id to calculate the default avatar index for
+ */
+export function calculateUserDefaultAvatarIndex(userId: Snowflake) {
+	return Number(BigInt(userId) >> 22n) % 6;
+}
+
+/**
+ * Sleeps for a given amount of time.
+ *
+ * @param ms - The amount of time (in milliseconds) to sleep for
+ */
+export async function sleep(ms: number): Promise<void> {
+	return new Promise<void>((resolve) => {
+		setTimeout(() => resolve(), ms);
+	});
+}
+
+/**
+ * Verifies that a value is a buffer-like object.
+ *
+ * @param value - The value to check
+ */
+export function isBufferLike(value: unknown): value is ArrayBuffer | Uint8Array | Uint8ClampedArray {
+	return value instanceof ArrayBuffer || value instanceof Uint8Array || value instanceof Uint8ClampedArray;
+}
+
+/**
+ * Normalizes the offset for rate limits. Applies a Math.max(0, N) to prevent negative offsets,
+ * also deals with callbacks.
+ *
+ * @internal
+ */
+export function normalizeRateLimitOffset(offset: GetRateLimitOffsetFunction | number, route: string): number {
+	if (typeof offset === 'number') {
+		return Math.max(0, offset);
+	}
+
+	const result = offset(route);
+	return Math.max(0, result);
+}
+
+/**
+ * Normalizes the retry backoff used to add delay to retrying 5xx and aborted requests.
+ * Applies a Math.max(0, N) to prevent negative backoffs, also deals with callbacks.
+ *
+ * @internal
+ */
+export function normalizeRetryBackoff(
+	retryBackoff: GetRetryBackoffFunction | number,
+	route: string,
+	statusCode: number | null,
+	retryCount: number,
+	requestBody: unknown,
+): number | null {
+	if (typeof retryBackoff === 'number') {
+		return Math.max(0, retryBackoff) * (1 << retryCount);
+	}
+
+	// No need to Math.max as we'll only set the sleep timer if the value is > 0 (and not equal)
+	return retryBackoff(route, statusCode, retryCount, requestBody);
+}
+
+/**
+ * Normalizes the timeout for aborting requests. Applies a Math.max(0, N) to prevent negative timeouts,
+ * also deals with callbacks.
+ *
+ * @internal
+ */
+export function normalizeTimeout(timeout: GetTimeoutFunction | number, route: string, requestBody: unknown): number {
+	if (typeof timeout === 'number') {
+		return Math.max(0, timeout);
+	}
+	const result = timeout(route, requestBody);
+	return Math.max(0, result);
+}
+
+/**
+ * Generates a UUID v5 according to RFC 4122
+ *
+ * @param value - The value to hash
+ * @param namespace - The namespace UUID
+ */
+export function uuidv5(value: string | Uint8Array, namespace: string): string {
+    // 1. Verify namespace is a valid UUID
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(namespace)) {
+        throw new TypeError('Invalid namespace UUID');
+    }
+
+    // 2. Parse namespace UUID into bytes
+    const namespaceBytes = new Uint8Array(16);
+    const hex = namespace.replace(/-/g, '');
+    for (let i = 0; i < 16; i++) {
+        namespaceBytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+
+    // 3. Convert value to bytes if string
+    const valueBytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
+
+    // 4. Concatenate namespace and value
+    const data = new Uint8Array(namespaceBytes.length + valueBytes.length);
+    data.set(namespaceBytes);
+    data.set(valueBytes, namespaceBytes.length);
+
+    // 5. Hash with SHA-1
+    const buffer = createHash('sha1').update(data).digest();
+    const hash = new Uint8Array(buffer);
+
+    // 6. Set version to 5 (0101)
+    hash[6] = (hash[6]! & 0x0f) | 0x50;
+
+    // 7. Set variant to RFC 4122 (10xx)
+    hash[8] = (hash[8]! & 0x3f) | 0x80;
+
+    // 8. Convert to hex string with dashes
+    const hexHash = Array.from(hash, (byte) => byte.toString(16).padStart(2, '0'));
+    
+    return [
+        hexHash.slice(0, 4).join(''),
+        hexHash.slice(4, 6).join(''),
+        hexHash.slice(6, 8).join(''),
+        hexHash.slice(8, 10).join(''),
+        hexHash.slice(10, 16).join('')
+    ].join('-');
+}

package/src/shared.ts

@@ -0,0 +1,16 @@
+export * from './lib/CDN.js';
+export * from './lib/errors/DiscordAPIError.js';
+export * from './lib/errors/HTTPError.js';
+export * from './lib/errors/RateLimitError.js';
+export type * from './lib/interfaces/Handler.js';
+export * from './lib/REST.js';
+export * from './lib/utils/constants.js';
+export * from './lib/utils/types.js';
+export { calculateUserDefaultAvatarIndex, makeURLSearchParams, parseResponse } from './lib/utils/utils.js';
+
+/**
+ * The {@link https://github.com/ovencord/ovencord/blob/main/packages/rest#readme | @ovencord/rest} version
+ * that you are currently using.
+ */
+// This needs to explicitly be `string` so it is not typed as a "const string" that gets injected by esbuild
+export const version = '[VI]{{inject}}[/VI]' as string;

package/src/strategies/bunRequest.ts

@@ -0,0 +1,32 @@
+import type { ResponseLike } from '../shared.js';
+
+/**
+ * Makes an HTTP request using Bun's native fetch API
+ *
+ * @param url - The URL to request
+ * @param init - Fetch options
+ * @returns A response-like object compatible with the REST manager
+ */
+export async function makeRequest(url: string, init: RequestInit): Promise<ResponseLike> {
+	const res = await fetch(url, init);
+
+	return {
+		body: res.body,
+		async arrayBuffer() {
+			return res.arrayBuffer();
+		},
+		async json() {
+			return res.json();
+		},
+		async text() {
+			return res.text();
+		},
+		get bodyUsed() {
+			return res.bodyUsed;
+		},
+		headers: res.headers,
+		status: res.status,
+		statusText: res.statusText,
+		ok: res.ok,
+	};
+}