fluxfast 0.1.0__tar.gz

fluxfast-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+node_modules/
+dist/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.pyc
+*.tsbuildinfo
+coverage/
+benchmark-results/
+playwright-report/
+test-results/
+tests/browser/frontend/.next/
+tests/browser/frontend/AGENTS.md
+tests/browser/frontend/CLAUDE.md
+tests/browser/frontend/next-env.d.ts
+tests/browser/frontend/src/.fluxfast/

fluxfast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FluxFast Contributors
+
+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.

fluxfast-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: fluxfast
+Version: 0.1.0
+Summary: High-performance server-driven application runtime for FastAPI
+Project-URL: Homepage, https://github.com/El37628/FluxFast
+Project-URL: Repository, https://github.com/El37628/FluxFast
+Project-URL: Issues, https://github.com/El37628/FluxFast/issues
+Author: FluxFast Contributors
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: fastapi<1.0.0,>=0.141.1
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: starlette<2.0.0,>=1.3.1
+Requires-Dist: uvicorn<1.0.0,>=0.30.0
+Provides-Extra: dev
+Requires-Dist: httpx2<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FluxFast for FastAPI
+
+The Python package provides FastAPI page routes, scoped versioned resources, a
+bounded in-memory cache, concurrent loader resolution, mutation helpers, 422
+mapping, redirects, and the `fluxfast/1` protocol.
+
+```bash
+python -m pip install fluxfast
+```
+
+```python
+from fastapi import FastAPI
+from fluxfast import FluxFast, Page, resource, scope
+
+app = FastAPI()
+flux = FluxFast(app)
+
+@flux.page("/")
+async def home():
+    return Page(
+        "home/index",
+        resources=[
+            resource("news", load_news, scope=scope.public(), ttl=60),
+        ],
+    )
+```
+
+Reusable data must declare an appropriate public, user, tenant, or custom scope.
+See the repository protocol and caching documentation for wire and invalidation
+semantics.
+
+For a Next.js consumer, install its backend and run both development processes
+under one supervisor:
+
+```bash
+python -m pip install -e backend
+fluxfast dev backend.app.main:app
+```
+
+The CLI starts FastAPI on an available internal loopback port and Next on the
+browser-facing development port. The companion Next config uses the injected
+server-only address, so browser requests stay same-origin.

fluxfast-0.1.0/README.md

@@ -0,0 +1,42 @@
+# FluxFast for FastAPI
+
+The Python package provides FastAPI page routes, scoped versioned resources, a
+bounded in-memory cache, concurrent loader resolution, mutation helpers, 422
+mapping, redirects, and the `fluxfast/1` protocol.
+
+```bash
+python -m pip install fluxfast
+```
+
+```python
+from fastapi import FastAPI
+from fluxfast import FluxFast, Page, resource, scope
+
+app = FastAPI()
+flux = FluxFast(app)
+
+@flux.page("/")
+async def home():
+    return Page(
+        "home/index",
+        resources=[
+            resource("news", load_news, scope=scope.public(), ttl=60),
+        ],
+    )
+```
+
+Reusable data must declare an appropriate public, user, tenant, or custom scope.
+See the repository protocol and caching documentation for wire and invalidation
+semantics.
+
+For a Next.js consumer, install its backend and run both development processes
+under one supervisor:
+
+```bash
+python -m pip install -e backend
+fluxfast dev backend.app.main:app
+```
+
+The CLI starts FastAPI on an available internal loopback port and Next on the
+browser-facing development port. The companion Next config uses the injected
+server-only address, so browser requests stay same-origin.

