diff --git a/modules/flare/README.md b/modules/flare/README.md index 017c39d9..5cba6e36 100644 --- a/modules/flare/README.md +++ b/modules/flare/README.md @@ -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`. diff --git a/modules/flare/example_test.go b/modules/flare/example_test.go index ea3a5962..b64278e2 100644 --- a/modules/flare/example_test.go +++ b/modules/flare/example_test.go @@ -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) + } +} diff --git a/modules/kiosk/README.md b/modules/kiosk/README.md index 2247b9e0..5064dbe1 100644 --- a/modules/kiosk/README.md +++ b/modules/kiosk/README.md @@ -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") } ``` diff --git a/modules/kiosk/example_test.go b/modules/kiosk/example_test.go index a857ac7b..5009cd7f 100644 --- a/modules/kiosk/example_test.go +++ b/modules/kiosk/example_test.go @@ -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) + } +} diff --git a/modules/lagoon/README.md b/modules/lagoon/README.md index 35547d91..14120ec8 100644 --- a/modules/lagoon/README.md +++ b/modules/lagoon/README.md @@ -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 + }, }, - }} + } } ``` diff --git a/modules/lagoon/example_test.go b/modules/lagoon/example_test.go index 2e0573b8..c65ba6ea 100644 --- a/modules/lagoon/example_test.go +++ b/modules/lagoon/example_test.go @@ -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) + } +} diff --git a/modules/lagoon/export_docs_test.go b/modules/lagoon/export_docs_test.go index e098cdb4..cf2b2508 100644 --- a/modules/lagoon/export_docs_test.go +++ b/modules/lagoon/export_docs_test.go @@ -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 +}