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
This commit is contained in:
Jakub Zych
2026-11-18 19:48:01 +01:00
parent becb31fbef
commit d04454c57b
8 changed files with 385 additions and 95 deletions

View File

@@ -33,39 +33,65 @@ Use cases:
## Usage
```go
package blog
import (
"context"
"git.golem15.com/golem15/summercms/modules/festival"
)
// PostPublished is fired after a post goes live. Listeners add payload
// entries and may mark the event handled.
```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 {
PostID uint
payload map[string]any
handled bool
}
func (e *PostPublished) Collected() map[string]any { return e.payload }
func (e *PostPublished) IsHandled() bool { return e.handled }
func publish(ctx context.Context, bus *festival.Bus) (map[string]any, error) {
bus.ListenPriority("acme.search", 10, func(ctx context.Context, e *PostPublished) error {
if e.payload == nil {
e.payload = map[string]any{}
}
e.payload["indexed"] = true
return nil
})
return bus.Collect(ctx, &PostPublished{PostID: 42})
Title string
}
```
The event type is inferred from the listener's parameter, so this listener only receives `*PostPublished` events. In a plugin, the bus is `app.Events` on the `backpack.App` passed to Boot; `festival.New` is for tests and standalone use.
```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] <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