Imported from jollyroger-1989/ratiodash (backend/internal/notifier/AGENTS.md). Install upstream with npx skills add jollyroger-1989/ratiodash --skill notifier. Copyright stays with the author.

Notifier layer — conventions

Notifiers deliver domain.Notification values to external channels (HTTP push, e-mail, webhooks, etc.). The domain.Notifier interface is the only dependency callers import; concrete implementations are invisible to the rest of the application.

Files & types

The multiNotifier in multi.go fans out to all group members and is the single domain.Notifier exposed to the rest of the application. Do not add a second fx.Provide for domain.Notifier.

Adding a new backend

1. Create internal/notifier/{transport}.go.
2. Define an unexported struct implementing domain.Notifier:

type ntfyNotifier struct{ topic string }

func NewNtfyNotifier(cfg config.Config) (domain.Notifier, error) {
    if cfg.NtfyTopic == "" {
        return nil, nil // disabled — MultiNotifier tolerates nils
    }
    return &ntfyNotifier{topic: cfg.NtfyTopic}, nil
}

func (n *ntfyNotifier) Notify(ctx context.Context, notif domain.Notification) error {
    // POST to ntfy …
}

3. Append to module.go:

fx.Provide(
    fx.Annotate(
        NewNtfyNotifier,
        fx.As(new(domain.Notifier)),
        fx.ResultTags(`group:"notifiers"`),
    ),
),

domain.Notification fields

Rules

• Constructors return nil, nil when disabled — check a config flag (topic URL, SMTP host, etc.) and return (nil, nil) rather than an error when a backend is not configured. MultiNotifier skips nil entries.
• One responsibility — a notifier only formats and delivers; routing, filtering, and retry logic belong in the caller or a wrapper.
• Context propagation — always forward ctx to HTTP clients, SMTP dials, etc. to respect request deadlines and cancellation.
• No business logic — notifiers must not query the database or call services.
• Error wrapping — wrap errors with context: fmt.Errorf("ntfy notify: %w", err).

Wiring in cmd/api/main.go

Insert notifier.Module after service and before handler in the FX options list:

config → database → repository → scraper → service → notifier → scheduler → handler → server

Testing conventions

Notifier tests are unit tests: they spin up a local httptest.Server (for HTTP-based backends) or stub collaborators directly, and assert on outgoing requests or return values — no real external services are contacted.

Files & packages

HTTP backends — test server pattern

Use net/http/httptest.NewServer to intercept outgoing requests without contacting a real service. Capture the request inside the handler, then assert on headers and body after Notify returns.

func TestNtfyNotifier_Notify(t *testing.T) {
    t.Run("sets correct priority for each level", func(t *testing.T) {
        var got *http.Request
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            got = r.Clone(context.Background())
            w.WriteHeader(http.StatusOK)
        }))
        defer srv.Close()

        n, err := notifier.NewNtfyNotifier(&config.Config{NtfyURL: srv.URL})
        require.NoError(t, err)
        require.NotNil(t, n)

        err = n.Notify(context.Background(), domain.Notification{
            Event: domain.EventSyncError,
            Level: domain.LevelError,
            Title: "test title",
            Body:  "test body",
        })

        require.NoError(t, err)
        assert.Equal(t, "5", got.Header.Get("Priority"))
        assert.Equal(t, "test title", got.Header.Get("Title"))
    })
}

What to test for every HTTP backend

multiNotifier tests (multi_test.go)

func TestMultiNotifier_Notify(t *testing.T) {
    t.Run("calls all backends", func(t *testing.T) {
        called := 0
        stub := stubNotifier(func(_ context.Context, _ domain.Notification) error {
            called++
            return nil
        })

        n := notifier.NewMultiNotifier(notifier.MultiParams{Notifiers: []domain.Notifier{stub, stub}})
        require.NoError(t, n.Notify(context.Background(), domain.Notification{}))
        assert.Equal(t, 2, called)
    })
}

Define a minimal stubNotifier helper inside the test file:

type stubNotifier func(context.Context, domain.Notification) error

func (s stubNotifier) Notify(ctx context.Context, n domain.Notification) error { return s(ctx, n) }

Assertions

Use github.com/stretchr/testify/require for setup steps and the first error check that would make subsequent assertions meaningless. Use assert for everything else.

require.NoError(t, err)           // fatal — no point continuing
assert.Equal(t, "5", priority)    // non-fatal header check
assert.NotNil(t, notif)           // non-fatal nil guard

Coverage requirement

Tests must achieve 100% statement coverage of the implementation file. Run with:

go test -coverprofile=cover.out ./internal/notifier/...
go tool cover -func=cover.out