Granian

一个用于 Python 应用程序的 Rust HTTP 服务器。

设计理念

Granian 设计的主要原因如下：

• 拥有一个单一、正确的 HTTP 实现，支持 1、2（最终会支持 3）版本
• 为多个平台提供单一软件包
• 避免在 Unix 系统上常见的 Gunicorn + uvicorn + http-tools 依赖组合
• 与现有替代方案相比，提供稳定的性能

特性

• 支持 ASGI/3、RSGI 和 WSGI 接口应用程序
• 实现 HTTP/1 和 HTTP/2 协议
• 支持 HTTPS
• 支持 Websockets

快速入门

你可以使用 pip 安装 Granian：

$ pip install granian

在你的 main.py 中创建一个 ASGI 应用程序：

async def app(scope, receive, send):
    assert scope['type'] == 'http'

    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [
            [b'content-type', b'text/plain'],
        ],
    })
    await send({
        'type': 'http.response.body',
        'body': b'Hello, world!',
    })

然后运行它：

$ granian --interface asgi main:app

你也可以使用 RSGI 规范创建一个应用程序：

async def app(scope, proto):
    assert scope.proto == 'http'

    proto.response_str(
        status=200,
        headers=[
            ('content-type', 'text/plain')
        ],
        body="Hello, world!"
    )

然后使用以下命令运行：

$ granian --interface rsgi main:app

选项

你可以使用 --help 命令查看 Granian 提供的所有选项：

$ granian --help
用法：granian [选项] APP

  APP  要运行的应用程序目标。  [必需]
