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

package/src/FlinkRepo.ts

@@ -16,7 +16,7 @@ export abstract class FlinkRepo<C extends FlinkContext, Model extends Document>
         this._ctx = ctx as C;
     }
 
-    get ctx() {
+    get ctx(): C {
         if (!this._ctx) throw new Error("Missing FlinkContext");
         return this._ctx;
     }
@@ -51,7 +51,7 @@ export abstract class FlinkRepo<C extends FlinkContext, Model extends Document>
         return { ...model, _id: result.insertedId.toString() };
     }
 
-    async updateOne(id: string | ObjectId, model: PartialModel<Model>): Promise<Model | null> {
+    async updateById(id: string | ObjectId, model: PartialModel<Model>): Promise<Model | null> {
         const oid = this.buildId(id);
 
         const { _id, ...modelWithoutId } = model;
@@ -66,6 +66,13 @@ export abstract class FlinkRepo<C extends FlinkContext, Model extends Document>
         return null;
     }
 
+    /**
+     * @deprecated Use `updateById` instead. This will be removed in a future major version.
+     */
+    async updateOne(id: string | ObjectId, model: PartialModel<Model>): Promise<Model | null> {
+        return this.updateById(id, model);
+    }
+
     async updateMany<U = PartialModel<Model>>(query: any, model: U): Promise<number> {
         const { _id, ...modelWithoutId } = model as any;
 
@@ -103,7 +110,7 @@ export abstract class FlinkRepo<C extends FlinkContext, Model extends Document>
         return oid;
     }
 
-    private objectIdToString<T>(doc: T & { _id?: any }) {
+    protected objectIdToString<T>(doc: T & { _id?: any }) {
         if (doc && doc._id) {
             doc._id = doc._id.toString();
         }

package/src/FlinkRequestContext.ts

@@ -0,0 +1,95 @@
+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 const requestContext = new AsyncLocalStorage<RequestContext>();
+
+/**
+ * Get the current request context
+ * Returns undefined if called outside of a request context
+ */
+export function getRequestContext(): RequestContext | undefined {
+    return requestContext.getStore();
+}
+
+/**
+ * Get the authenticated user from request context
+ * Returns undefined if no user is authenticated or outside request context
+ */
+export function getRequestUser<T = any>(): T | undefined {
+    return requestContext.getStore()?.user;
+}
+
+/**
+ * Get user permissions from request context
+ * Returns empty array if no permissions available
+ */
+export function getRequestPermissions(): string[] {
+    return requestContext.getStore()?.userPermissions || [];
+}
+
+/**
+ * Get request ID from context
+ * Returns undefined if called outside of request context
+ */
+export function getReqId(): string | undefined {
+    return requestContext.getStore()?.reqId;
+}
+
+/**
+ * Check if current user has a specific permission
+ * @param permission - Permission string to check
+ * @returns true if user has the permission, false otherwise
+ */
+export function hasPermission(permission: string): boolean {
+    const 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
+ */
+export function hasAllPermissions(requiredPermissions: string[]): boolean {
+    const permissions = getRequestPermissions();
+    return requiredPermissions.every(p => 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
+ */
+export function hasAnyPermission(requiredPermissions: string[]): boolean {
+    const permissions = getRequestPermissions();
+    return requiredPermissions.some(p => permissions.includes(p));
+}

package/src/FlinkResponse.ts

@@ -34,6 +34,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;
     };
 
     /**

package/src/FlinkService.ts

@@ -0,0 +1,49 @@
+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 abstract class FlinkService<C extends FlinkContext> {
+    private _ctx?: C;
+
+    set ctx(ctx: FlinkContext) {
+        this._ctx = ctx as C;
+    }
+
+    get ctx(): C {
+        if (!this._ctx) {
+            throw new Error("FlinkService: ctx is not available in constructor. Use onInit() for setup logic.");
+        }
+        return this._ctx;
+    }
+
+    /**
+     * 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/src/LeaderElection.ts

@@ -0,0 +1,203 @@
+import { Collection, Db } from "mongodb";
+import { v4 } from "uuid";
+import { FlinkLogFactory } from "./FlinkLogFactory";
+
+const log = FlinkLogFactory.createLogger("flink.scheduler");
+
+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;
+}
+
+interface LeaderRecord {
+    _id: string;
+    instanceId: string;
+    lastHeartbeat: Date;
+    claimedAt: Date;
+}
+
+const LOCK_NAME = "job-scheduler";
+
+export class LeaderElection {
+    private instanceId = v4();
+    private _isLeader = false;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+    private collection: Collection<LeaderRecord>;
+    private leaseDurationMs: number;
+    private heartbeatIntervalMs: number;
+    private onBecameLeader?: () => void | Promise<void>;
+    private onLostLeadership?: () => void | Promise<void>;
+    private stopped = false;
+    private transitioning = false;
+
+    constructor(db: Db, opts?: LeaderElectionOptions) {
+        const collectionName = opts?.collectionName || "_flink_leader";
+        this.leaseDurationMs = opts?.leaseDurationMs || 15000;
+        this.heartbeatIntervalMs = opts?.heartbeatIntervalMs || 5000;
+        this.collection = db.collection<LeaderRecord>(collectionName);
+    }
+
+    get isLeader() {
+        return this._isLeader;
+    }
+
+    /**
+     * Start the leader election process.
+     * @param onBecameLeader Called when this instance becomes the leader
+     * @param onLostLeadership Called when this instance loses leadership
+     */
+    async start(onBecameLeader: () => void | Promise<void>, onLostLeadership: () => void | Promise<void>) {
+        this.onBecameLeader = onBecameLeader;
+        this.onLostLeadership = onLostLeadership;
+        this.stopped = false;
+
+        // Ensure TTL index exists for cleanup
+        const ttlSeconds = Math.ceil((this.leaseDurationMs * 2) / 1000);
+        try {
+            await this.collection.createIndex({ lastHeartbeat: 1 }, { expireAfterSeconds: ttlSeconds });
+        } catch (err: any) {
+            if (err.codeName === "IndexOptionsConflict" || err.code === 85) {
+                log.debug("TTL index options changed, recreating index");
+                await this.collection.dropIndex("lastHeartbeat_1");
+                await this.collection.createIndex({ lastHeartbeat: 1 }, { expireAfterSeconds: ttlSeconds });
+            } else {
+                throw err;
+            }
+        }
+
+        log.info(`Leader election started (instance: ${this.instanceId.substring(0, 8)})`);
+
+        // Run first election attempt immediately
+        await this.tryClaimLeadership();
+    }
+
+    /**
+     * Stop the leader election and release leadership if held.
+     */
+    async stop() {
+        this.stopped = true;
+
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+
+        if (this._isLeader) {
+            try {
+                await this.collection.deleteOne({
+                    _id: LOCK_NAME as any,
+                    instanceId: this.instanceId,
+                });
+                log.info("Leadership released on shutdown");
+            } catch (err) {
+                log.error(`Failed to release leadership on shutdown: ${err}`);
+            }
+            this._isLeader = false;
+        }
+    }
+
+    private async tryClaimLeadership() {
+        if (this.stopped || this.transitioning) return;
+
+        const now = new Date();
+        const leaseExpiry = new Date(now.getTime() - this.leaseDurationMs);
+
+        try {
+            const result = await this.collection.findOneAndUpdate(
+                {
+                    _id: LOCK_NAME as any,
+                    $or: [
+                        { instanceId: this.instanceId },
+                        { lastHeartbeat: { $lt: leaseExpiry } },
+                    ],
+                },
+                {
+                    $set: {
+                        instanceId: this.instanceId,
+                        lastHeartbeat: now,
+                    },
+                    $setOnInsert: {
+                        claimedAt: now,
+                    },
+                },
+                { upsert: true, returnDocument: "after" }
+            );
+
+            const gotLock = result && (result as any).instanceId === this.instanceId;
+
+            if (gotLock && !this._isLeader) {
+                log.info(`This instance became the leader (instance: ${this.instanceId.substring(0, 8)})`);
+                this._isLeader = true;
+                this.transitioning = true;
+                try {
+                    await this.onBecameLeader?.();
+                } catch (err) {
+                    log.error(`Error in onBecameLeader callback: ${err}`);
+                } finally {
+                    this.transitioning = false;
+                }
+            } else if (!gotLock && this._isLeader) {
+                log.warn(`This instance lost leadership (instance: ${this.instanceId.substring(0, 8)})`);
+                this._isLeader = false;
+                this.transitioning = true;
+                try {
+                    await this.onLostLeadership?.();
+                } catch (err) {
+                    log.error(`Error in onLostLeadership callback: ${err}`);
+                } finally {
+                    this.transitioning = false;
+                }
+            }
+        } catch (err: any) {
+            if (err.code === 11000) {
+                // Duplicate key - another instance claimed first
+                if (this._isLeader) {
+                    log.warn(`This instance lost leadership (instance: ${this.instanceId.substring(0, 8)})`);
+                    this._isLeader = false;
+                    try {
+                        await this.onLostLeadership?.();
+                    } catch (cbErr) {
+                        log.error(`Error in onLostLeadership callback: ${cbErr}`);
+                    }
+                }
+            } else {
+                log.error(`Leader election error: ${err}`);
+                // On error, assume we lost leadership to be safe
+                if (this._isLeader) {
+                    this._isLeader = false;
+                    try {
+                        await this.onLostLeadership?.();
+                    } catch (cbErr) {
+                        log.error(`Error in onLostLeadership callback: ${cbErr}`);
+                    }
+                }
+            }
+        }
+
+        // Schedule next attempt
+        if (!this.stopped) {
+            const nextInterval = this._isLeader
+                ? this.heartbeatIntervalMs
+                : this.heartbeatIntervalMs * 2;
+
+            this.timer = setTimeout(() => this.tryClaimLeadership(), nextInterval);
+        }
+    }
+}

package/src/SchemaCache.ts

@@ -0,0 +1,232 @@
+import { createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+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 class SchemaCache {
+  private static CACHE_VERSION = '1.0.0';
+  private cacheFile: string;
+  private entries: Map<string, SchemaCacheEntry> = new Map();
+  private dirty = false;
+
+  constructor(private projectRoot: string) {
+    this.cacheFile = path.join(projectRoot, '.flink', 'schema-cache.json');
+  }
+
+  /**
+   * Compute SHA-256 hash of file content
+   */
+  static async hashFile(filePath: string): Promise<string> {
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      return SchemaCache.hashContent(content);
+    } catch (error) {
+      // File doesn't exist or can't be read
+      return '';
+    }
+  }
+
+  /**
+   * Compute SHA-256 hash of string content
+   */
+  static hashContent(content: string): string {
+    return createHash('sha256').update(content, 'utf-8').digest('hex');
+  }
+
+  /**
+   * Load cache from disk
+   */
+  async load(): Promise<void> {
+    try {
+      // Ensure .flink directory exists
+      const flinkDir = path.dirname(this.cacheFile);
+      await fs.mkdir(flinkDir, { recursive: true });
+
+      // Read cache file
+      const data = await fs.readFile(this.cacheFile, 'utf-8');
+      const cache: SchemaCacheFile = JSON.parse(data);
+
+      // Validate cache version
+      if (cache.version !== SchemaCache.CACHE_VERSION) {
+        console.log('[SchemaCache] Cache version mismatch, invalidating cache');
+        this.entries.clear();
+        return;
+      }
+
+      // Validate TypeScript version (major.minor)
+      const currentTsVersion = this.getTsVersion();
+      if (cache.tsVersion !== currentTsVersion) {
+        console.log('[SchemaCache] TypeScript version changed, invalidating cache');
+        this.entries.clear();
+        return;
+      }
+
+      // Load entries
+      this.entries = new Map(Object.entries(cache.entries));
+      console.log(`[SchemaCache] Loaded ${this.entries.size} cached schemas`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        console.warn('[SchemaCache] Failed to load cache:', error);
+      }
+      this.entries.clear();
+    }
+  }
+
+  /**
+   * Save cache to disk
+   */
+  async save(): Promise<void> {
+    if (!this.dirty) {
+      return;
+    }
+
+    try {
+      const cache: SchemaCacheFile = {
+        version: SchemaCache.CACHE_VERSION,
+        tsVersion: this.getTsVersion(),
+        generated: new Date().toISOString(),
+        entries: Object.fromEntries(this.entries),
+      };
+
+      const flinkDir = path.dirname(this.cacheFile);
+      await fs.mkdir(flinkDir, { recursive: true });
+      await fs.writeFile(this.cacheFile, JSON.stringify(cache, null, 2), 'utf-8');
+
+      console.log(`[SchemaCache] Saved ${this.entries.size} schemas to cache`);
+      this.dirty = false;
+    } catch (error) {
+      console.warn('[SchemaCache] Failed to save cache:', error);
+    }
+  }
+
+  /**
+   * Get cached entry for schema
+   */
+  get(schemaName: string): SchemaCacheEntry | undefined {
+    return this.entries.get(schemaName);
+  }
+
+  /**
+   * Add or update cache entry
+   */
+  set(entry: SchemaCacheEntry): void {
+    this.entries.set(entry.schemaName, entry);
+    this.dirty = true;
+  }
+
+  /**
+   * Remove cache entry
+   */
+  delete(schemaName: string): void {
+    if (this.entries.delete(schemaName)) {
+      this.dirty = true;
+    }
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear(): void {
+    this.entries.clear();
+    this.dirty = true;
+  }
+
+  /**
+   * Check if schema needs regeneration
+   * Returns { needed: boolean, reason?: string }
+   */
+  async needsRegeneration(
+    schemaName: string,
+    schemaFile: string,
+    dependencies: Map<string, string>
+  ): Promise<{ needed: boolean; reason?: string }> {
+    const cached = this.entries.get(schemaName);
+
+    // No cache entry
+    if (!cached) {
+      return { needed: true, reason: 'no cache entry' };
+    }
+
+    // Schema file changed
+    const currentHash = await SchemaCache.hashFile(schemaFile);
+    if (cached.contentHash !== currentHash) {
+      return { needed: true, reason: 'schema file changed' };
+    }
+
+    // Dependency set changed
+    const cachedDeps = Object.keys(cached.dependencyHashes).sort();
+    const currentDeps = Array.from(dependencies.keys()).sort();
+    if (JSON.stringify(cachedDeps) !== JSON.stringify(currentDeps)) {
+      return { needed: true, reason: 'dependency set changed' };
+    }
+
+    // Check each dependency hash
+    for (const [depPath, depHash] of Array.from(dependencies.entries())) {
+      const cachedHash = cached.dependencyHashes[depPath];
+      if (cachedHash !== depHash) {
+        return { needed: true, reason: `dependency changed: ${depPath}` };
+      }
+    }
+
+    // Cache is valid
+    return { needed: false };
+  }
+
+  /**
+   * Get TypeScript version (major.minor)
+   */
+  private getTsVersion(): string {
+    try {
+      const tsPackageJson = require('typescript/package.json');
+      const [major, minor] = tsPackageJson.version.split('.');
+      return `${major}.${minor}`;
+    } catch {
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    totalEntries: number;
+    oldestEntry?: string;
+    newestEntry?: string;
+  } {
+    if (this.entries.size === 0) {
+      return { totalEntries: 0 };
+    }
+
+    const timestamps = Array.from(this.entries.values()).map(e => new Date(e.generatedAt).getTime());
+    return {
+      totalEntries: this.entries.size,
+      oldestEntry: new Date(Math.min(...timestamps)).toISOString(),
+      newestEntry: new Date(Math.max(...timestamps)).toISOString(),
+    };
+  }
+}