Forge Extension

Dispatch includes an extension adapter for the Forge framework. It handles store wiring, migration, route registration, and lifecycle management automatically.

Setup

import (
    "github.com/xraph/dispatch/extension"
    "github.com/xraph/dispatch/store/postgres"
)

store, _ := postgres.New(ctx, os.Getenv("DATABASE_URL"))

ext := extension.New(
    extension.WithStore(store),
    extension.WithConcurrency(20),
    extension.WithQueues([]string{"default", "critical"}),
    extension.WithBasePath("/api/dispatch"),
)

app := forge.New()
app.RegisterExtension(ext)

Forge will call ext.Start(ctx) on application start and ext.Stop(ctx) on shutdown.

Extension options

Option	Purpose	Default
`WithStore(s)`	Persistence backend (required)	—
`WithConcurrency(n)`	Max concurrent jobs	`10`
`WithQueues(q)`	Queues to poll	`["default"]`
`WithBasePath(p)`	HTTP API prefix	`"/api/dispatch"`
`WithExtension(x)`	Register a lifecycle extension	—
`WithMiddleware(m)`	Add job execution middleware	—
`WithBackoff(b)`	Retry backoff strategy	exponential
`WithDisableRoutes()`	Skip HTTP route registration	`false`
`WithDisableMigrate()`	Skip auto-migration at startup	`false`

Auto-migration

By default, extension.New() runs store.Migrate(ctx) during Start. Disable this if you manage migrations externally:

ext := extension.New(
    extension.WithStore(store),
    extension.WithDisableMigrate(),
)

Accessing the engine from Forge context

When using Forge dependency injection, retrieve the engine from context:

eng := extension.EngineFromContext(ctx)
engine.Enqueue(ctx, eng, SendEmail, input)

Standalone usage (without Forge)

The extension works without Forge too:

ext := extension.New(extension.WithStore(store))
ext.Start(ctx)
defer ext.Stop(ctx)

eng := ext.Engine()
engine.Register(eng, SendEmail)
engine.Enqueue(ctx, eng, SendEmail, input)