ap-client 0.8.0.dev6__tar.gz → 0.8.1.dev1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/PKG-INFO +5 -4
  2. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/api.py +446 -13
  3. ap_client-0.8.1.dev1/ap_client/canonical_get.py +210 -0
  4. ap_client-0.8.1.dev1/ap_client/canonical_put.py +956 -0
  5. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/cli.py +494 -191
  6. ap_client-0.8.1.dev1/ap_client/cli_help.py +159 -0
  7. ap_client-0.8.1.dev1/ap_client/cluster_layout_fetcher.py +362 -0
  8. ap_client-0.8.1.dev1/ap_client/cluster_region_resolver.py +394 -0
  9. ap_client-0.8.1.dev1/ap_client/fs_commands.py +827 -0
  10. ap_client-0.8.1.dev1/ap_client/fs_storage.py +53 -0
  11. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/instance_commands.py +50 -36
  12. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/irepo_sdk.py +372 -0
  13. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/ossutil_io.py +48 -2
  14. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/profile_commands.py +317 -93
  15. ap_client-0.8.1.dev1/ap_client/replica_policy.py +114 -0
  16. ap_client-0.8.1.dev1/ap_client/shared_adapter.py +1476 -0
  17. ap_client-0.8.1.dev1/ap_client/shared_commands.py +1138 -0
  18. ap_client-0.8.1.dev1/ap_client/tool_manifest.py +184 -0
  19. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/waiter.py +3 -0
  20. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/pyproject.toml +5 -4
  21. ap_client-0.8.0.dev6/ap_client/fs_commands.py +0 -861
  22. ap_client-0.8.0.dev6/ap_client/fs_storage.py +0 -146
  23. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/__init__.py +0 -0
  24. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/akpool_commands.py +0 -0
  25. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/cli_submission_defaults.py +0 -0
  26. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/config.py +0 -0
  27. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/dataset_commands.py +0 -0
  28. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/dataset_name.py +0 -0
  29. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/dataset_register.py +0 -0
  30. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/dfs_commands.py +0 -0
  31. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/exporter.py +0 -0
  32. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/fs_transfer.py +0 -0
  33. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/instance_options.py +0 -0
  34. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/managed_ak.py +0 -0
  35. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/manifest_view.py +0 -0
  36. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/ossutil_hash.py +0 -0
  37. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/profile_cascade_all.py +0 -0
  38. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/profile_cascade_cli.py +0 -0
  39. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/profile_cascade_display.py +0 -0
  40. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/profile_cascade_state.py +0 -0
  41. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/profile_diagnostics.py +0 -0
  42. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/profile_display.py +0 -0
  43. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/profile_references.py +0 -0
  44. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/repo_read_guard.py +0 -0
  45. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/share_api.py +0 -0
  46. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/split_publish.py +0 -0
  47. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/submission_metadata.py +0 -0
  48. {ap_client-0.8.0.dev6 → ap_client-0.8.1.dev1}/ap_client/tbb.py +0 -0
@@ -1,18 +1,19 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: ap-client
3
- Version: 0.8.0.dev6
3
+ Version: 0.8.1.dev1
4
4
  Summary: Agent Platform API Client & CLI
5
5
  Requires-Python: >=3.10
6
+ Requires-Dist: click<8.2.0,>=8.1.8
6
7
  Requires-Dist: irepo-artifact==0.2.6
7
8
  Requires-Dist: pyyaml>=6.0
8
9
  Requires-Dist: requests>=2.28.0
9
10
  Requires-Dist: rich>=13.0.0
10
- Requires-Dist: typer>=0.9.0
11
+ Requires-Dist: typer<0.21.0,>=0.20.1
11
12
  Requires-Dist: websockets>=13.0
12
13
  Provides-Extra: all
13
- Requires-Dist: instance-repo[oss]<1.5.0,>=1.4.8.dev1; extra == 'all'
14
+ Requires-Dist: instance-repo[oss]<2.0.0,>=1.7.0; extra == 'all'
14
15
  Provides-Extra: dataset
15
- Requires-Dist: instance-repo[oss]<1.5.0,>=1.4.8.dev1; extra == 'dataset'
16
+ Requires-Dist: instance-repo[oss]<2.0.0,>=1.7.0; extra == 'dataset'
16
17
  Description-Content-Type: text/markdown
17
18
 
18
19
  A lightweight Python SDK and command line interface for Agent Platform. It provides helpers for configuring API access and managing templates, datasets, jobs, and groups.
