@pranshulsoni/flowwatch 1.0.0

package/dist/engine/background/queues/workflowQueue.d.ts

@@ -0,0 +1,6 @@
+import { Queue } from "bullmq";
+export interface WorkflowJobData {
+    executionId: string;
+}
+export declare function createWorkflowQueue(redisUrl: string): Queue<WorkflowJobData, any, string, WorkflowJobData, any, string>;
+export declare function addWorkflowJobToQueue(queue: ReturnType<typeof createWorkflowQueue>, executionId: string): Promise<void>;

package/dist/engine/background/queues/workflowQueue.js

@@ -0,0 +1,14 @@
+import { Queue } from "bullmq";
+export function createWorkflowQueue(redisUrl) {
+    return new Queue("workflows", {
+        prefix: "{flowwatch}",
+        connection: {
+            url: redisUrl,
+        },
+    });
+}
+export async function addWorkflowJobToQueue(queue, executionId) {
+    await queue.add("run-workflow", {
+        executionId,
+    });
+}

package/dist/engine/background/workers/workflowWorker.d.ts

@@ -0,0 +1,15 @@
+import { Worker } from "bullmq";
+import type { Pool } from "pg";
+import type { WorkflowJobData } from "../queues/workflowQueue.js";
+import type { RegisteredWorkflow } from "../../workflows/types.js";
+import type { TraceEngine } from "../../trace/traceEngine.js";
+import type { CaptureErrorFunction } from "../../errors/errorEngine.js";
+export interface WorkflowWorkerOptions {
+    redisUrl: string;
+    pool: Pool;
+    getWorkflow: (name: string) => RegisteredWorkflow | undefined;
+    traceEngine: TraceEngine;
+    captureError: CaptureErrorFunction;
+}
+export declare function createWorkflowWorker(options: WorkflowWorkerOptions): Worker<WorkflowJobData>;
+export declare function executeWorkflow(executionId: string, worker: WorkflowWorkerOptions): Promise<void>;

package/dist/engine/background/workers/workflowWorker.js

@@ -0,0 +1,98 @@
+import { Worker } from "bullmq";
+import { getWorkflowExecution, getWorkflowExecutionSteps, markWorkflowExecutionCompleted, markWorkflowExecutionFailed, markWorkflowExecutionRunning, markWorkflowStepCompleted, markWorkflowStepFailed, markWorkflowStepRunning, } from "../../../persistence/repositories/workflows/workflowRepository.js";
+export function createWorkflowWorker(options) {
+    return new Worker("workflows", async (job) => {
+        await executeWorkflow(job.data.executionId, options);
+    }, {
+        prefix: "{flowwatch}",
+        connection: {
+            url: options.redisUrl,
+        },
+    });
+}
+export async function executeWorkflow(executionId, worker) {
+    const result = await getWorkflowExecution(worker.pool, executionId);
+    if (!result) {
+        throw new Error("No workflow exists with that id");
+    }
+    const executions = await getWorkflowExecutionSteps(worker.pool, executionId);
+    if (executions.length === 0) {
+        throw new Error("No workflow execution steps exists");
+    }
+    const workflowToExecute = worker.getWorkflow(result.workflow_name);
+    if (!workflowToExecute) {
+        throw new Error("Cannot find workflow in the working memory");
+    }
+    await markWorkflowExecutionRunning(worker.pool, executionId);
+    try {
+        let lastStepOutput;
+        for (const stepExecution of executions) {
+            if (stepExecution.status === "completed") {
+                continue;
+            }
+            const registeredStep = workflowToExecute.steps.find((step) => {
+                return step.name === stepExecution.step_name;
+            });
+            if (!registeredStep) {
+                throw new Error(`Cannot find registered step: ${stepExecution.step_name}`);
+            }
+            let attempt = stepExecution.attempt_count;
+            const maxAttempts = stepExecution.max_retries + 1;
+            while (attempt < maxAttempts) {
+                await markWorkflowStepRunning(worker.pool, stepExecution.id);
+                try {
+                    lastStepOutput = await worker.traceEngine.trace(`flowwatch.workflow.step.${stepExecution.step_name}`, "workflow_step", async () => registeredStep.run(stepExecution.input), {
+                        workflowName: result.workflow_name,
+                        workflowVersion: result.workflow_version,
+                        executionId,
+                        stepExecutionId: stepExecution.id,
+                        stepName: stepExecution.step_name,
+                        stepIndex: stepExecution.step_index,
+                        attempt: attempt + 1,
+                    });
+                    await markWorkflowStepCompleted(worker.pool, stepExecution.id, lastStepOutput);
+                    break;
+                }
+                catch (error) {
+                    attempt += 1;
+                    await worker.captureError(error, {
+                        source: "workflow",
+                        category: "server",
+                        level: "error",
+                        statusCode: 500,
+                        metadata: {
+                            workflowName: result.workflow_name,
+                            workflowVersion: result.workflow_version,
+                            executionId,
+                            stepExecutionId: stepExecution.id,
+                            stepName: stepExecution.step_name,
+                            stepIndex: stepExecution.step_index,
+                            attempt,
+                            maxAttempts,
+                        },
+                    });
+                    await markWorkflowStepFailed(worker.pool, stepExecution.id, error);
+                    if (attempt >= maxAttempts) {
+                        throw error;
+                    }
+                }
+            }
+        }
+        await markWorkflowExecutionCompleted(worker.pool, executionId, lastStepOutput);
+    }
+    catch (error) {
+        await worker.captureError(error, {
+            source: "workflow",
+            category: "server",
+            level: "error",
+            statusCode: 500,
+            metadata: {
+                workflowName: result.workflow_name,
+                workflowVersion: result.workflow_version,
+                executionId,
+            },
+        });
+        await markWorkflowExecutionFailed(worker.pool, executionId, error);
+        throw error;
+    }
+}

