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