reqon-dsl 0.2.0

package/dist/auth/oauth2-provider.js

@@ -0,0 +1,131 @@
+/**
+ * OAuth2 auth provider with automatic token refresh
+ */
+export class OAuth2AuthProvider {
+    connectionId;
+    store;
+    config;
+    refreshBuffer;
+    refreshPromise = null;
+    constructor(options) {
+        this.connectionId = options.connectionId;
+        this.store = options.store;
+        this.config = options.config;
+        this.refreshBuffer = (options.config.refreshBuffer ?? 300) * 1000; // Convert to ms
+    }
+    async getToken() {
+        const tokens = await this.store.get(this.connectionId);
+        if (!tokens) {
+            throw new Error(`No tokens found for connection: ${this.connectionId}`);
+        }
+        // Check if we need to refresh
+        if (this.shouldRefresh(tokens)) {
+            return this.refreshToken();
+        }
+        // Update last used time
+        await this.store.touch(this.connectionId);
+        return tokens.accessToken;
+    }
+    async refreshToken() {
+        // Deduplicate concurrent refresh requests
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.doRefresh();
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async doRefresh() {
+        const tokens = await this.store.get(this.connectionId);
+        if (!tokens?.refreshToken) {
+            throw new Error(`No refresh token available for connection: ${this.connectionId}`);
+        }
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: tokens.refreshToken,
+            client_id: this.config.clientId,
+        });
+        if (this.config.clientSecret) {
+            body.set('client_secret', this.config.clientSecret);
+        }
+        const response = await fetch(this.config.tokenEndpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Token refresh failed: ${response.status} ${error}`);
+        }
+        const data = (await response.json());
+        const newTokens = {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token ?? tokens.refreshToken, // Keep old if not rotated
+            tokenType: data.token_type ?? 'Bearer',
+            scope: data.scope,
+        };
+        // Calculate expiry
+        if (data.expires_in) {
+            newTokens.expiresAt = new Date(Date.now() + data.expires_in * 1000);
+        }
+        await this.store.set(this.connectionId, newTokens);
+        await this.store.touch(this.connectionId);
+        return newTokens.accessToken;
+    }
+    shouldRefresh(tokens) {
+        if (!tokens.expiresAt) {
+            return false; // No expiry info, assume valid
+        }
+        const now = Date.now();
+        const expiresAt = tokens.expiresAt.getTime();
+        // Refresh if within buffer of expiry
+        return expiresAt - now < this.refreshBuffer;
+    }
+    getTokenInfo() {
+        // Synchronous - returns cached info
+        return {
+            connectionId: this.connectionId,
+        };
+    }
+}
+/**
+ * Simple bearer token provider (no refresh)
+ */
+export class BearerTokenProvider {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+    async getToken() {
+        return this.token;
+    }
+    getTokenInfo() {
+        return {};
+    }
+}
+/**
+ * API key provider
+ */
+export class ApiKeyProvider {
+    apiKey;
+    headerName;
+    constructor(apiKey, headerName = 'X-API-Key') {
+        this.apiKey = apiKey;
+        this.headerName = headerName;
+    }
+    async getToken() {
+        return this.apiKey;
+    }
+    getHeaderName() {
+        return this.headerName;
+    }
+    getTokenInfo() {
+        return {};
+    }
+}

package/dist/auth/rate-limiter.d.ts

@@ -0,0 +1,61 @@
+import type { RateLimiter, RateLimitInfo, RateLimitStatus, RateLimitConfig, RateLimitCallbacks } from './types.js';
+/**
+ * Rate limit timeout error - thrown when maxWait is exceeded
+ */
+export declare class RateLimitTimeoutError extends Error {
+    source: string;
+    waitedSeconds: number;
+    maxWait: number;
+    constructor(source: string, waitedSeconds: number, maxWait: number);
+}
+/**
+ * Rate limit error - thrown when strategy is 'fail'
+ */
+export declare class RateLimitError extends Error {
+    source: string;
+    resetAt?: Date | undefined;
+    constructor(source: string, resetAt?: Date | undefined);
+}
+export declare class AdaptiveRateLimiter implements RateLimiter {
+    private defaultConfig;
+    private state;
+    private configs;
+    private callbacks;
+    private lastCleanup;
+    private maxStaleAgeMs;
+    private responsesSinceCleanup;
+    constructor(defaultConfig?: Partial<RateLimitConfig>, options?: {
+        maxStaleAgeMs?: number;
+    });
+    /**
+     * Clean up stale entries from the state map to prevent memory leaks
+     */
+    private cleanup;
+    /**
+     * Get the number of tracked endpoints (for monitoring)
+     */
+    getTrackedEndpointCount(): number;
+    /**
+     * Force cleanup of stale entries
+     */
+    forceCleanup(): void;
+    private getKey;
+    private getConfig;
+    configure(source: string, config: RateLimitConfig): void;
+    setCallbacks(callbacks: RateLimitCallbacks): void;
+    canProceed(source: string, endpoint?: string): Promise<boolean>;
+    waitForCapacity(source: string, endpoint?: string): Promise<void>;
+    getThrottleDelay(source: string, endpoint?: string): number;
+    recordResponse(source: string, info: RateLimitInfo, endpoint?: string): void;
+    getStatus(source: string, endpoint?: string): RateLimitStatus;
+}
+/**
+ * Parse rate limit info from HTTP response headers
+ *
+ * Supports common header patterns:
+ * - X-RateLimit-Remaining, X-RateLimit-Limit, X-RateLimit-Reset
+ * - RateLimit-Remaining, RateLimit-Limit, RateLimit-Reset
+ * - X-Rate-Limit-Remaining, etc.
+ * - Retry-After (from 429 responses)
+ */
+export declare function parseRateLimitHeaders(headers: Record<string, string>): RateLimitInfo;

package/dist/auth/rate-limiter.js

@@ -0,0 +1,380 @@
+import { sleep } from '../utils/async.js';
+/** Max age for stale entries (default: 1 hour) */
+const DEFAULT_MAX_STALE_AGE_MS = 60 * 60 * 1000;
+/** Cleanup interval (default: 5 minutes) */
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+/** Max number of entries before forced cleanup */
+const MAX_ENTRIES_BEFORE_CLEANUP = 1000;
+const DEFAULT_CONFIG = {
+    strategy: 'pause',
+    maxWait: 300,
+    notifyAt: 10,
+    fallbackRpm: 60,
+};
+/**
+ * Rate limit timeout error - thrown when maxWait is exceeded
+ */
+export class RateLimitTimeoutError extends Error {
+    source;
+    waitedSeconds;
+    maxWait;
+    constructor(source, waitedSeconds, maxWait) {
+        super(`Rate limit timeout: waited ${waitedSeconds}s (max: ${maxWait}s) for ${source}`);
+        this.source = source;
+        this.waitedSeconds = waitedSeconds;
+        this.maxWait = maxWait;
+        this.name = 'RateLimitTimeoutError';
+    }
+}
+/**
+ * Rate limit error - thrown when strategy is 'fail'
+ */
+export class RateLimitError extends Error {
+    source;
+    resetAt;
+    constructor(source, resetAt) {
+        const resetIn = resetAt ? Math.ceil((resetAt.getTime() - Date.now()) / 1000) : undefined;
+        super(`Rate limited on ${source}${resetIn ? ` - resets in ${resetIn}s` : ''}`);
+        this.source = source;
+        this.resetAt = resetAt;
+        this.name = 'RateLimitError';
+    }
+}
+/**
+ * Adaptive rate limiter that learns from response headers
+ * Supports pause, throttle, and fail strategies
+ */
+/** Number of responses between cleanup checks */
+const CLEANUP_CHECK_INTERVAL = 100;
+export class AdaptiveRateLimiter {
+    defaultConfig;
+    state = new Map();
+    configs = new Map();
+    callbacks = {};
+    lastCleanup = Date.now();
+    maxStaleAgeMs;
+    responsesSinceCleanup = 0;
+    constructor(defaultConfig = {}, options = {}) {
+        this.defaultConfig = defaultConfig;
+        this.maxStaleAgeMs = options.maxStaleAgeMs ?? DEFAULT_MAX_STALE_AGE_MS;
+    }
+    /**
+     * Clean up stale entries from the state map to prevent memory leaks
+     */
+    cleanup() {
+        const now = Date.now();
+        // Skip if cleanup was done recently and we're under the entry limit
+        if (now - this.lastCleanup < CLEANUP_INTERVAL_MS &&
+            this.state.size < MAX_ENTRIES_BEFORE_CLEANUP) {
+            return;
+        }
+        this.lastCleanup = now;
+        const nowDate = new Date(now);
+        const staleThreshold = new Date(now - this.maxStaleAgeMs);
+        for (const [key, state] of this.state) {
+            // Remove if:
+            // 1. Reset time has passed AND no recent requests
+            // 2. Last request is older than max stale age
+            const isResetPassed = state.resetAt && state.resetAt < nowDate;
+            const isRetryPassed = !state.retryAfter || state.retryAfter < nowDate;
+            const isStale = state.lastRequestAt && state.lastRequestAt < staleThreshold;
+            if ((isResetPassed && isRetryPassed && isStale) || (!state.lastRequestAt && isResetPassed)) {
+                this.state.delete(key);
+            }
+        }
+    }
+    /**
+     * Get the number of tracked endpoints (for monitoring)
+     */
+    getTrackedEndpointCount() {
+        return this.state.size;
+    }
+    /**
+     * Force cleanup of stale entries
+     */
+    forceCleanup() {
+        this.lastCleanup = 0;
+        this.cleanup();
+    }
+    getKey(source, endpoint) {
+        return endpoint ? `${source}:${endpoint}` : source;
+    }
+    getConfig(source) {
+        const sourceConfig = this.configs.get(source) ?? {};
+        return { ...DEFAULT_CONFIG, ...this.defaultConfig, ...sourceConfig };
+    }
+    configure(source, config) {
+        this.configs.set(source, config);
+    }
+    setCallbacks(callbacks) {
+        this.callbacks = callbacks;
+    }
+    async canProceed(source, endpoint) {
+        const key = this.getKey(source, endpoint);
+        const state = this.state.get(key);
+        if (!state)
+            return true;
+        const now = new Date();
+        // Check retry-after (from 429)
+        if (state.retryAfter && state.retryAfter > now) {
+            return false;
+        }
+        // Check if we've reset
+        if (state.resetAt && state.resetAt <= now) {
+            // Reset has passed, clear the limit
+            this.state.delete(key);
+            return true;
+        }
+        // Check remaining quota
+        if (state.remaining !== undefined && state.remaining <= 0) {
+            return false;
+        }
+        return true;
+    }
+    async waitForCapacity(source, endpoint) {
+        const config = this.getConfig(source);
+        const key = this.getKey(source, endpoint);
+        // Check if we can proceed immediately
+        if (await this.canProceed(source, endpoint)) {
+            // In throttle mode, add delay between requests
+            if (config.strategy === 'throttle') {
+                const delay = this.getThrottleDelay(source, endpoint);
+                if (delay > 0) {
+                    await sleep(delay);
+                }
+            }
+            return;
+        }
+        // We're rate limited
+        const state = this.state.get(key);
+        const now = Date.now();
+        // Calculate wait time
+        let waitUntil;
+        if (state?.retryAfter) {
+            waitUntil = state.retryAfter;
+        }
+        else if (state?.resetAt) {
+            waitUntil = state.resetAt;
+        }
+        else {
+            // No reset info, use fallback
+            waitUntil = new Date(now + 60000);
+        }
+        const totalWaitMs = waitUntil.getTime() - now;
+        const totalWaitSeconds = Math.ceil(totalWaitMs / 1000);
+        // Check strategy
+        if (config.strategy === 'fail') {
+            throw new RateLimitError(source, state?.resetAt);
+        }
+        // Check if wait exceeds max
+        if (totalWaitSeconds > config.maxWait) {
+            throw new RateLimitTimeoutError(source, 0, config.maxWait);
+        }
+        // Emit rate limited event
+        const event = {
+            source,
+            endpoint,
+            waitSeconds: totalWaitSeconds,
+            remaining: state?.remaining,
+            resetAt: state?.resetAt,
+            strategy: config.strategy,
+        };
+        this.callbacks.onRateLimited?.(event);
+        // Wait with periodic updates
+        const startTime = Date.now();
+        let lastNotify = 0;
+        while (!(await this.canProceed(source, endpoint))) {
+            const elapsed = Math.floor((Date.now() - startTime) / 1000);
+            // Check timeout
+            if (elapsed >= config.maxWait) {
+                throw new RateLimitTimeoutError(source, elapsed, config.maxWait);
+            }
+            // Periodic notification
+            if (elapsed >= config.notifyAt && elapsed - lastNotify >= 10) {
+                lastNotify = elapsed;
+                this.callbacks.onWaiting?.({
+                    ...event,
+                    elapsedSeconds: elapsed,
+                    waitSeconds: Math.max(0, totalWaitSeconds - elapsed),
+                });
+            }
+            // Sleep in chunks (check every 1-5 seconds)
+            const remainingMs = waitUntil.getTime() - Date.now();
+            const sleepMs = Math.min(Math.max(remainingMs, 1000), 5000);
+            await sleep(sleepMs);
+        }
+        // Emit resumed event
+        const waitedSeconds = Math.floor((Date.now() - startTime) / 1000);
+        this.callbacks.onResumed?.({ source, endpoint, waitedSeconds });
+    }
+    getThrottleDelay(source, endpoint) {
+        const key = this.getKey(source, endpoint);
+        const state = this.state.get(key);
+        const config = this.getConfig(source);
+        if (config.strategy !== 'throttle')
+            return 0;
+        if (!state)
+            return 0;
+        const now = Date.now();
+        // If we have remaining count and reset time, calculate optimal spacing
+        if (state.remaining !== undefined &&
+            state.remaining > 0 &&
+            state.resetAt &&
+            state.resetAt.getTime() > now) {
+            const msUntilReset = state.resetAt.getTime() - now;
+            // Space requests evenly across remaining time
+            const optimalInterval = msUntilReset / state.remaining;
+            // Check time since last request
+            if (state.lastRequestAt) {
+                const msSinceLastRequest = now - state.lastRequestAt.getTime();
+                const delay = Math.max(0, optimalInterval - msSinceLastRequest);
+                return Math.round(delay);
+            }
+            return Math.round(optimalInterval);
+        }
+        // Fallback: use configured RPM
+        const intervalMs = 60000 / config.fallbackRpm;
+        if (state.lastRequestAt) {
+            const msSinceLastRequest = now - state.lastRequestAt.getTime();
+            return Math.max(0, Math.round(intervalMs - msSinceLastRequest));
+        }
+        return 0;
+    }
+    recordResponse(source, info, endpoint) {
+        const key = this.getKey(source, endpoint);
+        const now = new Date();
+        const state = this.state.get(key) ?? {};
+        if (info.remaining !== undefined) {
+            state.remaining = info.remaining;
+        }
+        if (info.limit !== undefined) {
+            state.limit = info.limit;
+        }
+        if (info.resetAt) {
+            state.resetAt = info.resetAt;
+        }
+        if (info.retryAfter !== undefined) {
+            state.retryAfter = new Date(now.getTime() + info.retryAfter * 1000);
+        }
+        state.lastRequestAt = now;
+        this.state.set(key, state);
+        // Periodically clean up stale entries (every N responses)
+        this.responsesSinceCleanup++;
+        if (this.responsesSinceCleanup >= CLEANUP_CHECK_INTERVAL) {
+            this.responsesSinceCleanup = 0;
+            this.cleanup();
+        }
+    }
+    getStatus(source, endpoint) {
+        const key = this.getKey(source, endpoint);
+        const state = this.state.get(key);
+        const now = new Date();
+        if (!state) {
+            return { isLimited: false };
+        }
+        const isLimited = (state.retryAfter && state.retryAfter > now) ||
+            (state.remaining !== undefined && state.remaining <= 0 && state.resetAt && state.resetAt > now);
+        let resetInSeconds;
+        if (isLimited && state.resetAt) {
+            resetInSeconds = Math.ceil((state.resetAt.getTime() - now.getTime()) / 1000);
+        }
+        else if (isLimited && state.retryAfter) {
+            resetInSeconds = Math.ceil((state.retryAfter.getTime() - now.getTime()) / 1000);
+        }
+        return {
+            remaining: state.remaining,
+            limit: state.limit,
+            resetAt: state.resetAt,
+            isLimited: Boolean(isLimited),
+            resetInSeconds,
+        };
+    }
+}
+/**
+ * Parse rate limit info from HTTP response headers
+ *
+ * Supports common header patterns:
+ * - X-RateLimit-Remaining, X-RateLimit-Limit, X-RateLimit-Reset
+ * - RateLimit-Remaining, RateLimit-Limit, RateLimit-Reset
+ * - X-Rate-Limit-Remaining, etc.
+ * - Retry-After (from 429 responses)
+ */
+export function parseRateLimitHeaders(headers) {
+    const info = {};
+    // Normalize headers to lowercase for matching
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        normalized[key.toLowerCase()] = value;
+    }
+    // Parse remaining
+    const remainingKey = findHeader(normalized, [
+        'x-ratelimit-remaining',
+        'ratelimit-remaining',
+        'x-rate-limit-remaining',
+    ]);
+    if (remainingKey) {
+        info.remaining = parseInt(normalized[remainingKey], 10);
+    }
+    // Parse limit
+    const limitKey = findHeader(normalized, [
+        'x-ratelimit-limit',
+        'ratelimit-limit',
+        'x-rate-limit-limit',
+    ]);
+    if (limitKey) {
+        info.limit = parseInt(normalized[limitKey], 10);
+    }
+    // Parse reset
+    const resetKey = findHeader(normalized, [
+        'x-ratelimit-reset',
+        'ratelimit-reset',
+        'x-rate-limit-reset',
+    ]);
+    if (resetKey) {
+        const resetValue = normalized[resetKey];
+        // Could be Unix timestamp or ISO date
+        const asNumber = parseInt(resetValue, 10);
+        if (!isNaN(asNumber)) {
+            // Unix timestamp (seconds)
+            if (asNumber > 1000000000000) {
+                // Already in milliseconds
+                info.resetAt = new Date(asNumber);
+            }
+            else {
+                // In seconds
+                info.resetAt = new Date(asNumber * 1000);
+            }
+        }
+        else {
+            // Try as date string
+            const parsed = new Date(resetValue);
+            if (!isNaN(parsed.getTime())) {
+                info.resetAt = parsed;
+            }
+        }
+    }
+    // Parse Retry-After (usually from 429 responses)
+    const retryAfter = normalized['retry-after'];
+    if (retryAfter) {
+        const asNumber = parseInt(retryAfter, 10);
+        if (!isNaN(asNumber)) {
+            info.retryAfter = asNumber;
+        }
+        else {
+            // HTTP-date format
+            const parsed = new Date(retryAfter);
+            if (!isNaN(parsed.getTime())) {
+                info.retryAfter = Math.ceil((parsed.getTime() - Date.now()) / 1000);
+            }
+        }
+    }
+    return info;
+}
+function findHeader(headers, candidates) {
+    for (const candidate of candidates) {
+        if (candidate in headers) {
+            return candidate;
+        }
+    }
+    return undefined;
+}

package/dist/auth/token-store.d.ts

@@ -0,0 +1,30 @@
+import type { TokenStore, OAuth2Tokens } from './types.js';
+/**
+ * In-memory token store - useful for development and single-process deployments
+ */
+export declare class InMemoryTokenStore implements TokenStore {
+    private tokens;
+    get(connectionId: string): Promise<OAuth2Tokens | null>;
+    set(connectionId: string, tokens: OAuth2Tokens): Promise<void>;
+    delete(connectionId: string): Promise<void>;
+    touch(connectionId: string): Promise<void>;
+    list(): Promise<string[]>;
+    /** Get tokens that need proactive refresh (approaching expiry or non-use expiry) */
+    getTokensNeedingRefresh(bufferSeconds?: number): Promise<string[]>;
+}
+/**
+ * File-based token store - persists tokens to a JSON file
+ * Suitable for CLI tools and single-user scenarios
+ */
+export declare class FileTokenStore implements TokenStore {
+    private filePath;
+    private cache;
+    constructor(filePath: string);
+    private load;
+    private save;
+    get(connectionId: string): Promise<OAuth2Tokens | null>;
+    set(connectionId: string, tokens: OAuth2Tokens): Promise<void>;
+    delete(connectionId: string): Promise<void>;
+    touch(connectionId: string): Promise<void>;
+    list(): Promise<string[]>;
+}