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

@@ -46,25 +46,35 @@ Use cases:
A plugin or job reads and writes the cache the framework published:
```go
package blog
import (
"context"
"time"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/cooler"
)
// Sidebar returns the rendered sidebar, cached for five minutes.
func Sidebar(ctx context.Context, app *backpack.App, render func(context.Context) ([]byte, error)) ([]byte, error) {
cache, err := cooler.FromApp(app)
if err != nil {
return nil, err
}
return cache.Remember(ctx, "blog:sidebar", 5*time.Minute, render)
```go src=modules/cooler/example_test.go#ExampleFromApp
// serve publishes the Cache at start-up; a job or console command asks
// FromApp, which builds the configured driver (memory here) once.
app := backpack.New(nil)
cache, err := cooler.FromApp(app)
if err != nil {
fmt.Println(err)
return
}
ctx := context.Background()
loads := 0
popular := func(context.Context) ([]byte, error) {
loads++
return json.Marshal([]string{"Hello", "Summer"})
}
var titles []string
for range 2 {
raw, err := cache.Remember(ctx, "blog:popular", 10*time.Minute, popular)
if err != nil {
fmt.Println(err)
return
}
if err := json.Unmarshal(raw, &titles); err != nil {
fmt.Println(err)
return
}
}
fmt.Println(titles, loads)
// Output: [Hello Summer] 1
```
`cooler.FromApp` returns the Cache `serve` published, so in a request handler `app.Lookup[cooler.Cache]()` works as well. In a separate `queue:work` process or a console command, `cooler.FromApp` builds the configured Cache the first time.
@@ -93,51 +103,46 @@ Nothing else changes: routes keep `throttle:60,1` or `throttle:<bucket>`, and `s
An admin controller purges the host site's page cache after its saves. The hook runs inside the save transaction, and the purge waits for the commit:
```go
package blog
import (
"context"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/cabana"
"git.golem15.com/golem15/summercms/modules/cooler"
)
// Article is the blog's article model.
```go src=modules/cooler/example_test.go#Article
// Article is a blog's article model.
type Article struct {
Slug string
}
```
```go src=modules/cooler/example_test.go#articlesController
// articlesController is a blog's admin controller (its pact.AdminController
// methods are left out here).
type articlesController struct {
app func() *backpack.App
}
```
// FormAfterUpdate purges the site cache once the save commits.
func (c articlesController) FormAfterUpdate(ctx context.Context, model any) error {
tx, ok := cabana.TxFromContext(ctx)
```go src=modules/cooler/example_test.go#articlesController.purge
// purge queues one site-cache purge for the saved article once the save
// transaction commits (at once outside one); the save never waits for the
// site. Without a purge configured the purger is nil and nothing is sent.
func (c articlesController) purge(ctx context.Context, model any) error {
article, ok := model.(*Article)
if !ok {
return nil
}
purger := cooler.SiteCacheFromApp(c.app())
cooler.PurgeSiteCacheAfterCommit(ctx, tx, purger, "article", model.(*Article).Slug)
tx, _ := cabana.TxFromContext(ctx)
cooler.PurgeSiteCacheAfterCommit(ctx, tx, cooler.SiteCacheFromApp(c.app()), "article", article.Slug)
return nil
}
```
```go src=modules/cooler/example_test.go#articlesController.FormAfterUpdate
// FormAfterUpdate runs inside the update's transaction.
func (c articlesController) FormAfterUpdate(ctx context.Context, model any) error {
return c.purge(ctx, model)
}
```
A tool outside `serve` can use the store directly:
```go
package blog
import (
"context"
"time"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/cooler"
)
```go src=modules/cooler/example_test.go#AllowExport
// AllowExport admits five exports a minute per user across all instances.
func AllowExport(ctx context.Context, app *backpack.App, fallback cooler.Attempter, userKey string) (bool, error) {
client, err := cooler.OpenRedis(ctx, app.Config.String(cooler.RedisURLKey))