hotdata-framework 0.12.0__tar.gz → 0.12.1__tar.gz

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/.github/workflows/publish.yml

@@ -31,6 +31,21 @@ jobs:
       # The tag being released, whether it arrived by push or by dispatch.
       TAG: ${{ inputs.tag || github.ref_name }}
     steps:
+      # Before checkout, because checkout resolves the input as an arbitrary ref:
+      # a branch or SHA is fetched first and only rejected later by the version
+      # match below, which is also looser (`^v[0-9]`). Strict here so the dispatch
+      # contract matches release.yml — release.sh only ever produces X.Y.Z.
+      - name: Validate release tag format
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$INPUT_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "tag must look like vX.Y.Z, got: $INPUT_TAG" >&2
+            exit 1
+          fi
+
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.tag || github.ref_name }}

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/.github/workflows/release.yml

@@ -25,6 +25,24 @@ jobs:
       # The tag being released, whether it arrived by push or by dispatch.
       TAG: ${{ inputs.tag || github.ref_name }}
     steps:
+      # Before checkout, because checkout resolves the input as an arbitrary ref
+      # — and this workflow needs the guard more than publish.yml does. It holds
+      # `contents: write`, and action-gh-release CREATES a tag when tag_name does
+      # not resolve to one, so an unvalidated `tag: main` would check out cleanly
+      # and leave refs/tags/main plus a release named for it. The push path is
+      # constrained by the v[0-9]* filter; the dispatch path was not constrained
+      # at all.
+      - name: Validate release tag format
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$INPUT_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "tag must look like vX.Y.Z, got: $INPUT_TAG" >&2
+            exit 1
+          fi
+
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.tag || github.ref_name }}

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.12.1] - 2026-08-18
+
+### Fixed
+
+- fix(load): submit managed loads as a job and poll, instead of holding one request open
+
 ## [0.12.0] - 2026-08-11
 
 ### Added

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hotdata-framework
-Version: 0.12.0
+Version: 0.12.1
 Summary: Python framework for building Hotdata integrations: workspace runtime, query execution, and managed databases
 Project-URL: Homepage, https://www.hotdata.dev
 Project-URL: Documentation, https://www.hotdata.dev/docs

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/hotdata_framework/client.py

@@ -25,6 +25,7 @@ from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl
 from hotdata.models.index_info_response import IndexInfoResponse
 from hotdata.models.job_status_response import JobStatusResponse
 from hotdata.models.load_managed_table_request import LoadManagedTableRequest
+from hotdata.models.load_managed_table_response import LoadManagedTableResponse
 from hotdata.models.query_request import QueryRequest
 from hotdata.models.query_response import QueryResponse
 from hotdata.models.submit_job_response import SubmitJobResponse
@@ -81,6 +82,37 @@ _RESULT_FAILURE = frozenset({"failed", "cancelled"})
 # Jobs have no "cancelled" state; "partially_succeeded" carries an error_message.
 _JOB_TERMINAL = frozenset({"succeeded", "partially_succeeded", "failed"})
 
+# How long a load may finish INLINE before the server hands back a job instead.
+# Small enough that a slow load stops holding a request open, large enough that
+# the overwhelming majority never become jobs at all: dlt's bookkeeping tables
+# (`_dlt_version`, `_dlt_loads`, `_dlt_pipeline_state`) settle in under a second,
+# and paying a submit-then-poll round trip for those would be a regression.
+_LOAD_INLINE_WAIT_MS = 10_000
+
+# A load's own polling budget. Deliberately NOT the 300s used for queries and
+# results: a load is the one operation here whose duration scales with the data,
+# and reusing the query budget is what put a five-minute ceiling on it in the
+# first place. Bounded rather than unbounded so a wedged job still surfaces.
+_LOAD_JOB_TIMEOUT_S = 3600.0
+
+# How long a poll tolerates CONTINUOUS status-check failure before giving up.
+#
+# Time, not a count: a count means whatever the caller's `interval_s` makes it,
+# and callers differ -- five checks is eight seconds at the load interval and
+# something else at the index one. The thing being survived is a gateway blip,
+# and a rolling restart or a load balancer reconverging routinely serves 502s for
+# longer than a few seconds. Too short and the poll aborts, the caller's retry
+# re-submits the load, and the original job is still holding the table -- the
+# door this tolerance exists to close.
+#
+# Still bounded by the poll's own deadline, so this only decides how a stretch of
+# failures ends, never how long the wait can be.
+_JOB_POLL_ERROR_GRACE_S = 120.0
+
+# Failed checks back off rather than hammering at `interval_s`: whatever is
+# serving 502s does not need the extra traffic.
+_JOB_POLL_ERROR_MAX_BACKOFF_S = 15.0
+
 
 @dataclass(frozen=True)
 class ResultSummary:
