gramlot-py-server 0.2.1__py3-none-any.whl

gramlot_py_server/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+"""Python server adapters for Gramlot: uvicorn, django, flask, fastapi and kajenn."""

gramlot_py_server/django.py

@@ -0,0 +1,156 @@
+# Copyright 2026 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+"""Translate the Gramlot Host protocol into Django views and URLs."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from secrets import token_urlsafe
+
+from asgiref.sync import async_to_sync
+from django.http import FileResponse, HttpResponse
+from django.urls import path
+from django.views.decorators.csrf import csrf_exempt
+from gramlot.server import (
+    FileHost,
+    HostCapacity,
+    PageExpired,
+    PageNotFound,
+    SourceNotFound,
+    runtime_asset,
+)
+
+MAX_REQUEST_BYTES = 4096
+OWNER_COOKIE = "gramlot_owner"
+COMPANION_MEDIA_TYPES = {
+    ".css": "text/css; charset=utf-8",
+    "_aux.js": "text/javascript; charset=utf-8",
+}
+
+
+class Pages:
+    """Own a Gramlot ``FileHost`` and expose it at one Django URLconf mount point.
+
+    Include ``urls`` at the same ``mount_path`` supplied here: ``mount_path`` is
+    passed to ``open_page`` as the mount prefix of browser URLs. The cookie
+    associates browser requests with in-process page records; it is not
+    authentication.
+
+    GET and HEAD serve a ``.css`` or ``_aux.js`` file whose real path is below the
+    pages folder: the companions of ``FileHost`` and ``Page.css`` files placed
+    there. Every other file of the folder is not served.
+
+    ``content_security_policy`` is the application's policy, sent as the
+    ``Content-Security-Policy`` header of each HTML page; ``{nonce}`` in it is
+    replaced by the nonce that ``open_page`` puts on the bootstrap script.
+    """
+
+    def __init__(self, pages: str | Path, *, mount_path: str = "", page_ttl: float = 1800,
+                 max_pages: int = 1000, content_security_policy: str | None = None) -> None:
+        self.mount_path = "/" + mount_path.strip("/") if mount_path.strip("/") else ""
+        self.content_security_policy = content_security_policy
+        self.host = FileHost(
+            pages,
+            runtime_url="/assets/gramlot.js",
+            main_url="/gramlot/main",
+            source_url="/gramlot/source",
+            close_url="/gramlot/close",
+            page_ttl=page_ttl,
+            max_pages=max_pages,
+        )
+        self.urls = [
+            path("assets/gramlot.js", self.asset),
+            path("gramlot/main", csrf_exempt(self.main)),
+            path("gramlot/source", csrf_exempt(self.source)),
+            path("gramlot/close", csrf_exempt(self.close)),
+            path("", self.page),
+            path("<path:page_path>", self.page),
+        ]
+
+    def asset(self, request):
+        if request.method not in ("GET", "HEAD"):
+            return HttpResponse(status=405)
+        response = FileResponse(runtime_asset().open("rb"), content_type="text/javascript")
+        response["Cache-Control"] = "no-cache"
+        return response
+
+    def page(self, request, page_path=""):
+        suffix = next((suffix for suffix in COMPANION_MEDIA_TYPES if page_path.endswith(suffix)), None)
+        if suffix is not None:
+            return self.companion(request, page_path, suffix)
+        if request.method not in ("GET", "HEAD"):
+            return HttpResponse(status=405)
+        owner = request.COOKIES.get(OWNER_COOKIE) or token_urlsafe(24)
+        try:
+            opened = async_to_sync(self.host.open_page)(page_path, owner=owner, prefix=self.mount_path)
+        except PageNotFound:
+            return HttpResponse("Page not found", status=404)
+        except HostCapacity:
+            return HttpResponse("Page capacity reached", status=503)
+        response = HttpResponse(opened.html, content_type="text/html; charset=utf-8")
+        response["Cache-Control"] = "no-store"
+        if self.content_security_policy is not None:
+            policy = self.content_security_policy.replace("{nonce}", opened.nonce)
+            response["Content-Security-Policy"] = policy
+        response.set_cookie(OWNER_COOKIE, owner, path=self.mount_path or "/", httponly=True, samesite="Lax")
+        return response
+
+    def companion(self, request, page_path, suffix):
+        """Serve the file of ``page_path`` when its real path is below the pages folder."""
+        if request.method not in ("GET", "HEAD"):
+            return HttpResponse(status=405)
+        root = self.host.pages_dir.resolve()
+        real = root.joinpath(*page_path.strip("/").split("/")).resolve()
+        if not (real.is_relative_to(root) and real.is_file()):
+            return HttpResponse("Not found", status=404)
+        body = b"" if request.method == "HEAD" else real.read_bytes()
+        response = HttpResponse(body, content_type=COMPANION_MEDIA_TYPES[suffix])
+        response["Cache-Control"] = "no-store"
+        return response
+
+    def main(self, request):
+        return self._operation(request, "main")
+
+    def source(self, request):
+        return self._operation(request, "source")
+
+    def close(self, request):
+        return self._operation(request, "close")
+
+    def _operation(self, request, operation):
+        if request.method != "POST":
+            return HttpResponse(status=405)
+        if request.content_type != "application/json":
+            return HttpResponse("Expected application/json", status=415)
+        if len(request.body) > MAX_REQUEST_BYTES:
+            return HttpResponse("Request too large", status=413)
+        try:
+            payload = json.loads(request.body)
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return HttpResponse("Invalid JSON request", status=400)
+        if not isinstance(payload, dict) or not isinstance(payload.get("pageId"), str):
+            return HttpResponse("Invalid JSON request", status=400)
+        if operation == "source" and not isinstance(payload.get("params", {}), dict):
+            return HttpResponse("Source params must be a dictionary", status=400)
+        owner = request.COOKIES.get(OWNER_COOKIE)
+        try:
+            if operation == "main":
+                result = async_to_sync(self.host.main)(payload["pageId"], owner=owner)
+            elif operation == "source":
+                result = async_to_sync(self.host.source)(
+                    payload["pageId"], payload.get("method"), payload.get("params", {}),
+                    owner=owner,
+                )
+            else:
+                self.host.close_page(payload["pageId"], owner=owner)
+                result = json.dumps({"ok": True})
+        except PageExpired:
+            return HttpResponse("Unknown page", status=404)
+        except SourceNotFound:
+            return HttpResponse("Unknown Source method", status=404)
+        response = HttpResponse(result, content_type="application/json")
+        response["Cache-Control"] = "no-store"
+        return response
+
+
+__all__ = ["Pages"]

