feat: complete the beta admin and runtime config stack

.gitignore

@@ -51,3 +51,6 @@ report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 todo.md
 .dex-plans/
 .dex/
+
+# Bench load-generator binary built for the container runs
+bench/.bin/

Dockerfile

@@ -11,8 +11,15 @@ COPY api ./api
 COPY sdk ./sdk
 RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /out/filegate ./cmd/filegate
 
+# Distroless has no shell, so the runtime directories are staged in the build
+# image and copied in with the right ownership. Without them a container that
+# configures nothing cannot create its default mount and refuses to start.
+RUN mkdir -p /stage/var/lib/filegate/data /stage/var/lib/filegate/index /stage/var/lib/filegate/config \
+    && chown -R 65532:65532 /stage/var/lib/filegate
+
 FROM gcr.io/distroless/static-debian12:nonroot
 WORKDIR /app
+COPY --from=build --chown=65532:65532 /stage/var/lib/filegate /var/lib/filegate
 COPY --from=build /out/filegate /app/filegate
 EXPOSE 8080/tcp
 ENTRYPOINT ["/app/filegate"]

Makefile

@@ -1,4 +1,7 @@
-.PHONY: test test-race test-short test-detector-linux test-detector-soak test-detector-chaos test-detector-btrfs-real test-detector-btrfs-real-docker test-versioning-btrfs-real-docker test-versioning-soak fuzz-smoke bench-go bench-http bench-compose check
+.PHONY: docs-config test test-race test-short test-detector-linux test-detector-soak test-detector-chaos test-detector-btrfs-real test-detector-btrfs-real-docker test-versioning-btrfs-real-docker test-versioning-soak fuzz-smoke bench-go bench-http bench-compose bench-tree check
+
+docs-config:
+	go run ./cmd/filegate config schema --format markdown > docs-site/docs/en/reference/config.md
 
 test:
 	go test ./...
@@ -45,4 +48,7 @@ bench-http:
 bench-compose:
 	./bench/scripts/run-http-bench-compose.sh
 
+bench-tree:
+	./bench/scripts/run-tree-bench.sh
+
 check: test test-race test-detector-linux bench-go

README.md

@@ -115,7 +115,27 @@ curl -fsS -H 'Authorization: Bearer dev-token' \
 
 ## Configuration
 
-Filegate reads config from `--config`, `FILEGATE_CONFIG`, or default candidates such as `/etc/filegate/conf.yaml`. Environment variables use `FILEGATE_` plus the config path, for example `FILEGATE_SERVER_LISTEN`.
+Filegate uses a versioned desired-state manifest for repository-managed configuration. Plan and apply use the same bearer-authenticated HTTP API locally and remotely:
+
+```yaml
+# filegate.manifest.yaml
+version: 1
+config:
+  server:
+    public_url: https://files.example.com
+    access_log_enabled: true
+  upload:
+    max_upload_bytes: 1073741824
+```
+
+```bash
+fg config plan -f filegate.manifest.yaml --host https://files.example.com --token-file /run/secrets/filegate-token
+fg config apply -f filegate.manifest.yaml --host https://files.example.com --token-file /run/secrets/filegate-token
+```
+
+The manifest is a complete replacement: removing a key removes it from managed state. Runtime keys apply immediately; static keys are stored as desired state until restart. The admin Settings page is a read-only view of effective and desired configuration.
+
+Bootstrap settings and secrets still come from `--config`, `FILEGATE_CONFIG`, environment, or default candidates such as `/etc/filegate/conf.yaml`. Environment variables use `FILEGATE_` plus the config path, for example `FILEGATE_SERVER_LISTEN`.
 
 Use the config CLI for offline edits:
 
@@ -128,13 +148,12 @@ sudo fg config mount add --config /etc/filegate/conf.yaml /srv/filegate/photos
 
 sudo fg config set --config /etc/filegate/conf.yaml \
   --auth-bearer-token '<strong-token>' \
