@uploadista/adapters-express 0.0.3

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@uploadista/adapters-express",
+  "type": "module",
+  "version": "0.0.3",
+  "description": "Express adapter for Uploadista",
+  "license": "MIT",
+  "author": "Uploadista",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "effect": "3.18.4",
+    "zod": "4.1.12",
+    "@uploadista/core": "0.0.3",
+    "@uploadista/observability": "0.0.3",
+    "@uploadista/server": "0.0.3",
+    "@uploadista/event-broadcaster-memory": "0.0.3",
+    "@uploadista/event-emitter-websocket": "0.0.3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "24.8.1",
+    "typescript": "5.9.3",
+    "@uploadista/typescript-config": "0.0.3"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "format": "biome format --write ./src",
+    "lint": "biome lint --write ./src",
+    "check": "biome check --write ./src",
+    "clean": "rimraf -rf dist && rimraf -rf .turbo && rimraf tsconfig.tsbuildinfo"
+  }
+}

package/src/error-types.ts

@@ -0,0 +1,103 @@
+import type { UploadistaError } from "@uploadista/core/errors";
+import {
+  AdapterError,
+  BadRequestError as BaseBadRequestError,
+  NotFoundError as BaseNotFoundError,
+  ValidationError as BaseValidationError,
+  createErrorResponseBody,
+  createGenericErrorResponseBody,
+  createUploadistaErrorResponseBody,
+} from "@uploadista/server";
+import { Effect } from "effect";
+import type { Response } from "express";
+
+// Re-export shared error types for backward compatibility
+export {
+  AdapterError as ExpressAdapterError,
+  BaseValidationError as ValidationError,
+  BaseNotFoundError as NotFoundError,
+  BaseBadRequestError as BadRequestError,
+};
+
+/**
+ * Sends error response using Express Response object
+ */
+export const sendErrorResponse = (res: Response, error: AdapterError): void => {
+  res.status(error.statusCode).json(createErrorResponseBody(error));
+};
+
+/**
+ * Sends UploadistaError response using Express Response object
+ */
+export const sendUploadistaErrorResponse = (
+  res: Response,
+  error: UploadistaError,
+): void => {
+  res.status(error.status).json(createUploadistaErrorResponseBody(error));
+};
+
+/**
+ * Sends generic error response using Express Response object
+ */
+export const sendGenericErrorResponse = (
+  res: Response,
+  message = "Internal server error",
+): void => {
+  res.status(500).json(createGenericErrorResponseBody(message));
+};
+
+/**
+ * Universal error handler that sends error response via Express Response.
+ * Handles AdapterError, UploadistaError, and unknown errors.
+ * This is the recommended way to handle errors in HTTP handlers.
+ */
+export const handleErrorResponse = (res: Response) => (error: unknown) => {
+  console.error(error);
+
+  // Handle known adapter errors
+  if (error instanceof AdapterError) {
+    return Effect.sync(() => sendErrorResponse(res, error));
+  }
+
+  // Handle UploadistaError
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    "status" in error &&
+    "body" in error
+  ) {
+    return Effect.sync(() =>
+      sendUploadistaErrorResponse(res, error as UploadistaError),
+    );
+  }
+
+  // Handle unknown errors - try to extract what we can
+  let message = "Internal server error";
+  let code = "UNKNOWN_ERROR";
+  let status = 500;
+
+  if (typeof error === "object" && error !== null) {
+    const errorObj = error as Record<string, unknown>;
+
+    if ("message" in errorObj && typeof errorObj.message === "string") {
+      message = errorObj.message;
+    }
+
+    if ("code" in errorObj && typeof errorObj.code === "string") {
+      code = errorObj.code;
+    }
+
+    if ("status" in errorObj && typeof errorObj.status === "number") {
+      status = errorObj.status;
+    }
+  }
+
+  return Effect.sync(() => {
+    res.status(status).json({
+      error: message,
+      code,
+      timestamp: new Date().toISOString(),
+    });
+  });
+};

package/src/flow-http-handlers.ts

