nerdstack-ark 1.0.3__tar.gz → 1.0.4__tar.gz

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.3
+Version: 1.0.4
 Summary: Official Python SDK for Ark storage, with sync, async, and S3-compatible access.
 Project-URL: Homepage, https://ark.nerdstackgrp.com
 Project-URL: Documentation, https://github.com/joshhumphrey02/ark-sdk/tree/master/packages/ark-py#readme
@@ -132,9 +132,21 @@ session = ark.create_client_session(ttl_seconds=900)
 
 ## Ark Streams
 
-Both synchronous and asynchronous clients expose the Ark Streams control
-plane. Creating a video returns a TUS endpoint for the client that owns the
-video bytes. A remote import is fetched directly by Ark's video provider.
+Both synchronous and asynchronous clients expose Ark Streams. `upload` is the
+one call most applications need: it creates the video and sends the bytes,
+resuming from the server's acknowledged offset if the connection drops.
+
+```python
+stream = ark.streams.upload(
+    "./launch.mp4",
+    title="Product launch",
+    app_id=app_id,
+    on_progress=lambda sent, total: print(f"{sent}/{total}"),
+)
+```
+
+Use `create` directly when the bytes belong to someone else -- a browser, or a
+worker -- and you only need the upload ticket:
 
 ```python
 creation = ark.streams.create("Product launch", size_bytes, app_id=app_id)
@@ -147,9 +159,10 @@ ark.streams.refresh_upload_url(stream.id, app_id=app_id)
 ark.streams.delete(stream.id, app_id=app_id)
 ```
 
-The same methods on `AsyncArk.streams` are awaitable. Poll `get` while a video
-is uploading or encoding; `hls_url` and `embed_url` are populated when its
-status becomes `ready`.
+The same methods on `AsyncArk.streams` are awaitable. Encoding continues after
+an upload returns, so poll `get` until `status` is `ready`; `hls_url`,
+`thumbnail_url` and `embed_url` are `None` until then. `embed_url` is an
+Ark-hosted player page that can go straight into an iframe.
 
 ## S3-compatible access
 

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.4}/README.md

@@ -89,9 +89,21 @@ session = ark.create_client_session(ttl_seconds=900)
 
 ## Ark Streams
 
-Both synchronous and asynchronous clients expose the Ark Streams control
-plane. Creating a video returns a TUS endpoint for the client that owns the
-video bytes. A remote import is fetched directly by Ark's video provider.
+Both synchronous and asynchronous clients expose Ark Streams. `upload` is the
+one call most applications need: it creates the video and sends the bytes,
+resuming from the server's acknowledged offset if the connection drops.
+
+```python
+stream = ark.streams.upload(
+    "./launch.mp4",
+    title="Product launch",
+    app_id=app_id,
+    on_progress=lambda sent, total: print(f"{sent}/{total}"),
+)
+```
+
+Use `create` directly when the bytes belong to someone else -- a browser, or a
+worker -- and you only need the upload ticket:
 
 ```python
 creation = ark.streams.create("Product launch", size_bytes, app_id=app_id)
@@ -104,9 +116,10 @@ ark.streams.refresh_upload_url(stream.id, app_id=app_id)
 ark.streams.delete(stream.id, app_id=app_id)
 ```
 
-The same methods on `AsyncArk.streams` are awaitable. Poll `get` while a video
-is uploading or encoding; `hls_url` and `embed_url` are populated when its
-status becomes `ready`.
+The same methods on `AsyncArk.streams` are awaitable. Encoding continues after
+an upload returns, so poll `get` until `status` is `ready`; `hls_url`,
+`thumbnail_url` and `embed_url` are `None` until then. `embed_url` is an
+Ark-hosted player page that can go straight into an iframe.
 
 ## S3-compatible access
 

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nerdstack-ark"
-version = "1.0.3"
+version = "1.0.4"
 description = "Official Python SDK for Ark storage, with sync, async, and S3-compatible access."
 readme = "README.md"
 requires-python = ">=3.10"

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.4}/src/ark_py/_shared.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import base64
 import mimetypes
 import os
 from collections.abc import Iterable, Iterator, Mapping
