@gravito/core 1.6.1 → 2.0.0

package/README.md

@@ -20,11 +20,16 @@
 - 🛰️ **Orbit Mounting** - Easily mount external Photon applications (Orbits) to specific paths.
 - 📝 **Logger System** - PSR-3 style logger interface with default standard output implementation.
 - ⚙️ **Config Manager** - Unified configuration management supporting environment variables, runtime injection, and file-based config loading.
-- 🛡️ **Security Middleware** - Built-in protection including CSRF, CORS, HSTS, and request throttling.
+- 🛡️ **Security Middleware** - Built-in protection (deprecated in v1.7.0, moved to `@gravito/photon`).
 - 🔌 **Runtime Adapters** - Abstraction layer for underlying runtimes (Bun, Node.js) and HTTP engines.
 - 🛡️ **Error Handling** - Built-in standardized JSON error responses, 404 handling, and process-level error management.
+- 🧠 **Request Context** - Global access to request data via `AsyncLocalStorage` (requestId, userId, etc.).
+- 🛠️ **CLI Commands** - CommandKernel for building artisan-style CLI tools.
+- 🏥 **Health Probes** - Cloud-native Liveness and Readiness probes.
+- ⚡ **Native Accelerators** - FFI-powered CBOR and hashing for peak performance.
 - 🚀 **Modern** - Built for **Bun** runtime with native TypeScript support.
 - 🪶 **Lightweight** - Zero external dependencies (except `@gravito/photon`).
+- 📈 **Performance Audited** - Full [2026 Performance & Debt Audit](../../docs/optimization/CORE_AUDIT_2026.md) completed.
 
 ## 📦 Installation
 
@@ -64,7 +69,19 @@ const core = new PlanetCore({
 });
 ```
 
-### 2. Dependency Injection
+### 2. Request Context (AsyncLocalStorage)
+
+Access request-scoped data anywhere in your application without parameter drilling:
+
+```typescript
+import { RequestContext } from '@gravito/core';
+
+// In a deep service layer
+const userId = RequestContext.get()?.userId;
+const requestId = RequestContext.get()?.requestId;
+```
+
+### 3. Dependency Injection
 
 Use the IoC Container to manage your application services:
 
@@ -95,7 +112,7 @@ await core.bootstrap();
 const cache = core.container.make('cache');
 ```
 
-### 3. Register Hooks
+### 4. Register Hooks
 
 Use **Filters** to modify data:
 
