@uploadista/server 0.0.18-beta.16 → 0.0.18-beta.2

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

@@ -1,219 +0,0 @@
-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/health-http-handlers.ts

@@ -1,150 +0,0 @@
-/**
- * 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/permissions/errors.ts

@@ -1,105 +0,0 @@
-/**
- * Authorization Error Types
- *
- * Error classes for permission and authorization failures.
- */
-
-import { AdapterError } from "../error-types";
-
-/**
- * Authorization error - indicates the user lacks required permissions.
- * Returns HTTP 403 Forbidden status.
- *
- * @example
- * ```typescript
- * if (!hasPermission(permissions, "engine:metrics")) {
- *   throw new AuthorizationError("engine:metrics");
- * }
- * ```
- */
-export class AuthorizationError extends AdapterError {
-  /**
-   * The permission that was required but not granted.
-   */
-  public readonly requiredPermission: string;
-
-  constructor(requiredPermission: string, message?: string) {
-    super(
-      message ?? `Permission denied: ${requiredPermission} required`,
-      403,
-      "PERMISSION_DENIED",
-    );
-    this.name = "AuthorizationError";
-    this.requiredPermission = requiredPermission;
-  }
-}
-
-/**
- * Authentication required error - indicates no authentication context.
- * Returns HTTP 401 Unauthorized status.
- *
- * @example
- * ```typescript
- * if (!authContext) {
- *   throw new AuthenticationRequiredError();
- * }
- * ```
- */
-export class AuthenticationRequiredError extends AdapterError {
-  constructor(message = "Authentication required") {
-    super(message, 401, "AUTHENTICATION_REQUIRED");
-    this.name = "AuthenticationRequiredError";
-  }
-}
-
-/**
- * Organization mismatch error - indicates accessing a resource from another organization.
- * Returns HTTP 403 Forbidden status.
- *
- * @example
- * ```typescript
- * if (resource.organizationId !== clientId) {
- *   throw new OrganizationMismatchError();
- * }
- * ```
- */
-export class OrganizationMismatchError extends AdapterError {
-  constructor(message = "Access denied: resource belongs to another organization") {
-    super(message, 403, "ORGANIZATION_MISMATCH");
-    this.name = "OrganizationMismatchError";
-  }
-}
-
-/**
- * Quota exceeded error - indicates usage quota has been exceeded.
- * Returns HTTP 402 Payment Required status.
- *
- * @example
- * ```typescript
- * if (usage > quota) {
- *   throw new QuotaExceededError("Storage quota exceeded");
- * }
- * ```
- */
-export class QuotaExceededError extends AdapterError {
-  constructor(message = "Quota exceeded", code = "QUOTA_EXCEEDED") {
-    super(message, 402, code);
-    this.name = "QuotaExceededError";
-  }
-}
-
-/**
- * Creates a standardized error response body for AuthorizationError.
- * Includes the required permission in the response.
- *
- * @param error - The AuthorizationError to format
- * @returns Standardized error response body
- */
-export const createAuthorizationErrorResponseBody = (
-  error: AuthorizationError,
-) => ({
-  error: error.message,
-  code: error.errorCode,
-  requiredPermission: error.requiredPermission,
-  timestamp: new Date().toISOString(),
-});

package/src/permissions/index.ts

@@ -1,9 +0,0 @@
-/**
- * Permissions Module
- *
- * Exports all permission-related types, constants, and utilities.
- */
-
-export * from "./types";
-export * from "./matcher";
-export * from "./errors";

package/src/permissions/matcher.ts

