@uploadista/server 0.0.7 → 0.0.9

package/src/core/server.ts

@@ -0,0 +1,327 @@
+import type { UploadistaError } from "@uploadista/core";
+import { type Flow, FlowProvider, FlowWaitUntil } from "@uploadista/core/flow";
+import {
+  createDataStoreLayer,
+  type UploadFileDataStores,
+  type UploadFileKVStore,
+} from "@uploadista/core/types";
+import { GenerateIdLive } from "@uploadista/core/utils";
+import { memoryEventBroadcaster } from "@uploadista/event-broadcaster-memory";
+import { webSocketEventEmitter } from "@uploadista/event-emitter-websocket";
+import { NodeSdkLive, NoOpMetricsServiceLive } from "@uploadista/observability";
+import { Effect, Layer, ManagedRuntime } from "effect";
+import type { z } from "zod";
+import type { StandardResponse } from "../adapter";
+import { AuthCacheServiceLive } from "../cache";
+import { handleFlowError } from "../http-utils";
+import { createFlowServerLayer, createUploadServerLayer } from "../layer-utils";
+import { AuthContextServiceLive } from "../service";
+import type { AuthContext } from "../types";
+import { handleUploadistaRequest } from "./http-handlers/http-handlers";
+import type { NotFoundResponse } from "./routes";
+import type { UploadistaServer, UploadistaServerConfig } from "./types";
+
+/**
+ * Creates the unified Uploadista server with framework-specific adapter.
+ *
+ * This function composes all layers (upload server, flow server, auth, metrics)
+ * and returns a handler that works with any framework via the provided adapter.
+ *
+ * The core server handles:
+ * - Route parsing and matching
+ * - Auth middleware execution with timeout protection
+ * - Layer composition (upload/flow servers, auth cache, metrics)
+ * - Error handling and response formatting
+ * - Effect program execution with optional tracing
+ *
+ * @param config - Server configuration including adapter and business logic
+ * @returns Object with handler function, optional WebSocket handler, and base URL
+ *
+ * @example
+ * ```typescript
+ * import { createUploadistaServer, honoAdapter } from "@uploadista/server";
+ *
+ * const server = await createUploadistaServer({
+ *   flows: getFlowById,
+ *   dataStore: { type: "s3", config: { bucket: "uploads" } },
+ *   kvStore: redisKvStore,
+ *   adapter: honoAdapter({
+ *     authMiddleware: async (c) => ({ clientId: "user-123" })
+ *   })
+ * });
+ *
+ * // Use with Hono
+ * app.all("/uploadista/*", server.handler);
+ * ```
+ */
+export const createUploadistaServer = async <
+  TContext,
+  TResponse,
+  TWebSocketHandler = unknown,
+>({
+  flows,
+  dataStore,
+  kvStore,
+  plugins = [],
+  eventEmitter,
+  eventBroadcaster = memoryEventBroadcaster,
+  withTracing = false,
+  baseUrl: configBaseUrl = "uploadista",
+  generateId = GenerateIdLive,
+  metricsLayer,
+  bufferedDataStore,
+  adapter,
+  authCacheConfig,
+}: UploadistaServerConfig<TContext, TResponse, TWebSocketHandler>): Promise<
+  UploadistaServer<TContext, TResponse, TWebSocketHandler>
+> => {
+  // Default eventEmitter to webSocketEventEmitter with the provided eventBroadcaster
+  const finalEventEmitter =
+    eventEmitter ?? webSocketEventEmitter(eventBroadcaster);
+
+  // Normalize baseUrl (remove trailing slash)
+  const baseUrl = configBaseUrl.endsWith("/")
+    ? configBaseUrl.slice(0, -1)
+    : configBaseUrl;
+
+  // Create flow provider layer from flows function
+  const flowProviderLayer = Layer.effect(
+    FlowProvider,
+    Effect.succeed({
+      getFlow: (flowId: string, clientId: string | null) => {
+        // Cast the flows function to match FlowProvider expectations
+        // The context requirements will be provided at the layer level
+        return flows(flowId, clientId) as Effect.Effect<
+          Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, unknown>,
+          UploadistaError,
+          never
+        >;
+      },
+    }),
+  );
+
+  // Validate that eventEmitter is provided (required for upload/flow servers)
+  if (!finalEventEmitter) {
+    throw new Error(
+      "eventEmitter is required. Provide an event emitter layer in the configuration.",
+    );
+  }
+
+  // Create data store layer
+  const dataStoreLayer: Layer.Layer<
+    UploadFileDataStores,
+    never,
+    UploadFileKVStore
+  > = await createDataStoreLayer(dataStore);
+
+  // Create upload server layer
+  const uploadServerLayer = createUploadServerLayer({
+    kvStore,
+    eventEmitter: finalEventEmitter,
+    dataStore: dataStoreLayer,
+    bufferedDataStore,
+    generateId,
+  });
+
+  // Create flow server layer
+  const flowServerLayer = createFlowServerLayer({
+    kvStore,
+    eventEmitter: finalEventEmitter,
+    flowProvider: flowProviderLayer,
+    uploadServer: uploadServerLayer,
+  });
+
+  // Create auth cache layer (always present, even if auth is not enabled)
+  const authCacheLayer = AuthCacheServiceLive(authCacheConfig);
+
+  // Metrics layer (defaults to NoOp if not provided)
+  const effectiveMetricsLayer = metricsLayer ?? NoOpMetricsServiceLive;
+
+  const serverLayer = Layer.mergeAll(
+    uploadServerLayer,
+    flowServerLayer,
+    effectiveMetricsLayer,
+    authCacheLayer,
+    ...plugins,
+  );
+
+  // Create a shared managed runtime from the server layer
+  // This ensures all requests use the same layer instances (including event broadcaster)
+  // ManagedRuntime properly handles scoped resources and provides convenient run methods
+  const managedRuntime = ManagedRuntime.make(serverLayer);
+
+  /**
+   * Main request handler that processes HTTP requests through the adapter.
+   * Delegates to adapter's httpHandler if provided, otherwise uses standard flow.
+   */
+  const handler = async <TRequirements>(ctx: TContext) => {
+    // Fallback: Standard routing logic (for adapters without httpHandler)
+    const program = Effect.gen(function* () {
+      // Extract standard request from framework-specific request
+      const uploadistaRequest = yield* adapter.extractRequest(ctx, { baseUrl });
+
+      // Run auth middleware if provided
+      let authContext: AuthContext | null = null;
+      if (adapter.runAuthMiddleware) {
+        const authMiddlewareWithTimeout = adapter.runAuthMiddleware(ctx).pipe(
+          Effect.timeout("5 seconds"),
+          Effect.catchAll(() => {
+            // Timeout error
+            console.error("Auth middleware timeout exceeded (5 seconds)");
+            return Effect.succeed({
+              _tag: "TimeoutError" as const,
+            } as const);
+          }),
+          Effect.catchAllCause((cause) => {
+            // Other errors
+            console.error("Auth middleware error:", cause);
+            return Effect.succeed({
+              _tag: "AuthError" as const,
+              error: cause,
+            } as const);
+          }),
+        );
+
+        const authResult:
+          | AuthContext
+          | null
+          | { _tag: "TimeoutError" }
+          | { _tag: "AuthError"; error: unknown } =
+          yield* authMiddlewareWithTimeout;
+
+        // Handle timeout
+        if (
+          authResult &&
+          typeof authResult === "object" &&
+          "_tag" in authResult &&
+          authResult._tag === "TimeoutError"
+        ) {
+          const errorResponse: StandardResponse = {
+            status: 503,
+            headers: { "Content-Type": "application/json" },
+            body: {
+              error: "Authentication service unavailable",
+              message:
+                "Authentication took too long to respond. Please try again.",
+            },
+          };
+          return yield* adapter.sendResponse(errorResponse, ctx);
+        }
+
+        // Handle auth error
+        if (
+          authResult &&
+          typeof authResult === "object" &&
+          "_tag" in authResult &&
+          authResult._tag === "AuthError"
+        ) {
+          const errorResponse: StandardResponse = {
+            status: 500,
+            headers: { "Content-Type": "application/json" },
+            body: {
+              error: "Internal Server Error",
+              message: "An error occurred during authentication",
+            },
+          };
+          return yield* adapter.sendResponse(errorResponse, ctx);
+        }
+
+        // Handle authentication failure (null result)
+        if (authResult === null) {
+          const errorResponse: StandardResponse = {
+            status: 401,
+            headers: { "Content-Type": "application/json" },
+            body: {
+              error: "Unauthorized",
+              message: "Invalid credentials",
+            },
+          };
+          return yield* adapter.sendResponse(errorResponse, ctx);
+        }
+
+        authContext = authResult;
+      }
+
+      // Create auth context layer for this request
+      const authContextLayer = AuthContextServiceLive(authContext);
+
+      // Extract waitUntil callback if available (for Cloudflare Workers)
+      // This must be extracted per-request since it comes from the framework context
+      const waitUntilLayers: Layer.Layer<any, never, never>[] = [];
+      if (adapter.extractWaitUntil) {
+        const waitUntilCallback = adapter.extractWaitUntil(ctx);
+        if (waitUntilCallback) {
+          waitUntilLayers.push(Layer.succeed(FlowWaitUntil, waitUntilCallback));
+        }
+      }
+
+      // Combine auth context, auth cache, metrics layers, plugins, and waitUntil
+      // This ensures that flow nodes have access to all required services
+      const requestContextLayer = Layer.mergeAll(
+        authContextLayer,
+        authCacheLayer,
+        effectiveMetricsLayer,
+        ...plugins,
+        ...waitUntilLayers,
+      );
+
+      // Check for baseUrl/api/ prefix
+      if (uploadistaRequest.type === "not-found") {
+        const notFoundResponse: NotFoundResponse = {
+          type: "not-found",
+          status: 404,
+          headers: { "Content-Type": "application/json" },
+          body: { error: "Not found" },
+        };
+        return yield* adapter.sendResponse(notFoundResponse, ctx);
+      }
+
+      // Handle the request
+      const response = yield* handleUploadistaRequest<TRequirements>(
+        uploadistaRequest,
+      ).pipe(Effect.provide(requestContextLayer));
+
+      return yield* adapter.sendResponse(response, ctx);
+    }).pipe(
+      // Catch all errors and format them appropriately
+      Effect.catchAll((error: unknown) => {
+        const errorInfo = handleFlowError(error);
+        const errorBody: Record<string, unknown> = {
+          code: errorInfo.code,
+          message: errorInfo.message,
+        };
+        if (errorInfo.details !== undefined) {
+          errorBody.details = errorInfo.details;
+        }
+        const errorResponse: StandardResponse = {
+          status: errorInfo.status,
+          headers: { "Content-Type": "application/json" },
+          body: errorBody,
+        };
+        return adapter.sendResponse(errorResponse, ctx);
+      }),
+    );
+
+    // Use the shared managed runtime instead of creating a new one per request
+    if (withTracing) {
+      return managedRuntime.runPromise(
+        program.pipe(Effect.provide(NodeSdkLive)),
+      );
+    }
+    return managedRuntime.runPromise(program);
+  };
+
+  // Create WebSocket handler using the shared managed runtime
+  const websocketHandler = await managedRuntime.runPromise(
+    adapter.webSocketHandler({
+      baseUrl,
+    }),
+  );
+
+  return {
+    handler,
+    websocketHandler,
+    baseUrl,
+    dispose: () => managedRuntime.dispose(),
+  };
+};

