tor-config

Arti配置管理的工具

概述

此crate是Arti项目的一部分，该项目旨在使用Rust实现Tor。

它提供处理配置值的类型，以及配置管理的一般机制。

Arti中的配置

arti命令行程序和其他嵌入Arti并重用配置机制的程序配置如下

1. 我们使用tor_config::ConfigurationSources来列出配置信息需要从哪些地方获取，以及如何读取它们。arti使用ConfigurationSources::from_cmdline。

2. ConfigurationSources::load实际上读取所有这些来源，解析它们（例如，作为TOML文件），并返回一个ConfigurationTree。这是一个树状动态类型数据结构，反映了输入配置结构，基本上未经验证，包含输入配置来源中的所有内容。

3. 我们调用tor_config::resolve家族中的一个。这会将输入配置数据映射到程序中配置消费者具体的ConfigBuilder 。对于arti，这是TorClientConfigBuilder和ArtiBuilder。这种映射是通过在Builder上使用Deserialize实现完成的。resolve接着在配置的每个部分上调用build()方法，这会应用默认值并验证产生的配置。

   对于所有配置消费者，重要的一点是只调用一次resolve，这样它可以看到输入中未识别的配置设置，因此可能需要向用户报告。请参阅load模块文档中的示例。

4. 产生的配置对象（例如，TorClientConfig，ArtiConfig）将提供给必须使用它们的代码（例如，创建一个TorClient）。

请参阅tor_config::load模块级文档以获取示例。

特定情况的设施和方法

列表

当配置包含用户可能希望逐个添加条目、修改、过滤等的项列表时，请使用[list_builder]模块中的列表构建器辅助工具。

条件编译的配置项

如果用户通过配置请求了一个编译时被排除（由于未选择cargo功能）的功能，通常最好是让代码简单地忽略它。

这可以通过对配置字段和结构体应用适当的#[cfg]来实现。结果是，如果用户确实指定了相关选项，Arti将生成一个“未知配置项”警告。（在未来，提供缺失的功能消息可能是个好主意。）

即使编译时被排除，也必须检测并拒绝的配置项

例如，如果Arti没有编译桥接支持，指定使用桥接的配置应导致失败，而不是直接连接。

在这些情况下，您应该无条件地包含必须检测和拒绝的配置字段。

然后为这些字段提供替代的“编译时排除”类型的版本。（如果字段是一个列表，当启用时使用list_builder，提供替代的“编译时排除”版本的entry类型。）

配置的构建形式（在列表的情况下是Field或Entry），应该是一个空的枚举，带有#[non_exhaustive]注释。它应该实现与编译内版本相同的所有标准特质。所以一切都会编译。但是，由于它是一个未占用类型，这样的值永远不会真正出现。

构建器表单（FieldBuilder 或 EntryBuilder）应为一个空的 #[non_exhaustive] 结构体。它应该有一个平凡的 Deserialize 实现，总是成功返回，以及一个派生的 Serialize 实现（以及常规特质）。这将允许识别尝试指定此类值的配置。

为了使代码编译，当然，构建器将必须有一个 .build() 方法。这个方法应该返回 ConfigBuildError::Invalid。 （显然不能返回未居住的构建类型。）配置解析安排被设置为调用此方法，并将报告错误。

例如，请参阅 crates/tor-guardmgr/src/bridge_disabled.rs。

许可证：MIT OR Apache-2.0