diff --git a/modules/cabana/README.md b/modules/cabana/README.md index 2d1f8cef..f7c38d7c 100644 --- a/modules/cabana/README.md +++ b/modules/cabana/README.md @@ -196,46 +196,71 @@ Plugin CSS (declared through `pact.AdminClientAssets`) and any widget shadow DOM ## Usage -A plugin exposes an admin controller and embeds its YAML. `summer make:admin-controller` scaffolds the controller type and its four YAML files, names the model after the singular of the controller (or `--model`) and lists the controller in the plugin's generated `registry.gen.go`, which also embeds the YAML for a scaffolded plugin's `AdminFS`. Written by hand, the same pieces look like this: - -```go -package blog - -import ( - "embed" - "io/fs" - - "git.golem15.com/golem15/summercms/modules/pact" -) - -// adminFS holds controllers/post/config_list.yaml, controllers/post/config_form.yaml, -// models/post/columns.yaml and models/post/fields.yaml. -// -//go:embed controllers models -var adminFS embed.FS +A plugin exposes an admin controller and embeds its YAML. `summer make:admin-controller` scaffolds the controller type and its four YAML files, names the model after the singular of the controller (or `--model`) and lists the controller in the plugin's generated `registry.gen.go`, which also embeds the YAML for a scaffolded plugin's `AdminFS`. Written by hand, the same pieces look like this. The model: +```go src=modules/cabana/example_controller_test.go#Post +// Post is the model behind the acme.blog posts controller. type Post struct { - ID uint `gorm:"primaryKey"` - Title string `gorm:"column:title"` + ID uint `gorm:"column:id;primaryKey"` + Title string `gorm:"column:title"` + Slug string `gorm:"column:slug"` + Status string `gorm:"column:status"` + Published bool `gorm:"column:published"` + PublishedAt *time.Time `gorm:"column:published_at"` + Content string `gorm:"column:content"` } +``` +```go src=modules/cabana/example_controller_test.go#Post.TableName func (Post) TableName() string { return "acme_blog_posts" } +``` -type postAdmin struct{} +The controller (`config_list.yaml` and `config_form.yaml` live in `controllers/posts`; the model files in `models/post`): -func (postAdmin) ID() string { return "acme.blog.post" } -func (postAdmin) ModelName() string { return "Post" } // must equal modelClass in the YAML -func (postAdmin) ConfigDir() string { return "controllers/post" } -func (postAdmin) NewRecord() any { return &Post{} } // pact.AdminRecordSource +```go src=modules/cabana/example_controller_test.go#PostsController +// PostsController is the admin controller for posts: the Go form of a +// WinterCMS controller with the List and Form behaviours. +type PostsController struct{} +``` -// Plugin also implements party.Plugin (ID, Requires, Register, Boot). -type Plugin struct{} +```go src=modules/cabana/example_controller_test.go#PostsController.ID +// ID is the controller ID; its admin API path is /acme/blog/posts. +func (PostsController) ID() string { return "acme.blog.posts" } +``` -func (p *Plugin) AdminControllers() []pact.AdminController { - return []pact.AdminController{postAdmin{}} +```go src=modules/cabana/example_controller_test.go#PostsController.ModelName +// ModelName must equal modelClass in the YAML. +func (PostsController) ModelName() string { return "Post" } +``` + +```go src=modules/cabana/example_controller_test.go#PostsController.ConfigDir +// ConfigDir holds config_list.yaml, config_form.yaml and config_filter.yaml. +func (PostsController) ConfigDir() string { return "controllers/posts" } +``` + +```go src=modules/cabana/example_controller_test.go#PostsController.NewRecord +// NewRecord returns the model the generic admin handlers query. +func (PostsController) NewRecord() any { return &Post{} } +``` + +The plugin lists the controller and returns the tree that holds its YAML: + +```go src=modules/cabana/example_controller_test.go#BlogPlugin +// BlogPlugin is the acme.blog plugin; only its backend surface is shown. +type BlogPlugin struct{} +``` + +```go src=modules/cabana/example_controller_test.go#BlogPlugin.AdminControllers +// AdminControllers registers the plugin's admin controllers. +func (p *BlogPlugin) AdminControllers() []pact.AdminController { + return []pact.AdminController{PostsController{}} } +``` -func (p *Plugin) AdminFS() fs.FS { return adminFS } +```go src=modules/cabana/example_controller_test.go#BlogPlugin.AdminFS +// AdminFS is the plugin's embedded controllers/ and models/ tree. A real +// plugin returns an embed.FS; the example reads the same files from testdata. +func (p *BlogPlugin) AdminFS() fs.FS { return os.DirFS("testdata/docs") } ``` `config_list.yaml` and `config_form.yaml` reference the model files with WinterCMS paths such as `~/plugins/acme/blog/models/post/columns.yaml`. At boot, `surf.BuildRouter` calls `cabana.Activate` with the activated plugins and mounts the returned `cabana.Routes`; when no plugin registers an admin controller, `cabana.Activate` returns nil and no admin routes exist. `surf.Router.AdminPrefix` reports which case applies, and the `serve` and `route:list` commands print it as an admin status line. Record and user lookups use the `*gorm.DB` that [lagoon](../lagoon/README.md) publishes on the `backpack.App`. diff --git a/modules/cabana/example_test.go b/modules/cabana/example_test.go index aaa96ada..0ace8cec 100644 --- a/modules/cabana/example_test.go +++ b/modules/cabana/example_test.go @@ -2,6 +2,7 @@ package cabana_test import ( "fmt" + "io/fs" "os" "testing" @@ -81,9 +82,25 @@ func ExampleActivate() { // false } -// TestDocsDeclarations checks the plugin declarations the Backend pages show. +// TestDocsDeclarations checks the plugin declarations the Backend pages and +// the README show. func TestDocsDeclarations(t *testing.T) { p := &BlogPlugin{} + c := PostsController{} + if c.ID() != "acme.blog.posts" || c.ModelName() != "Post" || c.ConfigDir() != "controllers/posts" { + t.Fatalf("controller = %q %q %q", c.ID(), c.ModelName(), c.ConfigDir()) + } + if _, ok := c.NewRecord().(*Post); !ok || (Post{}).TableName() != "acme_blog_posts" { + t.Fatalf("NewRecord() = %T, table %q", c.NewRecord(), Post{}.TableName()) + } + if ctrls := p.AdminControllers(); len(ctrls) != 1 || ctrls[0].ID() != c.ID() { + t.Fatalf("AdminControllers() = %+v", ctrls) + } + for _, name := range []string{"controllers/posts/config_list.yaml", "controllers/posts/config_form.yaml", "models/post/columns.yaml", "models/post/fields.yaml"} { + if _, err := fs.Stat(p.AdminFS(), name); err != nil { + t.Fatalf("AdminFS(): %v", err) + } + } if n := len(p.Permissions()); n != 2 { t.Fatalf("Permissions() = %d entries", n) } diff --git a/modules/compass/README.md b/modules/compass/README.md index f9a6a58d..c3a60ad2 100644 --- a/modules/compass/README.md +++ b/modules/compass/README.md @@ -37,47 +37,83 @@ Use cases: ## Usage -```go -package blog - -import ( - "git.golem15.com/golem15/summercms/modules/compass" -) - +```go src=modules/compass/example_test.go#mailSettings type mailSettings struct { - Host string `koanf:"host"` - Port int `koanf:"port"` -} - -func loadConfig() (*compass.Config, error) { - cfg, err := compass.Open(compass.Options{Dir: "config", Env: "development"}) - if err != nil { - return nil, err - } - - name := cfg.String("app.name") - perPage := cfg.Int("acme.blog.posts_per_page") - _, _ = name, perPage - - var mail mailSettings - if err := cfg.LoadSection("mail", &mail); err != nil { - return nil, err - } - - // Store a runtime override and write it to config/env/development/overrides.yaml. - if err := cfg.Set("acme.blog.posts_per_page", 25); err != nil { - return nil, err - } - return cfg, cfg.Persist() + Driver string `koanf:"driver"` + From string `koanf:"from"` } ``` -A matching configuration directory: +```go src=modules/compass/example_test.go#ExampleOpen +dir, err := os.MkdirTemp("", "acme-config") +if err != nil { + fmt.Println(err) + return +} +defer os.RemoveAll(dir) +if err := writeConfig(dir); err != nil { + fmt.Println(err) + return +} + +// Environ stands in for the process environment (nil reads os.Environ). +cfg, err := compass.Open(compass.Options{ + Dir: dir, + Env: "development", + Environ: []string{"SUMMER_MAIL__DRIVER=smtp"}, +}) +if err != nil { + fmt.Println(err) + return +} + +// A plugin's embedded config/config.yaml becomes its defaults. +plugin := fstest.MapFS{"config/config.yaml": {Data: []byte("posts_per_page: 10\n")}} +if err := cfg.MergePlugin("acme.blog", plugin); err != nil { + fmt.Println(err) + return +} + +fmt.Println(cfg.String("app.name"), cfg.Bool("app.debug"), cfg.Int("acme.blog.posts_per_page")) +var mail mailSettings +if err := cfg.LoadSection("mail", &mail); err != nil { + fmt.Println(err) + return +} +fmt.Println(mail.Driver, mail.From) +_, found := cfg.Lookup("app.timezone") +fmt.Println(cfg.Environment(), found) + +// A runtime override, saved to env/development/overrides.yaml. +if err := cfg.Set("acme.blog.posts_per_page", 25); err != nil { + fmt.Println(err) + return +} +if err := cfg.Persist(); err != nil { + fmt.Println(err) + return +} +saved, _ := os.ReadFile(filepath.Join(dir, "env", "development", "overrides.yaml")) +fmt.Print(string(saved)) +// Output: +// Acme true 10 +// smtp blog@example.com +// development false +// acme: +// blog: +// posts_per_page: 25 +``` + +The configuration directory the example writes: ```yaml # config/app.yaml name: Acme -url: http://localhost:8080 +debug: false + +# config/mail.yaml +driver: log +from: blog@example.com # config/env/development/app.yaml debug: true diff --git a/modules/conga/README.md b/modules/conga/README.md index 48676cde..92ff2aab 100644 --- a/modules/conga/README.md +++ b/modules/conga/README.md @@ -43,99 +43,109 @@ Use cases: ## Usage -A plugin declares a job: - -```go -package blog - -import ( - "context" - - "git.golem15.com/golem15/summercms/modules/conga" - "git.golem15.com/golem15/summercms/modules/pact" -) +A plugin declares a job's arguments and kind: +```go src=modules/conga/example_test.go#ImportPostsArgs +// ImportPostsArgs are the arguments of the acme.blog post import job. type ImportPostsArgs struct { File string `json:"file"` } +``` +```go src=modules/conga/example_test.go#ImportPostsArgs.Kind +// Kind names the job. It must be unique across the application. func (ImportPostsArgs) Kind() string { return "acme_blog_import_posts" } +``` -func ImportPostsJob(m *conga.Manager) pact.Job { - return conga.Job(func(ctx context.Context, args ImportPostsArgs) error { - id, _ := conga.JobID(ctx) - // ... import args.File ... - return m.CompleteJob(ctx, id, nil) - }, conga.OnQueue("imports")) +lists its jobs, so every worker registers them: + +```go src=modules/conga/example_test.go#BlogPlugin.Jobs +// Jobs returns the plugin's background jobs; every worker registers them. +func (p *BlogPlugin) Jobs() []pact.Job { + return []pact.Job{ImportPostsJob(p.jobs)} } ``` and dispatches it inside the write that needs it: -```go -func startImport(ctx context.Context, app *backpack.App, gdb *gorm.DB, file string) (uint, error) { - m, err := conga.From(app) - if err != nil { - return 0, err - } - var id uint - err = gdb.WithContext(ctx).Transaction(func(tx *gorm.DB) error { - // ... write the import record ... - id, err = m.Dispatch(ctx, tx, ImportPostsArgs{File: file}, conga.DispatchOpts{Label: "Import posts", Count: 100}) - return err - }) - return id, err +```go src=modules/conga/example_test.go#dispatch +m, err := conga.From(app) +if err != nil { + return 0, err } +var id uint +err = db.WithContext(ctx).Transaction(func(tx *gorm.DB) error { + // ... write the import's own records on tx ... + id, err = m.Dispatch(ctx, tx, ImportPostsArgs{File: file}, conga.DispatchOpts{ + Label: "Import posts", + Count: 1, + }) + return err +}) +return id, err ``` A long job reports progress and honours cancellation between items: -```go -func importPosts(ctx context.Context, m *conga.Manager, files []string) error { - id, _ := conga.JobID(ctx) - if err := m.StartJob(ctx, id, len(files)); err != nil { - return err - } - for i, f := range files { - if canceled, err := m.CheckIfCanceled(ctx, id); err != nil || canceled { +```go src=modules/conga/example_test.go#ImportPostsJob +// ImportPostsJob is the acme.blog import job. It reports progress on its +// summer_jobs row, stops when the row is cancelled and completes the row. +func ImportPostsJob(m *conga.Manager) pact.Job { + return conga.Job(func(ctx context.Context, args ImportPostsArgs) error { + id, _ := conga.JobID(ctx) + rows := []string{args.File} // ... read the rows of args.File ... + if err := m.StartJob(ctx, id, len(rows)); err != nil { + return err + } + for i := range rows { + canceled, err := m.CheckIfCanceled(ctx, id) if err != nil { return err } - return m.StopJob(ctx, id, nil) + if canceled { + return m.StopJob(ctx, id, nil) + } + // ... import rows[i] ... + if err := m.UpdateJobState(ctx, id, i+1, nil); err != nil { + return err + } } - // ... import f ... - _ = f - if err := m.UpdateJobState(ctx, id, i+1, nil); err != nil { - return err - } - } - return m.CompleteJob(ctx, id, map[string]any{"imported": len(files)}) + return m.CompleteJob(ctx, id, map[string]any{"imported": len(rows)}) + }, conga.OnQueue("imports")) } ``` A plugin schedules one of its registered commands; the worker runs it: -```go -var _ pact.HasSchedule = (*Plugin)(nil) - -func (p *Plugin) Schedule() []pact.ScheduledCommand { +```go src=modules/conga/example_test.go#FeedPlugin.Schedule +// Schedule runs two of the plugin's registered console commands. +func (p *FeedPlugin) Schedule() []pact.ScheduledCommand { return []pact.ScheduledCommand{ - {Command: "blog:prune-drafts", Cadence: pact.Daily()}, - {Command: "blog:sync-feed", Args: []string{"--quiet"}, Cadence: pact.Every(15 * time.Minute)}, + {Command: "feed:prune", Cadence: pact.Daily()}, + {Command: "feed:sync", Args: []string{"--quiet"}, Cadence: pact.Every(15 * time.Minute)}, } } ``` A job whose worker ships in a later release can already be queued from a request, on a queue that nothing serves yet. It waits there until a release registers its worker and the queue becomes served: -```go +```go src=modules/conga/example_test.go#ReindexArgs +// ReindexArgs are the arguments of the acme.reindex job, whose worker ships +// in a later release. +type ReindexArgs struct { + SiteID int `json:"site_id"` +} +``` + +```go src=modules/conga/example_test.go#reindex // No plugin registers acme.reindex yet; its queue is served by nobody. -_, err := m.Dispatch(ctx, tx, ReindexArgs{SiteID: 7}, conga.DispatchOpts{ +id, err := m.Dispatch(ctx, tx, ReindexArgs{SiteID: 7}, conga.DispatchOpts{ Label: "acme.reindex", Queue: "acme_reindex", }) if errors.Is(err, conga.ErrUnregisteredKindQueue) { // the queue is empty or a worker serves it + return 0, fmt.Errorf("acme.reindex cannot wait: %w", err) } ``` @@ -143,7 +153,7 @@ Queue names follow River's rule: lowercase letters and digits, separated by `_` A worker runs in the same process or in a separate one: -```go +```go src=modules/conga/example_test.go#worker w, err := conga.StartWorker(ctx, app, plugins, conga.WorkerOptions{}) if err != nil { return err diff --git a/modules/conga/example_test.go b/modules/conga/example_test.go index edbf11c7..60944021 100644 --- a/modules/conga/example_test.go +++ b/modules/conga/example_test.go @@ -2,6 +2,7 @@ package conga_test import ( "context" + "errors" "fmt" "testing" "time" @@ -127,9 +128,49 @@ func importStatus(ctx context.Context, m *conga.Manager, id uint) (string, error // docs:end status } -// TestDocsDispatch runs the dispatch region of the Jobs page on the -// package's Postgres harness: a worker registers the plugin's job, the job -// is dispatched in a transaction and completes its row. +// ReindexArgs are the arguments of the acme.reindex job, whose worker ships +// in a later release. +type ReindexArgs struct { + SiteID int `json:"site_id"` +} + +// Kind names the job. +func (ReindexArgs) Kind() string { return "acme_reindex" } + +// queueReindex queues the acme.reindex job in the transaction tx, before +// any plugin registers its worker. +func queueReindex(ctx context.Context, m *conga.Manager, tx *gorm.DB) (uint, error) { + // docs:start reindex + // No plugin registers acme.reindex yet; its queue is served by nobody. + id, err := m.Dispatch(ctx, tx, ReindexArgs{SiteID: 7}, conga.DispatchOpts{ + Label: "acme.reindex", + Queue: "acme_reindex", + }) + if errors.Is(err, conga.ErrUnregisteredKindQueue) { + // the queue is empty or a worker serves it + return 0, fmt.Errorf("acme.reindex cannot wait: %w", err) + } + // docs:end reindex + return id, err +} + +// runWorker starts a worker for the plugins' jobs, runs fn while it works +// and stops it. +func runWorker(ctx context.Context, app *backpack.App, plugins []party.Plugin, fn func() error) error { + // docs:start worker + w, err := conga.StartWorker(ctx, app, plugins, conga.WorkerOptions{}) + if err != nil { + return err + } + defer w.Stop(context.Background()) + // docs:end worker + return fn() +} + +// TestDocsDispatch runs the dispatch, reindex and worker regions of the Jobs +// page and the README on the package's Postgres harness: a worker registers +// the plugin's job, the job is dispatched in a transaction and completes its +// row, and a job without a registered worker waits on its own queue. func TestDocsDispatch(t *testing.T) { app, db := conga.DocsApp(t) plugin := &BlogPlugin{} @@ -139,39 +180,80 @@ func TestDocsDispatch(t *testing.T) { if n := len(plugin.Jobs()); n != 1 { t.Fatalf("Jobs() = %d jobs, want 1", n) } - w, err := conga.StartWorker(t.Context(), app, []party.Plugin{plugin}, conga.WorkerOptions{}) - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { - ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) - defer cancel() - if err := w.Stop(ctx); err != nil { - t.Errorf("stop worker: %v", err) - } - }) - - id, err := startImport(t.Context(), app, db, "posts.csv") - if err != nil { - t.Fatal(err) - } m, err := conga.From(app) if err != nil { t.Fatal(err) } - deadline := time.Now().Add(15 * time.Second) - for { - got, err := importStatus(t.Context(), m, id) + err = runWorker(t.Context(), app, []party.Plugin{plugin}, func() error { + id, err := startImport(t.Context(), app, db, "posts.csv") if err != nil { - t.Fatal(err) + return err } - if got == "Import posts: done (1/1)" { - return + deadline := time.Now().Add(15 * time.Second) + for { + got, err := importStatus(t.Context(), m, id) + if err != nil { + return err + } + if got == "Import posts: done (1/1)" { + break + } + if time.Now().After(deadline) { + return fmt.Errorf("status = %q, want the job to complete", got) + } + time.Sleep(25 * time.Millisecond) } - if time.Now().After(deadline) { - t.Fatalf("status = %q, want the job to complete", got) + + var reindex uint + if err := db.WithContext(t.Context()).Transaction(func(tx *gorm.DB) error { + reindex, err = queueReindex(t.Context(), m, tx) + return err + }); err != nil { + return err } - time.Sleep(25 * time.Millisecond) + rec, err := m.Get(t.Context(), reindex) + if err != nil { + return err + } + if rec.Label != "acme.reindex" || rec.Status == conga.StatusComplete { + return fmt.Errorf("reindex row = %+v, want it waiting", rec) + } + // The imports queue is served, so the unregistered kind is refused. + _, err = m.Dispatch(t.Context(), db, ReindexArgs{SiteID: 7}, conga.DispatchOpts{Label: "acme.reindex", Queue: "imports"}) + if !errors.Is(err, conga.ErrUnregisteredKindQueue) { + return fmt.Errorf("dispatch on a served queue = %v, want ErrUnregisteredKindQueue", err) + } + return nil + }) + if err != nil { + t.Fatal(err) + } +} + +// FeedPlugin is the acme.feed plugin; only its schedule is shown here. +type FeedPlugin struct{} + +var _ pact.HasSchedule = (*FeedPlugin)(nil) + +// Schedule runs two of the plugin's registered console commands. +func (p *FeedPlugin) Schedule() []pact.ScheduledCommand { + return []pact.ScheduledCommand{ + {Command: "feed:prune", Cadence: pact.Daily()}, + {Command: "feed:sync", Args: []string{"--quiet"}, Cadence: pact.Every(15 * time.Minute)}, + } +} + +// TestDocsSchedule checks the schedule the README shows. +func TestDocsSchedule(t *testing.T) { + entries := (&FeedPlugin{}).Schedule() + if len(entries) != 2 { + t.Fatalf("Schedule() = %+v", entries) + } + if h, m, daily := entries[0].Cadence.At(); entries[0].Command != "feed:prune" || !daily || h != 0 || m != 0 { + t.Fatalf("entry 0 = %+v", entries[0]) + } + if e := entries[1]; e.Command != "feed:sync" || len(e.Args) != 1 || e.Args[0] != "--quiet" || e.Cadence.Interval() != 15*time.Minute { + t.Fatalf("entry 1 = %+v", e) } }