witchcraft-rust-server

文档

witchcraft-server 是一个Witchcraft服务器的Rust实现。它提供了一种快速轻松地创建在Witchcraft生态系统中工作的服务器的方法。请参阅Crate的文档以获取更多详细信息。

许可证

此仓库根据 Apache 2.0许可证 提供。

lib.rs:

一个高度定制的嵌入应用程序服务器，用于RESTful API。

初始化

Witchcraft服务器的入口是一个用 #[witchcraft_server::main] 注释的初始化函数

use conjure_error::Error;
use refreshable::Refreshable;
use witchcraft_server::config::install::InstallConfig;
use witchcraft_server::config::runtime::RuntimeConfig;

#[witchcraft_server::main]
fn main(
    install: InstallConfig,
    runtime: Refreshable<RuntimeConfig>,
    wc: &mut Witchcraft,
) -> Result<(), Error> {
    wc.api(CustomApiEndpoints::new(CustomApiResource));

    Ok(())
}

此函数提供了服务器的安装和运行时配置，以及可以使用来配置服务器的 Witchcraft 对象。一旦初始化函数返回，服务器将启动。

注意

初始化函数应快速返回 - 任何需要长时间运行的工作应发生在后台。

配置

Witchcraft将配置分为两个类别

• 安装 - 在服务生命周期内固定的配置。例如，服务器监听的端口是服务器安装配置的一部分。
• 运行时 - 在服务运行期间可以动态更新的配置。例如，日志详细程度是服务器运行时配置的一部分。

配置从 var/conf/install.yml 和 var/conf/runtime.yml 文件中加载。每隔几秒钟会自动检查 runtime.yml 文件的更新。

扩展

配置文件通过 serde::Deserialize 特性反序列化为 Rust 类型。`witchcraft-server` 的内部配置由 InstallConfig 和 RuntimeConfig 类型表示。需要自己配置的服务应该使用 #[serde(flatten)] 注解将 Witchcraft 配置嵌入自己的配置中，并实现 AsRef 特性

use serde::Deserialize;
use witchcraft_server::config::install::InstallConfig;

#[derive(Deserialize)]
#[serde(rename_all = "kebab-case")]
struct MyInstallConfig {
    shave_yaks: bool,
    #[serde(flatten)]
    base: InstallConfig,
}

impl AsRef<InstallConfig> for MyInstallConfig {
    fn as_ref(&self) -> &InstallConfig {
        &self.base
    }
}

服务的自定义配置将位于标准的 Witchcraft 配置旁边

product-name: my-service
product-version: 1.0.0
port: 12345
shave-yaks: true

敏感值

服务器配置的反序列化器支持两种处理敏感值的方法

• ${enc:5BBfGvf90H6bApwfx...} - 使用加密形式内联在 serde_encrypted_value 中，密钥存储在 var/conf/encrypted-config-value.key。
• ${file:/mnt/secrets/foo} - 使用 serde_file_value 作为包含值的文件的引用。

可刷新的运行时配置

服务器的运行时配置被封装在 Refreshable 类型中，以便代码可以正确处理配置的更新。根据用例，实现可以使用 Refreshable::get 在需要时检索配置的当前状态，或者使用 Refreshable::subscribe 方法在配置更改时接收通知。有关 refreshable 包的详细信息，请参阅其文档。

HTTP API

服务器支持实现 Service 和 AsyncService 特性的 HTTP 端点。这些实现可以由 Conjure YML 定义 通过 conjure-codegen 包生成。

虽然我们强烈建议使用由Conjure生成的API，但某些服务可能需要暴露无法在Conjure中定义的端点。可以使用 conjure_http::conjure_endpoints 宏来定义任意HTTP端点。

API端点通常应使用 Witchcraft::api 和 Witchcraft::blocking_api 方法进行注册，这将使端点位于 /api 路由下。如果需要，可以使用 Witchcraft::app 和 Witchcraft::blocking_app 方法将端点直接放置在根路由下。

HTTP客户端

远程服务配置在运行时配置的 service-discovery 部分，客户端可以由 ClientFactory 创建，该工厂由 Witchcraft::client_factory 方法返回。客户端将根据运行时配置的变化自动更新。有关 conjure_runtime 库的详细信息，请参阅文档。

状态端点

服务器公开了几个“状态”端点来报告服务器的一些方面。

活跃性

/status/liveness 端点对所有请求返回成功响应，指示服务器正在运行。

就绪性

/status/readiness 端点返回一个响应，指示服务器就绪处理对其端点的请求。部署基础设施使用此端点的结果来决定是否将请求路由到服务的特定实例。可以通过 ReadinessCheckRegistry 将自定义就绪检查添加到服务器，该注册表由 Witchcraft::readiness_checks 方法返回。任何长时间运行的自定义逻辑应异步执行，并使用就绪检查来指示完成。

健康状态

/status/health 端点返回一个响应，指示服务器整体的健康状况。部署基础设施使用此端点的结果来触发警报。可以通过 HealthCheckRegistry 将自定义健康检查添加到服务器，该注册表由 Witchcraft::health_checks 方法返回。对此端点的请求必须使用运行时配置中的 health-checks.shared-secret 令牌进行身份验证。

服务器注册了几个内置的健康检查

• CONFIG_RELOAD - 如果运行时配置无法正确重新加载，则报告错误状态。
• ENDPOINT_FIVE_HUNDREDS - 如果端点有大量 500 内部服务器错误 响应，则报告警告。
• SERVICE_DEPENDENCY - 跟踪通过服务器客户端工厂创建的HTTP客户端发出的请求的状态，并报告对远程服务的请求有高失败率的警告状态。
• PANICS - 如果服务器在任何时候崩溃，则报告警告。