@@ -180,3 +181,46 @@ def sorted_parts(parts: Iterable[dict[str, object]]) -> list[dict[str, object]]:
         return value
 
     return sorted(parts, key=part_number)
+
+
+# --- Ark Streams resumable upload (TUS) -------------------------------------
+#
+# Video goes to the encoding network over TUS rather than through the presigned
+# path files use: an encode is long enough that a dropped connection is normal
+# rather than exceptional, so the protocol has to be able to say "you already
+# have the first N bytes, continue from there".
+
+#: TUS sends metadata as base64, so a filename with non-ASCII characters
+#: survives the header intact.
+def tus_metadata(value: str) -> str:
+    return base64.b64encode(value.encode("utf-8")).decode("ascii")
+
+
+#: Default slice sent per PATCH. Large enough that a long video is not thousands
+#: of round trips, small enough that a failure re-sends little.
+DEFAULT_VIDEO_CHUNK_SIZE = 64 * 1024 * 1024
+
+#: Consecutive failures tolerated per chunk before giving up. Each retry first
+#: asks the server what it actually holds, so a retry never duplicates bytes.
+MAX_VIDEO_CHUNK_RETRIES = 2
+
+
+def validate_chunk_size(chunk_size: int) -> None:
+    if isinstance(chunk_size, bool) or not isinstance(chunk_size, int) or chunk_size <= 0:
+        raise invalid_argument("chunk_size must be a positive integer")
+
+
+def resumed_offset(header: str | None, total: int, fallback: Exception) -> int:
+    """Read an Upload-Offset the server reported, or re-raise.
+
+    A server that answers with an offset past the end of the file, or with
+    something unparseable, cannot be resumed from safely -- continuing would
+    either skip bytes or corrupt the video.
+    """
+    try:
+        offset = int(header or "")
+    except ValueError:
+        raise fallback from None
+    if offset < 0 or offset > total:
+        raise fallback
+    return offset

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.4}/src/ark_py/async_client.py

@@ -4,8 +4,9 @@ import asyncio
 import builtins
 import mimetypes
 import os
-from collections.abc import AsyncIterable, AsyncIterator, Mapping
+from collections.abc import AsyncIterable, AsyncIterator, Callable, Mapping
 from contextlib import suppress
+from pathlib import Path
 from types import TracebackType
 from typing import Any, BinaryIO, TypeVar, cast
 
