contree-client 0.2.1.dev0__tar.gz → 0.2.2__tar.gz

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contree-client
-Version: 0.2.1.dev0
+Version: 0.2.2
 Summary: Python client for the Contree API, generated from the OpenAPI specification
 Author: Dmitry Orlov
 Author-email: Dmitry Orlov <mosquito@nebius.com>

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/contree_client/base.py

@@ -16,9 +16,9 @@ import platform
 import sys
 import time
 from abc import ABC, abstractmethod
-from collections.abc import AsyncGenerator, Iterable, Iterator
+from collections.abc import AsyncGenerator, Iterable, Iterator, Sequence
 from contextlib import aclosing
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from types import EllipsisType, TracebackType
 from typing import IO, Any, Literal, TypeVar
@@ -35,6 +35,7 @@ from .exceptions import (
 from .models import (
     ClosableStreamRepr,
     DirectoryList,
+    EventDataCompletion,
     File,
     FileResponse,
     FilesListResponse,
@@ -55,6 +56,7 @@ from .models import (
 )
 from .profiles import AUTH_TYPE_IAM, Profile, ProfileError, resolve_profile
 from .runtime import (
+    EVENTS_UNAVAILABLE_STATUSES,
     TIGHT_LOOP_FLOOR,
     BodyFormatter,
     HeaderFormatter,
@@ -370,10 +372,13 @@ class ContreeSyncClient(ContreeClientBase, ABC):
         (410/425/5xx) reconnect from the last received event id, so no
         event is delivered twice; before every reconnect the operation
         status is probed and iteration ends if it already became
-        terminal. Other API errors (404, 403, ...) propagate.
+        terminal. A status meaning the events endpoint itself doesn't
+        exist for this operation/server (400/404/405/406) stops
+        reconnecting and instead polls :meth:`get_operation_status`
+        until the operation is terminal. Other API errors propagate.
         Iteration also ends after the ``completion`` event. *timeout*
-        bounds the whole wait; it is enforced between events and
-        reconnect cycles and raises :class:`TimeoutError`.
+        bounds the whole wait; it is enforced between events, reconnect
+        cycles and polling, and raises :class:`TimeoutError`.
         """
         last_id = last_event_id
         delays = retry_generator()
@@ -410,6 +415,55 @@ class ContreeSyncClient(ContreeClientBase, ABC):
                     last_id = exc.last_event_id
                 self.log.warning("stream error (last_id=%s): %s", last_id, exc)
             except ContreeAPIError as exc:
+                if exc.status in EVENTS_UNAVAILABLE_STATUSES:
+                    # the endpoint is gone, not just failing: reconnecting
+                    # the same request will never work, but the operation
+                    # may still finish - stop touching /events and poll
+                    # status instead for the rest of this wait
+                    self.log.warning(
+                        "events endpoint unavailable (%d), falling back to polling",
+                        exc.status,
+                    )
+                    while True:
+                        check_deadline()
+                        try:
+                            response = self.get_operation_status(operation_id)
+                        except (ContreeError, *self.retryable_errors):
+                            response = None
+                        if (
+                            response is not None
+                            and not isinstance(response.status, EllipsisType)
+                            and response.status.is_terminal()
+                        ):
+                            # no event log to relay, but a caller of
+                            # follow_operation_events must still observe a
+                            # terminal completion rather than nothing at all
+                            last_id = 0 if last_id is None else last_id + 1
+                            duration = response.duration
+                            image_size = response.image_size
+                            yield OperationEvent(
+                                id=last_id,
+                                ts=datetime.now(timezone.utc),
+                                type="completion",
+                                data=EventDataCompletion(
+                                    status=response.status,
+                                    duration_ms=round(duration * 1000)
+                                    if isinstance(duration, (int, float))
+                                    else 0,
+                                    result_image_uuid=response.result_image_uuid,
+                                    error=response.error,
+                                    image_size_bytes=(
+                                        image_size
+                                        if isinstance(image_size, int)
+                                        else ...
+                                    ),
+                                ),
+                            )
+                            return
+                        delay = next(delays)
+                        if deadline is not None:
+                            delay = min(delay, max(0.0, deadline - time.monotonic()))
+                        time.sleep(delay)
                 retryable = exc.status in (410, 425) or 500 <= exc.status < 600
                 if not retryable:
                     raise
@@ -925,9 +979,12 @@ class ContreeSyncClient(ContreeClientBase, ABC):
             uid: User ID to run the process as. Example: ``0``.
             gid: Group ID to run the process as. Example: ``0``.
             timeout: Maximum execution time in seconds Example: ``60``.
-            truncate_output_at: Maximum number of bytes to keep from
-                stdout/stderr. Default is ``1048576`` (1 MiB). The maximum
-                value is ``10485760`` (10 MiB). Example: ``65535``.
+            truncate_output_at: Maximum number of bytes to keep per stream
+                (stdout, stderr, and stdin) in the subprocess event log.
+                Does not affect stdin delivery to the child, which always
+                receives the complete stream regardless of this cap. Default
+                is ``1048576`` (1 MiB). The maximum value is ``10485760``
+                (10 MiB). Example: ``65535``.
             files: Map of absolute file paths to file metadata Example:
                 ``{"/root/hello.txt":{"uuid":"a9165a5d-5c86-4bd8-8ee4-ae46c...``.
         """
@@ -1335,9 +1392,11 @@ class ContreeSyncClient(ContreeClientBase, ABC):
                 main process and exec'd subprocesses. With ``close=false``
                 the pipe stays open and more data can be written via
                 ``POST /operations/{operationId}/subprocesses/{spid}/stdin``.
-            truncate_output_at: Maximum number of bytes of stdout / stderr
-                to keep. Defaults to 1 MiB; capped at 10 MiB. Example:
-                ``65535``.
+            truncate_output_at: Maximum number of bytes to keep per stream
+                (stdout, stderr, and stdin) in the subprocess event log.
+                Does not affect delivery to the child — stdin is always
+                delivered in full regardless of this cap. Defaults to 1 MiB;
+                capped at 10 MiB. Example: ``65535``.
         """
         spec = operations.build_operation_subprocess_create(
             operation_id=operation_id,
@@ -1618,10 +1677,10 @@ class ContreeSyncClient(ContreeClientBase, ABC):
     def inspect_image_grep(
         self,
         image_uuid: str,
-        pattern: str,
+        pattern: str | Sequence[str],
         *,
-        path: str | None = None,
-        glob: str | None = None,
+        path: str | Sequence[str] | None = None,
+        glob: str | Sequence[str] | None = None,
         max_count: int | None = None,
         max_total: int | None = None,
         case: Literal["sensitive", "insensitive", "smart"] | None = None,
@@ -1863,10 +1922,13 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
         (410/425/5xx) reconnect from the last received event id, so no
         event is delivered twice; before every reconnect the operation
         status is probed and iteration ends if it already became
-        terminal. Other API errors (404, 403, ...) propagate.
+        terminal. A status meaning the events endpoint itself doesn't
+        exist for this operation/server (400/404/405/406) stops
+        reconnecting and instead polls :meth:`get_operation_status`
+        until the operation is terminal. Other API errors propagate.
         Iteration also ends after the ``completion`` event. *timeout*
-        bounds the whole wait; it is enforced between events and
-        reconnect cycles and raises :class:`TimeoutError`.
+        bounds the whole wait; it is enforced between events, reconnect
+        cycles and polling, and raises :class:`TimeoutError`.
         """
         last_id = last_event_id
         delays = retry_generator()
@@ -1894,6 +1956,24 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
                 check_deadline()
                 raise
 
+        async def operation_status_before_deadline() -> OperationResponse | None:
+            try:
+                if deadline is None:
+                    return await self.get_operation_status(operation_id)
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    check_deadline()
+                try:
+                    return await asyncio.wait_for(
+                        self.get_operation_status(operation_id),
+                        timeout=remaining,
+                    )
+                except asyncio.TimeoutError:
+                    check_deadline()
+                    raise
+            except (ContreeError, *self.retryable_errors):
+                return None
+
         while True:
             check_deadline()
             events_before = last_id
@@ -1923,6 +2003,51 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
                     last_id = exc.last_event_id
                 self.log.warning("stream error (last_id=%s): %s", last_id, exc)
             except ContreeAPIError as exc:
+                if exc.status in EVENTS_UNAVAILABLE_STATUSES:
+                    # the endpoint is gone, not just failing: reconnecting
+                    # the same request will never work, but the operation
+                    # may still finish - stop touching /events and poll
+                    # status instead for the rest of this wait
+                    self.log.warning(
+                        "events endpoint unavailable (%d), falling back to polling",
+                        exc.status,
+                    )
+                    while True:
+                        response = await operation_status_before_deadline()
+                        if (
+                            response is not None
+                            and not isinstance(response.status, EllipsisType)
+                            and response.status.is_terminal()
+                        ):
+                            # no event log to relay, but a caller of
+                            # follow_operation_events must still observe a
+                            # terminal completion rather than nothing at all
+                            last_id = 0 if last_id is None else last_id + 1
+                            duration = response.duration
+                            image_size = response.image_size
+                            yield OperationEvent(
+                                id=last_id,
+                                ts=datetime.now(timezone.utc),
+                                type="completion",
+                                data=EventDataCompletion(
+                                    status=response.status,
+                                    duration_ms=round(duration * 1000)
+                                    if isinstance(duration, (int, float))
+                                    else 0,
+                                    result_image_uuid=response.result_image_uuid,
+                                    error=response.error,
+                                    image_size_bytes=(
+                                        image_size
+                                        if isinstance(image_size, int)
+                                        else ...
+                                    ),
+                                ),
+                            )
+                            return
+                        delay = next(delays)
+                        if deadline is not None:
+                            delay = min(delay, max(0.0, deadline - time.monotonic()))
+                        await asyncio.sleep(delay)
                 retryable = exc.status in (410, 425) or 500 <= exc.status < 600
                 if not retryable:
                     raise
@@ -2450,9 +2575,12 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
             uid: User ID to run the process as. Example: ``0``.
             gid: Group ID to run the process as. Example: ``0``.
             timeout: Maximum execution time in seconds Example: ``60``.
-            truncate_output_at: Maximum number of bytes to keep from
-                stdout/stderr. Default is ``1048576`` (1 MiB). The maximum
-                value is ``10485760`` (10 MiB). Example: ``65535``.
+            truncate_output_at: Maximum number of bytes to keep per stream
+                (stdout, stderr, and stdin) in the subprocess event log.
+                Does not affect stdin delivery to the child, which always
+                receives the complete stream regardless of this cap. Default
+                is ``1048576`` (1 MiB). The maximum value is ``10485760``
+                (10 MiB). Example: ``65535``.
             files: Map of absolute file paths to file metadata Example:
                 ``{"/root/hello.txt":{"uuid":"a9165a5d-5c86-4bd8-8ee4-ae46c...``.
         """
@@ -2861,9 +2989,11 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
                 main process and exec'd subprocesses. With ``close=false``
                 the pipe stays open and more data can be written via
                 ``POST /operations/{operationId}/subprocesses/{spid}/stdin``.
-            truncate_output_at: Maximum number of bytes of stdout / stderr
-                to keep. Defaults to 1 MiB; capped at 10 MiB. Example:
-                ``65535``.
+            truncate_output_at: Maximum number of bytes to keep per stream
+                (stdout, stderr, and stdin) in the subprocess event log.
+                Does not affect delivery to the child — stdin is always
+                delivered in full regardless of this cap. Defaults to 1 MiB;
+                capped at 10 MiB. Example: ``65535``.
         """
         spec = operations.build_operation_subprocess_create(
             operation_id=operation_id,
@@ -3149,10 +3279,10 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
     async def inspect_image_grep(
         self,
         image_uuid: str,
-        pattern: str,
+        pattern: str | Sequence[str],
         *,
-        path: str | None = None,
-        glob: str | None = None,
+        path: str | Sequence[str] | None = None,
+        glob: str | Sequence[str] | None = None,
         max_count: int | None = None,
         max_total: int | None = None,
         case: Literal["sensitive", "insensitive", "smart"] | None = None,

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/contree_client/models.py

@@ -601,9 +601,12 @@ class StreamRepr(ContreeModel):
 
 @dataclass
 class ClosableStreamRepr(ContreeModel):
-    """Stdin payload.  Unlike output streams it is never truncated;.
+    """Stdin payload.  Delivery to the child is always complete —.
 
-    instead it carries a ``close`` flag controlling the pipe's EOF.
+    stdin is never truncated on its way to the process.  Only the
+    *recorded* ``stdin`` events in the subprocess event log are
+    capped by ``truncate_output_at``, same as stdout/stderr.  This
+    schema also carries a ``close`` flag controlling the pipe's EOF.
     """
 
     value: str = field(
@@ -732,8 +735,10 @@ class ExecSpec(ContreeModel):
         default=...,
         metadata={
             "description": (
-                "Maximum number of bytes of stdout / stderr to keep.\nDefaults to 1 "
-                "MiB; capped at 10 MiB."
+                "Maximum number of bytes to keep per stream (stdout,\nstderr, and "
+                "stdin) in the subprocess event log.  Does not\naffect delivery to the "
+                "child — stdin is always delivered\nin full regardless of this cap.  "
+                "Defaults to 1 MiB; capped\nat 10 MiB."
             ),
             "example": 65535,
             "default": 1048576,
@@ -904,8 +909,11 @@ class InstanceSpawnRequest(ContreeModel):
         default=...,
         metadata={
             "description": (
-                "Maximum number of bytes to keep from stdout/stderr. Default is "
-                "`1048576` (1 MiB). The maximum value is `10485760` (10 MiB)."
+                "Maximum number of bytes to keep per stream (stdout, stderr, and "
+                "stdin) in the subprocess event log. Does not affect stdin delivery to "
+                "the child, which always receives the complete stream regardless of "
+                "this cap. Default is `1048576` (1 MiB). The maximum value is "
+                "`10485760` (10 MiB)."
             ),
             "example": 65535,
             "default": 1048576,
@@ -1357,8 +1365,11 @@ class OperationInstanceMetadata(ContreeModel):
         default=...,
         metadata={
             "description": (
-                "Maximum number of bytes to keep from stdout/stderr. Default is "
-                "`1048576` (1 MiB). The maximum value is `10485760` (10 MiB)."
+                "Maximum number of bytes to keep per stream (stdout, stderr, and "
+                "stdin) in the subprocess event log. Does not affect stdin delivery to "
+                "the child, which always receives the complete stream regardless of "
+                "this cap. Default is `1048576` (1 MiB). The maximum value is "
+                "`10485760` (10 MiB)."
             ),
             "example": 65535,
             "default": 1048576,

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/contree_client/operations.py

@@ -6,6 +6,7 @@ Generated by codegen from the OpenAPI spec - do not edit.
 from __future__ import annotations
 
 import json
+from collections.abc import Sequence
 from datetime import datetime
 from types import EllipsisType
 from typing import IO, Any, Literal
@@ -591,10 +592,10 @@ def parse_inspect_image_list(response: ResponseData) -> DirectoryList:
 
 def build_inspect_image_grep(
     image_uuid: str,
-    pattern: str,
+    pattern: str | Sequence[str],
     *,
-    path: str | None = None,
-    glob: str | None = None,
+    path: str | Sequence[str] | None = None,
+    glob: str | Sequence[str] | None = None,
     max_count: int | None = None,
     max_total: int | None = None,
     case: Literal["sensitive", "insensitive", "smart"] | None = None,
@@ -602,7 +603,7 @@ def build_inspect_image_grep(
     after: int | None = None,
 ) -> RequestSpec:
     """Build the request for `GET /inspect/{image_uuid}/grep`."""
-    query: dict[str, str] = {}
+    query: dict[str, str | Sequence[str]] = {}
     query["pattern"] = pattern
     if path is not None:
         query["path"] = path

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/contree_client/runtime.py

@@ -9,7 +9,7 @@ import logging
 import math
 import re
 import zlib
-from collections.abc import AsyncIterator, Iterable, Iterator
+from collections.abc import AsyncIterator, Iterable, Iterator, Mapping, Sequence
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from email.utils import parsedate_to_datetime
@@ -146,7 +146,7 @@ class RequestSpec:
 
     method: str
     path: str
-    query: dict[str, str] = field(default_factory=dict)
+    query: Mapping[str, str | Sequence[str]] = field(default_factory=dict)
     headers: dict[str, str] = field(default_factory=dict)
     body: bytes | IO[bytes] | None = None
     content_type: str | None = None
@@ -247,6 +247,15 @@ RETRY_DELAYS = (0.1, 0.2, 0.5, 1.0, 2.0, 5.0)
 # returning immediate empty streams does not spin the client
 TIGHT_LOOP_FLOOR = 0.5
 
+# the events route itself doesn't exist for this operation/server
+# (malformed request an older backend rejects, or a reverse proxy
+# that never forwards it) rather than merely being down: reconnecting
+# will never succeed, but the operation itself may still complete -
+# degrade to polling instead of failing the whole wait. 401/403 are
+# deliberately excluded: an auth/permission failure here likely means
+# the whole client is broken, not just this route, so it still raises
+EVENTS_UNAVAILABLE_STATUSES = frozenset({400, 404, 405, 406})
+
 
 def retry_generator(delays: tuple[float, ...] = RETRY_DELAYS) -> Iterator[float]:
     """An endless ladder of backoff delays.
@@ -370,8 +379,8 @@ def quote_path(value: str | int) -> str:
     return quote(str(value), safe="")
 
 
-def encode_query(query: dict[str, str]) -> str:
-    return urlencode(query, safe="/", quote_via=quote)
+def encode_query(query: Mapping[str, str | Sequence[str]]) -> str:
+    return urlencode(query, doseq=True, safe="/", quote_via=quote)
 
 
 def format_time_param(value: str | int | float | datetime) -> str:

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/contree_client/spec_info.py

@@ -2146,8 +2146,11 @@ Generated by codegen from the OpenAPI spec - do not edit.
         ClosableStreamRepr:
           type: object
           description: |
-            Stdin payload.  Unlike output streams it is never truncated;
-            instead it carries a `close` flag controlling the pipe's EOF.
+            Stdin payload.  Delivery to the child is always complete —
+            stdin is never truncated on its way to the process.  Only the
+            *recorded* `stdin` events in the subprocess event log are
+            capped by `truncate_output_at`, same as stdout/stderr.  This
+            schema also carries a `close` flag controlling the pipe's EOF.
           required:
             - value
           properties:
@@ -2251,8 +2254,11 @@ Generated by codegen from the OpenAPI spec - do not edit.
             truncate_output_at:
               type: integer
               description: |
-                Maximum number of bytes of stdout / stderr to keep.
-                Defaults to 1 MiB; capped at 10 MiB.
+                Maximum number of bytes to keep per stream (stdout,
+                stderr, and stdin) in the subprocess event log.  Does not
+                affect delivery to the child — stdin is always delivered
+                in full regardless of this cap.  Defaults to 1 MiB; capped
+                at 10 MiB.
               default: 1048576
               example: 65535
 
@@ -2361,7 +2367,10 @@ Generated by codegen from the OpenAPI spec - do not edit.
             truncate_output_at:
               type: integer
               description: >
-                Maximum number of bytes to keep from stdout/stderr.
+                Maximum number of bytes to keep per stream (stdout,
+                stderr, and stdin) in the subprocess event log.
+                Does not affect stdin delivery to the child, which always
+                receives the complete stream regardless of this cap.
                 Default is `1048576` (1 MiB).
                 The maximum value is `10485760` (10 MiB).
               example: 65535
@@ -3446,4 +3455,4 @@ DEFAULT_BASE_URL = "https://api.tokenfactory.nebius.com/sandboxes"
 
 # sha256 of the exact OpenAPI document this package was built from -
 # the build input provenance
-SPEC_SHA256 = "2bfd239341e6f61ccba1aafb39cef7b476d56f424156860a204f089d7d79b7bf"
+SPEC_SHA256 = "23d748a2918b1124b3072d54d17d8eb43aa00d0b969bc1fa718f34ac884ee887"

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "contree-client"
-version = "0.2.1.dev0"
+version = "0.2.2"
 description = "Python client for the Contree API, generated from the OpenAPI specification"
 readme = "README.md"
 requires-python = ">=3.10"

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/pyproject.toml.orig

@@ -6,7 +6,7 @@ build-backend = "uv_build"
 
 [project]
 name = "contree-client"
-version = "0.2.1.dev0"
+version = "0.2.2"
 description = "Python client for the Contree API, generated from the OpenAPI specification"
 readme = "README.md"
 requires-python = ">=3.10"

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/tests/stub_server.py

@@ -41,6 +41,8 @@ CLOSING_OPERATION_UUID = "00000000-0000-0000-0000-0000000c105e"
 DROPPING_OPERATION_UUID = "00000000-0000-0000-0000-00000000d40b"
 KEEPALIVE_OPERATION_UUID = "00000000-0000-0000-0000-0000000cee9a"
 RESET_OPERATION_UUID = "00000000-0000-0000-0000-000000000e5e"
+EVENTS_UNAVAILABLE_OPERATION_UUID = "00000000-0000-0000-0000-00000000eee0"
+EVENTS_UNAVAILABLE_STALLED_OPERATION_UUID = "00000000-0000-0000-0000-00000000eee1"
 SSE_HANG_SECONDS = 10.0
 STATUS_HANG_SECONDS = 2.0
 FILE_UUID = "a9165a5d-5c86-4bd8-8ee4-ae46c19cf45d"
@@ -409,6 +411,49 @@ def route(request: Captured, attempts: collections.Counter[str]) -> Reply:
             stream_chunks=chunks,
         )
 
+    if (
+        path == f"/v1/operations/{EVENTS_UNAVAILABLE_OPERATION_UUID}"
+        and method == "GET"
+    ):
+        # the operation itself progresses and finishes normally; only
+        # its /events route is missing
+        status = "EXECUTING" if attempt < 3 else "SUCCESS"
+        return json_reply(
+            200,
+            {
+                **OPERATION_RESPONSE,
+                "uuid": EVENTS_UNAVAILABLE_OPERATION_UUID,
+                "status": status,
+            },
+        )
+
+    if path == f"/v1/operations/{EVENTS_UNAVAILABLE_OPERATION_UUID}/events":
+        # no /events route at all for this operation (older backend,
+        # or a reverse proxy that doesn't forward it): reconnecting
+        # this exact request will never succeed, but the operation
+        # itself is healthy - the client must fall back to polling
+        # get_operation_status instead of failing the whole wait
+        return json_reply(404, {"error": "not found", "status": 404})
+
+    if (
+        path == f"/v1/operations/{EVENTS_UNAVAILABLE_STALLED_OPERATION_UUID}"
+        and method == "GET"
+    ):
+        # same missing-events situation, but the operation itself
+        # never finishes - the polling fallback must still honor the
+        # caller's deadline instead of looping forever
+        return json_reply(
+            200,
+            {
+                **OPERATION_RESPONSE,
+                "uuid": EVENTS_UNAVAILABLE_STALLED_OPERATION_UUID,
+                "status": "EXECUTING",
+            },
+        )
+
+    if path == f"/v1/operations/{EVENTS_UNAVAILABLE_STALLED_OPERATION_UUID}/events":
+        return json_reply(404, {"error": "not found", "status": 404})
+
     if (
         path == f"/v1/operations/{PAYLOAD_INTERRUPTION_OPERATION_UUID}"
         and method == "GET"

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/tests/test_operation_helpers.py

@@ -3,11 +3,14 @@
 from __future__ import annotations
 
 from collections.abc import Callable
+from types import ModuleType
 from typing import Any
 
 import pytest
 
 from tests.stub_server import (
+    EVENTS_UNAVAILABLE_OPERATION_UUID,
+    EVENTS_UNAVAILABLE_STALLED_OPERATION_UUID,
     EXECUTING_OPERATION_UUID,
     IMAGE_UUID,
     PENDING_OPERATION_UUID,
@@ -62,6 +65,52 @@ def test_follow_operation_events_reconnects(
     assert stream_requests[1].headers["last-event-id"] == "1"
 
 
+def test_wait_operation_falls_back_to_polling_when_events_missing(
+    invoke: Callable[..., Any], stub_server: StubServer
+) -> None:
+    # /events 404s outright (older backend, proxy that drops the
+    # route, ...); the operation itself still finishes
+    operation = invoke("wait_operation", EVENTS_UNAVAILABLE_OPERATION_UUID)
+
+    assert str(operation.status) == "SUCCESS"
+    events_path = f"/v1/operations/{EVENTS_UNAVAILABLE_OPERATION_UUID}/events"
+    events_requests = [c for c in stub_server.captured if c.path == events_path]
+    # a 404 means reconnecting will never work: touched exactly once
+    assert len(events_requests) == 1
+    status_path = f"/v1/operations/{EVENTS_UNAVAILABLE_OPERATION_UUID}"
+    status_requests = [c for c in stub_server.captured if c.path == status_path]
+    # polled until terminal, plus wait_operation's own final fetch
+    assert len(status_requests) >= 3
+
+
+def test_follow_operation_events_yields_completion_when_events_missing(
+    invoke: Callable[..., Any], stub_server: StubServer, models: ModuleType
+) -> None:
+    # there is no event log to relay, but the caller must still see a
+    # terminal completion event, not an iterator that silently ends
+    events = invoke(
+        "follow_operation_events", EVENTS_UNAVAILABLE_OPERATION_UUID, collect=True
+    )
+
+    assert len(events) == 1
+    assert events[0].type == "completion"
+    assert isinstance(events[0].data, models.EventDataCompletion)
+    assert str(events[0].data.status) == "SUCCESS"
+
+
+def test_wait_operation_polling_fallback_respects_timeout(
+    invoke: Callable[..., Any], stub_server: StubServer
+) -> None:
+    # events unavailable and the operation never finishes: the polling
+    # fallback must still honor the deadline instead of spinning forever
+    with pytest.raises(TimeoutError, match=EVENTS_UNAVAILABLE_STALLED_OPERATION_UUID):
+        invoke(
+            "wait_operation",
+            EVENTS_UNAVAILABLE_STALLED_OPERATION_UUID,
+            timeout=0.3,
+        )
+
+
 def test_resolve_image_tag_prefix(
     invoke: Callable[..., Any], stub_server: StubServer
 ) -> None:

{contree_client-0.2.1.dev0 → contree_client-0.2.2}/tests/test_runtime.py

@@ -26,6 +26,20 @@ def test_format_time_param(runtime: ModuleType) -> None:
     assert runtime.format_time_param("1h") == "1h"
 
 
+def test_encode_query_preserves_repeated_values(runtime: ModuleType) -> None:
+    assert (
+        runtime.encode_query(
+            {
+                "pattern": ["^root:", "^bin:"],
+                "path": ("/etc/passwd", "/etc/group"),
+                "case": "sensitive",
+            }
+        )
+        == "pattern=%5Eroot%3A&pattern=%5Ebin%3A"
+        "&path=/etc/passwd&path=/etc/group&case=sensitive"
+    )
+
+
 def test_json_object_rejects_array(
     runtime: ModuleType,
     exceptions: ModuleType,