@@ -418,10 +450,25 @@ class HotdataClient:
         else:
             assert file is not None
             resolved_upload_id = self.upload_parquet(file)
+        # ASKED FOR AS A JOB, not as a held-open request. A load's duration scales
+        # with the data, and a single request that must survive minutes has to
+        # survive every layer between here and the engine -- CDN, gateway, socket
+        # read timeout -- any one of which ends it. When it ends, the server logs
+        # the load `abandoned` and DISCARDS work it had already done, while the
+        # table's write lock is still held against the retry that follows; the
+        # retry then collides with it (409 RESOURCE_LOCKED) and the pair can spin
+        # indefinitely without the load ever completing. Observed in production on
+        # a table whose load runs past five minutes.
+        #
+        # `async_after_ms` keeps the common case unchanged: the server answers 200
+        # with the result if it finishes inside the window, and only falls back to
+        # a job when it does not. So nothing pays for polling that did not need it.
         request = LoadManagedTableRequest(
             mode=mode,
             upload_id=resolved_upload_id,
             key=key,
+            var_async=True,
+            async_after_ms=_LOAD_INLINE_WAIT_MS,
         )
         try:
             loaded = self.connections().load_managed_table(
@@ -432,12 +479,21 @@ class HotdataClient:
             )
         except ApiException as e:
             raise RuntimeError(api_error_message(e)) from e
+        # Only the job branch is type-checked. The index path can also assert its
+        # inline type because it names it positively first; here the inline shape is
+        # read duck-typed, which callers and tests already rely on, so asserting it
+        # would narrow an interface this change has no business narrowing.
+        job_id: str | None = None
+        if isinstance(loaded, SubmitJobResponse):
+            job_id = loaded.id
+            loaded = self._load_response_from_job(job_id)
         return LoadManagedTableResult(
             connection_id=loaded.connection_id,
             schema_name=loaded.schema_name,
             table_name=loaded.table_name,
             row_count=loaded.row_count,
             full_name=f"{db.id}.{loaded.schema_name}.{loaded.table_name}",
+            job_id=job_id,
         )
 
     def add_managed_table(
@@ -880,11 +936,40 @@ class HotdataClient:
         jobs = self._jobs_api()
         deadline = time.monotonic() + timeout_s
         last: JobStatusResponse | None = None
+        # When the current run of failures began, or None while checks succeed.
+        failing_since: float | None = None
+        error_backoff = interval_s
         while time.monotonic() < deadline:
             try:
                 last = jobs.get_job(job_id)
+                failing_since = None
+                error_backoff = interval_s
             except ApiException as e:
-                raise RuntimeError(api_error_message(e)) from e
+                # A failed STATUS CHECK is not a failed job. Aborting here throws
+                # away work that is still running, and the caller's retry then
+                # re-submits it while the original still holds its resources -- so
+                # one blip becomes a collision with the job it just abandoned. A
+                # load polls for up to `_LOAD_JOB_TIMEOUT_S`, so the longer the
+                # wait the more chances to hit it, which is exactly backwards.
+                #
+                # CONSECUTIVE failures are the signal: an isolated 502 is noise, a
+                # run of them means the API is gone and there is nothing to wait
+                # for. The poll's own deadline bounds the total wait regardless.
+                now = time.monotonic()
+                if failing_since is None:
+                    failing_since = now
+                elif now - failing_since >= _JOB_POLL_ERROR_GRACE_S:
+                    # Name the job. This is one of the two paths where the caller
+                    # cannot tell whether the load landed, so the id is the only
+                    # thing that makes the question answerable -- and it is exactly
+                    # what a message like "502: Bad Gateway" leaves out.
+                    raise RuntimeError(
+                        f"Job {job_id} status checks failed for "
+                        f"{_JOB_POLL_ERROR_GRACE_S:.0f}s: {api_error_message(e)}"
+                    ) from e
+                time.sleep(error_backoff)
+                error_backoff = min(error_backoff * 2, _JOB_POLL_ERROR_MAX_BACKOFF_S)
+                continue
             if last.status in _JOB_TERMINAL:
                 return last
             time.sleep(interval_s)
@@ -893,6 +978,39 @@ class HotdataClient:
             f"Job {job_id} did not finish within {timeout_s}s (last status: {last_status})"
         )
 