package/dist/engine/errors/errorEngine.d.ts

@@ -0,0 +1,27 @@
+import type { ErrorRequestHandler } from "express";
+import type { Pool } from "pg";
+import type { Client } from "@elastic/elasticsearch";
+import { type ErrorCategory, type ErrorLevel, type ErrorRow, type ErrorSource } from "../../persistence/repositories/errors/errorRepository.js";
+export interface NormalizedError {
+    name: string;
+    message: string;
+    stack?: string;
+}
+export interface ErrorEngineOptions {
+    pool: Pool;
+    elasticsearchClient: Client;
+}
+export interface CaptureErrorOptions {
+    source: ErrorSource;
+    category?: ErrorCategory;
+    level?: ErrorLevel;
+    statusCode?: number;
+    metadata?: unknown;
+    occurredAt?: Date;
+}
+export type CaptureErrorFunction = (error: unknown, options: CaptureErrorOptions) => Promise<ErrorRow | undefined>;
+export declare function createErrorHandler(options: ErrorEngineOptions): ErrorRequestHandler;
+export declare function captureError(engineOptions: ErrorEngineOptions, error: unknown, captureOptions: CaptureErrorOptions): Promise<ErrorRow | undefined>;
+export declare function normalizeError(error: unknown): NormalizedError;
+export declare function getStatusCode(error: unknown, responseStatusCode: number): number;
+export declare function getErrorCategory(statusCode: number): ErrorCategory;

