seyfert 0.1.0 → 1.0.0

package/lib/api/handlers/BurstHandler.d.ts

@@ -1,51 +0,0 @@
-import type { RequestInit } from 'undici-types';
-import type { REST } from '../REST.js';
-import type { IHandler } from '../interfaces/Handler.js';
-import type { HandlerRequestData, ResponseLike, RouteData } from '../utils/types.js';
-/**
- * The structure used to handle burst requests for a given bucket.
- * Burst requests have no ratelimit handling but allow for pre- and post-processing
- * of data in the same manner as sequentially queued requests.
- *
- * @remarks
- * This queue may still emit a rate limit error if an unexpected 429 is hit
- */
-export declare class BurstHandler implements IHandler {
-    private readonly manager;
-    private readonly hash;
-    private readonly majorParameter;
-    /**
-     * {@inheritdoc IHandler.id}
-     */
-    readonly id: string;
-    /**
-     * {@inheritDoc IHandler.inactive}
-     */
-    inactive: boolean;
-    /**
-     * @param manager - The request manager
-     * @param hash - The hash that this RequestHandler handles
-     * @param majorParameter - The major parameter for this handler
-     */
-    constructor(manager: REST, hash: string, majorParameter: string);
-    /**
-     * Emits a debug message
-     *
-     * @param message - The message to debug
-     */
-    private debug;
-    /**
-     * {@inheritDoc IHandler.queueRequest}
-     */
-    queueRequest(routeId: RouteData, url: string, options: RequestInit, requestData: HandlerRequestData): Promise<ResponseLike>;
-    /**
-     * The method that actually makes the request to the API, and updates info about the bucket accordingly
-     *
-     * @param routeId - The generalized API route with literal ids for major parameters
-     * @param url - The fully resolved URL to make the request to
-     * @param options - The fetch options needed to make the request
-     * @param requestData - Extra data from the user's request needed for errors and additional processing
-     * @param retries - The number of retries this request has already attempted (recursion)
-     */
-    private runRequest;
-}

package/lib/api/handlers/BurstHandler.js

