@esengine/server 4.3.0 → 4.5.0

package/dist/index-B1sr5YAl.d.ts

@@ -0,0 +1,1076 @@
+import { Connection } from '@esengine/rpc';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * @zh HTTP 路由类型定义
+ * @en HTTP router type definitions
+ */
+
+/**
+ * @zh HTTP 请求上下文
+ * @en HTTP request context
+ */
+interface HttpRequest {
+    /**
+     * @zh 原始请求对象
+     * @en Raw request object
+     */
+    raw: IncomingMessage;
+    /**
+     * @zh 请求方法
+     * @en Request method
+     */
+    method: string;
+    /**
+     * @zh 请求路径
+     * @en Request path
+     */
+    path: string;
+    /**
+     * @zh 路由参数（从 URL 路径提取，如 /users/:id）
+     * @en Route parameters (extracted from URL path, e.g., /users/:id)
+     */
+    params: Record<string, string>;
+    /**
+     * @zh 查询参数
+     * @en Query parameters
+     */
+    query: Record<string, string>;
+    /**
+     * @zh 请求头
+     * @en Request headers
+     */
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * @zh 解析后的 JSON 请求体
+     * @en Parsed JSON body
+     */
+    body: unknown;
+    /**
+     * @zh 客户端 IP
+     * @en Client IP
+     */
+    ip: string;
+}
+/**
+ * @zh HTTP 响应工具
+ * @en HTTP response utilities
+ */
+interface HttpResponse {
+    /**
+     * @zh 原始响应对象
+     * @en Raw response object
+     */
+    raw: ServerResponse;
+    /**
+     * @zh 设置状态码
+     * @en Set status code
+     */
+    status(code: number): HttpResponse;
+    /**
+     * @zh 设置响应头
+     * @en Set response header
+     */
+    header(name: string, value: string): HttpResponse;
+    /**
+     * @zh 发送 JSON 响应
+     * @en Send JSON response
+     */
+    json(data: unknown): void;
+    /**
+     * @zh 发送文本响应
+     * @en Send text response
+     */
+    text(data: string): void;
+    /**
+     * @zh 发送错误响应
+     * @en Send error response
+     */
+    error(code: number, message: string): void;
+}
+/**
+ * @zh HTTP 路由处理器
+ * @en HTTP route handler
+ */
+type HttpHandler = (req: HttpRequest, res: HttpResponse) => void | Promise<void>;
+/**
+ * @zh HTTP 中间件函数
+ * @en HTTP middleware function
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware: HttpMiddleware = async (req, res, next) => {
+ *     if (!req.headers.authorization) {
+ *         res.error(401, 'Unauthorized');
+ *         return;
+ *     }
+ *     await next();
+ * };
+ * ```
+ */
+type HttpMiddleware = (req: HttpRequest, res: HttpResponse, next: () => Promise<void>) => void | Promise<void>;
+/**
+ * @zh 带中间件和超时的路由处理器定义
+ * @en Route handler definition with middleware and timeout support
+ */
+interface HttpHandlerDefinition {
+    /**
+     * @zh 处理函数
+     * @en Handler function
+     */
+    handler: HttpHandler;
+    /**
+     * @zh 路由级中间件
+     * @en Route-level middlewares
+     */
+    middlewares?: HttpMiddleware[];
+    /**
+     * @zh 路由级超时时间（毫秒），覆盖全局设置
+     * @en Route-level timeout in milliseconds, overrides global setting
+     */
+    timeout?: number;
+}
+/**
+ * @zh HTTP 路由方法配置（支持简单处理器或完整定义）
+ * @en HTTP route method configuration (supports simple handler or full definition)
+ */
+type HttpMethodHandler = HttpHandler | HttpHandlerDefinition;
+/**
+ * @zh HTTP 路由方法映射
+ * @en HTTP route methods mapping
+ */
+interface HttpRouteMethods {
+    GET?: HttpMethodHandler;
+    POST?: HttpMethodHandler;
+    PUT?: HttpMethodHandler;
+    DELETE?: HttpMethodHandler;
+    PATCH?: HttpMethodHandler;
+    OPTIONS?: HttpMethodHandler;
+}
+/**
+ * @zh HTTP 路由配置
+ * @en HTTP routes configuration
+ *
+ * @example
+ * ```typescript
+ * const routes: HttpRoutes = {
+ *     // 简单处理器
+ *     '/health': (req, res) => res.json({ ok: true }),
+ *
+ *     // 按方法分开
+ *     '/users': {
+ *         GET: (req, res) => res.json([]),
+ *         POST: (req, res) => res.json({ created: true })
+ *     },
+ *
+ *     // 路由参数
+ *     '/users/:id': {
+ *         GET: (req, res) => res.json({ id: req.params.id }),
+ *         DELETE: {
+ *             handler: (req, res) => res.json({ deleted: true }),
+ *             middlewares: [authMiddleware],
+ *             timeout: 5000
+ *         }
+ *     }
+ * };
+ * ```
+ */
+type HttpRoutes = Record<string, HttpMethodHandler | HttpRouteMethods>;
+/**
+ * @zh CORS 配置
+ * @en CORS configuration
+ */
+interface CorsOptions {
+    /**
+     * @zh 允许的来源
+     * @en Allowed origins
+     */
+    origin?: string | string[] | boolean;
+    /**
+     * @zh 允许的方法
+     * @en Allowed methods
+     */
+    methods?: string[];
+    /**
+     * @zh 允许的请求头
+     * @en Allowed headers
+     */
+    allowedHeaders?: string[];
+    /**
+     * @zh 是否允许携带凭证
+     * @en Allow credentials
+     */
+    credentials?: boolean;
+    /**
+     * @zh 预检请求缓存时间（秒）
+     * @en Preflight cache max age
+     */
+    maxAge?: number;
+}
+/**
+ * @zh HTTP 路由器选项
+ * @en HTTP router options
+ */
+interface HttpRouterOptions {
+    /**
+     * @zh CORS 配置
+     * @en CORS configuration
+     */
+    cors?: CorsOptions | boolean;
+    /**
+     * @zh 全局请求超时时间（毫秒）
+     * @en Global request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * @zh 全局中间件
+     * @en Global middlewares
+     */
+    middlewares?: HttpMiddleware[];
+}
+
+/**
+ * @zh 分布式适配器接口
+ * @en Distributed adapter interface
+ *
+ * @zh 定义分布式房间系统的存储和通信层抽象
+ * @en Defines the storage and communication layer abstraction for distributed room system
+ */
+
+/**
+ * @zh 分布式适配器接口
+ * @en Distributed adapter interface
+ *
+ * @zh 所有分布式后端（Redis、消息队列等）都需要实现此接口
+ * @en All distributed backends (Redis, message queue, etc.) must implement this interface
+ */
+interface IDistributedAdapter {
+    /**
+     * @zh 连接到分布式后端
+     * @en Connect to distributed backend
+     */
+    connect(): Promise<void>;
+    /**
+     * @zh 断开连接
+     * @en Disconnect from backend
+     */
+    disconnect(): Promise<void>;
+    /**
+     * @zh 检查是否已连接
+     * @en Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * @zh 注册服务器
+     * @en Register server
+     *
+     * @param server - 服务器注册信息 | Server registration info
+     */
+    registerServer(server: ServerRegistration): Promise<void>;
+    /**
+     * @zh 注销服务器
+     * @en Unregister server
+     *
+     * @param serverId - 服务器 ID | Server ID
+     */
+    unregisterServer(serverId: string): Promise<void>;
+    /**
+     * @zh 更新服务器心跳
+     * @en Update server heartbeat
+     *
+     * @param serverId - 服务器 ID | Server ID
+     */
+    heartbeat(serverId: string): Promise<void>;
+    /**
+     * @zh 获取所有在线服务器
+     * @en Get all online servers
+     */
+    getServers(): Promise<ServerRegistration[]>;
+    /**
+     * @zh 获取指定服务器
+     * @en Get specific server
+     *
+     * @param serverId - 服务器 ID | Server ID
+     */
+    getServer(serverId: string): Promise<ServerRegistration | null>;
+    /**
+     * @zh 更新服务器信息
+     * @en Update server info
+     *
+     * @param serverId - 服务器 ID | Server ID
+     * @param updates - 更新内容 | Updates
+     */
+    updateServer(serverId: string, updates: Partial<ServerRegistration>): Promise<void>;
+    /**
+     * @zh 注册房间
+     * @en Register room
+     *
+     * @param room - 房间注册信息 | Room registration info
+     */
+    registerRoom(room: RoomRegistration): Promise<void>;
+    /**
+     * @zh 注销房间
+     * @en Unregister room
+     *
+     * @param roomId - 房间 ID | Room ID
+     */
+    unregisterRoom(roomId: string): Promise<void>;
+    /**
+     * @zh 更新房间信息
+     * @en Update room info
+     *
+     * @param roomId - 房间 ID | Room ID
+     * @param updates - 更新内容 | Updates
+     */
+    updateRoom(roomId: string, updates: Partial<RoomRegistration>): Promise<void>;
+    /**
+     * @zh 获取房间信息
+     * @en Get room info
+     *
+     * @param roomId - 房间 ID | Room ID
+     */
+    getRoom(roomId: string): Promise<RoomRegistration | null>;
+    /**
+     * @zh 查询房间列表
+     * @en Query room list
+     *
+     * @param query - 查询条件 | Query criteria
+     */
+    queryRooms(query: RoomQuery): Promise<RoomRegistration[]>;
+    /**
+     * @zh 获取指定类型的可用房间（用于 joinOrCreate）
+     * @en Get available room of type (for joinOrCreate)
+     *
+     * @param roomType - 房间类型 | Room type
+     */
+    findAvailableRoom(roomType: string): Promise<RoomRegistration | null>;
+    /**
+     * @zh 获取服务器的所有房间
+     * @en Get all rooms of a server
+     *
+     * @param serverId - 服务器 ID | Server ID
+     */
+    getRoomsByServer(serverId: string): Promise<RoomRegistration[]>;
+    /**
+     * @zh 保存房间状态快照
+     * @en Save room state snapshot
+     *
+     * @param snapshot - 状态快照 | State snapshot
+     */
+    saveSnapshot(snapshot: RoomSnapshot): Promise<void>;
+    /**
+     * @zh 加载房间状态快照
+     * @en Load room state snapshot
+     *
+     * @param roomId - 房间 ID | Room ID
+     */
+    loadSnapshot(roomId: string): Promise<RoomSnapshot | null>;
+    /**
+     * @zh 删除房间状态
+     * @en Delete room state
+     *
+     * @param roomId - 房间 ID | Room ID
+     */
+    deleteSnapshot(roomId: string): Promise<void>;
+    /**
+     * @zh 发布事件
+     * @en Publish event
+     *
+     * @param event - 分布式事件 | Distributed event
+     */
+    publish(event: DistributedEvent): Promise<void>;
+    /**
+     * @zh 订阅事件
+     * @en Subscribe to events
+     *
+     * @param pattern - 事件类型模式（支持 '*' 通配符） | Event type pattern (supports '*' wildcard)
+     * @param handler - 事件处理器 | Event handler
+     * @returns 取消订阅函数 | Unsubscribe function
+     */
+    subscribe(pattern: DistributedEventType | '*', handler: DistributedEventHandler): Promise<Unsubscribe>;
+    /**
+     * @zh 向特定房间发送消息（跨服务器）
+     * @en Send message to specific room (cross-server)
+     *
+     * @param roomId - 房间 ID | Room ID
+     * @param messageType - 消息类型 | Message type
+     * @param data - 消息数据 | Message data
+     * @param playerId - 发送者玩家 ID（可选） | Sender player ID (optional)
+     */
+    sendToRoom(roomId: string, messageType: string, data: unknown, playerId?: string): Promise<void>;
+    /**
+     * @zh 获取分布式锁
+     * @en Acquire distributed lock
+     *
+     * @param key - 锁的键名 | Lock key
+     * @param ttlMs - 锁的生存时间（毫秒） | Lock TTL (ms)
+     * @returns 是否成功获取锁 | Whether lock was acquired
+     */
+    acquireLock(key: string, ttlMs: number): Promise<boolean>;
+    /**
+     * @zh 释放分布式锁
+     * @en Release distributed lock
+     *
+     * @param key - 锁的键名 | Lock key
+     */
+    releaseLock(key: string): Promise<void>;
+    /**
+     * @zh 扩展锁的生存时间
+     * @en Extend lock TTL
+     *
+     * @param key - 锁的键名 | Lock key
+     * @param ttlMs - 新的生存时间（毫秒） | New TTL (ms)
+     * @returns 是否成功扩展 | Whether extension was successful
+     */
+    extendLock(key: string, ttlMs: number): Promise<boolean>;
+}
+
+/**
+ * @zh 分布式房间支持类型定义
+ * @en Distributed room support type definitions
+ */
+/**
+ * @zh 服务器状态
+ * @en Server status
+ */
+type ServerStatus = 'online' | 'draining' | 'offline';
+/**
+ * @zh 服务器注册信息
+ * @en Server registration info
+ */
+interface ServerRegistration {
+    /**
+     * @zh 服务器唯一标识
+     * @en Server unique identifier
+     */
+    serverId: string;
+    /**
+     * @zh 服务器地址（供客户端连接）
+     * @en Server address (for client connection)
+     */
+    address: string;
+    /**
+     * @zh 服务器端口
+     * @en Server port
+     */
+    port: number;
+    /**
+     * @zh 当前房间数量
+     * @en Current room count
+     */
+    roomCount: number;
+    /**
+     * @zh 当前玩家数量
+     * @en Current player count
+     */
+    playerCount: number;
+    /**
+     * @zh 服务器容量（最大房间数）
+     * @en Server capacity (max rooms)
+     */
+    capacity: number;
+    /**
+     * @zh 服务器状态
+     * @en Server status
+     */
+    status: ServerStatus;
+    /**
+     * @zh 最后心跳时间戳
+     * @en Last heartbeat timestamp
+     */
+    lastHeartbeat: number;
+    /**
+     * @zh 服务器元数据
+     * @en Server metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * @zh 房间注册信息
+ * @en Room registration info
+ */
+interface RoomRegistration {
+    /**
+     * @zh 房间唯一标识
+     * @en Room unique identifier
+     */
+    roomId: string;
+    /**
+     * @zh 房间类型名称
+     * @en Room type name
+     */
+    roomType: string;
+    /**
+     * @zh 所在服务器 ID
+     * @en Host server ID
+     */
+    serverId: string;
+    /**
+     * @zh 服务器地址
+     * @en Server address
+     */
+    serverAddress: string;
+    /**
+     * @zh 当前玩家数量
+     * @en Current player count
+     */
+    playerCount: number;
+    /**
+     * @zh 最大玩家数量
+     * @en Max player count
+     */
+    maxPlayers: number;
+    /**
+     * @zh 房间是否已锁定
+     * @en Whether room is locked
+     */
+    isLocked: boolean;
+    /**
+     * @zh 房间元数据（标签、自定义属性等）
+     * @en Room metadata (tags, custom properties, etc.)
+     */
+    metadata: Record<string, unknown>;
+    /**
+     * @zh 创建时间戳
+     * @en Creation timestamp
+     */
+    createdAt: number;
+    /**
+     * @zh 更新时间戳
+     * @en Update timestamp
+     */
+    updatedAt: number;
+}
+/**
+ * @zh 房间查询条件
+ * @en Room query criteria
+ */
+interface RoomQuery {
+    /**
+     * @zh 房间类型
+     * @en Room type
+     */
+    roomType?: string;
+    /**
+     * @zh 服务器 ID（查询特定服务器上的房间）
+     * @en Server ID (query rooms on specific server)
+     */
+    serverId?: string;
+    /**
+     * @zh 是否有空位
+     * @en Whether has available space
+     */
+    hasSpace?: boolean;
+    /**
+     * @zh 是否未锁定
+     * @en Whether not locked
+     */
+    notLocked?: boolean;
+    /**
+     * @zh 元数据过滤
+     * @en Metadata filter
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * @zh 返回数量限制
+     * @en Result limit
+     */
+    limit?: number;
+    /**
+     * @zh 偏移量（分页）
+     * @en Offset (pagination)
+     */
+    offset?: number;
+}
+/**
+ * @zh 玩家快照
+ * @en Player snapshot
+ */
+interface PlayerSnapshot {
+    /**
+     * @zh 玩家 ID
+     * @en Player ID
+     */
+    id: string;
+    /**
+     * @zh 玩家数据
+     * @en Player data
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * @zh 房间状态快照
+ * @en Room state snapshot
+ */
+interface RoomSnapshot<TState = unknown> {
+    /**
+     * @zh 房间 ID
+     * @en Room ID
+     */
+    roomId: string;
+    /**
+     * @zh 房间类型
+     * @en Room type
+     */
+    roomType: string;
+    /**
+     * @zh 房间状态
+     * @en Room state
+     */
+    state: TState;
+    /**
+     * @zh 玩家列表
+     * @en Player list
+     */
+    players: PlayerSnapshot[];
+    /**
+     * @zh 快照版本号
+     * @en Snapshot version
+     */
+    version: number;
+    /**
+     * @zh 快照时间戳
+     * @en Snapshot timestamp
+     */
+    timestamp: number;
+}
+/**
+ * @zh 分布式事件类型
+ * @en Distributed event types
+ */
+type DistributedEventType = 'room:created' | 'room:disposed' | 'room:updated' | 'room:locked' | 'room:unlocked' | 'room:message' | 'room:migrated' | 'player:joined' | 'player:left' | 'server:online' | 'server:offline' | 'server:draining';
+/**
+ * @zh 分布式事件
+ * @en Distributed event
+ */
+interface DistributedEvent<T = unknown> {
+    /**
+     * @zh 事件类型
+     * @en Event type
+     */
+    type: DistributedEventType;
+    /**
+     * @zh 发送方服务器 ID
+     * @en Sender server ID
+     */
+    serverId: string;
+    /**
+     * @zh 相关房间 ID（可选）
+     * @en Related room ID (optional)
+     */
+    roomId?: string;
+    /**
+     * @zh 事件载荷
+     * @en Event payload
+     */
+    payload: T;
+    /**
+     * @zh 事件时间戳
+     * @en Event timestamp
+     */
+    timestamp: number;
+}
+/**
+ * @zh 事件处理器
+ * @en Event handler
+ */
+type DistributedEventHandler<T = unknown> = (event: DistributedEvent<T>) => void;
+/**
+ * @zh 取消订阅函数
+ * @en Unsubscribe function
+ */
+type Unsubscribe = () => void;
+/**
+ * @zh 分布式房间管理器配置
+ * @en Distributed room manager configuration
+ */
+interface DistributedRoomManagerConfig {
+    /**
+     * @zh 服务器 ID（唯一标识）
+     * @en Server ID (unique identifier)
+     */
+    serverId: string;
+    /**
+     * @zh 服务器公开地址（供客户端连接）
+     * @en Server public address (for client connection)
+     */
+    serverAddress: string;
+    /**
+     * @zh 服务器端口
+     * @en Server port
+     */
+    serverPort: number;
+    /**
+     * @zh 心跳间隔（毫秒）
+     * @en Heartbeat interval (ms)
+     * @default 5000
+     */
+    heartbeatInterval?: number;
+    /**
+     * @zh 状态快照间隔（毫秒），0 = 禁用
+     * @en State snapshot interval (ms), 0 = disabled
+     * @default 30000
+     */
+    snapshotInterval?: number;
+    /**
+     * @zh 房间迁移超时（毫秒）
+     * @en Room migration timeout (ms)
+     * @default 10000
+     */
+    migrationTimeout?: number;
+    /**
+     * @zh 是否启用自动故障转移
+     * @en Whether to enable automatic failover
+     * @default true
+     */
+    enableFailover?: boolean;
+    /**
+     * @zh 服务器容量（最大房间数）
+     * @en Server capacity (max rooms)
+     * @default 100
+     */
+    capacity?: number;
+    /**
+     * @zh 服务器元数据
+     * @en Server metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * @zh 服务器分布式配置（用于 createServer）
+ * @en Server distributed configuration (for createServer)
+ */
+interface DistributedConfig extends Omit<DistributedRoomManagerConfig, 'serverPort'> {
+    /**
+     * @zh 是否启用分布式模式
+     * @en Whether to enable distributed mode
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * @zh 分布式适配器（可选，默认使用 MemoryAdapter）
+     * @en Distributed adapter (optional, defaults to MemoryAdapter)
+     */
+    adapter?: IDistributedAdapter;
+    /**
+     * @zh 服务器端口（可选，默认使用服务器配置的端口）
+     * @en Server port (optional, defaults to server config port)
+     */
+    serverPort?: number;
+}
+/**
+ * @zh 路由结果类型
+ * @en Routing result type
+ */
+type RoutingResultType = 'local' | 'redirect' | 'create' | 'unavailable';
+/**
+ * @zh 路由结果
+ * @en Routing result
+ */
+interface RoutingResult {
+    /**
+     * @zh 路由类型
+     * @en Routing type
+     */
+    type: RoutingResultType;
+    /**
+     * @zh 目标服务器地址（redirect 时）
+     * @en Target server address (for redirect)
+     */
+    serverAddress?: string;
+    /**
+     * @zh 目标房间 ID
+     * @en Target room ID
+     */
+    roomId?: string;
+    /**
+     * @zh 错误信息（unavailable 时）
+     * @en Error message (for unavailable)
+     */
+    reason?: string;
+}
+/**
+ * @zh 路由请求
+ * @en Routing request
+ */
+interface RoutingRequest {
+    /**
+     * @zh 玩家 ID
+     * @en Player ID
+     */
+    playerId: string;
+    /**
+     * @zh 房间类型（joinOrCreate 时）
+     * @en Room type (for joinOrCreate)
+     */
+    roomType?: string;
+    /**
+     * @zh 房间 ID（joinById 时）
+     * @en Room ID (for joinById)
+     */
+    roomId?: string;
+    /**
+     * @zh 首选服务器 ID
+     * @en Preferred server ID
+     */
+    preferredServerId?: string;
+    /**
+     * @zh 房间查询条件
+     * @en Room query criteria
+     */
+    query?: RoomQuery;
+}
+
+/**
+ * @zh ESEngine Server 类型定义
+ * @en ESEngine Server type definitions
+ */
+
+/**
+ * @zh 服务器配置
+ * @en Server configuration
+ */
+interface ServerConfig {
+    /**
+     * @zh 监听端口
+     * @en Listen port
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * @zh API 目录路径
+     * @en API directory path
+     * @default 'src/api'
+     */
+    apiDir?: string;
+    /**
+     * @zh 消息处理器目录路径
+     * @en Message handlers directory path
+     * @default 'src/msg'
+     */
+    msgDir?: string;
+    /**
+     * @zh HTTP 路由目录路径
+     * @en HTTP routes directory path
+     * @default 'src/http'
+     *
+     * @zh 文件命名规则：
+     * - `login.ts` → POST /api/login
+     * - `users/[id].ts` → /api/users/:id
+     * - `health.ts` (method: 'GET') → GET /api/health
+     * @en File naming convention:
+     * - `login.ts` → POST /api/login
+     * - `users/[id].ts` → /api/users/:id
+     * - `health.ts` (method: 'GET') → GET /api/health
+     */
+    httpDir?: string;
+    /**
+     * @zh HTTP 路由前缀
+     * @en HTTP routes prefix
+     * @default '/api'
+     */
+    httpPrefix?: string;
+    /**
+     * @zh 游戏 Tick 速率 (每秒)
+     * @en Game tick rate (per second)
+     * @default 20
+     */
+    tickRate?: number;
+    /**
+     * @zh HTTP 路由配置（内联定义，与 httpDir 文件路由合并）
+     * @en HTTP routes configuration (inline definition, merged with httpDir file routes)
+     */
+    http?: HttpRoutes;
+    /**
+     * @zh CORS 配置
+     * @en CORS configuration
+     * @default true
+     */
+    cors?: CorsOptions | boolean;
+    /**
+     * @zh 服务器启动回调
+     * @en Server start callback
+     */
+    onStart?: (port: number) => void;
+    /**
+     * @zh 连接建立回调
+     * @en Connection established callback
+     */
+    onConnect?: (conn: ServerConnection) => void | Promise<void>;
+    /**
+     * @zh 连接断开回调
+     * @en Connection closed callback
+     */
+    onDisconnect?: (conn: ServerConnection) => void | Promise<void>;
+    /**
+     * @zh 分布式模式配置
+     * @en Distributed mode configuration
+     *
+     * @example
+     * ```typescript
+     * const server = await createServer({
+     *     port: 3000,
+     *     distributed: {
+     *         enabled: true,
+     *         adapter: new RedisAdapter({ factory: () => new Redis() }),
+     *         serverId: 'server-1',
+     *         serverAddress: 'ws://192.168.1.100',
+     *         serverPort: 3000
+     *     }
+     * });
+     * ```
+     */
+    distributed?: DistributedConfig;
+}
+/**
+ * @zh 服务器连接（扩展 RPC Connection）
+ * @en Server connection (extends RPC Connection)
+ */
+interface ServerConnection<TData = Record<string, unknown>> extends Connection<TData> {
+    /**
+     * @zh 连接唯一标识（继承自 Connection）
+     * @en Connection unique identifier (inherited from Connection)
+     */
+    readonly id: string;
+    /**
+     * @zh 用户自定义数据
+     * @en User-defined data
+     */
+    data: TData;
+}
+/**
+ * @zh API 处理器上下文
+ * @en API handler context
+ */
+interface ApiContext<TData = Record<string, unknown>> {
+    /**
+     * @zh 当前连接
+     * @en Current connection
+     */
+    conn: ServerConnection<TData>;
+    /**
+     * @zh 服务器实例
+     * @en Server instance
+     */
+    server: GameServer;
+}
+/**
+ * @zh API 定义选项
+ * @en API definition options
+ */
+interface ApiDefinition<TReq = unknown, TRes = unknown, TData = Record<string, unknown>> {
+    /**
+     * @zh API 处理函数
+     * @en API handler function
+     */
+    handler: (req: TReq, ctx: ApiContext<TData>) => TRes | Promise<TRes>;
+}
+/**
+ * @zh 消息处理器上下文
+ * @en Message handler context
+ */
+interface MsgContext<TData = Record<string, unknown>> {
+    /**
+     * @zh 当前连接
+     * @en Current connection
+     */
+    conn: ServerConnection<TData>;
+    /**
+     * @zh 服务器实例
+     * @en Server instance
+     */
+    server: GameServer;
+}
+/**
+ * @zh 消息定义选项
+ * @en Message definition options
+ */
+interface MsgDefinition<TMsg = unknown, TData = Record<string, unknown>> {
+    /**
+     * @zh 消息处理函数
+     * @en Message handler function
+     */
+    handler: (msg: TMsg, ctx: MsgContext<TData>) => void | Promise<void>;
+}
+/**
+ * @zh 游戏服务器接口
+ * @en Game server interface
+ */
+interface GameServer {
+    /**
+     * @zh 启动服务器
+     * @en Start server
+     */
+    start(): Promise<void>;
+    /**
+     * @zh 停止服务器
+     * @en Stop server
+     */
+    stop(): Promise<void>;
+    /**
+     * @zh 广播消息
+     * @en Broadcast message
+     */
+    broadcast<T>(name: string, data: T): void;
+    /**
+     * @zh 发送消息给指定连接
+     * @en Send message to specific connection
+     */
+    send<T>(conn: ServerConnection, name: string, data: T): void;
+    /**
+     * @zh 获取所有连接
+     * @en Get all connections
+     */
+    readonly connections: ReadonlyArray<ServerConnection>;
+    /**
+     * @zh 当前 Tick
+     * @en Current tick
+     */
+    readonly tick: number;
+    /**
+     * @zh 注册房间类型
+     * @en Define room type
+     */
+    define(name: string, roomClass: new () => unknown): void;
+}
+/**
+ * @zh HTTP 请求方法
+ * @en HTTP request method
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * @zh HTTP 定义选项
+ * @en HTTP definition options
+ *
+ * @example
+ * ```typescript
+ * // src/http/login.ts
+ * import { defineHttp } from '@esengine/server'
+ *
+ * export default defineHttp({
+ *     method: 'POST',
+ *     handler: async (req, res) => {
+ *         const { username, password } = req.body
+ *         // ... authentication logic
+ *         res.json({ token: '...', userId: '...' })
+ *     }
+ * })
+ * ```
+ */
+interface HttpDefinition<TBody = unknown> {
+    /**
+     * @zh 请求方法
+     * @en Request method
+     * @default 'POST'
+     */
+    method?: HttpMethod;
+    /**
+     * @zh 处理函数
+     * @en Handler function
+     */
+    handler: (req: HttpRequest & {
+        body: TBody;
+    }, res: HttpResponse) => void | Promise<void>;
+}
+
+export type { ApiContext as A, CorsOptions as C, DistributedEvent as D, GameServer as G, HttpDefinition as H, IDistributedAdapter as I, MsgContext as M, RoomRegistration as R, ServerConnection as S, Unsubscribe as U, ServerConfig as a, ApiDefinition as b, MsgDefinition as c, HttpRoutes as d, HttpRouterOptions as e, ServerRegistration as f, RoomQuery as g, RoomSnapshot as h, DistributedEventType as i, DistributedEventHandler as j, DistributedRoomManagerConfig as k, RoutingRequest as l, RoutingResult as m, HttpMethod as n, HttpRequest as o, HttpResponse as p, HttpHandler as q, ServerStatus as r, DistributedConfig as s };