@opengroundplan/core 0.1.1

package/templates/layers/queue-broker/files/go.mod

@@ -0,0 +1,2 @@
+require github.com/hibiken/asynq v0.26.0
+require github.com/redis/go-redis/v9 v9.21.0

package/templates/layers/queue-broker/files/internal/queue/client.go

@@ -0,0 +1,57 @@
+package queue
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/hibiken/asynq"
+)
+
+// Client is the producer side. Safe for concurrent use; close it when the process exits.
+type Client struct {
+	inner *asynq.Client
+	cfg   Config
+}
+
+func NewClient(cfg Config) (*Client, error) {
+	opt, err := asynq.ParseRedisURI(cfg.BrokerURL)
+	if err != nil {
+		return nil, fmt.Errorf("queue: broker url: %w", err)
+	}
+	return &Client{inner: asynq.NewClient(opt), cfg: cfg}, nil
+}
+
+func (c *Client) Close() error { return c.inner.Close() }
+
+// Enqueue applies the configured retry, timeout and retention policy. Extra options
+// override those defaults, so a caller can delay or re-route a single job.
+func (c *Client) Enqueue(
+	ctx context.Context,
+	typename string,
+	payload any,
+	opts ...asynq.Option,
+) (string, error) {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("queue: marshal %s: %w", typename, err)
+	}
+
+	policy := []asynq.Option{
+		asynq.Queue(c.cfg.Name),
+		asynq.MaxRetry(c.cfg.MaxRetry()),
+		asynq.Timeout(c.cfg.JobTimeout()),
+		asynq.Retention(c.cfg.CompletedTTL()),
+	}
+
+	info, err := c.inner.EnqueueContext(ctx, asynq.NewTask(typename, body), append(policy, opts...)...)
+	if err != nil {
+		return "", fmt.Errorf("queue: enqueue %s: %w", typename, err)
+	}
+	return info.ID, nil
+}
+
+// EnqueueWelcomeEmail is the typed entry point application code should use.
+func (c *Client) EnqueueWelcomeEmail(ctx context.Context, payload WelcomeEmailPayload) (string, error) {
+	return c.Enqueue(ctx, TypeWelcomeEmail, payload)
+}

package/templates/layers/queue-broker/files/internal/queue/config.go

