- cabana: the hand-written controller fence points at Post, PostsController and BlogPlugin declarations; TestDocsDeclarations now calls each of them - compass: mailSettings and ExampleOpen; the YAML block matches the directory ExampleOpen writes - conga: job, dispatch and progress fences reuse the Jobs page targets; new reindex and worker regions run in TestDocsDispatch (Docker), and the schedule fence is FeedPlugin.Schedule, checked by TestDocsSchedule
267 lines
8.3 KiB
Go
267 lines
8.3 KiB
Go
package conga_test
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"testing"
|
|
"time"
|
|
|
|
"git.golem15.com/golem15/summercms/modules/backpack"
|
|
"git.golem15.com/golem15/summercms/modules/conga"
|
|
"git.golem15.com/golem15/summercms/modules/pact"
|
|
"git.golem15.com/golem15/summercms/modules/party"
|
|
"gorm.io/gorm"
|
|
)
|
|
|
|
// ImportPostsArgs are the arguments of the acme.blog post import job.
|
|
type ImportPostsArgs struct {
|
|
File string `json:"file"`
|
|
}
|
|
|
|
// Kind names the job. It must be unique across the application.
|
|
func (ImportPostsArgs) Kind() string { return "acme_blog_import_posts" }
|
|
|
|
func ExampleJob() {
|
|
job := conga.Job(func(ctx context.Context, args ImportPostsArgs) error {
|
|
_, dispatched := conga.JobID(ctx)
|
|
fmt.Println("import", args.File, "with a summer_jobs row:", dispatched)
|
|
return nil
|
|
}, conga.OnQueue("imports"), conga.MaxAttempts(5), conga.Timeout(10*time.Minute))
|
|
|
|
// A worker calls Work with the decoded arguments; a unit test can too.
|
|
if err := job.Work(context.Background(), ImportPostsArgs{File: "posts.csv"}); err != nil {
|
|
fmt.Println(err)
|
|
}
|
|
fmt.Println(ImportPostsArgs{}.Kind())
|
|
// Output:
|
|
// import posts.csv with a summer_jobs row: false
|
|
// acme_blog_import_posts
|
|
}
|
|
|
|
// 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
|
|
}
|
|
if canceled {
|
|
return m.StopJob(ctx, id, nil)
|
|
}
|
|
// ... import rows[i] ...
|
|
if err := m.UpdateJobState(ctx, id, i+1, nil); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
return m.CompleteJob(ctx, id, map[string]any{"imported": len(rows)})
|
|
}, conga.OnQueue("imports"))
|
|
}
|
|
|
|
// BlogPlugin is the acme.blog plugin; only its jobs are shown here.
|
|
type BlogPlugin struct {
|
|
jobs *conga.Manager
|
|
}
|
|
|
|
var _ pact.HasJobs = (*BlogPlugin)(nil)
|
|
|
|
func (p *BlogPlugin) ID() string { return "acme.blog" }
|
|
func (p *BlogPlugin) Requires() []string { return nil }
|
|
|
|
// Register keeps the application's job manager for the plugin's jobs.
|
|
func (p *BlogPlugin) Register(app *backpack.App) error {
|
|
m, err := conga.From(app)
|
|
p.jobs = m
|
|
return err
|
|
}
|
|
|
|
func (p *BlogPlugin) Boot(app *backpack.App) error { return nil }
|
|
|
|
// Jobs returns the plugin's background jobs; every worker registers them.
|
|
func (p *BlogPlugin) Jobs() []pact.Job {
|
|
return []pact.Job{ImportPostsJob(p.jobs)}
|
|
}
|
|
|
|
// startImport dispatches the import job in the transaction of the write
|
|
// that needs it and returns the summer_jobs row id.
|
|
func startImport(ctx context.Context, app *backpack.App, db *gorm.DB, file string) (uint, error) {
|
|
// docs:start 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
|
|
// docs:end dispatch
|
|
}
|
|
|
|
// importStatus reads the progress of a dispatched job from its row.
|
|
func importStatus(ctx context.Context, m *conga.Manager, id uint) (string, error) {
|
|
// docs:start status
|
|
rec, err := m.Get(ctx, id)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
switch rec.Status {
|
|
case conga.StatusComplete:
|
|
return fmt.Sprintf("%s: done (%d/%d)", rec.Label, rec.Progress, rec.ProgressMax), nil
|
|
case conga.StatusError, conga.StatusStopped:
|
|
return fmt.Sprintf("%s: failed or stopped", rec.Label), nil
|
|
default:
|
|
return fmt.Sprintf("%s: %d/%d", rec.Label, rec.Progress, rec.ProgressMax), nil
|
|
}
|
|
// docs:end status
|
|
}
|
|
|
|
// 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{}
|
|
if err := plugin.Register(app); err != nil {
|
|
t.Fatal(err)
|
|
}
|
|
if n := len(plugin.Jobs()); n != 1 {
|
|
t.Fatalf("Jobs() = %d jobs, want 1", n)
|
|
}
|
|
m, err := conga.From(app)
|
|
if err != nil {
|
|
t.Fatal(err)
|
|
}
|
|
err = runWorker(t.Context(), app, []party.Plugin{plugin}, func() error {
|
|
id, err := startImport(t.Context(), app, db, "posts.csv")
|
|
if err != nil {
|
|
return err
|
|
}
|
|
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)
|
|
}
|
|
|
|
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
|
|
}
|
|
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)
|
|
}
|
|
}
|
|
|
|
func ExampleDescribe() {
|
|
job := conga.Job(func(ctx context.Context, args ImportPostsArgs) error { return nil },
|
|
conga.OnQueue("imports"), conga.Timeout(4*time.Minute))
|
|
info, ok := conga.Describe(job)
|
|
fmt.Println(ok, info.Kind, info.Queue, info.MaxAttempts, info.Timeout)
|
|
// Output: true acme_blog_import_posts imports 0 4m0s
|
|
}
|