fluxfast-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fluxfast"
+version = "0.1.0"
+description = "High-performance server-driven application runtime for FastAPI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "FluxFast Contributors" }]
+dependencies = [
+    "fastapi>=0.141.1,<1.0.0",
+    "pydantic>=2.9.0",
+    "anyio>=4.0.0",
+    "starlette>=1.3.1,<2.0.0",
+    "uvicorn>=0.30.0,<1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/El37628/FluxFast"
+Repository = "https://github.com/El37628/FluxFast"
+Issues = "https://github.com/El37628/FluxFast/issues"
+
+[project.scripts]
+fluxfast = "fluxfast.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "httpx2>=2.0.0,<3.0.0",
+    "pytest>=8.0.0",
+    "ruff>=0.3.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fluxfast"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+ignore = ["B008"]

fluxfast-0.1.0/src/fluxfast/__init__.py

@@ -0,0 +1,83 @@
+"""FluxFast — high-performance server-driven application runtime for FastAPI."""
+
+from .app import FluxFast
+from .cache import CachedResource, MemoryResourceCache, ResourceCacheBackend
+from .errors import (
+    FluxFastError,
+    PageNotFoundError,
+    ProtocolError,
+    ResourceError,
+    ScopeError,
+    ValidationError,
+)
+from .mutation import (
+    InvalidateResource,
+    MutationResult,
+    append_item,
+    flux_external_redirect,
+    flux_redirect,
+    invalidate_resource,
+    merge_object,
+    mutation,
+    remove_item,
+    replace_item,
+    replace_resource,
+)
+from .page import Page
+from .protocol import (
+    PROTOCOL_MEDIA_TYPE,
+    PROTOCOL_VERSION,
+    ErrorDetail,
+    ErrorEnvelope,
+    MutationEnvelope,
+    MutationPayload,
+    PageDescriptor,
+    PageEnvelope,
+    ResourceWireRecord,
+)
+from .resource import ResourceLoader, ResourceSpec, resource
+from .router import FluxRouter
+from .scope import CacheScope, ScopeType, scope
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PROTOCOL_MEDIA_TYPE",
+    "PROTOCOL_VERSION",
+    "CacheScope",
+    "CachedResource",
+    "ErrorDetail",
+    "ErrorEnvelope",
+    "FluxFast",
+    "FluxFastError",
+    "FluxRouter",
+    "InvalidateResource",
+    "MemoryResourceCache",
+    "MutationEnvelope",
+    "MutationPayload",
+    "MutationResult",
+    "Page",
+    "PageDescriptor",
+    "PageEnvelope",
+    "PageNotFoundError",
+    "ProtocolError",
+    "ResourceCacheBackend",
+    "ResourceError",
+    "ResourceLoader",
+    "ResourceSpec",
+    "ResourceWireRecord",
+    "ScopeError",
+    "ScopeType",
+    "ValidationError",
+    "append_item",
+    "flux_external_redirect",
+    "flux_redirect",
+    "invalidate_resource",
+    "merge_object",
+    "mutation",
+    "remove_item",
+    "replace_item",
+    "replace_resource",
+    "resource",
+    "scope",
+]

fluxfast-0.1.0/src/fluxfast/app.py

