@gravito/radiance 1.0.4 → 2.0.0

package/dist/core/src/hooks/dlq-operations.d.ts

@@ -0,0 +1,60 @@
+import type { DeadLetterQueue } from '../events/DeadLetterQueue';
+import type { EventOptions } from '../events/EventOptions';
+import type { DeadLetterQueueManager } from '../reliability/DeadLetterQueueManager';
+/**
+ * DLQ 操作輔助函式模組。
+ *
+ * 提取自 HookManager 的 DLQ 管理邏輯，以降低 HookManager 複雜度。
+ * 這些函式接受所需依賴作為參數，便於測試與重用。
+ *
+ * @internal
+ */
+/**
+ * 重新加入單一 DLQ 項目到事件佇列。
+ *
+ * @param dlqEntryId - DLQ 項目 ID
+ * @param dlq - 記憶體內 DLQ 實例
+ * @param requeue - 重新加入佇列的回調函式
+ * @returns 是否成功重新加入
+ */
+export declare function requeueDLQEntry(dlqEntryId: string, dlq: DeadLetterQueue, requeue: (eventName: string, payload: unknown, options: EventOptions) => Promise<void>): Promise<boolean>;
+/**
+ * 批次重新加入指定事件名稱的所有 DLQ 項目。
+ *
+ * @param eventName - 事件名稱
+ * @param dlq - 記憶體內 DLQ 實例
+ * @param requeue - 重新加入佇列的回調函式
+ * @returns 成功重新加入的項目數
+ */
+export declare function requeueDLQBatch(eventName: string, dlq: DeadLetterQueue, requeue: (entryId: string) => Promise<boolean>): Promise<number>;
+/**
+ * 建立 EventPriorityQueue 持久化 DLQ 處理器。
+ *
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @returns 持久化 DLQ 處理器函式
+ */
+export declare function createPersistentDLQHandler(persistentDlqManager: DeadLetterQueueManager): (hook: string, args: unknown, options: EventOptions, error: Error, retryCount: number, _firstFailedAt: number) => Promise<void>;
+/**
+ * 重新加入持久化 DLQ 單一項目到事件佇列。
+ *
+ * @param dlqId - 持久化 DLQ 項目 UUID
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @param doActionAsync - 重新加入佇列的回調函式
+ * @returns 是否成功重新加入
+ */
+export declare function requeuePersistentDLQEntry(dlqId: string, persistentDlqManager: DeadLetterQueueManager, doActionAsync: (event: string, args: unknown, options: EventOptions) => Promise<void>): Promise<boolean>;
+/**
+ * 批次重新加入持久化 DLQ 項目。
+ *
+ * @param filter - 過濾條件
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @returns 批次操作結果統計
+ */
+export declare function requeuePersistentDLQBatch(filter: {
+    eventName?: string;
+    status?: 'pending' | 'requeued' | 'resolved' | 'abandoned';
+} | undefined, persistentDlqManager: DeadLetterQueueManager): Promise<{
+    total: number;
+    succeeded: number;
+    failed: number;
+}>;

package/dist/core/src/hooks/types.d.ts

