ap-client 0.7.1.dev7__py3-none-any.whl → 0.7.2.dev2__py3-none-any.whl

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.
ap_client/api.py CHANGED
@@ -268,6 +268,9 @@ class APIError(Exception):
268
268
  self.request_id = request_id
269
269
  self.response = response
270
270
  self.retry_stop_reason = retry_stop_reason
271
+ self.response_request_id = (
272
+ response.headers.get("X-Request-ID") if response is not None else None
273
+ )
271
274
  self.pop_request_id = (
272
275
  response.headers.get("x-acs-request-id") if response is not None else None
273
276
  )
@@ -275,10 +278,8 @@ class APIError(Exception):
275
278
 
276
279
  def __str__(self) -> str:
277
280
  message = self._build_message()
278
- if self.retry_stop_reason:
279
- message += f" (retry_stop_reason={self.retry_stop_reason})"
280
- if self.pop_request_id:
281
- message += f" (pop_request_id={self.pop_request_id})"
281
+ for diagnostic in format_api_error_diagnostics(self):
282
+ message += f" ({diagnostic})"
282
283
  return message
283
284
 
284
285
  def _build_message(self) -> str:
@@ -287,10 +288,119 @@ class APIError(Exception):
287
288
  return f"API Error {self.status_code}: {self.detail} (request_id={self.request_id})"
288
289
 
289
290
 
291
+ def format_api_error_diagnostics(exc: APIError, *, separator: str = "=") -> list[str]:
292
+ """Render response and retry diagnostics without repeating the local request ID."""
293
+ diagnostics = []
294
+ seen = {exc.request_id}
295
+ for name in ("response_request_id", "pop_request_id"):
296
+ value = getattr(exc, name)
297
+ if value and value not in seen:
298
+ seen.add(value)
299
+ diagnostics.append(f"{name}{separator}{value}")
300
+ if exc.retry_stop_reason:
301
+ diagnostics.append(f"retry_stop_reason{separator}{exc.retry_stop_reason}")
302
+ return diagnostics
303
+
304
+
290
305
  class PaginationProtocolError(RuntimeError):
291
306
  """The server stopped honoring a pagination protocol already in use."""
292
307
 
293
308
 