@@ -0,0 +1,109 @@
+// Package queue is the async job seam: one asynq client for producers, one server for
+// workers, and a single typed default table shared by both.
+package queue
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Own prefix rather than internal/config's, so the worker binary can load queue settings
+// without booting the HTTP server's configuration.
+const envPrefix = "{{ queueEnvPrefix }}"
+
+// Config is the only place queue settings are read.
+type Config struct {
+	BrokerURL              string
+	Name                   string
+	Concurrency            int
+	MaxAttempts            int
+	BackoffMS              int
+	JobTimeoutMS           int
+	CompletedTTLSeconds    int
+	ShutdownTimeoutSeconds int
+}
+
+// Typed defaults. The single place a literal queue value may appear.
+func defaults() Config {
+	return Config{
+		BrokerURL: "redis://127.0.0.1:6379/0",
+		Name:      "{{ queueName }}",
+		// First attempt included, so 3 means one try plus two retries.
+		Concurrency:            5,
+		MaxAttempts:            3,
+		BackoffMS:              1_000,
+		JobTimeoutMS:           30_000,
+		CompletedTTLSeconds:    3_600,
+		ShutdownTimeoutSeconds: 30,
+	}
+}
+
+// LoadConfig reads the environment once and reports a malformed value instead of
+// passing it to the broker client.
+func LoadConfig() (Config, error) {
+	cfg := defaults()
+	var err error
+
+	cfg.BrokerURL = str("BROKER_URL", cfg.BrokerURL)
+	cfg.Name = str("NAME", cfg.Name)
+	if cfg.Concurrency, err = positive("CONCURRENCY", cfg.Concurrency); err != nil {
+		return cfg, err
+	}
+	if cfg.MaxAttempts, err = positive("MAX_ATTEMPTS", cfg.MaxAttempts); err != nil {
+		return cfg, err
+	}
+	if cfg.BackoffMS, err = positive("BACKOFF_MS", cfg.BackoffMS); err != nil {
+		return cfg, err
+	}
+	if cfg.JobTimeoutMS, err = positive("JOB_TIMEOUT_MS", cfg.JobTimeoutMS); err != nil {
+		return cfg, err
+	}
+	if cfg.CompletedTTLSeconds, err = positive("COMPLETED_TTL_SECONDS", cfg.CompletedTTLSeconds); err != nil {
+		return cfg, err
+	}
+	if cfg.ShutdownTimeoutSeconds, err = positive("SHUTDOWN_TIMEOUT_SECONDS", cfg.ShutdownTimeoutSeconds); err != nil {
+		return cfg, err
+	}
+	return cfg, nil
+}
+
+// MaxRetry is what asynq counts: attempts after the first one.
+func (c Config) MaxRetry() int { return c.MaxAttempts - 1 }
+
+func (c Config) Backoff() time.Duration {
+	return time.Duration(c.BackoffMS) * time.Millisecond
+}
+
+func (c Config) JobTimeout() time.Duration {
+	return time.Duration(c.JobTimeoutMS) * time.Millisecond
+}
+
+func (c Config) CompletedTTL() time.Duration {
+	return time.Duration(c.CompletedTTLSeconds) * time.Second
+}
+
+func (c Config) ShutdownTimeout() time.Duration {
+	return time.Duration(c.ShutdownTimeoutSeconds) * time.Second
+}
+
+func str(key, fallback string) string {
+	if v, found := os.LookupEnv(envPrefix + "_" + key); found && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return fallback
+}
+
+func positive(key string, fallback int) (int, error) {
+	raw := str(key, "")
+	if raw == "" {
+		return fallback, nil
+	}
+	v, err := strconv.Atoi(raw)
+	if err != nil || v < 1 {
+		return fallback, fmt.Errorf("queue: %s_%s must be a positive integer, got %q", envPrefix, key, raw)
+	}
+	return v, nil
+}

package/templates/layers/queue-broker/files/internal/queue/config_test.go

@@ -0,0 +1,38 @@
+package queue
+
+import "testing"
+
+// Config is the layer's contract with the environment; a silent default here is an outage.
+func TestLoadConfigUsesDefaultsWhenEnvironmentIsEmpty(t *testing.T) {
+	cfg, err := LoadConfig()
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	if cfg.Name == "" || cfg.Concurrency < 1 {
+		t.Fatalf("LoadConfig() returned unusable defaults: %+v", cfg)
+	}
+	if cfg.MaxRetry() != cfg.MaxAttempts-1 {
+		t.Fatalf("MaxRetry() = %d, want %d", cfg.MaxRetry(), cfg.MaxAttempts-1)
+	}
+}
+
+func TestLoadConfigReadsEnvironment(t *testing.T) {
+	t.Setenv(envPrefix+"_NAME", "urgent")
+	t.Setenv(envPrefix+"_CONCURRENCY", "16")
+
+	cfg, err := LoadConfig()
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	if cfg.Name != "urgent" || cfg.Concurrency != 16 {
+		t.Fatalf("LoadConfig() = %+v, want name=urgent concurrency=16", cfg)
+	}
+}
+
+func TestLoadConfigRejectsNonInteger(t *testing.T) {
+	t.Setenv(envPrefix+"_CONCURRENCY", "many")
+
+	if _, err := LoadConfig(); err == nil {
+		t.Fatal("LoadConfig() accepted a non-integer concurrency")
+	}
+}

package/templates/layers/queue-broker/files/internal/queue/handlers.go

