hungerbridge 1.0.dev4__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.
@@ -0,0 +1,81 @@
1
+ '''Exception hierarchy. Every error raised by this package is a ``HungerBridgeError``.'''
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ import requests
8
+
9
+ __all__ = [
10
+ 'HungerBridgeError',
11
+ 'HungerBridgeRateLimit',
12
+ 'HungerBridgeAuthError',
13
+ 'HungerBridgeForbidden',
14
+ 'HungerBridgeNotFound',
15
+ 'HungerBridgeConnectionError',
16
+ 'InvalidModeError',
17
+ ]
18
+
19
+
20
+ class HungerBridgeError(Exception):
21
+ '''Base error. ``status``/``code``/``reason`` mirror the server's error body.
22
+
23
+ Server error bodies look like ``{'ok': false, 'error': '<code>',
24
+ 'message': '<text>', 'reason': '<optional detail>'}``.
25
+ '''
26
+
27
+ def __init__(
28
+ self,
29
+ message: str = '',
30
+ *,
31
+ status: int | None = None,
32
+ code: str | None = None,
33
+ reason: str | None = None,
34
+ body: Any = None,
35
+ ):
36
+ super().__init__(message)
37
+ self.message = message
38
+ self.status = status
39
+ self.code = code
40
+ self.reason = reason
41
+ self.body = body
42
+
43
+
44
+ class HungerBridgeRateLimit(HungerBridgeError):
45
+ '''HTTP 429. ``retry_after`` is the server's ``Retry-After`` hint (seconds) if any.'''
46
+
47
+ def __init__(self, message: str | None = None, *, retry_after: Any = None, **kwargs: Any):
48
+ if message is None:
49
+ message = 'HungerBridge rate limit exceeded'
50
+ if retry_after is not None:
51
+ message += f' (retry after {retry_after}s)'
52
+ kwargs.setdefault('status', 429)
53
+ kwargs.setdefault('code', 'rate_limited')
54
+ super().__init__(message, **kwargs)
55
+ self.retry_after = retry_after
56
+
57
+
58
+ class HungerBridgeAuthError(HungerBridgeError):
59
+ '''HTTP 401: missing/invalid signature, unknown/revoked/expired token,
60
+ clock skew (``reason == 'timestamp_out_of_range'``) or nonce replay.'''
61
+
62
+
63
+ class HungerBridgeForbidden(HungerBridgeError):
64
+ '''HTTP 403: authenticated, but the token lacks the permission node
65
+ (or the client IP is not allowed by ``security.yaml``).'''
66
+
67
+
68
+ class HungerBridgeNotFound(HungerBridgeError):
69
+ '''HTTP 404: unknown endpoint or pickup.'''
70
+
71
+
72
+ class HungerBridgeConnectionError(HungerBridgeError, requests.exceptions.ConnectionError):
73
+ '''The server could not be reached or did not answer in time.
74
+
75
+ Also a ``requests.ConnectionError`` so code written against the previous
76
+ client (which leaked raw ``requests`` exceptions) keeps working.
77
+ '''
78
+
79
+
80
+ class InvalidModeError(HungerBridgeError, ValueError):
81
+ '''An unsupported ``mode`` argument was passed to a client getter.'''
@@ -0,0 +1,16 @@
1
+ from __future__ import annotations
2
+
3
+ __all__ = ['PROTOCOL_VERSION', 'PROTOCOL_HEADER', 'SSE_HISTORY_END', 'SSE_KEEPALIVE']
4
+
5
+ #: Protocol major version implemented by this client. The server advertises
6
+ #: its version in the ``X-HungerBridge-Protocol`` response header and in
7
+ #: ``/server/meta`` (``protocol_version``). Servers that predate versioning
8
+ #: send neither and are treated as version 1.
9
+ PROTOCOL_VERSION = 1
10
+ PROTOCOL_HEADER = 'X-HungerBridge-Protocol'
11
+
12
+ #: SSE comment sent by the server right after the requested history has been
13
+ #: written (also sent when no history was requested). Older clients ignore it.
14
+ SSE_HISTORY_END = 'history-end'
15
+ #: SSE comment sent every 15 seconds by the server to keep the stream alive.
16
+ SSE_KEEPALIVE = 'keepalive'
hungerbridge/py.typed ADDED
File without changes
hungerbridge/stream.py ADDED
@@ -0,0 +1,389 @@
1
+ '''Server-Sent-Events client for ``GET /server/stream``.
2
+
3
+ Wire format (protocol v1)::
4
+
5
+ : history-end <- comment, sent once the requested history is written
6
+ data:<log line> <- one event per log line; '\\n'/'\\r' inside the line
7
+ are escaped as the two characters backslash+n/r
8
+ : keepalive <- comment every 15 s
9
+
10
+ Older servers do not send ``history-end``; for them the client falls back to
11
+ the previous time-based heuristic (lines received within one second of
12
+ connecting are treated as history).
13
+ '''
14
+
15
+ from __future__ import annotations
16
+
17
+ import codecs
18
+ import re
19
+ import socket
20
+ import threading
21
+ import time
22
+ from typing import Callable, Iterable, Iterator, List, Optional, Tuple, Union
23
+
24
+ import requests
25
+
26
+ from .protocol import PROTOCOL_HEADER, SSE_HISTORY_END
27
+ from .transport import parse_retry_after
28
+
29
+ __all__ = ['Stream', 'parse_sse']
30
+
31
+ HeadersProvider = Union[Callable[[], dict], dict]
32
+
33
+ _ANSI_RE = re.compile(r'\x1b\[[0-9;]*m')
34
+ # Matches '[12:34:56]' and the server's '[12:34:56 INFO]' line prefix.
35
+ _TIMESTAMP_RE = re.compile(r'\[([0-9]{2}:[0-9]{2}:[0-9]{2})(?:\]|\s)')
36
+ _LINE_SPLIT_RE = re.compile(r'\r\n|\r|\n')
37
+
38
+ #: Legacy servers (no ``history-end`` marker): history window after connect.
39
+ LEGACY_HISTORY_WINDOW_SEC = 1.0
40
+
41
+
42
+ def _split_lines(chunks: Iterable[bytes]) -> Iterator[str]:
43
+ '''Split a byte stream into SSE lines (CRLF, LF or CR terminated).
44
+
45
+ Unlike ``str.splitlines`` this does not split on Unicode line separators
46
+ (U+2028, form feed, ...) that may legitimately appear inside a log line.
47
+ A trailing line without terminator is discarded, as the SSE spec requires.
48
+ '''
49
+ decoder = codecs.getincrementaldecoder('utf-8')(errors='replace')
50
+ buf = ''
51
+ for chunk in chunks:
52
+ if not chunk:
53
+ continue
54
+ buf += decoder.decode(chunk)
55
+ while True:
56
+ match = _LINE_SPLIT_RE.search(buf)
57
+ if match is None:
58
+ break
59
+ if match.group() == '\r' and match.end() == len(buf):
60
+ break # possibly the first half of a CRLF split across chunks
61
+ yield buf[: match.start()]
62
+ buf = buf[match.end() :]
63
+ buf += decoder.decode(b'', final=True)
64
+ yield from _LINE_SPLIT_RE.split(buf)[:-1]
65
+
66
+
67
+ def _iter_raw_chunks(response: requests.Response) -> Iterator[bytes]:
68
+ '''Yield bytes as soon as they arrive.
69
+
70
+ ``iter_content(chunk_size=None)`` only streams chunked responses; behind a
71
+ proxy that turns the stream into a close-delimited body it would block
72
+ until EOF. urllib3 2's ``read1`` returns whatever is available instead.
73
+ '''
74
+ read1 = getattr(response.raw, 'read1', None)
75
+ if read1 is None:
76
+ yield from response.iter_content(chunk_size=1)
77
+ return
78
+ while True:
79
+ chunk = read1(8192, decode_content=True)
80
+ if not chunk:
81
+ return
82
+ yield chunk
83
+
84
+
85
+ def parse_sse(lines: Iterable[str]) -> Iterator[Tuple[str, str]]:
86
+ '''Parse SSE lines into ``('data', text)`` and ``('comment', text)`` items.
87
+
88
+ Follows the WHATWG SSE rules: a single space after the colon is removed
89
+ (and nothing else, so indentation inside log lines is preserved);
90
+ multiple ``data`` fields in one event are joined with ``\\n``.
91
+ '''
92
+ data: Optional[List[str]] = None
93
+ for line in lines:
94
+ if line == '':
95
+ if data is not None:
96
+ yield ('data', '\n'.join(data))
97
+ data = None
98
+ continue
99
+ name, sep, value = line.partition(':')
100
+ if sep and value.startswith(' '):
101
+ value = value[1:]
102
+ if name == '':
103
+ yield ('comment', value)
104
+ elif name == 'data':
105
+ if data is None:
106
+ data = []
107
+ data.append(value)
108
+ # 'event', 'id', 'retry' and unknown fields are ignored.
109
+ if data is not None:
110
+ yield ('data', '\n'.join(data))
111
+
112
+
113
+ class Stream:
114
+ '''SSE streaming wrapper for ``/server/stream``.
115
+
116
+ ``history_handler(lines)`` receives the requested history once per
117
+ connection; ``new_log_handler(line)`` receives each live line. Without
118
+ handlers, lines are accumulated in :meth:`getRaw`, :meth:`getSanitized`
119
+ and :meth:`getTimestamped`.
120
+ '''
121
+
122
+ def __init__(
123
+ self,
124
+ base_url: str,
125
+ headers_provider: HeadersProvider,
126
+ history_handler: Optional[Callable[[List[str]], None]] = None,
127
+ new_log_handler: Optional[Callable[[str], None]] = None,
128
+ *,
129
+ connect_timeout: float = 5.0,
130
+ session_factory: Callable[[], requests.Session] = requests.Session,
131
+ ):
132
+ self.url = base_url.rstrip('/') + '/server/stream'
133
+ self.headers_provider = headers_provider
134
+ self.history_handler = history_handler
135
+ self.new_log_handler = new_log_handler
136
+ self.connect_timeout = connect_timeout
137
+ self._session_factory = session_factory
138
+
139
+ self.raw_stream: List[str] = []
140
+ self.sanitized_stream: List[str] = []
141
+ self.timestamped_stream: dict = {}
142
+ #: Last exception that ended a connection attempt (``None`` if clean).
143
+ self.last_error: Optional[BaseException] = None
144
+
145
+ self._lock = threading.Lock()
146
+ self._thread: Optional[threading.Thread] = None
147
+ self._stop_event: Optional[threading.Event] = None
148
+ self._connected = threading.Event()
149
+ self._session: Optional[requests.Session] = None
150
+ self._response: Optional[requests.Response] = None
151
+ self._last_line: Optional[str] = None
152
+ self._connections = 0
153
+
154
+ # -- default handlers ----------------------------------------------------------
155
+
156
+ def _record(self, line: str) -> None:
157
+ clean = self.sanitize(line)
158
+ ts = self.extractTimestamp(clean)
159
+ with self._lock:
160
+ self.raw_stream.append(line)
161
+ self.sanitized_stream.append(clean)
162
+ if ts is not None:
163
+ self.timestamped_stream[ts] = clean
164
+
165
+ def _default_history_handler(self, historic_lines: List[str]) -> None:
166
+ for line in historic_lines:
167
+ self._record(line)
168
+
169
+ def _default_new_log_handler(self, line: str) -> None:
170
+ self._record(line)
171
+
172
+ def _emit_history(self, lines: List[str]) -> None:
173
+ try:
174
+ (self.history_handler or self._default_history_handler)(list(lines))
175
+ except Exception: # handler errors must not kill the stream
176
+ pass
177
+
178
+ def _emit_live(self, line: str) -> None:
179
+ try:
180
+ (self.new_log_handler or self._default_new_log_handler)(line)
181
+ except Exception:
182
+ pass
183
+
184
+ # -- lifecycle -----------------------------------------------------------------
185
+
186
+ def connect(
187
+ self,
188
+ keepalive: int = 15,
189
+ history: Optional[int] = None,
190
+ *,
191
+ reconnect: bool = False,
192
+ reconnect_delay: float = 1.0,
193
+ max_reconnect_delay: float = 30.0,
194
+ ) -> None:
195
+ '''Start streaming in a background daemon thread (no-op if already running).
196
+
197
+ ``keepalive`` is the server's keepalive interval; the read timeout is
198
+ derived from it so dead connections are detected. With
199
+ ``reconnect=True`` the stream reconnects with exponential back-off and
200
+ de-duplicates the replayed history against the last line seen.
201
+ '''
202
+ if self._thread and self._thread.is_alive():
203
+ return
204
+ stop = threading.Event()
205
+ self._stop_event = stop
206
+ self._connected.clear()
207
+ read_timeout = max(3.0 * float(keepalive or 15), 30.0)
208
+ self._thread = threading.Thread(
209
+ target=self._run,
210
+ args=(stop, history, read_timeout, reconnect, reconnect_delay, max_reconnect_delay),
211
+ name='HungerBridgeStream',
212
+ daemon=True,
213
+ )
214
+ self._thread.start()
215
+
216
+ def disconnect(self, timeout: float = 5.0) -> None:
217
+ stop, thread = self._stop_event, self._thread
218
+ if stop:
219
+ stop.set()
220
+ if thread and thread is not threading.current_thread():
221
+ # Closing the response here would block: the buffered reader's lock is held by
222
+ # the worker's blocking read. Shutting the socket down makes that read return
223
+ # immediately; the worker then closes the response/session itself.
224
+ self._abort_socket()
225
+ thread.join(timeout)
226
+ else:
227
+ self._close_transport()
228
+ self._thread = None
229
+ self._stop_event = None
230
+ self._connected.clear()
231
+
232
+ def wait_until_connected(self, timeout: Optional[float] = None) -> bool:
233
+ '''Block until the server accepted the stream (HTTP 200 received).'''
234
+ return self._connected.wait(timeout)
235
+
236
+ def isConnected(self) -> bool:
237
+ return self._thread is not None and self._thread.is_alive()
238
+
239
+ def getRaw(self) -> list:
240
+ with self._lock:
241
+ return list(self.raw_stream)
242
+
243
+ def getSanitized(self) -> list:
244
+ with self._lock:
245
+ return list(self.sanitized_stream)
246
+
247
+ def getTimestamped(self) -> dict:
248
+ with self._lock:
249
+ return dict(self.timestamped_stream)
250
+
251
+ # -- worker --------------------------------------------------------------------
252
+
253
+ def _abort_socket(self) -> None:
254
+ response = self._response
255
+ if response is None:
256
+ return
257
+ raw = getattr(response, 'raw', None)
258
+ candidates = [
259
+ getattr(getattr(raw, '_connection', None), 'sock', None), # urllib3 2.x
260
+ getattr(getattr(getattr(getattr(raw, '_fp', None), 'fp', None), 'raw', None), '_sock', None), # http.client
261
+ ]
262
+ for sock in candidates:
263
+ if sock is None:
264
+ continue
265
+ try:
266
+ sock.shutdown(socket.SHUT_RDWR)
267
+ return
268
+ except OSError:
269
+ continue
270
+
271
+ def _close_transport(self) -> None:
272
+ response, session = self._response, self._session
273
+ for closable in (response, session):
274
+ if closable is not None:
275
+ try:
276
+ closable.close()
277
+ except Exception:
278
+ pass
279
+
280
+ def _request_url(self, history: Optional[int]) -> str:
281
+ if not history:
282
+ return self.url
283
+ sep = '&' if '?' in self.url else '?'
284
+ return f'{self.url}{sep}history={int(history)}'
285
+
286
+ def _run(self, stop, history, read_timeout, reconnect, delay, max_delay) -> None:
287
+ backoff = delay
288
+ try:
289
+ while not stop.is_set():
290
+ received = False
291
+ try:
292
+ received = self._stream_once(stop, history, read_timeout)
293
+ self.last_error = None
294
+ except Exception as exc: # network errors, HTTP errors
295
+ self.last_error = exc
296
+ finally:
297
+ self._connected.clear()
298
+ self._close_transport()
299
+ self._response = None
300
+ self._session = None
301
+ if not reconnect or stop.is_set():
302
+ break
303
+ backoff = delay if received else min(backoff * 2, max_delay)
304
+ retry_after = getattr(self.last_error, 'retry_after', None)
305
+ wait = max(backoff, float(retry_after)) if isinstance(retry_after, (int, float)) else backoff
306
+ stop.wait(wait)
307
+ finally:
308
+ if self._stop_event is stop:
309
+ self._thread = None
310
+ self._stop_event = None
311
+
312
+ def _stream_once(self, stop: threading.Event, history: Optional[int], read_timeout: float) -> bool:
313
+ '''Run a single connection. Returns True if any event was received.'''
314
+ headers = self.headers_provider() if callable(self.headers_provider) else dict(self.headers_provider)
315
+ headers.setdefault('Accept', 'text/event-stream')
316
+ self._session = self._session_factory()
317
+ response = self._session.get(
318
+ self._request_url(history),
319
+ headers=headers,
320
+ stream=True,
321
+ timeout=(self.connect_timeout, read_timeout),
322
+ )
323
+ self._response = response
324
+ if not response.ok:
325
+ error = requests.HTTPError(f'{response.status_code}: {response.text}', response=response)
326
+ if response.status_code == 429:
327
+ error.retry_after = parse_retry_after(response.headers.get('Retry-After')) # type: ignore[attr-defined]
328
+ raise error
329
+ self._connections += 1
330
+ self._connected.set()
331
+
332
+ reconnecting = self._connections > 1
333
+ in_history = bool(history)
334
+ history_lines: List[str] = []
335
+ # Servers that advertise a protocol version always send the history-end
336
+ # marker; only legacy servers need the time-window heuristic.
337
+ legacy = response.headers.get(PROTOCOL_HEADER) is None
338
+ legacy_deadline = time.monotonic() + LEGACY_HISTORY_WINDOW_SEC
339
+ received = False
340
+
341
+ def finish_history() -> None:
342
+ nonlocal in_history
343
+ in_history = False
344
+ lines = history_lines
345
+ if reconnecting:
346
+ # Replay only what was missed while disconnected, as live lines.
347
+ if self._last_line is not None and self._last_line in lines:
348
+ idx = len(lines) - 1 - lines[::-1].index(self._last_line)
349
+ lines = lines[idx + 1 :]
350
+ for line in lines:
351
+ self._last_line = line
352
+ self._emit_live(line)
353
+ else:
354
+ if lines:
355
+ self._last_line = lines[-1]
356
+ self._emit_history(lines)
357
+
358
+ for kind, value in parse_sse(_split_lines(_iter_raw_chunks(response))):
359
+ if stop.is_set():
360
+ break
361
+ received = True
362
+ if kind == 'comment':
363
+ if in_history and (value.strip() == SSE_HISTORY_END or (legacy and time.monotonic() >= legacy_deadline)):
364
+ finish_history()
365
+ continue
366
+ if in_history:
367
+ if not legacy or time.monotonic() < legacy_deadline:
368
+ history_lines.append(value)
369
+ continue
370
+ finish_history() # legacy server: window elapsed, this line is live
371
+ self._last_line = value
372
+ self._emit_live(value)
373
+ if in_history and history_lines and not stop.is_set():
374
+ finish_history()
375
+ return received
376
+
377
+ # -- helpers -------------------------------------------------------------------
378
+
379
+ @staticmethod
380
+ def sanitize(line: str) -> str:
381
+ '''Strip ANSI colors, unescape ``\\n``/``\\r`` and trailing whitespace.'''
382
+ clean = _ANSI_RE.sub('', line)
383
+ clean = clean.replace('\\n', '\n').replace('\\r', '\r')
384
+ return clean.rstrip()
385
+
386
+ @staticmethod
387
+ def extractTimestamp(line: str) -> Optional[str]:
388
+ m = _TIMESTAMP_RE.match(line)
389
+ return m.group(1) if m else None
@@ -0,0 +1,198 @@
1
+ '''HTTP transport: signing, throttling, retries, timeouts and error mapping.'''
2
+
3
+ from __future__ import annotations
4
+
5
+ import threading
6
+ import time
7
+ import warnings
8
+ from typing import Any, Callable, Optional, Tuple, Union
9
+
10
+ import requests
11
+
12
+ from .auth import Credentials, build_auth_headers
13
+ from .canonical import canonical_body
14
+ from .exceptions import (
15
+ HungerBridgeAuthError,
16
+ HungerBridgeConnectionError,
17
+ HungerBridgeError,
18
+ HungerBridgeForbidden,
19
+ HungerBridgeNotFound,
20
+ HungerBridgeRateLimit,
21
+ )
22
+ from .protocol import PROTOCOL_HEADER, PROTOCOL_VERSION
23
+
24
+ __all__ = ['Transport', 'DEFAULT_TIMEOUT']
25
+
26
+ Timeout = Union[float, Tuple[float, float], None]
27
+
28
+ #: (connect, read) seconds. ``/server/run`` waits up to 5 s for the game
29
+ #: thread server-side, so 30 s of read time is generous.
30
+ DEFAULT_TIMEOUT: Tuple[float, float] = (5.0, 30.0)
31
+
32
+ BASE_HEADERS = {'Content-Type': 'application/json', 'Accept': 'application/json'}
33
+
34
+ _STATUS_ERRORS = {
35
+ 401: HungerBridgeAuthError,
36
+ 403: HungerBridgeForbidden,
37
+ 404: HungerBridgeNotFound,
38
+ }
39
+
40
+
41
+ def parse_retry_after(value: Optional[str]) -> Union[int, str, None]:
42
+ if not value:
43
+ return None
44
+ try:
45
+ return int(float(value))
46
+ except ValueError:
47
+ return value # HTTP-date form; surfaced verbatim
48
+
49
+
50
+ class Transport:
51
+ '''Signs and sends requests to one HungerBridge server.
52
+
53
+ Thread-safe: a single instance may be shared between threads.
54
+ '''
55
+
56
+ def __init__(
57
+ self,
58
+ base_url: str,
59
+ credentials: Optional[Credentials],
60
+ *,
61
+ max_retries: int = 0,
62
+ retry_backoff_sec: float = 1.0,
63
+ swallow_rate_limit: bool = False,
64
+ static_delay: float = 0.0,
65
+ timeout: Timeout = DEFAULT_TIMEOUT,
66
+ session: Optional[requests.Session] = None,
67
+ sleep: Callable[[float], None] = time.sleep,
68
+ ):
69
+ self.base_url = base_url.rstrip('/')
70
+ self.credentials = credentials
71
+ self.max_retries = int(max_retries or 0)
72
+ self.retry_backoff_sec = float(retry_backoff_sec or 1.0)
73
+ self.swallow_rate_limit = bool(swallow_rate_limit)
74
+ self.static_delay = float(static_delay or 0.0)
75
+ self.timeout = timeout
76
+ self.session = session or requests.Session()
77
+ self._sleep = sleep
78
+ self._last_request_time = 0.0
79
+ self._throttle_lock = threading.Lock()
80
+ #: Protocol version advertised by the server (``None`` until the first response).
81
+ self.server_protocol_version: Optional[int] = None
82
+ self._warned_protocol = False
83
+
84
+ # -- signing -----------------------------------------------------------------
85
+
86
+ def auth_headers(self, method: str, path: str, payload: Any = None) -> dict:
87
+ return build_auth_headers(self.credentials, method, path, payload, base_headers=BASE_HEADERS)
88
+
89
+ # -- throttle ----------------------------------------------------------------
90
+
91
+ def _throttle(self) -> None:
92
+ if self.static_delay <= 0:
93
+ return
94
+ with self._throttle_lock:
95
+ delta = time.time() - self._last_request_time
96
+ if delta < self.static_delay:
97
+ self._sleep(self.static_delay - delta)
98
+ self._last_request_time = time.time()
99
+
100
+ # -- requests ----------------------------------------------------------------
101
+
102
+ def get(self, path: str) -> Any:
103
+ return self.request('GET', path)
104
+
105
+ def post(self, path: str, payload: Any) -> Any:
106
+ return self.request('POST', path, payload)
107
+
108
+ def request(self, method: str, path: str, payload: Any = None) -> Any:
109
+ '''Send a signed request and return the decoded JSON (or text) body.
110
+
111
+ 429 responses are retried up to ``max_retries`` times, waiting
112
+ ``max(retry_backoff_sec * attempt, Retry-After)``. Each attempt is
113
+ signed with a fresh nonce/timestamp. Returns ``None`` instead of
114
+ raising on a final 429 when ``swallow_rate_limit`` is set.
115
+ '''
116
+ self._throttle()
117
+ full_path = '/' + path.lstrip('/')
118
+ url = self.base_url + full_path
119
+ body = canonical_body(payload) if method.upper() != 'GET' else None
120
+
121
+ for attempt in range(self.max_retries + 1):
122
+ headers = self.auth_headers(method, full_path, payload if body is not None else None)
123
+ try:
124
+ response = self.session.request(method, url, headers=headers, data=body, timeout=self.timeout)
125
+ except requests.exceptions.Timeout as exc:
126
+ raise HungerBridgeConnectionError(f'HungerBridge request timed out: {method} {full_path}') from exc
127
+ except requests.exceptions.ConnectionError as exc:
128
+ raise HungerBridgeConnectionError(f'Cannot reach HungerBridge at {self.base_url}: {exc}') from exc
129
+
130
+ self._observe_protocol(response)
131
+
132
+ if response.status_code == 429:
133
+ retry_after = parse_retry_after(response.headers.get('Retry-After'))
134
+ if attempt < self.max_retries:
135
+ delay = self.retry_backoff_sec * (attempt + 1)
136
+ if isinstance(retry_after, (int, float)):
137
+ delay = max(delay, float(retry_after))
138
+ self._sleep(delay)
139
+ continue
140
+ if self.swallow_rate_limit:
141
+ return None
142
+ raise HungerBridgeRateLimit(retry_after=retry_after, body=_json_or_none(response))
143
+
144
+ if not response.ok:
145
+ raise self._error_for(response)
146
+
147
+ return _json_or_text(response)
148
+ return None # pragma: no cover - loop always returns or raises
149
+
150
+ # -- helpers -----------------------------------------------------------------
151
+
152
+ def _observe_protocol(self, response: requests.Response) -> None:
153
+ raw = response.headers.get(PROTOCOL_HEADER)
154
+ if raw is None:
155
+ return
156
+ try:
157
+ version = int(str(raw).split('.', 1)[0])
158
+ except ValueError:
159
+ return
160
+ self.server_protocol_version = version
161
+ if version != PROTOCOL_VERSION and not self._warned_protocol:
162
+ self._warned_protocol = True
163
+ warnings.warn(
164
+ f'HungerBridge server speaks protocol v{version}, this client implements v{PROTOCOL_VERSION}',
165
+ RuntimeWarning,
166
+ stacklevel=4,
167
+ )
168
+
169
+ @staticmethod
170
+ def _error_for(response: requests.Response) -> HungerBridgeError:
171
+ data = _json_or_none(response)
172
+ code = reason = None
173
+ if isinstance(data, dict):
174
+ code = data.get('error') if isinstance(data.get('error'), str) else None
175
+ reason = data.get('reason') if isinstance(data.get('reason'), str) else None
176
+ cls = _STATUS_ERRORS.get(response.status_code, HungerBridgeError)
177
+ # Message format kept from the original client for log/grep compatibility.
178
+ return cls(
179
+ f'HungerBridge error {response.status_code}: {response.text}',
180
+ status=response.status_code,
181
+ code=code,
182
+ reason=reason,
183
+ body=data,
184
+ )
185
+
186
+
187
+ def _json_or_none(response: requests.Response) -> Any:
188
+ try:
189
+ return response.json()
190
+ except ValueError:
191
+ return None
192
+
193
+
194
+ def _json_or_text(response: requests.Response) -> Any:
195
+ try:
196
+ return response.json()
197
+ except ValueError:
198
+ return response.text