@@ -14,6 +15,8 @@ import httpx
 from ._shared import (
     DEFAULT_BASE_URL,
     DEFAULT_CONTENT_TYPE,
+    DEFAULT_VIDEO_CHUNK_SIZE,
+    MAX_VIDEO_CHUNK_RETRIES,
     UploadSource,
     api_url,
     image_url,
@@ -21,9 +24,12 @@ from ._shared import (
     query_string,
     read_exact,
     resolve_upload_source,
+    resumed_offset,
     segment,
     sorted_parts,
+    tus_metadata,
     upload_payload,
+    validate_chunk_size,
     validate_size,
 )
 from .errors import ArkError, error_from_response, invalid_argument, network_error, upload_error
@@ -525,6 +531,138 @@ class AsyncStreams:
         suffix = query_string({"appId": app_id})
         await self._ark._request("DELETE", f"/streams/{segment(stream_id)}{suffix}")
 
+    async def upload(
+        self,
+        source: str | Path | BinaryIO,
+        *,
+        title: str | None = None,
+        size: int | None = None,
+        filename: str | None = None,
+        content_type: str | None = None,
+        app_id: str | None = None,
+        collection_id: str | None = None,
+        chunk_size: int = DEFAULT_VIDEO_CHUNK_SIZE,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> ArkStream:
+        """Create a stream and upload the video, resuming across failures.
+
+        The async twin of `Streams.upload`. See that method for why this exists
+        rather than leaving TUS to the caller.
+        """
+        validate_chunk_size(chunk_size)
+        resolved = resolve_upload_source(
+            source,
+            size=size,
+            filename=filename,
+            content_type=content_type or "video/mp4",
+        )
+
+        created = await self.create(
+            title or Path(resolved.filename).stem,
+            resolved.size,
+            app_id=app_id,
+            collection_id=collection_id,
+        )
+
+        upload_url = await self._create_tus_upload(created.upload.endpoint, resolved)
+        handle = resolved.path.open("rb") if resolved.path is not None else resolved.stream
+        try:
+            await self._send_chunks(
+                upload_url, handle, resolved.size, chunk_size, on_progress
+            )
+        finally:
+            if resolved.path is not None:
+                handle.close()
+        return created.stream
+
+    async def _create_tus_upload(self, endpoint: str, resolved: UploadSource) -> str:
+        url = self._ark._url(endpoint) if endpoint.startswith("/") else endpoint
+        try:
+            response = await self._ark._client.request(
+                "POST",
+                url,
+                headers={
+                    "authorization": f"Bearer {self._ark._token}",
+                    "Tus-Resumable": "1.0.0",
+                    "Upload-Length": str(resolved.size),
+                    "Upload-Metadata": (
+                        f"filename {tus_metadata(resolved.filename)},"
+                        f"filetype {tus_metadata(resolved.content_type)}"
+                    ),
+                },
+            )
+        except httpx.HTTPError as error:
+            raise network_error(error) from error
+        if response.is_error:
+            raise error_from_response(response)
+
+        location = response.headers.get("location")
+        if not location:
+            raise ArkError("INTERNAL_ERROR", "Ark did not return an upload location")
+        return str(httpx.URL(url).join(location))
+
+    async def _send_chunks(
+        self,
+        upload_url: str,
+        handle: BinaryIO,
+        total: int,
+        chunk_size: int,
+        on_progress: Callable[[int, int], None] | None,
+    ) -> None:
+        offset = 0
+        retries = 0
+        while offset < total:
+            handle.seek(offset)
+            chunk = handle.read(min(chunk_size, total - offset))
+            if not chunk:
+                raise ArkError(
+                    "INVALID_ARGUMENT",
+                    "The video source ended before the declared size was reached",
+                )
+            try:
+                response = await self._ark._client.request(
+                    "PATCH",
+                    upload_url,
+                    headers={
+                        "authorization": f"Bearer {self._ark._token}",
+                        "Tus-Resumable": "1.0.0",
+                        "Upload-Offset": str(offset),
+                        "Content-Type": "application/offset+octet-stream",
+                    },
+                    content=chunk,
+                )
+                if response.is_error:
+                    raise error_from_response(response)
+                acknowledged = response.headers.get("upload-offset")
+                try:
+                    offset = max(offset + len(chunk), int(acknowledged or ""))
+                except ValueError:
+                    offset += len(chunk)
+                retries = 0
+                if on_progress is not None:
+                    on_progress(offset, total)
+            except ArkError as error:
+                if retries >= MAX_VIDEO_CHUNK_RETRIES:
+                    raise
+                retries += 1
+                offset = await self._head_offset(upload_url, total, error)
+
+    async def _head_offset(self, upload_url: str, total: int, fallback: ArkError) -> int:
+        try:
+            head = await self._ark._client.request(
+                "HEAD",
+                upload_url,
+                headers={
+                    "authorization": f"Bearer {self._ark._token}",
+                    "Tus-Resumable": "1.0.0",
+                },
+            )
+        except httpx.HTTPError:
+            raise fallback from None
+        if head.is_error:
+            raise fallback
+        return resumed_offset(head.headers.get("upload-offset"), total, fallback)
+
 
 def _as_async_iterable(source: AsyncSource) -> AsyncIterator[bytes] | None:
     method = getattr(source, "__aiter__", None)

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.4}/src/ark_py/models.py

@@ -101,7 +101,15 @@ StreamStatus = Literal["created", "uploading", "processing", "ready", "failed"]
 
 @dataclass(frozen=True, slots=True)
 class ArkStream:
-    """A video managed by Ark Streams. Playback URLs are None until it is ready."""
+    """A video managed by Ark Streams.
+
+    ``hls_url``, ``thumbnail_url`` and ``embed_url`` are None until ``status``
+    is ``"ready"``: an encode takes time, and returning a URL that 404s would be
+    worse than reporting that it is unfinished. Poll ``streams.get`` until then.
+
+    ``embed_url`` is an Ark-hosted player page -- put it straight in an iframe.
+    Playback is signed server-side per viewer, so it carries no credential.
+    """
 
     id: str
     title: str

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.4}/src/ark_py/sync.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import builtins
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from concurrent.futures import FIRST_COMPLETED, Future, ThreadPoolExecutor, wait
 from contextlib import suppress
 from pathlib import Path
