@uploadista/server 0.0.3

package/src/cache.test.ts

@@ -0,0 +1,306 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import {
+  AuthCacheService,
+  AuthCacheServiceLive,
+  NoAuthCacheServiceLive,
+} from "./cache";
+import type { AuthContext } from "./types";
+
+describe("AuthCacheService", () => {
+  describe("AuthCacheServiceLive", () => {
+    it("should set and get auth context", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+        metadata: { role: "admin" },
+      };
+
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        // Set auth context
+        yield* cache.set("job-1", authContext);
+
+        // Get auth context
+        const retrieved = yield* cache.get("job-1");
+
+        expect(retrieved).toEqual(authContext);
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive())),
+      );
+    });
+
+    it("should return null for non-existent job ID", async () => {
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        const retrieved = yield* cache.get("non-existent");
+
+        expect(retrieved).toBeNull();
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive())),
+      );
+    });
+
+    it("should delete cached auth context", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+      };
+
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        // Set and verify
+        yield* cache.set("job-1", authContext);
+        const before = yield* cache.get("job-1");
+        expect(before).toEqual(authContext);
+
+        // Delete
+        yield* cache.delete("job-1");
+
+        // Verify deleted
+        const after = yield* cache.get("job-1");
+        expect(after).toBeNull();
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive())),
+      );
+    });
+
+    it("should clear all cached auth contexts", async () => {
+      const authContext1: AuthContext = { clientId: "user-1" };
+      const authContext2: AuthContext = { clientId: "user-2" };
+
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        // Set multiple entries
+        yield* cache.set("job-1", authContext1);
+        yield* cache.set("job-2", authContext2);
+
+        const sizeBefore = yield* cache.size();
+        expect(sizeBefore).toBe(2);
+
+        // Clear all
+        yield* cache.clear();
+
+        const sizeAfter = yield* cache.size();
+        expect(sizeAfter).toBe(0);
+
+        // Verify both deleted
+        const job1 = yield* cache.get("job-1");
+        const job2 = yield* cache.get("job-2");
+        expect(job1).toBeNull();
+        expect(job2).toBeNull();
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive())),
+      );
+    });
+
+    it("should track cache size", async () => {
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        let size = yield* cache.size();
+        expect(size).toBe(0);
+
+        yield* cache.set("job-1", { clientId: "user-1" });
+        size = yield* cache.size();
+        expect(size).toBe(1);
+
+        yield* cache.set("job-2", { clientId: "user-2" });
+        size = yield* cache.size();
+        expect(size).toBe(2);
+
+        yield* cache.delete("job-1");
+        size = yield* cache.size();
+        expect(size).toBe(1);
+
+        yield* cache.clear();
+        size = yield* cache.size();
+        expect(size).toBe(0);
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive())),
+      );
+    });
+
+    it("should evict expired entries", async () => {
+      // Set very short TTL for testing
+      const shortTtl = 50; // 50ms
+
+      const authContext: AuthContext = {
+        clientId: "user-123",
+      };
+
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        // Set auth context
+        yield* cache.set("job-1", authContext);
+
+        // Verify it's there immediately
+        const immediate = yield* cache.get("job-1");
+        expect(immediate).toEqual(authContext);
+
+        // Wait for TTL to expire
+        yield* Effect.sleep(100); // Wait 100ms (longer than 50ms TTL)
+
+        // Should be evicted now
+        const afterExpiry = yield* cache.get("job-1");
+        expect(afterExpiry).toBeNull();
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive({ ttl: shortTtl }))),
+      );
+    });
+
+    it("should enforce max size limit with LRU eviction", async () => {
+      const maxSize = 3;
+
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        // Add entries up to max size
+        yield* cache.set("job-1", { clientId: "user-1" });
+        yield* Effect.sleep(10); // Small delay to ensure ordering
+        yield* cache.set("job-2", { clientId: "user-2" });
+        yield* Effect.sleep(10);
+        yield* cache.set("job-3", { clientId: "user-3" });
+
+        let size = yield* cache.size();
+        expect(size).toBe(3);
+
+        // Add one more - should evict oldest (job-1)
+        yield* Effect.sleep(10);
+        yield* cache.set("job-4", { clientId: "user-4" });
+
+        size = yield* cache.size();
+        expect(size).toBe(3); // Still at max size
+
+        // job-1 should be evicted (oldest)
+        const job1 = yield* cache.get("job-1");
+        expect(job1).toBeNull();
+
+        // Others should still exist
+        const job2 = yield* cache.get("job-2");
+        const job3 = yield* cache.get("job-3");
+        const job4 = yield* cache.get("job-4");
+        expect(job2).toEqual({ clientId: "user-2" });
+        expect(job3).toEqual({ clientId: "user-3" });
+        expect(job4).toEqual({ clientId: "user-4" });
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive({ maxSize }))),
+      );
+    });
+
+    it("should handle multiple auth contexts independently", async () => {
+      const authContext1: AuthContext = {
+        clientId: "user-1",
+        metadata: { role: "admin" },
+      };
+      const authContext2: AuthContext = {
+        clientId: "user-2",
+        permissions: ["read", "write"],
+      };
+
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        yield* cache.set("upload-123", authContext1);
+        yield* cache.set("flow-456", authContext2);
+
+        const upload = yield* cache.get("upload-123");
+        const flow = yield* cache.get("flow-456");
+
+        expect(upload).toEqual(authContext1);
+        expect(flow).toEqual(authContext2);
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive())),
+      );
+    });
+
+    it("should update existing entry when setting same job ID", async () => {
+      const authContext1: AuthContext = { clientId: "user-1" };
+      const authContext2: AuthContext = { clientId: "user-2" };
+
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        yield* cache.set("job-1", authContext1);
+        const first = yield* cache.get("job-1");
+        expect(first).toEqual(authContext1);
+
+        // Update with new auth context
+        yield* cache.set("job-1", authContext2);
+        const second = yield* cache.get("job-1");
+        expect(second).toEqual(authContext2);
+
+        // Should still be only 1 entry
+        const size = yield* cache.size();
+        expect(size).toBe(1);
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(AuthCacheServiceLive())),
+      );
+    });
+  });
+
+  describe("NoAuthCacheServiceLive", () => {
+    it("should not cache anything", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+      };
+
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        // Try to set
+        yield* cache.set("job-1", authContext);
+
+        // Should always return null
+        const retrieved = yield* cache.get("job-1");
+        expect(retrieved).toBeNull();
+
+        // Size should always be 0
+        const size = yield* cache.size();
+        expect(size).toBe(0);
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(NoAuthCacheServiceLive)),
+      );
+    });
+
+    it("should handle delete and clear without errors", async () => {
+      const program = Effect.gen(function* () {
+        const cache = yield* AuthCacheService;
+
+        // These should not throw
+        yield* cache.delete("non-existent");
+        yield* cache.clear();
+
+        const size = yield* cache.size();
+        expect(size).toBe(0);
+      });
+
+      await Effect.runPromise(
+        program.pipe(Effect.provide(NoAuthCacheServiceLive)),
+      );
+    });
+  });
+});

