koatty_serve

v3.0.0

Published

a month ago

Provide http1/2/3, websocket, gRPC server for Koatty.

0High
0Medium
0Low

richenlin

IOC koatty thinkkoa

koatty_serve

高性能单协议服务器框架，为Koatty提供统一的HTTP、HTTPS、HTTP/2、HTTP/3、WebSocket、gRPC服务支持。采用现代化架构设计，具备企业级的配置管理、连接池、优雅关闭、健康检查和性能监控功能。

🚀 核心特性

🏗️ 统一架构设计

✅ 模板方法模式: 基于BaseServer的统一服务器架构
✅ 单协议设计: 每个服务器实例专注于单一协议，职责清晰
✅ 多种协议支持: HTTP、HTTPS、HTTP/2、HTTP/3 (QUIC)、WebSocket、WSS、gRPC
✅ 配置统一管理: ConfigHelper提供一致的配置接口
✅ 连接池系统: 高性能的协议专用连接池管理

🔧 统一配置管理

🔄 统一配置接口: 所有协议使用相同的配置模式
🔥 配置热重载: 智能检测配置变更，自动决定重启策略
📋 类型安全: 完整的TypeScript类型定义和验证
🎛️ 默认值管理: 智能的默认配置和环境适配

🏊‍♂️ 高性能连接池

⚡ 协议专用池: 每种协议优化的连接池实现
📊 智能监控: 实时连接统计和健康检查
🔄 自动清理: 过期连接自动清理和资源回收
🎯 负载均衡: 智能连接分配和负载管理

🛡️ 运维监控

🔄 优雅关闭: 五步式优雅关闭流程
🏥 健康检查: 多层次健康状态监控
📊 性能监控: 实时指标收集和历史数据
📝 结构化日志: 统一的日志系统和链路追踪

📦 安装

npm install koatty_serve
# 或者
yarn add koatty_serve
# 或者
pnpm add koatty_serve

🎯 快速开始

使用 NewServe 创建服务器（推荐）

import { NewServe } from "koatty_serve";
import { KoattyApplication } from "koatty_core";

const app = new KoattyApplication();

// 创建单协议 HTTP 服务器
const server = NewServe(app, {
  hostname: '127.0.0.1',
  port: 3000,
  protocol: 'http'  // 单个协议
});

server.Start(() => {
  console.log('HTTP服务器已启动: http://127.0.0.1:3000');
});

运行多个协议服务

如果需要同时运行多个协议，创建多个服务器实例：

import { NewServe } from "koatty_serve";

const app = new KoattyApplication();

// HTTP 服务器
const httpServer = NewServe(app, {
  hostname: '127.0.0.1',
  port: 3000,
  protocol: 'http'
});

// gRPC 服务器
const grpcServer = NewServe(app, {
  hostname: '127.0.0.1',
  port: 50051,
  protocol: 'grpc'
});

// WebSocket 服务器
const wsServer = NewServe(app, {
  hostname: '127.0.0.1',
  port: 8080,
  protocol: 'ws'
});

// 启动所有服务器
httpServer.Start(() => console.log('HTTP 服务器已启动'));
grpcServer.Start(() => console.log('gRPC 服务器已启动'));
wsServer.Start(() => console.log('WebSocket 服务器已启动'));

使用协议专用服务器类（高级用法）

import { HttpServer } from "koatty_serve";
import { ConfigHelper } from "koatty_serve/config";

const app = new KoattyApplication();

// 使用ConfigHelper创建配置
const config = ConfigHelper.createHttpConfig({
  hostname: '127.0.0.1',
  port: 3000,
  connectionPool: {
    maxConnections: 1000,
    connectionTimeout: 30000
  }
});

// 直接创建HTTP服务器
const server = new HttpServer(app, config);

server.Start(() => {
  console.log('HTTP服务器已启动: http://127.0.0.1:3000');
});

HTTPS服务器

import { HttpsServer } from "koatty_serve";
import { ConfigHelper } from "koatty_serve/config";

const httpsConfig = ConfigHelper.createHttpsConfig({
  hostname: '0.0.0.0',
  port: 443,
  ssl: {
    mode: 'auto',
    key: './ssl/server.key',
    cert: './ssl/server.crt'
  },
  connectionPool: {
    maxConnections: 2000,
    keepAliveTimeout: 65000
  }
});

const httpsServer = new HttpsServer(app, httpsConfig);
httpsServer.Start(() => {
  console.log('HTTPS服务器已启动: https://0.0.0.0:443');
});

