exposr 0.5.2__py3-none-any.whl

client/__init__.py

@@ -0,0 +1 @@
+"""Exposr client package."""

client/config.py

@@ -0,0 +1,43 @@
+import json
+import secrets
+from pathlib import Path
+
+
+CONFIG_PATH = Path.home() / ".exposr" / "config.json"
+TOKEN_PATH = CONFIG_PATH.parent / "agent_token.txt"
+
+
+def load_config():
+    if not CONFIG_PATH.exists():
+        return {"server_host": "", "agent_token": ""}
+    try:
+        with CONFIG_PATH.open("r", encoding="utf-8") as config_file:
+            config = json.load(config_file)
+    except (OSError, json.JSONDecodeError):
+        return {"server_host": "", "agent_token": ""}
+    return {
+        "server_host": str(config.get("server_host", "")).strip(),
+        "agent_token": str(config.get("agent_token", "")).strip(),
+    }
+
+
+def set_server(server_host):
+    agent_token = secrets.token_urlsafe(32)
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with CONFIG_PATH.open("w", encoding="utf-8") as config_file:
+        json.dump(
+            {"server_host": server_host.strip(), "agent_token": agent_token},
+            config_file,
+            indent=2,
+        )
+        config_file.write("\n")
+    TOKEN_PATH.write_text(f"{agent_token}\n", encoding="utf-8")
+    return agent_token
+
+
+def get_server_host():
+    return load_config()["server_host"]
+
+
+def get_agent_token():
+    return load_config()["agent_token"]

client/main.py

@@ -0,0 +1,75 @@
+import asyncio
+
+from client.config import get_agent_token, get_server_host, set_server
+from client.tcp.connection import AgentConfig as TcpAgentConfig, connect_to_server as connect_tcp
+from client.udp.connection import AgentConfig as UdpAgentConfig, connect_to_server as connect_udp
+from common.cli import parse_arguments
+from common.logger import error, info
+
+
+def main():
+    args = parse_arguments()
+    if args.command == "server":
+        from server.config import get_agent_token as get_server_agent_token
+        from server.config import init_token
+
+        if args.server_command == "init-token":
+            if not args.agent_token.strip():
+                error("Agent token cannot be empty")
+                return
+            init_token(args.agent_token)
+            info("Agent token saved to ~/.exposr/config.json")
+        elif args.server_command == "start":
+            if not get_server_agent_token():
+                error("Server token is not configured. Run: exposr server init-token <token>")
+                return
+            from server.main import main as start_server
+
+            try:
+                asyncio.run(start_server())
+            except KeyboardInterrupt:
+                print()
+                info("Exposr server stopped")
+        return
+    if args.command == "config":
+        if args.config_command == "set-server":
+            set_server(args.server_host)
+            info(f"Server address saved: {args.server_host}")
+            info("Agent token generated and saved to ~/.exposr/agent_token.txt")
+        return
+    server_host = args.server_host or get_server_host()
+    agent_token = get_agent_token()
+    if not server_host:
+        error(
+            "Server IP is not configured. "
+            "Run: exposr config set-server <server-ip>"
+        )
+        return
+    if not agent_token:
+        error(
+            "Agent token is not configured. "
+            "Run: exposr config set-server <server-ip>"
+        )
+        return
+
+    config_class = UdpAgentConfig if args.command == "udp" else TcpAgentConfig
+    connect = connect_udp if args.command == "udp" else connect_tcp
+    config = config_class(
+        server_host=server_host,
+        agent_token=agent_token,
+        control_port=args.control_port,
+        data_port=args.data_port,
+        local_host=args.local_host,
+        local_port=args.local_port,
+        preferred_public_port=args.public_port or 25565,
+        explicit_public_port=args.public_port is not None,
+    )
+    try:
+        asyncio.run(connect(config))
+    except KeyboardInterrupt:
+        print()
+        info("Exposr stopped")
+
+
+if __name__ == "__main__":
+    main()

client/tcp/__init__.py

@@ -0,0 +1 @@
+"""TCP client transport implementation."""

client/tcp/connection.py

