bitpoint 0.1.0__py3-none-any.whl

bitpoint/__init__.py

@@ -0,0 +1,8 @@
+"""Bitpoint: create HTTP endpoints quickly using files.
+
+This module is intentionally import-light: it is imported inside the
+per-endpoint environments (which only need `bitpoint.request` and
+`bitpoint.response`), so nothing here may import Flask.
+"""
+
+__version__ = "0.1.0"

bitpoint/__main__.py

@@ -0,0 +1,108 @@
+"""Command-line entry point: python -m bitpoint [options]."""
+
+import argparse
+import atexit
+import logging
+import os
+import signal
+import sys
+
+from . import __version__, router
+from .app import create_app
+
+log = logging.getLogger("bitpoint")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="python -m bitpoint",
+        description="Create HTTP endpoints quickly using files.",
+    )
+    parser.add_argument("--port", type=int, default=8000, help="listening port")
+    parser.add_argument("--host", default="127.0.0.1", help="listening address")
+    parser.add_argument(
+        "--dir", default="./routes", help="root directory for endpoints"
+    )
+    parser.add_argument(
+        "--production",
+        action="store_true",
+        help="hide tracebacks and disable filesystem-based hot reload",
+    )
+    parser.add_argument(
+        "--no-install",
+        action="store_true",
+        help="do not install dependencies automatically",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"bitpoint {__version__}"
+    )
+    args = parser.parse_args(argv)
+
+    routes_dir = os.path.abspath(args.dir)
+    if not os.path.isdir(routes_dir):
+        parser.error(f"routes directory not found: {routes_dir}")
+
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+    )
+
+    app = create_app(
+        routes_dir, production=args.production, install=not args.no_install
+    )
+    state = app.extensions["bitpoint"]
+
+    endpoints = list(router.iter_endpoints(routes_dir))
+    if endpoints:
+        for method, url, file_path in endpoints:
+            rel = os.path.join(
+                os.path.basename(routes_dir), os.path.relpath(file_path, routes_dir)
+            )
+            log.info("%-7s %s  (%s)", method, url, rel)
+    else:
+        log.warning("No endpoints found under %s", routes_dir)
+    if not args.no_install:
+        state["deps"].sync_all(routes_dir)
+
+    if hasattr(signal, "SIGHUP"):
+
+        def _reload(signum, frame):
+            log.info("SIGHUP received, reloading endpoints")
+            state["loader"].clear()
+            state["deps"].clear()
+            state["pool"].kill_all()
+
+        signal.signal(signal.SIGHUP, _reload)
+
+    if args.production:
+        pid_file = os.path.abspath("bitpoint.pid")
+        with open(pid_file, "w", encoding="utf-8") as fh:
+            fh.write(str(os.getpid()))
+
+        def _remove_pid_file():
+            try:
+                os.remove(pid_file)
+            except OSError:
+                pass
+
+        atexit.register(_remove_pid_file)
+
+    atexit.register(state["pool"].kill_all)
+
+    mode = "production" if args.production else "development"
+    log.info(
+        "Bitpoint %s serving %s on http://%s:%d (%s)",
+        __version__,
+        routes_dir,
+        args.host,
+        args.port,
+        mode,
+    )
+    try:
+        app.run(host=args.host, port=args.port, threaded=True, use_reloader=False)
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bitpoint/app.py