@@ -5,7 +5,9 @@ import math
5
5
  import os
6
6
  import platform
7
7
  import re
8
+ import socket
8
9
  import sys
10
+ import threading
9
11
  import time
10
12
  import uuid
11
13
  from email.utils import parsedate_to_datetime
@@ -306,6 +308,263 @@ class PaginationProtocolError(RuntimeError):
306
308
  """The server stopped honoring a pagination protocol already in use."""
307
309
 
308
310
 
311
+ # Bounded canonical control-response helpers (CR 30865361 review P1 fixes).
312
+
313
+ # Upper bound for one canonical control response body (metadata JSONs are
314
+ # small; this only bounds memory and the byte-drip amortisation window).
315
+ _DEFAULT_CONTROL_BYTES = 8 * 1024 * 1024
316
+ _MAX_CONTROL_BYTES = 64 * 1024 * 1024
317
+
318
+
319
+ class CanonicalControlAPIError(APIError):
320
+ """Sanitized typed refusal for bounded canonical control requests.
321
+
322
+ Never holds a native response or raw cause; redirects are reported as
323
+ ``redirect`` only after allow_redirects=False already prevented any
324
+ credential from following the Location."""
325
+
326
+ def __init__(self, reason, *, status_code=None, biz_code=None):
327
+ self.reason = reason
328
+ detail = {"code": biz_code} if type(biz_code) is int else "canonical control request failed"
329
+ super().__init__(status_code, detail, None, None)
330
+
331
+
332
+ def _validate_control_bytes(limit: int) -> None:
333
+ if type(limit) is not int or not 1 <= limit <= _MAX_CONTROL_BYTES:
334
+ raise CanonicalControlAPIError("invalid_limit")
335
+
336
+
337
+ def _close_response_quietly(resp) -> None:
338
+ """Close a streamed response, tolerating already-closed objects."""
339
+ try:
340
+ resp.close()
341
+ except Exception:
342
+ pass
343
+
344
+
345
+ def _response_socket(resp) -> Optional[Any]:
346
+ """Best-effort extraction of the response's live socket (downgrade-safe).
347
+
348
+ urllib3 ``HTTPResponse._fp`` → http.client ``.fp`` (BufferedReader) →
349
+ ``.raw`` (SocketIO) → ``._sock``. Any missing/private-shift layer just
350
+ returns None — callers treat None as "no hard interruption available"
351
+ and rely on the in-loop deadline checks only.
352
+ """
353
+ try:
354
+ fp = getattr(resp, "raw", None)
355
+ fp = getattr(fp, "_fp", None)
356
+ if fp is None:
357
+ return None
358
+ buf = getattr(fp, "fp", None)
359
+ rawio = getattr(buf, "raw", None) if buf is not None else None
360
+ sock = getattr(rawio, "_sock", None) if rawio is not None else None
361
+ if sock is not None and callable(getattr(sock, "shutdown", None)):
362
+ return sock
363
+ except Exception:
364
+ pass
365
+ return None
366
+
367
+
368
+ class _DeadlineWatchdog:
369
+ """Force-interrupt a blocked streamed body read at the deadline.
370
+
371
+ ``requests``/``urllib3`` buffered reads block until the requested amount
372
+ (or EOF) arrives: with a Content-Length body dripping one byte per
373
+ interval, ``iter_content(chunk_size=64K)`` never returns mid-stream, so
374
+ in-loop deadline checks never run (review P1: 80ms budget exited at
375
+ ~300ms via drip). Same approach as the SDK transport's per-request
376
+ watchdog: an independent daemon timer shuts the live socket down at the
377
+ deadline; the blocked read then unblocks with a transport error, which
378
+ the callers classify against the actual clock.
379
+
380
+ Connection-reuse safety (review P2, two races):
381
+ 1. cancel/fire race: ``threading.Timer.cancel`` only prevents a callback
382
+ that has not *started*. Disarm happens under a lock in both
383
+ directions — the callback re-checks the flag — and ``__exit__``
384
+ joins the timer thread.
385
+ 2. release-before-exit race (the deeper one): urllib3 returns a
386
+ keep-alive connection to the pool as soon as ``iter_content`` drains
387
+ to EOF — BEFORE ``__exit__`` runs disarm/join. A later request can
388
+ borrow the connection in that window, and a stale timer firing then
389
+ kills an unrelated request. The callback therefore does NOT use the
390
+ socket captured at construction: at fire time it re-extracts the
391
+ socket from the response and shuts it down only when it is still the
392
+ SAME object — after EOF the response's file pointer is closed
393
+ (``_fp.fp = None``), extraction yields None, and the callback gives
394
+ up (the connection is no longer ours to interrupt). Construction
395
+ still keeps the socket purely as the identity reference.
396
+
397
+ No-socket fallback: if the layered private path is unavailable, the
398
+ watchdog stays inert and the in-loop checks remain the only guard.
399
+ """
400
+
401
+ def __init__(self, resp, deadline: Optional[float]):
402
+ self._resp = resp
403
+ self._sock = _response_socket(resp) if deadline is not None else None
404
+ self._deadline = deadline
405
+ self._timer: Optional[threading.Timer] = None
406
+ # Guards the disarmed flag AND serializes callback shutdown vs
407
+ # __exit__ disarm — the callback holds this lock while shutting the
408
+ # socket down, so once __exit__ completes the callback can never
409
+ # still be mid-shutdown.
410
+ self._lock = threading.Lock()
411
+ self._disarmed = False
412
+
413
+ def __enter__(self) -> "_DeadlineWatchdog":
414
+ sock = self._sock
415
+ if sock is not None:
416
+ delay = self._deadline - time.monotonic()
417
+ if delay > 0:
418
+ self._timer = threading.Timer(delay, self._fire)
419
+ self._timer.daemon = True
420
+ self._timer.start()
421
+ else:
422
+ self._fire()
423
+ return self
424
+
425
+ def __exit__(self, *exc_info) -> bool:
426
+ # Disarm BEFORE releasing anything: with the lock held, any in-flight
427
+ # callback has either finished its shutdown already (this read is
428
+ # being aborted anyway) or will re-check the flag and give up.
429
+ with self._lock:
430
+ self._disarmed = True
431
+ timer = self._timer
432
+ if timer is not None:
433
+ self._timer = None
434
+ timer.cancel()
435
+ # The timer thread may have passed its finished-event check and
436
+ # be running the callback right now (cancel is advisory there).
437
+ # Join it so the callback has fully exited — only then does the
438
+ # caller close the response and urllib3 release the connection
439
+ # back to the pool for reuse by later requests.
440
+ timer.join(timeout=5.0)
441
+ return False
442
+
443
+ def _fire(self) -> None:
444
+ # Runs on the timer thread (or synchronously from __enter__ when the
445
+ # budget is already spent). The lock + disarmed re-check closes the
446
+ # cancel race; the fresh re-extraction + identity check closes the
447
+ # release-before-exit race: after the stream drained to EOF urllib3
448
+ # has already returned the connection to the pool (the response's
449
+ # file pointer is closed), so the extraction yields None (or a
450
+ # different socket) and the stale fire gives up instead of killing
451
+ # whatever request borrowed the connection next.
452
+ with self._lock:
453
+ if self._disarmed:
454
+ return
455
+ current = _response_socket(self._resp)
456
+ if current is None or current is not self._sock:
457
+ return
458
+ try:
459
+ current.shutdown(socket.SHUT_RDWR)
460
+ except Exception:
461
+ pass
462
+
463
+
464
+ def _read_bounded_control_bytes(resp, limit: int = _DEFAULT_CONTROL_BYTES,
465
+ deadline: Optional[float] = None) -> bytes:
466
+ """Stream one bounded canonical control response via public requests APIs.
467
+
468
+ Content-Length pre-check plus streamed chunk reads keep memory at
469
+ O(cap+chunk) — a byte-drip response cannot grow unbounded. With a finite
470
+ ``deadline`` the read is ALSO hard-interruptible: a watchdog shuts the
471
+ response socket down at the deadline, so a slow drip cannot outlive the
472
+ budget even while ``iter_content`` is blocked mid-block (its buffered
473
+ read waits for the full chunk/EOF and would otherwise defer every
474
+ in-loop deadline check until the body finishes)."""
475
+ _validate_control_bytes(limit)
476
+ if deadline is not None and time.monotonic() >= deadline:
477
+ raise CanonicalControlAPIError("deadline")
478
+ length = resp.headers.get("Content-Length")
479
+ if isinstance(length, str) and length.isascii() and length.isdecimal():
480
+ digits, cap = length.lstrip('0') or '0', str(limit)
481
+ if len(digits) > len(cap) or (len(digits) == len(cap) and digits > cap):
482
+ raise CanonicalControlAPIError("response_limit", status_code=resp.status_code)
483
+ data = bytearray()
484
+ try:
485
+ with _DeadlineWatchdog(resp, deadline):
486
+ for block in resp.iter_content(chunk_size=min(65536, max(1, limit))):
487
+ if block:
488
+ if deadline is not None and time.monotonic() >= deadline:
489
+ # The stream is interrupted by the operation budget
490
+ # itself, not by body completion.
491
+ raise CanonicalControlAPIError("deadline")
492
+ if len(block) > limit - len(data):
493
+ raise CanonicalControlAPIError(
494
+ "response_limit", status_code=resp.status_code)
495
+ data.extend(block)
496
+ except CanonicalControlAPIError:
497
+ raise
498
+ except Exception:
499
+ # Hard interruption (watchdog shutdown) or transport error: classify
500
+ # against the actual clock — a spent budget is a deadline refusal,
501
+ # never a raw exception or a partial-body success.
502
+ if deadline is not None and time.monotonic() >= deadline:
503
+ raise CanonicalControlAPIError("deadline") from None
504
+ raise
505
+ if deadline is not None and time.monotonic() >= deadline:
506
+ # Body completed but the budget is spent: refuse the late success.
507
+ raise CanonicalControlAPIError("deadline")
508
+ return bytes(data)
509
+
510
+
511
+ def _bounded_response_prefix(resp, limit: int = _DEFAULT_CONTROL_BYTES,
512
+ deadline: Optional[float] = None) -> bytes:
513
+ """Read one bounded first block of an error body for typed classification.
514
+
515
+ Oversized bodies contribute only this bounded prefix; their real status
516
+ stays reportable. With a finite ``deadline`` the same watchdog
517
+ hard-interrupts a blocked first-block read; a deadline reached mid-prefix
518
+ (or a transport interruption with the budget spent) is reported as
519
+ ``deadline`` — never a late ``http_error`` classification of an unread
520
+ body."""
521
+ try:
522
+ if deadline is not None and time.monotonic() >= deadline:
523
+ raise CanonicalControlAPIError("deadline")
524
+ with _DeadlineWatchdog(resp, deadline):
525
+ for block in resp.iter_content(chunk_size=min(65536, max(1, limit))):
526
+ if block:
527
+ if deadline is not None and time.monotonic() >= deadline:
528
+ raise CanonicalControlAPIError("deadline")
529
+ return bytes(block[:limit])
530
+ except CanonicalControlAPIError:
531
+ raise
532
+ except Exception:
533
+ if deadline is not None and time.monotonic() >= deadline:
534
+ # The read was interrupted (watchdog shutdown or read timeout)
535
+ # with the budget already spent: report the deadline, not a
536
+ # post-hoc classification of an unread error body.
537
+ raise CanonicalControlAPIError("deadline") from None
538
+ return b""
539
+ return b""
540
+
541
+
542
+ def _bounded_error_biz_code(prefix: bytes) -> Optional[int]:
543
+ """Typed numeric classification only; never message/data.
544
+
545
+ Decodes the dual envelope (bare ``{code,message,data}`` or FastAPI
546
+ ``{detail}``) from a bounded prefix so raw error text is never
547
+ forwarded; only the typed numeric family survives."""
548
+ parsed = None
549
+ if prefix:
550
+ try:
551
+ parsed = json.loads(prefix.decode("utf-8", errors="replace"))
552
+ except (ValueError, UnicodeError, RecursionError):
553
+ pass
554
+ detail = parsed.get("detail", parsed) if isinstance(parsed, dict) else None
555
+ if isinstance(detail, str):
556
+ decoded = None
557
+ try:
558
+ decoded = json.loads(detail)
559
+ except (ValueError, RecursionError):
560
+ pass
561
+ detail = decoded
562
+ code = detail.get("code") if isinstance(detail, dict) else None
563
+ if type(code) is bool or not isinstance(code, int):
564
+ code = None
565
+ return code
566
+
567
+
309
568
  def _ensure_next_token_honored(response: dict, *, next_token: Optional[str], endpoint: str) -> None:
