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:
@@ -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))
|
||||
|
||||
Reference in New Issue
Block a user