@flink-app/flink 2.0.0-alpha.73 → 2.0.0-alpha.75

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/index.d.ts

@@ -10,6 +10,8 @@ export * from "./FlinkRequestContext";
 export * from "./FlinkErrors";
 export * from "./FlinkPlugin";
 export * from "./FlinkJob";
+export { LeaderElection } from "./LeaderElection";
+export type { LeaderElectionOptions } from "./LeaderElection";
 export * from "./auth/FlinkAuthUser";
 export * from "./auth/FlinkAuthPlugin";
 export * from "./ai/FlinkTool";

package/dist/src/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadPluginSchemas = exports.agentInstructions = void 0;
+exports.loadPluginSchemas = exports.agentInstructions = exports.LeaderElection = void 0;
 __exportStar(require("./FlinkLog"), exports);
 __exportStar(require("./FlinkLogFactory"), exports);
 __exportStar(require("./FlinkApp"), exports);
@@ -27,6 +27,8 @@ __exportStar(require("./FlinkRequestContext"), exports);
 __exportStar(require("./FlinkErrors"), exports);
 __exportStar(require("./FlinkPlugin"), exports);
 __exportStar(require("./FlinkJob"), exports);
+var LeaderElection_1 = require("./LeaderElection");
+Object.defineProperty(exports, "LeaderElection", { enumerable: true, get: function () { return LeaderElection_1.LeaderElection; } });
 __exportStar(require("./auth/FlinkAuthUser"), exports);
 __exportStar(require("./auth/FlinkAuthPlugin"), exports);
 __exportStar(require("./ai/FlinkTool"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.73",
+  "version": "2.0.0-alpha.75",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",

package/spec/FlinkJob.spec.ts

@@ -1,6 +1,7 @@
 import { FlinkApp, autoRegisteredJobs } from "../src/FlinkApp";
 import { FlinkContext } from "../src/FlinkContext";
 import { FlinkJobFile } from "../src/FlinkJob";
+import { FlinkLogFactory } from "../src/FlinkLogFactory";
 
 interface TestContext extends FlinkContext {}
 
@@ -93,3 +94,78 @@ describe("FlinkJob error handling", () => {
         expect(runCount).toBe(1);
     });
 });
+
+describe("FlinkJob leader election with runOnAllInstances", () => {
+    let app: FlinkApp<TestContext>;
+
+    afterEach(async () => {
+        autoRegisteredJobs.length = 0;
+        if (app?.started) {
+            await app.stop();
+        }
+    });
+
+    it("should run all jobs when leader election is enabled but no db is configured", async () => {
+        const schedulerLog = FlinkLogFactory.createLogger("flink.scheduler");
+        const warnSpy = spyOn(schedulerLog, "warn");
+
+        let leaderJobRan = false;
+        let allInstanceJobRan = false;
+
+        autoRegisteredJobs.push({
+            Job: { id: "leader-only-job", afterDelay: "0ms" },
+            default: async () => {
+                leaderJobRan = true;
+            },
+        });
+
+        autoRegisteredJobs.push({
+            Job: { id: "all-instance-job", afterDelay: "0ms", runOnAllInstances: true },
+            default: async () => {
+                allInstanceJobRan = true;
+            },
+        });
+
+        app = new FlinkApp<TestContext>({
+            name: "test-leader-no-db",
+            disableHttpServer: true,
+            scheduling: { leaderElection: true },
+        });
+
+        await app.start();
+        await new Promise((resolve) => setTimeout(resolve, 50));
+
+        // Without db, falls back to running all jobs
+        expect(leaderJobRan).toBe(true);
+        expect(allInstanceJobRan).toBe(true);
+        expect(warnSpy).toHaveBeenCalled();
+        const warnMessage = warnSpy.calls.mostRecent().args[0];
+        expect(warnMessage).toContain("Leader election is enabled but no database is configured");
+    });
+
+    it("should not start scheduler for leader-only jobs when not leader", async () => {
+        // Without a real MongoDB, we can't fully test leader election.
+        // This test verifies that when leaderElection is enabled without db,
+        // the warning is shown and all jobs still run as a fallback.
+        let jobRanCount = 0;
+
+        autoRegisteredJobs.push({
+            Job: { id: "interval-job", interval: "50ms" },
+            default: async () => {
+                jobRanCount++;
+            },
+        });
+
+        app = new FlinkApp<TestContext>({
+            name: "test-no-db-fallback",
+            disableHttpServer: true,
+            scheduling: { leaderElection: true },
+        });
+
+        await app.start();
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        // Should have run at least once since it falls back without db
+        expect(jobRanCount).toBeGreaterThan(0);
+    });
+});

package/spec/FlinkRepo.spec.ts

