fastapi-vue 0.0.1__tar.gz

fastapi_vue-0.0.1/.gitignore

@@ -0,0 +1,5 @@
+.*
+!.gitignore
+*.lock
+__pycache__/
+dist/

fastapi_vue-0.0.1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: fastapi-vue
+Version: 0.0.1
+Summary: Serves Vue static files / SPA on a FastAPI app. Use fastapi-vue-setup to install.
+Project-URL: Homepage, https://git.zi.fi/LeoVasanko/fastapi-vue
+Project-URL: Repository, https://github.com/LeoVasanko/fastapi-vue
+Requires-Python: >=3.11
+Requires-Dist: aeg>=0.9.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: zstandard>=0.23.0
+Description-Content-Type: text/markdown
+
+# fastapi-vue
+
+Implements static files routing with caching, compression and SPA support. Can be mounted at site root, unlike the built-in module.
+
+- Automatic zstd compression
+- ETag-based caching with immutable headers for hashed assets
+- SPA (Single Page Application) support
+- Favicon handling from hashed assets
+- Dev mode integration with Vite
+
+## Installation
+
+```bash
+uv add fastapi-vue
+```
+
+## Usage
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi_vue import Frontend
+
+# Point to your built frontend assets
+frontend = Frontend(
+    "path/to/frontend-build",
+    spa=True,
+    favicon="/assets/favicon.ico",
+    cached=["/assets/"],
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await frontend.load()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+# All your other routes...
+
+# Final catch-all route for frontend files (keep at end of file)
+frontend.route(app, "/")
+```
+
+## Configuration
+
+- `directory`: Path to static files directory
+- `spa`: Enable SPA mode (serve index.html for unknown routes)
+- `cached`: Path prefixes for immutable cache headers (e.g., `["/assets/"]`)
+- `favicon`: Path prefix to serve at `/favicon.ico` (e.g., `"/assets/favicon.webp"`)
+- `zstdlevel`: Compression level (default: 18)
+
+## See also
+
+Script [fastapi-vue-setup](https://github.com/LeoVasanko/fastapi-vue-setup) to create a project with statically built Vue using this module, and Vite devmode support.

fastapi_vue-0.0.1/README.md

@@ -0,0 +1,55 @@
+# fastapi-vue
+
+Implements static files routing with caching, compression and SPA support. Can be mounted at site root, unlike the built-in module.
+
+- Automatic zstd compression
+- ETag-based caching with immutable headers for hashed assets
+- SPA (Single Page Application) support
+- Favicon handling from hashed assets
+- Dev mode integration with Vite
+
+## Installation
+
+```bash
+uv add fastapi-vue
+```
+
+## Usage
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi_vue import Frontend
+
+# Point to your built frontend assets
+frontend = Frontend(
+    "path/to/frontend-build",
+    spa=True,
+    favicon="/assets/favicon.ico",
+    cached=["/assets/"],
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await frontend.load()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+# All your other routes...
+
+# Final catch-all route for frontend files (keep at end of file)
+frontend.route(app, "/")
+```
+
+## Configuration
+
+- `directory`: Path to static files directory
+- `spa`: Enable SPA mode (serve index.html for unknown routes)
+- `cached`: Path prefixes for immutable cache headers (e.g., `["/assets/"]`)
+- `favicon`: Path prefix to serve at `/favicon.ico` (e.g., `"/assets/favicon.webp"`)
+- `zstdlevel`: Compression level (default: 18)
+
+## See also
+
+Script [fastapi-vue-setup](https://github.com/LeoVasanko/fastapi-vue-setup) to create a project with statically built Vue using this module, and Vite devmode support.

fastapi_vue-0.0.1/dist/.gitignore

@@ -0,0 +1 @@
+*

fastapi_vue-0.0.1/fastapi_vue/__init__.py

@@ -0,0 +1,3 @@
+from .staticfiles import Frontend
+
+__all__ = ["Frontend"]

fastapi_vue-0.0.1/fastapi_vue/staticfiles.py

@@ -0,0 +1,253 @@
+"""FastAPI static file serving with zstd compression and SPA support."""
+
+import asyncio
+import mimetypes
+import os
+import time
+from pathlib import Path, PurePath, PurePosixPath
+from wsgiref.handlers import format_date_time
+
+from aeg.aegis128x2 import mac
+from fastapi import FastAPI, Request, Response
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import JSONResponse, RedirectResponse
+from starlette.exceptions import HTTPException
+from zstandard import ZstdCompressor
+
+# Dev mode: index files but don't load content, return error responses
+_DEVMODE = os.getenv("FASTAPI_VUE_FRONTEND_URL")
+
+
+class Frontend:
+    """Static file server with automatic zstd compression and caching.
+
+    Features:
+    - Automatic zstd compression for compressible files
+    - ETag-based caching with configurable cache headers
+    - SPA (Single Page Application) support
+    - Favicon handling from hashed assets
+    - Dev mode: indexes files but returns error directing to Vite server
+
+    Args:
+        directory: Path to the directory containing static files
+        index: Name of the index file (default: "index.html")
+        spa: Enable SPA mode - serve index.html for unknown routes (default: False)
+        cached: Path prefixes that should have immutable cache headers
+        zstdlevel: Zstd compression level (default: 18)
+        favicon: Path to favicon for automatic /favicon.ico handling
+    """
+
+    def __init__(
+        self,
+        directory: Path | str,
+        *,
+        index: str = "index.html",
+        spa: bool = False,
+        cached: str | list[str] | None = None,
+        zstdlevel: int = 18,
+        favicon: str | None = None,
+    ) -> None:
+        self.www: dict[str, tuple[bytes, bytes | None, dict]] = {}
+        self.base: Path = Path(directory)
+        self.index = index
+        self.spa = spa
+        if cached is None:
+            self.cached_paths = []
+        elif isinstance(cached, str):
+            self.cached_paths = [cached]
+        else:
+            self.cached_paths = cached
+        self.zstdlevel = zstdlevel
+        self.favicon = favicon
+        self.devmode = bool(_DEVMODE)
+
+    def _index_only(self) -> set[str]:
+        """Index file paths without loading content (for dev mode)."""
+        paths: set[str] = set()
+        if not self.base.exists():
+            return paths
+        queue = [PurePath()]
+        while queue:
+            current = self.base / queue.pop(0)
+            for p in current.iterdir():
+                rel = p.relative_to(self.base)
+                if p.is_dir():
+                    queue.append(rel)
+                    continue
+                name = "/" + rel.as_posix()
+                name = name.removesuffix(self.index)
+                paths.add(name)
+        if self.favicon:
+            p = PurePosixPath(self.favicon)
+            base = str(p.with_suffix(""))
+            ext = p.suffix
+            if any(path.startswith(base) and path.endswith(ext) for path in paths):
+                paths.add("/favicon.ico")
+        return paths
+
+    def _load(self, existing: dict):
+        """Load static files from disk with compression."""
+        new: dict[str, tuple[bytes, bytes | None, dict]] = {}
+        paths = [PurePath()]
+        while paths:
+            current = self.base / paths.pop(0)
+            for p in current.iterdir():
+                rel = p.relative_to(self.base)
+                if p.is_dir():
+                    paths.append(rel)
+                    continue
+                # Read file
+                name = "/" + rel.as_posix()
+                mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
+                name = name.removesuffix(self.index)
+                data = p.read_bytes()
+                etag = mac(bytes(16), None, data)[:8].hex()
+                # Keep existing identical files as they are
+                if name in existing and existing[name][2]["etag"] == etag:
+                    new[name] = existing[name]
+                    continue
+                if mime.startswith("text/"):
+                    mime += "; charset=UTF-8"
+                mtime = p.stat().st_mtime
+                cached = any(name.startswith(prefix) for prefix in self.cached_paths)
+                headers = {
+                    "etag": etag,
+                    "last-modified": format_date_time(mtime),
+                    "cache-control": (
+                        "max-age=31536000, immutable" if cached else "no-cache"
+                    ),
+                    "content-type": mime,
+                }
+                zstd = ZstdCompressor(self.zstdlevel).compress(data)
+                if len(zstd) >= len(data):
+                    zstd = None
+                new[name] = data, zstd, headers
+        if self.favicon:
+            p = PurePosixPath(self.favicon)
+            base = str(p.with_suffix(""))
+            ext = p.suffix
+            hashed_path = next(
+                (path for path in new if path.startswith(base) and path.endswith(ext)),
+                None,
+            )
+            if hashed_path:
+                new["/favicon.ico"] = new[hashed_path]
+        if not new:
+            msg = "Frontend files missing, check your installation.\n"
+            new["/"] = (
+                msg.encode(),
+                None,
+                {
+                    "etag": "error",
+                    "content-type": "text/plain",
+                    "cache-control": "no-store",
+                },
+            )
+        return new
+
+    async def load(self, *, log=True):
+        """Load or reload static files from disk.
+
+        In dev mode (FASTAPI_VUE_FRONTEND_URL set), only indexes paths without loading content.
+        """
+        start = time.perf_counter()
+        if self.devmode:
+            # Dev mode: just index paths, no content loading
+            paths = await run_in_threadpool(self._index_only)
+            self._devmode_paths = paths
+            duration = time.perf_counter() - start
+            if log and paths:
+                print(
+                    f"{self.base.name}: indexed {len(paths)} paths in {1000 * duration:.1f} ms (dev mode)"
+                )
+            return
+
+        self.www = await run_in_threadpool(self._load, self.www)
+        duration = time.perf_counter() - start
+        if not log:
+            return
+        compfiles = [(len(d), len(z)) for d, z, _ in self.www.values() if z]
+        raw = sum(v[0] for v in compfiles)
+        comp = sum(v[1] for v in compfiles)
+        ratio = comp / raw * 100 if raw else 100.0
+        print(
+            f"{self.base.name}: {len(self.www)} files in {1000 * duration:.1f} ms | "
+            f"zstd {len(compfiles)} files {1e-6 * raw:.2f}->{1e-6 * comp:.2f} MB ({ratio:.0f} %)"
+        )
+
+    async def refresh_task(self, interval=1.0):
+        """Background task to watch for file changes (for development)."""
+        if self.devmode:
+            return  # No refresh needed in dev mode
+        try:
+            while True:
+                await asyncio.sleep(interval)
+                old = self.www
+                await self.load(log=False)
+                changes = []
+                changes += [
+                    f"{h.get('last-modified', '')} {n}"
+                    for n, (_, _, h) in sorted(self.www.items())
+                    if not (n in old and old[n][2] is h)
+                ]
+                deleted = set(old) - set(self.www)
+                changes += [f"Deleted {name}" for name in sorted(deleted)]
+                if changes:
+                    print("Updated static files:\n" + "\n".join(changes))
+        except asyncio.CancelledError:
+            return
+
+    def route(self, app: FastAPI, mount_path="/", *, name="static"):
+        """Register this frontend handler with a FastAPI app.
+
+        Args:
+            app: FastAPI application instance
+            mount_path: Path where the frontend should be mounted (default: "/")
+            name: Route name for the handler
+        """
+        # Skip routing if in dev mode and no files were indexed
+        if self.devmode and not getattr(self, "_devmode_paths", None):
+            return
+        path = mount_path.rstrip("/") + "{path:path}"
+        app.api_route(path, methods=["GET", "HEAD"], name=name)(self.handle)
+
+    def handle(self, request: Request, path: str):
+        """Static file handler. Takes path already stripped of mount_path prefix."""
+        name = path.removesuffix(self.index)
+
+        # Dev mode: return error directing to Vite server
+        if self.devmode:
+            paths = getattr(self, "_devmode_paths", set())
+            if name not in paths:
+                if name and f"{name}/" in paths:
+                    return RedirectResponse(request.url.path + "/")
+                if self.spa and "text/html" in request.headers.get("accept", ""):
+                    name = "/"
+                if name not in paths:
+                    raise HTTPException(status_code=404)
+            return JSONResponse(
+                status_code=503,
+                content={
+                    "detail": "Frontend assets served by Vite in dev mode. "
+                    f"Connect via {_DEVMODE} instead."
+                },
+            )
+
+        if name not in self.www:
+            # Friendly redirect for directories missing trailing slash
+            if name and f"{name}/" in self.www:
+                return RedirectResponse(request.url.path + "/")
+            # SPA support: serve / for unknown paths if the browser wants HTML
+            if self.spa and "text/html" in request.headers.get("accept", ""):
+                name = "/"
+            # 404 for everything else
+            if name not in self.www:
+                raise HTTPException(status_code=404)
+        # File found, give the appropriate response
+        data, zstd, headers = self.www[name]
+        if request.headers.get("if-none-match") == headers["etag"]:
+            return Response(status_code=304, headers=headers)
+        if zstd and "zstd" in request.headers.get("accept-encoding", ""):
+            headers["content-encoding"] = "zstd"
+            data = zstd
+        return Response(content=data, headers=headers)

fastapi_vue-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "fastapi-vue"
+dynamic = ["version"]
+description = "Serves Vue static files / SPA on a FastAPI app. Use fastapi-vue-setup to install."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "zstandard>=0.23.0",
+    "aeg>=0.9.0",
+]
+
+[project.urls]
+Homepage = "https://git.zi.fi/LeoVasanko/fastapi-vue"
+Repository = "https://github.com/LeoVasanko/fastapi-vue"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"