选项：
  --host TEXT                     要绑定的主机地址 [环境变量：GRANIAN_HOST；默认值：(127.0.0.1)]
  --port INTEGER                  要绑定的端口 [环境变量：GRANIAN_PORT；默认值：8000]
  --interface [asgi|asginl|rsgi|wsgi]
                                  应用程序接口类型 [环境变量：GRANIAN_INTERFACE；默认值：(rsgi)]
  --http [auto|1|2]               HTTP 版本 [环境变量：GRANIAN_HTTP；默认值：(auto)]
  --ws / --no-ws                  启用 WebSocket 处理 [环境变量：GRANIAN_WEBSOCKETS；默认：(启用)]
  --workers INTEGER RANGE         工作进程数量 [环境变量：GRANIAN_WORKERS；默认值：1；x>=1]
  --threads INTEGER RANGE         线程数量（每个工作进程）[环境变量：GRANIAN_THREADS；默认值：1；x>=1]
  --blocking-threads INTEGER RANGE
                                  阻塞线程数量（每个工作进程）[环境变量：GRANIAN_BLOCKING_THREADS；x>=1]
  --threading-mode [runtime|workers]
                                  使用的线程模式 [环境变量：GRANIAN_THREADING_MODE；默认值：(workers)]
  --loop [auto|asyncio|uvloop]    事件循环实现 [环境变量：GRANIAN_LOOP；默认值：(auto)]
  --opt / --no-opt                启用循环优化 [环境变量：GRANIAN_LOOP_OPT；默认：(禁用)]
  --backlog INTEGER RANGE         最大连接队列长度（全局）[环境变量：GRANIAN_BACKLOG；默认值：1024；x>=128]
  --backpressure INTEGER RANGE    并发处理的最大请求数（每个工作进程）[环境变量：GRANIAN_BACKPRESSURE；默认值：(backlog/workers)；x>=1]
  --http1-buffer-size INTEGER RANGE
                                  设置 HTTP/1 连接的最大缓冲区大小 [环境变量：GRANIAN_HTTP1_BUFFER_SIZE；默认值：417792；x>=8192]
  --http1-keep-alive / --no-http1-keep-alive
                                  启用或禁用 HTTP/1 keep-alive [环境变量：GRANIAN_HTTP1_KEEP_ALIVE；默认：(启用)]
  --http1-pipeline-flush / --no-http1-pipeline-flush
                                  聚合 HTTP/1 刷新以更好地支持流水线响应（实验性）[环境变量：GRANIAN_HTTP1_PIPELINE_FLUSH；默认：(禁用)]
  --http2-adaptive-window / --no-http2-adaptive-window
                                  设置是否为 HTTP/2 使用自适应流控制 [环境变量：GRANIAN_HTTP2_ADAPTIVE_WINDOW；默认：(禁用)]
  --http2-initial-connection-window-size INTEGER
                                  设置 HTTP/2 的最大连接级流控制 [环境变量：GRANIAN_HTTP2_INITIAL_CONNECTION_WINDOW_SIZE；默认值：1048576]
  --http2-initial-stream-window-size INTEGER
                                  设置 HTTP/2 流级流控制的 `SETTINGS_INITIAL_WINDOW_SIZE` 选项 [环境变量：GRANIAN_HTTP2_INITIAL_STREAM_WINDOW_SIZE；默认值：1048576]
  --http2-keep-alive-interval INTEGER
                                  设置发送 HTTP/2 Ping 帧以保持连接活跃的间隔 [环境变量：GRANIAN_HTTP2_KEEP_ALIVE_INTERVAL]
  --http2-keep-alive-timeout INTEGER
                                  设置接收 HTTP/2 keep-alive ping 确认的超时时间 [环境变量：GRANIAN_HTTP2_KEEP_ALIVE_TIMEOUT；默认值：20]
  --http2-max-concurrent-streams INTEGER
                                  设置 HTTP/2 连接的 SETTINGS_MAX_CONCURRENT_STREAMS 选项 [环境变量：GRANIAN_HTTP2_MAX_CONCURRENT_STREAMS；默认值：200]
  --http2-max-frame-size INTEGER  设置 HTTP/2 使用的最大帧大小 [环境变量：GRANIAN_HTTP2_MAX_FRAME_SIZE；默认值：16384]
  --http2-max-headers-size INTEGER
                                  设置接收的头部帧的最大大小 [环境变量：GRANIAN_HTTP2_MAX_HEADERS_SIZE；默认值：16777216]
  --http2-max-send-buffer-size INTEGER
                                  设置每个 HTTP/2 流的最大写入缓冲区大小 [环境变量：GRANIAN_HTTP2_MAX_SEND_BUFFER_SIZE；默认值：409600]
  --log / --no-log                启用日志记录 [环境变量：GRANIAN_LOG_ENABLED；默认：(启用)]
  --log-level [critical|error|warning|warn|info|debug]
                                  日志级别 [环境变量：GRANIAN_LOG_LEVEL；默认值：(info)]
  --log-config FILE               日志配置文件（json）[环境变量：GRANIAN_LOG_CONFIG]
  --access-log / --no-access-log  启用访问日志 [环境变量：GRANIAN_LOG_ACCESS_ENABLED；默认：(禁用)]
  --access-log-fmt TEXT           访问日志格式 [环境变量：GRANIAN_LOG_ACCESS_FMT]
  --ssl-keyfile FILE              SSL 密钥文件 [环境变量：GRANIAN_SSL_KEYFILE]
  --ssl-certificate FILE          SSL 证书文件 [环境变量：GRANIAN_SSL_CERTIFICATE]
  --url-path-prefix TEXT          应用程序挂载的 URL 路径前缀 [环境变量：GRANIAN_URL_PATH_PREFIX]
  --respawn-failed-workers / --no-respawn-failed-workers
                                  在意外退出时启用工作进程重生 [环境变量：GRANIAN_RESPAWN_FAILED_WORKERS；默认：(禁用)]
  --respawn-interval FLOAT        工作进程重生之间的睡眠秒数 [环境变量：GRANIAN_RESPAWN_INTERVAL；默认值：3.5]
  --reload / --no-reload          启用应用程序文件更改时的自动重载（需要 granian[reload] 额外包）[环境变量：GRANIAN_RELOAD；默认：(禁用)]
  --process-name TEXT             设置进程的自定义名称（需要 granian[pname] 额外包）[环境变量：GRANIAN_PROCESS_NAME]
  --version                       显示版本并退出
  --help                          显示此消息并退出

