@x47base/pocketbase-addon 0.1.0 → 0.2.0

package/hosting/README.md

@@ -0,0 +1,62 @@
+# Hosting — @x47base/pocketbase-addon
+
+Optional named backup targets, a native **Hosting** dashboard and deployment rendering. Included in the [combined npm package](../README.md); no separate hosting package is needed.
+
+## Enable backup policies
+
+From your application directory:
+
+```sh
+npx pocketbase-addon init
+HOSTING_ADDON_CONFIG=./hosting.json PB_SECURITY_MODE=enforce \
+  npx pocketbase-addon serve --http=127.0.0.1:8090 --dir=./pb_data
+```
+
+The initial configuration uses `{"targets":[{"key":"native","kind":"native"}]}`. The native destination follows PocketBase's backup settings. For named local or S3 targets, copy and edit `node_modules/@x47base/pocketbase-addon/hosting/hosting.example.json`. Remove unused targets. Paths must be absolute; local targets must be outside the data directory or under its excluded `backups` directory. Symlink aliases are checked. S3 endpoints must use HTTPS, with bucket, region and credential environment references configured on the server.
+
+Administrators select named targets in **Hosting**; client input cannot select arbitrary endpoints or paths. `hosting_backup_policies` and `hosting_backup_runs` default to superuser-only access. Policies support intervals of 5–43,200 minutes and retention of 1–1,000 snapshots. Schedules run once a minute; missed executions coalesce. Manual execution also advances the next scheduled run. Overlapping backup/restore operations are rejected. Configuration target changes require a restart; policy changes do not.
+
+Named S3 targets require the base encryption hook and refuse plaintext writes. Supply `PB_BACKUP_ENCRYPTION_KEY` securely and enable encryption in **Settings → x47base extensions**. A completed run verifies that the snapshot object exists; it does not prove restoration. Retention deletes only that policy's snapshot prefix after the new backup exists. Interrupted runs become `unknown` on restart. Inspect the destination before retrying.
+
+Backups cover the entire owner database and its local files. They do not include externally stored record files or a separate Vendure/PostgreSQL database. Retrieve alternate-target snapshots securely and use the native backup import/recovery flow on a disposable owner to test recovery. Review restored policies before enabling schedules against production backup destinations.
+
+## Embed in Go
+
+Use the npm-installed source replacement described in [MIGRATION.md](../MIGRATION.md), then register after the base add-on and before `app.Start()`:
+
+```go
+import hosting "github.com/spink-dev/pocketbase-extension/hosting"
+
+config, err := hosting.Load(os.Getenv("HOSTING_ADDON_CONFIG"))
+if err != nil { log.Fatal(err) }
+if _, err := hosting.Register(app, config); err != nil { log.Fatal(err) }
+```
+
+Do not register hosting both manually and through the bundled CLI.
+
+## Render a commerce deployment
+
+This renderer targets a **separate commerce application**. It requires a Vendure integration, custom storefront/domain-guard endpoints and built images. The combined base server does not implement those business endpoints. Generic PocketBase deployments can use the [base deployment guide](../deploy/README.md).
+
+```sh
+cp node_modules/@x47base/pocketbase-addon/hosting/blueprint.example.json blueprint.json
+# Edit image tags, domains, email, storage/ingress classes, issuer and egress CIDRs.
+npx pocketbase-addon hosting -blueprint ./blueprint.json -out ./generated
+```
+
+Rendering creates Compose/Kubernetes JSON, gateway routes, Caddy TLS configuration and a DNS plan. It creates no cloud resources or running services. See [deployment contracts and recovery](docs/DEPLOYMENT.md) for the required files, secrets and image behavior. Build the gateway image from the installed package root with `docker build --target gateway -t your-registry/gateway:your-version node_modules/@x47base/pocketbase-addon`.
+
+Public ingress reaches only the gateway; administration and database origins remain private. Never scale an owner above one writer per data directory. Kubernetes templates require an enforcing CNI, CSI storage supporting `ReadWriteOncePod`, ingress, DNS and a TLS issuer. Provider deployment and restore drills need environment-specific validation.
+
+### Verified domain export and DNS
+
+The separate commerce application must validate domain ownership and enforce live store/domain bindings on the origin. Then:
+
+```sh
+# Supply HOSTING_PB_TOKEN via the environment, never committed configuration.
+node node_modules/@x47base/pocketbase-addon/hosting/scripts/routes.mjs https://management.example.com blueprint.json routed.json
+npx pocketbase-addon hosting -blueprint routed.json -out generated
+node node_modules/@x47base/pocketbase-addon/hosting/scripts/dns.mjs dns.json plan
+```
+
+Start `dns.json` from the packaged `hosting/deploy/dns.example.json` and replace all placeholders. DNS scripts support Cloudflare or Route 53. The explicit `apply` argument makes provider changes; review plans first. Cloudflare uses a named token environment variable; Route 53 uses the AWS CLI credential chain. No credentials are stored in PocketBase. DNS changes and gateway route reloads are separate operations.

