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