-  --server-listen ':8080' \
-  --server-public-url 'https://files.example.com'
+  --server-listen ':8080'
 ```
 
 Mutating `fg config` commands require explicit `--config`, create a timestamped backup by default, validate the resulting YAML before replacing it, and print a restart reminder. They do not hot-reload a running daemon.
 
-`fg serve` accepts the same config-value flags as one-shot runtime overrides:
+`fg serve` accepts the same config-value flags as one-shot startup overrides:
 
 ```bash
 fg serve --config ./conf.yaml --server-listen ':9090'
@@ -411,7 +430,7 @@ The default ring buffer retains 500 records. Set `activity.ring_buffer_size` to
 ## Limits
 
 - Single-node service; no replication.
-- Config changes are offline; restart after editing config.
+- Bootstrap config changes are offline. Manifest runtime keys apply immediately; static keys take effect after restart.
 - REST uses one bearer token. S3 supports multiple keys and per-key bucket allowlists.
 - REST has no request rate limiting. S3 supports per-key request limits.
 - `X-Forwarded-For` is trusted only from configured `server.trusted_proxies`.

adapter/http/config.go

@@ -0,0 +1,73 @@
+package httpadapter
+
+import (
+	"errors"
+	"net/http"
+
+	apiv1 "github.com/valentinkolb/filegate/api/v1"
+	"github.com/valentinkolb/filegate/domain"
+	"github.com/valentinkolb/filegate/infra/activity"
+)
+
+// ConfigService is the declarative configuration surface the router exposes.
+type ConfigService interface {
+	Schema() []apiv1.ConfigKeySchema
+	Values() apiv1.ConfigValuesResponse
+	PlanManifest(values map[string]any) (apiv1.ConfigManifestPlanResponse, error)
+	ApplyManifest(values map[string]any, expectedRevision, actor string) (apiv1.ConfigManifestApplyResponse, error)
+}
+
+type configHandlers struct {
+	svc ConfigService
+}
+
+func (h configHandlers) handleSchema(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, apiv1.ConfigSchemaResponse{Keys: h.svc.Schema()})
+}
+
+func (h configHandlers) handleValues(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, h.svc.Values())
+}
+
+func (h configHandlers) handlePlan(w http.ResponseWriter, r *http.Request) {
+	var req apiv1.ConfigManifestPlanRequest
+	if !decodeStrict(w, r, &req) {
+		return
+	}
+	if req.Values == nil {
+		req.Values = map[string]any{}
+	}
+	plan, err := h.svc.PlanManifest(req.Values)
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, plan)
+}
+
+func (h configHandlers) handleApply(w http.ResponseWriter, r *http.Request) {
+	var req apiv1.ConfigManifestApplyRequest
+	if !decodeStrict(w, r, &req) {
+		return
+	}
+	if req.Values == nil {
+		req.Values = map[string]any{}
+	}
+	applied, err := h.svc.ApplyManifest(req.Values, req.ExpectedRevision, configActor(r))
+	if err != nil {
+		status := http.StatusBadRequest
+		if errors.Is(err, domain.ErrConflict) {
+			status = http.StatusConflict
+		}
+		writeErr(w, status, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, applied)
+}
+
+func configActor(r *http.Request) string {
+	if label := activity.CleanActorLabel(r.Header.Get("X-Filegate-Actor")); label != "" {
+		return label
+	}
+	return "bearer-token"
+}

adapter/http/config_test.go

@@ -0,0 +1,99 @@
+package httpadapter
+
+import (
+	"bytes"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	apiv1 "github.com/valentinkolb/filegate/api/v1"
+	"github.com/valentinkolb/filegate/domain"
+)
+
+type configServiceStub struct {
+	planned  map[string]any
+	applied  map[string]any
+	expected string
+	actor    string
+	applyErr error
+}
+
+func (s *configServiceStub) Schema() []apiv1.ConfigKeySchema { return nil }
+func (s *configServiceStub) Values() apiv1.ConfigValuesResponse {
+	return apiv1.ConfigValuesResponse{}
+}
+func (s *configServiceStub) PlanManifest(values map[string]any) (apiv1.ConfigManifestPlanResponse, error) {
+	s.planned = values
+	return apiv1.ConfigManifestPlanResponse{CurrentRevision: "old", ProposedRevision: "new"}, nil
+}
+func (s *configServiceStub) ApplyManifest(values map[string]any, expectedRevision, actor string) (apiv1.ConfigManifestApplyResponse, error) {
+	s.applied = values
+	s.expected = expectedRevision
+	s.actor = actor
+	return apiv1.ConfigManifestApplyResponse{}, s.applyErr
+}
+
+func TestConfigPlanAcceptsCompleteEmptyManifest(t *testing.T) {
+	stub := &configServiceStub{}
+	handler := configHandlers{svc: stub}
+	req := httptest.NewRequest(http.MethodPost, "/v1/config/plan", bytes.NewBufferString(`{"values":{}}`))
+	out := httptest.NewRecorder()
+
+	handler.handlePlan(out, req)
+
+	if out.Code != http.StatusOK {
+		t.Fatalf("status = %d, body=%s", out.Code, out.Body.String())
+	}
+	if stub.planned == nil || len(stub.planned) != 0 {
+		t.Errorf("planned = %#v, want empty non-nil map", stub.planned)
+	}
+}
+
+func TestConfigApplyPassesRevisionAndSanitizedActor(t *testing.T) {
+	stub := &configServiceStub{}
+	handler := configHandlers{svc: stub}
+	req := httptest.NewRequest(http.MethodPost, "/v1/config/apply", bytes.NewBufferString(
+		`{"values":{"upload.expiry":"2h"},"expectedRevision":"old"}`,
+	))
+	req.Header.Set("X-Filegate-Actor", "  Alice\nAdmin  ")
+	out := httptest.NewRecorder()
+
+	handler.handleApply(out, req)
+
+	if out.Code != http.StatusOK {
+		t.Fatalf("status = %d, body=%s", out.Code, out.Body.String())
+	}
+	if stub.expected != "old" || stub.actor != "Alice Admin" {
+		t.Errorf("expected=%q actor=%q", stub.expected, stub.actor)
+	}
+}
+
+func TestConfigApplyMapsStaleRevisionToConflict(t *testing.T) {
+	stub := &configServiceStub{applyErr: fmt.Errorf("%w: stale manifest", domain.ErrConflict)}
+	handler := configHandlers{svc: stub}
+	req := httptest.NewRequest(http.MethodPost, "/v1/config/apply", bytes.NewBufferString(
+		`{"values":{},"expectedRevision":"old"}`,
+	))
+	out := httptest.NewRecorder()
+
+	handler.handleApply(out, req)
+
+	if out.Code != http.StatusConflict {
+		t.Fatalf("status = %d, want 409; body=%s", out.Code, out.Body.String())
+	}
+}
+
+func TestConfigManifestEndpointsRejectUnknownEnvelopeFields(t *testing.T) {
+	handler := configHandlers{svc: &configServiceStub{}}
+	req := httptest.NewRequest(http.MethodPost, "/v1/config/plan", bytes.NewBufferString(
+		`{"values":{},"changes":{}}`,
+	))
+	out := httptest.NewRecorder()
+
+	handler.handlePlan(out, req)
+
+	if out.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want 400", out.Code)
+	}
+}

