borecli 1.0.0__py3-none-any.whl

bore/websocket/proxy.py

@@ -0,0 +1,147 @@
+import asyncio
+import contextlib
+import logging
+from typing import Awaitable, Callable, Optional
+
+from websockets.exceptions import ConnectionClosed
+from websockets.protocol import State
+
+logger = logging.getLogger(__name__)
+
+
+class WebSocketProxy:
+    """
+    Bidirectional websocket proxy.
+
+    Relays websocket frames between two websocket connections while
+    preserving text and binary frames.
+
+    The proxy exits when either side disconnects.
+    """
+
+    def __init__(
+        self,
+        client_ws,
+        local_ws,
+        *,
+        on_close: Optional[Callable[[], Awaitable[None]]] = None,
+    ):
+        self.client_ws = client_ws
+        self.local_ws = local_ws
+        self.on_close = on_close
+
+        self._closed = False
+
+    async def run(self):
+        """
+        Start bidirectional proxying.
+
+        Returns when either websocket closes.
+        """
+
+        task1 = asyncio.create_task(
+            self._pipe(
+                self.client_ws,
+                self.local_ws,
+                "CLIENT",
+                "LOCAL",
+            )
+        )
+
+        task2 = asyncio.create_task(
+            self._pipe(
+                self.local_ws,
+                self.client_ws,
+                "LOCAL",
+                "CLIENT",
+            )
+        )
+
+        done, pending = await asyncio.wait(
+            {task1, task2},
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+
+        for task in pending:
+            task.cancel()
+
+        for task in pending:
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+
+        await self.close()
+
+    async def _pipe(
+        self,
+        source,
+        destination,
+        source_name: str,
+        destination_name: str,
+    ):
+        """
+        Forward websocket frames.
+        """
+
+        try:
+
+            async for message in source:
+
+                if isinstance(message, bytes):
+                    logger.debug(
+                        "%s → %s (%d bytes)",
+                        source_name,
+                        destination_name,
+                        len(message),
+                    )
+                else:
+                    logger.debug(
+                        "%s → %s (%d chars)",
+                        source_name,
+                        destination_name,
+                        len(message),
+                    )
+
+                # Preserve frame type automatically.
+                await destination.send(message)
+
+        except ConnectionClosed as exc:
+
+            logger.info(
+                "%s disconnected (%s)",
+                source_name,
+                exc.code,
+            )
+
+        except asyncio.CancelledError:
+            raise
+
+        except Exception:
+
+            logger.exception(
+                "Proxy error %s -> %s",
+                source_name,
+                destination_name,
+            )
+
+    async def close(self):
+
+        if self._closed:
+            return
+
+        self._closed = True
+
+        await self._close_socket(self.client_ws)
+        await self._close_socket(self.local_ws)
+
+        if self.on_close:
+            await self.on_close()
+
+    async def _close_socket(self, ws):
+
+        try:
+
+            if ws.state is not State.CLOSED:
+                await ws.close()
+
+        except Exception:
+            pass

bore/websocket_client.py

@@ -0,0 +1,338 @@
+# borecli/bore/websocket_client.py
+
+import base64
+import json
+import logging
+import threading
+from concurrent.futures import ThreadPoolExecutor
+
+import requests
+import websocket
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(threadName)s] %(levelname)s %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+DEFAULT_WORKERS = 20
+MAX_RESPONSE_BYTES = 50 * 1024 * 1024
+CHUNK_SIZE = 512 * 1024
+
+SESSION = requests.Session()
+adapter = requests.adapters.HTTPAdapter(
+    pool_connections=DEFAULT_WORKERS,
+    pool_maxsize=DEFAULT_WORKERS,
+)
+SESSION.mount("http://", adapter)
+SESSION.mount("https://", adapter)
+
+SEND_LOCK = threading.Lock()
+
+EXCLUDED_REQUEST_HEADERS = {
+    "host", "connection", "keep-alive",
+    "proxy-authenticate", "proxy-authorization",
+    "te", "trailers", "transfer-encoding",
+    "upgrade", "content-length", "accept-encoding",
+}
+
+
+def is_binary_content(content_type):
+    if not content_type:
+        return True
+    content_type = content_type.lower()
+    text_types = (
+        "text/",
+        "application/json",
+        "application/javascript",
+        "application/x-javascript",
+        "application/xml",
+        "application/xhtml+xml",
+        "application/graphql",
+        "application/ld+json",
+        "application/problem+json",
+        "image/svg+xml",
+    )
+    return not any(content_type.startswith(p) for p in text_types)
+
+
+def handle_request(local_port, data):
+    method = data.get("method", "GET")
+    path = data.get("path", "/")
+    body = data.get("body", "")
+    request_binary = data.get("binary", False)
+
+    #
+    # Decode request body received from BoreHook.
+    #
+    if request_binary:
+        body = base64.b64decode(body)
+    else:
+        if isinstance(body, str):
+            body = body.encode("utf-8")
+    request_id = data.get("request_id")
+    incoming_headers = dict(data.get("headers", {}))
+
+    headers = {
+        k: v for k, v in incoming_headers.items()
+        if k.lower() not in EXCLUDED_REQUEST_HEADERS
+    }
+
+    url = f"http://127.0.0.1:{local_port}{path}"
+    logger.info("Incoming %s %s", method, path)
+
+    try:
+        response = SESSION.request(
+            method=method,
+            url=url,
+            headers=headers,
+            data=body,
+            allow_redirects=False,
+            timeout=(5, 120),
+            stream=True,
+        )
+
+        response_headers = dict(response.headers)
+        response_headers.pop("Content-Encoding", None)
+        response_headers.pop("Transfer-Encoding", None)
+        response_headers.pop("Content-Length", None)
+
+        content_type = response_headers.get("Content-Type", "")
+        binary = is_binary_content(content_type)
+
+        chunks = []
+        total = 0
+        for chunk in response.iter_content(chunk_size=65536):
+            if chunk:
+                total += len(chunk)
+                if total > MAX_RESPONSE_BYTES:
+                    logger.warning("Response for %s exceeded %d bytes, truncating.", path, MAX_RESPONSE_BYTES)
+                    break
+                chunks.append(chunk)
+        raw = b"".join(chunks)
+
+        logger.info("Completed %s %s -> %s (%d bytes)", method, path, response.status_code, total)
+
+        return {
+            "request_id": request_id,
+            "status": response.status_code,
+            "headers": response_headers,
+            "raw": raw,
+            "binary": binary,
+        }
+
+    except requests.Timeout:
+        logger.error("Timeout forwarding %s %s", method, path)
+        return {
+            "request_id": request_id,
+            "status": 504,
+            "headers": {"Content-Type": "text/plain; charset=utf-8"},
+            "raw": b"Tunnel timeout",
+            "binary": False,
+        }
+    except requests.RequestException:
+        logger.exception("Error forwarding request.")
+        return {
+            "request_id": request_id,
+            "status": 502,
+            "headers": {"Content-Type": "text/plain; charset=utf-8"},
+            "raw": b"Unable to reach local application.",
+            "binary": False,
+        }
+    except Exception:
+        logger.exception("Unexpected forwarding error.")
+        return {
+            "request_id": request_id,
+            "status": 500,
+            "headers": {"Content-Type": "text/plain; charset=utf-8"},
+            "raw": b"Internal tunnel error.",
+            "binary": False,
+        }
+
+
+def send_response(ws, result):
+    request_id = result["request_id"]
+    binary = result["binary"]
+    raw = result["raw"]
+
+    if binary:
+        encoded = base64.b64encode(raw).decode("ascii")
+        body_bytes = encoded.encode("ascii")
+    else:
+        encoded = raw.decode("utf-8", errors="replace")
+        body_bytes = encoded.encode("utf-8")
+
+    total_size = len(body_bytes)
+
+    if total_size <= CHUNK_SIZE:
+        payload = json.dumps({
+            "type": "response",
+            "request_id": request_id,
+            "status": result["status"],
+            "headers": result["headers"],
+            "body": encoded,
+            "binary": binary,
+        })
+        with SEND_LOCK:
+            ws.send(payload)
+        return
+
+    chunk_list = [
+        body_bytes[i: i + CHUNK_SIZE]
+        for i in range(0, total_size, CHUNK_SIZE)
+    ]
+    total_chunks = len(chunk_list)
+    logger.info("Sending %s in %d chunks (%d bytes total)", request_id, total_chunks, total_size)
+
+    for index, chunk in enumerate(chunk_list):
+        chunk_body = chunk.decode("ascii" if binary else "utf-8")
+        frame = {
+            "type": "response_chunk",
+            "request_id": request_id,
+            "chunk_index": index,
+            "total_chunks": total_chunks,
+            "body": chunk_body,
+            "binary": binary,
+        }
+        if index == 0:
+            frame["status"] = result["status"]
+            frame["headers"] = result["headers"]
+        with SEND_LOCK:
+            ws.send(json.dumps(frame))
+
+
+def process_request(ws, local_port, data):
+    request_id = data.get("request_id")
+    try:
+        result = handle_request(local_port, data)
+        send_response(ws, result)
+    except websocket.WebSocketConnectionClosedException:
+        logger.warning("WebSocket closed while sending response for %s.", request_id)
+    except BrokenPipeError:
+        logger.warning("Broken pipe while sending response for %s.", request_id)
+    except Exception as e:
+        logger.error("Error processing request %s: %r", request_id, e)
+
+
+def cleanup_futures(futures):
+    completed = {f for f in futures if f.done()}
+    for future in completed:
+        try:
+            future.result()
+        except Exception:
+            logger.exception("Worker raised an exception.")
+    futures.difference_update(completed)
+
+
+def run(
+    ws_url,
+    local_port,
+    workers=DEFAULT_WORKERS,
+    should_shutdown=lambda: False,
+):
+    assert isinstance(workers, int), f"workers must be int, got {type(workers)}"
+
+    logger.info("Forwarding -> http://127.0.0.1:%s", local_port)
+    logger.info("WebSocket  -> %s", ws_url)
+
+    executor = ThreadPoolExecutor(
+        max_workers=workers,
+        thread_name_prefix="worker",
+    )
+    futures = set()
+
+    def on_message(ws_app, message):
+        logger.info("=" * 60)
+        logger.info("RAW MESSAGE FROM SERVER")
+        logger.info(message)
+        logger.info("=" * 60)
+        logger.info("Received WebSocket message:")
+        logger.info(message)
+        cleanup_futures(futures)
+        if not message or should_shutdown():
+            ws_app.close()
+            return
+        try:
+            data = json.loads(message)
+        except json.JSONDecodeError:
+            logger.warning("Received invalid JSON.")
+            return
+        # if "request_id" not in data:
+        #     return
+        # future = executor.submit(process_request, ws_app, local_port, data)
+        
+        #
+        # Only process HTTP forwarding messages.
+        #\
+# =============================================================
+        logger.info(data.get("type"))
+        if data.get("type") != "http.request":
+        # if data.get("type") != "request":
+            return
+# =============================================================
+        if "request_id" not in data:
+            return
+
+        future = executor.submit(
+            process_request,
+            ws_app,
+            local_port,
+            data,
+        )
+        futures.add(future)
+
+    def on_error(ws_app, error):
+        if isinstance(error, (KeyboardInterrupt, SystemExit)):
+            ws_app.close()
+            return
+        logger.error("Tunnel error: %r", error)
+
+    def on_close(ws_app, close_status_code, close_msg):
+        logger.warning("Tunnel closed: %s - %s", close_status_code, close_msg)
+
+    def on_open(ws_app):
+        logger.info("Tunnel connected.")
+
+    ws_app = websocket.WebSocketApp(
+        ws_url,
+        on_open=on_open,
+        on_message=on_message,
+        on_error=on_error,
+        on_close=on_close,
+    )
+
+    # ------------------------------------------------------------------ #
+    # Run run_forever in a daemon thread so the main thread stays free.   #
+    # The signal handler calls ws_app.close() which stops the thread.     #
+    # We then join with a timeout so we never block forever.              #
+    # ------------------------------------------------------------------ #
+    ws_thread = threading.Thread(
+        target=ws_app.run_forever,
+        kwargs={"ping_interval": 15, "ping_timeout": 5},
+        daemon=True,  # dies automatically if the process exits
+        name="ws-run-forever",
+    )
+    ws_thread.start()
+    logger.info("Tunnel Connected Natively")
+
+    # Block the caller here, but interruptibly — check the shutdown
+    # flag every 0.2 s instead of sleeping inside run_forever.
+    try:
+        while ws_thread.is_alive():
+            if should_shutdown():
+                logger.info("Shutdown flag set — closing WebSocket.")
+                ws_app.close()
+                break
+            ws_thread.join(timeout=0.2)
+    finally:
+        # Give the WS thread up to 3 s to finish its close handshake.
+        ws_thread.join(timeout=3)
+
+        logger.info("Waiting for %d active workers...", len(futures))
+        for future in list(futures):
+            try:
+                future.result(timeout=2)
+            except Exception:
+                pass
+        executor.shutdown(wait=False)
+        logger.info("Tunnel closed.")

