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