htsget-config

为 htsget-rs 和相关 crates 提供配置。

概览

该 crate 通过使用配置文件或读取环境变量来配置 htsget-rs。

使用方法

运行 htsget-rs 作为应用程序

要配置 htsget-rs，可以使用 TOML 配置文件。它还支持从环境变量中读取配置。环境变量中设置的任何配置选项都将覆盖配置文件中的值。对于一些更深层嵌套的配置选项，使用配置文件可能比使用环境变量更方便。

配置由多个部分组成，包括票据服务器配置、数据服务器配置、服务信息配置和解析器配置。

票据服务器配置

票据服务器通过返回一组客户端必须获取和连接的 URL 票据来响应 htsget 请求。要配置票据服务器，设置以下选项

通过设置ticket_server_key和ticket_server_cert选项支持TLS。票据服务器配置示例

ticket_server_addr = '127.0.0.1:8080'
ticket_server_cors_allow_credentials = false
ticket_server_cors_allow_origins = 'Mirror'
ticket_server_cors_allow_headers = ['Content-Type']
ticket_server_cors_allow_methods = ['GET', 'POST']
ticket_server_cors_max_age = 86400
ticket_server_cors_expose_headers = []

本地数据服务器配置

本地数据服务器通过提供本地文件系统数据来响应票据服务器生成的票据。要配置数据服务器，设置以下选项

通过设置data_server_key和data_server_cert选项支持TLS。数据服务器配置示例

data_server_addr = '127.0.0.1:8081'
data_server_local_path = './'
data_server_serve_at = ''
data_server_key = 'key.pem'
data_server_cert = 'cert.pem'
data_server_cors_allow_credentials = false
data_server_cors_allow_origins = 'Mirror'
data_server_cors_allow_headers = ['Content-Type']
data_server_cors_allow_methods = ['GET', 'POST']
data_server_cors_max_age = 86400
data_server_cors_expose_headers = []

有时禁用数据服务器可能很有用，因为所有对票据服务器的响应都将由其他地方处理，例如使用AWS S3数据服务器。

要禁用数据服务器，设置以下选项

data_server_enabled = false

服务信息配置

服务信息配置控制当查询service-info路径时返回什么。
要配置service-info，设置以下选项

服务信息配置示例

id = 'id'
name = 'name'
version = '0.1'
organization_name = 'name'
organization_url = 'https://example.com/'
contact_url = 'mailto:[email protected]'
documentation_url = 'https://example.com/'
created_at = '2022-01-01T12:00:00Z'
updated_at = '2022-01-01T12:00:00Z'
environment = 'dev'

解析器

htsget-rs的解析器组件用于将查询ID映射到资源的位置。htsget-rs接收到的每个查询都会被解析到一个位置，数据服务器可以响应该位置。查询ID与正则表达式匹配，然后与一个替换字符串映射，该替换字符串可以访问正则表达式的捕获组。解析器在数组中配置，第一个匹配的解析器用于映射ID。

要创建解析器，添加一个[[resolvers]]表格数组，并设置以下选项

例如，下面是一个regex选项，它匹配两个组之间的斜杠，并使用substitution_string在组之间插入额外的data。

[[resolvers]]
regex = '(?P<group1>.*?)/(?P<group2>.*)'
substitution_string = '$group1/data/$group2'

有关正则表达式选项的更多信息，请参阅regex crate。

每个解析器也映射到特定的存储后端。此存储后端可用于设置从本地存储、S3风格的存储桶存储或HTTP URL提供查询ID。要为解析器设置存储后端，添加一个[resolvers.storage]表格。一些存储后端在编译htsget-rs时需要设置功能标志。

要使用LocalStorage，设置storage = 'Local'。这将从data_server配置中推导出以下字段的值

要使用S3Storage，启用s3-storage功能构建htsget-rs，并设置storage = 'S3'。这将从regex组件中派生resolvers的bucket值。

UrlStorage是另一个存储后端，可以从远程HTTP URL提供数据。当使用此存储后端时，htsget-rs将从配置中设置的url获取数据。它还将转发初始查询中接收到的任何头，这对于认证非常有用。要使用UrlStorage，请启用url-storage功能构建htsget-rs，并在以下选项下设置以下选项：[resolvers.storage]

当使用UrlStorage时，将对以下url发出以下请求。

