@gravito/radiance 1.0.4 → 2.0.0

package/dist/core/src/PlanetCore.d.ts

@@ -0,0 +1,408 @@
+/**
+ * @fileoverview PlanetCore - The Heart of Gravito Framework
+ *
+ * The micro-kernel that orchestrates the entire Galaxy Architecture.
+ * Manages HTTP routing, middleware, error handling, and orbit integration.
+ *
+ * @module @gravito/core
+ * @since 1.0.0
+ */
+import { type HttpAdapter } from './adapters/types';
+import { ConfigManager } from './ConfigManager';
+import { Container } from './Container';
+import { EventManager } from './EventManager';
+import { type RegisterGlobalErrorHandlersOptions } from './GlobalErrorHandlers';
+import { HookManager } from './HookManager';
+import type { fail } from './helpers/response';
+import type { ContentfulStatusCode, GravitoContext } from './http/types';
+import { type Logger } from './Logger';
+import { type ObservabilityProvider } from './observability/contracts';
+import type { ServiceProvider } from './ServiceProvider';
+/**
+ * CacheService interface for orbit-injected cache
+ * Orbits implementing cache should conform to this interface
+ */
+export interface CacheService {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    remember<T>(key: string, ttl: number, callback: () => Promise<T>): Promise<T>;
+}
+/**
+ * Interface for View Rendering Service
+ * @public
+ */
+export interface ViewService {
+    render(view: string, data?: Record<string, unknown>, options?: Record<string, unknown>): string;
+}
+/**
+ * Context passed to error handlers
+ * @public
+ */
+export type ErrorHandlerContext = {
+    core: PlanetCore;
+    c: GravitoContext;
+    error: unknown;
+    isProduction: boolean;
+    accept: string;
+    wantsHtml: boolean;
+    status: ContentfulStatusCode;
+    payload: ReturnType<typeof fail>;
+    logLevel?: 'error' | 'warn' | 'info' | 'none';
+    logMessage?: string;
+    html?: {
+        templates: string[];
+        data: Record<string, unknown>;
+    };
+};
+/**
+ * Interface for Gravito Orbit (Plugin/Module)
+ * @public
+ */
+export interface GravitoOrbit {
+    install(core: PlanetCore): void | Promise<void>;
+}
+/**
+ * Configuration for booting PlanetCore
+ * @public
+ */
+export type GravitoConfig = {
+    logger?: Logger;
+    config?: Record<string, unknown>;
+    orbits?: (new () => GravitoOrbit)[] | GravitoOrbit[];
+    /**
+     * HTTP Adapter to use. Defaults to BunNativeAdapter in Bun environments.
+     * In non-Bun environments, must be provided explicitly.
+     * @example
+     * ```typescript
+     * import { PhotonAdapter } from '@gravito/photon/adapter'
+     * new PlanetCore({ adapter: new PhotonAdapter() })
+     * ```
+     * See https://gravito.dev/guides/http-adapters for available adapters.
+     * @since 2.0.0
+     */
+    adapter?: HttpAdapter;
+    /**
+     * Dependency Injection Container. If provided, PlanetCore will use this
+     * container instead of creating a new one. This allows sharing a container
+     * between Application and PlanetCore.
+     * @since 2.0.0
+     */
+    container?: Container;
+    /**
+     * Observability configuration for event system.
+     * @since 2.1.0
+     */
+    observability?: {
+        /**
+         * Enable event system observability (metrics, tracing).
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Enable OpenTelemetry distributed tracing.
+         * @default false
+         */
+        tracing?: boolean;
+        /**
+         * Prefix for metric names.
+         * @default 'gravito_event_'
+         */
+        metricsPrefix?: string;
+        /**
+         * Prometheus metrics configuration.
+         */
+        prometheus?: {
+            /**
+             * Enable Prometheus metrics endpoint.
+             * @default true
+             */
+            enabled?: boolean;
+            /**
+             * Port for Prometheus metrics endpoint.
+             * @default 9090
+             */
+            port?: number;
+            /**
+             * Endpoint path for metrics.
+             * @default '/metrics'
+             */
+            endpoint?: string;
+        };
+    };
+    /**
+     * Observability provider for distributed tracing and metrics.
+     * If provided, this will be used instead of the default OTel setup.
+     * @since 2.2.0
+     */
+    observabilityProvider?: ObservabilityProvider;
+};
+import { Router } from './Router';
+import { Encrypter } from './security/Encrypter';
+import { BunHasher } from './security/Hasher';
+/**
+ * PlanetCore - The Heart of Gravito Framework
+ *
+ * The micro-kernel that orchestrates the entire Galaxy Architecture.
+ * Manages HTTP routing, middleware, error handling, and orbit integration.
+ * @public
+ */
+export declare class PlanetCore {
+    /**
+     * The HTTP adapter used by this core instance.
+     * @since 2.0.0
+     */
+    private _adapter;
+    /**
+     * Access the underlying Photon app instance.
+     * @deprecated Use adapter methods for new code. This property is kept for backward compatibility.
+     */
+    get app(): unknown;
+    /**
+     * Get the HTTP adapter instance.
+     * @since 2.0.0
+     */
+    get adapter(): HttpAdapter;
+    logger: Logger;
+    config: ConfigManager;
+    hooks: HookManager;
+    events: EventManager;
+    router: Router;
+    container: Container;
+    /** @deprecated Use core.container instead */
+    services: Map<string, unknown>;
+    encrypter?: Encrypter;
+    hasher: BunHasher;
+    /**
+     * Observability provider for distributed tracing and metrics.
+     * @since 2.2.0
+     */
+    observabilityProvider: ObservabilityProvider;
+    private providers;
+    private deferredProviders;
+    private bootedProviders;
+    private isShuttingDown;
+    /**
+     * Global shutdown timeout in milliseconds (D-10).
+     * If the entire shutdown sequence does not complete within this limit,
+     * a warning is logged and shutdown is force-completed so the process can exit.
+     */
+    private static readonly GLOBAL_SHUTDOWN_TIMEOUT;
+    /**
+     * Initialize observability asynchronously (metrics, tracing, Prometheus).
+     * This is called from constructor but doesn't block initialization.
+     *
+     * Phase 2.2 Update: Now uses the observabilityProvider passed from @gravito/monitor
+     * or falls back to OTel implementation if available for backward compatibility.
+     *
+     * @internal
+     */
+    private initializeObservabilityAsync;
+    /**
+     * Initialize Prometheus metrics asynchronously.
+     *
+     * @internal
+     * @deprecated Prometheus setup has been moved to @gravito/monitor
+     */
+    private initializePrometheusAsync;
+    /**
+     * Register a service provider to the core.
+     *
+     * Service providers are the central place to configure your application.
+     * They bind services to the container and bootstrap application features.
+     *
+     * @param provider - The ServiceProvider instance to register.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * core.register(new DatabaseServiceProvider());
+     * ```
+     */
+    register(provider: ServiceProvider): this;
+    /**
+     * Bootstrap the application by registering and booting providers.
+     *
+     * This method orchestrates the two-phase startup sequence:
+     * 1. Registration: Calls `register()` on all providers to bind services.
+     * 2. Booting: Calls `boot()` on all providers once all bindings are ready.
+     *
+     * This method must be called before the application starts handling requests.
+     *
+     * @returns Promise that resolves when bootstrapping is complete.
+     * @throws Error if a deferred provider has an asynchronous register method.
+     *
+     * @example
+     * ```typescript
+     * await core.bootstrap();
+     * ```
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Called when the application is ready to accept requests.
+     *
+     * Invokes the `onReady()` lifecycle hook on all providers.
+     * Called automatically at the end of `bootstrap()`.
+     *
+     * @returns Promise that resolves when all providers are ready.
+     *
+     * @example
+     * ```typescript
+     * await core.ready();
+     * ```
+     */
+    ready(): Promise<void>;
+    /**
+     * Gracefully shutdown the application.
+     *
+     * Invokes the `onShutdown()` lifecycle hook on all providers in reverse order (LIFO).
+     * Should be called when the application receives a termination signal.
+     *
+     * @returns Promise that resolves when all providers have shut down.
+     *
+     * @example
+     * ```typescript
+     * process.on('SIGTERM', () => core.shutdown());
+     * ```
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Setup deferred provider resolution.
+     * Wraps container.make to auto-register deferred providers on first request.
+     *
+     * @internal
+     */
+    private setupDeferredProviderResolution;
+    /**
+     * Register a deferred provider on-demand.
+     *
+     * @internal
+     */
+    private registerDeferredProvider;
+    /**
+     * Boot a single provider if not already booted.
+     *
+     * @internal
+     */
+    private bootProvider;
+    constructor(options?: {
+        logger?: Logger;
+        config?: Record<string, unknown>;
+        adapter?: HttpAdapter;
+        container?: Container;
+        observabilityProvider?: ObservabilityProvider;
+    });
+    /**
+     * Setup process signal handlers for graceful shutdown
+     *
+     * @internal
+     */
+    private setupSignalHandlers;
+    /**
+     * Programmatically register an infrastructure module (Orbit).
+     * @since 2.0.0
+     *
+     * @param orbit - The orbit class or instance to register.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * await core.orbit(OrbitCache);
+     * ```
+     */
+    orbit(orbit: GravitoOrbit | (new () => GravitoOrbit)): Promise<this>;
+    /**
+     * Programmatically register a feature module (Satellite).
+     * Alias for register() with provider support.
+     * @since 2.0.0
+     *
+     * @param satellite - The provider or setup function.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * await core.use(new AuthProvider());
+     * ```
+     */
+    use(satellite: ServiceProvider | ((core: PlanetCore) => void | Promise<void>)): Promise<this>;
+    /**
+     * Register a global error handler for process-level exceptions.
+     *
+     * Captures `unhandledRejection` and `uncaughtException` to prevent process crashes
+     * and allow for graceful shutdown or error reporting.
+     *
+     * @param options - Configuration for global error handling.
+     * @returns A function to unregister the global error handlers.
+     *
+     * @example
+     * ```typescript
+     * const unregister = core.registerGlobalErrorHandlers({
+     *   exitOnFatal: true
+     * });
+     * ```
+     */
+    registerGlobalErrorHandlers(options?: Omit<RegisterGlobalErrorHandlersOptions, 'core'>): () => void;
+    /**
+     * Predictive Route Warming (JIT Optimization).
+     *
+     * Pre-compiles or warms up the specified paths in the HTTP adapter to reduce
+     * latency for the first request to these endpoints.
+     *
+     * @param paths - List of paths to warm up.
+     * @returns Promise that resolves when warming is complete.
+     *
+     * @example
+     * ```typescript
+     * await core.warmup(['/api/v1/products', '/api/v1/categories']);
+     * ```
+     */
+    warmup(paths: string[]): Promise<void>;
+    /**
+     * Boot the application with a configuration object (IoC style default entry)
+     *
+     * @param config - The Gravito configuration object.
+     * @returns A Promise resolving to the booted PlanetCore instance.
+     *
+     * @example
+     * ```typescript
+     * const core = await PlanetCore.boot(config);
+     * ```
+     */
+    static boot(config: GravitoConfig): Promise<PlanetCore>;
+    /**
+     * Mount an Orbit (a PlanetCore instance or native app) to a specific URL path.
+     *
+     * This allows for micro-service like composition where different parts of the
+     * application can be developed as independent Orbits and mounted together.
+     *
+     * @param path - The URL path to mount the orbit at.
+     * @param orbitApp - The application instance (PlanetCore, HttpAdapter, or native app).
+     *
+     * @example
+     * ```typescript
+     * const blogOrbit = new PlanetCore();
+     * core.mountOrbit('/blog', blogOrbit);
+     * ```
+     */
+    mountOrbit(path: string, orbitApp: unknown): void;
+    /**
+     * Start the core (Liftoff).
+     *
+     * Returns a config object for `Bun.serve`.
+     *
+     * @param port - Optional port number (defaults to config or 3000).
+     * @returns An object compatible with Bun.serve({ ... }).
+     *
+     * @example
+     * ```typescript
+     * export default core.liftoff(3000);
+     * ```
+     */
+    liftoff(port?: number): {
+        port: number;
+        fetch: (request: Request, server?: unknown) => Response | Promise<Response>;
+        core: PlanetCore;
+        websocket?: HttpAdapter['websocket'];
+    };
+}