@@ -12,6 +12,8 @@ import httpx
 
 from ._shared import (
     DEFAULT_BASE_URL,
+    DEFAULT_VIDEO_CHUNK_SIZE,
+    MAX_VIDEO_CHUNK_RETRIES,
     UploadSource,
     api_url,
     ensure_stream_complete,
@@ -22,9 +24,12 @@ from ._shared import (
     query_string,
     read_exact,
     resolve_upload_source,
+    resumed_offset,
     segment,
     sorted_parts,
+    tus_metadata,
     upload_payload,
+    validate_chunk_size,
 )
 from .errors import ArkError, error_from_response, network_error, upload_error
 from .models import (
@@ -479,3 +484,145 @@ class Streams:
     def delete(self, stream_id: str, *, app_id: str | None = None) -> None:
         suffix = query_string({"appId": app_id})
         self._ark._request("DELETE", f"/streams/{segment(stream_id)}{suffix}")
+
+    def upload(
+        self,
+        source: str | Path | BinaryIO,
+        *,
+        title: str | None = None,
+        size: int | None = None,
+        filename: str | None = None,
+        content_type: str | None = None,
+        app_id: str | None = None,
+        collection_id: str | None = None,
+        chunk_size: int = DEFAULT_VIDEO_CHUNK_SIZE,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> ArkStream:
+        """Create a stream and upload the video, resuming across failures.
+
+        `create()` only returns a ticket; the bytes still have to be sent, and
+        doing that correctly means speaking TUS. Without this a Python caller
+        had to implement the protocol themselves, which is the one part of
+        Streams they should not have to think about.
+
+        Returns the stream as it was at creation. Encoding continues afterwards,
+        so poll `get()` for `status == "ready"` before using the playback URLs.
+        """
+        validate_chunk_size(chunk_size)
+        resolved = resolve_upload_source(
+            source,
+            size=size,
+            filename=filename,
+            content_type=content_type or "video/mp4",
+        )
+
+        created = self.create(
+            title or Path(resolved.filename).stem,
+            resolved.size,
+            app_id=app_id,
+            collection_id=collection_id,
+        )
+
+        upload_url = self._create_tus_upload(created.upload.endpoint, resolved)
+        handle = resolved.path.open("rb") if resolved.path is not None else resolved.stream
+        try:
+            self._send_chunks(upload_url, handle, resolved.size, chunk_size, on_progress)
+        finally:
+            if resolved.path is not None:
+                handle.close()
+        return created.stream
+
+    def _create_tus_upload(self, endpoint: str, resolved: UploadSource) -> str:
+        """Open the TUS upload and return the URL to send chunks to."""
+        url = self._ark._url(endpoint) if endpoint.startswith("/") else endpoint
+        try:
+            response = self._ark._client.request(
+                "POST",
+                url,
+                headers={
+                    "authorization": f"Bearer {self._ark._token}",
+                    "Tus-Resumable": "1.0.0",
+                    "Upload-Length": str(resolved.size),
+                    "Upload-Metadata": (
+                        f"filename {tus_metadata(resolved.filename)},"
+                        f"filetype {tus_metadata(resolved.content_type)}"
+                    ),
+                },
+            )
+        except httpx.HTTPError as error:
+            raise network_error(error) from error
+        if response.is_error:
+            raise error_from_response(response)
+
+        location = response.headers.get("location")
+        if not location:
+            raise ArkError("INTERNAL_ERROR", "Ark did not return an upload location")
+        # The server may answer with a relative location.
+        return str(httpx.URL(url).join(location))
+
+    def _send_chunks(
+        self,
+        upload_url: str,
+        handle: BinaryIO,
+        total: int,
+        chunk_size: int,
+        on_progress: Callable[[int, int], None] | None,
+    ) -> None:
+        offset = 0
+        retries = 0
+        while offset < total:
+            handle.seek(offset)
+            chunk = handle.read(min(chunk_size, total - offset))
+            if not chunk:
+                raise ArkError(
+                    "INVALID_ARGUMENT",
+                    "The video source ended before the declared size was reached",
+                )
+            try:
+                response = self._ark._client.request(
+                    "PATCH",
+                    upload_url,
+                    headers={
+                        "authorization": f"Bearer {self._ark._token}",
+                        "Tus-Resumable": "1.0.0",
+                        "Upload-Offset": str(offset),
+                        "Content-Type": "application/offset+octet-stream",
+                    },
+                    content=chunk,
+                )
+                if response.is_error:
+                    raise error_from_response(response)
+                # Trust the server's acknowledged offset over our own arithmetic:
+                # it is the only party that knows what actually landed.
+                acknowledged = response.headers.get("upload-offset")
+                try:
+                    offset = max(offset + len(chunk), int(acknowledged or ""))
+                except ValueError:
+                    offset += len(chunk)
+                retries = 0
+                if on_progress is not None:
+                    on_progress(offset, total)
+            except ArkError as error:
+                if retries >= MAX_VIDEO_CHUNK_RETRIES:
+                    raise
+                retries += 1
+                # Ask what the server holds rather than assuming the chunk was
+                # lost -- a failure after the bytes landed would otherwise send
+                # them twice.
+                offset = self._head_offset(upload_url, total, error)
+
+    def _head_offset(self, upload_url: str, total: int, fallback: ArkError) -> int:
+        try:
+            head = self._ark._client.request(
+                "HEAD",
+                upload_url,
+                headers={
+                    "authorization": f"Bearer {self._ark._token}",
+                    "Tus-Resumable": "1.0.0",
+                },
+            )
+        except httpx.HTTPError:
+            raise fallback from None
+        if head.is_error:
+            raise fallback
+        return resumed_offset(head.headers.get("upload-offset"), total, fallback)

nerdstack_ark-1.0.4/tests/test_stream_upload.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+import pytest
+from conftest import json_response
+
+from ark_py import Ark, ArkError
+
+STREAM = {
+    "id": "stream-1",
+    "title": "clip",
+    "status": "created",
+    "encodeProgress": 0,
+    "durationSeconds": 0,
+    "width": 0,
+    "height": 0,
+    "size": 9,
+    "thumbnailUrl": None,
+    "hlsUrl": None,
+    "embedUrl": None,
+    "createdAt": "2026-09-03T00:00:00.000Z",
+}
+
+
+class TusServer:
+    """A TUS endpoint that records what it was sent.
+
+    `fail_at_offset` makes exactly one PATCH fail *after* accepting the bytes,
+    which is the case worth testing: a client that assumes a failed request
+    transferred nothing would resend those bytes and corrupt the video.
+    """
+
+    def __init__(self, total: int, *, fail_at_offset: int | None = None) -> None:
+        self.total = total
+        self.fail_at_offset = fail_at_offset
+        self.received = bytearray()
+        self.patches: list[int] = []
+        self.head_calls = 0
+
+    def handler(self, request: httpx.Request) -> httpx.Response:
+        if request.url.path.endswith("/streams") and request.method == "POST":
+            return json_response({"stream": STREAM, "upload": {"endpoint": "/streams/stream-1/upload"}})
+
+        if request.url.path == "/api/v2/streams/stream-1/upload" and request.method == "POST":
+            assert request.headers["upload-length"] == str(self.total)
+            assert "filename" in request.headers["upload-metadata"]
+            return httpx.Response(201, headers={"location": "/api/v2/streams/stream-1/upload/abc"})
+
+        if request.url.path.endswith("/upload/abc") and request.method == "HEAD":
+            self.head_calls += 1
+            return httpx.Response(200, headers={"upload-offset": str(len(self.received))})
+
+        if request.url.path.endswith("/upload/abc") and request.method == "PATCH":
+            offset = int(request.headers["upload-offset"])
+            self.patches.append(offset)
+            body = request.read()
+            # The server only accepts a write that starts where it left off.
+            assert offset == len(self.received), "client resent or skipped bytes"
+            self.received.extend(body)
+            if self.fail_at_offset is not None and offset == self.fail_at_offset:
+                self.fail_at_offset = None
+                return httpx.Response(500, json={"error": "flaky"})
+            return httpx.Response(204, headers={"upload-offset": str(len(self.received))})
+
+        raise AssertionError(f"unexpected {request.method} {request.url}")
+
+
+def client_for(server: TusServer) -> Ark:
+    return Ark(
+        "token",
+        base_url="https://ark.test",
+        client=httpx.Client(transport=httpx.MockTransport(server.handler)),
+    )
+
+
+def test_uploads_a_file_in_chunks(tmp_path: Path) -> None:
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abcdefghi")
+    server = TusServer(9)
+
+    stream = client_for(server).streams.upload(path, chunk_size=4)
+
+    assert stream.id == "stream-1"
+    assert bytes(server.received) == b"abcdefghi"
+    assert server.patches == [0, 4, 8]
+
+
+def test_resumes_from_the_server_offset_after_a_failure(tmp_path: Path) -> None:
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abcdefghi")
+    # The failure lands after the server stored bytes 4-7.
+    server = TusServer(9, fail_at_offset=4)
+
+    client_for(server).streams.upload(path, chunk_size=4)
+
+    # The whole file arrives exactly once: the retry asked where to continue
+    # rather than resending the chunk that had in fact landed.
+    assert bytes(server.received) == b"abcdefghi"
+    assert server.head_calls == 1
+
+
+def test_reports_progress(tmp_path: Path) -> None:
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abcdefghi")
+    seen: list[tuple[int, int]] = []
+
+    client_for(TusServer(9)).streams.upload(
+        path, chunk_size=4, on_progress=lambda done, total: seen.append((done, total))
+    )
+
+    assert seen == [(4, 9), (8, 9), (9, 9)]
+
+
+def test_derives_the_title_from_the_filename(tmp_path: Path) -> None:
+    path = tmp_path / "my-launch-video.mp4"
+    path.write_bytes(b"abc")
+    titles: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path.endswith("/streams") and request.method == "POST":
+            import json as _json
+
+            titles.append(_json.loads(request.read())["title"])
+            return json_response({"stream": STREAM, "upload": {"endpoint": "/streams/stream-1/upload"}})
+        if request.method == "POST":
+            return httpx.Response(201, headers={"location": "/api/v2/streams/stream-1/upload/abc"})
+        return httpx.Response(204, headers={"upload-offset": "3"})
+
+    Ark(
+        "token",
+        base_url="https://ark.test",
+        client=httpx.Client(transport=httpx.MockTransport(handler)),
+    ).streams.upload(path)
+
+    assert titles == ["my-launch-video"]
+
+
+def test_rejects_an_invalid_chunk_size(tmp_path: Path) -> None:
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abc")
+
+    with pytest.raises(ArkError) as excinfo:
+        client_for(TusServer(3)).streams.upload(path, chunk_size=0)
+
+    assert excinfo.value.code == "INVALID_ARGUMENT"
+
+
+@pytest.mark.asyncio
+async def test_async_upload_matches_the_sync_client(tmp_path: Path) -> None:
+    """The async client must transfer identically, not merely succeed."""
+    from ark_py import AsyncArk
+
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abcdefghi")
+    server = TusServer(9, fail_at_offset=4)
+
+    ark = AsyncArk(
+        "token",
+        base_url="https://ark.test",
+        client=httpx.AsyncClient(transport=httpx.MockTransport(server.handler)),
+    )
+    stream = await ark.streams.upload(path, chunk_size=4)
+
+    assert stream.id == "stream-1"
+    assert bytes(server.received) == b"abcdefghi"
+    assert server.head_calls == 1