amadan

carlos / platform Public

edge: /__carlos/ is reserved on every route, answered before the observer

The platform now owns /__carlos/ on every hostname the edge serves. The
intercept sits in ServeHTTP between the route lookup and the observing
writer (spec 2026-09-07 §3.4, §4): after the lookup because attribution
needs up.route and an unknown host must still backhaul or 404 exactly as
before, and before the wrapper so nothing under the prefix is metered,
compressed, cached, proxied, or able to wake a hibernating instance.
Everything under it is a plain 404 for now; tasks 4 and 7 fill in the
snippet and the beacon dispatch inside serveReserved.

The prefix is exact — /__carlosx and /__carlos with no trailing slash
stay the app's — and the reserved segment cannot be steered away from
the hostname's root app: lookupUpstreamPath returns the host's own route
for a first segment of "__carlos" in either the cleaned or the raw form,
ahead of the prefix map, so a stale or hand-edited route_paths row can
never point the browser door at another account's app. validPathPrefix
(internal/domains) refuses "__carlos" so no supported writer can publish
such a row in the first place.

fakeActivator's call counter is now mutex guarded with a calls()
accessor; the two existing tests that read .served directly use it.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Paul Campbell pushed by paul@keymail.dev 987ffd191f89a1eb2287bf3fc83794ddec1b5109 parent 0fb9157
9 files changed, +178 −8
  • internal/domains/claims.go +6 −2
  • internal/domains/claims_test.go +20 −0
  • internal/domains/paths_test.go +1 −1
  • internal/edge/edge.go +20 −0
  • internal/edge/edge_test.go +14 −1
  • internal/edge/fleet_route_test.go +2 −2
  • internal/edge/reserved.go +24 −0
  • internal/edge/reserved_test.go +89 −0
  • internal/edge/tunnel_test.go +2 −2
