Adding upstream version 0.28.1.

Signed-off-by: Daniel Baumann <daniel@debian.org>

tools/hook/hook.go

@@ -0,0 +1,178 @@
+package hook
+
+import (
+	"sort"
+	"sync"
+
+	"github.com/pocketbase/pocketbase/tools/security"
+)
+
+// Handler defines a single Hook handler.
+// Multiple handlers can share the same id.
+// If Id is not explicitly set it will be autogenerated by Hook.Add and Hook.AddHandler.
+type Handler[T Resolver] struct {
+	// Func defines the handler function to execute.
+	//
+	// Note that users need to call e.Next() in order to proceed with
+	// the execution of the hook chain.
+	Func func(T) error
+
+	// Id is the unique identifier of the handler.
+	//
+	// It could be used later to remove the handler from a hook via [Hook.Remove].
+	//
+	// If missing, an autogenerated value will be assigned when adding
+	// the handler to a hook.
+	Id string
+
+	// Priority allows changing the default exec priority of the handler within a hook.
+	//
+	// If 0, the handler will be executed in the same order it was registered.
+	Priority int
+}
+
+// Hook defines a generic concurrent safe structure for managing event hooks.
+//
+// When using custom event it must embed the base [hook.Event].
+//
+// Example:
+//
+//	type CustomEvent struct {
+//		hook.Event
+//		SomeField int
+//	}
+//
+//	h := Hook[*CustomEvent]{}
+//
+//	h.BindFunc(func(e *CustomEvent) error {
+//		println(e.SomeField)
+//
+//		return e.Next()
+//	})
+//
+//	h.Trigger(&CustomEvent{ SomeField: 123 })
+type Hook[T Resolver] struct {
+	handlers []*Handler[T]
+	mu       sync.RWMutex
+}
+
+// Bind registers the provided handler to the current hooks queue.
+//
+// If handler.Id is empty it is updated with autogenerated value.
+//
+// If a handler from the current hook list has Id matching handler.Id
+// then the old handler is replaced with the new one.
+func (h *Hook[T]) Bind(handler *Handler[T]) string {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	var exists bool
+
+	if handler.Id == "" {
+		handler.Id = generateHookId()
+
+		// ensure that it doesn't exist
+	DUPLICATE_CHECK:
+		for _, existing := range h.handlers {
+			if existing.Id == handler.Id {
+				handler.Id = generateHookId()
+				goto DUPLICATE_CHECK
+			}
+		}
+	} else {
+		// replace existing
+		for i, existing := range h.handlers {
+			if existing.Id == handler.Id {
+				h.handlers[i] = handler
+				exists = true
+				break
+			}
+		}
+	}
+
+	// append new
+	if !exists {
+		h.handlers = append(h.handlers, handler)
+	}
+
+	// sort handlers by Priority, preserving the original order of equal items
+	sort.SliceStable(h.handlers, func(i, j int) bool {
+		return h.handlers[i].Priority < h.handlers[j].Priority
+	})
+
+	return handler.Id
+}
+
+// BindFunc is similar to Bind but registers a new handler from just the provided function.
+//
+// The registered handler is added with a default 0 priority and the id will be autogenerated.
+//
+// If you want to register a handler with custom priority or id use the [Hook.Bind] method.
+func (h *Hook[T]) BindFunc(fn func(e T) error) string {
+	return h.Bind(&Handler[T]{Func: fn})
+}
+
+// Unbind removes one or many hook handler by their id.
+func (h *Hook[T]) Unbind(idsToRemove ...string) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	for _, id := range idsToRemove {
+		for i := len(h.handlers) - 1; i >= 0; i-- {
+			if h.handlers[i].Id == id {
+				h.handlers = append(h.handlers[:i], h.handlers[i+1:]...)
+				break // for now stop on the first occurrence since we don't allow handlers with duplicated ids
+			}
+		}
+	}
+}
+
+// UnbindAll removes all registered handlers.
+func (h *Hook[T]) UnbindAll() {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	h.handlers = nil
+}
+
+// Length returns to total number of registered hook handlers.
+func (h *Hook[T]) Length() int {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+
+	return len(h.handlers)
+}
+
+// Trigger executes all registered hook handlers one by one
+// with the specified event as an argument.
+//
+// Optionally, this method allows also to register additional one off
+// handler funcs that will be temporary appended to the handlers queue.
+//
+// NB! Each hook handler must call event.Next() in order the hook chain to proceed.
+func (h *Hook[T]) Trigger(event T, oneOffHandlerFuncs ...func(T) error) error {
+	h.mu.RLock()
+	handlers := make([]func(T) error, 0, len(h.handlers)+len(oneOffHandlerFuncs))
+	for _, handler := range h.handlers {
+		handlers = append(handlers, handler.Func)
+	}
+	handlers = append(handlers, oneOffHandlerFuncs...)
+	h.mu.RUnlock()
+
+	event.setNextFunc(nil) // reset in case the event is being reused
+
+	for i := len(handlers) - 1; i >= 0; i-- {
+		i := i
+		old := event.nextFunc()
+		event.setNextFunc(func() error {
+			event.setNextFunc(old)
+			return handlers[i](event)
+		})
+	}
+
+	return event.Next()
+}
+
+func generateHookId() string {
+	return security.PseudorandomString(20)
+}