@@ -0,0 +1,184 @@
+import type { FlowServerShape } from "@uploadista/core/flow";
+import {
+  AuthCacheService,
+  AuthContextService,
+  getLastSegment,
+} from "@uploadista/server";
+import { Effect } from "effect";
+import type { Request, Response } from "express";
+import { handleErrorResponse } from "./error-types";
+
+export const handleFlowGet = (
+  req: Request,
+  res: Response,
+  flowServer: FlowServerShape,
+) => {
+  return Effect.gen(function* () {
+    // Access auth context if available
+    const authService = yield* AuthContextService;
+    const clientId = yield* authService.getClientId();
+
+    const url = new URL(req.url, `http://${req.get("host")}`);
+    const id = getLastSegment(url.pathname);
+    if (!id) {
+      res.status(400).json({ error: "No id" });
+      return;
+    }
+
+    const flowData = yield* flowServer.getFlowData(id, clientId);
+
+    res.status(200).json(flowData);
+  }).pipe(Effect.catchAll(handleErrorResponse(res)));
+};
+
+export const handleFlowPost = <TRequirements = never>(
+  req: Request,
+  res: Response,
+  flowServer: FlowServerShape,
+) => {
+  return Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+    const authCache = yield* AuthCacheService;
+    const clientId = yield* authService.getClientId();
+
+    const urlSegments = req.url.split("/");
+    const storageId = urlSegments.pop();
+    const flowId = urlSegments.pop();
+
+    if (!flowId) {
+      res.status(400).json({ error: "No id" });
+      return;
+    }
+    if (!storageId) {
+      res.status(400).json({ error: "No storage id" });
+      return;
+    }
+
+    const params = req.body;
+
+    if (clientId) {
+      console.log(
+        `[Flow] Executing flow: ${flowId}, storage: ${storageId}, client: ${clientId}`,
+      );
+      console.log(JSON.stringify(params, null, 2));
+    } else {
+      console.log(`Flow execution params: ${flowId} ${storageId}`);
+      console.log(JSON.stringify(params, null, 2));
+    }
+
+    // Run flow returns immediately with jobId
+    const result = yield* flowServer.runFlow<TRequirements>({
+      flowId,
+      storageId,
+      clientId,
+      inputs: params.inputs,
+    });
+
+    // Cache auth context for subsequent flow operations (continue, status)
+    const authContext = yield* authService.getAuthContext();
+    if (authContext) {
+      yield* authCache.set(result.id, authContext);
+    }
+
+    if (clientId) {
+      console.log(
+        `[Flow] Flow started with jobId: ${result.id}, client: ${clientId}`,
+      );
+    }
+
+    res.status(200).json(result);
+  }).pipe(Effect.catchAll(handleErrorResponse(res)));
+};
+
+export const handleJobStatus = (
+  req: Request,
+  res: Response,
+  flowServer: FlowServerShape,
+): Effect.Effect<void> => {
+  return Effect.gen(function* () {
+    const urlSegments = req.url.split("/");
+    const jobId = urlSegments[urlSegments.length - 2]; // .../jobs/:jobId/status
+
+    if (!jobId) {
+      res.status(400).json({ error: "No job id" });
+      return;
+    }
+
+    const result = yield* flowServer.getJobStatus(jobId);
+
+    res.status(200).json(result);
+  }).pipe(Effect.catchAll(handleErrorResponse(res)));
+};
+
+export const handleContinueFlow = <TRequirements = never>(
+  req: Request,
+  res: Response,
+  flowServer: FlowServerShape,
+) => {
+  return Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+    const clientId = yield* authService.getClientId();
+
+    const url = new URL(req.url, `http://${req.get("host")}`);
+    const urlSegments = url.pathname.split("/");
+    const jobId = urlSegments[urlSegments.length - 3]; // .../jobs/:jobId/continue/:nodeId
+    const nodeId = urlSegments[urlSegments.length - 1]; // .../jobs/:jobId/continue/:nodeId
+
+    if (!jobId) {
+      console.error("No job id");
+      res.status(400).json({ error: "No job id" });
+      return;
+    }
+
+    if (!nodeId) {
+      console.error("No node id");
+      res.status(400).json({ error: "No node id" });
+      return;
+    }
+
+    const contentType = req.get("Content-Type");
+
+    let newData: unknown;
+
+    // Handle different content types
+    if (contentType?.includes("application/octet-stream")) {
+      // For streaming data, convert Node.js Readable to web ReadableStream
+      newData = new ReadableStream({
+        start(controller) {
+          req.on("data", (chunk) => {
+            controller.enqueue(chunk);
+          });
+          req.on("end", () => {
+            controller.close();
+          });
+          req.on("error", (error) => {
+            controller.error(error);
+          });
+        },
+      });
+    } else if (contentType?.includes("application/json")) {
+      // For JSON data, use the parsed body
+      const body = req.body;
+
+      if (body.newData === undefined) {
+        console.error("Missing newData");
+        res.status(400).json({ error: "Missing newData" });
+        return;
+      }
+
+      newData = body.newData;
+    } else {
+      res.status(415).json({ error: "Unsupported Content-Type" });
+      return;
+    }
+
+    const result = yield* flowServer.continueFlow<TRequirements>({
+      jobId,
+      nodeId,
+      newData,
+      clientId,
+    });
+
+    res.status(200).json(result);
+  }).pipe(Effect.catchAll(handleErrorResponse(res)));
+};

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from "./uploadista-adapter";
+
+// Export types and utilities for WebSocket integration
+export type {
+  ExpressWebSocketHandler,
+  WebSocketConnection,
+  WebSocketHandlers,
+} from "./uploadista-adapter-layer";
+export {
+  createUploadistaWebSocketHandler,
+  createWebSocketCloseHandler,
+  createWebSocketErrorHandler,
+  createWebSocketMessageHandler,
+} from "./uploadista-websocket-handler";

