@cleocode/lafs-protocol 0.5.0 → 1.1.0

package/dist/src/shutdown/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * LAFS Graceful Shutdown Module
+ *
+ * Handles graceful shutdown of LAFS servers
+ */
+import { Server } from 'http';
+export interface GracefulShutdownConfig {
+    timeout?: number;
+    signals?: NodeJS.Signals[];
+    onShutdown?: () => Promise<void> | void;
+    onClose?: () => Promise<void> | void;
+}
+export interface ShutdownState {
+    isShuttingDown: boolean;
+    activeConnections: number;
+    shutdownStartTime?: Date;
+}
+/**
+ * Enable graceful shutdown for an HTTP server
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { gracefulShutdown } from '@cleocode/lafs-protocol/shutdown';
+ *
+ * const app = express();
+ * const server = app.listen(3000);
+ *
+ * gracefulShutdown(server, {
+ *   timeout: 30000,
+ *   signals: ['SIGTERM', 'SIGINT'],
+ *   onShutdown: async () => {
+ *     console.log('Shutting down...');
+ *     await db.close();
+ *   }
+ * });
+ * ```
+ */
+export declare function gracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
+/**
+ * Check if server is shutting down
+ */
+export declare function isShuttingDown(): boolean;
+/**
+ * Get shutdown state
+ */
+export declare function getShutdownState(): ShutdownState;
+/**
+ * Force immediate shutdown (emergency use only)
+ */
+export declare function forceShutdown(exitCode?: number): void;
+/**
+ * Middleware to reject requests during shutdown
+ *
+ * @example
+ * ```typescript
+ * app.use(shutdownMiddleware());
+ * ```
+ */
+export declare function shutdownMiddleware(): (req: any, res: any, next: any) => void;
+/**
+ * Wait for shutdown to complete
+ *
+ * @example
+ * ```typescript
+ * await waitForShutdown();
+ * ```
+ */
+export declare function waitForShutdown(): Promise<void>;

package/dist/src/shutdown/index.js

