@x47base/pocketbase-addon 0.1.0 → 0.2.0

package/cmd/hosting/main.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	hosting "github.com/spink-dev/pocketbase-extension/hosting"
+	"log"
+	"os"
+)
+
+func main() {
+	config := flag.String("blueprint", "blueprint.json", "Deployment blueprint")
+	out := flag.String("out", "generated", "Output directory")
+	flag.Parse()
+	raw, err := os.ReadFile(*config)
+	if err != nil {
+		log.Fatal(err)
+	}
+	var b hosting.Blueprint
+	if err = json.Unmarshal(raw, &b); err != nil {
+		log.Fatal(err)
+	}
+	if err = b.Render(*out); err != nil {
+		log.Fatal(err)
+	}
+	log.Print("Rendered Docker, Kubernetes, routing and DNS plans; no infrastructure was changed")
+}

package/cmd/pocketbase/main.go

@@ -6,6 +6,7 @@ import (
 	"github.com/pocketbase/pocketbase/plugins/migratecmd"
 	adapter "github.com/spink-dev/pocketbase-extension"
 	_ "github.com/spink-dev/pocketbase-extension/features"
+	"github.com/spink-dev/pocketbase-extension/hosting"
 	"github.com/spink-dev/pocketbase-extension/jsvm"
 	"github.com/spink-dev/pocketbase-extension/web"
 	"log"
@@ -28,11 +29,13 @@ func main() {
 		log.Fatal(err)
 	}
 	config := adapter.DefaultConfig()
+	config.Mode = "enforce"
 	statePath, err := filepath.Abs(filepath.Join(app.DataDir(), "security", "state.json"))
 	if err != nil {
 		log.Fatal(err)
 	}
 	config.StatePath = statePath
+	config.EdgeStatePath = os.Getenv("PB_SECURITY_EDGE_STATE_PATH")
 	if override := os.Getenv("PB_SECURITY_STATE_PATH"); override != "" {
 		config.StatePath = override
 	}
@@ -64,6 +67,15 @@ func main() {
 	if err := adapter.Register(app, config); err != nil {
 		log.Fatal(err)
 	}
+	if path := os.Getenv("HOSTING_ADDON_CONFIG"); path != "" {
+		c, err := hosting.Load(path)
+		if err != nil {
+			log.Fatal(err)
+		}
+		if _, err := hosting.Register(app, c); err != nil {
+			log.Fatal(err)
+		}
+	}
 	jsvm.MustRegister(app, jsvm.Config{HooksDir: hooksDir, MigrationsDir: migrationsDir, HooksWatch: watchHooks, HooksPoolSize: 15})
 	migratecmd.MustRegister(app, app.RootCmd, migratecmd.Config{Dir: migrationsDir, Automigrate: automigrate, TemplateLang: migratecmd.TemplateLangJS})
 	app.OnServe().BindFunc(func(e *core.ServeEvent) error {

package/deploy/README.md

@@ -5,7 +5,7 @@ has no published port. Use this as a single-host deployment template, with upstr
 TLS/DDoS protection appropriate to your hosting provider.
 
 ```sh
-cd /Users/x47base/git/spink-dev_pocketbase-extension
+cd /path/to/pocketbase-addon
 docker compose -f deploy/compose.yaml up --build -d --wait
 docker compose -f deploy/compose.yaml logs pocketbase
 ```
@@ -19,7 +19,7 @@ your existing development instance on 8090 and its admin account are untouched.
 |---|---|
 | `http://127.0.0.1:8080` | Public API: explicitly allowed collections only |
 | `http://127.0.0.1:8081/_/` | Native admin, Security, Backups, x47base extensions |
-| `http://127.0.0.1:8081/edge/status` | Gateway accepted/rejected counts, active work, readiness |
+| `http://127.0.0.1:8081/edge/status` | Gateway traffic, rejection reasons, upload bytes, active work and readiness |
 | `http://127.0.0.1:8081/edge/healthz` | Gateway process liveness; no database call |
 | `http://127.0.0.1:8081/edge/readyz` | Policy validity plus cached upstream health |
 
@@ -35,6 +35,8 @@ flowchart LR
     Lane --> DB
     DB --> State[Security checkpoint volume]
     State -. read only, one second poll .-> Edge
+    Edge --> Telemetry[Separate aggregate telemetry volume]
+    Telemetry -. read only, one second poll .-> DB
     App[Versioned migrations and hooks] --> DB
 ```
 
@@ -74,10 +76,20 @@ remains available to diagnose and recover. Preserve the separate security volume
 when replacing the database; it is not included in database backup archives.
 
 Defaults: 50 public requests/second (burst 100), 20 per client (burst 40), 32 active
-requests, 1MiB bodies, 4096 tracked clients. No waiting queue is added. New identities
+requests, at most 4 concurrent requests per client, 1MiB bodies, 4096 tracked clients. No waiting queue is added. New identities
 are denied when the bounded table is full; idle entries expire after a minute.
 Public bodies, including chunked bodies, are read and size-checked **before** any
-upstream side effect. Aggregate configured body buffering is capped at 128MiB.
+upstream side effect. Declared oversize bodies are rejected before reading. Unknown
+length bodies read at most the configured maximum plus one detection byte. Buffers
+have fixed capacity, avoiding geometric growth beyond the configured body budget
+(128MiB total plus at most one byte per active request). `bodyReadTimeoutSeconds`
+defaults to 5 (range 1–10); `maxClientConcurrent` defaults to min(4, maxConcurrent).
+Timed-out uploads return 408 and size violations return 413; failed reads return
+400. Rejections close HTTP/1 connections and expire the read deadline so unread
+uploads are not drained before responding. The timeout uses Go's
+[ResponseController](https://pkg.go.dev/net/http#ResponseController.SetReadDeadline).
+The per-client budget shares capacity behind a NAT unless a trusted proxy supplies
+a sanitized client address.
 Public connections cap at 256, headers at 16KiB, header reads at 3 seconds, request
 reads at 10 seconds, writes at 30 seconds. Realtime streams must reconnect after
 the public write deadline; they share the public concurrency budget.
@@ -130,8 +142,25 @@ Health checks report health; Docker restart policy restarts exited processes,
 not merely unhealthy ones. Rejection reduces database work; it cannot guarantee
 availability during link saturation, host exhaustion, disk failure or costly
 allowed queries. Use provider/CDN DDoS protection, backups and external monitoring.
-Gateway rejections appear in `/edge/status`; PocketBase incidents only describe
-traffic that reaches PocketBase, so the two counts intentionally differ.
+Gateway rejections appear in `/edge/status` and **Security → Overview / Incidents**
+through the dedicated telemetry volume. Both sources are labeled; do not sum their
+request counts. The UI reports stale/missing telemetry instead of implying safety.
+See [metric semantics and retention](../security/README.md#firewall-telemetry).
+
+## Upgrade an existing deployment
+
+Rebuild **both** images and recreate both services using the updated Compose file:
+
+```sh
+docker compose -f deploy/compose.yaml up --build -d --wait
+```
+
+Keep the existing Compose project name and data/security volumes. Do not use
+`down -v`. The new telemetry volume is automatically created with non-root
+ownership. Custom Compose configurations must add `PB_SECURITY_EDGE_STATE_PATH`,
+the edge `-telemetry` argument and the separate volume mounts from this template.
+Reload `http://127.0.0.1:8081/_/#/security` after deployment. A source update alone
+does not change an already-running image or a published npm installation.
 
 ## Verification and stopping
 

package/deploy/compose.yaml

@@ -16,6 +16,7 @@ services:
     environment:
       PB_SECURITY_MODE: enforce
       PB_SECURITY_STATE_PATH: /state/state.json
+      PB_SECURITY_EDGE_STATE_PATH: /telemetry/edge.json
       PB_SECURITY_OPERATOR_PEERS: 172.30.80.2/32
       PB_SECURITY_TRUSTED_PEERS: 172.30.80.2/32
       PB_SECURITY_MANAGEMENT_PEERS: 172.30.80.2/32,127.0.0.0/8,::1/128
@@ -23,6 +24,7 @@ services:
     volumes:
       - data:/pb_data
       - security:/state
+      - telemetry:/telemetry:ro
     networks:
       backend:
         ipv4_address: 172.30.80.3
@@ -34,6 +36,7 @@ services:
       context: ..
       target: edge
     image: spink-pocketbase-edge:local
+    command: ["-telemetry", "/telemetry/edge.json"]
     restart: unless-stopped
     read_only: true
     cap_drop: [ALL]
@@ -48,6 +51,7 @@ services:
     volumes:
       - ./edge.json:/etc/spink/edge.json:ro
       - security:/state:ro
+      - telemetry:/telemetry
     depends_on:
       pocketbase:
         condition: service_healthy
@@ -66,3 +70,4 @@ networks:
 volumes:
   data: {}
   security: {}
+  telemetry: {}

package/deploy/edge.json

@@ -1,5 +1,7 @@
 {
-  "collections": ["notes"],
+  "collections": [
+    "notes"
+  ],
   "blockedCIDRs": [],
   "blockedPaths": [],
   "trustedProxies": [],
@@ -9,5 +11,7 @@
   "clientBurst": 40,
   "maxClients": 4096,
   "maxConcurrent": 32,
-  "maxBodyBytes": 1048576
+  "maxBodyBytes": 1048576,
+  "maxClientConcurrent": 4,
+  "bodyReadTimeoutSeconds": 5
 }

package/edge/gateway.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	_ "embed"
 	"encoding/json"
+	"errors"
 	"io"
 	"net"
 	"net/http"
@@ -52,18 +53,22 @@ type Gateway struct {
 	global          bucket
 	clients         map[netip.Addr]*bucket
 	active          int
+	clientActive    map[netip.Addr]int
+	metrics         *telemetry
 	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)}
+	metrics, err := newTelemetry()
+	if err != nil {
+		return nil, err
+	}
+	g := &Gateway{metrics: metrics, clientActive: map[netip.Addr]int{}, policy: p, clients: map[netip.Addr]*bucket{}, admin: make(chan struct{}, security.OperatorConcurrency)}
 	g.proxy = &httputil.ReverseProxy{
 		Rewrite: func(r *httputil.ProxyRequest) {
 			r.SetURL(upstream)
@@ -82,8 +87,17 @@ func New(upstream *url.URL, p Policy) (*Gateway, error) {
 		},
 		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) {
+			if r.Context().Value(operatorKey{}) != true {
+				g.metrics.upstreamFailure()
+			}
 			http.Error(w, "upstream unavailable", http.StatusBadGateway)
 		},
+		ModifyResponse: func(r *http.Response) error {
+			if r.StatusCode >= 500 && r.Request.Context().Value(operatorKey{}) != true {
+				g.metrics.upstreamFailure()
+			}
+			return nil
+		},
 		FlushInterval: -1,
 	}
 	return g, nil
@@ -101,13 +115,21 @@ func (g *Gateway) Apply(p Policy, s Snapshot, valid bool) {
 }
 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 (g *Gateway) rejectPublic(w http.ResponseWriter, r *http.Request, code int, reason string, read uint64) {
+	g.metrics.outcome(reason, read, r.ContentLength)
+	// Do not let net/http drain an unread upload before sending the rejection.
+	if r.ProtoMajor == 1 {
+		w.Header().Set("Connection", "close")
+	}
+	_ = http.NewResponseController(w).SetReadDeadline(time.Now())
+	g.reject(w, 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, "//")
@@ -166,92 +188,125 @@ func publicPath(r *http.Request, p Policy) bool {
 	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) {
+	g.metrics.begin()
 	if !canonical(r) {
-		g.reject(w, 400)
+		g.rejectPublic(w, r, 400, "invalid_path", 0)
 		return
 	}
 	g.mu.Lock()
 	p := g.policy
 	ip, ok := client(r, p)
-	code := 0
+	code, reason := 0, ""
 	now := time.Now()
 	switch {
 	case !g.valid:
-		code = 503
+		code, reason = 503, "policy_unavailable"
 	case !ok:
-		code = 400
+		code, reason = 400, "invalid_client"
+	case r.ContentLength > p.MaxBodyBytes:
+		code, reason = 413, "body_too_large"
 	case contains(p.blocked, ip):
-		code = 403
+		code, reason = 403, "blocked_network"
 	case !publicPath(r, p):
-		code = 403
+		code, reason = 403, "private_route"
 	}
 	if code == 0 {
 		for _, prefix := range p.BlockedPaths {
 			if strings.HasPrefix(r.URL.Path, prefix) {
-				code = 403
+				code, reason = 403, "blocked_path"
 				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
+			code, reason = 403, "family_block"
 		}
 	}
 	if code == 0 && !g.global.take(now, p.Rate, p.Burst) {
-		code = 429
+		code, reason = 429, "global_rate"
 	}
 	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 {
+					if now.Sub(old.updated) > time.Minute && g.clientActive[key] == 0 {
 						delete(g.clients, key)
 					}
 				}
 			}
 			if len(g.clients) >= p.MaxClients {
-				code = 429
+				code, reason = 429, "client_capacity"
 			} else {
 				b = &bucket{}
 				g.clients[ip] = b
 			}
 		}
 		if b != nil && !b.take(now, p.ClientRate, p.ClientBurst) {
-			code = 429
+			code, reason = 429, "client_rate"
 		}
 	}
 	if code == 0 {
 		if g.active >= p.MaxConcurrent {
-			code = 503
+			code, reason = 503, "global_concurrency"
+		} else if g.clientActive[ip] >= p.MaxClientConcurrent {
+			code, reason = 429, "client_concurrency"
 		} else {
 			g.active++
+			g.clientActive[ip]++
 		}
 	}
 	g.mu.Unlock()
 	if code != 0 {
-		g.reject(w, code)
+		g.rejectPublic(w, r, code, reason, 0)
 		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)
+	defer func() {
+		g.mu.Lock()
+		g.active--
+		g.clientActive[ip]--
+		if g.clientActive[ip] == 0 {
+			delete(g.clientActive, ip)
+		}
+		g.mu.Unlock()
+	}()
+	var read uint64
+	if r.Body != nil && r.Body != http.NoBody {
+		controller := http.NewResponseController(w)
+		_ = controller.SetReadDeadline(time.Now().Add(time.Duration(p.BodyReadTimeoutSeconds) * time.Second))
+		// Allocate a fixed upper bound; ReadAll's growing buffers can exceed the body budget.
+		size := p.MaxBodyBytes + 1
+		if r.ContentLength >= 0 {
+			size = min(size, r.ContentLength+1)
+		}
+		body := make([]byte, int(size))
+		n, err := readBoundedBody(r.Body, body)
+		read = uint64(n)
+		if int64(n) > p.MaxBodyBytes {
+			g.rejectPublic(w, r, 413, "body_too_large", read)
 			return
 		}
-		r.Body = io.NopCloser(bytes.NewReader(b))
-		r.ContentLength = int64(len(b))
+		var timeout net.Error
+		if errors.As(err, &timeout) && timeout.Timeout() {
+			g.rejectPublic(w, r, 408, "body_timeout", read)
+			return
+		}
+		if err != nil && err != io.EOF {
+			g.rejectPublic(w, r, 400, "body_read_error", read)
+			return
+		}
+		if r.ContentLength >= 0 && int64(n) != r.ContentLength {
+			g.rejectPublic(w, r, 400, "body_read_error", read)
+			return
+		}
+		r.Body.Close()
+		_ = controller.SetReadDeadline(time.Time{})
+		r.Body = io.NopCloser(bytes.NewReader(body[:n]))
+		r.ContentLength = int64(n)
 	}
 	r.RemoteAddr = net.JoinHostPort(ip.String(), "0")
-	g.accepted.Add(1)
+	g.metrics.outcome("", read, 0)
 	g.proxy.ServeHTTP(w, r)
 }
 func (g *Gateway) Operator(w http.ResponseWriter, r *http.Request) {
@@ -274,9 +329,7 @@ func (g *Gateway) Operator(w http.ResponseWriter, r *http.Request) {
 		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()
+		state := g.Telemetry()
 		w.Header().Set("Content-Type", "application/json")
 		w.Header().Set("Cache-Control", "no-store")
 		json.NewEncoder(w).Encode(state)
@@ -293,3 +346,25 @@ func (g *Gateway) Operator(w http.ResponseWriter, r *http.Request) {
 	r = r.WithContext(context.WithValue(r.Context(), operatorKey{}, true))
 	g.proxy.ServeHTTP(w, r)
 }
+
+// Preserve malformed/chopped chunked-body errors instead of converting EOF to
+// ErrUnexpectedEOF, which would make a valid short body indistinguishable.
+func readBoundedBody(reader io.Reader, buffer []byte) (int, error) {
+	total, empty := 0, 0
+	for total < len(buffer) {
+		n, err := reader.Read(buffer[total:])
+		total += n
+		if err != nil {
+			return total, err
+		}
+		if n == 0 {
+			empty++
+			if empty >= 100 {
+				return total, io.ErrNoProgress
+			}
+		} else {
+			empty = 0
+		}
+	}
+	return total, nil
+}