one-ring-http 0.1.0__tar.gz

one_ring_http-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Tools
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+*.swp
+*.swo
+
+# Docs
+site/
+
+# Secrets
+.env
+.env.*
+*.pem
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Personal testing.
+tmp/
+
+# Agents
+.claude

one_ring_http-0.1.0/CLAUDE.md

@@ -0,0 +1,28 @@
+# one-ring-http — Package Context
+
+Part of the **one-ring** monorepo. See the root `CLAUDE.md` for shared conventions.
+
+## Purpose
+
+<!-- Describe what this package does -->
+
+## Package Commands
+
+```bash
+# From this directory:
+just test          # Run tests for this package
+just test-cov      # Tests with coverage
+just typecheck     # Type check this package
+
+# From monorepo root:
+just test-pkg one-ring-http   # Test this package
+just check                # Run all checks (all packages)
+```
+
+## Layout
+
+```
+src/one_ring_http/    # Source code
+tests/                                # Tests
+pyproject.toml                        # Package metadata (tool config inherited from root)
+```

one_ring_http-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: one-ring-http
+Version: 0.1.0
+Summary: HTTP/1.1 server built on one-ring-loop and io_uring
+Project-URL: Homepage, https://github.com/otto-sellerstam/one-ring
+Project-URL: Repository, https://github.com/otto-sellerstam/one-ring
+Project-URL: Issues, https://github.com/otto-sellerstam/one-ring/issues
+Author-email: Otto Sellerstam <ottosellerstam@gmail.com>
+License: MIT
+Keywords: async,http,io_uring,linux,server
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: one-ring-loop>=0.1.0
+Requires-Dist: structlog>=24.0
+Description-Content-Type: text/markdown
+
+# one-ring-http
+
+HTTP/1.1 server built on [one-ring-loop](https://pypi.org/project/one-ring-loop/) and Linux io_uring.
+
+Part of the [one-ring](https://github.com/otto-sellerstam/one-ring) project.
+
+## What it provides
+
+- **HTTPServer** - TLS-enabled HTTP/1.1 server
+- **Router** - method + path routing with fallback handlers
+- **Request/Response** - parsed HTTP requests, serializable responses
+- **Static file serving** - built-in static file handler
+
+## Example
+
+```python
+import ssl
+
+from one_ring_http.response import Response
+from one_ring_http.router import Router
+from one_ring_http.server import HTTPServer
+from one_ring_loop import run
+
+ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+ssl_context.load_cert_chain("cert.pem", "key.pem")
+
+def hello(request):
+    return Response(status_code=200, body=b"Hello, world!")
+
+router = Router()
+router.add("GET", "/", hello)
+
+server = HTTPServer(router=router, host="127.0.0.1", port=8000, ssl_context=ssl_context)
+run(server.serve())
+```
+
+## Requirements
+
+- **Linux** with io_uring support (kernel 6.7+)
+- **Python 3.14+**
+
+## Installation
+
+```bash
+uv add one-ring-http
+```
+
+## License
+
+MIT

one_ring_http-0.1.0/README.md

@@ -0,0 +1,50 @@
+# one-ring-http
+
+HTTP/1.1 server built on [one-ring-loop](https://pypi.org/project/one-ring-loop/) and Linux io_uring.
+
+Part of the [one-ring](https://github.com/otto-sellerstam/one-ring) project.
+
+## What it provides
+
+- **HTTPServer** - TLS-enabled HTTP/1.1 server
+- **Router** - method + path routing with fallback handlers
+- **Request/Response** - parsed HTTP requests, serializable responses
+- **Static file serving** - built-in static file handler
+
+## Example
+
+```python
+import ssl
+
+from one_ring_http.response import Response
+from one_ring_http.router import Router
+from one_ring_http.server import HTTPServer
+from one_ring_loop import run
+
+ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+ssl_context.load_cert_chain("cert.pem", "key.pem")
+
+def hello(request):
+    return Response(status_code=200, body=b"Hello, world!")
+
+router = Router()
+router.add("GET", "/", hello)
+
+server = HTTPServer(router=router, host="127.0.0.1", port=8000, ssl_context=ssl_context)
+run(server.serve())
+```
+
+## Requirements
+
+- **Linux** with io_uring support (kernel 6.7+)
+- **Python 3.14+**
+
+## Installation
+
+```bash
+uv add one-ring-http
+```
+
+## License
+
+MIT

one_ring_http-0.1.0/justfile

@@ -0,0 +1,20 @@
+# List available recipes
+default:
+    @just --list
+
+pkg := "one_ring_http"
+
+# Run tests for this package
+test:
+    uv run pytest tests/
+
+# Run tests with coverage
+test-cov:
+    uv run pytest tests/ --cov={{pkg}} --cov-report=term-missing
+
+# Run type checker for this package
+typecheck:
+    uv run pyrefly check src/ tests/
+
+# Run all checks for this package
+check: typecheck test

one_ring_http-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "one-ring-http"
+version = "0.1.0"
+description = "HTTP/1.1 server built on one-ring-loop and io_uring"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [
+    { name = "Otto Sellerstam", email = "ottosellerstam@gmail.com" },
+]
+readme = "README.md"
+keywords = ["io_uring", "http", "server", "async", "linux"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Typing :: Typed",
+]
+dependencies = [
+    "structlog>=24.0",
+    "one-ring-loop>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/otto-sellerstam/one-ring"
+Repository = "https://github.com/otto-sellerstam/one-ring"
+Issues = "https://github.com/otto-sellerstam/one-ring/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/one_ring_http"]
+
+# ── Coverage (per-package source) ───────────────────────────────────────
+# Other coverage settings (fail_under, exclude_lines) are in root pyproject.toml.
+
+[tool.coverage.run]
+source = ["one_ring_http"]
+branch = true

one_ring_http-0.1.0/src/one_ring_http/__init__.py

@@ -0,0 +1,3 @@
+"""One Ring Http package."""
+
+__version__ = "0.1.0"

one_ring_http-0.1.0/src/one_ring_http/log.py

@@ -0,0 +1,55 @@
+"""Structured logging configuration using structlog."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import structlog
+
+
+def setup_logging() -> None:
+    """Configure structlog with sensible defaults.
+
+    Uses JSON output when ``LOG_FORMAT=json`` (e.g. production),
+    otherwise uses colored console output for development.
+    """
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    if os.environ.get("LOG_FORMAT") == "json":
+        renderer: structlog.types.Processor = structlog.processors.JSONRenderer()
+    else:
+        renderer = structlog.dev.ConsoleRenderer()
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            renderer,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(0),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+        cache_logger_on_first_use=True,
+    )
+
+
+_configured = False
+
+
+def get_logger(*args: object, **kwargs: object) -> structlog.stdlib.BoundLogger:
+    """Return a structlog logger, configuring on first call.
+
+    This avoids running ``setup_logging()`` at import time, which would
+    interfere with tests and multi-process setups.
+    """
+    global _configured  # noqa: PLW0603
+    if not _configured:
+        setup_logging()
+        _configured = True
+    return structlog.get_logger(*args, **kwargs)

one_ring_http-0.1.0/src/one_ring_http/request.py

@@ -0,0 +1,86 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Self, TypeGuard
+
+from one_ring_loop.log import get_logger
+
+if TYPE_CHECKING:
+    from one_ring_http.typedef import HTTPHeaders, HTTPMethod
+    from one_ring_loop.streams.buffered import BufferedByteReceiveStream
+    from one_ring_loop.typedefs import Coro
+
+
+logger = get_logger()
+
+ALLOWED_HTTP_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE"}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Request:
+    """Represents a parsed HTTP/1.1 request."""
+
+    """The HTTP method"""
+    method: HTTPMethod
+
+    """The URL path"""
+    path: str
+
+    """HTTP version"""
+    http_version: str
+
+    """HTTP headers"""
+    headers: HTTPHeaders
+
+    """HTTP body"""
+    body: bytes
+
+    @classmethod
+    def parse(cls, buffered_stream: BufferedByteReceiveStream) -> Coro[Self]:
+        """Parses data from a buffered receive stream and provides a Request object."""
+        # 1. Get tokens from first line
+        first_line = yield from buffered_stream.receive_until(
+            delimiter=b"\r\n", max_bytes=65536
+        )
+        tokens = first_line.split(b" ")
+        method = tokens[0].decode()
+        target = tokens[1].decode()
+        version = tokens[2].decode()
+
+        if not cls.verify_http_method(method):
+            raise RuntimeError
+
+        # 2. Get headers, until reaching empty line
+        headers: HTTPHeaders = {}
+        line = yield from buffered_stream.receive_until(
+            delimiter=b"\r\n", max_bytes=65536
+        )
+        while line:
+            key_val = line.split(b": ", 1)
+            header_name = key_val[0].decode().lower()
+            header_val = key_val[1].decode()
+
+            if header_name in headers:
+                header_val = headers[header_name] + ", " + header_val
+
+            headers[header_name] = header_val
+            line = yield from buffered_stream.receive_until(
+                delimiter=b"\r\n", max_bytes=65536
+            )
+
+        # 3. Get body, if we have "content-length"
+        body = b""
+        if "content-length" in headers:
+            content_length = int(headers["content-length"])
+            body = yield from buffered_stream.receive_exactly(content_length)
+
+        return cls(
+            method=method,
+            path=target,
+            http_version=version,
+            headers=headers,
+            body=body,
+        )
+
+    @staticmethod
+    def verify_http_method(method: str) -> TypeGuard[HTTPMethod]:
+        """Verifies that HTTP method is valid."""
+        return method in ALLOWED_HTTP_METHODS

one_ring_http-0.1.0/src/one_ring_http/response.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from one_ring_http.typedef import HTTPHeaders
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Response:
+    """A HTTP/1.1 response to be serialized."""
+
+    """HTTP status code of the response"""
+    status_code: int
+
+    """HTTP headers for the response"""
+    headers: HTTPHeaders = field(default_factory=dict)
+
+    """HTTP body for the response"""
+    body: bytes = field(default=b"")
+
+    def serialize(self) -> bytes:
+        """Serializes a response for transfer."""
+        # 1. Add first line
+        serialized_response = f"HTTP/1.1 {self.status_code}\r\n".encode()
+
+        # 2. Add headers
+        content_length = len(self.body)
+        serialized_response += f"content-length: {content_length}\r\n".encode()
+
+        for header_name, header_val in self.headers.items():
+            serialized_response += f"{header_name}: {header_val}\r\n".encode()
+
+        serialized_response += b"\r\n"
+
+        # 3. Add body
+        serialized_response += self.body
+
+        return serialized_response

one_ring_http-0.1.0/src/one_ring_http/router.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from one_ring_http.response import Response
+
+if TYPE_CHECKING:
+    from one_ring_http.request import Request
+    from one_ring_http.typedef import HTTPHandler, HTTPMethod
+
+
+def page_not_found(_: Request) -> Response:
+    """Default handler for 404."""
+    return Response(status_code=404)
+
+
+@dataclass(slots=True, kw_only=True)
+class Router:
+    """Routes HTTP request to handlers."""
+
+    _registry: dict[tuple[HTTPMethod, str], HTTPHandler] = field(
+        default_factory=dict, init=False
+    )
+
+    _fallback: HTTPHandler = field(default=page_not_found, init=False)
+
+    def add(self, method: HTTPMethod, path: str, handler: HTTPHandler) -> None:
+        """Registers a path."""
+        self._registry[(method, path)] = handler
+
+    def resolve(self, method: HTTPMethod, path: str) -> HTTPHandler:
+        """Returns the handler for a method and path."""
+        handler = self._registry.get((method, path))
+        if handler is None:
+            return self._fallback
+        return handler
+
+    def set_fallback(self, handler: HTTPHandler) -> None:
+        """Sets fallback."""
+        self._fallback = handler

one_ring_http-0.1.0/src/one_ring_http/server.py

@@ -0,0 +1,79 @@
+from collections.abc import Generator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from one_ring_http.log import get_logger
+from one_ring_http.request import Request
+from one_ring_loop import TaskGroup
+from one_ring_loop.cancellation import move_on_after
+from one_ring_loop.socketio import Connection, create_server
+from one_ring_loop.streams.buffered import BufferedByteStream
+from one_ring_loop.streams.tls import TLSStream
+
+logger = get_logger()
+
+if TYPE_CHECKING:
+    import ssl
+
+    from one_ring_http.router import Router
+    from one_ring_loop.typedefs import Coro
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class HTTPServer:
+    """A simple HTTP server built on one-ring-loop."""
+
+    """Routes method and path to a handler"""
+    router: Router
+
+    """The host for the server to run on"""
+    host: str
+
+    """The port for the server to run on"""
+    port: int
+
+    """The SSL context for TLS wrapping"""
+    ssl_context: ssl.SSLContext
+
+    def serve(self) -> Coro[None]:
+        """Starts the server."""
+        server = yield from create_server(self.host.encode(), self.port)
+        tg = TaskGroup()
+        tg.enter()
+        try:
+            while True:
+                conn = yield from server.accept()
+                tg.create_task(self._handle_connection(conn))
+        finally:
+            yield from tg.exit()
+
+    def _handle_connection(self, conn: Connection) -> Coro[None]:
+        """Handles an incoming connection."""
+        try:
+            try:
+                tls_con = yield from TLSStream.wrap(
+                    conn, ssl_context=self.ssl_context, standard_compatible=False
+                )
+            except Exception:
+                with move_on_after(3, shield=True):
+                    yield from conn.close()
+                raise
+
+            buffered_stream = BufferedByteStream(
+                receive_stream=tls_con, send_stream=tls_con
+            )
+
+            try:
+                request = yield from Request.parse(buffered_stream)
+                handler = self.router.resolve(request.method, request.path)
+                result = handler(request)
+                if isinstance(result, Generator):
+                    response = yield from result
+                else:
+                    response = result
+                yield from buffered_stream.send(response.serialize())
+            finally:
+                with move_on_after(3, shield=True):
+                    yield from buffered_stream.close()
+        except Exception:
+            logger.exception("Connection error")

one_ring_http-0.1.0/src/one_ring_http/static.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from one_ring_http.log import get_logger
+from one_ring_http.response import Response
+from one_ring_loop.fileio import open_file  # or however your file I/O is exposed
+
+if TYPE_CHECKING:
+    from one_ring_http.request import Request
+    from one_ring_http.typedef import HTTPHandler
+    from one_ring_loop.typedefs import Coro
+
+logger = get_logger()
+
+
+def static_handler(root: str | Path) -> HTTPHandler:
+    """Returns a handler that serves files from root directory."""
+    root_path = Path(root).resolve()
+
+    def handler(request: Request) -> Coro[Response]:
+        path = request.path
+        if path == "/":
+            path = "/index.html"
+
+        candidates = [
+            root_path / path.lstrip("/"),
+            root_path / (path.lstrip("/") + ".html"),
+            root_path / path.lstrip("/") / "index.html",
+        ]
+
+        for candidate in candidates:
+            # Resolve and check it's still under root
+            file_path = candidate.resolve()
+            if not file_path.is_relative_to(root_path) or not file_path.is_file():
+                continue
+            try:
+                file = yield from open_file(file_path)
+            except FileNotFoundError:
+                continue
+
+            try:
+                body = yield from file.read()
+                content_type = (
+                    mimetypes.guess_type(str(file_path))[0]
+                    or "application/octet-stream"
+                )
+            finally:
+                yield from file.close()
+
+            return Response(
+                status_code=200,
+                headers={"content-type": content_type},
+                body=body.encode(),
+            )
+
+        return Response(status_code=404, body=b"Not Found")
+
+    return handler

one_ring_http-0.1.0/src/one_ring_http/typedef.py

@@ -0,0 +1,12 @@
+from collections.abc import Callable
+from typing import Literal
+
+from one_ring_http.request import Request
+from one_ring_http.response import Response
+from one_ring_loop.typedefs import Coro
+
+type HTTPHeaders = dict[str, str]
+
+type HTTPMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+
+type HTTPHandler = Callable[[Request], Coro[Response] | Response]

one_ring_http-0.1.0/tests/conftest.py

@@ -0,0 +1,37 @@
+"""Shared test fixtures for one-ring-http."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from one_ring_http.typedef import HTTPHeaders
+    from one_ring_loop.streams.buffered import BufferedByteReceiveStream
+    from one_ring_loop.typedefs import Coro
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RawHTTPResponse:
+    """Parsed raw HTTP response from a buffered stream."""
+
+    status_code: int
+    headers: HTTPHeaders
+    body: bytes
+
+
+def parse_raw_response(stream: BufferedByteReceiveStream) -> Coro[RawHTTPResponse]:
+    """Reads and parses a raw HTTP response from a buffered byte stream."""
+    status_line = yield from stream.receive_until(delimiter=b"\r\n", max_bytes=65536)
+    status_code = int(status_line.split(b" ", 2)[1])
+
+    headers: dict[str, str] = {}
+    line = yield from stream.receive_until(delimiter=b"\r\n", max_bytes=65536)
+    while line:
+        key, val = line.split(b": ", 1)
+        headers[key.decode().lower()] = val.decode()
+        line = yield from stream.receive_until(delimiter=b"\r\n", max_bytes=65536)
+
+    body = b""
+    if "content-length" in headers:
+        body = yield from stream.receive_exactly(int(headers["content-length"]))
+
+    return RawHTTPResponse(status_code=status_code, headers=headers, body=body)