访问日志格式

可以通过指定要包含的原子（见下文）来配置访问日志格式。默认情况下，Granian 将使用 `[%(time)s] %(addr)s - "%(method)s %(path)s %(protocol)s" %(status)d %(dt_ms).3f` 作为格式。

访问日志原子

以下原子可供使用：

| 标识符 | 描述 |
| --- | --- |
| addr | 客户端远程地址 |
| time | 请求的日期时间 | 
| dt_ms | 请求持续时间（毫秒） |
| status | HTTP 响应状态 |
| path | 请求路径（不含查询字符串） |
| query_string | 请求查询字符串 |
| method | 请求 HTTP 方法 |
| scheme | 请求协议 |
| protocol | HTTP 协议版本 |

进程和线程

Granian 提供了不同的选项来配置要运行的进程和线程数量，特别是：
- **workers**：持有专用 Python 解释器运行应用程序的进程总数
- **threads**：每个 worker 执行网络 I/O 的 Rust 线程数
- **blocking threads**：每个 worker 参与阻塞操作的 Rust 线程数。这些线程的主要作用是处理阻塞 I/O（如打开文件），但在 WSGI 等同步协议中，这些线程还负责与应用程序代码交互。

一般来说，Granian 会尽最大努力自动为线程配置选择适当的值，让你只需负责选择所需的 worker 数量。

这里没有"黄金法则"，因为这些数字在很大程度上取决于你的应用程序行为和部署目标，但我们可以列出一些建议：
- 将 worker 数量与 CPU 核心数量匹配通常是最佳起点；在 Docker 或 K8s 等容器化环境中，最好每个容器使用 1 个 worker，然后使用相关的编排器来扩展容器；
- 默认的线程数对绝大多数应用程序来说都没问题；对于处理多个并发打开的 WebSocket 的应用程序，你可能需要增加这个数字；
- 默认的阻塞线程数应该适用于大多数应用程序；在 WSGI 等同步协议中，这也会影响你可以处理的并发请求数，但你应该使用 `backpressure` 配置参数来控制它，只有当你的应用程序平均响应时间非常低（毫秒级）时，才设置较低的阻塞线程数；

此外，你通常应该避免根据其他服务器的数字来配置 worker 和线程，因为 Granian 的架构与 Gunicorn 或 Uvicorn 等项目有很大不同。

### 线程模式

Granian 提供两种不同的线程范式，这是因为内部 Rust 运行时可以是多线程的——与 Python 事件循环只能作为单线程运行不同。

假设你用相关选项指定 N 个线程，在 **workers** 线程模式下，Granian 将生成 N 个单线程 Rust 运行时，而在 **runtime** 线程模式下，Granian 将生成一个具有 N 个线程的多线程运行时。

基准测试表明，**workers** 模式在进程数量较少时更有效，而 **runtime** 模式在 CPU 数量较多时似乎可以更有效地扩展。但实际性能将取决于特定的应用程序代码，因此 *你的实际情况可能有所不同*。

### 事件循环优化

使用 `--opt` 选项，Granian 将为 Python 协程和可等待对象使用自定义任务处理程序，以提高 Python 代码执行效率。由于这些处理程序的性质，一些依赖 `asyncio` 内部机制的库和特定应用程序代码可能无法正常工作。

你可以测试这些优化对你的应用程序造成的影响，并决定是否启用它们或保持禁用状态（默认情况下）。

## 项目状态

Granian 目前正在积极开发中。

Granian 兼容 Python 3.8 及以上版本。

## 许可证

Granian 在 BSD 许可证下发布。