docs(flare,kiosk,lagoon): compile README Go examples via src= (quick-261118-qsd)

- flare: send region run by TestDocsNotifyReply against a loopback TLS push
  service; blogSubscriptions and the publish-source region run by
  TestDocsSubscriptionSource on a Postgres container (skips under -short)
- kiosk: write, newest and client regions run by TestDocsWriteManifest (a
  copy of the literal fixture), ExampleVersionsResponse and
  TestDocsBlogReleases (httptest registry); the CheckT fence reuses
  TestPluginManifest
- lagoon: new open region run by TestDocsOpenFromApp (DocsDSN added to
  export_docs_test.go); the model, create-post, on-database, publish and
  migrations fences reuse the Database pages' targets
This commit is contained in:
Jakub Zych
2026-11-18 19:53:27 +01:00
parent d04454c57b
commit c517db564c
7 changed files with 535 additions and 63 deletions

View File

@@ -43,10 +43,10 @@ Use cases:
Send a push to one stored subscription:
```go
```go src=modules/flare/example_test.go#send
svc, err := flare.From(app)
if err != nil {
return err
return false, err
}
payload := []byte(`{"title":"New comment","body":"Someone replied to your post"}`)
err = svc.Pusher().Send(ctx, flare.Subscription{
@@ -56,24 +56,29 @@ err = svc.Pusher().Send(ctx, flare.Subscription{
}, payload, flare.SendOptions{Urgency: "normal"})
if errors.Is(err, flare.ErrSubscriptionGone) {
// The browser unsubscribed: delete the row.
return true, nil
}
```
Publish a subscription source from a plugin's `Boot`, so operator commands can read the stored subscriptions of a user:
```go
```go src=modules/flare/example_test.go#blogSubscriptions
// blogSubscriptions reads the blog's stored push subscriptions for
// operator commands such as websockets:test-push.
type blogSubscriptions struct{ db *gorm.DB }
```
```go src=modules/flare/example_test.go#blogSubscriptions.Subscriptions
func (s blogSubscriptions) Subscriptions(ctx context.Context, userID uint) ([]flare.SubscriptionInfo, error) {
var user models.User
var user User
if err := s.db.WithContext(ctx).First(&user, userID).Error; err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, flare.ErrUserNotFound
}
return nil, err
}
var rows []models.PushSubscription
if err := s.db.WithContext(ctx).Where("user_id = ?", userID).Find(&rows).Error; err != nil {
var rows []PushSubscription
if err := s.db.WithContext(ctx).Where("user_id = ?", userID).Order("id").Find(&rows).Error; err != nil {
return nil, err
}
out := make([]flare.SubscriptionInfo, 0, len(rows))
@@ -87,8 +92,9 @@ func (s blogSubscriptions) Subscriptions(ctx context.Context, userID uint) ([]fl
}
return out, nil
}
```
// In Boot:
```go src=modules/flare/example_test.go#publish-source
if err := app.Publish[flare.SubscriptionSource](blogSubscriptions{db: gdb}); err != nil {
return err
}
@@ -148,4 +154,4 @@ Both commands print their own failure messages and return `bonfire.Reported` err
go test ./modules/flare/...
```
`TestRFC8291AppendixA` fixes the RFC's salt and application server key and compares the output with the RFC's published bytes. The send tests run an `httptest.NewTLSServer` push service with `127.0.0.1` in the allowlist; it verifies the VAPID token with the key from `k=` and decrypts the body as a browser would. Pass the test server's client to `flare.NewVAPIDPusher` or `flare.Service.SetHTTPClient` so it trusts the test certificate.
`TestRFC8291AppendixA` fixes the RFC's salt and application server key and compares the output with the RFC's published bytes. The send tests run an `httptest.NewTLSServer` push service with `127.0.0.1` in the allowlist; it verifies the VAPID token with the key from `k=` and decrypts the body as a browser would. Pass the test server's client to `flare.NewVAPIDPusher` or `flare.Service.SetHTTPClient` so it trusts the test certificate. `TestDocsSubscriptionSource` runs the subscription source shown above on a Postgres container and skips under `-short`.

View File

@@ -4,15 +4,24 @@ import (
"context"
"crypto/ecdh"
"crypto/rand"
"database/sql"
"encoding/base64"
"errors"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/compass"
"git.golem15.com/golem15/summercms/modules/flare"
"git.golem15.com/golem15/summercms/modules/lagoon"
_ "github.com/jackc/pgx/v5/stdlib"
"github.com/testcontainers/testcontainers-go"
"github.com/testcontainers/testcontainers-go/modules/postgres"
"gorm.io/gorm"
)
// browserSubscription stands in for the PushSubscription a browser posts to
@@ -110,3 +119,192 @@ func ExampleHostAllowed() {
// push.apple.com false
// evil.example false
}
// User is the blog's user model, as much as the examples need.
type User struct {
ID uint `gorm:"column:id;primaryKey"`
}
func (User) TableName() string { return "acme_blog_users" }
// PushSubscription is a browser push subscription the blog stored.
type PushSubscription struct {
ID uint `gorm:"column:id;primaryKey"`
UserID uint `gorm:"column:user_id"`
Endpoint string `gorm:"column:endpoint"`
P256dh string `gorm:"column:p256dh"`
Auth string `gorm:"column:auth"`
UserAgent string `gorm:"column:user_agent"`
CreatedAt time.Time `gorm:"column:created_at"`
}
func (PushSubscription) TableName() string { return "acme_blog_push_subscriptions" }
// notifyReply pushes a reply notice to one stored subscription and reports
// whether the browser dropped it.
func notifyReply(ctx context.Context, app *backpack.App, row PushSubscription) (gone bool, err error) {
// docs:start send
svc, err := flare.From(app)
if err != nil {
return false, err
}
payload := []byte(`{"title":"New comment","body":"Someone replied to your post"}`)
err = svc.Pusher().Send(ctx, flare.Subscription{
Endpoint: row.Endpoint,
P256dh: row.P256dh,
Auth: row.Auth,
}, payload, flare.SendOptions{Urgency: "normal"})
if errors.Is(err, flare.ErrSubscriptionGone) {
// The browser unsubscribed: delete the row.
return true, nil
}
// docs:end send
return false, err
}
// TestDocsNotifyReply runs notifyReply on an app whose push.* config allows
// a stand-in push service on loopback.
func TestDocsNotifyReply(t *testing.T) {
push := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/gone" {
w.WriteHeader(http.StatusGone)
return
}
w.WriteHeader(http.StatusCreated)
}))
defer push.Close()
keys, err := flare.GenerateVAPIDKeys()
if err != nil {
t.Fatal(err)
}
cfg, err := compass.Open(compass.Options{Dir: t.TempDir(), Environ: []string{}})
if err != nil {
t.Fatal(err)
}
for k, v := range map[string]any{
"push.enabled": true,
"push.public_key": keys.PublicKey,
"push.private_key": keys.PrivateKey,
"push.subject": "mailto:admin@example.com",
"push.allowed_hosts": []string{"127.0.0.1"},
} {
if err := cfg.Set(k, v); err != nil {
t.Fatal(err)
}
}
app := backpack.New(cfg)
svc, err := flare.From(app)
if err != nil {
t.Fatal(err)
}
svc.SetHTTPClient(push.Client()) // trust the test server's certificate
for path, wantGone := range map[string]bool{"/live": false, "/gone": true} {
sub, err := browserSubscription(push.URL + path)
if err != nil {
t.Fatal(err)
}
gone, err := notifyReply(t.Context(), app, PushSubscription{Endpoint: sub.Endpoint, P256dh: sub.P256dh, Auth: sub.Auth})
if err != nil || gone != wantGone {
t.Fatalf("%s: gone = %v, %v", path, gone, err)
}
}
}
// blogSubscriptions reads the blog's stored push subscriptions for
// operator commands such as websockets:test-push.
type blogSubscriptions struct{ db *gorm.DB }
func (s blogSubscriptions) Subscriptions(ctx context.Context, userID uint) ([]flare.SubscriptionInfo, error) {
var user User
if err := s.db.WithContext(ctx).First(&user, userID).Error; err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, flare.ErrUserNotFound
}
return nil, err
}
var rows []PushSubscription
if err := s.db.WithContext(ctx).Where("user_id = ?", userID).Order("id").Find(&rows).Error; err != nil {
return nil, err
}
out := make([]flare.SubscriptionInfo, 0, len(rows))
for _, r := range rows {
out = append(out, flare.SubscriptionInfo{
Subscription: flare.Subscription{Endpoint: r.Endpoint, P256dh: r.P256dh, Auth: r.Auth},
ID: r.ID,
UserAgent: r.UserAgent,
SubscribedAt: &r.CreatedAt,
})
}
return out, nil
}
// publishSubscriptions is the part of the blog plugin's Boot that hands
// its subscriptions to flare.
func publishSubscriptions(app *backpack.App, gdb *gorm.DB) error {
// docs:start publish-source
if err := app.Publish[flare.SubscriptionSource](blogSubscriptions{db: gdb}); err != nil {
return err
}
// docs:end publish-source
return nil
}
// TestDocsSubscriptionSource runs blogSubscriptions on a Postgres container:
// the published source lists a user's subscriptions and reports an unknown
// user as flare.ErrUserNotFound. It needs Docker and skips under -short.
func TestDocsSubscriptionSource(t *testing.T) {
if testing.Short() {
t.Skip("needs Docker (Postgres)")
}
ctx := t.Context()
ctr, err := postgres.Run(ctx, "postgres:16-alpine",
postgres.WithDatabase("flare"), postgres.WithUsername("flare"), postgres.WithPassword("flare"),
postgres.BasicWaitStrategies())
testcontainers.CleanupContainer(t, ctr)
if err != nil {
t.Fatal(err)
}
dsn, err := ctr.ConnectionString(ctx, "sslmode=disable")
if err != nil {
t.Fatal(err)
}
sqlDB, err := sql.Open("pgx", dsn)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = sqlDB.Close() })
gdb, err := lagoon.Use(ctx, sqlDB)
if err != nil {
t.Fatal(err)
}
for _, stmt := range []string{
`CREATE TABLE acme_blog_users (id SERIAL PRIMARY KEY)`,
`CREATE TABLE acme_blog_push_subscriptions (id SERIAL PRIMARY KEY, user_id INTEGER NOT NULL, endpoint TEXT NOT NULL,
p256dh TEXT NOT NULL, auth TEXT NOT NULL, user_agent TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL)`,
`INSERT INTO acme_blog_users (id) VALUES (7)`,
`INSERT INTO acme_blog_push_subscriptions (user_id, endpoint, p256dh, auth, user_agent, created_at) VALUES
(7, 'https://fcm.googleapis.com/fcm/send/a', 'p1', 'a1', 'Firefox', now()),
(7, 'https://fcm.googleapis.com/fcm/send/b', 'p2', 'a2', 'Chrome', now())`,
} {
if err := gdb.Exec(stmt).Error; err != nil {
t.Fatal(err)
}
}
app := backpack.New(nil)
if err := publishSubscriptions(app, gdb); err != nil {
t.Fatal(err)
}
source, ok := app.Lookup[flare.SubscriptionSource]()
if !ok {
t.Fatal("no flare.SubscriptionSource published")
}
subs, err := source.Subscriptions(ctx, 7)
if err != nil || len(subs) != 2 || subs[0].UserAgent != "Firefox" || subs[1].Endpoint != "https://fcm.googleapis.com/fcm/send/b" || subs[0].SubscribedAt == nil {
t.Fatalf("Subscriptions(7) = %+v, %v", subs, err)
}
if _, err := source.Subscriptions(ctx, 8); !errors.Is(err, flare.ErrUserNotFound) {
t.Fatalf("Subscriptions(8) error = %v, want ErrUserNotFound", err)
}
}