309
+ # Bounded canonical control-response helpers (CR 30865361 review P1 fixes).
310
+
311
+ # Upper bound for one canonical control response body (metadata JSONs are
312
+ # small; this only bounds memory and the byte-drip amortisation window).
313
+ _DEFAULT_CONTROL_BYTES = 8 * 1024 * 1024
314
+ _MAX_CONTROL_BYTES = 64 * 1024 * 1024
315
+
316
+
317
+ class CanonicalControlAPIError(APIError):
318
+ """Sanitized typed refusal for bounded canonical control requests.
319
+
320
+ Never holds a native response or raw cause; redirects are reported as
321
+ ``redirect`` only after allow_redirects=False already prevented any
322
+ credential from following the Location."""
323
+
324
+ def __init__(self, reason, *, status_code=None, biz_code=None):
325
+ self.reason = reason
326
+ detail = {"code": biz_code} if type(biz_code) is int else "canonical control request failed"
327
+ super().__init__(status_code, detail, None, None)
328
+
329
+
330
+ def _validate_control_bytes(limit: int) -> None:
331
+ if type(limit) is not int or not 1 <= limit <= _MAX_CONTROL_BYTES:
332
+ raise CanonicalControlAPIError("invalid_limit")
333
+
334
+
335
+ def _close_response_quietly(resp) -> None:
336
+ """Close a streamed response, tolerating already-closed objects."""
337
+ try:
338
+ resp.close()
339
+ except Exception:
340
+ pass
341
+
342
+
343
+ def _read_bounded_control_bytes(resp, limit: int = _DEFAULT_CONTROL_BYTES) -> bytes:
344
+ """Stream one bounded canonical control response via public requests APIs.
345
+
346
+ Content-Length pre-check plus streamed chunk reads keep memory at
347
+ O(cap+chunk) — a byte-drip response cannot grow unbounded, and the
348
+ per-attempt HTTP timeout bounds each read syscall."""
349
+ _validate_control_bytes(limit)
350
+ length = resp.headers.get("Content-Length")
351
+ if isinstance(length, str) and length.isascii() and length.isdecimal():
352
+ digits, cap = length.lstrip('0') or '0', str(limit)
353
+ if len(digits) > len(cap) or (len(digits) == len(cap) and digits > cap):
354
+ raise CanonicalControlAPIError("response_limit", status_code=resp.status_code)
355
+ data = bytearray()
356
+ for block in resp.iter_content(chunk_size=min(65536, max(1, limit))):
357
+ if block:
358
+ if len(block) > limit - len(data):
359
+ raise CanonicalControlAPIError("response_limit", status_code=resp.status_code)
360
+ data.extend(block)
361
+ return bytes(data)
362
+
363
+
364
+ def _bounded_response_prefix(resp, limit: int = _DEFAULT_CONTROL_BYTES) -> bytes:
365
+ """Read one bounded first block of an error body for typed classification.
366
+
367
+ Oversized bodies contribute only this bounded prefix; their real status
368
+ stays reportable."""
369
+ try:
370
+ for block in resp.iter_content(chunk_size=min(65536, max(1, limit))):
371
+ if block:
372
+ return bytes(block[:limit])
373
+ except Exception:
374
+ pass
375
+ return b""
376
+
377
+
378
+ def _bounded_error_biz_code(prefix: bytes) -> Optional[int]:
379
+ """Typed numeric classification only; never message/data.
380
+
381
+ Decodes the dual envelope (bare ``{code,message,data}`` or FastAPI
382
+ ``{detail}``) from a bounded prefix so raw error text is never
383
+ forwarded; only the typed numeric family survives."""
384
+ parsed = None
385
+ if prefix:
386
+ try:
387
+ parsed = json.loads(prefix.decode("utf-8", errors="replace"))
388
+ except (ValueError, UnicodeError, RecursionError):
389
+ pass
390
+ detail = parsed.get("detail", parsed) if isinstance(parsed, dict) else None
391
+ if isinstance(detail, str):
392
+ decoded = None
393
+ try:
394
+ decoded = json.loads(detail)
395
+ except (ValueError, RecursionError):
396
+ pass
397
+ detail = decoded
398
+ code = detail.get("code") if isinstance(detail, dict) else None
399
+ if type(code) is bool or not isinstance(code, int):
400
+ code = None
401
+ return code
402
+
403
+
294
404
  def _ensure_next_token_honored(response: dict, *, next_token: Optional[str], endpoint: str) -> None:
295
405
  # An old server ignores the unknown next_token param and answers with its
296
406
  # default first page, so a `response.get("next_token")` loop would silently
@@ -426,8 +536,17 @@ class APIClient:
426
536
  timeout: TimeoutType = None,
427
537
  deadline: Optional[float] = None,
428
538
  _return_response: bool = False,
539
+ _single_attempt: bool = False,
540
+ _bounded: bool = False,
429
541
  ) -> Any:
430
- """Send through the normal authenticated HTTP channel."""
542
+ """Send through the normal authenticated HTTP channel.
543
+
544
+ ``_bounded`` (canonical adapter control requests) opts this single
545
+ request into the bounded canonical response projection: redirects
546
+ refused (auth headers never follow a cross-origin Location), a
547
+ finite timeout owns ONE deadline across retries, streamed bounded
548
+ reads (O(cap+chunk) memory), and late successes refused.
549
+ """
431
550
  self._require_cluster_config()
432
551
  return self._request_http(
433
552
  method,
@@ -437,6 +556,8 @@ class APIClient:
437
556
  timeout=timeout,
438
557
  deadline=deadline,
439
558
  _return_response=_return_response,
559
+ _single_attempt=_single_attempt,
560
+ _bounded=_bounded,
440
561
  )
441
562
 
442
563
  def _request_http(
@@ -449,6 +570,8 @@ class APIClient:
449
570
  timeout: TimeoutType = None,
450
571
  deadline: Optional[float] = None,
451
572
  _return_response: bool = False,
573
+ _single_attempt: bool = False,
574
+ _bounded: bool = False,
452
575
  ) -> Any:
453
576
  """One retry budget shared by cluster and central requests.
454
577
 
@@ -459,8 +582,14 @@ class APIClient:
459
582
  timeout = _default_timeout()
460
583
  else:
461
584
  timeout = _normalize_explicit_timeout(timeout)
585
+ # Bounded canonical projection (P1 fix): a finite per-request duration
586
+ # owns ONE deadline across this request's retries, never per attempt,
587
+ # so a slow byte-drip response cannot outlive its budget.
588
+ if _bounded and deadline is None and isinstance(timeout, (int, float)) \
589
+ and not isinstance(timeout, bool) and math.isfinite(timeout) and timeout >= 0:
590
+ deadline = time.monotonic() + timeout
462
591
  verbose = self.config.verbose
463
- max_attempts = max(1, self.config.http_max_attempts)
592
+ max_attempts = 1 if _single_attempt else max(1, self.config.http_max_attempts)
464
593
  max_wait = self.config.http_max_wait
465
594
  read_only = method.upper() in _RETRYABLE_METHODS
466
595
  recovery_deadline = None
@@ -491,7 +620,17 @@ class APIClient:
491
620
  max_attempts=max_attempts,
492
621
  )
493
622
  start = time.perf_counter()
623
+ resp = None
494
624
  try:
625
+ # A single-attempt mutation must also stop on redirects.
626
+ # Read the body separately so a truncated error still keeps its HTTP status.
627
+ # Bounded canonical requests always refuse redirects (auth
628
+ # headers must never follow a cross-origin Location) and read
629
+ # the body streamed-bounded instead of unbounded .content.
630
+ if _single_attempt or _bounded:
631
+ options = {"allow_redirects": False, "stream": True}
632
+ else:
633
+ options = {}
495
634
  resp = self.session.request(
496
635
  method,
497
636
  url,
@@ -499,8 +638,28 @@ class APIClient:
499
638
  json=json_body,
500
639
  headers=headers,
501
640
  timeout=attempt_timeout,
641
+ **options,
502
642
  )
643
+ if _single_attempt and not _bounded:
644
+ # Legacy single-attempt semantics: read the body so a
645
+ # truncated error keeps its status. The bounded projection
646
+ # reads the body itself (streamed, bounded).
647
+ _ = resp.content
503
648
  except requests.RequestException as exc:
649
+ if _bounded:
650
+ # Bounded canonical projection: a network failure during a
651
+ # streamed bounded read is a typed refusal, not a retry of
652
+ # an unbounded request.
653
+ resp_is_error = resp is not None and not 200 <= resp.status_code < 300
654
+ if resp_is_error:
655
+ resp.close()
656
+ reason = "deadline" if (deadline is not None and time.monotonic() >= deadline) else "network"
657
+ raise CanonicalControlAPIError(reason) from None
658
+ if _single_attempt and resp is not None:
659
+ status = resp.status_code
660
+ resp.close()
661
+ if not 200 <= status < 300:
662
+ raise APIError(status, "Incomplete HTTP error response", request_id, resp) from None
504
663
  if deadline is not None:
505
664
  _manifest_budget_remaining(deadline)
506
665
  duration_ms = (time.perf_counter() - start) * 1000
@@ -531,7 +690,67 @@ class APIClient:
531
690
  duration_ms = (time.perf_counter() - start) * 1000
532
691
  if verbose:
533
692
  self._log_response(method, url, request_id, resp, duration_ms)
534
- if not resp.ok:
693
+ if _bounded:
694
+ # Bounded canonical projection: sanitize every exit — refusals
695
+ # never carry a cause; redirects are refused before any auth
696
+ # header could follow the Location; the body is read streamed
697
+ # and bounded, and a late success (budget exhausted mid-read)
698
+ # is refused.
699
+ try:
700
+ if deadline is not None and time.monotonic() >= deadline:
701
+ raise CanonicalControlAPIError("deadline")
702
+ if _return_response:
703
+ raise CanonicalControlAPIError("invalid_request")
704
+ if 300 <= resp.status_code < 400:
705
+ # Request had allow_redirects=False: the redirect was
706
+ # NOT followed — the Location was never requested and
707
+ # auth headers were never sent there. Refuse.
708
+ raise CanonicalControlAPIError("redirect", status_code=resp.status_code)
709
+ if not 200 <= resp.status_code < 300:
710
+ if read_only and attempt < max_attempts and _is_retryable_status(resp.status_code):
711
+ delay = _retry_delay(attempt, resp, max_wait=max_wait)
712
+ if not math.isfinite(delay):
713
+ delay = _retry_delay(attempt)
714
+ if deadline is not None:
715
+ remaining = deadline - time.monotonic()
716
+ if remaining <= 0:
717
+ raise CanonicalControlAPIError("deadline")
718
+ delay = min(delay, remaining)
719
+ resp.close()
720
+ if deadline is not None:
721
+ _deadline_sleep(delay, deadline)
722
+ else:
723
+ time.sleep(delay)
724
+ continue
725
+ prefix = _bounded_response_prefix(resp, _DEFAULT_CONTROL_BYTES)
726
+ code = _bounded_error_biz_code(prefix)
727
+ raise CanonicalControlAPIError(
728
+ "http_error", status_code=resp.status_code, biz_code=code)
729
+ data = _read_bounded_control_bytes(resp)
730
+ if not data:
731
+ resp.close()
732
+ return None
733
+ refusal = None
734
+ try:
735
+ parsed = data.decode("utf-8", errors="strict")
736
+ except UnicodeError:
737
+ refusal = "invalid_utf8"
738
+ if refusal is None:
739
+ try:
740
+ result = json.loads(parsed)
741
+ except (ValueError, RecursionError):
742
+ refusal = "invalid_json"
743
+ if refusal is not None:
744
+ raise CanonicalControlAPIError(
745
+ refusal, status_code=resp.status_code)
746
+ if deadline is not None and time.monotonic() >= deadline:
747
+ # Refuse a late success; the budget is already spent.
748
+ raise CanonicalControlAPIError("deadline")
749
+ resp.close()
750
+ return result
751
+ finally:
752
+ _close_response_quietly(resp)
753
+ if not resp.ok or (_single_attempt and not 200 <= resp.status_code < 300):
535
754
  pop_rejected = _is_pop_rejection(resp)
536
755
  if pop_rejected and recovery_deadline is None:
537
756
  recovery_deadline = time.monotonic() + self.config.http_retry_window
@@ -1210,6 +1429,7 @@ class APIClient:
1210
1429
  transparency: Optional[Literal["whitebox", "blackbox"]] = None,
1211
1430
  idempotency_key: Optional[str] = None,
1212
1431
  group_concurrency_policy: Optional[dict] = None,
1432
+ metrics_retry_policy: Optional[dict] = None,
1213
1433
  ) -> dict:
1214
1434
  """Create a group with optional scheduling defaults for its Jobs.
