@uploadista/server 0.0.17 → 0.0.18-beta.10

package/src/core/http-handlers/dlq-http-handlers.ts

@@ -0,0 +1,219 @@
+import { DeadLetterQueueService } from "@uploadista/core/flow";
+import { Effect } from "effect";
+import { PERMISSIONS } from "../../permissions/types";
+import { AuthContextService } from "../../service";
+import type {
+  DlqCleanupRequest,
+  DlqCleanupResponse,
+  DlqDeleteRequest,
+  DlqDeleteResponse,
+  DlqGetRequest,
+  DlqGetResponse,
+  DlqListRequest,
+  DlqListResponse,
+  DlqResolveRequest,
+  DlqResolveResponse,
+  DlqRetryAllRequest,
+  DlqRetryAllResponse,
+  DlqRetryRequest,
+  DlqRetryResponse,
+  DlqStatsRequest,
+  DlqStatsResponse,
+} from "../routes";
+
+/**
+ * Handle GET /api/dlq - List DLQ items
+ */
+export const handleDlqList = (req: DlqListRequest) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for reading DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_READ);
+
+    const dlq = yield* DeadLetterQueueService;
+    const result = yield* dlq.list(req.options);
+
+    return {
+      type: "dlq-list",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: result,
+    } satisfies DlqListResponse;
+  });
+
+/**
+ * Handle GET /api/dlq/:itemId - Get a specific DLQ item
+ */
+export const handleDlqGet = (req: DlqGetRequest) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for reading DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_READ);
+
+    const dlq = yield* DeadLetterQueueService;
+    const item = yield* dlq.get(req.itemId);
+
+    return {
+      type: "dlq-get",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: item,
+    } satisfies DlqGetResponse;
+  });
+
+/**
+ * Handle POST /api/dlq/:itemId/retry - Retry a specific DLQ item
+ */
+export const handleDlqRetry = (req: DlqRetryRequest) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
+    const dlq = yield* DeadLetterQueueService;
+
+    // Mark item as retrying
+    yield* dlq.markRetrying(req.itemId);
+
+    // TODO: Implement actual retry logic by re-executing the flow
+    // This would require access to FlowServer and the original job context
+    // For now, we just mark it as retrying and return success
+    // The actual retry would be handled by a background scheduler
+
+    return {
+      type: "dlq-retry",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: { success: true },
+    } satisfies DlqRetryResponse;
+  });
+
+/**
+ * Handle POST /api/dlq/retry-all - Retry all matching DLQ items
+ */
+export const handleDlqRetryAll = (req: DlqRetryAllRequest) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
+    const dlq = yield* DeadLetterQueueService;
+
+    // List items matching the filter
+    const { items } = yield* dlq.list({
+      status: req.options?.status,
+      flowId: req.options?.flowId,
+    });
+
+    let succeeded = 0;
+    let failed = 0;
+
+    // Mark each item for retry
+    for (const item of items) {
+      const result = yield* Effect.either(dlq.markRetrying(item.id));
+      if (result._tag === "Right") {
+        succeeded++;
+      } else {
+        failed++;
+      }
+    }
+
+    return {
+      type: "dlq-retry-all",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: {
+        retried: items.length,
+        succeeded,
+        failed,
+      },
+    } satisfies DlqRetryAllResponse;
+  });
+
+/**
+ * Handle DELETE /api/dlq/:itemId - Delete a DLQ item
+ */
+export const handleDlqDelete = (req: DlqDeleteRequest) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
+    const dlq = yield* DeadLetterQueueService;
+    yield* dlq.delete(req.itemId);
+
+    return {
+      type: "dlq-delete",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: { success: true },
+    } satisfies DlqDeleteResponse;
+  });
+
+/**
+ * Handle POST /api/dlq/:itemId/resolve - Manually resolve a DLQ item
+ */
+export const handleDlqResolve = (req: DlqResolveRequest) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
+    const dlq = yield* DeadLetterQueueService;
+    const item = yield* dlq.markResolved(req.itemId);
+
+    return {
+      type: "dlq-resolve",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: item,
+    } satisfies DlqResolveResponse;
+  });
+
+/**
+ * Handle POST /api/dlq/cleanup - Cleanup old DLQ items
+ */
+export const handleDlqCleanup = (req: DlqCleanupRequest) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for writing to DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_WRITE);
+
+    const dlq = yield* DeadLetterQueueService;
+    const result = yield* dlq.cleanup(req.options);
+
+    return {
+      type: "dlq-cleanup",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: result,
+    } satisfies DlqCleanupResponse;
+  });
+
+/**
+ * Handle GET /api/dlq/stats - Get DLQ statistics
+ */
+export const handleDlqStats = (_req: DlqStatsRequest) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for reading DLQ
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.DLQ_READ);
+
+    const dlq = yield* DeadLetterQueueService;
+    const stats = yield* dlq.getStats();
+
+    return {
+      type: "dlq-stats",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: stats,
+    } satisfies DlqStatsResponse;
+  });

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

