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

package/src/permissions/types.ts

@@ -1,151 +0,0 @@
-/**
- * Permission Types and Constants
- *
- * Defines the permission model for fine-grained access control in the uploadista engine.
- * Permissions follow a hierarchical format: `resource:action` with support for wildcards.
- */
-
-// ============================================================================
-// Engine Permissions - Admin operations
-// ============================================================================
-
-/**
- * Engine permissions for administrative operations.
- * These control access to health, readiness, metrics, and DLQ endpoints.
- */
-export const ENGINE_PERMISSIONS = {
-  /** Full admin access to all engine operations */
-  ALL: "engine:*",
-  /** Access health endpoint */
-  HEALTH: "engine:health",
-  /** Access readiness endpoint */
-  READINESS: "engine:readiness",
-  /** Access metrics endpoint */
-  METRICS: "engine:metrics",
-  /** Full DLQ access (implies read and write) */
-  DLQ: "engine:dlq",
-  /** Read DLQ entries */
-  DLQ_READ: "engine:dlq:read",
-  /** Retry/delete DLQ entries */
-  DLQ_WRITE: "engine:dlq:write",
-} as const;
-
-// ============================================================================
-// Flow Permissions - Flow execution operations
-// ============================================================================
-
-/**
- * Flow permissions for flow execution operations.
- */
-export const FLOW_PERMISSIONS = {
-  /** Full access to all flow operations */
-  ALL: "flow:*",
-  /** Execute flows */
-  EXECUTE: "flow:execute",
-  /** Cancel running flows */
-  CANCEL: "flow:cancel",
-  /** Check flow status */
-  STATUS: "flow:status",
-} as const;
-
-// ============================================================================
-// Upload Permissions - File upload operations
-// ============================================================================
-
-/**
- * Upload permissions for file upload operations.
- */
-export const UPLOAD_PERMISSIONS = {
-  /** Full access to all upload operations */
-  ALL: "upload:*",
-  /** Create uploads */
-  CREATE: "upload:create",
-  /** Read upload status */
-  READ: "upload:read",
-  /** Cancel uploads */
-  CANCEL: "upload:cancel",
-} as const;
-
-// ============================================================================
-// Combined Permissions Object
-// ============================================================================
-
-/**
- * All available permissions organized by category.
- *
- * @example
- * ```typescript
- * import { PERMISSIONS } from "@uploadista/server";
- *
- * const adminPermissions = [PERMISSIONS.ENGINE.ALL];
- * const userPermissions = [PERMISSIONS.FLOW.ALL, PERMISSIONS.UPLOAD.ALL];
- * ```
- */
-export const PERMISSIONS = {
-  ENGINE: ENGINE_PERMISSIONS,
-  FLOW: FLOW_PERMISSIONS,
-  UPLOAD: UPLOAD_PERMISSIONS,
-} as const;
-
-// ============================================================================
-// Permission Type Definitions
-// ============================================================================
-
-/** All engine permission strings */
-export type EnginePermission =
-  (typeof ENGINE_PERMISSIONS)[keyof typeof ENGINE_PERMISSIONS];
-
-/** All flow permission strings */
-export type FlowPermission =
-  (typeof FLOW_PERMISSIONS)[keyof typeof FLOW_PERMISSIONS];
-
-/** All upload permission strings */
-export type UploadPermission =
-  (typeof UPLOAD_PERMISSIONS)[keyof typeof UPLOAD_PERMISSIONS];
-
-/**
- * Union type of all valid permission strings.
- * Includes standard permissions and allows custom permissions via string.
- */
-export type Permission =
-  | EnginePermission
-  | FlowPermission
-  | UploadPermission
-  | (string & {}); // Allow custom permissions while maintaining autocomplete
-
-/**
- * Predefined permission sets for common use cases.
- */
-export const PERMISSION_SETS = {
-  /** Full admin access - all engine, flow, and upload permissions */
-  ADMIN: [ENGINE_PERMISSIONS.ALL] as const,
-
-  /** Organization owner - all flow and upload permissions */
-  ORGANIZATION_OWNER: [
-    FLOW_PERMISSIONS.ALL,
-    UPLOAD_PERMISSIONS.ALL,
-  ] as const,
-
-  /** Organization member - same as owner for now */
-  ORGANIZATION_MEMBER: [
-    FLOW_PERMISSIONS.ALL,
-    UPLOAD_PERMISSIONS.ALL,
-  ] as const,
-
-  /** API key - limited to execute flows and create uploads */
-  API_KEY: [
-    FLOW_PERMISSIONS.EXECUTE,
-    UPLOAD_PERMISSIONS.CREATE,
-  ] as const,
-} as const;
-
-/**
- * Hierarchical permission relationships.
- * When a parent permission is granted, all child permissions are implied.
- */
-export const PERMISSION_HIERARCHY: Record<string, readonly string[]> = {
-  [ENGINE_PERMISSIONS.DLQ]: [
-    ENGINE_PERMISSIONS.DLQ_READ,
-    ENGINE_PERMISSIONS.DLQ_WRITE,
-  ],
-} as const;