package/src/cache.ts

@@ -0,0 +1,204 @@
+import { Context, Effect, Layer } from "effect";
+import type { AuthContext } from "./types";
+
+/**
+ * Configuration options for the auth cache.
+ */
+export type AuthCacheConfig = {
+  /**
+   * Maximum number of entries in the cache.
+   * When exceeded, oldest entries are removed (LRU eviction).
+   * @default 10000
+   */
+  maxSize?: number;
+
+  /**
+   * Time-to-live for cache entries in milliseconds.
+   * Entries older than this will be automatically evicted.
+   * @default 3600000 (1 hour)
+   */
+  ttl?: number;
+};
+
+/**
+ * Cache entry with auth context and timestamp.
+ */
+type CacheEntry = {
+  authContext: AuthContext;
+  timestamp: number;
+};
+
+/**
+ * Auth Cache Service
+ *
+ * Provides caching of authentication contexts for upload and flow jobs.
+ * This allows subsequent operations (chunk uploads, flow continuations)
+ * to reuse the auth context from the initial request without re-authenticating.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { AuthCacheService } from "@uploadista/server";
+ *
+ * const handler = Effect.gen(function* () {
+ *   const authCache = yield* AuthCacheService;
+ *   const authContext = { userId: "user-123" };
+ *
+ *   // Cache auth for upload
+ *   yield* authCache.set("upload-abc", authContext);
+ *
+ *   // Retrieve cached auth later
+ *   const cached = yield* authCache.get("upload-abc");
+ *   console.log(cached?.userId); // "user-123"
+ *
+ *   // Clear when done
+ *   yield* authCache.delete("upload-abc");
+ * });
+ * ```
+ */
+export class AuthCacheService extends Context.Tag("AuthCacheService")<
+  AuthCacheService,
+  {
+    /**
+     * Store an auth context for a job ID.
+     */
+    readonly set: (
+      jobId: string,
+      authContext: AuthContext,
+    ) => Effect.Effect<void>;
+
+    /**
+     * Retrieve a cached auth context by job ID.
+     * Returns null if not found or expired.
+     */
+    readonly get: (jobId: string) => Effect.Effect<AuthContext | null>;
+
+    /**
+     * Delete a cached auth context by job ID.
+     */
+    readonly delete: (jobId: string) => Effect.Effect<void>;
+
+    /**
+     * Clear all cached auth contexts.
+     */
+    readonly clear: () => Effect.Effect<void>;
+
+    /**
+     * Get the current number of cached entries.
+     */
+    readonly size: () => Effect.Effect<number>;
+  }
+>() {}
+
+/**
+ * Creates an AuthCacheService Layer with in-memory storage.
+ *
+ * @param config - Optional configuration for cache behavior
+ * @returns Effect Layer providing AuthCacheService
+ */
+export const AuthCacheServiceLive = (
+  config: AuthCacheConfig = {},
+): Layer.Layer<AuthCacheService> => {
+  const maxSize = config.maxSize ?? 10000;
+  const ttl = config.ttl ?? 3600000; // 1 hour default
+
+  // In-memory cache storage
+  const cache = new Map<string, CacheEntry>();
+
+  /**
+   * Evict expired entries based on TTL.
+   */
+  const evictExpired = (): void => {
+    const now = Date.now();
+    for (const [jobId, entry] of cache.entries()) {
+      if (now - entry.timestamp > ttl) {
+        cache.delete(jobId);
+      }
+    }
+  };
+
+  /**
+   * Enforce max size limit using LRU eviction.
+   * Removes oldest entry when cache exceeds max size.
+   */
+  const enforceSizeLimit = (): void => {
+    if (cache.size <= maxSize) return;
+
+    // Find and remove oldest entry
+    let oldestKey: string | null = null;
+    let oldestTime = Number.POSITIVE_INFINITY;
+
+    for (const [jobId, entry] of cache.entries()) {
+      if (entry.timestamp < oldestTime) {
+        oldestTime = entry.timestamp;
+        oldestKey = jobId;
+      }
+    }
+
+    if (oldestKey) {
+      cache.delete(oldestKey);
+    }
+  };
+
+  return Layer.succeed(AuthCacheService, {
+    set: (jobId: string, authContext: AuthContext) =>
+      Effect.sync(() => {
+        // Evict expired entries periodically
+        if (cache.size % 100 === 0) {
+          evictExpired();
+        }
+
+        cache.set(jobId, {
+          authContext,
+          timestamp: Date.now(),
+        });
+
+        // Enforce size limit after adding
+        enforceSizeLimit();
+      }),
+
+    get: (jobId: string) =>
+      Effect.sync(() => {
+        const entry = cache.get(jobId);
+        if (!entry) return null;
+
+        // Check if expired
+        const now = Date.now();
+        if (now - entry.timestamp > ttl) {
+          cache.delete(jobId);
+          return null;
+        }
+
+        return entry.authContext;
+      }),
+
+    delete: (jobId: string) =>
+      Effect.sync(() => {
+        cache.delete(jobId);
+      }),
+
+    clear: () =>
+      Effect.sync(() => {
+        cache.clear();
+      }),
+
+    size: () =>
+      Effect.sync(() => {
+        return cache.size;
+      }),
+  });
+};
+
+/**
+ * No-op implementation of AuthCacheService.
+ * Does not cache anything - all operations are no-ops.
+ * Used when caching is disabled or not needed.
+ */
+export const NoAuthCacheServiceLive: Layer.Layer<AuthCacheService> =
+  Layer.succeed(AuthCacheService, {
+    set: () => Effect.void,
+    get: () => Effect.succeed(null),
+    delete: () => Effect.void,
+    clear: () => Effect.void,
+    size: () => Effect.succeed(0),
+  });

