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