package/src/core/types.ts

@@ -0,0 +1,322 @@
+import type { UploadistaError } from "@uploadista/core";
+import type { Flow } from "@uploadista/core/flow";
+import type {
+  BaseEventEmitterService,
+  BaseKvStoreService,
+  DataStoreConfig,
+  EventBroadcasterService,
+  UploadFileDataStore,
+  UploadFileKVStore,
+} from "@uploadista/core/types";
+import type { GenerateId } from "@uploadista/core/utils";
+import type { Effect, Layer } from "effect";
+import type { z } from "zod";
+import type { ServerAdapter } from "../adapter";
+import type { AuthCacheConfig } from "../cache";
+
+/**
+ * Function type for retrieving flows based on flow ID and client ID.
+ *
+ * This function is called by the core server when a flow needs to be executed.
+ * It should return an Effect that resolves to the requested Flow or fails with
+ * an UploadistaError if the flow is not found or not authorized.
+ *
+ * @param flowId - The unique identifier of the flow to retrieve
+ * @param clientId - The authenticated client ID (null if not authenticated)
+ * @returns Effect that produces the Flow or fails with an error
+ *
+ * @example
+ * ```typescript
+ * const flows: FlowsFunction = (flowId, clientId) =>
+ *   Effect.gen(function* () {
+ *     if (flowId === "image-resize") {
+ *       return imageResizeFlow;
+ *     }
+ *     return yield* Effect.fail(
+ *       new UploadistaError({ code: "FLOW_NOT_FOUND", status: 404 })
+ *     );
+ *   });
+ * ```
+ */
+export type FlowsFunction = (
+  flowId: string,
+  clientId: string | null,
+) => Effect.Effect<
+  Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, unknown>,
+  UploadistaError,
+  unknown
+>;
+
+/**
+ * Configuration for creating the unified Uploadista server.
+ *
+ * This configuration is framework-agnostic and contains all the business logic
+ * configuration. Framework-specific details are provided via the `adapter` field.
+ *
+ * @template TRequest - Framework-specific request type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocket - Framework-specific WebSocket type (optional)
+ *
+ * @example
+ * ```typescript
+ * import { createUploadistaServer, honoAdapter } from "@uploadista/server";
+ *
+ * const config: UploadistaServerConfig<Context, Context, WSEvents> = {
+ *   // Core business logic configuration
+ *   flows: getFlowById,
+ *   dataStore: { type: "s3", config: { bucket: "my-bucket" } },
+ *   kvStore: redisKvStore,
+ *   baseUrl: "/uploadista",
+ *
+ *   // Framework-specific adapter
+ *   adapter: honoAdapter({
+ *     authMiddleware: async (c) => {
+ *       // Hono-specific auth logic
+ *       return { clientId: "user-123" };
+ *     },
+ *   }),
+ * };
+ *
+ * const server = await createUploadistaServer(config);
+ * ```
+ */
+export interface UploadistaServerConfig<
+  TRequest,
+  TResponse,
+  TWebSocket = unknown,
+> {
+  /**
+   * Function for retrieving flows by ID.
+   *
+   * This function is called when a flow execution is requested.
+   * It receives the flow ID and client ID (from auth context) and should
+   * return an Effect that resolves to the Flow definition.
+   *
+   * @example
+   * ```typescript
+   * flows: (flowId, clientId) => Effect.succeed(myFlows[flowId])
+   * ```
+   */
+  flows: FlowsFunction;
+
+  /**
+   * Data store configuration for file storage.
+   *
+   * Specifies where uploaded files should be stored (S3, Azure, GCS, filesystem).
+   * The core server creates the appropriate data store layer from this configuration.
+   *
+   * @example
+   * ```typescript
+   * dataStore: {
+   *   type: "s3",
+   *   config: {
+   *     bucket: "my-uploads",
+   *     region: "us-east-1"
+   *   }
+   * }
+   * ```
+   */
+  dataStore: DataStoreConfig;
+
+  /**
+   * Key-value store layer for metadata storage.
+   *
+   * Used for storing upload metadata, flow job state, and other persistent data.
+   * Can be Redis, Cloudflare KV, in-memory, or any implementation of BaseKvStoreService.
+   *
+   * @example
+   * ```typescript
+   * import { redisKvStore } from "@uploadista/kv-store-redis";
+   *
+   * kvStore: redisKvStore({ url: "redis://localhost:6379" })
+   * ```
+   */
+  kvStore: Layer.Layer<BaseKvStoreService>;
+
+  /**
+   * Optional: Plugins to extend functionality.
+   *
+   * Plugins are Effect layers that add additional capabilities to the upload
+   * and flow servers. They are merged into the server layer composition.
+   *
+   * @example
+   * ```typescript
+   * plugins: [imageProcessingPlugin, virusScanPlugin]
+   * ```
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: Permissive constraint allows plugin tuples
+  plugins?: readonly Layer.Layer<any, never, never>[];
+
+  /**
+   * Optional: Event emitter layer for progress notifications.
+   *
+   * Used to emit upload progress, flow status updates, and other events.
+   * Defaults to in-memory event emitter if not provided.
+   *
+   * @example
+   * ```typescript
+   * import { webSocketEventEmitter } from "@uploadista/event-emitter-websocket";
+   *
+   * eventEmitter: webSocketEventEmitter()
+   * ```
+   */
+  eventEmitter?: Layer.Layer<BaseEventEmitterService>;
+
+  /**
+   * Optional: Event broadcaster layer for real-time updates.
+   *
+   * Used to broadcast events to multiple subscribers (e.g., WebSocket connections).
+   * Defaults to in-memory broadcaster if not provided.
+   *
+   * @example
+   * ```typescript
+   * import { memoryEventBroadcaster } from "@uploadista/event-broadcaster-memory";
+   *
+   * eventBroadcaster: memoryEventBroadcaster()
+   * ```
+   */
+  eventBroadcaster?: Layer.Layer<EventBroadcasterService>;
+
+  /**
+   * Optional: Base URL path for Uploadista endpoints.
+   *
+   * All Uploadista routes will be prefixed with `{baseUrl}/api/`.
+   * For example, with baseUrl="/uploadista", routes become:
+   * - POST /uploadista/api/upload
+   * - POST /uploadista/api/flow/{flowId}/{storageId}
+   *
+   * @default "" (no prefix, routes start with /api/)
+   */
+  baseUrl?: string;
+
+  /**
+   * Optional: Custom ID generator layer.
+   *
+   * Used for generating upload IDs, job IDs, and other unique identifiers.
+   * Defaults to built-in ID generator if not provided.
+   *
+   * @example
+   * ```typescript
+   * import { nanoidGenerator } from "@uploadista/utils";
+   *
+   * generateId: nanoidGenerator()
+   * ```
+   */
+  generateId?: Layer.Layer<GenerateId>;
+
+  /**
+   * Optional: Enable distributed tracing with OpenTelemetry.
+   *
+   * When true, Effect programs run with OpenTelemetry tracing enabled,
+   * allowing observability into upload and flow execution.
+   *
+   * @default false
+   */
+  withTracing?: boolean;
+
+  /**
+   * Optional: Metrics layer for observability.
+   *
+   * Used to collect metrics about upload/flow performance, errors, and usage.
+   * Defaults to NoOp metrics if not provided.
+   *
+   * @example
+   * ```typescript
+   * import { prometheusMetrics } from "@uploadista/observability";
+   *
+   * metricsLayer: prometheusMetrics()
+   * ```
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: MetricsService is defined in @uploadista/observability
+  metricsLayer?: Layer.Layer<any, never, never>;
+
+  /**
+   * Optional: Buffered data store layer for performance optimization.
+   *
+   * Provides in-memory buffering for frequently accessed data,
+   * reducing latency for chunk uploads and reads.
+   *
+   * @example
+   * ```typescript
+   * import { bufferedDataStore } from "@uploadista/core/data-store";
+   *
+   * bufferedDataStore: bufferedDataStore({ maxSize: 1024 * 1024 * 10 })
+   * ```
+   */
+  bufferedDataStore?: Layer.Layer<
+    UploadFileDataStore,
+    never,
+    UploadFileKVStore
+  >;
+
+  /**
+   * Framework-specific adapter.
+   *
+   * The adapter provides the bridge between framework-specific request/response
+   * types and the standard types used by the core server. Each framework
+   * (Hono, Express, Fastify) has its own adapter implementation.
+   *
+   * @example
+   * ```typescript
+   * import { honoAdapter } from "@uploadista/adapters-hono";
+   *
+   * adapter: honoAdapter({
+   *   authMiddleware: async (c) => ({ clientId: "user-123" })
+   * })
+   * ```
+   */
+  adapter: ServerAdapter<TRequest, TResponse, TWebSocket>;
+
+  /**
+   * Optional: Configuration for auth context caching.
+   *
+   * Caching allows subsequent requests (chunk uploads, flow continuations) to
+   * reuse the auth context from the initial request without re-authenticating.
+   *
+   * @example
+   * ```typescript
+   * authCacheConfig: {
+   *   maxSize: 10000,
+   *   ttl: 3600000 // 1 hour
+   * }
+   * ```
+   */
+  authCacheConfig?: AuthCacheConfig;
+}
+
+/**
+ * Return type from createUploadistaServer.
+ *
+ * Contains the handler function and exposed server layers for framework-specific routing.
+ *
+ * @template TRequest - Framework-specific request type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocket - Framework-specific WebSocket type (optional)
+ */
+export interface UploadistaServer<
+  TRequest,
+  TResponse,
+  TWebSocketHandler = unknown,
+> {
+  /**
+   * Main request handler that processes HTTP requests through the adapter.
+   */
+  handler: (req: TRequest) => Promise<TResponse>;
+
+  /**
+   * Optional WebSocket handler if the adapter supports WebSocket connections.
+   */
+  websocketHandler: TWebSocketHandler;
+
+  /**
+   * Base URL path for Uploadista endpoints.
+   */
+  baseUrl: string;
+
+  /**
+   * Dispose function for graceful shutdown.
+   * Cleans up all resources associated with the managed runtime.
+   * Should be called when the server is shutting down.
+   */
+  dispose: () => Promise<void>;
+}

