arkitekt-fastapi 2.0.2__tar.gz → 2.1.0__tar.gz

{arkitekt_fastapi-2.0.2 → arkitekt_fastapi-2.1.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: arkitekt-fastapi
-Version: 2.0.2
+Version: 2.1.0
 Summary: server mode for an Arkitekt app: serve a declared app over HTTP with FastAPI
 Author-email: jhnnsrs <jhnnsrs@gmail.com>
 License-Expression: MIT
 Requires-Python: >=3.11
 Requires-Dist: aiosqlite>=0.19
-Requires-Dist: arkitekt-runtime>=4.3
-Requires-Dist: arkitekt-spec>=3.4
+Requires-Dist: arkitekt-runtime>=4.5
+Requires-Dist: arkitekt-spec>=3.7
 Requires-Dist: fastapi>=0.100
 Requires-Dist: httpx>=0.27
 Requires-Dist: jsonpatch>=1.33
@@ -37,4 +37,19 @@ websockets, no rath, no rekuest server.
 A served app registers with no one and so cannot call other actions: `Task.call` raises
 `NoCallerError` at once.
 
+## Assets
+
+The files an app registers with `register_asset` are served by the name its bloks call them
+by (`@self.assets.<name>`):
+
+- `GET /schemas/assets` lists them as they are declared: name, kind, reference, and the size
+  or the source.
+- `GET /assets/<name>` is the file, with its reference as the `ETag` (`If-None-Match` answers
+  304). An asset registered with a `source` is not held by the app: the route redirects (307)
+  to that source and fetches nothing.
+
+A file that changed on disk since it was registered is refused with 409, since a reader checks
+the bytes against the reference. Like the schema routes, the asset routes ask for no user.
+`configure_fastapi(..., add_assets=False)` leaves them out; `assets_path=` moves them.
+
 `AsyncAgentTestClient` drives a served app in tests without a network.

{arkitekt_fastapi-2.0.2 → arkitekt_fastapi-2.1.0}/README.md

@@ -20,4 +20,19 @@ websockets, no rath, no rekuest server.
 A served app registers with no one and so cannot call other actions: `Task.call` raises
 `NoCallerError` at once.
 
+## Assets
+
+The files an app registers with `register_asset` are served by the name its bloks call them
+by (`@self.assets.<name>`):
+
+- `GET /schemas/assets` lists them as they are declared: name, kind, reference, and the size
+  or the source.
+- `GET /assets/<name>` is the file, with its reference as the `ETag` (`If-None-Match` answers
+  304). An asset registered with a `source` is not held by the app: the route redirects (307)
+  to that source and fetches nothing.
+
+A file that changed on disk since it was registered is refused with 409, since a reader checks
+the bytes against the reference. Like the schema routes, the asset routes ask for no user.
+`configure_fastapi(..., add_assets=False)` leaves them out; `assets_path=` moves them.
+
 `AsyncAgentTestClient` drives a served app in tests without a network.

{arkitekt_fastapi-2.0.2 → arkitekt_fastapi-2.1.0}/arkitekt_fastapi/__init__.py

@@ -12,6 +12,7 @@ from .auth import (
 )
 from .routes import (
     add_agent_routes,
+    add_asset_routes,
     add_implementation_routes,
     add_lock_routes,
     add_schema_routes,
@@ -40,6 +41,7 @@ __all__ = [
     "configure_fastapi",
     "create_lifespan",
     "add_agent_routes",
+    "add_asset_routes",
     "add_implementation_routes",
     "add_lock_routes",
     "add_schema_routes",

{arkitekt_fastapi-2.0.2 → arkitekt_fastapi-2.1.0}/arkitekt_fastapi/route_groups/__init__.py

@@ -1,5 +1,6 @@
 """Grouped FastAPI route builders."""
 
+from .assets import build_asset_router
 from .core import build_core_router
 from .implementations import add_implementation_route, build_implementation_router
 from .journal import build_journal_router
@@ -9,6 +10,7 @@ from .states import build_state_router
 from .tasks import build_task_router
 
 __all__ = [
+    "build_asset_router",
     "build_core_router",
     "build_implementation_router",
     "add_implementation_route",

arkitekt_fastapi-2.1.0/arkitekt_fastapi/route_groups/assets.py

@@ -0,0 +1,119 @@
+"""Asset route builders: the files an app registered, served by name."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import FileResponse, RedirectResponse, Response
+
+from arkitekt_spec.declare.app import AssetDeclaration
+
+from arkitekt_fastapi.agent import FastApiAgent
+
+logger = logging.getLogger(__name__)
+
+#: What a file is served as, by its extension. A file with another extension (its
+#: kind was said with ``kind=``) is served as bytes.
+_CONTENT_TYPES: dict[str, str] = {
+    ".glb": "model/gltf-binary",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+}
+
+
+def _still_as_registered(asset: AssetDeclaration, path: Path) -> bool:
+    """Whether the file at ``path`` still has the bytes its reference was computed from."""
+    try:
+        digest = hashlib.sha256()
+        with path.open("rb") as file:
+            for chunk in iter(lambda: file.read(1 << 20), b""):
+                digest.update(chunk)
+    except OSError:
+        return False
+    return "sha256:" + digest.hexdigest() == asset.ref
+
+
+def _same_size(asset: AssetDeclaration, path: Path) -> bool:
+    try:
+        return path.stat().st_size == asset.size
+    except OSError:
+        return False
+
+
+def build_asset_router(
+    agent: FastApiAgent,
+    assets_path: str = "/assets",
+) -> APIRouter:
+    """Build the routes serving the app's registered assets.
+
+    A blok names an asset as ``@self.assets.<name>``; ``{assets_path}/<name>`` is
+    that file. A file the app brings is served from where it was registered, with
+    its reference as the ETag. A file the app only names a source for is answered
+    with a redirect to that source: nothing is fetched here.
+
+    Every held file is hashed once, now. One that no longer has the bytes it was
+    registered with is refused when asked for, since whoever reads it checks it
+    against the reference and would only see that check fail.
+    """
+    router = APIRouter(tags=["Assets"])
+    assets = dict(agent.app_registry.registered_assets)
+    changed: set[str] = set()
+    for name, asset in assets.items():
+        if asset.path is not None and not _still_as_registered(asset, asset.path):
+            changed.add(name)
+            logger.warning(
+                "The asset '%s' (%s) changed since it was registered: it is not served",
+                name,
+                asset.where,
+            )
+
+    async def get_asset(name: str, request: Request) -> Response:
+        asset = assets.get(name)
+        if asset is None:
+            raise HTTPException(status_code=404, detail=f"No asset is registered as '{name}'")
+        if asset.path is None:
+            return RedirectResponse(str(asset.source), status_code=307)
+        if name in changed or not _same_size(asset, asset.path):
+            raise HTTPException(
+                status_code=409,
+                detail=(
+                    f"The asset '{name}' ({asset.where}) changed since it was "
+                    f"registered: restart the app"
+                ),
+            )
+        etag = f'"{asset.ref}"'
+        headers = {"ETag": etag, "Cache-Control": "no-cache"}
+        asked = request.headers.get("if-none-match", "")
+        if etag in (tag.strip().removeprefix("W/") for tag in asked.split(",")):
+            return Response(status_code=304, headers=headers)
+        return FileResponse(
+            asset.path,
+            media_type=_CONTENT_TYPES.get(
+                asset.path.suffix.lower(), "application/octet-stream"
+            ),
+            headers=headers,
+        )
+
+    router.add_api_route(
+        f"{assets_path}/{{name}}",
+        get_asset,
+        methods=["GET"],
+        response_class=Response,
+        responses={
+            200: {"description": "The file."},
+            304: {"description": "The file is the one the caller already has."},
+            307: {"description": "The app does not hold the file: its source."},
+            404: {"description": "No asset is registered under this name."},
+            409: {"description": "The file changed since it was registered."},
+        },
+    )
+    # HEAD is the same answer without the body; one entry in the OpenAPI schema.
+    router.add_api_route(
+        f"{assets_path}/{{name}}", get_asset, methods=["HEAD"], include_in_schema=False
+    )
+    return router

{arkitekt_fastapi-2.0.2 → arkitekt_fastapi-2.1.0}/arkitekt_fastapi/route_groups/schemas.py

@@ -31,10 +31,18 @@ def build_schema_router(
         blok_schemas = agent.app_registry.get_declared_bloks()
         return {"count": len(blok_schemas), "bloks": blok_schemas}
 
+    async def get_asset_schemas() -> dict:
+        assets = [
+            asset.model_dump(mode="json", exclude_none=True)
+            for asset in agent.app_registry.get_declared_assets()
+        ]
+        return {"count": len(assets), "assets": assets}
+
     router.add_api_route(
         "/schemas/implementations", get_implementation_schemas, methods=["GET"]
     )
     router.add_api_route("/schemas/states", get_state_schemas, methods=["GET"])
     router.add_api_route("/schemas/locks", get_lock_schemas, methods=["GET"])
     router.add_api_route("/schemas/bloks", get_blok_schemas, methods=["GET"])
+    router.add_api_route("/schemas/assets", get_asset_schemas, methods=["GET"])
     return router

{arkitekt_fastapi-2.0.2 → arkitekt_fastapi-2.1.0}/arkitekt_fastapi/routes.py

@@ -25,6 +25,7 @@ from arkitekt_fastapi.openapi_utils import (
 )
 from arkitekt_fastapi.route_groups import (
     add_implementation_route,
+    build_asset_router,
     build_core_router,
     build_implementation_router,
     build_journal_router,
@@ -233,6 +234,15 @@ def add_schema_routes(
     _include_router(app, build_schema_router(agent))
 
 
+def add_asset_routes(
+    app: FastAPI,
+    agent: FastApiAgent,
+    assets_path: str = "/assets",
+) -> None:
+    """Include the routes serving the app's registered assets by name."""
+    _include_router(app, build_asset_router(agent, assets_path=assets_path))
+
+
 def configure_fastapi(
     app: FastAPI,
     app_registry: AppRegistry,
@@ -246,11 +256,13 @@ def configure_fastapi(
     add_tasks: bool = True,
     add_task_details: bool = True,
     add_journal: bool = True,
+    add_assets: bool = True,
     ws_path: str = "/ws",
     tasks_path: str = "/tasks",
     assign_path: str = "/assign",
     states_path: str = "/states",
     locks_path: str = "/locks",
+    assets_path: str = "/assets",
     db_file: str = "agent_data.db",
     app_context: Any | None = None,
     bound_app: Any | None = None,
@@ -284,6 +296,11 @@ def configure_fastapi(
             absent, in which case the websocket stays unauthenticated as before.
         add_journal: Serve the journal routes (``/journal…`` and
             ``{tasks_path}/{task_id}/events``, see ``docs/journal.md``).
+        add_assets: Serve the files the app registered with ``register_asset``,
+            each at ``{assets_path}/<name>``: the file itself, or a redirect to
+            the source of one the app does not hold. Like the schema routes,
+            they ask for no user.
+        assets_path: Where the assets are served.
     """
     # Imported here: the sqlite retriever reads the protocol under this
     # package, so a module-level import would be circular.
@@ -331,6 +348,8 @@ def configure_fastapi(
                 get_user_from_request=get_user_from_request,
                 expand_user_from_request=expand_user_from_request,
             )
+        if add_assets:
+            add_asset_routes(fastapi_app, agent, assets_path=assets_path)
         if add_schema:
             add_schema_routes(fastapi_app, agent)
         configure_openapi(fastapi_app)
@@ -348,6 +367,7 @@ def configure_fastapi(
 
 __all__ = [
     "add_agent_routes",
+    "add_asset_routes",
     "add_implementation_route",
     "add_implementation_routes",
     "add_journal_routes",

{arkitekt_fastapi-2.0.2 → arkitekt_fastapi-2.1.0}/pyproject.toml

@@ -9,8 +9,8 @@ license = "MIT"
 # Serving an app needs the execution core and FastAPI, not the distributed runtime:
 # no rekuest, no websockets client, no rath, no graphql-core.
 dependencies = [
-    "arkitekt-spec>=3.4",
-    "arkitekt-runtime>=4.3",
+    "arkitekt-spec>=3.7",
+    "arkitekt-runtime>=4.5",
     "pydantic>=2.11",
     "koil>=3.3.6",
     "fastapi>=0.100",