AbsaOSS / AbsaOSS/EventGate

Self-host Swagger UI assets (remove cdn.jsdelivr.net dependency from /docs)

Đang mở
#197 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Python
Star
4
Fork
0
Merge trung bình
1 ngày 5 giờ
Pull request đã merge (30 ngày)
8

Mô tả

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

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.