@@ -0,0 +1,86 @@
+import asyncio
+import random
+from dataclasses import dataclass
+
+from common.logger import connected, error, trying
+from common.protocol import CONNECT, REGISTER, REGISTERED, command
+from client.tcp.tunnel import handle_connection
+
+RANDOM_PORT_START = 20000
+RANDOM_PORT_END = 30000
+MAX_PORT_ATTEMPTS = 100
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    server_host: str
+    agent_token: str
+    control_port: int
+    data_port: int
+    local_host: str
+    local_port: int
+    preferred_public_port: int
+    explicit_public_port: bool
+
+
+async def register_port(reader, writer, port, config):
+    trying(f"Trying to register public port {port}")
+    writer.write(command(REGISTER, f"{port} {config.agent_token}"))
+    await writer.drain()
+    response = await reader.readline()
+    if not response:
+        error("Server disconnected while registering")
+        return False
+    if response.startswith(REGISTERED.encode()):
+        connected(f"Public tunnel active: {config.server_host}:{port}")
+        connected(f"Forwarding to: {config.local_host}:{config.local_port}")
+        return True
+    error(f"Port {port} unavailable")
+    return False
+
+
+async def connect_to_server(config):
+    while True:
+        writer = None
+        try:
+            trying(f"Connecting to Exposr {config.server_host}:{config.control_port}")
+            reader, writer = await asyncio.open_connection(
+                config.server_host, config.control_port
+            )
+            connected("Connected to Exposr control server")
+            public_port = config.preferred_public_port
+            registered = await register_port(reader, writer, public_port, config)
+            if not registered and config.explicit_public_port:
+                error(f"Requested public port {public_port} is unavailable")
+                raise RuntimeError(f"Port {public_port} is unavailable")
+            attempts = 0
+            while not registered:
+                attempts += 1
+                if attempts > MAX_PORT_ATTEMPTS:
+                    error("Could not find an available public port after 100 attempts")
+                    raise RuntimeError("No public ports available")
+                public_port = random.randint(RANDOM_PORT_START, RANDOM_PORT_END)
+                trying(f"Trying random public port {public_port}")
+                registered = await register_port(reader, writer, public_port, config)
+            while True:
+                command_line = await reader.readline()
+                if not command_line:
+                    error("Server disconnected")
+                    break
+                parts = command_line.decode().strip().split()
+                if len(parts) == 2 and parts[0] == CONNECT:
+                    trying(f"Setting up connection {parts[1][:8]}")
+                    asyncio.create_task(handle_connection(parts[1], config))
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            error(f"Control connection error: {exc}")
+        finally:
+            if writer is not None:
+                writer.close()
+                try:
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+        trying("Retrying connection in 5 seconds")
+        await asyncio.sleep(5)

client/tcp/tunnel.py

@@ -0,0 +1,44 @@
+import asyncio
+
+from common.logger import connected, error, trying
+from common.protocol import command, DATA
+
+
+async def pipe(reader, writer):
+    try:
+        while True:
+            data = await reader.read(65536)
+            if not data:
+                break
+            writer.write(data)
+            await writer.drain()
+    except Exception:
+        pass
+    finally:
+        try:
+            writer.close()
+            await writer.wait_closed()
+        except Exception:
+            pass
+
+
+async def handle_connection(connection_id, config):
+    connected(f"New connection ({connection_id[:8]})")
+    try:
+        trying(f"Connecting to local service {config.local_host}:{config.local_port}")
+        local_reader, local_writer = await asyncio.open_connection(
+            config.local_host, config.local_port
+        )
+        trying(f"Opening data connection to {config.server_host}:{config.data_port}")
+        data_reader, data_writer = await asyncio.open_connection(
+            config.server_host, config.data_port
+        )
+        data_writer.write(command(DATA, connection_id))
+        await data_writer.drain()
+        connected(f"Tunnel established -> {config.local_host}:{config.local_port}")
+        await asyncio.gather(
+            pipe(data_reader, local_writer),
+            pipe(local_reader, data_writer),
+        )
+    except Exception as exc:
+        error(f"Connection failed: {exc}")