1215
1435
 
@@ -1229,6 +1449,8 @@ class APIClient:
1229
1449
  raise ValueError("ak_ids entries must be nonempty strings")
1230
1450
  references = list(dict.fromkeys(references))
1231
1451
  body: dict = {}
1452
+ if metrics_retry_policy is not None:
1453
+ body["metrics_retry_policy"] = metrics_retry_policy
1232
1454
  if transparency is not None:
1233
1455
  body["transparency"] = transparency
1234
1456
  if idempotency_key is not None:
@@ -1357,6 +1579,7 @@ class APIClient:
1357
1579
  instance_range: Optional[str] = None,
1358
1580
  profile: Optional[str] = None,
1359
1581
  transparency: Optional[Literal["whitebox", "blackbox"]] = None,
1582
+ metrics_retry_policy: Optional[dict] = None,
1360
1583
  ) -> dict:
1361
1584
  """Create a job."""
1362
1585
  body = self.build_create_job_body(
@@ -1381,6 +1604,7 @@ class APIClient:
1381
1604
  runner_options=runner_options,
1382
1605
  idempotency_key=idempotency_key,
1383
1606
  max_failure_retries=max_failure_retries,
1607
+ metrics_retry_policy=metrics_retry_policy,
1384
1608
  priority=priority,
1385
1609
  priority_weight=priority_weight,
1386
1610
  resource_mode=resource_mode,
@@ -1473,6 +1697,7 @@ class APIClient:
1473
1697
  instance_range: Optional[str] = None,
1474
1698
  profile: Optional[str] = None,
1475
1699
  transparency: Optional[Literal["whitebox", "blackbox"]] = None,
1700
+ metrics_retry_policy: Optional[dict] = None,
1476
1701
  ) -> dict:
