@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/dist/src/FlinkRequestContext.d.ts

@@ -0,0 +1,63 @@
+import { AsyncLocalStorage } from 'async_hooks';
+/**
+ * Request-scoped context available throughout handler → agent → tool execution
+ */
+export interface RequestContext {
+    /** Unique request identifier (from req.reqId) */
+    reqId: string;
+    /** Authenticated user object (from req.user) */
+    user?: any;
+    /** Resolved user permissions from auth plugin (from req.userPermissions) */
+    userPermissions?: string[];
+    /** HTTP method (GET, POST, etc.) */
+    method?: string;
+    /** Request path */
+    path?: string;
+    /** Request start timestamp */
+    timestamp: number;
+    /** Whether this is a streaming request (SSE/NDJSON) */
+    isStreaming?: boolean;
+}
+/**
+ * AsyncLocalStorage instance for request-scoped context
+ * Available throughout the entire request lifecycle including async operations
+ */
+export declare const requestContext: AsyncLocalStorage<RequestContext>;
+/**
+ * Get the current request context
+ * Returns undefined if called outside of a request context
+ */
+export declare function getRequestContext(): RequestContext | undefined;
+/**
+ * Get the authenticated user from request context
+ * Returns undefined if no user is authenticated or outside request context
+ */
+export declare function getRequestUser<T = any>(): T | undefined;
+/**
+ * Get user permissions from request context
+ * Returns empty array if no permissions available
+ */
+export declare function getRequestPermissions(): string[];
+/**
+ * Get request ID from context
+ * Returns undefined if called outside of request context
+ */
+export declare function getReqId(): string | undefined;
+/**
+ * Check if current user has a specific permission
+ * @param permission - Permission string to check
+ * @returns true if user has the permission, false otherwise
+ */
+export declare function hasPermission(permission: string): boolean;
+/**
+ * Check if current user has all of the specified permissions (AND logic)
+ * @param requiredPermissions - Array of permission strings (all required)
+ * @returns true if user has all permissions, false otherwise
+ */
+export declare function hasAllPermissions(requiredPermissions: string[]): boolean;
+/**
+ * Check if current user has any of the specified permissions (OR logic)
+ * @param requiredPermissions - Array of permission strings (any required)
+ * @returns true if user has at least one permission, false otherwise
+ */
+export declare function hasAnyPermission(requiredPermissions: string[]): boolean;

package/dist/src/FlinkRequestContext.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestContext = void 0;
+exports.getRequestContext = getRequestContext;
+exports.getRequestUser = getRequestUser;
+exports.getRequestPermissions = getRequestPermissions;
+exports.getReqId = getReqId;
+exports.hasPermission = hasPermission;
+exports.hasAllPermissions = hasAllPermissions;
+exports.hasAnyPermission = hasAnyPermission;
+var async_hooks_1 = require("async_hooks");
+/**
+ * AsyncLocalStorage instance for request-scoped context
+ * Available throughout the entire request lifecycle including async operations
+ */
+exports.requestContext = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Get the current request context
+ * Returns undefined if called outside of a request context
+ */
+function getRequestContext() {
+    return exports.requestContext.getStore();
+}
+/**
+ * Get the authenticated user from request context
+ * Returns undefined if no user is authenticated or outside request context
+ */
+function getRequestUser() {
+    var _a;
+    return (_a = exports.requestContext.getStore()) === null || _a === void 0 ? void 0 : _a.user;
+}
+/**
+ * Get user permissions from request context
+ * Returns empty array if no permissions available
+ */
+function getRequestPermissions() {
+    var _a;
+    return ((_a = exports.requestContext.getStore()) === null || _a === void 0 ? void 0 : _a.userPermissions) || [];
+}
+/**
+ * Get request ID from context
+ * Returns undefined if called outside of request context
+ */
+function getReqId() {
+    var _a;
+    return (_a = exports.requestContext.getStore()) === null || _a === void 0 ? void 0 : _a.reqId;
+}
+/**
+ * Check if current user has a specific permission
+ * @param permission - Permission string to check
+ * @returns true if user has the permission, false otherwise
+ */
+function hasPermission(permission) {
+    var permissions = getRequestPermissions();
+    return permissions.includes(permission);
+}
+/**
+ * Check if current user has all of the specified permissions (AND logic)
+ * @param requiredPermissions - Array of permission strings (all required)
+ * @returns true if user has all permissions, false otherwise
+ */
+function hasAllPermissions(requiredPermissions) {
+    var permissions = getRequestPermissions();
+    return requiredPermissions.every(function (p) { return permissions.includes(p); });
+}
+/**
+ * Check if current user has any of the specified permissions (OR logic)
+ * @param requiredPermissions - Array of permission strings (any required)
+ * @returns true if user has at least one permission, false otherwise
+ */
+function hasAnyPermission(requiredPermissions) {
+    var permissions = getRequestPermissions();
+    return requiredPermissions.some(function (p) { return permissions.includes(p); });
+}