client/udp/__init__.py

@@ -0,0 +1 @@
+"""Placeholder package for future UDP client transport support."""

client/udp/connection.py

@@ -0,0 +1,76 @@
+import asyncio
+import random
+from dataclasses import dataclass
+
+from common.logger import connected, error, trying
+from common.protocol import CONNECT, REGISTER, REGISTERED, UDP, command
+from client.udp.tunnel import handle_connection
+
+RANDOM_PORT_START = 20000
+RANDOM_PORT_END = 30000
+MAX_PORT_ATTEMPTS = 100
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    server_host: str
+    agent_token: str
+    control_port: int
+    data_port: int
+    local_host: str
+    local_port: int
+    preferred_public_port: int
+    explicit_public_port: bool
+
+
+async def register_port(reader, writer, port, config):
+    trying(f"Trying to register UDP public port {port}")
+    writer.write(command(REGISTER, f"{port} {config.agent_token} {UDP}"))
+    await writer.drain()
+    response = await reader.readline()
+    if response.startswith(REGISTERED.encode()):
+        connected(f"UDP tunnel active: {config.server_host}:{port}")
+        connected(f"Forwarding UDP to: {config.local_host}:{config.local_port}")
+        return True
+    error(f"UDP port {port} unavailable")
+    return False
+
+
+async def connect_to_server(config):
+    while True:
+        writer = None
+        try:
+            trying(f"Connecting to Exposr {config.server_host}:{config.control_port}")
+            reader, writer = await asyncio.open_connection(config.server_host, config.control_port)
+            connected("Connected to Exposr control server")
+            public_port = config.preferred_public_port
+            registered = await register_port(reader, writer, public_port, config)
+            if not registered and config.explicit_public_port:
+                raise RuntimeError(f"UDP port {public_port} is unavailable")
+            attempts = 0
+            while not registered:
+                attempts += 1
+                if attempts > MAX_PORT_ATTEMPTS:
+                    raise RuntimeError("No UDP public ports available")
+                public_port = random.randint(RANDOM_PORT_START, RANDOM_PORT_END)
+                registered = await register_port(reader, writer, public_port, config)
+            while True:
+                line = await reader.readline()
+                if not line:
+                    break
+                parts = line.decode().strip().split()
+                if len(parts) == 2 and parts[0] == CONNECT:
+                    asyncio.create_task(handle_connection(parts[1], config))
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            error(f"UDP control connection error: {exc}")
+        finally:
+            if writer is not None:
+                writer.close()
+                try:
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+        trying("Retrying UDP connection in 5 seconds")
+        await asyncio.sleep(5)

client/udp/tunnel.py

@@ -0,0 +1,68 @@
+import asyncio
+import struct
+
+from common.logger import connected, error, trying
+from common.protocol import DATA, command
+
+
+def pack_datagram(data):
+    return struct.pack("!I", len(data)) + data
+
+
+async def read_datagram(reader):
+    header = await reader.readexactly(4)
+    size = struct.unpack("!I", header)[0]
+    if size > 65535:
+        raise ValueError("UDP datagram is too large")
+    return await reader.readexactly(size)
+
+
+class LocalUdpProtocol(asyncio.DatagramProtocol):
+    def __init__(self, queue):
+        self.queue = queue
+
+    def datagram_received(self, data, address):
+        self.queue.put_nowait(data)
+
+
+async def handle_connection(connection_id, config):
+    data_writer = None
+    local_transport = None
+    try:
+        trying(f"Connecting to local UDP service {config.local_host}:{config.local_port}")
+        queue = asyncio.Queue()
+        loop = asyncio.get_running_loop()
+        local_transport, _ = await loop.create_datagram_endpoint(
+            lambda: LocalUdpProtocol(queue),
+            remote_addr=(config.local_host, config.local_port),
+        )
+        trying(f"Opening UDP data connection to {config.server_host}:{config.data_port}")
+        data_reader, data_writer = await asyncio.open_connection(
+            config.server_host, config.data_port
+        )
+        data_writer.write(command(DATA, connection_id))
+        await data_writer.drain()
+        connected(f"UDP tunnel established -> {config.local_host}:{config.local_port}")
+
+        async def send_local_datagrams():
+            while True:
+                data = await queue.get()
+                data_writer.write(pack_datagram(data))
+                await data_writer.drain()
+
+        async def receive_local_datagrams():
+            while True:
+                local_transport.sendto(await read_datagram(data_reader))
+
+        await asyncio.gather(send_local_datagrams(), receive_local_datagrams())
+    except Exception as exc:
+        error(f"UDP connection failed: {exc}")
+    finally:
+        if local_transport is not None:
+            local_transport.close()
+        if data_writer is not None:
+            data_writer.close()
+            try:
+                await data_writer.wait_closed()
+            except Exception:
+                pass

