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:
|
Send a push to one stored subscription:
|
||||||
|
|
||||||
```go
|
```go src=modules/flare/example_test.go#send
|
||||||
svc, err := flare.From(app)
|
svc, err := flare.From(app)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return err
|
return false, err
|
||||||
}
|
}
|
||||||
payload := []byte(`{"title":"New comment","body":"Someone replied to your post"}`)
|
payload := []byte(`{"title":"New comment","body":"Someone replied to your post"}`)
|
||||||
err = svc.Pusher().Send(ctx, flare.Subscription{
|
err = svc.Pusher().Send(ctx, flare.Subscription{
|
||||||
@@ -56,24 +56,29 @@ err = svc.Pusher().Send(ctx, flare.Subscription{
|
|||||||
}, payload, flare.SendOptions{Urgency: "normal"})
|
}, payload, flare.SendOptions{Urgency: "normal"})
|
||||||
if errors.Is(err, flare.ErrSubscriptionGone) {
|
if errors.Is(err, flare.ErrSubscriptionGone) {
|
||||||
// The browser unsubscribed: delete the row.
|
// 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:
|
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 }
|
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) {
|
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 err := s.db.WithContext(ctx).First(&user, userID).Error; err != nil {
|
||||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||||
return nil, flare.ErrUserNotFound
|
return nil, flare.ErrUserNotFound
|
||||||
}
|
}
|
||||||
return nil, err
|
return nil, err
|
||||||
}
|
}
|
||||||
var rows []models.PushSubscription
|
var rows []PushSubscription
|
||||||
if err := s.db.WithContext(ctx).Where("user_id = ?", userID).Find(&rows).Error; err != nil {
|
if err := s.db.WithContext(ctx).Where("user_id = ?", userID).Order("id").Find(&rows).Error; err != nil {
|
||||||
return nil, err
|
return nil, err
|
||||||
}
|
}
|
||||||
out := make([]flare.SubscriptionInfo, 0, len(rows))
|
out := make([]flare.SubscriptionInfo, 0, len(rows))
|
||||||
@@ -87,8 +92,9 @@ func (s blogSubscriptions) Subscriptions(ctx context.Context, userID uint) ([]fl
|
|||||||
}
|
}
|
||||||
return out, nil
|
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 {
|
if err := app.Publish[flare.SubscriptionSource](blogSubscriptions{db: gdb}); err != nil {
|
||||||
return err
|
return err
|
||||||
}
|
}
|
||||||
@@ -148,4 +154,4 @@ Both commands print their own failure messages and return `bonfire.Reported` err
|
|||||||
go test ./modules/flare/...
|
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"
|
"context"
|
||||||
"crypto/ecdh"
|
"crypto/ecdh"
|
||||||
"crypto/rand"
|
"crypto/rand"
|
||||||
|
"database/sql"
|
||||||
"encoding/base64"
|
"encoding/base64"
|
||||||
"errors"
|
"errors"
|
||||||
"fmt"
|
"fmt"
|
||||||
"net/http"
|
"net/http"
|
||||||
"net/http/httptest"
|
"net/http/httptest"
|
||||||
"strings"
|
"strings"
|
||||||
|
"testing"
|
||||||
"time"
|
"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/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
|
// browserSubscription stands in for the PushSubscription a browser posts to
|
||||||
@@ -110,3 +119,192 @@ func ExampleHostAllowed() {
|
|||||||
// push.apple.com false
|
// push.apple.com false
|
||||||
// evil.example 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
|
## Usage
|
||||||
|
|
||||||
```go
|
Regenerating the manifest of a plugin directory (plugins/acme/blog, say) and checking it:
|
||||||
path, warnings, err := kiosk.Write(ctx, "plugins/acme/blog", kiosk.DeriveOptions{})
|
|
||||||
|
```go src=modules/kiosk/example_test.go#write
|
||||||
|
path, warnings, err := kiosk.Write(ctx, dir, kiosk.DeriveOptions{})
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return err
|
return err
|
||||||
}
|
}
|
||||||
@@ -36,7 +38,7 @@ for _, w := range warnings {
|
|||||||
}
|
}
|
||||||
fmt.Println("wrote", path)
|
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
|
var stale *kiosk.StaleError
|
||||||
if errors.As(err, &stale) {
|
if errors.As(err, &stale) {
|
||||||
fmt.Printf("expected:\n%s", stale.Want)
|
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:
|
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
|
var versions kiosk.VersionsResponse
|
||||||
if err := json.Unmarshal(body, &versions); err != nil {
|
if err := json.Unmarshal(body, &versions); err != nil {
|
||||||
return err
|
return err
|
||||||
@@ -61,25 +63,28 @@ fmt.Println("go get", v.Module+"@"+v.Version)
|
|||||||
|
|
||||||
Asking the configured registry for a plugin's releases:
|
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)
|
client, err := kiosk.NewClient(kiosk.RegistryURL(app.Config), app.Config)
|
||||||
if errors.Is(err, kiosk.ErrRegistryDisabled) {
|
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 {
|
if err != nil {
|
||||||
return err
|
return nil, err
|
||||||
}
|
}
|
||||||
versions, err := client.Versions(ctx, "acme.blog")
|
versions, err := client.Versions(ctx, "acme.blog")
|
||||||
if errors.Is(err, kiosk.ErrNotFound) {
|
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:
|
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) {
|
func TestPluginManifest(t *testing.T) {
|
||||||
kiosk.CheckT(t, ".")
|
kiosk.CheckT(t, "testdata/literal")
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -1,8 +1,19 @@
|
|||||||
package kiosk_test
|
package kiosk_test
|
||||||
|
|
||||||
import (
|
import (
|
||||||
|
"context"
|
||||||
|
"encoding/json"
|
||||||
|
"errors"
|
||||||
"fmt"
|
"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"
|
"git.golem15.com/golem15/summercms/modules/kiosk"
|
||||||
)
|
)
|
||||||
|
|
||||||
@@ -55,3 +66,143 @@ func ExampleNewestCompatible() {
|
|||||||
// v0.7.0 v0.3.0 true
|
// v0.7.0 v0.3.0 true
|
||||||
// v0.4.0 false
|
// 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:
|
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)
|
sqlDB, gdb, err := lagoon.OpenFromApp(ctx, app)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return err
|
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 {
|
type Post struct {
|
||||||
ID uint `gorm:"column:id;primaryKey"`
|
ID uint `gorm:"column:id;primaryKey" json:"id"`
|
||||||
Title string `gorm:"column:title"`
|
Title string `gorm:"column:title" json:"title"`
|
||||||
Tags lagoon.Jsonable[[]string] `gorm:"column:tags"`
|
Slug string `gorm:"column:slug" json:"slug"`
|
||||||
APIToken lagoon.Encrypted `gorm:"column:api_token"`
|
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"} }
|
Categories []Category `gorm:"many2many:acme_blog_post_categories" json:"-"`
|
||||||
|
|
||||||
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
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
```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)):
|
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
|
```go src=modules/lagoon/example_test.go#on-database
|
||||||
func (p *Plugin) Boot(app *backpack.App) error {
|
return lagoon.OnDatabase(app, func(_ *sql.DB, gdb *gorm.DB) 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) {
|
||||||
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 {
|
if db.Error != nil || !ok {
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
lagoon.AfterCommit(db.Statement.Context, db, func(ctx context.Context, db *gorm.DB) {
|
lagoon.AfterCommit(db.Statement.Context, db, func(ctx context.Context, db *gorm.DB) {
|
||||||
// runs only once the insert is committed
|
*log = append(*log, "created "+post.Slug) // runs only once the insert is committed
|
||||||
})
|
|
||||||
})
|
})
|
||||||
})
|
})
|
||||||
}
|
})
|
||||||
|
```
|
||||||
|
|
||||||
func publish(ctx context.Context, gdb *gorm.DB, post *Post) error {
|
```go src=modules/lagoon/example_test.go#publish
|
||||||
return lagoon.Transaction(ctx, gdb, func(ctx context.Context, tx *gorm.DB) error {
|
return lagoon.Transaction(ctx, db, func(ctx context.Context, tx *gorm.DB) error {
|
||||||
return tx.Create(post).Error // acme:post_created work waits for this commit
|
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:
|
A plugin ships its schema as an ordered gormigrate set; `migrate` runs it after the framework sets:
|
||||||
|
|
||||||
```go
|
```go src=modules/lagoon/example_test.go#BlogPlugin.Migrations
|
||||||
func (p *Plugin) Migrations() []*gormigrate.Migration {
|
// Migrations returns the plugin's schema as an ordered gormigrate set. In a
|
||||||
return []*gormigrate.Migration{{
|
// scaffolded plugin each migration is a file in updates/ and this list is
|
||||||
ID: "202601010001_create_posts",
|
// generated in file name order.
|
||||||
Migrate: func(tx *gorm.DB) error {
|
func (p *BlogPlugin) Migrations() []*gormigrate.Migration {
|
||||||
return tx.Exec(`CREATE TABLE posts (id SERIAL PRIMARY KEY, title TEXT NOT NULL, tags TEXT, api_token TEXT)`).Error
|
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 (
|
import (
|
||||||
"context"
|
"context"
|
||||||
"database/sql"
|
"database/sql"
|
||||||
|
"encoding/base64"
|
||||||
"encoding/json"
|
"encoding/json"
|
||||||
"errors"
|
"errors"
|
||||||
"fmt"
|
"fmt"
|
||||||
@@ -10,6 +11,7 @@ import (
|
|||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
"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/lagoon"
|
||||||
"git.golem15.com/golem15/summercms/modules/pact"
|
"git.golem15.com/golem15/summercms/modules/pact"
|
||||||
"git.golem15.com/golem15/summercms/modules/party"
|
"git.golem15.com/golem15/summercms/modules/party"
|
||||||
@@ -645,3 +647,49 @@ func TestDocsModelDeclarations(t *testing.T) {
|
|||||||
t.Fatalf("Migrations() = %d, want 2", n)
|
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
|
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