diff --git a/internal/domains/claims.go b/internal/domains/claims.go
index 935a8b062..018ee92be 100644
--- a/internal/domains/claims.go
+++ b/internal/domains/claims.go
@@ -377,8 +377,12 @@ func validPathPrefix(p string) bool {
}
// "." and ".." would be normalised away by any path cleaner between the
// browser and here, so a row keyed on either is unreachable by
- // construction.
- return p != "." && p != ".."
+ // construction. "__carlos" is unreachable for a different reason: the
+ // edge reserves /__carlos/ on every route (internal/edge/reserved.go)
+ // and answers it before the upstream is consulted, so a row keyed on it
+ // could only ever be dead weight — and it is refused at the door rather
+ // than stored to look like it steers something.
+ return p != "." && p != ".." && p != "__carlos"
}
// SetClaimPaths is the ONLY writer of a claim's Paths field, the same
diff --git a/internal/domains/claims_test.go b/internal/domains/claims_test.go
index 0a3fd8063..7a5888c22 100644
--- a/internal/domains/claims_test.go
+++ b/internal/domains/claims_test.go
@@ -315,3 +315,23 @@ func TestHostDenied(t *testing.T) {
t.Fatal("empty deny entry must never match")
}
}
+
+// TestValidPathPrefixReservedSegment: "__carlos" is the edge's own path space
+// (internal/edge/reserved.go), answered ahead of the upstream on every route,
+// so a prefix row keyed on it could never match a request and must not be
+// storable. The segment boundary is exact — "__carlosx" is an ordinary prefix
+// an account may claim.
+func TestValidPathPrefixReservedSegment(t *testing.T) {
+ cases := []struct {
+ prefix string
+ want bool
+ }{
+ {"__carlos", false},
+ {"__carlosx", true},
+ }
+ for _, c := range cases {
+ if got := validPathPrefix(c.prefix); got != c.want {
+ t.Errorf("validPathPrefix(%q) = %v, want %v", c.prefix, got, c.want)
+ }
+ }
+}
diff --git a/internal/domains/paths_test.go b/internal/domains/paths_test.go
index 7e172915b..c2ddf81b9 100644
--- a/internal/domains/paths_test.go
+++ b/internal/domains/paths_test.go
@@ -216,7 +216,7 @@ func TestSetClaimPathsRejectsMalformedPrefixes(t *testing.T) {
}); err != nil {
t.Fatal(err)
}
- for _, bad := range []string{"/paulca", "paulca/awesomeconf", "", "with space"} {
+ for _, bad := range []string{"/paulca", "paulca/awesomeconf", "", "with space", "__carlos"} {
if _, err := SetClaimPaths(ctx, s, "ti.to", "tito", "classic",
map[string]string{bad: "go.tito.io"}); !errors.Is(err, ErrBadPathPrefix) {
t.Fatalf("prefix %q: err = %v, want ErrBadPathPrefix", bad, err)
diff --git a/internal/edge/edge.go b/internal/edge/edge.go
index aa7bad5f6..44208ee61 100644
--- a/internal/edge/edge.go
+++ b/internal/edge/edge.go
@@ -1133,6 +1133,16 @@ func (e *Edge) lookupUpstreamPath(host, urlPath string) (upstream, bool) {
// below simply miss, falling through to the host's own route.
seg := firstSegmentClean(urlPath)
raw := firstSegment(urlPath)
+ // The reserved segment belongs to the hostname's ROOT app, never to a
+ // prefix target (reserved.go). validPathPrefix refuses "__carlos" so no
+ // supported writer can publish such a row, but a map is data on a store
+ // that older code may have written: refusing it here means a stale or
+ // hand-edited row can never point the browser door — and the attribution
+ // ServeHTTP hands it — at a different account's app. Both forms are
+ // checked for the reason the block above gives.
+ if seg == reservedSegment || raw == reservedSegment {
+ return up, true
+ }
target, ok := up.paths[seg]
if !ok && raw != seg {
target, ok = up.paths[raw]
@@ -1279,6 +1289,16 @@ func (e *Edge) ServeHTTP(w http.ResponseWriter, r *http.Request) {
return
}
+ // The platform's own path space (reserved.go). Placed AFTER the lookup
+ // (attribution needs up.route, and an unknown host must still backhaul
+ // or 404 exactly as before) and BEFORE the observing writer, so a beacon
+ // is neither metered nor compressed nor cached and never reaches the
+ // activator branches below (spec §3.4, §4).
+ if strings.HasPrefix(r.URL.Path, ReservedPrefix) {
+ e.serveReserved(w, r, host, up)
+ return
+ }
+
// A login POST re-resolves its upstream by the path in `next`, not by
// its own (spec §4.2). On a hostname that routes by path prefix,
// lookupUpstreamPath keys on the first segment; "/.carlos/gate" has no
diff --git a/internal/edge/edge_test.go b/internal/edge/edge_test.go
index 157fc7d71..2e4ce7040 100644
--- a/internal/edge/edge_test.go
+++ b/internal/edge/edge_test.go
@@ -15,6 +15,7 @@ import (
"path/filepath"
"slices"
"strings"
+ "sync"
"sync/atomic"
"syscall"
"testing"
@@ -248,18 +249,30 @@ func TestFirstFingerprintObservationReloads(t *testing.T) {
t.Fatalf("route never served: first fingerprint observation was baselined away instead of reloading")
}
-// fakeActivator records the hibernation hook's calls.
+// fakeActivator records the hibernation hook's calls. The counter is mutex
+// guarded because the edge serves concurrently: a test that drives real
+// requests and then asserts on the count would otherwise race under -race.
type fakeActivator struct {
+ mu sync.Mutex
served int
retired []map[string]bool
}
func (f *fakeActivator) ServeHTTP(w http.ResponseWriter, r *http.Request, rt registry.Route, proxy http.Handler) bool {
+ f.mu.Lock()
f.served++
+ f.mu.Unlock()
proxy.ServeHTTP(w, r) // "wake" is instant; proxy straight through
return true
}
+// calls reports how many times the hibernation hook was invoked.
+func (f *fakeActivator) calls() int {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ return f.served
+}
+
func (f *fakeActivator) RetireExcept(keep map[string]bool) {
f.retired = append(f.retired, keep)
}
diff --git a/internal/edge/fleet_route_test.go b/internal/edge/fleet_route_test.go
index a1764b490..99024ccb1 100644
--- a/internal/edge/fleet_route_test.go
+++ b/internal/edge/fleet_route_test.go
@@ -273,8 +273,8 @@ func TestFleetRouteIsNeverActivatorManaged(t *testing.T) {
req := httptest.NewRequest("GET", "http://fleet-hib.example/", nil)
req.Host = "fleet-hib.example"
e.ServeHTTP(httptest.NewRecorder(), req)
- if act.served != 0 {
- t.Fatalf("activator woke a local process for a fleet-served host (%d call(s))", act.served)
+ if act.calls() != 0 {
+ t.Fatalf("activator woke a local process for a fleet-served host (%d call(s))", act.calls())
}
}
diff --git a/internal/edge/reserved.go b/internal/edge/reserved.go
new file mode 100644
index 000000000..24aa1b2af
--- /dev/null
+++ b/internal/edge/reserved.go
@@ -0,0 +1,24 @@
+package edge
+
+import "net/http"
+
+// ReservedPrefix is the platform's own path space on every route (spec
+// 2026-09-07 §3.4, §8 ruling 2): the browser door and its snippet. It is
+// answered here, between the route lookup and the observing writer, so
+// nothing under it is billed, compressed, cached, proxied or able to wake
+// an instance (§4).
+const ReservedPrefix = "/__carlos/"
+
+// reservedSegment is ReservedPrefix as a bare first path segment, the form
+// lookupUpstreamPath and internal/domains' validPathPrefix compare against:
+// no prefix map may steer it, and no claim may store a row keyed on it.
+const reservedSegment = "__carlos"
+
+// serveReserved answers a request under ReservedPrefix for the route the
+// lookup resolved. Anything not explicitly served is a plain 404 — never
+// the upstream's answer. Tasks 4 and 7 add the snippet and the beacon
+// dispatch inside it; host and up are already threaded through because both
+// need them for attribution.
+func (e *Edge) serveReserved(w http.ResponseWriter, r *http.Request, host string, up upstream) {
+ http.NotFound(w, r)
+}
diff --git a/internal/edge/reserved_test.go b/internal/edge/reserved_test.go
new file mode 100644
index 000000000..8819683f7
--- /dev/null
+++ b/internal/edge/reserved_test.go
@@ -0,0 +1,89 @@
+package edge
+
+import (
+ "net/http"
+ "net/http/httptest"
+ "sync/atomic"
+ "testing"
+
+ "github.com/carlosframework/platform/internal/registry"
+)
+
+// A route's upstream never sees /__carlos/*, whatever it would have served.
+func TestReservedPrefixNeverProxied(t *testing.T) {
+ var hits atomic.Int32
+ backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ hits.Add(1)
+ w.Write([]byte("upstream"))
+ }))
+ t.Cleanup(backend.Close)
+ reg := openReg(t)
+ if err := reg.Upsert(registry.Route{Host: "app.example.com", Kind: "service", Addr: backend.Listener.Addr().String(), Status: "ready", App: "web"}); err != nil {
+ t.Fatal(err)
+ }
+ e, err := New(reg, nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ srv := httptest.NewServer(e)
+ t.Cleanup(srv.Close)
+ for _, p := range []string{"/__carlos/x", "/__carlos/", "/__carlos/e"} {
+ req, _ := http.NewRequest("GET", srv.URL+p, nil)
+ req.Host = "app.example.com"
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatal(err)
+ }
+ resp.Body.Close()
+ if resp.StatusCode != http.StatusNotFound {
+ t.Fatalf("%s: status %d, want 404", p, resp.StatusCode)
+ }
+ }
+ if hits.Load() != 0 {
+ t.Fatalf("upstream saw %d reserved requests", hits.Load())
+ }
+ // The prefix is exact: /__carlosx and /__carlos (no slash) are the app's.
+ req, _ := http.NewRequest("GET", srv.URL+"/__carlosx", nil)
+ req.Host = "app.example.com"
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatal(err)
+ }
+ resp.Body.Close()
+ if hits.Load() != 1 {
+ t.Fatal("/__carlosx must reach the upstream")
+ }
+}
+
+// A hibernating route's activator is never invoked for a reserved path.
+func TestReservedPrefixNeverWakes(t *testing.T) {
+ reg := openReg(t)
+ if err := reg.Upsert(registry.Route{Host: "sleepy.example.com", Kind: "instance", Addr: "127.0.0.1:1", Status: "ready", App: "web", Hibernate: true}); err != nil {
+ t.Fatal(err)
+ }
+ act := &fakeActivator{}
+ e, err := New(reg, act)
+ if err != nil {
+ t.Fatal(err)
+ }
+ rec := httptest.NewRecorder()
+ req := httptest.NewRequest("POST", "http://sleepy.example.com/__carlos/a", nil)
+ e.ServeHTTP(rec, req)
+ if act.calls() != 0 {
+ t.Fatal("the activator must not see a reserved path")
+ }
+}
+
+// A prefix map cannot steer the reserved segment: a key "__carlos" is ignored.
+func TestLookupIgnoresReservedPrefixKey(t *testing.T) {
+ root := upstream{route: registry.Route{Host: "shared.example.com", App: "root"}, paths: map[string]string{"__carlos": "other.example.com", "team": "other.example.com"}}
+ other := upstream{route: registry.Route{Host: "other.example.com", App: "other"}}
+ e := &Edge{}
+ e.upstreams.Store(&map[string]upstream{"shared.example.com": root, "other.example.com": other})
+ if up, _ := e.lookupUpstreamPath("shared.example.com", "/__carlos/e"); up.route.App != "root" {
+ t.Fatalf("__carlos steered to %q", up.route.App)
+ }
+ if up, _ := e.lookupUpstreamPath("shared.example.com", "/team/x"); up.route.App != "other" {
+ t.Fatalf("ordinary prefix broke: %q", up.route.App)
+ }
+}
diff --git a/internal/edge/tunnel_test.go b/internal/edge/tunnel_test.go
index 4ba3c095a..5bbbc7739 100644
--- a/internal/edge/tunnel_test.go
+++ b/internal/edge/tunnel_test.go
@@ -700,8 +700,8 @@ func TestTunnelRouteIsNeverActivatorManaged(t *testing.T) {
req := httptest.NewRequest("GET", "http://moved.example/", nil)
req.Host = "moved.example"
e.ServeHTTP(httptest.NewRecorder(), req)
- if act.served != 0 {
- t.Fatalf("activator woke a local process for a tunnel-served host (%d call(s))", act.served)
+ if act.calls() != 0 {
+ t.Fatalf("activator woke a local process for a tunnel-served host (%d call(s))", act.calls())
}
}