bookclerk_plugin_manifest::setting_network

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Network destinations named by plugin settings.

A [[settings]] entry may declare network = "fetch" (its value is a URL) or network = "tcp" (its value is host:port). The host turns the value an operator saved into one SettingDestination with derive_setting_destination, lists it on the consent form with the setting as its source, and adds it to the plugin's egress policy only once the operator approved that exact destination.

The value is untrusted text (an operator typed it, or a plugin's own default supplied it), so derivation is a pure function over the string and is fuzzed (fuzz/fuzz_targets/setting_destination.rs).

Item Kind Summary
SettingDestination struct The one network destination a setting's value names.
DestinationScope enum What kind of address a setting's host is, which decides how the grant reaches it.
SettingDestinationError enum Why a setting value names no usable destination.
derive_setting_destination function Derives the destination a network setting's value names.

Structs

SettingDestination

pub struct SettingDestination {
    pub network: SettingNetwork,
    pub host: String,
    pub port: u16,
    pub tls: bool,
    pub scope: DestinationScope,
}

The one network destination a setting's value names.

Fields

  • network: Whether the plugin fetches it or opens a raw socket to it.
  • host: The host: an IDNA-normalized name, or a canonical IP literal (IPv6 without brackets, IPv4-mapped IPv6 unwrapped).
  • port: The port, 1-65535: the value's own, else the setting's default_port, else the URL scheme's.
  • tls: True for an https fetch, whose certificate is verified; false for plain HTTP and raw TCP, which trust the resolver.
  • scope: What kind of address Self::host is.

SettingDestination::domain_entry

pub fn domain_entry(&self) -> Option<String>

The domains entry a fetch destination adds (host:port), or None for a TCP destination.

SettingDestination::tcp_grant

pub fn tcp_grant(&self) -> Option<TcpGrant>

The TCP grant a TCP destination adds, or None for a fetch.

SettingDestination::local_name

pub fn local_name(&self) -> Option<String>

The crate::EgressPolicy::local_names entry this destination adds: its name, or its local-network address. None for a public or restricted address.

SettingDestination::display

pub fn display(&self) -> String

How the destination reads on the consent form and in logs: https://abs.home.lan:13378 for a fetch, db.home.lan:5432 for TCP.

Implements: Clone, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize

Enums

DestinationScope

pub enum DestinationScope {
    Name,
    PublicAddress,
    LocalAddress,
    Restricted,
}

What kind of address a setting's host is, which decides how the grant reaches it.

Variants

  • Name: A host name. It may resolve to a public address, or to a local-network address (RFC 1918, shared CGNAT space, IPv6 ULA) for this name only.
  • PublicAddress: A public IP literal.
  • LocalAddress: A local-network IP literal; the grant reaches exactly that address.
  • Restricted: Loopback, link-local (cloud metadata), another special address, or a restricted name such as localhost. The destination is listed, but the connection still needs an address grant the operator adds explicitly.

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize

SettingDestinationError

pub enum SettingDestinationError {
    Empty,
    Malformed,
    Scheme,
    Credentials,
    Host,
    Port,
}

Why a setting value names no usable destination.

Variants

  • Empty: The value is empty: the setting names no destination.
  • Malformed: Longer than a setting value may be, or holds whitespace or control characters.
  • Scheme: A fetch URL whose scheme is not http or https.
  • Credentials: The value carries a user name or password; credentials belong in a secret setting.
  • Host: The host is missing, a wildcard, percent-encoded or not a valid name.
  • Port: The port is missing (a bare tcp host without default_port), zero or not a number.

Implements: Clone, Copy, Debug, Display, Eq, Error, PartialEq

Functions

derive_setting_destination

pub fn derive_setting_destination(
    network: SettingNetwork,
    default_port: Option<u16>,
    value: &str,
) -> Result<SettingDestination, SettingDestinationError>

Derives the destination a network setting's value names.

  • fetch: an http:// or https:// URL; a value without :// is read as https://<value>. The port is the URL's own, else default_port for a bare value, else the scheme's (80 or 443). Paths and queries are ignored.
  • tcp: host:port, [v6]:port, a bare host (port from default_port), or a URL of any scheme (its host and port, else default_port), so a postgres://db:5432/x value works.

A user name or password anywhere is refused, and so is a wildcard host.

Arguments

  • network - The setting's declared SettingNetwork.
  • default_port - The setting's declared default_port.
  • value - The saved value (surrounding whitespace is ignored).

Returns

The normalized destination.

Errors

SettingDestinationError naming the first problem.

Examples

use bookclerk_plugin_abi::SettingNetwork;
use bookclerk_plugin_manifest::{derive_setting_destination, DestinationScope};

let abs = derive_setting_destination(SettingNetwork::Fetch, None, "http://ABS.home.lan:13378/")
    .unwrap();
assert_eq!(abs.domain_entry().as_deref(), Some("abs.home.lan:13378"));
assert_eq!(abs.scope, DestinationScope::Name);

let db = derive_setting_destination(SettingNetwork::Tcp, Some(5432), "192.168.1.5").unwrap();
assert_eq!(db.display(), "192.168.1.5:5432");
assert_eq!(db.scope, DestinationScope::LocalAddress);

Generated from crates/bookclerk-plugin-manifest at main · View as Markdown