package/dist/src/FlinkResponse.d.ts

@@ -28,6 +28,12 @@ export interface FlinkResponse<T = any> {
         title: string;
         detail?: string;
         code?: string;
+        /**
+         * Optional structured payload with additional error context.
+         * Must be JSON-serializable; non-serializable values are stripped
+         * with a warning before sending the response.
+         */
+        meta?: unknown;
     };
     /**
      * HTTP headers, names are lower cased

package/dist/src/FlinkService.d.ts

@@ -0,0 +1,38 @@
+import { FlinkContext } from "./FlinkContext";
+/**
+ * Base class for Flink services - optional business logic layer.
+ *
+ * Services provide a place for shared business logic that can be used by
+ * handlers, jobs, agents, and other services via `ctx.services`.
+ *
+ * Context (`this.ctx`) is not available in the constructor - use `onInit()`
+ * for any setup that requires context.
+ *
+ * @example
+ * ```typescript
+ * class CarService extends FlinkService<AppCtx> {
+ *     async onInit() {
+ *         // Called after all services are instantiated and ctx is fully wired
+ *     }
+ *
+ *     async getWithOwner(carId: string) {
+ *         const car = await this.ctx.repos.carRepo.getById(carId);
+ *         if (!car) throw notFound("Car not found");
+ *         return car;
+ *     }
+ * }
+ * ```
+ */
+export declare abstract class FlinkService<C extends FlinkContext> {
+    private _ctx?;
+    set ctx(ctx: FlinkContext);
+    get ctx(): C;
+    /**
+     * Optional async initialization hook called after all services are
+     * instantiated and ctx is fully wired (repos, plugins, agents, services all available).
+     *
+     * All service onInit() methods run in parallel via Promise.all.
+     * Do not depend on another service's onInit() having completed.
+     */
+    onInit?(): Promise<void>;
+}