1477
1702
  """Build the /jobs request body for job creation."""
1478
1703
  if transparency is not None and transparency not in {"whitebox", "blackbox"}:
@@ -1544,6 +1769,8 @@ class APIClient:
1544
1769
  body["runner_options"] = runner_options
1545
1770
  if idempotency_key is not None:
1546
1771
  body["idempotency_key"] = idempotency_key
1772
+ if metrics_retry_policy is not None:
1773
+ body["metrics_retry_policy"] = metrics_retry_policy
1547
1774
  if max_failure_retries:
1548
1775
  body["max_failure_retries"] = max_failure_retries
1549
1776
 
@@ -160,8 +160,16 @@ class APIClientTransportAdapter:
160
160
  return TransportError(label, status=status, biz_code=biz_code, data=data)
161
161
 
162
162
  def _call(self, method: str, path: str, *, json_body=None,
163
- timeout: float | None = None, params=None):
164
- options = dict(timeout=timeout, deadline=self._base_deadline)
163
+ timeout: float | None = None, params=None,
164
+ deadline: float | None = None, single_attempt: bool = False):
165
+ options = dict(timeout=timeout, deadline=self._base_deadline if deadline is None else deadline)
166
+ if single_attempt:
167
+ options["_single_attempt"] = True
168
+ # ALL canonical control requests go through the bounded projection
169
+ # (review P1): redirects refused (auth headers never follow a
170
+ # cross-origin Location), a finite timeout owns one deadline across
171
+ # retries, streamed bounded reads, late successes refused.
172
+ options["_bounded"] = True
165
173
  if json_body is not None:
166
174
  options['json_body'] = json_body
167
175
  if params is not None:
@@ -169,7 +177,36 @@ class APIClientTransportAdapter:
169
177
  try:
170
178
  return self._client._request(method, path, **options)
171
179
  except Exception as exc:
172
- from .api import APIError
180
+ from .api import APIError, CanonicalControlAPIError
181
+ if isinstance(exc, CanonicalControlAPIError):
182
+ # Sanitized typed refusal from the bounded projection: map
183
+ # the closed reason set to the SDK's typed error family so
184
+ # deadline/budget semantics survive the bridge (never raw
185
+ # causes or response bodies).
186
+ reason = getattr(exc, "reason", None)
187
+ if reason == "deadline":
188
+ from instance_repo.errors import RequestDeadlineExceeded
189
+ raise RequestDeadlineExceeded(
190
+ "canonical control request deadline exhausted") from None
191
+ if reason in ("response_limit", "invalid_limit"):
192
+ from instance_repo.errors import SchemaError
193
+ raise SchemaError("canonical control response exceeded its bound") from None
194
+ if reason in ("invalid_utf8", "invalid_json"):
195
+ from instance_repo.errors import SchemaError
196
+ raise SchemaError("canonical control response is not valid JSON") from None
197
+ if reason == "redirect":
198
+ from instance_repo.errors import TransportError
199
+ raise TransportError("canonical control redirect refused") from None
200
+ status = getattr(exc, "status_code", None)
201
+ biz = None
202
+ detail = getattr(exc, "detail", None)
203
+ if isinstance(detail, dict):
204
+ biz = detail.get("code")
205
+ if type(biz) is not int:
206
+ biz = None
207
+ from instance_repo.errors import TransportError
208
+ raise TransportError("apiserver rejected the request",
209
+ status=status, biz_code=biz) from None
173
210
  if isinstance(exc, APIError) or getattr(exc, 'status_code', None) is not None:
174
211
  raise self._translate_api_error(exc) from None
175
212
  else:
@@ -181,27 +218,72 @@ class APIClientTransportAdapter:
181
218
 
