nerdstack-ark 1.0.5__tar.gz → 1.0.6__tar.gz

{nerdstack_ark-1.0.5 → nerdstack_ark-1.0.6}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## 1.0.5
 
+### Added
+
+- `ArkStream.hls_expires_at` reports when `hls_url` and `thumbnail_url` stop
+  working, so a caller can refresh before playback breaks instead of guessing a
+  lifetime. Absent on older deployments, where it parses as `None`.
+
+### Changed
+
+- Documented that `hls_url` and `thumbnail_url` are signed and expire within
+  the hour, and must not be stored. `ArkFile.url` is a permanent CDN path, and
+  the identical field names made the opposite behaviour easy to miss: storing a
+  playback URL yields a link that works in testing and is dead when a user
+  opens it. Persist `id` and resolve playback on demand, or use `embed_url`,
+  which carries no credential and does not expire.
+
 ### Fixed
 
 - `folders.list()` and `AsyncFolders.list()` returned an empty tuple against

{nerdstack_ark-1.0.5 → nerdstack_ark-1.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.5
+Version: 1.0.6
 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

{nerdstack_ark-1.0.5 → nerdstack_ark-1.0.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nerdstack-ark"
-version = "1.0.5"
+version = "1.0.6"
 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.5 → nerdstack_ark-1.0.6}/src/ark_py/errors.py

@@ -30,16 +30,55 @@ class ArkError(Exception):
 
     @property
     def retryable(self) -> bool:
-        return self.code in {"NETWORK_ERROR", "RATE_LIMITED"} or (
+        # BLOCKED_BY_EDGE is retryable: the request never reached Ark, and a
+        # challenge can clear on a retry or once the block is lifted.
+        return self.code in {"NETWORK_ERROR", "RATE_LIMITED", "BLOCKED_BY_EDGE"} or (
             self.status is not None and self.status >= 500
         )
 
 
+def _is_edge_block(response: httpx.Response, parsed: bool) -> bool:
+    """Whether a failure came from something in front of Ark rather than Ark.
+
+    The Ark API answers every request -- success or error -- with JSON, so an
+    HTML body on an error response cannot have come from Ark. In practice it is
+    a CDN or WAF challenge page: server-side SDK calls originate from
+    data-centre IP ranges, which bot protection scores as automated traffic.
+
+    Detected by content type rather than by matching challenge text, so this
+    holds for any interposed proxy and not just one vendor's wording.
+    """
+    if parsed:
+        return False
+    if response.status_code not in {403, 503, 429}:
+        return False
+    return "text/html" in response.headers.get("content-type", "")
+
+
 def error_from_response(response: httpx.Response) -> ArkError:
+    parsed = True
     try:
         body = response.json()
     except ValueError:
         body = {}
+        parsed = False
+
+    # Reported before the status mapping below, which would otherwise call this
+    # INSUFFICIENT_SCOPE and send the developer to audit a token that is fine.
+    if _is_edge_block(response, parsed):
+        ray = response.headers.get("cf-ray")
+        return ArkError(
+            "BLOCKED_BY_EDGE",
+            "The request was blocked by a network in front of Ark and never reached it. "
+            "This usually means bot protection challenged the call because it came from a "
+            "data-centre IP, which is where server-side code runs. "
+            "The site owner can allow it by exempting the API path from the challenge."
+            + (f" Reference: cf-ray {ray}." if ray else ""),
+            status=response.status_code,
+            request_id=ray,
+            details={"cfRay": ray} if ray else None,
+        )
+
     raw_error = body.get("error") if isinstance(body, dict) else None
     envelope = raw_error if isinstance(raw_error, dict) else {}
     status_codes = {

{nerdstack_ark-1.0.5 → nerdstack_ark-1.0.6}/src/ark_py/models.py

@@ -108,7 +108,15 @@ class ArkStream:
     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.
+    Playback is signed server-side per viewer, so it carries no credential, and
+    it does not expire. It is the one playback value that is safe to store.
+
+    **Do not store ``hls_url`` or ``thumbnail_url``.** Unlike ``ArkFile.url``,
+    which is a permanent CDN path, both are signed and expire within the hour
+    (``hls_expires_at`` says when). Persist ``id`` instead and call
+    ``streams.get(id)`` when you are about to play; treat them the way you
+    would a presigned URL. Writing one into a database or an email produces a
+    link that works in testing and is dead when a user opens it.
     """
 
     id: str
@@ -121,6 +129,9 @@ class ArkStream:
     size: int
     thumbnail_url: str | None
     hls_url: str | None
+    #: When ``hls_url``/``thumbnail_url`` stop working (ISO-8601), or None when
+    #: the library serves unsigned URLs that never expire.
+    hls_expires_at: str | None
     embed_url: str | None
     created_at: str
 
@@ -137,6 +148,7 @@ class ArkStream:
             size=int(value.get("size") or 0),
             thumbnail_url=_optional_string(value.get("thumbnailUrl")),
             hls_url=_optional_string(value.get("hlsUrl")),
+            hls_expires_at=_optional_string(value.get("hlsExpiresAt")),
             embed_url=_optional_string(value.get("embedUrl")),
             created_at=str(value.get("createdAt") or ""),
         )

nerdstack_ark-1.0.6/tests/test_edge_block.py

@@ -0,0 +1,62 @@
+"""A challenge page from a CDN in front of Ark must not read as a token problem.
+
+Regression test for a real incident: a customer's Netlify functions were
+challenged by Cloudflare bot protection, and the SDK reported the 403 as
+INSUFFICIENT_SCOPE. Their developer spent hours auditing token scopes for a
+request that never reached Ark at all.
+"""
+
+import httpx
+
+from ark_py.errors import error_from_response
+
+CHALLENGE_BODY = "<!DOCTYPE html><html><head><title>Just a moment...</title></head></html>"
+
+
+def _response(status, body, content_type, headers=None):
+    return httpx.Response(
+        status,
+        content=body,
+        headers={"content-type": content_type, **(headers or {})},
+    )
+
+
+def test_html_challenge_is_reported_as_an_edge_block():
+    error = error_from_response(
+        _response(403, CHALLENGE_BODY, "text/html; charset=UTF-8", {"cf-ray": "a376f9d70bd71709-CMH"})
+    )
+    assert error.code == "BLOCKED_BY_EDGE"
+    assert error.status == 403
+    # The ray id is the only handle on the block in the Cloudflare event log,
+    # so it has to survive into the error rather than be discarded.
+    assert error.details == {"cfRay": "a376f9d70bd71709-CMH"}
+    assert "cf-ray a376f9d70bd71709-CMH" in error.message
+
+
+def test_edge_block_is_retryable():
+    error = error_from_response(_response(403, CHALLENGE_BODY, "text/html"))
+    assert error.retryable is True
+
+
+def test_a_genuine_scope_failure_is_untouched():
+    body = '{"error": {"code": "INSUFFICIENT_SCOPE", "message": "Token lacks scope"}}'
+    error = error_from_response(_response(403, body, "application/json"))
+    assert error.code == "INSUFFICIENT_SCOPE"
+    assert error.retryable is False
+
+
+def test_non_html_403_keeps_the_status_mapping():
+    error = error_from_response(_response(403, "nope", "text/plain"))
+    assert error.code == "INSUFFICIENT_SCOPE"
+
+
+def test_html_on_an_unrelated_status_is_not_an_edge_block():
+    # A 500 HTML page is an origin fault, not a challenge; calling it an edge
+    # block would point the developer at Cloudflare for an Ark bug.
+    error = error_from_response(_response(500, "<html>oops</html>", "text/html"))
+    assert error.code == "INTERNAL_ERROR"
+
+
+def test_html_503_is_an_edge_block():
+    error = error_from_response(_response(503, CHALLENGE_BODY, "text/html"))
+    assert error.code == "BLOCKED_BY_EDGE"

{nerdstack_ark-1.0.5 → nerdstack_ark-1.0.6}/tests/test_sync.py

@@ -24,6 +24,7 @@ STREAM_RESPONSE = {
     "size": 42,
     "thumbnailUrl": "https://cdn.test/thumb.jpg",
     "hlsUrl": "https://cdn.test/playlist.m3u8",
+    "hlsExpiresAt": "2026-09-03T01:00:00.000Z",
     "embedUrl": "https://player.test/embed",
     "createdAt": "2026-09-03T00:00:00.000Z",
 }
@@ -136,7 +137,11 @@ def test_streams_control_plane() -> None:
     assert streams.create("Launch", 42, app_id="app-1").upload.endpoint.endswith("/upload")
     assert streams.import_from_url("Remote", "https://video.test/a.mp4").id == "stream-1"
     assert streams.list(app_id="app-1", limit=10).next_cursor == "next"
-    assert streams.get("stream-1", app_id="app-1").hls_url is not None
+    fetched = streams.get("stream-1", app_id="app-1")
+    assert fetched.hls_url is not None
+    # Playback URLs are signed and short-lived; the expiry has to survive
+    # deserialization or a caller has no way to refresh before it lapses.
+    assert fetched.hls_expires_at == "2026-09-03T01:00:00.000Z"
     assert streams.refresh_upload_url("stream-1", app_id="app-1").endpoint.endswith("appId=app-1")
     assert streams.delete("stream-1", app_id="app-1") is None
     assert requests[2] == ("GET", "https://ark.test/api/v2/streams?appId=app-1&limit=10")