gRPC服务器

import { GrpcServer } from "koatty_serve";
import { ConfigHelper } from "koatty_serve/config";

const grpcConfig = ConfigHelper.createGrpcConfig({
  hostname: '127.0.0.1',
  port: 50051,
  ssl: {
    enabled: true,
    keyFile: './certs/server.key',
    certFile: './certs/server.crt',
    clientCertRequired: false
  },
  connectionPool: {
    maxConnections: 500,
    protocolSpecific: {
      keepAliveTime: 30000,
      maxReceiveMessageLength: 4 * 1024 * 1024,
      maxSendMessageLength: 4 * 1024 * 1024
    }
  }
});

const grpcServer = new GrpcServer(app, grpcConfig);
grpcServer.Start(() => {
  console.log('gRPC服务器已启动: 127.0.0.1:50051');
});

HTTP/3服务器（基于QUIC）

import { Http3Server } from "koatty_serve";
import { ConfigHelper } from "koatty_serve/config";

const http3Config = ConfigHelper.createHttp3Config({
  hostname: '0.0.0.0',
  port: 443,
  ssl: {
    mode: 'auto',
    key: './ssl/server.key',
    cert: './ssl/server.crt',
    alpnProtocols: ['h3'],  // HTTP/3 ALPN
  },
  quic: {
    maxIdleTimeout: 30000,
    maxUdpPayloadSize: 65527,
    initialMaxStreamsBidi: 100,
    initialMaxStreamsUni: 100,
  },
  http3: {
    maxHeaderListSize: 16384,
    qpackMaxTableCapacity: 4096,
  },
  connectionPool: {
    maxConnections: 2000,
    keepAliveTimeout: 65000
  }
});

const http3Server = new Http3Server(app, http3Config);
http3Server.Start(() => {
  console.log('HTTP/3服务器已启动: https://0.0.0.0:443 (QUIC)');
});

注意: HTTP/3 基于 QUIC 协议（UDP），使用 @matrixai/quic 作为 QUIC 传输层（基于 Cloudflare QuICHE），并实现了完整的 HTTP/3 帧解析和 QPACK 头部压缩（符合 RFC 9114 和 RFC 9204 规范）。

WebSocket服务器

import { WsServer } from "koatty_serve";
import { ConfigHelper } from "koatty_serve/config";

const wsConfig = ConfigHelper.createWebSocketConfig({
  hostname: '127.0.0.1',
  port: 8080,
  ssl: {
    enabled: false
  },
  connectionPool: {
    maxConnections: 5000,
    connectionTimeout: 60000,
    protocolSpecific: {
      pingInterval: 30000,
      pongTimeout: 5000,
      heartbeatInterval: 60000
    }
  }
});

const wsServer = new WsServer(app, wsConfig);
wsServer.Start(() => {
  console.log('WebSocket服务器已启动: ws://127.0.0.1:8080');
});

🏗️ 架构设计

BaseServer模板方法模式

所有协议服务器都继承自BaseServer抽象类，实现统一的生命周期管理：

abstract class BaseServer<T extends BaseServerOptions> {
  // 模板方法：定义服务器初始化流程
  protected initializeServer(): void {
    this.initializeConnectionPool();
    this.createProtocolServer();
    this.configureServerOptions();
    this.performProtocolSpecificInitialization();
  }
  
  // 模板方法：定义配置更新流程
  async updateConfig(newConfig: Partial<T>): Promise<void> {
    const analysis = this.analyzeConfigChanges(changedKeys, oldConfig, newConfig);
    if (analysis.requiresRestart) {
      await this.gracefulRestart(newConfig);
    } else {
      this.applyConfigChanges(changedKeys, newConfig);
    }
  }
  
  // 模板方法：定义优雅关闭流程
  async gracefulShutdown(options?: ShutdownOptions): Promise<void> {
    // 五步式关闭流程
    await this.stopAcceptingNewConnections(traceId);
    await this.waitDrainDelay(options.drainDelay, traceId);
    await this.waitForConnectionCompletion(timeout, traceId);
    await this.forceCloseRemainingConnections(traceId);
    this.stopMonitoringAndCleanup(traceId);
  }
  
  // 抽象方法：子类必须实现
  protected abstract initializeConnectionPool(): void;
  protected abstract createProtocolServer(): void;
  protected abstract configureServerOptions(): void;
}

统一配置管理

