@x47base/pocketbase-addon 0.1.0

package/jsvm/pool.go

@@ -0,0 +1,73 @@
+package jsvm
+
+import (
+	"sync"
+
+	"github.com/dop251/goja"
+)
+
+type poolItem struct {
+	mux  sync.Mutex
+	busy bool
+	vm   *goja.Runtime
+}
+
+type vmsPool struct {
+	mux     sync.RWMutex
+	factory func() *goja.Runtime
+	items   []*poolItem
+}
+
+// newPool creates a new pool with pre-warmed vms generated from the specified factory.
+func newPool(size int, factory func() *goja.Runtime) *vmsPool {
+	pool := &vmsPool{
+		factory: factory,
+		items:   make([]*poolItem, size),
+	}
+
+	for i := 0; i < size; i++ {
+		vm := pool.factory()
+		pool.items[i] = &poolItem{vm: vm}
+	}
+
+	return pool
+}
+
+// run executes "call" with a vm created from the pool
+// (either from the buffer or a new one if all buffered vms are busy)
+func (p *vmsPool) run(call func(vm *goja.Runtime) error) error {
+	p.mux.RLock()
+
+	// try to find a free item
+	var freeItem *poolItem
+	for _, item := range p.items {
+		item.mux.Lock()
+		if item.busy {
+			item.mux.Unlock()
+			continue
+		}
+		item.busy = true
+		item.mux.Unlock()
+		freeItem = item
+		break
+	}
+
+	p.mux.RUnlock()
+
+	// create a new one-off item if of all of the pool items are currently busy
+	//
+	// note: if turned out not efficient we may change this in the future
+	// by adding the created item in the pool with some timer for removal
+	if freeItem == nil {
+		return call(p.factory())
+	}
+
+	execErr := call(freeItem.vm)
+
+	// "free" the vm
+	freeItem.mux.Lock()
+	freeItem.busy = false
+	freeItem.mux.Unlock()
+
+	return execErr
+}

package/jsvm/program_source_test.go

@@ -0,0 +1,24 @@
+package jsvm
+
+import (
+	"errors"
+	"github.com/dop251/goja"
+	"testing"
+)
+
+func TestProgramSource(t *testing.T) {
+	count := 0
+	p := &plugin{config: Config{ProgramSource: func(name, source string) (*goja.Program, error) { count++; return goja.Compile(name, source, false) }}}
+	v, err := p.runScript(goja.New(), "test.js", "2+3")
+	if err != nil || v.ToInteger() != 5 || count != 1 {
+		t.Fatalf("%v %v %d", v, err, count)
+	}
+	p.config.ProgramSource = func(string, string) (*goja.Program, error) { return nil, errors.New("compile failed") }
+	if _, err = p.runScript(goja.New(), "x", ""); err == nil {
+		t.Fatal("missing compile error")
+	}
+	p.config.ProgramSource = func(string, string) (*goja.Program, error) { return nil, nil }
+	if _, err = p.runScript(goja.New(), "x", ""); err == nil {
+		t.Fatal("nil program accepted")
+	}
+}

package/loadtest/loadtest.go