@@ -0,0 +1,107 @@
+import type { CircuitBreakerOptions } from '../events/CircuitBreaker';
+import type { EventBackend } from '../events/EventBackend';
+import type { EventQueueConfig } from '../events/EventPriorityQueue';
+/**
+ * Callback function for filters (transforms values).
+ * @public
+ */
+export type FilterCallback<T = unknown> = (value: T, ...args: unknown[]) => Promise<T> | T;
+/**
+ * Callback function for actions (side effects).
+ * @public
+ */
+export type ActionCallback<TArgs = unknown> = (args: TArgs) => Promise<void> | void;
+/**
+ * Options for listener registration.
+ * @public
+ */
+export interface ListenerOptions {
+    /**
+     * Explicitly specify the listener type.
+     * - 'sync': Force synchronous dispatch for this listener
+     * - 'async': Force asynchronous dispatch for this listener
+     * - 'auto': Auto-detect based on function signature (default)
+     * @default 'auto'
+     */
+    type?: 'sync' | 'async' | 'auto';
+    /**
+     * Circuit breaker configuration for this listener.
+     */
+    circuitBreaker?: CircuitBreakerOptions;
+}
+/**
+ * Information about a registered listener.
+ * @public
+ */
+export interface ListenerInfo {
+    /**
+     * The callback function.
+     */
+    callback: ActionCallback;
+    /**
+     * Whether the listener is considered async.
+     */
+    isAsync: boolean;
+    /**
+     * The explicit type override, if any.
+     */
+    typeOverride?: 'sync' | 'async' | 'auto';
+}
+/**
+ * Configuration for HookManager.
+ * @public
+ */
+export interface HookManagerConfig {
+    /**
+     * Enable async event dispatch by default.
+     * When true, doAction() will automatically use async dispatch if any listener is async.
+     * @default false
+     */
+    asyncByDefault?: boolean;
+    /**
+     * Migration mode for backward compatibility.
+     * - 'sync': All events use synchronous dispatch (legacy mode)
+     * - 'hybrid': Auto-detect and use async for async listeners (recommended)
+     * - 'async': All events use async dispatch (future mode)
+     * @default 'sync'
+     */
+    migrationMode?: 'sync' | 'hybrid' | 'async';
+    /**
+     * Enable deprecation warnings for synchronous event dispatch.
+     * @default false
+     */
+    showDeprecationWarnings?: boolean;
+    /**
+     * Enable Dead Letter Queue for failed events.
+     * @default true
+     */
+    enableDLQ?: boolean;
+    /**
+     * Configuration for the event priority queue (Backpressure).
+     */
+    queue?: EventQueueConfig;
+    /**
+     * Custom event backend for distributed processing.
+     */
+    backend?: EventBackend;
+    /**
+     * Database connection for persistent DLQ (optional).
+     * If provided, failed events after max retries will be persisted to database.
+     */
+    db?: any;
+    /**
+     * Enable persistent DLQ for failed events (requires db).
+     * @default false
+     */
+    enablePersistentDLQ?: boolean;
+    /**
+     * Message Queue Bridge for distributed event processing via Bull Queue.
+     * When provided, enables dispatchQueued() method for routing events to Redis-backed queue.
+     */
+    messageQueueBridge?: any;
+    /**
+     * Event aggregation configuration (FS-102).
+     * Enables deduplication and micro-batching for improved throughput.
+     */
+    aggregation?: any;
+}

package/dist/core/src/http/CookieJar.d.ts

@@ -0,0 +1,51 @@
+import type { Encrypter } from '../security/Encrypter';
+import type { GravitoContext } from './types';
+/**
+ * Options for setting cookies
+ * @public
+ */
+export interface CookieOptions {
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    maxAge?: number;
+    expires?: Date;
+    encrypt?: boolean;
+}
+/**
+ * Utility for managing cookies (request/response/encryption).
+ * @public
+ */
+export declare class CookieJar {
+    private encrypter?;
+    private queued;
+    constructor(encrypter?: Encrypter | undefined);
+    /**
+     * Parse cookies from a Cookie header string using Bun's native CookieMap
+     * @param header - The Cookie header value
+     * @returns Parsed cookies as key-value pairs
+     */
+    static parseCookies(header: string): Record<string, string>;
+    /**
+     * Queue a cookie to be sent with the response
+     */
+    queue(name: string, value: string, minutes?: number, options?: CookieOptions): void;
+    /**
+     * Make a cookie that lasts "forever" (5 years)
+     */
+    forever(name: string, value: string, options?: CookieOptions): void;
+    /**
+     * Expire a cookie
+     */
+    forget(name: string, options?: CookieOptions): void;
+    /**
+     * Serialize a cookie to a Set-Cookie header value using Bun's native Cookie API
+     */
+    private serializeCookie;
+    /**
+     * Attach queued cookies to the context
+     */
+    attach(c: GravitoContext): void;
+}

