Skip to content

Self-improving AI Employees for everyone

feat(media): add write_media, the kind-agnostic sibling of write_audio

trohitg4f2b202e95d2
diff --git a/server/services/media/__init__.py b/server/services/media/__init__.py
index 3752ee3e..c752dc72 100644
--- a/server/services/media/__init__.py
+++ b/server/services/media/__init__.py
@@ -18,9 +18,10 @@ from services.media.limits import (
TEMPORAL_PAYLOAD_ERROR_BYTES,
TEMPORAL_PAYLOAD_WARN_BYTES,
)
-from services.media.refs import AudioRef
+from services.media.refs import AudioRef, FileKind, FileRef
from services.media.workspace import (
AUDIO_SUBDIR,
+ MEDIA_SUBDIR,
UPLOAD_SUBDIR,
coerce_file_param,
read_media_bytes,
@@ -28,13 +29,17 @@ from services.media.workspace import (
workspace_file_url,
workspace_root,
write_audio,
+ write_media,
)
__all__ = [
"AUDIO_SUBDIR",
+ "MEDIA_SUBDIR",
"UPLOAD_SUBDIR",
"AudioProbe",
"AudioRef",
+ "FileKind",
+ "FileRef",
"MEDIA_MAX_AUDIO_SECONDS",
"MEDIA_MAX_READ_BYTES",
"MEDIA_MAX_UPLOAD_BYTES",
@@ -47,4 +52,5 @@ __all__ = [
"workspace_file_url",
"workspace_root",
"write_audio",
+ "write_media",
]
diff --git a/server/services/media/workspace.py b/server/services/media/workspace.py
index 9b8f81c5..31f6e8a4 100644
--- a/server/services/media/workspace.py
+++ b/server/services/media/workspace.py
@@ -30,6 +30,7 @@ logger = get_logger(__name__)
AUDIO_SUBDIR = "audio"
UPLOAD_SUBDIR = "uploads"
+MEDIA_SUBDIR = "media"
_SLUG_RE = re.compile(r"[^a-z0-9]+")
@@ -171,30 +172,28 @@ def read_media_bytes(
return target.name, target.read_bytes()
-def write_audio(
+def _persist(
payload: bytes,
*,
ctx: Any,
stem: str,
ext: str,
- mime_type: Optional[str] = None,
- subdir: str = AUDIO_SUBDIR,
- inspect: bool = True,
- sample_rate: Optional[int] = None,
- channels: int = 1,
-) -> AudioRef:
- """Atomically write audio into the workspace and return a reference.
-
- The filename shape (``<stem>-<node8>-<rand6>.<ext>``) matches what the
- Sarvam TTS node produced before this helper existed, so porting it is
- behaviour-preserving. The random suffix also means retries and repeated
- runs never collide or silently overwrite earlier audio.
+ subdir: str,
+ empty_message: str,
+) -> Tuple[str, str, Path, Optional[str]]:
+ """Atomically place bytes in the workspace.
+
+ Returns ``(rel_path, filename, absolute_target, workflow_id)``. Shared by
+ :func:`write_audio` and :func:`write_media` so both produce byte-identical
+ naming, containment and atomicity -- the filename shape
+ ``<stem>-<node8>-<rand6>.<ext>`` carries a random suffix precisely so
+ retries and repeated runs never collide or silently overwrite.
"""
from nodes.filesystem._backend import atomic_write_bytes
from services.plugin import NodeUserError
if not payload:
- raise NodeUserError("Refusing to write an empty audio file.")
+ raise NodeUserError(empty_message)
root = workspace_root(ctx)
node_id = str(getattr(ctx, "node_id", "") or "node")
@@ -205,6 +204,41 @@ def write_audio(
target.parent.mkdir(parents=True, exist_ok=True)
atomic_write_bytes(target, payload, root_dir=root)
+ return rel, name, target, getattr(ctx, "workflow_id", None)
+
+
+def write_audio(
+ payload: bytes,
+ *,
+ ctx: Any,
+ stem: str,
+ ext: str,
+ mime_type: Optional[str] = None,
+ subdir: str = AUDIO_SUBDIR,
+ inspect: bool = True,
+ sample_rate: Optional[int] = None,
+ channels: int = 1,
+) -> AudioRef:
+ """Atomically write audio into the workspace and return a reference.
+
+ The filename shape (``<stem>-<node8>-<rand6>.<ext>``) matches what the
+ Sarvam TTS node produced before this helper existed, so porting it is
+ behaviour-preserving. The random suffix also means retries and repeated
+ runs never collide or silently overwrite earlier audio.
+
+ Returns an ``AudioRef``, i.e. it *claims* the container was probed. Use
+ :func:`write_media` for anything whose duration you have not measured --
+ see the note there.
+ """
+ rel, name, target, workflow_id = _persist(
+ payload,
+ ctx=ctx,
+ stem=stem,
+ ext=ext,
+ subdir=subdir,
+ empty_message="Refusing to write an empty audio file.",
+ )
+
probe = (
inspect_audio(
target,
@@ -215,7 +249,6 @@ def write_audio(
if inspect
else None
)
- workflow_id = getattr(ctx, "workflow_id", None)
return AudioRef(
path=rel,
@@ -232,6 +265,59 @@ def write_audio(
)
+def write_media(
+ payload: bytes,
+ *,
+ ctx: Any,
+ stem: str,
+ ext: str,
+ kind: FileKind = "file",
+ mime_type: Optional[str] = None,
+ subdir: str = MEDIA_SUBDIR,
+) -> FileRef:
+ """Atomically write any file into the workspace and return a reference.
+
+ The kind-agnostic sibling of :func:`write_audio`: same naming, same
+ containment, same atomic write, but it makes no claim about the
+ container beyond what the caller declares.
+
+ ``kind`` narrows what the reference asserts, and the honest default is
+ ``"file"``. Do **not** pass ``"audio"`` here -- that value asserts the
+ duration/rate fields came from :func:`inspect_audio`, and a fabricated
+ duration silently mis-bills per-second providers downstream. Reach for
+ :func:`write_audio` when you want that claim, which measures rather than
+ guesses. ``image`` / ``video`` / ``document`` assert nothing beyond a
+ rendering hint, so they are safe to declare from a MIME type.
+ """
+ from services.plugin import NodeUserError
+
+ if kind == "audio":
+ raise NodeUserError(
+ "write_media cannot produce kind='audio': that claims the container "
+ "was probed. Use write_audio, which measures the duration."
+ )
+
+ rel, name, _target, workflow_id = _persist(
+ payload,
+ ctx=ctx,
+ stem=stem,
+ ext=ext,
+ subdir=subdir,
+ empty_message="Refusing to write an empty file.",
+ )
+
+ return FileRef(
+ kind=kind,
+ path=rel,
+ workflow_id=workflow_id,
+ filename=name,
+ mime_type=mime_type or mimetypes.guess_type(name)[0] or "application/octet-stream",
+ size_bytes=len(payload),
+ sha256=hashlib.sha256(payload).hexdigest(),
+ url=workspace_file_url(workflow_id, rel),
+ )
+
+
def workspace_file_url(workflow_id: Optional[str], rel_path: str) -> Optional[str]:
"""Path-only URL for the workspace file route. No scheme, no host."""
if not workflow_id:
@@ -320,6 +406,7 @@ def coerce_file_param(
__all__ = [
"AUDIO_SUBDIR",
+ "MEDIA_SUBDIR",
"UPLOAD_SUBDIR",
"coerce_file_param",
"read_media_bytes",
@@ -327,4 +414,5 @@ __all__ = [
"workspace_file_url",
"workspace_root",
"write_audio",
+ "write_media",
]
diff --git a/server/tests/media/test_write_media.py b/server/tests/media/test_write_media.py
new file mode 100644
index 00000000..6e6a8554
--- /dev/null
+++ b/server/tests/media/test_write_media.py
@@ -0,0 +1,177 @@
+"""Contract for ``write_media`` — the kind-agnostic sibling of ``write_audio``.
+
+``write_audio`` produces an ``AudioRef``, which *asserts* the container was
+probed. Everything that is not audio needs the same containment, atomicity
+and naming without that claim, because ``kind="audio"`` on an unprobed file
+means a fabricated duration, and a fabricated duration silently mis-bills
+per-second providers downstream.
+"""
+
+from __future__ import annotations
+
+import struct
+import wave
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from services.media import (
+ AudioRef,
+ FileRef,
+ MEDIA_SUBDIR,
+ read_media_bytes,
+ resolve_media,
+ write_audio,
+ write_media,
+)
+
+
+pytestmark = pytest.mark.unit
+
+
+def _ctx(tmp_path: Path, *, node_id: str = "wa-node-1", workflow_id: str = "wf-1"):
+ return SimpleNamespace(
+ node_id=node_id,
+ workflow_id=workflow_id,
+ workspace_dir=str(tmp_path),
+ raw={"workspace_dir": str(tmp_path)},
+ )
+
+
+def _wav_bytes(seconds: float = 0.25, rate: int = 8000) -> bytes:
+ import io
+
+ buffer = io.BytesIO()
+ with wave.open(buffer, "wb") as handle:
+ handle.setnchannels(1)
+ handle.setsampwidth(2)
+ handle.setframerate(rate)
+ handle.writeframes(struct.pack("<h", 0) * int(rate * seconds))
+ return buffer.getvalue()
+
+
+class TestWriteMedia:
+ def test_round_trips_through_the_workspace(self, tmp_path):
+ ctx = _ctx(tmp_path)
+ ref = write_media(b"%PDF-1.7 fake", ctx=ctx, stem="invoice", ext="pdf", kind="document")
+
+ assert isinstance(ref, FileRef)
+ assert ref.kind == "document"
+ assert ref.path.startswith(f"{MEDIA_SUBDIR}/")
+ assert not ref.path.startswith("/")
+ name, blob = read_media_bytes(ref, ctx=ctx)
+ assert blob == b"%PDF-1.7 fake"
+ assert name == ref.filename
+
+ def test_defaults_to_the_honest_kind(self, tmp_path):
+ """``file`` asserts nothing beyond existence, so it is the default."""
+ ref = write_media(b"data", ctx=_ctx(tmp_path), stem="x", ext="bin")
+ assert ref.kind == "file"
+
+ @pytest.mark.parametrize("kind", ["file", "image", "video", "document"])
+ def test_accepts_every_non_audio_kind(self, tmp_path, kind):
+ ref = write_media(b"data", ctx=_ctx(tmp_path), stem="x", ext="bin", kind=kind)
+ assert ref.kind == kind
+
+ def test_refuses_to_claim_audio(self, tmp_path):
+ """The whole point of the split.
+
+ ``kind="audio"`` means the duration/rate fields came from a real
+ probe. Letting a caller assert it here would reintroduce exactly the
+ mis-billing ``AudioRef`` exists to prevent, so it is refused rather
+ than silently downgraded.
+ """
+ from services.plugin import NodeUserError
+
+ with pytest.raises(NodeUserError, match="write_audio"):
+ write_media(_wav_bytes(), ctx=_ctx(tmp_path), stem="clip", ext="wav", kind="audio")
+
+ def test_carries_no_probe_fields(self, tmp_path):
+ """A FileRef has no duration to fabricate -- structurally."""
+ ref = write_media(_wav_bytes(), ctx=_ctx(tmp_path), stem="clip", ext="wav")
+ assert not hasattr(ref, "duration_seconds")
+ assert "duration_seconds" not in ref.model_dump()
+
+ def test_never_collides_across_runs(self, tmp_path):
+ ctx = _ctx(tmp_path)
+ first = write_media(b"a", ctx=ctx, stem="same", ext="bin")
+ second = write_media(b"b", ctx=ctx, stem="same", ext="bin")
+ assert first.path != second.path
+ assert read_media_bytes(first, ctx=ctx)[1] == b"a"
+ assert read_media_bytes(second, ctx=ctx)[1] == b"b"
+
+ def test_url_is_path_only(self, tmp_path):
+ ref = write_media(b"data", ctx=_ctx(tmp_path), stem="x", ext="png", kind="image")
+ assert ref.url == f"/api/workspace/wf-1/files/{ref.path}"
+ assert "://" not in ref.url
+
+ def test_mime_is_guessed_but_overridable(self, tmp_path):
+ guessed = write_media(b"data", ctx=_ctx(tmp_path), stem="x", ext="png", kind="image")
+ assert guessed.mime_type == "image/png"
+
+ declared = write_media(
+ b"data", ctx=_ctx(tmp_path), stem="x", ext="bin", mime_type="application/vnd.custom"
+ )
+ assert declared.mime_type == "application/vnd.custom"
+
+ def test_unknown_extension_falls_back_to_octet_stream(self, tmp_path):
+ ref = write_media(b"data", ctx=_ctx(tmp_path), stem="x", ext="zzzz")
+ assert ref.mime_type == "application/octet-stream"
+
+ def test_refuses_empty_payload(self, tmp_path):
+ from services.plugin import NodeUserError
+
+ with pytest.raises(NodeUserError):
+ write_media(b"", ctx=_ctx(tmp_path), stem="x", ext="bin")
+
+ def test_sha256_matches_payload(self, tmp_path):
+ import hashlib
+
+ payload = b"some bytes"
+ ref = write_media(payload, ctx=_ctx(tmp_path), stem="x", ext="bin")
+ assert ref.sha256 == hashlib.sha256(payload).hexdigest()
+ assert ref.size_bytes == len(payload)
+
+
+class TestContainmentIsShared:
+ """write_media must inherit the same containment as write_audio."""
+
+ def test_a_ref_cannot_reach_another_workflows_workspace(self, tmp_path):
+ alpha, beta = tmp_path / "alpha", tmp_path / "beta"
+ alpha.mkdir()
+ beta.mkdir()
+
+ ref = write_media(b"data", ctx=_ctx(alpha, workflow_id="alpha"), stem="x", ext="bin")
+ with pytest.raises(Exception):
+ read_media_bytes(ref, ctx=_ctx(beta, workflow_id="beta"))
+
+ def test_traversing_stem_cannot_escape(self, tmp_path):
+ """The stem is slugified, so separators never survive into the path."""
+ ref = write_media(b"data", ctx=_ctx(tmp_path), stem="../../etc/passwd", ext="bin")
+ assert ".." not in ref.path
+ assert ref.path.startswith(f"{MEDIA_SUBDIR}/")
+ resolved = resolve_media(ref, ctx=_ctx(tmp_path))
+ assert tmp_path in resolved.parents
+
+
+class TestWriteAudioUnchanged:
+ """The refactor must not alter write_audio's observable behaviour."""
+
+ def test_still_returns_an_audio_ref_with_a_measured_duration(self, tmp_path):
+ ref = write_audio(_wav_bytes(seconds=0.5, rate=8000), ctx=_ctx(tmp_path), stem="clip", ext="wav")
+ assert isinstance(ref, AudioRef)
+ assert ref.kind == "audio"
+ assert ref.format == "wav"
+ assert ref.duration_seconds == pytest.approx(0.5, abs=0.05)
+ assert ref.sample_rate == 8000
+
+ def test_still_defaults_to_the_audio_subdir(self, tmp_path):
+ ref = write_audio(_wav_bytes(), ctx=_ctx(tmp_path), stem="clip", ext="wav")
+ assert ref.path.startswith("audio/")
+
+ def test_still_refuses_empty_payload(self, tmp_path):
+ from services.plugin import NodeUserError
+
+ with pytest.raises(NodeUserError, match="empty audio"):
+ write_audio(b"", ctx=_ctx(tmp_path), stem="x", ext="wav")