bucli 0.6.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.
bucli/metering.py ADDED
@@ -0,0 +1,331 @@
1
+ """Reserving metered units without letting Bucli stop your business (spec §2.6).
2
+
3
+ ``UsageGuard.reserve`` asks Bucli for a unit right before the irreversible
4
+ act (sending a document). What happens when Bucli does not answer is the
5
+ meter's ``on_unavailable``:
6
+
7
+ - ``allow``: if Bucli does not answer within ``timeout`` (2 s by default) —
8
+ a connection error, a timeout, a 5xx — the unit is let through, queued
9
+ locally with its ``idempotency_key`` and reported later
10
+ (``POST /v1/usage`` with ``occurred_at``) by ``flush()``. Bucli records it
11
+ even beyond the quota (``overage``) and never refuses it.
12
+ - ``deny``: the error is raised; nothing is queued.
13
+
14
+ A refusal of Bucli (``402 quota_exhausted``, ``402 entitlement_access_denied``)
15
+ is an answer, never «unavailable»: it is returned as ``allowed=False``.
16
+
17
+ Each answer of Bucli carries the customer's ``remaining`` (allowance +
18
+ grants; ``-1`` unlimited) and the guard keeps it (``store``), so a customer
19
+ already at zero is refused locally — no call — until ``cache_seconds`` pass
20
+ or ``forget()`` is called (a grant bought, a new plan: on ``grant.created``
21
+ or ``entitlements.updated``).
22
+
23
+ ``store`` is where the queue and the balances live: ``MemoryUsageStore`` (one
24
+ process; tests), or ``bucli.contrib.django.metering.DatabaseUsageStore``
25
+ (the database: survives a restart, shared by every worker).
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import datetime
31
+ import logging
32
+ import threading
33
+ import time
34
+ from dataclasses import dataclass, field
35
+ from typing import TYPE_CHECKING, Any, Protocol
36
+
37
+ from bucli.constants import UNLIMITED
38
+ from bucli.errors import APIConnectionError, APIError, BillingError, BucliError, RateLimitError
39
+
40
+ if TYPE_CHECKING:
41
+ from bucli.client import Bucli
42
+ from bucli.objects import BucliObject
43
+
44
+ logger = logging.getLogger("bucli.metering")
45
+
46
+ ALLOW = "allow"
47
+ DENY = "deny"
48
+ #: Codes of Bucli that refuse a unit (an answer, not an outage).
49
+ REFUSALS = ("quota_exhausted", "entitlement_access_denied")
50
+ #: A conflict that only means «the same request is still running»: wait, as for an outage.
51
+ IN_FLIGHT_CODES = ("idempotency_key_in_use",)
52
+
53
+
54
+ @dataclass
55
+ class Reservation:
56
+ """What ``UsageGuard.reserve`` decided.
57
+
58
+ ``allowed``: go ahead. ``record``: Bucli's ``usage_record`` (``None`` when
59
+ decided without Bucli). ``offline``: let through while Bucli did not
60
+ answer (queued). ``refusal``: Bucli's code when refused (or
61
+ ``"quota_exhausted"`` when refused locally). ``remaining``: what the
62
+ customer has left, if known (``-1`` unlimited)."""
63
+
64
+ allowed: bool
65
+ record: BucliObject | None = None
66
+ offline: bool = False
67
+ refusal: str | None = None
68
+ remaining: int | None = None
69
+ error: BucliError | None = None
70
+
71
+ @property
72
+ def usage_id(self) -> str | None:
73
+ return getattr(self.record, "id", None) if self.record is not None else None
74
+
75
+
76
+ @dataclass
77
+ class PendingUnit:
78
+ """A unit let through while Bucli did not answer, waiting to be reported."""
79
+
80
+ meter: str
81
+ customer: str
82
+ idempotency_key: str
83
+ quantity: int
84
+ occurred_at: datetime.datetime
85
+ billable: bool = True
86
+ metadata: dict[str, Any] = field(default_factory=dict)
87
+ attempts: int = 0
88
+
89
+
90
+ class UsageStore(Protocol):
91
+ def enqueue(self, unit: PendingUnit) -> None: ...
92
+
93
+ def pending(self, limit: int) -> list[PendingUnit]: ...
94
+
95
+ def done(self, unit: PendingUnit) -> None: ...
96
+
97
+ def failed(self, unit: PendingUnit, error: str) -> None: ...
98
+
99
+ def remember(self, meter: str, customer: str, remaining: int | None) -> None: ...
100
+
101
+ def remaining(self, meter: str, customer: str, max_age: float) -> int | None: ...
102
+
103
+ def forget(self, meter: str | None, customer: str) -> None: ...
104
+
105
+ def discard(self, meter: str, customer: str, idempotency_key: str) -> bool: ...
106
+
107
+
108
+ #: A queued unit Bucli refused this many times is left out of the flush
109
+ #: (kept, for a person to look at): a refusal is not an outage.
110
+ MAX_REPORT_ATTEMPTS = 20
111
+
112
+
113
+ class MemoryUsageStore:
114
+ """The queue and the balances in this process (tests, scripts)."""
115
+
116
+ def __init__(self, max_attempts: int = MAX_REPORT_ATTEMPTS) -> None:
117
+ self.max_attempts = max_attempts
118
+ self._lock = threading.Lock()
119
+ self._queue: dict[tuple[str, str, str], PendingUnit] = {}
120
+ self._balances: dict[tuple[str, str], tuple[int, float]] = {}
121
+
122
+ def enqueue(self, unit: PendingUnit) -> None:
123
+ with self._lock:
124
+ self._queue.setdefault((unit.meter, unit.customer, unit.idempotency_key), unit)
125
+
126
+ def pending(self, limit: int) -> list[PendingUnit]:
127
+ with self._lock:
128
+ return [unit for unit in self._queue.values() if unit.attempts < self.max_attempts][:limit]
129
+
130
+ def done(self, unit: PendingUnit) -> None:
131
+ with self._lock:
132
+ self._queue.pop((unit.meter, unit.customer, unit.idempotency_key), None)
133
+
134
+ def failed(self, unit: PendingUnit, error: str) -> None:
135
+ with self._lock:
136
+ unit.attempts += 1
137
+
138
+ def remember(self, meter: str, customer: str, remaining: int | None) -> None:
139
+ with self._lock:
140
+ if remaining is None:
141
+ self._balances.pop((meter, customer), None)
142
+ else:
143
+ self._balances[(meter, customer)] = (remaining, time.monotonic())
144
+
145
+ def remaining(self, meter: str, customer: str, max_age: float) -> int | None:
146
+ with self._lock:
147
+ found = self._balances.get((meter, customer))
148
+ if found is None or time.monotonic() - found[1] > max_age:
149
+ return None
150
+ return found[0]
151
+
152
+ def forget(self, meter: str | None, customer: str) -> None:
153
+ with self._lock:
154
+ for key in [key for key in self._balances if key[1] == customer and meter in (None, key[0])]:
155
+ self._balances.pop(key, None)
156
+
157
+ def discard(self, meter: str, customer: str, idempotency_key: str) -> bool:
158
+ with self._lock:
159
+ return self._queue.pop((meter, customer, idempotency_key), None) is not None
160
+
161
+
162
+ def _unavailable(error: BucliError) -> bool:
163
+ """Bucli did not answer (or answered that it cannot now): never the
164
+ unit's fault, so it never spends a report attempt."""
165
+ if isinstance(error, APIConnectionError | RateLimitError):
166
+ return True
167
+ if getattr(error, "code", None) in IN_FLIGHT_CODES:
168
+ return True
169
+ return isinstance(error, APIError) and (error.http_status or 500) >= 500
170
+
171
+
172
+ def aware(moment: datetime.datetime) -> datetime.datetime:
173
+ """A moment with its zone (a naive one is taken as UTC)."""
174
+ return (
175
+ moment if moment.tzinfo is not None and moment.utcoffset() is not None else moment.replace(tzinfo=datetime.UTC)
176
+ )
177
+
178
+
179
+ def _remaining_of_refusal(error: BucliError) -> int | None:
180
+ """What a ``402 quota_exhausted`` says is left (cupo + grants), if it says."""
181
+ payload = (error.json_body or {}).get("error") if isinstance(error.json_body, dict) else None
182
+ if not isinstance(payload, dict):
183
+ return None
184
+ allowance, used, grants = payload.get("allowance"), payload.get("used"), payload.get("grants_remaining")
185
+ if not all(isinstance(value, int) for value in (allowance, used, grants)) or allowance == UNLIMITED:
186
+ return None
187
+ return max(allowance - used, 0) + grants
188
+
189
+
190
+ class UsageGuard:
191
+ """``UsageGuard(client, on_unavailable="allow", store=...)``; one per meter
192
+ policy. ``on_unavailable`` may also be a dict ``{meter_key: "allow"|"deny"}``
193
+ (default ``deny`` for a meter not named)."""
194
+
195
+ def __init__(
196
+ self,
197
+ client: Bucli,
198
+ *,
199
+ on_unavailable: str | dict[str, str] = DENY,
200
+ store: UsageStore | None = None,
201
+ timeout: float = 2.0,
202
+ cache_seconds: float = 300.0,
203
+ deny_when_exhausted: bool = True,
204
+ clock: Any = None,
205
+ ) -> None:
206
+ self.client = client
207
+ self.on_unavailable = on_unavailable
208
+ self.store = store or MemoryUsageStore()
209
+ self.timeout = timeout
210
+ self.cache_seconds = cache_seconds
211
+ self.deny_when_exhausted = deny_when_exhausted
212
+ self._now = clock or (lambda: datetime.datetime.now(datetime.UTC))
213
+
214
+ def policy(self, meter: str) -> str:
215
+ if isinstance(self.on_unavailable, dict):
216
+ return self.on_unavailable.get(meter, DENY)
217
+ return self.on_unavailable
218
+
219
+ def reserve(
220
+ self,
221
+ meter: str,
222
+ *,
223
+ customer: str,
224
+ idempotency_key: str,
225
+ quantity: int = 1,
226
+ billable: bool = True,
227
+ metadata: dict[str, Any] | None = None,
228
+ ) -> Reservation:
229
+ """Take ``quantity`` units of ``meter`` for ``customer``, or say why not."""
230
+ if billable and self.deny_when_exhausted:
231
+ cached = self.store.remaining(meter, customer, self.cache_seconds)
232
+ if cached is not None and cached != UNLIMITED and cached < quantity:
233
+ return Reservation(allowed=False, refusal="quota_exhausted", remaining=cached)
234
+ try:
235
+ record = self.client.meters.reserve(
236
+ meter,
237
+ customer=customer,
238
+ idempotency_key=idempotency_key,
239
+ quantity=quantity,
240
+ billable=billable,
241
+ metadata=metadata,
242
+ timeout=self.timeout,
243
+ max_retries=0,
244
+ )
245
+ except BillingError as error:
246
+ if error.code in REFUSALS:
247
+ left = _remaining_of_refusal(error) if error.code == "quota_exhausted" else None
248
+ self.store.remember(meter, customer, left)
249
+ return Reservation(allowed=False, refusal=error.code, remaining=left, error=error)
250
+ raise
251
+ except BucliError as error:
252
+ if not _unavailable(error) or self.policy(meter) != ALLOW:
253
+ raise
254
+ self.store.enqueue(
255
+ PendingUnit(
256
+ meter=meter,
257
+ customer=customer,
258
+ idempotency_key=idempotency_key,
259
+ quantity=quantity,
260
+ occurred_at=aware(self._now()),
261
+ billable=billable,
262
+ metadata=dict(metadata or {}),
263
+ )
264
+ )
265
+ return Reservation(allowed=True, offline=True, error=error)
266
+ remaining = getattr(record, "remaining", None)
267
+ self.store.remember(meter, customer, remaining)
268
+ return Reservation(allowed=True, record=record, remaining=remaining)
269
+
270
+ def release(self, usage_id: str) -> BucliObject:
271
+ """Give a unit back (``POST /v1/usage/{id}/release``); the cached
272
+ balance of its customer is dropped."""
273
+ record = self.client.usage.release(usage_id)
274
+ meter, customer = getattr(record, "meter", None), getattr(record, "customer", None)
275
+ if isinstance(meter, str) and isinstance(customer, str):
276
+ self.store.forget(meter, customer)
277
+ return record
278
+
279
+ def discard(self, meter: str, *, customer: str, idempotency_key: str) -> bool:
280
+ """Drop a unit let through offline that never happened after all (the
281
+ document was not sent): it is not reported. Whether it was queued."""
282
+ return self.store.discard(meter, customer, idempotency_key)
283
+
284
+ def forget(self, customer: str, meter: str | None = None) -> None:
285
+ """Drop the cached balance (a grant bought, a plan changed)."""
286
+ self.store.forget(meter, customer)
287
+
288
+ def flush(self, limit: int = 200) -> dict[str, int]:
289
+ """Report the queued units to Bucli. Returns ``{"reported", "failed"}``;
290
+ what fails stays queued for the next flush."""
291
+ reported = failed = 0
292
+ for unit in self.store.pending(limit):
293
+ try:
294
+ self.client.usage.report(
295
+ meter=unit.meter,
296
+ customer=unit.customer,
297
+ idempotency_key=unit.idempotency_key,
298
+ quantity=unit.quantity,
299
+ occurred_at=aware(unit.occurred_at),
300
+ billable=unit.billable,
301
+ metadata=unit.metadata or None,
302
+ )
303
+ except BucliError as error:
304
+ failed += 1
305
+ if _unavailable(error):
306
+ break # still down: nothing is the units' fault; they wait for the next flush
307
+ self._refused(unit, f"{type(error).__name__}: {error.code or error}")
308
+ continue
309
+ except (TypeError, ValueError) as error: # a unit that cannot be sent: never block the rest
310
+ failed += 1
311
+ self._refused(unit, f"{type(error).__name__}: {error}")
312
+ continue
313
+ self.store.done(unit)
314
+ self.store.forget(unit.meter, unit.customer)
315
+ reported += 1
316
+ return {"reported": reported, "failed": failed}
317
+
318
+ def _refused(self, unit: PendingUnit, error: str) -> None:
319
+ """Bucli refused a report (not an outage): one attempt spent; past the
320
+ cap the unit stays stored but out of the flush, and it is logged."""
321
+ self.store.failed(unit, error)
322
+ if unit.attempts >= getattr(self.store, "max_attempts", MAX_REPORT_ATTEMPTS):
323
+ logger.error(
324
+ "Bucli refused the report of a metered unit too many times (%s, %s, %s): %s",
325
+ unit.meter,
326
+ unit.customer,
327
+ unit.idempotency_key,
328
+ error,
329
+ )
330
+ else:
331
+ logger.warning("Bucli refused the report of a metered unit (%s): %s", unit.idempotency_key, error)
bucli/objects.py ADDED
@@ -0,0 +1,168 @@
1
+ """API objects: plain dicts that also read by attribute (``sub.status``).
2
+
3
+ ``BucliObject`` IS the dict the API answered (``json.dumps(obj)`` works,
4
+ ``obj["status"]`` works); nested objects and lists are converted on the way
5
+ in. A key that clashes with a dict method must be read with brackets — the
6
+ one that matters is a subscription's ``sub["items"]`` (``sub.items`` is
7
+ ``dict.items``).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from collections.abc import Iterator
13
+ from typing import TYPE_CHECKING, Any
14
+ from urllib.parse import parse_qsl, urlsplit
15
+
16
+ if TYPE_CHECKING:
17
+ from bucli.client import Bucli
18
+
19
+
20
+ class LastResponse:
21
+ """What the HTTP answer said besides its body."""
22
+
23
+ __slots__ = ("headers", "http_status", "idempotency_key", "request_id")
24
+
25
+ def __init__(self, http_status: int, headers: dict[str, str], idempotency_key: str | None = None) -> None:
26
+ self.http_status = http_status
27
+ self.headers = headers
28
+ self.request_id = headers.get("Request-Id")
29
+ self.idempotency_key = idempotency_key
30
+
31
+ @property
32
+ def replayed(self) -> bool:
33
+ """``True`` when Bucli answered a stored response for the same ``Idempotency-Key``."""
34
+ return self.headers.get("Idempotent-Replayed", "").lower() == "true"
35
+
36
+ def __repr__(self) -> str:
37
+ return f"LastResponse(http_status={self.http_status}, request_id={self.request_id!r})"
38
+
39
+
40
+ class BucliObject(dict):
41
+ """An object of the API (``customer``, ``subscription``…)."""
42
+
43
+ def __init__(self, *args: Any, **kwargs: Any) -> None:
44
+ super().__init__(*args, **kwargs)
45
+ object.__setattr__(self, "_client", None)
46
+ object.__setattr__(self, "last_response", None)
47
+
48
+ # -- attribute access -----------------------------------------------------
49
+
50
+ def __getattr__(self, name: str) -> Any:
51
+ if name.startswith("__"):
52
+ raise AttributeError(name)
53
+ try:
54
+ return self[name]
55
+ except KeyError:
56
+ raise AttributeError(f"{type(self).__name__} no tiene el campo {name!r}") from None
57
+
58
+ def __setattr__(self, name: str, value: Any) -> None:
59
+ if name.startswith("_") or name == "last_response":
60
+ object.__setattr__(self, name, value)
61
+ else:
62
+ self[name] = value
63
+
64
+ def __delattr__(self, name: str) -> None:
65
+ try:
66
+ del self[name]
67
+ except KeyError:
68
+ raise AttributeError(name) from None
69
+
70
+ def __repr__(self) -> str:
71
+ ident = self.get("id")
72
+ kind = self.get("object", type(self).__name__)
73
+ head = f"<{kind} {ident}>" if ident else f"<{kind}>"
74
+ return f"{head} {dict.__repr__(self)}"
75
+
76
+ def __reduce__(self) -> Any:
77
+ return (type(self), (dict(self),))
78
+
79
+ # -- conversion -------------------------------------------------------------
80
+
81
+ @classmethod
82
+ def construct_from(cls, value: Any, client: Bucli | None = None) -> Any:
83
+ """Converts the JSON the API answered (dicts become objects, lists stay lists)."""
84
+ return convert(value, client)
85
+
86
+ def to_dict(self) -> dict[str, Any]:
87
+ """A deep copy made only of plain ``dict``/``list`` (for storing or serializing)."""
88
+ return _plain(self)
89
+
90
+
91
+ class ListObject(BucliObject):
92
+ """``{"object": "list", "data": [...], "has_more": bool, "url": "/v1/..."}``."""
93
+
94
+ def __init__(self, *args: Any, **kwargs: Any) -> None:
95
+ super().__init__(*args, **kwargs)
96
+ object.__setattr__(self, "_path", None)
97
+ object.__setattr__(self, "_params", {})
98
+
99
+ @property
100
+ def data(self) -> list[Any]:
101
+ return self.get("data") or []
102
+
103
+ @property
104
+ def has_more(self) -> bool:
105
+ return bool(self.get("has_more"))
106
+
107
+ def is_empty(self) -> bool:
108
+ return not self.data
109
+
110
+ def _source(self) -> tuple[str, dict[str, Any]]:
111
+ if self._path:
112
+ return self._path, dict(self._params)
113
+ parts = urlsplit(self.get("url") or "")
114
+ path = parts.path
115
+ if path.startswith("/v1/"):
116
+ path = path[len("/v1") :]
117
+ return path, dict(parse_qsl(parts.query))
118
+
119
+ def next_page(self) -> ListObject:
120
+ """The page after this one (``starting_after`` = the last id)."""
121
+ path, params = self._source()
122
+ params.pop("ending_before", None)
123
+ params["starting_after"] = self.data[-1]["id"]
124
+ return self._client._get_list(path, params)
125
+
126
+ def previous_page(self) -> ListObject:
127
+ """The page before this one (``ending_before`` = the first id)."""
128
+ path, params = self._source()
129
+ params.pop("starting_after", None)
130
+ params["ending_before"] = self.data[0]["id"]
131
+ return self._client._get_list(path, params)
132
+
133
+ def auto_paging_iter(self) -> Iterator[Any]:
134
+ """Every object from this page on, fetching the next pages as needed.
135
+
136
+ A page fetched with ``ending_before`` walks backwards (towards newer
137
+ objects), as Stripe's does."""
138
+ if self._client is None:
139
+ yield from self.data
140
+ return
141
+ _, params = self._source()
142
+ backwards = "ending_before" in params and "starting_after" not in params
143
+ page: ListObject = self
144
+ while True:
145
+ items = list(reversed(page.data)) if backwards else page.data
146
+ yield from items
147
+ if not page.has_more or not page.data:
148
+ return
149
+ page = page.previous_page() if backwards else page.next_page()
150
+
151
+
152
+ def convert(value: Any, client: Bucli | None = None) -> Any:
153
+ if isinstance(value, dict) and not isinstance(value, BucliObject):
154
+ cls = ListObject if value.get("object") == "list" else BucliObject
155
+ obj = cls({key: convert(item, client) for key, item in value.items()})
156
+ object.__setattr__(obj, "_client", client)
157
+ return obj
158
+ if isinstance(value, list):
159
+ return [convert(item, client) for item in value]
160
+ return value
161
+
162
+
163
+ def _plain(value: Any) -> Any:
164
+ if isinstance(value, dict):
165
+ return {key: _plain(item) for key, item in value.items()}
166
+ if isinstance(value, list):
167
+ return [_plain(item) for item in value]
168
+ return value
bucli/py.typed ADDED
File without changes