@@ -0,0 +1,131 @@
+"""FluxFast FastAPI application integration and lifecycle management."""
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from .cache import MemoryResourceCache, ResourceCacheBackend
+from .errors import FluxFastError, ProtocolError, ResourceError
+from .headers import HEADER_FLUXFAST, HEADER_PROTOCOL, is_fluxfast_request
+from .protocol import PROTOCOL_MEDIA_TYPE, PROTOCOL_VERSION, ErrorDetail, ErrorEnvelope
+from .router import FluxRouter
+
+
+class FluxFast:
+    """Main application integrator configuring FastAPI with FluxFast support."""
+
+    def __init__(
+        self,
+        app: FastAPI,
+        cache: ResourceCacheBackend | None = None,
+        debug: bool = False,
+    ):
+        self.app = app
+        self.cache = cache if cache is not None else MemoryResourceCache()
+        self.debug = debug
+
+        # Attach cache to FastAPI app state
+        self.app.state.fluxfast_cache = self.cache
+        self.app.state.fluxfast_debug = self.debug
+
+        # Setup exception handlers
+        self._setup_exception_handlers()
+
+        # Shared router
+        self.router = FluxRouter()
+
+    def _setup_exception_handlers(self) -> None:
+        @self.app.exception_handler(RequestValidationError)
+        async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+            # Map Pydantic validation errors to structured dictionary
+            field_errors: dict[str, list[str]] = {}
+            for error in exc.errors():
+                loc = error.get("loc", ())
+                # Extract field name (skip 'body', 'query', etc. if nested)
+                field_name = str(loc[-1]) if loc else "general"
+                msg = error.get("msg", "Invalid value")
+                if field_name not in field_errors:
+                    field_errors[field_name] = []
+                field_errors[field_name].append(msg)
+
+            if is_fluxfast_request(request):
+                envelope = ErrorEnvelope(
+                    protocol=PROTOCOL_VERSION,
+                    error=ErrorDetail(
+                        type="ValidationError",
+                        message="Request validation failed",
+                        details=field_errors,
+                    ),
+                )
+                return JSONResponse(
+                    status_code=422,
+                    content=envelope.model_dump(mode="json"),
+                    media_type=PROTOCOL_MEDIA_TYPE,
+                    headers={
+                        HEADER_FLUXFAST: "1",
+                        HEADER_PROTOCOL: "1",
+                    },
+                )
+
+            # Fallback standard response for non-Flux requests
+            return JSONResponse(
+                status_code=422,
+                content={"detail": exc.errors()},
+            )
+
+        @self.app.exception_handler(FluxFastError)
+        async def fluxfast_exception_handler(request: Request, exc: FluxFastError) -> JSONResponse:
+            status_code = 409 if isinstance(exc, ProtocolError) else 500
+            public_message = exc.message
+            public_details = exc.details
+            if isinstance(exc, ResourceError) and not self.debug:
+                public_message = "A resource could not be resolved"
+                public_details = None
+
+            envelope = ErrorEnvelope(
+                protocol=PROTOCOL_VERSION,
+                error=ErrorDetail(
+                    type=type(exc).__name__,
+                    message=public_message,
+                    details=public_details,
+                ),
+            )
+            return JSONResponse(
+                status_code=status_code,
+                content=envelope.model_dump(mode="json"),
+                media_type=PROTOCOL_MEDIA_TYPE,
+                headers={HEADER_FLUXFAST: "1", HEADER_PROTOCOL: "1"},
+            )
+
+    def page(self, path: str, *args: Any, **kwargs: Any) -> Callable[..., Any]:
+        """Define a page directly on the integrated FastAPI application."""
+        register = self.router.page(path, *args, **kwargs)
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            route_count = len(self.router.routes)
+            registered = register(func)
+            self.app.router.routes.extend(self.router.routes[route_count:])
+            return registered
+
+        return decorator
+
+    def mutation(
+        self,
+        path: str,
+        methods: list[str] | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Callable[..., Any]:
+        """Define a mutation directly on the integrated FastAPI application."""
+        register = self.router.mutation(path, methods, *args, **kwargs)
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            route_count = len(self.router.routes)
+            registered = register(func)
+            self.app.router.routes.extend(self.router.routes[route_count:])
+            return registered
+
+        return decorator

fluxfast-0.1.0/src/fluxfast/cache.py

@@ -0,0 +1,126 @@
+"""Server-side in-memory resource caching backend and interface."""
+
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, replace
+from typing import Any, Protocol
+
+import anyio
+
+
+@dataclass(slots=True)
+class CachedResource:
+    """Represents a cached resource entry."""
+
+    version: str
+    value: Any
+    expires_at: float
+    tags: tuple[str, ...] = ()
+
+    @property
+    def is_expired(self) -> bool:
+        return time.monotonic() >= self.expires_at
+
+
+class ResourceCacheBackend(Protocol):
+    """Abstract interface for server resource caches."""
+
+    async def get(self, key: str) -> CachedResource | None: ...
+
+    async def set(
+        self,
+        key: str,
+        resource: CachedResource,
+        ttl: float,
+    ) -> None: ...
+
+    async def delete(self, key: str) -> None: ...
+
+    async def invalidate_tag(self, tag: str) -> None: ...
+
+    async def clear(self) -> None: ...
+
+
+class MemoryResourceCache:
+    """Async-safe, bounded, TTL-aware LRU in-memory resource cache."""
+
+    def __init__(self, max_entries: int = 10000):
+        if max_entries <= 0:
+            raise ValueError("max_entries must be greater than zero")
+        self.max_entries = max_entries
+        self._cache: OrderedDict[str, CachedResource] = OrderedDict()
+        self._tag_index: dict[str, set[str]] = {}
+        self._lock = anyio.Lock()
+
+    async def get(self, key: str) -> CachedResource | None:
+        async with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return None
+
+            # Check expiration
+            if entry.is_expired:
+                self._remove_internal(key)
+                return None
+
+            # Mark as recently used (LRU)
+            self._cache.move_to_end(key)
+            return entry
+
+    async def set(self, key: str, resource: CachedResource, ttl: float) -> None:
+        async with self._lock:
+            if key in self._cache:
+                self._remove_internal(key)
+
+            if ttl <= 0:
+                return
+
+            # Evict LRU if full
+            while len(self._cache) >= self.max_entries:
+                oldest_key, oldest_entry = self._cache.popitem(last=False)
+                self._cleanup_tags(oldest_key, oldest_entry.tags)
+
+            stored_resource = replace(
+                resource,
+                expires_at=time.monotonic() + ttl,
+            )
+            self._cache[key] = stored_resource
+
+            # Index tags
+            for tag in stored_resource.tags:
+                if tag not in self._tag_index:
+                    self._tag_index[tag] = set()
+                self._tag_index[tag].add(key)
+
+    async def delete(self, key: str) -> None:
+        async with self._lock:
+            self._remove_internal(key)
+
+    async def invalidate_tag(self, tag: str) -> None:
+        async with self._lock:
+            keys = self._tag_index.pop(tag, set())
+            for key in keys:
+                if key in self._cache:
+                    self._remove_internal(key)
+
+    async def clear(self) -> None:
+        async with self._lock:
+            self._cache.clear()
+            self._tag_index.clear()
+
+    def _remove_internal(self, key: str) -> None:
+        entry = self._cache.pop(key, None)
+        if entry:
+            self._cleanup_tags(key, entry.tags)
+
+    def _cleanup_tags(self, key: str, tags: tuple[str, ...] | None = None) -> None:
+        if tags is None:
+            # Clean from all tag index sets
+            for tag_keys in self._tag_index.values():
+                tag_keys.discard(key)
+        else:
+            for tag in tags:
+                if tag in self._tag_index:
+                    self._tag_index[tag].discard(key)
+                    if not self._tag_index[tag]:
+                        del self._tag_index[tag]