package/src/usage-hooks/index.ts

@@ -1,8 +0,0 @@
-/**
- * Usage Hooks Module
- *
- * Exports all usage hook types and services.
- */
-
-export * from "./types";
-export * from "./service";

package/src/usage-hooks/service.ts

@@ -1,162 +0,0 @@
-/**
- * Usage Hook Service
- *
- * Effect service for executing usage tracking hooks with timeout handling.
- */
-
-import { Context, Effect, Layer } from "effect";
-import type {
-  UsageHookConfig,
-  UsageHookResult,
-  UploadUsageContext,
-  FlowUsageContext,
-} from "./types";
-import { DEFAULT_USAGE_HOOK_TIMEOUT, continueResult } from "./types";
-
-/**
- * Usage Hook Service
- *
- * Provides methods to execute usage hooks during upload and flow processing.
- * Handles timeout and error recovery gracefully.
- */
-export class UsageHookService extends Context.Tag("UsageHookService")<
-  UsageHookService,
-  {
-    /**
-     * Execute onUploadStart hook if configured.
-     * Returns continue result if no hook is configured or on error/timeout.
-     */
-    readonly onUploadStart: (
-      ctx: UploadUsageContext,
-    ) => Effect.Effect<UsageHookResult>;
-
-    /**
-     * Execute onUploadComplete hook if configured.
-     * Errors are logged but swallowed (fire-and-forget).
-     */
-    readonly onUploadComplete: (ctx: UploadUsageContext) => Effect.Effect<void>;
-
-    /**
-     * Execute onFlowStart hook if configured.
-     * Returns continue result if no hook is configured or on error/timeout.
-     */
-    readonly onFlowStart: (
-      ctx: FlowUsageContext,
-    ) => Effect.Effect<UsageHookResult>;
-
-    /**
-     * Execute onFlowComplete hook if configured.
-     * Errors are logged but swallowed (fire-and-forget).
-     */
-    readonly onFlowComplete: (ctx: FlowUsageContext) => Effect.Effect<void>;
-  }
->() {}
-
-/**
- * Creates a UsageHookService Layer from configuration.
- *
- * @param config - Usage hook configuration with optional hooks and timeout
- * @returns Effect Layer providing UsageHookService
- */
-export const UsageHookServiceLive = (
-  config?: UsageHookConfig,
-): Layer.Layer<UsageHookService> => {
-  const hooks = config?.hooks;
-  const timeout = config?.timeout ?? DEFAULT_USAGE_HOOK_TIMEOUT;
-
-  return Layer.succeed(UsageHookService, {
-    onUploadStart: (ctx: UploadUsageContext) => {
-      if (!hooks?.onUploadStart) {
-        return Effect.succeed(continueResult());
-      }
-
-      return hooks
-        .onUploadStart(ctx)
-        .pipe(
-          // Add timeout - proceed on timeout (fail-open)
-          Effect.timeout(timeout),
-          Effect.map((result) => result ?? continueResult()),
-          // On any error, log and continue (fail-open for availability)
-          Effect.catchAll((error) =>
-            Effect.gen(function* () {
-              yield* Effect.logWarning(
-                `onUploadStart hook failed: ${error}. Proceeding with upload.`,
-              );
-              return continueResult();
-            }),
-          ),
-        );
-    },
-
-    onUploadComplete: (ctx: UploadUsageContext) => {
-      if (!hooks?.onUploadComplete) {
-        return Effect.void;
-      }
-
-      return hooks
-        .onUploadComplete(ctx)
-        .pipe(
-          // Add timeout
-          Effect.timeout(timeout),
-          Effect.asVoid,
-          // On any error, just log (fire-and-forget)
-          Effect.catchAll((error) =>
-            Effect.logWarning(
-              `onUploadComplete hook failed: ${error}. Upload already completed.`,
-            ),
-          ),
-        );
-    },
-
-    onFlowStart: (ctx: FlowUsageContext) => {
-      if (!hooks?.onFlowStart) {
-        return Effect.succeed(continueResult());
-      }
-
-      return hooks
-        .onFlowStart(ctx)
-        .pipe(
-          // Add timeout - proceed on timeout (fail-open)
-          Effect.timeout(timeout),
-          Effect.map((result) => result ?? continueResult()),
-          // On any error, log and continue (fail-open for availability)
-          Effect.catchAll((error) =>
-            Effect.gen(function* () {
-              yield* Effect.logWarning(
-                `onFlowStart hook failed: ${error}. Proceeding with flow.`,
-              );
-              return continueResult();
-            }),
-          ),
-        );
-    },
-
-    onFlowComplete: (ctx: FlowUsageContext) => {
-      if (!hooks?.onFlowComplete) {
-        return Effect.void;
-      }
-
-      return hooks
-        .onFlowComplete(ctx)
-        .pipe(
-          // Add timeout
-          Effect.timeout(timeout),
-          Effect.asVoid,
-          // On any error, just log (fire-and-forget)
-          Effect.catchAll((error) =>
-            Effect.logWarning(
-              `onFlowComplete hook failed: ${error}. Flow already completed.`,
-            ),
-          ),
-        );
-    },
-  });
-};
-
-/**
- * No-op implementation of UsageHookService.
- * All hooks are no-ops that return continue/void.
- * Used when no usage hooks are configured (default backward compatibility).
- */
-export const NoUsageHookServiceLive: Layer.Layer<UsageHookService> =
-  UsageHookServiceLive();

