# festival Typed, synchronous event bus with listener priorities, payload collection and stop-when-handled dispatch. `import "git.golem15.com/golem15/summercms/modules/festival"` **Name:** A summer festival announces events and the crowd reacts; it is the event bus. ## Overview `festival` is the SummerCMS counterpart of WinterCMS's `Event::listen` and `Event::fire`, the mechanism plugins use to extend each other without direct calls. Events are routed by their Go type rather than by a string name, so a listener registered for `*PostPublished` receives exactly that type, and a payload mismatch is a compile error. Each application owns one bus: [backpack](../backpack/README.md) creates it in `backpack.New` and exposes it as `backpack.App.Events`, and plugins register listeners from their Boot step. ## Role in the framework A dependency-free core primitive owned by `backpack`, so every plugin reaches the bus through the application. It is in-process and synchronous. Delivery to browsers is `lighthouse` and delivery to devices is `flare`; those depend on the database and jobs, so they cannot sit under `backpack` without an import cycle. Use cases: - Let one plugin react to another without importing it, for example sending a welcome mail when a user registers. - Let plugins veto or change an action by priority, the WinterCMS "before" event style. - Collect contributions from several listeners, such as extra fields for an API response. ## Features - Listener registration with `festival.Bus.Listen` (priority 0) and `festival.Bus.ListenPriority`. Higher priorities run first; listeners with equal priority run in registration order. Every listener carries the ID of the plugin that owns it. - Three dispatch modes, all synchronous on the caller's goroutine: - `festival.Bus.Fire` runs every listener and returns the joined errors of all that failed (`errors.Join`). - `festival.Bus.Collect` runs every listener and, after each one, merges the event's `festival.Collectable.Collected` map into a single payload (later keys win). It returns the payload gathered so far together with the joined errors. - `festival.Bus.UntilHandled` stops at the first error or as soon as the event's `festival.Handleable.IsHandled` reports true, and returns whether the event was handled (WinterCMS's halting fire). - Panic isolation: a panicking listener is recovered and reported as an error that names its owner plugin, so one faulty plugin cannot take down the dispatch. - Safe for concurrent use: registration is locked and dispatch works on a snapshot of the listener list. - Value and pointer types are distinct event types; events that listeners modify (for `Collect` and `UntilHandled`) are usually pointers. ## Usage ```go src=modules/festival/example_test.go#PostPublished // PostPublished is the event the acme.blog plugin fires after a post goes live. type PostPublished struct { Title string } ``` ```go src=modules/festival/example_test.go#ExampleBus_Fire bus := festival.New() // in a plugin, use app.Events // acme.search and acme.notify extend acme.blog from their Boot steps. bus.Listen("acme.search", func(ctx context.Context, e PostPublished) error { fmt.Println("index", e.Title) return nil }) bus.ListenPriority("acme.notify", 10, func(ctx context.Context, e PostPublished) error { fmt.Println("notify subscribers of", e.Title) return nil }) // acme.blog fires the event; higher priorities run first. if err := bus.Fire(context.Background(), PostPublished{Title: "Hello"}); err != nil { fmt.Println(err) } // Output: // notify subscribers of Hello // index Hello ``` The event type is inferred from the listener's parameter, so these listeners only receive `PostPublished` events. Events that listeners modify are pointers; `festival.Bus.Collect` merges what each listener collected: ```go src=modules/festival/example_test.go#PostFormExtended // PostFormExtended gathers extra fields other plugins add to the post form. type PostFormExtended struct { fields map[string]any } ``` ```go src=modules/festival/example_test.go#PostFormExtended.Collected func (e *PostFormExtended) Collected() map[string]any { return e.fields } ``` ```go src=modules/festival/example_test.go#ExampleBus_Collect bus := festival.New() bus.Listen("acme.seo", func(ctx context.Context, e *PostFormExtended) error { e.fields = map[string]any{"meta_title": "text"} return nil }) bus.Listen("acme.gallery", func(ctx context.Context, e *PostFormExtended) error { e.fields = map[string]any{"cover": "fileupload"} return nil }) fields, err := bus.Collect(context.Background(), &PostFormExtended{}) fmt.Println(fields, err) // Output: map[cover:fileupload meta_title:text] ``` In a plugin, the bus is `app.Events` on the `backpack.App` passed to Boot; `festival.New` is for tests and standalone use. ## API reference | Identifier | Description | |------------|-------------| | `festival.Bus` | Application-owned, type-keyed event dispatcher. | | `festival.New` | Returns an empty bus. | | `festival.Bus.Listen` | Registers a listener for event type T at priority 0. | | `festival.Bus.ListenPriority` | Registers a listener for event type T at an explicit priority. | | `festival.Bus.Fire` | Runs every listener and joins their errors. | | `festival.Bus.Collect` | Runs every listener and merges the event's collected payload. | | `festival.Bus.UntilHandled` | Runs listeners until one handles the event or fails. | | `festival.Collectable` | Implemented by events that expose a mergeable payload for `Collect`. | | `festival.Handleable` | Implemented by events that can stop `UntilHandled`. | ## Dependencies - SummerCMS modules: none. - Third-party: none. - Standard library: `context`, `errors`, `fmt`, `reflect`, `sort`, `sync`. ## Testing ```sh go test ./modules/festival/... ``` The tests use in-process listeners and need no external services.