gramlot_py_server/fastapi.py

@@ -0,0 +1,191 @@
+# Copyright 2026 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+"""FastAPI integration for the Gramlot ``Host`` protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from secrets import token_urlsafe
+
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.responses import HTMLResponse, Response
+from gramlot.server import (
+    FileHost,
+    HostCapacity,
+    PageExpired,
+    PageNotFound,
+    SourceNotFound,
+    runtime_asset,
+)
+
+MAX_REQUEST_BYTES = 4096
+OWNER_COOKIE = "gramlot_owner"
+COMPANION_MEDIA_TYPES = {
+    ".css": "text/css; charset=utf-8",
+    "_aux.js": "text/javascript; charset=utf-8",
+}
+
+
+class Pages:
+    """Own a Gramlot ``FileHost`` and its FastAPI route translations.
+
+    The routes are included at ``mount_path``, which is also passed to
+    ``open_page`` as the mount prefix of browser URLs.
+
+    GET and HEAD serve a ``.css`` or ``_aux.js`` file whose real path is below the
+    pages folder: the companions of ``FileHost`` and ``Page.css`` files placed
+    there. Every other file of the folder is not served.
+
+    ``content_security_policy`` is the application's policy, sent as the
+    ``Content-Security-Policy`` header of each HTML page; ``{nonce}`` in it is
+    replaced by the nonce that ``open_page`` puts on the bootstrap script.
+    """
+
+    def __init__(self, pages: str | Path, *, mount_path: str = "", page_ttl: float = 1800,
+                 max_pages: int = 1000, content_security_policy: str | None = None) -> None:
+        self.mount_path = "/" + mount_path.strip("/") if mount_path.strip("/") else ""
+        self.content_security_policy = content_security_policy
+        self.host = FileHost(
+            pages,
+            runtime_url="/assets/gramlot.js",
+            main_url="/gramlot/main",
+            source_url="/gramlot/source",
+            close_url="/gramlot/close",
+            page_ttl=page_ttl,
+            max_pages=max_pages,
+        )
+
+    def mount(self, app: FastAPI) -> None:
+        router = APIRouter(prefix=self.mount_path)
+        router.add_api_route("/assets/gramlot.js", self.asset, methods=["GET", "HEAD"])
+        router.add_api_route("/gramlot/main", self.main, methods=["POST"])
+        router.add_api_route("/gramlot/source", self.source, methods=["POST"])
+        router.add_api_route("/gramlot/close", self.close, methods=["POST"])
+        router.add_api_route("/", self.page, methods=["GET", "HEAD"])
+        router.add_api_route("/{page_path:path}", self.page, methods=["GET", "HEAD"])
+        app.include_router(router)
+        app.router.add_event_handler("shutdown", self.shutdown)
+
+    async def shutdown(self) -> None:
+        self.host._pages.clear()
+
+    async def asset(self, request: Request) -> Response:
+        body = b"" if request.method == "HEAD" else runtime_asset().read_bytes()
+        return Response(body, media_type="text/javascript", headers={"Cache-Control": "no-cache"})
+
+    async def page(self, request: Request, page_path: str = "") -> Response:
+        suffix = next((suffix for suffix in COMPANION_MEDIA_TYPES if page_path.endswith(suffix)), None)
+        if suffix is not None:
+            return await self.companion(request, page_path, suffix)
+        if request.method != "GET":
+            return Response(status_code=405, headers={"Allow": "GET"})
+        owner = request.cookies.get(OWNER_COOKIE) or token_urlsafe(24)
+        try:
+            opened = await self.host.open_page(page_path, owner=owner, prefix=self.mount_path)
+        except PageNotFound:
+            return Response("Page not found", status_code=404)
+        except HostCapacity:
+            return Response("Page capacity reached", status_code=503)
+        headers = {"Cache-Control": "no-store"}
+        if self.content_security_policy is not None:
+            headers["Content-Security-Policy"] = self.content_security_policy.replace("{nonce}", opened.nonce)
+        response = HTMLResponse(opened.html, headers=headers)
+        response.set_cookie(
+            OWNER_COOKIE,
+            owner,
+            path=self.mount_path or "/",
+            httponly=True,
+            samesite="lax",
+        )
+        return response
+
+    async def companion(self, request: Request, page_path: str, suffix: str) -> Response:
+        """Serve the file of ``page_path`` when its real path is below the pages folder."""
+        root = self.host.pages_dir.resolve()
+        real = root.joinpath(*page_path.strip("/").split("/")).resolve()
+        if not (real.is_relative_to(root) and real.is_file()):
+            return Response("Not found", status_code=404)
+        body = b"" if request.method == "HEAD" else await asyncio.to_thread(real.read_bytes)
+        return Response(body, headers={"Content-Type": COMPANION_MEDIA_TYPES[suffix],
+                                       "Cache-Control": "no-store"})
+
+    async def main(self, request: Request) -> Response:
+        return await self._operation(request, "main")
+
+    async def source(self, request: Request) -> Response:
+        return await self._operation(request, "source")
+
+    async def close(self, request: Request) -> Response:
+        return await self._operation(request, "close")
+
+    async def _operation(self, request: Request, operation: str) -> Response:
+        if request.headers.get("content-type", "").split(";", 1)[0].strip().lower() != "application/json":
+            return Response("Expected application/json", status_code=415)
+        try:
+            raw = await self._body(request)
+            payload = json.loads(raw)
+            if not isinstance(payload, dict) or not isinstance(payload.get("pageId"), str):
+                raise ValueError
+        except RequestTooLarge:
+            return Response("Request too large", status_code=413)
+        except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+            return Response("Invalid JSON request", status_code=400)
+        owner = request.cookies.get(OWNER_COOKIE)
+        if operation == "source" and not isinstance(payload.get("params", {}), dict):
+            return Response("Source params must be a dictionary", status_code=400)
+        try:
+            if operation == "main":
+                result = await self.host.main(payload["pageId"], owner=owner)
+            elif operation == "source":
+                result = await self.host.source(
+                    payload["pageId"], payload.get("method"), payload.get("params", {}), owner=owner
+                )
+            else:
+                self.host.close_page(payload["pageId"], owner=owner)
+                result = json.dumps({"ok": True})
+        except PageExpired:
+            return Response("Unknown page", status_code=404)
+        except SourceNotFound:
+            return Response("Unknown Source method", status_code=404)
+        return Response(result, media_type="application/json", headers={"Cache-Control": "no-store"})
+
+    @staticmethod
+    async def _body(request: Request) -> str:
+        length = request.headers.get("content-length")
+        if length and length.isdigit() and int(length) > MAX_REQUEST_BYTES:
+            raise RequestTooLarge
+        body = bytearray()
+        async for chunk in request.stream():
+            body.extend(chunk)
+            if len(body) > MAX_REQUEST_BYTES:
+                raise RequestTooLarge
+        return body.decode()
+
+
+class RequestTooLarge(ValueError):
+    pass
+
+
+class Application(FastAPI):
+    """Ready-made FastAPI application serving Gramlot pages."""
+
+    def __init__(self, pages: str | Path, *, mount_path: str = "", page_ttl: float = 1800,
+                 max_pages: int = 1000, content_security_policy: str | None = None,
+                 **fastapi_options) -> None:
+        super().__init__(**fastapi_options)
+        self.gramlot_pages = mount_pages(
+            self, pages, mount_path=mount_path, page_ttl=page_ttl, max_pages=max_pages,
+            content_security_policy=content_security_policy,
+        )
+
+
+def mount_pages(app: FastAPI, pages: str | Path, **options) -> Pages:
+    """Mount the bounded Gramlot page protocol on an existing FastAPI app."""
+
+    integration = Pages(pages, **options)
+    integration.mount(app)
+    return integration
+
+
+__all__ = ["Application", "Pages", "mount_pages"]

