feat(backend,website): proxy LAPIS calls through backend with structured query API (POC) by fhennig · Pull Request #6498 · loculus-project/loculus

fhennig · 2026-05-26T11:03:48Z

Summary

This branch is a proof-of-concept for routing all LAPIS data queries through the Loculus backend instead of having the website call LAPIS directly.

Motivation:

Path decoupling: The frontend talks to backend-defined paths, not LAPIS's API schema. LAPIS API changes can be absorbed at the backend without touching the frontend.
Auth extension point: Group-based authentication on specific endpoints can be enforced at the backend layer.
Unified API surface: Submission and query APIs are documented together in one place (Scalar/Swagger UI).

What changed

Backend

Added LapisProxyController — a wildcard proxy that forwards /{organism}/lapis/** requests to the upstream LAPIS service for that organism
Added QueryController — a new structured query API at /query/{organism}/{versionGroup}/... that mirrors LAPIS data endpoints, adding backend-owned paths and auth
- current = latest sequence versions only
- allVersions = includes historical versions / exact accession versions
Added LapisAccessFilter — restricts query endpoints so users only access their own groups' data (demo of what group-based auth looks like)
Added GET endpoints to QueryController alongside POST, download button migrated to use them
Added Scalar API reference UI (alongside existing Swagger UI)
Added QueryOpenApiCustomizer to generate per-organism OpenAPI docs

Website

lapisUrls removed from runtime_config.json — no longer needed since all traffic routes through the backend
All LAPIS calls migrated from lapisClient.ts to a new queryApi.ts service pointing at the backend QueryController
Authentication-required messaging unified

Docs

api-refactoring-docs/lapis-proxy.md — arc42-style architecture documentation (single file, sections 1–12 + 20)
POC_PLAN.md — full implementation plan with call inventory, routing diagrams, and steps

Architecture

Before:
  Browser/SSR → (Traefik / internal K8s) → loculus-lapis-service-{organism}:8080

After:
  Browser/SSR → loculus-backend-service:8079/{organism}/lapis/** → loculus-lapis-service-{organism}:8080
             → loculus-backend-service:8079/query/{organism}/**  → loculus-lapis-service-{organism}:8080

🚀 Preview: https://feat-lapis-proxy.loculus.org

+        val url = lapisBaseUrl.trimEnd('/') + lapisPath
+        log.debug { "Proxying POST $url" }
+        val request = HttpRequest.newBuilder()
+            .uri(URI.create(url))


+        val url = lapisBaseUrl.trimEnd('/') + lapisPath + query
+        log.debug { "Proxying GET $url" }
+        val request = HttpRequest.newBuilder()
+            .uri(URI.create(url))


Adds a generic wildcard proxy at `/{organism}/lapis/**` that forwards GET and POST requests to the upstream LAPIS service, enabling the website to route all LAPIS calls through the backend instead of hitting LAPIS directly. Changes: - Add `lapisUrl` field to `InstanceConfig` so each organism config carries its upstream LAPIS URL - New `LapisProxyController` using Java 21 `HttpClient`, streaming response via `StreamingResponseBody` (handles large FASTA downloads without memory buffering), strips `Authorization` and hop-by-hop headers - `SecurityConfig`: permit `/*/lapis/**` for GET + POST, disable CSRF - `WebConfig`: exclude `/*/lapis/**` from `ReadOnlyModeInterceptor` (LAPIS POSTs are reads, not writes) - Test fixture JSONs: add `lapisUrl` to each organism entry - Helm `_common-metadata.tpl`: inject `lapisUrl` per organism into backend config using internal K8s service name - Helm `_urls.tpl`: add `loculus.generateInternalLapisUrlsViaBackend` helper that builds LAPIS URLs routed through the backend proxy - `loculus-website-config.yaml`: serverSide `lapisUrls` now point at the backend proxy (`backend-service:8079/{organism}/lapis`) - `vitest.setup.ts`: test config `lapisUrls` updated to match the backend-proxy URL pattern Website TypeScript changes (remove `lapisUrls` from `ServiceUrls` type, rewrite `getLapisUrl()`) are tracked in POC_PLAN.md and will follow. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

`lapisUrls` is no longer injected into `runtime_config.json` — the LAPIS URL for any organism is now derived as `{backendUrl}/{organism}/lapis`, matching the backend proxy routes added in the previous commit. Changes: - `runtimeConfig.ts`: remove `lapisUrls` field from `serviceUrls` Zod schema - `config.ts`: rewrite `getLapisUrl()` to compute from `backendUrl` instead of reading a config map; no more runtime error on unknown organisms - `GroupPage.tsx`: replace `clientConfig.lapisUrls[key]` (with null guard) with `getLapisUrl(clientConfig, key)` - `SeqSetRecordsTableWithMetadata.tsx`: add `organisms: string[]` prop; iterate that list and compute each URL via `getLapisUrl` — removes the hacky `lapisUrls` dummy-organism filter - `SeqSetItem.tsx`: thread `organisms` prop through to `SeqSetRecordsTableWithMetadata` - `seqsets/[seqSetId].[version].astro`: pass `Object.keys(websiteConfig.organisms)` as `organisms` - `api-documentation/index.astro`: compute LAPIS doc links from `backendUrl` + organism keys (already available as `organismKeys`) - `loculus-info/index.ts`: compute `lapis` response field from `backendUrl` + organism keys instead of reading `lapisUrls` - `_common-metadata.tpl`: remove `lapisUrls` from `publicRuntimeConfig` - `loculus-website-config.yaml`: remove `lapisUrls` from serverSide block (URL is now computed client-side) - test files: replace `testConfig.serverSide.lapisUrls[testOrganism]` with `getLapisUrl(testConfig.serverSide, testOrganism)` Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…d is local When `disableBackend=true` (i.e. the backend runs locally outside the cluster), the generated backend_config.json must point lapisUrl at the port-forwarded LAPIS address (http://localhost:8080/{organism}) rather than the K8s-internal service name, which is unreachable from outside the cluster. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds /query/{organism}/{versionGroup}/... endpoints as a typed alternative to the generic LAPIS proxy. The versionGroup segment ("current" or "allVersions") controls whether versionStatus=LATEST_VERSION is injected into the forwarded LAPIS request body. Extracts shared HTTP proxy logic into LapisProxyService so both LapisProxyController and QueryController can reuse it without duplication. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Route metadata/aggregated/mutations/sequences queries through the new structured /query/{organism}/{versionGroup}/... backend endpoints instead of the generic LAPIS proxy, so the backend can inject version filters automatically per path rather than requiring callers to supply them. - Add getQueryUrl() to config.ts for building query endpoint URLs - New queryApi.ts with Zodios endpoint definitions for QueryController paths - LapisClient: add currentUrl/allVersionsUrl fields, requestFull() helper, migrate 6 methods (getSequenceEntryVersionDetails, getLatestAccessionVersion, getAllSequenceEntryHistoryForAccession, getSequenceMutations nucleotide, getUnalignedSequences); remove explicit versionStatus from getLatestAccessionVersion - serviceHooks: optional queryCurrentUrl param routes useAggregated/useDetails through QueryController when provided, falls back to proxy otherwise - SearchFullUI: compute and pass queryCurrentUrl to lapisClientHooks - GroupPage: use getQueryUrl for sequence count and time series queries - SeqSetRecordsTableWithMetadata: use allVersions for versioned accessions, current for bare accessions - Update vitest mocks for new endpoint paths Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

@hidden

…te download button GET /query/{organism}/{versionGroup}/{path} endpoints mirror the existing POSTs but accept query string parameters and inject versionStatus as a query param (for the current group) rather than into a JSON body. This enables browser-navigable download URLs to go through the structured endpoint instead of the raw LAPIS proxy. Backend: - Add prepareQuery() that appends versionStatus=LATEST_VERSION for current - Add get() helper mirroring post() - Add GET endpoints: metadata, sequences, sequences/{segment}, sequencesAligned, sequencesAligned/{referenceName}, translations/{gene} - Remove @hidden annotation so all QueryController endpoints show in Swagger Website: - DownloadUrlGenerator: use downloadBaseUrl + new paths (/metadata, /sequences, /sequencesAligned, /translations/{gene}) instead of the old /sample/... LAPIS proxy paths - SearchFullUI: pass queryCurrentUrl to DownloadUrlGenerator - Update DownloadDialog tests to match new endpoint paths Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…s' groups /query/** now requires a valid JWT. Each request has the user's group IDs injected as a LAPIS filter so users only see sequences belonging to their own groups. Super users bypass the filter and see all data. Users with no group memberships receive a sentinel groupId of -1, guaranteeing an empty result set. The website passes the session access token to the query Zodios client so requests are properly authenticated. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…file Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fhennig added the preview Triggers a deployment to argocd label May 26, 2026

fhennig self-assigned this May 26, 2026

fhennig force-pushed the feat/lapis-proxy branch from 59bc74b to 02fcb00 Compare May 26, 2026 11:34

github-advanced-security AI found potential problems May 27, 2026

View reviewed changes

Comment thread backend/src/main/kotlin/org/loculus/backend/controller/LapisProxyController.kt Fixed

github-advanced-security AI found potential problems May 27, 2026

View reviewed changes

fhennig added preview Triggers a deployment to argocd and removed preview Triggers a deployment to argocd labels Jun 8, 2026

fhennig and others added 8 commits June 8, 2026 13:46

disable a few viruses

6f816d4

chaoran-chen force-pushed the feat/lapis-proxy branch from f76b251 to afb792a Compare June 8, 2026 13:49

chaoran-chen added preview Triggers a deployment to argocd and removed preview Triggers a deployment to argocd labels Jun 8, 2026

fixes

c7d11fc

chaoran-chen force-pushed the feat/lapis-proxy branch from afb792a to c7d11fc Compare June 8, 2026 14:28

chaoran-chen added preview Triggers a deployment to argocd and removed preview Triggers a deployment to argocd labels Jun 8, 2026

chaoran-chen-bot added 8 commits June 8, 2026 16:13

fix(website): show private landing notice

caa7db8

docs(backend): document lapis proxy refactoring

c4c384b

docs(backend): generate organism-specific query docs

c74006f

docs(backend): refine query endpoint OpenAPI docs

f4f7264

fix(backend): improve query Swagger parameters

f21b00f

fix(backend): expose query GET endpoints

024fe63

fix(website): unify authentication required message

6a2e02b

feat(backend): add Scalar API reference

458b587

chaoran-chen-bot added 2 commits June 8, 2026 22:33

refactor(backend): clean up query API docs wiring

5ecc2ee

chore(deployment): enable all default organisms

9827b93

fhennig changed the title ~~POC WIP~~ feat(backend,website): proxy LAPIS calls through backend with structured query API (POC) Jun 9, 2026

docs(backend): consolidate lapis-proxy architecture docs into single …

7e6dde7

…file Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fhennig added preview Triggers a deployment to argocd and removed preview Triggers a deployment to argocd labels Jun 9, 2026

fhennig and others added 2 commits June 9, 2026 20:31

ping

10b14f3

Merge branch 'main' into feat/lapis-proxy

fcee219

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(backend,website): proxy LAPIS calls through backend with structured query API (POC)#6498

feat(backend,website): proxy LAPIS calls through backend with structured query API (POC)#6498
fhennig wants to merge 22 commits into
mainfrom
feat/lapis-proxy

fhennig commented May 26, 2026 •

edited by loculus-bot

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

fhennig commented May 26, 2026 • edited by loculus-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Backend

Website

Docs

Architecture

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fhennig commented May 26, 2026 •

edited by loculus-bot

Loading