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 }