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

package/docs/HEALTH_CHECKS.md

@@ -1,256 +0,0 @@
-# Health Check Endpoints
-
-Uploadista SDK provides production-ready health check endpoints for Kubernetes deployments, load balancer health checks, and operational monitoring.
-
-## Endpoints
-
-All health endpoints are available at `/{baseUrl}/` (not under `/api/`):
-
-| Endpoint | Aliases | Purpose | HTTP Status |
-|----------|---------|---------|-------------|
-| `/health` | `/healthz` | Liveness probe - is the server alive? | Always 200 |
-| `/ready` | `/readyz` | Readiness probe - can the server accept traffic? | 200 or 503 |
-| `/health/components` | - | Detailed component status for debugging | Always 200 |
-
-## Liveness Probe (`/health`)
-
-The liveness endpoint returns immediately without checking dependencies. Use this for Kubernetes liveness probes to detect if the server process is stuck.
-
-**Request:**
-```http
-GET /uploadista/health
-Accept: application/json
-```
-
-**Response (JSON):**
-```json
-{
-  "status": "healthy",
-  "timestamp": "2024-01-15T10:30:00.000Z",
-  "uptime": 3600000,
-  "version": "1.2.3"
-}
-```
-
-**Response (Plain Text):**
-```http
-GET /uploadista/health
-Accept: text/plain
-
-OK
-```
-
-## Readiness Probe (`/ready`)
-
-The readiness endpoint checks all critical dependencies before accepting traffic. Use this for Kubernetes readiness probes to prevent traffic from being routed to unhealthy instances.
-
-**Request:**
-```http
-GET /uploadista/ready
-Accept: application/json
-```
-
-**Response (Healthy):**
-```json
-{
-  "status": "healthy",
-  "timestamp": "2024-01-15T10:30:00.000Z",
-  "uptime": 3600000,
-  "components": {
-    "storage": {
-      "status": "healthy",
-      "latency": 15,
-      "message": "Storage backend configured",
-      "lastCheck": "2024-01-15T10:30:00.000Z"
-    },
-    "kvStore": {
-      "status": "healthy",
-      "latency": 5,
-      "message": "KV store configured",
-      "lastCheck": "2024-01-15T10:30:00.000Z"
-    },
-    "eventBroadcaster": {
-      "status": "healthy",
-      "latency": 2,
-      "message": "Event broadcaster configured",
-      "lastCheck": "2024-01-15T10:30:00.000Z"
-    }
-  }
-}
-```
-
-**Response (Unhealthy - HTTP 503):**
-```json
-{
-  "status": "unhealthy",
-  "timestamp": "2024-01-15T10:30:00.000Z",
-  "components": {
-    "storage": {
-      "status": "unhealthy",
-      "latency": 5000,
-      "message": "Connection timeout",
-      "lastCheck": "2024-01-15T10:30:00.000Z"
-    },
-    "kvStore": {
-      "status": "healthy",
-      "latency": 5,
-      "message": "KV store configured",
-      "lastCheck": "2024-01-15T10:30:00.000Z"
-    }
-  }
-}
-```
-
-## Component Details (`/health/components`)
-
-The components endpoint returns detailed health information including circuit breaker and dead letter queue status. Always returns HTTP 200 for debugging purposes.
-
-**Request:**
-```http
-GET /uploadista/health/components
-Accept: application/json
-```
-
-**Response:**
-```json
-{
-  "status": "degraded",
-  "timestamp": "2024-01-15T10:30:00.000Z",
-  "uptime": 3600000,
-  "version": "1.2.3",
-  "components": {
-    "storage": {
-      "status": "healthy",
-      "latency": 15,
-      "message": "Storage backend configured",
-      "lastCheck": "2024-01-15T10:30:00.000Z"
-    },
-    "kvStore": {
-      "status": "healthy",
-      "latency": 5,
-      "message": "KV store configured",
-      "lastCheck": "2024-01-15T10:30:00.000Z"
-    },
-    "eventBroadcaster": {
-      "status": "healthy",
-      "latency": 2,
-      "message": "Event broadcaster configured",
-      "lastCheck": "2024-01-15T10:30:00.000Z"
-    },
-    "circuitBreaker": {
-      "status": "degraded",
-      "openCircuits": 1,
-      "totalCircuits": 5,
-      "circuits": [
-        {
-          "nodeType": "image-resize",
-          "state": "open",
-          "failureCount": 10,
-          "timeSinceLastStateChange": 30000
-        }
-      ]
-    },
-    "deadLetterQueue": {
-      "status": "healthy",
-      "pendingItems": 3,
-      "exhaustedItems": 0,
-      "oldestItem": "2024-01-15T10:25:00.000Z"
-    }
-  }
-}
-```
-
-## Configuration
-
-Configure health check behavior in your server configuration:
-
-```typescript
-import { createUploadistaServer } from "@uploadista/server";
-
-const server = await createUploadistaServer({
-  // ... other config ...
-
-  healthCheck: {
-    // Timeout for dependency checks (default: 5000ms)
-    timeout: 3000,
-
-    // Enable/disable specific checks
-    checkStorage: true,
-    checkKvStore: true,
-    checkEventBroadcaster: true,
-
-    // Optional version string for deployment identification
-    version: "1.2.3"
-  }
-});
-```
-
-## Kubernetes Deployment Example
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: uploadista-server
-spec:
-  template:
-    spec:
-      containers:
-        - name: uploadista
-          image: your-image:latest
-          ports:
-            - containerPort: 8080
-          livenessProbe:
-            httpGet:
-              path: /uploadista/health
-              port: 8080
-            initialDelaySeconds: 5
-            periodSeconds: 10
-            timeoutSeconds: 1
-            failureThreshold: 3
-          readinessProbe:
-            httpGet:
-              path: /uploadista/ready
-              port: 8080
-            initialDelaySeconds: 10
-            periodSeconds: 5
-            timeoutSeconds: 5
-            failureThreshold: 3
-```
-
-## Health Status Values
-
-| Status | Description |
-|--------|-------------|
-| `healthy` | All checks passed, system is fully operational |
-| `degraded` | Some non-critical issues detected (e.g., open circuits, DLQ items), but system is functional |
-| `unhealthy` | Critical components unavailable, system cannot serve requests |
-
-## Response Formats
-
-Health endpoints support content negotiation via the `Accept` header:
-
-| Accept Header | Response Format |
-|--------------|-----------------|
-| `application/json` (default) | Full JSON response with status and details |
-| `text/plain` | Simple text: "OK" or "Service Unavailable" |
-
-## Integration with Existing Monitoring
-
-### Circuit Breaker Integration
-
-When circuit breakers are enabled, the `/health/components` endpoint includes:
-- Count of open circuits
-- Total number of circuits
-- Individual circuit states and failure counts
-
-Status becomes `degraded` when any circuit is open.
-
-### Dead Letter Queue Integration
-
-When DLQ is enabled, the `/health/components` endpoint includes:
-- Count of pending items awaiting retry
-- Count of exhausted items (exceeded max retries)
-- Timestamp of oldest item in queue
-
-Status becomes `degraded` when there are exhausted items.

package/src/core/health-check-service.ts

@@ -1,367 +0,0 @@
-/**
- * Health Check Service for Uploadista SDK.
- *
- * This module provides health checking functionality for:
- * - Storage backends
- * - KV stores
- * - Event broadcasters
- * - Circuit breaker state
- * - Dead letter queue state
- *
- * @module core/health-check-service
- */
-
-import { DeadLetterQueueService } from "@uploadista/core/flow";
-import type {
-  CircuitBreakerHealthSummary,
-  ComponentHealth,
-  DlqHealthSummary,
-  HealthCheckConfig,
-  HealthComponents,
-  HealthResponse,
-  HealthStatus,
-} from "@uploadista/core/types";
-import {
-  CircuitBreakerStoreService,
-  DEFAULT_HEALTH_CHECK_CONFIG,
-} from "@uploadista/core/types";
-import { Effect, Option } from "effect";
-
-// Track server start time for uptime calculation
-const serverStartTime = Date.now();
-
-/**
- * Gets the server uptime in milliseconds.
- */
-export function getServerUptime(): number {
-  return Date.now() - serverStartTime;
-}
-
-/**
- * Creates a timestamp string in ISO 8601 format.
- */
-export function getTimestamp(): string {
-  return new Date().toISOString();
-}
-
-/**
- * Creates a simple liveness health response.
- *
- * This is used for the `/health` endpoint which should return immediately
- * without checking any dependencies.
- */
-export function createLivenessResponse(
-  config?: HealthCheckConfig,
-): HealthResponse {
-  return {
-    status: "healthy",
-    timestamp: getTimestamp(),
-    version: config?.version,
-    uptime: getServerUptime(),
-  };
-}
-
-/**
- * Aggregates component health statuses into an overall status.
- *
- * @param components - The components to aggregate
- * @returns The overall health status
- */
-export function aggregateHealthStatus(
-  components: HealthComponents,
-): HealthStatus {
-  const statuses: HealthStatus[] = [];
-
-  // Core components (critical for readiness)
-  if (components.storage) statuses.push(components.storage.status);
-  if (components.kvStore) statuses.push(components.kvStore.status);
-
-  // Optional components (don't fail readiness)
-  // eventBroadcaster, circuitBreaker, and DLQ being degraded doesn't make system unhealthy
-
-  // If any critical component is unhealthy, overall is unhealthy
-  if (statuses.includes("unhealthy")) {
-    return "unhealthy";
-  }
-
-  // Check if any component (including optional) is degraded
-  const allStatuses: HealthStatus[] = [...statuses];
-  if (components.eventBroadcaster)
-    allStatuses.push(components.eventBroadcaster.status);
-  if (components.circuitBreaker)
-    allStatuses.push(components.circuitBreaker.status);
-  if (components.deadLetterQueue)
-    allStatuses.push(components.deadLetterQueue.status);
-
-  if (allStatuses.includes("degraded")) {
-    return "degraded";
-  }
-
-  return "healthy";
-}
-
-/**
- * Checks storage backend health by performing a simple operation.
- *
- * Currently returns healthy as we don't have direct access to storage
- * in health check context. This can be enhanced to do actual connectivity
- * checks when storage service is available.
- */
-export function checkStorageHealth(
-  _config: HealthCheckConfig,
-): Effect.Effect<ComponentHealth, never, never> {
-  const startTime = Date.now();
-
-  // TODO: When storage service is available in health context,
-  // perform actual health check (e.g., list bucket, check credentials)
-  // For now, return healthy with a note
-  return Effect.succeed({
-    status: "healthy" as HealthStatus,
-    latency: Date.now() - startTime,
-    message: "Storage backend configured",
-    lastCheck: getTimestamp(),
-  });
-}
-
-/**
- * Checks KV store health by performing a simple operation.
- *
- * Currently returns healthy as we don't have direct access to KV store
- * in health check context. This can be enhanced to do actual connectivity
- * checks when KV store service is available.
- */
-export function checkKvStoreHealth(
-  _config: HealthCheckConfig,
-): Effect.Effect<ComponentHealth, never, never> {
-  const startTime = Date.now();
-
-  // TODO: When KV store service is available in health context,
-  // perform actual health check (e.g., get/set test key)
-  // For now, return healthy with a note
-  return Effect.succeed({
-    status: "healthy" as HealthStatus,
-    latency: Date.now() - startTime,
-    message: "KV store configured",
-    lastCheck: getTimestamp(),
-  });
-}
-
-/**
- * Checks event broadcaster health.
- *
- * Currently returns healthy as we don't have direct access to event broadcaster
- * in health check context.
- */
-export function checkEventBroadcasterHealth(
-  _config: HealthCheckConfig,
-): Effect.Effect<ComponentHealth, never, never> {
-  const startTime = Date.now();
-
-  // TODO: When event broadcaster service is available in health context,
-  // perform actual health check
-  return Effect.succeed({
-    status: "healthy" as HealthStatus,
-    latency: Date.now() - startTime,
-    message: "Event broadcaster configured",
-    lastCheck: getTimestamp(),
-  });
-}
-
-/**
- * Gets circuit breaker health summary from the circuit breaker store.
- *
- * Uses the optional service pattern to check if circuit breaker is available.
- */
-export function getCircuitBreakerSummary(): Effect.Effect<
-  CircuitBreakerHealthSummary | undefined,
-  never,
-  never
-> {
-  return Effect.gen(function* () {
-    const cbStoreOption = yield* Effect.serviceOption(
-      CircuitBreakerStoreService,
-    );
-
-    if (Option.isNone(cbStoreOption)) {
-      // Circuit breaker not configured
-      return undefined;
-    }
-
-    const cbStore = cbStoreOption.value;
-    const statsResult = yield* Effect.either(cbStore.getAllStats());
-
-    if (statsResult._tag === "Left") {
-      // Error getting stats - return degraded status
-      return {
-        status: "degraded" as HealthStatus,
-        openCircuits: 0,
-        totalCircuits: 0,
-      };
-    }
-
-    const stats = statsResult.right;
-    const circuits = Array.from(stats.values());
-    const openCircuits = circuits.filter((c) => c.state === "open").length;
-    const totalCircuits = circuits.length;
-
-    // Determine status based on open circuits
-    let status: HealthStatus = "healthy";
-    if (openCircuits > 0) {
-      status = "degraded";
-    }
-
-    return {
-      status,
-      openCircuits,
-      totalCircuits,
-      circuits: circuits.map((c) => ({
-        nodeType: c.nodeType,
-        state: c.state,
-        failureCount: c.failureCount,
-        timeSinceLastStateChange: c.timeSinceLastStateChange,
-      })),
-    };
-  });
-}
-
-/**
- * Gets dead letter queue health summary from the DLQ service.
- *
- * Uses the optional service pattern to check if DLQ is available.
- */
-export function getDlqSummary(): Effect.Effect<
-  DlqHealthSummary | undefined,
-  never,
-  never
-> {
-  return Effect.gen(function* () {
-    const dlqOption = yield* DeadLetterQueueService.optional;
-
-    if (Option.isNone(dlqOption)) {
-      // DLQ not configured
-      return undefined;
-    }
-
-    const dlq = dlqOption.value;
-    const statsResult = yield* Effect.either(dlq.getStats());
-
-    if (statsResult._tag === "Left") {
-      // Error getting stats - return degraded status
-      return {
-        status: "degraded" as HealthStatus,
-        pendingItems: 0,
-        exhaustedItems: 0,
-      };
-    }
-
-    const stats = statsResult.right;
-
-    // Determine status based on exhausted items
-    let status: HealthStatus = "healthy";
-    if (stats.byStatus.exhausted > 0) {
-      status = "degraded";
-    }
-
-    return {
-      status,
-      pendingItems: stats.byStatus.pending,
-      exhaustedItems: stats.byStatus.exhausted,
-      oldestItem: stats.oldestItem?.toISOString(),
-    };
-  });
-}
-
-/**
- * Performs a full readiness check including all configured dependencies.
- *
- * @param config - Health check configuration
- * @returns Health response with component details
- */
-export function performReadinessCheck(
-  config: HealthCheckConfig = {},
-): Effect.Effect<HealthResponse, never, never> {
-  const effectiveConfig = { ...DEFAULT_HEALTH_CHECK_CONFIG, ...config };
-
-  return Effect.gen(function* () {
-    const components: HealthComponents = {};
-
-    // Check storage if enabled
-    if (effectiveConfig.checkStorage) {
-      components.storage = yield* checkStorageHealth(effectiveConfig);
-    }
-
-    // Check KV store if enabled
-    if (effectiveConfig.checkKvStore) {
-      components.kvStore = yield* checkKvStoreHealth(effectiveConfig);
-    }
-
-    // Check event broadcaster if enabled
-    if (effectiveConfig.checkEventBroadcaster) {
-      components.eventBroadcaster =
-        yield* checkEventBroadcasterHealth(effectiveConfig);
-    }
-
-    // Aggregate status
-    const status = aggregateHealthStatus(components);
-
-    return {
-      status,
-      timestamp: getTimestamp(),
-      version: config.version,
-      uptime: getServerUptime(),
-      components,
-    };
-  });
-}
-
-/**
- * Performs a full component health check including circuit breaker and DLQ.
- *
- * @param config - Health check configuration
- * @returns Health response with all component details
- */
-export function performComponentsCheck(
-  config: HealthCheckConfig = {},
-): Effect.Effect<HealthResponse, never, never> {
-  const effectiveConfig = { ...DEFAULT_HEALTH_CHECK_CONFIG, ...config };
-
-  return Effect.gen(function* () {
-    const components: HealthComponents = {};
-
-    // Check core components
-    if (effectiveConfig.checkStorage) {
-      components.storage = yield* checkStorageHealth(effectiveConfig);
-    }
-
-    if (effectiveConfig.checkKvStore) {
-      components.kvStore = yield* checkKvStoreHealth(effectiveConfig);
-    }
-
-    if (effectiveConfig.checkEventBroadcaster) {
-      components.eventBroadcaster =
-        yield* checkEventBroadcasterHealth(effectiveConfig);
-    }
-
-    // Check optional components (circuit breaker and DLQ)
-    const circuitBreakerSummary = yield* getCircuitBreakerSummary();
-    if (circuitBreakerSummary) {
-      components.circuitBreaker = circuitBreakerSummary;
-    }
-
-    const dlqSummary = yield* getDlqSummary();
-    if (dlqSummary) {
-      components.deadLetterQueue = dlqSummary;
-    }
-
-    // Aggregate status
-    const status = aggregateHealthStatus(components);
-
-    return {
-      status,
-      timestamp: getTimestamp(),
-      version: config.version,
-      uptime: getServerUptime(),
-      components,
-    };
-  });
-}