@@ -0,0 +1,202 @@
+package loadtest
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+type Config struct {
+	NormalEvery int
+	Target      string
+	Rate        int
+	Clients     int
+	Duration    time.Duration
+	MaxRequests int
+}
+type Report struct {
+	CanarySent      uint64        `json:"canarySent"`
+	CanarySucceeded uint64        `json:"canarySucceeded"`
+	Offered         uint64        `json:"offered"`
+	Interrupted     bool          `json:"interrupted"`
+	Sent            uint64        `json:"sent"`
+	Completed       uint64        `json:"completed"`
+	Errors          uint64        `json:"errors"`
+	RateLimited     uint64        `json:"rateLimited"`
+	Unavailable     uint64        `json:"unavailable"`
+	Dropped         uint64        `json:"dropped"`
+	StatusClasses   [6]uint64     `json:"statusClasses"`
+	LatencyBuckets  [7]uint64     `json:"latencyBuckets"`
+	Elapsed         time.Duration `json:"elapsedNanoseconds"`
+}
+
+func (c Config) validate() (*url.URL, error) {
+	u, err := url.Parse(c.Target)
+	if err != nil || u.Scheme != "http" || u.User != nil || u.Fragment != "" || u.RawQuery != "" {
+		return nil, errors.New("target must be an HTTP loopback URL without credentials, query, or fragment")
+	}
+	ip, err := netip.ParseAddr(u.Hostname())
+	if err != nil || !ip.IsLoopback() || ip.Zone() != "" {
+		return nil, errors.New("target must use a literal loopback IP")
+	}
+	if u.Path != "/api/health" && u.Path != "/api/realtime" && u.Path != "/api/collections/pb_sim_records/records" {
+		return nil, errors.New("supported read-only targets are health, realtime and the pb_sim_records fixture")
+	}
+	if c.NormalEvery < 0 || c.NormalEvery == 1 || c.NormalEvery > 100 {
+		return nil, errors.New("normalEvery must be zero or 2 to 100")
+	}
+	if c.Rate < 1 || c.Rate > 10000 || c.Clients < 1 || c.Clients > 512 || c.Duration < time.Millisecond || c.Duration > 10*time.Minute || c.MaxRequests < 1 || c.MaxRequests > 1000000 {
+		return nil, errors.New("limits: 1..10000 requests/s, 1..512 clients, up to 10 minutes and 1000000 requests")
+	}
+	return u, nil
+}
+func Validate(c Config) error { _, err := c.validate(); return err }
+
+func Run(ctx context.Context, c Config) (Report, error) {
+	callerCtx := ctx
+	u, err := c.validate()
+	if err != nil {
+		return Report{}, err
+	}
+	dialer := &net.Dialer{Timeout: 2 * time.Second}
+	transport := &http.Transport{MaxConnsPerHost: c.Clients, MaxIdleConnsPerHost: c.Clients, MaxIdleConns: c.Clients, ResponseHeaderTimeout: 2 * time.Second, DisableCompression: true, DialContext: func(ctx context.Context, network, address string) (net.Conn, error) {
+		expected := u.Host
+		if u.Port() == "" {
+			expected = net.JoinHostPort(u.Hostname(), "80")
+		}
+		if address != expected {
+			return nil, fmt.Errorf("unexpected target address")
+		}
+		return dialer.DialContext(ctx, network, address)
+	}}
+	defer transport.CloseIdleConnections()
+	client := &http.Client{Transport: transport, Timeout: 3 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
+	ctx, cancel := context.WithTimeout(ctx, c.Duration)
+	defer cancel()
+	var report Report
+	var mu sync.Mutex
+	var sent atomic.Uint64
+	jobs := make(chan int)
+	var wg sync.WaitGroup
+	start := time.Now()
+	for i := 0; i < c.Clients; i++ {
+		wg.Go(func() {
+			for sequence := range jobs {
+				destination := *u
+				canary := c.NormalEvery > 0 && sequence%c.NormalEvery == 0
+				if canary {
+					destination.Path = "/api/health"
+				}
+				req, err := http.NewRequestWithContext(ctx, http.MethodGet, destination.String(), nil)
+				if err != nil {
+					return
+				}
+				req.Header.Set("User-Agent", "PocketBase-local-loadtest")
+				begin := time.Now()
+				sent.Add(1)
+				res, err := client.Do(req)
+				status := 0
+				if err == nil {
+					status = res.StatusCode
+					if destination.Path == "/api/realtime" && status == 200 {
+						scanner := bufio.NewScanner(io.LimitReader(res.Body, 65537))
+						connected := false
+						eventName := ""
+						for scanner.Scan() {
+							line := scanner.Text()
+							if strings.HasPrefix(line, "event:") {
+								eventName = strings.TrimSpace(strings.TrimPrefix(line, "event:"))
+							}
+							if eventName == "PB_CONNECT" && strings.HasPrefix(line, "data:") {
+								var data struct {
+									ClientID string `json:"clientId"`
+								}
+								connected = json.Unmarshal([]byte(strings.TrimSpace(strings.TrimPrefix(line, "data:"))), &data) == nil && data.ClientID != ""
+								break
+							}
+						}
+						if !connected {
+							err = errors.New("missing realtime connection event")
+						}
+					} else {
+						var body []byte
+						body, err = io.ReadAll(io.LimitReader(res.Body, (1<<20)+1))
+						if len(body) > 1<<20 {
+							err = errors.New("response body exceeds 1 MiB")
+						}
+						if status >= 200 && status < 300 && !json.Valid(body) {
+							err = errors.New("invalid JSON response")
+						}
+					}
+					res.Body.Close()
+				}
+				elapsed := time.Since(begin)
+				mu.Lock()
+				if canary {
+					report.CanarySent++
+					if err == nil && status >= 200 && status < 300 {
+						report.CanarySucceeded++
+					}
+				}
+				if err != nil {
+					report.Errors++
+				} else {
+					report.Completed++
+				}
+				if status > 0 {
+					report.StatusClasses[min(status/100, 5)]++
+				}
+				if status == 429 {
+					report.RateLimited++
+				}
+				if status == 503 {
+					report.Unavailable++
+				}
+				bucket := 6
+				for i, limit := range []time.Duration{time.Millisecond, 5 * time.Millisecond, 10 * time.Millisecond, 50 * time.Millisecond, 100 * time.Millisecond, time.Second} {
+					if elapsed <= limit {
+						bucket = i
+						break
+					}
+				}
+				report.LatencyBuckets[bucket]++
+				mu.Unlock()
+			}
+		})
+	}
+	ticker := time.NewTicker(time.Second / time.Duration(c.Rate))
+	defer ticker.Stop()
+	scheduled := 0
+loop:
+	for scheduled < c.MaxRequests {
+		select {
+		case <-ctx.Done():
+			break loop
+		case <-ticker.C:
+			select {
+			case jobs <- scheduled:
+				scheduled++
+			default:
+				report.Dropped++
+			}
+		}
+	}
+	close(jobs)
+	wg.Wait()
+	report.Sent = sent.Load()
+	report.Offered = report.Sent + report.Dropped
+	report.Interrupted = callerCtx.Err() != nil
+	report.Elapsed = time.Since(start)
+	return report, nil
+}

package/loadtest/loadtest_test.go

@@ -0,0 +1,84 @@
+package loadtest
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestRejectExternalTargets(t *testing.T) {
+	for _, target := range []string{"http://example.com/api/health", "http://192.0.2.1/api/health", "http://localhost/api/health", "http://127.0.0.1/api/collections/users/records", "http://user:secret@127.0.0.1/api/health", "http://127.0.0.1/api/health?url=example.com"} {
+		_, err := Run(context.Background(), Config{Target: target, Rate: 1, Clients: 1, Duration: time.Second, MaxRequests: 1})
+		if err == nil {
+			t.Fatalf("accepted %s", target)
+		}
+	}
+}
+func TestBudgetAndNoRedirect(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "http://192.0.2.1/", http.StatusFound)
+	}))
+	defer server.Close()
+	report, err := Run(context.Background(), Config{Target: server.URL + "/api/health", Rate: 100, Clients: 2, Duration: time.Second, MaxRequests: 5})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if report.Sent != 5 || report.Completed != 5 || report.StatusClasses[3] != 5 {
+		t.Fatalf("unexpected report %+v", report)
+	}
+}
+func TestCancellation(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { <-r.Context().Done() }))
+	defer server.Close()
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	report, err := Run(ctx, Config{Target: server.URL + "/api/realtime", Rate: 100, Clients: 2, Duration: time.Minute, MaxRequests: 100})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if time.Since(start) > time.Second || report.Sent > 2 || report.Errors != report.Sent {
+		t.Fatalf("cancellation failed %+v", report)
+	}
+}
+
+func TestProtocolAndResponseBounds(t *testing.T) {
+	for _, tc := range []struct {
+		path, body string
+		valid      bool
+	}{
+		{"/api/health", `{"code":200}`, true},
+		{"/api/health", `not json`, false},
+		{"/api/health", strings.Repeat(" ", 1<<20) + `{}`, false},
+		{"/api/realtime", "event: PB_CONNECT\ndata: {\"clientId\":\"fixture\"}\n\n", true},
+		{"/api/realtime", "event: PB_CONNECT\ndata: {}\n\n", false},
+	} {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, tc.body) }))
+		config := Config{Target: server.URL + tc.path, Rate: 100, Clients: 1, Duration: time.Second, MaxRequests: 1}
+		if err := Validate(config); err != nil {
+			t.Fatal(err)
+		}
+		report, err := Run(context.Background(), config)
+		server.Close()
+		if err != nil || (report.Errors == 0) != tc.valid || report.Sent != 1 {
+			t.Fatalf("unexpected protocol result %+v %v", report, err)
+		}
+	}
+}
+
+func TestDryValidationDoesNotContactTarget(t *testing.T) {
+	var calls atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { calls.Add(1) }))
+	defer server.Close()
+	if err := Validate(Config{Target: server.URL + "/api/health", Rate: 1, Clients: 1, Duration: time.Second, MaxRequests: 1}); err != nil {
+		t.Fatal(err)
+	}
+	if calls.Load() != 0 {
+		t.Fatal("validation sent traffic")
+	}
+}

package/localization/README.md

@@ -0,0 +1,23 @@
+# Validation messages
+
+Opt-in error-code translations for a custom Go binary:
+
+```go
+localization.Register(app, localization.Catalog{
+    "de": {"validation_required": "Pflichtfeld"},
+    "fr": {"validation_required": "Champ obligatoire"},
+})
+```
+
+Clients select a language with `?lang=de` (including SDK query options). Exact tags
+are tried before progressively shorter language tags. Missing translations keep
+PocketBase's English message. This changes only normalized public validation
+messages, preserving status, error codes and parameters. It never translates raw
+internal errors or mutates shared validation errors. Top-level API messages remain
+unchanged. Translations are startup configuration; no new settings database or
+admin translation application is introduced.
+
+`catalogue.json` lists literal codes/messages found in PocketBase and its pinned
+validation dependency. Regenerate with `the root repository’s `python3 scripts/localization/catalogue.py``.
+Dynamic/custom plugin error codes are not enumerable and must be supplied by the
+application. Catalogue messages are text, not HTML; clients must render them as text.