@x47base/pocketbase-addon 0.1.0

package/edge/gateway.go

@@ -0,0 +1,295 @@
+package edge
+
+import (
+	"bytes"
+	"context"
+	_ "embed"
+	"encoding/json"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httputil"
+	"net/netip"
+	"net/url"
+	"path"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/spink-dev/pocketbase-extension/security"
+)
+
+//go:embed openapi.json
+var contract []byte
+
+type operatorKey struct{}
+
+type bucket struct {
+	tokens  float64
+	updated time.Time
+}
+
+func (b *bucket) take(now time.Time, rate, burst int) bool {
+	if b.updated.IsZero() {
+		b.tokens = float64(burst)
+	} else {
+		b.tokens = min(float64(burst), b.tokens+now.Sub(b.updated).Seconds()*float64(rate))
+	}
+	b.updated = now
+	if b.tokens < 1 {
+		return false
+	}
+	b.tokens--
+	return true
+}
+
+type Gateway struct {
+	mu              sync.Mutex
+	policy          Policy
+	snapshot        Snapshot
+	valid           bool
+	global          bucket
+	clients         map[netip.Addr]*bucket
+	active          int
+	admin           chan struct{}
+	proxy           *httputil.ReverseProxy
+	upstreamHealthy atomic.Bool
+	accepted        atomic.Uint64
+	rejected        atomic.Uint64
+}
+
+func New(upstream *url.URL, p Policy) (*Gateway, error) {
+	if err := p.Validate(); err != nil {
+		return nil, err
+	}
+	g := &Gateway{policy: p, clients: map[netip.Addr]*bucket{}, admin: make(chan struct{}, 8)}
+	g.proxy = &httputil.ReverseProxy{
+		Rewrite: func(r *httputil.ProxyRequest) {
+			r.SetURL(upstream)
+			// Only our sanitized peer identity crosses the private network.
+			r.Out.Header.Del("X-Spink-Operator")
+			if r.In.Context().Value(operatorKey{}) == true {
+				r.Out.Header.Set("X-Spink-Operator", "1")
+			}
+			r.Out.Header.Del("Forwarded")
+			r.Out.Header.Del("X-Real-IP")
+			r.Out.Header.Del("X-Forwarded-Host")
+			r.Out.Header.Del("X-Forwarded-Proto")
+			r.Out.Header.Del("X-Forwarded-For")
+			host, _, _ := net.SplitHostPort(r.In.RemoteAddr)
+			r.Out.Header.Set("X-Forwarded-For", host)
+		},
+		Transport: &http.Transport{Proxy: nil, DialContext: (&net.Dialer{Timeout: 3 * time.Second, KeepAlive: 30 * time.Second}).DialContext, MaxIdleConns: 128, MaxIdleConnsPerHost: 128, IdleConnTimeout: 60 * time.Second, ResponseHeaderTimeout: 10 * time.Second, MaxResponseHeaderBytes: 64 << 10},
+		ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
+			http.Error(w, "upstream unavailable", http.StatusBadGateway)
+		},
+		FlushInterval: -1,
+	}
+	return g, nil
+}
+
+// Apply never resets budgets during reload, including unchanged polling results.
+func (g *Gateway) Apply(p Policy, s Snapshot, valid bool) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if valid {
+		g.policy = p
+		g.snapshot = s
+	}
+	g.valid = valid
+}
+func (g *Gateway) SetHealthy(v bool) { g.upstreamHealthy.Store(v) }
+func (g *Gateway) reject(w http.ResponseWriter, code int) {
+	g.rejected.Add(1)
+	w.Header().Set("Cache-Control", "no-store")
+	if code == 429 || code == 503 {
+		w.Header().Set("Retry-After", "1")
+	}
+	http.Error(w, http.StatusText(code), code)
+}
+func canonical(r *http.Request) bool {
+	// Reject ambiguous decoding instead of normalizing differently from the backend.
+	return r.URL.RawPath == "" && !strings.ContainsAny(r.URL.Path, "\\%\x00") && path.Clean(r.URL.Path) == strings.TrimSuffix(r.URL.Path, "/") && !strings.Contains(r.URL.Path, "//")
+}
+func client(r *http.Request, p Policy) (netip.Addr, bool) {
+	host, _, err := net.SplitHostPort(r.RemoteAddr)
+	if err != nil {
+		return netip.Addr{}, false
+	}
+	ip, err := netip.ParseAddr(host)
+	if err != nil {
+		return ip, false
+	}
+	ip = ip.Unmap()
+	if !contains(p.trusted, ip) {
+		return ip, true
+	}
+	parts := strings.Split(r.Header.Get("X-Forwarded-For"), ",")
+	if len(parts) > 16 {
+		return ip, false
+	}
+	for i := len(parts) - 1; i >= 0; i-- {
+		next, e := netip.ParseAddr(strings.TrimSpace(parts[i]))
+		if e != nil {
+			return ip, false
+		}
+		ip = next.Unmap()
+		if !contains(p.trusted, ip) {
+			return ip, true
+		}
+	}
+	return ip, true
+}
+func publicPath(r *http.Request, p Policy) bool {
+	parts := strings.Split(strings.Trim(r.URL.Path, "/"), "/")
+	if len(parts) == 2 && parts[0] == "api" && (parts[1] == "health" || parts[1] == "realtime") {
+		return true
+	}
+	if len(parts) < 3 || parts[0] != "api" || (parts[1] != "collections" && parts[1] != "files") {
+		return false
+	}
+	allowed := false
+	for _, c := range p.Collections {
+		if parts[2] == c {
+			allowed = true
+			break
+		}
+	}
+	if !allowed {
+		return false
+	}
+	if parts[1] == "files" {
+		return len(parts) >= 5
+	}
+	// Collection schema/settings APIs never cross the public listener.
+	return len(parts) >= 4 && (parts[3] == "records" || strings.HasPrefix(parts[3], "auth-") || strings.HasPrefix(parts[3], "request-") || strings.HasPrefix(parts[3], "confirm-"))
+}
+func (g *Gateway) Public(w http.ResponseWriter, r *http.Request) {
+	if !canonical(r) {
+		g.reject(w, 400)
+		return
+	}
+	g.mu.Lock()
+	p := g.policy
+	ip, ok := client(r, p)
+	code := 0
+	now := time.Now()
+	switch {
+	case !g.valid:
+		code = 503
+	case !ok:
+		code = 400
+	case contains(p.blocked, ip):
+		code = 403
+	case !publicPath(r, p):
+		code = 403
+	}
+	if code == 0 {
+		for _, prefix := range p.BlockedPaths {
+			if strings.HasPrefix(r.URL.Path, prefix) {
+				code = 403
+				break
+			}
+		}
+	}
+	if code == 0 && g.snapshot.Policy.Mode == "enforce" {
+		if a, exists := g.snapshot.Actions[security.RequestFamily(r)]; exists && a.ExpiresAt.After(now) {
+			code = 403
+		}
+	}
+	if code == 0 && !g.global.take(now, p.Rate, p.Burst) {
+		code = 429
+	}
+	if code == 0 {
+		b := g.clients[ip]
+		if b == nil {
+			if len(g.clients) >= p.MaxClients {
+				for key, old := range g.clients {
+					if now.Sub(old.updated) > time.Minute {
+						delete(g.clients, key)
+					}
+				}
+			}
+			if len(g.clients) >= p.MaxClients {
+				code = 429
+			} else {
+				b = &bucket{}
+				g.clients[ip] = b
+			}
+		}
+		if b != nil && !b.take(now, p.ClientRate, p.ClientBurst) {
+			code = 429
+		}
+	}
+	if code == 0 {
+		if g.active >= p.MaxConcurrent {
+			code = 503
+		} else {
+			g.active++
+		}
+	}
+	g.mu.Unlock()
+	if code != 0 {
+		g.reject(w, code)
+		return
+	}
+	defer func() { g.mu.Lock(); g.active--; g.mu.Unlock() }()
+	if r.ContentLength > p.MaxBodyBytes {
+		g.reject(w, 413)
+		return
+	}
+	// Fully bound and validate chunked bodies before any upstream side effect.
+	if r.Body != nil {
+		b, err := io.ReadAll(http.MaxBytesReader(w, r.Body, p.MaxBodyBytes))
+		r.Body.Close()
+		if err != nil {
+			g.reject(w, 413)
+			return
+		}
+		r.Body = io.NopCloser(bytes.NewReader(b))
+		r.ContentLength = int64(len(b))
+	}
+	r.RemoteAddr = net.JoinHostPort(ip.String(), "0")
+	g.accepted.Add(1)
+	g.proxy.ServeHTTP(w, r)
+}
+func (g *Gateway) Operator(w http.ResponseWriter, r *http.Request) {
+	switch r.URL.Path {
+	case "/edge/openapi.json":
+		w.Header().Set("Content-Type", "application/json")
+		w.Write(contract)
+		return
+	case "/edge/healthz":
+		w.WriteHeader(204)
+		return
+	case "/edge/readyz":
+		g.mu.Lock()
+		valid := g.valid
+		g.mu.Unlock()
+		if !valid || !g.upstreamHealthy.Load() {
+			http.Error(w, "not ready", 503)
+			return
+		}
+		w.WriteHeader(204)
+		return
+	case "/edge/status":
+		g.mu.Lock()
+		state := map[string]any{"policyReady": g.valid, "upstreamHealthy": g.upstreamHealthy.Load(), "active": g.active, "trackedClients": len(g.clients), "accepted": g.accepted.Load(), "rejected": g.rejected.Load()}
+		g.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Cache-Control", "no-store")
+		json.NewEncoder(w).Encode(state)
+		return
+	}
+	select {
+	case g.admin <- struct{}{}:
+		defer func() { <-g.admin }()
+	default:
+		g.reject(w, 503)
+		return
+	}
+	// Operator uploads retain native limits without buffering large backups.
+	r = r.WithContext(context.WithValue(r.Context(), operatorKey{}, true))
+	g.proxy.ServeHTTP(w, r)
+}