@@ -0,0 +1,158 @@
+"""The Flask application that powers Bitpoint.
+
+Flask is an implementation detail: a single catch-all view resolves the
+URL against the routes directory on every request, then executes the
+endpoint either in-process (no PEP 723 block) or through its persistent
+worker (isolated environment).
+"""
+
+import base64
+import logging
+import os
+import traceback
+
+from flask import Flask, Response
+from flask import request as flask_request
+
+from . import router
+from .deps import DependencyError, DepsManager
+from .loader import Loader
+from .request import CaseInsensitiveDict, HTTPError, Request
+from .response import normalize
+from .workers import WorkerCrash, WorkerPool
+
+log = logging.getLogger("bitpoint")
+
+ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+
+
+def create_app(routes_dir="./routes", production=False, install=True):
+    routes_dir = os.path.abspath(routes_dir)
+    app = Flask("bitpoint")
+    loader = Loader(routes_dir, production=production)
+    deps = DepsManager(production=production, install=install)
+    pool = WorkerPool(routes_dir, production=production)
+    app.extensions["bitpoint"] = {
+        "loader": loader,
+        "deps": deps,
+        "pool": pool,
+        "routes_dir": routes_dir,
+    }
+
+    def dispatch(path=""):
+        resolved = router.resolve(routes_dir, path)
+        if resolved is None:
+            pool.reap_deleted()
+            return _plain("404 Not Found\n", 404)
+        endpoint_dir, params = resolved
+        file_path = router.method_file(endpoint_dir, flask_request.method)
+        if file_path is None:
+            pool.reap_deleted()
+            allowed = router.allowed_methods(endpoint_dir)
+            if not allowed:
+                return _plain("404 Not Found\n", 404)
+            return _plain(
+                "405 Method Not Allowed\n", 405, extra={"Allow": ", ".join(allowed)}
+            )
+        try:
+            return _execute(file_path, params)
+        except HTTPError as exc:
+            return _plain(exc.message + "\n", exc.status)
+        except (DependencyError, WorkerCrash) as exc:
+            log.error("%s", exc)
+            body = "Internal Server Error\n" if production else str(exc) + "\n"
+            return _plain(body, 500)
+        except Exception:
+            log.exception("Unhandled error in %s", file_path)
+            body = "Internal Server Error\n" if production else traceback.format_exc()
+            return _plain(body, 500)
+
+    def _execute(file_path, params):
+        python = deps.python_for(file_path)
+        if python is None:
+            request = Request(
+                method=flask_request.method,
+                path=flask_request.path,
+                params=params,
+                args=flask_request.args.to_dict(),
+                headers=CaseInsensitiveDict(dict(flask_request.headers)),
+                body=flask_request.get_data(),
+            )
+            module = loader.load(file_path)
+            handler = getattr(module, "handle", None)
+            if handler is None:
+                raise RuntimeError(
+                    f"{os.path.relpath(file_path)} does not define a handle(request) function"
+                )
+            body, status, headers, content_type = normalize(handler(request))
+        else:
+            payload = {
+                "method": flask_request.method,
+                "path": flask_request.path,
+                "params": params,
+                "args": flask_request.args.to_dict(),
+                "headers": dict(flask_request.headers),
+                "body": base64.b64encode(flask_request.get_data()).decode("ascii"),
+            }
+            result = pool.request(file_path, python, payload)
+            error = result.get("error")
+            if error is not None:
+                if error.get("status"):
+                    raise HTTPError(error["status"], error.get("message", ""))
+                detail = error.get("traceback", "unknown endpoint error")
+                if "ModuleNotFoundError" in detail and not install:
+                    detail += (
+                        "\nDependencies for this endpoint are not installed and "
+                        "--no-install is active. Install them (uv sync --script "
+                        f"{os.path.relpath(file_path)}) or start without --no-install."
+                    )
+                return _endpoint_error(detail, production)
+            body = base64.b64decode(result["body"])
+            status = result["status"]
+            headers = result["headers"]
+            content_type = result["content_type"]
+        return _build_response(body, status, headers, content_type)
+
+    app.add_url_rule(
+        "/",
+        endpoint="bitpoint_root",
+        view_func=dispatch,
+        defaults={"path": ""},
+        methods=ALL_METHODS,
+        provide_automatic_options=False,
+    )
+    app.add_url_rule(
+        "/<path:path>",
+        endpoint="bitpoint_dispatch",
+        view_func=dispatch,
+        methods=ALL_METHODS,
+        provide_automatic_options=False,
+    )
+    return app
+
+
+def _endpoint_error(detail, production):
+    log.error("Endpoint error:\n%s", detail)
+    body = "Internal Server Error\n" if production else detail
+    return _plain(body, 500)
+
+
+def _build_response(body, status, headers, content_type):
+    response = Response(body, status=status)
+    response.headers.remove("Content-Type")
+    has_content_type = False
+    for key, value in headers:
+        if key.lower() == "content-type":
+            has_content_type = True
+        response.headers[key] = value
+    if content_type and not has_content_type:
+        response.headers["Content-Type"] = content_type
+    return response
+
+
+def _plain(body, status, extra=None):
+    response = Response(body, status=status, mimetype="text/plain")
+    if extra:
+        for key, value in extra.items():
+            response.headers[key] = value
+    return response

bitpoint/deps.py

