devconfig-gen-singbox 2.0.0__py3-none-any.whl

devconfig_gen/providers/singbox/models.py

@@ -0,0 +1,76 @@
+"""Internal data structures for the sing-box provider.
+
+These types are deliberately small and immutable. They carry the *normalized*
+input (already validated by :mod:`schema`) so that variant plugins only deal
+with their own domain fields and never with raw, untrusted mappings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Sequence
+
+
+@dataclass(frozen=True)
+class ProtocolConfig:
+    """One entry of ``network.protocols`` after normalization.
+
+    ``raw`` is the whole protocol mapping (including ``auth`` / ``tls`` /
+    variant sections). ``path`` is the dotted location used for diagnostics,
+    for example ``network.protocols.0``.
+    """
+
+    type: str
+    enabled: bool
+    port: Optional[int]
+    raw: Mapping[str, Any] = field(default_factory=dict)
+    path: str = "network.protocols.0"
+
+    def section(self, name: str) -> Mapping[str, Any]:
+        """Return a nested mapping section (``auth`` / ``tls`` / ...)."""
+
+        value = self.raw.get(name)
+        return value if isinstance(value, Mapping) else {}
+
+
+@dataclass(frozen=True)
+class NetworkConfig:
+    """Normalized ``network`` section."""
+
+    domain_root: str = ""
+    subdomain_prefixes: Mapping[str, str] = field(default_factory=dict)
+    tunnel_mode: str = "proxy"
+    protocols: Sequence[ProtocolConfig] = ()
+    routing: Mapping[str, Any] = field(default_factory=dict)
+    dns: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Normalized ``client`` section."""
+
+    server_ip: Optional[str] = None
+    fingerprint: str = "chrome"
+
+
+@dataclass(frozen=True)
+class BuildContext:
+    """Everything a plugin needs to build its pieces.
+
+    Plugins receive this instead of reaching into the raw context, which keeps
+    them free of side effects and of knowledge about the surrounding schema.
+    """
+
+    network: NetworkConfig
+    client: ClientConfig
+    hosts: Mapping[str, str]
+    options: Mapping[str, Any] = field(default_factory=dict)
+
+    def host(self, key: str) -> str:
+        """Return the FQDN for a plugin's ``host_key``."""
+
+        return self.hosts.get(key, "")
+
+    @property
+    def fingerprint(self) -> str:
+        return self.client.fingerprint or "chrome"

devconfig_gen/providers/singbox/plugins/__init__.py