package/dist/src/FlinkService.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlinkService = void 0;
+/**
+ * Base class for Flink services - optional business logic layer.
+ *
+ * Services provide a place for shared business logic that can be used by
+ * handlers, jobs, agents, and other services via `ctx.services`.
+ *
+ * Context (`this.ctx`) is not available in the constructor - use `onInit()`
+ * for any setup that requires context.
+ *
+ * @example
+ * ```typescript
+ * class CarService extends FlinkService<AppCtx> {
+ *     async onInit() {
+ *         // Called after all services are instantiated and ctx is fully wired
+ *     }
+ *
+ *     async getWithOwner(carId: string) {
+ *         const car = await this.ctx.repos.carRepo.getById(carId);
+ *         if (!car) throw notFound("Car not found");
+ *         return car;
+ *     }
+ * }
+ * ```
+ */
+var FlinkService = /** @class */ (function () {
+    function FlinkService() {
+    }
+    Object.defineProperty(FlinkService.prototype, "ctx", {
+        get: function () {
+            if (!this._ctx) {
+                throw new Error("FlinkService: ctx is not available in constructor. Use onInit() for setup logic.");
+            }
+            return this._ctx;
+        },
+        set: function (ctx) {
+            this._ctx = ctx;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return FlinkService;
+}());
+exports.FlinkService = FlinkService;

package/dist/src/LeaderElection.d.ts

@@ -0,0 +1,45 @@
+import { Db } from "mongodb";
+export interface LeaderElectionOptions {
+    /**
+     * Duration in milliseconds before a leader's lease expires.
+     * If the leader fails to heartbeat within this time, another instance can take over.
+     * @default 15000
+     */
+    leaseDurationMs?: number;
+    /**
+     * Interval in milliseconds between heartbeats sent by the leader.
+     * Should be significantly less than leaseDurationMs (typically 1/3).
+     * @default 5000
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Name of the MongoDB collection used for leader election.
+     * @default "_flink_leader"
+     */
+    collectionName?: string;
+}
+export declare class LeaderElection {
+    private instanceId;
+    private _isLeader;
+    private timer;
+    private collection;
+    private leaseDurationMs;
+    private heartbeatIntervalMs;
+    private onBecameLeader?;
+    private onLostLeadership?;
+    private stopped;
+    private transitioning;
+    constructor(db: Db, opts?: LeaderElectionOptions);
+    get isLeader(): boolean;
+    /**
+     * Start the leader election process.
+     * @param onBecameLeader Called when this instance becomes the leader
+     * @param onLostLeadership Called when this instance loses leadership
+     */
+    start(onBecameLeader: () => void | Promise<void>, onLostLeadership: () => void | Promise<void>): Promise<void>;
+    /**
+     * Stop the leader election and release leadership if held.
+     */
+    stop(): Promise<void>;
+    private tryClaimLeadership;
+}

package/dist/src/LeaderElection.js

@@ -0,0 +1,269 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeaderElection = void 0;
+var uuid_1 = require("uuid");
+var FlinkLogFactory_1 = require("./FlinkLogFactory");
+var log = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.scheduler");
+var LOCK_NAME = "job-scheduler";
+var LeaderElection = /** @class */ (function () {
+    function LeaderElection(db, opts) {
+        this.instanceId = (0, uuid_1.v4)();
+        this._isLeader = false;
+        this.timer = null;
+        this.stopped = false;
+        this.transitioning = false;
+        var collectionName = (opts === null || opts === void 0 ? void 0 : opts.collectionName) || "_flink_leader";
+        this.leaseDurationMs = (opts === null || opts === void 0 ? void 0 : opts.leaseDurationMs) || 15000;
+        this.heartbeatIntervalMs = (opts === null || opts === void 0 ? void 0 : opts.heartbeatIntervalMs) || 5000;
+        this.collection = db.collection(collectionName);
+    }
+    Object.defineProperty(LeaderElection.prototype, "isLeader", {
+        get: function () {
+            return this._isLeader;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Start the leader election process.
+     * @param onBecameLeader Called when this instance becomes the leader
+     * @param onLostLeadership Called when this instance loses leadership
+     */
+    LeaderElection.prototype.start = function (onBecameLeader, onLostLeadership) {
+        return __awaiter(this, void 0, void 0, function () {
+            var ttlSeconds, err_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        this.onBecameLeader = onBecameLeader;
+                        this.onLostLeadership = onLostLeadership;
+                        this.stopped = false;
+                        ttlSeconds = Math.ceil((this.leaseDurationMs * 2) / 1000);
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 8]);
+                        return [4 /*yield*/, this.collection.createIndex({ lastHeartbeat: 1 }, { expireAfterSeconds: ttlSeconds })];
+                    case 2:
+                        _a.sent();
+                        return [3 /*break*/, 8];
+                    case 3:
+                        err_1 = _a.sent();
+                        if (!(err_1.codeName === "IndexOptionsConflict" || err_1.code === 85)) return [3 /*break*/, 6];
+                        log.debug("TTL index options changed, recreating index");
+                        return [4 /*yield*/, this.collection.dropIndex("lastHeartbeat_1")];
+                    case 4:
+                        _a.sent();
+                        return [4 /*yield*/, this.collection.createIndex({ lastHeartbeat: 1 }, { expireAfterSeconds: ttlSeconds })];
+                    case 5:
+                        _a.sent();
+                        return [3 /*break*/, 7];
+                    case 6: throw err_1;
+                    case 7: return [3 /*break*/, 8];
+                    case 8:
+                        log.info("Leader election started (instance: ".concat(this.instanceId.substring(0, 8), ")"));
+                        // Run first election attempt immediately
+                        return [4 /*yield*/, this.tryClaimLeadership()];
+                    case 9:
+                        // Run first election attempt immediately
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Stop the leader election and release leadership if held.
+     */
+    LeaderElection.prototype.stop = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var err_2;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        this.stopped = true;
+                        if (this.timer) {
+                            clearTimeout(this.timer);
+                            this.timer = null;
+                        }
+                        if (!this._isLeader) return [3 /*break*/, 5];
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.collection.deleteOne({
+                                _id: LOCK_NAME,
+                                instanceId: this.instanceId,
+                            })];
+                    case 2:
+                        _a.sent();
+                        log.info("Leadership released on shutdown");
+                        return [3 /*break*/, 4];
+                    case 3:
+                        err_2 = _a.sent();
+                        log.error("Failed to release leadership on shutdown: ".concat(err_2));
+                        return [3 /*break*/, 4];
+                    case 4:
+                        this._isLeader = false;
+                        _a.label = 5;
+                    case 5: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    LeaderElection.prototype.tryClaimLeadership = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var now, leaseExpiry, result, gotLock, err_3, err_4, err_5, cbErr_1, cbErr_2, nextInterval;
+            var _this = this;
+            var _a, _b, _c, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        if (this.stopped || this.transitioning)
+                            return [2 /*return*/];
+                        now = new Date();
+                        leaseExpiry = new Date(now.getTime() - this.leaseDurationMs);
+                        _e.label = 1;
+                    case 1:
+                        _e.trys.push([1, 14, , 24]);
+                        return [4 /*yield*/, this.collection.findOneAndUpdate({
+                                _id: LOCK_NAME,
+                                $or: [
+                                    { instanceId: this.instanceId },
+                                    { lastHeartbeat: { $lt: leaseExpiry } },
+                                ],
+                            }, {
+                                $set: {
+                                    instanceId: this.instanceId,
+                                    lastHeartbeat: now,
+                                },
+                                $setOnInsert: {
+                                    claimedAt: now,
+                                },
+                            }, { upsert: true, returnDocument: "after" })];
+                    case 2:
+                        result = _e.sent();
+                        gotLock = result && result.instanceId === this.instanceId;
+                        if (!(gotLock && !this._isLeader)) return [3 /*break*/, 8];
+                        log.info("This instance became the leader (instance: ".concat(this.instanceId.substring(0, 8), ")"));
+                        this._isLeader = true;
+                        this.transitioning = true;
+                        _e.label = 3;
+                    case 3:
+                        _e.trys.push([3, 5, 6, 7]);
+                        return [4 /*yield*/, ((_a = this.onBecameLeader) === null || _a === void 0 ? void 0 : _a.call(this))];
+                    case 4:
+                        _e.sent();
+                        return [3 /*break*/, 7];
+                    case 5:
+                        err_3 = _e.sent();
+                        log.error("Error in onBecameLeader callback: ".concat(err_3));
+                        return [3 /*break*/, 7];
+                    case 6:
+                        this.transitioning = false;
+                        return [7 /*endfinally*/];
+                    case 7: return [3 /*break*/, 13];
+                    case 8:
+                        if (!(!gotLock && this._isLeader)) return [3 /*break*/, 13];
+                        log.warn("This instance lost leadership (instance: ".concat(this.instanceId.substring(0, 8), ")"));
+                        this._isLeader = false;
+                        this.transitioning = true;
+                        _e.label = 9;
+                    case 9:
+                        _e.trys.push([9, 11, 12, 13]);
+                        return [4 /*yield*/, ((_b = this.onLostLeadership) === null || _b === void 0 ? void 0 : _b.call(this))];
+                    case 10:
+                        _e.sent();
+                        return [3 /*break*/, 13];
+                    case 11:
+                        err_4 = _e.sent();
+                        log.error("Error in onLostLeadership callback: ".concat(err_4));
+                        return [3 /*break*/, 13];
+                    case 12:
+                        this.transitioning = false;
+                        return [7 /*endfinally*/];
+                    case 13: return [3 /*break*/, 24];
+                    case 14:
+                        err_5 = _e.sent();
+                        if (!(err_5.code === 11000)) return [3 /*break*/, 19];
+                        if (!this._isLeader) return [3 /*break*/, 18];
+                        log.warn("This instance lost leadership (instance: ".concat(this.instanceId.substring(0, 8), ")"));
+                        this._isLeader = false;
+                        _e.label = 15;
+                    case 15:
+                        _e.trys.push([15, 17, , 18]);
+                        return [4 /*yield*/, ((_c = this.onLostLeadership) === null || _c === void 0 ? void 0 : _c.call(this))];
+                    case 16:
+                        _e.sent();
+                        return [3 /*break*/, 18];
+                    case 17:
+                        cbErr_1 = _e.sent();
+                        log.error("Error in onLostLeadership callback: ".concat(cbErr_1));
+                        return [3 /*break*/, 18];
+                    case 18: return [3 /*break*/, 23];
+                    case 19:
+                        log.error("Leader election error: ".concat(err_5));
+                        if (!this._isLeader) return [3 /*break*/, 23];
+                        this._isLeader = false;
+                        _e.label = 20;
+                    case 20:
+                        _e.trys.push([20, 22, , 23]);
+                        return [4 /*yield*/, ((_d = this.onLostLeadership) === null || _d === void 0 ? void 0 : _d.call(this))];
+                    case 21:
+                        _e.sent();
+                        return [3 /*break*/, 23];
+                    case 22:
+                        cbErr_2 = _e.sent();
+                        log.error("Error in onLostLeadership callback: ".concat(cbErr_2));
+                        return [3 /*break*/, 23];
+                    case 23: return [3 /*break*/, 24];
+                    case 24:
+                        // Schedule next attempt
+                        if (!this.stopped) {
+                            nextInterval = this._isLeader
+                                ? this.heartbeatIntervalMs
+                                : this.heartbeatIntervalMs * 2;
+                            this.timer = setTimeout(function () { return _this.tryClaimLeadership(); }, nextInterval);
+                        }
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    return LeaderElection;
+}());
+exports.LeaderElection = LeaderElection;

package/dist/src/SchemaCache.d.ts

@@ -0,0 +1,84 @@
+import type { JSONSchema7 } from 'json-schema';
+/**
+ * Cache entry for a single schema
+ */
+export interface SchemaCacheEntry {
+    schemaName: string;
+    schemaFile: string;
+    contentHash: string;
+    dependencyHashes: Record<string, string>;
+    jsonSchema: JSONSchema7;
+    generatedAt: string;
+}
+/**
+ * Cache file format
+ */
+export interface SchemaCacheFile {
+    version: string;
+    tsVersion: string;
+    generated: string;
+    entries: Record<string, SchemaCacheEntry>;
+}
+/**
+ * Manages persistent caching of generated JSON schemas
+ */
+export declare class SchemaCache {
+    private projectRoot;
+    private static CACHE_VERSION;
+    private cacheFile;
+    private entries;
+    private dirty;
+    constructor(projectRoot: string);
+    /**
+     * Compute SHA-256 hash of file content
+     */
+    static hashFile(filePath: string): Promise<string>;
+    /**
+     * Compute SHA-256 hash of string content
+     */
+    static hashContent(content: string): string;
+    /**
+     * Load cache from disk
+     */
+    load(): Promise<void>;
+    /**
+     * Save cache to disk
+     */
+    save(): Promise<void>;
+    /**
+     * Get cached entry for schema
+     */
+    get(schemaName: string): SchemaCacheEntry | undefined;
+    /**
+     * Add or update cache entry
+     */
+    set(entry: SchemaCacheEntry): void;
+    /**
+     * Remove cache entry
+     */
+    delete(schemaName: string): void;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Check if schema needs regeneration
+     * Returns { needed: boolean, reason?: string }
+     */
+    needsRegeneration(schemaName: string, schemaFile: string, dependencies: Map<string, string>): Promise<{
+        needed: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Get TypeScript version (major.minor)
+     */
+    private getTsVersion;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        totalEntries: number;
+        oldestEntry?: string;
+        newestEntry?: string;
+    };
+}