诊断

端点 /debug/diagnostic/{diagnosticType} 返回诊断信息。对端点的请求必须使用运行时配置中的 diagnostics.debug-shared-secret 承载令牌进行认证。

定义了几个诊断类型

• diagnostic.types.v1 - 返回所有有效诊断类型的JSON编码列表。
• rust.heap.status.v1 - 返回有关堆状态的详细统计信息。需要 jemalloc 功能（默认启用）。
• metric.names.v1 - 返回所有已注册的度量名称的JSON编码列表。
• rust.thread.dump.v1 - 返回进程中每个线程的堆栈跟踪。仅在Linux上运行时受支持。

日志记录

witchcraft-server 按照以下规范 witchcraft-api spec 发射JSON编码的日志。默认情况下，日志将写入位于 var/log 的文件中，对应于日志消息的类型（service.log、request.log 等）。这些文件将根据不可配置的策略自动轮换和压缩。如果在Docker容器中运行或安装配置中启用了 use-console-log 设置，则日志将写入标准输出。

服务

服务日志包含由 witchcraft_log crate 中的宏调用产生的消息。由标准 Rust [log] crate 发射的消息也将被捕获，但作为Witchcraft服务的代码编写部分应使用 witchcraft_log 代替以获得更好的集成。有关该crate的详细信息，请参阅其文档。

请求

请求日志记录服务器处理的每个HTTP请求的条目。被端点的Conjure定义标记为安全的参数将作为参数包含在日志记录中。

跟踪

跟踪日志记录 Zipkin 风格的跟踪跨度。服务器会根据请求的传播元数据自动为每个传入的HTTP请求创建跨度。尚未做出采样决策的跟踪将按照服务器运行时配置中的 logging.trace-rate 字段的指定率进行采样，默认为0.005%。服务器逻辑可以使用 zipkin crate 创建额外的跨度。有关该crate的详细信息，请参阅其文档。

度量

性能日志包含指标值，用于报告服务器各种组件的状态。指标每30秒记录一次。服务器逻辑可以使用MetricRegistry创建额外的指标，该指标由Witchcraft::metrics方法返回。有关更多详细信息，请参阅witchcraft_metrics库的文档。

指标

服务器默认报告各种指标

线程池

• server.worker.max（仪表）- 服务器线程池配置的最大大小，用于请求阻塞端点。
• server.worker.active（仪表）- 正在处理请求到阻塞端点的线程数。
• server.worker.utilization-max（仪表）- server.worker.active除以server.worker.max。如果是1，则服务器将立即拒绝到阻塞端点的调用，并返回503 服务不可用状态码。

日志记录

• logging.queue (type: <log_type>)（仪表）- 队列中等待输出的日志消息数。

进程

• process.heap（仪表）- 从堆中分配的字节总数。需要jemalloc功能（默认启用）。
• process.heap.active（仪表）- 活跃页面的总字节数。需要jemalloc功能（默认启用）。
• process.heap.resident（仪表）- 物理驻留页面的总字节数。需要jemalloc功能（默认启用）。
• process.uptime（仪表）- 服务器启动以来经过的微秒数。
• process.panics（计数器）- 服务器崩溃的次数。
• process.user-time（仪表）- 进程在用户空间中运行花费的微秒数。
• process.user-time.norm（仪表）- process.user-time除以CPU核心数。
• process.system-time（仪表）- 进程在内核空间或不可中断的IO等待中运行的微秒数。
• process.system-time.norm（仪表）- process.system-time除以CPU核心数。
• process.blocks-read（仪表）- 服务器读取的文件系统块数。
• process.blocks-written (gauge) - 服务器已写入的文件系统块的数量。
• process.threads (gauge) - 进程中的线程数量。
• process.filedescriptor (gauge) - 进程持有的打开文件描述符数量除以服务器可能打开的最大文件数。

连接

• server.connection.active (counter) - 当前连接到HTTP服务器的TCP套接字数量。
• server.connection.utilization (gauge) - 服务器最大连接数除以 server.connection.active。

TLS

• tls.handshake (context: server, protocol: <protocol>, cipher: <cipher>) (meter) - HTTP服务器完成的TLS握手的速率。

服务器

• server.request.active (counter) - 正在积极处理的请求数量。
• server.request.unmatched (meter) - 服务器返回的 404 Not Found 响应的速率。
• server.response.all (meter) - 服务器返回的响应速率。
• server.response.1xx (meter) - 服务器返回的 1xx 响应的速率。
• server.response.2xx (meter) - 服务器返回的 2xx 响应的速率。
• server.response.3xx (meter) - 服务器返回的 3xx 响应的速率。
• server.response.4xx (meter) - 服务器返回的 4xx 响应的速率。
• server.response.5xx (meter) - 服务器返回的 5xx 响应的速率。
• server.response.500 (meter) - 服务器返回的 500 Internal Server Error 响应的速率。

端点

• server.response (service-name: <service_name>, endpoint: <endpoint>) (timer) - 处理每个端点请求所需的时间，包括发送整个响应体。
• server.response.error (service-name: <service_name>, endpoint: <endpoint>) (计量) - 对于端点请求返回的 5xx 错误的比率。

HTTP客户端

请参阅 conjure_runtime 库的文档，了解 HTTP 客户端报告的指标。