From 31cfa8f4bd1926a7dfbe41e4ca94fec8bbc208cd Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 12:54:38 -0400
Subject: [PATCH 01/14] docs: design doc for HTTP path-based routing +
 redirects (#137)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Proposes a host+path route table, decoupled from service definitions,
distributed to nullnet-proxy the same way certs/port-mappings already are.
Covers proto, server config/validation, proxy dispatch, and an admin UI
editor. No code changes yet — design for review before implementation.
---
 docs/http-path-routing-design.md | 337 +++++++++++++++++++++++++++++++
 1 file changed, 337 insertions(+)
 create mode 100644 docs/http-path-routing-design.md

diff --git a/docs/http-path-routing-design.md b/docs/http-path-routing-design.md
new file mode 100644
index 0000000..b4ae1b1
--- /dev/null
+++ b/docs/http-path-routing-design.md
@@ -0,0 +1,337 @@
+# HTTP path-based routing + redirects
+
+> Design for [#137](https://github.com/NullNet-ai/nullnet/issues/137): let
+> `nullnet-proxy` route a single Host across multiple backend services by URL
+> path (NGINX `location` block parity), and configure literal redirects —
+> without a separate NGINX instance in front of it.
+
+## Goal
+
+Today one HTTP service name **is** the Host — `upstream_peer` resolves the
+`Host`/`:authority` header straight to a `service_name` and asks the control
+service for an upstream. There is no way to send `example.com/api` to one
+backend and `example.com/grafana` to another, and no way to configure an
+arbitrary redirect (the only redirect that exists is the hardcoded
+HTTP→HTTPS 301). Kevin's ask: something like NGINX's `location` block —
+route by path prefix to different backends, redirects included — so multiple
+apps can share one Host without a separate NGINX in front of `nullnet-proxy`.
+
+Scope: **HTTP(S) only.** TCP/UDP port mappings are unaffected — they have no
+notion of a request path.
+
+## Current model (recap)
+
+- A `[[services]]` TOML entry's `name` *is* the routing key for HTTP: the
+  proxy takes the Host header verbatim as `service_name` and calls the
+  `Proxy` RPC, which resolves/builds the backend (container discovery, VXLAN
+  edge, etc.) — see `members/nullnet-proxy/src/main.rs` `upstream_peer` and
+  `members/nullnet-server/src/nullnet_grpc_impl.rs` `handle_proxy_request`.
+- `tcp`/`udp` services instead get a `listen_port` and flow through
+  `PortMappingBundle`/`WatchPortMappings`, which the proxy turns into raw
+  listeners (`port_mappings.rs`).
+- Path is never read anywhere in the request path; `ServiceProtocol::Http`
+  literally means "Host-header routed, no path awareness."
+
+## Proposed model
+
+Introduce a **route table**, decoupled from service definitions, using the
+same "server owns the config, proxy subscribes to a watch stream" pattern
+already used for `CertBundle`/`PortMappingBundle`.
+
+A route is `(host, path_prefix) → target`, where `target` is either an
+existing service name (proxy_pass equivalent) or a literal redirect
+(host/path/status/URL). Backends keep meaning exactly what they mean today —
+this only adds a dispatch layer in front of them.
+
+### Backward compatibility (no migration required)
+
+Every `[[services]]` entry with `protocol = "http"` (default) and a
+`timeout` (proxy-reachable) is *implicitly* also a route:
+`{ host = name, path_prefix = "/", target = Service(name) }`. An install
+with zero `[[route]]` entries behaves exactly as it does today — this is the
+same trick `local_protocol()` already plays for backward-compat elsewhere in
+this codebase.
+
+An explicit `[[route]]` for a host takes over that host's dispatch entirely:
+once any route names a host, the implicit `{name} → "/"` fallback for that
+host is dropped and every path must be explicitly covered (falling outside
+all prefixes → 404), same as an NGINX `server{}` block with no catch-all
+`location /`.
+
+### Config (TOML)
+
+```toml
+# unchanged — still the backend a route can point at
+[[services]]
+name = "grafana"
+docker_container = "grafana"
+port = 3000
+timeout = 30
+
+[[services]]
+name = "gitlab"
+docker_container = "gitlab"
+port = 80
+timeout = 30
+
+# new — explicit location blocks for one Host
+[[route]]
+host = "ops.example.com"
+path = "/grafana"
+service = "grafana"
+
+[[route]]
+host = "ops.example.com"
+path = "/gitlab"
+service = "gitlab"
+
+[[route]]
+host = "ops.example.com"
+path = "/"
+service = "grafana"          # catch-all, same as an NGINX `location /`
+
+# new — a redirect needs no backend at all
+[[route]]
+host = "old.example.com"
+path = "/"
+redirect_to = "https://ops.example.com/"
+redirect_status = 301        # optional, defaults to 301
+```
+
+`service` and `redirect_to` are mutually exclusive (exactly one required),
+mirroring how `*_blocked_countries`/`*_allowed_countries` are already
+validated as mutually exclusive in `input.rs`. `redirect_status` is
+restricted to `301 | 302 | 307 | 308`.
+
+### Proto
+
+```proto
+// One location-block-style dispatch rule for HTTP(S). Longest path_prefix
+// match wins within a host; "/" is the catch-all. Mutually exclusive target.
+message HttpRoute {
+  string host = 1;
+  string path_prefix = 2;
+  oneof target {
+    string service_name = 3;     // proxy_pass equivalent — resolved the same
+                                  // way a Host-routed service is today
+    HttpRedirect redirect = 4;
+  }
+}
+
+message HttpRedirect {
+  string to = 1;           // absolute URL, or a path template — see "Redirect
+                            // target" below
+  uint32 status_code = 2;  // 301/302/307/308
+}
+
+message HttpRouteBundle {
+  repeated HttpRoute routes = 1;
+}
+
+// Long-lived stream, mirrors WatchCertificates/WatchPortMappings: full table
+// on subscribe, one push per services.toml change.
+rpc WatchHttpRoutes(Empty) returns (stream HttpRouteBundle);
+```
+
+No change to `ProxyRequest`/`Upstream`/`Proxy` RPC — once a route resolves to
+a `service_name`, everything downstream (container discovery, VXLAN edge
+setup, `get_or_add_upstream`) is untouched.
+
+### Redirect target
+
+Keep it simple for v1: `to` is either an absolute URL (used verbatim) or
+starts with `/` (path-only — same scheme/host as the incoming request,
+target path substituted). No variable interpolation (no `$request_uri`
+equivalent) in v1 — see Open wrinkles.
+
+### Server changes (`nullnet-server`)
+
+- `ServiceToml` gains no fields. New `RouteToml` struct alongside it in
+  `services/input.rs`:
+  ```rust
+  #[derive(Deserialize)]
+  struct RouteToml {
+      host: String,
+      #[serde(default = "default_path")]
+      path: String,
+      service: Option<String>,
+      redirect_to: Option<String>,
+      #[serde(default)]
+      redirect_status: Option<u16>,
+  }
+  ```
+- `ServicesToml` gains `#[serde(default)] routes: Vec<RouteToml>`.
+- Validation (in `parse_stack_content`, so both the file loader and the UI's
+  save-time check share it, same as today):
+  - exactly one of `service`/`redirect_to` per route;
+  - `redirect_status` ∈ {301,302,307,308} when present;
+  - `service` must name a declared service in the *same* stack (routes don't
+    reach across stacks, same scoping as `proxy_dependencies`);
+  - the referenced service must be `protocol = "http"`;
+  - no two routes in the *same stack* share `(host, path)` exactly — this
+    plus the equivalent cross-stack check (below) is `detect_route_conflicts`,
+    the HTTP-route sibling of the existing `detect_port_conflicts`.
+- `detect_route_conflicts(&StackMap) -> Vec<RouteConflict>`, cross-stack, same
+  shape/spirit as `detect_port_conflicts` — `(host, path)` is a global proxy
+  resource like `(protocol, listen_port)` is today. Wired into
+  `load_validated()` and the reload path identically (drop offending stacks
+  rather than brick the control plane, emit the same kind of event).
+- `nullnet_grpc_impl.rs`: `build_http_route_bundle(&StackMap) -> HttpRouteBundle`
+  next to `build_port_mapping_bundle`, folding in each stack's implicit
+  fallback routes for hosts with no explicit `[[route]]`. New
+  `http_routes: watch::Receiver<HttpRouteBundle>` field + `http_routes_changed:
+  Arc<Notify>` (its own `Notify`, matching the existing comment on why
+  `port_mappings_changed` isn't shared) + `watch_http_routes` RPC handler,
+  copy-pasted from `watch_port_mappings`.
+
+### Proxy changes (`nullnet-proxy`)
+
+- New `routes.rs`: `RouteTable` (host → `Vec<HttpRoute>` sorted by
+  `path_prefix` length descending, so first match = longest-prefix match),
+  held in an `Arc<ArcSwap<RouteTable>>` exactly like `CertStore`.
+  `watch_and_serve` mirrors `watch_certificates` in `main.rs` (subscribe,
+  atomic-swap on each push, exit-for-restart if the stream drops).
+- `main.rs`:
+  - `ProxyHttp::CTX` changes from `()` to a small struct carrying the
+    resolved dispatch decision (`enum Dispatch { Backend(String), NotFound
+    }`, default `Backend(host)` when no route table entry matches — this is
+    the backward-compat fallback), computed once in `request_filter`.
+  - `request_filter` looks up `(host, session.req_header().uri.path())` in
+    the route table *before* the existing TLS-redirect logic:
+    - `Redirect` match → write the 301/302/307/308 response directly (same
+      shape as the existing HTTP→HTTPS 301 writer), return `Ok(true)`.
+    - `Backend(service_name)` match → stash it in ctx, fall through to the
+      existing ingress-country-check / TLS-redirect logic unchanged (ingress
+      policy is evaluated against the *resolved backend* service, since
+      that's the service actually being reached).
+    - no match at all (host has explicit routes but none cover this path) →
+      write a 404, return `Ok(true)`.
+  - `upstream_peer` uses `ctx`'s resolved service name instead of
+    recomputing it from the Host header — the only production-code change to
+    this function is where `service_name` comes from.
+
+### What is reused vs new
+
+| Piece | Reused | New |
+|---|---|---|
+| Backend resolution (container discovery, VXLAN edge, `get_or_add_upstream`) | 100% — a route's `service_name` target goes through exactly today's path | — |
+| Distribution to the proxy | `ArcSwap` hot-swap pattern (`CertStore`), `watch::Receiver` + `Notify` pattern (`PortMappingBundle`) | one more `Watch*` RPC + bundle type |
+| Config validation | `parse_stack_content` single-source-of-truth, cross-stack conflict detection shape (`detect_port_conflicts`) | `detect_route_conflicts`, mutual-exclusion check on route target |
+| Redirect response writing | the existing 301 writer in `request_filter` (host+path→Location) | parameterized status code, arbitrary target |
+| Request-path awareness | — | first read of `session.req_header().uri.path()` for routing (previously unused for routing) |
+
+## Admin UI
+
+The UI (`members/nullnet-server/ui`, React 19 + TS + Vite, embedded into the
+server binary via `rust-embed`) has no structured form anywhere today —
+`Config.tsx` is a raw `<textarea>` bound 1:1 to the stack's TOML text
+(GET/POST/DELETE `/api/config/{stack}`), and the services list
+(`Services.tsx` / `services.rs` `ServiceJson`) doesn't even surface
+`protocol`/`listen_port`. Routes get a real form, following the one existing
+CRUD+modal precedent in this codebase (`pages/Users.tsx`: table + "+ Add"
+button opening a shared `Modal`, per-field `useState`, busy/error state,
+disabled-until-valid submit) rather than raw TOML editing or a new pattern.
+
+### New endpoints (`nullnet-server`, alongside `config.rs`/`services.rs`)
+
+```
+GET  /api/routes/{stack}   -> { routes: RouteJson[], http_services: string[] }
+POST /api/routes/{stack}   -> body: RouteJson[]  (whole-list replace)
+                            -> { ok: bool, error?: string }   // same SaveResult shape as config.rs
+```
+
+`http_services` is every declared `protocol = "http"` service name in that
+stack — kept as a routes-endpoint-only field rather than adding `protocol` to
+`ServiceJson`, so `services.rs`/`Services.tsx` stay untouched.
+
+```rust
+#[derive(Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "lowercase")]
+enum RouteTargetJson {
+    Service { service: String },
+    Redirect { to: String, status: u16 },
+}
+
+#[derive(Serialize, Deserialize)]
+struct RouteJson { host: String, path: String, target: RouteTargetJson }
+```
+
+`POST` re-runs the same validation as the route parsing described above
+(mutual exclusion, status ∈ {301,302,307,308}, referenced service exists and
+is `http`, `(host, path)` uniqueness / cross-stack conflict check), then
+merges the new route list into the stack's existing TOML **without
+disturbing the rest of the file** (services, comments, formatting) — the
+same guarantee raw-text editing already gives for everything else. Plain
+`toml`/serde round-tripping loses comments/ordering on a full-file
+rewrite, so this needs a structural editor (`toml_edit`, already a
+lightweight transitive dependency of the `toml` ecosystem) to splice the
+`[[route]]` array in place instead of reserializing the whole document.
+
+### New page: `pages/RoutesPage.tsx`
+
+- Table: Host | Path | Target (`→ grafana` for a service target, `redirect
+  301 → https://…` for a redirect), Edit/Delete per row.
+- "+ Add route" opens the shared `Modal` with: Host (text), Path (text,
+  default `/`), a Service/Redirect toggle, then either a `<select>` populated
+  from `http_services` or a URL text input + status `<select>`
+  (301/302/307/308, default 301).
+- Save posts the full edited array to `POST /api/routes/{stack}`; a
+  structural/business-rule error surfaces via the same `.modal-err` pattern
+  `Users.tsx` already uses.
+- Scoped to the active stack via the existing `useStack()` context
+  (`StackContext.tsx`), same as `Config.tsx`/`Services.tsx`.
+- New nav entry in the `Ops` group (`components/Layout.tsx`, next to
+  `services`/`config`) and a route in `App.tsx` (named `RoutesPage` to avoid
+  colliding with `react-router-dom`'s own `Routes`), both wrapped in
+  `RequireAuth` like every other page.
+
+## Open wrinkles
+
+- **Path matching is prefix-only**, like NGINX's plain (non-regex)
+  `location` — no wildcards/regex in v1. If a follow-up needs `location ~`
+  parity, that's a separate `path_regex` field on `HttpRoute`, additive.
+- **No variable interpolation in redirect targets** (`$request_uri`-style).
+  A path-only `to` re-appends the literal target path, not the *matched
+  suffix* — `path="/old" → to="/new"` on request `/old/x` redirects to
+  `/new`, not `/new/x`. If suffix-preserving redirects are needed, that's a
+  `preserve_suffix: bool` flag as a follow-up, not a v1 requirement (the
+  issue only asks for redirects "of course that's included," not detailed
+  semantics).
+- **Ingress country policy is keyed by service name today** — a redirect
+  route has no backend service, so there's no ingress policy to check before
+  issuing it. This is consistent with NGINX (a `return` in a `location`
+  doesn't consult upstream ACLs) but worth calling out explicitly.
+- **Route table size**: sent in full on every push, like certs/port-mappings.
+  Fine at expected config scale (this mirrors two existing streams that
+  already do this); revisit only if it becomes a real bottleneck.
+
+## Follow-ups (out of scope for this issue)
+
+- Regex/wildcard path matching.
+- Redirect target variable interpolation (preserve matched suffix, query
+  string passthrough is already implicit since redirects don't touch it).
+- Header-based routing (beyond Host), if ever needed.
+
+## Implementation status
+
+Design only — nothing below is implemented yet. Planned as a sequence of
+commits so each stage builds/tests independently:
+
+1. **Contract** (`nullnet-grpc-lib`): `HttpRoute`, `HttpRedirect`,
+   `HttpRouteBundle`, `WatchHttpRoutes` RPC.
+2. **Server**: `RouteToml` parsing + validation (mutual exclusion, status
+   code, same-stack service reference, `protocol = http` check),
+   `detect_route_conflicts`, `build_http_route_bundle` (incl. implicit
+   fallback routes), `watch_http_routes` RPC handler + its own `Notify`.
+   Unit tests mirroring the existing `detect_port_conflicts`/
+   `parses_explicit_and_implicit_services` coverage in `services/input.rs`.
+3. **Proxy**: `routes.rs` (`RouteTable`, longest-prefix lookup,
+   `watch_and_serve`), `main.rs` dispatch changes (`request_filter`
+   redirect/404/backend-selection, `upstream_peer` reading resolved ctx).
+   Unit tests for prefix matching, backward-compat fallback (no explicit
+   routes → today's behavior), and the redirect response writer.
+4. **Admin API**: `GET`/`POST /api/routes/{stack}`, `toml_edit`-based
+   structural merge into the stack file.
+5. **UI**: `RoutesPage.tsx`, nav entry, `Modal`-based add/edit form.
+6. **Docs**: update `docs/architecture.md` if the route-table stream is
+   worth calling out at the overview level once shipped.

From 7f8869fee36bd2b070a63844852403fc5aa99e53 Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 13:00:45 -0400
Subject: [PATCH 02/14] docs: add worked example to HTTP routing design doc

---
 docs/http-path-routing-design.md | 77 ++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/docs/http-path-routing-design.md b/docs/http-path-routing-design.md
index b4ae1b1..1d8e6b2 100644
--- a/docs/http-path-routing-design.md
+++ b/docs/http-path-routing-design.md
@@ -103,6 +103,83 @@ mirroring how `*_blocked_countries`/`*_allowed_countries` are already
 validated as mutually exclusive in `input.rs`. `redirect_status` is
 restricted to `301 | 302 | 307 | 308`.
 
+### Example: the issue's own scenario
+
+One host fronting three apps by path (`/api`, `/grafana`, `/gitlab`, as named
+in the issue), plus a legacy-domain redirect:
+
+```toml
+# services/ops.toml
+
+# --- Backends (unchanged from today — these are just services) ---
+
+[[services]]
+name = "api"
+docker_container = "api-backend"
+port = 8080
+timeout = 30
+
+[[services]]
+name = "grafana"
+docker_container = "grafana"
+port = 3000
+timeout = 30
+
+[[services]]
+name = "gitlab"
+docker_container = "gitlab"
+port = 80
+timeout = 60
+
+# --- Routes: NGINX location-block equivalent for ops.example.com ---
+
+[[route]]
+host = "ops.example.com"
+path = "/api"
+service = "api"
+
+[[route]]
+host = "ops.example.com"
+path = "/grafana"
+service = "grafana"
+
+[[route]]
+host = "ops.example.com"
+path = "/gitlab"
+service = "gitlab"
+
+# Catch-all for this host — anything not matching a more specific prefix
+# above falls here. Without this, unmatched paths on ops.example.com 404.
+[[route]]
+host = "ops.example.com"
+path = "/"
+service = "grafana"
+
+# --- A literal redirect: legacy domain -> the new one, no backend needed ---
+
+[[route]]
+host = "old-ops.example.com"
+path = "/"
+redirect_to = "https://ops.example.com/"
+redirect_status = 301
+```
+
+Resulting behavior:
+
+| Request | Result |
+|---|---|
+| `https://ops.example.com/api/users` | proxied to `api` (port 8080) — longest matching prefix is `/api` |
+| `https://ops.example.com/grafana/d/xyz` | proxied to `grafana` (port 3000) |
+| `https://ops.example.com/gitlab/` | proxied to `gitlab` (port 80) |
+| `https://ops.example.com/anything-else` | proxied to `grafana` — the catch-all `path = "/"` |
+| `https://old-ops.example.com/whatever` | `301 https://ops.example.com/` |
+
+A single-service host with **no** `[[route]]` block at all keeps working
+exactly as it does today (the implicit `{host = name, path = "/"} →
+service(name)` fallback from the backward-compatibility section above) — you
+only add `[[route]]` entries for hosts that actually need path-based fan-out
+or a redirect.
+
 ### Proto
 
 ```proto

From 275a2add7d1853c1afda56db47bbd646684f39d1 Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 13:02:32 -0400
Subject: [PATCH 03/14] grpc: add HttpRoute/HttpRedirect/HttpRouteBundle +
 WatchHttpRoutes RPC
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Contract stage for #137 (docs/http-path-routing-design.md). No behavior
change yet — nothing produces or consumes the new stream.
---
 .../nullnet-grpc-lib/proto/nullnet_grpc.proto |  37 +++++
 members/nullnet-grpc-lib/src/lib.rs           |  19 ++-
 .../src/proto/nullnet_grpc.rs                 | 131 ++++++++++++++++++
 3 files changed, 185 insertions(+), 2 deletions(-)

diff --git a/members/nullnet-grpc-lib/proto/nullnet_grpc.proto b/members/nullnet-grpc-lib/proto/nullnet_grpc.proto
index 133a265..ce8f81e 100644
--- a/members/nullnet-grpc-lib/proto/nullnet_grpc.proto
+++ b/members/nullnet-grpc-lib/proto/nullnet_grpc.proto
@@ -66,6 +66,14 @@ service NullnetGrpc {
   // table immediately on subscribe and again whenever services.toml changes,
   // so the proxy opens/closes raw TCP/UDP listeners without a restart.
   rpc WatchPortMappings(Empty) returns (stream PortMappingBundle);
+
+  // HTTP path-routing distribution APIs --------------------------------------------------------
+
+  // Long-lived stream: the server pushes the full HTTP (host, path) → target
+  // route table immediately on subscribe and again whenever services.toml
+  // changes, so the proxy dispatches path-based routes/redirects without a
+  // restart. See docs/http-path-routing-design.md.
+  rpc WatchHttpRoutes(Empty) returns (stream HttpRouteBundle);
 }
 
 // TAP-based clients ---------------------------------------------------------------------------------------------------
@@ -290,6 +298,35 @@ message PortMappingBundle {
   repeated PortMapping mappings = 1;
 }
 
+// HTTP path routing ----------------------------------------------------------------------------
+
+// One location-block-style dispatch rule for HTTP(S): within a host, the
+// entry with the longest `path_prefix` that prefix-matches the request path
+// wins. `path_prefix = "/"` is the catch-all. Target is mutually exclusive:
+// either proxy_pass to an existing HTTP service (resolved exactly like a
+// Host-routed service is today) or a literal redirect.
+message HttpRoute {
+  string host = 1;
+  string path_prefix = 2;
+  oneof target {
+    string service_name = 3;
+    HttpRedirect redirect = 4;
+  }
+}
+
+// A literal redirect target for an HttpRoute. `to` is either an absolute URL
+// (used verbatim) or a path (starting with `/`; same scheme/host as the
+// incoming request, target path substituted). No variable interpolation.
+message HttpRedirect {
+  string to = 1;
+  // One of 301/302/307/308.
+  uint32 status_code = 2;
+}
+
+message HttpRouteBundle {
+  repeated HttpRoute routes = 1;
+}
+
 // Backend-triggered chains --------------------------------------------------------------------------------------------
 
 message BackendTriggerRequest {
diff --git a/members/nullnet-grpc-lib/src/lib.rs b/members/nullnet-grpc-lib/src/lib.rs
index a0f0d0b..41d8c56 100644
--- a/members/nullnet-grpc-lib/src/lib.rs
+++ b/members/nullnet-grpc-lib/src/lib.rs
@@ -5,8 +5,9 @@ use crate::control_tls_verifier::PinnedCa;
 use crate::nullnet_grpc::nullnet_grpc_client::NullnetGrpcClient;
 use crate::nullnet_grpc::{
     AgentEvent, BackendTriggerRequest, CertBundle, EgressDestinationEntry, EgressDestinationReport,
-    EgressPolicyCheck, EgressTriggerRequest, Empty, IngressPolicyCheck, MsgId, NetMessage, NetType,
-    PortMappingBundle, ProxyRequest, ServiceReport, ServicesListResponse, Upstream,
+    EgressPolicyCheck, EgressTriggerRequest, Empty, HttpRouteBundle, IngressPolicyCheck, MsgId,
+    NetMessage, NetType, PortMappingBundle, ProxyRequest, ServiceReport, ServicesListResponse,
+    Upstream,
 };
 pub use proto::*;
 use std::path::Path;
@@ -239,4 +240,18 @@ impl NullnetGrpcInterface {
             .map_err(|e| e.to_string())?
             .into_inner())
     }
+
+    /// Subscribe to HTTP route-table changes: the returned stream yields the
+    /// full (host, path) → target table immediately on subscribe and again
+    /// whenever it changes.
+    #[allow(clippy::missing_errors_doc)]
+    pub async fn watch_http_routes(&self) -> Result<Streaming<HttpRouteBundle>, String> {
+        Ok(self
+            .client
+            .clone()
+            .watch_http_routes(Request::new(Empty {}))
+            .await
+            .map_err(|e| e.to_string())?
+            .into_inner())
+    }
 }
diff --git a/members/nullnet-grpc-lib/src/proto/nullnet_grpc.rs b/members/nullnet-grpc-lib/src/proto/nullnet_grpc.rs
index f40dc71..2d69e5d 100644
--- a/members/nullnet-grpc-lib/src/proto/nullnet_grpc.rs
+++ b/members/nullnet-grpc-lib/src/proto/nullnet_grpc.rs
@@ -284,6 +284,46 @@ pub struct PortMappingBundle {
     #[prost(message, repeated, tag = "1")]
     pub mappings: ::prost::alloc::vec::Vec<PortMapping>,
 }
+/// One location-block-style dispatch rule for HTTP(S): within a host, the
+/// entry with the longest `path_prefix` that prefix-matches the request path
+/// wins. `path_prefix = "/"` is the catch-all. Target is mutually exclusive:
+/// either proxy_pass to an existing HTTP service (resolved exactly like a
+/// Host-routed service is today) or a literal redirect.
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct HttpRoute {
+    #[prost(string, tag = "1")]
+    pub host: ::prost::alloc::string::String,
+    #[prost(string, tag = "2")]
+    pub path_prefix: ::prost::alloc::string::String,
+    #[prost(oneof = "http_route::Target", tags = "3, 4")]
+    pub target: ::core::option::Option<http_route::Target>,
+}
+/// Nested message and enum types in `HttpRoute`.
+pub mod http_route {
+    #[derive(Clone, PartialEq, Eq, Hash, ::prost::Oneof)]
+    pub enum Target {
+        #[prost(string, tag = "3")]
+        ServiceName(::prost::alloc::string::String),
+        #[prost(message, tag = "4")]
+        Redirect(super::HttpRedirect),
+    }
+}
+/// A literal redirect target for an HttpRoute. `to` is either an absolute URL
+/// (used verbatim) or a path (starting with `/`; same scheme/host as the
+/// incoming request, target path substituted). No variable interpolation.
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct HttpRedirect {
+    #[prost(string, tag = "1")]
+    pub to: ::prost::alloc::string::String,
+    /// One of 301/302/307/308.
+    #[prost(uint32, tag = "2")]
+    pub status_code: u32,
+}
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct HttpRouteBundle {
+    #[prost(message, repeated, tag = "1")]
+    pub routes: ::prost::alloc::vec::Vec<HttpRoute>,
+}
 #[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
 pub struct BackendTriggerRequest {
     #[prost(string, tag = "1")]
@@ -1163,6 +1203,34 @@ pub mod nullnet_grpc_client {
                 );
             self.inner.server_streaming(req, path, codec).await
         }
+        /// Long-lived stream: the server pushes the full HTTP (host, path) → target
+        /// route table immediately on subscribe and again whenever services.toml
+        /// changes, so the proxy dispatches path-based routes/redirects without a
+        /// restart. See docs/http-path-routing-design.md.
+        pub async fn watch_http_routes(
+            &mut self,
+            request: impl tonic::IntoRequest<super::Empty>,
+        ) -> std::result::Result<
+            tonic::Response<tonic::codec::Streaming<super::HttpRouteBundle>>,
+            tonic::Status,
+        > {
+            self.inner
+                .ready()
+                .await
+                .map_err(|e| {
+                    tonic::Status::unknown(
+                        format!("Service was not ready: {}", e.into()),
+                    )
+                })?;
+            let codec = tonic_prost::ProstCodec::default();
+            let path = http::uri::PathAndQuery::from_static(
+                "/nullnet_grpc.NullnetGrpc/WatchHttpRoutes",
+            );
+            let mut req = request.into_request();
+            req.extensions_mut()
+                .insert(GrpcMethod::new("nullnet_grpc.NullnetGrpc", "WatchHttpRoutes"));
+            self.inner.server_streaming(req, path, codec).await
+        }
     }
 }
 /// Generated server implementations.
@@ -1292,6 +1360,23 @@ pub mod nullnet_grpc_server {
             tonic::Response<Self::WatchPortMappingsStream>,
             tonic::Status,
         >;
+        /// Server streaming response type for the WatchHttpRoutes method.
+        type WatchHttpRoutesStream: tonic::codegen::tokio_stream::Stream<
+                Item = std::result::Result<super::HttpRouteBundle, tonic::Status>,
+            >
+            + std::marker::Send
+            + 'static;
+        /// Long-lived stream: the server pushes the full HTTP (host, path) → target
+        /// route table immediately on subscribe and again whenever services.toml
+        /// changes, so the proxy dispatches path-based routes/redirects without a
+        /// restart. See docs/http-path-routing-design.md.
+        async fn watch_http_routes(
+            &self,
+            request: tonic::Request<super::Empty>,
+        ) -> std::result::Result<
+            tonic::Response<Self::WatchHttpRoutesStream>,
+            tonic::Status,
+        >;
     }
     #[derive(Debug)]
     pub struct NullnetGrpcServer<T> {
@@ -1914,6 +1999,52 @@ pub mod nullnet_grpc_server {
                     };
                     Box::pin(fut)
                 }
+                "/nullnet_grpc.NullnetGrpc/WatchHttpRoutes" => {
+                    #[allow(non_camel_case_types)]
+                    struct WatchHttpRoutesSvc<T: NullnetGrpc>(pub Arc<T>);
+                    impl<
+                        T: NullnetGrpc,
+                    > tonic::server::ServerStreamingService<super::Empty>
+                    for WatchHttpRoutesSvc<T> {
+                        type Response = super::HttpRouteBundle;
+                        type ResponseStream = T::WatchHttpRoutesStream;
+                        type Future = BoxFuture<
+                            tonic::Response<Self::ResponseStream>,
+                            tonic::Status,
+                        >;
+                        fn call(
+                            &mut self,
+                            request: tonic::Request<super::Empty>,
+                        ) -> Self::Future {
+                            let inner = Arc::clone(&self.0);
+                            let fut = async move {
+                                <T as NullnetGrpc>::watch_http_routes(&inner, request).await
+                            };
+                            Box::pin(fut)
+                        }
+                    }
+                    let accept_compression_encodings = self.accept_compression_encodings;
+                    let send_compression_encodings = self.send_compression_encodings;
+                    let max_decoding_message_size = self.max_decoding_message_size;
+                    let max_encoding_message_size = self.max_encoding_message_size;
+                    let inner = self.inner.clone();
+                    let fut = async move {
+                        let method = WatchHttpRoutesSvc(inner);
+                        let codec = tonic_prost::ProstCodec::default();
+                        let mut grpc = tonic::server::Grpc::new(codec)
+                            .apply_compression_config(
+                                accept_compression_encodings,
+                                send_compression_encodings,
+                            )
+                            .apply_max_message_size_config(
+                                max_decoding_message_size,
+                                max_encoding_message_size,
+                            );
+                        let res = grpc.server_streaming(method, req).await;
+                        Ok(res)
+                    };
+                    Box::pin(fut)
+                }
                 _ => {
                     Box::pin(async move {
                         let mut response = http::Response::new(

From 64356fe559f542e67595c863116bf0e92af0e942 Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 13:55:14 -0400
Subject: [PATCH 04/14] server: HTTP path-based route config, validation, and
 distribution (#137)

Adds [[route]] TOML entries (host + path prefix -> service or literal
redirect), validated the same way [[services]] already is (mutual
exclusion, redirect status code, in-stack/http/proxy-reachable service
checks), plus a cross-stack (host, path) conflict check mirroring
detect_port_conflicts. build_http_route_bundle folds in an implicit
{host=name, path="/"} fallback for every proxy-reachable http service
with no explicit route, so installs with zero [[route]] entries keep
today's plain Host-header routing unchanged.

Distributed to the proxy via a new WatchHttpRoutes stream, following the
existing WatchCertificates/WatchPortMappings pattern exactly (its own
watch::Receiver + Notify, pushed on every services.toml change).

Adds GET/POST /api/routes/{stack} for the admin UI: POST re-runs the same
validation and merges the new route list into the stack's TOML file via
toml_edit (new dependency) so services/comments/formatting are preserved,
instead of round-tripping the whole document through serde.

[[services]] is now #[serde(default)] so a stack can be routes-only (a
bare redirect needs no backend at all).

See docs/http-path-routing-design.md.
---
 Cargo.lock                                    |  17 +
 Cargo.toml                                    |   1 +
 members/nullnet-server/Cargo.toml             |   1 +
 members/nullnet-server/src/events.rs          |  24 +
 .../nullnet-server/src/http_server/config.rs  |  43 +-
 members/nullnet-server/src/http_server/mod.rs |  11 +-
 .../nullnet-server/src/http_server/routes.rs  | 254 +++++++++
 members/nullnet-server/src/main.rs            |   1 +
 .../nullnet-server/src/nullnet_grpc_impl.rs   | 261 +++++++++-
 members/nullnet-server/src/services/input.rs  | 485 ++++++++++++++++--
 10 files changed, 1049 insertions(+), 49 deletions(-)
 create mode 100644 members/nullnet-server/src/http_server/routes.rs

diff --git a/Cargo.lock b/Cargo.lock
index a06bf9a..2daef20 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3335,6 +3335,7 @@ dependencies = [
  "tokio",
  "tokio-stream",
  "toml 1.1.2+spec-1.1.0",
+ "toml_edit",
  "tonic",
  "tonic-prost",
  "totp-rs",
@@ -5422,6 +5423,19 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "toml_edit"
+version = "0.23.10+spec-1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84c8b9f757e028cee9fa244aea147aab2a9ec09d5325a9b01e0a49730c2b5269"
+dependencies = [
+ "indexmap 2.14.0",
+ "toml_datetime 0.7.5+spec-1.1.0",
+ "toml_parser",
+ "toml_writer",
+ "winnow 0.7.15",
+]
+
 [[package]]
 name = "toml_parser"
 version = "1.1.2+spec-1.1.0"
@@ -6294,6 +6308,9 @@ name = "winnow"
 version = "0.7.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+dependencies = [
+ "memchr",
+]
 
 [[package]]
 name = "winnow"
diff --git a/Cargo.toml b/Cargo.toml
index d8d0b4f..8517a4d 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -16,6 +16,7 @@ tokio = "1.51.1"
 serde = "1.0.228"
 serde_json = "1.0"
 toml = "1.1.2"
+toml_edit = "0.23"
 chrono = "0.4.44"
 gag = "1.0.0"
 ipnetwork = "0.21.1"
diff --git a/members/nullnet-server/Cargo.toml b/members/nullnet-server/Cargo.toml
index b640c1f..0b8813e 100644
--- a/members/nullnet-server/Cargo.toml
+++ b/members/nullnet-server/Cargo.toml
@@ -20,6 +20,7 @@ ctrlc = { version = "3.5.2", features = ["termination"] }
 serde = { workspace = true, features = ["derive"] }
 serde_json.workspace = true
 toml.workspace = true
+toml_edit.workspace = true
 uuid = { version = "1.23.0", features = ["v4"] }
 ipnetwork.workspace = true
 notify.workspace = true
diff --git a/members/nullnet-server/src/events.rs b/members/nullnet-server/src/events.rs
index 9ce0fc1..6d6703c 100644
--- a/members/nullnet-server/src/events.rs
+++ b/members/nullnet-server/src/events.rs
@@ -110,6 +110,13 @@ pub(crate) enum Event {
         listen_port: u16,
         timestamp: u64,
     },
+    RouteConflict {
+        stack_a: String,
+        stack_b: String,
+        host: String,
+        path: String,
+        timestamp: u64,
+    },
     AllReplicasRemoved {
         service: String,
         stack: String,
@@ -362,6 +369,7 @@ impl Event {
             Self::ConfigReloaded { .. } => "config_reloaded",
             Self::ConfigStackRemoved { .. } => "config_stack_removed",
             Self::PortMappingConflict { .. } => "port_mapping_conflict",
+            Self::RouteConflict { .. } => "route_conflict",
             Self::AllReplicasRemoved { .. } => "all_replicas_removed",
             Self::ServiceReachabilityToggled { .. } => "service_reachability_toggled",
             Self::ProxyClientTimedOut { .. } => "proxy_client_timed_out",
@@ -465,6 +473,7 @@ impl Event {
             | Self::ProxyClientNotInet { .. }
             | Self::TlsCertificateInvalid { .. }
             | Self::PortMappingConflict { .. }
+            | Self::RouteConflict { .. }
             | Self::TcpListenerBindFailed { .. }
             | Self::UdpListenerBindFailed { .. }
             | Self::TcpUpstreamConnectFailed { .. }
@@ -601,6 +610,21 @@ impl Event {
         }
     }
 
+    pub(crate) fn route_conflict(
+        stack_a: String,
+        stack_b: String,
+        host: String,
+        path: String,
+    ) -> Self {
+        Self::RouteConflict {
+            stack_a,
+            stack_b,
+            host,
+            path,
+            timestamp: now_secs(),
+        }
+    }
+
     pub(crate) fn all_replicas_removed(service: String, stack: String, ip: String) -> Self {
         Self::AllReplicasRemoved {
             service,
diff --git a/members/nullnet-server/src/http_server/config.rs b/members/nullnet-server/src/http_server/config.rs
index 90346ff..70b6ab3 100644
--- a/members/nullnet-server/src/http_server/config.rs
+++ b/members/nullnet-server/src/http_server/config.rs
@@ -1,7 +1,7 @@
 use super::AppState;
 use super::auth::{AuthContext, require_scope};
 use crate::auth::Scope;
-use crate::services::input::{detect_port_conflicts, validate_stack_toml};
+use crate::services::input::{detect_port_conflicts, detect_route_conflicts, validate_stack_toml};
 use axum::extract::{Extension, Path, State};
 use axum::http::{StatusCode, header};
 use axum::response::{IntoResponse, Response};
@@ -12,7 +12,7 @@ use serde::Serialize;
 /// the UI enforces (`[A-Za-z0-9_-]+`) — this also rejects path separators, dots,
 /// NUL, whitespace, and control characters, which would traverse, fail the write
 /// with a 500, or create ghost files.
-fn valid_stack_name(stack: &str) -> bool {
+pub(super) fn valid_stack_name(stack: &str) -> bool {
     !stack.is_empty()
         && stack
             .chars()
@@ -48,13 +48,21 @@ pub(super) async fn config_handler(
 }
 
 #[derive(Serialize)]
-struct SaveResult {
+pub(super) struct SaveResult {
     ok: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
     error: Option<String>,
 }
 
-fn rejected(status: StatusCode, error: impl Into<String>) -> Response {
+pub(super) fn saved_ok() -> Response {
+    axum::Json(SaveResult {
+        ok: true,
+        error: None,
+    })
+    .into_response()
+}
+
+pub(super) fn rejected(status: StatusCode, error: impl Into<String>) -> Response {
     (
         status,
         axum::Json(SaveResult {
@@ -84,8 +92,8 @@ pub(super) async fn save_handler(
     }
 
     // 1. Syntax + semantic validation (mirrors the loader).
-    let parsed = match validate_stack_toml(&body) {
-        Ok(map) => map,
+    let (parsed, parsed_routes) = match validate_stack_toml(&body) {
+        Ok(parsed) => parsed,
         Err(e) => return rejected(StatusCode::UNPROCESSABLE_ENTITY, e),
     };
 
@@ -111,6 +119,29 @@ pub(super) async fn save_handler(
         );
     }
 
+    // 2b. Cross-stack route conflicts: same idea, for this stack's `[[route]]`
+    //     (host, path) pairs — including its own explicit routes clashing
+    //     with each other.
+    let mut candidate_routes = state.routes.read().await.clone();
+    candidate_routes.insert(stack.clone(), parsed_routes);
+    if let Some(c) = detect_route_conflicts(&candidate_routes)
+        .into_iter()
+        .find(|c| c.stack_a == stack || c.stack_b == stack)
+    {
+        let other_stack = if c.stack_a == stack {
+            c.stack_b
+        } else {
+            c.stack_a
+        };
+        return rejected(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            format!(
+                "route '{} {}' already claimed by stack '{other_stack}'",
+                c.host, c.path
+            ),
+        );
+    }
+
     // 3. Valid → persist. The services watcher picks up the write and applies it.
     let path = format!("./services/{stack}.toml");
     if tokio::fs::write(&path, body).await.is_err() {
diff --git a/members/nullnet-server/src/http_server/mod.rs b/members/nullnet-server/src/http_server/mod.rs
index cf5e63c..710db75 100644
--- a/members/nullnet-server/src/http_server/mod.rs
+++ b/members/nullnet-server/src/http_server/mod.rs
@@ -1,7 +1,7 @@
 use crate::db::Db;
 use crate::events::EventStore;
 use crate::orchestrator::Orchestrator;
-use crate::services::input::StackMap;
+use crate::services::input::{RouteMap, StackMap};
 use axum::Router;
 use axum::routing::{delete, get, patch, post};
 use std::net::{IpAddr, Ipv4Addr, SocketAddr};
@@ -17,6 +17,7 @@ mod events_stream;
 mod graph;
 mod health;
 mod nodes;
+mod routes;
 mod services;
 mod sessions;
 mod stacks;
@@ -27,6 +28,10 @@ const HTTP_PORT: u16 = 8080;
 #[derive(Clone)]
 pub(crate) struct AppState {
     pub(crate) services: Arc<RwLock<StackMap>>,
+    /// Explicit `[[route]]` entries, partitioned by stack name — read for
+    /// cross-stack `(host, path)` conflict checks on config/route saves. See
+    /// docs/http-path-routing-design.md.
+    pub(crate) routes: Arc<RwLock<RouteMap>>,
     pub(crate) orchestrator: Orchestrator,
     pub(crate) events: EventStore,
     pub(crate) db: Db,
@@ -46,6 +51,10 @@ pub async fn serve(state: AppState) {
                 .post(config::save_handler)
                 .delete(config::delete_handler),
         )
+        .route(
+            "/api/routes/{stack}",
+            get(routes::routes_handler).post(routes::save_handler),
+        )
         .route("/api/graph/{stack}", get(graph::graph_handler))
         .route("/api/sessions/{stack}", get(sessions::list_handler))
         .route(
diff --git a/members/nullnet-server/src/http_server/routes.rs b/members/nullnet-server/src/http_server/routes.rs
new file mode 100644
index 0000000..c33110b
--- /dev/null
+++ b/members/nullnet-server/src/http_server/routes.rs
@@ -0,0 +1,254 @@
+use super::AppState;
+use super::auth::{AuthContext, require_scope};
+use super::config::{rejected, saved_ok, valid_stack_name};
+use crate::auth::Scope;
+use crate::services::input::{RouteEntry, RouteTarget, detect_route_conflicts};
+use axum::Json;
+use axum::extract::{Extension, Path, State};
+use axum::http::StatusCode;
+use axum::response::{IntoResponse, Response};
+use nullnet_grpc_lib::nullnet_grpc::ServiceProtocol;
+use serde::{Deserialize, Serialize};
+
+/// One route as exchanged with the UI — mirrors `RouteEntry`/`HttpRoute`,
+/// JSON-tagged so a service target and a redirect target are unambiguous on
+/// the wire: `{"kind":"service","service":"grafana"}` vs
+/// `{"kind":"redirect","to":"...","status":301}`. See
+/// docs/http-path-routing-design.md.
+#[derive(Serialize, Deserialize, Clone)]
+#[serde(tag = "kind", rename_all = "lowercase")]
+pub(super) enum RouteTargetJson {
+    Service { service: String },
+    Redirect { to: String, status: u16 },
+}
+
+#[derive(Serialize, Deserialize, Clone)]
+pub(super) struct RouteJson {
+    host: String,
+    path: String,
+    target: RouteTargetJson,
+}
+
+impl From<&RouteEntry> for RouteJson {
+    fn from(r: &RouteEntry) -> Self {
+        RouteJson {
+            host: r.host.clone(),
+            path: r.path.clone(),
+            target: match &r.target {
+                RouteTarget::Service(service) => RouteTargetJson::Service {
+                    service: service.clone(),
+                },
+                RouteTarget::Redirect { to, status } => RouteTargetJson::Redirect {
+                    to: to.clone(),
+                    status: *status,
+                },
+            },
+        }
+    }
+}
+
+#[derive(Serialize)]
+struct RoutesResponse {
+    routes: Vec<RouteJson>,
+    /// Every declared, proxy-reachable `protocol = "http"` service name in
+    /// this stack — populates the UI's service-target dropdown. Kept as a
+    /// field on this endpoint's response rather than added to
+    /// `services::ServiceJson`, so the services list stays untouched.
+    http_services: Vec<String>,
+}
+
+/// GET the stack's explicit routes plus the http service names a new route
+/// could target.
+pub(super) async fn routes_handler(
+    Extension(ctx): Extension<AuthContext>,
+    Path(stack): Path<String>,
+    State(state): State<AppState>,
+) -> Response {
+    if let Err(resp) = require_scope(&ctx, Scope::ConfigRead) {
+        return resp;
+    }
+    let services = state.services.read().await;
+    let Some(stack_map) = services.get(&stack) else {
+        return StatusCode::NOT_FOUND.into_response();
+    };
+    let mut http_services: Vec<String> = stack_map
+        .iter()
+        .filter(|(_, info)| info.protocol() == ServiceProtocol::Http && info.timeout().is_some())
+        .map(|(name, _)| name.clone())
+        .collect();
+    http_services.sort();
+    drop(services);
+
+    let routes = state.routes.read().await;
+    let routes: Vec<RouteJson> = routes
+        .get(&stack)
+        .map(|entries| entries.iter().map(RouteJson::from).collect())
+        .unwrap_or_default();
+
+    axum::Json(RoutesResponse {
+        routes,
+        http_services,
+    })
+    .into_response()
+}
+
+/// POST the stack's full route list (whole-list replace, like the raw-TOML
+/// config save). Re-runs the same validation the TOML loader enforces
+/// (mutual exclusion, redirect status code, service exists/is
+/// http/proxy-reachable, cross-stack `(host, path)` uniqueness), then merges
+/// the new `[[route]]` array into the stack's existing TOML file — leaving
+/// its `[[services]]` entries, comments, and formatting untouched — and
+/// writes it. The `./services` watcher picks up the write and applies it the
+/// same way any other config edit is applied.
+pub(super) async fn save_handler(
+    Extension(ctx): Extension<AuthContext>,
+    Path(stack): Path<String>,
+    State(state): State<AppState>,
+    Json(body): Json<Vec<RouteJson>>,
+) -> Response {
+    if let Err(resp) = require_scope(&ctx, Scope::ConfigWrite) {
+        return resp;
+    }
+    if !valid_stack_name(&stack) {
+        return rejected(StatusCode::BAD_REQUEST, "invalid stack name");
+    }
+
+    // 1. Validate each route's target against this stack's declared services.
+    let services = state.services.read().await;
+    let Some(stack_map) = services.get(&stack) else {
+        return rejected(StatusCode::NOT_FOUND, "stack not found");
+    };
+    let mut entries = Vec::with_capacity(body.len());
+    for r in &body {
+        match &r.target {
+            RouteTargetJson::Service { service } => {
+                let Some(info) = stack_map.get(service) else {
+                    return rejected(
+                        StatusCode::UNPROCESSABLE_ENTITY,
+                        format!(
+                            "route '{} {}': service '{service}' is not declared in this stack",
+                            r.host, r.path
+                        ),
+                    );
+                };
+                if info.protocol() != ServiceProtocol::Http {
+                    return rejected(
+                        StatusCode::UNPROCESSABLE_ENTITY,
+                        format!(
+                            "route '{} {}': service '{service}' is not protocol http",
+                            r.host, r.path
+                        ),
+                    );
+                }
+                if info.timeout().is_none() {
+                    return rejected(
+                        StatusCode::UNPROCESSABLE_ENTITY,
+                        format!(
+                            "route '{} {}': service '{service}' has no 'timeout', so it isn't a \
+                             proxy-reachable entry point",
+                            r.host, r.path
+                        ),
+                    );
+                }
+                entries.push(RouteEntry {
+                    host: r.host.clone(),
+                    path: r.path.clone(),
+                    target: RouteTarget::Service(service.clone()),
+                });
+            }
+            RouteTargetJson::Redirect { to, status } => {
+                if !matches!(status, 301 | 302 | 307 | 308) {
+                    return rejected(
+                        StatusCode::UNPROCESSABLE_ENTITY,
+                        format!(
+                            "route '{} {}': redirect_status {status} must be one of 301/302/307/308",
+                            r.host, r.path
+                        ),
+                    );
+                }
+                entries.push(RouteEntry {
+                    host: r.host.clone(),
+                    path: r.path.clone(),
+                    target: RouteTarget::Redirect {
+                        to: to.clone(),
+                        status: *status,
+                    },
+                });
+            }
+        }
+    }
+    drop(services);
+
+    // 2. Cross-stack (host, path) conflicts — same check the raw-TOML save uses.
+    let mut candidate = state.routes.read().await.clone();
+    candidate.insert(stack.clone(), entries);
+    if let Some(c) = detect_route_conflicts(&candidate)
+        .into_iter()
+        .find(|c| c.stack_a == stack || c.stack_b == stack)
+    {
+        let other_stack = if c.stack_a == stack {
+            c.stack_b
+        } else {
+            c.stack_a
+        };
+        return rejected(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            format!(
+                "route '{} {}' already claimed by stack '{other_stack}'",
+                c.host, c.path
+            ),
+        );
+    }
+
+    // 3. Valid → merge into the stack's TOML file and persist.
+    let path = format!("./services/{stack}.toml");
+    let content = match tokio::fs::read_to_string(&path).await {
+        Ok(c) => c,
+        Err(_) => return rejected(StatusCode::NOT_FOUND, "stack not found"),
+    };
+    let new_content = match merge_routes_into_toml(&content, &body) {
+        Ok(c) => c,
+        Err(e) => return rejected(StatusCode::INTERNAL_SERVER_ERROR, e),
+    };
+    if tokio::fs::write(&path, new_content).await.is_err() {
+        return rejected(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "failed to write configuration file",
+        );
+    }
+    saved_ok()
+}
+
+/// Replace the `[[route]]` array in `content` with `routes`, leaving every
+/// other table — `[[services]]`, comments, formatting — untouched.
+/// `toml_edit`'s structural editing (rather than a plain `toml`/serde
+/// round-trip of the whole document) is what makes that possible.
+fn merge_routes_into_toml(content: &str, routes: &[RouteJson]) -> Result<String, String> {
+    let mut doc: toml_edit::DocumentMut = content
+        .parse()
+        .map_err(|e: toml_edit::TomlError| e.to_string())?;
+
+    let mut array = toml_edit::ArrayOfTables::new();
+    for r in routes {
+        let mut table = toml_edit::Table::new();
+        table.insert("host", toml_edit::value(r.host.clone()));
+        table.insert("path", toml_edit::value(r.path.clone()));
+        match &r.target {
+            RouteTargetJson::Service { service } => {
+                table.insert("service", toml_edit::value(service.clone()));
+            }
+            RouteTargetJson::Redirect { to, status } => {
+                table.insert("redirect_to", toml_edit::value(to.clone()));
+                table.insert("redirect_status", toml_edit::value(i64::from(*status)));
+            }
+        }
+        array.push(table);
+    }
+
+    if array.is_empty() {
+        doc.remove("route");
+    } else {
+        doc["route"] = toml_edit::Item::ArrayOfTables(array);
+    }
+    Ok(doc.to_string())
+}
diff --git a/members/nullnet-server/src/main.rs b/members/nullnet-server/src/main.rs
index 7d80f46..3b379ac 100644
--- a/members/nullnet-server/src/main.rs
+++ b/members/nullnet-server/src/main.rs
@@ -101,6 +101,7 @@ async fn main() -> Result<(), Error> {
     let nullnet = init_nullnet().await?;
     let app_state = http_server::AppState {
         services: nullnet.services().clone(),
+        routes: nullnet.routes().clone(),
         events: nullnet.orchestrator().events.clone(),
         orchestrator: nullnet.orchestrator().clone(),
         db,
diff --git a/members/nullnet-server/src/nullnet_grpc_impl.rs b/members/nullnet-server/src/nullnet_grpc_impl.rs
index 21856bc..348fb67 100644
--- a/members/nullnet-server/src/nullnet_grpc_impl.rs
+++ b/members/nullnet-server/src/nullnet_grpc_impl.rs
@@ -13,15 +13,17 @@ use crate::services::changes::{
 };
 use crate::services::clients::{Client, ClientInfo};
 use crate::services::edge::{Edge, RegisteredEdge};
-use crate::services::input::{MatchIndex, ServicesToml, StackMap};
+use crate::services::input::{MatchIndex, RouteMap, RouteTarget, ServicesToml, StackMap};
 use crate::services::service_info::{CountryPolicy, ServiceInfo, backend_involved_services};
 use crate::timeout::check_timeouts;
 use nullnet_grpc_lib::nullnet_grpc::nullnet_grpc_server::NullnetGrpc;
 use nullnet_grpc_lib::nullnet_grpc::{
     AgentEvent, BackendTriggerRequest, CertBundle, EgressDestinationReport, EgressPolicyCheck,
-    EgressPolicyVerdict, EgressTriggerRequest, Empty, IngressPolicyCheck, IngressPolicyVerdict,
-    MsgId, Net, NetMessage, NetType, PortMapping, PortMappingBundle, ProxyRequest, ServiceReport,
-    ServiceTrigger, ServicesListResponse, Upstream, agent_event::Event as AgentEventKind,
+    EgressPolicyVerdict, EgressTriggerRequest, Empty, HttpRedirect, HttpRoute, HttpRouteBundle,
+    IngressPolicyCheck, IngressPolicyVerdict, MsgId, Net, NetMessage, NetType, PortMapping,
+    PortMappingBundle, ProxyRequest, ServiceProtocol, ServiceReport, ServiceTrigger,
+    ServicesListResponse, Upstream, agent_event::Event as AgentEventKind,
+    http_route::Target as HttpRouteTarget,
 };
 use nullnet_liberror::{Error, ErrorHandler, Location, location};
 use std::collections::{HashMap, HashSet};
@@ -38,6 +40,12 @@ pub(crate) struct NullnetGrpcImpl {
     /// Host-match index (stack → match entries), rebuilt alongside `services`.
     /// Used to join a client's raw observations to the services it hosts.
     match_index: Arc<RwLock<MatchIndex>>,
+    /// Explicit `[[route]]` entries, partitioned by stack name, rebuilt
+    /// alongside `services`. The admin API reads this for cross-stack
+    /// `(host, path)` conflict checks on save; see `build_http_route_bundle`
+    /// for how it's turned into the wire table (including implicit fallback
+    /// routes) the proxy actually consumes.
+    routes: Arc<RwLock<RouteMap>>,
     /// Orchestrator to manage TAP-based clients and NET setups
     orchestrator: Orchestrator,
     /// Latest TLS certificate set, kept in sync with `./certs` by a watcher.
@@ -46,6 +54,10 @@ pub(crate) struct NullnetGrpcImpl {
     /// Live TCP/UDP port→service table, derived from `services` and refreshed
     /// on every services.toml change. Proxies subscribe for updates.
     port_mappings: watch::Receiver<PortMappingBundle>,
+    /// Live HTTP (host, path) → target route table, derived from `services`/
+    /// `routes` and refreshed on every services.toml change. Proxies
+    /// subscribe for updates. See docs/http-path-routing-design.md.
+    http_routes: watch::Receiver<HttpRouteBundle>,
     /// One lock per in-flight proxy request identity, so concurrent duplicates
     /// are serialized rather than each building the same chain. See
     /// [`NullnetGrpcImpl::handle_proxy_request`].
@@ -84,6 +96,55 @@ fn build_port_mapping_bundle(stacks: &StackMap) -> PortMappingBundle {
     PortMappingBundle { mappings }
 }
 
+/// Build the live HTTP `(host, path)` → target route table from the current
+/// `StackMap`/`RouteMap`: every explicit `[[route]]` entry, plus an implicit
+/// `{host = name, path = "/"} -> Service(name)` fallback for every
+/// proxy-reachable http service whose name isn't already claimed as a host by
+/// an explicit route in *any* stack — so an install with no `[[route]]`
+/// entries at all keeps today's plain Host-header routing unchanged. See
+/// docs/http-path-routing-design.md.
+fn build_http_route_bundle(stacks: &StackMap, routes: &RouteMap) -> HttpRouteBundle {
+    let explicit_hosts: HashSet<&str> = routes
+        .values()
+        .flat_map(|entries| entries.iter().map(|r| r.host.as_str()))
+        .collect();
+
+    let mut wire_routes: Vec<HttpRoute> = routes
+        .values()
+        .flat_map(|entries| entries.iter())
+        .map(|r| HttpRoute {
+            host: r.host.clone(),
+            path_prefix: r.path.clone(),
+            target: Some(match &r.target {
+                RouteTarget::Service(name) => HttpRouteTarget::ServiceName(name.clone()),
+                RouteTarget::Redirect { to, status } => HttpRouteTarget::Redirect(HttpRedirect {
+                    to: to.clone(),
+                    status_code: u32::from(*status),
+                }),
+            }),
+        })
+        .collect();
+
+    for (name, info) in stacks.values().flat_map(HashMap::iter) {
+        if info.protocol() != ServiceProtocol::Http || info.timeout().is_none() {
+            continue;
+        }
+        if explicit_hosts.contains(name.as_str()) {
+            continue;
+        }
+        wire_routes.push(HttpRoute {
+            host: name.clone(),
+            path_prefix: "/".to_string(),
+            target: Some(HttpRouteTarget::ServiceName(name.clone())),
+        });
+    }
+
+    println!("[http-routes] bundle built: {} route(s)", wire_routes.len());
+    HttpRouteBundle {
+        routes: wire_routes,
+    }
+}
+
 /// Build the trigger config for one node: the triggers of the services it
 /// declared as hosting, each carrying the real container names hosting that
 /// service *there*.
@@ -151,9 +212,10 @@ fn find_service_stack<'a>(services: &'a StackMap, service_name: &str) -> Option<
 
 impl NullnetGrpcImpl {
     pub async fn new() -> Result<Self, Error> {
-        let (stacks, index) = ServicesToml::load_validated().await?;
+        let (stacks, index, route_map) = ServicesToml::load_validated().await?;
         let services = Arc::new(RwLock::new(stacks));
         let match_index = Arc::new(RwLock::new(index));
+        let routes = Arc::new(RwLock::new(route_map));
 
         // regenerate the service graphviz periodically for debugging
         let services_2 = services.clone();
@@ -167,20 +229,25 @@ impl NullnetGrpcImpl {
         // one waiter, so each consumer needs its own `Notify` rather than
         // racing `check_timeouts` for the same wake-up.
         let port_mappings_changed = Arc::new(Notify::new());
+        let http_routes_changed = Arc::new(Notify::new());
 
         // keep services up to date with the services.toml file
         let services_2 = services.clone();
         let match_index_2 = match_index.clone();
+        let routes_2 = routes.clone();
         let orchestrator_2 = orchestrator.clone();
         let config_changed_2 = config_changed.clone();
         let port_mappings_changed_2 = port_mappings_changed.clone();
+        let http_routes_changed_2 = http_routes_changed.clone();
         tokio::spawn(async move {
             if let Err(e) = ServicesToml::watch(
                 &services_2,
                 &match_index_2,
+                &routes_2,
                 orchestrator_2,
                 config_changed_2,
                 port_mappings_changed_2,
+                http_routes_changed_2,
             )
             .await
             {
@@ -202,6 +269,24 @@ impl NullnetGrpcImpl {
             }
         });
 
+        // live HTTP (host, path)→target route table, refreshed whenever
+        // services.toml changes
+        let initial_routes =
+            build_http_route_bundle(&*services.read().await, &*routes.read().await);
+        let (http_routes_tx, http_routes_rx) = watch::channel(initial_routes);
+        let services_2 = services.clone();
+        let routes_2 = routes.clone();
+        tokio::spawn(async move {
+            loop {
+                http_routes_changed.notified().await;
+                let bundle =
+                    build_http_route_bundle(&*services_2.read().await, &*routes_2.read().await);
+                if http_routes_tx.send(bundle).is_err() {
+                    break;
+                }
+            }
+        });
+
         // periodically check for timed-out proxy clients and tear down their chains
         let services_2 = services.clone();
         let orchestrator_2 = orchestrator.clone();
@@ -220,9 +305,11 @@ impl NullnetGrpcImpl {
         Ok(NullnetGrpcImpl {
             services,
             match_index,
+            routes,
             orchestrator,
             certs: certs_rx,
             port_mappings: port_mappings_rx,
+            http_routes: http_routes_rx,
             inflight_proxy: Arc::new(StdMutex::new(HashMap::new())),
         })
     }
@@ -1124,6 +1211,10 @@ impl NullnetGrpcImpl {
         &self.services
     }
 
+    pub(crate) fn routes(&self) -> &Arc<RwLock<RouteMap>> {
+        &self.routes
+    }
+
     pub(crate) fn orchestrator(&self) -> &Orchestrator {
         &self.orchestrator
     }
@@ -1561,12 +1652,15 @@ impl NullnetGrpcImpl {
     pub(crate) fn new_for_test(services: StackMap) -> Self {
         let (_, certs) = watch::channel(CertBundle::default());
         let (_, port_mappings) = watch::channel(PortMappingBundle::default());
+        let (_, http_routes) = watch::channel(HttpRouteBundle::default());
         NullnetGrpcImpl {
             services: Arc::new(RwLock::new(services)),
             match_index: Arc::new(RwLock::new(MatchIndex::new())),
+            routes: Arc::new(RwLock::new(RouteMap::new())),
             orchestrator: Orchestrator::new(),
             certs,
             port_mappings,
+            http_routes,
             inflight_proxy: Arc::new(StdMutex::new(HashMap::new())),
         }
     }
@@ -1728,6 +1822,30 @@ impl NullnetGrpc for NullnetGrpcImpl {
         Ok(Response::new(ReceiverStream::new(rx)))
     }
 
+    type WatchHttpRoutesStream = ReceiverStream<Result<HttpRouteBundle, Status>>;
+
+    async fn watch_http_routes(
+        &self,
+        _: Request<Empty>,
+    ) -> Result<Response<Self::WatchHttpRoutesStream>, Status> {
+        let mut routes = self.http_routes.clone();
+        let (tx, rx) = mpsc::channel(4);
+        tokio::spawn(async move {
+            // send the current table immediately, then one snapshot per change
+            let initial = routes.borrow_and_update().clone();
+            if tx.send(Ok(initial)).await.is_err() {
+                return;
+            }
+            while routes.changed().await.is_ok() {
+                let snapshot = routes.borrow_and_update().clone();
+                if tx.send(Ok(snapshot)).await.is_err() {
+                    break;
+                }
+            }
+        });
+        Ok(Response::new(ReceiverStream::new(rx)))
+    }
+
     async fn report_event(&self, req: Request<AgentEvent>) -> Result<Response<Empty>, Status> {
         let Some(kind) = req.into_inner().event else {
             return Ok(Response::new(Empty {}));
@@ -1831,3 +1949,136 @@ impl NullnetGrpc for NullnetGrpcImpl {
         Ok(Response::new(Empty {}))
     }
 }
+
+#[cfg(test)]
+mod http_route_bundle_tests {
+    use super::*;
+    use crate::services::input::{RouteEntry, RouteTarget};
+    use crate::services::service_info::CountryPolicy;
+
+    fn http_service(timeout: Option<u64>) -> ServiceInfo {
+        ServiceInfo::new(
+            vec![],
+            HashMap::new(),
+            timeout,
+            None,
+            ServiceProtocol::Http,
+            None,
+            CountryPolicy::None,
+            CountryPolicy::None,
+        )
+    }
+
+    fn tcp_service(listen_port: u16) -> ServiceInfo {
+        ServiceInfo::new(
+            vec![],
+            HashMap::new(),
+            Some(0),
+            None,
+            ServiceProtocol::Tcp,
+            Some(listen_port),
+            CountryPolicy::None,
+            CountryPolicy::None,
+        )
+    }
+
+    #[test]
+    fn declares_no_routes_falls_back_to_implicit_host_route() {
+        let stacks: StackMap = HashMap::from([(
+            "alpha".to_string(),
+            HashMap::from([("grafana".to_string(), http_service(Some(30)))]),
+        )]);
+        let bundle = build_http_route_bundle(&stacks, &RouteMap::new());
+
+        assert_eq!(bundle.routes.len(), 1);
+        assert_eq!(bundle.routes[0].host, "grafana");
+        assert_eq!(bundle.routes[0].path_prefix, "/");
+        assert_eq!(
+            bundle.routes[0].target,
+            Some(HttpRouteTarget::ServiceName("grafana".to_string()))
+        );
+    }
+
+    #[test]
+    fn explicit_route_for_a_host_suppresses_its_implicit_fallback() {
+        let stacks: StackMap = HashMap::from([(
+            "alpha".to_string(),
+            HashMap::from([
+                ("grafana".to_string(), http_service(Some(30))),
+                ("gitlab".to_string(), http_service(Some(30))),
+            ]),
+        )]);
+        // "grafana" gets explicit path-based routes; "gitlab" gets none, so it
+        // still falls back to its own implicit `{host=name, path="/"}` route.
+        let routes: RouteMap = HashMap::from([(
+            "alpha".to_string(),
+            vec![RouteEntry {
+                host: "grafana".to_string(),
+                path: "/dashboards".to_string(),
+                target: RouteTarget::Service("grafana".to_string()),
+            }],
+        )]);
+        let bundle = build_http_route_bundle(&stacks, &routes);
+
+        assert_eq!(bundle.routes.len(), 2);
+        assert!(
+            bundle
+                .routes
+                .iter()
+                .any(|r| r.host == "grafana" && r.path_prefix == "/dashboards")
+        );
+        assert!(
+            bundle
+                .routes
+                .iter()
+                .any(|r| r.host == "gitlab" && r.path_prefix == "/"),
+            "gitlab has no explicit route, so it should keep its implicit fallback"
+        );
+        // no separate implicit "/" route synthesized for grafana on top of its
+        // explicit one
+        assert!(
+            !bundle
+                .routes
+                .iter()
+                .any(|r| r.host == "grafana" && r.path_prefix == "/")
+        );
+    }
+
+    #[test]
+    fn backend_only_and_non_http_services_get_no_implicit_route() {
+        let stacks: StackMap = HashMap::from([(
+            "alpha".to_string(),
+            HashMap::from([
+                ("backend.only".to_string(), http_service(None)),
+                ("redis".to_string(), tcp_service(6379)),
+            ]),
+        )]);
+        let bundle = build_http_route_bundle(&stacks, &RouteMap::new());
+        assert!(bundle.routes.is_empty());
+    }
+
+    #[test]
+    fn redirect_route_converts_to_wire_redirect() {
+        let routes: RouteMap = HashMap::from([(
+            "alpha".to_string(),
+            vec![RouteEntry {
+                host: "old.example.com".to_string(),
+                path: "/".to_string(),
+                target: RouteTarget::Redirect {
+                    to: "https://new.example.com/".to_string(),
+                    status: 301,
+                },
+            }],
+        )]);
+        let bundle = build_http_route_bundle(&StackMap::new(), &routes);
+
+        assert_eq!(bundle.routes.len(), 1);
+        assert_eq!(
+            bundle.routes[0].target,
+            Some(HttpRouteTarget::Redirect(HttpRedirect {
+                to: "https://new.example.com/".to_string(),
+                status_code: 301,
+            }))
+        );
+    }
+}
diff --git a/members/nullnet-server/src/services/input.rs b/members/nullnet-server/src/services/input.rs
index a578df5..6c96787 100644
--- a/members/nullnet-server/src/services/input.rs
+++ b/members/nullnet-server/src/services/input.rs
@@ -35,6 +35,145 @@ pub(crate) struct MatchEntry {
 /// Stack name → its services' match entries. Rebuilt on every load/reload.
 pub(crate) type MatchIndex = HashMap<String, Vec<MatchEntry>>;
 
+/// A parsed, validated `[[route]]` entry: an HTTP(S) dispatch rule matching
+/// `host` + a `path` prefix, to either an existing (in-stack, http-protocol)
+/// service or a literal redirect. See docs/http-path-routing-design.md.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) struct RouteEntry {
+    pub(crate) host: String,
+    pub(crate) path: String,
+    pub(crate) target: RouteTarget,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) enum RouteTarget {
+    Service(String),
+    Redirect { to: String, status: u16 },
+}
+
+/// Stack name → its explicit route entries. Rebuilt on every load/reload,
+/// alongside `StackMap`/`MatchIndex`. Implicit per-service fallback routes
+/// (an http service with no explicit route naming it) are *not* stored here
+/// — whether one applies depends on every stack's explicit routes, not just
+/// this one's, so they're derived at bundle-build time
+/// (`nullnet_grpc_impl::build_http_route_bundle`).
+pub(crate) type RouteMap = HashMap<String, Vec<RouteEntry>>;
+
+/// Validate and convert one stack's raw `[[route]]` entries against its
+/// `[[services]]` list: exactly one target (`service`/`redirect_to`) per
+/// route, a `service` target must name an in-stack, http-protocol service,
+/// and `redirect_status` (when present) must be a supported redirect code.
+/// `(host, path)` uniqueness — within this stack or across stacks — is a
+/// separate check; see `detect_route_conflicts`.
+fn build_route_entries(
+    services: &[ServiceToml],
+    routes: &[RouteToml],
+) -> Result<Vec<RouteEntry>, Error> {
+    let mut entries = Vec::with_capacity(routes.len());
+    for r in routes {
+        let target = match (&r.service, &r.redirect_to) {
+            (Some(_), Some(_)) => {
+                return Err(format!(
+                    "route '{} {}': 'service' and 'redirect_to' are mutually exclusive",
+                    r.host, r.path
+                ))
+                .handle_err(location!());
+            }
+            (None, None) => {
+                return Err(format!(
+                    "route '{} {}': exactly one of 'service'/'redirect_to' is required",
+                    r.host, r.path
+                ))
+                .handle_err(location!());
+            }
+            (Some(service_name), None) => {
+                let Some(svc) = services.iter().find(|s| &s.name == service_name) else {
+                    return Err(format!(
+                        "route '{} {}': service '{service_name}' is not declared in this stack",
+                        r.host, r.path
+                    ))
+                    .handle_err(location!());
+                };
+                let protocol = svc
+                    .protocol
+                    .map_or(ServiceProtocol::Http, ServiceProtocol::from);
+                if protocol != ServiceProtocol::Http {
+                    return Err(format!(
+                        "route '{} {}': service '{service_name}' is protocol {protocol:?}, \
+                         routes can only target http services",
+                        r.host, r.path
+                    ))
+                    .handle_err(location!());
+                }
+                if svc.timeout.is_none() {
+                    return Err(format!(
+                        "route '{} {}': service '{service_name}' has no 'timeout', so it isn't a \
+                         proxy-reachable entry point",
+                        r.host, r.path
+                    ))
+                    .handle_err(location!());
+                }
+                RouteTarget::Service(service_name.clone())
+            }
+            (None, Some(to)) => {
+                let status = r.redirect_status.unwrap_or(301);
+                if !matches!(status, 301 | 302 | 307 | 308) {
+                    return Err(format!(
+                        "route '{} {}': redirect_status {status} must be one of 301/302/307/308",
+                        r.host, r.path
+                    ))
+                    .handle_err(location!());
+                }
+                RouteTarget::Redirect {
+                    to: to.clone(),
+                    status,
+                }
+            }
+        };
+        entries.push(RouteEntry {
+            host: r.host.clone(),
+            path: r.path.clone(),
+            target,
+        });
+    }
+    Ok(entries)
+}
+
+/// Two routes (possibly in different stacks, or the same one) that both
+/// claim the same `(host, path)` pair — that pair dispatches to exactly one
+/// target on the proxy, so it must be globally unique, the same way
+/// `(protocol, listen_port)` already is for tcp/udp.
+pub(crate) struct RouteConflict {
+    pub(crate) stack_a: String,
+    pub(crate) stack_b: String,
+    pub(crate) host: String,
+    pub(crate) path: String,
+}
+
+/// Scan every stack for `(host, path)` pairs claimed by more than one route,
+/// including two routes within the same stack.
+pub(crate) fn detect_route_conflicts(routes: &RouteMap) -> Vec<RouteConflict> {
+    let mut claimed: HashMap<(String, String), String> = HashMap::new();
+    let mut conflicts = Vec::new();
+    for (stack, entries) in routes {
+        for entry in entries {
+            let key = (entry.host.clone(), entry.path.clone());
+            match claimed.get(&key) {
+                Some(other_stack) => conflicts.push(RouteConflict {
+                    stack_a: other_stack.clone(),
+                    stack_b: stack.clone(),
+                    host: entry.host.clone(),
+                    path: entry.path.clone(),
+                }),
+                None => {
+                    claimed.insert(key, stack.clone());
+                }
+            }
+        }
+    }
+    conflicts
+}
+
 /// Match entries for one file: only services with a match key are hostable, and
 /// such a service must declare a `port`.
 fn build_match_entries(services: &[ServiceToml]) -> Result<Vec<MatchEntry>, Error> {
@@ -62,20 +201,29 @@ fn build_match_entries(services: &[ServiceToml]) -> Result<Vec<MatchEntry>, Erro
 
 #[derive(Deserialize)]
 pub(crate) struct ServicesToml {
+    // Defaulted so a stack can be routes-only (e.g. a bare redirect, which
+    // needs no backend at all) without an empty `services = []` boilerplate.
+    #[serde(default)]
     services: Vec<ServiceToml>,
+    #[serde(default, rename = "route")]
+    routes: Vec<RouteToml>,
 }
 
 impl ServicesToml {
-    pub(crate) async fn load() -> Result<(StackMap, MatchIndex), Error> {
+    pub(crate) async fn load() -> Result<(StackMap, MatchIndex, RouteMap), Error> {
         Self::load_from_dir(SERVICES_DIR).await
     }
 
     /// Load every `*.toml` file under `dir`; the file stem is the stack name.
-    /// Returns the service map and the parallel host-match index.
-    pub(crate) async fn load_from_dir(dir: &str) -> Result<(StackMap, MatchIndex), Error> {
+    /// Returns the service map, the parallel host-match index, and the
+    /// parallel route map.
+    pub(crate) async fn load_from_dir(
+        dir: &str,
+    ) -> Result<(StackMap, MatchIndex, RouteMap), Error> {
         let mut entries = tokio::fs::read_dir(dir).await.handle_err(location!())?;
         let mut stacks: StackMap = HashMap::new();
         let mut index: MatchIndex = HashMap::new();
+        let mut routes: RouteMap = HashMap::new();
         while let Some(entry) = entries.next_entry().await.handle_err(location!())? {
             let path = entry.path();
             if path.extension().and_then(|s| s.to_str()) != Some("toml") {
@@ -88,12 +236,13 @@ impl ServicesToml {
             else {
                 continue;
             };
-            let (services, match_entries) = parse_file(&path).await?;
+            let (services, match_entries, route_entries) = parse_file(&path).await?;
             println!("Loaded stack '{stack}': {services:?}");
             stacks.insert(stack.clone(), services);
-            index.insert(stack, match_entries);
+            index.insert(stack.clone(), match_entries);
+            routes.insert(stack, route_entries);
         }
-        Ok((stacks, index))
+        Ok((stacks, index, routes))
     }
 
     /// Load a single file as one stack's service map. Used by tests.
@@ -103,14 +252,16 @@ impl ServicesToml {
     }
 
     /// Load every stack and fail loudly if any `(protocol, listen_port)` pair
-    /// is claimed by more than one service — ports are global on the proxy,
-    /// unlike service names which only need to be unique within a stack.
-    pub(crate) async fn load_validated() -> Result<(StackMap, MatchIndex), Error> {
-        let (mut stacks, mut index) = Self::load().await?;
-        // Don't brick the control plane on a port conflict (e.g. a bad UI edit or
-        // hand-edited file left two stacks claiming the same listen_port). Drop the
-        // offending stacks and start anyway, logging loudly — the reload path is
-        // likewise tolerant, and an operator can fix the files without downtime.
+    /// or `(host, path)` route pair is claimed by more than one service/route
+    /// — both are global on the proxy, unlike service names which only need
+    /// to be unique within a stack.
+    pub(crate) async fn load_validated() -> Result<(StackMap, MatchIndex, RouteMap), Error> {
+        let (mut stacks, mut index, mut routes) = Self::load().await?;
+        // Don't brick the control plane on a conflict (e.g. a bad UI edit or
+        // hand-edited file left two stacks claiming the same listen_port/route).
+        // Drop the offending stacks and start anyway, logging loudly — the
+        // reload path is likewise tolerant, and an operator can fix the files
+        // without downtime.
         let conflicts = detect_port_conflicts(&stacks);
         let mut bad: HashSet<String> = HashSet::new();
         for c in &conflicts {
@@ -122,24 +273,39 @@ impl ServicesToml {
             bad.insert(c.stack_a.clone());
             bad.insert(c.stack_b.clone());
         }
+        let route_conflicts = detect_route_conflicts(&routes);
+        for c in &route_conflicts {
+            eprintln!(
+                "[config] route conflict on startup: '{} {}' claimed by both '{}' and '{}' — \
+                 dropping these stacks until fixed",
+                c.host, c.path, c.stack_a, c.stack_b
+            );
+            bad.insert(c.stack_a.clone());
+            bad.insert(c.stack_b.clone());
+        }
         for stack in &bad {
             stacks.remove(stack);
             index.remove(stack);
+            routes.remove(stack);
         }
-        Ok((stacks, index))
+        Ok((stacks, index, routes))
     }
 
-    /// `config_changed` and `port_mappings_changed` are separate `Notify`s —
-    /// each has exactly one consumer (`check_timeouts` and the port-mapping
-    /// refresh task, respectively). `Notify::notify_one` wakes at most one
-    /// waiter, so sharing a single `Notify` across two consumers would have
-    /// them race for each wake-up instead of both reliably observing it.
+    /// `config_changed`, `port_mappings_changed`, and `http_routes_changed`
+    /// are separate `Notify`s — each has exactly one consumer (`check_timeouts`,
+    /// the port-mapping refresh task, and the route-table refresh task,
+    /// respectively). `Notify::notify_one` wakes at most one waiter, so
+    /// sharing a single `Notify` across consumers would have them race for
+    /// each wake-up instead of all reliably observing it.
+    #[allow(clippy::too_many_arguments)]
     pub(crate) async fn watch(
         services: &Arc<RwLock<StackMap>>,
         match_index: &Arc<RwLock<MatchIndex>>,
+        routes: &Arc<RwLock<RouteMap>>,
         orchestrator: Orchestrator,
         config_changed: Arc<Notify>,
         port_mappings_changed: Arc<Notify>,
+        http_routes_changed: Arc<Notify>,
     ) -> Result<(), Error> {
         let services_directory = PathBuf::from(SERVICES_DIR);
 
@@ -174,19 +340,24 @@ impl ServicesToml {
                     // ensure file changes are propagated
                     tokio::time::sleep(Duration::from_millis(100)).await;
                     match ServicesToml::load().await {
-                        Ok((loaded_services, loaded_index)) => {
+                        Ok((loaded_services, loaded_index, loaded_routes)) => {
                             let conflicts = detect_port_conflicts(&loaded_services);
-                            if conflicts.is_empty() {
+                            let route_conflicts = detect_route_conflicts(&loaded_routes);
+                            if conflicts.is_empty() && route_conflicts.is_empty() {
                                 let services_mut = &mut *services.write().await;
                                 apply_config_update(services_mut, loaded_services, &orchestrator)
                                     .await;
                                 *match_index.write().await = loaded_index;
+                                *routes.write().await = loaded_routes;
                                 config_changed.notify_one();
                                 port_mappings_changed.notify_one();
+                                http_routes_changed.notify_one();
                             } else {
                                 eprintln!(
-                                    "Rejecting services.toml reload: {} port mapping conflict(s)",
-                                    conflicts.len()
+                                    "Rejecting services.toml reload: {} port mapping conflict(s), \
+                                     {} route conflict(s)",
+                                    conflicts.len(),
+                                    route_conflicts.len()
                                 );
                                 for c in conflicts {
                                     orchestrator
@@ -201,6 +372,14 @@ impl ServicesToml {
                                         ))
                                         .await;
                                 }
+                                for c in route_conflicts {
+                                    orchestrator
+                                        .events
+                                        .emit(ServerEvent::route_conflict(
+                                            c.stack_a, c.stack_b, c.host, c.path,
+                                        ))
+                                        .await;
+                                }
                             }
                         }
                         Err(e) => eprintln!("Failed to reload services.toml: {e:?}"),
@@ -380,27 +559,38 @@ fn country_policy(
     }
 }
 
+/// One stack file's parsed, validated contents: its service map, host-match
+/// index entries, and route entries.
+type ParsedStack = (
+    HashMap<String, ServiceInfo>,
+    Vec<MatchEntry>,
+    Vec<RouteEntry>,
+);
+
 /// Single source of truth for "is this stack file valid?": TOML syntax, then the
-/// host-match/port, protocol/listen_port, and country-list rules. Shared by the
-/// disk loader ([`parse_file`]) and the UI save handler ([`validate_stack_toml`]).
-/// Cross-stack port conflicts are separate — see [`detect_port_conflicts`].
-fn parse_stack_content(
-    content: &str,
-) -> Result<(HashMap<String, ServiceInfo>, Vec<MatchEntry>), Error> {
+/// host-match/port, protocol/listen_port, route, and country-list rules. Shared
+/// by the disk loader ([`parse_file`]) and the UI save handlers
+/// ([`validate_stack_toml`]). Cross-stack port/route conflicts are separate —
+/// see [`detect_port_conflicts`]/[`detect_route_conflicts`].
+fn parse_stack_content(content: &str) -> Result<ParsedStack, Error> {
     let parsed: ServicesToml = toml::from_str(content).handle_err(location!())?;
     let match_entries = build_match_entries(&parsed.services)?;
-    Ok((parsed.services_map()?, match_entries))
+    let route_entries = build_route_entries(&parsed.services, &parsed.routes)?;
+    Ok((parsed.services_map()?, match_entries, route_entries))
 }
 
-/// Validate raw TOML the same way the loader does, returning the per-service map
-/// on success or a human-readable error for the UI's parse-status indicator.
-pub(crate) fn validate_stack_toml(content: &str) -> Result<HashMap<String, ServiceInfo>, String> {
+/// Validate raw TOML the same way the loader does, returning the per-service
+/// map and route list on success or a human-readable error for the UI's
+/// parse-status indicator.
+pub(crate) fn validate_stack_toml(
+    content: &str,
+) -> Result<(HashMap<String, ServiceInfo>, Vec<RouteEntry>), String> {
     parse_stack_content(content)
-        .map(|(services, _)| services)
+        .map(|(services, _match_entries, routes)| (services, routes))
         .map_err(|e| e.to_str().to_string())
 }
 
-async fn parse_file(path: &Path) -> Result<(HashMap<String, ServiceInfo>, Vec<MatchEntry>), Error> {
+async fn parse_file(path: &Path) -> Result<ParsedStack, Error> {
     let str_repr = tokio::fs::read_to_string(path)
         .await
         .handle_err(location!())?;
@@ -642,6 +832,24 @@ struct TriggerToml {
     chain: Vec<String>,
 }
 
+/// One `[[route]]` entry: an HTTP(S) location-block-style dispatch rule.
+/// `service`/`redirect_to` are mutually exclusive — validated (along with
+/// `redirect_status`) in [`build_route_entries`], not here, so a raw parse
+/// error and a semantic one both surface through the same caller.
+#[derive(Deserialize)]
+struct RouteToml {
+    host: String,
+    #[serde(default = "default_route_path")]
+    path: String,
+    service: Option<String>,
+    redirect_to: Option<String>,
+    redirect_status: Option<u16>,
+}
+
+fn default_route_path() -> String {
+    "/".to_string()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -760,7 +968,7 @@ timeout = 30
             .await
             .unwrap();
 
-        let (stacks, _index) = ServicesToml::load_from_dir(dir.to_str().unwrap())
+        let (stacks, _index, _routes) = ServicesToml::load_from_dir(dir.to_str().unwrap())
             .await
             .expect("load");
 
@@ -908,4 +1116,207 @@ listen_port = 6379
 
         assert!(detect_port_conflicts(&stacks).is_empty());
     }
+
+    fn routes_of(toml_str: &str) -> Result<Vec<RouteEntry>, String> {
+        parse_stack_content(toml_str)
+            .map(|(_, _, routes)| routes)
+            .map_err(|e| e.to_str().to_string())
+    }
+
+    #[test]
+    fn route_targeting_a_declared_http_service_parses() {
+        let toml_str = r#"
+[[services]]
+name = "grafana"
+timeout = 30
+
+[[route]]
+host = "ops.example.com"
+path = "/grafana"
+service = "grafana"
+"#;
+        let routes = routes_of(toml_str).unwrap();
+        assert_eq!(
+            routes,
+            vec![RouteEntry {
+                host: "ops.example.com".to_string(),
+                path: "/grafana".to_string(),
+                target: RouteTarget::Service("grafana".to_string()),
+            }]
+        );
+    }
+
+    #[test]
+    fn route_path_defaults_to_slash() {
+        let toml_str = r#"
+[[services]]
+name = "grafana"
+timeout = 30
+
+[[route]]
+host = "ops.example.com"
+service = "grafana"
+"#;
+        let routes = routes_of(toml_str).unwrap();
+        assert_eq!(routes[0].path, "/");
+    }
+
+    #[test]
+    fn redirect_route_defaults_status_to_301() {
+        let toml_str = r#"
+[[route]]
+host = "old.example.com"
+redirect_to = "https://new.example.com/"
+"#;
+        let routes = routes_of(toml_str).unwrap();
+        assert_eq!(
+            routes,
+            vec![RouteEntry {
+                host: "old.example.com".to_string(),
+                path: "/".to_string(),
+                target: RouteTarget::Redirect {
+                    to: "https://new.example.com/".to_string(),
+                    status: 301,
+                },
+            }]
+        );
+    }
+
+    #[test]
+    fn route_with_both_service_and_redirect_is_rejected() {
+        let toml_str = r#"
+[[services]]
+name = "grafana"
+timeout = 30
+
+[[route]]
+host = "ops.example.com"
+service = "grafana"
+redirect_to = "https://elsewhere.example.com/"
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("mutually exclusive")
+        );
+    }
+
+    #[test]
+    fn route_with_neither_service_nor_redirect_is_rejected() {
+        let toml_str = r#"
+[[route]]
+host = "ops.example.com"
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("exactly one of 'service'/'redirect_to'")
+        );
+    }
+
+    #[test]
+    fn route_targeting_undeclared_service_is_rejected() {
+        let toml_str = r#"
+[[route]]
+host = "ops.example.com"
+service = "grafana"
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("not declared in this stack")
+        );
+    }
+
+    #[test]
+    fn route_targeting_tcp_service_is_rejected() {
+        let toml_str = r#"
+[[services]]
+name = "redis.internal"
+timeout = 0
+protocol = "tcp"
+listen_port = 6379
+
+[[route]]
+host = "ops.example.com"
+service = "redis.internal"
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("routes can only target http services")
+        );
+    }
+
+    #[test]
+    fn route_targeting_non_entry_point_service_is_rejected() {
+        let toml_str = r#"
+[[services]]
+name = "backend.only"
+
+[[route]]
+host = "ops.example.com"
+service = "backend.only"
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("isn't a proxy-reachable entry point")
+        );
+    }
+
+    #[test]
+    fn redirect_route_with_unsupported_status_is_rejected() {
+        let toml_str = r#"
+[[route]]
+host = "old.example.com"
+redirect_to = "https://new.example.com/"
+redirect_status = 200
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("must be one of 301/302/307/308")
+        );
+    }
+
+    #[test]
+    fn detect_route_conflicts_flags_cross_stack_collision() {
+        let alpha = vec![RouteEntry {
+            host: "ops.example.com".to_string(),
+            path: "/".to_string(),
+            target: RouteTarget::Service("a".to_string()),
+        }];
+        let bravo = vec![RouteEntry {
+            host: "ops.example.com".to_string(),
+            path: "/".to_string(),
+            target: RouteTarget::Service("b".to_string()),
+        }];
+        let routes: RouteMap =
+            HashMap::from([("alpha".to_string(), alpha), ("bravo".to_string(), bravo)]);
+
+        let conflicts = detect_route_conflicts(&routes);
+        assert_eq!(conflicts.len(), 1);
+        assert_eq!(conflicts[0].host, "ops.example.com");
+        assert_eq!(conflicts[0].path, "/");
+    }
+
+    #[test]
+    fn detect_route_conflicts_allows_same_host_different_paths() {
+        let alpha = vec![
+            RouteEntry {
+                host: "ops.example.com".to_string(),
+                path: "/a".to_string(),
+                target: RouteTarget::Service("a".to_string()),
+            },
+            RouteEntry {
+                host: "ops.example.com".to_string(),
+                path: "/b".to_string(),
+                target: RouteTarget::Service("b".to_string()),
+            },
+        ];
+        let routes: RouteMap = HashMap::from([("alpha".to_string(), alpha)]);
+
+        assert!(detect_route_conflicts(&routes).is_empty());
+    }
 }

From b3874063d968dbda5426dc9e3aac02be60cb62b5 Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 13:55:29 -0400
Subject: [PATCH 05/14] proxy: dispatch HTTP requests through the (host, path)
 route table (#137)

New routes::RouteTable, kept in sync via WatchHttpRoutes exactly like
tls::CertStore is kept in sync via WatchCertificates (ArcSwap, hot-swap on
every push, exit-for-restart if the stream drops).

request_filter resolves (host, path) before anything else: a matched
redirect writes the response directly; an explicitly-uncovered path 404s;
a resolved backend is stashed in a new ProxyCtx and used by upstream_peer
in place of recomputing the service name from the Host header. A host with
no route-table entry at all (unknown host, or the startup race before the
first push arrives) falls back to today's Host-as-service-name behavior
unchanged.

Ingress country policy is now checked against the resolved backend rather
than the raw Host header, since path routing can send a host to a
different service than its own name.
---
 members/nullnet-proxy/src/main.rs          | 108 +++++++++--
 members/nullnet-proxy/src/nullnet_proxy.rs |  10 +-
 members/nullnet-proxy/src/routes.rs        | 199 +++++++++++++++++++++
 3 files changed, 305 insertions(+), 12 deletions(-)
 create mode 100644 members/nullnet-proxy/src/routes.rs

diff --git a/members/nullnet-proxy/src/main.rs b/members/nullnet-proxy/src/main.rs
index 207f8c9..b0c453c 100644
--- a/members/nullnet-proxy/src/main.rs
+++ b/members/nullnet-proxy/src/main.rs
@@ -1,11 +1,13 @@
 mod env;
 mod nullnet_proxy;
 mod port_mappings;
+mod routes;
 mod tcp_relay;
 mod tls;
 mod udp_relay;
 
 use crate::nullnet_proxy::NullnetProxy;
+use crate::routes::{Resolution, RouteMatch, RouteTable};
 use crate::tls::{CertStore, TlsResolver};
 use arc_swap::ArcSwap;
 use async_trait::async_trait;
@@ -30,19 +32,64 @@ use std::time::Instant;
 const PROXY_PORT: u16 = 80;
 const HTTPS_PROXY_PORT: u16 = 443;
 
+/// Per-request state threaded from `request_filter` to `upstream_peer`.
+#[derive(Default)]
+pub struct ProxyCtx {
+    /// The backend service name the HTTP route table resolved for this
+    /// request, if any. Set in `request_filter` (either an explicit route
+    /// match or the [`Resolution::Fallback`] Host-header default) and read
+    /// by `upstream_peer` in place of recomputing it from scratch. `None`
+    /// only when `request_filter` had no Host at all to resolve —
+    /// `upstream_peer`'s own header derivation is the fallback for that case,
+    /// exactly as it was before path-based routing existed.
+    service_name: Option<String>,
+}
+
 #[async_trait]
 impl ProxyHttp for NullnetProxy {
-    type CTX = ();
-    fn new_ctx(&self) -> Self::CTX {}
+    type CTX = ProxyCtx;
+    fn new_ctx(&self) -> Self::CTX {
+        ProxyCtx::default()
+    }
+
+    async fn request_filter(&self, session: &mut Session, ctx: &mut ProxyCtx) -> Result<bool> {
+        // Resolve HTTP path-based routing/redirects first — a redirect or an
+        // explicitly-uncovered path short-circuits right here, on both the
+        // HTTP and HTTPS listeners. A resolved backend feeds both the
+        // ingress-country check below and `upstream_peer`. See
+        // docs/http-path-routing-design.md.
+        if let Some(host) = ingress_host(session) {
+            let path = session.req_header().uri.path().to_string();
+            match self.routes.load().resolve(&host, &path) {
+                Resolution::Matched(RouteMatch::Backend(name)) => ctx.service_name = Some(name),
+                Resolution::Matched(RouteMatch::Redirect { to, status }) => {
+                    let location = resolve_redirect_target(&to, session.req_header(), self.tls);
+                    let mut resp = ResponseHeader::build(status, None)?;
+                    resp.insert_header("location", location.as_str())?;
+                    resp.insert_header("content-length", "0")?;
+                    session.write_response_header(Box::new(resp), true).await?;
+                    return Ok(true);
+                }
+                Resolution::NotFound => {
+                    let mut resp = ResponseHeader::build(404, None)?;
+                    resp.insert_header("content-length", "0")?;
+                    session.write_response_header(Box::new(resp), true).await?;
+                    return Ok(true);
+                }
+                Resolution::Fallback => ctx.service_name = Some(host),
+            }
+        }
 
-    async fn request_filter(&self, session: &mut Session, _ctx: &mut ()) -> Result<bool> {
         // Ingress country policy (both HTTP and HTTPS listeners), enforced before
-        // we touch the backend. Best-effort: if host or client IP can't be read
-        // we let upstream_peer handle it; only an explicit server deny 403s, and a
-        // check RPC error is logged and allowed through (upstream lookup will fail
-        // anyway if the control plane is down).
+        // we touch the backend. Keyed on the *resolved* backend — path routing
+        // may send this host to a different service than its own name — not
+        // the raw Host header. Best-effort: if host/client IP/resolution
+        // can't be read we let upstream_peer handle it; only an explicit
+        // server deny 403s, and a check RPC error is logged and allowed
+        // through (upstream lookup will fail anyway if the control plane is
+        // down).
         if let (Some(service), Some(client_ip)) =
-            (ingress_host(session), ingress_client_ip(session))
+            (ctx.service_name.clone(), ingress_client_ip(session))
         {
             match self.server.check_ingress(service.clone(), client_ip).await {
                 Ok(false) => {
@@ -79,7 +126,11 @@ impl ProxyHttp for NullnetProxy {
         Ok(true)
     }
 
-    async fn upstream_peer(&self, session: &mut Session, _ctx: &mut ()) -> Result<Box<HttpPeer>> {
+    async fn upstream_peer(
+        &self,
+        session: &mut Session,
+        ctx: &mut ProxyCtx,
+    ) -> Result<Box<HttpPeer>> {
         println!(
             "Received new proxy request from client: {:?}\n",
             session.client_addr()
@@ -181,7 +232,12 @@ impl ProxyHttp for NullnetProxy {
             },
         };
 
-        let service_name = url.to_string();
+        // Prefer the route table's resolution (`request_filter` already ran)
+        // over the raw Host header — path-based routing may send this host to
+        // a different backend than its own name. Falls back to the Host
+        // header itself when `request_filter` had nothing to resolve (no
+        // Host at all), matching pre-routing behavior.
+        let service_name = ctx.service_name.clone().unwrap_or_else(|| url.to_string());
         let proxy_req = ProxyRequest {
             client_ip: client_ip.clone(),
             service_name: service_name.clone(),
@@ -329,7 +385,12 @@ async fn main() -> Result<(), nullnet_liberror::Error> {
     // Certificates come from the control service over gRPC. Start empty; the
     // watch task fills this and hot-reloads it on every change.
     let cert_store: Arc<ArcSwap<CertStore>> = Arc::new(ArcSwap::from_pointee(CertStore::default()));
-    let nullnet_proxy = NullnetProxy::new(cert_store.clone()).await?;
+    // HTTP route table, same story: starts empty (Resolution::Fallback keeps
+    // Host-header routing until the first push arrives), hot-reloaded from
+    // then on. See docs/http-path-routing-design.md.
+    let route_table: Arc<ArcSwap<RouteTable>> =
+        Arc::new(ArcSwap::from_pointee(RouteTable::default()));
+    let nullnet_proxy = NullnetProxy::new(cert_store.clone(), route_table.clone()).await?;
 
     // subscribe to certificate updates (initial set + every subsequent change)
     {
@@ -338,6 +399,13 @@ async fn main() -> Result<(), nullnet_liberror::Error> {
         tokio::spawn(async move { watch_certificates(server, store).await });
     }
 
+    // subscribe to HTTP route-table updates (initial set + every subsequent change)
+    {
+        let server = nullnet_proxy.server.clone();
+        let store = route_table.clone();
+        tokio::spawn(async move { routes::watch_and_serve(server, store).await });
+    }
+
     // Egress is handled by the co-located nullnet-client's kernel forwarding
     // (ip_forward + MASQUERADE, the Cilium egress-gateway model), not by a
     // userspace forward proxy here. See docs/egress-gateway-cilium-model.md.
@@ -387,6 +455,24 @@ fn https_redirect_url(req: &RequestHeader, https_port: u16) -> String {
     }
 }
 
+/// Build the `Location` value for a matched redirect route: `to` verbatim if
+/// it already names a scheme, otherwise (a bare `/...` path) the same
+/// scheme/host as the incoming request with `to` substituted as the path. No
+/// variable interpolation (e.g. no matched-suffix preservation) — see
+/// docs/http-path-routing-design.md.
+fn resolve_redirect_target(to: &str, req: &RequestHeader, tls: bool) -> String {
+    if to.contains("://") {
+        return to.to_string();
+    }
+    let host_header = req
+        .headers
+        .get("host")
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("");
+    let scheme = if tls { "https" } else { "http" };
+    format!("{scheme}://{host_header}{to}")
+}
+
 /// Subscribe to the control service's certificate stream and atomically swap the
 /// proxy's cert store on every push (initial set + each change). The stream is
 /// also our server-liveness signal: when it drops (server down) we exit so the
diff --git a/members/nullnet-proxy/src/nullnet_proxy.rs b/members/nullnet-proxy/src/nullnet_proxy.rs
index a59711e..a8bb4bf 100644
--- a/members/nullnet-proxy/src/nullnet_proxy.rs
+++ b/members/nullnet-proxy/src/nullnet_proxy.rs
@@ -1,4 +1,5 @@
 use crate::env::{CONTROL_SERVICE_ADDR, CONTROL_SERVICE_CA_CERT, CONTROL_SERVICE_PORT};
+use crate::routes::RouteTable;
 use crate::tls::CertStore;
 use arc_swap::ArcSwap;
 use nullnet_grpc_lib::NullnetGrpcInterface;
@@ -14,11 +15,17 @@ use std::sync::Arc;
 pub struct NullnetProxy {
     pub(crate) server: NullnetGrpcInterface,
     pub(crate) certs: Arc<ArcSwap<CertStore>>,
+    /// Live HTTP `(host, path)` → target route table, kept in sync with the
+    /// control service. See docs/http-path-routing-design.md.
+    pub(crate) routes: Arc<ArcSwap<RouteTable>>,
     pub(crate) tls: bool,
 }
 
 impl NullnetProxy {
-    pub async fn new(certs: Arc<ArcSwap<CertStore>>) -> Result<Self, Error> {
+    pub async fn new(
+        certs: Arc<ArcSwap<CertStore>>,
+        routes: Arc<ArcSwap<RouteTable>>,
+    ) -> Result<Self, Error> {
         let host = CONTROL_SERVICE_ADDR.to_string();
         let port = *CONTROL_SERVICE_PORT;
         let server =
@@ -29,6 +36,7 @@ impl NullnetProxy {
         Ok(Self {
             server,
             certs,
+            routes,
             tls: false,
         })
     }
diff --git a/members/nullnet-proxy/src/routes.rs b/members/nullnet-proxy/src/routes.rs
new file mode 100644
index 0000000..30619af
--- /dev/null
+++ b/members/nullnet-proxy/src/routes.rs
@@ -0,0 +1,199 @@
+use arc_swap::ArcSwap;
+use nullnet_grpc_lib::NullnetGrpcInterface;
+use nullnet_grpc_lib::nullnet_grpc::{HttpRouteBundle, http_route::Target};
+use std::collections::HashMap;
+use std::process;
+use std::sync::Arc;
+
+/// What a matched route dispatches to.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) enum RouteMatch {
+    Backend(String),
+    Redirect { to: String, status: u16 },
+}
+
+/// The outcome of resolving `(host, path)` against the route table.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) enum Resolution {
+    /// This host has no entries at all — either the table hasn't loaded yet
+    /// (startup race, before the first `WatchHttpRoutes` push arrives) or the
+    /// host genuinely isn't a registered service. Callers fall back to
+    /// treating the Host header itself as the service name, exactly as they
+    /// did before this feature existed — the server errors out downstream
+    /// for a truly unknown name, same as today.
+    Fallback,
+    /// Longest-prefix match found.
+    Matched(RouteMatch),
+    /// This host has explicit routes, but none of their prefixes cover
+    /// `path`.
+    NotFound,
+}
+
+/// In-memory `(host, path_prefix)` → target table. Rebuilt wholesale from an
+/// `HttpRouteBundle` pushed by the control service and swapped in
+/// atomically (see `watch_and_serve`, mirroring `tls::CertStore`).
+///
+/// The server already folds in an implicit `{host = name, path = "/"}`
+/// fallback route for every proxy-reachable http service that declares no
+/// explicit `[[route]]` of its own (see
+/// `nullnet-server::nullnet_grpc_impl::build_http_route_bundle`), so this
+/// table is the *complete* picture — [`Resolution::Fallback`] is a proxy-side
+/// safety net for the startup race, not the everyday path.
+#[derive(Default)]
+pub struct RouteTable {
+    /// Per host, routes sorted by `path_prefix` length descending, so the
+    /// first prefix match is the longest (most specific) one.
+    by_host: HashMap<String, Vec<nullnet_grpc_lib::nullnet_grpc::HttpRoute>>,
+}
+
+impl RouteTable {
+    pub fn from_bundle(bundle: &HttpRouteBundle) -> Self {
+        let mut by_host: HashMap<String, Vec<_>> = HashMap::new();
+        for r in &bundle.routes {
+            by_host.entry(r.host.clone()).or_default().push(r.clone());
+        }
+        for routes in by_host.values_mut() {
+            routes.sort_by_key(|r| std::cmp::Reverse(r.path_prefix.len()));
+        }
+        Self { by_host }
+    }
+
+    /// Resolve `(host, path)`: longest matching `path_prefix` wins.
+    pub(crate) fn resolve(&self, host: &str, path: &str) -> Resolution {
+        let Some(routes) = self.by_host.get(host) else {
+            return Resolution::Fallback;
+        };
+        for r in routes {
+            if !path.starts_with(r.path_prefix.as_str()) {
+                continue;
+            }
+            return match &r.target {
+                Some(Target::ServiceName(name)) => {
+                    Resolution::Matched(RouteMatch::Backend(name.clone()))
+                }
+                Some(Target::Redirect(redirect)) => Resolution::Matched(RouteMatch::Redirect {
+                    to: redirect.to.clone(),
+                    status: u16::try_from(redirect.status_code).unwrap_or(301),
+                }),
+                // Malformed entry (neither target set) — the server never
+                // sends this; skip rather than dispatch nowhere.
+                None => continue,
+            };
+        }
+        Resolution::NotFound
+    }
+}
+
+/// Subscribe to the control service's HTTP route-table stream and atomically
+/// swap the proxy's route table on every push (initial set + each
+/// `services.toml` change). Mirrors `main::watch_certificates`: the stream
+/// also doubles as a server-liveness signal, so a drop exits the process for
+/// a clean restart rather than serving a stale table forever.
+pub(crate) async fn watch_and_serve(server: NullnetGrpcInterface, store: Arc<ArcSwap<RouteTable>>) {
+    match server.watch_http_routes().await {
+        Ok(mut stream) => loop {
+            match stream.message().await {
+                Ok(Some(bundle)) => {
+                    let n = bundle.routes.len();
+                    store.store(Arc::new(RouteTable::from_bundle(&bundle)));
+                    println!("[http-routes] loaded {n} route(s) from control service");
+                }
+                Ok(None) => break,
+                Err(e) => {
+                    eprintln!("HTTP route watch stream error: {e}");
+                    break;
+                }
+            }
+        },
+        Err(e) => eprintln!("Failed to open HTTP route watch stream: {e}"),
+    }
+    eprintln!("HTTP route watch stream to server closed; exiting for restart");
+    process::exit(1);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use nullnet_grpc_lib::nullnet_grpc::{HttpRedirect, HttpRoute};
+
+    fn service_route(host: &str, path: &str, service: &str) -> HttpRoute {
+        HttpRoute {
+            host: host.to_string(),
+            path_prefix: path.to_string(),
+            target: Some(Target::ServiceName(service.to_string())),
+        }
+    }
+
+    fn redirect_route(host: &str, path: &str, to: &str, status: u32) -> HttpRoute {
+        HttpRoute {
+            host: host.to_string(),
+            path_prefix: path.to_string(),
+            target: Some(Target::Redirect(HttpRedirect {
+                to: to.to_string(),
+                status_code: status,
+            })),
+        }
+    }
+
+    #[test]
+    fn unknown_host_falls_back() {
+        let table = RouteTable::from_bundle(&HttpRouteBundle::default());
+        assert_eq!(table.resolve("example.com", "/"), Resolution::Fallback);
+    }
+
+    #[test]
+    fn longest_prefix_wins() {
+        let bundle = HttpRouteBundle {
+            routes: vec![
+                service_route("ops.example.com", "/", "grafana"),
+                service_route("ops.example.com", "/api", "api"),
+                service_route("ops.example.com", "/api/v2", "api-v2"),
+            ],
+        };
+        let table = RouteTable::from_bundle(&bundle);
+        assert_eq!(
+            table.resolve("ops.example.com", "/api/v2/users"),
+            Resolution::Matched(RouteMatch::Backend("api-v2".to_string()))
+        );
+        assert_eq!(
+            table.resolve("ops.example.com", "/api/users"),
+            Resolution::Matched(RouteMatch::Backend("api".to_string()))
+        );
+        assert_eq!(
+            table.resolve("ops.example.com", "/anything-else"),
+            Resolution::Matched(RouteMatch::Backend("grafana".to_string()))
+        );
+    }
+
+    #[test]
+    fn no_catch_all_yields_not_found() {
+        let bundle = HttpRouteBundle {
+            routes: vec![service_route("ops.example.com", "/api", "api")],
+        };
+        let table = RouteTable::from_bundle(&bundle);
+        assert_eq!(
+            table.resolve("ops.example.com", "/other"),
+            Resolution::NotFound
+        );
+    }
+
+    #[test]
+    fn redirect_target_resolves() {
+        let bundle = HttpRouteBundle {
+            routes: vec![redirect_route(
+                "old.example.com",
+                "/",
+                "https://ops.example.com/",
+                301,
+            )],
+        };
+        let table = RouteTable::from_bundle(&bundle);
+        assert_eq!(
+            table.resolve("old.example.com", "/whatever"),
+            Resolution::Matched(RouteMatch::Redirect {
+                to: "https://ops.example.com/".to_string(),
+                status: 301,
+            })
+        );
+    }
+}

From 039a44840502fbb8998ae375c88674b40d1cdf1a Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 13:55:41 -0400
Subject: [PATCH 06/14] ui: add a Routes page for configuring HTTP path
 routing/redirects (#137)

New RoutesPage.tsx follows the Users.tsx CRUD+modal pattern (the one
existing precedent for structured forms in this UI, which otherwise only
offers raw-TOML editing): a table of routes with Edit/Delete per row, an
Add-route modal with a Backend-service/Redirect target toggle. The service
dropdown is populated from the new /api/routes/{stack} response's
http_services field rather than adding protocol to the existing services
list endpoint, so services.rs/Services.tsx stay untouched.

Every add/edit/delete recomputes the full route array client-side and
POSTs it (the API is whole-list replace, like the raw-TOML config save)
so the server re-validates it exactly as a hand-edited [[route]] block
would be.

New nav entry under Ops, alongside Config.
---
 members/nullnet-server/ui/src/App.tsx         |   2 +
 .../ui/src/components/Layout.tsx              |   3 +-
 .../nullnet-server/ui/src/pages/Routes.tsx    | 303 ++++++++++++++++++
 members/nullnet-server/ui/src/types.ts        |  18 ++
 4 files changed, 325 insertions(+), 1 deletion(-)
 create mode 100644 members/nullnet-server/ui/src/pages/Routes.tsx

diff --git a/members/nullnet-server/ui/src/App.tsx b/members/nullnet-server/ui/src/App.tsx
index 7431f4a..2a53c33 100644
--- a/members/nullnet-server/ui/src/App.tsx
+++ b/members/nullnet-server/ui/src/App.tsx
@@ -8,6 +8,7 @@ import Services from './pages/Services';
 import Nodes from './pages/Nodes';
 import Sessions from './pages/Sessions';
 import Config from './pages/Config';
+import RoutesPage from './pages/Routes';
 import Events from './pages/Events';
 import Certificates from './pages/Certificates';
 import Topology from './pages/Topology';
@@ -25,6 +26,7 @@ export default function App() {
             <Route path="/nodes" element={<RequireAuth><Nodes /></RequireAuth>} />
             <Route path="/sessions" element={<RequireAuth><Sessions /></RequireAuth>} />
             <Route path="/config" element={<RequireAuth><Config /></RequireAuth>} />
+            <Route path="/routes" element={<RequireAuth><RoutesPage /></RequireAuth>} />
             <Route path="/certificates" element={<RequireAuth><Certificates /></RequireAuth>} />
             <Route path="/events" element={<RequireAuth><Events /></RequireAuth>} />
             <Route path="/topology" element={<RequireAuth><Topology /></RequireAuth>} />
diff --git a/members/nullnet-server/ui/src/components/Layout.tsx b/members/nullnet-server/ui/src/components/Layout.tsx
index 52359c8..e704d55 100644
--- a/members/nullnet-server/ui/src/components/Layout.tsx
+++ b/members/nullnet-server/ui/src/components/Layout.tsx
@@ -7,7 +7,7 @@ import MfaSetupDialog from './MfaSetupDialog';
 import type { SessionJson } from '../types';
 import { useRef, useState, useEffect } from 'react';
 
-type Page = 'dashboard' | 'topology' | 'services' | 'nodes' | 'sessions' | 'config' | 'certificates' | 'events' | 'users';
+type Page = 'dashboard' | 'topology' | 'services' | 'nodes' | 'sessions' | 'config' | 'routes' | 'certificates' | 'events' | 'users';
 
 interface Props {
   page: Page;
@@ -37,6 +37,7 @@ const NAV = [
       { id: 'events', icon: '≡', label: 'Events', to: '/events' },
       { id: 'certificates', icon: '⛨', label: 'Certificates', to: '/certificates' },
       { id: 'config', icon: '⚙', label: 'Config', to: '/config' },
+      { id: 'routes', icon: '↪', label: 'Routes', to: '/routes' },
       { id: 'users', icon: '⚉', label: 'Users', to: '/users', adminOnly: true },
     ],
   },
diff --git a/members/nullnet-server/ui/src/pages/Routes.tsx b/members/nullnet-server/ui/src/pages/Routes.tsx
new file mode 100644
index 0000000..1ba340f
--- /dev/null
+++ b/members/nullnet-server/ui/src/pages/Routes.tsx
@@ -0,0 +1,303 @@
+import { useState } from 'react';
+import Layout from '../components/Layout';
+import Modal from '../components/Modal';
+import { useApi } from '../hooks/useApi';
+import { apiFetch } from '../lib/apiFetch';
+import { useStack } from '../StackContext';
+import type { RouteJson, RoutesResponseJson } from '../types';
+
+type RedirectStatus = 301 | 302 | 307 | 308;
+
+interface RouteFormState {
+  host: string;
+  path: string;
+  targetKind: 'service' | 'redirect';
+  service: string;
+  redirectTo: string;
+  redirectStatus: RedirectStatus;
+}
+
+const EMPTY_FORM: RouteFormState = {
+  host: '',
+  path: '/',
+  targetKind: 'service',
+  service: '',
+  redirectTo: '',
+  redirectStatus: 301,
+};
+
+function routeToForm(r: RouteJson): RouteFormState {
+  return {
+    host: r.host,
+    path: r.path,
+    targetKind: r.target.kind,
+    service: r.target.kind === 'service' ? r.target.service : '',
+    redirectTo: r.target.kind === 'redirect' ? r.target.to : '',
+    redirectStatus: r.target.kind === 'redirect' ? (r.target.status as RedirectStatus) : 301,
+  };
+}
+
+function formToRoute(f: RouteFormState): RouteJson {
+  return {
+    host: f.host.trim(),
+    path: f.path.trim() || '/',
+    target:
+      f.targetKind === 'service'
+        ? { kind: 'service', service: f.service }
+        : { kind: 'redirect', to: f.redirectTo.trim(), status: f.redirectStatus },
+  };
+}
+
+function targetLabel(r: RouteJson): string {
+  return r.target.kind === 'service' ? `→ ${r.target.service}` : `redirect ${r.target.status} → ${r.target.to}`;
+}
+
+export default function RoutesPage() {
+  const { stack } = useStack();
+  const { data, loading, error, refetch } = useApi<RoutesResponseJson>(`/api/routes/${stack}`);
+  const routes = data?.routes ?? [];
+  const httpServices = data?.http_services ?? [];
+
+  const [modalOpen, setModalOpen] = useState(false);
+  const [editingIndex, setEditingIndex] = useState<number | null>(null);
+  const [form, setForm] = useState<RouteFormState>(EMPTY_FORM);
+  const [busy, setBusy] = useState(false);
+  const [formError, setFormError] = useState<string | null>(null);
+  const [deleting, setDeleting] = useState<Set<number>>(new Set());
+  const [listError, setListError] = useState<string | null>(null);
+
+  function openAdd() {
+    setEditingIndex(null);
+    setForm({ ...EMPTY_FORM, service: httpServices[0] ?? '' });
+    setFormError(null);
+    setModalOpen(true);
+  }
+
+  function openEdit(i: number) {
+    setEditingIndex(i);
+    setForm(routeToForm(routes[i]));
+    setFormError(null);
+    setModalOpen(true);
+  }
+
+  // The API is a whole-list replace (like the raw-TOML config save) rather
+  // than per-route CRUD endpoints, so every add/edit/delete recomputes the
+  // full array client-side and POSTs it — the server re-validates it the
+  // same way a hand-edited [[route]] block would be.
+  async function persist(nextRoutes: RouteJson[]): Promise<{ ok: boolean; error?: string }> {
+    try {
+      const res = await apiFetch(`/api/routes/${stack}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(nextRoutes),
+      });
+      const data = await res.json().catch(() => ({ ok: res.ok, error: `HTTP ${res.status}` }));
+      return { ok: res.ok && data.ok, error: data.error };
+    } catch (e) {
+      return { ok: false, error: String(e) };
+    }
+  }
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true);
+    setFormError(null);
+    const entry = formToRoute(form);
+    const next =
+      editingIndex === null ? [...routes, entry] : routes.map((r, i) => (i === editingIndex ? entry : r));
+    const r = await persist(next);
+    if (r.ok) {
+      setModalOpen(false);
+      refetch();
+    } else {
+      setFormError(r.error ?? 'unknown error');
+    }
+    setBusy(false);
+  }
+
+  async function remove(i: number) {
+    const target = routes[i];
+    if (!confirm(`Delete route "${target.host} ${target.path}"?`)) return;
+    setDeleting(prev => new Set(prev).add(i));
+    setListError(null);
+    const next = routes.filter((_, idx) => idx !== i);
+    const r = await persist(next);
+    if (r.ok) refetch();
+    else setListError(r.error ?? 'unknown error');
+    setDeleting(prev => {
+      const n = new Set(prev);
+      n.delete(i);
+      return n;
+    });
+  }
+
+  const formValid =
+    form.host.trim() !== '' &&
+    (form.targetKind === 'service' ? form.service.trim() !== '' : form.redirectTo.trim() !== '');
+
+  return (
+    <Layout page="routes">
+      <div className="content">
+        <div className="page-title">Routes</div>
+        <div className="page-sub">
+          Path-based HTTP routing and redirects for stack{' '}
+          <span style={{ fontFamily: "'JetBrains Mono',monospace", color: 'var(--t1)' }}>{stack}</span> — like an
+          NGINX <code>location</code> block. A host with no explicit route here keeps routing by its own name,
+          unchanged.
+        </div>
+
+        <div className="card">
+          <div className="card-head">
+            <span className="card-label">Routes</span>
+            <button
+              className="card-action"
+              style={{ background: 'none', border: 'none', cursor: 'pointer' }}
+              onClick={openAdd}
+            >
+              + Add route
+            </button>
+          </div>
+
+          {listError && (
+            <div className="modal-err" style={{ margin: '0 16px 12px' }}>
+              {listError}
+            </div>
+          )}
+
+          <table className="tbl">
+            <thead>
+              <tr>
+                <th>Host</th>
+                <th>Path</th>
+                <th>Target</th>
+                <th></th>
+              </tr>
+            </thead>
+            <tbody>
+              {loading && (
+                <tr>
+                  <td colSpan={4} style={{ color: 'var(--t2)', padding: '20px 16px' }}>
+                    Loading…
+                  </td>
+                </tr>
+              )}
+              {!loading && error && (
+                <tr>
+                  <td colSpan={4} style={{ color: 'var(--red)', padding: '20px 16px' }}>
+                    Failed to load: {error}
+                  </td>
+                </tr>
+              )}
+              {routes.map((r, i) => (
+                <tr key={`${r.host}-${r.path}-${i}`}>
+                  <td style={{ fontFamily: "'JetBrains Mono',monospace" }}>{r.host}</td>
+                  <td style={{ fontFamily: "'JetBrains Mono',monospace", color: 'var(--t2)' }}>{r.path}</td>
+                  <td style={{ fontSize: 12 }}>{targetLabel(r)}</td>
+                  <td style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
+                    <button className="save-btn" onClick={() => openEdit(i)}>
+                      Edit
+                    </button>
+                    <button className="teardown-btn" onClick={() => remove(i)} disabled={deleting.has(i)}>
+                      {deleting.has(i) ? '…' : 'Delete'}
+                    </button>
+                  </td>
+                </tr>
+              ))}
+              {!loading && !error && routes.length === 0 && (
+                <tr>
+                  <td colSpan={4} style={{ color: 'var(--t2)', padding: '20px 16px' }}>
+                    No explicit routes — every http service routes by its own name.
+                  </td>
+                </tr>
+              )}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <Modal open={modalOpen} onClose={() => setModalOpen(false)} title={editingIndex === null ? 'Add route' : 'Edit route'}>
+        <form onSubmit={submit} style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+          <label className="modal-field">
+            <span>Host</span>
+            <input
+              value={form.host}
+              onChange={e => setForm(f => ({ ...f, host: e.target.value }))}
+              placeholder="ops.example.com"
+              spellCheck={false}
+              autoFocus
+            />
+          </label>
+          <label className="modal-field">
+            <span>Path prefix</span>
+            <input
+              value={form.path}
+              onChange={e => setForm(f => ({ ...f, path: e.target.value }))}
+              placeholder="/"
+              spellCheck={false}
+            />
+          </label>
+          <label className="modal-field">
+            <span>Target</span>
+            <select
+              value={form.targetKind}
+              onChange={e => setForm(f => ({ ...f, targetKind: e.target.value as 'service' | 'redirect' }))}
+            >
+              <option value="service">Backend service</option>
+              <option value="redirect">Redirect</option>
+            </select>
+          </label>
+          {form.targetKind === 'service' ? (
+            <label className="modal-field">
+              <span>Service</span>
+              <select value={form.service} onChange={e => setForm(f => ({ ...f, service: e.target.value }))}>
+                <option value="" disabled>
+                  select a service…
+                </option>
+                {httpServices.map(s => (
+                  <option key={s} value={s}>
+                    {s}
+                  </option>
+                ))}
+              </select>
+              {httpServices.length === 0 && (
+                <div style={{ fontSize: 11, color: 'var(--t2)' }}>
+                  No proxy-reachable http services declared in this stack yet.
+                </div>
+              )}
+            </label>
+          ) : (
+            <>
+              <label className="modal-field">
+                <span>Redirect to</span>
+                <input
+                  value={form.redirectTo}
+                  onChange={e => setForm(f => ({ ...f, redirectTo: e.target.value }))}
+                  placeholder="https://example.com/ or /new-path"
+                  spellCheck={false}
+                />
+              </label>
+              <label className="modal-field">
+                <span>Status</span>
+                <select
+                  value={form.redirectStatus}
+                  onChange={e => setForm(f => ({ ...f, redirectStatus: Number(e.target.value) as RedirectStatus }))}
+                >
+                  <option value={301}>301 Moved Permanently</option>
+                  <option value={302}>302 Found</option>
+                  <option value={307}>307 Temporary Redirect</option>
+                  <option value={308}>308 Permanent Redirect</option>
+                </select>
+              </label>
+            </>
+          )}
+          {formError && <div className="modal-err">{formError}</div>}
+          <div className="modal-actions">
+            <button className="save-btn" disabled={busy || !formValid}>
+              {busy ? 'Saving…' : editingIndex === null ? 'Add' : 'Save'}
+            </button>
+          </div>
+        </form>
+      </Modal>
+    </Layout>
+  );
+}
diff --git a/members/nullnet-server/ui/src/types.ts b/members/nullnet-server/ui/src/types.ts
index bc5b414..7f40f27 100644
--- a/members/nullnet-server/ui/src/types.ts
+++ b/members/nullnet-server/ui/src/types.ts
@@ -177,3 +177,21 @@ export interface ChainJson {
   proxy_net_id: number;
   all_net_ids: number[];
 }
+
+// HTTP path-based routing — see docs/http-path-routing-design.md.
+export type RouteTargetJson =
+  | { kind: 'service'; service: string }
+  | { kind: 'redirect'; to: string; status: number };
+
+export interface RouteJson {
+  host: string;
+  path: string;
+  target: RouteTargetJson;
+}
+
+export interface RoutesResponseJson {
+  routes: RouteJson[];
+  /** Declared, proxy-reachable `protocol = "http"` service names in this
+   * stack — populates the "backend service" dropdown when adding a route. */
+  http_services: string[];
+}

From 65f9d626dcd0afa3b7a0fdcbe82996b75abfca4b Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 13:55:48 -0400
Subject: [PATCH 07/14] docs: mark HTTP path-routing design as implemented

---
 docs/http-path-routing-design.md | 56 +++++++++++++++++++-------------
 1 file changed, 34 insertions(+), 22 deletions(-)

diff --git a/docs/http-path-routing-design.md b/docs/http-path-routing-design.md
index 1d8e6b2..21e5724 100644
--- a/docs/http-path-routing-design.md
+++ b/docs/http-path-routing-design.md
@@ -382,33 +382,45 @@ lightweight transitive dependency of the `toml` ecosystem) to splice the
   Fine at expected config scale (this mirrors two existing streams that
   already do this); revisit only if it becomes a real bottleneck.
 
