configs

configs

Shared configuration models for BigBrotr services.

Provides Pydantic models for managing per-network settings (clearnet, Tor, I2P, Lokinet). Each network type has its own config class with sensible defaults, allowing partial YAML overrides (e.g., setting only tor.enabled: true inherits the default proxy_url).

The network type is determined by the NetworkType enum, and the relay's network is auto-detected from its URL scheme and hostname by the Relay model.

Attributes:

• enabled –

  Whether to process relays on this network.

• proxy_url –

  SOCKS5 proxy URL for overlay networks.

• max_tasks –

  Maximum concurrent connections.

• timeout –

  Connection timeout in seconds.

See Also

NetworkType: Enum that identifies each overlay network. NetworkSemaphoresMixin: Uses max_tasks to create per-network concurrency semaphores. ValidatorConfig, MonitorConfig, SynchronizerConfig: Service configs that embed NetworksConfig.

Examples:

networks:
  clearnet:
    enabled: true
    max_tasks: 100
  tor:
    enabled: true  # Inherits default proxy_url

Classes

ClearnetConfig

Bases: BaseModel

Configuration for clearnet (standard internet) relays.

Direct connections without a proxy. Supports high concurrency with short timeouts.

See Also

NetworkType.CLEARNET: The enum member this config maps to.

TorConfig

Bases: BaseModel

Configuration for Tor (.onion) relays.

Requires a SOCKS5 proxy. Lower concurrency and longer timeouts due to Tor network latency.

See Also

NetworkType.TOR: The enum member this config maps to.

I2pConfig

Bases: BaseModel

Configuration for I2P (.i2p) relays.

Requires a SOCKS5 proxy. Lowest concurrency and longest timeouts due to I2P network latency.

See Also

NetworkType.I2P: The enum member this config maps to.

LokiConfig

Bases: BaseModel

Configuration for Lokinet (.loki) relays.

Requires a SOCKS5 proxy.

Warning

Lokinet is only supported on Linux. Enabling this config on macOS or Windows will result in connection failures.

See Also

NetworkType.LOKI: The enum member this config maps to.

NetworksConfig

Bases: BaseModel

Unified network configuration container for all BigBrotr services.

Aggregates per-network settings with convenience methods for querying enabled state, proxy URLs, and network-specific configs. Designed to be embedded in service configuration models such as ValidatorConfig, MonitorConfig, and SynchronizerConfig.

See Also

NetworkSemaphoresMixin: Creates per-network asyncio.Semaphore instances from max_tasks values in this config. NetworkType: Enum used as lookup keys in get(), is_enabled(), and get_proxy_url().

Examples:

config = NetworksConfig(tor=TorConfig(enabled=True))
config.is_enabled(NetworkType.TOR)  # True
config.get_proxy_url(NetworkType.TOR)  # 'socks5://tor:9050'
config.get_enabled_networks()  # ['clearnet', 'tor']

Functions

get

get(network: NetworkType) -> NetworkTypeConfig

Get configuration for a specific network type.

Parameters:

• network (NetworkType) –

  The NetworkType enum value to look up.

Returns:

• NetworkTypeConfig –

  The configuration for the specified network.

• NetworkTypeConfig –

  Falls back to clearnet config if network is not found.

Source code in src/bigbrotr/services/common/configs.py

def get(self, network: NetworkType) -> NetworkTypeConfig:
    """Get configuration for a specific network type.

    Args:
        network: The [NetworkType][bigbrotr.models.constants.NetworkType]
            enum value to look up.

    Returns:
        The configuration for the specified network.
        Falls back to clearnet config if network is not found.
    """
    config: NetworkTypeConfig | None = getattr(self, network.value, None)
    if config is None:
        logger.warning("no config for network=%s, falling back to clearnet", network.value)
        return self.clearnet
    return config

get_proxy_url

get_proxy_url(network: NetworkType) -> str | None

Get the SOCKS5 proxy URL for a network type.

Returns the proxy URL only if the network is enabled and has a configured proxy. Clearnet always returns None.

Parameters:

• network (NetworkType) –

  The NetworkType enum value to look up.

Returns:

• str | None –

  The SOCKS5 proxy URL if enabled and configured, None otherwise.

Note

Used by connect_relay and is_nostr_relay to route overlay-network connections through SOCKS5 proxies.

Source code in src/bigbrotr/services/common/configs.py

def get_proxy_url(self, network: NetworkType) -> str | None:
    """Get the SOCKS5 proxy URL for a network type.

    Returns the proxy URL only if the network is enabled and has a
    configured proxy. Clearnet always returns ``None``.

    Args:
        network: The [NetworkType][bigbrotr.models.constants.NetworkType]
            enum value to look up.

    Returns:
        The SOCKS5 proxy URL if enabled and configured, ``None`` otherwise.

    Note:
        Used by [connect_relay][bigbrotr.utils.protocol.connect_relay]
        and [is_nostr_relay][bigbrotr.utils.protocol.is_nostr_relay]
        to route overlay-network connections through SOCKS5 proxies.
    """
    if network == NetworkType.CLEARNET:
        return None

    config = self.get(network)
    return config.proxy_url if config.enabled else None

is_enabled

is_enabled(network: NetworkType) -> bool

Check if processing is enabled for a network type.

Parameters:

• network (NetworkType) –

  The NetworkType enum value to look up.

Returns:

• bool –

  True if the network is enabled, False otherwise.

Source code in src/bigbrotr/services/common/configs.py

def is_enabled(self, network: NetworkType) -> bool:
    """Check if processing is enabled for a network type.

    Args:
        network: The [NetworkType][bigbrotr.models.constants.NetworkType]
            enum value to look up.

    Returns:
        True if the network is enabled, False otherwise.
    """
    return self.get(network).enabled

get_enabled_networks

get_enabled_networks() -> list[str]

Get a list of all enabled network type names.

Returns:

• list[str] –

  Names of enabled networks (order matches field definition).

Source code in src/bigbrotr/services/common/configs.py

def get_enabled_networks(self) -> list[str]:
    """Get a list of all enabled network type names.

    Returns:
        Names of enabled networks (order matches field definition).
    """
    return [name for name in type(self).model_fields if getattr(self, name).enabled]