tw-framework 0.3.7__tar.gz → 0.3.8__tar.gz

{tw_framework-0.3.7 → tw_framework-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tw-framework
-Version: 0.3.7
+Version: 0.3.8
 Summary: TW framework CLI with create, dev, build, and deploy commands
 Author: TW Framework
 Requires-Python: >=3.9

{tw_framework-0.3.7 → tw_framework-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tw-framework"
-version = "0.3.7"
+version = "0.3.8"
 description = "TW framework CLI with create, dev, build, and deploy commands"
 readme = "README.md"
 requires-python = ">=3.9"

{tw_framework-0.3.7 → tw_framework-0.3.8}/tw_framework/framework.py

@@ -23,6 +23,7 @@ import time
 import ctypes
 import select
 import struct
+import importlib.util
 import urllib.parse
 from email.utils import formatdate
 from dataclasses import dataclass
@@ -32,6 +33,7 @@ from . import compiler
 from .common import content_hash, log
 from .plugin_runtime import ExtensionManager
 from .twm_parser import compile_twm_module_to_cjs, parse_twm_functions
+from . import websocket as tw_websocket
 
 # Deployment adapter imports
 from .adapters.vercel import build_vercel_config, generate_vercel_output
@@ -614,6 +616,73 @@ def load_project_env(project_root: str, mode: str) -> Dict[str, str]:
     return env
 
 
+def validate_env_schema(config: dict, env: Dict[str, str]) -> List[str]:
+    raw = compiler.get_config_value(config, "env", "required", default="")
+    if not raw:
+        return []
+    if isinstance(raw, str):
+        names = [part.strip() for part in raw.split(",") if part.strip()]
+    elif isinstance(raw, (list, tuple)):
+        names = [str(part).strip() for part in raw if str(part).strip()]
+    else:
+        return []
+    missing = []
+    for name in names:
+        value = env.get(name) if env.get(name) is not None else os.environ.get(name)
+        if value is None or str(value).strip() == "":
+            missing.append(name)
+    return missing
+
+
+def warn_missing_env(missing: List[str]) -> None:
+    if not missing:
+        return
+    log("", level="warning")
+    log("\u26a0 Missing required environment variable(s):", level="warning")
+    for name in missing:
+        log(f"   - {name}", level="warning")
+    log("  Set these in `.env`, `.env.development`, or `.env.local` before relying on them.", level="warning")
+    log("  Declared in `tw.config` under `env: required:`.", level="warning")
+    log("", level="warning")
+
+
+def discover_ws_routes(project_root: str) -> Dict[str, str]:
+    routes = {}
+    ws_dir = os.path.join(project_root, "[home]", "ws")
+    if not os.path.isdir(ws_dir):
+        return routes
+    for dirpath, _, filenames in os.walk(ws_dir):
+        for filename in sorted(filenames):
+            if not filename.endswith(".py") or filename.startswith("_"):
+                continue
+            full_path = os.path.join(dirpath, filename)
+            rel = os.path.relpath(full_path, ws_dir)
+            rel = rel[:-3] if rel.endswith(".py") else rel
+            rel = rel.replace(os.sep, "/")
+            if rel.endswith("/index"):
+                rel = rel[: -len("/index")]
+            elif rel == "index":
+                rel = ""
+            route = "/ws/" + rel if rel else "/ws"
+            routes[route] = full_path
+    return routes
+
+
+def load_ws_handler(path: str):
+    module_name = f"tw_ws_{os.path.splitext(os.path.basename(path))[0]}_{content_hash(path, length=10)}"
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        logger.exception("Failed to load WebSocket route: %s", path)
+        return None
+    handler = getattr(module, "on_connect", None)
+    return handler if callable(handler) else None
+
+
 def parse_cookie_header(raw_value: str) -> Dict[str, str]:
     cookies = {}
     if not raw_value:
@@ -1269,6 +1338,7 @@ class TWProject:
         configure_compiler_paths(self.project_root)
         self.env = load_project_env(self.project_root, "development")
         self.config = compiler.load_config()
+        warn_missing_env(validate_env_schema(self.config, self.env))
         self.modular_pipeline = use_modular_pipeline(self.config)
         self.extensions = ExtensionManager(self.project_root, self.config, self.env).refresh()
         self._rate_limiters: Dict[str, TokenBucketRateLimiter] = {}
@@ -2029,6 +2099,11 @@ def make_dev_handler(state: TWDevState):
 
         def handle_request(self, method: str):
             path = normalize_url_path(self.path)
+
+            if tw_websocket.is_websocket_upgrade(self.headers):
+                self.handle_websocket(path)
+                return
+
             if path == "/__tw/events":
                 self.handle_events()
                 return
@@ -2155,6 +2230,44 @@ def make_dev_handler(state: TWDevState):
                     body = render_error_html("Compile error", message, 500, ip=self.client_address[0] if self.client_address else "")
                     self.respond_bytes(500, body, "text/html; charset=utf-8", headers=middleware.get("headers", []), cookies=middleware.get("cookies", []))
 
+        def handle_websocket(self, path: str):
+            routes = discover_ws_routes(state.project.project_root)
+            handler_path = routes.get(path)
+            if handler_path is None:
+                self.send_response(404)
+                self.send_header("Content-Type", "text/plain; charset=utf-8")
+                self.end_headers()
+                try:
+                    self.wfile.write(b"No WebSocket route for this path")
+                except (BrokenPipeError, ConnectionResetError):
+                    pass
+                return
+
+            on_connect = load_ws_handler(handler_path)
+            if on_connect is None:
+                self.send_response(500)
+                self.send_header("Content-Type", "text/plain; charset=utf-8")
+                self.end_headers()
+                try:
+                    self.wfile.write(b"WebSocket route failed to load (see server logs)")
+                except (BrokenPipeError, ConnectionResetError):
+                    pass
+                return
+
+            if not tw_websocket.perform_handshake(self):
+                return
+
+            conn = tw_websocket.WebSocketConnection(
+                self.connection, path,
+                headers={key: value for key, value in self.headers.items()},
+            )
+            try:
+                on_connect(conn)
+            except Exception:
+                logger.exception("WebSocket handler raised an exception: %s", handler_path)
+            finally:
+                conn.close()
+
         def handle_events(self):
             self.send_response(200)
             self.send_header("Content-Type", "text/event-stream")

tw_framework-0.3.8/tw_framework/websocket.py

@@ -0,0 +1,189 @@
+"""Minimal RFC 6455 WebSocket implementation, stdlib-only (no external deps).
+
+Handles the HTTP Upgrade handshake and basic text/binary frame
+send/receive over the raw socket owned by an http.server request
+handler. Designed for TW's threaded dev/prod server: each connection
+runs in its own thread (ThreadingMixIn), so a blocking recv loop here
+is fine and does not stall other requests.
+"""
+import base64
+import hashlib
+import socket
+import struct
+
+WS_MAGIC = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+OPCODE_CONTINUATION = 0x0
+OPCODE_TEXT = 0x1
+OPCODE_BINARY = 0x2
+OPCODE_CLOSE = 0x8
+OPCODE_PING = 0x9
+OPCODE_PONG = 0xA
+
+
+class WebSocketClosed(Exception):
+    """Raised internally when the peer closes the connection or the socket errors out."""
+
+
+def is_websocket_upgrade(headers) -> bool:
+    connection = str(headers.get("Connection", "")).lower()
+    upgrade = str(headers.get("Upgrade", "")).lower()
+    return "upgrade" in connection and upgrade == "websocket"
+
+
+def _compute_accept_key(client_key: str) -> str:
+    sha1 = hashlib.sha1((client_key + WS_MAGIC).encode("utf-8")).digest()
+    return base64.b64encode(sha1).decode("ascii")
+
+
+def perform_handshake(handler) -> bool:
+    """Sends the 101 Switching Protocols response directly over the raw socket.
+    Returns True on success. `handler` is a BaseHTTPRequestHandler instance."""
+    client_key = handler.headers.get("Sec-WebSocket-Key")
+    if not client_key:
+        return False
+    accept_key = _compute_accept_key(client_key)
+    response = (
+        "HTTP/1.1 101 Switching Protocols\r\n"
+        "Upgrade: websocket\r\n"
+        "Connection: Upgrade\r\n"
+        f"Sec-WebSocket-Accept: {accept_key}\r\n"
+        "\r\n"
+    )
+    try:
+        handler.wfile.write(response.encode("utf-8"))
+        handler.wfile.flush()
+    except (BrokenPipeError, ConnectionResetError, OSError):
+        return False
+    return True
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    chunks = []
+    remaining = n
+    while remaining > 0:
+        chunk = sock.recv(remaining)
+        if not chunk:
+            raise WebSocketClosed("connection closed while reading")
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+def _read_frame(sock: socket.socket):
+    """Reads one WebSocket frame from the client. Returns (opcode, payload_bytes)."""
+    header = _recv_exact(sock, 2)
+    b0, b1 = header[0], header[1]
+    fin = (b0 & 0x80) != 0
+    opcode = b0 & 0x0F
+    masked = (b1 & 0x80) != 0
+    length = b1 & 0x7F
+
+    if length == 126:
+        length = struct.unpack(">H", _recv_exact(sock, 2))[0]
+    elif length == 127:
+        length = struct.unpack(">Q", _recv_exact(sock, 8))[0]
+
+    mask_key = _recv_exact(sock, 4) if masked else b""
+    payload = _recv_exact(sock, length) if length else b""
+    if masked:
+        payload = bytes(b ^ mask_key[i % 4] for i, b in enumerate(payload))
+
+    return opcode, payload, fin
+
+
+def _encode_frame(opcode: int, payload: bytes) -> bytes:
+    header = bytearray()
+    header.append(0x80 | opcode)
+    length = len(payload)
+    if length < 126:
+        header.append(length)
+    elif length < 65536:
+        header.append(126)
+        header += struct.pack(">H", length)
+    else:
+        header.append(127)
+        header += struct.pack(">Q", length)
+    return bytes(header) + payload
+
+
+class WebSocketConnection:
+    """A single upgraded connection. One instance per client; runs on its
+    own request-handler thread."""
+
+    def __init__(self, sock: socket.socket, path: str, headers=None):
+        self.sock = sock
+        self.path = path
+        self.headers = headers or {}
+        self.closed = False
+
+    def send_text(self, message: str) -> None:
+        if self.closed:
+            return
+        try:
+            self.sock.sendall(_encode_frame(OPCODE_TEXT, message.encode("utf-8")))
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            self.closed = True
+
+    def send_bytes(self, data: bytes) -> None:
+        if self.closed:
+            return
+        try:
+            self.sock.sendall(_encode_frame(OPCODE_BINARY, data))
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            self.closed = True
+
+    def close(self, code: int = 1000) -> None:
+        if self.closed:
+            return
+        self.closed = True
+        try:
+            self.sock.sendall(_encode_frame(OPCODE_CLOSE, struct.pack(">H", code)))
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            pass
+
+    def _pong(self, payload: bytes) -> None:
+        try:
+            self.sock.sendall(_encode_frame(OPCODE_PONG, payload))
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            self.closed = True
+
+    def __iter__(self):
+        """Yields text (str) or binary (bytes) messages until the client
+        disconnects. Ping/pong and close frames are handled transparently."""
+        buffer = bytearray()
+        buffer_opcode = None
+        while not self.closed:
+            try:
+                opcode, payload, fin = _read_frame(self.sock)
+            except (WebSocketClosed, ConnectionResetError, OSError, struct.error):
+                self.closed = True
+                return
+
+            if opcode == OPCODE_CLOSE:
+                self.closed = True
+                return
+            if opcode == OPCODE_PING:
+                self._pong(payload)
+                continue
+            if opcode == OPCODE_PONG:
+                continue
+
+            if opcode in (OPCODE_TEXT, OPCODE_BINARY):
+                buffer_opcode = opcode
+                buffer = bytearray(payload)
+            elif opcode == OPCODE_CONTINUATION:
+                buffer.extend(payload)
+            else:
+                continue
+
+            if fin and buffer_opcode is not None:
+                if buffer_opcode == OPCODE_TEXT:
+                    try:
+                        yield buffer.decode("utf-8")
+                    except UnicodeDecodeError:
+                        continue
+                else:
+                    yield bytes(buffer)
+                buffer = bytearray()
+                buffer_opcode = None

{tw_framework-0.3.7 → tw_framework-0.3.8}/tw_framework.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tw-framework
-Version: 0.3.7
+Version: 0.3.8
 Summary: TW framework CLI with create, dev, build, and deploy commands
 Author: TW Framework
 Requires-Python: >=3.9

{tw_framework-0.3.7 → tw_framework-0.3.8}/tw_framework.egg-info/SOURCES.txt

@@ -49,6 +49,7 @@ tw_framework/test_build_cli_pytest.py
 tw_framework/tree_shaking.py
 tw_framework/twm_api_runner.js
 tw_framework/twm_parser.py
+tw_framework/websocket.py
 tw_framework.egg-info/PKG-INFO
 tw_framework.egg-info/SOURCES.txt
 tw_framework.egg-info/dependency_links.txt