-## Follow-ups (out of scope for this issue)
-
-- Regex/wildcard path matching.
-- Redirect target variable interpolation (preserve matched suffix, query
-  string passthrough is already implicit since redirects don't touch it).
-- Header-based routing (beyond Host), if ever needed.
-
 ## Implementation status
 
-Design only — nothing below is implemented yet. Planned as a sequence of
-commits so each stage builds/tests independently:
+Implemented on `feature/proxy-redirects-137`:
 
 1. **Contract** (`nullnet-grpc-lib`): `HttpRoute`, `HttpRedirect`,
-   `HttpRouteBundle`, `WatchHttpRoutes` RPC.
+   `HttpRouteBundle`, `WatchHttpRoutes` RPC. ✅ builds + tested.
 2. **Server**: `RouteToml` parsing + validation (mutual exclusion, status
-   code, same-stack service reference, `protocol = http` check),
-   `detect_route_conflicts`, `build_http_route_bundle` (incl. implicit
-   fallback routes), `watch_http_routes` RPC handler + its own `Notify`.
+   code, same-stack service reference, `protocol = http` + proxy-reachable
+   check), `detect_route_conflicts`, `build_http_route_bundle` (incl. implicit
+   fallback routes), `watch_http_routes` RPC handler + its own `Notify`,
+   `route_conflict` server event. `[[services]]` is now `#[serde(default)]`
+   so a stack can be routes-only (a bare redirect needs no backend at all).
    Unit tests mirroring the existing `detect_port_conflicts`/