@@ -0,0 +1,118 @@
+"""PEP 723 dependency handling, delegated to uv.
+
+For each endpoint with a script block, `uv sync --script` materializes a
+cached environment and `uv python find --script` locates its interpreter.
+That interpreter is what the worker pool uses to spawn the endpoint's
+persistent worker process.
+"""
+
+import hashlib
+import logging
+import os
+import re
+import shutil
+import subprocess
+import threading
+
+from . import router
+
+log = logging.getLogger("bitpoint")
+
+# Canonical PEP 723 regex, from the spec.
+PEP723_RE = re.compile(
+    r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s(?P<content>(^#(| .*)$\s)+)^# ///$"
+)
+
+
+class DependencyError(RuntimeError):
+    """uv is missing, or dependency resolution/installation failed."""
+
+
+def script_block(source):
+    """Return the PEP 723 `script` block of a source file, or None."""
+    for match in PEP723_RE.finditer(source):
+        if match.group("type") == "script":
+            return match.group(0)
+    return None
+
+
+class DepsManager:
+    """Decides how each endpoint runs and keeps its environment in sync.
+
+    python_for() returns None for endpoints without a PEP 723 block (they
+    run in-process, in the base environment) or the path to the isolated
+    environment's interpreter otherwise.
+    """
+
+    def __init__(self, production=False, install=True):
+        self.production = production
+        self.install = install
+        self._cache = {}  # file_path -> (mtime_ns, block_digest, python_path)
+        self._lock = threading.Lock()
+
+    def python_for(self, file_path):
+        file_path = os.path.abspath(file_path)
+        with self._lock:
+            cached = self._cache.get(file_path)
+            if cached is not None and self.production:
+                return cached[2]
+            mtime = os.stat(file_path).st_mtime_ns
+            if cached is not None and cached[0] == mtime:
+                return cached[2]
+            with open(file_path, encoding="utf-8") as fh:
+                block = script_block(fh.read())
+            if block is None:
+                self._cache[file_path] = (mtime, None, None)
+                return None
+            digest = hashlib.sha256(block.encode("utf-8")).hexdigest()
+            if cached is not None and cached[1] == digest and cached[2] is not None:
+                # The file changed but the dependency block did not: no resync.
+                self._cache[file_path] = (mtime, digest, cached[2])
+                return cached[2]
+            python = self._prepare(file_path)
+            self._cache[file_path] = (mtime, digest, python)
+            return python
+
+    def sync_all(self, routes_dir):
+        """Install every endpoint's dependencies (used at startup)."""
+        for _, url, file_path in router.iter_endpoints(routes_dir):
+            with open(file_path, encoding="utf-8") as fh:
+                if script_block(fh.read()) is None:
+                    continue
+            log.info(
+                "Syncing dependencies for %s",
+                os.path.relpath(file_path, os.path.dirname(routes_dir) or routes_dir),
+            )
+            try:
+                self.python_for(file_path)
+            except DependencyError as exc:
+                log.error("%s", exc)
+
+    def clear(self):
+        with self._lock:
+            self._cache.clear()
+
+    def _prepare(self, file_path):
+        if shutil.which("uv") is None:
+            raise DependencyError(
+                f"{os.path.relpath(file_path)} declares PEP 723 dependencies, but uv "
+                "is not on PATH. Install it: https://docs.astral.sh/uv/"
+            )
+        if self.install:
+            result = _run(["uv", "sync", "--script", file_path])
+            if result.returncode != 0:
+                raise DependencyError(
+                    f"uv sync failed for {os.path.relpath(file_path)}:\n"
+                    + result.stderr.strip()
+                )
+        result = _run(["uv", "python", "find", "--script", file_path])
+        if result.returncode != 0:
+            raise DependencyError(
+                f"could not resolve an interpreter for {os.path.relpath(file_path)}:\n"
+                + result.stderr.strip()
+            )
+        return result.stdout.strip().splitlines()[-1]
+
+
+def _run(cmd):
+    return subprocess.run(cmd, capture_output=True, text=True)

bitpoint/loader.py

@@ -0,0 +1,89 @@
+"""In-process loading of endpoints that have no PEP 723 block.
+
+Reloading never uses importlib.reload: a changed file is re-executed as
+a brand-new module object, so no stale state can survive. Shared code
+under routes/lib is tracked too; when any lib file changes, everything
+is evicted and re-imported fresh.
+"""
+
+import os
+import sys
+import threading
+import types
+
+
+class Loader:
+    def __init__(self, routes_dir, production=False):
+        self.routes_dir = os.path.abspath(routes_dir)
+        self.production = production
+        self._cache = {}  # file_path -> (mtime_ns, module)
+        self._lib_mtimes = None
+        self._lock = threading.Lock()
+        # lib/ modules are imported normally; without this, a re-import
+        # after eviction could hit a stale __pycache__ entry.
+        sys.dont_write_bytecode = True
+        if self.routes_dir not in sys.path:
+            sys.path.insert(0, self.routes_dir)
+        self._evict_lib()  # drop any 'lib' left over from a previous routes dir
+
+    def load(self, file_path):
+        file_path = os.path.abspath(file_path)
+        with self._lock:
+            if not self.production:
+                self._refresh_lib()
+            cached = self._cache.get(file_path)
+            if cached is not None:
+                if self.production or os.stat(file_path).st_mtime_ns == cached[0]:
+                    return cached[1]
+            mtime = os.stat(file_path).st_mtime_ns
+            module = self._execute(file_path)
+            self._cache[file_path] = (mtime, module)
+            return module
+
+    def clear(self):
+        with self._lock:
+            self._cache.clear()
+            self._lib_mtimes = None
+            self._evict_lib()
+            for name in [n for n in sys.modules if n.startswith("bitpoint_routes.")]:
+                del sys.modules[name]
+
+    def _execute(self, file_path):
+        rel = os.path.relpath(file_path, self.routes_dir)
+        name = "bitpoint_routes." + rel[:-3].replace(os.sep, ".").replace(
+            "[", "_"
+        ).replace("]", "_")
+        # Compile straight from source, never through the .pyc cache: its
+        # validator only looks at whole-second mtime and file size, which
+        # can serve stale code right after a save. Reload must be reliable.
+        with open(file_path, encoding="utf-8") as fh:
+            source = fh.read()
+        module = types.ModuleType(name)
+        module.__file__ = file_path
+        sys.modules[name] = module
+        code = compile(source, file_path, "exec")
+        exec(code, module.__dict__)
+        return module
+
+    def _refresh_lib(self):
+        lib_dir = os.path.join(self.routes_dir, "lib")
+        mtimes = {}
+        for dirpath, _, filenames in os.walk(lib_dir):
+            for filename in filenames:
+                if filename.endswith(".py"):
+                    path = os.path.join(dirpath, filename)
+                    try:
+                        mtimes[path] = os.stat(path).st_mtime_ns
+                    except OSError:
+                        pass
+        if self._lib_mtimes is None:
+            self._lib_mtimes = mtimes
+        elif mtimes != self._lib_mtimes:
+            self._lib_mtimes = mtimes
+            self._cache.clear()
+            self._evict_lib()
+
+    @staticmethod
+    def _evict_lib():
+        for name in [n for n in sys.modules if n == "lib" or n.startswith("lib.")]:
+            del sys.modules[name]

bitpoint/request.py

@@ -0,0 +1,60 @@
+"""The request object passed to every handle() function.
+
+This module must stay free of Flask imports: it is also imported inside
+the per-endpoint worker environments, where only the endpoint's own
+dependencies are installed.
+"""
+
+import json
+
+
+class HTTPError(Exception):
+    """An error with an associated HTTP status code."""
+
+    def __init__(self, status, message):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+class CaseInsensitiveDict(dict):
+    """A dict with case-insensitive string keys (stored lowercase)."""
+
+    def __init__(self, data=None):
+        super().__init__()
+        if data:
+            items = data.items() if hasattr(data, "items") else data
+            for key, value in items:
+                self[key] = value
+
+    def __setitem__(self, key, value):
+        super().__setitem__(key.lower(), value)
+
+    def __getitem__(self, key):
+        return super().__getitem__(key.lower())
+
+    def __contains__(self, key):
+        return super().__contains__(key.lower())
+
+    def get(self, key, default=None):
+        return super().get(key.lower(), default)
+
+
+class Request:
+    """What an endpoint receives: method, path, params, args, headers, body."""
+
+    __slots__ = ("method", "path", "params", "args", "headers", "body")
+
+    def __init__(self, method, path, params, args, headers, body):
+        self.method = method
+        self.path = path
+        self.params = params
+        self.args = args
+        self.headers = headers
+        self.body = body
+
+    def json(self):
+        try:
+            return json.loads(self.body)
+        except ValueError:
+            raise HTTPError(400, "Invalid JSON body") from None

bitpoint/response.py

@@ -0,0 +1,43 @@
+"""Translate handle() return values into HTTP responses.
+
+Must stay free of Flask imports: it also runs inside the per-endpoint
+worker environments.
+"""
+
+import json
+
+
+def normalize(rv):
+    """Return (body: bytes, status: int, headers: list[tuple], content_type).
+
+    content_type is None when there is no body (204) so the server can
+    omit the header entirely; explicit Content-Type headers from the
+    endpoint always win.
+    """
+    headers = []
+    status = None
+    body = rv
+    if isinstance(rv, tuple):
+        if len(rv) == 2:
+            body, status = rv
+        elif len(rv) == 3:
+            body, status, raw_headers = rv
+            items = (
+                raw_headers.items() if hasattr(raw_headers, "items") else raw_headers
+            )
+            headers = [(str(k), str(v)) for k, v in items]
+        else:
+            raise TypeError(
+                f"handle() returned a tuple of length {len(rv)}, "
+                "expected (body, status) or (body, status, headers)"
+            )
+    if body is None:
+        return b"", status if status is not None else 204, headers, None
+    if isinstance(body, str):
+        return body.encode("utf-8"), status or 200, headers, "text/plain; charset=utf-8"
+    if isinstance(body, (dict, list)):
+        data = json.dumps(body).encode("utf-8")
+        return data, status or 200, headers, "application/json"
+    if isinstance(body, (bytes, bytearray)):
+        return bytes(body), status or 200, headers, "application/octet-stream"
+    raise TypeError(f"handle() returned an unsupported type: {type(body).__name__}")

bitpoint/router.py

@@ -0,0 +1,91 @@
+"""Filesystem-based routing: the directory tree under `routes` is the router.
+
+Resolution happens against the live filesystem on every request, so new
+files and directories are picked up without any registration step.
+"""
+
+import os
+
+METHOD_FILES = ("get", "post", "put", "patch", "delete", "head", "options")
+RESERVED_DIRS = frozenset({"lib"})
+
+
+def resolve(routes_dir, url_path):
+    """Map a URL path to (endpoint_dir, params) or None if no directory matches."""
+    current = routes_dir
+    params = {}
+    for depth, segment in enumerate(s for s in url_path.split("/") if s):
+        if segment in (".", "..") or "\\" in segment or "\x00" in segment:
+            return None
+        if depth == 0 and segment in RESERVED_DIRS:
+            return None
+        try:
+            entries = os.listdir(current)
+        except OSError:
+            return None
+        if (
+            segment in entries
+            and not _is_dynamic(segment)
+            and os.path.isdir(os.path.join(current, segment))
+        ):
+            current = os.path.join(current, segment)
+            continue
+        dynamic = sorted(
+            e
+            for e in entries
+            if _is_dynamic(e) and os.path.isdir(os.path.join(current, e))
+        )
+        if not dynamic:
+            return None
+        params[dynamic[0][1:-1]] = segment
+        current = os.path.join(current, dynamic[0])
+    if not os.path.isdir(current):
+        return None
+    return current, params
+
+
+def method_file(endpoint_dir, method):
+    """Return the file that serves `method` in this directory, or None.
+
+    HEAD falls back to get.py when there is no head.py.
+    """
+    method = method.lower()
+    candidates = [method] if method != "head" else ["head", "get"]
+    for name in candidates:
+        if name in METHOD_FILES:
+            path = os.path.join(endpoint_dir, name + ".py")
+            if os.path.isfile(path):
+                return path
+    return None
+
+
+def allowed_methods(endpoint_dir):
+    """Methods served by this directory, for the Allow header."""
+    methods = {
+        name.upper()
+        for name in METHOD_FILES
+        if os.path.isfile(os.path.join(endpoint_dir, name + ".py"))
+    }
+    if "GET" in methods:
+        methods.add("HEAD")
+    return sorted(methods)
+
+
+def iter_endpoints(routes_dir):
+    """Yield (METHOD, url, file_path) for every endpoint under routes_dir."""
+    routes_dir = os.path.abspath(routes_dir)
+    for dirpath, dirnames, filenames in os.walk(routes_dir):
+        if os.path.abspath(dirpath) == routes_dir:
+            dirnames[:] = [d for d in dirnames if d not in RESERVED_DIRS]
+        dirnames.sort()
+        rel = os.path.relpath(dirpath, routes_dir)
+        segments = [] if rel == "." else rel.split(os.sep)
+        for filename in sorted(filenames):
+            stem, ext = os.path.splitext(filename)
+            if ext == ".py" and stem in METHOD_FILES:
+                url = "/" + "/".join(segments)
+                yield stem.upper(), url, os.path.join(dirpath, filename)
+
+
+def _is_dynamic(name):
+    return len(name) > 2 and name.startswith("[") and name.endswith("]")

bitpoint/worker.py

@@ -0,0 +1,89 @@
+"""Persistent endpoint worker.
+
+Runs inside the endpoint's isolated environment (resolved by uv) and
+serves requests over a newline-delimited JSON protocol: one request line
+in on stdin, one response line out on stdout. The endpoint module is
+loaded once per worker; the server kills and respawns the worker when
+the file changes, so a reload is always a fresh process.
+
+Only the standard library plus bitpoint.request/bitpoint.response are
+used here: the endpoint's environment does not contain Flask.
+"""
+
+import base64
+import json
+import os
+import sys
+import traceback
+import types
+
+
+def main():
+    file_path, routes_dir, bitpoint_parent = sys.argv[1:4]
+    # Endpoint print() calls must not corrupt the protocol: keep the real
+    # stdout for ourselves and point sys.stdout at stderr.
+    protocol_out = os.fdopen(os.dup(sys.stdout.fileno()), "w", buffering=1)
+    sys.stdout = sys.stderr
+    # Never read or write .pyc caches: their whole-second validator can
+    # hand a freshly-respawned worker the previous version of the code.
+    sys.dont_write_bytecode = True
+    sys.path.insert(0, bitpoint_parent)
+    sys.path.insert(0, routes_dir)
+
+    from bitpoint.request import CaseInsensitiveDict, HTTPError, Request
+    from bitpoint.response import normalize
+
+    module = None
+    load_error = None
+    try:
+        module = _load(file_path)
+    except BaseException:
+        load_error = traceback.format_exc()
+
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        payload = json.loads(line)
+        try:
+            if load_error is not None:
+                raise RuntimeError("endpoint failed to load:\n" + load_error)
+            handler = getattr(module, "handle", None)
+            if handler is None:
+                raise RuntimeError(
+                    f"{file_path} does not define a handle(request) function"
+                )
+            request = Request(
+                method=payload["method"],
+                path=payload["path"],
+                params=payload["params"],
+                args=payload["args"],
+                headers=CaseInsensitiveDict(payload["headers"]),
+                body=base64.b64decode(payload["body"]),
+            )
+            body, status, headers, content_type = normalize(handler(request))
+            result = {
+                "status": status,
+                "headers": headers,
+                "body": base64.b64encode(body).decode("ascii"),
+                "content_type": content_type,
+            }
+        except HTTPError as exc:
+            result = {"error": {"status": exc.status, "message": exc.message}}
+        except Exception:
+            result = {"error": {"traceback": traceback.format_exc()}}
+        protocol_out.write(json.dumps(result) + "\n")
+
+
+def _load(file_path):
+    with open(file_path, encoding="utf-8") as fh:
+        source = fh.read()
+    module = types.ModuleType("bitpoint_endpoint")
+    module.__file__ = file_path
+    sys.modules["bitpoint_endpoint"] = module
+    code = compile(source, file_path, "exec")
+    exec(code, module.__dict__)
+    return module
+
+
+if __name__ == "__main__":
+    main()

bitpoint/workers.py

@@ -0,0 +1,125 @@
+"""Worker pool: one persistent process per PEP 723 endpoint.
+
+Lifecycle: spawned lazily on first request, killed and respawned when
+the endpoint file changes (reload is always a fresh process, never a
+module reload), killed when the file disappears, and killed on SIGHUP
+in production so a `git pull` deploy picks up new code and dependencies.
+"""
+
+import json
+import logging
+import os
+import subprocess
+import threading
+
+log = logging.getLogger("bitpoint")
+
+_WORKER_SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "worker.py")
+_BITPOINT_PARENT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+class WorkerCrash(RuntimeError):
+    """The worker process died before producing a response."""
+
+
+class Worker:
+    def __init__(self, python, file_path, routes_dir):
+        self.python = python
+        self.file_path = file_path
+        self.mtime_ns = os.stat(file_path).st_mtime_ns
+        self._lock = threading.Lock()
+        self._proc = subprocess.Popen(
+            [python, _WORKER_SCRIPT, file_path, routes_dir, _BITPOINT_PARENT],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+        log.debug("Spawned worker %d for %s", self._proc.pid, file_path)
+
+    def request(self, payload):
+        """Send one request and read one response. Serialized per worker."""
+        with self._lock:
+            if self._proc.poll() is not None:
+                raise WorkerCrash(
+                    f"worker for {self.file_path} exited with code {self._proc.returncode}"
+                )
+            try:
+                self._proc.stdin.write(json.dumps(payload) + "\n")
+                self._proc.stdin.flush()
+            except OSError as exc:
+                raise WorkerCrash(
+                    f"worker for {self.file_path} is gone: {exc}"
+                ) from exc
+            line = self._proc.stdout.readline()
+            if not line:
+                raise WorkerCrash(
+                    f"worker for {self.file_path} died while handling a request"
+                )
+            return json.loads(line)
+
+    def alive(self):
+        return self._proc.poll() is None
+
+    def kill(self):
+        if self._proc.poll() is None:
+            self._proc.terminate()
+            try:
+                self._proc.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                self._proc.kill()
+                self._proc.wait()
+
+
+class WorkerPool:
+    def __init__(self, routes_dir, production=False):
+        self.routes_dir = routes_dir
+        self.production = production
+        self._workers = {}  # file_path -> Worker
+        self._lock = threading.Lock()
+
+    def request(self, file_path, python, payload):
+        worker = self._get(file_path, python)
+        try:
+            return worker.request(payload)
+        except WorkerCrash as exc:
+            # One respawn-and-retry; a second crash surfaces as a 500.
+            log.warning("%s, respawning", exc)
+            self._evict(worker)
+            worker = self._get(file_path, python)
+            return worker.request(payload)
+
+    def _get(self, file_path, python):
+        with self._lock:
+            worker = self._workers.get(file_path)
+            if worker is not None:
+                stale = worker.python != python or not worker.alive()
+                if not stale and not self.production:
+                    stale = os.stat(file_path).st_mtime_ns != worker.mtime_ns
+                if stale:
+                    worker.kill()
+                    del self._workers[file_path]
+                    worker = None
+            if worker is None:
+                worker = Worker(python, file_path, self.routes_dir)
+                self._workers[file_path] = worker
+            return worker
+
+    def _evict(self, worker):
+        with self._lock:
+            if self._workers.get(worker.file_path) is worker:
+                del self._workers[worker.file_path]
+        worker.kill()
+
+    def reap_deleted(self):
+        """Kill workers whose endpoint file no longer exists."""
+        with self._lock:
+            for path in [p for p in self._workers if not os.path.isfile(p)]:
+                log.info("Endpoint %s deleted, stopping its worker", path)
+                self._workers.pop(path).kill()
+
+    def kill_all(self):
+        with self._lock:
+            for worker in self._workers.values():
+                worker.kill()
+            self._workers.clear()

bitpoint-0.1.0.dist-info/METADATA

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: bitpoint
+Version: 0.1.0
+Summary: Create HTTP endpoints quickly using files, without going through a framework.
+Project-URL: Homepage, https://github.com/tanrax/bitpoint
+Project-URL: Repository, https://github.com/tanrax/bitpoint
+Project-URL: Issues, https://github.com/tanrax/bitpoint/issues
+Author-email: Andros Fenollosa <andros@fenollosa.email>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: endpoints,file-based-routing,http,microframework,pep723,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Requires-Dist: flask>=3.0
+Description-Content-Type: text/markdown
+
+# Bitpoint
+
+Create HTTP endpoints quickly using files, without going through a framework like Flask or FastAPI.
+
+- **File-based routing**: the directory structure defines the routes, the file name defines the HTTP method.
+- **Hot reload**: save the file and the server updates automatically. Deploy with a simple `git pull`.
+- **Per-endpoint dependencies**: each endpoint declares its dependencies with [PEP 723](https://peps.python.org/pep-0723/) and they are installed automatically in an isolated environment.
+
+Bitpoint is for the moments when a full project feels like too much: exposing a script as a webhook, mocking an API so the frontend can move forward, publishing a small internal service for your team, or keeping a handful of endpoints alive on a personal server. In all these cases the API is not the product, it is just plumbing, and spending an afternoon on scaffolding, virtual environments and deploy pipelines is out of proportion. With Bitpoint you write one file and you get one endpoint.
+
+Under the hood, Bitpoint stays out of your way. There is nothing to register and nothing to configure: no app object, no decorators, no config files, just a `handle` function per file. Dependency isolation is delegated to [uv](https://docs.astral.sh/uv/), with a cached environment per endpoint, so two endpoints can use incompatible versions of the same library without ever conflicting. Responses follow the type you return: a string becomes plain text, a dict becomes JSON, a tuple adds a status code and headers, and the sensible thing happens by default.
+
+## Installation
+
+```bash
+pip install bitpoint
+```
+
+Or, if you use [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install bitpoint
+```
+
+Python 3.9 or later. If you want per-endpoint dependencies, `uv` must be available on the server.
+
+## Quickstart
+
+Create a directory called `routes` and, inside it, a subdirectory called `hello` (this will be the route). Inside `hello`, create a file called `get.py` with the following content:
+
+```python
+# routes/hello/get.py
+
+def handle(request):
+    return "world"
+```
+
+Start the server with:
+
+```bash
+python -m bitpoint
+```
+
+You can now try your endpoint:
+
+```bash
+curl localhost:8000/hello
+```
+
+It will return:
+
+```
+world
+```
+
+## Routing
+
+The URL path maps to the directory path inside `routes`, and the HTTP method maps to the file name:
+
+```
+routes/
+├── hello/
+│   └── get.py          → GET  /hello
+├── users/
+│   ├── get.py          → GET  /users
+│   ├── post.py         → POST /users
+│   └── [id]/
+│       ├── get.py      → GET  /users/42
+│       └── delete.py   → DELETE /users/42
+└── lib/                → shared code, does not generate routes
+    └── db.py
+```
+
+Valid file names are the HTTP methods in lowercase: `get.py`, `post.py`, `put.py`, `patch.py`, `delete.py`, `head.py` and `options.py`. Any other file is ignored and does not generate routes, so you can keep helper modules next to your endpoints.
+
+### Dynamic routes
+
+A directory whose name is wrapped in brackets captures a URL segment:
+
+```python
+# routes/users/[id]/get.py
+
+def handle(request):
+    return {"user_id": request.params["id"]}
+```
+
+```bash
+curl localhost:8000/users/42
+# {"user_id": "42"}
+```
+
+Captured values always arrive as `str`. Type conversion is the endpoint's responsibility.
+
+## The `handle` contract
+
+Each endpoint exposes a `handle(request)` function. It is the only symbol Bitpoint looks for in the file, the rest of the module is yours.
+
+### The `request` object
+
+| Attribute | Type | Description |
+|---|---|---|
+| `request.method` | `str` | HTTP method in uppercase, for example `"GET"` |
+| `request.path` | `str` | Request path, for example `/users/42` |
+| `request.params` | `dict[str, str]` | Dynamic path segments |
+| `request.args` | `dict[str, str]` | Query string parameters |
+| `request.headers` | `dict[str, str]` | Headers, case-insensitive keys |
+| `request.body` | `bytes` | Raw request body |
+| `request.json()` | `Any` | Body parsed as JSON, raises a 400 error if invalid |
+
+Example with a query string:
+
+```python
+# routes/greet/get.py
+
+def handle(request):
+    name = request.args.get("name", "world")
+    return f"Hello, {name}!"
+```
+
+```bash
+curl "localhost:8000/greet?name=Bob"
+# Hello, Bob!
+```
+
+### Return values
+
+The return type determines the response:
+
+| Return | Response |
+|---|---|
+| `str` | `200`, `text/plain; charset=utf-8` |
+| `dict` or `list` | `200`, `application/json` |
+| `bytes` | `200`, `application/octet-stream` |
+| `(body, status)` | As above, with the given status code |
+| `(body, status, headers)` | Additionally with custom headers |
+| `None` | `204 No Content` |
+
+```python
+# routes/users/post.py
+
+def handle(request):
+    data = request.json()
+    return {"created": data["name"]}, 201
+```
+
+### Errors
+
+- If `handle` raises an exception, Bitpoint responds with `500`.
+- In development mode (the default) the body includes the traceback. In production (`--production`) the body is a generic message and the traceback goes to the log.
+- Path with no matching directory: `404`. Directory exists but there is no file for that method: `405` with the `Allow` header listing the available methods.
+
+## Dependencies
+
+Declare each endpoint's dependencies with a [PEP 723](https://peps.python.org/pep-0723/) block at the top of the file, the same format understood by `uv` and `pipx`:
+
+```python
+# routes/status/get.py
+
+# /// script
+# dependencies = ["requests"]
+# ///
+
+def handle(request):
+    import requests
+    return requests.get("https://example.com").json()
+```
+
+Bitpoint delegates resolution and installation to [uv](https://docs.astral.sh/uv/): each endpoint runs with its dependencies in an isolated, cached environment. Two endpoints can use incompatible versions of the same library without conflict.
+
+- An endpoint without a PEP 723 block runs in the base environment, with no extra cost.
+- Installation happens on first startup and whenever the dependency block changes, not on every request.
+
+> **Security note**: installing dependencies automatically after a `git pull` means running third-party code at deploy time. If you prefer to control that step, start with `--no-install` and Bitpoint will fail with a clear error on endpoints whose dependencies are not already installed.
+
+## Shared code
+
+The `routes/lib/` directory is reserved: it does not generate routes and is importable from any endpoint:
+
+```python
+# routes/lib/db.py
+
+def get_connection():
+    ...
+```
+
+```python
+# routes/users/get.py
+
+from lib.db import get_connection
+
+def handle(request):
+    conn = get_connection()
+    ...
+```
+
+## Configuration
+
+Everything is controlled from the command line, there is no configuration file:
+
+```bash
+python -m bitpoint [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--port` | `8000` | Listening port |
+| `--host` | `127.0.0.1` | Listening address |
+| `--dir` | `./routes` | Root directory for endpoints |
+| `--production` | disabled | Hides tracebacks and disables filesystem-based hot reload |
+| `--no-install` | disabled | Does not install dependencies automatically |
+
+## Hot reload
+
+In development mode, Bitpoint watches the `routes` directory and reloads each module when its file changes. There is no shared state across reloads: if your endpoint keeps in-memory state (caches, connections), it is lost on reload. For persistent state use external resources (a database, Redis, files).
+
+In production, filesystem-based reload is disabled. The recommended deploy flow is `git pull` followed by a reload signal:
+
+```bash
+git pull && kill -HUP $(cat bitpoint.pid)
+```
+
+## A real example
+
+A GitHub webhook that sends a Telegram message on every push:
+
+```python
+# routes/webhooks/github/post.py
+
+# /// script
+# dependencies = ["requests"]
+# ///
+import os
+import requests
+
+def handle(request):
+    if request.headers.get("x-github-event") != "push":
+        return None
+    payload = request.json()
+    pusher = payload["pusher"]["name"]
+    repo = payload["repository"]["name"]
+    commits = len(payload["commits"])
+    requests.post(
+        f"https://api.telegram.org/bot{os.environ['TELEGRAM_TOKEN']}/sendMessage",
+        json={
+            "chat_id": os.environ["TELEGRAM_CHAT_ID"],
+            "text": f"{pusher} pushed {commits} commit(s) to {repo}",
+        },
+    )
+    return None
+```
+
+One file, deployed with a `git pull`. No project, no virtualenv, no route registration, no restart.
+
+## Why not Flask or FastAPI?
+
+Use Flask or FastAPI when the API is your product: they are excellent frameworks and Bitpoint does not try to compete with them.
+
+Bitpoint is for when the API is just plumbing. A webhook here, an internal endpoint there, a mock for the frontend. In those cases a framework gives you power you will not use at the price of ceremony you have to pay every time: a project to scaffold, an app to configure, routes to register, a virtualenv to maintain and a server to restart. Bitpoint removes all of that by turning the decisions into conventions: the filesystem is the router, the file is the endpoint, and its header declares its dependencies.
+
+If an endpoint outgrows Bitpoint, nothing locks you in: `handle` is a plain function, and moving it to a Flask or FastAPI route is a copy-paste.
+
+## Small core
+
+Some areas are explicitly not covered in order to keep the core small:
+
+- Middleware and global hooks
+- Authentication
+- WebSockets and streaming
+- `async` endpoints
+- Static files
+
+If you need any of this today, Bitpoint is not your tool, you will have to use external tools.

bitpoint-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+bitpoint/__init__.py,sha256=gWKOyye32Cw9unXGjrVbhNrm7MTml68d6qkTVRsWSJg,275
+bitpoint/__main__.py,sha256=_WycoF3Ig_LsshTTPJtCak6wK8QceU77hqi5noro6Cw,3080
+bitpoint/app.py,sha256=IdX2H4vFi0FlQYhSGc_EIUVwt3KFTP9JO5AETfDRyNw,5888
+bitpoint/deps.py,sha256=HNxawER0FBG-GAmovRqgg6426-lUHX328KkY4xqokzk,4278
+bitpoint/loader.py,sha256=bSbGD-0_uvxJG8NZJ80ZS-hPfeR8L-Xna3xRkYwdZ8s,3406
+bitpoint/request.py,sha256=ad_01EPB-y_nEbuLkiS3I-WsQXXYagZtVU4E8IXPHjo,1699
+bitpoint/response.py,sha256=pEo9jQfVRQ3V-z7nvzH6UYaPcTi71BjadlO0OkNBzdw,1590
+bitpoint/router.py,sha256=t21T71BPERG2SRmhtfRKKDnycPcJLxPG_b4Hk3vXLm4,3114
+bitpoint/worker.py,sha256=R6yAlqPkXz9BF0tfTCy8_q6fdPzvXAPnq6bFrkSy5zU,3131
+bitpoint/workers.py,sha256=DpjA-mQ83mQdf4mhSXySdHL4EVGLxF2PNWRALitS2uI,4469
+bitpoint-0.1.0.dist-info/METADATA,sha256=RLT9bd6obkyLmWG-wiMPIYFUNxew91urRgOWLNUSaOs,10795
+bitpoint-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+bitpoint-0.1.0.dist-info/licenses/LICENSE,sha256=-ZEiPx9pAy1-h5EUoMe_jvG225xP7dxkqXo9zZqzuFM,1073
+bitpoint-0.1.0.dist-info/RECORD,,

bitpoint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

bitpoint-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andros Fenollosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.