package/dist/engine/errors/errorEngine.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { getCurrentTraceId, getCurrentSpanId } from "../../runtime/tracing/traceContext.js";
+import { createError, } from "../../persistence/repositories/errors/errorRepository.js";
+import { indexError } from "../../search/elasticsearch/indexer.js";
+export function createErrorHandler(options) {
+    return async function flowwatchErrorHandler(error, req, res, next) {
+        const normalizedError = normalizeError(error);
+        const statusCode = getStatusCode(error, res.statusCode);
+        // Log every uncaught error with route info so we can trace the primary cause
+        console.error(`[Flowwatch] Unhandled error on ${req.method} ${req.originalUrl || req.path}:`, normalizedError.message);
+        await captureError(options, error, {
+            source: "http",
+            category: getErrorCategory(statusCode),
+            level: "error",
+            statusCode,
+            metadata: {
+                method: req.method,
+                path: req.originalUrl || req.path,
+            },
+        });
+        if (res.headersSent) {
+            return next(error);
+        }
+        res.status(statusCode).json({
+            message: statusCode >= 500 ? "Internal server error" : normalizedError.message,
+        });
+    };
+}
+export async function captureError(engineOptions, error, captureOptions) {
+    const normalizedError = normalizeError(error);
+    const statusCode = captureOptions.statusCode ?? getStatusCode(error, 500);
+    const category = captureOptions.category ?? getErrorCategory(statusCode);
+    const fingerprint = createErrorFingerprint({
+        source: captureOptions.source,
+        category,
+        name: normalizedError.name,
+        message: normalizedError.message,
+        statusCode,
+    });
+    try {
+        const storedError = await createError(engineOptions.pool, {
+            traceId: getCurrentTraceId(),
+            spanId: getCurrentSpanId(),
+            source: captureOptions.source,
+            category,
+            level: captureOptions.level ?? "error",
+            message: normalizedError.message,
+            stack: normalizedError.stack,
+            name: normalizedError.name,
+            statusCode,
+            fingerprint,
+            metadata: captureOptions.metadata,
+            occurredAt: captureOptions.occurredAt,
+        });
+        try {
+            await indexError(engineOptions.elasticsearchClient, storedError);
+        }
+        catch (errorIndexingFailure) {
+            console.error("Failed to index error", errorIndexingFailure);
+        }
+        return storedError;
+    }
+    catch (errorCaptureFailure) {
+        console.error("[Flowwatch] Failed to capture error", errorCaptureFailure);
+        return undefined;
+    }
+}
+export function normalizeError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    if (typeof error === "string") {
+        return {
+            name: "UnknownError",
+            message: error,
+        };
+    }
+    return {
+        name: "UnknownError",
+        message: "Unknown error",
+    };
+}
+export function getStatusCode(error, responseStatusCode) {
+    if (typeof error === "object" && error !== null) {
+        const errorObject = error;
+        if (typeof errorObject.statusCode === "number") {
+            return errorObject.statusCode;
+        }
+        if (typeof errorObject.status === "number") {
+            return errorObject.status;
+        }
+    }
+    if (responseStatusCode >= 400) {
+        return responseStatusCode;
+    }
+    return 500;
+}
+export function getErrorCategory(statusCode) {
+    if (statusCode >= 400 && statusCode < 500) {
+        return "client";
+    }
+    if (statusCode >= 500 && statusCode < 600) {
+        return "server";
+    }
+    return "unknown";
+}
+function createErrorFingerprint(input) {
+    return createHash("sha256")
+        .update(`${input.source}:${input.category}:${input.name}:${input.message}:${input.statusCode}`)
+        .digest("hex");
+}

package/dist/engine/flags/evaluateFlag.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureFlagRow, FeatureFlagRuleRow } from "../../persistence/repositories/flags/flagRepository.js";
+import type { FlagContext } from "./types.js";
+export declare function evaluateFlag(flag: FeatureFlagRow | undefined, rules: FeatureFlagRuleRow[], context?: FlagContext): boolean;

package/dist/engine/flags/evaluateFlag.js

@@ -0,0 +1,50 @@
+import { getRolloutBucket } from "./hashRollout.js";
+export function evaluateFlag(flag, rules, context = {}) {
+    if (!flag) {
+        return false;
+    }
+    if (!flag.enabled) {
+        return false;
+    }
+    for (const rule of rules) {
+        if (rule.enabled && ruleMatches(rule, context)) {
+            return true;
+        }
+    }
+    if (flag.rollout_percentage >= 100) {
+        return true;
+    }
+    if (flag.rollout_percentage <= 0) {
+        return false;
+    }
+    if (!context.userId) {
+        return false;
+    }
+    const bucket = getRolloutBucket(flag.key, context.userId);
+    return bucket < flag.rollout_percentage;
+}
+function ruleMatches(rule, context) {
+    const contextValue = context[rule.attribute];
+    switch (rule.operator) {
+        case "equals":
+            return contextValue === rule.value;
+        case "not_equals":
+            return contextValue !== rule.value;
+        case "in":
+            return Array.isArray(rule.value) && rule.value.includes(contextValue);
+        case "not_in":
+            return Array.isArray(rule.value) && !rule.value.includes(contextValue);
+        case "contains":
+            return typeof contextValue === "string" && typeof rule.value === "string" && contextValue.includes(rule.value);
+        case "starts_with":
+            return typeof contextValue === "string" && typeof rule.value === "string" && contextValue.startsWith(rule.value);
+        case "ends_with":
+            return typeof contextValue === "string" && typeof rule.value === "string" && contextValue.endsWith(rule.value);
+        case "greater_than":
+            return typeof contextValue === "number" && typeof rule.value === "number" && contextValue > rule.value;
+        case "less_than":
+            return typeof contextValue === "number" && typeof rule.value === "number" && contextValue < rule.value;
+        default:
+            return false;
+    }
+}

package/dist/engine/flags/flagEngine.d.ts