@@ -1,7 +1,10 @@
 import { FlowServer } from "@uploadista/core/flow";
 import { Effect } from "effect";
 import { AuthCacheService } from "../../cache";
+import { PERMISSIONS } from "../../permissions/types";
+import { QuotaExceededError } from "../../permissions/errors";
 import { AuthContextService } from "../../service";
+import { UsageHookService } from "../../usage-hooks/service";
 import type {
   CancelFlowRequest,
   CancelFlowResponse,
@@ -20,10 +23,12 @@ import type {
 export const handleGetFlow = ({ flowId }: GetFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Access auth context if available
     const authService = yield* AuthContextService;
     const clientId = yield* authService.getClientId();
 
+    // Check permission for reading flow status
+    yield* authService.requirePermission(PERMISSIONS.FLOW.STATUS);
+
     if (clientId) {
       yield* Effect.logInfo(
         `[Flow] Getting flow data: ${flowId}, client: ${clientId}`,
@@ -46,11 +51,14 @@ export const handleRunFlow = <TRequirements>({
 }: RunFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Access auth context if available
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
+    const usageHookService = yield* UsageHookService;
     const clientId = yield* authService.getClientId();
 
+    // Check permission for executing flows
+    yield* authService.requirePermission(PERMISSIONS.FLOW.EXECUTE);
+
     if (clientId) {
       yield* Effect.logInfo(
         `[Flow] Executing flow: ${flowId}, storage: ${storageId}, client: ${clientId}`,
@@ -65,7 +73,28 @@ export const handleRunFlow = <TRequirements>({
       );
     }
 
+    // Execute onFlowStart hook for quota checking
+    if (clientId) {
+      const hookResult = yield* usageHookService.onFlowStart({
+        clientId,
+        operation: "flow",
+        metadata: {
+          flowId,
+        },
+      });
+
+      if (hookResult.action === "abort") {
+        return yield* Effect.fail(
+          new QuotaExceededError(
+            hookResult.reason,
+            hookResult.code ?? "SUBSCRIPTION_REQUIRED",
+          ),
+        );
+      }
+    }
+
     // Run flow returns immediately with jobId
+    const startTime = Date.now();
     yield* Effect.logInfo(`[Flow] Calling flowServer.runFlow...`);
     const result = yield* flowServer
       .runFlow<TRequirements>({
@@ -91,6 +120,10 @@ export const handleRunFlow = <TRequirements>({
 
     yield* Effect.logInfo(`[Flow] Flow started with jobId: ${result.id}`);
 
+    // Note: onFlowComplete hook is called when the flow actually completes,
+    // which happens asynchronously. The hook should be invoked from the
+    // flow execution pipeline, not here where we just start the flow.
+
     return {
       status: 200,
       body: result,
@@ -101,11 +134,13 @@ export const handleRunFlow = <TRequirements>({
 export const handleJobStatus = ({ jobId }: GetJobStatusRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Access auth context if available
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
     const clientId = yield* authService.getClientId();
 
+    // Check permission for checking flow status
+    yield* authService.requirePermission(PERMISSIONS.FLOW.STATUS);
+
     if (!jobId) {
       throw new Error("No job id");
     }
@@ -142,10 +177,12 @@ export const handleResumeFlow = <TRequirements>({
 }: ResumeFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Try to get auth from current request or cached auth
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
 
+    // Check permission for executing flows (resume is part of execution)
+    yield* authService.requirePermission(PERMISSIONS.FLOW.EXECUTE);
+
     // Try current auth first, fallback to cached auth
     let clientId = yield* authService.getClientId();
     if (!clientId) {
@@ -186,13 +223,16 @@ export const handleResumeFlow = <TRequirements>({
     } as ResumeFlowResponse;
   });
 };
+
 export const handlePauseFlow = ({ jobId }: PauseFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Try to get auth from current request or cached auth
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
 
+    // Check permission for cancelling flows (pause is related to cancel)
+    yield* authService.requirePermission(PERMISSIONS.FLOW.CANCEL);
+
     // Try current auth first, fallback to cached auth
     let clientId = yield* authService.getClientId();
     if (!clientId) {
@@ -224,9 +264,12 @@ export const handlePauseFlow = ({ jobId }: PauseFlowRequest) => {
 export const handleCancelFlow = ({ jobId }: CancelFlowRequest) => {
   return Effect.gen(function* () {
     const flowServer = yield* FlowServer;
-    // Try to get auth from current request or cached auth
     const authService = yield* AuthContextService;
     const authCache = yield* AuthCacheService;
+    const usageHookService = yield* UsageHookService;
+
+    // Check permission for cancelling flows
+    yield* authService.requirePermission(PERMISSIONS.FLOW.CANCEL);
 
     if (!jobId) {
       throw new Error("No job id");
@@ -253,6 +296,18 @@ export const handleCancelFlow = ({ jobId }: CancelFlowRequest) => {
       yield* Effect.logInfo(
         `[Flow] Flow cancelled, cleared auth cache: ${jobId}`,
       );
+
+      // Execute onFlowComplete hook for cancelled flow
+      yield* Effect.forkDaemon(
+        usageHookService.onFlowComplete({
+          clientId,
+          operation: "flow",
+          metadata: {
+            jobId,
+            status: "cancelled",
+          },
+        }),
+      );
     }
 
     return {

package/src/core/http-handlers/health-http-handlers.ts

@@ -0,0 +1,150 @@
+/**
+ * Health Check HTTP Handlers for Uploadista SDK.
+ *
+ * This module provides HTTP handlers for health check endpoints:
+ * - `/health` (liveness) - Simple alive check, no dependencies
+ * - `/ready` (readiness) - Full dependency check for accepting traffic
+ * - `/health/components` - Detailed component status for debugging
+ *
+ * @module core/http-handlers/health-http-handlers
+ */
+
+import {
+  formatHealthAsText,
+  getHealthResponseFormat,
+  type HealthCheckConfig,
+} from "@uploadista/core/types";
+import { Effect } from "effect";
+import { PERMISSIONS } from "../../permissions/types";
+import { AuthContextService } from "../../service";
+import {
+  createLivenessResponse,
+  performComponentsCheck,
+  performReadinessCheck,
+} from "../health-check-service";
+import type {
+  HealthComponentsRequest,
+  HealthComponentsResponse,
+  HealthReadyRequest,
+  HealthReadyResponse,
+  HealthRequest,
+  HealthResponse,
+} from "../routes";
+
+/**
+ * Handle GET /health - Liveness probe
+ *
+ * Returns immediately with 200 OK if the server is alive.
+ * Does not check any dependencies.
+ */
+export const handleHealthLiveness = (
+  req: HealthRequest,
+  config?: HealthCheckConfig,
+) =>
+  Effect.sync(() => {
+    const response = createLivenessResponse(config);
+    const format = getHealthResponseFormat(req.acceptHeader);
+
+    if (format === "text") {
+      return {
+        type: "health",
+        status: 200,
+        headers: { "Content-Type": "text/plain" },
+        body: formatHealthAsText(response.status),
+      } as HealthResponse;
+    }
+
+    return {
+      type: "health",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: response,
+    } satisfies HealthResponse;
+  });
+
+/**
+ * Handle GET /ready - Readiness probe
+ *
+ * Checks all critical dependencies (storage, KV store) and returns:
+ * - 200 OK if all dependencies are healthy
+ * - 503 Service Unavailable if any critical dependency is unavailable
+ *
+ * Requires `engine:readiness` permission.
+ */
+export const handleHealthReadiness = (
+  req: HealthReadyRequest,
+  config?: HealthCheckConfig,
+) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for readiness endpoint
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.READINESS);
+
+    const response = yield* performReadinessCheck(config);
+    const format = getHealthResponseFormat(req.acceptHeader);
+
+    // Determine HTTP status based on health status
+    const httpStatus = response.status === "unhealthy" ? 503 : 200;
+
+    if (format === "text") {
+      return {
+        type: "health-ready",
+        status: httpStatus,
+        headers: { "Content-Type": "text/plain" },
+        body: formatHealthAsText(response.status),
+      } as HealthReadyResponse;
+    }
+
+    return {
+      type: "health-ready",
+      status: httpStatus,
+      headers: { "Content-Type": "application/json" },
+      body: response,
+    } satisfies HealthReadyResponse;
+  });
+
+/**
+ * Handle GET /health/components - Detailed component status
+ *
+ * Returns detailed health information for each component including:
+ * - Storage backend
+ * - KV store
+ * - Event broadcaster
+ * - Circuit breaker (if enabled)
+ * - Dead letter queue (if enabled)
+ *
+ * Always returns 200 OK for debugging purposes (even if components are degraded).
+ *
+ * Requires `engine:readiness` permission.
+ */
+export const handleHealthComponents = (
+  req: HealthComponentsRequest,
+  config?: HealthCheckConfig,
+) =>
+  Effect.gen(function* () {
+    const authService = yield* AuthContextService;
+
+    // Check permission for components endpoint
+    yield* authService.requirePermission(PERMISSIONS.ENGINE.READINESS);
+
+    const response = yield* performComponentsCheck(config);
+    const format = getHealthResponseFormat(req.acceptHeader);
+
+    if (format === "text") {
+      // For text format, just return the overall status
+      return {
+        type: "health-components",
+        status: 200,
+        headers: { "Content-Type": "text/plain" },
+        body: formatHealthAsText(response.status),
+      } as HealthComponentsResponse;
+    }
+
+    return {
+      type: "health-components",
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      body: response,
+    } satisfies HealthComponentsResponse;
+  });

package/src/core/http-handlers/http-handlers.ts

@@ -1,5 +1,16 @@
+import type { HealthCheckConfig } from "@uploadista/core/types";
 import { Effect } from "effect";
 import type { UploadistaRequest, UploadistaResponse } from "../routes";
+import {
+  handleDlqCleanup,
+  handleDlqDelete,
+  handleDlqGet,
+  handleDlqList,
+  handleDlqResolve,
+  handleDlqRetry,
+  handleDlqRetryAll,
+  handleDlqStats,
+} from "./dlq-http-handlers";
 import {
   handleCancelFlow,
   handleGetFlow,
@@ -8,6 +19,11 @@ import {
   handleResumeFlow,
   handleRunFlow,
 } from "./flow-http-handlers";
+import {
+  handleHealthComponents,
+  handleHealthLiveness,
+  handleHealthReadiness,
+} from "./health-http-handlers";
 import {
   handleCreateUpload,
   handleGetCapabilities,
@@ -19,6 +35,7 @@ export type { UploadistaRequest, UploadistaResponse } from "../routes";
 
 export const handleUploadistaRequest = <TRequirements>(
   req: UploadistaRequest,
+  options?: { healthCheckConfig?: HealthCheckConfig },
 ) => {
   return Effect.gen(function* () {
     switch (req.type) {
@@ -44,6 +61,39 @@ export const handleUploadistaRequest = <TRequirements>(
         return (yield* handlePauseFlow(req)) as UploadistaResponse;
       case "cancel-flow":
         return (yield* handleCancelFlow(req)) as UploadistaResponse;
+      // DLQ Admin routes
+      case "dlq-list":
+        return (yield* handleDlqList(req)) as UploadistaResponse;
+      case "dlq-get":
+        return (yield* handleDlqGet(req)) as UploadistaResponse;
+      case "dlq-retry":
+        return (yield* handleDlqRetry(req)) as UploadistaResponse;
+      case "dlq-retry-all":
+        return (yield* handleDlqRetryAll(req)) as UploadistaResponse;
+      case "dlq-delete":
+        return (yield* handleDlqDelete(req)) as UploadistaResponse;
+      case "dlq-resolve":
+        return (yield* handleDlqResolve(req)) as UploadistaResponse;
+      case "dlq-cleanup":
+        return (yield* handleDlqCleanup(req)) as UploadistaResponse;
+      case "dlq-stats":
+        return (yield* handleDlqStats(req)) as UploadistaResponse;
+      // Health check routes
+      case "health":
+        return (yield* handleHealthLiveness(
+          req,
+          options?.healthCheckConfig,
+        )) as UploadistaResponse;
+      case "health-ready":
+        return (yield* handleHealthReadiness(
+          req,
+          options?.healthCheckConfig,
+        )) as UploadistaResponse;
+      case "health-components":
+        return (yield* handleHealthComponents(
+          req,
+          options?.healthCheckConfig,
+        )) as UploadistaResponse;
       case "not-found":
         return {
           status: 404,