@@ -0,0 +1,33 @@
+package queue
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+
+	"github.com/hibiken/asynq"
+)
+
+// Handlers routes every task type to its worker function.
+func Handlers(log *slog.Logger) *asynq.ServeMux {
+	mux := asynq.NewServeMux()
+	mux.HandleFunc(TypeWelcomeEmail, handleWelcomeEmail(log))
+	return mux
+}
+
+// Replace with real work - it exists so the worker has something to run on day one.
+func handleWelcomeEmail(log *slog.Logger) func(context.Context, *asynq.Task) error {
+	return func(ctx context.Context, task *asynq.Task) error {
+		var payload WelcomeEmailPayload
+		if err := json.Unmarshal(task.Payload(), &payload); err != nil {
+			// A payload that will never parse must not burn the retry budget.
+			return fmt.Errorf("%s: %w: %w", TypeWelcomeEmail, err, asynq.SkipRetry)
+		}
+
+		log.InfoContext(ctx, "would send welcome email",
+			"email", payload.Email,
+			"user_id", payload.UserID)
+		return nil
+	}
+}

package/templates/layers/queue-broker/files/internal/queue/server.go

@@ -0,0 +1,29 @@
+package queue
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/hibiken/asynq"
+)
+
+// Exponential backoff stops doubling here so a long outage cannot push a retry past the day.
+const maxBackoffShift = 10
+
+// NewServer builds the consumer side. Run it with server.Run(Handlers(log)), which blocks
+// until SIGINT or SIGTERM and then drains in-flight jobs.
+func NewServer(cfg Config) (*asynq.Server, error) {
+	opt, err := asynq.ParseRedisURI(cfg.BrokerURL)
+	if err != nil {
+		return nil, fmt.Errorf("queue: broker url: %w", err)
+	}
+
+	return asynq.NewServer(opt, asynq.Config{
+		Concurrency:     cfg.Concurrency,
+		Queues:          map[string]int{cfg.Name: 1},
+		ShutdownTimeout: cfg.ShutdownTimeout(),
+		RetryDelayFunc: func(n int, _ error, _ *asynq.Task) time.Duration {
+			return cfg.Backoff() * time.Duration(int64(1)<<min(n, maxBackoffShift))
+		},
+	}), nil
+}

package/templates/layers/queue-broker/files/internal/queue/tasks.go

@@ -0,0 +1,11 @@
+package queue
+
+// Task type names are a wire contract shared by producers and workers across deploys -
+// renaming one strands every job already sitting in Redis.
+const TypeWelcomeEmail = "{{ solutionName | kebab }}:welcome-email"
+
+// WelcomeEmailPayload round-trips through Redis as JSON, so every field needs a tag.
+type WelcomeEmailPayload struct {
+	UserID string `json:"user_id"`
+	Email  string `json:"email"`
+}

package/templates/layers/queue-broker/files/package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "bullmq": "^5.80.8",
+    "ioredis": "^5.11.1"
+  }
+}

package/templates/layers/queue-broker/files/pyproject.toml

@@ -0,0 +1,2 @@
+[project]
+dependencies = ["celery>=5.6.3"]

package/templates/layers/queue-broker/files/src/__solutionName.dot__.Queue/Consumers/WelcomeEmailRequestedConsumer.cs

@@ -0,0 +1,24 @@
+using MassTransit;
+using Microsoft.Extensions.Logging;
+using {{ solutionName | dot }}.Queue.Contracts;
+
+namespace {{ solutionName | dot }}.Queue.Consumers;
+
+public sealed partial class WelcomeEmailRequestedConsumer(ILogger<WelcomeEmailRequestedConsumer> logger)
+    : IConsumer<WelcomeEmailRequested>
+{
+    // Replace with real work - it exists so the queue has something to run on day one.
+    public Task Consume(ConsumeContext<WelcomeEmailRequested> context)
+    {
+        WouldSendWelcomeEmail(logger, context.Message.Email, context.Message.UserId);
+        return Task.CompletedTask;
+    }
+
+    // Source-generated: the arguments are only evaluated when Information is enabled, and
+    // the message template is validated at compile time (CA1873).
+    [LoggerMessage(
+        EventId = 1,
+        Level = LogLevel.Information,
+        Message = "Would send a welcome email to {Email} (user {UserId})")]
+    private static partial void WouldSendWelcomeEmail(ILogger logger, string email, Guid userId);
+}

package/templates/layers/queue-broker/files/src/__solutionName.dot__.Queue/Contracts/WelcomeEmailRequested.cs

