wsbuilder 0.1.0__tar.gz → 0.2.2__tar.gz

wsbuilder-0.2.2/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: wsbuilder
+Version: 0.2.2
+Summary: Framework ligero HTTP + WebSocket extraido de PortHound4.
+Author: wsbuilder Authors
+License-Expression: MIT
+Keywords: websocket,http,framework,server,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# wsbuilder
+
+`wsbuilder` es un paquete Python extraido de `PortHound4` para construir servidores HTTP + WebSocket sin dependencias externas.
+
+Lightweight Python HTTP + WebSocket framework for building real-time APIs and custom servers.
+
+**Keywords:** `python`, `http-server`, `websocket`, `framework`, `real-time`, `api`, `socket`.
+
+## Incluye
+
+- `wsbuilder.framework`: router, request/response, servidor HTTP, handshake WS y utilidades de frames.
+- `wsbuilder.ws_demo`: demo completo HTTP + WebSocket + REST + SQLite.
+
+## Instalacion local
+
+```bash
+python -m pip install -e .
+```
+
+## Uso rapido del framework
+
+```python
+from wsbuilder import App, Response, parse_close_payload
+
+app = App()
+
+@app.view("/")
+def home(_request):
+    return Response.html("<h1>wsbuilder</h1>")
+
+@app.api("/api/health")
+def health(_request):
+    return {"ok": True}
+
+@app.ws("/ws/")
+def ws_handler(ws, _request):
+    while True:
+        fin, opcode, payload, _masked, _mask = ws.recv_frame()
+        if opcode == 0x8:
+            code, reason = parse_close_payload(payload)
+            ws.close(code or 1000, reason or "")
+            break
+        if opcode == 0x9:
+            ws.send_pong(payload)
+            continue
+        if opcode == 0x1:
+            ws.send_text(payload.decode("utf-8", errors="ignore"))
+        elif opcode == 0x2:
+            ws.send_binary(payload)
+
+app.run("0.0.0.0", 8765)
+```
+
+Para CORS sin variables de entorno:
+
+```python
+app = App(cors_allow_origin="*")
+```
+
+## HTTP streaming (chunked)
+
+```python
+import time
+from wsbuilder import App, Response
+
+app = App()
+
+@app.view("/stream")
+def stream(_request):
+    def chunks():
+        for i in range(5):
+            yield f"chunk {i}\n"
+            time.sleep(1)
+    return Response.stream(chunks(), content_type="text/plain; charset=utf-8")
+```
+
+## Ejecutar demo incluido
+
+```bash
+python -m wsbuilder --host 0.0.0.0 --port 8765
+# o
+wsbuilder --host 0.0.0.0 --port 8765
+```
+
+## Configuracion CORS
+
+- Usa `App(cors_allow_origin="https://tu-dominio.com")`.
+- Usa `App(cors_allow_origin="*")` para permitir cualquier origen.
+
+## CI/CD (GitHub Actions)
+
+- `package-build.yml`: construye `sdist` + `wheel`, valida metadata y prueba instalacion/import.
+- `release-from-main.yml` en push a `main`: calcula `semver` automaticamente, crea rama `release/v<version>` desde `main`, actualiza version del paquete, crea tag `v<version>` y publica GitHub Release.
+- `publish-packages.yml` en push de tag `v*`: construye y publica a PyPI/TestPyPI (instalable con `pip`).
+- `publish-packages.yml` en tags `v*`: adjunta los paquetes al GitHub Release.
+- `main-only-from-develop.yml` (workflow `main-pr-source-check`): valida metadata minima del PR hacia `main`.
+
+### Reglas de versionado automatico
+
+- `major`: si algun commit trae `BREAKING CHANGE`, `type(scope)!:` o ramas/commits marcados como `breaking`/`major`.
+- `minor`: si hay suficiente peso de `feat`/`feature` (proporcional frente a cambios `patch`) y no hay `major`.
+- `patch`: cualquier otro caso.
+
+Recomendado usar Conventional Commits para que el calculo de version sea preciso.
+
+### Secrets requeridos
+
+- `RELEASE_BOT_TOKEN` (recomendado): PAT/fine-grained token para crear rama `release/*`, crear tag y publicar GitHub Release.
+- `RULESET_ADMIN_TOKEN` (fallback): usado automaticamente si no existe `RELEASE_BOT_TOKEN`.
+- `PYPI_API_TOKEN`: token de publicacion para PyPI.
+- `TEST_PYPI_API_TOKEN` (opcional): token de publicacion para TestPyPI.