@@ -0,0 +1,33 @@
+"""Variant plugin registry.
+
+Adding a protocol means adding one module here plus one line in
+``_PLUGIN_CLASSES``; nothing in ``provider.py`` / ``schema.py`` / ``route.py``
+changes.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .anytls import AnyTlsPlugin
+from .hysteria2 import Hysteria2Plugin
+from .tuic import TuicPlugin
+
+_PLUGIN_CLASSES = (AnyTlsPlugin, TuicPlugin, Hysteria2Plugin)
+
+PLUGINS = {cls.protocol_type: cls() for cls in _PLUGIN_CLASSES}
+
+
+def get_plugin(protocol_type: str) -> Optional[object]:
+    """Return the plugin for ``protocol_type`` or ``None`` when unknown."""
+
+    return PLUGINS.get(str(protocol_type).strip().lower())
+
+
+def protocol_types() -> tuple:
+    """Return the registered protocol type names in registry order."""
+
+    return tuple(PLUGINS)
+
+
+__all__ = ["PLUGINS", "get_plugin", "protocol_types"]

devconfig_gen/providers/singbox/plugins/anytls.py

@@ -0,0 +1,129 @@
+"""AnyTLS (REALITY) variant plugin.
+
+All AnyTLS/REALITY field names live here. Upstream sing-box renames are
+absorbed by editing this module only.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlencode
+
+from ..models import BuildContext, ProtocolConfig
+from .base import (
+    domain_resolver,
+    optional_integer,
+    optional_string,
+    require_string,
+)
+
+DEFAULT_PORT = 23244
+DEFAULT_DECOY_SERVER = "www.cloudflare.com"
+DEFAULT_DECOY_PORT = 443
+
+PADDING_SCHEME = [
+    "stop=8",
+    "0=30-30",
+    "1=100-400",
+    "2=400-500,c,500-1000,c,500-1000,c,500-1000,c,500-1000",
+    "3=9-9,500-1000",
+    "4=500-1000",
+    "5=500-1000",
+    "6=500-1000",
+    "7=500-1000",
+]
+
+
+class AnyTlsPlugin:
+    protocol_type = "anytls"
+    host_key = "reality"
+    inbound_tag = "anytls-in"
+    outbound_tag = "anytls-out"
+    default_port = DEFAULT_PORT
+    sniff_inbound = True
+
+    def validate(self, cfg: ProtocolConfig, errors: list) -> None:
+        require_string(cfg, "auth.password", errors)
+        require_string(cfg, "reality.private_key", errors)
+        require_string(cfg, "reality.public_key", errors)
+        require_string(cfg, "reality.short_id", errors)
+        optional_string(cfg, "reality.decoy_server", errors, default=DEFAULT_DECOY_SERVER)
+        optional_integer(
+            cfg, "reality.decoy_port", errors, default=DEFAULT_DECOY_PORT, minimum=1, maximum=65535
+        )
+
+    def _port(self, cfg: ProtocolConfig) -> int:
+        return cfg.port if cfg.port is not None else DEFAULT_PORT
+
+    def _decoy(self, cfg: ProtocolConfig) -> tuple:
+        server = optional_string(cfg, "reality.decoy_server", [], default=DEFAULT_DECOY_SERVER)
+        port = optional_integer(
+            cfg, "reality.decoy_port", [], default=DEFAULT_DECOY_PORT, minimum=1, maximum=65535
+        )
+        return server, port
+
+    def build_server_inbound(self, cfg: ProtocolConfig, ctx: BuildContext) -> dict:
+        password = require_string(cfg, "auth.password", [], default="")
+        private_key = require_string(cfg, "reality.private_key", [], default="")
+        short_id = require_string(cfg, "reality.short_id", [], default="")
+        decoy_server, decoy_port = self._decoy(cfg)
+        return {
+            "type": "anytls",
+            "tag": self.inbound_tag,
+            "listen": "::",
+            "listen_port": self._port(cfg),
+            "users": [{"name": "user", "password": password}],
+            "padding_scheme": list(PADDING_SCHEME),
+            "tls": {
+                "enabled": True,
+                "server_name": decoy_server,
+                "reality": {
+                    "enabled": True,
+                    "handshake": {
+                        "server": decoy_server,
+                        "server_port": decoy_port,
+                    },
+                    "private_key": private_key,
+                    "short_id": short_id,
+                },
+            },
+        }
+
+    def build_client_outbound(self, cfg: ProtocolConfig, ctx: BuildContext) -> dict:
+        password = require_string(cfg, "auth.password", [], default="")
+        public_key = require_string(cfg, "reality.public_key", [], default="")
+        short_id = require_string(cfg, "reality.short_id", [], default="")
+        decoy_server, _ = self._decoy(cfg)
+        return {
+            "type": "anytls",
+            "tag": self.outbound_tag,
+            "server": ctx.host(self.host_key),
+            "domain_resolver": domain_resolver(),
+            "server_port": self._port(cfg),
+            "tls": {
+                "enabled": True,
+                "server_name": decoy_server,
+                "utls": {"enabled": True, "fingerprint": ctx.fingerprint},
+                "reality": {
+                    "enabled": True,
+                    "public_key": public_key,
+                    "short_id": short_id,
+                },
+            },
+            "password": password,
+        }
+
+    def build_share_link(self, cfg: ProtocolConfig, ctx: BuildContext) -> str:
+        password = require_string(cfg, "auth.password", [], default="")
+        public_key = require_string(cfg, "reality.public_key", [], default="")
+        short_id = require_string(cfg, "reality.short_id", [], default="")
+        decoy_server, _ = self._decoy(cfg)
+        params = urlencode(
+            {
+                "security": "reality",
+                "sni": decoy_server,
+                "fp": ctx.fingerprint,
+                "pbk": public_key,
+                "sid": short_id,
+            }
+        )
+        return f"anytls://{password}@{ctx.host(self.host_key)}:{self._port(cfg)}?{params}#AnyTLS"

