lessormq 0.1.0__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.
- lessormq/__init__.py +57 -0
- lessormq/_client.py +514 -0
- lessormq/_errors.py +134 -0
- lessormq/_models.py +149 -0
- lessormq/_worker.py +459 -0
- lessormq/py.typed +0 -0
- lessormq-0.1.0.dist-info/METADATA +141 -0
- lessormq-0.1.0.dist-info/RECORD +10 -0
- lessormq-0.1.0.dist-info/WHEEL +4 -0
- lessormq-0.1.0.dist-info/licenses/LICENSE +201 -0
lessormq/__init__.py
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""LessorMQ for Python: the message queue over HTTP where the server decides and
|
|
2
|
+
clients only claim, run, ack or fail.
|
|
3
|
+
|
|
4
|
+
from lessormq import Client, Worker
|
|
5
|
+
|
|
6
|
+
client = Client("https://mq.example.com", api_key)
|
|
7
|
+
client.publish("mail", {"to": "ada@example.com"})
|
|
8
|
+
Worker(client, "mail", lambda message, job: send(message.body)).run()
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from ._client import AsyncClient, Client
|
|
12
|
+
from ._errors import (
|
|
13
|
+
ApiError,
|
|
14
|
+
AuthenticationError,
|
|
15
|
+
ConflictError,
|
|
16
|
+
ForbiddenError,
|
|
17
|
+
LeaseLostError,
|
|
18
|
+
LessorMQError,
|
|
19
|
+
NotFoundError,
|
|
20
|
+
PayloadTooLargeError,
|
|
21
|
+
PermanentFailure,
|
|
22
|
+
RateLimitedError,
|
|
23
|
+
ServerError,
|
|
24
|
+
TransportError,
|
|
25
|
+
ValidationError,
|
|
26
|
+
)
|
|
27
|
+
from ._models import FailResult, Lease, Message, Published, Stats
|
|
28
|
+
from ._worker import AsyncJob, AsyncWorker, Job, Worker
|
|
29
|
+
|
|
30
|
+
__all__ = [
|
|
31
|
+
"ApiError",
|
|
32
|
+
"AsyncClient",
|
|
33
|
+
"AsyncJob",
|
|
34
|
+
"AsyncWorker",
|
|
35
|
+
"AuthenticationError",
|
|
36
|
+
"Client",
|
|
37
|
+
"ConflictError",
|
|
38
|
+
"FailResult",
|
|
39
|
+
"ForbiddenError",
|
|
40
|
+
"Job",
|
|
41
|
+
"Lease",
|
|
42
|
+
"LeaseLostError",
|
|
43
|
+
"LessorMQError",
|
|
44
|
+
"Message",
|
|
45
|
+
"NotFoundError",
|
|
46
|
+
"PayloadTooLargeError",
|
|
47
|
+
"PermanentFailure",
|
|
48
|
+
"Published",
|
|
49
|
+
"RateLimitedError",
|
|
50
|
+
"ServerError",
|
|
51
|
+
"Stats",
|
|
52
|
+
"TransportError",
|
|
53
|
+
"ValidationError",
|
|
54
|
+
"Worker",
|
|
55
|
+
]
|
|
56
|
+
|
|
57
|
+
__version__ = "0.1.0"
|
lessormq/_client.py
ADDED
|
@@ -0,0 +1,514 @@
|
|
|
1
|
+
"""The six protocol calls of LessorMQ (docs/protocol.md), nothing more, sync and async.
|
|
2
|
+
|
|
3
|
+
The client never decides what happens to a message: no retry of a failed job, no delay,
|
|
4
|
+
no dead-lettering. It reports, and the queue decides. It does retry its own HTTP calls
|
|
5
|
+
when that is safe: network errors, 5xx and 429, for every call that can be repeated
|
|
6
|
+
(all of them, given the automatic dedup key on publish).
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import asyncio
|
|
12
|
+
import json
|
|
13
|
+
import logging
|
|
14
|
+
import secrets
|
|
15
|
+
import time
|
|
16
|
+
import traceback
|
|
17
|
+
from dataclasses import dataclass
|
|
18
|
+
from datetime import datetime
|
|
19
|
+
from typing import Any
|
|
20
|
+
from urllib.parse import quote
|
|
21
|
+
|
|
22
|
+
import httpx
|
|
23
|
+
|
|
24
|
+
from ._errors import ApiError, PermanentFailure, RateLimitedError, ServerError, TransportError
|
|
25
|
+
from ._models import FailResult, Lease, Published, Stats, format_time, parse_time
|
|
26
|
+
|
|
27
|
+
__all__ = ["AsyncClient", "Client"]
|
|
28
|
+
|
|
29
|
+
USER_AGENT = "lessormq-python/1"
|
|
30
|
+
_MAX_ERROR_MESSAGE = 65535
|
|
31
|
+
_MAX_ERROR_TYPE = 255
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass(frozen=True)
|
|
35
|
+
class _Call:
|
|
36
|
+
"""One protocol call as HTTP: what to send, whether it may be sent again, and how
|
|
37
|
+
long it may take."""
|
|
38
|
+
|
|
39
|
+
method: str
|
|
40
|
+
path: str
|
|
41
|
+
payload: Any
|
|
42
|
+
repeatable: bool
|
|
43
|
+
extra_timeout: float = 0.0
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass(frozen=True)
|
|
47
|
+
class _Response:
|
|
48
|
+
status: int
|
|
49
|
+
body: Any
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class _Base:
|
|
53
|
+
def __init__(
|
|
54
|
+
self,
|
|
55
|
+
base_url: str,
|
|
56
|
+
api_key: str,
|
|
57
|
+
*,
|
|
58
|
+
http_retries: int,
|
|
59
|
+
retry_delay: float,
|
|
60
|
+
auto_dedup_key: bool,
|
|
61
|
+
timeout: float,
|
|
62
|
+
user_agent: str,
|
|
63
|
+
logger: logging.Logger | None,
|
|
64
|
+
) -> None:
|
|
65
|
+
self._base_url = base_url.rstrip("/")
|
|
66
|
+
self._api_key = api_key
|
|
67
|
+
self._http_retries = http_retries
|
|
68
|
+
self._retry_delay = retry_delay
|
|
69
|
+
self._auto_dedup_key = auto_dedup_key
|
|
70
|
+
self._timeout = timeout
|
|
71
|
+
self._user_agent = user_agent
|
|
72
|
+
self._logger = logger or logging.getLogger("lessormq")
|
|
73
|
+
|
|
74
|
+
def __repr__(self) -> str:
|
|
75
|
+
# Never the key.
|
|
76
|
+
return f"{type(self).__name__}({self._base_url!r})"
|
|
77
|
+
|
|
78
|
+
# The calls, as HTTP. Shared by Client and AsyncClient.
|
|
79
|
+
|
|
80
|
+
def _publish_call(
|
|
81
|
+
self,
|
|
82
|
+
queue: str,
|
|
83
|
+
body: Any,
|
|
84
|
+
headers: dict[str, str] | None,
|
|
85
|
+
dedup_key: str | None,
|
|
86
|
+
delay_seconds: int | None,
|
|
87
|
+
available_at: datetime | None,
|
|
88
|
+
max_attempts: int | None,
|
|
89
|
+
) -> _Call:
|
|
90
|
+
if dedup_key is None and self._auto_dedup_key:
|
|
91
|
+
dedup_key = "lmq-auto-" + secrets.token_hex(12)
|
|
92
|
+
payload: dict[str, Any] = {"body": body}
|
|
93
|
+
if headers:
|
|
94
|
+
payload["headers"] = headers
|
|
95
|
+
if dedup_key is not None:
|
|
96
|
+
payload["dedup_key"] = dedup_key
|
|
97
|
+
if delay_seconds is not None:
|
|
98
|
+
payload["delay_seconds"] = delay_seconds
|
|
99
|
+
if available_at is not None:
|
|
100
|
+
payload["available_at"] = format_time(available_at)
|
|
101
|
+
if max_attempts is not None:
|
|
102
|
+
payload["max_attempts"] = max_attempts
|
|
103
|
+
# Without a dedup key a repeated publish could create a second message.
|
|
104
|
+
return _Call("POST", f"/v1/queues/{_segment(queue)}/messages", payload, dedup_key is not None)
|
|
105
|
+
|
|
106
|
+
def _claim_call(
|
|
107
|
+
self,
|
|
108
|
+
queue: str,
|
|
109
|
+
consumer: str | None,
|
|
110
|
+
route: str | None,
|
|
111
|
+
wait_seconds: int,
|
|
112
|
+
lease_seconds: int | None,
|
|
113
|
+
) -> _Call:
|
|
114
|
+
payload: dict[str, Any] = {}
|
|
115
|
+
if consumer is not None:
|
|
116
|
+
payload["consumer"] = consumer
|
|
117
|
+
if route is not None:
|
|
118
|
+
payload["route"] = route
|
|
119
|
+
if wait_seconds > 0:
|
|
120
|
+
payload["wait_seconds"] = wait_seconds
|
|
121
|
+
if lease_seconds is not None:
|
|
122
|
+
payload["lease_seconds"] = lease_seconds
|
|
123
|
+
# A claim whose answer got lost leaves a lease that simply expires and counts as
|
|
124
|
+
# an attempt, so claims are retried like the rest.
|
|
125
|
+
return _Call("POST", f"/v1/queues/{_segment(queue)}/claims", payload, True, float(max(wait_seconds, 0)))
|
|
126
|
+
|
|
127
|
+
@staticmethod
|
|
128
|
+
def _extend_call(lease: Lease, lease_seconds: int | None) -> _Call:
|
|
129
|
+
payload: dict[str, Any] = {"receipt": lease.receipt}
|
|
130
|
+
if lease_seconds is not None:
|
|
131
|
+
payload["lease_seconds"] = lease_seconds
|
|
132
|
+
return _Call("POST", _message_path(lease, "extend"), payload, True)
|
|
133
|
+
|
|
134
|
+
@staticmethod
|
|
135
|
+
def _ack_call(lease: Lease) -> _Call:
|
|
136
|
+
return _Call("POST", _message_path(lease, "ack"), {"receipt": lease.receipt}, True)
|
|
137
|
+
|
|
138
|
+
@staticmethod
|
|
139
|
+
def _fail_call(
|
|
140
|
+
lease: Lease,
|
|
141
|
+
error: BaseException | str,
|
|
142
|
+
permanent: bool | None,
|
|
143
|
+
details: Any,
|
|
144
|
+
type: str | None,
|
|
145
|
+
) -> _Call:
|
|
146
|
+
if isinstance(error, BaseException):
|
|
147
|
+
text = str(error)
|
|
148
|
+
if type is None:
|
|
149
|
+
type = _type_name(error)
|
|
150
|
+
if details is None:
|
|
151
|
+
details = _origin(error)
|
|
152
|
+
if permanent is None:
|
|
153
|
+
permanent = isinstance(error, PermanentFailure)
|
|
154
|
+
else:
|
|
155
|
+
text = error
|
|
156
|
+
report: dict[str, Any] = {"message": text[:_MAX_ERROR_MESSAGE] or "(no message)"}
|
|
157
|
+
if type is not None:
|
|
158
|
+
report["type"] = type[:_MAX_ERROR_TYPE]
|
|
159
|
+
if details is not None:
|
|
160
|
+
report["details"] = details
|
|
161
|
+
payload = {"receipt": lease.receipt, "error": report, "permanent": bool(permanent)}
|
|
162
|
+
return _Call("POST", _message_path(lease, "fail"), payload, True)
|
|
163
|
+
|
|
164
|
+
@staticmethod
|
|
165
|
+
def _release_call(lease: Lease, delay_seconds: int) -> _Call:
|
|
166
|
+
payload: dict[str, Any] = {"receipt": lease.receipt}
|
|
167
|
+
if delay_seconds > 0:
|
|
168
|
+
payload["delay_seconds"] = delay_seconds
|
|
169
|
+
return _Call("POST", _message_path(lease, "release"), payload, True)
|
|
170
|
+
|
|
171
|
+
@staticmethod
|
|
172
|
+
def _stats_call(queue: str) -> _Call:
|
|
173
|
+
return _Call("GET", f"/v1/queues/{_segment(queue)}", None, True)
|
|
174
|
+
|
|
175
|
+
# Sending, shared parts.
|
|
176
|
+
|
|
177
|
+
def _request(self, call: _Call) -> dict[str, Any]:
|
|
178
|
+
headers = {
|
|
179
|
+
"Authorization": "Bearer " + self._api_key,
|
|
180
|
+
"Accept": "application/json",
|
|
181
|
+
"User-Agent": self._user_agent,
|
|
182
|
+
}
|
|
183
|
+
content = None
|
|
184
|
+
if call.payload is not None:
|
|
185
|
+
headers["Content-Type"] = "application/json"
|
|
186
|
+
content = json.dumps(call.payload, ensure_ascii=False, separators=(",", ":")).encode()
|
|
187
|
+
return {
|
|
188
|
+
"method": call.method,
|
|
189
|
+
"url": self._base_url + call.path,
|
|
190
|
+
"headers": headers,
|
|
191
|
+
"content": content,
|
|
192
|
+
"timeout": self._timeout + call.extra_timeout,
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
def _outcome(self, call: _Call, response: httpx.Response, attempt: int) -> _Response | tuple[ApiError, float]:
|
|
196
|
+
"""The response, or the error and how long to wait before sending again."""
|
|
197
|
+
try:
|
|
198
|
+
body = response.json() if response.content else None
|
|
199
|
+
except ValueError:
|
|
200
|
+
# A proxy's error page, say: the status says enough.
|
|
201
|
+
body = None
|
|
202
|
+
if response.status_code < 400:
|
|
203
|
+
return _Response(response.status_code, body)
|
|
204
|
+
|
|
205
|
+
retry_after = _retry_after(response)
|
|
206
|
+
error = ApiError.from_response(response.status_code, body, retry_after)
|
|
207
|
+
# A 429 was not processed at all, so it is always safe to send again.
|
|
208
|
+
retry = isinstance(error, RateLimitedError) or (call.repeatable and isinstance(error, ServerError))
|
|
209
|
+
if retry and attempt <= self._http_retries:
|
|
210
|
+
return error, self._pause(attempt, retry_after, call.path, str(error))
|
|
211
|
+
raise error
|
|
212
|
+
|
|
213
|
+
def _transport_failed(self, call: _Call, error: httpx.HTTPError, attempt: int) -> float:
|
|
214
|
+
"""How long to wait before sending again, or raises TransportError."""
|
|
215
|
+
if call.repeatable and attempt <= self._http_retries:
|
|
216
|
+
return self._pause(attempt, None, call.path, str(error) or type(error).__name__)
|
|
217
|
+
raise TransportError(f"{call.method} {call.path} failed: {error!s}") from error
|
|
218
|
+
|
|
219
|
+
def _pause(self, attempt: int, retry_after: int | None, path: str, reason: str) -> float:
|
|
220
|
+
delay = float(retry_after) if retry_after is not None else self._retry_delay * attempt
|
|
221
|
+
self._logger.warning(
|
|
222
|
+
"LessorMQ request failed, retrying",
|
|
223
|
+
extra={"path": path, "attempt": attempt, "delay": delay, "reason": reason},
|
|
224
|
+
)
|
|
225
|
+
return delay
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
class Client(_Base):
|
|
229
|
+
"""LessorMQ over HTTP, blocking. Thread-safe: a worker's extend timer shares it.
|
|
230
|
+
|
|
231
|
+
``http`` lets you bring your own ``httpx.Client`` (proxies, TLS, transports); its
|
|
232
|
+
timeout is replaced per request.
|
|
233
|
+
"""
|
|
234
|
+
|
|
235
|
+
def __init__(
|
|
236
|
+
self,
|
|
237
|
+
base_url: str,
|
|
238
|
+
api_key: str,
|
|
239
|
+
*,
|
|
240
|
+
http_retries: int = 3,
|
|
241
|
+
retry_delay: float = 0.1,
|
|
242
|
+
auto_dedup_key: bool = True,
|
|
243
|
+
timeout: float = 10.0,
|
|
244
|
+
user_agent: str = USER_AGENT,
|
|
245
|
+
http: httpx.Client | None = None,
|
|
246
|
+
logger: logging.Logger | None = None,
|
|
247
|
+
) -> None:
|
|
248
|
+
"""
|
|
249
|
+
:param http_retries: retries after a network error, a 5xx or a 429, for calls that
|
|
250
|
+
are safe to repeat (all but a publish without a dedup key)
|
|
251
|
+
:param retry_delay: base delay between retries in seconds, times the attempt number
|
|
252
|
+
:param auto_dedup_key: give every publish without a dedup key one of its own, so a
|
|
253
|
+
retried publish can never create a second message
|
|
254
|
+
:param timeout: seconds per request; a claim gets its wait on top
|
|
255
|
+
"""
|
|
256
|
+
super().__init__(
|
|
257
|
+
base_url,
|
|
258
|
+
api_key,
|
|
259
|
+
http_retries=http_retries,
|
|
260
|
+
retry_delay=retry_delay,
|
|
261
|
+
auto_dedup_key=auto_dedup_key,
|
|
262
|
+
timeout=timeout,
|
|
263
|
+
user_agent=user_agent,
|
|
264
|
+
logger=logger,
|
|
265
|
+
)
|
|
266
|
+
self._owns_http = http is None
|
|
267
|
+
self._http = http or httpx.Client()
|
|
268
|
+
|
|
269
|
+
def __enter__(self) -> Client:
|
|
270
|
+
return self
|
|
271
|
+
|
|
272
|
+
def __exit__(self, *exc: object) -> None:
|
|
273
|
+
self.close()
|
|
274
|
+
|
|
275
|
+
def close(self) -> None:
|
|
276
|
+
if self._owns_http:
|
|
277
|
+
self._http.close()
|
|
278
|
+
|
|
279
|
+
def publish(
|
|
280
|
+
self,
|
|
281
|
+
queue: str,
|
|
282
|
+
body: Any,
|
|
283
|
+
*,
|
|
284
|
+
headers: dict[str, str] | None = None,
|
|
285
|
+
dedup_key: str | None = None,
|
|
286
|
+
delay_seconds: int | None = None,
|
|
287
|
+
available_at: datetime | None = None,
|
|
288
|
+
max_attempts: int | None = None,
|
|
289
|
+
) -> Published:
|
|
290
|
+
"""Put a message on a queue.
|
|
291
|
+
|
|
292
|
+
With a dedup key (yours, or the automatic one), an open message with that key is
|
|
293
|
+
returned instead of a new one: ``published.duplicate``.
|
|
294
|
+
"""
|
|
295
|
+
call = self._publish_call(queue, body, headers, dedup_key, delay_seconds, available_at, max_attempts)
|
|
296
|
+
return Published.from_api(self._send(call).body)
|
|
297
|
+
|
|
298
|
+
def claim(
|
|
299
|
+
self,
|
|
300
|
+
queue: str,
|
|
301
|
+
*,
|
|
302
|
+
consumer: str | None = None,
|
|
303
|
+
route: str | None = None,
|
|
304
|
+
wait_seconds: int = 0,
|
|
305
|
+
lease_seconds: int | None = None,
|
|
306
|
+
) -> Lease | None:
|
|
307
|
+
"""Lease the next message of a queue, waiting up to ``wait_seconds`` (at most 20)
|
|
308
|
+
for one. None when nothing became available, or the queue is paused."""
|
|
309
|
+
response = self._send(self._claim_call(queue, consumer, route, wait_seconds, lease_seconds))
|
|
310
|
+
return None if response.status == 204 else Lease.from_api(response.body)
|
|
311
|
+
|
|
312
|
+
def extend(self, lease: Lease, lease_seconds: int | None = None) -> Lease:
|
|
313
|
+
"""Move the end of the lease to now plus ``lease_seconds`` (or the queue's lease).
|
|
314
|
+
|
|
315
|
+
:raises LeaseLostError: when the lease already ended
|
|
316
|
+
"""
|
|
317
|
+
response = self._send(self._extend_call(lease, lease_seconds))
|
|
318
|
+
lease.lease_until = parse_time(str(response.body["lease_until"]))
|
|
319
|
+
return lease
|
|
320
|
+
|
|
321
|
+
def ack(self, lease: Lease) -> None:
|
|
322
|
+
"""Report success.
|
|
323
|
+
|
|
324
|
+
:raises LeaseLostError: when the lease already ended
|
|
325
|
+
"""
|
|
326
|
+
self._send(self._ack_call(lease))
|
|
327
|
+
|
|
328
|
+
def fail(
|
|
329
|
+
self,
|
|
330
|
+
lease: Lease,
|
|
331
|
+
error: BaseException | str,
|
|
332
|
+
*,
|
|
333
|
+
permanent: bool | None = None,
|
|
334
|
+
details: Any = None,
|
|
335
|
+
type: str | None = None,
|
|
336
|
+
) -> FailResult:
|
|
337
|
+
"""Report failure. The server decides what follows and says so in the result.
|
|
338
|
+
|
|
339
|
+
:param error: the exception, or a message
|
|
340
|
+
:param permanent: the input itself cannot be processed; by default, whether
|
|
341
|
+
``error`` is a :class:`PermanentFailure`
|
|
342
|
+
:param details: any JSON value with more context; by default where the exception
|
|
343
|
+
was raised
|
|
344
|
+
:param type: the error type; by default the exception's class
|
|
345
|
+
:raises LeaseLostError: when the lease already ended
|
|
346
|
+
"""
|
|
347
|
+
return FailResult.from_api(self._send(self._fail_call(lease, error, permanent, details, type)).body)
|
|
348
|
+
|
|
349
|
+
def release(self, lease: Lease, delay_seconds: int = 0) -> None:
|
|
350
|
+
"""Give the message back without an outcome; the attempt does not count.
|
|
351
|
+
|
|
352
|
+
:raises LeaseLostError: when the lease already ended
|
|
353
|
+
"""
|
|
354
|
+
self._send(self._release_call(lease, delay_seconds))
|
|
355
|
+
|
|
356
|
+
def stats(self, queue: str) -> Stats:
|
|
357
|
+
"""A queue's counts. Needs the consume or admin scope. Not part of the protocol;
|
|
358
|
+
for monitoring."""
|
|
359
|
+
return Stats.from_api(self._send(self._stats_call(queue)).body.get("stats") or {})
|
|
360
|
+
|
|
361
|
+
def _send(self, call: _Call) -> _Response:
|
|
362
|
+
attempt = 0
|
|
363
|
+
while True:
|
|
364
|
+
attempt += 1
|
|
365
|
+
try:
|
|
366
|
+
response = self._http.request(**self._request(call))
|
|
367
|
+
except httpx.HTTPError as e:
|
|
368
|
+
time.sleep(self._transport_failed(call, e, attempt))
|
|
369
|
+
continue
|
|
370
|
+
outcome = self._outcome(call, response, attempt)
|
|
371
|
+
if isinstance(outcome, _Response):
|
|
372
|
+
return outcome
|
|
373
|
+
time.sleep(outcome[1])
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
class AsyncClient(_Base):
|
|
377
|
+
"""LessorMQ over HTTP for asyncio. The same calls as :class:`Client`, awaited."""
|
|
378
|
+
|
|
379
|
+
def __init__(
|
|
380
|
+
self,
|
|
381
|
+
base_url: str,
|
|
382
|
+
api_key: str,
|
|
383
|
+
*,
|
|
384
|
+
http_retries: int = 3,
|
|
385
|
+
retry_delay: float = 0.1,
|
|
386
|
+
auto_dedup_key: bool = True,
|
|
387
|
+
timeout: float = 10.0,
|
|
388
|
+
user_agent: str = USER_AGENT,
|
|
389
|
+
http: httpx.AsyncClient | None = None,
|
|
390
|
+
logger: logging.Logger | None = None,
|
|
391
|
+
) -> None:
|
|
392
|
+
super().__init__(
|
|
393
|
+
base_url,
|
|
394
|
+
api_key,
|
|
395
|
+
http_retries=http_retries,
|
|
396
|
+
retry_delay=retry_delay,
|
|
397
|
+
auto_dedup_key=auto_dedup_key,
|
|
398
|
+
timeout=timeout,
|
|
399
|
+
user_agent=user_agent,
|
|
400
|
+
logger=logger,
|
|
401
|
+
)
|
|
402
|
+
self._owns_http = http is None
|
|
403
|
+
self._http = http or httpx.AsyncClient()
|
|
404
|
+
|
|
405
|
+
async def __aenter__(self) -> AsyncClient:
|
|
406
|
+
return self
|
|
407
|
+
|
|
408
|
+
async def __aexit__(self, *exc: object) -> None:
|
|
409
|
+
await self.aclose()
|
|
410
|
+
|
|
411
|
+
async def aclose(self) -> None:
|
|
412
|
+
if self._owns_http:
|
|
413
|
+
await self._http.aclose()
|
|
414
|
+
|
|
415
|
+
async def publish(
|
|
416
|
+
self,
|
|
417
|
+
queue: str,
|
|
418
|
+
body: Any,
|
|
419
|
+
*,
|
|
420
|
+
headers: dict[str, str] | None = None,
|
|
421
|
+
dedup_key: str | None = None,
|
|
422
|
+
delay_seconds: int | None = None,
|
|
423
|
+
available_at: datetime | None = None,
|
|
424
|
+
max_attempts: int | None = None,
|
|
425
|
+
) -> Published:
|
|
426
|
+
"""See :meth:`Client.publish`."""
|
|
427
|
+
call = self._publish_call(queue, body, headers, dedup_key, delay_seconds, available_at, max_attempts)
|
|
428
|
+
return Published.from_api((await self._send(call)).body)
|
|
429
|
+
|
|
430
|
+
async def claim(
|
|
431
|
+
self,
|
|
432
|
+
queue: str,
|
|
433
|
+
*,
|
|
434
|
+
consumer: str | None = None,
|
|
435
|
+
route: str | None = None,
|
|
436
|
+
wait_seconds: int = 0,
|
|
437
|
+
lease_seconds: int | None = None,
|
|
438
|
+
) -> Lease | None:
|
|
439
|
+
"""See :meth:`Client.claim`."""
|
|
440
|
+
response = await self._send(self._claim_call(queue, consumer, route, wait_seconds, lease_seconds))
|
|
441
|
+
return None if response.status == 204 else Lease.from_api(response.body)
|
|
442
|
+
|
|
443
|
+
async def extend(self, lease: Lease, lease_seconds: int | None = None) -> Lease:
|
|
444
|
+
"""See :meth:`Client.extend`."""
|
|
445
|
+
response = await self._send(self._extend_call(lease, lease_seconds))
|
|
446
|
+
lease.lease_until = parse_time(str(response.body["lease_until"]))
|
|
447
|
+
return lease
|
|
448
|
+
|
|
449
|
+
async def ack(self, lease: Lease) -> None:
|
|
450
|
+
"""See :meth:`Client.ack`."""
|
|
451
|
+
await self._send(self._ack_call(lease))
|
|
452
|
+
|
|
453
|
+
async def fail(
|
|
454
|
+
self,
|
|
455
|
+
lease: Lease,
|
|
456
|
+
error: BaseException | str,
|
|
457
|
+
*,
|
|
458
|
+
permanent: bool | None = None,
|
|
459
|
+
details: Any = None,
|
|
460
|
+
type: str | None = None,
|
|
461
|
+
) -> FailResult:
|
|
462
|
+
"""See :meth:`Client.fail`."""
|
|
463
|
+
return FailResult.from_api((await self._send(self._fail_call(lease, error, permanent, details, type))).body)
|
|
464
|
+
|
|
465
|
+
async def release(self, lease: Lease, delay_seconds: int = 0) -> None:
|
|
466
|
+
"""See :meth:`Client.release`."""
|
|
467
|
+
await self._send(self._release_call(lease, delay_seconds))
|
|
468
|
+
|
|
469
|
+
async def stats(self, queue: str) -> Stats:
|
|
470
|
+
"""See :meth:`Client.stats`."""
|
|
471
|
+
return Stats.from_api((await self._send(self._stats_call(queue))).body.get("stats") or {})
|
|
472
|
+
|
|
473
|
+
async def _send(self, call: _Call) -> _Response:
|
|
474
|
+
attempt = 0
|
|
475
|
+
while True:
|
|
476
|
+
attempt += 1
|
|
477
|
+
try:
|
|
478
|
+
response = await self._http.request(**self._request(call))
|
|
479
|
+
except httpx.HTTPError as e:
|
|
480
|
+
await asyncio.sleep(self._transport_failed(call, e, attempt))
|
|
481
|
+
continue
|
|
482
|
+
outcome = self._outcome(call, response, attempt)
|
|
483
|
+
if isinstance(outcome, _Response):
|
|
484
|
+
return outcome
|
|
485
|
+
await asyncio.sleep(outcome[1])
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
def _segment(value: str) -> str:
|
|
489
|
+
return quote(value, safe="")
|
|
490
|
+
|
|
491
|
+
|
|
492
|
+
def _message_path(lease: Lease, action: str) -> str:
|
|
493
|
+
return f"/v1/messages/{_segment(lease.message.id)}/{action}"
|
|
494
|
+
|
|
495
|
+
|
|
496
|
+
def _type_name(error: BaseException) -> str:
|
|
497
|
+
cls = type(error)
|
|
498
|
+
return cls.__qualname__ if cls.__module__ == "builtins" else f"{cls.__module__}.{cls.__qualname__}"
|
|
499
|
+
|
|
500
|
+
|
|
501
|
+
def _origin(error: BaseException) -> dict[str, Any] | None:
|
|
502
|
+
"""Where the exception was raised: the innermost frame of its traceback."""
|
|
503
|
+
frames = traceback.extract_tb(error.__traceback__) if error.__traceback__ else []
|
|
504
|
+
if not frames:
|
|
505
|
+
return None
|
|
506
|
+
return {"file": frames[-1].filename, "line": frames[-1].lineno}
|
|
507
|
+
|
|
508
|
+
|
|
509
|
+
def _retry_after(response: httpx.Response) -> int | None:
|
|
510
|
+
value = response.headers.get("Retry-After")
|
|
511
|
+
try:
|
|
512
|
+
return int(value) if value is not None else None
|
|
513
|
+
except ValueError:
|
|
514
|
+
return None
|
lessormq/_errors.py
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
"""Everything the library raises, and what a handler raises to report a permanent failure."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class LessorMQError(Exception):
|
|
9
|
+
"""Everything this library raises."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class TransportError(LessorMQError):
|
|
13
|
+
"""The server could not be reached, after the configured retries."""
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class ApiError(LessorMQError):
|
|
17
|
+
"""The server answered with an error (RFC 9457 problem details).
|
|
18
|
+
|
|
19
|
+
``code`` is the stable problem code to branch on; the subclasses cover the ones a
|
|
20
|
+
client acts on.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
def __init__(self, status: int, code: str, detail: str = "", errors: list[dict[str, str]] | None = None) -> None:
|
|
24
|
+
self.status = status
|
|
25
|
+
self.code = code
|
|
26
|
+
self.detail = detail
|
|
27
|
+
self.errors = errors or []
|
|
28
|
+
super().__init__(detail or f"LessorMQ error {status} ({code})")
|
|
29
|
+
|
|
30
|
+
@staticmethod
|
|
31
|
+
def from_response(status: int, body: Any, retry_after: int | None = None) -> ApiError:
|
|
32
|
+
problem: dict[str, Any] = body if isinstance(body, dict) else {}
|
|
33
|
+
raw_code = problem.get("code")
|
|
34
|
+
raw_detail = problem.get("detail")
|
|
35
|
+
raw_errors = problem.get("errors")
|
|
36
|
+
code = raw_code if isinstance(raw_code, str) else _code_for(status)
|
|
37
|
+
detail = raw_detail if isinstance(raw_detail, str) else ""
|
|
38
|
+
errors = raw_errors if isinstance(raw_errors, list) else []
|
|
39
|
+
|
|
40
|
+
if code == "rate_limited":
|
|
41
|
+
return RateLimitedError(status, code, detail, errors, retry_after)
|
|
42
|
+
cls = _BY_CODE.get(code)
|
|
43
|
+
if cls is None:
|
|
44
|
+
cls = ServerError if status >= 500 else ApiError
|
|
45
|
+
return cls(status, code, detail, errors)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class LeaseLostError(ApiError):
|
|
49
|
+
"""The receipt is not the current lease of the message.
|
|
50
|
+
|
|
51
|
+
The lease expired, was released, or the message was claimed again. Stop reporting
|
|
52
|
+
on it: the server has already made it available again.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class ValidationError(ApiError):
|
|
57
|
+
"""The request was rejected as invalid; ``errors`` names each field."""
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class AuthenticationError(ApiError):
|
|
61
|
+
"""The API key is missing, unknown or revoked."""
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class ForbiddenError(ApiError):
|
|
65
|
+
"""The key lacks the scope or the queue, or its tenant is suspended (code ``tenant_suspended``)."""
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class NotFoundError(ApiError):
|
|
69
|
+
"""No such queue or message for this tenant."""
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class ConflictError(ApiError):
|
|
73
|
+
"""The message is in a state that does not allow this (``invalid_state``)."""
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class PayloadTooLargeError(ApiError):
|
|
77
|
+
"""Body and headers exceed the queue's ``max_message_bytes``."""
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
class RateLimitedError(ApiError):
|
|
81
|
+
"""The tenant exceeded a quota or rate limit, after the configured retries."""
|
|
82
|
+
|
|
83
|
+
def __init__(
|
|
84
|
+
self,
|
|
85
|
+
status: int,
|
|
86
|
+
code: str,
|
|
87
|
+
detail: str = "",
|
|
88
|
+
errors: list[dict[str, str]] | None = None,
|
|
89
|
+
retry_after: int | None = None,
|
|
90
|
+
) -> None:
|
|
91
|
+
super().__init__(status, code, detail, errors)
|
|
92
|
+
self.retry_after = retry_after
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
class ServerError(ApiError):
|
|
96
|
+
"""The server failed (5xx), after the configured retries."""
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
class PermanentFailure(Exception):
|
|
100
|
+
"""Raise from a handler when the message itself cannot be processed.
|
|
101
|
+
|
|
102
|
+
It cannot be decoded, it fails validation: retrying it would only fail again. Raise
|
|
103
|
+
it directly, or mix it into your own exception (``class BadInput(ValueError,
|
|
104
|
+
PermanentFailure)``). A fact for the server; the queue's ``on_permanent`` decides
|
|
105
|
+
what it means.
|
|
106
|
+
"""
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
_BY_CODE: dict[str, type[ApiError]] = {
|
|
110
|
+
"lease_lost": LeaseLostError,
|
|
111
|
+
"validation_failed": ValidationError,
|
|
112
|
+
"unauthorized": AuthenticationError,
|
|
113
|
+
"forbidden": ForbiddenError,
|
|
114
|
+
"tenant_suspended": ForbiddenError,
|
|
115
|
+
"not_found": NotFoundError,
|
|
116
|
+
"invalid_state": ConflictError,
|
|
117
|
+
"payload_too_large": PayloadTooLargeError,
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _code_for(status: int) -> str:
|
|
122
|
+
if status == 401:
|
|
123
|
+
return "unauthorized"
|
|
124
|
+
if status == 403:
|
|
125
|
+
return "forbidden"
|
|
126
|
+
if status == 404:
|
|
127
|
+
return "not_found"
|
|
128
|
+
if status == 413:
|
|
129
|
+
return "payload_too_large"
|
|
130
|
+
if status == 429:
|
|
131
|
+
return "rate_limited"
|
|
132
|
+
if status >= 500:
|
|
133
|
+
return "internal"
|
|
134
|
+
return "validation_failed"
|