@@ -0,0 +1,7 @@
+namespace {{ solutionName | dot }}.Queue.Contracts;
+
+/// <summary>
+/// Message contracts are a wire format shared across deploys - renaming this record or
+/// any of its members strands every message already sitting in the broker.
+/// </summary>
+public sealed record WelcomeEmailRequested(Guid UserId, string Email);

package/templates/layers/queue-broker/files/src/__solutionName.dot__.Queue/IJobPublisher.cs

@@ -0,0 +1,11 @@
+namespace {{ solutionName | dot }}.Queue;
+
+/// <summary>
+/// The port application code depends on, so no project outside this one references
+/// MassTransit types and the transport stays swappable.
+/// </summary>
+public interface IJobPublisher
+{
+    Task PublishAsync<TMessage>(TMessage message, CancellationToken cancellationToken = default)
+        where TMessage : class;
+}

package/templates/layers/queue-broker/files/src/__solutionName.dot__.Queue/JobPublisher.cs

@@ -0,0 +1,10 @@
+using MassTransit;
+
+namespace {{ solutionName | dot }}.Queue;
+
+internal sealed class JobPublisher(IPublishEndpoint endpoint) : IJobPublisher
+{
+    public Task PublishAsync<TMessage>(TMessage message, CancellationToken cancellationToken = default)
+        where TMessage : class
+        => endpoint.Publish(message, cancellationToken);
+}

package/templates/layers/queue-broker/files/src/__solutionName.dot__.Queue/QueueOptions.cs

@@ -0,0 +1,32 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace {{ solutionName | dot }}.Queue;
+
+// The only default table: appsettings.*.json and Queue__* env vars override these initializers.
+public sealed class QueueOptions
+{
+    public const string SectionName = "Queue";
+
+    [Required]
+    public string BrokerUrl { get; set; } = "amqp://guest:guest@localhost:5672/";
+
+    [Required]
+    public string Name { get; set; } = "{{ queueName }}";
+
+    [Range(1, 512)]
+    public int Concurrency { get; set; } = 5;
+
+    /// <summary>First attempt included, so 3 means one try plus two retries.</summary>
+    [Range(1, 100)]
+    public int MaxAttempts { get; set; } = 3;
+
+    [Range(1, 600_000)]
+    public int BackoffMs { get; set; } = 1_000;
+
+    [Range(1, 3_600_000)]
+    public int JobTimeoutMs { get; set; } = 30_000;
+
+    public TimeSpan Backoff => TimeSpan.FromMilliseconds(BackoffMs);
+
+    public TimeSpan JobTimeout => TimeSpan.FromMilliseconds(JobTimeoutMs);
+}

package/templates/layers/queue-broker/files/src/__solutionName.dot__.Queue/QueueServiceCollectionExtensions.cs

@@ -0,0 +1,60 @@
+using System.ComponentModel.DataAnnotations;
+using MassTransit;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using {{ solutionName | dot }}.Queue.Consumers;
+
+namespace {{ solutionName | dot }}.Queue;
+
+public static class QueueServiceCollectionExtensions
+{
+    // Exponential retry never waits longer than this multiple of the configured base delay.
+    private const int MaxBackoffFactor = 30;
+
+    /// <summary>
+    /// Registers the broker, the consumers, and <see cref="IJobPublisher"/>. MassTransit
+    /// starts and stops itself with the host, so nothing else has to manage its lifetime.
+    /// </summary>
+    public static IServiceCollection AddQueueBroker(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        var section = configuration.GetSection(QueueOptions.SectionName);
+
+        // Bound eagerly because the bus topology is built during registration, long before
+        // the first IOptions resolve. Bad settings must stop startup, not the first publish.
+        var options = section.Get<QueueOptions>() ?? new QueueOptions();
+        Validator.ValidateObject(options, new ValidationContext(options), validateAllProperties: true);
+
+        services.Configure<QueueOptions>(section);
+        services.AddScoped<IJobPublisher, JobPublisher>();
+
+        services.AddMassTransit(bus =>
+        {
+            bus.AddConsumer<WelcomeEmailRequestedConsumer>();
+
+            bus.UsingRabbitMq((context, cfg) =>
+            {
+                cfg.Host(new Uri(options.BrokerUrl));
+
+                cfg.ReceiveEndpoint(options.Name, endpoint =>
+                {
+                    endpoint.ConcurrentMessageLimit = options.Concurrency;
+
+                    // Transient faults retry in place; whatever survives lands on <name>_error.
+                    endpoint.UseMessageRetry(retry => retry.Exponential(
+                        options.MaxAttempts - 1,
+                        options.Backoff,
+                        options.Backoff * MaxBackoffFactor,
+                        options.Backoff));
+
+                    endpoint.UseTimeout(timeout => timeout.Timeout = options.JobTimeout);
+
+                    endpoint.ConfigureConsumer<WelcomeEmailRequestedConsumer>(context);
+                });
+            });
+        });
+
+        return services;
+    }
+}