devconfig_gen/providers/singbox/plugins/base.py

@@ -0,0 +1,117 @@
+"""Plugin contract and shared helpers for sing-box protocol variants.
+
+A variant plugin owns *all* domain detail for one protocol: the exact inbound
+and outbound field names, the share-link format, and the variant-specific
+validation rules. The rest of the provider (``provider.py`` / ``schema.py`` /
+``route.py``) never mentions a variant name, so an upstream sing-box change is
+absorbed by editing a single file here plus the registry.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Protocol
+
+from ....validation import expect_integer, expect_string
+from ..models import BuildContext, ProtocolConfig
+
+
+class ProtocolPlugin(Protocol):
+    """Structural contract every variant plugin implements."""
+
+    protocol_type: str
+    host_key: str
+    inbound_tag: str
+    outbound_tag: str
+    default_port: int
+
+    def validate(self, cfg: ProtocolConfig, errors: list) -> None:
+        ...
+
+    def build_server_inbound(self, cfg: ProtocolConfig, ctx: BuildContext) -> dict:
+        ...
+
+    def build_client_outbound(self, cfg: ProtocolConfig, ctx: BuildContext) -> dict:
+        ...
+
+    def build_share_link(self, cfg: ProtocolConfig, ctx: BuildContext) -> str:
+        ...
+
+
+def dig(source: Mapping[str, Any], path: str) -> Any:
+    """Read a dotted path from a mapping, returning ``None`` when absent."""
+
+    current: Any = source
+    for part in path.split("."):
+        if not isinstance(current, Mapping):
+            return None
+        current = current.get(part)
+    return current
+
+
+def field_path(cfg: ProtocolConfig, relative: str) -> str:
+    return f"{cfg.path}.{relative}" if relative else cfg.path
+
+
+def require_string(
+    cfg: ProtocolConfig,
+    relative: str,
+    errors: list,
+    *,
+    default: Optional[str] = None,
+) -> Optional[str]:
+    """Validate a required string field, falling back to ``default``."""
+
+    value = dig(cfg.raw, relative)
+    if value is None and default is not None:
+        return default
+    result = expect_string(value, field_path(cfg, relative), errors)
+    return result if result is not None else default
+
+
+def optional_string(
+    cfg: ProtocolConfig,
+    relative: str,
+    errors: list,
+    *,
+    default: Optional[str] = None,
+) -> Optional[str]:
+    """Validate a string field only when it is present."""
+
+    value = dig(cfg.raw, relative)
+    if value is None:
+        return default
+    result = expect_string(value, field_path(cfg, relative), errors)
+    return result if result is not None else default
+
+
+def optional_integer(
+    cfg: ProtocolConfig,
+    relative: str,
+    errors: list,
+    *,
+    default: Optional[int] = None,
+    minimum: Optional[int] = None,
+    maximum: Optional[int] = None,
+) -> Optional[int]:
+    """Validate an integer field only when it is present."""
+
+    value = dig(cfg.raw, relative)
+    if value is None:
+        return default
+    result = expect_integer(
+        value,
+        field_path(cfg, relative),
+        errors,
+        minimum=minimum,
+        maximum=maximum,
+    )
+    return result if result is not None else default
+
+
+DIRECT_DNS_TAG = "dns-direct"
+
+
+def domain_resolver(server_tag: str = DIRECT_DNS_TAG) -> dict:
+    """Domain resolver shared by every client outbound."""
+
+    return {"server": server_tag, "strategy": "prefer_ipv4"}

devconfig_gen/providers/singbox/plugins/hysteria2.py

@@ -0,0 +1,110 @@
+"""Hysteria2 variant plugin.
+
+All Hysteria2 field names live here. Upstream sing-box renames are absorbed by
+editing this module only.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlencode
+
+from ..models import BuildContext, ProtocolConfig
+from .base import domain_resolver, optional_integer, optional_string, require_string
+
+DEFAULT_PORT = 7443
+DEFAULT_MASQUERADE = "https://www.cloudflare.com"
+DEFAULT_SERVER_UP_MBPS = 500
+DEFAULT_SERVER_DOWN_MBPS = 500
+DEFAULT_CLIENT_UP_MBPS = 50
+DEFAULT_CLIENT_DOWN_MBPS = 200
+
+
+class Hysteria2Plugin:
+    protocol_type = "hysteria2"
+    host_key = "hy2"
+    inbound_tag = "hy2-in"
+    outbound_tag = "hy2-out"
+    default_port = DEFAULT_PORT
+    sniff_inbound = False
+
+    def validate(self, cfg: ProtocolConfig, errors: list) -> None:
+        require_string(cfg, "auth.password", errors)
+        require_string(cfg, "auth.obfs_password", errors)
+        require_string(cfg, "tls.cert_path", errors)
+        require_string(cfg, "tls.key_path", errors)
+        optional_integer(cfg, "bandwidth.up_mbps", errors, minimum=1)
+        optional_integer(cfg, "bandwidth.down_mbps", errors, minimum=1)
+        optional_string(cfg, "masquerade", errors, default=DEFAULT_MASQUERADE)
+
+    def _port(self, cfg: ProtocolConfig) -> int:
+        return cfg.port if cfg.port is not None else DEFAULT_PORT
+
+    def _obfs(self, cfg: ProtocolConfig) -> dict:
+        return {
+            "type": "salamander",
+            "password": require_string(cfg, "auth.obfs_password", [], default=""),
+        }
+
+    def build_server_inbound(self, cfg: ProtocolConfig, ctx: BuildContext) -> dict:
+        up = optional_integer(cfg, "bandwidth.up_mbps", [], default=DEFAULT_SERVER_UP_MBPS, minimum=1)
+        down = optional_integer(
+            cfg, "bandwidth.down_mbps", [], default=DEFAULT_SERVER_DOWN_MBPS, minimum=1
+        )
+        cert_path = require_string(cfg, "tls.cert_path", [], default="")
+        key_path = require_string(cfg, "tls.key_path", [], default="")
+        masquerade = optional_string(cfg, "masquerade", [], default=DEFAULT_MASQUERADE)
+        return {
+            "type": "hysteria2",
+            "tag": self.inbound_tag,
+            "listen": "::",
+            "listen_port": self._port(cfg),
+            "users": [{"password": require_string(cfg, "auth.password", [], default="")}],
+            "ignore_client_bandwidth": False,
+            "up_mbps": up,
+            "down_mbps": down,
+            "obfs": self._obfs(cfg),
+            "masquerade": masquerade,
+            "tls": {
+                "enabled": True,
+                "server_name": ctx.host(self.host_key),
+                "alpn": ["h3"],
+                "certificate_path": cert_path,
+                "key_path": key_path,
+            },
+        }
+
+    def build_client_outbound(self, cfg: ProtocolConfig, ctx: BuildContext) -> dict:
+        up = optional_integer(cfg, "bandwidth.up_mbps", [], default=DEFAULT_CLIENT_UP_MBPS, minimum=1)
+        down = optional_integer(
+            cfg, "bandwidth.down_mbps", [], default=DEFAULT_CLIENT_DOWN_MBPS, minimum=1
+        )
+        return {
+            "type": "hysteria2",
+            "tag": self.outbound_tag,
+            "server": ctx.host(self.host_key),
+            "domain_resolver": domain_resolver(),
+            "server_port": self._port(cfg),
+            "up_mbps": up,
+            "down_mbps": down,
+            "obfs": self._obfs(cfg),
+            "password": require_string(cfg, "auth.password", [], default=""),
+            "tls": {
+                "enabled": True,
+                "server_name": ctx.host(self.host_key),
+                "alpn": ["h3"],
+            },
+        }
+
+    def build_share_link(self, cfg: ProtocolConfig, ctx: BuildContext) -> str:
+        host = ctx.host(self.host_key)
+        params = urlencode(
+            {
+                "obfs": "salamander",
+                "obfs-password": require_string(cfg, "auth.obfs_password", [], default=""),
+                "sni": host,
+            }
+        )
+        return (
+            f"hy2://{require_string(cfg, 'auth.password', [], default='')}"
+            f"@{host}:{self._port(cfg)}?{params}#Hysteria2"
+        )