package/src/error-types.ts

@@ -0,0 +1,172 @@
+import type { UploadistaError } from "@uploadista/core/errors";
+
+/**
+ * Base adapter error class for HTTP adapters.
+ * All adapter-specific errors should extend this class or one of its subclasses.
+ *
+ * @example
+ * ```typescript
+ * throw new AdapterError("Something went wrong", 500, "INTERNAL_ERROR");
+ * ```
+ */
+export class AdapterError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number = 500,
+    public readonly errorCode: string = "INTERNAL_ERROR",
+  ) {
+    super(message);
+    this.name = "AdapterError";
+  }
+}
+
+/**
+ * Validation error - indicates invalid request data or parameters.
+ * Returns HTTP 400 Bad Request status.
+ *
+ * @example
+ * ```typescript
+ * if (!isValidUploadId(id)) {
+ *   throw new ValidationError("Invalid upload ID format");
+ * }
+ * ```
+ */
+export class ValidationError extends AdapterError {
+  constructor(message: string) {
+    super(message, 400, "VALIDATION_ERROR");
+    this.name = "ValidationError";
+  }
+}
+
+/**
+ * Not found error - indicates a requested resource does not exist.
+ * Returns HTTP 404 Not Found status.
+ *
+ * @example
+ * ```typescript
+ * if (!upload) {
+ *   throw new NotFoundError("Upload");
+ * }
+ * ```
+ */
+export class NotFoundError extends AdapterError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 404, "NOT_FOUND");
+    this.name = "NotFoundError";
+  }
+}
+
+/**
+ * Bad request error - indicates a malformed request.
+ * Returns HTTP 400 Bad Request status.
+ * Similar to ValidationError but for request structure issues.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const data = JSON.parse(body);
+ * } catch {
+ *   throw new BadRequestError("Invalid JSON body");
+ * }
+ * ```
+ */
+export class BadRequestError extends AdapterError {
+  constructor(message: string) {
+    super(message, 400, "BAD_REQUEST");
+    this.name = "BadRequestError";
+  }
+}
+
+/**
+ * Creates a standardized error response object for AdapterError.
+ * Includes error message, error code, and ISO timestamp.
+ *
+ * @param error - The AdapterError to format
+ * @returns Standardized error response body
+ *
+ * @example
+ * ```typescript
+ * import { createErrorResponseBody } from "@uploadista/server";
+ *
+ * try {
+ *   // ... operation
+ * } catch (err) {
+ *   const errorResponse = createErrorResponseBody(err);
+ *   res.status(err.statusCode).json(errorResponse);
+ * }
+ * ```
+ */
+export const createErrorResponseBody = (error: AdapterError) => ({
+  error: error.message,
+  code: error.errorCode,
+  timestamp: new Date().toISOString(),
+});
+
+/**
+ * Creates a standardized error response body from UploadistaError.
+ * Formats core library errors for HTTP responses with optional details.
+ *
+ * @param error - The UploadistaError to format
+ * @returns Standardized error response body with error, code, timestamp, and optional details
+ *
+ * @example
+ * ```typescript
+ * import { createUploadistaErrorResponseBody } from "@uploadista/server";
+ *
+ * try {
+ *   const result = yield* uploadServer.handleUpload(input);
+ * } catch (err) {
+ *   if (err instanceof UploadistaError) {
+ *     const errorResponse = createUploadistaErrorResponseBody(err);
+ *     res.status(400).json(errorResponse);
+ *   }
+ * }
+ * ```
+ */
+export const createUploadistaErrorResponseBody = (error: UploadistaError) => {
+  const response: {
+    error: string;
+    code: string;
+    timestamp: string;
+    details?: unknown;
+  } = {
+    error: error.body,
+    code: error.code,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (error.details !== undefined) {
+    response.details = error.details;
+  }
+
+  return response;
+};
+
+/**
+ * Creates a generic error response body for unknown/unexpected errors.
+ * Used as a fallback when error type cannot be determined.
+ *
+ * @param message - Error message to include in response (defaults to "Internal server error")
+ * @returns Standardized error response body with generic INTERNAL_ERROR code
+ *
+ * @example
+ * ```typescript
+ * import { createGenericErrorResponseBody } from "@uploadista/server";
+ *
+ * try {
+ *   // ... operation
+ * } catch (err) {
+ *   const errorResponse = createGenericErrorResponseBody(
+ *     err instanceof Error ? err.message : "Unknown error"
+ *   );
+ *   res.status(500).json(errorResponse);
+ * }
+ * ```
+ */
+export const createGenericErrorResponseBody = (
+  message = "Internal server error",
+) => ({
+  error: message,
+  code: "INTERNAL_ERROR",
+  timestamp: new Date().toISOString(),
+});