package/dist/core/src/http/cookie.d.ts

@@ -0,0 +1,29 @@
+import { type CookieOptions } from './CookieJar';
+import type { GravitoContext } from './types';
+/**
+ * Get a cookie value from the request
+ * @param c - Context object
+ * @param name - Cookie name
+ * @returns Cookie value or undefined
+ * @public
+ */
+export declare function getCookie(c: GravitoContext, name: string): string | undefined;
+/**
+ * Set a cookie in the response
+ * @param c - Context object
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options
+ * @public
+ */
+export declare function setCookie(c: GravitoContext, name: string, value: string, options?: CookieOptions & {
+    maxAge?: number;
+}): void;
+/**
+ * Delete a cookie (expire it)
+ * @param c - Context object
+ * @param name - Cookie name
+ * @param options - Cookie options (path, domain, etc.)
+ * @public
+ */
+export declare function deleteCookie(c: GravitoContext, name: string, options?: CookieOptions): void;

package/dist/core/src/http/types.d.ts

@@ -0,0 +1,395 @@
+/**
+ * @fileoverview Core HTTP Types for Gravito Framework
+ *
+ * These types provide a unified abstraction layer that decouples the framework
+ * from any specific HTTP engine (Photon, Express, custom, etc.).
+ *
+ * @module @gravito/core/http
+ * @since 2.0.0
+ */
+declare global {
+    interface ExecutionContext {
+        waitUntil(promise: Promise<unknown>): void;
+        passThroughOnException(): void;
+    }
+}
+/**
+ * Standard HTTP methods supported by Gravito
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * HTTP status codes
+ */
+export type StatusCode = number;
+/**
+ * Content-bearing HTTP status codes (excludes 1xx, 204, 304)
+ */
+export type ContentfulStatusCode = Exclude<StatusCode, 100 | 101 | 102 | 103 | 204 | 304>;
+/**
+ * Base context variables available in every request
+ * Orbits can extend this interface via module augmentation
+ *
+ * @example
+ * ```typescript
+ * // Extending variables in your orbit:
+ * declare module '@gravito/core' {
+ *   interface GravitoVariables {
+ *     myService: MyService
+ *   }
+ * }
+ * ```
+ */
+export interface GravitoVariables {
+    /**
+     * The PlanetCore instance
+     * @remarks Always available in PlanetCore-managed contexts
+     */
+    core?: unknown;
+    /**
+     * Logger instance
+     */
+    logger?: unknown;
+    /**
+     * Configuration manager
+     */
+    config?: unknown;
+    /**
+     * Cookie jar for managing response cookies
+     */
+    cookieJar?: unknown;
+    /**
+     * Middleware scope tracking for Orbit isolation
+     * Tracks which Orbit/scope this request belongs to
+     * Used to prevent cross-Orbit middleware contamination
+     * @since 2.3.0
+     */
+    middlewareScope?: string;
+    /** @deprecated Use ctx.route() instead */
+    route?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Validated request data targets
+ */
+export type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'form' | 'cookie';
+/**
+ * GravitoRequest - Unified request interface
+ *
+ * Provides a consistent API for accessing request data regardless of
+ * the underlying HTTP engine.
+ *
+ * @example
+ * ```typescript
+ * const userId = ctx.req.param('id')
+ * const search = ctx.req.query('q')
+ * const body = await ctx.req.json<CreateUserDto>()
+ * ```
+ */
+export interface GravitoRequest {
+    /** Full request URL */
+    readonly url: string;
+    /** HTTP method (uppercase) */
+    readonly method: string;
+    /** Request path without query string */
+    readonly path: string;
+    /**
+     * Route pattern (e.g., /users/:id) for the matched route
+     *
+     * This provides the parameterized route pattern instead of the concrete path,
+     * which is critical for preventing high cardinality issues in metrics systems.
+     *
+     * @example
+     * ```typescript
+     * // For request: GET /users/123
+     * ctx.req.path          // => "/users/123"
+     * ctx.req.routePattern  // => "/users/:id"
+     * ```
+     */
+    readonly routePattern?: string;
+    /**
+     * Alias for routePattern (for Hono/Express compatibility)
+     * @deprecated Use `routePattern` instead
+     */
+    readonly routePath?: string;
+    /**
+     * Get a route parameter value
+     * @param name - Parameter name (e.g., 'id' for route '/users/:id')
+     */
+    param(name: string): string | undefined;
+    /**
+     * Get all route parameters
+     */
+    params(): Record<string, string>;
+    /**
+     * Get a query string parameter
+     * @param name - Query parameter name
+     */
+    query(name: string): string | undefined;
+    /**
+     * Get all query parameters
+     */
+    queries(): Record<string, string | string[]>;
+    /**
+     * Get a request header value
+     * @param name - Header name (case-insensitive)
+     */
+    header(name: string): string | undefined;
+    /**
+     * Get all request headers
+     */
+    header(): Record<string, string>;
+    /**
+     * Parse request body as JSON
+     * @throws {Error} If body is not valid JSON
+     */
+    json<T = unknown>(): Promise<T>;
+    /**
+     * Parse request body as text
+     */
+    text(): Promise<string>;
+    /**
+     * Parse request body as FormData
+     */
+    formData(): Promise<FormData>;
+    /**
+     * Parse request body as ArrayBuffer
+     */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Parse form data (urlencoded or multipart)
+     */
+    parseBody<T = unknown>(): Promise<T>;
+    /**
+     * Get the raw Request object
+     */
+    readonly raw: Request;
+    /**
+     * Get validated data from a specific source
+     * @param target - The validation target
+     * @throws {Error} If validation was not performed for this target
+     */
+    valid<T = unknown>(target: ValidationTarget): T;
+    /**
+     * Store validated data for a specific source
+     * @param target - The validation target
+     * @param data - The validated data to store
+     */
+    setValidated(target: ValidationTarget, data: unknown): void;
+}
+/**
+ * Options for request forwarding (Proxy)
+ */
+export interface ProxyOptions {
+    /** Override or add request headers */
+    headers?: Record<string, string>;
+    /** Whether to keep the original Host header (default: false) */
+    preserveHost?: boolean;
+    /** Whether to add X-Forwarded-* headers (default: true) */
+    addForwardedHeaders?: boolean;
+    /** Path rewriting logic */
+    rewritePath?: (path: string) => string;
+}
+/**
+ * GravitoContext - Unified request context
+ *
+ * This interface encapsulates all HTTP request/response operations,
+ * enabling seamless replacement of the underlying HTTP engine.
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * // In a controller
+ * async show(ctx: GravitoContext) {
+ *   const id = ctx.req.param('id')
+ *   const user = await User.find(id)
+ *   return ctx.json({ user })
+ * }
+ * ```
+ */
+export interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
+    /** The incoming request */
+    readonly req: GravitoRequest;
+    /**
+     * The response object (for middleware introspection).
+     * Middleware can read response headers and status, or mutate the response.
+     *
+     * @remarks
+     * This property is mutable, allowing middleware to replace the response object.
+     * Example: `c.res = new Response(...)`
+     *
+     * May be undefined until a handler creates a response.
+     */
+    res?: Response;
+    /**
+     * Send a JSON response
+     * @param data - Data to serialize as JSON
+     * @param status - HTTP status code (default: 200)
+     */
+    json<T>(data: T, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a plain text response
+     * @param text - Text content
+     * @param status - HTTP status code (default: 200)
+     */
+    text(text: string, status?: ContentfulStatusCode): Response;
+    /**
+     * Send an HTML response
+     * @param html - HTML content
+     * @param status - HTTP status code (default: 200)
+     */
+    html(html: string, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a redirect response
+     * @param url - Target URL
+     * @param status - Redirect status code (default: 302)
+     */
+    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+    /**
+     * Create a Response with no body
+     * @param status - HTTP status code
+     */
+    body(data: BodyInit | null, status?: StatusCode): Response;
+    /**
+     * Stream a response
+     * @param stream - ReadableStream to send
+     * @param status - HTTP status code (default: 200)
+     */
+    stream(stream: ReadableStream, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a 404 Not Found response
+     */
+    notFound(message?: string): Response;
+    /**
+     * Send a 403 Forbidden response
+     */
+    forbidden(message?: string): Response;
+    /**
+     * Send a 401 Unauthorized response
+     */
+    unauthorized(message?: string): Response;
+    /**
+     * Send a 400 Bad Request response
+     */
+    badRequest(message?: string): Response;
+    /**
+     * Forward the current request to another URL (Reverse Proxy)
+     * @param target - Target URL or base URL to forward to
+     * @param options - Optional proxy options
+     */
+    forward(target: string, options?: ProxyOptions): Promise<Response>;
+    /**
+     * Set a response header
+     * @param name - Header name
+     * @param value - Header value
+     * @param options - Options (append: true to add multiple values)
+     */
+    header(name: string, value: string, options?: {
+        append?: boolean;
+    }): void;
+    /**
+     * Get a request header
+     * @param name - Header name (case-insensitive)
+     */
+    header(name: string): string | undefined;
+    /**
+     * Set the response status code
+     * @param code - HTTP status code
+     */
+    status(code: StatusCode): void;
+    /**
+     * Get a context variable
+     * @param key - Variable key
+     */
+    get<K extends keyof V>(key: K): V[K];
+    /**
+     * Set a context variable
+     * @param key - Variable key
+     * @param value - Variable value
+     */
+    set<K extends keyof V>(key: K, value: V[K]): void;
+    /**
+     * Get the execution context (for Cloudflare Workers, etc.)
+     */
+    readonly executionCtx?: ExecutionContext;
+    /**
+     * Get environment bindings (for Cloudflare Workers, etc.)
+     */
+    readonly env?: Record<string, unknown>;
+    /**
+     * URL generator helper.
+     * Generates a URL for a named route.
+     */
+    route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
+    /**
+     * Access the native context object from the underlying HTTP engine.
+     *
+     * ⚠️ WARNING: Using this ties your code to a specific adapter.
+     * Prefer using the abstraction methods when possible.
+     *
+     * @example
+     * ```typescript
+     * // Only when absolutely necessary
+     * const photonCtx = ctx.native as Context // Photon Context
+     * ```
+     */
+    readonly native: unknown;
+    /**
+     * Access the RequestScopeManager for this request
+     * Services resolved through this manager are scoped to the HTTP request lifetime.
+     */
+    requestScope(): any;
+    /**
+     * Resolve or create a request-scoped service
+     *
+     * @param key - Service key (string or symbol)
+     * @param factory - Factory function to create the service if not cached
+     * @returns The cached or newly created service instance
+     *
+     * @example
+     * ```typescript
+     * // Subsequent calls in the same request return the same instance
+     * const cache = ctx.scoped('product:cache', () => new RequestProductCache())
+     * ```
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
+}
+/**
+ * Next function for middleware chain
+ */
+export type GravitoNext = () => Promise<void>;
+/**
+ * GravitoHandler - Standard route handler type
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * const handler: GravitoHandler = async (ctx) => {
+ *   return ctx.json({ message: 'Hello, World!' })
+ * }
+ * ```
+ */
+export type GravitoHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;
+/**
+ * GravitoMiddleware - Standard middleware type
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * const logger: GravitoMiddleware = async (ctx, next) => {
+ *   console.log(`${ctx.req.method} ${ctx.req.path}`)
+ *   await next()
+ * }
+ * ```
+ */
+export type GravitoMiddleware<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>, next: GravitoNext) => Response | void | Promise<Response | void>;
+/**
+ * Error handler type
+ */
+export type GravitoErrorHandler<V extends GravitoVariables = GravitoVariables> = (error: Error, ctx: GravitoContext<V>) => Response | Promise<Response>;
+/**
+ * Not found handler type
+ */
+export type GravitoNotFoundHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;