@@ -1,124 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BurstHandler = void 0;
-const utils_js_1 = require("../utils/utils.js");
-const Shared_js_1 = require("./Shared.js");
-/**
- * The structure used to handle burst requests for a given bucket.
- * Burst requests have no ratelimit handling but allow for pre- and post-processing
- * of data in the same manner as sequentially queued requests.
- *
- * @remarks
- * This queue may still emit a rate limit error if an unexpected 429 is hit
- */
-class BurstHandler {
-    manager;
-    hash;
-    majorParameter;
-    /**
-     * {@inheritdoc IHandler.id}
-     */
-    id;
-    /**
-     * {@inheritDoc IHandler.inactive}
-     */
-    inactive = false;
-    /**
-     * @param manager - The request manager
-     * @param hash - The hash that this RequestHandler handles
-     * @param majorParameter - The major parameter for this handler
-     */
-    constructor(manager, hash, majorParameter) {
-        this.manager = manager;
-        this.hash = hash;
-        this.majorParameter = majorParameter;
-        this.id = `${hash}:${majorParameter}`;
-    }
-    /**
-     * Emits a debug message
-     *
-     * @param message - The message to debug
-     */
-    debug(message) {
-        this.manager.debugger?.info(`#${this.id} ${message}`);
-    }
-    /**
-     * {@inheritDoc IHandler.queueRequest}
-     */
-    async queueRequest(routeId, url, options, requestData) {
-        return this.runRequest(routeId, url, options, requestData);
-    }
-    /**
-     * The method that actually makes the request to the API, and updates info about the bucket accordingly
-     *
-     * @param routeId - The generalized API route with literal ids for major parameters
-     * @param url - The fully resolved URL to make the request to
-     * @param options - The fetch options needed to make the request
-     * @param requestData - Extra data from the user's request needed for errors and additional processing
-     * @param retries - The number of retries this request has already attempted (recursion)
-     */
-    async runRequest(routeId, url, options, requestData, retries = 0) {
-        const method = options.method ?? 'get';
-        const res = await (0, Shared_js_1.makeNetworkRequest)(this.manager, routeId, url, options, requestData, retries);
-        // Retry requested
-        if (res === null) {
-            // eslint-disable-next-line no-param-reassign
-            return this.runRequest(routeId, url, options, requestData, ++retries);
-        }
-        const status = res.status;
-        let retryAfter = 0;
-        const retry = res.headers.get('Retry-After');
-        // Amount of time in milliseconds until we should retry if rate limited (globally or otherwise)
-        if (retry)
-            retryAfter = Number(retry) * 1_000 + this.manager.options.offset;
-        // Count the invalid requests
-        if (status === 401 || status === 403 || status === 429) {
-            (0, Shared_js_1.incrementInvalidCount)(this.manager);
-        }
-        if (status >= 200 && status < 300) {
-            return res;
-        }
-        if (status === 429) {
-            // Unexpected ratelimit
-            const isGlobal = res.headers.has('X-RateLimit-Global');
-            const scope = (res.headers.get('X-RateLimit-Scope') ?? 'user');
-            await (0, utils_js_1.onRateLimit)(this.manager, {
-                global: isGlobal,
-                method,
-                url,
-                route: routeId.bucketRoute,
-                majorParameter: this.majorParameter,
-                hash: this.hash,
-                limit: Number.POSITIVE_INFINITY,
-                timeToReset: retryAfter,
-                retryAfter,
-                sublimitTimeout: 0,
-                scope,
-            });
-            this.debug([
-                'Encountered unexpected 429 rate limit',
-                `  Global         : ${isGlobal}`,
-                `  Method         : ${method}`,
-                `  URL            : ${url}`,
-                `  Bucket         : ${routeId.bucketRoute}`,
-                `  Major parameter: ${routeId.majorParameter}`,
-                `  Hash           : ${this.hash}`,
-                `  Limit          : ${Number.POSITIVE_INFINITY}`,
-                `  Retry After    : ${retryAfter}ms`,
-                '  Sublimit       : None',
-                `  Scope          : ${scope}`,
-            ].join('\n'));
-            // We are bypassing all other limits, but an encountered limit should be respected (it's probably a non-punished rate limit anyways)
-            await (0, utils_js_1.sleep)(retryAfter);
-            // Since this is not a server side issue, the next request should pass, so we don't bump the retries counter
-            return this.runRequest(routeId, url, options, requestData, retries);
-        }
-        const handled = await (0, Shared_js_1.handleErrors)(this.manager, res, method, url, requestData, retries);
-        if (handled === null) {
-            // eslint-disable-next-line no-param-reassign
-            return this.runRequest(routeId, url, options, requestData, ++retries);
-        }
-        return handled;
-    }
-}
-exports.BurstHandler = BurstHandler;

package/lib/api/handlers/SequentialHandler.d.ts

@@ -1,81 +0,0 @@
-import type { RequestInit } from 'undici-types';
-import type { REST } from '../REST.js';
-import type { IHandler } from '../interfaces/Handler.js';
-import type { HandlerRequestData, ResponseLike, RouteData } from '../utils/types.js';
-/**
- * The structure used to handle sequential requests for a given bucket
- */
-export declare class SequentialHandler implements IHandler {
-    #private;
-    private readonly manager;
-    private readonly hash;
-    private readonly majorParameter;
-    /**
-     * {@inheritDoc IHandler.id}
-     */
-    readonly id: string;
-    /**
-     * The time this rate limit bucket will reset
-     */
-    private reset;
-    /**
-     * The remaining requests that can be made before we are rate limited
-     */
-    private remaining;
-    /**
-     * The total number of requests that can be made before we are rate limited
-     */
-    private limit;
-    /**
-     * @param manager - The request manager
-     * @param hash - The hash that this RequestHandler handles
-     * @param majorParameter - The major parameter for this handler
-     */
-    constructor(manager: REST, hash: string, majorParameter: string);
-    /**
-     * {@inheritDoc IHandler.inactive}
-     */
-    get inactive(): boolean;
-    /**
-     * If the rate limit bucket is currently limited by the global limit
-     */
-    private get globalLimited();
-    /**
-     * If the rate limit bucket is currently limited by its limit
-     */
-    private get localLimited();
-    /**
-     * If the rate limit bucket is currently limited
-     */
-    private get limited();
-    /**
-     * The time until queued requests can continue
-     */
-    private get timeToReset();
-    /**
-     * Emits a debug message
-     *
-     * @param message - The message to debug
-     */
-    private debug;
-    /**
-     * Delay all requests for the specified amount of time, handling global rate limits
-     *
-     * @param time - The amount of time to delay all requests for
-     */
-    private globalDelayFor;
-    /**
-     * {@inheritDoc IHandler.queueRequest}
-     */
-    queueRequest(routeId: RouteData, url: string, options: RequestInit, requestData: HandlerRequestData): Promise<ResponseLike>;
-    /**
-     * The method that actually makes the request to the api, and updates info about the bucket accordingly
-     *
-     * @param routeId - The generalized api route with literal ids for major parameters
-     * @param url - The fully resolved url to make the request to
-     * @param options - The fetch options needed to make the request
-     * @param requestData - Extra data from the user's request needed for errors and additional processing
-     * @param retries - The number of retries this request has already attempted (recursion)
-     */
-    private runRequest;
-}

