@trentapps/manager-protocol 1.1.3 → 1.2.0

package/dist/utils/rate-limiting.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Enterprise Agent Supervisor - Rate Limiting Utilities
+ *
+ * Reusable utilities for rate limiting:
+ * - Bucket key building for different scopes
+ * - Sliding window time-based tracking
+ */
+/**
+ * Scope types for rate limit bucket keys
+ */
+export type BucketScope = 'global' | 'agent' | 'session' | 'user' | 'action_type';
+/**
+ * Identifiers used to build bucket keys
+ */
+export interface BucketIdentifiers {
+    agentId?: string;
+    sessionId?: string;
+    userId?: string;
+    actionType?: string;
+}
+/**
+ * Window algorithm types
+ */
+export type WindowAlgorithm = 'fixed' | 'sliding';
+/**
+ * Statistics for a time window
+ */
+export interface WindowStats {
+    /** Number of requests in the current window */
+    count: number;
+    /** Number of requests remaining before limit */
+    remaining: number;
+    /** Timestamp when the window started (ms since epoch) */
+    windowStart: number;
+    /** Timestamp when the window resets (ms since epoch) */
+    resetAt: number;
+    /** ISO string of reset time */
+    resetAtISO: string;
+    /** Whether the limit has been exceeded */
+    exceeded: boolean;
+    /** Percentage of limit used (0-100) */
+    usagePercent: number;
+}
+/**
+ * Configuration for SlidingWindow
+ */
+export interface SlidingWindowConfig {
+    /** Window duration in milliseconds */
+    windowMs: number;
+    /** Maximum requests allowed in the window */
+    maxRequests: number;
+    /** Optional burst limit for short-term spikes */
+    burstLimit?: number;
+    /** Window algorithm: 'fixed' resets at boundaries, 'sliding' moves with time */
+    algorithm?: WindowAlgorithm;
+}
+/**
+ * Build a bucket key based on scope and identifiers.
+ *
+ * Key format: `{prefix}:{scope}:{identifier}`
+ *
+ * This creates consistent, collision-free keys for rate limit buckets.
+ *
+ * @param scope - The scope for the bucket (global, agent, session, user, action_type)
+ * @param identifiers - Object containing identifier values
+ * @param prefix - Optional prefix for namespacing (e.g., config ID)
+ * @returns A unique bucket key string
+ *
+ * @example
+ * ```typescript
+ * // Global scope
+ * buildBucketKey('global', {}) // "global"
+ * buildBucketKey('global', {}, 'rate-1') // "rate-1:global"
+ *
+ * // Agent scope
+ * buildBucketKey('agent', { agentId: 'agent-123' }) // "agent:agent-123"
+ *
+ * // Session scope with prefix
+ * buildBucketKey('session', { sessionId: 'sess-456' }, 'api-limit')
+ * // "api-limit:session:sess-456"
+ * ```
+ */
+export declare function buildBucketKey(scope: BucketScope, identifiers: BucketIdentifiers, prefix?: string): string;
+/**
+ * Parse a bucket key to extract scope and identifier.
+ *
+ * @param key - The bucket key to parse
+ * @returns Object with scope and identifier, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseBucketKey('rate-1:agent:agent-123')
+ * // { prefix: 'rate-1', scope: 'agent', identifier: 'agent-123' }
+ *
+ * parseBucketKey('global')
+ * // { prefix: undefined, scope: 'global', identifier: undefined }
+ * ```
+ */
+export declare function parseBucketKey(key: string): {
+    prefix?: string;
+    scope: BucketScope | 'unknown';
+    identifier?: string;
+} | null;
+/**
+ * SlidingWindow class for time-based window tracking.
+ *
+ * Supports both fixed and sliding window algorithms:
+ * - Fixed: Window resets at fixed boundaries (simpler, less memory)
+ * - Sliding: Window slides with time (more accurate, tracks individual requests)
+ *
+ * @example
+ * ```typescript
+ * // Create a window: 100 requests per minute
+ * const window = new SlidingWindow({
+ *   windowMs: 60000,
+ *   maxRequests: 100,
+ *   algorithm: 'fixed'
+ * });
+ *
+ * // Check and record a request
+ * if (window.canAccept()) {
+ *   window.record();
+ *   // Process request
+ * } else {
+ *   // Rate limited
+ *   const stats = window.getStats();
+ *   console.log(`Retry after ${stats.resetAt}`);
+ * }
+ * ```
+ */
+export declare class SlidingWindow {
+    private config;
+    private count;
+    private burstCount;
+    private windowStart;
+    private requestTimestamps;
+    constructor(config: SlidingWindowConfig);
+    /**
+     * Check if the window has expired and needs reset.
+     *
+     * For fixed windows: Checks if current time is past window boundary.
+     * For sliding windows: Always returns false (sliding handles this differently).
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Whether the window has expired
+     */
+    isExpired(now?: number): boolean;
+    /**
+     * Reset the window to initial state.
+     *
+     * @param now - Timestamp to use as new window start (defaults to Date.now())
+     */
+    reset(now?: number): void;
+    /**
+     * Check if the window can accept another request.
+     * Automatically resets expired windows (for fixed algorithm).
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Whether a request can be accepted
+     */
+    canAccept(now?: number): boolean;
+    /**
+     * Check if the window can accept based on burst limit only.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Whether burst limit allows acceptance
+     */
+    canAcceptBurst(now?: number): boolean;
+    /**
+     * Record a request in the window.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     */
+    record(now?: number): void;
+    /**
+     * Get current window statistics.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns WindowStats object with current state
+     */
+    getStats(now?: number): WindowStats;
+    /**
+     * Get the current count of requests in the window.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Current request count
+     */
+    getCount(now?: number): number;
+    /**
+     * Get remaining requests before limit is hit.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Number of remaining requests
+     */
+    getRemaining(now?: number): number;
+    /**
+     * Get timestamp when the window resets.
+     *
+     * @returns Reset timestamp in milliseconds since epoch
+     */
+    getResetTime(): number;
+    /**
+     * Get the window configuration.
+     *
+     * @returns The window configuration
+     */
+    getConfig(): Required<SlidingWindowConfig>;
+    /**
+     * Set internal state (useful for persistence/restoration).
+     *
+     * @param state - State to restore
+     */
+    setState(state: {
+        count: number;
+        windowStart: number;
+        burstCount?: number;
+    }): void;
+    /**
+     * Get internal state (useful for persistence).
+     *
+     * @returns Current internal state
+     */
+    getState(): {
+        count: number;
+        windowStart: number;
+        burstCount: number;
+    };
+    private maybeResetWindow;
+    private getSlidingCount;
+    private cleanupOldTimestamps;
+}
+/**
+ * Create a sliding window with common presets.
+ *
+ * @param preset - Preset name
+ * @returns Configured SlidingWindow
+ *
+ * @example
+ * ```typescript
+ * // 60 requests per minute
+ * const perMinute = createWindowPreset('per-minute');
+ *
+ * // 1000 requests per hour
+ * const perHour = createWindowPreset('per-hour');
+ * ```
+ */
+export declare function createWindowPreset(preset: 'per-second' | 'per-minute' | 'per-hour' | 'per-day'): SlidingWindow;
+/**
+ * Create multiple bucket keys for different scopes from the same identifiers.
+ *
+ * @param identifiers - Identifiers to use
+ * @param prefix - Optional prefix for all keys
+ * @returns Object with keys for each scope
+ *
+ * @example
+ * ```typescript
+ * const keys = createBucketKeys({ agentId: 'a1', userId: 'u1' }, 'rate');
+ * // {
+ * //   global: 'rate:global',
+ * //   agent: 'rate:agent:a1',
+ * //   user: 'rate:user:u1',
+ * //   session: 'rate:session:unknown',
+ * //   action_type: 'rate:action:unknown'
+ * // }
+ * ```
+ */
+export declare function createBucketKeys(identifiers: BucketIdentifiers, prefix?: string): Record<BucketScope, string>;
+//# sourceMappingURL=rate-limiting.d.ts.map