182
219
  # -- SDK Transport surface ---------------------------------------------
183
220
 
221
+ @staticmethod
222
+ def _split_query(path: str):
223
+ base, _, query = path.partition("?")
224
+ pairs = parse_qsl(query, keep_blank_values=True)
225
+ params = dict(pairs)
226
+ if len(params) != len(pairs):
227
+ from instance_repo.errors import SchemaError
228
+
229
+ raise SchemaError("duplicate query keys in request path")
230
+ return base, params or None
231
+
184
232
  def get(self, path: str, *, timeout: float | None = None) -> dict:
185
- if "?" in path:
186
- base, _, query = path.partition("?")
187
- pairs = parse_qsl(query, keep_blank_values=True)
188
- keys = [k for k, _ in pairs]
189
- if len(keys) != len(set(keys)):
190
- from instance_repo.errors import SchemaError
191
-
192
- raise SchemaError("duplicate query keys in request path")
193
- params = dict(pairs)
194
- return self._call("GET", base, timeout=timeout) if not params \
195
- else self._request_get_with_params(base, params, timeout)
196
- return self._call("GET", path, timeout=timeout)
197
-
198
- def _request_get_with_params(self, path, params, timeout):
199
- return self._call('GET', path, params=params, timeout=timeout)
233
+ base, params = self._split_query(path)
234
+ return self._call("GET", base, params=params, timeout=timeout)
200
235
 
201
236
  def post(self, path: str, body: dict, *, idempotent: bool = False,
202
237
  headers: dict | None = None, timeout: float | None = None) -> dict:
203
238
  return self._call("POST", path, json_body=body, timeout=timeout)
204
239
 
240
+ def _acl_response(self, method, path, body, timeout):
241
+ from instance_repo.errors import RequestDeadlineExceeded, SchemaError, TransportError
242
+
243
+ deadline = self._base_deadline
244
+ if timeout is not None:
245
+ if type(timeout) not in (int, float) or not math.isfinite(timeout) or timeout < 0:
246
+ raise SchemaError("invalid ACL request timeout")
247
+ call_deadline = time.monotonic() + timeout
248
+ deadline = min(deadline, call_deadline) if deadline is not None else call_deadline
249
+ if deadline is not None and time.monotonic() >= deadline:
250
+ raise RequestDeadlineExceeded("ACL request budget exhausted")
251
+
252
+ base, params = self._split_query(path)
253
+ response = self._call(method, base, json_body=body, params=params,
254
+ timeout=timeout, deadline=deadline, single_attempt=method != "GET")
255
+ if isinstance(response, dict) and set(response) <= {"code", "message", "data", "pagination"}:
256
+ if "code" in response:
257
+ code = response["code"]
258
+ if type(code) is not int:
259
+ raise SchemaError("invalid ACL response code")
260
+ if code != 0:
261
+ raise TransportError("ACL request rejected", status=200, biz_code=code)
262
+ if "data" in response:
263
+ return response["data"], response.get("pagination")
264
+ return response, None
265
+
266
+ def request(self, method, path, body=None, *, idempotent=None, timeout=None):
267
+ from instance_repo.errors import SchemaError
268
+
269
+ # Only the ABI used by the ACL SDK is supported. Never silently turn a
270
+ # non-idempotent write into a retryable call.
271
+ if not (
272
+ (method == "GET" and body is None and idempotent is True)
273
+ or (method == "POST" and type(body) is dict and idempotent is False)
274
+ or (method == "DELETE" and body is None and idempotent is False)
275
+ ):
276
+ raise SchemaError("unsupported ACL request")
277
+ data, _ = self._acl_response(method, path, body, timeout)
278
+ return data
279
+
280
+ def request_with_meta(self, method, path, *, timeout=None):
281
+ from instance_repo.errors import SchemaError
282
+
283
+ if method != "GET":
284
+ raise SchemaError("unsupported ACL metadata request")
285
+ return self._acl_response(method, path, None, timeout)
286
+
205
287
 
206
288
  # ---------------------------------------------------------------------------
207
289
  # Budget: absolute internally, REMAINING DURATION for B public APIs