Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(media): FileRef base, entry-level containment, one workspace locator
trohitgdc0907bd0e24
diff --git a/server/nodes/filesystem/_backend.py b/server/nodes/filesystem/_backend.pyindex 8b5ed4e6..2daa6efb 100644--- a/server/nodes/filesystem/_backend.py+++ b/server/nodes/filesystem/_backend.py@@ -569,6 +569,38 @@ def resolve_within(root: os.PathLike[str] | str, key: str) -> Path:return resolved+def resolve_entry_within(root: os.PathLike[str] | str, key: str) -> Path:+ """Contained path that names the entry itself, not a symlink's target.++ :func:`resolve_within` fully resolves the path, which is correct for+ reads and wrong for mutations: a symlink inside the workspace pointing+ at another file inside the workspace resolves *inside* (so containment+ passes), and unlinking or renaming the resolved path then acts on the+ target instead of the link.++ Containment is instead proved on the **parent**, which is fully+ resolved -- so no component along the way can redirect outside the root+ -- and the basename is appended unresolved. ``unlink`` / ``rename`` then+ act on the entry the caller named.++ Refuses the root itself: no mutation may delete or rename the workspace.++ Raises ``ValueError`` on escape or on a refused target, matching+ :func:`resolve_within` so callers translate the same way.+ """+ root_path = Path(os.path.abspath(os.fspath(root)))+ virtual = _validate_virtual_path(key).strip("/")+ if not virtual:+ raise ValueError("Refusing to operate on the workspace root itself")++ parent_virtual, _, basename = virtual.rpartition("/")+ if basename in ("", ".", ".."):+ raise ValueError(f"Path '{key}' does not name an entry")++ parent = resolve_within(root_path, parent_virtual or "/")+ return parent / basename++def normalize_virtual_path(path: str) -> str:"""Normalize user paths to canonical workspace-relative virtual paths."""from services.plugin import NodeUserErrordiff --git a/server/routers/workspace.py b/server/routers/workspace.pyindex 20f34189..67df5798 100644--- a/server/routers/workspace.py+++ b/server/routers/workspace.py@@ -26,7 +26,6 @@ import hashlibimport mimetypesfrom pathlib import Pathfrom types import SimpleNamespace-from typing import Optionalfrom fastapi import APIRouter, Depends, File, HTTPException, Path as PathParam, UploadFilefrom fastapi.responses import FileResponse@@ -34,7 +33,6 @@ from fastapi.responses import FileResponsefrom core.container import containerfrom core.database import Databasefrom core.logging import get_logger-from core.paths import workspaces_dirfrom services.media import MEDIA_MAX_UPLOAD_BYTES, AudioRef, write_audiofrom services.media.workspace import UPLOAD_SUBDIR@@ -64,19 +62,14 @@ def _db() -> Database:async def _workspace_root(workflow_id: str, database: Database) -> Path:"""Resolve a workflow id to its on-disk workspace directory.- Mirrors ``WorkflowService._resolve_workflow_slug`` including the- ``"default"`` fallback, which is the anonymous workspace a one-off run- without a saved row writes into.+ Delegates to :mod:`services.workspace_locator`, which owns the id->slug+ translation for every consumer. Both routes here are reads, so the+ ``"default"`` fallback (the anonymous workspace a one-off run without a+ saved row writes into) stays enabled."""- slug: Optional[str] = None- try:- workflow = await database.get_workflow(workflow_id)- slug = getattr(workflow, "slug", None) if workflow else None- except Exception as exc:- logger.warning(- "workspace slug lookup failed", workflow_id=workflow_id, error=str(exc)- )- return workspaces_dir() / (slug or "default")+ from services.workspace_locator import resolve_workspace_root++ return await resolve_workspace_root(workflow_id, database)def _resolve(root: Path, rel_path: str) -> Path:diff --git a/server/services/media/refs.py b/server/services/media/refs.pyindex fa6d7fb6..ef2add61 100644--- a/server/services/media/refs.py+++ b/server/services/media/refs.py@@ -1,10 +1,16 @@-"""``AudioRef`` — a reference to audio, never the audio itself.+"""``FileRef`` / ``AudioRef`` — a reference to a file, never the file itself.-The one rule this module exists to enforce: **audio bytes do not travel+The one rule this module exists to enforce: **file bytes do not travelthrough the workflow engine.** See :mod:`services.media.limits` for the-measured reason. This model has no bytes field, no base64 field, and+measured reason. These models have no bytes field, no base64 field, and``extra="forbid"`` so that adding one is a validation error rather than asilent regression.++``FileRef`` is the base every kind shares; ``AudioRef`` narrows it with the+container metadata a probe produced. Kind-specific siblings (image, video,+document) subclass the same base as they are needed — see+``docs-internal/media_transport.md``, which rejects one fat generic model+because the metadata that matters differs per kind."""from __future__ import annotations@@ -14,8 +20,15 @@ from typing import Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field-class AudioRef(BaseModel):- """A pointer to an audio file inside a workflow workspace.+# The narrowing a producer may claim. ``file`` is the honest default: it+# asserts nothing beyond "this exists in the workspace". A node that has not+# probed the container must not claim a richer kind — a fabricated duration+# silently mis-bills per-second providers downstream.+FileKind = Literal["file", "audio", "image", "video", "document"]+++class FileRef(BaseModel):+ """A pointer to a file inside a workflow workspace.Serializes to roughly 400 bytes, i.e. about 5,200 refs beforeapproaching Temporal's 2 MiB error limit -- the envelope is@@ -24,10 +37,12 @@ class AudioRef(BaseModel):``path`` is workspace-**relative** POSIX, never an absolute host path.Absolute paths embed the mutable workflow slug, leak the operator'shome directory into the database / WebSocket broadcasts / LLM context,- and cannot be safely turned into an HTTP URL.+ and cannot be safely turned into an HTTP URL. A leading slash is also+ not merely cosmetic: ``resolve_media`` treats it as absolute on POSIX+ (and not on Windows), so the wrong shape fails only in production."""- kind: Literal["audio"] = "audio"+ kind: FileKind = "file"path: str = Field(description="Workspace-relative POSIX path, no leading slash "@@ -40,14 +55,10 @@ class AudioRef(BaseModel):filename: str = Field(description="Display name. Never used for resolution.")mime_type: str = "application/octet-stream"- format: str = Field(default="", description="Container/codec: wav, mp3, opus, ...")size_bytes: int = 0- # None whenever the container could not be inspected. Never guessed --- # a fabricated duration would silently mis-bill per-second providers.- duration_seconds: Optional[float] = None- sample_rate: Optional[int] = None- channels: Optional[int] = None+ # ISO 8601. Advisory only -- a listing snapshot, not a cache key.+ modified_at: Optional[str] = Nonesha256: Optional[str] = None@@ -59,4 +70,23 @@ class AudioRef(BaseModel):model_config = ConfigDict(extra="forbid")-__all__ = ["AudioRef"]+class AudioRef(FileRef):+ """A :class:`FileRef` whose container has actually been probed.++ Only set ``kind="audio"`` when the duration/rate fields come from+ :func:`services.media.inspect.inspect_audio`. Guessing the kind from a+ file extension is what ``FileRef`` is for.+ """++ kind: Literal["audio"] = "audio"++ format: str = Field(default="", description="Container/codec: wav, mp3, opus, ...")++ # None whenever the container could not be inspected. Never guessed --+ # a fabricated duration would silently mis-bill per-second providers.+ duration_seconds: Optional[float] = None+ sample_rate: Optional[int] = None+ channels: Optional[int] = None+++__all__ = ["AudioRef", "FileKind", "FileRef"]diff --git a/server/services/media/workspace.py b/server/services/media/workspace.pyindex 3617b13c..8483e4c9 100644--- a/server/services/media/workspace.py+++ b/server/services/media/workspace.py@@ -18,13 +18,13 @@ import hashlibimport mimetypesimport refrom pathlib import Path-from typing import Any, Optional, Tuple+from typing import Any, Optional, Tuple, get_argsfrom uuid import uuid4from core.logging import get_loggerfrom services.media.inspect import inspect_audiofrom services.media.limits import MEDIA_MAX_READ_BYTES-from services.media.refs import AudioRef+from services.media.refs import AudioRef, FileKind, FileReflogger = get_logger(__name__)@@ -100,7 +100,7 @@ def workspace_root(def resolve_media(- ref: AudioRef | str,+ ref: FileRef | str,*,ctx: Any = None,workspace_dir: Optional[str] = None,@@ -110,11 +110,11 @@ def resolve_media(from nodes.filesystem._backend import resolve_withinfrom services.plugin import NodeUserError- key = ref.path if isinstance(ref, AudioRef) else str(ref or "")+ key = ref.path if isinstance(ref, FileRef) else str(ref or "")if not key.strip():raise NodeUserError("No media path was provided.")- if isinstance(ref, AudioRef) and ref.workflow_id and workflow_id is None:+ if isinstance(ref, FileRef) and ref.workflow_id and workflow_id is None:workflow_id = ref.workflow_idroot = workspace_root(ctx, workspace_dir=workspace_dir, workflow_id=workflow_id)@@ -138,7 +138,7 @@ def resolve_media(def read_media_bytes(- ref: AudioRef | str,+ ref: FileRef | str,*,ctx: Any = None,workspace_dir: Optional[str] = None,@@ -254,10 +254,25 @@ def coerce_file_param(import base64import binascii+ from pydantic import ValidationError+from services.plugin import NodeUserError- if isinstance(value, dict) and value.get("kind") == "audio":- ref = AudioRef.model_validate(value)+ if isinstance(value, dict) and value.get("kind") in get_args(FileKind):+ # The model is picked explicitly rather than always validating as the+ # base: ``extra="forbid"`` means an audio payload does NOT validate as+ # a plain FileRef (it carries duration_seconds/sample_rate/channels).+ model = AudioRef if value.get("kind") == "audio" else FileRef+ try:+ ref = model.model_validate(value)+ except ValidationError as exc:+ # A well-known ``kind`` with a malformed body is still a bad file+ # parameter, not a server fault: keep it on the NodeUserError path+ # so it logs one WARN line instead of a pydantic traceback.+ raise NodeUserError(+ "File parameter is not a usable file reference. "+ "Re-select the file in the parameter panel."+ ) from excreturn read_media_bytes(ref, ctx=ctx, max_bytes=max_bytes)if isinstance(value, dict) and value.get("type") == "upload":diff --git a/server/services/workspace_locator.py b/server/services/workspace_locator.pynew file mode 100644index 00000000..5e7df284--- /dev/null+++ b/server/services/workspace_locator.py@@ -0,0 +1,84 @@+"""Workflow id -> workspace directory, in one place.++The workspace directory is named by ``Workflow.slug``, which is **mutable**+(renaming a workflow renames the directory). Every stable reference — a+``FileRef``, the file-serving route, a WebSocket request from the editor —+carries the immutable ``Workflow.id`` instead, so the id must be translated+to a slug against the database on every use.++That translation existed in two copies before this module (the workspace+router and ``WorkflowService``), and a third consumer was about to be added.+One implementation means one place to change when the naming rule changes,+and one place where the ``"default"`` fallback below is reasoned about.+"""++from __future__ import annotations++from pathlib import Path+from typing import Any, Optional++from core.logging import get_logger+from core.paths import workspaces_dir++logger = get_logger(__name__)++# The anonymous workspace a one-off run without a saved workflow row writes+# into. Reads may fall back to it; mutations must not (see below).+DEFAULT_WORKSPACE_SLUG = "default"+++async def resolve_workflow_slug(workflow_id: Optional[str], database: Any) -> Optional[str]:+ """Look up a workflow's slug. ``None`` when it cannot be resolved.++ Never raises: a database hiccup during a read should degrade to the+ default workspace rather than fail the request.+ """+ if not workflow_id:+ return None+ try:+ workflow = await database.get_workflow(workflow_id)+ except Exception as exc: # noqa: BLE001+ logger.warning(+ "workspace slug lookup failed",+ workflow_id=workflow_id,+ error=str(exc),+ )+ return None+ return getattr(workflow, "slug", None) if workflow else None+++async def resolve_workspace_root(+ workflow_id: Optional[str],+ database: Any,+ *,+ allow_default: bool = True,+) -> Path:+ """Resolve a workflow id to its on-disk workspace directory.++ ``allow_default=False`` is mandatory for any **mutating** caller.++ With the fallback enabled, an id that does not resolve — a stale tab, a+ typo, a workflow deleted in another window — silently lands in the shared+ anonymous workspace. For a read that is harmless. For a delete or a+ rename it means destroying files belonging to a different context than+ the caller believes they are operating on, which is the only irreversible+ failure this surface can produce.+ """+ slug = await resolve_workflow_slug(workflow_id, database)+ if slug is None:+ if not allow_default:+ from services.plugin import NodeUserError++ raise NodeUserError(+ "This workflow could not be found, so its workspace cannot be "+ "modified. Save the workflow and try again."+ )+ slug = DEFAULT_WORKSPACE_SLUG+ return workspaces_dir() / slug+++__all__ = [+ "DEFAULT_WORKSPACE_SLUG",+ "resolve_workflow_slug",+ "resolve_workspace_root",+]diff --git a/server/tests/media/test_audio_ref.py b/server/tests/media/test_audio_ref.pyindex 67e32311..2b10add4 100644--- a/server/tests/media/test_audio_ref.py+++ b/server/tests/media/test_audio_ref.py@@ -246,6 +246,115 @@ class TestCoerceFileParam:coerce_file_param(value, ctx=_ctx(tmp_path))+class TestFileRefBase:+ """FileRef is the base every kind shares; AudioRef narrows it.++ The base exists because a file manager lists arbitrary files, most of+ which are not media at all, and ``AudioRef`` forbids extras so it cannot+ stand in for them.+ """++ def test_audio_ref_is_a_file_ref(self):+ from services.media.refs import FileRef++ ref = AudioRef(path="audio/x.wav", filename="x.wav")+ assert isinstance(ref, FileRef)++ def test_file_ref_structurally_cannot_carry_bytes(self):+ """Same invariant as AudioRef: adding a payload field must fail."""+ from services.media.refs import FileRef++ for field in ("data", "content", "bytes", "audio_base64"):+ with pytest.raises(ValidationError):+ FileRef.model_validate(+ {"path": "a.bin", "filename": "a.bin", field: "QUJD"}+ )++ def test_audio_ref_keeps_its_field_set_after_the_refactor(self):+ """Guards the inheritance change against silently dropping a field."""+ keys = set(AudioRef(path="audio/x.wav", filename="x.wav").model_dump())+ assert {+ "kind", "path", "workflow_id", "filename", "mime_type", "size_bytes",+ "sha256", "url", "format", "duration_seconds", "sample_rate", "channels",+ } <= keys++ def test_audio_payload_does_not_validate_as_the_plain_base(self):+ """Why coerce_file_param must pick the model instead of always+ validating as FileRef: extra='forbid' rejects the audio-only fields."""+ from services.media.refs import FileRef++ payload = AudioRef(path="audio/x.wav", filename="x.wav").model_dump()+ with pytest.raises(ValidationError):+ FileRef.model_validate(payload)+++class TestCoerceFileParamAcceptsFileRefs:+ def test_accepts_a_plain_file_ref(self, tmp_path):+ from services.media.refs import FileRef++ (tmp_path / "chart.png").write_bytes(b"PNGDATA")+ ref = FileRef(path="chart.png", filename="chart.png", mime_type="image/png")++ name, blob = coerce_file_param(ref.model_dump(), ctx=_ctx(tmp_path))++ assert name == "chart.png"+ assert blob == b"PNGDATA"++ def test_still_accepts_an_audio_ref(self, tmp_path):+ (tmp_path / "audio").mkdir(exist_ok=True)+ (tmp_path / "audio" / "x.wav").write_bytes(b"RIFFDATA")+ ref = AudioRef(path="audio/x.wav", filename="x.wav")++ assert coerce_file_param(ref.model_dump(), ctx=_ctx(tmp_path))[1] == b"RIFFDATA"++ def test_malformed_ref_is_a_user_error_not_a_validation_traceback(self, tmp_path):+ """A known kind with a broken body still belongs on the NodeUserError+ path — one WARN line, no pydantic traceback in the operator log."""+ from services.plugin import NodeUserError++ with pytest.raises(NodeUserError):+ coerce_file_param({"kind": "image"}, ctx=_ctx(tmp_path))+++class TestResolveEntryWithin:+ """Mutations must name the entry, not what a symlink points at."""++ def test_refuses_the_root_and_non_entries(self, tmp_path):+ from nodes.filesystem._backend import resolve_entry_within++ for key in ("", "/", "..", "../../etc/passwd", "~/x", "C:/Windows/x"):+ with pytest.raises(ValueError):+ resolve_entry_within(tmp_path, key)++ def test_contains_nested_paths(self, tmp_path):+ from nodes.filesystem._backend import resolve_entry_within++ target = resolve_entry_within(tmp_path, "sub/dir/file.txt")+ assert target.relative_to(tmp_path) == Path("sub/dir/file.txt")++ def test_names_the_link_not_its_target(self, tmp_path):+ """resolve_within would return the target, so deleting it would+ destroy the pointed-at file instead of removing the link."""+ import os++ from nodes.filesystem._backend import resolve_entry_within, resolve_within++ (tmp_path / "real.txt").write_text("IMPORTANT")+ try:+ os.symlink(tmp_path / "real.txt", tmp_path / "link.txt")+ except (OSError, NotImplementedError):+ pytest.skip("symlink creation not permitted on this platform")++ assert resolve_within(tmp_path, "link.txt").name == "real.txt"++ entry = resolve_entry_within(tmp_path, "link.txt")+ assert entry.name == "link.txt"++ os.unlink(entry)+ assert not (tmp_path / "link.txt").exists()+ assert (tmp_path / "real.txt").read_text() == "IMPORTANT"++class TestInspectNeverRaises:"""D8: a parser miss degrades billing, it does not fail a workflow."""diff --git a/server/tests/routers/test_workspace.py b/server/tests/routers/test_workspace.pyindex b5810508..006c7a59 100644--- a/server/tests/routers/test_workspace.py+++ b/server/tests/routers/test_workspace.py@@ -47,7 +47,12 @@ def workspace(tmp_path, monkeypatch):"""A workspaces root containing one workflow directory, keyed by SLUG."""root = tmp_path / "workspaces"(root / SLUG / "audio").mkdir(parents=True)- monkeypatch.setattr(workspace_router, "workspaces_dir", lambda: root)+ # The id->slug translation now lives in services.workspace_locator, which+ # this router delegates to, so that is where the roots directory has to be+ # patched.+ from services import workspace_locator++ monkeypatch.setattr(workspace_locator, "workspaces_dir", lambda: root)return root / SLUGdiff --git a/server/tests/services/test_workspace_locator.py b/server/tests/services/test_workspace_locator.pynew file mode 100644index 00000000..afd6eeda--- /dev/null+++ b/server/tests/services/test_workspace_locator.py@@ -0,0 +1,87 @@+"""Contract for the workflow-id -> workspace-directory translation.++The directory on disk is named by ``Workflow.slug``, which the rename path+moves; every stable reference carries the immutable ``Workflow.id``. One+module owns that translation so the naming rule and the ``"default"``+fallback are reasoned about once.+"""++from __future__ import annotations++from types import SimpleNamespace+from unittest.mock import AsyncMock++import pytest++from services import workspace_locator+from services.workspace_locator import (+ DEFAULT_WORKSPACE_SLUG,+ resolve_workflow_slug,+ resolve_workspace_root,+)++pytestmark = pytest.mark.unit++WORKFLOW_ID = "019f99e2dc997cf390193ad3e6260de1"+SLUG = "My_Workflow_1"+++def roots(tmp_path, monkeypatch):+ monkeypatch.setattr(workspace_locator, "workspaces_dir", lambda: tmp_path)+ return tmp_path+++def _db(slug=SLUG):+ database = AsyncMock()+ database.get_workflow.return_value = SimpleNamespace(slug=slug) if slug else None+ return database+++class TestResolution:+ async def test_uses_the_slug_not_the_id(self, roots):+ root = await resolve_workspace_root(WORKFLOW_ID, _db())++ assert root == roots / SLUG+ assert WORKFLOW_ID not in str(root)++ async def test_missing_row_falls_back_to_default_for_reads(self, roots):+ assert await resolve_workspace_root(WORKFLOW_ID, _db(slug=None)) == (+ roots / DEFAULT_WORKSPACE_SLUG+ )++ async def test_database_failure_degrades_rather_than_raising(self, roots):+ database = AsyncMock()+ database.get_workflow.side_effect = RuntimeError("db down")++ assert await resolve_workflow_slug(WORKFLOW_ID, database) is None+ assert await resolve_workspace_root(WORKFLOW_ID, database) == (+ roots / DEFAULT_WORKSPACE_SLUG+ )+++class TestMutationsRefuseTheDefaultFallback:+ """The only irreversible failure this surface can produce.++ With the fallback enabled, an id that does not resolve — a stale tab, a+ workflow deleted in another window — silently lands in the shared+ anonymous workspace. Harmless for a read; for a delete it destroys files+ belonging to a different context than the caller believes.+ """++ async def test_unresolvable_workflow_is_refused(self, roots):+ from services.plugin import NodeUserError++ with pytest.raises(NodeUserError):+ await resolve_workspace_root(WORKFLOW_ID, _db(slug=None), allow_default=False)++ async def test_missing_workflow_id_is_refused(self, roots):+ from services.plugin import NodeUserError++ with pytest.raises(NodeUserError):+ await resolve_workspace_root("", _db(), allow_default=False)++ async def test_a_resolvable_workflow_still_works(self, roots):+ root = await resolve_workspace_root(WORKFLOW_ID, _db(), allow_default=False)++ assert root == roots / SLUG