@@ -118,7 +135,23 @@ core.hooks.addAction('user_registered', async (userId: string) => {
 await core.hooks.doAction('user_registered', 'user_123');
 ```
 
-### 4. Mount an Orbit
+### 5. Reliability & Distributed Retries
+
+Built-in support for distributed retries via Bull Queue:
+
+```typescript
+import { RetryScheduler } from '@gravito/core';
+
+const scheduler = new RetryScheduler({
+  initialDelayMs: 1000,
+  multiplier: 2,
+  maxRetries: 5
+});
+
+core.hooks.setRetryScheduler(scheduler);
+```
+
+### 6. Mount an Orbit
 
 Orbits are just standard Photon applications that plug into the core.
 
@@ -132,14 +165,14 @@ blogOrbit.get('/posts', (c) => c.json({ posts: [] }));
 core.mountOrbit('/api/blog', blogOrbit);
 ```
 
-### 5. Liftoff! 🚀
+### 7. Liftoff! 🚀
 
 ```typescript
 // Export for Bun.serve
 export default core.liftoff(); // Automatically uses PORT from config/env
 ```
 
-### 6. Process-level Error Handling (Recommended)
+### 8. Process-level Error Handling (Recommended)
 
 Request-level errors are handled by `PlanetCore` automatically, but background jobs and startup code can still fail outside the request lifecycle.
 
@@ -154,6 +187,65 @@ core.hooks.addAction('processError:report', async (ctx) => {
 })
 ```
 
+## 📊 Observability & Metrics
+
+### Route Pattern Support
+
+To prevent high cardinality in Prometheus metrics caused by dynamic paths (e.g., `/users/123`, `/users/456`), Gravito automatically detects the `routePattern`:
+
+- **Path**: `/users/123`
+- **Pattern**: `/users/:id`
+
+The `routePattern` is available on the request object and used by the monitoring system.
+
+## 🩺 Health Probes
+
+Built-in support for cloud-native health checks:
+
+```typescript
+import { HealthProvider } from '@gravito/core';
+
+app.register(new HealthProvider());
+
+// Check: http://localhost:3000/health/liveness
+// Check: http://localhost:3000/health/readiness
+```
+
+## 🛠️ CLI Commands
+
+Easily build artisan-style CLI tools:
+
+```typescript
+import { CommandKernel } from '@gravito/core';
+
+const kernel = new CommandKernel(container);
+kernel.register('greet', async (args) => {
+  console.log('Hello', args[0]);
+});
+
+await kernel.handle(process.argv.slice(2));
+```
+
+## ⚡ Native Accelerators (FFI)
+
+Gravito Core leverages FFI to use high-performance C implementations for critical tasks:
+
+- **CBOR**: Efficient binary serialization.
+- **Hashing**: SIMD-accelerated SHA-256 and HMAC via Bun primitives.
+
+## 🛡️ Security Middleware Migration
+
+As of v1.7.0, all HTTP security middleware has been migrated to `@gravito/photon` for better engine alignment. Existing exports in `@gravito/core` are marked as `@deprecated` and will be removed in v2.0.0.
+
+**Migration:**
+```typescript
+// Before
+import { cors } from '@gravito/core';
+
+// After
+import { cors } from '@gravito/photon/middleware/security';
+```
+
 ## 📖 API Reference
 
 ### `Application` (Enterprise Container)
@@ -186,6 +278,8 @@ core.hooks.addAction('processError:report', async (ctx) => {
 - **`instance(key, instance)`**: Register an existing object instance.
 - **`has(key)`**: Check if a service is bound.
 
+The container includes built-in **circular dependency detection** to help identify architectural issues during development.
+
 #### Type Safety (ServiceMap)
 
 You can extend the `ServiceMap` interface to get automatic type inference for `container.make()`:

package/README.zh-TW.md

@@ -20,9 +20,13 @@
 - 🛰️ **Orbit Mounting** - 輕鬆將外部 Photon 應用程式（Orbits）掛載到特定路徑。
 - 📝 **Logger System** - PSR-3 風格的日誌介面，內建標準輸出實作。
 - ⚙️ **Config Manager** - 統一的配置管理，支援環境變數、運行時注入與基於檔案的配置載入。
-- 🛡️ **Security Middleware** - 內建保護功能，包括 CSRF、CORS、HSTS 與請求限流（Throttling）。
+- 🛡️ **Security Middleware** - 內建保護功能（自 v1.7.0 起標記為棄用，已遷移至 `@gravito/photon`）。
 - 🔌 **Runtime Adapters** - 底層運行時（Bun, Node.js）與 HTTP 引擎的抽象層。
 - 🛡️ **Error Handling** - 內建標準化 JSON 錯誤回應、404 處理與進程級別錯誤管理。
+- 🧠 **Request Context** - 透過 `AsyncLocalStorage` 全域存取請求資料（requestId, userId 等）。
+- 🛠️ **CLI Commands** - 使用 CommandKernel 構建 Artisan 風格的命令行工具。
+- 🏥 **Health Probes** - 雲原生 Liveness 與 Readiness 探針支援。
+- ⚡ **Native Accelerators** - 基於 FFI 的高效能 CBOR 與雜湊計算（雜湊加速）。
 - 🚀 **Modern** - 專為 **Bun** 運行時設計，原生支援 TypeScript。
 - 🪶 **Lightweight** - 除了 `@gravito/photon` 外零外部依賴。
 
@@ -64,7 +68,19 @@ const core = new PlanetCore({
 });
 ```
 
-### 2. 依賴注入
+### 2. 請求上下文 (AsyncLocalStorage)
+
+在應用程式的任何地方存取請求範圍內的資料，無需透過參數逐層傳遞：
+
+```typescript
+import { RequestContext } from '@gravito/core';
+
+// 在深層 Service 中
+const userId = RequestContext.get()?.userId;
+const requestId = RequestContext.get()?.requestId;
+```
+
+### 3. 依賴注入
 
 使用 IoC 容器管理應用程式服務：
 
@@ -95,7 +111,7 @@ await core.bootstrap();
 const cache = core.container.make('cache');
 ```
 
-### 3. 註冊 Hooks
+### 4. 註冊 Hooks
 
 使用 **Filters** 修改資料：
 
@@ -118,7 +134,23 @@ core.hooks.addAction('user_registered', async (userId: string) => {
 await core.hooks.doAction('user_registered', 'user_123');
 ```
 
-### 4. 掛載 Orbit
+### 5. 可靠性與分佈式重試
+
+內建透過 Bull Queue 實作的分佈式重試支援：
+
+```typescript
+import { RetryScheduler } from '@gravito/core';
+
+const scheduler = new RetryScheduler({
+  initialDelayMs: 1000,
+  multiplier: 2,
+  maxRetries: 5
+});
+
+core.hooks.setRetryScheduler(scheduler);
+```
+
+### 6. 掛載 Orbit
 
 Orbits 是標準的 Photon 應用程式，可以插入核心中。
 
@@ -132,14 +164,14 @@ blogOrbit.get('/posts', (c) => c.json({ posts: [] }));
 core.mountOrbit('/api/blog', blogOrbit);
 ```
 
-### 5. Liftoff! 🚀
+### 7. Liftoff! 🚀
 
 ```typescript
 // 為 Bun.serve 導出
 export default core.liftoff(); // 自動使用來自配置或環境變數的 PORT
 ```
 
-### 6. 進程級別錯誤處理（推薦）
+### 8. 進程級別錯誤處理（推薦）
 
 請求級別的錯誤由 `PlanetCore` 自動處理，但背景工作與啟動代碼仍可能在請求生命週期外失敗。
 
@@ -154,6 +186,67 @@ core.hooks.addAction('processError:report', async (ctx) => {
 })
 ```
 
+## 📊 可觀測性與指標
+
+### 路由模式（Route Pattern）支援
+
+為了防止因動態路徑（如 `/users/123`, `/users/456`）導致 Prometheus 指標基數（cardinality）爆炸，Gravito 會自動偵測 `routePattern`：
+
+- **Path**: `/users/123`
+- **Pattern**: `/users/:id`
+
+`routePattern` 可在請求物件中取得，並由監控系統自動使用。
+
+## 🩺 健康檢查（Health Probes）
+
+內建雲原生健康檢查支援：
+
+```typescript
+import { HealthProvider } from '@gravito/core';
+
+app.register(new HealthProvider());
+
+// 檢查: http://localhost:3000/health/liveness
+// 檢查: http://localhost:3000/health/readiness
+```
+
+## 🛠️ 命令行工具（CLI Commands）
+
+輕鬆構建 Artisan 風格的 CLI 工具：
+
+```typescript
+import { CommandKernel } from '@gravito/core';
+
+const kernel = new CommandKernel(container);
+kernel.register('greet', async (args) => {
+  console.log('Hello', args[0]);
+});
+
+await kernel.handle(process.argv.slice(2));
+```
+
+## ⚡ 原生加速器（Native Accelerators）
+
+Gravito Core 深度利用 Bun 的原生特性與 FFI (Foreign Function Interface) 來處理關鍵任務，實現極限效能：
+
+- **原生 Web 引擎 (Bun 1.39+)**: 專為 Bun 優化的獨立 HTTP 引擎，支援 SIMD 加速路由、中介軟體預編譯與 AOT 卸載。
+- **物件池化 (Object Pooling)**: 透過 `FastContext` 回收機制，達成請求處理過程中的「零 JS 堆分配」，極大化吞吐量。
+- **FFI 加速**: 高效能的二進位序列化 (CBOR) 與雜湊計算。
+- **雜湊（Hashing）**: 使用 Bun 原生指令集加速的 SHA-256 與 HMAC 計算。
+
+## 🛡️ 安全中介軟體遷移
+
+自 v1.7.0 起，所有 HTTP 安全相關的中介軟體已遷移至 `@gravito/photon` 以獲得更好的引擎適配。`@gravito/core` 中的現有匯出已被標記為 `@deprecated`，並將於 v2.0.0 中移除。
+
+**遷移方式：**
+```typescript
+// 之前
+import { cors } from '@gravito/core';
+
+// 之後
+import { cors } from '@gravito/photon/middleware/security';
+```
+
 ## 📖 API 參考
 
 ### `Application` (企業級容器)
@@ -186,6 +279,8 @@ core.hooks.addAction('processError:report', async (ctx) => {
 - **`instance(key, instance)`**: 註冊現有的物件實例。
 - **`has(key)`**: 檢查服務是否已綁定。
 
+容器內建 **循環依賴偵測（Circular Dependency Detection）**，幫助您在開發階段及時發現架構設計問題。
+
 ### `HookManager`
 
 - **`addFilter(hook, callback)`**: 註冊過濾器。

package/dist/Application.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @fileoverview Application - Enterprise Application Container
+ *
+ * A high-level application class that orchestrates the entire framework.
+ * Provides a centralized entry point for enterprise applications with
+ * auto-discovery of providers, config loading, and lifecycle management.
+ *
+ * Phase 4 優化：Provider 預掃描 + 平行載入
+ * - Phase 1：預掃描所有 Provider 文件（語法驗證）
+ * - Phase 2：篩選有效 Provider（跳過無效的）
+ * - Phase 3：平行 import 所有有效 Provider
+ * - Phase 4：註冊到容器
+ *
+ * @module @gravito/core
+ * @since 2.0.0
+ */
+import { ConfigManager } from './ConfigManager';
+import { Container } from './Container';
+import type { EventManager } from './EventManager';
+import type { Logger } from './Logger';
+import { PlanetCore } from './PlanetCore';
+import type { ServiceProvider } from './ServiceProvider';
+/**
+ * Application Config options for the Application class.
+ * @public
+ */
+export interface ApplicationConfig {
+    /**
+     * Base path of the application
+     */
+    basePath: string;
+    /**
+     * Path to the config directory (relative to basePath)
+     * @default 'config'
+     */
+    configPath?: string;
+    /**
+     * Path to the providers directory (relative to basePath)
+     * @default 'src/Providers'
+     */
+    providersPath?: string;
+    /**
+     * Environment (development, production, testing)
+     */
+    env?: 'development' | 'production' | 'testing';
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+    /**
+     * Initial configuration values
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Service providers to register
+     */
+    providers?: ServiceProvider[];
+    /**
+     * Whether to auto-discover providers from providersPath
+     * @default true
+     */
+    autoDiscoverProviders?: boolean;
+}
+/**
+ * Application - Enterprise-grade application container.
+ *
+ * Provides a higher-level abstraction over PlanetCore for building
+ * enterprise applications with convention-over-configuration patterns.
+ *
+ * @example
+ * ```typescript
+ * // Create application
+ * const app = new Application({
+ *   basePath: import.meta.dir,
+ *   env: process.env.NODE_ENV as 'development' | 'production',
+ * });
+ *
+ * // Boot the application
+ * await app.boot();
+ *
+ * // Access core
+ * export default app.core.liftoff();
+ * ```
+ */
+export declare class Application {
+    /**
+     * The underlying PlanetCore instance.
+     */
+    readonly core: PlanetCore;
+    /**
+     * The IoC container.
+     */
+    readonly container: Container;
+    /**
+     * The configuration manager.
+     */
+    readonly config: ConfigManager;
+    /**
+     * The event manager.
+     */
+    readonly events: EventManager;
+    /**
+     * The logger instance.
+     */
+    readonly logger: Logger;
+    /**
+     * Application base path.
+     */
+    readonly basePath: string;
+    /**
+     * Environment mode.
+     */
+    readonly env: 'development' | 'production' | 'testing';
+    /**
+     * Configuration options.
+     */
+    private readonly options;
+    /**
+     * Whether the application has been booted.
+     */
+    private booted;
+    constructor(options: ApplicationConfig);
+    /**
+     * Boot the application and its dependencies.
+     *
+     * This method orchestrates the full application lifecycle:
+     * 1. Configuration: Loads all config files from the config directory.
+     * 2. Discovery: Auto-discovers ServiceProviders from the providers directory.
+     * 3. Registration: Registers all discovered and explicit providers.
+     * 4. Bootstrapping: Triggers the PlanetCore bootstrap sequence.
+     *
+     * @returns Promise that resolves to the application instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * const app = new Application({ basePath: import.meta.dir });
+     * await app.boot();
+     * ```
+     */
+    boot(): Promise<this>;
+    /**
+     * Load configuration files from the config directory.
+     *
+     * @internal
+     */
+    private loadConfiguration;
+    /**
+     * Discover and register providers from the providers directory.
+     *
+     * Phase 4 優化版本：採用 4-Phase 載入策略
+     * - Phase 1：預掃描所有候選 Provider 檔案（語法驗證）
+     * - Phase 2：篩選有效 Provider 檔案（跳過語法錯誤的）
+     * - Phase 3：平行 import 所有有效 Provider（從循序 → 並行）
+     * - Phase 4：逐一註冊到容器
+     *
+     * 效能改進：N 個 Provider 從 O(N * importTime) 降至 O(importTime + overhead)
+     *
+     * @internal
+     */
+    private discoverProviders;
+    /**
+     * Phase 1+2：預掃描 Provider 目錄中的所有候選檔案。
+     *
+     * 使用輕量語法驗證（嘗試讀取 + 基本結構檢查）篩選有效的 Provider 檔案，
+     * 讓語法錯誤在 import 之前被發現，提供更清晰的錯誤訊息。
+     *
+     * 策略：
+     * 1. 使用 Bun.Transpiler 進行 import 掃描（在 Bun 環境下）
+     * 2. Fallback 至基本檔案讀取驗證（在 Node/Deno 環境下）
+     *
+     * @param providersPath - Provider 目錄絕對路徑
+     * @returns 掃描結果陣列（含有效/無效標記）
+     * @internal
+     */
+    private prescribeProviders;
+    /**
+     * Phase 3：平行 import 所有有效的 Provider 檔案。
+     *
+     * 使用 Promise.all() 同時 import 所有通過預掃描的 Provider 檔案，
+     * 從循序載入（O(N)）改善為平行載入（O(1) 理論上），
+     * 實際效能受 I/O、CPU 和 V8 模組解析限制。
+     *
+     * @param validProviders - 通過預掃描的 Provider 掃描結果
+     * @returns 模組載入結果陣列
+     * @internal
+     */
+    private loadProvidersInParallel;
+    /**
+     * Resolve a service instance from the IoC container.
+     *
+     * This is a convenience wrapper around `container.make()`.
+     *
+     * @template T - The expected type of the service.
+     * @param key - The unique identifier or class name of the service.
+     * @returns The resolved service instance.
+     * @throws Error if the service is not bound in the container.
+     *
+     * @example
+     * ```typescript
+     * const db = app.make<Database>('db');
+     * ```
+     */
+    make<T>(key: string): T;
+    /**
+     * Check if a service is bound.
+     *
+     * @param key - The service key
+     * @returns True if bound
+     */
+    has(key: string): boolean;
+    /**
+     * Retrieve a configuration value using dot notation.
+     *
+     * @template T - The expected type of the configuration value.
+     * @param key - The configuration key (e.g., 'app.name', 'database.connections.mysql').
+     * @param defaultValue - Optional value to return if the key is not found.
+     * @returns The configuration value or the default value.
+     *
+     * @example
+     * ```typescript
+     * const port = app.getConfig<number>('app.port', 3000);
+     * ```
+     */
+    getConfig<T>(key: string, defaultValue?: T): T;
+    /**
+     * Resolve an absolute path relative to the application base path.
+     *
+     * @param segments - Path segments to join with the base path.
+     * @returns The absolute path string.
+     *
+     * @example
+     * ```typescript
+     * const storagePath = app.path('storage', 'logs');
+     * ```
+     */
+    path(...segments: string[]): string;
+    /**
+     * Get the config path.
+     *
+     * @param segments - Additional path segments
+     * @returns Absolute path to config directory
+     */
+    configPath(...segments: string[]): string;
+    /**
+     * Check if running in production.
+     */
+    isProduction(): boolean;
+    /**
+     * Check if running in development.
+     */
+    isDevelopment(): boolean;
+    /**
+     * Check if running in testing.
+     */
+    isTesting(): boolean;
+}

package/dist/CommandKernel.d.ts

@@ -0,0 +1,33 @@
+import type { Container } from './Container';
+/**
+ * CommandHandler type for custom CLI commands.
+ */
+export type CommandHandler = (args: string[], container: Container) => Promise<void> | void;
+/**
+ * CommandKernel - Structured CLI Command handling.
+ *
+ * Manages registration and execution of custom CLI commands that can
+ * reuse the application container and providers.
+ *
+ * @example
+ * ```typescript
+ * const kernel = new CommandKernel(container);
+ * kernel.register('greet', (args) => console.log('Hello', args[0]));
+ * await kernel.handle(['greet', 'Universe']);
+ * ```
+ */
+export declare class CommandKernel {
+    private container;
+    private commands;
+    constructor(container: Container);
+    /**
+     * Register a new command handler.
+     */
+    register(name: string, handler: CommandHandler): void;
+    /**
+     * Handle an incoming CLI command.
+     *
+     * @param argv - Array of command line arguments (e.g. process.argv.slice(2))
+     */
+    handle(argv: string[]): Promise<void>;
+}

package/dist/ConfigManager.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Configuration manager (ConfigManager)
+ *
+ * Unifies environment variables and application configuration access.
+ */
+import type { ZodSchema } from 'zod';
+/**
+ * ConfigManager - Central configuration store.
+ * Supports loading from environment variables and initial objects.
+ * @public
+ */
+export declare class ConfigManager {
+    private config;
+    private schema;
+    constructor(initialConfig?: Record<string, unknown>);
+    /**
+     * Load all environment variables from the active runtime.
+     */
+    private loadEnv;
+    /**
+     * Get a configuration value (generic return type supported).
+     * Supports dot notation for deep access (e.g. 'app.name').
+     */
+    get<T = unknown>(key: string, defaultValue?: T): T;
+    /**
+     * Set a configuration value.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Check whether a key exists.
+     */
+    has(key: string): boolean;
+    /**
+     * Define a Zod schema for configuration validation.
+     *
+     * @param schema - Zod schema for validation
+     *
+     * @example
+     * ```typescript
+     * config.defineSchema(z.object({
+     *   DATABASE_URL: z.string().url(),
+     *   PORT: z.number().default(3000),
+     * }))
+     * ```
+     */
+    defineSchema(schema: ZodSchema): void;
+    /**
+     * Validate configuration against the defined schema.
+     *
+     * Should be called during bootstrap to catch configuration errors early.
+     *
+     * @throws Error if validation fails with details about missing/invalid fields
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   config.validate()
+     * } catch (error) {
+     *   console.error('Config validation failed:', error.message)
+     *   process.exit(1)
+     * }
+     * ```
+     */
+    validate(): void;
+}