ConfigHelper提供了统一的配置创建接口：

export class ConfigHelper {
  // HTTP配置
  static createHttpConfig(options: HttpConfigOptions): HttpServerOptions;
  
  // HTTPS配置  
  static createHttpsConfig(options: HttpsConfigOptions): HttpsServerOptions;
  
  // HTTP/2配置
  static createHttp2Config(options: Http2ConfigOptions): Http2ServerOptions;
  
  // gRPC配置
  static createGrpcConfig(options: GrpcConfigOptions): GrpcServerOptions;
  
  // WebSocket配置
  static createWebSocketConfig(options: WebSocketConfigOptions): WebSocketServerOptions;
}

连接池架构

每种协议都有专门优化的连接池管理器：

// HTTP连接池
class HttpConnectionPoolManager extends ConnectionPoolManager<Socket> {
  // HTTP特定的连接管理
}

// gRPC连接池  
class GrpcConnectionPoolManager extends ConnectionPoolManager<GrpcConnection> {
  // gRPC特定的连接管理
  async addGrpcConnection(peer: string, metadata: any): Promise<boolean>;
}

// WebSocket连接池
class WebSocketConnectionPoolManager extends ConnectionPoolManager<WebSocket> {
  // WebSocket特定的连接管理
  async addWebSocketConnection(ws: WebSocket, request: IncomingMessage): Promise<boolean>;
}

🔧 配置管理

配置类型系统

// 监听选项（用于传递配置）
interface ListeningOptions {
  hostname: string;
  port: number;
  protocol: string;
  trace?: boolean;
  ext?: {                        // 扩展配置字段
    ssl?: BaseSSLConfig;         // SSL 配置
    protoFile?: string;          // gRPC proto 文件
    schemaFile?: string;         // GraphQL schema 文件
    [key: string]: any;          // 其他扩展配置
  };
  connectionPool?: ConnectionPoolConfig;
}

// 基础服务器选项（不包含 ext）
interface BaseServerOptions {
  hostname: string;
  port: number;
  protocol: string;
  trace?: boolean;
  connectionPool?: ConnectionPoolConfig;
}

// SSL配置层次
interface BaseSSLConfig {
  enabled?: boolean;
  key?: string;                  // 私钥路径或内容
  cert?: string;                 // 证书路径或内容
  ca?: string;                   // CA证书路径或内容
  passphrase?: string;           // 私钥密码
  ciphers?: string;              // 加密套件
  honorCipherOrder?: boolean;    // 遵循加密套件顺序
  secureProtocol?: string;       // SSL/TLS 协议版本
}

// gRPC 和 WebSocket 使用的简单 SSL 配置
interface SSLConfig extends BaseSSLConfig {
  clientCertRequired?: boolean;  // 是否需要客户端证书
}

// HTTPS 使用的高级 SSL 配置
interface SSL1Config extends BaseSSLConfig {
  mode: 'auto' | 'manual' | 'mutual_tls';  // SSL 模式
  requestCert?: boolean;                    // 请求客户端证书
  rejectUnauthorized?: boolean;             // 拒绝未授权连接
  // 扩展配置选项
  handshakeTimeout?: number;                // TLS 握手超时
  sessionTimeout?: number;                  // TLS 会话超时
  SNICallback?: Function;                   // SNI 回调
  sessionIdContext?: string;                // 会话 ID 上下文
  ticketKeys?: Buffer;                      // TLS 会话票据密钥
  ALPNProtocols?: string[];                 // ALPN 协议
}

// HTTP/2 使用的 SSL 配置（支持 HTTP/1.1 降级）
interface SSL2Config extends SSL1Config {
  allowHTTP1?: boolean;                     // 允许 HTTP/1.1 回退
}

// HTTP/3 使用的 SSL 配置（基于 QUIC，必须使用 TLS 1.3）
interface SSL3Config extends BaseSSLConfig {
  mode: 'auto' | 'manual' | 'mutual_tls';
  requestCert?: boolean;
  rejectUnauthorized?: boolean;
  // QUIC 特定配置
  alpnProtocols?: string[];                 // ALPN 协议（默认: ['h3']）
  maxIdleTimeout?: number;                  // 最大空闲超时
  initialMaxStreamsBidi?: number;           // 初始最大双向流数量
  initialMaxStreamsUni?: number;            // 初始最大单向流数量
}

配置方式

koatty_serve 支持两种 SSL 配置方式（向后兼容）：