310
569
  # An old server ignores the unknown next_token param and answers with its
311
570
  # default first page, so a `response.get("next_token")` loop would silently
@@ -441,8 +700,17 @@ class APIClient:
441
700
  timeout: TimeoutType = None,
442
701
  deadline: Optional[float] = None,
443
702
  _return_response: bool = False,
703
+ _single_attempt: bool = False,
704
+ _bounded: bool = False,
444
705
  ) -> Any:
445
- """Send an HTTP request with X-Request-ID and optional verbose logging."""
706
+ """Send through the normal authenticated HTTP channel.
707
+
708
+ ``_bounded`` (canonical adapter control requests) opts this single
709
+ request into the bounded canonical response projection: redirects
710
+ refused (auth headers never follow a cross-origin Location), a
711
+ finite timeout owns ONE deadline across retries, streamed bounded
712
+ reads (O(cap+chunk) memory), and late successes refused.
713
+ """
446
714
  self._require_cluster_config()
447
715
  return self._request_http(
448
716
  method,
@@ -452,6 +720,8 @@ class APIClient:
452
720
  timeout=timeout,
453
721
  deadline=deadline,
454
722
  _return_response=_return_response,
723
+ _single_attempt=_single_attempt,
724
+ _bounded=_bounded,
455
725
  )
