API-Docker
view release on metacpan or search on metacpan
misc/agent-context/.claude/skills/docker-engine-api/examples/python/engine_helpers.py view on Meta::CPAN
"""Bounded protocol helpers, not a complete Docker SDK. Python 3.10+."""
from __future__ import annotations
import base64
import json
import re
import struct
from collections.abc import Iterator, Mapping
from typing import Any, BinaryIO
class ProtocolError(ValueError):
"""Unexpected, malformed, or truncated protocol input."""
class CompatibilityError(ValueError):
"""No deliberately supported API version is available."""
class DaemonStreamError(RuntimeError):
"""An error reported after the daemon started a stream."""
def parse_version(value: str) -> tuple[int, int]:
if not isinstance(value, str) or not re.fullmatch(r'(0|[1-9]\d*)\.(0|[1-9]\d*)', value):
raise CompatibilityError('API version must have integer major.minor form')
major, minor = value.split('.')
return int(major), int(minor)
def negotiate_version(server: Mapping[str, Any], *, client_min: str,
client_max: str, pin: str | None = None,
legacy_server_min: str | None = None) -> str:
"""Intersect supported ranges; no implicit guessed server minimum."""
cmin, cmax = parse_version(client_min), parse_version(client_max)
smax = parse_version(server.get('ApiVersion'))
minimum = server.get('MinAPIVersion')
if minimum is None:
minimum = legacy_server_min
if minimum is None:
raise CompatibilityError('Server omitted MinAPIVersion; an explicit legacy policy is required')
smin = parse_version(minimum)
if cmin > cmax or smin > smax:
raise CompatibilityError('Invalid supported version range')
low, high = max(cmin, smin), min(cmax, smax)
if low > high:
raise CompatibilityError('Client and daemon API ranges do not intersect')
selected = parse_version(pin) if pin is not None else high
if not low <= selected <= high:
raise CompatibilityError('Pinned API version lies outside the shared supported range')
return f'{selected[0]}.{selected[1]}'
def encode_registry_auth(auth: Mapping[str, str]) -> str:
"""Padded URL-safe base64 JSON; output is a secret, not safe logging data."""
if not isinstance(auth, Mapping) or any(not isinstance(k, str) or not isinstance(v, str)
for k, v in auth.items()):
raise TypeError('Auth must map strings to strings')
raw = json.dumps(dict(auth), ensure_ascii=False, separators=(',', ':')).encode('utf-8')
return base64.urlsafe_b64encode(raw).decode('ascii')
def read_exact(reader: BinaryIO, size: int, *, allow_clean_eof: bool = False) -> bytes | None:
if size < 0:
raise ValueError('size must be non-negative')
parts: list[bytes] = []
remaining = size
while remaining:
part = reader.read(remaining)
if part is None:
raise ProtocolError('Nonblocking readers require an adapter')
if not isinstance(part, bytes) or len(part) > remaining:
raise ProtocolError('Reader violated the bounded binary-read contract')
if not part:
if allow_clean_eof and remaining == size:
return None
raise ProtocolError('Truncated stream')
parts.append(part)
remaining -= len(part)
return b''.join(parts)
def iter_output(reader: BinaryIO, *, tty: bool = False,
max_frame_bytes: int = 16 * 1024 * 1024,
chunk_size: int = 65536) -> Iterator[tuple[int, bytes]]:
"""Yield (stream type, bytes). TTY output is raw combined output, labeled 1.
Strict reserved-byte and truncation checks are this client's safety policy.
"""
if max_frame_bytes <= 0 or chunk_size <= 0:
raise ValueError('Limits must be positive')
if tty:
while True:
data = reader.read(chunk_size)
if not isinstance(data, bytes) or len(data) > chunk_size:
raise ProtocolError('Reader violated the bounded binary-read contract')
if not data:
return
yield 1, data
else:
while True:
header = read_exact(reader, 8, allow_clean_eof=True)
if header is None:
return
kind = header[0]
if header[1:4] != b'\x00\x00\x00' or kind not in (0, 1, 2, 3):
raise ProtocolError('Invalid or unsupported multiplex header')
length = struct.unpack('>I', header[4:])[0]
if length > max_frame_bytes:
raise ProtocolError('Frame exceeds configured size limit')
payload = read_exact(reader, length)
( run in 0.664 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )