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 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"