docs(cabana,compass,conga): compile README Go examples via src= (quick-261118-qsd)
- 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
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user