package/templates/layers/queue-broker/files/src/__solutionName.dot__.Queue/__solutionName.dot__.Queue.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Queue</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Queue</AssemblyName>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Pinned to 8.x: it is Apache-2.0, while MassTransit 9 requires a paid licence. -->
+    <PackageReference Include="MassTransit" />
+    <PackageReference Include="MassTransit.RabbitMQ" />
+    <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" />
+  </ItemGroup>
+
+</Project>

package/templates/layers/queue-broker/files/src/__solutionName.snake__/queue/__init__.py

@@ -0,0 +1,12 @@
+"""Async job queue: Celery over Redis, configured entirely from the environment."""
+
+from .app import celery_app
+from .config import QueueConfig, queue_config
+from .producer import enqueue_welcome_email
+
+__all__ = [
+    "QueueConfig",
+    "celery_app",
+    "enqueue_welcome_email",
+    "queue_config",
+]

package/templates/layers/queue-broker/files/src/__solutionName.snake__/queue/app.py

@@ -0,0 +1,35 @@
+"""The Celery application. Imported by producers and by the worker CLI alike."""
+
+from __future__ import annotations
+
+from celery import Celery
+
+from .config import queue_config
+
+celery_app = Celery("{{ solutionName | snake }}")
+
+celery_app.conf.update(
+    broker_url=queue_config.broker_url,
+    result_backend=queue_config.result_backend_url or None,
+    task_ignore_result=not queue_config.result_backend_url,
+    task_default_queue=queue_config.name,
+    task_serializer="json",
+    result_serializer="json",
+    accept_content=["json"],
+    timezone="UTC",
+    enable_utc=True,
+    # Ack after the handler returns, so a worker crash redelivers instead of losing the job.
+    task_acks_late=True,
+    task_reject_on_worker_lost=True,
+    # Late acks only pay off when a worker holds one job at a time.
+    worker_prefetch_multiplier=1,
+    worker_concurrency=queue_config.concurrency,
+    task_time_limit=queue_config.job_timeout_seconds,
+    # Soft limit fires first so a handler can clean up before it is killed outright.
+    task_soft_time_limit=max(queue_config.job_timeout_seconds - 5, 1),
+    result_expires=queue_config.completed_ttl_seconds,
+    broker_connection_retry_on_startup=True,
+)
+
+# Resolves ".queue.tasks" lazily, so importing this module never triggers a cycle.
+celery_app.autodiscover_tasks(["{{ solutionName | snake }}.queue"])

package/templates/layers/queue-broker/files/src/__solutionName.snake__/queue/config.py