@@ -0,0 +1,9 @@
+import type { Pool } from "pg";
+import type { CaptureErrorFunction } from "../errors/errorEngine.js";
+import type { TraceEngine } from "../trace/traceEngine.js";
+import type { EvaluateFlag } from "./types.js";
+import type { Redis } from "ioredis";
+export interface FlagEngine {
+    flag: EvaluateFlag;
+}
+export declare function createFlagEngine(pool: Pool, traceEngine: TraceEngine, captureError: CaptureErrorFunction, redisClient: Redis): FlagEngine;

package/dist/engine/flags/flagEngine.js

@@ -0,0 +1,52 @@
+import { getFlagByKey, listFlagRules } from "../../persistence/repositories/flags/flagRepository.js";
+import { evaluateFlag } from "./evaluateFlag.js";
+export function createFlagEngine(pool, traceEngine, captureError, redisClient) {
+    async function flag(key, context = {}) {
+        try {
+            return await traceEngine.trace("flowwatch.feature_flag.evaluate", "feature_flag", async () => {
+                const cacheKey = `flowwatch:flags:${key}`;
+                // Cache read — non-fatal, falls back to DB on any Redis error
+                try {
+                    const cachedValue = await redisClient.get(cacheKey);
+                    if (cachedValue) {
+                        const cached = JSON.parse(cachedValue);
+                        return evaluateFlag(cached.flag, cached.rules, context);
+                    }
+                }
+                catch {
+                    // Redis unavailable or version mismatch — continue to DB
+                }
+                const storedFlag = await getFlagByKey(pool, key);
+                if (!storedFlag) {
+                    return false;
+                }
+                const rules = await listFlagRules(pool, key);
+                // Cache write — non-fatal
+                try {
+                    await redisClient.set(cacheKey, JSON.stringify({ flag: storedFlag, rules }), "EX", 60);
+                }
+                catch {
+                    // Cache write failed — not critical
+                }
+                return evaluateFlag(storedFlag, rules, context);
+            }, {
+                flagKey: key,
+            });
+        }
+        catch (error) {
+            await captureError(error, {
+                source: "feature_flag",
+                category: "server",
+                level: "error",
+                statusCode: 500,
+                metadata: {
+                    flagKey: key,
+                },
+            });
+            throw error;
+        }
+    }
+    return {
+        flag,
+    };
+}

package/dist/engine/flags/hashRollout.d.ts

@@ -0,0 +1 @@
+export declare function getRolloutBucket(flagKey: string, userId: string): number;

package/dist/engine/flags/hashRollout.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+export function getRolloutBucket(flagKey, userId) {
+    const hash = createHash("sha256")
+        .update(`${flagKey}:${userId}`)
+        .digest("hex");
+    const firstEightHexChars = hash.slice(0, 8);
+    const value = Number.parseInt(firstEightHexChars, 16);
+    return value % 100;
+}

package/dist/engine/flags/types.d.ts

@@ -0,0 +1,7 @@
+export interface FlagContext {
+    userId?: string;
+    role?: string;
+    email?: string;
+    [key: string]: unknown;
+}
+export type EvaluateFlag = (key: string, context?: FlagContext) => Promise<boolean>;

package/dist/engine/flags/types.js

@@ -0,0 +1 @@
+export {};

package/dist/engine/trace/traceEngine.d.ts

@@ -0,0 +1,26 @@
+import type { Client } from "@elastic/elasticsearch";
+import type { Pool } from "pg";
+import { type TraceSpanType, type TraceStatus } from "../../persistence/repositories/traces/traceRepository.js";
+export interface ActiveTraceSpan {
+    id: string;
+    startedAt: number;
+}
+export interface StartSpanOptions {
+    metadata?: unknown;
+}
+export interface EndSpanOptions {
+    metadata?: unknown;
+}
+export type TraceCallback<T> = () => T | Promise<T>;
+export type TraceFunction = <T>(name: string, type: TraceSpanType, callback: TraceCallback<T>, metadata?: unknown) => Promise<T>;
+export interface TraceEngine {
+    trace: TraceFunction;
+}
+export interface TraceEngineOptions {
+    pool: Pool;
+    elasticsearchClient: Client;
+}
+export declare function createTraceEngine(options: TraceEngineOptions): TraceEngine;
+export declare function startSpan(pool: Pool, name: string, type: TraceSpanType, options?: StartSpanOptions): Promise<ActiveTraceSpan | undefined>;
+export declare function endSpan(pool: Pool, elasticsearchClient: Client, span: ActiveTraceSpan | undefined, status: TraceStatus, options?: EndSpanOptions): Promise<void>;
+export declare function runInsideSpan<T>(span: ActiveTraceSpan | undefined, callback: TraceCallback<T>): T | Promise<T>;