456
726
 
457
727
  def _request_http(
@@ -464,6 +734,8 @@ class APIClient:
464
734
  timeout: TimeoutType = None,
465
735
  deadline: Optional[float] = None,
466
736
  _return_response: bool = False,
737
+ _single_attempt: bool = False,
738
+ _bounded: bool = False,
467
739
  ) -> Any:
468
740
  """One retry budget shared by cluster and central requests.
469
741
 
@@ -474,8 +746,14 @@ class APIClient:
474
746
  timeout = _default_timeout()
475
747
  else:
476
748
  timeout = _normalize_explicit_timeout(timeout)
749
+ # Bounded canonical projection (P1 fix): a finite per-request duration
750
+ # owns ONE deadline across this request's retries, never per attempt,
751
+ # so a slow byte-drip response cannot outlive its budget.
752
+ if _bounded and deadline is None and isinstance(timeout, (int, float)) \
753
+ and not isinstance(timeout, bool) and math.isfinite(timeout) and timeout >= 0:
754
+ deadline = time.monotonic() + timeout
477
755
  verbose = self.config.verbose
478
- max_attempts = max(1, self.config.http_max_attempts)
756
+ max_attempts = 1 if _single_attempt else max(1, self.config.http_max_attempts)
479
757
  max_wait = self.config.http_max_wait
480
758
  read_only = method.upper() in _RETRYABLE_METHODS
481
759
  recovery_deadline = None
@@ -506,16 +784,66 @@ class APIClient:
506
784
  max_attempts=max_attempts,
507
785
  )
508
786
  start = time.perf_counter()
787
+ resp = None
509
788
  try:
789
+ # A single-attempt mutation must also stop on redirects.
790
+ # Read the body separately so a truncated error still keeps its HTTP status.
791
+ # Bounded canonical requests always refuse redirects (auth
792
+ # headers must never follow a cross-origin Location) and read
793
+ # the body streamed-bounded instead of unbounded .content.
794
+ if _single_attempt or _bounded:
795
+ options = {"allow_redirects": False, "stream": True}
796
+ else:
797
+ options = {}
798
+ if _bounded:
799
+ # Watchdog pool isolation (review P2, final round): the
800
+ # deadline watchdog interrupts a blocked read by shutting
801
+ # the response's socket down. A keep-alive connection is
802
+ # returned to the pool as soon as iter_content drains to
803
+ # EOF — BEFORE the watchdog context exits — so any
804
+ # "check ownership then shutdown" sequence retains a
805
+ # check-then-act window in which the connection is
806
+ # borrowed by the NEXT request and killed by the stale
807
+ # fire. Closing the connection for this one request
808
+ # (``Connection: close``) removes the pooled connection
809
+ # from the equation entirely: the socket is never
810
+ # released back to the pool, a late fire hits an
811
+ # already-closed socket (OSError, swallowed), and later
812
+ # requests always get a fresh connection. Bounded control
813
+ # requests are short-lived metadata calls; the extra
814
+ # connection setup stays inside the same finite budget.
815
+ request_headers = {**headers, "Connection": "close"}
816
+ else:
817
+ request_headers = headers
510
818
  resp = self.session.request(
511
819
  method,
512
820
  url,
513
821
  params=params,
514
822
  json=json_body,
515
- headers=headers,
823
+ headers=request_headers,
516
824
  timeout=attempt_timeout,
825
+ **options,
517
826
  )
827
+ if _single_attempt and not _bounded:
828
+ # Legacy single-attempt semantics: read the body so a
829
+ # truncated error keeps its status. The bounded projection
830
+ # reads the body itself (streamed, bounded).
831
+ _ = resp.content
518
832
  except requests.RequestException as exc:
833
+ if _bounded:
834
+ # Bounded canonical projection: a network failure during a
835
+ # streamed bounded read is a typed refusal, not a retry of
836
+ # an unbounded request.
837
+ resp_is_error = resp is not None and not 200 <= resp.status_code < 300
838
+ if resp_is_error:
839
+ resp.close()
840
+ reason = "deadline" if (deadline is not None and time.monotonic() >= deadline) else "network"
841
+ raise CanonicalControlAPIError(reason) from None
842
+ if _single_attempt and resp is not None:
843
+ status = resp.status_code
844
+ resp.close()
845
+ if not 200 <= status < 300:
846
+ raise APIError(status, "Incomplete HTTP error response", request_id, resp) from None
519
847
  if deadline is not None:
520
848
  _manifest_budget_remaining(deadline)
521
849
  duration_ms = (time.perf_counter() - start) * 1000
@@ -546,7 +874,74 @@ class APIClient:
546
874
  duration_ms = (time.perf_counter() - start) * 1000
547
875
  if verbose:
548
876
  self._log_response(method, url, request_id, resp, duration_ms)
549
- if not resp.ok:
877
+ if _bounded:
878
+ # Bounded canonical projection: sanitize every exit — refusals
879
+ # never carry a cause; redirects are refused before any auth
880
+ # header could follow the Location; the body is read streamed
881
+ # and bounded, and a late success (budget exhausted mid-read)
882
+ # is refused.
883
+ try:
884
+ if deadline is not None and time.monotonic() >= deadline:
885
+ raise CanonicalControlAPIError("deadline")
886
+ if _return_response:
887
+ raise CanonicalControlAPIError("invalid_request")
888
+ if 300 <= resp.status_code < 400:
889
+ # Request had allow_redirects=False: the redirect was
890
+ # NOT followed — the Location was never requested and
891
+ # auth headers were never sent there. Refuse.
892
+ raise CanonicalControlAPIError("redirect", status_code=resp.status_code)
893
+ if not 200 <= resp.status_code < 300:
894
+ if read_only and attempt < max_attempts and _is_retryable_status(resp.status_code):
895
+ delay = _retry_delay(attempt, resp, max_wait=max_wait)
896
+ if not math.isfinite(delay):
897
+ delay = _retry_delay(attempt)
898
+ if deadline is not None:
899
+ remaining = deadline - time.monotonic()
900
+ if remaining <= 0:
901
+ raise CanonicalControlAPIError("deadline")
902
+ delay = min(delay, remaining)
903
+ resp.close()
904
+ if deadline is not None:
905
+ _deadline_sleep(delay, deadline)
906
+ else:
907
+ time.sleep(delay)
908
+ continue
909
+ if deadline is not None and time.monotonic() >= deadline:
910
+ # The error body would be classified only after a
911
+ # bounded read that the budget can no longer fund:
912
+ # report the deadline, never a late http_error.
913
+ raise CanonicalControlAPIError("deadline")
914
+ prefix = _bounded_response_prefix(
915
+ resp, _DEFAULT_CONTROL_BYTES, deadline=deadline)
916
+ code = _bounded_error_biz_code(prefix)
917
+ raise CanonicalControlAPIError(
918
+ "http_error", status_code=resp.status_code, biz_code=code)
919
+ data = _read_bounded_control_bytes(
920
+ resp, _DEFAULT_CONTROL_BYTES, deadline=deadline)
921
+ if not data:
922
+ resp.close()
923
+ return None
924
+ refusal = None
925
+ try:
926
+ parsed = data.decode("utf-8", errors="strict")
927
+ except UnicodeError:
928
+ refusal = "invalid_utf8"
929
+ if refusal is None:
930
+ try:
931
+ result = json.loads(parsed)
932
+ except (ValueError, RecursionError):
933
+ refusal = "invalid_json"
934
+ if refusal is not None:
935
+ raise CanonicalControlAPIError(
936
+ refusal, status_code=resp.status_code)
937
+ if deadline is not None and time.monotonic() >= deadline:
938
+ # Refuse a late success; the budget is already spent.
939
+ raise CanonicalControlAPIError("deadline")
940
+ resp.close()
941
+ return result
942
+ finally:
943
+ _close_response_quietly(resp)
944
+ if not resp.ok or (_single_attempt and not 200 <= resp.status_code < 300):
550
945
  pop_rejected = _is_pop_rejection(resp)
551
946
  if pop_rejected and recovery_deadline is None:
552
947
  recovery_deadline = time.monotonic() + self.config.http_retry_window
@@ -611,6 +1006,11 @@ class APIClient:
611
1006
  raise APIError(resp.status_code, detail, request_id, resp) from exc
612
1007
  raise RuntimeError("unreachable retry state")
613
1008
 
1009
+ def _max_attempts_for(self, method: str) -> int:
1010
+ if method.upper() not in _RETRYABLE_METHODS:
1011
+ return 1
1012
+ return max(1, self.config.http_max_attempts)
1013
+
614
1014
  def _require_cluster_config(self) -> None:
615
1015
  if has_cluster_header(self.config.headers):
616
1016
  return
@@ -1220,6 +1620,7 @@ class APIClient:
1220
1620
  transparency: Optional[Literal["whitebox", "blackbox"]] = None,
1221
1621
  idempotency_key: Optional[str] = None,
1222
1622
  group_concurrency_policy: Optional[dict] = None,
1623
+ visibility: Optional[Literal["queue", "private"]] = None,
1223
1624
  metrics_retry_policy: Optional[dict] = None,
1224
1625
  ) -> dict:
1225
1626
  """Create a group with optional scheduling defaults for its Jobs.
