Self-host Swagger UI assets (remove cdn.jsdelivr.net dependency from /docs)
- 主要語言
- Python
- 星號
- 4
- 分支
- 0
- 平均合併
- 1 天 5 小時
- 30 天內合併 PR
- 8
描述
## Summary
PR #190 adds a `GET /docs` endpoint that serves a Swagger UI page. The page currently loads Swagger UI assets from a public CDN:
```html
```
Depending on `cdn.jsdelivr.net` at runtime is undesirable:
- **Availability** — the docs page breaks whenever the CDN is unreachable (air-gapped / VPC-only deployments, CDN outage, corporate egress filtering).
- **Supply chain** — a compromised or hijacked CDN response executes arbitrary JS in the browser of anyone viewing the docs. No SRI hash pins the content.
- **Reproducibility** — the served asset version can drift under the `@5` major tag without any change to our image.
We should **vendor the Swagger UI static assets, bake them into the Docker image, and serve them from the Lambda** so `/docs` is fully self-hosted with zero external requests.
## Background
- Docs handler: `src/handlers/handler_api.py` → `get_docs()` (returns the HTML string).
- Routing: `src/event_gate_lambda.py` `ROUTE_MAP`, dispatched by exact API Gateway `resource` field via `src/utils/utils.py::dispatch_request`.
- Assets already baked into the image are `COPY`ed in `Dockerfile` (see `COPY api.yaml $LAMBDA_TASK_ROOT/api.yaml`).
- Only two files are strictly required from `swagger-ui-dist@5`: `swagger-ui.css` (~145 KB) and `swagger-ui-bundle.js` (~1.4 MB, self-contained — includes presets). Both are well under the 6 MB API Gateway Lambda-proxy response limit.
- Swagger UI is Apache-2.0 licensed — compatible with this project.
## Proposed work
**1. Vendor the assets**
Add pinned Swagger UI assets to the repo, e.g. `src/static/swagger-ui/`:
- `swagger-ui.css`
- `swagger-ui-bundle.js`
Pin the exact version (e.g. `swagger-ui-dist@5.x.y`, not floating `@5`). Record the version + upstream source + license in a short `README`/`NOTICE` next to the files so future upgrades are traceable.
> Alternative: download+checksum-verify during the Docker build instead of committing binaries. Committing is simpler, deterministic, and needs no build-time network — recommended unless the team prefers to keep vendored blobs out of git.
**2. Serve the assets from the Lambda**
Add handler methods that read the vendored files and return them with correct `Content-Type` (`text/css`, `application/javascript`). Register routes in `ROUTE_MAP`, e.g.:
- `/docs/swagger-ui.css`
- `/docs/swagger-ui-bundle.js`
(or a single `/docs/{proxy+}` catch-all dispatching by filename — fewer API Gateway resources to declare). Consider a long-lived `Cache-Control` header since assets are version-pinned.
**3. Point the page at the local assets**
Update `get_docs()` HTML to use relative paths instead of the CDN URLs:
```html
```
Relative paths keep working across all API Gateway stages / custom domains (same rationale as the existing `./api` reference).
**4. Bake assets into the image**
Add a `COPY src/static $LAMBDA_TASK_ROOT/src/static` (or the chosen path) to the `Dockerfile`, and ensure the non-root `app` user has read access (the existing `chown -R 1000:1000 ... ${LAMBDA_TASK_ROOT}` already covers files under the task root).
**5. Tests + docs**
- Unit: new asset routes return 200, correct `Content-Type`, non-empty body; `/docs` HTML references relative `./docs/...` paths and no longer contains `cdn.jsdelivr.net`.
- Integration: extend `EventGateTestClient` / `tests/integration/test_api_endpoint.py`.
- `api.yaml`: document the asset routes (or the `{proxy+}`).
## Deployment note
Like `/docs` itself (see PR #190), the API Gateway must route the new asset path(s) to the EventGate Lambda (explicit resources or a `{proxy+}` catch-all). This requires a matching infra change in `cps-eventbus-gateway`.
## Acceptance criteria
- [ ] `/docs` renders Swagger UI with **no** requests to `cdn.jsdelivr.net` or any external host (verifiable via browser network tab / offline).
- [ ] Swagger UI assets are version-pinned and vendored into the Docker image.
- [ ] Asset version, source, and license are recorded.
- [ ] Unit + integration tests cover the new asset routes and the CDN-free HTML.
Related: PR #190, #191
貢獻指南
這個儲存庫沒有索引到貢獻指南
評估
這個 Issue 還沒有評估資料。