@@ -0,0 +1,160 @@
+/**
+ * LAFS Graceful Shutdown Module
+ *
+ * Handles graceful shutdown of LAFS servers
+ */
+const state = {
+    isShuttingDown: false,
+    activeConnections: 0
+};
+/**
+ * Enable graceful shutdown for an HTTP server
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { gracefulShutdown } from '@cleocode/lafs-protocol/shutdown';
+ *
+ * const app = express();
+ * const server = app.listen(3000);
+ *
+ * gracefulShutdown(server, {
+ *   timeout: 30000,
+ *   signals: ['SIGTERM', 'SIGINT'],
+ *   onShutdown: async () => {
+ *     console.log('Shutting down...');
+ *     await db.close();
+ *   }
+ * });
+ * ```
+ */
+export function gracefulShutdown(server, config = {}) {
+    const { timeout = 30000, signals = ['SIGTERM', 'SIGINT'], onShutdown, onClose } = config;
+    // Track active connections
+    server.on('connection', (socket) => {
+        if (state.isShuttingDown) {
+            socket.destroy();
+            return;
+        }
+        state.activeConnections++;
+        socket.on('close', () => {
+            state.activeConnections--;
+        });
+    });
+    // Handle shutdown signals
+    signals.forEach((signal) => {
+        process.on(signal, async () => {
+            console.log(`${signal} received, starting graceful shutdown...`);
+            await performShutdown(server, timeout, onShutdown, onClose);
+        });
+    });
+    // Handle uncaught errors
+    process.on('uncaughtException', async (error) => {
+        console.error('Uncaught exception:', error);
+        await performShutdown(server, timeout, onShutdown, onClose);
+    });
+    process.on('unhandledRejection', async (reason) => {
+        console.error('Unhandled rejection:', reason);
+        await performShutdown(server, timeout, onShutdown, onClose);
+    });
+}
+async function performShutdown(server, timeout, onShutdown, onClose) {
+    if (state.isShuttingDown) {
+        console.log('Shutdown already in progress...');
+        return;
+    }
+    state.isShuttingDown = true;
+    state.shutdownStartTime = new Date();
+    try {
+        // Call user shutdown handler
+        if (onShutdown) {
+            await Promise.race([
+                onShutdown(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Shutdown timeout')), timeout))
+            ]);
+        }
+        // Stop accepting new connections
+        server.close((err) => {
+            if (err) {
+                console.error('Error closing server:', err);
+            }
+            else {
+                console.log('Server closed');
+            }
+        });
+        // Wait for active connections to close
+        const startTime = Date.now();
+        while (state.activeConnections > 0 && Date.now() - startTime < timeout) {
+            console.log(`Waiting for ${state.activeConnections} connections to close...`);
+            await sleep(1000);
+        }
+        if (state.activeConnections > 0) {
+            console.warn(`Forcing shutdown with ${state.activeConnections} active connections`);
+        }
+        // Call user close handler
+        if (onClose) {
+            await onClose();
+        }
+        console.log('Graceful shutdown complete');
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Error during shutdown:', error);
+        process.exit(1);
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Check if server is shutting down
+ */
+export function isShuttingDown() {
+    return state.isShuttingDown;
+}
+/**
+ * Get shutdown state
+ */
+export function getShutdownState() {
+    return { ...state };
+}
+/**
+ * Force immediate shutdown (emergency use only)
+ */
+export function forceShutdown(exitCode = 1) {
+    console.log('Force shutting down...');
+    process.exit(exitCode);
+}
+/**
+ * Middleware to reject requests during shutdown
+ *
+ * @example
+ * ```typescript
+ * app.use(shutdownMiddleware());
+ * ```
+ */
+export function shutdownMiddleware() {
+    return (req, res, next) => {
+        if (state.isShuttingDown) {
+            res.status(503).json({
+                error: 'Service is shutting down',
+                status: 'unavailable'
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Wait for shutdown to complete
+ *
+ * @example
+ * ```typescript
+ * await waitForShutdown();
+ * ```
+ */
+export async function waitForShutdown() {
+    while (!state.isShuttingDown) {
+        await sleep(100);
+    }
+}

package/dist/src/tokenEstimator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * LAFS Token Estimator
+ *
+ * Provides character-based token estimation for LAFS envelopes and JSON payloads.
+ * Uses the approximation: 1 token ≈ 4 characters.
+ * Properly handles nested objects, arrays, Unicode graphemes, and circular references.
+ */
+export interface TokenEstimatorOptions {
+    /**
+     * Characters per token ratio (default: 4)
+     */
+    charsPerToken?: number;
+    /**
+     * Maximum depth to traverse for circular reference detection (default: 100)
+     */
+    maxDepth?: number;
+    /**
+     * Maximum string length to process for Unicode grapheme counting (default: 100000)
+     */
+    maxStringLength?: number;
+}
+/**
+ * TokenEstimator provides character-based token counting for JSON payloads.
+ *
+ * Algorithm:
+ * 1. Serialize value to JSON (handling circular refs)
+ * 2. Count Unicode graphemes (not bytes)
+ * 3. Divide by charsPerToken ratio (default 4)
+ * 4. Add overhead for structural characters
+ */
+export declare class TokenEstimator {
+    private options;
+    constructor(options?: TokenEstimatorOptions);
+    /**
+     * Estimate tokens for any JavaScript value.
+     * Handles circular references, nested objects, arrays, and Unicode.
+     *
+     * @param value - Any value to estimate
+     * @returns Estimated token count
+     */
+    estimate(value: unknown): number;
+    /**
+     * Estimate tokens from a JSON string.
+     * More efficient if you already have the JSON string.
+     *
+     * @param json - JSON string to estimate
+     * @returns Estimated token count
+     */
+    estimateJSON(json: string): number;
+    /**
+     * Internal recursive estimation with circular reference tracking.
+     */
+    private estimateWithTracking;
+    /**
+     * Estimate tokens for an array.
+     */
+    private estimateArray;
+    /**
+     * Estimate tokens for a plain object.
+     */
+    private estimateObject;
+    /**
+     * Check if a value can be safely serialized (no circular refs).
+     */
+    canSerialize(value: unknown): boolean;
+    /**
+     * Serialize value to JSON with circular reference handling.
+     * Circular refs are replaced with "[Circular]".
+     */
+    safeStringify(value: unknown): string;
+    /**
+     * Create a safe copy of a value with circular refs removed.
+     */
+    safeCopy<T>(value: T): T;
+}
+/**
+ * Global token estimator instance with default settings.
+ */
+export declare const defaultEstimator: TokenEstimator;
+/**
+ * Convenience function to estimate tokens for a value.
+ */
+export declare function estimateTokens(value: unknown, options?: TokenEstimatorOptions): number;
+/**
+ * Convenience function to estimate tokens from a JSON string.
+ */
+export declare function estimateTokensJSON(json: string, options?: TokenEstimatorOptions): number;

package/dist/src/tokenEstimator.js

@@ -0,0 +1,238 @@
+/**
+ * LAFS Token Estimator
+ *
+ * Provides character-based token estimation for LAFS envelopes and JSON payloads.
+ * Uses the approximation: 1 token ≈ 4 characters.
+ * Properly handles nested objects, arrays, Unicode graphemes, and circular references.
+ */
+/**
+ * Counts Unicode graphemes in a string using Intl.Segmenter when available.
+ * Falls back to character counting for environments without Intl.Segmenter.
+ */
+function countGraphemes(str) {
+    // Use Intl.Segmenter for proper grapheme counting (Node.js 16+, modern browsers)
+    if (typeof Intl !== 'undefined' && 'Segmenter' in Intl) {
+        // @ts-ignore - Intl.Segmenter may not be in all TypeScript lib versions
+        const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
+        // @ts-ignore
+        return Array.from(segmenter.segment(str)).length;
+    }
+    // Fallback: count code points using spread operator (handles surrogate pairs)
+    return [...str].length;
+}
+/**
+ * Default options for token estimation
+ */
+const DEFAULT_OPTIONS = {
+    charsPerToken: 4,
+    maxDepth: 100,
+    maxStringLength: 100000,
+};
+/**
+ * TokenEstimator provides character-based token counting for JSON payloads.
+ *
+ * Algorithm:
+ * 1. Serialize value to JSON (handling circular refs)
+ * 2. Count Unicode graphemes (not bytes)
+ * 3. Divide by charsPerToken ratio (default 4)
+ * 4. Add overhead for structural characters
+ */
+export class TokenEstimator {
+    options;
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Estimate tokens for any JavaScript value.
+     * Handles circular references, nested objects, arrays, and Unicode.
+     *
+     * @param value - Any value to estimate
+     * @returns Estimated token count
+     */
+    estimate(value) {
+        return this.estimateWithTracking(value, new WeakSet(), 0);
+    }
+    /**
+     * Estimate tokens from a JSON string.
+     * More efficient if you already have the JSON string.
+     *
+     * @param json - JSON string to estimate
+     * @returns Estimated token count
+     */
+    estimateJSON(json) {
+        // Count graphemes in the JSON string
+        const graphemes = countGraphemes(json);
+        // Add overhead for JSON structure (brackets, quotes, colons, etc.)
+        const structuralOverhead = Math.ceil(graphemes * 0.1);
+        return Math.ceil((graphemes + structuralOverhead) / this.options.charsPerToken);
+    }
+    /**
+     * Internal recursive estimation with circular reference tracking.
+     */
+    estimateWithTracking(value, seen, depth) {
+        // Prevent infinite recursion
+        if (depth > this.options.maxDepth) {
+            return 1; // Minimal cost for max depth exceeded
+        }
+        // Handle null
+        if (value === null) {
+            return 1; // "null" = 4 chars / 4 = 1 token
+        }
+        // Handle undefined
+        if (value === undefined) {
+            return 1;
+        }
+        // Handle primitives
+        const type = typeof value;
+        if (type === 'boolean') {
+            return value ? 1 : 1; // "true" or "false" ≈ 1 token
+        }
+        if (type === 'number') {
+            const str = String(value);
+            return Math.ceil(countGraphemes(str) / this.options.charsPerToken);
+        }
+        if (type === 'string') {
+            const str = value;
+            // Limit string length to prevent performance issues
+            const truncated = str.length > this.options.maxStringLength
+                ? str.slice(0, this.options.maxStringLength) + '…'
+                : str;
+            const graphemes = countGraphemes(truncated);
+            // Add 2 for quotes
+            return Math.ceil((graphemes + 2) / this.options.charsPerToken);
+        }
+        // Handle objects and arrays
+        if (type === 'object') {
+            const obj = value;
+            // Check for circular reference
+            if (seen.has(obj)) {
+                return 1; // Minimal cost for circular ref placeholder
+            }
+            seen.add(obj);
+            try {
+                if (Array.isArray(obj)) {
+                    return this.estimateArray(obj, seen, depth);
+                }
+                return this.estimateObject(obj, seen, depth);
+            }
+            finally {
+                seen.delete(obj);
+            }
+        }
+        // Handle symbols, functions, etc.
+        return 1;
+    }
+    /**
+     * Estimate tokens for an array.
+     */
+    estimateArray(arr, seen, depth) {
+        let tokens = 1; // Opening bracket [ (already counted as structural)
+        for (let i = 0; i < arr.length; i++) {
+            tokens += this.estimateWithTracking(arr[i], seen, depth + 1);
+            // Add comma separator (except for last element)
+            if (i < arr.length - 1) {
+                tokens += 1; // comma + space ≈ 2 chars / 4 = 0.5, round up to 1
+            }
+        }
+        tokens += 1; // Closing bracket ]
+        return tokens;
+    }
+    /**
+     * Estimate tokens for a plain object.
+     */
+    estimateObject(obj, seen, depth) {
+        let tokens = 1; // Opening brace {
+        const keys = Object.keys(obj);
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            const value = obj[key];
+            // Estimate key (with quotes)
+            tokens += Math.ceil((countGraphemes(key) + 2) / this.options.charsPerToken);
+            // Colon separator
+            tokens += 1; // " : " ≈ 3 chars / 4 = 0.75, round up to 1
+            // Estimate value
+            tokens += this.estimateWithTracking(value, seen, depth + 1);
+            // Comma separator (except for last property)
+            if (i < keys.length - 1) {
+                tokens += 1; // comma + space ≈ 2 chars / 4 = 0.5, round up to 1
+            }
+        }
+        tokens += 1; // Closing brace }
+        return tokens;
+    }
+    /**
+     * Check if a value can be safely serialized (no circular refs).
+     */
+    canSerialize(value) {
+        try {
+            JSON.stringify(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Serialize value to JSON with circular reference handling.
+     * Circular refs are replaced with "[Circular]".
+     */
+    safeStringify(value) {
+        const seen = new WeakSet();
+        return JSON.stringify(value, (key, val) => {
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val)) {
+                    return '[Circular]';
+                }
+                seen.add(val);
+            }
+            return val;
+        });
+    }
+    /**
+     * Create a safe copy of a value with circular refs removed.
+     */
+    safeCopy(value) {
+        const seen = new WeakSet();
+        function clone(val) {
+            if (val === null || typeof val !== 'object') {
+                return val;
+            }
+            if (seen.has(val)) {
+                return '[Circular]';
+            }
+            seen.add(val);
+            try {
+                if (Array.isArray(val)) {
+                    return val.map(clone);
+                }
+                const result = {};
+                for (const [k, v] of Object.entries(val)) {
+                    result[k] = clone(v);
+                }
+                return result;
+            }
+            finally {
+                seen.delete(val);
+            }
+        }
+        return clone(value);
+    }
+}
+/**
+ * Global token estimator instance with default settings.
+ */
+export const defaultEstimator = new TokenEstimator();
+/**
+ * Convenience function to estimate tokens for a value.
+ */
+export function estimateTokens(value, options) {
+    const estimator = options ? new TokenEstimator(options) : defaultEstimator;
+    return estimator.estimate(value);
+}
+/**
+ * Convenience function to estimate tokens from a JSON string.
+ */
+export function estimateTokensJSON(json, options) {
+    const estimator = options ? new TokenEstimator(options) : defaultEstimator;
+    return estimator.estimateJSON(json);
+}

package/dist/src/types.d.ts

@@ -85,3 +85,28 @@ export interface ConformanceReport {
         detail?: string;
     }>;
 }
+export type BudgetEnforcementOptions = {
+    truncateOnExceed?: boolean;
+    onBudgetExceeded?: (estimated: number, budget: number) => void;
+};
+export interface TokenEstimate {
+    estimated: number;
+    truncated?: boolean;
+    originalEstimate?: number;
+}
+export interface LAFSMetaWithBudget extends LAFSMeta {
+    _tokenEstimate?: TokenEstimate;
+}
+export interface LAFSEnvelopeWithBudget extends Omit<LAFSEnvelope, '_meta'> {
+    _meta: LAFSMetaWithBudget;
+}
+export type MiddlewareFunction = (envelope: LAFSEnvelope) => LAFSEnvelope | Promise<LAFSEnvelope>;
+export type NextFunction = () => LAFSEnvelope | Promise<LAFSEnvelope>;
+export type BudgetMiddleware = (envelope: LAFSEnvelope, next: NextFunction) => Promise<LAFSEnvelope> | LAFSEnvelope;
+export interface BudgetEnforcementResult {
+    envelope: LAFSEnvelope;
+    withinBudget: boolean;
+    estimatedTokens: number;
+    budget: number;
+    truncated: boolean;
+}