方式一：直接配置（推荐）

const httpsConfig = ConfigHelper.createHttpsConfig({
  hostname: '0.0.0.0',
  port: 443,
  ssl: {                        // 直接在顶层配置 SSL
    mode: 'auto',
    key: './ssl/server.key',
    cert: './ssl/server.crt'
  }
});

方式二：通过 ext 配置（向后兼容）

const httpsConfig = ConfigHelper.createHttpsConfig({
  hostname: '0.0.0.0',
  port: 443,
  ext: {
    ssl: {                      // 通过 ext 配置 SSL
      mode: 'auto',
      key: './ssl/server.key',
      cert: './ssl/server.crt'
    }
  }
});

配置热重载

// 智能配置更新
const result = await server.updateConfig({
  connectionPool: {
    maxConnections: 2000,      // 运行时更新
    connectionTimeout: 60000   // 运行时更新
  }
});

// 关键配置变更（自动重启）
await server.updateConfig({
  hostname: '0.0.0.0',  // 触发优雅重启
  port: 8080,           // 触发优雅重启
  ssl: {                // 触发优雅重启
    mode: 'mutual_tls'
  }
});

🏊‍♂️ 连接池管理

统一连接池配置

interface ConnectionPoolConfig {
  maxConnections?: number;        // 最大连接数
  connectionTimeout?: number;     // 连接超时
  keepAliveTimeout?: number;      // Keep-Alive超时
  requestTimeout?: number;        // 请求超时
  headersTimeout?: number;        // 头部超时
  
  // 协议特定配置
  protocolSpecific?: {
    // HTTP/2特定
    maxSessionMemory?: number;
    maxHeaderListSize?: number;
    
    // gRPC特定
    keepAliveTime?: number;
    maxReceiveMessageLength?: number;
    maxSendMessageLength?: number;
    
    // WebSocket特定
    pingInterval?: number;
    pongTimeout?: number;
    heartbeatInterval?: number;
  };
}

连接池监控

// 获取连接池统计
const stats = server.connectionPool.getMetrics();
console.log('连接池统计:', {
  activeConnections: stats.activeConnections,
  totalConnections: stats.totalConnections,
  connectionsPerSecond: stats.connectionsPerSecond,
  averageLatency: stats.averageLatency,
  errorRate: stats.errorRate
});

// 获取连接池健康状态
const health = server.connectionPool.getHealth();
console.log('连接池健康:', health.status); // 'healthy' | 'degraded' | 'overloaded'

🛡️ 优雅关闭

五步式关闭流程

interface ShutdownOptions {
  timeout?: number;           // 总超时时间 (默认30秒)
  drainDelay?: number;        // 排空延迟 (默认5秒)
  stepTimeout?: number;       // 单步超时 (默认6秒)
  skipSteps?: string[];       // 跳过的步骤
}

// 执行优雅关闭
await server.gracefulShutdown({
  timeout: 45000,
  drainDelay: 10000,
  stepTimeout: 8000
});

关闭步骤详解：

停止接受新连接: 关闭服务器监听，拒绝新连接
等待排空延迟: 给负载均衡器时间发现服务下线
等待连接完成: 等待现有连接的请求处理完毕
强制关闭连接: 终止超时的连接
清理资源: 停止监控任务，清理连接池

信号处理

terminus模块会自动处理进程信号（SIGTERM、SIGINT等），并调用server.Stop()方法执行优雅关闭流程。

server.Stop()方法内部会自动调用gracefulShutdown()，无需应用层手动处理：

🔐 SSL/TLS配置

HTTPS SSL配置

基础配置

const httpsConfig = ConfigHelper.createHttpsConfig({
  hostname: '0.0.0.0',
  port: 443,
  ssl: {
    mode: 'auto',               // auto | manual | mutual_tls
    key: './ssl/server.key',    // 私钥路径或内容
    cert: './ssl/server.crt'    // 证书路径或内容
  }
});

高级配置（双向TLS + 扩展选项）

