qodalis-cli-server-plugin-public-api 1.0.0b29__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.
- qodalis_cli_public_api/__init__.py +30 -0
- qodalis_cli_public_api/cli_public_api_builder.py +530 -0
- qodalis_cli_public_api/headers_middleware.py +40 -0
- qodalis_cli_public_api/openapi.py +148 -0
- qodalis_cli_public_api/quota.py +26 -0
- qodalis_cli_public_api/swagger_ui/LICENSE +202 -0
- qodalis_cli_public_api/swagger_ui/NOTICE +2 -0
- qodalis_cli_public_api/swagger_ui/favicon-32x32.png +0 -0
- qodalis_cli_public_api/swagger_ui/swagger-ui-bundle.js +2 -0
- qodalis_cli_public_api/swagger_ui/swagger-ui-bundle.js.LICENSE.txt +131 -0
- qodalis_cli_public_api/swagger_ui/swagger-ui.css +3 -0
- qodalis_cli_public_api/swagger_ui.py +67 -0
- qodalis_cli_public_api/usage_service.py +137 -0
- qodalis_cli_public_api/usage_store.py +99 -0
- qodalis_cli_server_plugin_public_api-1.0.0b29.dist-info/METADATA +23 -0
- qodalis_cli_server_plugin_public_api-1.0.0b29.dist-info/RECORD +18 -0
- qodalis_cli_server_plugin_public_api-1.0.0b29.dist-info/WHEEL +4 -0
- qodalis_cli_server_plugin_public_api-1.0.0b29.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Qodalis CLI public-api plugin — a host's public REST API: routes guarded by
|
|
2
|
+
``host`` API tokens with per-account quotas (``X-RateLimit-*`` headers),
|
|
3
|
+
usage per token, the public OpenAPI document and Swagger UI."""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
#: The package's icon on the admin dashboard's plugins page (``CliInstalledPlugin.icon``).
|
|
8
|
+
__plugin_icon__ = "🔑"
|
|
9
|
+
|
|
10
|
+
from .cli_public_api_builder import (
|
|
11
|
+
DEFAULT_BASE_PATH,
|
|
12
|
+
CliPublicApiBuilder,
|
|
13
|
+
CliPublicApiPlugin,
|
|
14
|
+
)
|
|
15
|
+
from .quota import PublicApiQuota, QuotaResolver
|
|
16
|
+
from .usage_service import PublicApiAccountUsage, PublicApiTokenUsage, PublicApiUsageService
|
|
17
|
+
from .usage_store import InMemoryPublicApiUsageStore, IPublicApiUsageStore
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"CliPublicApiBuilder",
|
|
21
|
+
"CliPublicApiPlugin",
|
|
22
|
+
"DEFAULT_BASE_PATH",
|
|
23
|
+
"IPublicApiUsageStore",
|
|
24
|
+
"InMemoryPublicApiUsageStore",
|
|
25
|
+
"PublicApiAccountUsage",
|
|
26
|
+
"PublicApiQuota",
|
|
27
|
+
"PublicApiTokenUsage",
|
|
28
|
+
"PublicApiUsageService",
|
|
29
|
+
"QuotaResolver",
|
|
30
|
+
]
|
|
@@ -0,0 +1,530 @@
|
|
|
1
|
+
"""Fluent builder for the public-api plugin.
|
|
2
|
+
|
|
3
|
+
Usage::
|
|
4
|
+
|
|
5
|
+
users_plugin = CliUsersBuilder().build()
|
|
6
|
+
public_api = (
|
|
7
|
+
CliPublicApiBuilder()
|
|
8
|
+
.set_users(users_plugin)
|
|
9
|
+
.set_quota(lambda caller: PublicApiQuota(requests_per_day=1000, requests_per_minute=60))
|
|
10
|
+
.build()
|
|
11
|
+
)
|
|
12
|
+
result.mount_plugin(users_plugin)
|
|
13
|
+
result.mount_plugin(public_api)
|
|
14
|
+
|
|
15
|
+
@result.app.get("/v1/rates")
|
|
16
|
+
async def rates(caller: QcliCaller = Depends(public_api.guard("rates:read"))):
|
|
17
|
+
...
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
import asyncio
|
|
23
|
+
import json
|
|
24
|
+
import logging
|
|
25
|
+
import math
|
|
26
|
+
import os
|
|
27
|
+
import weakref
|
|
28
|
+
from dataclasses import dataclass, field
|
|
29
|
+
from datetime import datetime, timedelta, timezone
|
|
30
|
+
from typing import Any, Callable, Optional
|
|
31
|
+
|
|
32
|
+
import anyio
|
|
33
|
+
from fastapi import APIRouter, Request
|
|
34
|
+
from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
|
|
35
|
+
|
|
36
|
+
from qodalis_cli_users import QcliCaller, QcliGuardError
|
|
37
|
+
from qodalis_cli_users.errors import install_guard_error_handler
|
|
38
|
+
from qodalis_cli_users.middleware.auth_middleware import authenticate_host_token, tag_guard
|
|
39
|
+
|
|
40
|
+
from .headers_middleware import STATE_KEY, RateLimitHeadersMiddleware
|
|
41
|
+
from .openapi import PublicOpenApiDocument, check_source
|
|
42
|
+
from .swagger_ui import ASSETS as SWAGGER_ASSETS
|
|
43
|
+
from .swagger_ui import ASSETS_DIR as SWAGGER_ASSETS_DIR
|
|
44
|
+
from .swagger_ui import is_root_relative, swagger_html
|
|
45
|
+
from .quota import PublicApiQuota, QuotaResolver
|
|
46
|
+
from .usage_service import (
|
|
47
|
+
PublicApiUsageService,
|
|
48
|
+
day_window,
|
|
49
|
+
minute_window,
|
|
50
|
+
resolve_quota,
|
|
51
|
+
utc_now,
|
|
52
|
+
)
|
|
53
|
+
from .usage_store import InMemoryPublicApiUsageStore, IPublicApiUsageStore
|
|
54
|
+
|
|
55
|
+
logger = logging.getLogger(__name__)
|
|
56
|
+
|
|
57
|
+
DEFAULT_BASE_PATH = "/qcli/api"
|
|
58
|
+
DEFAULT_TITLE = "API reference"
|
|
59
|
+
DEFAULT_RETENTION_DAYS = 31
|
|
60
|
+
#: Minute windows are kept this long (the current one and the one before).
|
|
61
|
+
MINUTE_RETENTION = timedelta(minutes=2)
|
|
62
|
+
PRUNE_INTERVAL = timedelta(hours=1)
|
|
63
|
+
|
|
64
|
+
INTERNAL_ERROR = "internal server error"
|
|
65
|
+
NO_API_ACCESS = "forbidden: no API access"
|
|
66
|
+
USERS_REQUIRED = "public-api: set_users(users_plugin) is required"
|
|
67
|
+
#: ``request.state`` flag: the request was admitted (counted) by a guard.
|
|
68
|
+
COUNTED_KEY = "qcli_public_api_counted"
|
|
69
|
+
SWAGGER_ASSETS_TEXT = "public-api: Swagger UI assets must be root-relative paths"
|
|
70
|
+
NOT_FOUND = "not found"
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def validate_base_path(path: Any, label: str) -> str:
|
|
74
|
+
"""A mount path: starts with ``/``, no trailing ``/``, not ``/`` itself."""
|
|
75
|
+
if (
|
|
76
|
+
not isinstance(path, str)
|
|
77
|
+
or not path.startswith("/")
|
|
78
|
+
or path == "/"
|
|
79
|
+
or path.endswith("/")
|
|
80
|
+
or any(c.isspace() or ord(c) < 0x20 or c in "?#\\" for c in path)
|
|
81
|
+
or "//" in path
|
|
82
|
+
):
|
|
83
|
+
raise ValueError(f"invalid {label} base path: {path}")
|
|
84
|
+
return path
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
INVALID_PATH_BASE = "invalid path base"
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def path_base(request: Request) -> str | None:
|
|
91
|
+
"""The ASGI root path (no trailing ``/``), or ``None`` when it would make
|
|
92
|
+
a URL leave the host: it starts with two slashes or a slash and a
|
|
93
|
+
backslash, or holds whitespace or control characters (browsers drop them,
|
|
94
|
+
so a slash, a tab and a slash become ``//``)."""
|
|
95
|
+
root = request.scope.get("root_path", "") or ""
|
|
96
|
+
if root.startswith("//") or root.startswith("/\\") or any(c.isspace() or ord(c) < 0x20 or 0x7F <= ord(c) <= 0x9F for c in root):
|
|
97
|
+
return None
|
|
98
|
+
return root.rstrip("/")
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def invalid_path_base() -> Response:
|
|
102
|
+
return JSONResponse({"error": INVALID_PATH_BASE}, status_code=400)
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _drop_caller(request: Request) -> None:
|
|
106
|
+
"""A later stacked guard refused: the request has no caller."""
|
|
107
|
+
state = request.scope.get("state")
|
|
108
|
+
if isinstance(state, dict):
|
|
109
|
+
state.pop("qcli_caller", None)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _stacked_permissions(request: Request) -> list[str]:
|
|
113
|
+
"""Permissions of every tagged guard of the matched route (public-api
|
|
114
|
+
guards and the users plugin's ``require_permission`` /
|
|
115
|
+
``require_host_token``; FastAPI puts the route in ``scope["route"]``),
|
|
116
|
+
so the first public-api guard to run refuses a request another guard
|
|
117
|
+
would refuse before counting it. Empty when the route is not known."""
|
|
118
|
+
route = request.scope.get("route")
|
|
119
|
+
stack = list(getattr(getattr(route, "dependant", None), "dependencies", None) or [])
|
|
120
|
+
found: list[str] = []
|
|
121
|
+
while stack:
|
|
122
|
+
dep = stack.pop(0)
|
|
123
|
+
call = getattr(dep, "call", None)
|
|
124
|
+
if hasattr(call, "qcli_host_token_only"):
|
|
125
|
+
permission = getattr(call, "qcli_permission", None)
|
|
126
|
+
if permission and permission not in found:
|
|
127
|
+
found.append(permission)
|
|
128
|
+
stack.extend(getattr(dep, "dependencies", None) or [])
|
|
129
|
+
return found
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _seconds_until(now: datetime, then: datetime) -> int:
|
|
133
|
+
return max(1, math.ceil((then - now).total_seconds()))
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def seconds_to_next_day(now: datetime) -> int:
|
|
137
|
+
midnight = datetime(now.year, now.month, now.day, tzinfo=timezone.utc) + timedelta(days=1)
|
|
138
|
+
return _seconds_until(now, midnight)
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def seconds_to_next_minute(now: datetime) -> int:
|
|
142
|
+
return _seconds_until(now, now.replace(second=0, microsecond=0) + timedelta(minutes=1))
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
@dataclass
|
|
146
|
+
class CliPublicApiPlugin:
|
|
147
|
+
"""The built public-api plugin: mount it with
|
|
148
|
+
``CliServerResult.mount_plugin`` (after the users plugin), then guard
|
|
149
|
+
the host's public routes with :meth:`guard`."""
|
|
150
|
+
|
|
151
|
+
prefix: str
|
|
152
|
+
router: APIRouter
|
|
153
|
+
#: Usage of tokens and accounts (``await usage.account(user_id)``).
|
|
154
|
+
usage: PublicApiUsageService
|
|
155
|
+
#: What the portal plugin shows (``CliPortalBuilder().add_section(...)``).
|
|
156
|
+
portal_section: dict[str, str]
|
|
157
|
+
store: IPublicApiUsageStore
|
|
158
|
+
users: Any
|
|
159
|
+
#: The public OpenAPI document (``<prefix>/openapi.json``).
|
|
160
|
+
document: PublicOpenApiDocument
|
|
161
|
+
title: str = DEFAULT_TITLE
|
|
162
|
+
#: Host routes: never counted among the CLI's routes.
|
|
163
|
+
cli_routes: bool = False
|
|
164
|
+
#: The document and Swagger UI are served without sign-in, also under
|
|
165
|
+
#: ``/api/`` on a protected server (the guarded routes are elsewhere).
|
|
166
|
+
public_paths: list[str] = field(default_factory=list)
|
|
167
|
+
quota_resolver: Optional[QuotaResolver] = None
|
|
168
|
+
retention_days: int = DEFAULT_RETENTION_DAYS
|
|
169
|
+
clock: Callable[[], datetime] = field(default=lambda: datetime.now(timezone.utc))
|
|
170
|
+
_last_prune: Optional[datetime] = field(default=None, repr=False)
|
|
171
|
+
_account_locks: Any = field(default_factory=weakref.WeakValueDictionary, repr=False)
|
|
172
|
+
|
|
173
|
+
def guard(self, permission: str | None = None) -> Any:
|
|
174
|
+
"""FastAPI dependency for a public route: a ``host`` API token
|
|
175
|
+
holding ``permission`` (when given), within the account's quota.
|
|
176
|
+
Returns the :class:`QcliCaller` (also ``request.state.qcli_caller``).
|
|
177
|
+
|
|
178
|
+
Refusals, in order: the users plugin's authentication texts (401 /
|
|
179
|
+
403), 403 ``forbidden: a host token is required``, 403
|
|
180
|
+
``forbidden: missing permission <permission>``, 500 ``internal
|
|
181
|
+
server error`` (the quota resolver failed), 403 ``forbidden: no API
|
|
182
|
+
access`` (a limit of 0), 429 per day, then per minute. Nothing is
|
|
183
|
+
counted for a refused request."""
|
|
184
|
+
users = self.users
|
|
185
|
+
# The caller is exposed only once the guard fully passed.
|
|
186
|
+
authenticate = getattr(users, "authenticate", None) or users.require_auth
|
|
187
|
+
|
|
188
|
+
async def dependency(request: Request) -> QcliCaller:
|
|
189
|
+
try:
|
|
190
|
+
return await check(request)
|
|
191
|
+
except QcliGuardError:
|
|
192
|
+
# A refused request has no caller, also when a users guard
|
|
193
|
+
# that ran first on the route had set one.
|
|
194
|
+
_drop_caller(request)
|
|
195
|
+
raise
|
|
196
|
+
|
|
197
|
+
async def check(request: Request) -> QcliCaller:
|
|
198
|
+
ctx = await authenticate_host_token(authenticate, request)
|
|
199
|
+
# Stacked guards (a router's and a route's): the first one checks
|
|
200
|
+
# every stacked guard's permission, then counts the request once;
|
|
201
|
+
# the others check only their own permission.
|
|
202
|
+
counted = getattr(request.state, COUNTED_KEY, False)
|
|
203
|
+
required = [permission] if counted else [permission, *_stacked_permissions(request)]
|
|
204
|
+
for needed in required:
|
|
205
|
+
if needed and not ctx.can(needed):
|
|
206
|
+
if counted:
|
|
207
|
+
setattr(request.state, STATE_KEY, None)
|
|
208
|
+
raise QcliGuardError(403, f"forbidden: missing permission {needed}")
|
|
209
|
+
caller = ctx.caller
|
|
210
|
+
if counted:
|
|
211
|
+
return caller
|
|
212
|
+
headers = await self._admit(caller)
|
|
213
|
+
setattr(request.state, COUNTED_KEY, True)
|
|
214
|
+
if headers:
|
|
215
|
+
setattr(request.state, STATE_KEY, headers)
|
|
216
|
+
request.state.qcli_caller = caller
|
|
217
|
+
return caller
|
|
218
|
+
|
|
219
|
+
dependency.qcli_public_api = True
|
|
220
|
+
return tag_guard(dependency, permission, True)
|
|
221
|
+
|
|
222
|
+
def _account_lock(self, user_id: str) -> asyncio.Lock:
|
|
223
|
+
lock = self._account_locks.get(user_id)
|
|
224
|
+
if lock is None:
|
|
225
|
+
lock = asyncio.Lock()
|
|
226
|
+
self._account_locks[user_id] = lock
|
|
227
|
+
return lock
|
|
228
|
+
|
|
229
|
+
async def _admit(self, caller: QcliCaller) -> dict[str, str]:
|
|
230
|
+
"""Count the request or refuse it (C5 rows 4-7); returns the
|
|
231
|
+
``X-RateLimit-*`` headers of an admitted request."""
|
|
232
|
+
try:
|
|
233
|
+
quota = await resolve_quota(self.quota_resolver, caller)
|
|
234
|
+
except Exception:
|
|
235
|
+
logger.exception("public-api: the quota resolver failed")
|
|
236
|
+
raise QcliGuardError(500, INTERNAL_ERROR) from None
|
|
237
|
+
per_day, per_minute = quota.requests_per_day, quota.requests_per_minute
|
|
238
|
+
if (per_day is not None and per_day <= 0) or (per_minute is not None and per_minute <= 0):
|
|
239
|
+
raise QcliGuardError(403, NO_API_ACCESS)
|
|
240
|
+
|
|
241
|
+
now = utc_now(self.clock)
|
|
242
|
+
day, minute = day_window(now), minute_window(now)
|
|
243
|
+
token_id = caller.token_id or ""
|
|
244
|
+
store = self.store
|
|
245
|
+
#: Windows incremented so far (taken back when the store fails).
|
|
246
|
+
incremented: list[str] = []
|
|
247
|
+
try:
|
|
248
|
+
# One admission at a time per account in this process: exactly the
|
|
249
|
+
# limit here; across processes the compensation keeps the count at
|
|
250
|
+
# or under it.
|
|
251
|
+
lock = self._account_lock(caller.user_id)
|
|
252
|
+
async with lock:
|
|
253
|
+
for window in (day, minute):
|
|
254
|
+
await store.increment(token_id, caller.user_id, window)
|
|
255
|
+
incremented.append(window)
|
|
256
|
+
day_count = await store.account_count(caller.user_id, day) if per_day is not None else 0
|
|
257
|
+
minute_count = await store.account_count(caller.user_id, minute) if per_minute is not None else 0
|
|
258
|
+
exceeded = None
|
|
259
|
+
if per_day is not None and day_count > per_day:
|
|
260
|
+
exceeded = "day"
|
|
261
|
+
elif per_minute is not None and minute_count > per_minute:
|
|
262
|
+
exceeded = "minute"
|
|
263
|
+
if exceeded is not None:
|
|
264
|
+
while incremented:
|
|
265
|
+
await store.decrement(token_id, incremented[-1])
|
|
266
|
+
incremented.pop()
|
|
267
|
+
# Inside the handling below: a cancellation while pruning takes
|
|
268
|
+
# the counts back too.
|
|
269
|
+
await self._maybe_prune(now)
|
|
270
|
+
except anyio.get_cancelled_exc_class():
|
|
271
|
+
# The request was cancelled (the client went away): not counted.
|
|
272
|
+
# Shielded, so the take-back's own awaits are not cancelled.
|
|
273
|
+
with anyio.CancelScope(shield=True):
|
|
274
|
+
await self._take_back(token_id, incremented)
|
|
275
|
+
raise
|
|
276
|
+
except Exception:
|
|
277
|
+
logger.exception("public-api: the usage store failed")
|
|
278
|
+
# The request is not served: take back what was counted (best effort).
|
|
279
|
+
await self._take_back(token_id, incremented)
|
|
280
|
+
raise QcliGuardError(500, INTERNAL_ERROR) from None
|
|
281
|
+
|
|
282
|
+
headers: dict[str, str] = {}
|
|
283
|
+
if per_day is not None:
|
|
284
|
+
limit, count, reset = per_day, day_count, seconds_to_next_day(now)
|
|
285
|
+
elif per_minute is not None:
|
|
286
|
+
limit, count, reset = per_minute, minute_count, seconds_to_next_minute(now)
|
|
287
|
+
else:
|
|
288
|
+
limit = None
|
|
289
|
+
if limit is not None:
|
|
290
|
+
headers = {
|
|
291
|
+
"X-RateLimit-Limit": str(limit),
|
|
292
|
+
"X-RateLimit-Remaining": str(0 if exceeded else max(0, limit - count)),
|
|
293
|
+
"X-RateLimit-Reset": str(reset),
|
|
294
|
+
}
|
|
295
|
+
if exceeded == "day":
|
|
296
|
+
headers["Retry-After"] = str(seconds_to_next_day(now))
|
|
297
|
+
raise QcliGuardError(429, f"quota exceeded: {per_day} requests per day", headers)
|
|
298
|
+
if exceeded == "minute":
|
|
299
|
+
headers["Retry-After"] = str(seconds_to_next_minute(now))
|
|
300
|
+
raise QcliGuardError(429, f"too many requests: {per_minute} per minute", headers)
|
|
301
|
+
return headers
|
|
302
|
+
|
|
303
|
+
async def _take_back(self, token_id: str, windows: list[str]) -> None:
|
|
304
|
+
"""Decrement every window, also when the task is cancelled (natively)
|
|
305
|
+
meanwhile: an interrupted decrement is retried (at most three times)
|
|
306
|
+
and the cancellation is raised again once all are done."""
|
|
307
|
+
# The retry assumes a decrement either applied or did not: a store that
|
|
308
|
+
# applies it and is then cancelled before returning is decremented
|
|
309
|
+
# twice for that window (its counters floor at 0).
|
|
310
|
+
cancelled: BaseException | None = None
|
|
311
|
+
for window in reversed(windows):
|
|
312
|
+
for _ in range(3):
|
|
313
|
+
try:
|
|
314
|
+
await self.store.decrement(token_id, window)
|
|
315
|
+
break
|
|
316
|
+
except Exception:
|
|
317
|
+
logger.exception("public-api: taking back a request count failed")
|
|
318
|
+
break
|
|
319
|
+
except BaseException as exc: # cancellation: finish first
|
|
320
|
+
cancelled = exc
|
|
321
|
+
windows.clear()
|
|
322
|
+
if cancelled is not None:
|
|
323
|
+
raise cancelled
|
|
324
|
+
|
|
325
|
+
async def _maybe_prune(self, now: datetime) -> None:
|
|
326
|
+
if self._last_prune is not None and now - self._last_prune < PRUNE_INTERVAL:
|
|
327
|
+
return
|
|
328
|
+
self._last_prune = now
|
|
329
|
+
before_day = (now - timedelta(days=self.retention_days)).strftime("%Y-%m-%d")
|
|
330
|
+
before_minute = minute_window(now - MINUTE_RETENTION)
|
|
331
|
+
try:
|
|
332
|
+
await self.store.prune(before_day, before_minute)
|
|
333
|
+
except Exception:
|
|
334
|
+
logger.exception("public-api: pruning the usage store failed")
|
|
335
|
+
|
|
336
|
+
def on_mount(self, server: Any) -> None:
|
|
337
|
+
"""Hook called by ``CliServerResult.mount_plugin``: the token views
|
|
338
|
+
get ``usage``, refusals answer ``{"error": …}`` and admitted
|
|
339
|
+
requests carry their ``X-RateLimit-*`` headers."""
|
|
340
|
+
self.users.set_token_usage_provider(self.usage.tokens)
|
|
341
|
+
app = server.app
|
|
342
|
+
install_guard_error_handler(app)
|
|
343
|
+
if not any(getattr(m, "cls", None) is RateLimitHeadersMiddleware for m in app.user_middleware):
|
|
344
|
+
app.add_middleware(RateLimitHeadersMiddleware)
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
class CliPublicApiBuilder:
|
|
348
|
+
"""Fluent builder for the public-api plugin."""
|
|
349
|
+
|
|
350
|
+
def __init__(self) -> None:
|
|
351
|
+
self._users: Any = None
|
|
352
|
+
self._base_path: Any = DEFAULT_BASE_PATH
|
|
353
|
+
self._title = DEFAULT_TITLE
|
|
354
|
+
self._title_set = False
|
|
355
|
+
self._server_url: str | None = None
|
|
356
|
+
self._openapi: Any = None
|
|
357
|
+
self._quota: QuotaResolver | None = None
|
|
358
|
+
self._store: IPublicApiUsageStore | None = None
|
|
359
|
+
self._retention_days = DEFAULT_RETENTION_DAYS
|
|
360
|
+
self._clock: Callable[[], datetime] = lambda: datetime.now(timezone.utc)
|
|
361
|
+
self._version: str | None = None
|
|
362
|
+
#: ``None``: the vendored files under ``<base>/swagger/``.
|
|
363
|
+
self._swagger_js_url: str | None = None
|
|
364
|
+
self._swagger_css_url: str | None = None
|
|
365
|
+
|
|
366
|
+
def set_users(self, users_plugin: Any) -> CliPublicApiBuilder:
|
|
367
|
+
"""The users plugin whose tokens the guard accepts (required)."""
|
|
368
|
+
self._users = users_plugin
|
|
369
|
+
return self
|
|
370
|
+
|
|
371
|
+
def set_base_path(self, path: str) -> CliPublicApiBuilder:
|
|
372
|
+
"""Where the OpenAPI document and Swagger UI are served (default
|
|
373
|
+
``/qcli/api``): starts with ``/``, no trailing ``/``, not ``/``."""
|
|
374
|
+
self._base_path = path
|
|
375
|
+
return self
|
|
376
|
+
|
|
377
|
+
def set_title(self, title: str) -> CliPublicApiBuilder:
|
|
378
|
+
"""The portal's label of the API section (default ``API reference``).
|
|
379
|
+
A document read from an app or a router also takes it as
|
|
380
|
+
``info.title`` (default ``API``); a ``dict`` keeps its own."""
|
|
381
|
+
self._title = title
|
|
382
|
+
self._title_set = True
|
|
383
|
+
return self
|
|
384
|
+
|
|
385
|
+
def set_version(self, version: str) -> CliPublicApiBuilder:
|
|
386
|
+
"""``info.version`` of a document read from an app or a router
|
|
387
|
+
(default ``1.0.0``)."""
|
|
388
|
+
self._version = version
|
|
389
|
+
return self
|
|
390
|
+
|
|
391
|
+
def set_swagger_assets(self, js_url: str, css_url: str) -> CliPublicApiBuilder:
|
|
392
|
+
"""Swagger UI's script and stylesheet, served by the host itself
|
|
393
|
+
(default: the copies vendored in this package, under
|
|
394
|
+
``<base>/swagger/``). Root-relative paths only: the page never loads
|
|
395
|
+
anything from another origin."""
|
|
396
|
+
if not (is_root_relative(js_url) and is_root_relative(css_url)):
|
|
397
|
+
raise ValueError(SWAGGER_ASSETS_TEXT)
|
|
398
|
+
self._swagger_js_url = js_url
|
|
399
|
+
self._swagger_css_url = css_url
|
|
400
|
+
return self
|
|
401
|
+
|
|
402
|
+
def set_server_url(self, url: str | None) -> CliPublicApiBuilder:
|
|
403
|
+
"""The document's ``servers`` URL (default: the request's
|
|
404
|
+
``scheme://host`` and root path)."""
|
|
405
|
+
self._server_url = url
|
|
406
|
+
return self
|
|
407
|
+
|
|
408
|
+
def set_openapi(self, source: Any) -> CliPublicApiBuilder:
|
|
409
|
+
"""The public OpenAPI document: a ``dict``, a zero-argument callable
|
|
410
|
+
returning one (called per request), a ``FastAPI`` app or an
|
|
411
|
+
``APIRouter`` (its routes, read on the first request; routes with
|
|
412
|
+
``include_in_schema=False`` are left out)."""
|
|
413
|
+
self._openapi = check_source(source)
|
|
414
|
+
return self
|
|
415
|
+
|
|
416
|
+
def set_quota(self, resolver: QuotaResolver | None) -> CliPublicApiBuilder:
|
|
417
|
+
"""``resolver(caller)`` returns the account's
|
|
418
|
+
:class:`PublicApiQuota` (sync or async); without one the API is
|
|
419
|
+
unlimited."""
|
|
420
|
+
if resolver is not None and not callable(resolver):
|
|
421
|
+
raise TypeError("quota resolver must be callable")
|
|
422
|
+
self._quota = resolver
|
|
423
|
+
return self
|
|
424
|
+
|
|
425
|
+
def set_usage_store(self, store: IPublicApiUsageStore) -> CliPublicApiBuilder:
|
|
426
|
+
"""Where the counters live (default in memory, one process)."""
|
|
427
|
+
self._store = store
|
|
428
|
+
return self
|
|
429
|
+
|
|
430
|
+
def set_usage_retention_days(self, days: int) -> CliPublicApiBuilder:
|
|
431
|
+
"""Days the per-day counters are kept (default 31)."""
|
|
432
|
+
if isinstance(days, bool) or not isinstance(days, int) or days < 1:
|
|
433
|
+
raise ValueError("usage retention days must be a positive integer")
|
|
434
|
+
self._retention_days = days
|
|
435
|
+
return self
|
|
436
|
+
|
|
437
|
+
def set_clock(self, now: Callable[[], datetime]) -> CliPublicApiBuilder:
|
|
438
|
+
"""The clock (tests); read in UTC."""
|
|
439
|
+
self._clock = now
|
|
440
|
+
return self
|
|
441
|
+
|
|
442
|
+
def build(self) -> CliPublicApiPlugin:
|
|
443
|
+
if self._users is None:
|
|
444
|
+
raise ValueError(USERS_REQUIRED)
|
|
445
|
+
base_path = validate_base_path(self._base_path, "public-api")
|
|
446
|
+
store = self._store or InMemoryPublicApiUsageStore()
|
|
447
|
+
holder: dict[str, CliPublicApiPlugin] = {}
|
|
448
|
+
usage = PublicApiUsageService(
|
|
449
|
+
self._users,
|
|
450
|
+
store=lambda: holder["plugin"].store,
|
|
451
|
+
resolver=lambda: holder["plugin"].quota_resolver,
|
|
452
|
+
clock=lambda: holder["plugin"].clock(),
|
|
453
|
+
)
|
|
454
|
+
plugin = CliPublicApiPlugin(
|
|
455
|
+
prefix=base_path,
|
|
456
|
+
router=APIRouter(),
|
|
457
|
+
usage=usage,
|
|
458
|
+
portal_section={"kind": "api", "title": self._title, "base_path": base_path},
|
|
459
|
+
store=store,
|
|
460
|
+
users=self._users,
|
|
461
|
+
document=PublicOpenApiDocument(
|
|
462
|
+
self._openapi,
|
|
463
|
+
title=self._title if self._title_set else None,
|
|
464
|
+
version=self._version,
|
|
465
|
+
server_url=self._server_url,
|
|
466
|
+
),
|
|
467
|
+
title=self._title,
|
|
468
|
+
quota_resolver=self._quota,
|
|
469
|
+
retention_days=self._retention_days,
|
|
470
|
+
clock=self._clock,
|
|
471
|
+
)
|
|
472
|
+
holder["plugin"] = plugin
|
|
473
|
+
plugin.router = self._router(plugin)
|
|
474
|
+
plugin.public_paths = [
|
|
475
|
+
f"{base_path}/openapi.json", f"{base_path}/swagger", f"{base_path}/swagger/", f"{base_path}/swagger/*",
|
|
476
|
+
]
|
|
477
|
+
return plugin
|
|
478
|
+
|
|
479
|
+
def _router(self, plugin: CliPublicApiPlugin) -> APIRouter:
|
|
480
|
+
router = APIRouter()
|
|
481
|
+
document = plugin.document
|
|
482
|
+
js_url, css_url = self._swagger_js_url, self._swagger_css_url
|
|
483
|
+
|
|
484
|
+
def base_url(request: Request) -> str:
|
|
485
|
+
# Includes the ASGI root path (an app mounted under a prefix).
|
|
486
|
+
return str(request.base_url).rstrip("/")
|
|
487
|
+
|
|
488
|
+
@router.api_route("/openapi.json", methods=["GET", "HEAD"], include_in_schema=False)
|
|
489
|
+
async def openapi_json(request: Request) -> Response:
|
|
490
|
+
if path_base(request) is None:
|
|
491
|
+
return invalid_path_base()
|
|
492
|
+
body = json.dumps(document.build(base_url(request)), ensure_ascii=False)
|
|
493
|
+
return Response(
|
|
494
|
+
content=body.encode("utf-8"),
|
|
495
|
+
media_type="application/json; charset=utf-8",
|
|
496
|
+
headers={"Cache-Control": "no-cache", "Access-Control-Allow-Origin": "*"},
|
|
497
|
+
)
|
|
498
|
+
|
|
499
|
+
async def swagger(request: Request) -> Response:
|
|
500
|
+
root = path_base(request)
|
|
501
|
+
if root is None:
|
|
502
|
+
return invalid_path_base()
|
|
503
|
+
title = document.title_of(document.build(base_url(request)))
|
|
504
|
+
own = f"{root}{plugin.prefix}/swagger/"
|
|
505
|
+
# Every URL is same-origin and escaped in the page (the root path
|
|
506
|
+
# comes from the server's configuration, but is never trusted).
|
|
507
|
+
return HTMLResponse(swagger_html(
|
|
508
|
+
title=title,
|
|
509
|
+
openapi_url=f"{root}{plugin.prefix}/openapi.json",
|
|
510
|
+
js_url=root + js_url if js_url else own + "swagger-ui-bundle.js",
|
|
511
|
+
css_url=root + css_url if css_url else own + "swagger-ui.css",
|
|
512
|
+
favicon_url=own + "favicon-32x32.png",
|
|
513
|
+
))
|
|
514
|
+
|
|
515
|
+
async def swagger_asset(name: str) -> Response:
|
|
516
|
+
# A fixed allow-list: nothing else of the package is reachable.
|
|
517
|
+
media_type = SWAGGER_ASSETS.get(name)
|
|
518
|
+
if media_type is None:
|
|
519
|
+
return JSONResponse({"error": NOT_FOUND}, status_code=404)
|
|
520
|
+
return FileResponse(
|
|
521
|
+
os.path.join(SWAGGER_ASSETS_DIR, name), media_type=media_type,
|
|
522
|
+
headers={"Cache-Control": "public, max-age=86400"},
|
|
523
|
+
)
|
|
524
|
+
|
|
525
|
+
methods = ["GET", "HEAD"]
|
|
526
|
+
router.add_api_route("/swagger", swagger, methods=methods, include_in_schema=False)
|
|
527
|
+
router.add_api_route("/swagger/", swagger, methods=methods, include_in_schema=False)
|
|
528
|
+
# ``path`` so a name with an encoded "/" still gets this 404.
|
|
529
|
+
router.add_api_route("/swagger/{name:path}", swagger_asset, methods=methods, include_in_schema=False)
|
|
530
|
+
return router
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""Adds the ``X-RateLimit-*`` headers of an admitted request to its answer.
|
|
2
|
+
|
|
3
|
+
The guard stores them in ``request.state.qcli_rate_headers``
|
|
4
|
+
(``scope["state"]``); this pure ASGI middleware copies them onto the response
|
|
5
|
+
start message, so the handler's own answers (errors included) carry them.
|
|
6
|
+
Headers the handler set itself are left as they are.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
STATE_KEY = "qcli_rate_headers"
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class RateLimitHeadersMiddleware:
|
|
17
|
+
def __init__(self, app: Any) -> None:
|
|
18
|
+
self.app = app
|
|
19
|
+
|
|
20
|
+
async def __call__(self, scope: dict, receive: Any, send: Any) -> None:
|
|
21
|
+
if scope["type"] != "http":
|
|
22
|
+
await self.app(scope, receive, send)
|
|
23
|
+
return
|
|
24
|
+
# Created here so a scope copied further in still shares the dict.
|
|
25
|
+
state = scope.setdefault("state", {})
|
|
26
|
+
|
|
27
|
+
async def send_with_headers(message: dict) -> None:
|
|
28
|
+
if message["type"] == "http.response.start":
|
|
29
|
+
headers = state.get(STATE_KEY) if isinstance(state, dict) else None
|
|
30
|
+
if headers:
|
|
31
|
+
existing = list(message.get("headers") or [])
|
|
32
|
+
present = {name.lower() for name, _ in existing}
|
|
33
|
+
for name, value in headers.items():
|
|
34
|
+
raw = name.lower().encode("latin-1")
|
|
35
|
+
if raw not in present:
|
|
36
|
+
existing.append((raw, str(value).encode("latin-1")))
|
|
37
|
+
message = {**message, "headers": existing}
|
|
38
|
+
await send(message)
|
|
39
|
+
|
|
40
|
+
await self.app(scope, receive, send_with_headers)
|