@uploadista/core 0.0.18-beta.2 → 0.0.18-beta.4

package/src/types/circuit-breaker-store.ts

@@ -0,0 +1,222 @@
+/**
+ * Circuit Breaker Store - Distributed state storage for circuit breakers.
+ *
+ * This module defines the interface for storing circuit breaker state in
+ * distributed environments. It allows circuit breaker state to be shared
+ * across multiple instances in a cluster.
+ *
+ * @module types/circuit-breaker-store
+ */
+
+import { Context, Effect, Layer } from "effect";
+import { UploadistaError } from "../errors";
+
+// ============================================================================
+// State Types
+// ============================================================================
+
+/**
+ * Circuit breaker state values.
+ */
+export type CircuitBreakerStateValue = "closed" | "open" | "half-open";
+
+/**
+ * Persisted circuit breaker state data.
+ *
+ * This represents the full state of a circuit breaker that needs to be
+ * stored and shared across instances.
+ */
+export interface CircuitBreakerStateData {
+  /** Current circuit state */
+  state: CircuitBreakerStateValue;
+  /** Number of failures in current window */
+  failureCount: number;
+  /** Timestamp of last state transition */
+  lastStateChange: number;
+  /** Number of successful requests in half-open state */
+  halfOpenSuccesses: number;
+  /** Timestamp when the current failure window started */
+  windowStart: number;
+  /** Configuration snapshot for consistency */
+  config: {
+    failureThreshold: number;
+    resetTimeout: number;
+    halfOpenRequests: number;
+    windowDuration: number;
+  };
+}
+
+/**
+ * Statistics about a circuit breaker.
+ */
+export interface CircuitBreakerStats {
+  nodeType: string;
+  state: CircuitBreakerStateValue;
+  failureCount: number;
+  halfOpenSuccesses: number;
+  timeSinceLastStateChange: number;
+  timeUntilHalfOpen?: number; // Only when state is "open"
+}
+
+// ============================================================================
+// Store Interface
+// ============================================================================
+
+/**
+ * Interface for circuit breaker state storage.
+ *
+ * Implementations should handle distributed state for circuit breakers,
+ * allowing multiple instances to share circuit state. The interface is
+ * designed to work with eventually consistent stores - perfect consistency
+ * is not required for circuit breaker functionality.
+ *
+ * @example
+ * ```typescript
+ * // Using the store
+ * const store: CircuitBreakerStore = yield* CircuitBreakerStoreService;
+ *
+ * // Record a failure
+ * const newCount = yield* store.incrementFailures("describe-image", 60000);
+ * if (newCount >= 5) {
+ *   yield* store.setState("describe-image", {
+ *     state: "open",
+ *     failureCount: newCount,
+ *     lastStateChange: Date.now(),
+ *     // ...
+ *   });
+ * }
+ * ```
+ */
+export interface CircuitBreakerStore {
+  /**
+   * Gets the current state data for a circuit breaker.
+   *
+   * @param nodeType - The node type identifier
+   * @returns The state data or null if no state exists
+   */
+  readonly getState: (
+    nodeType: string,
+  ) => Effect.Effect<CircuitBreakerStateData | null, UploadistaError>;
+
+  /**
+   * Sets the complete state for a circuit breaker.
+   *
+   * @param nodeType - The node type identifier
+   * @param state - The new state data
+   */
+  readonly setState: (
+    nodeType: string,
+    state: CircuitBreakerStateData,
+  ) => Effect.Effect<void, UploadistaError>;
+
+  /**
+   * Increments the failure count and returns the new count.
+   *
+   * This operation should be atomic where possible. For stores that don't
+   * support atomic increment, a read-modify-write is acceptable as circuit
+   * breakers tolerate eventual consistency.
+   *
+   * The implementation should also handle window expiry - if the window
+   * has expired, reset the count before incrementing.
+   *
+   * @param nodeType - The node type identifier
+   * @param windowDuration - Duration of the sliding window in milliseconds
+   * @returns The new failure count after incrementing
+   */
+  readonly incrementFailures: (
+    nodeType: string,
+    windowDuration: number,
+  ) => Effect.Effect<number, UploadistaError>;
+
+  /**
+   * Resets the failure count to zero.
+   *
+   * Called when circuit closes or on successful requests.
+   *
+   * @param nodeType - The node type identifier
+   */
+  readonly resetFailures: (
+    nodeType: string,
+  ) => Effect.Effect<void, UploadistaError>;
+
+  /**
+   * Increments the half-open success count.
+   *
+   * @param nodeType - The node type identifier
+   * @returns The new half-open success count
+   */
+  readonly incrementHalfOpenSuccesses: (
+    nodeType: string,
+  ) => Effect.Effect<number, UploadistaError>;
+
+  /**
+   * Gets statistics for all tracked circuit breakers.
+   *
+   * @returns Map of node type to stats
+   */
+  readonly getAllStats: () => Effect.Effect<
+    Map<string, CircuitBreakerStats>,
+    UploadistaError
+  >;
+
+  /**
+   * Deletes circuit breaker state for a node type.
+   *
+   * @param nodeType - The node type identifier
+   */
+  readonly delete: (nodeType: string) => Effect.Effect<void, UploadistaError>;
+}
+
+// ============================================================================
+// Effect Context
+// ============================================================================
+
+/**
+ * Effect-TS context tag for the CircuitBreakerStore service.
+ *
+ * Use this to inject a circuit breaker store into your Effect programs.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const cbStore = yield* CircuitBreakerStoreService;
+ *   const state = yield* cbStore.getState("my-node-type");
+ *   // ...
+ * });
+ *
+ * // Provide the implementation
+ * const result = yield* program.pipe(
+ *   Effect.provide(kvCircuitBreakerStoreLayer)
+ * );
+ * ```
+ */
+export class CircuitBreakerStoreService extends Context.Tag(
+  "CircuitBreakerStoreService",
+)<CircuitBreakerStoreService, CircuitBreakerStore>() {}
+
+// ============================================================================
+// Default State Factory
+// ============================================================================
+
+/**
+ * Creates a default initial state for a circuit breaker.
+ *
+ * @param config - Circuit breaker configuration
+ * @returns Initial state data with closed circuit
+ */
+export function createInitialCircuitBreakerState(config: {
+  failureThreshold: number;
+  resetTimeout: number;
+  halfOpenRequests: number;
+  windowDuration: number;
+}): CircuitBreakerStateData {
+  const now = Date.now();
+  return {
+    state: "closed",
+    failureCount: 0,
+    lastStateChange: now,
+    halfOpenSuccesses: 0,
+    windowStart: now,
+    config,
+  };
+}

