LSQUIC库开发指南：从入门到实战

LSQUIC库开发指南：从入门到实战

【免费下载链接】lsquic LiteSpeed QUIC and HTTP/3 Library 项目地址: https://gitcode.com/gh_mirrors/ls/lsquic

概述

LSQUIC是一个功能强大的QUIC协议实现库，支持Google QUIC和IETF QUIC标准。本教程将深入讲解如何使用LSQUIC库开发QUIC客户端和服务器应用，涵盖核心概念、API使用和最佳实践。

核心概念

三大核心对象

LSQUIC库围绕三个核心对象构建：

1. 引擎(Engine)：管理所有连接，处理传入数据包并调度传出数据包

   • 可配置为客户端或服务器模式
   • 支持HTTP/3功能
   • 每个引擎实例只能运行在单一模式

2. 连接(Connection)：维护一个或多个流，确保可靠数据传输

   • 服务器模式下，连接对象创建时已完成握手
   • 客户端模式下，连接创建后才开始握手

3. 流(Stream)：双向通信通道，通常对应请求/响应交换

   • 属于特定连接
   • 支持并发多流操作

HTTP模式

LSQUIC内置HTTP支持，提供统一API处理：

• HTTP头部压缩/解压缩
• 流帧处理
• 控制流管理 透明支持Google QUIC和HTTP/3协议差异

开发准备

头文件包含

只需包含主头文件即可：

#include "lsquic.h"

库初始化

全局初始化

使用前必须初始化库：

if (0 != lsquic_global_init(LSQUIC_GLOBAL_CLIENT|LSQUIC_GLOBAL_SERVER)) {
    exit(EXIT_FAILURE);
}

参数说明：

• LSQUIC_GLOBAL_CLIENT：初始化客户端功能
• LSQUIC_GLOBAL_SERVER：初始化服务器功能

资源清理

程序退出前执行清理：

lsquic_global_cleanup();

引擎管理

创建引擎实例

lsquic_engine_t *engine = lsquic_engine_new(
    LSENG_SERVER|LSENG_HTTP,  // 模式标志
    &engine_api              // 回调函数结构
);

模式标志说明：

• LSENG_SERVER：服务器模式
• LSENG_HTTP：启用HTTP功能

引擎配置

必须提供的回调函数：

struct lsquic_engine_api engine_api = {
    .ea_packets_out     = send_packets_out,  // 发包函数
    .ea_packets_out_ctx = (void *) sockfd,   // 上下文(如socket fd)
    .ea_stream_if       = &stream_callbacks, // 流事件回调
    .ea_stream_if_ctx   = &some_context,     // 流回调上下文
    .ea_get_ssl_ctx     = get_ssl_ctx        // TLS上下文获取
};

引擎参数调优

通过ea_settings字段可调整：

• 支持的QUIC版本
• 内存分配策略
• 各类超时设置
• 流控参数等

不设置则使用默认值，适合大多数场景。

网络通信

数据包接收

使用唯一接口传入UDP数据：

int lsquic_engine_packet_in(
    lsquic_engine_t *engine,
    const unsigned char *udp_payload,  // UDP负载
    size_t size,                      // 负载大小
    const struct sockaddr *local_addr, // 本地地址
    const struct sockaddr *peer_addr,  // 对端地址 
    void *peer_ctx,                   // 对端上下文
    int ecn                           // ECN标记(0-3)
);

本地地址重要性：

• 确定出包源地址
• 多宿主环境必须正确设置
• 用于路径变更检测(NAT重绑定等)

数据包发送

实现ea_packets_out回调：

static int send_packets_out(void *ctx, 
    const struct lsquic_out_spec *specs,
    unsigned n_specs)
{
    // 实现发送逻辑
    // 返回成功发送的包数或-1(错误)
}

错误处理：

• EAGAIN：稍后重试，需调用lsquic_engine_send_unsent_packets
• EMSGSIZE：MTU探测失败，引擎会自动处理
• 其他错误：终止对应连接

事件处理

连接处理时机

引擎通过"tick"机制通知可处理连接：

• 有待处理入包
• 可读/可写流数据
• 内部协议维护需求

查询下次处理时间：

int lsquic_engine_earliest_adv_tick(
    lsquic_engine_t *engine, 
    int *diff_us  // 距下次处理的微秒数
);

连接处理实现

基本处理模式：

void process_connections(lsquic_engine_t *engine) {
    int diff;
    lsquic_engine_process_conns(engine);
    if (lsquic_engine_earliest_adv_tick(engine, &diff)) {
        // 根据diff设置下次处理时间
    }
}

注意：

• 禁止在回调函数内调用lsquic_engine_process_conns
• 未及时处理不会导致错误，但影响性能

回调函数实现

连接生命周期回调

// 新连接建立
lsquic_conn_ctx_t *on_new_conn(void *ctx, lsquic_conn_t *conn) {
    // 创建连接上下文
    if (客户端模式) {
        lsquic_conn_make_stream(conn); // 请求创建流
    }
    return 上下文指针;
}

// 连接关闭
void on_conn_closed(lsquic_conn_t *conn) {
    // 清理连接资源
}

流事件回调

// 新流创建
lsquic_stream_ctx_t *on_new_stream(void *ctx, lsquic_stream_t *stream) {
    return 流上下文;
}

// 流可读
void on_read(lsquic_stream_t *stream, lsquic_stream_ctx_t *ctx) {
    // 读取流数据
}

// 流可写  
void on_write(lsquic_stream_t *stream, lsquic_stream_ctx_t *ctx) {
    // 写入流数据
}

// 流关闭
void on_close(lsquic_stream_t *stream, lsquic_stream_ctx_t *ctx) {
    // 清理流资源
}

可选高级回调

• 握手完成通知
• GOAWAY帧处理
• 新令牌接收
• 会话恢复信息

最佳实践

1. 多引擎实例：需要同时支持客户端和服务器时，创建独立引擎实例

2. 错误恢复：

   • 实现健壮的EAGAIN处理
   • 监控连接错误事件

3. 性能调优：

   • 遵循tick建议时间
   • 适当调整引擎参数

4. 资源管理：

   • 及时释放连接和流资源
   • 合理设置超时参数

通过本指南，开发者可以快速掌握LSQUIC核心功能，构建高性能QUIC应用。实际开发中应根据具体需求调整配置，并充分利用库提供的各种回调机制实现业务逻辑。

【免费下载链接】lsquic LiteSpeed QUIC and HTTP/3 Library 项目地址: https://gitcode.com/gh_mirrors/ls/lsquic