package/src/usage-hooks/types.ts

@@ -1,221 +0,0 @@
-/**
- * Usage Hook Types
- *
- * Types for lifecycle hooks that fire during upload and flow processing.
- * Used for usage tracking, quota enforcement, and billing integration.
- */
-
-import { Effect } from "effect";
-
-// ============================================================================
-// Usage Hook Result Types
-// ============================================================================
-
-/**
- * Result of a usage hook that can abort processing.
- * Used by onUploadStart and onFlowStart hooks.
- */
-export type UsageHookResult =
-  | { readonly action: "continue" }
-  | {
-      readonly action: "abort";
-      readonly reason: string;
-      readonly code?: string;
-    };
-
-/**
- * Helper to create a continue result.
- */
-export const continueResult = (): UsageHookResult => ({ action: "continue" });
-
-/**
- * Helper to create an abort result.
- */
-export const abortResult = (
-  reason: string,
-  code?: string,
-): UsageHookResult => ({
-  action: "abort",
-  reason,
-  code,
-});
-
-// ============================================================================
-// Usage Context Types
-// ============================================================================
-
-/**
- * Base metadata shared across all usage contexts.
- */
-export interface BaseUsageMetadata {
-  /** File size in bytes (if known) */
-  fileSize?: number;
-  /** MIME type of the file */
-  mimeType?: string;
-  /** Original file name */
-  fileName?: string;
-}
-
-/**
- * Metadata specific to upload operations.
- */
-export interface UploadUsageMetadata extends BaseUsageMetadata {
-  /** Unique upload identifier */
-  uploadId?: string;
-  /** Duration of the upload in milliseconds */
-  duration?: number;
-}
-
-/**
- * Metadata specific to flow operations.
- */
-export interface FlowUsageMetadata extends BaseUsageMetadata {
-  /** Flow identifier being executed */
-  flowId?: string;
-  /** Unique job identifier */
-  jobId?: string;
-  /** Number of nodes in the flow */
-  nodeCount?: number;
-  /** Total size of input files */
-  inputFileSize?: number;
-  /** Total size of output files (on complete) */
-  outputSize?: number;
-  /** Number of nodes that were executed (on complete) */
-  nodesExecuted?: number;
-  /** Duration of flow execution in milliseconds (on complete) */
-  duration?: number;
-  /** Flow completion status (on complete) */
-  status?: "success" | "failed" | "cancelled";
-}
-
-/**
- * Context passed to usage hooks containing client and operation information.
- */
-export interface UsageContext<
-  TMetadata extends BaseUsageMetadata = BaseUsageMetadata,
-> {
-  /** Organization/client identifier */
-  clientId: string;
-  /** Type of operation */
-  operation: "upload" | "flow";
-  /** Operation-specific metadata */
-  metadata: TMetadata;
-}
-
-/**
- * Upload-specific usage context.
- */
-export type UploadUsageContext = UsageContext<UploadUsageMetadata>;
-
-/**
- * Flow-specific usage context.
- */
-export type FlowUsageContext = UsageContext<FlowUsageMetadata>;
-
-// ============================================================================
-// Usage Hook Function Types
-// ============================================================================
-
-/**
- * Hook called before upload processing begins.
- * Can return abort to reject the upload (e.g., quota exceeded).
- */
-export type OnUploadStartHook = (
-  ctx: UploadUsageContext,
-) => Effect.Effect<UsageHookResult>;
-
-/**
- * Hook called after upload completes successfully.
- * Used for recording usage. Errors are logged but don't fail the upload.
- */
-export type OnUploadCompleteHook = (
-  ctx: UploadUsageContext,
-) => Effect.Effect<void>;
-
-/**
- * Hook called before flow execution begins.
- * Can return abort to reject the flow (e.g., subscription expired).
- */
-export type OnFlowStartHook = (
-  ctx: FlowUsageContext,
-) => Effect.Effect<UsageHookResult>;
-
-/**
- * Hook called after flow completes (success, failure, or cancellation).
- * Used for recording usage. Errors are logged but don't fail the response.
- */
-export type OnFlowCompleteHook = (
-  ctx: FlowUsageContext,
-) => Effect.Effect<void>;
-
-// ============================================================================
-// Usage Hooks Configuration
-// ============================================================================
-
-/**
- * Configuration for usage tracking hooks.
- * All hooks are optional - unconfigured hooks are no-ops.
- *
- * @example
- * ```typescript
- * const usageHooks: UsageHooks = {
- *   onUploadStart: (ctx) => Effect.gen(function* () {
- *     const hasQuota = yield* checkQuota(ctx.clientId, ctx.metadata.fileSize);
- *     if (!hasQuota) {
- *       return abortResult("Storage quota exceeded", "QUOTA_EXCEEDED");
- *     }
- *     return continueResult();
- *   }),
- *   onUploadComplete: (ctx) => Effect.gen(function* () {
- *     yield* recordUsage(ctx.clientId, ctx.metadata.fileSize);
- *   }),
- * };
- * ```
- */
-export interface UsageHooks {
-  /**
-   * Called before upload processing begins.
-   * Return abort to reject the upload.
-   */
-  onUploadStart?: OnUploadStartHook;
-
-  /**
-   * Called after upload completes successfully.
-   * Errors are logged but don't fail the upload.
-   */
-  onUploadComplete?: OnUploadCompleteHook;
-
-  /**
-   * Called before flow execution begins.
-   * Return abort to reject the flow.
-   */
-  onFlowStart?: OnFlowStartHook;
-
-  /**
-   * Called after flow completes (success, failure, or cancellation).
-   * Errors are logged but don't fail the response.
-   */
-  onFlowComplete?: OnFlowCompleteHook;
-}
-
-/**
- * Configuration for the usage hook service.
- */
-export interface UsageHookConfig {
-  /**
-   * The usage hooks to execute.
-   */
-  hooks?: UsageHooks;
-
-  /**
-   * Timeout for hook execution in milliseconds.
-   * If a hook takes longer than this, it will be considered failed.
-   * Default: 5000ms (5 seconds)
-   */
-  timeout?: number;
-}
-
-/**
- * Default timeout for usage hooks (5 seconds).
- */
-export const DEFAULT_USAGE_HOOK_TIMEOUT = 5000;