package/dist/core/src/RequestContext.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview RequestContext - AsyncLocalStorage-based request context management
+ *
+ * Allows deep service layers to access request-scoped data (requestId, userId, etc.)
+ * without passing parameters through the call stack.
+ *
+ * @module @gravito/core/RequestContext
+ * @since 2.2.0
+ */
+/**
+ * 請求上下文資料介面
+ * 包含請求相關的唯一識別碼和上下文資訊
+ * @public
+ */
+export interface RequestContextData {
+    /** 唯一的請求識別碼 */
+    requestId: string;
+    /** 使用者 ID（可選） */
+    userId?: string;
+    /** 租戶 ID（可選） */
+    tenantId?: string;
+    /** 追蹤 ID（可選） */
+    traceId?: string;
+    /** 自訂欄位 */
+    [key: string]: unknown;
+}
+/**
+ * RequestContext 物件 - 管理請求上下文的 API
+ *
+ * 提供在非同步鏈中存取和設定請求上下文的方法
+ * @public
+ */
+export declare const RequestContext: {
+    /**
+     * 在給定的上下文中執行函式
+     *
+     * 確保函式及其所有非同步呼叫都在同一個上下文中執行
+     *
+     * @param data - 請求上下文資料
+     * @param fn - 要執行的函式（可以是非同步的或同步的）
+     * @returns 如果函式是非同步的，返回 Promise；如果是同步的，直接返回值
+     *
+     * @example
+     * ```typescript
+     * await RequestContext.run({ requestId: 'req-123' }, async () => {
+     *   const userId = RequestContext.get()?.userId;
+     * });
+     *
+     * const result = RequestContext.run({ requestId: 'req-123' }, () => {
+     *   return 'sync-result';
+     * });
+     * ```
+     */
+    run<T>(data: RequestContextData, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * 獲取當前請求的上下文資料
+     *
+     * @returns 請求上下文資料，如果不在請求上下文中則返回 undefined
+     *
+     * @example
+     * ```typescript
+     * const context = RequestContext.get();
+     * if (context) {
+     *   console.log(context.requestId);
+     * }
+     * ```
+     */
+    get(): RequestContextData | undefined;
+    /**
+     * 獲取當前請求的上下文資料，如果不存在則拋出錯誤
+     *
+     * @returns 請求上下文資料
+     * @throws Error 如果不在請求上下文中
+     *
+     * @example
+     * ```typescript
+     * const context = RequestContext.getOrThrow();
+     * console.log(context.requestId); // 保證不為 undefined
+     * ```
+     */
+    getOrThrow(): RequestContextData;
+    /**
+     * 在當前上下文中設定或修改值
+     *
+     * @param key - 要設定的欄位名稱
+     * @param value - 要設定的值
+     * @throws Error 如果不在請求上下文中
+     *
+     * @example
+     * ```typescript
+     * RequestContext.set('userId', 'user-456');
+     * const userId = RequestContext.get()?.userId; // 'user-456'
+     * ```
+     */
+    set(key: string, value: unknown): void;
+};
+export default RequestContext;

package/dist/core/src/Route.d.ts

@@ -0,0 +1,36 @@
+import type { GravitoMiddleware } from './http/types';
+import type { ControllerClass, FormRequestClass, ResourceOptions, RouteHandler, RouteOptions, Router } from './Router';
+/**
+ * Route definition helper.
+ * Represents a registered route and allows method chaining for middleware/names.
+ * @public
+ */
+export declare class Route {
+    private router;
+    private method;
+    private path;
+    private options;
+    constructor(router: Router, method: string, path: string, options: RouteOptions);
+    /**
+     * Name the route
+     */
+    name(name: string): this;
+    static get(path: string, handler: RouteHandler): Route;
+    static get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static get(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static post(path: string, handler: RouteHandler): Route;
+    static post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static post(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static put(path: string, handler: RouteHandler): Route;
+    static put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static put(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static delete(path: string, handler: RouteHandler): Route;
+    static delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static delete(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static patch(path: string, handler: RouteHandler): Route;
+    static patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static patch(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+    static prefix(path: string): import("@gravito/core").RouteGroup;
+    static middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): import("@gravito/core").RouteGroup;
+}