package/src/upload-http-handlers.ts

@@ -0,0 +1,186 @@
+import { inputFileSchema } from "@uploadista/core/types";
+import type { UploadServerShape } from "@uploadista/core/upload";
+import { MetricsService } from "@uploadista/observability";
+import { AuthCacheService, AuthContextService } from "@uploadista/server";
+import { Effect } from "effect";
+import type { Request, Response } from "express";
+import {
+  BadRequestError,
+  handleErrorResponse,
+  ValidationError,
+} from "./error-types";
+
+export const handleUploadPost = (
+  req: Request,
+  res: Response,
+  server: UploadServerShape,
+) =>
+  Effect.gen(function* () {
+    // Access auth context if available
+    const authService = yield* AuthContextService;
+    const authCache = yield* AuthCacheService;
+    const clientId = yield* authService.getClientId();
+
+    if (clientId) {
+      console.log(`[Upload] Creating upload for client: ${clientId}`);
+    }
+
+    const json = req.body;
+
+    if (!json) {
+      return yield* Effect.fail(new BadRequestError("Invalid JSON payload"));
+    }
+
+    const parsedInputFile = yield* Effect.sync(() =>
+      inputFileSchema.safeParse(json),
+    );
+
+    if (!parsedInputFile.success) {
+      return yield* Effect.fail(
+        new ValidationError("Invalid input file schema"),
+      );
+    }
+
+    const fileCreated = yield* server.createUpload(
+      parsedInputFile.data,
+      clientId,
+    );
+
+    // Cache auth context for subsequent chunk uploads
+    const authContext = yield* authService.getAuthContext();
+    if (authContext) {
+      yield* authCache.set(fileCreated.id, authContext);
+    }
+
+    if (clientId) {
+      console.log(
+        `[Upload] Upload created: ${fileCreated.id} for client: ${clientId}`,
+      );
+    }
+
+    res.status(200).json(fileCreated);
+  }).pipe(Effect.catchAll(handleErrorResponse(res)));
+
+export const handleUploadGet = (
+  req: Request,
+  res: Response,
+  server: UploadServerShape,
+) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+    const clientId = yield* authService.getClientId();
+
+    const url = new URL(req.url, `http://${req.get("host")}`);
+    const pathSegments = url.pathname.split("/").filter(Boolean);
+    const lastSegment = pathSegments[pathSegments.length - 1];
+
+    if (lastSegment === "capabilities") {
+      const storageId =
+        url.searchParams.get("storageId") ||
+        pathSegments[pathSegments.length - 2];
+
+      if (!storageId) {
+        return yield* Effect.fail(
+          new BadRequestError("storageId is required for capabilities"),
+        );
+      }
+
+      const capabilities = yield* server.getCapabilities(storageId, clientId);
+
+      res.status(200).json({
+        storageId,
+        capabilities,
+        timestamp: new Date().toISOString(),
+      });
+      return;
+    }
+
+    if (!lastSegment) {
+      return yield* Effect.fail(new BadRequestError("Upload ID is required"));
+    }
+
+    const fileResult = yield* server.getUpload(lastSegment);
+
+    res.status(200).json(fileResult);
+  }).pipe(Effect.catchAll(handleErrorResponse(res)));
+
+export const handleUploadPatch = (
+  req: Request,
+  res: Response,
+  server: UploadServerShape,
+) =>
+  Effect.gen(function* () {
+    // Try to get auth from current request or cached auth
+    const authService = yield* AuthContextService;
+    const authCache = yield* AuthCacheService;
+    const metricsService = yield* MetricsService;
+
+    const uploadId = req.url.split("/").pop();
+    if (!uploadId) {
+      return yield* Effect.fail(new BadRequestError("Upload ID is required"));
+    }
+
+    // Try current auth first, fallback to cached auth
+    let clientId = yield* authService.getClientId();
+    let authMetadata = yield* authService.getMetadata();
+    if (!clientId) {
+      const cachedAuth = yield* authCache.get(uploadId);
+      clientId = cachedAuth?.clientId ?? null;
+      authMetadata = cachedAuth?.metadata ?? {};
+    }
+
+    if (clientId) {
+      console.log(
+        `[Upload] Uploading chunk for upload: ${uploadId}, client: ${clientId}`,
+      );
+    }
+
+    // Convert Node.js Readable stream to web ReadableStream
+    const body = new ReadableStream({
+      start(controller) {
+        req.on("data", (chunk) => {
+          controller.enqueue(chunk);
+        });
+        req.on("end", () => {
+          controller.close();
+        });
+        req.on("error", (error) => {
+          controller.error(error);
+        });
+      },
+    });
+
+    const fileResult = yield* server.uploadChunk(uploadId, clientId, body);
+
+    // Clear cache and record metrics if upload is complete
+    if (fileResult.size && fileResult.offset >= fileResult.size) {
+      yield* authCache.delete(uploadId);
+      if (clientId) {
+        console.log(
+          `[Upload] Upload completed, cleared auth cache: ${uploadId}`,
+        );
+      }
+
+      // Record upload metrics if we have organization ID
+      if (clientId && fileResult.size) {
+        console.log(
+          `[Upload] Recording metrics for org: ${clientId}, size: ${fileResult.size}`,
+        );
+        yield* Effect.forkDaemon(
+          metricsService.recordUpload(clientId, fileResult.size, authMetadata),
+        );
+      } else {
+        console.warn(
+          `[Upload] Cannot record metrics - missing organizationId or size`,
+        );
+      }
+    }
+
+    if (clientId) {
+      console.log(
+        `[Upload] Chunk uploaded for upload: ${uploadId}, client: ${clientId}`,
+      );
+    }
+
+    res.status(200).json(fileResult);
+  }).pipe(Effect.catchAll(handleErrorResponse(res)));

package/src/uploadista-adapter-layer.ts

@@ -0,0 +1,32 @@
+import type { IncomingMessage } from "node:http";
+import { type Effect, Context as EffectContext } from "effect";
+import type { Request, Response } from "express";
+
+export interface WebSocketConnection {
+  id: string;
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+  readyState: number;
+}
+
+export type WebSocketHandlers = {
+  onMessage: (message: string) => void;
+  onClose: () => void;
+  onError: (error: Error) => void;
+};
+
+export type ExpressWebSocketHandler = (
+  req: IncomingMessage,
+  connection: WebSocketConnection,
+) => WebSocketHandlers;
+
+// Define the Uploadista adapter service interface
+export type ExpressUploadistaAdapterServiceShape = {
+  handler: (req: Request, res: Response) => Effect.Effect<void, never, never>;
+  websocketHandler: ExpressWebSocketHandler;
+};
+
+// Context Tag for the Uploadista adapter service
+export class ExpressUploadistaAdapterService extends EffectContext.Tag(
+  "ExpressUploadistaAdapterService",
+)<ExpressUploadistaAdapterService, ExpressUploadistaAdapterServiceShape>() {}