View File

@@ -26,8 +26,10 @@ WinterCMS keeps this data in a plugin's `Plugin.php` `pluginDetails()` and in `c
## Usage
```go
path, warnings, err := kiosk.Write(ctx, "plugins/acme/blog", kiosk.DeriveOptions{})
Regenerating the manifest of a plugin directory (plugins/acme/blog, say) and checking it:
```go src=modules/kiosk/example_test.go#write
path, warnings, err := kiosk.Write(ctx, dir, kiosk.DeriveOptions{})
if err != nil {
return err
}
@@ -36,7 +38,7 @@ for _, w := range warnings {
}
fmt.Println("wrote", path)
if err := kiosk.Check(ctx, "plugins/acme/blog"); err != nil {
if err := kiosk.Check(ctx, dir); err != nil {
var stale *kiosk.StaleError
if errors.As(err, &stale) {
fmt.Printf("expected:\n%s", stale.Want)
@@ -47,7 +49,7 @@ if err := kiosk.Check(ctx, "plugins/acme/blog"); err != nil {
Picking the newest release of a plugin that an application on framework v0.6.2 can install:
```go
```go src=modules/kiosk/example_test.go#newest
var versions kiosk.VersionsResponse
if err := json.Unmarshal(body, &versions); err != nil {
return err
@@ -61,25 +63,28 @@ fmt.Println("go get", v.Module+"@"+v.Version)
Asking the configured registry for a plugin's releases:
```go
```go src=modules/kiosk/example_test.go#client
client, err := kiosk.NewClient(kiosk.RegistryURL(app.Config), app.Config)
if errors.Is(err, kiosk.ErrRegistryDisabled) {
return nil // plugins.registry_url is empty: no registry calls
return nil, nil // plugins.registry_url is empty: no registry calls
}
if err != nil {
return err
return nil, err
}
versions, err := client.Versions(ctx, "acme.blog")
if errors.Is(err, kiosk.ErrNotFound) {
return fmt.Errorf("acme.blog is not listed")
return nil, fmt.Errorf("acme.blog is not listed")
}
```
A plugin repository keeps its manifest current with one test:
```go
```go src=modules/kiosk/checkt_test.go#TestPluginManifest
// TestPluginManifest is the test a plugin repository adds next to its
// plugin.go, with "." as the directory. Here it guards the committed
// manifest of the literal fixture.
func TestPluginManifest(t *testing.T) {
kiosk.CheckT(t, ".")
kiosk.CheckT(t, "testdata/literal")
}
```

View File

@@ -1,8 +1,19 @@
package kiosk_test
import (
"context"
"encoding/json"
"errors"
"fmt"
"log"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"testing"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/compass"
"git.golem15.com/golem15/summercms/modules/kiosk"
)
@@ -55,3 +66,143 @@ func ExampleNewestCompatible() {
// v0.7.0 v0.3.0 true
// v0.4.0 false
}
// writeManifest regenerates the plugin.yaml of the plugin in dir and checks
// that the committed file is current.
func writeManifest(ctx context.Context, dir string) error {
// docs:start write
path, warnings, err := kiosk.Write(ctx, dir, kiosk.DeriveOptions{})
if err != nil {
return err
}
for _, w := range warnings {
log.Println(w)
}
fmt.Println("wrote", path)
if err := kiosk.Check(ctx, dir); err != nil {
var stale *kiosk.StaleError
if errors.As(err, &stale) {
fmt.Printf("expected:\n%s", stale.Want)
}
return err
}
// docs:end write
return nil
}
// TestDocsWriteManifest runs writeManifest on a copy of the literal fixture
// plugin without its plugin.yaml and compares the result with the
// committed one.
func TestDocsWriteManifest(t *testing.T) {
dir := t.TempDir()
if err := os.CopyFS(dir, os.DirFS("testdata/literal")); err != nil {
t.Fatal(err)
}
if err := os.Remove(filepath.Join(dir, kiosk.FileName)); err != nil {
t.Fatal(err)
}
if err := writeManifest(t.Context(), dir); err != nil {
t.Fatal(err)
}
got, err := os.ReadFile(filepath.Join(dir, kiosk.FileName))
if err != nil {
t.Fatal(err)
}
want, err := os.ReadFile(filepath.Join("testdata", "literal", kiosk.FileName))
if err != nil {
t.Fatal(err)
}
if string(got) != string(want) {
t.Fatalf("plugin.yaml =\n%s\nwant\n%s", got, want)
}
}
// pickRelease prints the go get line of the newest release in a registry
// versions answer that an application on framework v0.6.2 can install.
func pickRelease(body []byte) error {
// docs:start newest
var versions kiosk.VersionsResponse
if err := json.Unmarshal(body, &versions); err != nil {
return err
}
v, ok := kiosk.NewestCompatible(versions.Data, "v0.6.2")
if !ok {
return errors.New("every release needs a newer framework")
}
fmt.Println("go get", v.Module+"@"+v.Version)
// docs:end newest
return nil
}
func ExampleVersionsResponse() {
// The body of GET {registry}/api/v1/plugins/acme.blog/versions.
body := []byte(`{"data":[
{"version":"v0.3.0","framework":"v0.7.0","module":"example.test/sm-blog-plugin"},
{"version":"v0.2.1","framework":"v0.6.0","module":"example.test/sm-blog-plugin"}
]}`)
if err := pickRelease(body); err != nil {
fmt.Println(err)
}
if err := pickRelease([]byte(`{"data":[{"version":"v0.3.0","framework":"v0.7.0"}]}`)); err != nil {
fmt.Println(err)
}
// Output:
// go get example.test/sm-blog-plugin@v0.2.1
// every release needs a newer framework
}
// blogReleases asks the configured registry for the releases of acme.blog.
func blogReleases(ctx context.Context, app *backpack.App) ([]kiosk.RegistryVersion, error) {
// docs:start client
client, err := kiosk.NewClient(kiosk.RegistryURL(app.Config), app.Config)
if errors.Is(err, kiosk.ErrRegistryDisabled) {
return nil, nil // plugins.registry_url is empty: no registry calls
}
if err != nil {
return nil, err
}
versions, err := client.Versions(ctx, "acme.blog")
if errors.Is(err, kiosk.ErrNotFound) {
return nil, fmt.Errorf("acme.blog is not listed")
}
// docs:end client
return versions, err
}
// TestDocsBlogReleases runs blogReleases against a stand-in registry, with
// the registry disabled, and against a registry that does not list the
// plugin.
func TestDocsBlogReleases(t *testing.T) {
listed := true
registry := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !listed || r.URL.Path != kiosk.RegistryAPIPath+"/plugins/acme.blog/versions" {
w.WriteHeader(http.StatusNotFound)
return
}
_ = json.NewEncoder(w).Encode(kiosk.VersionsResponse{Data: []kiosk.RegistryVersion{{Version: "v0.2.1", Framework: "v0.6.0"}}})
}))
defer registry.Close()
appWith := func(url string) *backpack.App {
cfg, err := compass.Open(compass.Options{Dir: t.TempDir(), Environ: []string{}})
if err != nil {
t.Fatal(err)
}
if err := cfg.Set("plugins.registry_url", url); err != nil {
t.Fatal(err)
}
return backpack.New(cfg)
}
versions, err := blogReleases(t.Context(), appWith(registry.URL))
if err != nil || len(versions) != 1 || versions[0].Version != "v0.2.1" {
t.Fatalf("releases = %+v, %v", versions, err)
}
if versions, err := blogReleases(t.Context(), appWith("")); err != nil || versions != nil {
t.Fatalf("disabled registry = %+v, %v", versions, err)
}
listed = false
if _, err := blogReleases(t.Context(), appWith(registry.URL)); err == nil || err.Error() != "acme.blog is not listed" {
t.Fatalf("unlisted plugin = %v", err)
}
}

View File

@@ -48,7 +48,7 @@ Use cases:
Open the shared pool once at boot and publish it, so plugins and handlers reuse the same handles:
```go
```go src=modules/lagoon/example_test.go#open
sqlDB, gdb, err := lagoon.OpenFromApp(ctx, app)
if err != nil {
return err
@@ -58,68 +58,123 @@ if err := lagoon.Publish(app, sqlDB, gdb); err != nil {
}
```
A model uses the column types and helpers directly:
A model uses the column types directly, and a handler validates and mass-assigns input through the helpers:
```go
```go src=modules/lagoon/example_test.go#Post
// Post is the acme.blog post model: a plain GORM struct with lagoon column
// types.
type Post struct {
ID uint `gorm:"column:id;primaryKey"`
Title string `gorm:"column:title"`
Tags lagoon.Jsonable[[]string] `gorm:"column:tags"`
APIToken lagoon.Encrypted `gorm:"column:api_token"`
}
ID uint `gorm:"column:id;primaryKey" json:"id"`
Title string `gorm:"column:title" json:"title"`
Slug string `gorm:"column:slug" json:"slug"`
Views int `gorm:"column:views" json:"views"`
Tags lagoon.Jsonable[[]string] `gorm:"column:tags" json:"-"`
APIToken lagoon.Encrypted `gorm:"column:api_token" json:"-"`
DeletedAt gorm.DeletedAt `gorm:"column:deleted_at" json:"-"`
func (Post) Fillable() []string { return []string{"title"} }
func createPost(ctx context.Context, gdb *gorm.DB, tr *phrasebook.Translator, input map[string]any) (map[string][]string, error) {
var post Post
rules := map[string]string{"title": "required|max:255|unique:posts"}
if errs, err := lagoon.Validate(ctx, gdb, &post, rules, input, tr); err != nil || errs != nil {
return errs, err
}
if err := lagoon.Fill(&post, post.Fillable(), input, false); err != nil {
return nil, err
}
post.APIToken = lagoon.NewEncrypted("change-me")
return nil, gdb.Create(&post).Error
Categories []Category `gorm:"many2many:acme_blog_post_categories" json:"-"`
}
```
```go src=modules/lagoon/example_test.go#Post.Fillable
// Fillable is the Go form of $fillable: the keys mass assignment may set.
func (Post) Fillable() []string { return []string{"title", "views"} }
```
```go src=modules/lagoon/example_test.go#create-post
rules := map[string]string{
"title": "required|max:255|unique:acme_blog_posts",
"views": "nullable|integer|min:0",
}
var post Post
errs, err := lagoon.Validate(ctx, db, &post, rules, input, nil)
if err != nil || errs != nil {
return nil, errs, err
}
if err := lagoon.Fill(&post, post.Fillable(), input, false); err != nil {
return nil, nil, err
}
if err := db.WithContext(ctx).Create(&post).Error; err != nil {
return nil, nil, err
}
return &post, nil, nil
```
A plugin registers its GORM callbacks from Boot through `lagoon.OnDatabase`, so they are installed whenever the database is published, and defers side effects until the write commits. Register the callback before GORM's `gorm:commit_or_rollback_transaction` step: lagoon runs a single-statement write's after-commit work from `lagoon:after_commit` right after that step, so work buffered by a callback GORM sorts later never runs, and `lagoon.AfterCommit` logs a warning for it (see [Callbacks registered at boot](../../docs/database/transactions.md#callbacks-registered-at-boot)):
```go
func (p *Plugin) Boot(app *backpack.App) error {
return lagoon.OnDatabase(app, func(_ *sql.DB, gdb *gorm.DB) error {
return gdb.Callback().Create().After("gorm:create").Before("gorm:commit_or_rollback_transaction").Register("acme:post_created", func(db *gorm.DB) {
if db.Error != nil {
return
}
lagoon.AfterCommit(db.Statement.Context, db, func(ctx context.Context, db *gorm.DB) {
// runs only once the insert is committed
})
```go src=modules/lagoon/example_test.go#on-database
return lagoon.OnDatabase(app, func(_ *sql.DB, gdb *gorm.DB) error {
return gdb.Callback().Create().After("gorm:create").Before("gorm:commit_or_rollback_transaction").Register("acme:post_created", func(db *gorm.DB) {
post, ok := db.Statement.Dest.(*Post)
if db.Error != nil || !ok {
return
}
lagoon.AfterCommit(db.Statement.Context, db, func(ctx context.Context, db *gorm.DB) {
*log = append(*log, "created "+post.Slug) // runs only once the insert is committed
})
})
}
})
```
func publish(ctx context.Context, gdb *gorm.DB, post *Post) error {
return lagoon.Transaction(ctx, gdb, func(ctx context.Context, tx *gorm.DB) error {
return tx.Create(post).Error // acme:post_created work waits for this commit
```go src=modules/lagoon/example_test.go#publish
return lagoon.Transaction(ctx, db, func(ctx context.Context, tx *gorm.DB) error {
if err := tx.Model(&Post{}).Where("id = ?", id).Update("title", "Published").Error; err != nil {
return err
}
lagoon.AfterCommit(ctx, tx, func(ctx context.Context, db *gorm.DB) {
*log = append(*log, fmt.Sprintf("post %d published", id)) // broadcast, index, send mail...
})
}
if fail {
return errors.New("rolled back") // the AfterCommit work never runs
}
return nil
})
```
A plugin ships its schema as an ordered gormigrate set; `migrate` runs it after the framework sets:
```go
func (p *Plugin) Migrations() []*gormigrate.Migration {
return []*gormigrate.Migration{{
ID: "202601010001_create_posts",
Migrate: func(tx *gorm.DB) error {
return tx.Exec(`CREATE TABLE posts (id SERIAL PRIMARY KEY, title TEXT NOT NULL, tags TEXT, api_token TEXT)`).Error
```go src=modules/lagoon/example_test.go#BlogPlugin.Migrations
// Migrations returns the plugin's schema as an ordered gormigrate set. In a
// scaffolded plugin each migration is a file in updates/ and this list is
// generated in file name order.
func (p *BlogPlugin) Migrations() []*gormigrate.Migration {
return []*gormigrate.Migration{
{
ID: "20260101000100_create_posts",
Migrate: func(tx *gorm.DB) error {
return tx.Exec(`CREATE TABLE acme_blog_posts (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
slug TEXT NOT NULL,
views INTEGER NOT NULL DEFAULT 0,
tags TEXT,
api_token TEXT,
deleted_at TIMESTAMPTZ
)`).Error
},
Rollback: func(tx *gorm.DB) error {
return tx.Exec(`DROP TABLE IF EXISTS acme_blog_posts`).Error
},
},
Rollback: func(tx *gorm.DB) error {
return tx.Exec(`DROP TABLE IF EXISTS posts`).Error
{
ID: "20260101000200_create_comments_and_categories",
Migrate: func(tx *gorm.DB) error {
for _, stmt := range []string{
`CREATE TABLE acme_blog_comments (id SERIAL PRIMARY KEY, post_id INTEGER NOT NULL, body TEXT NOT NULL, deleted_at TIMESTAMPTZ)`,
`CREATE TABLE acme_blog_categories (id SERIAL PRIMARY KEY, name TEXT NOT NULL)`,
`CREATE TABLE acme_blog_post_categories (post_id INTEGER NOT NULL, category_id INTEGER NOT NULL, sort_order INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (post_id, category_id))`,
} {
if err := tx.Exec(stmt).Error; err != nil {
return err
}
}
return nil
},
Rollback: func(tx *gorm.DB) error {
return tx.Exec(`DROP TABLE IF EXISTS acme_blog_post_categories, acme_blog_categories, acme_blog_comments`).Error
},
},
}}
}
}
```

View File

@@ -3,6 +3,7 @@ package lagoon_test
import (
"context"
"database/sql"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
@@ -10,6 +11,7 @@ import (
"testing"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/compass"
"git.golem15.com/golem15/summercms/modules/lagoon"
"git.golem15.com/golem15/summercms/modules/pact"
"git.golem15.com/golem15/summercms/modules/party"
@@ -645,3 +647,49 @@ func TestDocsModelDeclarations(t *testing.T) {
t.Fatalf("Migrations() = %d, want 2", n)
}
}
// openDatabase opens the shared pool from the app's config at boot and
// publishes it, so plugins and handlers reuse the same handles.
func openDatabase(ctx context.Context, app *backpack.App) error {
// docs:start open
sqlDB, gdb, err := lagoon.OpenFromApp(ctx, app)
if err != nil {
return err
}
if err := lagoon.Publish(app, sqlDB, gdb); err != nil {
return err
}
// docs:end open
return nil
}
// TestDocsOpenFromApp runs the open region on a config whose database.dsn
// and app.key come from the environment.
func TestDocsOpenFromApp(t *testing.T) {
dsn := lagoon.DocsDSN(t, "docs_open")
key := base64.StdEncoding.EncodeToString([]byte("0123456789abcdef0123456789abcdef"))
cfg, err := compass.Open(compass.Options{Dir: t.TempDir(), Environ: []string{
"SUMMER_DATABASE__DSN=" + dsn,
"SUMMER_APP__KEY=" + key,
}})
if err != nil {
t.Fatal(err)
}
app := backpack.New(cfg)
if err := openDatabase(t.Context(), app); err != nil {
t.Fatal(err)
}
sqlDB, ok := app.Lookup[*sql.DB]()
if !ok {
t.Fatal("no *sql.DB published")
}
t.Cleanup(func() { _ = sqlDB.Close() })
gdb, ok := app.Lookup[*gorm.DB]()
if !ok {
t.Fatal("no *gorm.DB published")
}
var one int
if err := gdb.WithContext(t.Context()).Raw(`SELECT 1`).Scan(&one).Error; err != nil || one != 1 {
t.Fatalf("SELECT 1 = %d, %v", one, err)
}
}

View File

@@ -19,3 +19,12 @@ func DocsDB(t *testing.T, name string) *gorm.DB {
}
return gdb
}
// DocsDSN returns the DSN of a fresh database named name in this package's
// Postgres harness, for the docs example that opens the pool from config.
// It skips under -short like DocsDB.
func DocsDSN(t *testing.T, name string) string {
t.Helper()
_, dsn := dedicatedDB(t, name)
return dsn
}