Getting Started

Prerequisites

Go 1.25 or later
A Go module (go mod init)

Install

go get github.com/xraph/dispatch

Step 1: Create a Dispatcher

Every Dispatcher requires a store backend. For development and testing, use the in-memory store:

package main

import (
    "context"
    "log"

    "github.com/xraph/dispatch"
    "github.com/xraph/dispatch/store/memory"
)

func main() {
    ctx := context.Background()

    d, err := dispatch.New(
        dispatch.WithStore(memory.New()),
    )
    if err != nil {
        log.Fatal(err)
    }

    _ = d
}

Step 2: Define a job

A job definition is a typed Go function. The input struct is JSON-serialized at enqueue time and deserialized before execution:

import (
    "github.com/xraph/dispatch/job"
)

type EmailInput struct {
    To      string `json:"to"`
    Subject string `json:"subject"`
    Body    string `json:"body"`
}

var SendEmail = job.NewDefinition("send_email",
    func(ctx context.Context, input EmailInput) error {
        log.Printf("sending email to %s: %s", input.To, input.Subject)
        return nil
    },
)

Step 3: Build the engine and register jobs

The engine package wires all subsystems. Register job definitions at startup:

import "github.com/xraph/dispatch/engine"

eng := engine.Build(d)
engine.Register(eng, SendEmail)

Step 4: Start the dispatcher

if err := d.Start(ctx); err != nil {
    log.Fatal(err)
}
defer d.Stop(ctx)

The engine starts polling for pending jobs and dispatching them to workers.

Step 5: Enqueue a job

engine.Enqueue(ctx, eng, SendEmail, EmailInput{
    To:      "user@example.com",
    Subject: "Welcome to Acme",
    Body:    "Thanks for signing up!",
})

Enqueue serializes the input to JSON and persists the job in pending state. A worker picks it up on the next poll cycle.

Step 6: Mount the admin API (optional)

import (
    "net/http"
    "github.com/xraph/dispatch/api"
)

mux := http.NewServeMux()
api.RegisterRoutes(mux, eng)

log.Fatal(http.ListenAndServe(":8080", mux))

The admin API exposes HTTP endpoints for inspecting jobs, workflows, crons, DLQ entries, and stats.

Next steps

Architecture — Understand how the packages fit together
Jobs — Typed definitions, priorities, retries, and backoff
Workflows — Durable multi-step functions with checkpointing
Stores — Connect to PostgreSQL for production

Getting Started

On this page