package/src/core/websocket-handlers/flow-websocket-handlers.ts

@@ -0,0 +1,47 @@
+import type { FlowServerShape } from "@uploadista/core/flow";
+import { Effect } from "effect";
+import type { WebSocketConnection } from "../websocket-routes";
+
+/**
+ * Handles subscription to flow events
+ * Subscribes the WebSocket connection to receive real-time flow execution events
+ */
+export const handleSubscribeToFlowEvents = (
+  flowServer: FlowServerShape,
+  jobId: string | undefined,
+  connection: WebSocketConnection,
+) => {
+  return Effect.gen(function* () {
+    if (!jobId) {
+      yield* Effect.sync(() => {
+        connection.send(
+          JSON.stringify({
+            type: "error",
+            message: "Job ID is required for flow event subscription",
+            code: "MISSING_JOB_ID",
+          }),
+        );
+      });
+      return;
+    }
+
+    yield* flowServer.subscribeToFlowEvents(jobId, connection);
+  });
+};
+
+/**
+ * Handles unsubscription from flow events
+ * Removes the WebSocket connection from receiving flow events
+ */
+export const handleUnsubscribeFromFlowEvents = (
+  flowServer: FlowServerShape,
+  jobId: string | undefined,
+) => {
+  return Effect.gen(function* () {
+    if (!jobId) {
+      return;
+    }
+
+    yield* flowServer.unsubscribeFromFlowEvents(jobId);
+  });
+};