package/dist/utils/rate-limiting.d.ts.map

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

package/dist/utils/rate-limiting.js

@@ -0,0 +1,403 @@
+/**
+ * Enterprise Agent Supervisor - Rate Limiting Utilities
+ *
+ * Reusable utilities for rate limiting:
+ * - Bucket key building for different scopes
+ * - Sliding window time-based tracking
+ */
+// ============================================================================
+// BUCKET KEY BUILDING
+// ============================================================================
+/**
+ * Separator used in bucket keys to prevent collisions
+ */
+const KEY_SEPARATOR = ':';
+/**
+ * Default identifier when none is provided
+ */
+const DEFAULT_IDENTIFIER = 'unknown';
+/**
+ * Build a bucket key based on scope and identifiers.
+ *
+ * Key format: `{prefix}:{scope}:{identifier}`
+ *
+ * This creates consistent, collision-free keys for rate limit buckets.
+ *
+ * @param scope - The scope for the bucket (global, agent, session, user, action_type)
+ * @param identifiers - Object containing identifier values
+ * @param prefix - Optional prefix for namespacing (e.g., config ID)
+ * @returns A unique bucket key string
+ *
+ * @example
+ * ```typescript
+ * // Global scope
+ * buildBucketKey('global', {}) // "global"
+ * buildBucketKey('global', {}, 'rate-1') // "rate-1:global"
+ *
+ * // Agent scope
+ * buildBucketKey('agent', { agentId: 'agent-123' }) // "agent:agent-123"
+ *
+ * // Session scope with prefix
+ * buildBucketKey('session', { sessionId: 'sess-456' }, 'api-limit')
+ * // "api-limit:session:sess-456"
+ * ```
+ */
+export function buildBucketKey(scope, identifiers, prefix) {
+    let key;
+    switch (scope) {
+        case 'global':
+            key = 'global';
+            break;
+        case 'agent':
+            key = `agent${KEY_SEPARATOR}${identifiers.agentId || DEFAULT_IDENTIFIER}`;
+            break;
+        case 'session':
+            key = `session${KEY_SEPARATOR}${identifiers.sessionId || DEFAULT_IDENTIFIER}`;
+            break;
+        case 'user':
+            key = `user${KEY_SEPARATOR}${identifiers.userId || DEFAULT_IDENTIFIER}`;
+            break;
+        case 'action_type':
+            key = `action${KEY_SEPARATOR}${identifiers.actionType || DEFAULT_IDENTIFIER}`;
+            break;
+        default:
+            key = 'unknown';
+    }
+    return prefix ? `${prefix}${KEY_SEPARATOR}${key}` : key;
+}
+/**
+ * Parse a bucket key to extract scope and identifier.
+ *
+ * @param key - The bucket key to parse
+ * @returns Object with scope and identifier, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseBucketKey('rate-1:agent:agent-123')
+ * // { prefix: 'rate-1', scope: 'agent', identifier: 'agent-123' }
+ *
+ * parseBucketKey('global')
+ * // { prefix: undefined, scope: 'global', identifier: undefined }
+ * ```
+ */
+export function parseBucketKey(key) {
+    if (!key)
+        return null;
+    const parts = key.split(KEY_SEPARATOR);
+    // Handle simple global key
+    if (parts.length === 1 && parts[0] === 'global') {
+        return { scope: 'global' };
+    }
+    // Handle keys without prefix: "scope:identifier"
+    if (parts.length === 2) {
+        const scopeMap = {
+            'agent': 'agent',
+            'session': 'session',
+            'user': 'user',
+            'action': 'action_type'
+        };
+        const scope = scopeMap[parts[0]];
+        if (scope) {
+            return { scope, identifier: parts[1] };
+        }
+    }
+    // Handle keys with prefix: "prefix:scope:identifier" or "prefix:global"
+    if (parts.length >= 2) {
+        const prefix = parts[0];
+        const scopePart = parts[1];
+        if (scopePart === 'global') {
+            return { prefix, scope: 'global' };
+        }
+        const scopeMap = {
+            'agent': 'agent',
+            'session': 'session',
+            'user': 'user',
+            'action': 'action_type'
+        };
+        const scope = scopeMap[scopePart];
+        if (scope && parts.length >= 3) {
+            return { prefix, scope, identifier: parts.slice(2).join(KEY_SEPARATOR) };
+        }
+    }
+    return { scope: 'unknown' };
+}
+// ============================================================================
+// SLIDING WINDOW
+// ============================================================================
+/**
+ * SlidingWindow class for time-based window tracking.
+ *
+ * Supports both fixed and sliding window algorithms:
+ * - Fixed: Window resets at fixed boundaries (simpler, less memory)
+ * - Sliding: Window slides with time (more accurate, tracks individual requests)
+ *
+ * @example
+ * ```typescript
+ * // Create a window: 100 requests per minute
+ * const window = new SlidingWindow({
+ *   windowMs: 60000,
+ *   maxRequests: 100,
+ *   algorithm: 'fixed'
+ * });
+ *
+ * // Check and record a request
+ * if (window.canAccept()) {
+ *   window.record();
+ *   // Process request
+ * } else {
+ *   // Rate limited
+ *   const stats = window.getStats();
+ *   console.log(`Retry after ${stats.resetAt}`);
+ * }
+ * ```
+ */
+export class SlidingWindow {
+    config;
+    // Fixed window state
+    count = 0;
+    burstCount = 0;
+    windowStart;
+    // Sliding window state (for sliding algorithm)
+    requestTimestamps = [];
+    constructor(config) {
+        this.config = {
+            windowMs: config.windowMs,
+            maxRequests: config.maxRequests,
+            burstLimit: config.burstLimit ?? config.maxRequests,
+            algorithm: config.algorithm ?? 'fixed'
+        };
+        this.windowStart = Date.now();
+    }
+    /**
+     * Check if the window has expired and needs reset.
+     *
+     * For fixed windows: Checks if current time is past window boundary.
+     * For sliding windows: Always returns false (sliding handles this differently).
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Whether the window has expired
+     */
+    isExpired(now = Date.now()) {
+        if (this.config.algorithm === 'sliding') {
+            return false; // Sliding windows don't expire in the same way
+        }
+        // Fixed window: expired when now - windowStart >= windowMs
+        return now - this.windowStart >= this.config.windowMs;
+    }
+    /**
+     * Reset the window to initial state.
+     *
+     * @param now - Timestamp to use as new window start (defaults to Date.now())
+     */
+    reset(now = Date.now()) {
+        this.count = 0;
+        this.burstCount = 0;
+        this.windowStart = now;
+        this.requestTimestamps = [];
+    }
+    /**
+     * Check if the window can accept another request.
+     * Automatically resets expired windows (for fixed algorithm).
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Whether a request can be accepted
+     */
+    canAccept(now = Date.now()) {
+        this.maybeResetWindow(now);
+        if (this.config.algorithm === 'sliding') {
+            return this.getSlidingCount(now) < this.config.maxRequests;
+        }
+        // Fixed window
+        if (this.count >= this.config.maxRequests) {
+            return false;
+        }
+        if (this.burstCount >= this.config.burstLimit) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Check if the window can accept based on burst limit only.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Whether burst limit allows acceptance
+     */
+    canAcceptBurst(now = Date.now()) {
+        this.maybeResetWindow(now);
+        if (this.config.algorithm === 'sliding') {
+            // For sliding, burst is same as regular limit
+            return this.getSlidingCount(now) < this.config.burstLimit;
+        }
+        return this.burstCount < this.config.burstLimit;
+    }
+    /**
+     * Record a request in the window.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     */
+    record(now = Date.now()) {
+        this.maybeResetWindow(now);
+        if (this.config.algorithm === 'sliding') {
+            this.requestTimestamps.push(now);
+            // Clean up old timestamps to prevent memory growth
+            this.cleanupOldTimestamps(now);
+        }
+        else {
+            this.count++;
+            this.burstCount++;
+        }
+    }
+    /**
+     * Get current window statistics.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns WindowStats object with current state
+     */
+    getStats(now = Date.now()) {
+        this.maybeResetWindow(now);
+        const count = this.config.algorithm === 'sliding'
+            ? this.getSlidingCount(now)
+            : this.count;
+        const remaining = Math.max(0, this.config.maxRequests - count);
+        const resetAt = this.windowStart + this.config.windowMs;
+        return {
+            count,
+            remaining,
+            windowStart: this.windowStart,
+            resetAt,
+            resetAtISO: new Date(resetAt).toISOString(),
+            exceeded: count >= this.config.maxRequests,
+            usagePercent: Math.min(100, Math.round((count / this.config.maxRequests) * 100))
+        };
+    }
+    /**
+     * Get the current count of requests in the window.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Current request count
+     */
+    getCount(now = Date.now()) {
+        this.maybeResetWindow(now);
+        return this.config.algorithm === 'sliding'
+            ? this.getSlidingCount(now)
+            : this.count;
+    }
+    /**
+     * Get remaining requests before limit is hit.
+     *
+     * @param now - Current timestamp (defaults to Date.now())
+     * @returns Number of remaining requests
+     */
+    getRemaining(now = Date.now()) {
+        return Math.max(0, this.config.maxRequests - this.getCount(now));
+    }
+    /**
+     * Get timestamp when the window resets.
+     *
+     * @returns Reset timestamp in milliseconds since epoch
+     */
+    getResetTime() {
+        return this.windowStart + this.config.windowMs;
+    }
+    /**
+     * Get the window configuration.
+     *
+     * @returns The window configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Set internal state (useful for persistence/restoration).
+     *
+     * @param state - State to restore
+     */
+    setState(state) {
+        this.count = state.count;
+        this.windowStart = state.windowStart;
+        this.burstCount = state.burstCount ?? 0;
+    }
+    /**
+     * Get internal state (useful for persistence).
+     *
+     * @returns Current internal state
+     */
+    getState() {
+        return {
+            count: this.count,
+            windowStart: this.windowStart,
+            burstCount: this.burstCount
+        };
+    }
+    // Private methods
+    maybeResetWindow(now) {
+        if (this.config.algorithm === 'fixed' && this.isExpired(now)) {
+            this.reset(now);
+        }
+    }
+    getSlidingCount(now) {
+        const windowStart = now - this.config.windowMs;
+        return this.requestTimestamps.filter(ts => ts > windowStart).length;
+    }
+    cleanupOldTimestamps(now) {
+        const windowStart = now - this.config.windowMs;
+        // Keep only timestamps within the window plus a small buffer
+        this.requestTimestamps = this.requestTimestamps.filter(ts => ts > windowStart - 1000);
+    }
+}
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+/**
+ * Create a sliding window with common presets.
+ *
+ * @param preset - Preset name
+ * @returns Configured SlidingWindow
+ *
+ * @example
+ * ```typescript
+ * // 60 requests per minute
+ * const perMinute = createWindowPreset('per-minute');
+ *
+ * // 1000 requests per hour
+ * const perHour = createWindowPreset('per-hour');
+ * ```
+ */
+export function createWindowPreset(preset) {
+    const presets = {
+        'per-second': { windowMs: 1000, maxRequests: 10, algorithm: 'fixed' },
+        'per-minute': { windowMs: 60000, maxRequests: 60, algorithm: 'fixed' },
+        'per-hour': { windowMs: 3600000, maxRequests: 1000, algorithm: 'fixed' },
+        'per-day': { windowMs: 86400000, maxRequests: 10000, algorithm: 'fixed' }
+    };
+    return new SlidingWindow(presets[preset]);
+}
+/**
+ * Create multiple bucket keys for different scopes from the same identifiers.
+ *
+ * @param identifiers - Identifiers to use
+ * @param prefix - Optional prefix for all keys
+ * @returns Object with keys for each scope
+ *
+ * @example
+ * ```typescript
+ * const keys = createBucketKeys({ agentId: 'a1', userId: 'u1' }, 'rate');
+ * // {
+ * //   global: 'rate:global',
+ * //   agent: 'rate:agent:a1',
+ * //   user: 'rate:user:u1',
+ * //   session: 'rate:session:unknown',
+ * //   action_type: 'rate:action:unknown'
+ * // }
+ * ```
+ */
+export function createBucketKeys(identifiers, prefix) {
+    return {
+        global: buildBucketKey('global', identifiers, prefix),
+        agent: buildBucketKey('agent', identifiers, prefix),
+        session: buildBucketKey('session', identifiers, prefix),
+        user: buildBucketKey('user', identifiers, prefix),
+        action_type: buildBucketKey('action_type', identifiers, prefix)
+    };
+}
+//# sourceMappingURL=rate-limiting.js.map

package/dist/utils/rate-limiting.js.map

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