Struct SetConfig 

pub(super) struct SetConfig {
    key: String,
    value: ConfigValue,
}

Change the value of a part of the configuration tree.

This method requires superuser capability, since it affects all Arti sessions.

Semantics

Arti takes its configuration from the following sources:

1. A set of default values
2. Configuration files on disk
3. Command-line configuration arguments
4. Options provided via RPC

These sources are applied in order, with later options possibly overriding earlier ones. (When a set of options is stored in a map, the maps are merged, with the later map getting precedence.) The set of options forms a tree. In the RPC system, we represent this tree as a JSON Object.

TODO: Explain all of this more clearly.

This RPC method lets you change the set of options provided via RPC. (source 4 in the list above).

When you use this method, it replaces part the the RPC configuration options at the path in the tree represented by key with the provided value.

Error behavior

This method will fail if:

• Any provided option is invalid
• The transition from the current set of options to the new set is not allowed
• Or something goes wrong when trying to transition.

If this method fails, and the configuration will (if possible¹) stay in its original state, and the method will return an error.

The current error type contains no machine-readable elements describing how it failed; we do intend to add some in the future.

NOTE: This method currently will not fail for any unrecognized options. We will, later, add options to require only recognized options, or to list unrecognized options.

Examples

Setting a single option

This invocation will disable client connections to “local” addresses over the Tor network. It will override any value for this option set in any other configuration source.

{ "key": "address_filter.allow_local_addrs", "value": false }

Setting several options at a given path.

This invocation will disable client connections to local addresses.

This replaces the whole sub-tree of RPC-provided options at address_filter. Therefore, if there are any other RPC-provided options for address_filter.*, this invocation will remove them.

We might add optional “merge” semantics (instead of replace) in the future.

{ "key": "address_filter",
  "value": { "allow_local_addrs": false } }

Clearing all RPC-provided options

This invocation will restore the configuration to the state of having no RPC-provided options:

{ "key": '', "value": {} }

It works by replacing the root of the RPC option tree with an empty Object, so that only options from the other sources will remain.

---

1. If arti can reject the configuration changes before it starts trying to apply them, we guarantee that the configuration will stay in its original state. Otherwise, arti will try its best to apply configuration changes on an all-or-nothing basis, but bugs or system limitations may prevent this from working completely. ↩

Fields

key: String

A path in the RPC configuration tree to override.

This path is either the empty string, or a sequence of period-separated configuration identifiers. The root of the tree can be represented as “.” or as “”.

No validation is done to ensure that the identifiers are actually a recognized configuration option.

value: ConfigValue

A value to replace part of the RPC configuration tree.

See the method description for an overview of the semantics of the RPC configuration tree. Notably, this method replaces parts of the RPC configuration tree, and the RPC configuration tree is merged into the configuration from other sources.

Trait Implementations

impl Debug for SetConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DeserMethod for SetConfig

fn upcast_box(self: Box<Self>) -> Box<dyn DynMethod>

Up-cast to a Box<dyn DynMethod>.

impl<'de> Deserialize<'de> for SetConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl DynMethod for SetConfig

fn invoke_without_dispatch( &self, ctx: Arc<dyn Context>, obj_id: &ObjectId, ) -> Result<Pin<Box<dyn Future<Output = Result<Box<dyn Serialize + Send>, RpcError>> + Send>>, InvokeError>

Try to invoke a method while bypassing the regular RPC method dispatch system.

fn is_cancellable(&self) -> bool

Return true if this method is safe to cancel.

impl RpcMethod for SetConfig

type Output = Nil

A type returned by this method on success.

type Update = NoUpdates

A type sent by this method on updates.