@@ -1228,6 +1629,8 @@ class APIClient:
1228
1629
  """
1229
1630
  if priority is not None and priority not in {"high", "medium"}:
1230
1631
  raise ValueError("priority must be one of high/medium")
1632
+ if visibility is not None and visibility not in {"queue", "private"}:
1633
+ raise ValueError("visibility must be queue or private")
1231
1634
  if transparency is not None and transparency not in {"whitebox", "blackbox"}:
1232
1635
  raise ValueError("transparency must be whitebox or blackbox")
1233
1636
  if transparency == "blackbox" and not idempotency_key:
@@ -1240,6 +1643,8 @@ class APIClient:
1240
1643
  raise ValueError("ak_ids entries must be nonempty strings")
1241
1644
  references = list(dict.fromkeys(references))
1242
1645
  body: dict = {}
1646
+ if visibility is not None:
1647
+ body["visibility"] = visibility
1243
1648
  if metrics_retry_policy is not None:
1244
1649
  body["metrics_retry_policy"] = metrics_retry_policy
1245
1650
  if transparency is not None:
@@ -1370,11 +1775,13 @@ class APIClient:
1370
1775
  instance_range: Optional[str] = None,
1371
1776
  profile: Optional[str] = None,
1372
1777
  transparency: Optional[Literal["whitebox", "blackbox"]] = None,
1778
+ visibility: Optional[Literal["queue", "private"]] = None,
1373
1779
  metrics_retry_policy: Optional[dict] = None,
1374
1780
  ) -> dict:
1375
1781
  """Create a job."""
1376
1782
  body = self.build_create_job_body(
1377
1783
  transparency=transparency,
1784
+ visibility=visibility,
1378
1785
  template=template,
1379
1786
  params=params,
1380
1787
  params_list=params_list,
@@ -1488,9 +1895,12 @@ class APIClient:
1488
1895
  instance_range: Optional[str] = None,
1489
1896
  profile: Optional[str] = None,
1490
1897
  transparency: Optional[Literal["whitebox", "blackbox"]] = None,
1898
+ visibility: Optional[Literal["queue", "private"]] = None,
1491
1899
  metrics_retry_policy: Optional[dict] = None,
1492
1900
  ) -> dict:
1493
1901
  """Build the /jobs request body for job creation."""
1902
+ if visibility is not None and visibility not in {"queue", "private"}:
1903
+ raise ValueError("visibility must be queue or private")
1494
1904
  if transparency is not None and transparency not in {"whitebox", "blackbox"}:
1495
1905
  raise ValueError("transparency must be whitebox or blackbox")
1496
1906
  if profile is not None and (profile_id is not None or profile_version is not None):
@@ -1619,6 +2029,8 @@ class APIClient:
1619
2029
  if experiment is not None:
1620
2030
  body["experiment"] = experiment
1621
2031
 
2032
+ if visibility is not None:
2033
+ body["visibility"] = visibility
1622
2034
  if transparency is not None:
1623
2035
  body["transparency"] = transparency
1624
2036
  return body
@@ -1687,7 +2099,7 @@ class APIClient:
1687
2099
  upstream_job_id: Optional[str] = None,
1688
2100
  next_token: Optional[str] = None,
1689
2101
  pagination: Optional[str] = None,
1690
- include_total: bool = True,
2102
+ include_total: bool = False,
1691
2103
  ak_id: Optional[str] = None,
1692
2104
  ) -> dict:
1693
2105
  """List jobs."""
@@ -1753,8 +2165,7 @@ class APIClient:
1753
2165
  params["next_token"] = next_token
1754
2166
  if pagination:
1755
2167
  params["pagination"] = pagination
1756
- if not include_total:
1757
- params["include_total"] = False
2168
+ params["include_total"] = include_total
1758
2169
  response = self._get("/jobs", params=params)
1759
2170
  _ensure_next_token_honored(response, next_token=next_token, endpoint="/jobs")
1760
2171
  return response
@@ -1936,10 +2347,11 @@ class APIClient:
1936
2347
  upstream_platform: Optional[str] = None,
1937
2348
  upstream_job_id: Optional[str] = None,
1938
2349
  ak_id: Optional[str] = None,
2350
+ include_total: bool = False,
1939
2351
  ) -> dict:
1940
- """List groups."""
2352
+ """List groups. Exact totals are opt-in and subject to the server query budget."""
1941
2353
  validate_ak_id(ak_id)
1942
- params: dict = {"skip": skip, "limit": limit}
2354
+ params: dict = {"skip": skip, "limit": limit, "include_total": include_total}
1943
2355
  if ak_id is not None:
1944
2356
  params["ak_id"] = ak_id
1945
2357
  if name is not None:
@@ -2001,7 +2413,7 @@ class APIClient:
2001
2413
  upstream_job_id: Optional[str] = None,
2002
2414
  next_token: Optional[str] = None,
2003
2415
  pagination: Optional[str] = None,
2004
- include_total: bool = True,
2416
+ include_total: bool = False,
2005
2417
  ) -> dict:
2006
2418
  """List jobs in a group."""
2007
2419
  params: dict = {"skip": skip, "limit": limit}
@@ -2029,8 +2441,7 @@ class APIClient:
2029
2441
  params["next_token"] = next_token
2030
2442
  if pagination:
2031
2443
  params["pagination"] = pagination
2032
- if not include_total:
2033
- params["include_total"] = False
2444
+ params["include_total"] = include_total
2034
2445
  endpoint = f"/groups/{quote(group_id)}/jobs"
2035
2446
  response = self._get(endpoint, params=params)
2036
2447
  _ensure_next_token_honored(response, next_token=next_token, endpoint=endpoint)
@@ -3662,12 +4073,34 @@ def _redact_url_query_secrets(value: str) -> str:
3662
4073
 
3663
4074
 
3664
4075
  def _response_error_detail(resp: requests.Response) -> Any:
4076
+ """错误响应体 → detail(兼容两代服务端错误形态,G2 修复)。
4077
+
4078
+ * FastAPI ``{"detail": <str|dict>}``:保持旧语义——detail 键优先
4079
+ (dict 时**整个内层 dict** 作为 detail 返回,不只是取 message);
4080
+ * Go/Gin 裸信封 ``{code, message, data}``(apiserver
4081
+ ``pkg/api/response/response.go writeErrorData``):**整个响应 dict**
4082
+ 作为 detail 返回——9404x 数字 code 与 ``data``(error_code/
4083
+ apply_url 等结构化负载)不再被降级成 message 字符串丢失;
4084
+ * 旧 ``{"message": ...}``(无 detail)形态:保持旧语义取 message
4085
+ 字符串(detail/message 缺省回退 resp.text)。
4086
+
4087
+ detail 消费方(如 shared_adapter._decode_api_error)按"dict 即结构化
4088
+ 错误体"自行解 code/data;str detail 继续支持(旧展示路径不变)。
4089
+ """
3665
4090
  try:
3666
4091
  err_data = resp.json()
3667
4092
  except Exception:
3668
4093
  return resp.text
3669
4094
  if isinstance(err_data, dict):
3670
- return err_data.get("detail", err_data.get("message", resp.text))
4095
+ if "detail" in err_data:
4096
+ inner = err_data["detail"]
4097
+ if isinstance(inner, dict):
4098
+ return inner # FastAPI detail=dict:内层即结构化错误体
4099
+ return inner # detail=str:旧语义
4100
+ if "code" in err_data:
4101
+ # Go 裸信封 {code, message, data}:保留完整结构化错误体
4102
+ return err_data
4103
+ return err_data.get("message", resp.text)
3671
4104
  return err_data
3672
4105
 
3673
4106