package/hosting/backups.go

@@ -0,0 +1,381 @@
+package hosting
+
+import (
+	"context"
+	"embed"
+	"errors"
+	"fmt"
+	"github.com/pocketbase/dbx"
+	"github.com/pocketbase/pocketbase/apis"
+	"github.com/pocketbase/pocketbase/core"
+	"github.com/pocketbase/pocketbase/tools/filesystem"
+	"github.com/pocketbase/pocketbase/tools/hook"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+const PoliciesCollection = "hosting_backup_policies"
+const RunsCollection = "hosting_backup_runs"
+
+//go:embed ui/*
+var assets embed.FS
+
+type targetKey struct{}
+type targetApp struct {
+	core.App
+	target Target
+}
+
+func (a *targetApp) NewBackupsFilesystem() (*filesystem.System, error) {
+	return openTarget(a.App, a.target)
+}
+func openTarget(app core.App, t Target) (*filesystem.System, error) {
+	switch t.Kind {
+	case "native":
+		return app.NewBackupsFilesystem()
+	case "local":
+		if err := validateLocalTarget(app.DataDir(), t.Path); err != nil {
+			return nil, err
+		}
+		if err := os.MkdirAll(t.Path, 0700); err != nil {
+			return nil, err
+		}
+		return filesystem.NewLocal(t.Path)
+	case "s3":
+		if os.Getenv(t.AccessKeyEnv) == "" || os.Getenv(t.SecretEnv) == "" {
+			return nil, errors.New("backup credentials unavailable")
+		}
+		f, err := filesystem.NewS3(t.Bucket, t.Region, t.Endpoint, os.Getenv(t.AccessKeyEnv), os.Getenv(t.SecretEnv), t.PathStyle)
+		if err != nil {
+			return nil, err
+		}
+		f.OnNewWriter().BindFunc(func(e *filesystem.NewWriterEvent) error {
+			if !strings.HasSuffix(e.FileKey, ".zip.age") {
+				return errors.New("remote backups require the base add-on's encrypted backup mode")
+			}
+			return e.Next()
+		})
+		return f, nil
+	}
+	return nil, errors.New("unknown target")
+}
+
+type Service struct {
+	owner    context.Context
+	app      core.App
+	config   Config
+	runMu    sync.Mutex
+	backupMu sync.Mutex
+}
+
+func (s *Service) target(key string) (Target, error) {
+	for _, t := range s.config.Targets {
+		if t.Key == key {
+			return t, nil
+		}
+	}
+	return Target{}, errors.New("unknown target")
+}
+func ensureCollections(app core.App) error {
+	return app.RunInTransaction(func(tx core.App) error {
+		if _, err := tx.FindCollectionByNameOrId(PoliciesCollection); err != nil {
+			c := core.NewBaseCollection(PoliciesCollection)
+			c.Fields.Add(&core.TextField{Name: "name", Required: true, Max: 128}, &core.TextField{Name: "target", Required: true, Max: 64}, &core.BoolField{Name: "enabled"}, &core.NumberField{Name: "intervalMinutes", Required: true, OnlyInt: true, Min: floatPointer(5), Max: floatPointer(43200)}, &core.NumberField{Name: "keep", Required: true, OnlyInt: true, Min: floatPointer(1), Max: floatPointer(1000)}, &core.DateField{Name: "nextRun"}, &core.TextField{Name: "lastStatus", Max: 32})
+			if err = tx.Save(c); err != nil {
+				return err
+			}
+		}
+		if _, err := tx.FindCollectionByNameOrId(RunsCollection); err != nil {
+			p, err := tx.FindCollectionByNameOrId(PoliciesCollection)
+			if err != nil {
+				return err
+			}
+			c := core.NewBaseCollection(RunsCollection)
+			c.Fields.Add(&core.RelationField{Name: "policy", Required: true, CollectionId: p.Id, MaxSelect: 1}, &core.TextField{Name: "target", Required: true, Max: 64}, &core.TextField{Name: "status", Required: true, Max: 32}, &core.TextField{Name: "key", Max: 256}, &core.TextField{Name: "message", Max: 1024}, &core.AutodateField{Name: "created", OnCreate: true}, &core.DateField{Name: "finished"})
+			c.AddIndex("idx_hosting_backup_runs", false, "policy, created", "")
+			return tx.Save(c)
+		}
+		return nil
+	})
+}
+func floatPointer(v float64) *float64 { return &v }
+func Register(app core.App, c Config) (*Service, error) {
+	if err := c.Validate(); err != nil {
+		return nil, err
+	}
+	s := &Service{app: app, config: c}
+	ownerContext, stop := context.WithCancel(context.Background())
+	s.owner = ownerContext
+	app.OnTerminate().BindFunc(func(e *core.TerminateEvent) error { stop(); s.runMu.Lock(); defer s.runMu.Unlock(); return e.Next() })
+	setup := func() error {
+		for _, target := range c.Targets {
+			if target.Kind == "local" {
+				if err := validateLocalTarget(app.DataDir(), target.Path); err != nil {
+					return err
+				}
+			}
+		}
+		if err := ensureCollections(app); err != nil {
+			return err
+		}
+		rows, err := app.FindRecordsByFilter(RunsCollection, "status='running'", "", 0, 0)
+		if err != nil {
+			return err
+		}
+		for _, r := range rows {
+			r.Set("status", "unknown")
+			r.Set("message", "Owner restarted; inspect the destination before retrying")
+			if err = app.Save(r); err != nil {
+				return err
+			}
+		}
+		return nil
+	}
+	if app.IsBootstrapped() {
+		if err := setup(); err != nil {
+			return nil, err
+		}
+	}
+	app.OnBootstrap().BindFunc(func(e *core.BootstrapEvent) error {
+		if err := e.Next(); err != nil {
+			return err
+		}
+		return setup()
+	})
+	app.OnBackupCreate().Bind(&hook.Handler[*core.BackupEvent]{Priority: -1000, Func: func(e *core.BackupEvent) error {
+		if !s.backupMu.TryLock() {
+			return errors.New("backup operation already running")
+		}
+		defer s.backupMu.Unlock()
+		if t, ok := e.Context.Value(targetKey{}).(Target); ok {
+			original := e.App
+			e.App = &targetApp{App: original, target: t}
+			defer func() { e.App = original }()
+		}
+		return e.Next()
+	}})
+	app.OnBackupRestore().Bind(&hook.Handler[*core.BackupEvent]{Priority: -1000, Func: func(e *core.BackupEvent) error {
+		if !s.backupMu.TryLock() {
+			return errors.New("backup operation already running")
+		}
+		defer s.backupMu.Unlock()
+		return e.Next()
+	}})
+	app.OnServe().BindFunc(func(e *core.ServeEvent) error {
+		bundle, err := fs.Sub(assets, "ui")
+		if err != nil {
+			return err
+		}
+		e.UIExtensions = append(e.UIExtensions, core.UIExtension{Name: "x47-hosting", FS: bundle})
+		g := e.Router.Group("/api/hosting").Bind(apis.RequireSuperuserAuth(), apis.BodyLimit(4096))
+		g.BindFunc(func(e *core.RequestEvent) error {
+			e.Response.Header().Set("Cache-Control", "no-store")
+			return e.Next()
+		})
+		g.GET("/backups", func(e *core.RequestEvent) error {
+			policies, err := app.FindRecordsByFilter(PoliciesCollection, "", "name", 1000, 0)
+			if err != nil {
+				return err
+			}
+			runs, err := app.FindRecordsByFilter(RunsCollection, "", "-created", 50, 0)
+			if err != nil {
+				return err
+			}
+			targets := []map[string]string{}
+			for _, t := range c.Targets {
+				targets = append(targets, map[string]string{"key": t.Key, "kind": t.Kind})
+			}
+			return e.JSON(200, map[string]any{"policies": policies, "runs": runs, "targets": targets})
+		})
+		save := func(e *core.RequestEvent) error {
+			var input struct {
+				Name, Target          string
+				Enabled               bool
+				IntervalMinutes, Keep int
+			}
+			if e.BindBody(&input) != nil {
+				return e.BadRequestError("Invalid policy", nil)
+			}
+			if _, err := s.target(input.Target); err != nil {
+				return e.BadRequestError("Unknown target", nil)
+			}
+			var record *core.Record
+			var err error
+			if id := e.Request.PathValue("id"); id != "" {
+				record, err = app.FindRecordById(PoliciesCollection, id)
+			} else {
+				var coll *core.Collection
+				coll, err = app.FindCollectionByNameOrId(PoliciesCollection)
+				if err == nil {
+					record = core.NewRecord(coll)
+				}
+			}
+			if err != nil {
+				return e.NotFoundError("Policy not found", nil)
+			}
+			record.Set("name", input.Name)
+			record.Set("target", input.Target)
+			record.Set("enabled", input.Enabled)
+			record.Set("intervalMinutes", input.IntervalMinutes)
+			record.Set("keep", input.Keep)
+			record.Set("nextRun", time.Now().Add(time.Duration(input.IntervalMinutes)*time.Minute))
+			if err = app.Save(record); err != nil {
+				return e.BadRequestError("Invalid policy", err)
+			}
+			return e.JSON(200, record)
+		}
+		g.POST("/backups/policies", save)
+		g.PUT("/backups/policies/{id}", save)
+		g.POST("/backups/policies/{id}/run", func(e *core.RequestEvent) error {
+			run, err := s.Run(e.Request.Context(), e.Request.PathValue("id"))
+			if err != nil {
+				return e.JSON(409, map[string]any{"message": err.Error(), "run": run})
+			}
+			return e.JSON(200, run)
+		})
+		app.Cron().MustAdd("hosting-backup-policies", "* * * * *", func() { s.Tick(ownerContext) })
+		return e.Next()
+	})
+	return s, nil
+}
+func (s *Service) Tick(ctx context.Context) {
+	rows, err := s.app.FindRecordsByFilter(PoliciesCollection, "enabled=true && nextRun<={:now}", "nextRun", 100, 0, dbx.Params{"now": time.Now().UTC().Format("2006-01-02 15:04:05.000Z")})
+	if err != nil {
+		return
+	}
+	for _, p := range rows {
+		if ctx.Err() != nil {
+			return
+		}
+		_, _ = s.run(ctx, p.Id, true)
+	}
+}
+func (s *Service) Run(ctx context.Context, id string) (*core.Record, error) {
+	return s.run(ctx, id, false)
+}
+func (s *Service) run(ctx context.Context, id string, scheduled bool) (*core.Record, error) {
+	if !s.runMu.TryLock() {
+		return nil, errors.New("a scheduled backup is already running")
+	}
+	defer s.runMu.Unlock()
+	if s.owner.Err() != nil {
+		return nil, errors.New("owner is stopping")
+	}
+	p, err := s.app.FindRecordById(PoliciesCollection, id)
+	if err != nil {
+		return nil, err
+	}
+	if scheduled && (!p.GetBool("enabled") || p.GetDateTime("nextRun").Time().After(time.Now())) {
+		return nil, nil
+	}
+	target, err := s.target(p.GetString("target"))
+	if err != nil {
+		return nil, err
+	}
+	c, err := s.app.FindCollectionByNameOrId(RunsCollection)
+	if err != nil {
+		return nil, err
+	}
+	run := core.NewRecord(c)
+	run.Set("policy", id)
+	run.Set("target", target.Key)
+	run.Set("status", "running")
+	prefix := "hosting_" + id + "_"
+	name := prefix + time.Now().UTC().Format("20060102T150405.000000000") + ".zip"
+	run.Set("key", name)
+	err = s.app.RunInTransaction(func(tx core.App) error {
+		current, err := tx.FindRecordById(PoliciesCollection, id)
+		if err != nil {
+			return err
+		}
+		current.Set("nextRun", time.Now().Add(time.Duration(current.GetInt("intervalMinutes"))*time.Minute))
+		current.Set("lastStatus", "running")
+		if err := tx.Save(current); err != nil {
+			return err
+		}
+		return tx.Save(run)
+	})
+	if err != nil {
+		return nil, err
+	}
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Minute)
+	defer cancel()
+	stopOwner := context.AfterFunc(s.owner, cancel)
+	defer stopOwner()
+	err = s.app.CreateBackup(context.WithValue(ctx, targetKey{}, target), name)
+	if err == nil {
+		err = s.retain(ctx, target, prefix, name, p.GetInt("keep"), run)
+	}
+	status, message := "completed", ""
+	if err != nil {
+		status = "failed"
+		message = "Backup or retention failed; inspect owner logs and destination before retrying"
+		s.app.Logger().Error("hosting backup failed", "policy", id, "error", err)
+	}
+	run.Set("status", status)
+	run.Set("message", message)
+	run.Set("finished", time.Now())
+	saveErr := s.app.RunInTransaction(func(tx core.App) error {
+		if err := tx.Save(run); err != nil {
+			return err
+		}
+		current, err := tx.FindRecordById(PoliciesCollection, id)
+		if err != nil {
+			return err
+		}
+		current.Set("lastStatus", status)
+		return tx.Save(current)
+	})
+	if saveErr != nil {
+		return run, errors.New("backup outcome persistence failed; inspect destination")
+	}
+	if err != nil {
+		return run, errors.New(message)
+	}
+	return run, nil
+}
+func (s *Service) retain(ctx context.Context, target Target, prefix, name string, keep int, run *core.Record) error {
+	f, err := openTarget(s.app, target)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	f.SetContext(ctx)
+	found := false
+	for _, key := range []string{name + ".age", name} {
+		found, err = f.Exists(key)
+		if err != nil {
+			return err
+		}
+		if found {
+			run.Set("key", key)
+			break
+		}
+	}
+	if !found {
+		return errors.New("snapshot completion could not be verified")
+	}
+	objects, err := f.List(prefix)
+	if err != nil {
+		return err
+	}
+	sort.Slice(objects, func(i, j int) bool { return objects[i].Key > objects[j].Key })
+	owned := 0
+	for _, o := range objects {
+		if o.IsDir || !strings.HasPrefix(o.Key, prefix) || filepath.Base(o.Key) != o.Key || !(strings.HasSuffix(o.Key, ".zip") || strings.HasSuffix(o.Key, ".zip.age")) {
+			continue
+		}
+		owned++
+		if owned > keep {
+			if err = f.Delete(o.Key); err != nil {
+				return fmt.Errorf("backup saved; retention incomplete: %w", err)
+			}
+		}
+	}
+	return nil
+}