devconfig_gen/providers/singbox/plugins/tuic.py

@@ -0,0 +1,90 @@
+"""TUIC variant plugin.
+
+All TUIC field names live here. Upstream sing-box renames are absorbed by
+editing this module only.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlencode
+
+from ..models import BuildContext, ProtocolConfig
+from .base import domain_resolver, require_string
+
+DEFAULT_PORT = 9443
+
+
+class TuicPlugin:
+    protocol_type = "tuic"
+    host_key = "tuic"
+    inbound_tag = "tuic-in"
+    outbound_tag = "tuic-out"
+    default_port = DEFAULT_PORT
+    sniff_inbound = False
+
+    def validate(self, cfg: ProtocolConfig, errors: list) -> None:
+        require_string(cfg, "auth.uuid", errors)
+        require_string(cfg, "auth.password", errors)
+        require_string(cfg, "tls.cert_path", errors)
+        require_string(cfg, "tls.key_path", errors)
+
+    def _port(self, cfg: ProtocolConfig) -> int:
+        return cfg.port if cfg.port is not None else DEFAULT_PORT
+
+    def build_server_inbound(self, cfg: ProtocolConfig, ctx: BuildContext) -> dict:
+        uuid = require_string(cfg, "auth.uuid", [], default="")
+        password = require_string(cfg, "auth.password", [], default="")
+        cert_path = require_string(cfg, "tls.cert_path", [], default="")
+        key_path = require_string(cfg, "tls.key_path", [], default="")
+        return {
+            "type": "tuic",
+            "tag": self.inbound_tag,
+            "listen": "::",
+            "listen_port": self._port(cfg),
+            "users": [{"uuid": uuid, "password": password}],
+            "congestion_control": "bbr",
+            "zero_rtt_handshake": False,
+            "heartbeat": "10s",
+            "tls": {
+                "enabled": True,
+                "server_name": ctx.host(self.host_key),
+                "alpn": ["h3"],
+                "certificate_path": cert_path,
+                "key_path": key_path,
+            },
+        }
+
+    def build_client_outbound(self, cfg: ProtocolConfig, ctx: BuildContext) -> dict:
+        uuid = require_string(cfg, "auth.uuid", [], default="")
+        password = require_string(cfg, "auth.password", [], default="")
+        return {
+            "type": "tuic",
+            "tag": self.outbound_tag,
+            "server": ctx.host(self.host_key),
+            "domain_resolver": domain_resolver(),
+            "server_port": self._port(cfg),
+            "uuid": uuid,
+            "password": password,
+            "congestion_control": "bbr",
+            "udp_relay_mode": "native",
+            "zero_rtt_handshake": False,
+            "heartbeat": "10s",
+            "tls": {
+                "enabled": True,
+                "server_name": ctx.host(self.host_key),
+                "alpn": ["h3"],
+            },
+        }
+
+    def build_share_link(self, cfg: ProtocolConfig, ctx: BuildContext) -> str:
+        uuid = require_string(cfg, "auth.uuid", [], default="")
+        password = require_string(cfg, "auth.password", [], default="")
+        host = ctx.host(self.host_key)
+        params = urlencode(
+            {
+                "congestion_control": "bbr",
+                "udp_relay_mode": "quic",
+                "sni": host,
+            }
+        )
+        return f"tuic://{uuid}:{password}@{host}:{self._port(cfg)}?{params}#TUIC"