docs(backpack,beachcomber,boardwalk,bonfire,bouncer): compile README Go examples via src= (quick-261118-qsd)

- backpack: Greeter and ExampleApp_Publish replace the whole-file fence
- beachcomber: Post's Searchable methods plus a new SearchIndexSchema, a
  Plugin.Boot that installs the gate, and the existing gate/search regions
- boardwalk: new example_test.go; the mount region runs in ExampleHandler
- bonfire: importPostsCommand and acmeMain (the binary's main as a function
  returning the exit code), run by ExampleExecute; ExampleCatalog_Has
- bouncer: users/FindByID and ExampleNewJWTGuard; RefreshRoute run by
  TestDocsRefreshRoute on a production compass config
This commit is contained in:
Jakub Zych
2026-11-18 19:39:50 +01:00
parent 48527e4206
commit a0f5b5e561
9 changed files with 366 additions and 125 deletions

View File

@@ -81,12 +81,18 @@ typesense:
A model implements `beachcomber.Searchable` without importing beachcomber:
```go
package models
```go src=modules/beachcomber/example_test.go#Post.SearchableAs
// SearchableAs is the index name, before search.prefix.
func (Post) SearchableAs() string { return "acme_blog_posts" }
```
func (Post) SearchableAs() string { return "acme_blog_posts" }
func (Post) ShouldBeSearchable() bool { return true }
```go src=modules/beachcomber/example_test.go#Post.ShouldBeSearchable
// ShouldBeSearchable keeps drafts out of the index.
func (p *Post) ShouldBeSearchable() bool { return p.Published }
```
```go src=modules/beachcomber/example_test.go#Post.ToSearchableArray
// ToSearchableArray builds the document from the committed row.
func (p *Post) ToSearchableArray(ctx context.Context, db *gorm.DB) (map[string]any, error) {
return map[string]any{
"id": strconv.FormatUint(uint64(p.ID), 10),
@@ -94,7 +100,10 @@ func (p *Post) ToSearchableArray(ctx context.Context, db *gorm.DB) (map[string]a
"title": p.Title,
}, nil
}
```
```go src=modules/beachcomber/example_test.go#Post.SearchIndexSchema
// SearchIndexSchema is the schema a missing index is created with.
func (Post) SearchIndexSchema() map[string]any {
return map[string]any{
"fields": []map[string]any{
@@ -106,40 +115,47 @@ func (Post) SearchIndexSchema() map[string]any {
}
```
The plugin imports the engine package for its side effect, builds the service at Boot and installs its kill-switch:
```go
package acme
import (
"context"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/beachcomber"
_ "git.golem15.com/golem15/summercms/modules/beachcomber/typesense"
"gorm.io/gorm"
)
The application imports the engine package (for example `beachcomber/typesense`) for its side effect. The plugin builds the service at Boot and installs its kill-switch:
```go src=modules/beachcomber/example_test.go#Plugin.Boot
// Boot builds the search service and installs its kill-switch.
func (p *Plugin) Boot(app *backpack.App) error {
svc, err := beachcomber.From(app)
if err != nil {
return err
}
svc.SetGate(beachcomber.GateFunc(func(ctx context.Context, db *gorm.DB) bool {
return acmeSearchEnabled(ctx, db) // false on any read error
}))
installGate(svc)
return nil
}
```
A search endpoint asks the engine for candidate ids:
```go src=modules/beachcomber/example_test.go#gate
svc.SetGate(beachcomber.GateFunc(func(ctx context.Context, db *gorm.DB) bool {
var enabled bool
err := db.WithContext(ctx).Raw(`SELECT search_enabled FROM acme_blog_settings WHERE id = 1`).Scan(&enabled).Error
return err == nil && enabled
}))
```
```go
ids, err := svc.Engine().SearchIDs(ctx, svc.IndexName(&models.Post{}), beachcomber.Query{
A search endpoint asks the engine for candidate ids and re-checks them in SQL:
```go src=modules/beachcomber/example_test.go#search
ids, err := svc.Engine().SearchIDs(ctx, svc.IndexName(&Post{}), beachcomber.Query{
Q: term,
QueryBy: []string{"title"},
FilterBy: "blog_id:=" + strconv.FormatUint(uint64(blogID), 10),
})
if err != nil {
return nil, err
}
// The ids are candidates from an index that may be stale or loosely
// filtered: re-check every one in SQL before exposing a row.
var posts []Post
err = db.WithContext(ctx).
Where("id IN ? AND blog_id = ? AND published", ids, blogID).
Order("id").
Find(&posts).Error
return posts, err
```
## API reference

View File

@@ -42,6 +42,17 @@ func (p *Post) ToSearchableArray(ctx context.Context, db *gorm.DB) (map[string]a
}, nil
}
// SearchIndexSchema is the schema a missing index is created with.
func (Post) SearchIndexSchema() map[string]any {
return map[string]any{
"fields": []map[string]any{
{"name": "id", "type": "string"},
{"name": "blog_id", "type": "int64"},
{"name": "title", "type": "string"},
},
}
}
// memoryEngine is a toy engine: it matches Q against the title and ignores
// FilterBy, so its answers are loose candidates, as a stale index's are.
type memoryEngine struct {
@@ -120,6 +131,19 @@ func ExampleFrom() {
// true
}
// Plugin is the acme.blog plugin.
type Plugin struct{}
// Boot builds the search service and installs its kill-switch.
func (p *Plugin) Boot(app *backpack.App) error {
svc, err := beachcomber.From(app)
if err != nil {
return err
}
installGate(svc)
return nil
}
// installGate turns search sync on only while the blog's search setting is
// on; a failed read counts as off.
func installGate(svc *beachcomber.Service) {
@@ -167,7 +191,10 @@ func TestDocsSearch(t *testing.T) {
t.Fatal(err)
}
}
svc, err := beachcomber.From(app)
if err := (&Plugin{}).Boot(app); err != nil {
t.Fatal(err)
}
svc, err := beachcomber.From(app) // the service Boot built
if err != nil {
t.Fatal(err)
}
@@ -175,7 +202,6 @@ func TestDocsSearch(t *testing.T) {
// test installs the toy engine directly, so the global engine list the
// package's own tests check stays unchanged.
beachcomber.DocsUseEngine(svc, memory)
installGate(svc)
ctx := t.Context()
indexed := func() int {
memory.mu.Lock()
@@ -255,4 +281,9 @@ func TestDocsDeclarations(t *testing.T) {
if err != nil || doc["id"] != "5" || doc["blog_id"] != int64(7) {
t.Fatalf("ToSearchableArray = %v, %v", doc, err)
}
var _ beachcomber.IndexSchemaProvider = Post{}
fields, _ := p.SearchIndexSchema()["fields"].([]map[string]any)
if len(fields) != 3 || fields[0]["name"] != "id" {
t.Fatalf("SearchIndexSchema fields = %v", fields)
}
}