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.
@@ -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)