• GET请求仅获取数据文件的头部（例如GET /data.bam，带有Range: bytes=0-<end_of_bam_header>）。
• GET请求获取整个索引文件（例如GET /data.bam.bai）。
• 对数据文件的HEAD请求以获取其长度（例如HEAD /data.bam）。

默认情况下，在发出这些请求时将包括初始查询中接收到的所有头部。要排除某些头部，请设置header_blacklist选项。请注意，被列入黑名单的头部将从对url发出的请求以及URL票证中删除。

例如，以下resolvers值

[[resolvers]]
regex = '^(example_bucket)/(?P<key>.*)$'
substitution_string = '$key'
storage = 'S3'

如果该解析器匹配，则将使用“example_bucket”作为S3存储桶，因为这是regex中的第一个捕获组。请注意，要使用此功能，必须在regex中定义至少一个捕获组。

注意，所有关于S3Storage或LocalStorage的值都可以通过添加一个[resolvers.storage]表格来手动设置。例如，要手动设置LocalStorage的配置

[[resolvers]]
regex = '.*'
substitution_string = '$0'

[resolvers.storage]
scheme = 'Http'
authority = '127.0.0.1:8081'
local_path = './'
path_prefix = ''

或者，要手动设置S3Storage的配置

[[resolvers]]
regex = '.*'
substitution_string = '$0'

[resolvers.storage]
bucket = 'bucket'

UrlStorage只能手动指定。以下是一个包含UrlStorage的解析器示例

[[resolvers]]
regex = ".*"
substitution_string = "$0"

[resolvers.storage]
url = "https://127.0.0.1:8080"
response_url = "https://example.com"
forward_headers = true
header_blacklist = ["Host"]

更多配置文件示例位于examples/config-files下。

注意

默认情况下，当使用带有s3-storage功能标志编译htsget-rs时，如果没有指定storage选项，将使用storage = 'S3'。否则，如果没有指定存储选项，将使用storage = 'Local'。由于默认情况下编译包含s3-storage功能标志，因此为了使storage = 'Local'成为默认值，可以将--no-default-features传递给cargo。

允许守卫

此外，解析器组件还有一个功能，允许根据查询中存在的其他字段来解析ID。这很有用，因为它允许解析器在存在特定的查询参数集时匹配ID。例如，可以将解析器设置为仅在格式也是BAM时解析ID。

可以通过设置[resolver.allow_guard]表格来配置此组件。以下选项可用于限制哪些查询由解析器解析

一个完全配置的解析器示例。

[[resolvers]]
regex = '.*'
substitution_string = '$0'

[resolvers.storage]
bucket = 'bucket'

[resolvers.allow_guard]
allow_reference_names = ['chr1']
allow_fields = ['QNAME']
allow_tags = ['RG']
allow_formats = ['BAM']
allow_classes = ['body']
allow_interval_start = 100
allow_interval_end = 1000

在这个例子中，解析器将仅在查询为chr1，且位置在100到1000之间时匹配查询ID。

TLS

TLS可以配置为票据服务器、数据服务器或URL存储客户端。这些选项从PEM格式文件中读取私钥和证书。证书必须是X.509格式，私钥可以是RSA、PKCS8或SEC1（EC）编码。以下选项可用：

当由票据服务器和数据服务器使用时，key和cert启用TLS，与URL存储客户端一起使用时，它们启用客户端身份验证。根存储仅由URL存储客户端使用。注意，URL存储客户端始终允许TLS，但是默认配置不执行客户端身份验证并使用本地根证书存储。

例如，可以通过指定key和cert选项来启用票据服务器的TLS：

ticket_server_tls.cert = "cert.pem"
ticket_server_tls.key = "key.pem"

该项目使用rustls进行所有TLS逻辑，并且不依赖于OpenSSL。rustls库在接受证书和密钥时可能更加严格。例如，它不接受用作最终实体的CA的自签名证书。如果使用OpenSSL为root_store生成证书，应包括正确的扩展，如subjectAltName。

为UrlStorage后端生成自定义根CA和证书的示例

# Create a root CA
openssl req -x509 -noenc -subj '/CN=localhost' -newkey rsa -keyout root.key -out root.crt

# Create a certificate signing request
openssl req -noenc -newkey rsa -keyout server.key -out server.csr -subj '/CN=localhost' -addext subjectAltName=DNS:localhost