package/hosting/backups_test.go

@@ -0,0 +1,81 @@
+package hosting
+
+import (
+	"context"
+	"github.com/pocketbase/pocketbase/core"
+	"github.com/pocketbase/pocketbase/tests"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestDynamicBackupsRetainOnlyOwnedSnapshots(t *testing.T) {
+	app, err := tests.NewTestApp()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer app.Cleanup()
+	dir := t.TempDir()
+	s, err := Register(app, Config{Targets: []Target{{Key: "local", Kind: "local", Path: dir}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	c, _ := app.FindCollectionByNameOrId(PoliciesCollection)
+	p := core.NewRecord(c)
+	p.Set("name", "Hourly")
+	p.Set("target", "local")
+	p.Set("intervalMinutes", 60)
+	p.Set("keep", 1)
+	if err = app.Save(p); err != nil {
+		t.Fatal(err)
+	}
+	os.WriteFile(filepath.Join(dir, "unrelated.zip"), []byte("preserve"), 0600)
+	if run, err := s.run(context.Background(), p.Id, true); err != nil || run != nil {
+		t.Fatal("disabled scheduled policy ran", err)
+	}
+	first, err := s.Run(context.Background(), p.Id)
+	if err != nil {
+		t.Fatal(err)
+	}
+	second, err := s.Run(context.Background(), p.Id)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first.GetString("status") != "completed" || second.GetString("status") != "completed" {
+		t.Fatal("backup failed")
+	}
+	if _, err = os.Stat(filepath.Join(dir, first.GetString("key"))); !os.IsNotExist(err) {
+		t.Fatal("retention failed")
+	}
+	if _, err = os.Stat(filepath.Join(dir, second.GetString("key"))); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = os.Stat(filepath.Join(dir, "unrelated.zip")); err != nil {
+		t.Fatal("deleted unrelated backup")
+	}
+	policies, _ := app.FindCollectionByNameOrId(PoliciesCollection)
+	if policies.ListRule != nil || policies.CreateRule != nil {
+		t.Fatal("public policy management")
+	}
+}
+func TestBackupConfigurationRejectsUnsafeTargets(t *testing.T) {
+	for _, c := range []Config{{Targets: []Target{{Key: "local", Kind: "local", Path: "relative"}}}, {Targets: []Target{{Key: "s3", Kind: "s3", Endpoint: "http://storage", Bucket: "b", AccessKeyEnv: "ACCESS", SecretEnv: "SECRET"}}}, {Targets: []Target{{Key: "local", Kind: "native"}, {Key: "local", Kind: "native"}}}} {
+		if c.Validate() == nil {
+			t.Fatal("unsafe target accepted")
+		}
+	}
+}
+func TestRemoteBackupRejectsUnencryptedWrites(t *testing.T) {
+	t.Setenv("BACKUP_ACCESS", "test")
+	t.Setenv("BACKUP_SECRET", "test")
+	f, err := openTarget(nil, Target{Key: "remote", Kind: "s3", Endpoint: "https://storage.example.invalid", Bucket: "backups", Region: "us-east-1", AccessKeyEnv: "BACKUP_ACCESS", SecretEnv: "BACKUP_SECRET"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	err = f.Upload([]byte("plaintext"), "hosting_test.zip")
+	if err == nil || !strings.Contains(err.Error(), "encrypted") {
+		t.Fatal("plaintext upload permitted", err)
+	}
+}

package/hosting/blueprint.example.json

@@ -0,0 +1,14 @@
+{
+ "name":"commerce",
+ "pocketbaseImage":"registry.example.com/commerce-owner:1.0.0",
+ "vendureImage":"registry.example.com/commerce-vendure:1.0.0",
+ "gatewayImage":"registry.example.com/commerce-gateway:1.0.0",
+ "postgresImage":"postgres:18.6-alpine",
+ "tlsImage":"caddy:2.10.2-alpine",
+ "email":"operations@example.com",
+ "domains":[{"host":"team.example.com","store":"team-autumn"}],
+ "storageClass":"standard",
+ "ingressClass":"nginx",
+ "issuer":"letsencrypt-production",
+ "egressCIDRs":[]
+}