@@ -0,0 +1,90 @@
+"""The only place queue settings are read.
+
+Tasks receive what they need as arguments; nothing else in the app reads the
+environment for the broker.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+_PREFIX = "{{ queueEnvPrefix }}"
+
+# Typed defaults. The single place a literal queue value may appear.
+_DEFAULTS = {
+    "broker_url": "redis://127.0.0.1:6379/0",
+    # Empty discards task results instead of writing them to the backend.
+    "result_backend_url": "",
+    "name": "{{ queueName }}",
+    "concurrency": 5,
+    # First attempt included, so 3 means one try plus two retries.
+    "max_attempts": 3,
+    "backoff_ms": 1_000,
+    "job_timeout_ms": 30_000,
+    "completed_ttl_seconds": 3_600,
+    "shutdown_timeout_seconds": 30,
+}
+
+
+def _raw(key: str) -> str | None:
+    value = os.environ.get(f"{_PREFIX}_{key}")
+    return value or None
+
+
+def _int(key: str, fallback: int) -> int:
+    value = _raw(key)
+    if value is None:
+        return fallback
+    try:
+        parsed = int(value)
+    except ValueError as exc:  # fail at startup rather than pass junk to Celery
+        raise ValueError(f"{_PREFIX}_{key} must be an integer, got {value!r}") from exc
+    if parsed < 1:
+        raise ValueError(f"{_PREFIX}_{key} must be positive, got {parsed}")
+    return parsed
+
+
+@dataclass(frozen=True, slots=True)
+class QueueConfig:
+    broker_url: str
+    result_backend_url: str
+    name: str
+    concurrency: int
+    max_attempts: int
+    backoff_ms: int
+    job_timeout_ms: int
+    completed_ttl_seconds: int
+    shutdown_timeout_seconds: int
+
+    @property
+    def job_timeout_seconds(self) -> float:
+        return self.job_timeout_ms / 1000
+
+    @property
+    def backoff_seconds(self) -> float:
+        return self.backoff_ms / 1000
+
+    @property
+    def max_retries(self) -> int:
+        """Celery counts retries after the first attempt, the env var counts attempts."""
+        return self.max_attempts - 1
+
+
+def load_config() -> QueueConfig:
+    return QueueConfig(
+        broker_url=_raw("BROKER_URL") or str(_DEFAULTS["broker_url"]),
+        result_backend_url=_raw("RESULT_BACKEND_URL") or str(_DEFAULTS["result_backend_url"]),
+        name=_raw("NAME") or str(_DEFAULTS["name"]),
+        concurrency=_int("CONCURRENCY", int(_DEFAULTS["concurrency"])),
+        max_attempts=_int("MAX_ATTEMPTS", int(_DEFAULTS["max_attempts"])),
+        backoff_ms=_int("BACKOFF_MS", int(_DEFAULTS["backoff_ms"])),
+        job_timeout_ms=_int("JOB_TIMEOUT_MS", int(_DEFAULTS["job_timeout_ms"])),
+        completed_ttl_seconds=_int("COMPLETED_TTL_SECONDS", int(_DEFAULTS["completed_ttl_seconds"])),
+        shutdown_timeout_seconds=_int(
+            "SHUTDOWN_TIMEOUT_SECONDS", int(_DEFAULTS["shutdown_timeout_seconds"])
+        ),
+    )
+
+
+queue_config = load_config()

package/templates/layers/queue-broker/files/src/__solutionName.snake__/queue/producer.py

@@ -0,0 +1,10 @@
+"""Enqueue helpers. Application code calls these instead of importing Celery directly."""
+
+from __future__ import annotations
+
+from .tasks import send_welcome_email
+
+
+def enqueue_welcome_email(user_id: str, email: str) -> str:
+    """Returns the task id so a caller can correlate it with worker logs."""
+    return send_welcome_email.delay(user_id=user_id, email=email).id

package/templates/layers/queue-broker/files/src/__solutionName.snake__/queue/tasks.py

@@ -0,0 +1,31 @@
+"""The job catalogue.
+
+A task name is a wire contract shared by producers and workers across deploys -
+renaming one strands every job already sitting in the broker.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from celery import shared_task
+
+from .config import queue_config
+
+logger = logging.getLogger(__name__)
+
+SEND_WELCOME_EMAIL = "{{ solutionName | snake }}.send_welcome_email"
+
+
+@shared_task(
+    name=SEND_WELCOME_EMAIL,
+    autoretry_for=(Exception,),
+    max_retries=queue_config.max_retries,
+    retry_backoff=queue_config.backoff_seconds,
+    retry_backoff_max=queue_config.job_timeout_seconds,
+    # Spread retries so a downstream outage does not produce a synchronised stampede.
+    retry_jitter=True,
+)
+def send_welcome_email(user_id: str, email: str) -> None:
+    """Replace with real work - it exists so the worker has something to run on day one."""
+    logger.info("would send a welcome email to %s (user %s)", email, user_id)