-   `parses_explicit_and_implicit_services` coverage in `services/input.rs`.
+   `parses_explicit_and_implicit_services` coverage in `services/input.rs`,
+   plus `build_http_route_bundle` coverage in `nullnet_grpc_impl.rs`. ✅ 154
+   tests pass.
 3. **Proxy**: `routes.rs` (`RouteTable`, longest-prefix lookup,
    `watch_and_serve`), `main.rs` dispatch changes (`request_filter`
-   redirect/404/backend-selection, `upstream_peer` reading resolved ctx).
-   Unit tests for prefix matching, backward-compat fallback (no explicit
-   routes → today's behavior), and the redirect response writer.
-4. **Admin API**: `GET`/`POST /api/routes/{stack}`, `toml_edit`-based
-   structural merge into the stack file.
-5. **UI**: `RoutesPage.tsx`, nav entry, `Modal`-based add/edit form.
-6. **Docs**: update `docs/architecture.md` if the route-table stream is
-   worth calling out at the overview level once shipped.
+   redirect/404/backend-selection via a new `ProxyCtx`, `upstream_peer`
+   reading the resolved service name). Unit tests for prefix matching,
+   backward-compat fallback (no explicit routes → today's behavior), and
+   redirect resolution. ✅ 22 tests pass.
+4. **Admin API**: `GET`/`POST /api/routes/{stack}` (`http_server/routes.rs`),
+   `toml_edit`-based structural merge into the stack file (new
+   `toml_edit` workspace dependency).
+5. **UI**: `pages/Routes.tsx` (table + add/edit `Modal`, following the
+   `Users.tsx` CRUD pattern), nav entry, `RouteJson`/`RoutesResponseJson`
+   types. ✅ `tsc -b` + `vite build` + `eslint` clean.
+6. **Docs**: not yet updated — `docs/architecture.md` doesn't currently
+   enumerate individual watch streams, so no change was needed there.
+
+`cargo fmt`/`cargo clippy -D warnings` clean for `nullnet-grpc-lib`,
+`nullnet-server`, `nullnet-proxy` (the three crates CI lints/tests).
+
+## Follow-ups (out of scope for this issue)
+
+- Manual end-to-end verification against a running proxy + control service
+  (this stage covered unit tests only).
+- Regex/wildcard path matching.
+- Redirect target variable interpolation (preserve matched suffix, query
+  string passthrough is already implicit since redirects don't touch it).
+- Header-based routing (beyond Host), if ever needed.

From baabee82f85adc9e84f62e13a06855208c977025 Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 17:38:20 -0400
Subject: [PATCH 08/14] server: add explicit backward-compat tests for
 route-less configs

Confirms end-to-end, not just by inspection: a stack file with zero
[[route]] blocks (both [[services]] and [[route]] are #[serde(default)])
parses with an empty route list, and build_http_route_bundle reconstructs
exactly the old Host-only dispatch for every proxy-reachable http service
-- nothing for tcp/udp (unrelated port_mappings) or backend-only services.
---
 .../nullnet-server/src/nullnet_grpc_impl.rs   | 45 +++++++++++++++++++
 members/nullnet-server/src/services/input.rs  | 15 +++++++
 2 files changed, 60 insertions(+)

diff --git a/members/nullnet-server/src/nullnet_grpc_impl.rs b/members/nullnet-server/src/nullnet_grpc_impl.rs
index 348fb67..c59c9d9 100644
--- a/members/nullnet-server/src/nullnet_grpc_impl.rs
+++ b/members/nullnet-server/src/nullnet_grpc_impl.rs
@@ -1982,6 +1982,51 @@ mod http_route_bundle_tests {
         )
     }
 
+    /// End-to-end backward-compatibility guarantee: a stack file written
+    /// before this feature existed — no `[[route]]` block anywhere, just a
+    /// mix of http/tcp/backend-only `[[services]]` — parses unchanged
+    /// (`[[services]]`/`[[route]]` are both optional) and produces exactly
+    /// the implicit Host-only dispatch every such service already had.
+    #[test]
+    fn old_config_with_no_route_blocks_is_unaffected() {
+        let toml_str = r#"
+[[services]]
+name = "color.com"
+timeout = 30
+docker_container = "color"
+port = 8080
+
+[[services]]
+name = "redis.internal"
+timeout = 0
+protocol = "tcp"
+listen_port = 6379
+
+[[services]]
+name = "backend.only"
+proxy_dependencies = [["color.com"]]
+"#;
+        let parsed: ServicesToml = toml::from_str(toml_str).unwrap();
+        let services = parsed.services_map().unwrap();
+        let stacks: StackMap = HashMap::from([("legacy".to_string(), services)]);
+
+        // No [[route]] block at all → RouteMap has no entry for this stack,
+        // exactly as a pre-feature server would never have populated one.
+        let bundle = build_http_route_bundle(&stacks, &RouteMap::new());
+
+        // Only the proxy-reachable http service ("color.com") gets a route —
+        // the tcp service stays on its listen_port (port_mappings, unrelated
+        // to this bundle) and the backend-only service was never
+        // proxy-reachable to begin with.
+        assert_eq!(bundle.routes.len(), 1);
+        assert_eq!(bundle.routes[0].host, "color.com");
+        assert_eq!(bundle.routes[0].path_prefix, "/");
+        assert_eq!(
+            bundle.routes[0].target,
+            Some(HttpRouteTarget::ServiceName("color.com".to_string()))
+        );
+    }
+
     #[test]
     fn declares_no_routes_falls_back_to_implicit_host_route() {
         let stacks: StackMap = HashMap::from([(
diff --git a/members/nullnet-server/src/services/input.rs b/members/nullnet-server/src/services/input.rs
index 6c96787..073893b 100644
--- a/members/nullnet-server/src/services/input.rs
+++ b/members/nullnet-server/src/services/input.rs
@@ -1123,6 +1123,21 @@ listen_port = 6379
             .map_err(|e| e.to_str().to_string())
     }
 
+    /// Backward compatibility: `[[route]]` is entirely optional. A stack file
+    /// written before this feature existed has no such block anywhere, and
+    /// must keep parsing exactly as it always did, with zero route entries.
+    #[test]
+    fn stack_with_no_route_blocks_parses_with_empty_routes() {
+        let toml_str = r#"
+[[services]]
+name = "color.com"
+timeout = 30
+docker_container = "color"
+port = 8080
+"#;
+        assert_eq!(routes_of(toml_str).unwrap(), Vec::new());
+    }
+
     #[test]
     fn route_targeting_a_declared_http_service_parses() {
         let toml_str = r#"

From 6f89fc1f27d1015917dcb359016cb19974c94cd5 Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 19:29:53 -0400
Subject: [PATCH 09/14] grpc: add strip_prefix/preserve_path/preserve_query to
 HTTP routes (#137)

Three gaps identified after the initial routing feature landed:
- backend targets never rewrote the forwarded path (no NGINX
  proxy_pass-trailing-slash equivalent) -- HttpRoute.strip_prefix
- redirects never preserved the request's query string at all, contrary to
  an earlier (incorrect) doc claim that this was already implicit
- redirects never preserved the matched path suffix -- HttpRedirect.preserve_path/preserve_query

All three default to false, reproducing exactly today's behavior.
---
 Cargo.lock                                      |  1 +
 .../nullnet-grpc-lib/proto/nullnet_grpc.proto   | 14 +++++++++++++-
 .../nullnet-grpc-lib/src/proto/nullnet_grpc.rs  | 17 ++++++++++++++++-
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 2daef20..8d59dd8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3282,6 +3282,7 @@ dependencies = [
  "chrono",
  "ctrlc",
  "gag",
+ "http 1.4.2",
  "nullnet-grpc-lib",
  "nullnet-liberror 0.1.1 (git+https://github.com/NullNet-ai/libguard.git?branch=nullnet-liberror-print)",
  "openssl",
diff --git a/members/nullnet-grpc-lib/proto/nullnet_grpc.proto b/members/nullnet-grpc-lib/proto/nullnet_grpc.proto
index ce8f81e..9c5fcba 100644
--- a/members/nullnet-grpc-lib/proto/nullnet_grpc.proto
+++ b/members/nullnet-grpc-lib/proto/nullnet_grpc.proto
@@ -312,15 +312,27 @@ message HttpRoute {
     string service_name = 3;
     HttpRedirect redirect = 4;
   }
+  // Only meaningful when `target` is `service_name`: strip the matched
+  // `path_prefix` from the path forwarded to the backend — the NGINX
+  // `proxy_pass http://backend/;` trailing-slash equivalent. `false`
+  // (default) forwards the original request path unchanged.
+  bool strip_prefix = 5;
 }
 
 // A literal redirect target for an HttpRoute. `to` is either an absolute URL
 // (used verbatim) or a path (starting with `/`; same scheme/host as the
-// incoming request, target path substituted). No variable interpolation.
+// incoming request, target path substituted).
 message HttpRedirect {
   string to = 1;
   // One of 301/302/307/308.
   uint32 status_code = 2;
+  // Append the request path's suffix beyond the matched `path_prefix` to
+  // `to` — the NGINX `rewrite ^/old(.*) /new$1 permanent;` equivalent.
+  // `false` (default) uses `to` verbatim, same as before this field existed.
+  bool preserve_path = 3;
+  // Append the original request's query string to the final redirect
+  // target (merged with `?`/`&` if `to` already carries its own query).
+  bool preserve_query = 4;
 }
 
 message HttpRouteBundle {
diff --git a/members/nullnet-grpc-lib/src/proto/nullnet_grpc.rs b/members/nullnet-grpc-lib/src/proto/nullnet_grpc.rs
index 2d69e5d..0e69486 100644
--- a/members/nullnet-grpc-lib/src/proto/nullnet_grpc.rs
+++ b/members/nullnet-grpc-lib/src/proto/nullnet_grpc.rs
@@ -295,6 +295,12 @@ pub struct HttpRoute {
     pub host: ::prost::alloc::string::String,
     #[prost(string, tag = "2")]
     pub path_prefix: ::prost::alloc::string::String,
+    /// Only meaningful when `target` is `service_name`: strip the matched
+    /// `path_prefix` from the path forwarded to the backend — the NGINX
+    /// `proxy_pass <http://backend/;`> trailing-slash equivalent. `false`
+    /// (default) forwards the original request path unchanged.
+    #[prost(bool, tag = "5")]
+    pub strip_prefix: bool,
     #[prost(oneof = "http_route::Target", tags = "3, 4")]
     pub target: ::core::option::Option<http_route::Target>,
 }
@@ -310,7 +316,7 @@ pub mod http_route {
 }
 /// A literal redirect target for an HttpRoute. `to` is either an absolute URL
 /// (used verbatim) or a path (starting with `/`; same scheme/host as the
-/// incoming request, target path substituted). No variable interpolation.
+/// incoming request, target path substituted).
 #[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
 pub struct HttpRedirect {
     #[prost(string, tag = "1")]
@@ -318,6 +324,15 @@ pub struct HttpRedirect {
     /// One of 301/302/307/308.
     #[prost(uint32, tag = "2")]
     pub status_code: u32,
+    /// Append the request path's suffix beyond the matched `path_prefix` to
+    /// `to` — the NGINX `rewrite ^/old(.*) /new$1 permanent;` equivalent.
+    /// `false` (default) uses `to` verbatim, same as before this field existed.
+    #[prost(bool, tag = "3")]
+    pub preserve_path: bool,
+    /// Append the original request's query string to the final redirect
+    /// target (merged with `?`/`&` if `to` already carries its own query).
+    #[prost(bool, tag = "4")]
+    pub preserve_query: bool,
 }
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct HttpRouteBundle {

From 95c861fd5768b17acc7717a824df2e01950ccd9a Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 19:30:07 -0400
Subject: [PATCH 10/14] server: validate and wire
 strip_prefix/preserve_path/preserve_query (#137)

RouteTarget::Service/Redirect carry the new fields; build_route_entries
rejects each on the wrong target kind (strip_prefix on a redirect_to route,
preserve_path/preserve_query on a service route) -- same style as the
existing mutual-exclusion checks. build_http_route_bundle threads them
through to the wire HttpRoute/HttpRedirect. Admin API (routes.rs) gains the
matching JSON fields and TOML merge support.

New tests: parsing + validation for all three fields, plus updates to every
existing RouteTarget construction site for the new struct-variant shapes.
---
 .../nullnet-server/src/http_server/routes.rs  |  69 ++++++-
 .../nullnet-server/src/nullnet_grpc_impl.rs   |  46 ++++-
 members/nullnet-server/src/services/input.rs  | 191 +++++++++++++++++-
 3 files changed, 274 insertions(+), 32 deletions(-)

diff --git a/members/nullnet-server/src/http_server/routes.rs b/members/nullnet-server/src/http_server/routes.rs
index c33110b..80bddb5 100644
--- a/members/nullnet-server/src/http_server/routes.rs
+++ b/members/nullnet-server/src/http_server/routes.rs
@@ -18,8 +18,19 @@ use serde::{Deserialize, Serialize};
 #[derive(Serialize, Deserialize, Clone)]
 #[serde(tag = "kind", rename_all = "lowercase")]
 pub(super) enum RouteTargetJson {
-    Service { service: String },
-    Redirect { to: String, status: u16 },
+    Service {
+        service: String,
+        #[serde(default)]
+        strip_prefix: bool,
+    },
+    Redirect {
+        to: String,
+        status: u16,
+        #[serde(default)]
+        preserve_path: bool,
+        #[serde(default)]
+        preserve_query: bool,
+    },
 }
 
 #[derive(Serialize, Deserialize, Clone)]
@@ -35,12 +46,20 @@ impl From<&RouteEntry> for RouteJson {
             host: r.host.clone(),
             path: r.path.clone(),
             target: match &r.target {
-                RouteTarget::Service(service) => RouteTargetJson::Service {
-                    service: service.clone(),
+                RouteTarget::Service { name, strip_prefix } => RouteTargetJson::Service {
+                    service: name.clone(),
+                    strip_prefix: *strip_prefix,
                 },
-                RouteTarget::Redirect { to, status } => RouteTargetJson::Redirect {
+                RouteTarget::Redirect {
+                    to,
+                    status,
+                    preserve_path,
+                    preserve_query,
+                } => RouteTargetJson::Redirect {
                     to: to.clone(),
                     status: *status,
+                    preserve_path: *preserve_path,
+                    preserve_query: *preserve_query,
                 },
             },
         }
@@ -121,7 +140,10 @@ pub(super) async fn save_handler(
     let mut entries = Vec::with_capacity(body.len());
     for r in &body {
         match &r.target {
-            RouteTargetJson::Service { service } => {
+            RouteTargetJson::Service {
+                service,
+                strip_prefix,
+            } => {
                 let Some(info) = stack_map.get(service) else {
                     return rejected(
                         StatusCode::UNPROCESSABLE_ENTITY,
@@ -153,10 +175,18 @@ pub(super) async fn save_handler(
                 entries.push(RouteEntry {
                     host: r.host.clone(),
                     path: r.path.clone(),
-                    target: RouteTarget::Service(service.clone()),
+                    target: RouteTarget::Service {
+                        name: service.clone(),
+                        strip_prefix: *strip_prefix,
+                    },
                 });
             }
-            RouteTargetJson::Redirect { to, status } => {
+            RouteTargetJson::Redirect {
+                to,
+                status,
+                preserve_path,
+                preserve_query,
+            } => {
                 if !matches!(status, 301 | 302 | 307 | 308) {
                     return rejected(
                         StatusCode::UNPROCESSABLE_ENTITY,
@@ -172,6 +202,8 @@ pub(super) async fn save_handler(
                     target: RouteTarget::Redirect {
                         to: to.clone(),
                         status: *status,
+                        preserve_path: *preserve_path,
+                        preserve_query: *preserve_query,
                     },
                 });
             }
@@ -234,12 +266,29 @@ fn merge_routes_into_toml(content: &str, routes: &[RouteJson]) -> Result<String,
         table.insert("host", toml_edit::value(r.host.clone()));
         table.insert("path", toml_edit::value(r.path.clone()));
         match &r.target {
-            RouteTargetJson::Service { service } => {
+            RouteTargetJson::Service {
+                service,
+                strip_prefix,
+            } => {
                 table.insert("service", toml_edit::value(service.clone()));
+                if *strip_prefix {
+                    table.insert("strip_prefix", toml_edit::value(true));
+                }
             }
-            RouteTargetJson::Redirect { to, status } => {
+            RouteTargetJson::Redirect {
+                to,
+                status,
+                preserve_path,
+                preserve_query,
+            } => {
                 table.insert("redirect_to", toml_edit::value(to.clone()));
                 table.insert("redirect_status", toml_edit::value(i64::from(*status)));
+                if *preserve_path {
+                    table.insert("preserve_path", toml_edit::value(true));
+                }
+                if *preserve_query {
+                    table.insert("preserve_query", toml_edit::value(true));
+                }
             }
         }
         array.push(table);
diff --git a/members/nullnet-server/src/nullnet_grpc_impl.rs b/members/nullnet-server/src/nullnet_grpc_impl.rs
index c59c9d9..6a3f2c3 100644
--- a/members/nullnet-server/src/nullnet_grpc_impl.rs
+++ b/members/nullnet-server/src/nullnet_grpc_impl.rs
@@ -112,16 +112,32 @@ fn build_http_route_bundle(stacks: &StackMap, routes: &RouteMap) -> HttpRouteBun
     let mut wire_routes: Vec<HttpRoute> = routes
         .values()
         .flat_map(|entries| entries.iter())
-        .map(|r| HttpRoute {
-            host: r.host.clone(),
-            path_prefix: r.path.clone(),
-            target: Some(match &r.target {
-                RouteTarget::Service(name) => HttpRouteTarget::ServiceName(name.clone()),
-                RouteTarget::Redirect { to, status } => HttpRouteTarget::Redirect(HttpRedirect {
-                    to: to.clone(),
-                    status_code: u32::from(*status),
-                }),
-            }),
+        .map(|r| {
+            let (target, strip_prefix) = match &r.target {
+                RouteTarget::Service { name, strip_prefix } => {
+                    (HttpRouteTarget::ServiceName(name.clone()), *strip_prefix)
+                }
+                RouteTarget::Redirect {
+                    to,
+                    status,
+                    preserve_path,
+                    preserve_query,
+                } => (
+                    HttpRouteTarget::Redirect(HttpRedirect {
+                        to: to.clone(),
+                        status_code: u32::from(*status),
+                        preserve_path: *preserve_path,
+                        preserve_query: *preserve_query,
+                    }),
+                    false,
+                ),
+            };
+            HttpRoute {
+                host: r.host.clone(),
+                path_prefix: r.path.clone(),
+                target: Some(target),
+                strip_prefix,
+            }
         })
         .collect();
 
@@ -136,6 +152,7 @@ fn build_http_route_bundle(stacks: &StackMap, routes: &RouteMap) -> HttpRouteBun
             host: name.clone(),
             path_prefix: "/".to_string(),
             target: Some(HttpRouteTarget::ServiceName(name.clone())),
+            strip_prefix: false,
         });
     }
 
@@ -2060,7 +2077,10 @@ proxy_dependencies = [["color.com"]]
             vec![RouteEntry {
                 host: "grafana".to_string(),
                 path: "/dashboards".to_string(),
-                target: RouteTarget::Service("grafana".to_string()),
+                target: RouteTarget::Service {
+                    name: "grafana".to_string(),
+                    strip_prefix: false,
+                },
             }],
         )]);
         let bundle = build_http_route_bundle(&stacks, &routes);
@@ -2112,6 +2132,8 @@ proxy_dependencies = [["color.com"]]
                 target: RouteTarget::Redirect {
                     to: "https://new.example.com/".to_string(),
                     status: 301,
+                    preserve_path: true,
+                    preserve_query: true,
                 },
             }],
         )]);
@@ -2123,6 +2145,8 @@ proxy_dependencies = [["color.com"]]
             Some(HttpRouteTarget::Redirect(HttpRedirect {
                 to: "https://new.example.com/".to_string(),
                 status_code: 301,
+                preserve_path: true,
+                preserve_query: true,
             }))
         );
     }
diff --git a/members/nullnet-server/src/services/input.rs b/members/nullnet-server/src/services/input.rs
index 073893b..da2e8e0 100644
--- a/members/nullnet-server/src/services/input.rs
+++ b/members/nullnet-server/src/services/input.rs
@@ -47,8 +47,23 @@ pub(crate) struct RouteEntry {
 
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) enum RouteTarget {
-    Service(String),
-    Redirect { to: String, status: u16 },
+    Service {
+        name: String,
+        /// Strip the matched `path_prefix` from the path forwarded to the
+        /// backend (NGINX `proxy_pass http://backend/;` trailing-slash
+        /// equivalent). `false` reproduces the original, only behavior.
+        strip_prefix: bool,
+    },
+    Redirect {
+        to: String,
+        status: u16,
+        /// Append the request path's suffix beyond the matched
+        /// `path_prefix` to `to` (NGINX `rewrite ^/old(.*) /new$1
+        /// permanent;` equivalent).
+        preserve_path: bool,
+        /// Append the original request's query string to the final target.
+        preserve_query: bool,
+    },
 }
 
 /// Stack name → its explicit route entries. Rebuilt on every load/reload,
@@ -62,9 +77,10 @@ pub(crate) type RouteMap = HashMap<String, Vec<RouteEntry>>;
 /// Validate and convert one stack's raw `[[route]]` entries against its
 /// `[[services]]` list: exactly one target (`service`/`redirect_to`) per
 /// route, a `service` target must name an in-stack, http-protocol service,
-/// and `redirect_status` (when present) must be a supported redirect code.
-/// `(host, path)` uniqueness — within this stack or across stacks — is a
-/// separate check; see `detect_route_conflicts`.
+/// `redirect_status` (when present) must be a supported redirect code, and
+/// `strip_prefix`/`preserve_path`/`preserve_query` each only apply to their
+/// own target kind. `(host, path)` uniqueness — within this stack or across
+/// stacks — is a separate check; see `detect_route_conflicts`.
 fn build_route_entries(
     services: &[ServiceToml],
     routes: &[RouteToml],
@@ -87,6 +103,14 @@ fn build_route_entries(
                 .handle_err(location!());
             }
             (Some(service_name), None) => {
+                if r.preserve_path || r.preserve_query {
+                    return Err(format!(
+                        "route '{} {}': 'preserve_path'/'preserve_query' only apply to \
+                         'redirect_to' routes",
+                        r.host, r.path
+                    ))
+                    .handle_err(location!());
+                }
                 let Some(svc) = services.iter().find(|s| &s.name == service_name) else {
                     return Err(format!(
                         "route '{} {}': service '{service_name}' is not declared in this stack",
@@ -113,9 +137,19 @@ fn build_route_entries(
                     ))
                     .handle_err(location!());
                 }
-                RouteTarget::Service(service_name.clone())
+                RouteTarget::Service {
+                    name: service_name.clone(),
+                    strip_prefix: r.strip_prefix,
+                }
             }
             (None, Some(to)) => {
+                if r.strip_prefix {
+                    return Err(format!(
+                        "route '{} {}': 'strip_prefix' only applies to 'service' routes",
+                        r.host, r.path
+                    ))
+                    .handle_err(location!());
+                }
                 let status = r.redirect_status.unwrap_or(301);
                 if !matches!(status, 301 | 302 | 307 | 308) {
                     return Err(format!(
@@ -127,6 +161,8 @@ fn build_route_entries(
                 RouteTarget::Redirect {
                     to: to.clone(),
                     status,
+                    preserve_path: r.preserve_path,
+                    preserve_query: r.preserve_query,
                 }
             }
         };
@@ -842,8 +878,14 @@ struct RouteToml {
     #[serde(default = "default_route_path")]
     path: String,
     service: Option<String>,
+    #[serde(default)]
+    strip_prefix: bool,
     redirect_to: Option<String>,
     redirect_status: Option<u16>,
+    #[serde(default)]
+    preserve_path: bool,
+    #[serde(default)]
+    preserve_query: bool,
 }
 
 fn default_route_path() -> String {
@@ -1156,7 +1198,10 @@ service = "grafana"
             vec![RouteEntry {
                 host: "ops.example.com".to_string(),
                 path: "/grafana".to_string(),
-                target: RouteTarget::Service("grafana".to_string()),
+                target: RouteTarget::Service {
+                    name: "grafana".to_string(),
+                    strip_prefix: false,
+                },
             }]
         );
     }
@@ -1192,6 +1237,8 @@ redirect_to = "https://new.example.com/"
                 target: RouteTarget::Redirect {
                     to: "https://new.example.com/".to_string(),
                     status: 301,
+                    preserve_path: false,
+                    preserve_query: false,
                 },
             }]
         );
@@ -1263,6 +1310,116 @@ service = "redis.internal"
         );
     }
 
+    #[test]
+    fn strip_prefix_route_parses_and_forwards_correctly() {
+        let toml_str = r#"
+[[services]]
+name = "api"
+timeout = 0
+
+[[route]]
+host = "ops.example.com"
+path = "/api"
+service = "api"
+strip_prefix = true
+"#;
+        let routes = routes_of(toml_str).unwrap();
+        assert_eq!(
+            routes,
+            vec![RouteEntry {
+                host: "ops.example.com".to_string(),
+                path: "/api".to_string(),
+                target: RouteTarget::Service {
+                    name: "api".to_string(),
+                    strip_prefix: true,
+                },
+            }]
+        );
+    }
+
+    #[test]
+    fn strip_prefix_on_a_redirect_route_is_rejected() {
+        let toml_str = r#"
+services = []
+
+[[route]]
+host = "old.example.com"
+redirect_to = "https://new.example.com/"
+strip_prefix = true
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("'strip_prefix' only applies to 'service' routes")
+        );
+    }
+
+    #[test]
+    fn preserve_path_on_a_service_route_is_rejected() {
+        let toml_str = r#"
+[[services]]
+name = "api"
+timeout = 0
+
+[[route]]
+host = "ops.example.com"
+service = "api"
+preserve_path = true
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("'preserve_path'/'preserve_query' only apply to 'redirect_to' routes")
+        );
+    }
+
+    #[test]
+    fn preserve_query_on_a_service_route_is_rejected() {
+        let toml_str = r#"
+[[services]]
+name = "api"
+timeout = 0
+
+[[route]]
+host = "ops.example.com"
+service = "api"
+preserve_query = true
+"#;
+        assert!(
+            routes_of(toml_str)
+                .unwrap_err()
+                .contains("'preserve_path'/'preserve_query' only apply to 'redirect_to' routes")
+        );
+    }
+
+    #[test]
+    fn redirect_route_with_preserve_flags_parses() {
+        let toml_str = r#"
+services = []
+
+[[route]]
+host = "old.example.com"
+path = "/old"
+redirect_to = "/new"
+preserve_path = true
+preserve_query = true
+"#;
+        let routes = routes_of(toml_str).unwrap();
+        assert_eq!(
+            routes,
+            vec![RouteEntry {
+                host: "old.example.com".to_string(),
+                path: "/old".to_string(),
+                target: RouteTarget::Redirect {
+                    to: "/new".to_string(),
+                    status: 301,
+                    preserve_path: true,
+                    preserve_query: true,
+                },
+            }]
+        );
+    }
+
     #[test]
     fn route_targeting_non_entry_point_service_is_rejected() {
         let toml_str = r#"
@@ -1300,12 +1457,18 @@ redirect_status = 200
         let alpha = vec![RouteEntry {
             host: "ops.example.com".to_string(),
             path: "/".to_string(),
-            target: RouteTarget::Service("a".to_string()),
+            target: RouteTarget::Service {
+                name: "a".to_string(),
+                strip_prefix: false,
+            },
         }];
         let bravo = vec![RouteEntry {
             host: "ops.example.com".to_string(),
             path: "/".to_string(),
-            target: RouteTarget::Service("b".to_string()),
+            target: RouteTarget::Service {
+                name: "b".to_string(),
+                strip_prefix: false,
+            },
         }];
         let routes: RouteMap =
             HashMap::from([("alpha".to_string(), alpha), ("bravo".to_string(), bravo)]);
@@ -1322,12 +1485,18 @@ redirect_status = 200
             RouteEntry {
                 host: "ops.example.com".to_string(),
                 path: "/a".to_string(),
-                target: RouteTarget::Service("a".to_string()),
+                target: RouteTarget::Service {
+                    name: "a".to_string(),
+                    strip_prefix: false,
+                },
             },
             RouteEntry {
                 host: "ops.example.com".to_string(),
                 path: "/b".to_string(),
-                target: RouteTarget::Service("b".to_string()),
+                target: RouteTarget::Service {
+                    name: "b".to_string(),
+                    strip_prefix: false,
+                },
             },
         ];
         let routes: RouteMap = HashMap::from([("alpha".to_string(), alpha)]);

From b607decce9e1e16657d35f07ac59030c222b684b Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 19:30:20 -0400
Subject: [PATCH 11/14] proxy: apply strip_prefix/preserve_path/preserve_query
 (#137)

RouteTable::resolve now returns RouteMatch::Backend{service_name,
forward_path} and RouteMatch::Redirect{..., matched_suffix} -- routes.rs
computes the path pieces it has access to (the matched prefix), main.rs
combines them with what only it has (the request's Host header, query
string, TLS flag):

- ProxyCtx gains forward_path; upstream_request_filter applies it via a new
  rewrite_uri_path helper (RequestHeader::set_uri, query string preserved)
  -- only the upstream-bound request changes, not the client-facing session
  or logs.
- resolve_redirect_target gained matched_suffix/preserve_path/preserve_query
  params: splits any query already in the configured "to", optionally
  appends the matched suffix, optionally appends the request's own query
  (merged with '&', not overwritten).

Adds http = "1" as a direct dependency (RequestHeader::set_uri takes
http::Uri; previously only reachable transitively through pingora-http).

14 new unit tests across routes.rs and main.rs.
---
 members/nullnet-proxy/Cargo.toml    |   1 +
 members/nullnet-proxy/src/main.rs   | 203 ++++++++++++++++++++++++++--
 members/nullnet-proxy/src/routes.rs | 167 +++++++++++++++++++++--
 3 files changed, 354 insertions(+), 17 deletions(-)

diff --git a/members/nullnet-proxy/Cargo.toml b/members/nullnet-proxy/Cargo.toml
index 0ad2571..655417b 100644
--- a/members/nullnet-proxy/Cargo.toml
+++ b/members/nullnet-proxy/Cargo.toml
@@ -10,6 +10,7 @@ async-trait.workspace = true
 pingora-core = { version = "0.8.0", features = ["openssl"] }
 pingora-proxy = "0.8.0"
 pingora-http = "0.8.0"
+http = "1"
 pingora-openssl = "0.8.0"
 openssl = "0.10"
 arc-swap = "1"
diff --git a/members/nullnet-proxy/src/main.rs b/members/nullnet-proxy/src/main.rs
index b0c453c..6c1833c 100644
--- a/members/nullnet-proxy/src/main.rs
+++ b/members/nullnet-proxy/src/main.rs
@@ -32,7 +32,8 @@ use std::time::Instant;
 const PROXY_PORT: u16 = 80;
 const HTTPS_PROXY_PORT: u16 = 443;
 
-/// Per-request state threaded from `request_filter` to `upstream_peer`.
+/// Per-request state threaded from `request_filter` to `upstream_peer`/
+/// `upstream_request_filter`.
 #[derive(Default)]
 pub struct ProxyCtx {
     /// The backend service name the HTTP route table resolved for this
@@ -43,6 +44,10 @@ pub struct ProxyCtx {
     /// `upstream_peer`'s own header derivation is the fallback for that case,
     /// exactly as it was before path-based routing existed.
     service_name: Option<String>,
+    /// The path to actually send upstream, when a matched route's
+    /// `strip_prefix` rewrote it. `None` means "forward the original path
+    /// unchanged" — the pre-this-field, only behavior.
+    forward_path: Option<String>,
 }
 
 #[async_trait]
@@ -61,9 +66,30 @@ impl ProxyHttp for NullnetProxy {
         if let Some(host) = ingress_host(session) {
             let path = session.req_header().uri.path().to_string();
             match self.routes.load().resolve(&host, &path) {
-                Resolution::Matched(RouteMatch::Backend(name)) => ctx.service_name = Some(name),
-                Resolution::Matched(RouteMatch::Redirect { to, status }) => {
-                    let location = resolve_redirect_target(&to, session.req_header(), self.tls);
+                Resolution::Matched(RouteMatch::Backend {
+                    service_name,
+                    forward_path,
+                }) => {
+                    ctx.service_name = Some(service_name);
+                    if forward_path != path {
+                        ctx.forward_path = Some(forward_path);
+                    }
+                }
+                Resolution::Matched(RouteMatch::Redirect {
+                    to,
+                    status,
+                    preserve_path,
+                    preserve_query,
+                    matched_suffix,
+                }) => {
+                    let location = resolve_redirect_target(
+                        &to,
+                        &matched_suffix,
+                        preserve_path,
+                        preserve_query,
+                        session.req_header(),
+                        self.tls,
+                    );
                     let mut resp = ResponseHeader::build(status, None)?;
                     resp.insert_header("location", location.as_str())?;
                     resp.insert_header("content-length", "0")?;
@@ -299,8 +325,15 @@ impl ProxyHttp for NullnetProxy {
         &self,
         session: &mut Session,
         upstream_request: &mut RequestHeader,
-        _ctx: &mut Self::CTX,
+        ctx: &mut Self::CTX,
     ) -> Result<()> {
+        // A matched route's `strip_prefix` rewrote the path to send
+        // upstream — apply it here, on the outgoing request only; the
+        // client-facing session/logs still show the original path.
+        if let Some(forward_path) = &ctx.forward_path {
+            rewrite_uri_path(upstream_request, forward_path)?;
+        }
+
         // TLS terminates at this proxy, so it is the sole source of truth for
         // client IP, scheme, and requested host; any X-Forwarded-* the client
         // itself sent is untrusted and must be overwritten, not appended to.
@@ -313,6 +346,24 @@ impl ProxyHttp for NullnetProxy {
     }
 }
 
+/// Replace `upstream_request`'s path with `new_path`, preserving its
+/// existing query string. Used when a matched route's `strip_prefix`
+/// rewrote the path to send upstream.
+fn rewrite_uri_path(upstream_request: &mut RequestHeader, new_path: &str) -> Result<()> {
+    let path_and_query = match upstream_request.uri.query() {
+        Some(q) => format!("{new_path}?{q}"),
+        None => new_path.to_string(),
+    };
+    let uri = http::Uri::builder()
+        .path_and_query(path_and_query)
+        .build()
+        .map_err(|e| {
+            Error::explain(ErrorType::InternalError, format!("bad rewritten path: {e}"))
+        })?;
+    upstream_request.set_uri(uri);
+    Ok(())
+}
+
 /// Overwrite the X-Forwarded-{For,Proto,Host} headers on the upstream request
 /// with the ingress connection's real client IP, scheme, and requested host.
 fn set_forwarded_headers(
@@ -460,9 +511,48 @@ fn https_redirect_url(req: &RequestHeader, https_port: u16) -> String {
 /// scheme/host as the incoming request with `to` substituted as the path. No
 /// variable interpolation (e.g. no matched-suffix preservation) — see
 /// docs/http-path-routing-design.md.
-fn resolve_redirect_target(to: &str, req: &RequestHeader, tls: bool) -> String {
-    if to.contains("://") {
-        return to.to_string();
+/// Build the `Location` value for a matched redirect route: `to` verbatim
+/// (plus any appended suffix/query — see below), or — for a bare `/...`
+/// path — the same scheme/host as the incoming request with `to`
+/// substituted as the path.
+///
+/// `matched_suffix` is the request path's suffix beyond the matched
+/// `path_prefix`; appended to `to` when `preserve_path` is set (NGINX
+/// `rewrite ^/old(.*) /new$1 permanent;` equivalent). `preserve_query`
+/// appends the original request's query string, merged with `to`'s own
+/// query (if any) via `&` rather than dropping either.
+fn resolve_redirect_target(
+    to: &str,
+    matched_suffix: &str,
+    preserve_path: bool,
+    preserve_query: bool,
+    req: &RequestHeader,
+    tls: bool,
+) -> String {
+    let (base, existing_query) = match to.split_once('?') {
+        Some((b, q)) => (b.to_string(), Some(q.to_string())),
+        None => (to.to_string(), None),
+    };
+
+    let mut target = base;
+    if preserve_path && !matched_suffix.is_empty() {
+        target.push_str(matched_suffix);
+    }
+
+    let mut query_parts: Vec<String> = Vec::new();
+    if let Some(q) = existing_query {
+        query_parts.push(q);
+    }
+    if preserve_query && let Some(q) = req.uri.query() {
+        query_parts.push(q.to_string());
+    }
+    if !query_parts.is_empty() {
+        target.push('?');
+        target.push_str(&query_parts.join("&"));
+    }
+
+    if target.contains("://") {
+        return target;
     }
     let host_header = req
         .headers
@@ -470,7 +560,7 @@ fn resolve_redirect_target(to: &str, req: &RequestHeader, tls: bool) -> String {
         .and_then(|v| v.to_str().ok())
         .unwrap_or("");
     let scheme = if tls { "https" } else { "http" };
-    format!("{scheme}://{host_header}{to}")
+    format!("{scheme}://{host_header}{target}")
 }
 
 /// Subscribe to the control service's certificate stream and atomically swap the
@@ -591,6 +681,101 @@ mod tests {
         set_forwarded_headers(&mut r, None, false, None).unwrap();
         assert!(r.headers.get("x-forwarded-host").is_none());
     }
+
+    #[test]
+    fn redirect_target_absolute_url_used_verbatim_by_default() {
+        let r = req("old.example.com", "/whatever?x=1");
+        assert_eq!(
+            resolve_redirect_target(
+                "https://new.example.com/",
+                "whatever?x=1",
+                false,
+                false,
+                &r,
+                false
+            ),
+            "https://new.example.com/"
+        );
+    }
+
+    #[test]
+    fn redirect_target_relative_path_uses_request_host_and_scheme() {
+        let r = req("old.example.com", "/old");
+        assert_eq!(
+            resolve_redirect_target("/new", "", false, false, &r, true),
+            "https://old.example.com/new"
+        );
+    }
+
+    #[test]
+    fn redirect_target_preserve_path_appends_matched_suffix() {
+        let r = req("old.example.com", "/old/x/y");
+        assert_eq!(
+            resolve_redirect_target("/new", "/x/y", true, false, &r, false),
+            "http://old.example.com/new/x/y"
+        );
+    }
+
+    #[test]
+    fn redirect_target_preserve_path_no_op_on_exact_match() {
+        let r = req("old.example.com", "/old");
+        assert_eq!(
+            resolve_redirect_target("/new", "", true, false, &r, false),
+            "http://old.example.com/new"
+        );
+    }
+
+    #[test]
+    fn redirect_target_preserve_query_appends_request_query() {
+        let r = req("old.example.com", "/old?foo=bar");
+        assert_eq!(
+            resolve_redirect_target("/new", "", false, true, &r, false),
+            "http://old.example.com/new?foo=bar"
+        );
+    }
+
+    #[test]
+    fn redirect_target_preserve_query_merges_with_configured_query() {
+        let r = req("old.example.com", "/old?foo=bar");
+        assert_eq!(
+            resolve_redirect_target("/new?static=1", "", false, true, &r, false),
+            "http://old.example.com/new?static=1&foo=bar"
+        );
+    }
+
+    #[test]
+    fn redirect_target_preserve_query_absent_when_request_has_none() {
+        let r = req("old.example.com", "/old");
+        assert_eq!(
+            resolve_redirect_target("/new", "", false, true, &r, false),
+            "http://old.example.com/new"
+        );
+    }
+
+    #[test]
+    fn redirect_target_preserve_path_and_query_together() {
+        let r = req("old.example.com", "/old/x?foo=bar");
+        assert_eq!(
+            resolve_redirect_target("/new", "/x", true, true, &r, true),
+            "https://old.example.com/new/x?foo=bar"
+        );
+    }
+
+    #[test]
+    fn rewrite_uri_path_preserves_query_string() {
+        let mut r = req("api", "/api/users?limit=10");
+        rewrite_uri_path(&mut r, "/users").unwrap();
+        assert_eq!(r.uri.path(), "/users");
+        assert_eq!(r.uri.query(), Some("limit=10"));
+    }
+
+    #[test]
+    fn rewrite_uri_path_without_query() {
+        let mut r = req("api", "/api/users");
+        rewrite_uri_path(&mut r, "/users").unwrap();
+        assert_eq!(r.uri.path(), "/users");
+        assert_eq!(r.uri.query(), None);
+    }
 }
 
 // fn redirect_stdout_stderr_to_file()
diff --git a/members/nullnet-proxy/src/routes.rs b/members/nullnet-proxy/src/routes.rs
index 30619af..9246b90 100644
--- a/members/nullnet-proxy/src/routes.rs
+++ b/members/nullnet-proxy/src/routes.rs
@@ -8,8 +8,27 @@ use std::sync::Arc;
 /// What a matched route dispatches to.
 #[derive(Clone, Debug, PartialEq)]
 pub(crate) enum RouteMatch {
-    Backend(String),
-    Redirect { to: String, status: u16 },
+    Backend {
+        service_name: String,
+        /// Path to actually forward to the backend: the original request
+        /// path unchanged, or — when the route's `strip_prefix` is set —
+        /// the original path with the matched `path_prefix` stripped (the
+        /// NGINX `proxy_pass http://backend/;` trailing-slash equivalent).
+        /// Always a valid absolute path (never empty, always starts with
+        /// `/`), even when stripping would otherwise leave nothing.
+        forward_path: String,
+    },
+    Redirect {
+        to: String,
+        status: u16,
+        preserve_path: bool,
+        preserve_query: bool,
+        /// The request path's suffix beyond the matched `path_prefix` —
+        /// appended to `to` when `preserve_path` is set. Caller (`main.rs`)
+        /// combines this with the request's query string and Host header;
+        /// `routes.rs` only knows about the path.
+        matched_suffix: String,
+    },
 }
 
 /// The outcome of resolving `(host, path)` against the route table.
@@ -64,16 +83,27 @@ impl RouteTable {
             return Resolution::Fallback;
         };
         for r in routes {
-            if !path.starts_with(r.path_prefix.as_str()) {
+            let Some(suffix) = path.strip_prefix(r.path_prefix.as_str()) else {
                 continue;
-            }
+            };
             return match &r.target {
                 Some(Target::ServiceName(name)) => {
-                    Resolution::Matched(RouteMatch::Backend(name.clone()))
+                    let forward_path = if r.strip_prefix {
+                        normalize_forward_path(suffix)
+                    } else {
+                        path.to_string()
+                    };
+                    Resolution::Matched(RouteMatch::Backend {
+                        service_name: name.clone(),
+                        forward_path,
+                    })
                 }
                 Some(Target::Redirect(redirect)) => Resolution::Matched(RouteMatch::Redirect {
                     to: redirect.to.clone(),
                     status: u16::try_from(redirect.status_code).unwrap_or(301),
+                    preserve_path: redirect.preserve_path,
+                    preserve_query: redirect.preserve_query,
+                    matched_suffix: suffix.to_string(),
                 }),
                 // Malformed entry (neither target set) — the server never
                 // sends this; skip rather than dispatch nowhere.
@@ -84,6 +114,20 @@ impl RouteTable {
     }
 }
 
+/// A stripped path is always forwarded as a valid absolute path: `""` (the
+/// whole path matched the prefix exactly) becomes `/`, and a suffix that
+/// lost its leading slash (stripping `path_prefix = "/"` itself) gets one
+/// back.
+fn normalize_forward_path(suffix: &str) -> String {
+    if suffix.is_empty() {
+        "/".to_string()
+    } else if suffix.starts_with('/') {
+        suffix.to_string()
+    } else {
+        format!("/{suffix}")
+    }
+}
+
 /// Subscribe to the control service's HTTP route-table stream and atomically
 /// swap the proxy's route table on every push (initial set + each
 /// `services.toml` change). Mirrors `main::watch_certificates`: the stream
@@ -121,6 +165,16 @@ mod tests {
             host: host.to_string(),
             path_prefix: path.to_string(),
             target: Some(Target::ServiceName(service.to_string())),
+            strip_prefix: false,
+        }
+    }
+
+    fn strip_prefix_route(host: &str, path: &str, service: &str) -> HttpRoute {
+        HttpRoute {
+            host: host.to_string(),
+            path_prefix: path.to_string(),
+            target: Some(Target::ServiceName(service.to_string())),
+            strip_prefix: true,
         }
     }
 
@@ -131,7 +185,24 @@ mod tests {
             target: Some(Target::Redirect(HttpRedirect {
                 to: to.to_string(),
                 status_code: status,
+                preserve_path: false,
+                preserve_query: false,
+            })),
+            strip_prefix: false,
+        }
+    }
+
+    fn preserving_redirect_route(host: &str, path: &str, to: &str, status: u32) -> HttpRoute {
+        HttpRoute {
+            host: host.to_string(),
+            path_prefix: path.to_string(),
+            target: Some(Target::Redirect(HttpRedirect {
+                to: to.to_string(),
+                status_code: status,
+                preserve_path: true,
+                preserve_query: true,
             })),
+            strip_prefix: false,
         }
     }
 
@@ -153,15 +224,24 @@ mod tests {
         let table = RouteTable::from_bundle(&bundle);
         assert_eq!(
             table.resolve("ops.example.com", "/api/v2/users"),
-            Resolution::Matched(RouteMatch::Backend("api-v2".to_string()))
+            Resolution::Matched(RouteMatch::Backend {
+                service_name: "api-v2".to_string(),
+                forward_path: "/api/v2/users".to_string(),
+            })
         );
         assert_eq!(
             table.resolve("ops.example.com", "/api/users"),
-            Resolution::Matched(RouteMatch::Backend("api".to_string()))
+            Resolution::Matched(RouteMatch::Backend {
+                service_name: "api".to_string(),
+                forward_path: "/api/users".to_string(),
+            })
         );
         assert_eq!(
             table.resolve("ops.example.com", "/anything-else"),
-            Resolution::Matched(RouteMatch::Backend("grafana".to_string()))
+            Resolution::Matched(RouteMatch::Backend {
+                service_name: "grafana".to_string(),
+                forward_path: "/anything-else".to_string(),
+            })
         );
     }
 
@@ -193,6 +273,77 @@ mod tests {
             Resolution::Matched(RouteMatch::Redirect {
                 to: "https://ops.example.com/".to_string(),
                 status: 301,
+                preserve_path: false,
+                preserve_query: false,
+                matched_suffix: "whatever".to_string(),
+            })
+        );
+    }
+
+    #[test]
+    fn strip_prefix_removes_matched_prefix_from_forward_path() {
+        let bundle = HttpRouteBundle {
+            routes: vec![strip_prefix_route("ops.example.com", "/api", "api")],
+        };
+        let table = RouteTable::from_bundle(&bundle);
+        assert_eq!(
+            table.resolve("ops.example.com", "/api/users"),
+            Resolution::Matched(RouteMatch::Backend {
+                service_name: "api".to_string(),
+                forward_path: "/users".to_string(),
+            })
+        );
+    }
+
+    #[test]
+    fn strip_prefix_on_exact_match_forwards_root() {
+        let bundle = HttpRouteBundle {
+            routes: vec![strip_prefix_route("ops.example.com", "/api", "api")],
+        };
+        let table = RouteTable::from_bundle(&bundle);
+        assert_eq!(
+            table.resolve("ops.example.com", "/api"),
+            Resolution::Matched(RouteMatch::Backend {
+                service_name: "api".to_string(),
+                forward_path: "/".to_string(),
+            })
+        );
+    }
+
+    #[test]
+    fn strip_prefix_on_catch_all_keeps_leading_slash() {
+        let bundle = HttpRouteBundle {
+            routes: vec![strip_prefix_route("ops.example.com", "/", "root")],
+        };
+        let table = RouteTable::from_bundle(&bundle);
+        assert_eq!(
+            table.resolve("ops.example.com", "/foo/bar"),
+            Resolution::Matched(RouteMatch::Backend {
+                service_name: "root".to_string(),
+                forward_path: "/foo/bar".to_string(),
+            })
+        );
+    }
+
+    #[test]
+    fn preserving_redirect_carries_suffix_and_flags() {
+        let bundle = HttpRouteBundle {
+            routes: vec![preserving_redirect_route(
+                "old.example.com",
+                "/old",
+                "/new",
+                301,
+            )],
+        };
+        let table = RouteTable::from_bundle(&bundle);
+        assert_eq!(
+            table.resolve("old.example.com", "/old/x/y"),
+            Resolution::Matched(RouteMatch::Redirect {
+                to: "/new".to_string(),
+                status: 301,
+                preserve_path: true,
+                preserve_query: true,
+                matched_suffix: "/x/y".to_string(),
             })
         );
     }

From 085e9d366e98a8da68f1af935bacd16065f591c3 Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 19:30:55 -0400
Subject: [PATCH 12/14] docs: document
 strip_prefix/preserve_path/preserve_query additions

Also corrects an inaccurate earlier claim that redirect query-string
passthrough was 'already implicit' -- it wasn't; resolve_redirect_target
never touched the request path/query in either direction before this.
---
 docs/http-path-routing-design.md | 131 ++++++++++++++++++++++++++-----
 1 file changed, 110 insertions(+), 21 deletions(-)

diff --git a/docs/http-path-routing-design.md b/docs/http-path-routing-design.md
index 21e5724..cc8b85e 100644
--- a/docs/http-path-routing-design.md
+++ b/docs/http-path-routing-design.md
@@ -96,12 +96,34 @@ host = "old.example.com"
 path = "/"
 redirect_to = "https://ops.example.com/"
 redirect_status = 301        # optional, defaults to 301
+
+# new — strip the matched prefix before forwarding (NGINX
+# `proxy_pass http://backend/;` trailing-slash equivalent): "api" sees
+# "/users", not "/api/users"
+[[route]]
+host = "ops.example.com"
+path = "/api"
+service = "api"
+strip_prefix = true
+
+# new — carry the matched suffix and the original query string into a
+# redirect (NGINX `rewrite ^/old(.*) /new$1 permanent;` equivalent):
+# /old/x/y?foo=bar -> /new/x/y?foo=bar
+[[route]]
+host = "old.example.com"
+path = "/old"
+redirect_to = "/new"
+preserve_path = true
+preserve_query = true
 ```
 
 `service` and `redirect_to` are mutually exclusive (exactly one required),
 mirroring how `*_blocked_countries`/`*_allowed_countries` are already
 validated as mutually exclusive in `input.rs`. `redirect_status` is
-restricted to `301 | 302 | 307 | 308`.
+restricted to `301 | 302 | 307 | 308`. `strip_prefix` only applies to
+`service` routes; `preserve_path`/`preserve_query` only apply to
+`redirect_to` routes — each is rejected on the wrong target kind. All three
+default to `false`, so every existing config is unaffected.
 
 ### Example: the issue's own scenario
 
@@ -193,12 +215,18 @@ message HttpRoute {
                                   // way a Host-routed service is today
     HttpRedirect redirect = 4;
   }
+  // Only meaningful when target = service_name: strip path_prefix from the
+  // path forwarded to the backend (NGINX `proxy_pass http://backend/;`
+  // trailing-slash equivalent). Default false forwards the path unchanged.
+  bool strip_prefix = 5;
 }
 
 message HttpRedirect {
-  string to = 1;           // absolute URL, or a path template — see "Redirect
-                            // target" below
-  uint32 status_code = 2;  // 301/302/307/308
+  string to = 1;              // absolute URL, or a path template — see
+                               // "Redirect target" below
+  uint32 status_code = 2;     // 301/302/307/308
+  bool preserve_path = 3;     // append the request path's matched suffix to `to`
+  bool preserve_query = 4;    // append the original request's query string
 }
 
 message HttpRouteBundle {
@@ -216,10 +244,20 @@ setup, `get_or_add_upstream`) is untouched.
 
 ### Redirect target
 
-Keep it simple for v1: `to` is either an absolute URL (used verbatim) or
-starts with `/` (path-only — same scheme/host as the incoming request,
-target path substituted). No variable interpolation (no `$request_uri`
-equivalent) in v1 — see Open wrinkles.
+`to` is either an absolute URL (used verbatim) or starts with `/` (path-only
+— same scheme/host as the incoming request, target path substituted).
+`preserve_path` appends the request path's suffix beyond the matched
+`path_prefix` (NGINX `rewrite ^/old(.*) /new$1 permanent;` equivalent);
+`preserve_query` appends the original request's `?query` string, merged with
+`&` if `to` already carries its own. Both default to `false`, reproducing
+`to` used verbatim — the only behavior before these two fields existed.
+
+**Correction to an earlier version of this doc**: it previously claimed
+query-string passthrough was "already implicit since redirects don't touch
+it." That was wrong — the original implementation never touched the request
+path/query at all in either direction, so nothing was preserved by default.
+`preserve_query`/`preserve_path` are the fix, not a refinement of existing
+passthrough.
 
 ### Server changes (`nullnet-server`)
 
@@ -232,9 +270,14 @@ equivalent) in v1 — see Open wrinkles.
       #[serde(default = "default_path")]
       path: String,
       service: Option<String>,
-      redirect_to: Option<String>,
       #[serde(default)]
+      strip_prefix: bool,
+      redirect_to: Option<String>,
       redirect_status: Option<u16>,
+      #[serde(default)]
+      preserve_path: bool,
+      #[serde(default)]
+      preserve_query: bool,
   }
   ```
 - `ServicesToml` gains `#[serde(default)] routes: Vec<RouteToml>`.
@@ -245,6 +288,9 @@ equivalent) in v1 — see Open wrinkles.
   - `service` must name a declared service in the *same* stack (routes don't
     reach across stacks, same scoping as `proxy_dependencies`);
   - the referenced service must be `protocol = "http"`;
+  - `strip_prefix` is rejected on a `redirect_to` route; `preserve_path`/
+    `preserve_query` are rejected on a `service` route — each only makes
+    sense for its own target kind;
   - no two routes in the *same stack* share `(host, path)` exactly — this
     plus the equivalent cross-stack check (below) is `detect_route_conflicts`,
     the HTTP-route sibling of the existing `detect_port_conflicts`.
@@ -287,6 +333,33 @@ equivalent) in v1 — see Open wrinkles.
     recomputing it from the Host header — the only production-code change to
     this function is where `service_name` comes from.
 
+### Path rewrite additions (`strip_prefix` / `preserve_path` / `preserve_query`)
+
+Added on top of the v1 design above, closing three gaps identified after the
+initial implementation landed:
+
+- `routes.rs`'s `RouteTable::resolve` computes the request path's suffix
+  beyond the matched `path_prefix` (via `str::strip_prefix`) and returns it
+  as part of the match — `RouteMatch::Backend { service_name, forward_path
+  }` (the path to actually forward — rewritten when `strip_prefix` is set,
+  via a `normalize_forward_path` helper that guarantees the result is a
+  valid absolute path even when stripping would otherwise leave `""`) or
+  `RouteMatch::Redirect { .., matched_suffix }` (the raw suffix; `main.rs`
+  combines it with the request's query string and Host header, which
+  `routes.rs` has no access to).
+- `main.rs`'s `ProxyCtx` gains `forward_path: Option<String>`, set in
+  `request_filter` alongside `service_name`. `upstream_request_filter`
+  applies it via a new `rewrite_uri_path` helper (`RequestHeader::set_uri`
+  with the new path, existing query string preserved) — the client-facing
+  session and every log line still show the *original* path; only the
+  request actually sent upstream changes.
+- `resolve_redirect_target` gained `matched_suffix`/`preserve_path`/
+  `preserve_query` parameters: splits any query already in the configured
+  `to`, optionally appends the matched suffix to the path portion, then
+  optionally appends the request's own query (merged with `&`, not
+  overwritten), before applying the existing absolute-URL-vs-relative-path
+  logic unchanged.
+
 ### What is reused vs new
 
 | Piece | Reused | New |
@@ -367,13 +440,14 @@ lightweight transitive dependency of the `toml` ecosystem) to splice the
 - **Path matching is prefix-only**, like NGINX's plain (non-regex)
   `location` — no wildcards/regex in v1. If a follow-up needs `location ~`
   parity, that's a separate `path_regex` field on `HttpRoute`, additive.
-- **No variable interpolation in redirect targets** (`$request_uri`-style).
-  A path-only `to` re-appends the literal target path, not the *matched
-  suffix* — `path="/old" → to="/new"` on request `/old/x` redirects to
-  `/new`, not `/new/x`. If suffix-preserving redirects are needed, that's a
-  `preserve_suffix: bool` flag as a follow-up, not a v1 requirement (the
-  issue only asks for redirects "of course that's included," not detailed
-  semantics).
+- **Resolved**: matched-suffix and query-string preservation in redirects
+  (`preserve_path`/`preserve_query`) and backend path rewriting
+  (`strip_prefix`) — see "Path rewrite additions" above.
+- **The admin UI form doesn't expose `strip_prefix`/`preserve_path`/
+  `preserve_query` yet** — `pages/Routes.tsx`'s Add/Edit modal only has
+  Host/Path/Service-or-Redirect/Status fields. They're fully settable via
+  TOML or a direct `POST /api/routes/{stack}` call (the API layer accepts
+  them), just not from the form. Follow-up UI work, not a backend gap.
 - **Ingress country policy is keyed by service name today** — a redirect
   route has no backend service, so there's no ingress policy to check before
   issuing it. This is consistent with NGINX (a `return` in a `location`
@@ -409,18 +483,33 @@ Implemented on `feature/proxy-redirects-137`:
    `toml_edit` workspace dependency).
 5. **UI**: `pages/Routes.tsx` (table + add/edit `Modal`, following the
    `Users.tsx` CRUD pattern), nav entry, `RouteJson`/`RoutesResponseJson`
-   types. ✅ `tsc -b` + `vite build` + `eslint` clean.
+   types. ✅ `tsc -b` + `vite build` + `eslint` clean. Does **not** yet expose
+   `strip_prefix`/`preserve_path`/`preserve_query` in the form (see Open
+   wrinkles) — added to the wire/API/TOML layers only so far.
 6. **Docs**: not yet updated — `docs/architecture.md` doesn't currently
    enumerate individual watch streams, so no change was needed there.
+7. **Path rewrite additions** (`strip_prefix`, `preserve_path`,
+   `preserve_query`): proto fields, server validation (each rejected on the
+   wrong target kind), `RouteTable::resolve`'s `forward_path`/
+   `matched_suffix` computation, `main.rs`'s `rewrite_uri_path` +
+   `resolve_redirect_target` rewrite. ✅ 161 server tests, 36 proxy tests pass
+   (found and fixed a genuine bug in the process — the original
+   `resolve_redirect_target` never touched the request's path/query at all,
+   contrary to what an earlier version of this doc claimed).
+
+Manually verified end-to-end by the repo owner against a real deployment
+(`nullnet-server` + `nullnet-proxy` + `nullnet-client`, real backend
+containers) — confirmed working, including hot-reload of route changes. A
+"not working" symptom hit during that verification turned out to be a stale
+`nullnet-proxy` binary (right commit checked out, binary not rebuilt from
+it), not a code bug.
 
 `cargo fmt`/`cargo clippy -D warnings` clean for `nullnet-grpc-lib`,
 `nullnet-server`, `nullnet-proxy` (the three crates CI lints/tests).
 
 ## Follow-ups (out of scope for this issue)
 
-- Manual end-to-end verification against a running proxy + control service
-  (this stage covered unit tests only).
+- Admin UI form support for `strip_prefix`/`preserve_path`/`preserve_query`
+  (backend/API already support them; see Open wrinkles).
 - Regex/wildcard path matching.
-- Redirect target variable interpolation (preserve matched suffix, query
-  string passthrough is already implicit since redirects don't touch it).
 - Header-based routing (beyond Host), if ever needed.

From dc04b2668d19fdaeb9d8ab1e9f05ec74e4b6e296 Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 19:36:30 -0400
Subject: [PATCH 13/14] ui: expose strip_prefix/preserve_path/preserve_query in
 the Routes form

Checkboxes on the Add/Edit modal (service target gets 'strip matched
prefix', redirect target gets 'preserve path suffix'/'preserve query
string'), each with a one-line explainer of what it does. Routes table's
target label now shows which flags are set. RouteTargetJson in types.ts
updated to match the server's always-present boolean fields.
---
 .../nullnet-server/ui/src/pages/Routes.tsx    | 100 ++++++++++++++----
 members/nullnet-server/ui/src/types.ts        |   4 +-
 2 files changed, 82 insertions(+), 22 deletions(-)

diff --git a/members/nullnet-server/ui/src/pages/Routes.tsx b/members/nullnet-server/ui/src/pages/Routes.tsx
index 1ba340f..8c183e5 100644
--- a/members/nullnet-server/ui/src/pages/Routes.tsx
+++ b/members/nullnet-server/ui/src/pages/Routes.tsx
@@ -13,8 +13,11 @@ interface RouteFormState {
   path: string;
   targetKind: 'service' | 'redirect';
   service: string;
+  stripPrefix: boolean;
   redirectTo: string;
   redirectStatus: RedirectStatus;
+  preservePath: boolean;
+  preserveQuery: boolean;
 }
 
 const EMPTY_FORM: RouteFormState = {
@@ -22,8 +25,11 @@ const EMPTY_FORM: RouteFormState = {
   path: '/',
   targetKind: 'service',
   service: '',
+  stripPrefix: false,
   redirectTo: '',
   redirectStatus: 301,
+  preservePath: false,
+  preserveQuery: false,
 };
 
 function routeToForm(r: RouteJson): RouteFormState {
@@ -32,8 +38,11 @@ function routeToForm(r: RouteJson): RouteFormState {
     path: r.path,
     targetKind: r.target.kind,
     service: r.target.kind === 'service' ? r.target.service : '',
+    stripPrefix: r.target.kind === 'service' ? r.target.strip_prefix : false,
     redirectTo: r.target.kind === 'redirect' ? r.target.to : '',
     redirectStatus: r.target.kind === 'redirect' ? (r.target.status as RedirectStatus) : 301,
+    preservePath: r.target.kind === 'redirect' ? r.target.preserve_path : false,
+    preserveQuery: r.target.kind === 'redirect' ? r.target.preserve_query : false,
   };
 }
 
@@ -43,13 +52,25 @@ function formToRoute(f: RouteFormState): RouteJson {
     path: f.path.trim() || '/',
     target:
       f.targetKind === 'service'
-        ? { kind: 'service', service: f.service }
-        : { kind: 'redirect', to: f.redirectTo.trim(), status: f.redirectStatus },
+        ? { kind: 'service', service: f.service, strip_prefix: f.stripPrefix }
+        : {
+            kind: 'redirect',
+            to: f.redirectTo.trim(),
+            status: f.redirectStatus,
+            preserve_path: f.preservePath,
+            preserve_query: f.preserveQuery,
+          },
   };
 }
 
 function targetLabel(r: RouteJson): string {
-  return r.target.kind === 'service' ? `→ ${r.target.service}` : `redirect ${r.target.status} → ${r.target.to}`;
+  if (r.target.kind === 'service') {
+    return `→ ${r.target.service}${r.target.strip_prefix ? ' (strip prefix)' : ''}`;
+  }
+  const flags = [r.target.preserve_path && 'preserve path', r.target.preserve_query && 'preserve query']
+    .filter(Boolean)
+    .join(', ');
+  return `redirect ${r.target.status} → ${r.target.to}${flags ? ` (${flags})` : ''}`;
 }
 
 export default function RoutesPage() {
@@ -247,24 +268,39 @@ export default function RoutesPage() {
             </select>
           </label>
           {form.targetKind === 'service' ? (
-            <label className="modal-field">
-              <span>Service</span>
-              <select value={form.service} onChange={e => setForm(f => ({ ...f, service: e.target.value }))}>
-                <option value="" disabled>
-                  select a service…
-                </option>
-                {httpServices.map(s => (
-                  <option key={s} value={s}>
-                    {s}
+            <>
+              <label className="modal-field">
+                <span>Service</span>
+                <select value={form.service} onChange={e => setForm(f => ({ ...f, service: e.target.value }))}>
+                  <option value="" disabled>
+                    select a service…
                   </option>
-                ))}
-              </select>
-              {httpServices.length === 0 && (
-                <div style={{ fontSize: 11, color: 'var(--t2)' }}>
-                  No proxy-reachable http services declared in this stack yet.
-                </div>
-              )}
-            </label>
+                  {httpServices.map(s => (
+                    <option key={s} value={s}>
+                      {s}
+                    </option>
+                  ))}
+                </select>
+                {httpServices.length === 0 && (
+                  <div style={{ fontSize: 11, color: 'var(--t2)' }}>
+                    No proxy-reachable http services declared in this stack yet.
+                  </div>
+                )}
+              </label>
+              <label className="scope-check">
+                <input
+                  type="checkbox"
+                  checked={form.stripPrefix}
+                  onChange={e => setForm(f => ({ ...f, stripPrefix: e.target.checked }))}
+                />
+                Strip matched prefix before forwarding
+              </label>
+              <div style={{ fontSize: 11, color: 'var(--t2)', marginTop: -8 }}>
+                E.g. path <code>/api</code> forwards <code>/users</code> instead of{' '}
+                <code>/api/users</code> — like NGINX's <code>proxy_pass http://backend/;</code>{' '}
+                trailing-slash behavior.
+              </div>
+            </>
           ) : (
             <>
               <label className="modal-field">
@@ -288,6 +324,30 @@ export default function RoutesPage() {
                   <option value={308}>308 Permanent Redirect</option>
                 </select>
               </label>
+              <label className="scope-check">
+                <input
+                  type="checkbox"
+                  checked={form.preservePath}
+                  onChange={e => setForm(f => ({ ...f, preservePath: e.target.checked }))}
+                />
+                Preserve matched path suffix
+              </label>
+              <div style={{ fontSize: 11, color: 'var(--t2)', marginTop: -8 }}>
+                E.g. path <code>/old</code> → <code>/new</code> on request <code>/old/x</code> redirects
+                to <code>/new/x</code>, not <code>/new</code>.
+              </div>
+              <label className="scope-check">
+                <input
+                  type="checkbox"
+                  checked={form.preserveQuery}
+                  onChange={e => setForm(f => ({ ...f, preserveQuery: e.target.checked }))}
+                />
+                Preserve query string
+              </label>
+              <div style={{ fontSize: 11, color: 'var(--t2)', marginTop: -8 }}>
+                Appends the original request's <code>?query</code> to the redirect target (merged
+                with <code>&amp;</code> if it already has one).
+              </div>
             </>
           )}
           {formError && <div className="modal-err">{formError}</div>}
diff --git a/members/nullnet-server/ui/src/types.ts b/members/nullnet-server/ui/src/types.ts
index 7f40f27..4c68a73 100644
--- a/members/nullnet-server/ui/src/types.ts
+++ b/members/nullnet-server/ui/src/types.ts
@@ -180,8 +180,8 @@ export interface ChainJson {
 
 // HTTP path-based routing — see docs/http-path-routing-design.md.
 export type RouteTargetJson =
-  | { kind: 'service'; service: string }
-  | { kind: 'redirect'; to: string; status: number };
+  | { kind: 'service'; service: string; strip_prefix: boolean }
+  | { kind: 'redirect'; to: string; status: number; preserve_path: boolean; preserve_query: boolean };
 
 export interface RouteJson {
   host: string;

From 2cb6b759f0be53178b5476f23f622f3820d1f6db Mon Sep 17 00:00:00 2001
From: antonl <antonl@jvl.ca>
Date: Fri, 7 Aug 2026 19:36:56 -0400
Subject: [PATCH 14/14] docs: mark admin UI form support for the path-rewrite
 fields as done

---
 docs/http-path-routing-design.md | 29 +++++++++++++----------------
 1 file changed, 13 insertions(+), 16 deletions(-)

diff --git a/docs/http-path-routing-design.md b/docs/http-path-routing-design.md
index cc8b85e..c50e172 100644
--- a/docs/http-path-routing-design.md
+++ b/docs/http-path-routing-design.md
@@ -441,13 +441,10 @@ lightweight transitive dependency of the `toml` ecosystem) to splice the
   `location` — no wildcards/regex in v1. If a follow-up needs `location ~`
   parity, that's a separate `path_regex` field on `HttpRoute`, additive.
 - **Resolved**: matched-suffix and query-string preservation in redirects
-  (`preserve_path`/`preserve_query`) and backend path rewriting
-  (`strip_prefix`) — see "Path rewrite additions" above.
-- **The admin UI form doesn't expose `strip_prefix`/`preserve_path`/
-  `preserve_query` yet** — `pages/Routes.tsx`'s Add/Edit modal only has
-  Host/Path/Service-or-Redirect/Status fields. They're fully settable via
-  TOML or a direct `POST /api/routes/{stack}` call (the API layer accepts
-  them), just not from the form. Follow-up UI work, not a backend gap.
+  (`preserve_path`/`preserve_query`), backend path rewriting
+  (`strip_prefix`) — see "Path rewrite additions" above — and admin UI form
+  support for all three (checkboxes on the Add/Edit modal, `RouteTargetJson`
+  updated in `types.ts`).
 - **Ingress country policy is keyed by service name today** — a redirect
   route has no backend service, so there's no ingress policy to check before
   issuing it. This is consistent with NGINX (a `return` in a `location`
@@ -483,19 +480,21 @@ Implemented on `feature/proxy-redirects-137`:
    `toml_edit` workspace dependency).
 5. **UI**: `pages/Routes.tsx` (table + add/edit `Modal`, following the
    `Users.tsx` CRUD pattern), nav entry, `RouteJson`/`RoutesResponseJson`
-   types. ✅ `tsc -b` + `vite build` + `eslint` clean. Does **not** yet expose
-   `strip_prefix`/`preserve_path`/`preserve_query` in the form (see Open
-   wrinkles) — added to the wire/API/TOML layers only so far.
+   types. Add/Edit modal has checkboxes for `strip_prefix`/`preserve_path`/
+   `preserve_query`, each with a one-line explainer; the routes table's
+   target label shows which are set (e.g. `→ api (strip prefix)`). ✅
+   `tsc -b` + `vite build` + `eslint` clean.
 6. **Docs**: not yet updated — `docs/architecture.md` doesn't currently
    enumerate individual watch streams, so no change was needed there.
 7. **Path rewrite additions** (`strip_prefix`, `preserve_path`,
    `preserve_query`): proto fields, server validation (each rejected on the
    wrong target kind), `RouteTable::resolve`'s `forward_path`/
    `matched_suffix` computation, `main.rs`'s `rewrite_uri_path` +
-   `resolve_redirect_target` rewrite. ✅ 161 server tests, 36 proxy tests pass
-   (found and fixed a genuine bug in the process — the original
-   `resolve_redirect_target` never touched the request's path/query at all,
-   contrary to what an earlier version of this doc claimed).
+   `resolve_redirect_target` rewrite, and the UI form fields above. ✅ 161
+   server tests, 36 proxy tests pass (found and fixed a genuine bug in the
+   process — the original `resolve_redirect_target` never touched the
+   request's path/query at all, contrary to what an earlier version of this
+   doc claimed).
 
 Manually verified end-to-end by the repo owner against a real deployment
 (`nullnet-server` + `nullnet-proxy` + `nullnet-client`, real backend
@@ -509,7 +508,5 @@ it), not a code bug.
 
 ## Follow-ups (out of scope for this issue)
 
-- Admin UI form support for `strip_prefix`/`preserve_path`/`preserve_query`
-  (backend/API already support them; see Open wrinkles).
 - Regex/wildcard path matching.
 - Header-based routing (beyond Host), if ever needed.