common/__init__.py

@@ -0,0 +1 @@
+"""Shared Exposr helpers."""

common/cli.py

@@ -0,0 +1,60 @@
+import argparse
+
+
+def parse_arguments(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="exposr",
+        description="Exposr TCP and UDP tunneling agent",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def add_tunnel_arguments(tunnel_parser):
+        tunnel_parser.add_argument("local_port", type=int)
+        tunnel_parser.add_argument(
+            "public_port",
+            nargs="?",
+            type=int,
+            default=None,
+        )
+
+        # Accept configuration flags both before and after the subcommand.
+        tunnel_parser.add_argument("--server-host", dest="server_host", default=argparse.SUPPRESS)
+        tunnel_parser.add_argument("--control-port", dest="control_port", type=int, default=argparse.SUPPRESS)
+        tunnel_parser.add_argument("--data-port", dest="data_port", type=int, default=argparse.SUPPRESS)
+        tunnel_parser.add_argument("--local-host", dest="local_host", default=argparse.SUPPRESS)
+
+    tcp_parser = subparsers.add_parser(
+        "tcp", help="Expose a local TCP port to the internet"
+    )
+    add_tunnel_arguments(tcp_parser)
+
+    udp_parser = subparsers.add_parser(
+        "udp", help="Expose a local UDP port to the internet"
+    )
+    add_tunnel_arguments(udp_parser)
+
+
+    config_parser = subparsers.add_parser("config", help="Manage Exposr configuration")
+    config_subparsers = config_parser.add_subparsers(dest="config_command", required=True)
+    set_server_parser = config_subparsers.add_parser(
+        "set-server", help="Set the Exposr relay server address"
+    )
+    set_server_parser.add_argument("server_host")
+
+    server_parser = subparsers.add_parser("server", help="Manage the Exposr relay server")
+    server_subparsers = server_parser.add_subparsers(
+        dest="server_command", required=True
+    )
+    init_token_parser = server_subparsers.add_parser(
+        "init-token", help="Set the relay server agent token"
+    )
+    init_token_parser.add_argument("agent_token")
+    server_subparsers.add_parser("start", help="Start the Exposr relay server")
+
+    parser.add_argument("--server-host", default=None)
+    parser.add_argument("--control-port", type=int, default=9000)
+    parser.add_argument("--data-port", type=int, default=9001)
+    parser.add_argument("--local-host", default="127.0.0.1")
+
+    args = parser.parse_args(argv)
+    return args

common/logger.py

@@ -0,0 +1,21 @@
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+RED = "\033[91m"
+BLUE = "\033[94m"
+RESET = "\033[0m"
+
+
+def connected(message):
+    print(f"{GREEN}[CONNECTED]{RESET} {message}")
+
+
+def trying(message):
+    print(f"{YELLOW}[TRYING]{RESET} {message}")
+
+
+def error(message):
+    print(f"{RED}[ERROR]{RESET} {message}")
+
+
+def info(message):
+    print(f"{BLUE}[INFO]{RESET} {message}")

common/protocol.py

@@ -0,0 +1,10 @@
+REGISTER = "REGISTER"
+REGISTERED = "REGISTERED"
+CONNECT = "CONNECT"
+DATA = "DATA"
+TCP = "TCP"
+UDP = "UDP"
+
+
+def command(name, value):
+    return f"{name} {value}\n".encode()