wsbuilder-0.2.2/README.md

@@ -0,0 +1,111 @@
+# wsbuilder
+
+`wsbuilder` es un paquete Python extraido de `PortHound4` para construir servidores HTTP + WebSocket sin dependencias externas.
+
+Lightweight Python HTTP + WebSocket framework for building real-time APIs and custom servers.
+
+**Keywords:** `python`, `http-server`, `websocket`, `framework`, `real-time`, `api`, `socket`.
+
+## Incluye
+
+- `wsbuilder.framework`: router, request/response, servidor HTTP, handshake WS y utilidades de frames.
+- `wsbuilder.ws_demo`: demo completo HTTP + WebSocket + REST + SQLite.
+
+## Instalacion local
+
+```bash
+python -m pip install -e .
+```
+
+## Uso rapido del framework
+
+```python
+from wsbuilder import App, Response, parse_close_payload
+
+app = App()
+
+@app.view("/")
+def home(_request):
+    return Response.html("<h1>wsbuilder</h1>")
+
+@app.api("/api/health")
+def health(_request):
+    return {"ok": True}
+
+@app.ws("/ws/")
+def ws_handler(ws, _request):
+    while True:
+        fin, opcode, payload, _masked, _mask = ws.recv_frame()
+        if opcode == 0x8:
+            code, reason = parse_close_payload(payload)
+            ws.close(code or 1000, reason or "")
+            break
+        if opcode == 0x9:
+            ws.send_pong(payload)
+            continue
+        if opcode == 0x1:
+            ws.send_text(payload.decode("utf-8", errors="ignore"))
+        elif opcode == 0x2:
+            ws.send_binary(payload)
+
+app.run("0.0.0.0", 8765)
+```
+
+Para CORS sin variables de entorno:
+
+```python
+app = App(cors_allow_origin="*")
+```
+
+## HTTP streaming (chunked)
+
+```python
+import time
+from wsbuilder import App, Response
+
+app = App()
+
+@app.view("/stream")
+def stream(_request):
+    def chunks():
+        for i in range(5):
+            yield f"chunk {i}\n"
+            time.sleep(1)
+    return Response.stream(chunks(), content_type="text/plain; charset=utf-8")
+```
+
+## Ejecutar demo incluido
+
+```bash
+python -m wsbuilder --host 0.0.0.0 --port 8765
+# o
+wsbuilder --host 0.0.0.0 --port 8765
+```
+
+## Configuracion CORS
+
+- Usa `App(cors_allow_origin="https://tu-dominio.com")`.
+- Usa `App(cors_allow_origin="*")` para permitir cualquier origen.
+
+## CI/CD (GitHub Actions)
+
+- `package-build.yml`: construye `sdist` + `wheel`, valida metadata y prueba instalacion/import.
+- `release-from-main.yml` en push a `main`: calcula `semver` automaticamente, crea rama `release/v<version>` desde `main`, actualiza version del paquete, crea tag `v<version>` y publica GitHub Release.
+- `publish-packages.yml` en push de tag `v*`: construye y publica a PyPI/TestPyPI (instalable con `pip`).
+- `publish-packages.yml` en tags `v*`: adjunta los paquetes al GitHub Release.
+- `main-only-from-develop.yml` (workflow `main-pr-source-check`): valida metadata minima del PR hacia `main`.
+
+### Reglas de versionado automatico
+
+- `major`: si algun commit trae `BREAKING CHANGE`, `type(scope)!:` o ramas/commits marcados como `breaking`/`major`.
+- `minor`: si hay suficiente peso de `feat`/`feature` (proporcional frente a cambios `patch`) y no hay `major`.
+- `patch`: cualquier otro caso.
+
+Recomendado usar Conventional Commits para que el calculo de version sea preciso.
+
+### Secrets requeridos
+
+- `RELEASE_BOT_TOKEN` (recomendado): PAT/fine-grained token para crear rama `release/*`, crear tag y publicar GitHub Release.
+- `RULESET_ADMIN_TOKEN` (fallback): usado automaticamente si no existe `RELEASE_BOT_TOKEN`.
+- `PYPI_API_TOKEN`: token de publicacion para PyPI.
+- `TEST_PYPI_API_TOKEN` (opcional): token de publicacion para TestPyPI.