package/src/types/index.ts

@@ -1,3 +1,4 @@
+export * from "./circuit-breaker-store";
 export * from "./data-store";
 export * from "./event-broadcaster";
 export * from "./event-emitter";

package/tests/flow/file-naming.test.ts

@@ -0,0 +1,390 @@
+import { describe, expect, it } from "vitest";
+
+import type { UploadFile } from "../../src/types/upload-file";
+import {
+  AVAILABLE_TEMPLATE_VARIABLES,
+  applyFileNaming,
+  buildNamingContext,
+  getBaseName,
+  getExtension,
+  interpolateFileName,
+  validatePattern,
+} from "../../src/flow/utils/file-naming";
+
+// Mock UploadFile for testing
+const createMockFile = (overrides?: Partial<UploadFile>): UploadFile => ({
+  id: "file-123",
+  offset: 0,
+  storage: { id: "storage-1", type: "S3", bucket: "test-bucket" },
+  size: 1024,
+  url: "https://example.com/file.jpg",
+  metadata: {
+    fileName: "photo.jpg",
+    width: 1920,
+    height: 1080,
+  },
+  ...overrides,
+});
+
+describe("getBaseName", () => {
+  it("should extract base name from filename with extension", () => {
+    expect(getBaseName("photo.jpg")).toBe("photo");
+    expect(getBaseName("document.pdf")).toBe("document");
+    expect(getBaseName("video.mp4")).toBe("video");
+  });
+
+  it("should handle multiple dots in filename", () => {
+    expect(getBaseName("document.tar.gz")).toBe("document.tar");
+    expect(getBaseName("file.name.with.dots.txt")).toBe("file.name.with.dots");
+  });
+
+  it("should return full name if no extension", () => {
+    expect(getBaseName("noextension")).toBe("noextension");
+    expect(getBaseName("README")).toBe("README");
+  });
+
+  it("should handle hidden files (starting with dot)", () => {
+    expect(getBaseName(".gitignore")).toBe(".gitignore");
+    expect(getBaseName(".env")).toBe(".env");
+  });
+
+  it("should handle empty string", () => {
+    expect(getBaseName("")).toBe("");
+  });
+});
+
+describe("getExtension", () => {
+  it("should extract extension from filename", () => {
+    expect(getExtension("photo.jpg")).toBe("jpg");
+    expect(getExtension("document.pdf")).toBe("pdf");
+    expect(getExtension("video.MP4")).toBe("MP4");
+  });
+
+  it("should return last extension for multiple dots", () => {
+    expect(getExtension("document.tar.gz")).toBe("gz");
+    expect(getExtension("file.name.txt")).toBe("txt");
+  });
+
+  it("should return empty string if no extension", () => {
+    expect(getExtension("noextension")).toBe("");
+    expect(getExtension("README")).toBe("");
+  });
+
+  it("should handle hidden files", () => {
+    expect(getExtension(".gitignore")).toBe("");
+    expect(getExtension(".env")).toBe("");
+  });
+
+  it("should handle empty string", () => {
+    expect(getExtension("")).toBe("");
+  });
+});
+
+describe("buildNamingContext", () => {
+  it("should build context from file and flow context", () => {
+    const file = createMockFile();
+    const flowContext = {
+      flowId: "flow-abc",
+      jobId: "job-123",
+      nodeId: "resize-1",
+      nodeType: "resize",
+    };
+
+    const context = buildNamingContext(file, flowContext);
+
+    expect(context.baseName).toBe("photo");
+    expect(context.extension).toBe("jpg");
+    expect(context.fileName).toBe("photo.jpg");
+    expect(context.nodeType).toBe("resize");
+    expect(context.nodeId).toBe("resize-1");
+    expect(context.flowId).toBe("flow-abc");
+    expect(context.jobId).toBe("job-123");
+    expect(context.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/); // ISO format
+  });
+
+  it("should include extra variables", () => {
+    const file = createMockFile();
+    const flowContext = {
+      flowId: "flow-abc",
+      jobId: "job-123",
+      nodeId: "resize-1",
+      nodeType: "resize",
+    };
+    const extraVars = { width: 800, height: 600, format: "webp" };
+
+    const context = buildNamingContext(file, flowContext, extraVars);
+
+    expect(context.width).toBe(800);
+    expect(context.height).toBe(600);
+    expect(context.format).toBe("webp");
+  });
+
+  it("should use fallback for missing fileName", () => {
+    const file = createMockFile({ metadata: {} });
+    const flowContext = {
+      flowId: "flow-abc",
+      jobId: "job-123",
+      nodeId: "node-1",
+      nodeType: "process",
+    };
+
+    const context = buildNamingContext(file, flowContext);
+
+    expect(context.fileName).toBe("unnamed");
+    expect(context.baseName).toBe("unnamed");
+    expect(context.extension).toBe("");
+  });
+
+  it("should handle originalName as fallback", () => {
+    const file = createMockFile({
+      metadata: { originalName: "original-file.png" },
+    });
+    const flowContext = {
+      flowId: "flow-abc",
+      jobId: "job-123",
+      nodeId: "node-1",
+      nodeType: "process",
+    };
+
+    const context = buildNamingContext(file, flowContext);
+
+    expect(context.fileName).toBe("original-file.png");
+    expect(context.baseName).toBe("original-file");
+    expect(context.extension).toBe("png");
+  });
+});
+
+describe("interpolateFileName", () => {
+  const sampleContext = {
+    baseName: "photo",
+    extension: "jpg",
+    fileName: "photo.jpg",
+    nodeType: "resize",
+    nodeId: "resize-1",
+    flowId: "flow-abc",
+    jobId: "job-123",
+    timestamp: "2024-01-15T10:30:00Z",
+    width: 800,
+    height: 600,
+  };
+
+  it("should interpolate simple variables", () => {
+    const result = interpolateFileName(
+      "{{baseName}}.{{extension}}",
+      sampleContext,
+    );
+    expect(result).toBe("photo.jpg");
+  });
+
+  it("should interpolate multiple variables", () => {
+    const result = interpolateFileName(
+      "{{baseName}}-{{width}}x{{height}}.{{extension}}",
+      sampleContext,
+    );
+    expect(result).toBe("photo-800x600.jpg");
+  });
+
+  it("should interpolate with static text", () => {
+    const result = interpolateFileName(
+      "processed-{{baseName}}-final.{{extension}}",
+      sampleContext,
+    );
+    expect(result).toBe("processed-photo-final.jpg");
+  });
+
+  it("should handle missing variables gracefully", () => {
+    const result = interpolateFileName(
+      "{{baseName}}-{{unknownVar}}.{{extension}}",
+      sampleContext,
+    );
+    // micromustache returns empty string for missing vars
+    expect(result).toBe("photo-.jpg");
+  });
+
+  it("should handle pattern without variables", () => {
+    const result = interpolateFileName("static-name.txt", sampleContext);
+    expect(result).toBe("static-name.txt");
+  });
+
+  it("should handle empty pattern", () => {
+    const result = interpolateFileName("", sampleContext);
+    expect(result).toBe("");
+  });
+});
+
+describe("applyFileNaming", () => {
+  const file = createMockFile();
+  const flowContext = {
+    flowId: "flow-abc",
+    jobId: "job-123",
+    nodeId: "resize-1",
+    nodeType: "resize",
+  };
+
+  it("should return original filename when no config", () => {
+    const context = buildNamingContext(file, flowContext);
+    const result = applyFileNaming(file, context);
+    expect(result).toBe("photo.jpg");
+  });
+
+  it("should return original filename when no config is undefined", () => {
+    const context = buildNamingContext(file, flowContext);
+    const result = applyFileNaming(file, context, undefined);
+    expect(result).toBe("photo.jpg");
+  });
+
+  it("should apply auto naming with suffix", () => {
+    const context = buildNamingContext(file, flowContext, {
+      width: 800,
+      height: 600,
+    });
+    const config = {
+      mode: "auto" as const,
+      autoSuffix: (ctx: typeof context) => `${ctx.width}x${ctx.height}`,
+    };
+
+    const result = applyFileNaming(file, context, config);
+    expect(result).toBe("photo-800x600.jpg");
+  });
+
+  it("should return original when auto mode has no suffix generator", () => {
+    const context = buildNamingContext(file, flowContext);
+    const config = { mode: "auto" as const };
+
+    const result = applyFileNaming(file, context, config);
+    expect(result).toBe("photo.jpg");
+  });
+
+  it("should apply custom naming with template pattern", () => {
+    const context = buildNamingContext(file, flowContext, {
+      width: 800,
+      height: 600,
+    });
+    const config = {
+      mode: "custom" as const,
+      pattern: "{{baseName}}-{{nodeType}}-{{width}}w.{{extension}}",
+    };
+
+    const result = applyFileNaming(file, context, config);
+    expect(result).toBe("photo-resize-800w.jpg");
+  });
+
+  it("should apply custom naming with rename function", () => {
+    const context = buildNamingContext(file, flowContext);
+    const config = {
+      mode: "custom" as const,
+      rename: (_file: UploadFile, ctx: typeof context) =>
+        `custom-${ctx.baseName}.${ctx.extension}`,
+    };
+
+    const result = applyFileNaming(file, context, config);
+    expect(result).toBe("custom-photo.jpg");
+  });
+
+  it("should prefer rename function over pattern in custom mode", () => {
+    const context = buildNamingContext(file, flowContext);
+    const config = {
+      mode: "custom" as const,
+      pattern: "pattern-{{baseName}}.{{extension}}",
+      rename: () => "function-result.jpg",
+    };
+
+    const result = applyFileNaming(file, context, config);
+    expect(result).toBe("function-result.jpg");
+  });
+
+  it("should handle file without extension in auto mode", () => {
+    const noExtFile = createMockFile({
+      metadata: { fileName: "noextension" },
+    });
+    const context = buildNamingContext(noExtFile, flowContext);
+    const config = {
+      mode: "auto" as const,
+      autoSuffix: () => "processed",
+    };
+
+    const result = applyFileNaming(noExtFile, context, config);
+    expect(result).toBe("noextension-processed");
+  });
+
+  it("should fallback to original on error in rename function", () => {
+    const context = buildNamingContext(file, flowContext);
+    const config = {
+      mode: "custom" as const,
+      rename: () => {
+        throw new Error("Intentional error");
+      },
+    };
+
+    const result = applyFileNaming(file, context, config);
+    expect(result).toBe("photo.jpg");
+  });
+});
+
+describe("validatePattern", () => {
+  it("should accept valid patterns", () => {
+    expect(validatePattern("{{baseName}}.{{extension}}")).toEqual({
+      isValid: true,
+    });
+    expect(
+      validatePattern("{{baseName}}-{{width}}x{{height}}.{{extension}}"),
+    ).toEqual({ isValid: true });
+    expect(validatePattern("static-name.txt")).toEqual({ isValid: true });
+  });
+
+  it("should reject empty pattern", () => {
+    const result = validatePattern("");
+    expect(result.isValid).toBe(false);
+    expect(result.error).toContain("empty");
+  });
+
+  it("should reject whitespace-only pattern", () => {
+    const result = validatePattern("   ");
+    expect(result.isValid).toBe(false);
+    expect(result.error).toContain("empty");
+  });
+
+  it("should reject unbalanced braces", () => {
+    let result = validatePattern("{{baseName");
+    expect(result.isValid).toBe(false);
+    expect(result.error).toContain("Unbalanced");
+
+    result = validatePattern("baseName}}");
+    expect(result.isValid).toBe(false);
+    expect(result.error).toContain("Unbalanced");
+
+    result = validatePattern("{{a}}{{b");
+    expect(result.isValid).toBe(false);
+    expect(result.error).toContain("Unbalanced");
+  });
+
+  it("should accept patterns with no variables", () => {
+    expect(validatePattern("static-file.txt")).toEqual({ isValid: true });
+  });
+});
+
+describe("AVAILABLE_TEMPLATE_VARIABLES", () => {
+  it("should include all expected variables", () => {
+    const varNames = AVAILABLE_TEMPLATE_VARIABLES.map((v) => v.name);
+
+    expect(varNames).toContain("baseName");
+    expect(varNames).toContain("extension");
+    expect(varNames).toContain("fileName");
+    expect(varNames).toContain("nodeType");
+    expect(varNames).toContain("nodeId");
+    expect(varNames).toContain("flowId");
+    expect(varNames).toContain("jobId");
+    expect(varNames).toContain("timestamp");
+    expect(varNames).toContain("width");
+    expect(varNames).toContain("height");
+    expect(varNames).toContain("format");
+  });
+
+  it("should have description and example for each variable", () => {
+    for (const variable of AVAILABLE_TEMPLATE_VARIABLES) {
+      expect(variable.name).toBeTruthy();
+      expect(variable.description).toBeTruthy();
+      expect(variable.example).toBeTruthy();
+    }
+  });
+});