package/lib/api/handlers/SequentialHandler.js

@@ -1,365 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SequentialHandler = void 0;
-const async_queue_1 = require("@sapphire/async-queue");
-const utils_js_1 = require("../utils/utils.js");
-const Shared_js_1 = require("./Shared.js");
-var QueueType;
-(function (QueueType) {
-    QueueType[QueueType["Standard"] = 0] = "Standard";
-    QueueType[QueueType["Sublimit"] = 1] = "Sublimit";
-})(QueueType || (QueueType = {}));
-/**
- * The structure used to handle sequential requests for a given bucket
- */
-class SequentialHandler {
-    manager;
-    hash;
-    majorParameter;
-    /**
-     * {@inheritDoc IHandler.id}
-     */
-    id;
-    /**
-     * The time this rate limit bucket will reset
-     */
-    reset = -1;
-    /**
-     * The remaining requests that can be made before we are rate limited
-     */
-    remaining = 1;
-    /**
-     * The total number of requests that can be made before we are rate limited
-     */
-    limit = Number.POSITIVE_INFINITY;
-    /**
-     * The interface used to sequence async requests sequentially
-     */
-    #asyncQueue = new async_queue_1.AsyncQueue();
-    /**
-     * The interface used to sequence sublimited async requests sequentially
-     */
-    #sublimitedQueue = null;
-    /**
-     * A promise wrapper for when the sublimited queue is finished being processed or null when not being processed
-     */
-    #sublimitPromise = null;
-    /**
-     * Whether the sublimit queue needs to be shifted in the finally block
-     */
-    #shiftSublimit = false;
-    /**
-     * @param manager - The request manager
-     * @param hash - The hash that this RequestHandler handles
-     * @param majorParameter - The major parameter for this handler
-     */
-    constructor(manager, hash, majorParameter) {
-        this.manager = manager;
-        this.hash = hash;
-        this.majorParameter = majorParameter;
-        this.id = `${hash}:${majorParameter}`;
-    }
-    /**
-     * {@inheritDoc IHandler.inactive}
-     */
-    get inactive() {
-        return (this.#asyncQueue.remaining === 0 &&
-            (this.#sublimitedQueue === null || this.#sublimitedQueue.remaining === 0) &&
-            !this.limited);
-    }
-    /**
-     * If the rate limit bucket is currently limited by the global limit
-     */
-    get globalLimited() {
-        return this.manager.globalRemaining <= 0 && Date.now() < this.manager.globalReset;
-    }
-    /**
-     * If the rate limit bucket is currently limited by its limit
-     */
-    get localLimited() {
-        return this.remaining <= 0 && Date.now() < this.reset;
-    }
-    /**
-     * If the rate limit bucket is currently limited
-     */
-    get limited() {
-        return this.globalLimited || this.localLimited;
-    }
-    /**
-     * The time until queued requests can continue
-     */
-    get timeToReset() {
-        return this.reset + this.manager.options.offset - Date.now();
-    }
-    /**
-     * Emits a debug message
-     *
-     * @param message - The message to debug
-     */
-    debug(message) {
-        this.manager.debugger?.info(`#${this.id} ${message}`);
-    }
-    /**
-     * Delay all requests for the specified amount of time, handling global rate limits
-     *
-     * @param time - The amount of time to delay all requests for
-     */
-    async globalDelayFor(time) {
-        await (0, utils_js_1.sleep)(time);
-        this.manager.globalDelay = null;
-    }
-    /**
-     * {@inheritDoc IHandler.queueRequest}
-     */
-    async queueRequest(routeId, url, options, requestData) {
-        let queue = this.#asyncQueue;
-        let queueType = QueueType.Standard;
-        // Separate sublimited requests when already sublimited
-        if (this.#sublimitedQueue && (0, utils_js_1.hasSublimit)(routeId.bucketRoute, requestData.body, options.method)) {
-            queue = this.#sublimitedQueue;
-            queueType = QueueType.Sublimit;
-        }
-        // Wait for any previous requests to be completed before this one is run
-        await queue.wait({ signal: requestData.signal });
-        // This set handles retroactively sublimiting requests
-        if (queueType === QueueType.Standard) {
-            if (this.#sublimitedQueue && (0, utils_js_1.hasSublimit)(routeId.bucketRoute, requestData.body, options.method)) {
-                /**
-                 * Remove the request from the standard queue, it should never be possible to get here while processing the
-                 * sublimit queue so there is no need to worry about shifting the wrong request
-                 */
-                queue = this.#sublimitedQueue;
-                const wait = queue.wait();
-                this.#asyncQueue.shift();
-                await wait;
-            }
-            else if (this.#sublimitPromise) {
-                // Stall requests while the sublimit queue gets processed
-                await this.#sublimitPromise.promise;
-            }
-        }
-        try {
-            // Make the request, and return the results
-            return this.runRequest(routeId, url, options, requestData);
-        }
-        finally {
-            // Allow the next request to fire
-            queue.shift();
-            if (this.#shiftSublimit) {
-                this.#shiftSublimit = false;
-                this.#sublimitedQueue?.shift();
-            }
-            // If this request is the last request in a sublimit
-            if (this.#sublimitedQueue?.remaining === 0) {
-                this.#sublimitPromise?.resolve();
-                this.#sublimitedQueue = null;
-            }
-        }
-    }
-    /**
-     * The method that actually makes the request to the api, and updates info about the bucket accordingly
-     *
-     * @param routeId - The generalized api route with literal ids for major parameters
-     * @param url - The fully resolved url to make the request to
-     * @param options - The fetch options needed to make the request
-     * @param requestData - Extra data from the user's request needed for errors and additional processing
-     * @param retries - The number of retries this request has already attempted (recursion)
-     */
-    async runRequest(routeId, url, options, requestData, retries = 0) {
-        /*
-         * After calculations have been done, pre-emptively stop further requests
-         * Potentially loop until this task can run if e.g. the global rate limit is hit twice
-         */
-        while (this.limited) {
-            const isGlobal = this.globalLimited;
-            let limit;
-            let timeout;
-            let delay;
-            if (isGlobal) {
-                // Set RateLimitData based on the global limit
-                limit = this.manager.options.globalRequestsPerSecond;
-                timeout = this.manager.globalReset + this.manager.options.offset - Date.now();
-                // If this is the first task to reach the global timeout, set the global delay
-                if (!this.manager.globalDelay) {
-                    // The global delay function clears the global delay state when it is resolved
-                    this.manager.globalDelay = this.globalDelayFor(timeout);
-                }
-                delay = this.manager.globalDelay;
-            }
-            else {
-                // Set RateLimitData based on the route-specific limit
-                limit = this.limit;
-                timeout = this.timeToReset;
-                delay = (0, utils_js_1.sleep)(timeout);
-            }
-            const rateLimitData = {
-                global: isGlobal,
-                method: options.method ?? 'get',
-                url,
-                route: routeId.bucketRoute,
-                majorParameter: this.majorParameter,
-                hash: this.hash,
-                limit,
-                timeToReset: timeout,
-                retryAfter: timeout,
-                sublimitTimeout: 0,
-                scope: 'user',
-            };
-            // Let library users know they have hit a rate limit
-            this.manager.debugger?.info(rateLimitData);
-            // Determine whether a RateLimitError should be thrown
-            await (0, utils_js_1.onRateLimit)(this.manager, rateLimitData);
-            // When not erroring, emit debug for what is happening
-            if (isGlobal) {
-                this.debug(`Global rate limit hit, blocking all requests for ${timeout}ms`);
-            }
-            else {
-                this.debug(`Waiting ${timeout}ms for rate limit to pass`);
-            }
-            // Wait the remaining time left before the rate limit resets
-            await delay;
-        }
-        // As the request goes out, update the global usage information
-        if (!this.manager.globalReset || this.manager.globalReset < Date.now()) {
-            this.manager.globalReset = Date.now() + 1_000;
-            this.manager.globalRemaining = this.manager.options.globalRequestsPerSecond;
-        }
-        this.manager.globalRemaining--;
-        const method = options.method ?? 'get';
-        const res = await (0, Shared_js_1.makeNetworkRequest)(this.manager, routeId, url, options, requestData, retries);
-        // Retry requested
-        if (res === null) {
-            // eslint-disable-next-line no-param-reassign
-            return this.runRequest(routeId, url, options, requestData, ++retries);
-        }
-        const status = res.status;
-        let retryAfter = 0;
-        const limit = res.headers.get('X-RateLimit-Limit');
-        const remaining = res.headers.get('X-RateLimit-Remaining');
-        const reset = res.headers.get('X-RateLimit-Reset-After');
-        const hash = res.headers.get('X-RateLimit-Bucket');
-        const retry = res.headers.get('Retry-After');
-        const scope = (res.headers.get('X-RateLimit-Scope') ?? 'user');
-        // Update the total number of requests that can be made before the rate limit resets
-        this.limit = limit ? Number(limit) : Number.POSITIVE_INFINITY;
-        // Update the number of remaining requests that can be made before the rate limit resets
-        this.remaining = remaining ? Number(remaining) : 1;
-        // Update the time when this rate limit resets (reset-after is in seconds)
-        this.reset = reset ? Number(reset) * 1_000 + Date.now() + this.manager.options.offset : Date.now();
-        // Amount of time in milliseconds until we should retry if rate limited (globally or otherwise)
-        if (retry)
-            retryAfter = Number(retry) * 1_000 + this.manager.options.offset;
-        // Handle buckets via the hash header retroactively
-        if (hash && hash !== this.hash) {
-            // Let library users know when rate limit buckets have been updated
-            this.debug(['Received bucket hash update', `  Old Hash  : ${this.hash}`, `  New Hash  : ${hash}`].join('\n'));
-            // This queue will eventually be eliminated via attrition
-            this.manager.hashes.set(`${method}:${routeId.bucketRoute}`, { value: hash, lastAccess: Date.now() });
-        }
-        else if (hash) {
-            // Handle the case where hash value doesn't change
-            // Fetch the hash data from the manager
-            const hashData = this.manager.hashes.get(`${method}:${routeId.bucketRoute}`);
-            // When fetched, update the last access of the hash
-            if (hashData) {
-                hashData.lastAccess = Date.now();
-            }
-        }
-        // Handle retryAfter, which means we have actually hit a rate limit
-        let sublimitTimeout = null;
-        if (retryAfter > 0) {
-            if (res.headers.has('X-RateLimit-Global')) {
-                this.manager.globalRemaining = 0;
-                this.manager.globalReset = Date.now() + retryAfter;
-            }
-            else if (!this.localLimited) {
-                /*
-                 * This is a sublimit (e.g. 2 channel name changes/10 minutes) since the headers don't indicate a
-                 * route-wide rate limit. Don't update remaining or reset to avoid rate limiting the whole
-                 * endpoint, just set a reset time on the request itself to avoid retrying too soon.
-                 */
-                sublimitTimeout = retryAfter;
-            }
-        }
-        // Count the invalid requests
-        if (status === 401 || status === 403 || status === 429) {
-            (0, Shared_js_1.incrementInvalidCount)(this.manager);
-        }
-        if (res.ok) {
-            return res;
-        }
-        if (status === 429) {
-            // A rate limit was hit - this may happen if the route isn't associated with an official bucket hash yet, or when first globally rate limited
-            const isGlobal = this.globalLimited;
-            let limit;
-            let timeout;
-            if (isGlobal) {
-                // Set RateLimitData based on the global limit
-                limit = this.manager.options.globalRequestsPerSecond;
-                timeout = this.manager.globalReset + this.manager.options.offset - Date.now();
-            }
-            else {
-                // Set RateLimitData based on the route-specific limit
-                limit = this.limit;
-                timeout = this.timeToReset;
-            }
-            await (0, utils_js_1.onRateLimit)(this.manager, {
-                global: isGlobal,
-                method,
-                url,
-                route: routeId.bucketRoute,
-                majorParameter: this.majorParameter,
-                hash: this.hash,
-                limit,
-                timeToReset: timeout,
-                retryAfter,
-                sublimitTimeout: sublimitTimeout ?? 0,
-                scope,
-            });
-            this.debug([
-                'Encountered unexpected 429 rate limit',
-                `  Global         : ${isGlobal.toString()}`,
-                `  Method         : ${method}`,
-                `  URL            : ${url}`,
-                `  Bucket         : ${routeId.bucketRoute}`,
-                `  Major parameter: ${routeId.majorParameter}`,
-                `  Hash           : ${this.hash}`,
-                `  Limit          : ${limit}`,
-                `  Retry After    : ${retryAfter}ms`,
-                `  Sublimit       : ${sublimitTimeout ? `${sublimitTimeout}ms` : 'None'}`,
-                `  Scope          : ${scope}`,
-            ].join('\n'));
-            // If caused by a sublimit, wait it out here so other requests on the route can be handled
-            if (sublimitTimeout) {
-                // Normally the sublimit queue will not exist, however, if a sublimit is hit while in the sublimit queue, it will
-                const firstSublimit = !this.#sublimitedQueue;
-                if (firstSublimit) {
-                    this.#sublimitedQueue = new async_queue_1.AsyncQueue();
-                    void this.#sublimitedQueue.wait();
-                    this.#asyncQueue.shift();
-                }
-                this.#sublimitPromise?.resolve();
-                this.#sublimitPromise = null;
-                await (0, utils_js_1.sleep)(sublimitTimeout);
-                let resolve;
-                // eslint-disable-next-line promise/param-names, no-promise-executor-return
-                const promise = new Promise(res => (resolve = res));
-                this.#sublimitPromise = { promise, resolve: resolve };
-                if (firstSublimit) {
-                    // Re-queue this request so it can be shifted by the finally
-                    await this.#asyncQueue.wait();
-                    this.#shiftSublimit = true;
-                }
-            }
-            // Since this is not a server side issue, the next request should pass, so we don't bump the retries counter
-            return this.runRequest(routeId, url, options, requestData, retries);
-        }
-        const handled = await (0, Shared_js_1.handleErrors)(this.manager, res, method, url, requestData, retries);
-        if (handled === null) {
-            // eslint-disable-next-line no-param-reassign
-            return this.runRequest(routeId, url, options, requestData, ++retries);
-        }
-        return handled;
-    }
-}
-exports.SequentialHandler = SequentialHandler;

package/lib/api/handlers/Shared.d.ts

@@ -1,14 +0,0 @@
-import type { REST } from '../REST.js';
-import type { HandlerRequestData, ResponseLike } from '../utils/types.js';
-/**
- * Handles 5xx and 4xx errors (not 429's) conventionally. 429's should be handled before calling this function
- *
- * @param manager - The manager that holds options and emits informational events
- * @param res - The response received from {@link makeNetworkRequest}
- * @param method - The method used to make the request
- * @param url - The fully resolved url to make the request to
- * @param requestData - Extra data from the user's request needed for errors and additional processing
- * @param retries - The number of retries this request has already attempted (recursion occurs on the handler)
- * @returns The response if the status code is not handled or null to request a retry
- */
-export declare function handleErrors(manager: REST, res: ResponseLike, method: string, url: string, requestData: HandlerRequestData, retries: number): Promise<ResponseLike | null>;