package/edge/gateway_test.go

@@ -0,0 +1,296 @@
+package edge
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/spink-dev/pocketbase-extension/security"
+)
+
+func policy() Policy {
+	return Policy{Collections: []string{"notes"}, Rate: 100, Burst: 200, ClientRate: 20, ClientBurst: 40, MaxClients: 16, MaxConcurrent: 2, MaxBodyBytes: 1024}
+}
+func snap() Snapshot {
+	c := security.DefaultConfig()
+	c.Mode = "enforce"
+	return Snapshot{Version: 1, Revision: 1, Policy: c, Actions: map[string]security.Action{}}
+}
+func fixture(t *testing.T, p Policy, h http.HandlerFunc) (*Gateway, *atomic.Int64) {
+	t.Helper()
+	count := new(atomic.Int64)
+	s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		count.Add(1)
+		if h != nil {
+			h(w, r)
+		} else {
+			w.WriteHeader(204)
+		}
+	}))
+	t.Cleanup(s.Close)
+	u, _ := url.Parse(s.URL)
+	g, err := New(u, p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g.Apply(g.policy, snap(), true)
+	return g, count
+}
+func req(target string) *http.Request {
+	r := httptest.NewRequest("GET", target, nil)
+	r.RemoteAddr = "192.0.2.10:1234"
+	return r
+}
+func TestRejectBeforeUpstream(t *testing.T) {
+	cases := []struct {
+		name, path string
+		code       int
+		alter      func(*Gateway, *http.Request)
+	}{
+		{"admin", "/_/", 403, nil},
+		{"schema", "/api/collections/notes", 403, nil},
+		{"superuser", "/api/collections/_superusers/auth-with-password", 403, nil},
+		{"superuserID", "/api/collections/pbc_3142635823/auth-with-password", 403, nil},
+		{"management", "/api/security/status", 403, nil},
+		{"batch", "/api/batch", 403, nil},
+		{"unknownCollection", "/api/collections/hidden/records", 403, nil},
+		{"ambiguous", "/api/collections/notes/../_superusers/records", 400, nil},
+		{"encoded", "/api/collections/%6eotes/records", 400, nil},
+		{"CIDR", "/api/health", 403, func(g *Gateway, r *http.Request) {
+			p := g.policy
+			p.BlockedCIDRs = []string{"192.0.2.0/24"}
+			p.Validate()
+			g.Apply(p, snap(), true)
+		}},
+		{"path", "/api/health", 403, func(g *Gateway, r *http.Request) {
+			p := g.policy
+			p.BlockedPaths = []string{"/api/health"}
+			g.Apply(p, snap(), true)
+		}},
+		{"action", "/api/collections/notes/records", 403, func(g *Gateway, r *http.Request) {
+			s := snap()
+			s.Actions["reads"] = security.Action{Family: "reads", ExpiresAt: time.Now().Add(time.Minute)}
+			g.Apply(g.policy, s, true)
+		}},
+		{"unready", "/api/health", 503, func(g *Gateway, r *http.Request) { g.Apply(Policy{}, Snapshot{}, false) }},
+		{"body", "/api/collections/notes/records", 413, func(g *Gateway, r *http.Request) {
+			*r = *httptest.NewRequest("POST", r.URL.String(), strings.NewReader(strings.Repeat("a", 1025)))
+			r.RemoteAddr = "192.0.2.10:1234"
+		}},
+		{"chunked", "/api/collections/notes/records", 413, func(g *Gateway, r *http.Request) {
+			*r = *httptest.NewRequest("POST", r.URL.String(), strings.NewReader(strings.Repeat("a", 1025)))
+			r.RemoteAddr = "192.0.2.10:1234"
+			r.ContentLength = -1
+		}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			g, n := fixture(t, policy(), nil)
+			r := req(tc.path)
+			if tc.alter != nil {
+				tc.alter(g, r)
+			}
+			w := httptest.NewRecorder()
+			g.Public(w, r)
+			if w.Code != tc.code || n.Load() != 0 {
+				t.Fatalf("status=%d upstream=%d", w.Code, n.Load())
+			}
+		})
+	}
+}
+func TestForwardedIdentity(t *testing.T) {
+	g, _ := fixture(t, policy(), func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Forwarded-For") != "192.0.2.10" || r.Header.Get("X-Real-IP") != "" || r.Header.Get("Forwarded") != "" {
+			t.Errorf("spoofed forwarding headers: %v", r.Header)
+		}
+		w.WriteHeader(204)
+	})
+	r := req("/api/health")
+	r.Header.Set("X-Forwarded-For", "127.0.0.1")
+	r.Header.Set("X-Real-IP", "127.0.0.1")
+	r.Header.Set("Forwarded", "for=127.0.0.1")
+	w := httptest.NewRecorder()
+	g.Public(w, r)
+	if w.Code != 204 {
+		t.Fatal(w.Code)
+	}
+	p := policy()
+	p.TrustedProxies = []string{"192.0.2.0/24"}
+	p.Validate()
+	r.Header.Set("X-Forwarded-For", "198.51.100.3, 192.0.2.20")
+	ip, ok := client(r, p)
+	if !ok || ip.String() != "198.51.100.3" {
+		t.Fatal(ip, ok)
+	}
+}
+func TestPublicCapacityDoesNotConsumeOperator(t *testing.T) {
+	entered := make(chan struct{}, 1)
+	release := make(chan struct{})
+	p := policy()
+	p.MaxConcurrent = 1
+	g, n := fixture(t, p, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/api/health" {
+			entered <- struct{}{}
+			<-release
+		}
+		w.WriteHeader(204)
+	})
+	done := make(chan struct{})
+	go func() { defer close(done); g.Public(httptest.NewRecorder(), req("/api/health")) }()
+	<-entered
+	w := httptest.NewRecorder()
+	g.Public(w, req("/api/health"))
+	if w.Code != 503 || n.Load() != 1 {
+		t.Fatal(w.Code, n.Load())
+	}
+	for _, path := range []string{"/edge/healthz", "/_/"} {
+		w = httptest.NewRecorder()
+		g.Operator(w, req(path))
+		if w.Code != 204 {
+			t.Fatal(path, w.Code)
+		}
+	}
+	close(release)
+	<-done
+}
+func TestRateReloadAndBoundedClients(t *testing.T) {
+	p := policy()
+	p.ClientBurst = 1
+	p.MaxClients = 1
+	g, n := fixture(t, p, nil)
+	w := httptest.NewRecorder()
+	g.Public(w, req("/api/health"))
+	if w.Code != 204 {
+		t.Fatal(w.Code)
+	}
+	g.Apply(g.policy, snap(), true)
+	w = httptest.NewRecorder()
+	g.Public(w, req("/api/health"))
+	if w.Code != 429 {
+		t.Fatal(w.Code)
+	}
+	r := req("/api/health")
+	r.RemoteAddr = "198.51.100.1:1234"
+	w = httptest.NewRecorder()
+	g.Public(w, r)
+	if w.Code != 429 || n.Load() != 1 || len(g.clients) != 1 {
+		t.Fatal(w.Code, n.Load(), len(g.clients))
+	}
+}
+func TestExpiredAndObserveActions(t *testing.T) {
+	for _, observe := range []bool{false, true} {
+		g, _ := fixture(t, policy(), nil)
+		s := snap()
+		expiry := time.Now().Add(-time.Minute)
+		if observe {
+			s.Policy.Mode = "observe"
+			expiry = time.Now().Add(time.Minute)
+		}
+		s.Actions["reads"] = security.Action{Family: "reads", ExpiresAt: expiry}
+		g.Apply(g.policy, s, true)
+		w := httptest.NewRecorder()
+		g.Public(w, req("/api/collections/notes/records"))
+		if w.Code != 204 {
+			t.Fatal(w.Code)
+		}
+	}
+}
+func TestPolicyAndSnapshotFiles(t *testing.T) {
+	dir := t.TempDir()
+	file := filepath.Join(dir, "policy.json")
+	b, _ := json.Marshal(policy())
+	os.WriteFile(file, b, 0600)
+	if _, err := LoadPolicy(file); err != nil {
+		t.Fatal(err)
+	}
+	os.WriteFile(file, append(b, []byte(" {}")...), 0600)
+	if _, err := LoadPolicy(file); err == nil {
+		t.Fatal("accepted trailing JSON")
+	}
+	os.WriteFile(file, []byte(`{"unknown":1}`), 0600)
+	if _, err := LoadPolicy(file); err == nil {
+		t.Fatal("accepted unknown field")
+	}
+	b, _ = json.Marshal(snap())
+	os.WriteFile(file, b, 0600)
+	if _, err := LoadSnapshot(file); err != nil {
+		t.Fatal(err)
+	}
+	s := snap()
+	s.Version = 2
+	b, _ = json.Marshal(s)
+	os.WriteFile(file, b, 0600)
+	if _, err := LoadSnapshot(file); err == nil {
+		t.Fatal("accepted wrong checkpoint version")
+	}
+	p := policy()
+	p.MaxConcurrent = 1024
+	p.MaxBodyBytes = 32 << 20
+	if p.Validate() == nil {
+		t.Fatal("unbounded memory budget")
+	}
+}
+func TestReadinessIsNotLiveness(t *testing.T) {
+	g, _ := fixture(t, policy(), nil)
+	w := httptest.NewRecorder()
+	g.Operator(w, req("/edge/readyz"))
+	if w.Code != 503 {
+		t.Fatal(w.Code)
+	}
+	g.SetHealthy(true)
+	w = httptest.NewRecorder()
+	g.Operator(w, req("/edge/readyz"))
+	if w.Code != 204 {
+		t.Fatal(w.Code)
+	}
+	g.Apply(Policy{}, Snapshot{}, false)
+	w = httptest.NewRecorder()
+	g.Operator(w, req("/edge/readyz"))
+	if w.Code != 503 {
+		t.Fatal(w.Code)
+	}
+	w = httptest.NewRecorder()
+	g.Operator(w, req("/edge/healthz"))
+	if w.Code != 204 {
+		t.Fatal(w.Code)
+	}
+}
+
+func TestStaleCheckpointFailsClosed(t *testing.T) {
+	file := filepath.Join(t.TempDir(), "state.json")
+	b, _ := json.Marshal(snap())
+	if err := os.WriteFile(file, b, 0600); err != nil {
+		t.Fatal(err)
+	}
+	old := time.Now().Add(-time.Minute)
+	os.Chtimes(file, old, old)
+	if _, err := LoadSnapshot(file); err == nil {
+		t.Fatal("accepted stale checkpoint")
+	}
+}
+
+func TestOperatorMarkerCannotCrossPublicListener(t *testing.T) {
+	operator := false
+	g, _ := fixture(t, policy(), func(w http.ResponseWriter, r *http.Request) {
+		want := ""
+		if operator {
+			want = "1"
+		}
+		if r.Header.Get("X-Spink-Operator") != want {
+			t.Error("wrong operator marker")
+		}
+		w.WriteHeader(204)
+	})
+	r := req("/api/health")
+	r.Header.Set("X-Spink-Operator", "1")
+	g.Public(httptest.NewRecorder(), r)
+	operator = true
+	g.Operator(httptest.NewRecorder(), req("/_/"))
+}

package/edge/openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"Spink edge local diagnostics","version":"0.1.0"},"servers":[{"url":"http://127.0.0.1:8081"}],"paths":{"/edge/healthz":{"get":{"summary":"Gateway process liveness","responses":{"204":{"description":"Alive"}}}},"/edge/readyz":{"get":{"summary":"Validated policy and cached upstream health","responses":{"204":{"description":"Ready"},"503":{"description":"Not ready"}}}},"/edge/status":{"get":{"summary":"Local-only aggregate counters; no database credentials","responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","properties":{"policyReady":{"type":"boolean"},"upstreamHealthy":{"type":"boolean"},"active":{"type":"integer"},"trackedClients":{"type":"integer"},"accepted":{"type":"integer"},"rejected":{"type":"integer"}}}}}}}}}}}