118 lines
4.7 KiB
Markdown
118 lines
4.7 KiB
Markdown
# RPKI Explorer
|
|
|
|
RPKI Explorer is the web UI for browsing the outputs of the ours RP
|
|
`rpki_query_service` — runs, repositories, publication points, objects,
|
|
validation issues and evidence exports. It is a read-only query layer: it does
|
|
not change validation logic or RP state.
|
|
|
|
## Features
|
|
|
|
- **Overview** — latest-run health at a glance: VRP/ASPA/object/PP counts,
|
|
validation result and object type charts, top repositories, top reject
|
|
reasons, all with drill-down links.
|
|
- **Repositories** — paginated repository list, repository detail with sync
|
|
phases/terminal states, publication points and scoped object browsing.
|
|
- **Publication Points** — global PP list and PP detail (URIs, sync state,
|
|
thisUpdate/nextUpdate, objects).
|
|
- **Objects** — global object browser with **server-side filters**
|
|
(`type`, `result`, `rejected`, `q` URI substring) and cursor paging.
|
|
- **Object detail** — structured parsed projections (ROA prefixes, ASPA
|
|
providers, manifest file list, CRL revocations, certificate fields),
|
|
validation summary, on-demand *explain* (audit projection, non-authoritative),
|
|
chain edges, raw DER download, object-set export.
|
|
- **Validation** — result distribution, reject-reason distribution with
|
|
click-to-filter, paginated issue list (`/issues`).
|
|
- **Search** — unified lookup: exact object URI, SHA-256 (full or ≥8 hex
|
|
prefix), repository host/URI substring, PP URI substring — plus **VRP
|
|
lookup**: enter an IPv4/IPv6 address or CIDR prefix to list the covering
|
|
VRPs (prefix queries use covering semantics: VRP prefix must cover the whole
|
|
queried prefix with `maxLength` ≥ queried length), with an optional ASN
|
|
filter and cursor paging. ASN-only queries are not supported by the API and
|
|
the page says so.
|
|
- **Exports** — export job list with live polling and tarball download.
|
|
- **Runs** — indexed run history; pin any run as the browsing context via the
|
|
run selector in the top bar (`?run=` URL param, deep-linkable everywhere).
|
|
- **API** — service health and endpoint reference.
|
|
|
|
## Backend requirements
|
|
|
|
`rpki_query_service` (this repository, `src/bin/rpki_query_service.rs`) with a
|
|
query-db built by `rpki_query_indexer`. Some features need extra service flags:
|
|
|
|
| Feature | Requirement |
|
|
| --- | --- |
|
|
| Parsed projections, raw download, exports | `--repo-bytes-db <path>` |
|
|
| New runs appear automatically | `--watch-run-root <path>` |
|
|
|
|
The service has **no CORS headers and no authentication** — the UI must be
|
|
served same-origin with the API behind a proxy (dev: Vite proxy; prod: reverse
|
|
proxy). VRP lookup needs runs indexed at query-db schema version 2 (`#122`);
|
|
re-index older runs with `rpki_query_indexer` (or the service
|
|
`--watch-run-root` backfill), otherwise lookup results are empty.
|
|
|
|
## Development
|
|
|
|
Start the query service (example with a local query-db):
|
|
|
|
```bash
|
|
rpki_2/rpki/target/debug/rpki_query_service \
|
|
--query-db /path/to/query-db \
|
|
--repo-bytes-db /path/to/repo-bytes.db \
|
|
--listen 127.0.0.1:9557
|
|
```
|
|
|
|
Start the Vite dev server:
|
|
|
|
```bash
|
|
cd rpki_2/rpki/ui/rpki-explorer
|
|
npm install
|
|
RPKI_EXPLORER_API_TARGET=http://127.0.0.1:9557 npm run dev
|
|
```
|
|
|
|
The dev server proxies `/api/v1/*` to `RPKI_EXPLORER_API_TARGET`
|
|
(default `http://127.0.0.1:9557`) and serves the UI on `http://127.0.0.1:5173`.
|
|
|
|
## Production
|
|
|
|
```bash
|
|
npm run build
|
|
RPKI_EXPLORER_API_TARGET=http://127.0.0.1:9557 npm run preview # smoke-test the build
|
|
```
|
|
|
|
For real deployments serve `dist/` with any static server / reverse proxy and
|
|
forward `/api/v1/*` to `rpki_query_service` on the same origin, e.g. nginx:
|
|
|
|
```nginx
|
|
location /api/v1/ { proxy_pass http://127.0.0.1:9557; }
|
|
location / { root /srv/rpki-explorer/dist; try_files $uri /index.html; }
|
|
```
|
|
|
|
`try_files ... /index.html` (SPA fallback) is required because routing is
|
|
client-side.
|
|
|
|
## Validation
|
|
|
|
```bash
|
|
npm run typecheck # tsc project references
|
|
npm run lint # eslint
|
|
npm test # vitest unit tests (lib + api contract)
|
|
npm run build # production build
|
|
npm run test:e2e # Playwright, fully mocked backend (no service needed)
|
|
```
|
|
|
|
E2E tests intercept every `/api/v1/**` request with a fixture-backed mock
|
|
(`tests/e2e/mockApi.ts`), so they are deterministic and need no running query
|
|
service. They start the Vite dev server automatically (`workers: 1`).
|
|
|
|
## Directory layout
|
|
|
|
```text
|
|
src/api/ fetch client, zod schemas, typed endpoint functions
|
|
src/app/ providers, router, react-query client
|
|
src/components/ shell, data table, pills, pager, tabs, object table, …
|
|
src/lib/ formatting, cursor pager state machine, run context, guards
|
|
src/pages/ one file per route
|
|
src/styles/ design tokens + base/shell/components/pages CSS
|
|
tests/e2e/ Playwright specs + fixture-backed API mock
|
|
```
|