borecli-1.0.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: borecli
+Version: 1.0.0
+Summary: Official BoreHook CLI for securely exposing localhost through BoreHook.
+Author-email: Chinonso Egwuaka <chinonso_patrick@yahoo.com>
+License: MIT
+Project-URL: Homepage, https://borehook.com
+Project-URL: Documentation, https://borehook.com/docs
+Project-URL: Repository, https://github.com/CHI-NONSO1/borecli
+Project-URL: Issues, https://github.com/CHI-NONSO1/borecli/issues
+Keywords: borehook,tunnel,localhost,webhook,cli,proxy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.7
+Requires-Dist: requests>=2.32.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: websockets>=15.0
+Dynamic: license-file
+
+# BoreHook CLI
+
+The official command-line interface for **BoreHook** — securely expose your localhost to the internet, test webhooks, and debug HTTP requests without deploying your application.
+
+## Features
+
+* 🚀 Expose localhost over HTTPS
+* 🔐 Secure authenticated tunnels
+* 🔄 Persistent tunnel management
+* 📡 WebSocket-powered request forwarding
+* ⏱️ Configurable login session duration
+* 💻 Cross-platform (Windows, macOS, Linux)
+
+---
+
+## Installation
+
+### Python (PyPI)
+
+```bash
+pip install borecli
+```
+
+### Node.js (npm)
+
+```bash
+npm install -g borecli
+```
+
+---
+
+## Login
+
+Authenticate your BoreHook account.
+
+```bash
+bore login
+```
+
+Specify a custom session duration:
+
+```bash
+bore login --time 30m
+```
+
+```bash
+bore login --time 8h
+```
+
+```bash
+bore login --time 7d
+```
+
+If no duration is specified, the default session length is **1 hour**.
+
+Supported time units:
+
+| Example | Meaning    |
+| ------- | ---------- |
+| `30m`   | 30 Minutes |
+| `2h`    | 2 Hours    |
+| `7d`    | 7 Days     |
+
+---
+
+## Check Current User
+
+```bash
+bore whoami
+```
+
+Example:
+
+```text
+Logged in as: john@example.com
+```
+
+---
+
+## Logout
+
+```bash
+bore logout
+```
+
+---
+
+## Connect a Tunnel
+
+Start forwarding traffic to your local application.
+
+```bash
+bore connect
+```
+
+You'll be prompted to select one of your configured tunnels.
+
+Example:
+
+```text
+Available Tunnels
+
+[1] my-api
+[2] webhook
+[3] development
+
+Select tunnel:
+```
+
+After connecting:
+
+```text
+🚀 Tunnel Connected
+
+Tunnel ID: 99c2c16b-e78b-4790-bab8-93865118f91b
+Subdomain: webhook
+Public URL: https://webhook.borehook.com
+
+Forwarding → http://127.0.0.1:8000
+
+Press Ctrl+C to disconnect.
+```
+
+---
+
+## Commands
+
+| Command        | Description                           |
+| -------------- | ------------------------------------- |
+| `bore login`   | Authenticate your account             |
+| `bore connect` | Connect to a tunnel                   |
+| `bore whoami`  | Display the current logged-in account |
+| `bore logout`  | Remove the local session              |
+
+---
+
+## Examples
+
+Login for one hour (default):
+
+```bash
+bore login
+```
+
+Login for 15 minutes:
+
+```bash
+bore login --time 15m
+```
+
+Login for 8 hours:
+
+```bash
+bore login --time 8h
+```
+
+Connect to a tunnel:
+
+```bash
+bore connect
+```
+
+Logout:
+
+```bash
+bore logout
+```
+
+---
+
+## Requirements
+
+* Windows
+* macOS
+* Linux
+
+Internet connection required.
+
+---
+
+## Documentation
+
+Visit **https://borehook.com** for documentation, tutorials, and guides.
+
+---
+
+## Support
+
+* Website: https://borehook.com
+* Email: [support@borehook.com](mailto:support@borehook.com)
+
+---
+
+## License
+
+MIT License.
+
+---
+
+Built with ❤️ by the BoreHook team.