feat(11-01): run job workers in serve and queue:work, add queue:clear

- Manager gains the apparatus JobManager surface: StartJob, UpdateJobState,
  UpdateMetadata, FailJob, CancelJob (is_canceled + STOPPED + River JobCancel),
  StopJob (STOPPED only), CheckIfCanceled and GetMetadata, all raw column
  writes so updated_at is untouched
- serve starts the in-process worker unless queue.work_in_serve is false and
  stops it on shutdown; an app without jobs gets an idle worker
- queue:work runs a foreground worker with repeatable --queue filters;
  queue:clear deletes available, scheduled and retryable jobs of one queue
- the generated main appends conga.RuntimeCommands; summer delegates
  queue:work and queue:clear; make:job scaffolds a conga.Job

modules/surf/README.md

@@ -151,18 +151,18 @@ http:
     supports_credentials: true
 ```
 
-The `serve` command also opens the database through [lagoon](../lagoon/README.md) and the uploads bucket through `attach.OpenBucket`, so their settings must be present as well.
+The `serve` command also opens the database through [lagoon](../lagoon/README.md) and the uploads bucket through `attach.OpenBucket`, so their settings must be present as well. It starts the background job worker of [conga](../conga/README.md) in the same process unless `queue.work_in_serve` is `false` (default `true`); set it to `false` when a separate `queue:work` process runs the jobs. The other `queue.*` keys are documented in the conga README.
 
 ## CLI commands
 
 | Command | Flags | Description |
 |---------|-------|-------------|
-| `serve` | `--addr` (default `:8080`) | Opens the database and uploads bucket, assembles the router and serves HTTP until SIGINT or SIGTERM, then shuts down gracefully within 10 seconds. |
+| `serve` | `--addr` (default `:8080`) | Opens the database and uploads bucket, assembles the router, starts the in-process job worker (see `queue.work_in_serve`) and serves HTTP until SIGINT or SIGTERM, then shuts the server and the worker down gracefully within 10 seconds. |
 | `route:list` | none | Builds the router the same way `serve` does, without opening the database or listening, and prints a table of method, pattern, plugin, middleware and raw flag for every route. |
 
 ## Dependencies
 
-- SummerCMS modules: [backpack](../backpack/README.md), [bonfire](../bonfire/README.md), [bouncer](../bouncer/README.md), [cabana](../cabana/README.md), [compass](../compass/README.md), [lagoon](../lagoon/README.md) (including `lagoon/attach`), [pact](../pact/README.md), [party](../party/README.md), [towel](../towel/README.md), [wire](../wire/README.md).
+- SummerCMS modules: [backpack](../backpack/README.md), [bonfire](../bonfire/README.md), [bouncer](../bouncer/README.md), [cabana](../cabana/README.md), [compass](../compass/README.md), [conga](../conga/README.md) (the in-process job worker of `serve`), [lagoon](../lagoon/README.md) (including `lagoon/attach`), [pact](../pact/README.md), [party](../party/README.md), [towel](../towel/README.md), [wire](../wire/README.md).
 - Third-party: `gocloud.dev/blob` (uploads bucket opened by `serve`).
 - Standard library: `bytes`, `context`, `fmt`, `math`, `net`, `net/http`, `net/netip`, `os`, `os/signal`, `regexp`, `strconv`, `strings`, `sync`, `syscall`, `time`.
 

modules/surf/serve.go

@@ -13,6 +13,7 @@ import (
 
 	"git.golem15.com/golem15/summercms/modules/backpack"
 	"git.golem15.com/golem15/summercms/modules/bonfire"
+	"git.golem15.com/golem15/summercms/modules/conga"
 	"git.golem15.com/golem15/summercms/modules/lagoon"
 	"git.golem15.com/golem15/summercms/modules/lagoon/attach"
 	"git.golem15.com/golem15/summercms/modules/party"
@@ -34,6 +35,8 @@ func ServeCommand(app *backpack.App, plugins []party.Plugin) bonfire.Command {
 			if strings.TrimSpace(addr) == "" {
 				addr = ":8080"
 			}
+			ctx, stop := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
+			defer stop()
 			sqlDB, gdb, err := lagoon.OpenFromApp(ctx, app)
 			if err != nil {
 				return err
@@ -51,36 +54,57 @@ func ServeCommand(app *backpack.App, plugins []party.Plugin) bonfire.Command {
 			if err != nil {
 				return err
 			}
-			ctx, stop := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
-			defer stop()
+			worker, err := conga.StartServeWorker(ctx, app, plugins)
+			if err != nil {
+				return err
+			}
+			if worker != nil {
+				out.Info(fmt.Sprintf("job worker started on queues: %s", strings.Join(worker.Queues(), ", ")))
+			}
 			srv := &http.Server{Addr: addr, Handler: h, BaseContext: func(net.Listener) context.Context { return ctx }}
 			errCh := make(chan error, 1)
 			go func() {
 				out.Info(fmt.Sprintf("listening on %s", addr))
 				errCh <- srv.ListenAndServe()
 			}()
+			shutdownCtx := func() (context.Context, context.CancelFunc) {
+				return context.WithTimeout(context.Background(), 10*time.Second)
+			}
 			select {
 			case <-ctx.Done():
-				shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+				sctx, cancel := shutdownCtx()
 				defer cancel()
-				if err := srv.Shutdown(shutdownCtx); err != nil {
-					return err
+				shutdownErr := srv.Shutdown(sctx)
+				workerErr := stopWorker(sctx, worker)
+				if shutdownErr != nil {
+					return shutdownErr
 				}
 				err := <-errCh
-				if err == nil || err == http.ErrServerClosed {
-					return nil
+				if err != nil && err != http.ErrServerClosed {
+					return err
 				}
-				return err
+				return workerErr
 			case err := <-errCh:
-				if err == nil || err == http.ErrServerClosed {
-					return nil
+				sctx, cancel := shutdownCtx()
+				defer cancel()
+				workerErr := stopWorker(sctx, worker)
+				if err != nil && err != http.ErrServerClosed {
+					return err
 				}
-				return err
+				return workerErr
 			}
 		},
 	}
 }
 
+// stopWorker stops the in-process job worker, if serve started one.
+func stopWorker(ctx context.Context, w *conga.Worker) error {
+	if w == nil {
+		return nil
+	}
+	return w.Stop(ctx)
+}
+
 // publishUploads opens storage.uploads.bucket_url and publishes *blob.Bucket.
 // An empty URL fails boot the same way an empty JWT secret does.
 func publishUploads(ctx context.Context, app *backpack.App) (*blob.Bucket, error) {