# Create the `UrlStorage` server's certificate
openssl x509 -req -in server.csr -CA root.crt -CAkey root.key -days 365 -out server.crt -copy_extensions copy

# An additional client certificate signing request and certificate can be created in the same way as the server
# certificate if using client authentication.

然后可以使用root.crt在htsget-rs中用于通过server.crt对UrlStorage后端进行身份验证

# Trust the root CA that signed the server's certificate.
tls.root_store = "root.crt"

或者，可以使用如mkcert的项目来简化此过程。

在examples/config-files下提供了更多的TLS示例。

配置文件位置

htsget-rs二进制文件（htsget-axum、htsget-actix和htsget-lambda）支持一些命令行选项。可以通过设置--config选项来指定配置文件位置

cargo run -p htsget-axum -- --config "config.toml"

配置也可以从环境变量中读取

export HTSGET_CONFIG="config.toml"

如果没有指定配置文件，则使用默认配置。此外，可以通过传递--print-default-config标志来打印默认配置文件到stdout

cargo run -p htsget-axum -- --print-default-config

使用--help标志可查看有关命令行选项的更多详细信息。

日志格式化

htsget-rs广泛使用Tracing crate来实现日志功能。变量RUST_LOG被读取以配置输出跟踪日志的级别。

例如，以下代码指示所有htsget crate的跟踪级别为info，其他crate的跟踪级别为info

export RUST_LOG='info,htsget_lambda=trace,htsget_lambda=trace,htsget_config=trace,htsget_http=trace,htsget_search=trace,htsget_test=trace'

有关设置此变量的更多信息，请参阅此处。

可以通过设置以下选项来配置日志格式化的风格

有关这些值外观的更多信息，请参阅此处。

使用环境变量配置htsget-rs

所有htsget-rs配置选项都可以通过环境变量设置，这对于AWS Lambda等运行时来说很方便。票据服务器、数据服务器和服务信息选项被扁平化，可以直接使用环境变量设置。不建议使用环境变量设置解析器，但可以通过设置一个包含结构列表的单个环境变量来实现，其中键名和值对用于设置嵌套选项。

环境变量将覆盖配置文件中设置的选项。注意，在环境变量中，数组用[和]分隔，项目用逗号分隔。

以下环境变量（对应于TOML配置）可用

为了使用HTSGET_RESOLVERS，必须设置整个解析器配置数组。可以使用name键和值对设置解析器结构的嵌套数组，例如

export HTSGET_RESOLVERS="[{
    regex=regex,
    substitution_string=substitution_string,
    storage={
        bucket=bucket
    },
    allow_guard={
        allow_reference_names=[chr1],
        allow_fields=[QNAME],
        allow_tags=[RG],
        allow_formats=[BAM],
        allow_classes=[body],
        allow_interval_start=100,
        allow_interval_end=1000
    }  
}]"

类似于data_server选项，可以通过设置等效的环境变量来禁用数据服务器

export HTSGET_DATA_SERVER_ENABLED=false

MinIO

通过利用以下所示的endpoint指令，可以使用本地对象存储MinIO

[[resolvers]]
regex = '.*'
substitution_string = '$0'

[resolvers.storage]
bucket = 'bucket'
endpoint = 'http://127.0.0.1:9000'
path_style = true

必须确保设置了正确的AWS_DEFAULT_REGION、AWS_ACCESS_KEY 和 AWS_SECRET_ACCESS_KEY，以便AWS SDK可以访问端点。使用虚拟主机样式寻址需要配置MinIO服务器，并设置环境变量MINIO_DOMAIN。可以使用path_style = true强制使用路径样式寻址。

有关如何配置htsget-rs和MinIO的更多信息，请参见MinIO部署示例。

作为库

此软件包使用 figment 读取配置文件和环境变量，并使用 clap 接受命令行参数。此功能的主要函数是 from_config，用于获取 Config 结构体。软件包还包含 regex_resolver 抽象，用于通过正则表达式匹配查询 ID，并通过替换字符串进行更改。

功能标志

此软件包具有以下功能

• s3-storage：用于启用 S3Storage 功能。
• url-storage：用于启用 UrlStorage 功能。

许可证

本项目采用 MIT 许可证。