linksocks 3.0.13__cp39-cp39-macosx_13_0_x86_64.whl

linksocks/__init__.py

@@ -0,0 +1,9 @@
+"""linksocks: SOCKS5 over WebSocket proxy library."""
+
+__version__ = "3.0.13"
+
+from ._server import Server
+from ._client import Client
+from ._base import ReverseTokenResult, set_log_level
+
+__all__ = ["Server", "Client", "ReverseTokenResult", "set_log_level"]

linksocks/_base.py

@@ -0,0 +1,230 @@
+"""
+Base classes and utilities for linksocks.
+
+This module contains shared functionality used by Server and Client classes.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import asyncio
+from dataclasses import dataclass
+import threading
+import time
+from datetime import timedelta
+from typing import Any, Callable, Dict, Iterable, Optional, Tuple, Union, List
+
+# Underlying Go bindings module (generated)
+from linksockslib import linksocks # type: ignore
+
+_logger = logging.getLogger(__name__)
+
+# Type aliases
+DurationLike = Union[int, float, timedelta, str]
+
+
+def _snake_to_camel(name: str) -> str:
+    """Convert snake_case to CamelCase."""
+    parts = name.split("_")
+    return "".join(p.capitalize() for p in parts if p)
+
+
+def _camel_to_snake(name: str) -> str:
+    """Convert CamelCase to snake_case."""
+    out: List[str] = []
+    for ch in name:
+        if ch.isupper() and out:
+            out.append("_")
+        out.append(ch.lower())
+    return "".join(out)
+
+
+def _to_duration(value: Optional[DurationLike]) -> Any:
+    """Convert seconds/str/timedelta to Go time.Duration via bindings.
+    
+    - None -> 0
+    - int/float -> seconds (supports fractions)
+    - timedelta -> total seconds
+    - str -> parsed by Go (e.g., "1.5s", "300ms")
+    """
+    if value is None:
+        return 0
+    if isinstance(value, timedelta):
+        seconds = value.total_seconds()
+        return seconds * linksocks.Second()
+    if isinstance(value, (int, float)):
+        return value * linksocks.Second()
+    if isinstance(value, str):
+        try:
+            return linksocks.ParseDuration(value)
+        except Exception as exc:
+            raise ValueError(f"Invalid duration string: {value}") from exc
+    raise TypeError(f"Unsupported duration type: {type(value)!r}")
+
+
+# Shared Go->Python log dispatcher
+_def_level_map = {
+    "trace": logging.DEBUG,
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warn": logging.WARNING,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+    "fatal": logging.CRITICAL,
+    "panic": logging.CRITICAL,
+}
+
+
+def _emit_go_log(py_logger: logging.Logger, line: str) -> None:
+    """Process a Go log line and emit it to the Python logger."""
+    try:
+        obj = json.loads(line)
+    except Exception:
+        py_logger.info(line)
+        return
+    level = str(obj.get("level", "")).lower()
+    message = obj.get("message") or obj.get("msg") or ""
+    extras: Dict[str, Any] = {}
+    for k, v in obj.items():
+        if k in ("level", "time", "message", "msg"):
+            continue
+        extras[k] = v
+    py_logger.log(_def_level_map.get(level, logging.INFO), message, extra={"go": extras})
+
+
+# Global registry for logger instances
+_logger_registry: Dict[str, logging.Logger] = {}
+
+# Event-driven log monitoring system
+_log_listeners: List[Callable[[List], None]] = []
+_listener_thread: Optional[threading.Thread] = None
+_listener_active: bool = False
+
+
+def _start_log_listener() -> None:
+    """Start background thread to drain Go log buffer and forward to Python loggers."""
+    global _listener_thread, _listener_active
+    if _listener_active and _listener_thread and _listener_thread.is_alive():
+        return
+    _listener_active = True
+
+    def _run() -> None:
+        # Drain loop: wait for entries with timeout to allow graceful shutdown
+        while _listener_active:
+            try:
+                entries = linksocks.WaitForLogEntries(2000)  # wait up to 2s
+            except Exception:
+                # Backoff on unexpected errors to avoid busy loop
+                time.sleep(0.2)
+                continue
+
+            if not entries:
+                continue
+
+            # Iterate returned entries; handle both attr and dict styles
+            for entry in entries:
+                try:
+                    logger_id = getattr(entry, "LoggerID", None)
+                    if logger_id is None and isinstance(entry, dict):
+                        logger_id = entry.get("LoggerID")
+
+                    message = getattr(entry, "Message", None)
+                    if message is None and isinstance(entry, dict):
+                        message = entry.get("Message")
+
+                    if not message:
+                        continue
+
+                    py_logger = _logger_registry.get(str(logger_id)) or _logger
+                    _emit_go_log(py_logger, str(message))
+                except Exception:
+                    # Never let logging path crash the listener
+                    continue
+
+    _listener_thread = threading.Thread(target=_run, name="linksocks-go-log-listener", daemon=True)
+    _listener_thread.start()
+
+
+def _stop_log_listener() -> None:
+    """Stop the background log listener thread."""
+    global _listener_active
+    _listener_active = False
+    try:
+        # Unblock WaitForLogEntries callers
+        linksocks.CancelLogWaiters()
+    except Exception:
+        pass
+
+
+class BufferZerologLogger:
+    """Buffer-based logger system for Go bindings."""
+    
+    def __init__(self, py_logger: logging.Logger, logger_id: str):
+        self.py_logger = py_logger
+        self.logger_id = logger_id
+        # Ensure background listener is running
+        _start_log_listener()
+
+        # Prefer Go logger with explicit ID so we can map entries back
+        try:
+            # Newer binding that tags entries with our provided ID
+            self.go_logger = linksocks.NewLoggerWithID(self.logger_id)
+        except Exception:
+            # Fallback to older API; if present, still try callback path
+            try:
+                def log_callback(line: str) -> None:
+                    _emit_go_log(py_logger, line)
+
+                self.go_logger = linksocks.NewLogger(log_callback)
+            except Exception:
+                # As a last resort, create a default Go logger
+                self.go_logger = linksocks.NewLoggerWithID(self.logger_id)  # may still raise; surface to caller
+        _logger_registry[logger_id] = py_logger
+    
+    def cleanup(self):
+        """Clean up logger resources."""
+        if self.logger_id in _logger_registry:
+            del _logger_registry[self.logger_id]
+
+
+@dataclass
+class ReverseTokenResult:
+    """Result of adding a reverse token."""
+    token: str
+    port: int
+
+
+class _SnakePassthrough:
+    """Mixin to map snake_case attribute access to underlying CamelCase.
+    
+    Only used when an explicit Pythonic method/attribute is not defined.
+    """
+
+    def __getattr__(self, name: str) -> Any:
+        raw = super().__getattribute__("_raw")  # type: ignore[attr-defined]
+        camel = _snake_to_camel(name)
+        try:
+            return getattr(raw, camel)
+        except AttributeError:
+            raise
+
+    def __dir__(self) -> List[str]:
+        # Expose snake_case versions of underlying CamelCase for IDEs
+        names = set(super().__dir__())
+        try:
+            raw = super().__getattribute__("_raw")  # type: ignore[attr-defined]
+            for attr in dir(raw):
+                if not attr or attr.startswith("_"):
+                    continue
+                names.add(_camel_to_snake(attr))
+        except Exception:
+            pass
+        return sorted(names)
+
+
+def set_log_level(level: Union[int, str]) -> None:
+    """Set the global log level for linksocks."""
+    if isinstance(level, str):
+        level = getattr(logging, level.upper())
+    _logger.setLevel(level)

linksocks/_cli.py

@@ -0,0 +1,291 @@
+"""
+Command-line interface for linksocks.
+
+This module provides all CLI commands for the linksocks SOCKS5 over WebSocket proxy tool.
+"""
+
+import asyncio
+import logging
+import platform
+from typing import Optional
+
+import click
+
+from ._logging_config import init_logging
+from ._utils import get_env_or_flag, parse_socks_proxy, validate_required_token
+
+
+@click.group()
+def cli():
+    """SOCKS5 over WebSocket proxy tool."""
+    pass
+
+
+@click.command()
+def version():
+    """Print version and platform information."""
+    try:
+        from linksocks import __version__
+        version_str = __version__
+    except ImportError:
+        version_str = "unknown"
+    
+    platform_str = platform.platform()
+    click.echo(f"linksocks version {version_str} {platform_str}")
+
+
+@click.command()
+@click.option("--token", "-t", help="Authentication token (env: LINKSOCKS_TOKEN)")
+@click.option("--url", "-u", default="ws://localhost:8765", help="WebSocket server address")
+@click.option("--reverse", "-r", is_flag=True, default=False, help="Use reverse SOCKS5 proxy")
+@click.option("--connector-token", "-c", default=None, help="Connector token for reverse proxy (env: LINKSOCKS_CONNECTOR_TOKEN)")
+@click.option("--socks-host", "-s", default="127.0.0.1", help="SOCKS5 server listen address")
+@click.option("--socks-port", "-p", default=9870, help="SOCKS5 server listen port")
+@click.option("--socks-username", "-n", help="SOCKS5 authentication username")
+@click.option("--socks-password", "-w", help="SOCKS5 authentication password (env: LINKSOCKS_SOCKS_PASSWORD)")
+@click.option("--socks-no-wait", "-i", is_flag=True, default=False, help="Start SOCKS server immediately")
+@click.option("--no-reconnect", "-R", is_flag=True, default=False, help="Stop when server disconnects")
+@click.option("--debug", "-d", count=True, help="Debug logging (-d for debug, -dd for trace)")
+@click.option("--threads", "-T", default=1, help="Number of threads for data transfer")
+@click.option("--upstream-proxy", "-x", help="Upstream SOCKS5 proxy (socks5://[user:pass@]host[:port])")
+@click.option("--fast-open", "-f", is_flag=True, default=False, help="Assume connection success and allow data transfer immediately")
+@click.option("--no-env-proxy", "-E", is_flag=True, default=False, help="Ignore proxy env vars for WebSocket connection")
+def client(
+    token: Optional[str],
+    url: str,
+    reverse: bool,
+    connector_token: Optional[str],
+    socks_host: str,
+    socks_port: int,
+    socks_username: Optional[str],
+    socks_password: Optional[str],
+    socks_no_wait: bool,
+    no_reconnect: bool,
+    debug: int,
+    threads: int,
+    upstream_proxy: Optional[str],
+    fast_open: bool,
+    no_env_proxy: bool,
+):
+    """Start SOCKS5 over WebSocket proxy client."""
+    from ._client import Client
+
+    async def main():
+        # Get values from flags or environment
+        actual_token = get_env_or_flag(token, "LINKSOCKS_TOKEN")
+        actual_connector_token = get_env_or_flag(connector_token, "LINKSOCKS_CONNECTOR_TOKEN")
+        actual_socks_password = get_env_or_flag(socks_password, "LINKSOCKS_SOCKS_PASSWORD")
+        
+        # Validate required token
+        try:
+            validated_token = validate_required_token(actual_token)
+        except ValueError as e:
+            raise click.ClickException(str(e)) from e
+        
+        # Setup logging
+        if debug == 0:
+            log_level = logging.INFO
+        elif debug == 1:
+            log_level = logging.DEBUG
+        else:
+            log_level = 5  # TRACE level
+        
+        init_logging(level=log_level)
+
+        # Parse upstream proxy
+        if upstream_proxy:
+            try:
+                upstream_host, upstream_username, upstream_password = parse_socks_proxy(upstream_proxy)
+            except ValueError as e:
+                raise click.ClickException(f"Invalid upstream proxy: {e}") from e
+        else:
+            upstream_host = upstream_username = upstream_password = None
+
+        # Create client
+        client = Client(
+            ws_url=url,
+            token=validated_token,
+            reverse=reverse,
+            socks_host=socks_host,
+            socks_port=socks_port,
+            socks_username=socks_username,
+            socks_password=actual_socks_password,
+            socks_wait_server=not socks_no_wait,
+            reconnect=not no_reconnect,
+            upstream_proxy=upstream_host,
+            upstream_username=upstream_username,
+            upstream_password=upstream_password,
+            threads=threads,
+            fast_open=fast_open,
+            no_env_proxy=no_env_proxy,
+        )
+        
+        # Add connector for reverse mode
+        if actual_connector_token and reverse:
+            await client.async_add_connector(actual_connector_token)
+            await asyncio.sleep(0.2)
+        
+        # Run client
+        async with client:
+            await asyncio.Future()
+
+    asyncio.run(main())
+
+
+@click.command()
+@click.option("--ws-host", "-H", default="0.0.0.0", help="WebSocket server listen address")
+@click.option("--ws-port", "-P", default=8765, help="WebSocket server listen port")
+@click.option("--token", "-t", default=None, help="Auth token, auto-generated if not provided (env: LINKSOCKS_TOKEN)")
+@click.option("--connector-token", "-c", default=None, help="Connector token for reverse proxy (env: LINKSOCKS_CONNECTOR_TOKEN)")
+@click.option("--connector-autonomy", "-a", is_flag=True, default=False, help="Allow clients to manage connector tokens")
+@click.option("--buffer-size", "-b", default=4096, help="Buffer size for data transfer")
+@click.option("--reverse", "-r", is_flag=True, default=False, help="Use reverse SOCKS5 proxy")
+@click.option("--socks-host", "-s", default="127.0.0.1", help="SOCKS5 server listen address for reverse proxy")
+@click.option("--socks-port", "-p", default=9870, help="SOCKS5 server listen port for reverse proxy")
+@click.option("--socks-username", "-n", help="SOCKS5 username for authentication")
+@click.option("--socks-password", "-w", help="SOCKS5 password for authentication (env: LINKSOCKS_SOCKS_PASSWORD)")
+@click.option("--socks-nowait", "-i", is_flag=True, default=False, help="Start SOCKS server immediately")
+@click.option("--debug", "-d", count=True, help="Debug logging (-d for debug, -dd for trace)")
+@click.option("--api-key", "-k", help="Enable HTTP API with specified key")
+@click.option("--upstream-proxy", "-x", help="Upstream SOCKS5 proxy (socks5://[user:pass@]host[:port])")
+@click.option("--fast-open", "-f", is_flag=True, default=False, help="Assume connection success and allow data transfer immediately")
+def server(
+    ws_host: str,
+    ws_port: int,
+    token: Optional[str],
+    connector_token: Optional[str],
+    connector_autonomy: bool,
+    buffer_size: int,
+    reverse: bool,
+    socks_host: str,
+    socks_port: int,
+    socks_username: Optional[str],
+    socks_password: Optional[str],
+    socks_nowait: bool,
+    debug: int,
+    api_key: Optional[str],
+    upstream_proxy: Optional[str],
+    fast_open: bool,
+):
+    """Start SOCKS5 over WebSocket proxy server."""
+    from ._server import Server
+
+    async def main():
+        # Get values from flags or environment
+        actual_token = get_env_or_flag(token, "LINKSOCKS_TOKEN")
+        actual_connector_token = get_env_or_flag(connector_token, "LINKSOCKS_CONNECTOR_TOKEN")
+        actual_socks_password = get_env_or_flag(socks_password, "LINKSOCKS_SOCKS_PASSWORD")
+        
+        # Setup logging
+        if debug == 0:
+            log_level = logging.INFO
+        elif debug == 1:
+            log_level = logging.DEBUG
+        else:
+            log_level = 5  # TRACE level
+        
+        init_logging(level=log_level)
+
+        # Parse upstream proxy
+        if upstream_proxy:
+            try:
+                upstream_host, upstream_username, upstream_password = parse_socks_proxy(upstream_proxy)
+            except ValueError as e:
+                raise click.ClickException(f"Invalid upstream proxy: {e}") from e
+        else:
+            upstream_host = upstream_username = upstream_password = None
+
+        # Create server
+        server = Server(
+            ws_host=ws_host,
+            ws_port=ws_port,
+            socks_host=socks_host,
+            socks_wait_client=not socks_nowait,
+            upstream_proxy=upstream_host,
+            upstream_username=upstream_username,
+            upstream_password=upstream_password,
+            buffer_size=buffer_size,
+            api_key=api_key,
+            fast_open=fast_open,
+        )
+
+        # Configure tokens if no API key
+        if not api_key:
+            if reverse:
+                result = await server.async_add_reverse_token(
+                    token=actual_token,
+                    port=socks_port,
+                    username=socks_username,
+                    password=actual_socks_password,
+                    allow_manage_connector=connector_autonomy,
+                )
+                use_token = result.token
+                
+                if not connector_autonomy:
+                    use_connector_token = await server.async_add_connector_token(
+                        actual_connector_token, use_token
+                    )
+                await asyncio.sleep(0.2)
+
+                server.log.info("Configuration:")
+                server.log.info("  Mode: reverse proxy (SOCKS5 on server -> client -> network)")
+                server.log.info(f"  Token: {use_token}")
+                server.log.info(f"  SOCKS5 port: {result.port}")
+                if socks_username and actual_socks_password:
+                    server.log.info(f"  SOCKS5 username: {socks_username}")
+                if not connector_autonomy:
+                    server.log.info(f"  Connector Token: {use_connector_token}")
+                if connector_autonomy:
+                    server.log.info("  Connector autonomy: enabled")
+            else:
+                use_token = await server.async_add_forward_token(actual_token)
+                await asyncio.sleep(0.2)
+                server.log.info("Configuration:")
+                server.log.info("  Mode: forward proxy (SOCKS5 on client -> server -> network)")
+                server.log.info(f"  Token: {use_token}")
+
+        # Run server
+        async with server:
+            await asyncio.Future()
+
+    asyncio.run(main())
+
+
+def create_provider_command():
+    """Create provider command as alias for client -r."""
+    def provider_wrapper(*args, **kwargs):
+        kwargs['reverse'] = True
+        return client(*args, **kwargs)
+    
+    return click.Command(
+        name="provider",
+        callback=provider_wrapper,
+        params=client.params.copy(),
+        help="Start reverse SOCKS5 proxy client (alias for 'client -r')"
+    )
+
+
+def create_connector_command():
+    """Create connector command as alias for client."""
+    return click.Command(
+        name="connector",
+        callback=client,
+        params=client.params.copy(),
+        help="Start SOCKS5 proxy client (alias for 'client')"
+    )
+
+
+# Create command aliases
+provider_cmd = create_provider_command()
+connector_cmd = create_connector_command()
+
+# Register commands
+cli.add_command(client)
+cli.add_command(connector_cmd)
+cli.add_command(provider_cmd)
+cli.add_command(server)
+cli.add_command(version)
+
+
+if __name__ == "__main__":
+    cli()