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.
- hungerbridge/__init__.py +47 -0
- hungerbridge/auth.py +106 -0
- hungerbridge/bridge.py +30 -0
- hungerbridge/canonical.py +123 -0
- hungerbridge/client.py +353 -0
- hungerbridge/exceptions.py +81 -0
- hungerbridge/protocol.py +16 -0
- hungerbridge/py.typed +0 -0
- hungerbridge/stream.py +389 -0
- hungerbridge/transport.py +198 -0
- hungerbridge/units.py +55 -0
- hungerbridge-1.0.dev4.dist-info/METADATA +148 -0
- hungerbridge-1.0.dev4.dist-info/RECORD +16 -0
- hungerbridge-1.0.dev4.dist-info/WHEEL +5 -0
- hungerbridge-1.0.dev4.dist-info/licenses/LICENSE +674 -0
- hungerbridge-1.0.dev4.dist-info/top_level.txt +1 -0
|
@@ -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.'''
|
hungerbridge/protocol.py
ADDED
|
@@ -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
|