Files
summercms/modules/festival
Jakub Zych d04454c57b docs(cooler,diary,festival,fetchguard): compile README Go examples via src= (quick-261118-qsd)
- cooler: ExampleFromApp and the articlesController purge declarations;
  AllowExport run by TestDocsAllowExport on miniredis
- diary: blogLog and ExampleFor; the generated main's run function, run by
  TestDocsRun in a temp directory with diary.Reset on cleanup
- festival: PostPublished/ExampleBus_Fire and PostFormExtended/Collected/
  ExampleBus_Collect, with a TestDocsDeclarations for Collected
- fetchguard: fetch region run by TestDocsFetchImage (loopback refused as
  private_ip), client region run by TestDocsSyncItems on a stub transport
2026-11-18 19:48:01 +01:00
..
2026-09-28 02:16:36 +02:00

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 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

// PostPublished is the event the acme.blog plugin fires after a post goes live.
type PostPublished struct {
	Title string
}
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:

// PostFormExtended gathers extra fields other plugins add to the post form.
type PostFormExtended struct {
	fields map[string]any
}
func (e *PostFormExtended) Collected() map[string]any { return e.fields }
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] <nil>

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

go test ./modules/festival/...

The tests use in-process listeners and need no external services.