gramlot_py_server/flask.py

@@ -0,0 +1,159 @@
+# Copyright 2026 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+"""Flask integration for the Gramlot ``Host`` protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from secrets import token_urlsafe
+
+from flask import Blueprint, Response, request
+from gramlot.server import (
+    FileHost,
+    HostCapacity,
+    PageExpired,
+    PageNotFound,
+    SourceNotFound,
+    runtime_asset,
+)
+
+MAX_REQUEST_BYTES = 4096
+OWNER_COOKIE = "gramlot_owner"
+COMPANION_MEDIA_TYPES = {
+    ".css": "text/css; charset=utf-8",
+    "_aux.js": "text/javascript; charset=utf-8",
+}
+
+
+class Pages:
+    """Own a Gramlot ``FileHost`` and its WSGI route translations.
+
+    The blueprint is registered at ``mount_path``, which is also passed to
+    ``open_page`` as the mount prefix of browser URLs.
+
+    GET and HEAD serve a ``.css`` or ``_aux.js`` file whose real path is below the
+    pages folder: the companions of ``FileHost`` and ``Page.css`` files placed
+    there. Every other file of the folder is not served.
+
+    ``content_security_policy`` is the application's policy, sent as the
+    ``Content-Security-Policy`` header of each HTML page; ``{nonce}`` in it is
+    replaced by the nonce that ``open_page`` puts on the bootstrap script.
+    """
+
+    def __init__(self, pages: str | Path, *, mount_path: str = "", page_ttl: float = 1800,
+                 max_pages: int = 1000, content_security_policy: str | None = None) -> None:
+        self.mount_path = "/" + mount_path.strip("/") if mount_path.strip("/") else ""
+        self.content_security_policy = content_security_policy
+        self.host = FileHost(
+            pages,
+            runtime_url="/assets/gramlot.js",
+            main_url="/gramlot/main",
+            source_url="/gramlot/source",
+            close_url="/gramlot/close",
+            page_ttl=page_ttl,
+            max_pages=max_pages,
+        )
+
+    def blueprint(self) -> Blueprint:
+        name = "gramlot_pages_" + (self.mount_path.strip("/") or "root").replace("/", "_")
+        blueprint = Blueprint(name, __name__, url_prefix=self.mount_path or None)
+        blueprint.add_url_rule("/assets/gramlot.js", "asset", self.asset, methods=["GET", "HEAD"])
+        blueprint.add_url_rule("/gramlot/main", "main", self.main, methods=["POST"])
+        blueprint.add_url_rule("/gramlot/source", "source", self.source, methods=["POST"])
+        blueprint.add_url_rule("/gramlot/close", "close", self.close, methods=["POST"])
+        blueprint.add_url_rule("/", "index", self.page, defaults={"page_path": ""})
+        blueprint.add_url_rule("/<path:page_path>", "page", self.page)
+        return blueprint
+
+    def asset(self) -> Response:
+        body = b"" if request.method == "HEAD" else runtime_asset().read_bytes()
+        return Response(body, mimetype="text/javascript", headers={"Cache-Control": "no-cache"})
+
+    def page(self, page_path="") -> Response:
+        suffix = next((suffix for suffix in COMPANION_MEDIA_TYPES if page_path.endswith(suffix)), None)
+        if suffix is not None:
+            return self.companion(page_path, suffix)
+        owner = request.cookies.get(OWNER_COOKIE) or token_urlsafe(24)
+        try:
+            opened = asyncio.run(self.host.open_page(page_path, owner=owner, prefix=self.mount_path))
+        except PageNotFound:
+            return Response("Page not found", status=404)
+        except HostCapacity:
+            return Response("Page capacity reached", status=503)
+        headers = {"Cache-Control": "no-store"}
+        if self.content_security_policy is not None:
+            headers["Content-Security-Policy"] = self.content_security_policy.replace("{nonce}", opened.nonce)
+        response = Response(opened.html, mimetype="text/html", headers=headers)
+        response.set_cookie(
+            OWNER_COOKIE,
+            owner,
+            path=self.mount_path or "/",
+            httponly=True,
+            samesite="Lax",
+        )
+        return response
+
+    def companion(self, page_path: str, suffix: str) -> Response:
+        """Serve the file of ``page_path`` when its real path is below the pages folder."""
+        root = self.host.pages_dir.resolve()
+        real = root.joinpath(*page_path.strip("/").split("/")).resolve()
+        if not (real.is_relative_to(root) and real.is_file()):
+            return Response("Not found", status=404)
+        body = b"" if request.method == "HEAD" else real.read_bytes()
+        return Response(body, content_type=COMPANION_MEDIA_TYPES[suffix],
+                        headers={"Cache-Control": "no-store"})
+
+    def main(self) -> Response:
+        return self._operation("main")
+
+    def source(self) -> Response:
+        return self._operation("source")
+
+    def close(self) -> Response:
+        return self._operation("close")
+
+    def _operation(self, operation: str) -> Response:
+        if request.mimetype != "application/json":
+            return Response("Expected application/json", status=415)
+        if request.content_length is not None and request.content_length > MAX_REQUEST_BYTES:
+            return Response("Request too large", status=413)
+        raw = request.get_data(cache=False)
+        if len(raw) > MAX_REQUEST_BYTES:
+            return Response("Request too large", status=413)
+        try:
+            payload = json.loads(raw)
+            if not isinstance(payload, dict) or not isinstance(payload.get("pageId"), str):
+                raise ValueError
+        except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+            return Response("Invalid JSON request", status=400)
+        owner = request.cookies.get(OWNER_COOKIE)
+        if operation == "source" and not isinstance(payload.get("params", {}), dict):
+            return Response("Source params must be a dictionary", status=400)
+        try:
+            if operation == "main":
+                result = asyncio.run(self.host.main(payload["pageId"], owner=owner))
+            elif operation == "source":
+                result = asyncio.run(self.host.source(
+                    payload["pageId"], payload.get("method"), payload.get("params", {}), owner=owner
+                ))
+            else:
+                self.host.close_page(payload["pageId"], owner=owner)
+                result = json.dumps({"ok": True})
+        except PageExpired:
+            return Response("Unknown page", status=404)
+        except SourceNotFound:
+            return Response("Unknown Source method", status=404)
+        return Response(result, mimetype="application/json", headers={"Cache-Control": "no-store"})
+
+
+def mount_pages(app, pages: str | Path, **options) -> Pages:
+    """Mount the bounded Gramlot page protocol on an existing Flask app."""
+
+    integration = Pages(pages, **options)
+    app.register_blueprint(integration.blueprint())
+    app.extensions.setdefault("gramlot_pages", {})[integration.mount_path] = integration
+    return integration
+
+
+__all__ = ["Pages", "mount_pages"]