const httpsConfig = ConfigHelper.createHttpsConfig({
  hostname: '0.0.0.0',
  port: 443,
  ssl: {
    mode: 'mutual_tls',                    // 双向 TLS 认证
    key: './ssl/server.key',
    cert: './ssl/server.crt',
    ca: './ssl/ca.crt',                    // CA 证书
    passphrase: 'your-passphrase',         // 私钥密码
    ciphers: 'ECDHE-RSA-AES128-GCM-SHA256:!RC4:!LOW:!MD5:!aNULL',
    honorCipherOrder: true,
    secureProtocol: 'TLSv1_2_method',
    requestCert: true,
    rejectUnauthorized: true,
    // 扩展配置选项
    handshakeTimeout: 10000,               // TLS 握手超时（毫秒）
    sessionTimeout: 300000,                // TLS 会话超时（毫秒）
    sessionIdContext: 'koatty-https',      // 会话 ID 上下文
    ALPNProtocols: ['http/1.1', 'h2']     // ALPN 协议列表
  }
});

HTTP/2 SSL配置

const http2Config = ConfigHelper.createHttp2Config({
  hostname: '0.0.0.0',
  port: 443,
  ssl: {
    mode: 'auto',
    key: './ssl/server.key',
    cert: './ssl/server.crt',
    allowHTTP1: true,                      // 允许回退到 HTTP/1.1
    ALPNProtocols: ['h2', 'http/1.1']     // HTTP/2 优先
  }
});

HTTP/3 SSL配置（QUIC）

const http3Config = ConfigHelper.createHttp3Config({
  hostname: '0.0.0.0',
  port: 443,
  ssl: {
    mode: 'auto',
    key: './ssl/server.key',
    cert: './ssl/server.crt',
    alpnProtocols: ['h3'],                 // HTTP/3 ALPN
    maxIdleTimeout: 30000,                 // QUIC 最大空闲超时
    initialMaxStreamsBidi: 100,            // 初始最大双向流
    initialMaxStreamsUni: 100              // 初始最大单向流
  }
});

gRPC SSL配置

const grpcConfig = ConfigHelper.createGrpcConfig({
  hostname: '0.0.0.0',
  port: 50051,
  ssl: {
    enabled: true,
    key: './certs/server.key',
    cert: './certs/server.crt',
    ca: './certs/ca.crt',
    clientCertRequired: true               // 需要客户端证书
  }
});

WebSocket SSL配置（WSS）

const wssConfig = ConfigHelper.createWebSocketConfig({
  hostname: '0.0.0.0',
  port: 8443,
  protocol: 'wss',                         // WebSocket Secure
  ssl: {
    enabled: true,
    key: './ssl/server.key',
    cert: './ssl/server.crt'
  }
});

📚 API参考

服务器类

HttpServer - HTTP服务器实现
HttpsServer - HTTPS服务器实现
Http2Server - HTTP/2服务器实现
Http3Server - HTTP/3服务器实现（基于QUIC）
WsServer - WebSocket服务器实现
GrpcServer - gRPC服务器实现

配置类

ConfigHelper - 统一配置创建器
ConnectionPoolConfig - 连接池配置接口
BaseServerOptions - 基础服务器选项
SSLConfig, SSL1Config, SSL2Config, SSL3Config - SSL配置接口

连接池类

HttpConnectionPoolManager - HTTP连接池
HttpsConnectionPoolManager - HTTPS连接池
Http2ConnectionPoolManager - HTTP/2连接池
Http3ConnectionPoolManager - HTTP/3连接池（QUIC）
WebSocketConnectionPoolManager - WebSocket连接池
GrpcConnectionPoolManager - gRPC连接池

🤝 贡献

欢迎提交Issue和Pull Request！

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

koatty_serve

🚀 核心特性

🏗️ 统一架构设计

🔧 统一配置管理

🏊‍♂️ 高性能连接池

🛡️ 运维监控

📦 安装

🎯 快速开始

使用 NewServe 创建服务器（推荐）

运行多个协议服务

使用协议专用服务器类（高级用法）

HTTPS服务器

gRPC服务器

HTTP/3服务器（基于QUIC）

WebSocket服务器

🏗️ 架构设计

BaseServer模板方法模式

统一配置管理

连接池架构

🔧 配置管理

配置类型系统

配置方式

方式一：直接配置（推荐）

方式二：通过 ext 配置（向后兼容）

配置热重载

🏊‍♂️ 连接池管理

统一连接池配置

连接池监控

🛡️ 优雅关闭

五步式关闭流程

信号处理

🔐 SSL/TLS配置

HTTPS SSL配置

基础配置

高级配置（双向TLS + 扩展选项）

HTTP/2 SSL配置

HTTP/3 SSL配置（QUIC）

gRPC SSL配置

WebSocket SSL配置（WSS）

📚 API参考

服务器类

配置类

连接池类

🤝 贡献