+    def _load_response_from_job(self, job_id: str) -> LoadManagedTableResponse:
+        """The result of a load the server chose to run as a job.
+
+        Polling replaces waiting on the request, so the outcome is read from
+        durable state rather than from a connection that has to stay alive. That
+        also gives a caller a handle: the job id is returned on
+        `LoadManagedTableResult`, so "did it land?" is answerable after a lost
+        response. `append` stays non-retryable -- knowing the id makes the question
+        answerable, it does not make a blind re-submission safe, and that call is
+        the caller's to make.
+
+        `partially_succeeded` is terminal and carries a message, so it is raised
+        rather than returned -- a caller asked for a table's contents to be
+        replaced or appended to, and "some of it" is not an answer it can use.
+        """
+        final = self._poll_job(job_id, timeout_s=_LOAD_JOB_TIMEOUT_S)
+        status = enum_value(final.status)
+        if status != "succeeded":
+            # The id goes in whether or not the server's message mentions it: the
+            # caller is being told the load did not succeed, and "which load" is
+            # the next thing it needs.
+            detail = final.error_message or f"finished {status}"
+            raise RuntimeError(f"load job {job_id} {status}: {detail}")
+        # `result` is a oneOf wrapper today; tolerate the model arriving directly,
+        # the same way the index path does rather than disagreeing with it.
+        payload = getattr(final.result, "actual_instance", final.result)
+        if not isinstance(payload, LoadManagedTableResponse):
+            raise RuntimeError(
+                f"load job {job_id} succeeded without a load result "
+                f"(got {type(payload).__name__})"
+            )
+        return payload
+
     def _wait_result_ready(
         self,
         result_id: str,

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/hotdata_framework/databases.py

@@ -83,6 +83,11 @@ class LoadManagedTableResult:
     table_name: str
     row_count: int
     full_name: str
+    # Set when the server ran the load as a background job. Carried for the same
+    # reason CreateIndexResult carries it: it is the only handle a caller has to
+    # ask "did that land?" after a lost response, and without it the question is
+    # unanswerable. `None` when the load finished inline.
+    job_id: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         return asdict(self)

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hotdata-framework"
-version = "0.12.0"
+version = "0.12.1"
 description = "Python framework for building Hotdata integrations: workspace runtime, query execution, and managed databases"
 readme = "README.md"
 requires-python = ">=3.10"

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/tests/test_client.py

@@ -37,11 +37,16 @@ class _ForbiddenDatabasesApi:
 
 
 class _FakeConnectionsApi:
-    def __init__(self) -> None:
+    def __init__(self, responses=None) -> None:
         self.load_calls: list[tuple[str, str, str]] = []
+        self.requests: list = []
+        self._responses = list(responses) if responses else None
 
     def load_managed_table(self, connection_id, schema, table, request):
         self.load_calls.append((connection_id, schema, table))
+        self.requests.append(request)
+        if self._responses:
+            return self._responses.pop(0)
         return SimpleNamespace(
             connection_id=connection_id,
             schema_name=schema,
@@ -544,3 +549,328 @@ def test_from_env_requires_an_api_key(monkeypatch: pytest.MonkeyPatch):
     monkeypatch.delenv("HOTDATA_API_KEY", raising=False)
     with pytest.raises(RuntimeError, match="HOTDATA_API_KEY"):
         HotdataClient.from_env()
+
+
+# --------------------------------------------------------------------------
+# A load is submitted as a job, not held open on one request
+# --------------------------------------------------------------------------
+
+
+def _load_response(rows=7):
+    from hotdata.models.load_managed_table_response import LoadManagedTableResponse
+
+    return LoadManagedTableResponse(
+        connection_id="conn_1", schema_name="public",
+        table_name="orders", row_count=rows,
+        arrow_schema_json="{}",
+    )
+
+
+def test_a_load_asks_for_a_job_with_an_inline_window():
+    """The request itself is the fix. A load whose duration scales with the data
+    must not depend on one HTTP request surviving minutes through every layer
+    between here and the engine; when such a request dies the server discards the
+    work and leaves the table locked against the retry."""
+    from hotdata_framework.client import _LOAD_INLINE_WAIT_MS
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    connections = _FakeConnectionsApi()
+
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=connections),
+    ):
+        client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+
+    req = connections.requests[0]
+    assert req.var_async is True, "load was not submitted as a job"
+    assert req.async_after_ms == _LOAD_INLINE_WAIT_MS
+
+
+def test_a_load_that_finishes_inline_costs_no_polling():
+    """dlt's bookkeeping tables settle in under a second. Making those pay a
+    submit-then-poll round trip would be a regression, which is what
+    `async_after_ms` exists to prevent."""
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    connections = _FakeConnectionsApi()
+
+    def _forbidden_poll(*a, **k):
+        raise AssertionError("polled a load the server answered inline")
+
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=connections),
+        patch.object(client, "_poll_job", _forbidden_poll),
+    ):
+        result = client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+
+    assert result.row_count == 3
+
+
+def test_a_load_the_server_defers_is_polled_to_completion():
+    """The 202 path: the result comes from durable job state rather than from a
+    connection that had to stay alive to carry it."""
+    from hotdata.models.submit_job_response import SubmitJobResponse
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    connections = _FakeConnectionsApi(responses=[
+        SubmitJobResponse(id="jobs_1", status="running", status_url="/v1/jobs/jobs_1"),
+    ])
+    final = SimpleNamespace(
+        status="succeeded", error_message=None,
+        result=SimpleNamespace(actual_instance=_load_response(rows=91)),
+    )
+
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=connections),
+        patch.object(client, "_poll_job", return_value=final) as poll,
+    ):
+        result = client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+
+    assert result.row_count == 91
+    assert poll.call_args.args[0] == "jobs_1"
+
+
+def test_a_load_job_gets_its_own_budget_not_the_query_one():
+    """Reusing the 300s query budget is what put a five-minute ceiling on loads in
+    the first place; a load is the one operation whose duration scales with the
+    data."""
+    from hotdata.models.submit_job_response import SubmitJobResponse
+
+    from hotdata_framework.client import _LOAD_JOB_TIMEOUT_S
+
+    assert _LOAD_JOB_TIMEOUT_S > 300.0
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    connections = _FakeConnectionsApi(responses=[
+        SubmitJobResponse(id="jobs_1", status="running", status_url="/v1/jobs/jobs_1"),
+    ])
+    final = SimpleNamespace(
+        status="succeeded", error_message=None,
+        result=SimpleNamespace(actual_instance=_load_response()),
+    )
+
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=connections),
+        patch.object(client, "_poll_job", return_value=final) as poll,
+    ):
+        client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+
+    assert poll.call_args.kwargs["timeout_s"] == _LOAD_JOB_TIMEOUT_S
+
+
+def test_a_failed_load_job_raises_with_the_server_message():
+    from hotdata.models.submit_job_response import SubmitJobResponse
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    connections = _FakeConnectionsApi(responses=[
+        SubmitJobResponse(id="jobs_1", status="running", status_url="/v1/jobs/jobs_1"),
+    ])
+    final = SimpleNamespace(status="failed", error_message="disk full", result=None)
+
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=connections),
+        patch.object(client, "_poll_job", return_value=final),
+    ):
+        try:
+            client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+        except RuntimeError as e:
+            assert "disk full" in str(e), e
+        else:
+            raise AssertionError("a failed load job did not raise")
+
+
+def test_a_partially_succeeded_load_job_is_not_treated_as_success():
+    """A caller asked for a table's contents to be replaced or appended to;
+    "some of it" is not an answer it can use."""
+    from hotdata.models.submit_job_response import SubmitJobResponse
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    connections = _FakeConnectionsApi(responses=[
+        SubmitJobResponse(id="jobs_1", status="running", status_url="/v1/jobs/jobs_1"),
+    ])
+    final = SimpleNamespace(
+        status="partially_succeeded", error_message="3 rows rejected",
+        result=SimpleNamespace(actual_instance=_load_response()),
+    )
+
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=connections),
+        patch.object(client, "_poll_job", return_value=final),
+    ):
+        try:
+            client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+        except RuntimeError as e:
+            assert "3 rows rejected" in str(e), e
+        else:
+            raise AssertionError("partially_succeeded was treated as success")
+
+
+def test_a_transient_status_check_does_not_discard_a_running_job():
+    """The regression this guards. A load polls for up to an hour, so there are
+    hundreds of status checks; aborting on the first bad one throws away a job
+    that is still running, and the caller's retry then re-submits the load while
+    the original still holds the table -- the 409 spin, from a new direction."""
+    from hotdata.exceptions import ApiException
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    calls = {"n": 0}
+    final = SimpleNamespace(status="succeeded", error_message=None,
+                            result=SimpleNamespace(actual_instance=_load_response(5)))
+
+    class _Flaky:
+        def get_job(self, job_id):
+            calls["n"] += 1
+            if calls["n"] < 3:
+                raise ApiException(status=502, reason="Bad Gateway")
+            return final
+
+    with (
+        patch.object(client, "_jobs_api", return_value=_Flaky()),
+        patch("time.sleep", lambda *_: None),
+    ):
+        got = client._poll_job("jobs_1", timeout_s=60.0, interval_s=0.01)
+
+    assert got is final, "a blipping status check aborted the poll"
+    assert calls["n"] == 3
+
+
+def test_a_sustained_run_of_failed_status_checks_gives_up_naming_the_job():
+    """Tolerance is for blips, not for an API that has gone away -- and the message
+    has to name the job, because this is one of the two paths where the caller
+    cannot tell whether the load landed. `502: Bad Gateway` alone does not."""
+    from hotdata.exceptions import ApiException
+
+    from hotdata_framework.client import _JOB_POLL_ERROR_GRACE_S
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+
+    class _Dead:
+        def get_job(self, job_id):
+            raise ApiException(status=502, reason="Bad Gateway")
+
+    # A FAKE CLOCK, advanced by the sleeps. The tolerance is measured in time, so
+    # a no-op `sleep` with a real clock would make this test wait out the whole
+    # grace period in wall time -- 120 seconds of a spinning loop to assert one
+    # message.
+    clock = {"t": 0.0}
+    with (
+        patch.object(client, "_jobs_api", return_value=_Dead()),
+        patch("time.monotonic", lambda: clock["t"]),
+        patch("time.sleep", lambda s: clock.__setitem__("t", clock["t"] + s)),
+    ):
+        try:
+            client._poll_job("jobs_1", timeout_s=6000.0, interval_s=1.0)
+        except RuntimeError as e:
+            assert "jobs_1" in str(e), f"gave up without naming the job: {e}"
+        else:
+            raise AssertionError("polled forever against a dead API")
+    assert clock["t"] >= _JOB_POLL_ERROR_GRACE_S, "gave up before the grace elapsed"
+    assert clock["t"] < 6000.0, "ran to the poll deadline instead of the grace"
+
+
+def test_the_error_tolerance_is_measured_in_time_not_checks():
+    """A count means whatever the caller's `interval_s` makes it, and callers
+    differ. The thing being survived is a gateway blip, which lasts seconds to
+    minutes regardless of how often we happen to ask."""
+    from hotdata_framework.client import _JOB_POLL_ERROR_GRACE_S
+
+    # long enough to outlast a rolling restart / LB reconverge, not seconds
+    assert _JOB_POLL_ERROR_GRACE_S >= 60.0
+
+
+def test_failed_status_checks_back_off_instead_of_hammering():
+    """Whatever is serving 502s does not need the extra traffic."""
+    from hotdata.exceptions import ApiException
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    sleeps: list[float] = []
+    calls = {"n": 0}
+    final = SimpleNamespace(status="succeeded", error_message=None,
+                            result=SimpleNamespace(actual_instance=_load_response()))
+
+    class _Flaky:
+        def get_job(self, job_id):
+            calls["n"] += 1
+            if calls["n"] < 5:
+                raise ApiException(status=502, reason="Bad Gateway")
+            return final
+
+    with (
+        patch.object(client, "_jobs_api", return_value=_Flaky()),
+        patch("time.sleep", lambda s: sleeps.append(s)),
+    ):
+        client._poll_job("jobs_1", timeout_s=600.0, interval_s=1.0)
+
+    failed_waits = sleeps[:4]
+    assert failed_waits == sorted(failed_waits), f"did not back off: {failed_waits}"
+    assert failed_waits[-1] > failed_waits[0]
+
+
+def test_a_failed_load_job_names_the_job_alongside_the_server_message():
+    from hotdata.models.submit_job_response import SubmitJobResponse
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    connections = _FakeConnectionsApi(responses=[
+        SubmitJobResponse(id="jobs_42", status="running", status_url="/v1/jobs/jobs_42"),
+    ])
+    final = SimpleNamespace(status="failed", error_message="disk full", result=None)
+
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=connections),
+        patch.object(client, "_poll_job", return_value=final),
+    ):
+        try:
+            client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+        except RuntimeError as e:
+            assert "disk full" in str(e) and "jobs_42" in str(e), e
+        else:
+            raise AssertionError("a failed load job did not raise")
+
+
+def test_a_deferred_load_returns_the_job_id_to_the_caller():
+    """`append` stays non-retryable, so the id is the only handle a caller has to
+    answer "did it land?" after a lost response -- the same reason
+    CreateIndexResult carries one."""
+    from hotdata.models.submit_job_response import SubmitJobResponse
+
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    connections = _FakeConnectionsApi(responses=[
+        SubmitJobResponse(id="jobs_77", status="running", status_url="/v1/jobs/jobs_77"),
+    ])
+    final = SimpleNamespace(status="succeeded", error_message=None,
+                            result=SimpleNamespace(actual_instance=_load_response()))
+
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=connections),
+        patch.object(client, "_poll_job", return_value=final),
+    ):
+        result = client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+
+    assert result.job_id == "jobs_77"
+
+
+def test_an_inline_load_carries_no_job_id():
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    db = ManagedDatabase(id="db_1", description="mydb", default_connection_id="conn_1")
+    with (
+        patch.object(client, "_databases_api", return_value=_ForbiddenDatabasesApi()),
+        patch.object(client, "connections", return_value=_FakeConnectionsApi()),
+    ):
+        result = client.load_managed_table(db, "orders", schema="public", upload_id="up_1")
+    assert result.job_id is None
+

{hotdata_framework-0.12.0 → hotdata_framework-0.12.1}/uv.lock

@@ -101,7 +101,7 @@ wheels = [
 
 [[package]]
 name = "hotdata-framework"
-version = "0.12.0"
+version = "0.12.1"
 source = { editable = "." }
 dependencies = [
     { name = "hotdata" },