adapter/http/direct_download.go

@@ -6,7 +6,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
-	"net/netip"
 	"strings"
 	"time"
 
@@ -20,10 +19,9 @@ const (
 )
 
 type directDownloadManager struct {
-	svc       *domain.Service
-	secret    []byte
-	publicURL string
-	trusted   []netip.Prefix
+	svc    *domain.Service
+	secret []byte
+	live   liveConfig
 }
 
 type directDownloadToken struct {
@@ -38,12 +36,11 @@ type directDownloadToken struct {
 	Nonce     string `json:"nonce"`
 }
 
-func newDirectDownloadManager(svc *domain.Service, bearerToken, publicURL string, trusted []netip.Prefix) *directDownloadManager {
+func newDirectDownloadManager(svc *domain.Service, bearerToken string, live liveConfig) *directDownloadManager {
 	return &directDownloadManager{
-		svc:       svc,
-		secret:    []byte(strings.TrimSpace(bearerToken)),
-		publicURL: strings.TrimRight(strings.TrimSpace(publicURL), "/"),
-		trusted:   append([]netip.Prefix(nil), trusted...),
+		svc:    svc,
+		secret: []byte(strings.TrimSpace(bearerToken)),
+		live:   live,
 	}
 }
 
@@ -92,7 +89,7 @@ func (m *directDownloadManager) handleCreate(w http.ResponseWriter, r *http.Requ
 		writeErr(w, http.StatusInternalServerError, "failed to create download url")
 		return
 	}
-	baseURL, err := directURLBaseForRequest(m.publicURL, m.trusted, r)
+	baseURL, err := directURLBaseForRequest(m.live.publicURL(), m.live.trustedProxies(), r)
 	if err != nil {
 		writeErr(w, http.StatusBadRequest, "public download URL unavailable")
 		return

adapter/http/direct_upload.go

@@ -25,11 +25,9 @@ const (
 )
 
 type directUploadManager struct {
-	svc            *domain.Service
-	secret         []byte
-	publicURL      string
-	trusted        []netip.Prefix
-	maxUploadBytes int64
+	svc    *domain.Service
+	secret []byte
+	live   liveConfig
 }
 
 type directUploadToken struct {
@@ -42,16 +40,11 @@ type directUploadToken struct {
 	Nonce       string `json:"nonce"`
 }
 
-func newDirectUploadManager(svc *domain.Service, bearerToken, publicURL string, maxUploadBytes int64, trusted []netip.Prefix) *directUploadManager {
-	if maxUploadBytes <= 0 {
-		maxUploadBytes = int64(500 * 1024 * 1024)
-	}
+func newDirectUploadManager(svc *domain.Service, bearerToken string, live liveConfig) *directUploadManager {
 	return &directUploadManager{
-		svc:            svc,
-		secret:         []byte(strings.TrimSpace(bearerToken)),
-		publicURL:      strings.TrimRight(strings.TrimSpace(publicURL), "/"),
-		trusted:        append([]netip.Prefix(nil), trusted...),
-		maxUploadBytes: maxUploadBytes,
+		svc:    svc,
+		secret: []byte(strings.TrimSpace(bearerToken)),
+		live:   live,
 	}
 }
 
@@ -77,11 +70,12 @@ func (m *directUploadManager) handleCreate(w http.ResponseWriter, r *http.Reques
 		return
 	}
 
+	maxUploadBytes := m.live.maxUploadBytes()
 	maxBytes := body.MaxBytes
 	if maxBytes <= 0 {
-		maxBytes = m.maxUploadBytes
+		maxBytes = maxUploadBytes
 	}
-	if maxBytes <= 0 || maxBytes > m.maxUploadBytes {
+	if maxBytes <= 0 || maxBytes > maxUploadBytes {
 		writeErr(w, http.StatusBadRequest, "maxBytes exceeds upload.max_upload_bytes")
 		return
 	}
@@ -109,7 +103,7 @@ func (m *directUploadManager) handleCreate(w http.ResponseWriter, r *http.Reques
 		writeErr(w, http.StatusInternalServerError, "failed to create upload url")
 		return
 	}
-	baseURL, err := directURLBaseForRequest(m.publicURL, m.trusted, r)
+	baseURL, err := directURLBaseForRequest(m.live.publicURL(), m.live.trustedProxies(), r)
 	if err != nil {
 		writeErr(w, http.StatusBadRequest, "public upload URL unavailable")
 		return

adapter/http/direct_upload_linux_test.go

@@ -171,7 +171,7 @@ func TestDirectUploadRejectsExpiredToken(t *testing.T) {
 	defer cleanup()
 
 	root := svc.ListRoot()[0]
-	direct := newDirectUploadManager(svc, "test-token", "", 1024, nil)
+	direct := newDirectUploadManager(svc, "test-token", newLiveConfig(RouterOptions{MaxUploadBytes: 1024}))
 	token, err := direct.sign(directUploadToken{
 		Version:    1,
 		Path:       root.Name + "/expired.txt",