Skip to content

Self-improving AI Employees for everyone

feat(media): FileRef base, entry-level containment, one workspace locator

trohitgdc0907bd0e24
diff --git a/server/nodes/filesystem/_backend.py b/server/nodes/filesystem/_backend.py
index 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 NodeUserError
diff --git a/server/routers/workspace.py b/server/routers/workspace.py
index 20f34189..67df5798 100644
--- a/server/routers/workspace.py
+++ b/server/routers/workspace.py
@@ -26,7 +26,6 @@ import hashlib
import mimetypes
from pathlib import Path
from types import SimpleNamespace
-from typing import Optional
from fastapi import APIRouter, Depends, File, HTTPException, Path as PathParam, UploadFile
from fastapi.responses import FileResponse
@@ -34,7 +33,6 @@ from fastapi.responses import FileResponse
from core.container import container
from core.database import Database
from core.logging import get_logger
-from core.paths import workspaces_dir
from services.media import MEDIA_MAX_UPLOAD_BYTES, AudioRef, write_audio
from 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.py
index 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 travel
through 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 a
silent 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, Optional
from 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 before
approaching 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's
home 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] = None
sha256: 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.py
index 3617b13c..8483e4c9 100644
--- a/server/services/media/workspace.py
+++ b/server/services/media/workspace.py
@@ -18,13 +18,13 @@ import hashlib
import mimetypes
import re
from pathlib import Path
-from typing import Any, Optional, Tuple
+from typing import Any, Optional, Tuple, get_args
from uuid import uuid4
from core.logging import get_logger
from services.media.inspect import inspect_audio
from services.media.limits import MEDIA_MAX_READ_BYTES
-from services.media.refs import AudioRef
+from services.media.refs import AudioRef, FileKind, FileRef
logger = 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_within
from 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_id
root = 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 base64
import 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 exc
return 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.py
new file mode 100644
index 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.py
index 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.py
index 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 / SLUG
diff --git a/server/tests/services/test_workspace_locator.py b/server/tests/services/test_workspace_locator.py
new file mode 100644
index 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