@@ -60,7 +60,7 @@ describe("FlinkRepo", () => {
     it("should update document", async () => {
         const createdDoc = await repo.create({ name: "bar" });
 
-        const updatedDoc = await repo.updateOne(createdDoc._id + "", {
+        const updatedDoc = await repo.updateById(createdDoc._id + "", {
             name: "foo",
             "nested.field": 1,
         });

package/spec/LeaderElection.spec.ts

@@ -0,0 +1,174 @@
+import { LeaderElection } from "../src/LeaderElection";
+
+describe("LeaderElection", () => {
+    let mockCollection: any;
+    let mockDb: any;
+
+    beforeEach(() => {
+        mockCollection = {
+            createIndex: jasmine.createSpy("createIndex").and.resolveTo(undefined),
+            findOneAndUpdate: jasmine.createSpy("findOneAndUpdate"),
+            deleteOne: jasmine.createSpy("deleteOne").and.resolveTo(undefined),
+        };
+
+        mockDb = {
+            collection: jasmine.createSpy("collection").and.returnValue(mockCollection),
+        };
+    });
+
+    it("should create collection with provided name", () => {
+        new LeaderElection(mockDb, { collectionName: "_my_leader" });
+        expect(mockDb.collection).toHaveBeenCalledWith("_my_leader");
+    });
+
+    it("should use default collection name", () => {
+        new LeaderElection(mockDb);
+        expect(mockDb.collection).toHaveBeenCalledWith("_flink_leader");
+    });
+
+    it("should create TTL index on start", async () => {
+        const le = new LeaderElection(mockDb, { leaseDurationMs: 10000 });
+
+        mockCollection.findOneAndUpdate.and.resolveTo({
+            instanceId: "will-not-match",
+        });
+
+        await le.start(
+            () => {},
+            () => {}
+        );
+        await le.stop();
+
+        expect(mockCollection.createIndex).toHaveBeenCalledWith(
+            { lastHeartbeat: 1 },
+            { expireAfterSeconds: 20 } // 2x lease duration in seconds
+        );
+    });
+
+    it("should call onBecameLeader when claiming leadership", async () => {
+        const onBecameLeader = jasmine.createSpy("onBecameLeader");
+        const onLostLeadership = jasmine.createSpy("onLostLeadership");
+
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 50000,
+        });
+
+        // findOneAndUpdate returns a document with our instanceId
+        // We need to intercept the instanceId set in the update
+        mockCollection.findOneAndUpdate.and.callFake((_filter: any, update: any) => {
+            return Promise.resolve({
+                instanceId: update.$set.instanceId,
+            });
+        });
+
+        await le.start(onBecameLeader, onLostLeadership);
+
+        expect(le.isLeader).toBe(true);
+        expect(onBecameLeader).toHaveBeenCalledTimes(1);
+        expect(onLostLeadership).not.toHaveBeenCalled();
+
+        await le.stop();
+    });
+
+    it("should not become leader when another instance holds the lock", async () => {
+        const onBecameLeader = jasmine.createSpy("onBecameLeader");
+        const onLostLeadership = jasmine.createSpy("onLostLeadership");
+
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 50000,
+        });
+
+        // findOneAndUpdate returns a document with a different instanceId
+        mockCollection.findOneAndUpdate.and.resolveTo({
+            instanceId: "other-instance",
+        });
+
+        await le.start(onBecameLeader, onLostLeadership);
+
+        expect(le.isLeader).toBe(false);
+        expect(onBecameLeader).not.toHaveBeenCalled();
+
+        await le.stop();
+    });
+
+    it("should handle duplicate key error gracefully", async () => {
+        const onBecameLeader = jasmine.createSpy("onBecameLeader");
+        const onLostLeadership = jasmine.createSpy("onLostLeadership");
+
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 50000,
+        });
+
+        const duplicateKeyError = new Error("E11000 duplicate key");
+        (duplicateKeyError as any).code = 11000;
+        mockCollection.findOneAndUpdate.and.rejectWith(duplicateKeyError);
+
+        await le.start(onBecameLeader, onLostLeadership);
+
+        expect(le.isLeader).toBe(false);
+        expect(onBecameLeader).not.toHaveBeenCalled();
+
+        await le.stop();
+    });
+
+    it("should release leadership on stop", async () => {
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 50000,
+        });
+
+        mockCollection.findOneAndUpdate.and.callFake((_filter: any, update: any) => {
+            return Promise.resolve({
+                instanceId: update.$set.instanceId,
+            });
+        });
+
+        await le.start(
+            () => {},
+            () => {}
+        );
+
+        expect(le.isLeader).toBe(true);
+
+        await le.stop();
+
+        expect(mockCollection.deleteOne).toHaveBeenCalled();
+        expect(le.isLeader).toBe(false);
+    });
+
+    it("should call onLostLeadership when losing the lock", async () => {
+        const onBecameLeader = jasmine.createSpy("onBecameLeader");
+        const onLostLeadership = jasmine.createSpy("onLostLeadership");
+
+        const le = new LeaderElection(mockDb, {
+            leaseDurationMs: 10000,
+            heartbeatIntervalMs: 100,
+        });
+
+        let callCount = 0;
+        mockCollection.findOneAndUpdate.and.callFake((_filter: any, update: any) => {
+            callCount++;
+            if (callCount === 1) {
+                // First call: we become leader
+                return Promise.resolve({ instanceId: update.$set.instanceId });
+            }
+            // Subsequent calls: another instance took over
+            return Promise.resolve({ instanceId: "other-instance" });
+        });
+
+        await le.start(onBecameLeader, onLostLeadership);
+
+        expect(le.isLeader).toBe(true);
+
+        // Wait for next heartbeat cycle
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        expect(onLostLeadership).toHaveBeenCalledTimes(1);
+        expect(le.isLeader).toBe(false);
+
+        await le.stop();
+    });
+});