package/dist/engine/trace/traceEngine.js

@@ -0,0 +1,76 @@
+import { createTraceSpan, finishTraceSpan } from "../../persistence/repositories/traces/traceRepository.js";
+import { getCurrentSpanId, getCurrentTraceId, runWithSpanContext } from "../../runtime/tracing/traceContext.js";
+import { indexTraceSpan } from "../../search/elasticsearch/indexer.js";
+import { captureError } from "../errors/errorEngine.js";
+export function createTraceEngine(options) {
+    const { pool, elasticsearchClient } = options;
+    async function trace(name, type, callback, metadata) {
+        const span = await startSpan(pool, name, type, { metadata });
+        try {
+            const result = await runInsideSpan(span, callback);
+            await endSpan(pool, elasticsearchClient, span, "ok");
+            return result;
+        }
+        catch (error) {
+            await endSpan(pool, elasticsearchClient, span, "error");
+            await captureError(options, error, {
+                source: "unknown",
+                category: "server",
+                level: "error",
+                statusCode: 500,
+                metadata: {
+                    spanName: name,
+                    spanType: type,
+                    spanMetadata: metadata,
+                },
+            });
+            throw error;
+        }
+    }
+    return {
+        trace,
+    };
+}
+export async function startSpan(pool, name, type, options = {}) {
+    const traceId = getCurrentTraceId();
+    if (!traceId) {
+        return undefined;
+    }
+    const span = await createTraceSpan(pool, {
+        traceId,
+        parentSpanId: getCurrentSpanId(),
+        name,
+        type,
+        metadata: options.metadata,
+    });
+    return {
+        id: span.id,
+        startedAt: Date.now(),
+    };
+}
+export async function endSpan(pool, elasticsearchClient, span, status, options = {}) {
+    if (!span) {
+        return;
+    }
+    const finishedSpan = await finishTraceSpan(pool, {
+        spanId: span.id,
+        status,
+        durationMs: Date.now() - span.startedAt,
+        metadata: options.metadata,
+    });
+    if (!finishedSpan) {
+        return;
+    }
+    try {
+        await indexTraceSpan(elasticsearchClient, finishedSpan);
+    }
+    catch (traceIndexingFailure) {
+        console.error("Failed to index trace span", traceIndexingFailure);
+    }
+}
+export function runInsideSpan(span, callback) {
+    if (!span) {
+        return callback();
+    }
+    return runWithSpanContext(span.id, callback);
+}

package/dist/engine/workflows/types.d.ts

@@ -0,0 +1,28 @@
+export type WorkflowStepHandler = (input: unknown) => unknown | Promise<unknown>;
+export type WorkflowStepInputResolver = (workflowInput: unknown) => unknown;
+export interface WorkflowStep {
+    name: string;
+    run: WorkflowStepHandler;
+    retries?: number;
+    input?: unknown | WorkflowStepInputResolver;
+}
+export interface RegisteredWorkflow {
+    name: string;
+    steps: WorkflowStep[];
+    dbWorkflow: {
+        id: string;
+        name: string;
+        version: number;
+    };
+    dbSteps: {
+        id: string;
+        workflowId: string;
+        stepIndex: number;
+        name: string;
+        maxRetries: number;
+    }[];
+}
+export type RegisterWorkflow = (name: string, steps: WorkflowStep[]) => Promise<void>;
+export type TriggerWorkflow = (name: string, input?: unknown) => Promise<{
+    executionId: string;
+}>;

package/dist/engine/workflows/types.js

@@ -0,0 +1 @@
+export {};

package/dist/engine/workflows/workflowEngine.d.ts

@@ -0,0 +1,15 @@
+import type { Pool } from "pg";
+import { type createWorkflowQueue } from "../background/queues/workflowQueue.js";
+import type { TraceEngine } from "../trace/traceEngine.js";
+import type { RegisterWorkflow, RegisteredWorkflow, TriggerWorkflow } from "./types.js";
+export interface WorkflowEngine {
+    workflow: RegisterWorkflow;
+    trigger: TriggerWorkflow;
+    getWorkflow: (name: string) => RegisteredWorkflow | undefined;
+}
+export interface WorkflowEngineOptions {
+    pool: Pool;
+    workflowQueue: ReturnType<typeof createWorkflowQueue> | null;
+    traceEngine: TraceEngine;
+}
+export declare function createWorkflowEngine(options: WorkflowEngineOptions): WorkflowEngine;