{wsbuilder-0.1.0 → wsbuilder-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wsbuilder"
-version = "0.1.0"
+version = "0.2.2"
 description = "Framework ligero HTTP + WebSocket extraido de PortHound4."
 readme = "README.md"
 requires-python = ">=3.11"

{wsbuilder-0.1.0 → wsbuilder-0.2.2}/src/wsbuilder/__init__.py

@@ -12,8 +12,7 @@ from .framework import (
     parse_query_string,
 )
 
-__version__ = "0.1.0"
-
+__version__ = "0.2.2"
 __all__ = [
     "App",
     "HTTPServer",

wsbuilder-0.2.2/src/wsbuilder/app.py

@@ -0,0 +1,115 @@
+from .constants import DEFAULT_CORS_ALLOW_ORIGIN
+from .http import Response
+
+
+class Route:
+    def __init__(self, path, methods, handler, kind):
+        self.path = path
+        self.methods = {m.upper() for m in methods}
+        self.handler = handler
+        self.kind = kind
+
+
+class Router:
+    def __init__(self):
+        self.routes = []
+
+    def add(self, route):
+        self.routes.append(route)
+
+    def resolve(self, path, method=None):
+        for route in self.routes:
+            if route.path != path:
+                continue
+            if method is None or method.upper() in route.methods:
+                return route
+        return None
+
+
+class App:
+    def __init__(self, cors_allow_origin=DEFAULT_CORS_ALLOW_ORIGIN):
+        self.router = Router()
+        self.ws_routes = {}
+        self.startup_hooks = []
+        self.cors_allow_origin = (cors_allow_origin or "").strip()
+
+    def route(self, path, methods=("GET",), kind="plain"):
+        def decorator(func):
+            self.router.add(Route(path, methods, func, kind))
+            return func
+
+        return decorator
+
+    def view(self, path, methods=("GET",)):
+        return self.route(path, methods=methods, kind="plain")
+
+    def api(self, path, methods=("GET",)):
+        return self.route(path, methods=methods, kind="api")
+
+    def ws(self, path):
+        def decorator(func):
+            self.ws_routes[path] = func
+            return func
+
+        return decorator
+
+    def add_startup(self, func):
+        self.startup_hooks.append(func)
+
+    def dispatch(self, request):
+        cors_allow_origin = self.cors_allow_origin
+        if request.method == "OPTIONS":
+            route = self.router.resolve(request.path, method=None)
+            if route:
+                allow = sorted(route.methods | {"OPTIONS"})
+                headers = {
+                    "Access-Control-Allow-Methods": ", ".join(allow),
+                    "Access-Control-Allow-Headers": "Content-Type, Authorization, X-API-Key",
+                }
+                if cors_allow_origin:
+                    headers["Access-Control-Allow-Origin"] = cors_allow_origin
+                    if cors_allow_origin != "*":
+                        headers["Vary"] = "Origin"
+                return Response(status=200, body=b"", headers=headers)
+
+        route = self.router.resolve(request.path, request.method)
+        if not route:
+            return Response.text("Not Found", status=404)
+
+        try:
+            result = route.handler(request)
+        except Exception as e:
+            print(f"[http] handler error {request.method} {request.path}: {e}")
+            if route.kind == "api":
+                headers = {}
+                if cors_allow_origin:
+                    headers["Access-Control-Allow-Origin"] = cors_allow_origin
+                    if cors_allow_origin != "*":
+                        headers["Vary"] = "Origin"
+                return Response.json(
+                    {"status": "error", "message": "Internal Server Error"},
+                    status=500,
+                    headers=headers,
+                )
+            return Response.text("Internal Server Error", status=500)
+
+        if isinstance(result, Response):
+            resp = result
+        elif route.kind == "api" and isinstance(result, (dict, list)):
+            resp = Response.json(result)
+        else:
+            resp = Response.text("" if result is None else str(result))
+
+        if route.kind == "api":
+            if cors_allow_origin:
+                resp.headers.setdefault("Access-Control-Allow-Origin", cors_allow_origin)
+                if cors_allow_origin != "*":
+                    resp.headers.setdefault("Vary", "Origin")
+
+        return resp
+
+    def run(self, host, port, ssl_context=None):
+        from .server import HTTPServer
+
+        server = HTTPServer(host, port, self, ssl_context=ssl_context)
+        server.serve_forever()

wsbuilder-0.2.2/src/wsbuilder/constants.py

@@ -0,0 +1,67 @@
+MAGIC_WS = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+DEFAULT_CORS_ALLOW_ORIGIN = ""
+
+STATUS_MESSAGES = {
+    100: "Continue",
+    101: "Switching Protocols",
+    102: "Processing",
+    103: "Early Hints",
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    203: "Non-Authoritative Information",
+    204: "No Content",
+    205: "Reset Content",
+    206: "Partial Content",
+    207: "Multi-Status",
+    208: "Already Reported",
+    226: "IM Used",
+    300: "Multiple Choices",
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    304: "Not Modified",
+    305: "Use Proxy",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Payload Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a teapot",
+    421: "Misdirected Request",
+    422: "Unprocessable Entity",
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required",
+}

wsbuilder-0.2.2/src/wsbuilder/framework.py

@@ -0,0 +1,44 @@
+"""Compatibility facade for the original single-file framework module."""
+
+from .app import App, Route, Router
+from .constants import DEFAULT_CORS_ALLOW_ORIGIN, MAGIC_WS, STATUS_MESSAGES
+from .http import Request, Response, parse_http_request, parse_query_string, send_http_response
+from .server import HTTPServer
+from .ws import (
+    B64_ALPHABET,
+    WebSocket,
+    base64_encode,
+    handshake_websocket,
+    is_ws_request,
+    make_ws_frame_bytes,
+    parse_close_payload,
+    read_ws_frame_raw,
+    recv_exact,
+    sha1,
+)
+
+__all__ = [
+    "App",
+    "HTTPServer",
+    "Request",
+    "Response",
+    "Route",
+    "Router",
+    "WebSocket",
+    "DEFAULT_CORS_ALLOW_ORIGIN",
+    "MAGIC_WS",
+    "STATUS_MESSAGES",
+    "B64_ALPHABET",
+    "base64_encode",
+    "handshake_websocket",
+    "is_ws_request",
+    "make_ws_frame_bytes",
+    "parse_close_payload",
+    "parse_http_request",
+    "parse_query_string",
+    "read_ws_frame_raw",
+    "recv_exact",
+    "send_http_response",
+    "sha1",
+]
+

wsbuilder-0.2.2/src/wsbuilder/http.py

@@ -0,0 +1,190 @@
+import json
+
+from .constants import STATUS_MESSAGES
+
+
+def parse_query_string(qs):
+    params = {}
+    if not qs:
+        return params
+    parts = qs.split("&")
+    for part in parts:
+        if not part:
+            continue
+        if "=" in part:
+            k, v = part.split("=", 1)
+        else:
+            k, v = part, ""
+        params[k] = v
+    return params
+
+
+class Request:
+    def __init__(self, method, path, query_string, headers, body, client, tls=None):
+        self.method = (method or "").upper()
+        self.path = path or "/"
+        self.query_string = query_string or ""
+        self.query = parse_query_string(self.query_string)
+        self.headers = headers or {}
+        self.body = body or b""
+        self.client = client
+        self.tls = tls or {}
+
+    def text(self, encoding="utf-8"):
+        return self.body.decode(encoding, errors="ignore")
+
+    def json(self):
+        try:
+            return json.loads(self.text())
+        except Exception:
+            return None
+
+
+class Response:
+    def __init__(self, status=200, body=b"", headers=None, reason=None, stream=None):
+        self.status = status
+        self.reason = reason
+        self.stream = stream
+        self.is_stream = stream is not None
+        if self.is_stream:
+            self.body = b""
+        elif isinstance(body, (bytes, bytearray)):
+            self.body = bytes(body)
+        else:
+            self.body = str(body).encode("utf-8")
+        self.headers = headers or {}
+
+    @classmethod
+    def json(cls, data, status=200, headers=None):
+        body = json.dumps(data).encode("utf-8")
+        hdrs = {"Content-Type": "application/json; charset=utf-8"}
+        if headers:
+            hdrs.update(headers)
+        return cls(status=status, body=body, headers=hdrs)
+
+    @classmethod
+    def text(cls, text, status=200, headers=None):
+        hdrs = {"Content-Type": "text/plain; charset=utf-8"}
+        if headers:
+            hdrs.update(headers)
+        return cls(status=status, body=text, headers=hdrs)
+
+    @classmethod
+    def html(cls, html, status=200, headers=None):
+        hdrs = {"Content-Type": "text/html; charset=utf-8"}
+        if headers:
+            hdrs.update(headers)
+        return cls(status=status, body=html, headers=hdrs)
+
+    @classmethod
+    def stream(cls, chunks, status=200, headers=None, content_type=None):
+        hdrs = {}
+        if content_type:
+            hdrs["Content-Type"] = content_type
+        if headers:
+            hdrs.update(headers)
+        return cls(status=status, headers=hdrs, stream=chunks)
+
+
+def parse_http_request(conn, max_header_bytes=65536):
+    data = b""
+    while b"\r\n\r\n" not in data:
+        chunk = conn.recv(1024)
+        if not chunk:
+            break
+        data += chunk
+        if len(data) > int(max_header_bytes):
+            raise ValueError("Request headers too large")
+    header_text, _, remainder = data.partition(b"\r\n\r\n")
+    lines = header_text.decode("utf-8", errors="ignore").split("\r\n")
+    if not lines:
+        return None
+    request_line = lines[0]
+    parts = request_line.split()
+    if len(parts) != 3:
+        return None
+    method, path, version = parts
+    if not version.startswith("HTTP/"):
+        return None
+    headers = {}
+    for line in lines[1:]:
+        if ":" in line:
+            k, v = line.split(":", 1)
+            headers[k.strip().lower()] = v.strip()
+    return {
+        "method": method,
+        "path": path,
+        "version": version,
+        "headers": headers,
+        "remainder": remainder,
+    }
+
+
+def send_http_response(conn, response):
+    status_code = response.status
+    reason = response.reason or STATUS_MESSAGES.get(status_code, "OK")
+    headers = dict(response.headers or {})
+    lowermap = {k.lower(): v for k, v in headers.items()}
+    if getattr(response, "is_stream", False):
+        if "transfer-encoding" not in lowermap and "content-length" not in lowermap:
+            headers["Transfer-Encoding"] = "chunked"
+        lowermap = {k.lower(): v for k, v in headers.items()}
+    elif "content-length" not in lowermap:
+        headers["Content-Length"] = str(len(response.body))
+        lowermap = {k.lower(): v for k, v in headers.items()}
+    if "connection" not in lowermap:
+        headers["Connection"] = "close"
+        lowermap = {k.lower(): v for k, v in headers.items()}
+    status_line = f"HTTP/1.1 {status_code} {reason}\r\n"
+    hdrs = ""
+    for k, v in headers.items():
+        hdrs += f"{k}: {v}\r\n"
+    resp = status_line + hdrs + "\r\n"
+    try:
+        conn.sendall(resp.encode("utf-8"))
+        if getattr(response, "is_stream", False):
+            use_chunked = "chunked" in lowermap.get("transfer-encoding", "").lower()
+            for chunk in _iter_stream_chunks(response.stream):
+                if use_chunked:
+                    conn.sendall(f"{len(chunk):X}\r\n".encode("utf-8"))
+                    conn.sendall(chunk)
+                    conn.sendall(b"\r\n")
+                else:
+                    conn.sendall(chunk)
+            if use_chunked:
+                conn.sendall(b"0\r\n\r\n")
+        else:
+            conn.sendall(response.body)
+    except Exception as e:
+        print(f"[http] send error {status_code}: {e}")
+
+
+def _iter_stream_chunks(source):
+    if source is None:
+        return
+    if isinstance(source, (bytes, bytearray, str)):
+        normalized = _normalize_chunk(source)
+        if normalized:
+            yield normalized
+        return
+    if hasattr(source, "read") and callable(source.read):
+        while True:
+            chunk = source.read(8192)
+            if not chunk:
+                break
+            normalized = _normalize_chunk(chunk)
+            if normalized:
+                yield normalized
+        return
+    for chunk in source:
+        normalized = _normalize_chunk(chunk)
+        if normalized:
+            yield normalized
+
+
+def _normalize_chunk(chunk):
+    if chunk is None:
+        return b""
+    if isinstance(chunk, (bytes, bytearray)):
+        return bytes(chunk)
+    return str(chunk).encode("utf-8")