@@ -1,139 +0,0 @@
-/**
- * Permission Matching Logic
- *
- * Implements permission matching with support for:
- * - Exact match: `engine:health` matches `engine:health`
- * - Wildcard match: `engine:*` matches `engine:health`, `engine:metrics`, etc.
- * - Hierarchical match: `engine:dlq` implies `engine:dlq:read` and `engine:dlq:write`
- */
-
-import { PERMISSION_HIERARCHY } from "./types";
-
-/**
- * Checks if a granted permission matches a required permission.
- *
- * @param granted - The permission that has been granted to the user
- * @param required - The permission that is required for the operation
- * @returns true if the granted permission satisfies the required permission
- *
- * @example
- * ```typescript
- * matchesPermission("engine:*", "engine:health") // true (wildcard)
- * matchesPermission("engine:health", "engine:health") // true (exact)
- * matchesPermission("engine:dlq", "engine:dlq:read") // true (hierarchical)
- * matchesPermission("flow:execute", "engine:health") // false
- * ```
- */
-export const matchesPermission = (
-  granted: string,
-  required: string,
-): boolean => {
-  // Exact match
-  if (granted === required) {
-    return true;
-  }
-
-  // Wildcard match: `engine:*` matches `engine:health`
-  if (granted.endsWith(":*")) {
-    const prefix = granted.slice(0, -1); // Remove the `*`, keep the `:`
-    if (required.startsWith(prefix)) {
-      return true;
-    }
-  }
-
-  // Hierarchical match: `engine:dlq` implies `engine:dlq:read`
-  const impliedPermissions = PERMISSION_HIERARCHY[granted];
-  if (impliedPermissions?.includes(required)) {
-    return true;
-  }
-
-  return false;
-};
-
-/**
- * Checks if any of the granted permissions satisfy the required permission.
- *
- * @param grantedPermissions - Array of permissions granted to the user
- * @param required - The permission that is required for the operation
- * @returns true if any granted permission satisfies the required permission
- *
- * @example
- * ```typescript
- * hasPermission(["flow:*", "upload:create"], "flow:execute") // true
- * hasPermission(["upload:create"], "flow:execute") // false
- * ```
- */
-export const hasPermission = (
-  grantedPermissions: readonly string[],
-  required: string,
-): boolean => {
-  return grantedPermissions.some((granted) =>
-    matchesPermission(granted, required),
-  );
-};
-
-/**
- * Checks if any of the granted permissions satisfy any of the required permissions.
- *
- * @param grantedPermissions - Array of permissions granted to the user
- * @param requiredPermissions - Array of permissions, any of which would be sufficient
- * @returns true if any granted permission satisfies any required permission
- *
- * @example
- * ```typescript
- * hasAnyPermission(["upload:create"], ["flow:execute", "upload:create"]) // true
- * hasAnyPermission(["upload:read"], ["flow:execute", "upload:create"]) // false
- * ```
- */
-export const hasAnyPermission = (
-  grantedPermissions: readonly string[],
-  requiredPermissions: readonly string[],
-): boolean => {
-  return requiredPermissions.some((required) =>
-    hasPermission(grantedPermissions, required),
-  );
-};
-
-/**
- * Checks if all of the required permissions are satisfied.
- *
- * @param grantedPermissions - Array of permissions granted to the user
- * @param requiredPermissions - Array of permissions, all of which must be satisfied
- * @returns true if all required permissions are satisfied
- *
- * @example
- * ```typescript
- * hasAllPermissions(["flow:*", "upload:*"], ["flow:execute", "upload:create"]) // true
- * hasAllPermissions(["flow:execute"], ["flow:execute", "upload:create"]) // false
- * ```
- */
-export const hasAllPermissions = (
-  grantedPermissions: readonly string[],
-  requiredPermissions: readonly string[],
-): boolean => {
-  return requiredPermissions.every((required) =>
-    hasPermission(grantedPermissions, required),
-  );
-};
-
-/**
- * Expands a permission to include all implied permissions.
- * Useful for display or audit purposes.
- *
- * @param permission - The permission to expand
- * @returns Array of the permission and all implied permissions
- *
- * @example
- * ```typescript
- * expandPermission("engine:dlq") // ["engine:dlq", "engine:dlq:read", "engine:dlq:write"]
- * expandPermission("engine:health") // ["engine:health"]
- * ```
- */
-export const expandPermission = (permission: string): string[] => {
-  const result = [permission];
-  const implied = PERMISSION_HIERARCHY[permission];
-  if (implied) {
-    result.push(...implied);
-  }
-  return result;
-};