diff --git a/modules/lighthouse/README.md b/modules/lighthouse/README.md
index 7b5c1b3a..44c381e4 100644
--- a/modules/lighthouse/README.md
+++ b/modules/lighthouse/README.md
@@ -79,18 +79,10 @@ centrifugo:
A plugin imports the driver package for its side effect, builds the service at Boot, installs a user lookup and registers its channel authorizers:
-```go
-package acme
-
-import (
- "context"
-
- "git.golem15.com/golem15/summercms/modules/backpack"
- "git.golem15.com/golem15/summercms/modules/lighthouse"
- _ "git.golem15.com/golem15/summercms/modules/lighthouse/centrifugo"
-)
-
-func (p *Plugin) Boot(app *backpack.App) error {
+```go src=modules/lighthouse/example_test.go#RoomsPlugin.Boot
+// Boot builds the realtime service, installs the user lookup and registers
+// the room authorizer.
+func (p *RoomsPlugin) Boot(app *backpack.App) error {
svc, err := lighthouse.From(app)
if err != nil {
return err
@@ -112,8 +104,9 @@ func (p *Plugin) Boot(app *backpack.App) error {
and mounts the driver's routes once:
-```go
-func (p *Plugin) Routes(r pact.Router) error {
+```go src=modules/lighthouse/example_test.go#RoomsPlugin.Routes
+// Routes mounts the driver's routes once.
+func (p *RoomsPlugin) Routes(r pact.Router) error {
return lighthouse.Mount(r, p.realtime.Driver(), lighthouse.Surfaces{
UserAuth: surf.Use("jwt.auth"),
ServerToServer: surf.Use(),
@@ -124,10 +117,10 @@ func (p *Plugin) Routes(r pact.Router) error {
A model package stays free of realtime code; the plugin binds the model at Boot:
-```go
-err := lighthouse.Bind[models.Post](svc, lighthouse.Binding[models.Post]{
+```go src=modules/lighthouse/example_test.go#bind
+return lighthouse.Bind[Post](svc, lighthouse.Binding[Post]{
Alias: "blog.post",
- Channels: func(ctx context.Context, tx *gorm.DB, p *models.Post) ([]string, error) {
+ Channels: func(ctx context.Context, tx *gorm.DB, p *Post) ([]string, error) {
return []string{"blog:" + strconv.FormatUint(uint64(p.BlogID), 10)}, nil
},
})
@@ -135,21 +128,20 @@ err := lighthouse.Bind[models.Post](svc, lighthouse.Binding[models.Post]{
A bulk import suppresses the per-row events and publishes one summary after commit:
-```go
-err := lighthouse.WithoutBroadcasting[models.Post](ctx, func(ctx context.Context) error {
- return lagoon.Transaction(ctx, gdb, func(ctx context.Context, tx *gorm.DB) error {
- for _, p := range posts {
- if err := tx.Create(&p).Error; err != nil {
+```go src=modules/lighthouse/example_test.go#bulk
+return lighthouse.WithoutBroadcasting[Post](ctx, func(ctx context.Context) error {
+ return lagoon.Transaction(ctx, db, func(ctx context.Context, tx *gorm.DB) error {
+ for _, title := range titles {
+ if err := tx.Create(&Post{BlogID: 7, Title: title}).Error; err != nil {
return err
}
}
return svc.Emit(ctx, tx, lighthouse.Broadcast{
Channels: []string{"blog:7"},
- Event: "blog.bulk_updated",
+ Event: "blog.posts_imported",
Payload: struct {
- Reason string `json:"reason"`
- Count int `json:"count"`
- }{"import", len(posts)},
+ Count int `json:"count"`
+ }{len(titles)},
})
})
})
@@ -157,7 +149,7 @@ err := lighthouse.WithoutBroadcasting[models.Post](ctx, func(ctx context.Context
Tests select the memory driver and read what was published:
-```go
+```go src=modules/lighthouse/example_test.go#publications
mem := svc.Driver().(*lighthouse.MemoryDriver)
for _, pub := range mem.Publications() {
fmt.Println(pub.Method, pub.Channels, pub.Event)
diff --git a/modules/lighthouse/example_test.go b/modules/lighthouse/example_test.go
index 3a80c567..985d88e8 100644
--- a/modules/lighthouse/example_test.go
+++ b/modules/lighthouse/example_test.go
@@ -2,8 +2,12 @@ package lighthouse_test
import (
"context"
+ "encoding/json"
"fmt"
+ "net/http"
+ "slices"
"strconv"
+ "strings"
"testing"
"time"
@@ -11,6 +15,9 @@ import (
"git.golem15.com/golem15/summercms/modules/compass"
"git.golem15.com/golem15/summercms/modules/lagoon"
"git.golem15.com/golem15/summercms/modules/lighthouse"
+ _ "git.golem15.com/golem15/summercms/modules/lighthouse/centrifugo"
+ "git.golem15.com/golem15/summercms/modules/pact"
+ "git.golem15.com/golem15/summercms/modules/surf"
"gorm.io/gorm"
)
@@ -194,3 +201,145 @@ func TestDocsBroadcast(t *testing.T) {
t.Fatalf("summary = %+v %s", pubs[1], pubs[1].Payload)
}
}
+
+// RoomsPlugin is the acme.rooms plugin: room:{id} channels for members.
+type RoomsPlugin struct {
+ realtime *lighthouse.Service
+}
+
+// lookupAcmeUser stands in for the application's own user model.
+func lookupAcmeUser(ctx context.Context, id uint) (lighthouse.User, bool, error) {
+ if id != 42 {
+ return lighthouse.User{}, false, nil
+ }
+ name := "Ada"
+ return lighthouse.User{ID: id, Name: &name}, true, nil
+}
+
+// isRoomMember stands in for the application's own membership query.
+func isRoomMember(ctx context.Context, userID uint, roomID int64) bool {
+ return userID == 42 && roomID == 7
+}
+
+// Boot builds the realtime service, installs the user lookup and registers
+// the room authorizer.
+func (p *RoomsPlugin) Boot(app *backpack.App) error {
+ svc, err := lighthouse.From(app)
+ if err != nil {
+ return err
+ }
+ p.realtime = svc
+ svc.SetUserLookup(func(ctx context.Context, id uint) (lighthouse.User, bool, error) {
+ return lookupAcmeUser(ctx, id) // the application's own user model
+ })
+ // Allow room:{id} to members only; re-checked on every subscribe.
+ return svc.Registry().Register("room", lighthouse.AuthorizerFunc(
+ func(ctx context.Context, userID uint, channel string) lighthouse.Result {
+ if isRoomMember(ctx, userID, lighthouse.ChannelID(channel)) {
+ return lighthouse.Allowed(nil)
+ }
+ return lighthouse.Denied("not a room member")
+ }))
+}
+
+// Routes mounts the driver's routes once.
+func (p *RoomsPlugin) Routes(r pact.Router) error {
+ return lighthouse.Mount(r, p.realtime.Driver(), lighthouse.Surfaces{
+ UserAuth: surf.Use("jwt.auth"),
+ ServerToServer: surf.Use(),
+ Middleware: surf.Use("throttle:acme-realtime"),
+ })
+}
+
+// routeRecorder is a pact.Router that records each route with its
+// middleware, standing in for surf's router.
+type routeRecorder struct {
+ prefix string
+ middleware []string
+ lines *[]string
+}
+
+func (r routeRecorder) group(prefix string, mw []string, raw bool, fn func(pact.Router)) {
+ if raw {
+ mw = append([]string{"raw"}, mw...)
+ }
+ fn(routeRecorder{strings.TrimSuffix(r.prefix+prefix, "/"), append(slices.Clone(r.middleware), mw...), r.lines})
+}
+func (r routeRecorder) add(method, path string, mw []string) {
+ *r.lines = append(*r.lines, method+" "+r.prefix+path+" "+strings.Join(append(slices.Clone(r.middleware), mw...), ","))
+}
+func (r routeRecorder) Group(p string, mw []string, fn func(pact.Router)) { r.group(p, mw, false, fn) }
+func (r routeRecorder) GroupRaw(p string, mw []string, fn func(pact.Router)) {
+ r.group(p, mw, true, fn)
+}
+func (r routeRecorder) Get(p string, _ http.HandlerFunc, mw ...string) { r.add("GET", p, mw) }
+func (r routeRecorder) Post(p string, _ http.HandlerFunc, mw ...string) { r.add("POST", p, mw) }
+func (r routeRecorder) Put(p string, _ http.HandlerFunc, mw ...string) { r.add("PUT", p, mw) }
+func (r routeRecorder) Patch(p string, _ http.HandlerFunc, mw ...string) { r.add("PATCH", p, mw) }
+func (r routeRecorder) Delete(p string, _ http.HandlerFunc, mw ...string) { r.add("DELETE", p, mw) }
+func (routeRecorder) Where(string, string) {}
+func (routeRecorder) WhereIn(string, ...string) {}
+
+// TestDocsRoomsPlugin boots the README's plugin on the centrifugo driver,
+// checks its user lookup and room authorizer, and mounts its routes.
+func TestDocsRoomsPlugin(t *testing.T) {
+ app, err := newApp(map[string]any{"realtime.driver": "centrifugo", "realtime.centrifugo.token_secret": "docs-secret"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ p := &RoomsPlugin{}
+ if err := p.Boot(app); err != nil {
+ t.Fatal(err)
+ }
+ ctx := t.Context()
+ if u, ok, err := p.realtime.User(ctx, 42); err != nil || !ok || u.Name == nil || *u.Name != "Ada" {
+ t.Fatalf("User(42) = %+v, %v, %v", u, ok, err)
+ }
+ room, ok := p.realtime.Registry().Get("room")
+ if !ok {
+ t.Fatal("no room authorizer")
+ }
+ if !room.Authorize(ctx, 42, "room:7").Allowed || room.Authorize(ctx, 42, "room:8").Reason() != "not a room member" {
+ t.Fatal("room authorizer does not follow membership")
+ }
+
+ var lines []string
+ if err := p.Routes(routeRecorder{lines: &lines}); err != nil {
+ t.Fatal(err)
+ }
+ want := []string{
+ "GET /api/realtime/token jwt.auth,throttle:acme-realtime",
+ "POST /api/realtime/subscribe raw,throttle:acme-realtime",
+ }
+ if !slices.Equal(lines, want) {
+ t.Fatalf("routes = %q, want %q", lines, want)
+ }
+}
+
+func ExampleMemoryDriver() {
+ app, err := newApp(map[string]any{"realtime.driver": "memory"})
+ if err != nil {
+ fmt.Println(err)
+ return
+ }
+ svc, err := lighthouse.From(app)
+ if err != nil {
+ fmt.Println(err)
+ return
+ }
+ // Code under test publishes; here the example calls the driver itself.
+ ctx := context.Background()
+ _ = svc.Driver().Publish(ctx, "blog:7", "blog.post_updated", json.RawMessage(`{"id":1}`))
+ _ = svc.Driver().Broadcast(ctx, []string{"blog:7", "blog:8"}, "blog.posts_imported", json.RawMessage(`{"count":3}`))
+
+ // docs:start publications
+ mem := svc.Driver().(*lighthouse.MemoryDriver)
+ for _, pub := range mem.Publications() {
+ fmt.Println(pub.Method, pub.Channels, pub.Event)
+ }
+ // docs:end publications
+
+ // Output:
+ // publish [blog:7] blog.post_updated
+ // broadcast [blog:7 blog:8] blog.posts_imported
+}
diff --git a/modules/lighthouse/lighthouse_test.go b/modules/lighthouse/lighthouse_test.go
index 44bf7a8b..e099869b 100644
--- a/modules/lighthouse/lighthouse_test.go
+++ b/modules/lighthouse/lighthouse_test.go
@@ -62,7 +62,9 @@ func TestFromSelectsDriver(t *testing.T) {
}
t.Run("unknown_lists_registered", func(t *testing.T) {
_, err := From(configApp(t, map[string]any{"realtime.driver": "nope"}))
- if err == nil || !strings.Contains(err.Error(), `unknown realtime.driver "nope"`) || !strings.Contains(err.Error(), "acme-nil-driver, log, memory, null") {
+ // example_test.go imports lighthouse/centrifugo, so "centrifugo" may
+ // sit between the drivers this package's tests register.
+ if err == nil || !strings.Contains(err.Error(), `unknown realtime.driver "nope"`) || !strings.Contains(err.Error(), "acme-nil-driver, ") || !strings.Contains(err.Error(), "log, memory, null") {
t.Fatalf("err = %v", err)
}
})
diff --git a/modules/postcard/README.md b/modules/postcard/README.md
index 00de5272..38ad182c 100644
--- a/modules/postcard/README.md
+++ b/modules/postcard/README.md
@@ -48,18 +48,9 @@ Hi **{{ .name }}**, thanks for joining the blog.
and sends it through the mailer the runtime published:
-```go
-package blog
-
-import (
- "context"
- "errors"
-
- "git.golem15.com/golem15/summercms/modules/backpack"
- "git.golem15.com/golem15/summercms/modules/postcard"
-)
-
-func SendWelcome(ctx context.Context, app *backpack.App, email, name string) error {
+```go src=modules/postcard/example_test.go#sendWelcome
+// sendWelcome sends the welcome mail through the mailer published at boot.
+func sendWelcome(ctx context.Context, app *backpack.App, email, name string) error {
mailer, ok := app.Lookup[postcard.Mailer]()
if !ok {
return errors.New("mailer not published")
@@ -74,17 +65,7 @@ func SendWelcome(ctx context.Context, app *backpack.App, email, name string) err
In tests, build the catalog and mailer directly and inspect what was sent:
-```go
-package blog
-
-import (
- "context"
- "testing"
- "testing/fstest"
-
- "git.golem15.com/golem15/summercms/modules/postcard"
-)
-
+```go src=modules/postcard/example_test.go#TestWelcomeMail
func TestWelcomeMail(t *testing.T) {
mailFS := fstest.MapFS{"views/mail/welcome.htm": {Data: []byte("subject = \"Welcome, {{ .name }}\"\n==\nHi **{{ .name }}**.\n")}}
cat := postcard.NewCatalog()
@@ -123,30 +104,14 @@ NOTE: {{ .text }}
{{ .text }}
```
-and declares it next to its templates:
+and declares it next to its templates (`mailFS` is the plugin's `views/mail` directory, embedded with `//go:embed views/mail`; the plugin asserts `var _ pact.HasMailPartials = BlogPlugin{}`):
-```go
-package blog
+```go src=modules/postcard/example_test.go#BlogPlugin.MailPartialsFS
+func (BlogPlugin) MailPartialsFS() fs.FS { return mailFS }
+```
-import (
- "embed"
- "io/fs"
-
- "git.golem15.com/golem15/summercms/modules/pact"
-)
-
-//go:embed views/mail
-var mailFS embed.FS
-
-type Plugin struct{}
-
-var _ pact.HasMailPartials = Plugin{}
-
-func (Plugin) ID() string { return "acme.blog" }
-
-func (Plugin) MailPartialsFS() fs.FS { return mailFS }
-
-func (Plugin) MailPartials() []string {
+```go src=modules/postcard/example_test.go#BlogPlugin.MailPartials
+func (BlogPlugin) MailPartials() []string {
return []string{"acme.blog::mail.partials.note"}
}
```
@@ -236,18 +201,12 @@ An override never stops mail:
`postcard.NewMailer` takes a source through `postcard.Options.Overrides`; any `postcard.OverrideSource` works, which is how a test supplies overrides without a database:
-```go
-package blog
-
-import (
- "context"
-
- "git.golem15.com/golem15/summercms/modules/postcard"
-)
-
+```go src=modules/postcard/example_test.go#fixedOverrides
// fixedOverrides overrides one template with a fixed subject and body.
type fixedOverrides struct{}
+```
+```go src=modules/postcard/example_test.go#fixedOverrides.MailOverrides
func (fixedOverrides) MailOverrides(_ context.Context, template string) (postcard.Overrides, error) {
if template != "acme.blog::mail.welcome" {
return postcard.Overrides{}, nil
@@ -257,7 +216,9 @@ func (fixedOverrides) MailOverrides(_ context.Context, template string) (postcar
Body: "Good to see you, **{{ .name }}**.",
}}, nil
}
+```
+```go src=modules/postcard/example_test.go#newTestMailer
func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Mailer {
return postcard.NewMailer(cat, driver, postcard.Options{Overrides: fixedOverrides{}})
}
@@ -324,17 +285,7 @@ Sample values are strings and are used only by `postcard.Editor`; `Send` never r
`postcard.EditorFrom` returns the `postcard.Editor` of the mailer `postcard.Activate` published. Admin code describes unsaved content as a `postcard.Draft` and asks the editor to check, render or send it:
-```go
-package blog
-
-import (
- "context"
- "errors"
-
- "git.golem15.com/golem15/summercms/modules/backpack"
- "git.golem15.com/golem15/summercms/modules/postcard"
-)
-
+```go src=modules/postcard/example_test.go#previewWelcome
// previewWelcome renders an edited welcome mail without saving it.
func previewWelcome(ctx context.Context, app *backpack.App, subject, body string) (postcard.Preview, error) {
editor, ok := postcard.EditorFrom(app)
diff --git a/modules/postcard/example_test.go b/modules/postcard/example_test.go
index d1638a34..17d423bf 100644
--- a/modules/postcard/example_test.go
+++ b/modules/postcard/example_test.go
@@ -2,10 +2,16 @@ package postcard_test
import (
"context"
+ "errors"
"fmt"
+ "io/fs"
"strings"
+ "testing"
"testing/fstest"
+ "git.golem15.com/golem15/summercms/modules/backpack"
+ "git.golem15.com/golem15/summercms/modules/compass"
+ "git.golem15.com/golem15/summercms/modules/pact"
"git.golem15.com/golem15/summercms/modules/postcard"
)
@@ -25,6 +31,12 @@ Hi **{{ .name }}**, thanks for joining the blog.
==
{{ .Content }}
+`)},
+ "views/mail/partials/note.htm": {Data: []byte(`name = "Note"
+==
+NOTE: {{ .text }}
+==
+{{ .text }}
`)},
}
@@ -71,3 +83,153 @@ func ExampleMailer_Send() {
// true
// true 1
}
+
+// sendWelcome sends the welcome mail through the mailer published at boot.
+func sendWelcome(ctx context.Context, app *backpack.App, email, name string) error {
+ mailer, ok := app.Lookup[postcard.Mailer]()
+ if !ok {
+ return errors.New("mailer not published")
+ }
+ return mailer.Send(ctx, postcard.Message{
+ Template: "acme.blog::mail.welcome",
+ To: []string{email},
+ Vars: map[string]any{"name": name},
+ })
+}
+
+func TestWelcomeMail(t *testing.T) {
+ mailFS := fstest.MapFS{"views/mail/welcome.htm": {Data: []byte("subject = \"Welcome, {{ .name }}\"\n==\nHi **{{ .name }}**.\n")}}
+ cat := postcard.NewCatalog()
+ if err := cat.Register("acme.blog", mailFS, []string{"acme.blog::mail.welcome"}, nil); err != nil {
+ t.Fatal(err)
+ }
+ driver := postcard.NewMemoryDriver()
+ mailer := postcard.NewMailer(cat, driver, postcard.Options{From: "blog@example.com"})
+ msg := postcard.Message{Template: "acme.blog::mail.welcome", To: []string{"ada@example.com"}, Vars: map[string]any{"name": "Ada"}}
+ if err := mailer.Send(context.Background(), msg); err != nil {
+ t.Fatal(err)
+ }
+ if got := driver.Messages()[0].Subject; got != "Welcome, Ada" {
+ t.Fatalf("subject = %q", got)
+ }
+}
+
+// BlogPlugin is the acme.blog plugin; only its mail partials are shown.
+type BlogPlugin struct{}
+
+var _ pact.HasMailPartials = BlogPlugin{}
+
+func (BlogPlugin) ID() string { return "acme.blog" }
+
+func (BlogPlugin) MailPartialsFS() fs.FS { return mailFS }
+
+func (BlogPlugin) MailPartials() []string {
+ return []string{"acme.blog::mail.partials.note"}
+}
+
+// fixedOverrides overrides one template with a fixed subject and body.
+type fixedOverrides struct{}
+
+func (fixedOverrides) MailOverrides(_ context.Context, template string) (postcard.Overrides, error) {
+ if template != "acme.blog::mail.welcome" {
+ return postcard.Overrides{}, nil
+ }
+ return postcard.Overrides{Template: &postcard.TemplateOverride{
+ Subject: "Hello, {{ .name }}",
+ Body: "Good to see you, **{{ .name }}**.",
+ }}, nil
+}
+
+func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Mailer {
+ return postcard.NewMailer(cat, driver, postcard.Options{Overrides: fixedOverrides{}})
+}
+
+// previewWelcome renders an edited welcome mail without saving it.
+func previewWelcome(ctx context.Context, app *backpack.App, subject, body string) (postcard.Preview, error) {
+ editor, ok := postcard.EditorFrom(app)
+ if !ok {
+ return postcard.Preview{}, errors.New("mailer not published")
+ }
+ draft := postcard.Draft{
+ Kind: postcard.KindTemplate,
+ Name: "acme.blog::mail.welcome",
+ Subject: subject,
+ Body: body,
+ }
+ if problem := editor.Validate(ctx, draft); problem != nil {
+ // problem.Field and problem.Rule say what to show next to which field.
+ return postcard.Preview{}, problem
+ }
+ return editor.Preview(ctx, draft)
+}
+
+// docsCatalog registers the example's welcome template and blog layout.
+func docsCatalog(t *testing.T) *postcard.Catalog {
+ t.Helper()
+ cat := postcard.NewCatalog()
+ err := cat.Register("acme.blog", mailFS,
+ []string{"acme.blog::mail.welcome"},
+ map[string]string{"blog": "acme.blog::mail.layouts.blog"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ return cat
+}
+
+// TestDocsMailer publishes a mailer on an app, boots BlogPlugin's partials
+// into it and runs sendWelcome, previewWelcome and newTestMailer.
+func TestDocsMailer(t *testing.T) {
+ ctx := t.Context()
+ app := backpack.New(&compass.Config{})
+ if err := sendWelcome(ctx, app, "ada@example.com", "Ada"); err == nil {
+ t.Fatal("sendWelcome without a mailer succeeded")
+ }
+ driver := postcard.NewMemoryDriver()
+ if err := app.Publish(postcard.NewMailer(docsCatalog(t), driver, postcard.Options{From: "blog@example.com"})); err != nil {
+ t.Fatal(err)
+ }
+ if err := postcard.BootPlugin(app, BlogPlugin{}); err != nil {
+ t.Fatal(err)
+ }
+
+ if err := sendWelcome(ctx, app, "ada@example.com", "Ada"); err != nil {
+ t.Fatal(err)
+ }
+ if got := driver.Messages()[0].Subject; got != "Welcome, Ada" {
+ t.Fatalf("subject = %q", got)
+ }
+
+ preview, err := previewWelcome(ctx, app, "Hi {{ .name }}",
+ "Thanks for joining.\n\n{{ partial \"acme.blog::mail.partials.note\" \"text\" \"Reply any time\" }}\n")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(preview.HTML, `Reply any time
`) || !strings.Contains(preview.Text, "NOTE: Reply any time") {
+ t.Fatalf("preview = %+v", preview)
+ }
+ var problem *postcard.DraftError
+ if _, err := previewWelcome(ctx, app, "Hi {{ .name", "Body"); !errors.As(err, &problem) || problem.Field != "subject" {
+ t.Fatalf("broken subject: %v", err)
+ }
+
+ // The declarations BootPlugin and the mailer call through interfaces.
+ p := BlogPlugin{}
+ if names := p.MailPartials(); len(names) != 1 {
+ t.Fatalf("MailPartials() = %v", names)
+ }
+ if _, err := fs.Stat(p.MailPartialsFS(), "views/mail/partials/note.htm"); err != nil {
+ t.Fatal(err)
+ }
+ if o, err := (fixedOverrides{}).MailOverrides(ctx, "acme.blog::mail.other"); err != nil || o.Template != nil {
+ t.Fatalf("MailOverrides(other) = %+v, %v", o, err)
+ }
+
+ overridden := postcard.NewMemoryDriver()
+ mailer := newTestMailer(docsCatalog(t), overridden)
+ if err := mailer.Send(ctx, postcard.Message{Template: "acme.blog::mail.welcome", To: []string{"ada@example.com"}, Vars: map[string]any{"name": "Ada"}}); err != nil {
+ t.Fatal(err)
+ }
+ if got := overridden.Messages()[0]; got.Subject != "Hello, Ada" || !strings.Contains(got.Text, "Good to see you, **Ada**.") {
+ t.Fatalf("overridden = %q %q", got.Subject, got.Text)
+ }
+}
diff --git a/modules/signpost/README.md b/modules/signpost/README.md
index 77a239e3..68441cab 100644
--- a/modules/signpost/README.md
+++ b/modules/signpost/README.md
@@ -32,57 +32,60 @@ Use cases:
A content plugin registers its types:
-```go
-package blog
-
-import (
- "context"
- "strings"
-
- "git.golem15.com/golem15/summercms/modules/pact"
-)
-
-var _ pact.HasMenuItemTypes = (*Plugin)(nil)
-
-type Plugin struct{}
-
-func (p *Plugin) MenuItemTypes() []pact.MenuItemType {
+```go src=modules/signpost/example_test.go#BlogPlugin.MenuItemTypes
+// MenuItemTypes registers acme-post, which points at one post, and
+// acme-all-posts, which lists every post. The list type names acme-post in
+// PatternFrom, so a host override of the post URL reaches its items too.
+func (p BlogPlugin) MenuItemTypes() []pact.MenuItemType {
return []pact.MenuItemType{{
Key: "acme-post",
Label: "acme.blog::lang.menuitem.post",
DefaultPattern: "/blog/:slug",
Placeholders: []string{":slug"},
- References: func(ctx context.Context) ([]pact.MenuItemReference, error) {
- return []pact.MenuItemReference{{Value: "hello-world", Label: "Hello world"}}, nil
- },
- Resolve: func(ctx context.Context, in pact.MenuItemResolve) (*pact.ResolvedMenuItem, error) {
- url := strings.ReplaceAll(in.Pattern, ":slug", in.Reference)
- return &pact.ResolvedMenuItem{
- Title: "Hello world",
- URL: url,
- Alternates: []pact.MenuItemAlternate{{Locale: "en", URL: url, Title: "Hello world"}},
- }, nil
- },
+ References: p.postReferences,
+ Resolve: p.resolvePost,
}, {
Key: "acme-all-posts",
Label: "acme.blog::lang.menuitem.all_posts",
DefaultPattern: "/blog/:slug",
PatternFrom: "acme-post",
Nesting: true,
- Resolve: resolveAllPosts,
+ DynamicItems: true,
+ Resolve: p.resolveAllPosts,
}}
}
```
A menu plugin resolves an entry and serves the reference dropdown of its form:
-```go
+```go src=modules/signpost/example_test.go#ExampleRegistry_Resolve
+app := exampleApp()
+blog := BlogPlugin{posts: []BlogPost{{Slug: "hello", Title: "Hello"}, {Slug: "again", Title: "Again"}}}
+if err := signpost.Activate(app, []BlogPlugin{blog}); err != nil {
+ fmt.Println(err)
+ return
+}
reg, _ := app.Lookup[*signpost.Registry]()
-item, err := reg.Resolve(ctx, entry.Type, entry.Reference, entry.URLPattern, true, "")
+item, err := reg.Resolve(context.Background(), "acme-all-posts", "", "", true, "")
+if err != nil {
+ fmt.Println(err)
+ return
+}
+for _, child := range item.Items {
+ fmt.Println(child.Title, child.URL)
+}
+// Output:
+// Hello /news/hello
+// Again /news/again
+```
-func (c entriesController) DependentOptions(ctx context.Context, field string, values map[string]any) (pact.DependentOptionSet, error) {
+```go src=modules/signpost/example_test.go#EntriesController.DependentOptions
+// DependentOptions serves the reference dropdown: the references of the
+// menu item type chosen in the type field, with their depth.
+func (c EntriesController) DependentOptions(ctx context.Context, field string, values map[string]any) (pact.DependentOptionSet, error) {
typ, _ := values["type"].(string)
- return signpost.ReferenceOptions(ctx, c.registry(), typ)
+ reg, _ := c.app.Lookup[*signpost.Registry]()
+ return signpost.ReferenceOptions(ctx, reg, typ)
}
```
@@ -90,38 +93,64 @@ func (c entriesController) DependentOptions(ctx context.Context, field string, v
A record type adds a `pact.ContentDescriptor`: the admin controller that edits the records, their morph type, and a `Describe` that answers each locale's URL (built from the pattern it receives, as `Resolve` builds alternates), title, description, image and word count:
-```go
-{
- Key: "acme-post",
- DefaultPattern: "/blog/:slug",
- Resolve: resolvePost,
- Content: &pact.ContentDescriptor{
- Controller: "acme.blog.posts",
- Model: "acme_blog_posts",
- Describe: func(ctx context.Context, in pact.ContentDescribe) (*pact.ContentRecord, error) {
- post, err := loadPost(ctx, in.ID)
- if err != nil || post == nil {
- return nil, err
- }
- return &pact.ContentRecord{
- ID: in.ID,
- Published: post.Published,
- Locales: []pact.ContentLocale{{
- Locale: "en",
- URL: strings.ReplaceAll(in.Pattern, ":slug", post.Slug),
- Title: post.Title,
- }},
- }, nil
+```go src=modules/signpost/example_content_test.go#NewsPlugin.MenuItemTypes
+// MenuItemTypes registers acme-article with a content descriptor: the
+// controller that edits articles, their morph type, what kind of record an
+// article is, the MCP tool that edits one, Describe and Match.
+func (p NewsPlugin) MenuItemTypes() []pact.MenuItemType {
+ return []pact.MenuItemType{{
+ Key: "acme-article",
+ Label: "acme.news::lang.menuitem.article",
+ DefaultPattern: "/news/:slug",
+ Placeholders: []string{":slug", ":id"},
+ Resolve: p.resolve,
+ Content: &pact.ContentDescriptor{
+ Controller: "acme.news.articles",
+ Model: "acme_news_articles",
+ Kind: pact.ContentKindArticle,
+ Tools: map[string]string{pact.ContentToolEdit: "acme_update_article"},
+ Describe: p.describe,
+ Match: p.match,
},
- },
+ }}
}
```
-The descriptor may also say what kind of record the type holds and which MCP tool edits one (`Kind: pact.ContentKindArticle`, `Tools: map[string]string{pact.ContentToolEdit: "acme_update_post"}`), and `Describe` may report the record's `PublishedAt`, `Parents`, `Authors` and `TopHeading`, and per locale its `Images`, `Videos` and `Headings` (see [Content descriptors](../../docs/plugins/menu-item-types.md#content-descriptors)). Every one of them is optional.
+```go src=modules/signpost/example_content_test.go#NewsPlugin.describe
+// describe answers one article per locale; the URL is built from the
+// layered pattern it receives. Besides the page defaults it reports the
+// first publication, the author and the body's heading outline, whose
+// headings start at level 2 because the page renders the title as the level-1
+// heading.
+func (p NewsPlugin) describe(_ context.Context, in pact.ContentDescribe) (*pact.ContentRecord, error) {
+ for _, a := range p.articles {
+ if a.ID != in.ID {
+ continue
+ }
+ url := strings.NewReplacer(":slug", a.Slug, ":id", a.ID).Replace(in.Pattern)
+ headings := []pact.ContentHeading{}
+ for _, h := range a.Headings {
+ headings = append(headings, pact.ContentHeading{Level: 2, Text: h})
+ }
+ published := a.PublishedAt
+ return &pact.ContentRecord{
+ ID: a.ID,
+ Published: a.Published,
+ PublishedAt: &published,
+ Authors: []pact.ContentPerson{{Name: a.Author}},
+ TopHeading: 2,
+ Locales: []pact.ContentLocale{{Locale: "en", URL: url, Title: a.Title, Headings: headings}},
+ }, nil
+ }
+ return nil, nil
+}
+```
+
+The descriptor may also say what kind of record the type holds and which MCP tool edits one (`Kind` and `Tools` above), match a public path back to a record (`Match`), and `Describe` may report the record's `PublishedAt`, `Parents`, `Authors` and `TopHeading`, and per locale its `Images`, `Videos` and `Headings` (see [Content descriptors](../../docs/plugins/menu-item-types.md#content-descriptors)). Every one of them is optional.
A consumer maps a record event to its type and reads the record's new URL:
-```go
+```go src=modules/signpost/example_content_test.go#listen
app.Events.Listen("acme.audit", func(ctx context.Context, ev *pact.RecordSaved) error {
reg, _ := app.Lookup[*signpost.Registry]()
typ, ok := reg.ContentTypeForModel(ev.Model)
@@ -132,7 +161,7 @@ app.Events.Listen("acme.audit", func(ctx context.Context, ev *pact.RecordSaved)
if err != nil || rec == nil {
return err
}
- log.Printf("%s now lives at %s", ev.ID, rec.Locales[0].URL)
+ logger.Printf("%s now lives at %s", ev.ID, rec.Locales[0].URL)
return nil
})
```
diff --git a/modules/signpost/example_content_test.go b/modules/signpost/example_content_test.go
index 42a557d9..15dbd5ec 100644
--- a/modules/signpost/example_content_test.go
+++ b/modules/signpost/example_content_test.go
@@ -1,11 +1,15 @@
package signpost_test
import (
+ "bytes"
"context"
"fmt"
+ "log"
"strings"
+ "testing"
"time"
+ "git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/pact"
"git.golem15.com/golem15/summercms/modules/signpost"
)
@@ -130,3 +134,46 @@ func ExampleRegistry_MatchPath() {
// 2026-10-01 Ada 2 2
// acme-article 7 true
}
+
+// listenForMoves registers a consumer that maps every saved record to its
+// content type and logs the record's URL.
+func listenForMoves(app *backpack.App, logger *log.Logger) {
+ // docs:start listen
+ app.Events.Listen("acme.audit", func(ctx context.Context, ev *pact.RecordSaved) error {
+ reg, _ := app.Lookup[*signpost.Registry]()
+ typ, ok := reg.ContentTypeForModel(ev.Model)
+ if !ok {
+ return nil
+ }
+ rec, err := reg.Describe(ctx, typ.Key, ev.ID, "")
+ if err != nil || rec == nil {
+ return err
+ }
+ logger.Printf("%s now lives at %s", ev.ID, rec.Locales[0].URL)
+ return nil
+ })
+ // docs:end listen
+}
+
+// TestDocsRecordListener fires record events for an article and for a model
+// no content type declares through listenForMoves.
+func TestDocsRecordListener(t *testing.T) {
+ app := exampleApp() // its menu_items.yaml overrides acme-post of BlogPlugin
+ news := NewsPlugin{articles: []Article{{ID: "7", Slug: "launch", Title: "Launch", Published: true}}}
+ if err := signpost.Activate(app, []interface{ ID() string }{BlogPlugin{}, news}); err != nil {
+ t.Fatal(err)
+ }
+ var buf bytes.Buffer
+ listenForMoves(app, log.New(&buf, "", 0))
+ for _, ev := range []*pact.RecordSaved{
+ {Model: "acme_news_articles", ID: "7"},
+ {Model: "acme_shop_orders", ID: "3"},
+ } {
+ if err := app.Events.Fire(t.Context(), ev); err != nil {
+ t.Fatal(err)
+ }
+ }
+ if got, want := buf.String(), "7 now lives at /news/launch\n"; got != want {
+ t.Fatalf("log = %q, want %q", got, want)
+ }
+}