foreman

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

README

Foreman

A Postgres-backed job queue for Go.

CI Release License

Architecture

flowchart TB
  APP["Your service"]

  subgraph PG["PostgreSQL"]
    direction LR
    JOBS[("foreman_jobs")]
    BUS{{"LISTEN / NOTIFY"}}
  end

  subgraph CL["Foreman client"]
    direction LR
    PROD["Producer"]
    WP["Workers"]
    DONE["Completions"]
    PROD --> WP --> DONE
  end

  subgraph LD["Leader"]
    direction LR
    SCH["Scheduler"]
    PER["Periodic jobs"]
    RES["Rescuer"]
    CLN["Cleaner"]
  end

  APP ==>|"enqueue"| JOBS
  JOBS -.->|"notify"| BUS
  BUS -.->|"wake"| PROD
  JOBS -->|"fetch"| PROD
  DONE -->|"complete"| JOBS
  LD <-->|"maintain"| JOBS

  classDef app fill:#eef4ff,stroke:#3b6fd8,color:#0b1f44,stroke-width:1.5px
  classDef db fill:#e9f7ef,stroke:#2f9e5c,color:#0d2e1a,stroke-width:1.5px
  classDef core fill:#f3eefe,stroke:#7a52d1,color:#22134a,stroke-width:1.5px
  classDef lead fill:#fff5e6,stroke:#d98a1c,color:#3d2504,stroke-width:1.5px
  class APP app
  class JOBS,BUS db
  class PROD,WP,DONE core
  class SCH,PER,RES,CLN lead
  style PG fill:#f6fcf8,stroke:#2f9e5c,stroke-dasharray:4 3
  style CL fill:#faf8ff,stroke:#7a52d1,stroke-dasharray:4 3
  style LD fill:#fffaf2,stroke:#d98a1c,stroke-dasharray:4 3

Jobs are rows in Postgres, written in your transaction. Every client fetches and runs jobs; one elected leader schedules, rescues and cleans up.

Why

Background jobs often live in Redis or RabbitMQ, a second system that cannot join your database transaction. Foreman stores jobs in the Postgres you already run, so a job is enqueued only if your transaction commits. It also limits concurrency per tenant and keeps one busy tenant from starving the others.

Install

go get github.com/thnhdatle/foreman@v0.1.1                    # library
go install github.com/thnhdatle/foreman/cmd/foreman@v0.1.1    # admin CLI
docker run --rm ghcr.io/thnhdatle/foreman:v0.1.1 version      # admin CLI in Docker

Prebuilt CLI binaries for Linux and macOS are on the releases page.

Quickstart

Needs Go 1.27+ and Docker. From a clone of this repository:

docker compose -f deploy/docker-compose.yml up -d --wait postgres
go run ./examples/basic

It prints job completed: id=1 state=completed.

Usage

type EmailArgs struct {
	UserID int64 `json:"user_id"`
}

func (EmailArgs) Kind() string { return "email" }

type EmailWorker struct{}

func (EmailWorker) Work(ctx context.Context, job *foreman.Job[EmailArgs]) error {
	return sendWelcome(ctx, job.Args.UserID)
}

workers := foreman.NewWorkers()
foreman.AddWorker(workers, EmailWorker{})
client, err := foreman.NewClient(pool, foreman.Config{Workers: workers})

// Enqueue in the same transaction as your data.
_, err = client.InsertTx(ctx, tx, EmailArgs{UserID: id}, nil)

A job can run more than once if its worker dies, so make workers idempotent. Migrations, shutdown, retries, cron, unique jobs and fairness are covered in the guides.

Performance

MacBook Pro M3 Pro 36 GB, Postgres 17 in Docker (8 CPU / 20 GB), Foreman v0.1.0, median of 3 runs. Clients run natively; load is open-model (inserts at a fixed rate, never waiting for workers).

Scenario Result
Throughput, no-op jobs, 4 clients × 50 workers, 5 min 35,518 jobs/s
Pickup latency p99 at 1,000 inserts/s, 2 min 8.7 ms
Small tenant p95 wait behind a 240k backlog, fair vs unfair 38 ms vs 64.6 s
1 h soak at 1,000 jobs/s: table size drift, p99 drift 0.3%, -0.1%

Documentation

Documentation

Overview

Package foreman is a Postgres-backed job queue for Go. Jobs are enqueued in the same transaction as your data.

Example
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/jackc/pgx/v5/pgxpool"

	"github.com/thnhdatle/foreman"
	"github.com/thnhdatle/foreman/migrate"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

type EmailWorker struct{}

func (w *EmailWorker) Work(ctx context.Context, job *foreman.Job[EmailArgs]) error {
	fmt.Printf("sending %s to user %d\n", job.Args.Tmpl, job.Args.UserID)
	return nil
}

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	pool, err := pgxpool.New(ctx, "postgres://foreman:foreman@localhost:55432/foreman")
	if err != nil {
		return err
	}
	defer pool.Close()
	if err := migrate.Up(ctx, pool); err != nil {
		return err
	}
	workers := foreman.NewWorkers()
	foreman.AddWorker(workers, &EmailWorker{})
	client, err := foreman.NewClient(pool, foreman.Config{
		Queues:  map[string]foreman.QueueConfig{"default": {MaxWorkers: 50, PerKeyLimit: 5, Fairness: true}},
		Workers: workers,
	})
	if err != nil {
		return err
	}
	if err := client.Start(ctx); err != nil {
		return err
	}
	defer func() { _ = client.Stop(ctx) }()

	tx, err := pool.Begin(ctx)
	if err != nil {
		return err
	}
	defer func() { _ = tx.Rollback(ctx) }()
	if _, err := client.InsertTx(ctx, tx, EmailArgs{UserID: 42, Tmpl: "welcome"},
		&foreman.InsertOpts{ConcurrencyKey: "tenant-7"}); err != nil {
		return err
	}
	return tx.Commit(ctx)
}

Index

Examples

Constants

View Source
const (
	DefaultListLimit = 50
	MaxListLimit     = 500
)

Pagination limits of JobList.

View Source
const (
	DefaultMaxWorkers            = 10
	DefaultFetchInterval         = time.Second
	DefaultHeartbeatInterval     = 30 * time.Second
	DefaultRescueStuckJobsAfter  = time.Hour
	DefaultCompletedJobRetention = 24 * time.Hour
	DefaultCancelledJobRetention = 7 * 24 * time.Hour
	DefaultDiscardedJobRetention = 7 * 24 * time.Hour
	DefaultReindexInterval       = 24 * time.Hour
	DefaultCleanerInterval       = 30 * time.Second
	DefaultMaxArgsBytes          = 1 << 20
	DefaultSchema                = "public"
)

Defaults of Config.

View Source
const (
	DefaultQueue       = "default"
	DefaultPriority    = 2
	DefaultMaxAttempts = 25
)

Default insert values.

Variables

View Source
var (
	// ErrArgsTooLarge reports args whose JSON exceeds Config.MaxArgsBytes.
	ErrArgsTooLarge = errors.New("foreman: args too large")
	// ErrUniqueArgsNotCanonical reports a non-integral number in unique args.
	ErrUniqueArgsNotCanonical = unique.ErrArgsNotCanonical
	// ErrInvalidConfig wraps every problem found by NewClient.
	ErrInvalidConfig = errors.New("foreman: invalid config")
	// ErrInvalidInsertOpts wraps every problem with InsertOpts or UniqueOpts.
	ErrInvalidInsertOpts = errors.New("foreman: invalid insert options")
	// ErrInvalidArgument reports a nil or malformed argument.
	ErrInvalidArgument = errors.New("foreman: invalid argument")
	// ErrNotFound reports a job id that does not exist.
	ErrNotFound = job.ErrNotFound
	// ErrInvalidTransition reports an admin operation not allowed in the job's state.
	ErrInvalidTransition = job.ErrInvalidTransition
	// ErrUniqueConflict reports a retry that would duplicate a unique job.
	ErrUniqueConflict = job.ErrUniqueConflict
	// ErrStaleJob reports that the attempt is no longer owned by this client.
	ErrStaleJob = job.ErrStale
	// ErrNotInWorker reports a call that is only valid inside Worker.Work.
	ErrNotInWorker = errors.New("foreman: not called from inside Work")
	// ErrAlreadyStarted reports a second Start of a running client.
	ErrAlreadyStarted = errors.New("foreman: client already started")
	// ErrNotStarted reports Stop of a client that is not running.
	ErrNotStarted = errors.New("foreman: client not started")
	// ErrSchemaNotMigrated reports a database without the required Foreman schema.
	ErrSchemaNotMigrated = errors.New("foreman: schema not migrated")
	// ErrNoWorker reports a kind without a registered worker.
	ErrNoWorker = job.ErrNoWorker
	// ErrClientStopping is the cause of a job's context when the client cancels it on shutdown.
	ErrClientStopping = job.ErrClientStopping
)

Errors returned by Foreman.

Functions

func AddWorker

func AddWorker[T JobArgs](w *Workers, worker Worker[T], opts ...WorkerOption)

AddWorker registers worker for the kind of T.

Example
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	workers := foreman.NewWorkers()
	foreman.AddWorker(workers, foreman.WorkFunc[EmailArgs](func(ctx context.Context, job *foreman.Job[EmailArgs]) error {
		return nil
	}), foreman.WithTimeout(time.Minute), foreman.WithMaxAttempts(5),
		foreman.WithRetryPolicy(foreman.ConstantBackoff{Delay: 10 * time.Second}))
	fmt.Println(workers.Kinds())
}
Output:
[email]

func Cancel

func Cancel(err error) error

Cancel returns an error that cancels the job.

Example
package main

import (
	"errors"
	"fmt"

	"github.com/thnhdatle/foreman"
)

func main() {
	err := foreman.Cancel(errors.New("user deleted"))
	fmt.Println(err)
}
Output:
job cancelled: user deleted

func CompleteTx

func CompleteTx[T JobArgs](ctx context.Context, tx pgx.Tx, job *Job[T]) error

CompleteTx marks the job completed inside tx.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	_ = foreman.WorkFunc[EmailArgs](func(ctx context.Context, job *foreman.Job[EmailArgs]) error {
		tx, err := foreman.ClientFromContext(ctx).Pool().Begin(ctx)
		if err != nil {
			return err
		}
		defer func() { _ = tx.Rollback(ctx) }()
		if err := foreman.CompleteTx(ctx, tx, job); err != nil {
			return err
		}
		return tx.Commit(ctx)
	})
}

func DecodeArgs

func DecodeArgs[T JobArgs](row *JobRow) (T, error)

DecodeArgs decodes the args of row into T. It fails if row is of another kind.

Example
package main

import (
	"fmt"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	row := &foreman.JobRow{ID: 1, Kind: "email", Args: []byte(`{"user_id":7,"tmpl":"welcome"}`)}
	args, err := foreman.DecodeArgs[EmailArgs](row)
	fmt.Println(args.UserID, args.Tmpl, err)
}
Output:
7 welcome <nil>

func Discard

func Discard(err error) error

Discard returns an error that discards the job.

Example
package main

import (
	"errors"
	"fmt"

	"github.com/thnhdatle/foreman"
)

func main() {
	err := foreman.Discard(errors.New("template does not exist"))
	fmt.Println(err)
}
Output:
job discarded: template does not exist

func Heartbeat

func Heartbeat(ctx context.Context)

Heartbeat refreshes the heartbeat of the running job.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	_ = foreman.WorkFunc[EmailArgs](func(ctx context.Context, job *foreman.Job[EmailArgs]) error {
		for i := 0; i < 10; i++ {
			foreman.Heartbeat(ctx)
		}
		return nil
	})
}

func Snooze

func Snooze(d time.Duration) error

Snooze returns an error that runs the job again after d without using an attempt.

Example
package main

import (
	"fmt"
	"time"

	"github.com/thnhdatle/foreman"
)

func main() {
	err := foreman.Snooze(30 * time.Second)
	fmt.Println(err)
}
Output:
job snoozed for 30s

Types

type AttemptError

type AttemptError struct {
	At      time.Time `json:"at"`
	Attempt int       `json:"attempt"`
	Error   string    `json:"error"`
	Trace   string    `json:"trace,omitempty"`
}

AttemptError records one failed attempt of a job.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client inserts jobs and runs worker pools and maintenance services.

func ClientFromContext

func ClientFromContext(ctx context.Context) *Client

ClientFromContext returns the client running the job, or nil outside Work.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	_ = foreman.WorkFunc[EmailArgs](func(ctx context.Context, job *foreman.Job[EmailArgs]) error {
		client := foreman.ClientFromContext(ctx)
		_, err := client.Insert(ctx, EmailArgs{UserID: job.Args.UserID, Tmpl: "follow-up"}, nil)
		return err
	})
}

func NewClient

func NewClient(pool *pgxpool.Pool, cfg Config) (*Client, error)

NewClient validates cfg and returns a client using pool.

Example
package main

import (
	"errors"
	"fmt"

	"github.com/jackc/pgx/v5/pgxpool"

	"github.com/thnhdatle/foreman"
)

func main() {
	var pool *pgxpool.Pool
	_, err := foreman.NewClient(pool, foreman.Config{})
	fmt.Println(errors.Is(err, foreman.ErrInvalidArgument))
}
Output:
true

func (*Client) ID

func (c *Client) ID() string

ID returns the client id used in attempted_by and the leader lease.

func (*Client) Insert

func (c *Client) Insert(ctx context.Context, args JobArgs, opts *InsertOpts) (*InsertResult, error)

Insert inserts one job. It is committed immediately.

Example
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	var client *foreman.Client
	res, err := client.Insert(context.Background(), EmailArgs{UserID: 1, Tmpl: "reset"}, &foreman.InsertOpts{
		Queue:      "mail",
		Priority:   1,
		UniqueOpts: &foreman.UniqueOpts{ByArgs: true, ByPeriod: time.Hour},
	})
	if err == nil && res.UniqueSkippedAsDuplicate {
		fmt.Println("already queued as job", res.Job.ID)
	}
}

func (*Client) InsertMany

func (c *Client) InsertMany(ctx context.Context, params []InsertParams) ([]*InsertResult, error)

InsertMany inserts a batch in one transaction.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	var client *foreman.Client
	params := make([]foreman.InsertParams, 0, 100)
	for i := int64(0); i < 100; i++ {
		params = append(params, foreman.InsertParams{Args: EmailArgs{UserID: i, Tmpl: "digest"}})
	}
	_, _ = client.InsertMany(context.Background(), params)
}

func (*Client) InsertManyTx

func (c *Client) InsertManyTx(ctx context.Context, tx pgx.Tx, params []InsertParams) ([]*InsertResult, error)

InsertManyTx inserts a batch in tx.

Example
package main

import (
	"context"

	"github.com/jackc/pgx/v5"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	var (
		client *foreman.Client
		tx     pgx.Tx
	)
	_, _ = client.InsertManyTx(context.Background(), tx, []foreman.InsertParams{
		{Args: EmailArgs{UserID: 1}}, {Args: EmailArgs{UserID: 2}},
	})
}

func (*Client) InsertTx

func (c *Client) InsertTx(ctx context.Context, tx pgx.Tx, args JobArgs, opts *InsertOpts) (*InsertResult, error)

InsertTx inserts one job in tx.

Example
package main

import (
	"context"

	"github.com/jackc/pgx/v5"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	var (
		client *foreman.Client
		tx     pgx.Tx
	)
	_, _ = client.InsertTx(context.Background(), tx, EmailArgs{UserID: 2, Tmpl: "welcome"}, nil)
}

func (*Client) IsLeader

func (c *Client) IsLeader() bool

IsLeader reports whether this client currently runs the leader services.

func (*Client) JobCancel

func (c *Client) JobCancel(ctx context.Context, id int64) (*JobRow, error)

JobCancel cancels a job.

Example
package main

import (
	"context"
	"fmt"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	job, err := client.JobCancel(context.Background(), 123)
	if err == nil && job.State == foreman.StateRunning {
		fmt.Println("cancel requested; the job ends as cancelled when Work returns")
	}
}

func (*Client) JobDeleteMany

func (c *Client) JobDeleteMany(ctx context.Context, f *JobFilter) (int, error)

JobDeleteMany deletes matching jobs except running ones and returns how many.

Example
package main

import (
	"context"
	"time"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	_, _ = client.JobDeleteMany(context.Background(), &foreman.JobFilter{
		States: []foreman.State{foreman.StateCompleted}, CreatedBefore: time.Now().Add(-30 * 24 * time.Hour),
	})
}

func (*Client) JobDiscard

func (c *Client) JobDiscard(ctx context.Context, id int64) (*JobRow, error)

JobDiscard moves a job to discarded.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	_, _ = client.JobDiscard(context.Background(), 123)
}

func (*Client) JobDiscardMany

func (c *Client) JobDiscardMany(ctx context.Context, f *JobFilter) (int, error)

JobDiscardMany discards every non-final job matching f and returns how many.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	_, _ = client.JobDiscardMany(context.Background(), &foreman.JobFilter{Queues: []string{"legacy"}})
}

func (*Client) JobGet

func (c *Client) JobGet(ctx context.Context, id int64) (*JobRow, error)

JobGet returns one job, or ErrNotFound.

Example
package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	job, err := client.JobGet(context.Background(), 123)
	if errors.Is(err, foreman.ErrNotFound) {
		return
	}
	fmt.Println(job.State, len(job.Errors))
}

func (*Client) JobList

func (c *Client) JobList(ctx context.Context, p *JobListParams) (*JobListResult, error)

JobList lists jobs newest first with cursor pagination.

Example
package main

import (
	"context"
	"fmt"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	params := &foreman.JobListParams{States: []foreman.State{foreman.StateDiscarded}, Limit: 100}
	for {
		page, err := client.JobList(context.Background(), params)
		if err != nil {
			return
		}
		for _, j := range page.Jobs {
			fmt.Println(j.ID, j.Kind)
		}
		if page.NextCursor == "" {
			return
		}
		params.Cursor = page.NextCursor
	}
}

func (*Client) JobRetry

func (c *Client) JobRetry(ctx context.Context, id int64) (*JobRow, error)

JobRetry moves a finished job back to available.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	_, _ = client.JobRetry(context.Background(), 123)
}

func (*Client) JobRetryMany

func (c *Client) JobRetryMany(ctx context.Context, f *JobFilter) (int, error)

JobRetryMany retries every final job matching f and returns how many.

Example
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	n, _ := client.JobRetryMany(context.Background(), &foreman.JobFilter{
		Kinds: []string{"email"}, States: []foreman.State{foreman.StateDiscarded},
		CreatedAfter: time.Now().Add(-24 * time.Hour),
	})
	fmt.Println("retried", n)
}

func (*Client) JobWork

func (c *Client) JobWork(ctx context.Context, id int64) (*JobRow, error)

JobWork runs one available job synchronously on this client.

Example
package main

import (
	"context"
	"fmt"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	var client *foreman.Client
	res, _ := client.Insert(context.Background(), EmailArgs{UserID: 3}, nil)
	job, _ := client.JobWork(context.Background(), res.Job.ID)
	fmt.Println(job.State)
}

func (*Client) LeaderGet

func (c *Client) LeaderGet(ctx context.Context) (*LeaderInfo, error)

LeaderGet returns the current lease, or ErrNotFound when no client holds one.

Example
package main

import (
	"context"
	"fmt"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	if l, err := client.LeaderGet(context.Background()); err == nil {
		fmt.Println(l.LeaderID, l.ExpiresAt)
	}
}

func (*Client) PeriodicList

func (c *Client) PeriodicList(ctx context.Context) ([]*PeriodicInfo, error)

PeriodicList lists periodic jobs that have enqueued at least one tick.

Example
package main

import (
	"context"
	"fmt"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	ps, _ := client.PeriodicList(context.Background())
	for _, p := range ps {
		fmt.Println(p.Name, p.LastTick)
	}
}

func (*Client) Pool

func (c *Client) Pool() *pgxpool.Pool

Pool returns the pool the client uses.

func (*Client) QueueList

func (c *Client) QueueList(ctx context.Context) ([]*QueueInfo, error)

QueueList lists the queues known to the database.

Example
package main

import (
	"context"
	"fmt"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	queues, _ := client.QueueList(context.Background())
	for _, q := range queues {
		fmt.Println(q.Name, q.Paused, q.Available, q.Running)
	}
}

func (*Client) QueuePause

func (c *Client) QueuePause(ctx context.Context, name string) error

QueuePause stops clients from fetching jobs of the queue.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	ctx := context.Background()
	_ = client.QueuePause(ctx, "mail")
	_ = client.QueueResume(ctx, "mail")
}

func (*Client) QueueResume

func (c *Client) QueueResume(ctx context.Context, name string) error

QueueResume lets clients fetch jobs of the queue again.

Example
package main

import (
	"context"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	_ = client.QueueResume(context.Background(), "mail")
}

func (*Client) Schema

func (c *Client) Schema() string

Schema returns the schema holding the Foreman tables.

func (*Client) Start

func (c *Client) Start(ctx context.Context) error

Start runs the worker pools, heartbeats, LISTEN connection and leader election.

Example
package main

import (
	"context"
	"log"
	"time"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	ctx := context.Background()
	if err := client.Start(ctx); err != nil {
		log.Fatal(err)
	}
	stopCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
	defer cancel()
	_ = client.Stop(stopCtx)
}

func (*Client) Stop

func (c *Client) Stop(ctx context.Context) error

Stop shuts down gracefully, waiting for running jobs until ctx is done.

func (*Client) StopAndCancel

func (c *Client) StopAndCancel(ctx context.Context) error

StopAndCancel cancels running jobs at once and waits for them.

Example
package main

import (
	"context"
	"time"

	"github.com/thnhdatle/foreman"
)

func main() {
	var client *foreman.Client
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	_ = client.StopAndCancel(ctx)
}

type Clock

type Clock = clock.Clock

Clock is the time source of a client.

type Config

type Config struct {
	// Queues served by this client. With none it is producer-only.
	Queues       map[string]QueueConfig
	Workers      *Workers
	PeriodicJobs []*PeriodicJob
	Logger       *slog.Logger
	Clock        Clock
	// ID identifies the client. Default hostname-pid-random.
	ID string
	// Schema holding the Foreman tables. Default public.
	Schema string
	// JobTimeout is the default timeout of Work. 0 means none.
	JobTimeout time.Duration
	// RescueStuckJobsAfter is how long a running job may go without a heartbeat. Default 1h.
	RescueStuckJobsAfter time.Duration
	// HeartbeatInterval is the time between heartbeats. Default 30s.
	HeartbeatInterval time.Duration
	// RetryPolicy defaults to ExponentialBackoff{}.
	RetryPolicy RetryPolicy
	// CompletedJobRetention defaults to 24h. Negative keeps jobs forever.
	CompletedJobRetention time.Duration
	// CancelledJobRetention defaults to 7 days. Negative keeps jobs forever.
	CancelledJobRetention time.Duration
	// DiscardedJobRetention defaults to 7 days. Negative keeps jobs forever.
	DiscardedJobRetention time.Duration
	// ReindexInterval defaults to 24h. Negative disables it.
	ReindexInterval time.Duration
	// CleanerInterval defaults to 30s.
	CleanerInterval time.Duration
	ErrorHandler    ErrorHandler
	Middleware      []Middleware
	// PollOnly disables LISTEN/NOTIFY and relies on polling.
	PollOnly bool
	// MaxArgsBytes bounds the JSON size of args. Default 1 MiB.
	MaxArgsBytes   int
	TracerProvider trace.TracerProvider
	Registerer     prometheus.Registerer
}

Config configures a client. Zero fields select their defaults.

type ConstantBackoff

type ConstantBackoff struct {
	Delay time.Duration
}

ConstantBackoff waits a fixed Delay.

func (ConstantBackoff) NextRetry

func (c ConstantBackoff) NextRetry(_ JobRow, now time.Time) time.Time

NextRetry implements RetryPolicy.

type ErrorHandler

type ErrorHandler interface {
	HandleError(ctx context.Context, job *JobRow, err error) *ErrorHandlerResult
	HandlePanic(ctx context.Context, job *JobRow, panicVal any, trace string) *ErrorHandlerResult
}

ErrorHandler is notified of failed attempts and may override the outcome.

type ErrorHandlerResult

type ErrorHandlerResult struct {
	SetCancelled bool
	SetDiscarded bool
	SnoozeFor    time.Duration
}

ErrorHandlerResult overrides the outcome of a failed attempt.

type ExponentialBackoff

type ExponentialBackoff struct {
	Base time.Duration
	Cap  time.Duration
}

ExponentialBackoff waits an exponentially growing, jittered delay.

Example
package main

import (
	"fmt"
	"time"

	"github.com/thnhdatle/foreman"
)

func main() {
	p := foreman.ExponentialBackoff{Base: time.Second, Cap: time.Hour}
	now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
	next := p.NextRetry(foreman.JobRow{Attempt: 3}, now)
	fmt.Println(next.Sub(now) < 4*time.Second)
}
Output:
true

func (ExponentialBackoff) NextRetry

func (e ExponentialBackoff) NextRetry(job JobRow, now time.Time) time.Time

NextRetry implements RetryPolicy.

type InsertOpts

type InsertOpts struct {
	// Queue defaults to "default".
	Queue string
	// Priority is 1 to 4, where 1 runs first. Default 2.
	Priority int
	// ScheduledAt in the future schedules the job.
	ScheduledAt time.Time
	// MaxAttempts defaults to 25.
	MaxAttempts int
	Tags        []string
	// Metadata must be a JSON object.
	Metadata json.RawMessage
	// ConcurrencyKey groups jobs for per-key limits and fairness (for example a tenant id).
	ConcurrencyKey string
	UniqueOpts     *UniqueOpts
	Timeout        time.Duration
}

InsertOpts are per-job options.

type InsertParams

type InsertParams struct {
	Args       JobArgs
	InsertOpts *InsertOpts
}

InsertParams is one job of an InsertMany call.

type InsertResult

type InsertResult struct {
	Job                      *JobRow
	UniqueSkippedAsDuplicate bool
}

InsertResult is the outcome of inserting one job.

type Job

type Job[T JobArgs] struct {
	ID          int64
	Args        T
	Attempt     int
	MaxAttempts int
	Queue       string
	Priority    int
	Tags        []string
	Metadata    json.RawMessage
	CreatedAt   time.Time
	ScheduledAt time.Time
	Errors      []AttemptError
}

Job is a job with decoded, typed args, as passed to Worker.Work.

type JobArgs

type JobArgs interface {
	Kind() string
}

JobArgs is the payload of a job.

type JobArgsWithInsertOpts

type JobArgsWithInsertOpts interface {
	JobArgs
	InsertOpts() InsertOpts
}

JobArgsWithInsertOpts is implemented by args types that provide insert defaults.

type JobFilter

type JobFilter struct {
	Kinds         []string
	Queues        []string
	States        []State
	CreatedAfter  time.Time
	CreatedBefore time.Time
}

JobFilter selects jobs for bulk operations.

type JobListParams

type JobListParams struct {
	States []State
	Kinds  []string
	Queues []string
	// Limit defaults to 50 and is at most 500.
	Limit  int
	Cursor string
}

JobListParams filters JobList.

type JobListResult

type JobListResult struct {
	Jobs       []*JobRow
	NextCursor string
}

JobListResult is one page of jobs, newest first.

type JobRow

type JobRow struct {
	ID                int64
	Kind              string
	Queue             string
	Args              json.RawMessage
	State             State
	Priority          int
	Attempt           int
	MaxAttempts       int
	ScheduledAt       time.Time
	CreatedAt         time.Time
	AttemptedAt       *time.Time
	FinalizedAt       *time.Time
	HeartbeatAt       *time.Time
	CancelRequestedAt *time.Time
	AttemptedBy       []string
	Errors            []AttemptError
	Tags              []string
	Metadata          json.RawMessage
	UniqueKey         []byte
	UniqueStates      []State
	ConcurrencyKey    string
	Timeout           time.Duration
}

JobRow is a job as stored in the database, with undecoded args.

type LeaderInfo

type LeaderInfo struct {
	LeaderID  string
	ElectedAt time.Time
	ExpiresAt time.Time
}

LeaderInfo describes the current leader lease.

type Middleware

type Middleware interface {
	InsertMany(ctx context.Context, params []InsertParams, next func(ctx context.Context) ([]*InsertResult, error)) (
		[]*InsertResult, error)
	Work(ctx context.Context, job *JobRow, next func(ctx context.Context) error) error
}

Middleware wraps inserts and work.

type MiddlewareDefaults

type MiddlewareDefaults struct{}

MiddlewareDefaults is a pass-through Middleware to embed.

func (MiddlewareDefaults) InsertMany

func (MiddlewareDefaults) InsertMany(
	ctx context.Context, _ []InsertParams, next func(ctx context.Context) ([]*InsertResult, error),
) ([]*InsertResult, error)

InsertMany calls next.

func (MiddlewareDefaults) Work

func (MiddlewareDefaults) Work(ctx context.Context, _ *JobRow, next func(ctx context.Context) error) error

Work calls next.

type PeriodicInfo

type PeriodicInfo struct {
	Name     string
	LastTick time.Time
	Ticks    int64
}

PeriodicInfo summarises the ticks enqueued for one periodic job.

type PeriodicJob

type PeriodicJob struct {
	Name       string
	Schedule   Schedule
	Args       func() (JobArgs, *InsertOpts)
	RunOnStart bool
	// CatchUp is how far back missed ticks are enqueued.
	CatchUp time.Duration
	// TimeZone evaluates cron expressions. Default UTC.
	TimeZone *time.Location
}

PeriodicJob is a job the leader enqueues on a schedule.

type QueueConfig

type QueueConfig struct {
	// MaxWorkers is how many jobs run at once. Default 10.
	MaxWorkers int
	// FetchInterval is the polling interval. Default 1s.
	FetchInterval time.Duration
	// PerKeyLimit caps running jobs per concurrency key. 0 means no limit.
	PerKeyLimit int
	// Fairness alternates between concurrency keys when jobs are backlogged.
	Fairness bool
}

QueueConfig configures one queue served by a client.

type QueueInfo

type QueueInfo struct {
	Name       string
	Paused     bool
	PausedAt   *time.Time
	LastSeenAt *time.Time
	Available  int64
	Scheduled  int64
	Running    int64
	Retryable  int64
}

QueueInfo describes a queue and its pending jobs.

type RetryPolicy

type RetryPolicy interface {
	NextRetry(job JobRow, now time.Time) time.Time
}

RetryPolicy decides when a failed job runs again.

type RetryPolicyFunc

type RetryPolicyFunc func(job JobRow, now time.Time) time.Time

RetryPolicyFunc adapts a function to RetryPolicy.

func (RetryPolicyFunc) NextRetry

func (f RetryPolicyFunc) NextRetry(job JobRow, now time.Time) time.Time

NextRetry calls f.

type Schedule

type Schedule interface {
	Next(t time.Time) time.Time
}

Schedule computes the ticks of a periodic job.

func Cron

func Cron(expr string) (Schedule, error)

Cron parses a cron expression.

Example
package main

import (
	"fmt"
	"log"
	"time"

	"github.com/thnhdatle/foreman"
)

func main() {
	s, err := foreman.Cron("0 9 * * MON")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(s.Next(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)))
}
Output:
2026-01-05 09:00:00 +0000 UTC

func Every

func Every(d time.Duration) Schedule

Every returns a schedule ticking every d.

Example
package main

import (
	"fmt"
	"time"

	"github.com/thnhdatle/foreman"
)

func main() {
	s := foreman.Every(15 * time.Minute)
	fmt.Println(s.Next(time.Date(2026, 1, 1, 10, 7, 0, 0, time.UTC)))
}
Output:
2026-01-01 10:15:00 +0000 UTC

func MustCron

func MustCron(expr string) Schedule

MustCron is Cron that panics on an invalid expression.

Example
package main

import (
	"fmt"
	"time"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

func main() {
	job := &foreman.PeriodicJob{
		Name:     "daily-report",
		Schedule: foreman.MustCron("@daily"),
		Args:     func() (foreman.JobArgs, *foreman.InsertOpts) { return EmailArgs{Tmpl: "report"}, nil },
		CatchUp:  time.Hour,
	}
	fmt.Println(job.Name, job.Schedule != nil, job.Args != nil, job.CatchUp)
}
Output:
daily-report true true 1h0m0s

type State

type State string

State is the lifecycle state of a job.

const (
	StateAvailable State = "available"
	StateScheduled State = "scheduled"
	StateRunning   State = "running"
	StateRetryable State = "retryable"
	StateCompleted State = "completed"
	StateCancelled State = "cancelled"
	StateDiscarded State = "discarded"
)

Job states.

type Ticker

type Ticker = clock.Ticker

Ticker is a ticker created by a Clock.

type UniqueOpts

type UniqueOpts struct {
	ByArgs      bool
	ByArgFields []string
	ByPeriod    time.Duration
	ByQueue     bool
	// ByState defaults to available, scheduled, running, retryable and completed.
	ByState []State
}

UniqueOpts selects the identity of a unique job.

type WorkFunc

type WorkFunc[T JobArgs] func(ctx context.Context, job *Job[T]) error

WorkFunc adapts a function to the Worker interface.

func (WorkFunc[T]) Work

func (f WorkFunc[T]) Work(ctx context.Context, job *Job[T]) error

Work calls f.

type Worker

type Worker[T JobArgs] interface {
	Work(ctx context.Context, job *Job[T]) error
}

Worker handles jobs of one kind.

type WorkerOption

type WorkerOption func(*workerEntry)

WorkerOption configures the jobs of one kind.

func WithMaxAttempts

func WithMaxAttempts(n int) WorkerOption

WithMaxAttempts sets the default max attempts of the kind.

func WithRetryPolicy

func WithRetryPolicy(p RetryPolicy) WorkerOption

WithRetryPolicy sets the retry policy of the kind (default: client policy).

func WithTimeout

func WithTimeout(d time.Duration) WorkerOption

WithTimeout sets the default timeout of the kind.

type Workers

type Workers struct {
	// contains filtered or unexported fields
}

Workers is the registry of workers by kind.

func NewWorkers

func NewWorkers() *Workers

NewWorkers returns an empty registry.

Example
package main

import (
	"context"
	"fmt"

	"github.com/thnhdatle/foreman"
)

type EmailArgs struct {
	UserID int64  `json:"user_id"`
	Tmpl   string `json:"tmpl"`
}

func (EmailArgs) Kind() string { return "email" }

type EmailWorker struct{}

func (w *EmailWorker) Work(ctx context.Context, job *foreman.Job[EmailArgs]) error {
	fmt.Printf("sending %s to user %d\n", job.Args.Tmpl, job.Args.UserID)
	return nil
}

func main() {
	workers := foreman.NewWorkers()
	foreman.AddWorker(workers, &EmailWorker{})
	fmt.Println(len(workers.Kinds()))
}
Output:
1

func (*Workers) Kinds

func (w *Workers) Kinds() []string

Kinds returns the registered kinds, sorted.

Directories

Path Synopsis
cmd
foreman command
Command foreman is the Foreman admin CLI.
Command foreman is the Foreman admin CLI.
examples
basic command
Command basic enqueues a job in a transaction and waits for it to complete.
Command basic enqueues a job in a transaction and waits for it to complete.
cancel-long-job command
Command cancel-long-job cancels a running job.
Command cancel-long-job cancels a running job.
insert-from-python command
Command insert-from-python runs a Go worker for jobs enqueued by a Python script.
Command insert-from-python runs a Go worker for jobs enqueued by a Python script.
internal/exampledb
Package exampledb connects the examples to Postgres with a freshly migrated schema.
Package exampledb connects the examples to Postgres with a freshly migrated schema.
multi-tenant-fairness command
Command multi-tenant-fairness shows a small tenant served despite a large backlog.
Command multi-tenant-fairness shows a small tenant served despite a large backlog.
otel command
Command otel traces job work with OpenTelemetry.
Command otel traces job work with OpenTelemetry.
periodic command
Command periodic enqueues a job every second through the leader.
Command periodic enqueues a job every second through the leader.
transactional-enqueue command
Command transactional-enqueue shows a job inserted in a transaction.
Command transactional-enqueue shows a job inserted in a transaction.
unique command
Command unique inserts the same unique job twice.
Command unique inserts the same unique job twice.
Package foremanhttp provides an embeddable admin JSON API for a Foreman client.
Package foremanhttp provides an embeddable admin JSON API for a Foreman client.
Package foremantest provides helpers for testing code that uses Foreman.
Package foremantest provides helpers for testing code that uses Foreman.
internal
adapter/pgstore
Package pgstore implements the job store ports on Postgres with pgx.
Package pgstore implements the job store ports on Postgres with pgx.
app/completer
Package completer writes job completions and heartbeats to the database in batches.
Package completer writes job completions and heartbeats to the database in batches.
app/elector
Package elector elects one leader per cluster with a lease row.
Package elector elects one leader per cluster with a lease row.
app/executor
Package executor runs one attempt of a job and maps the result to a completion.
Package executor runs one attempt of a job and maps the result to a completion.
app/maintenance
Package maintenance runs the leader-only background services and the cancel poller.
Package maintenance runs the leader-only background services and the cancel poller.
app/notifier
Package notifier shares one Postgres LISTEN connection between subscribers and reconnects when it drops.
Package notifier shares one Postgres LISTEN connection between subscribers and reconnects when it drops.
app/producer
Package producer runs the fetch loop of one queue and runs each fetched job on its own goroutine.
Package producer runs the fetch loop of one queue and runs each fetched job on its own goroutine.
cli
Package cli implements the foreman admin CLI.
Package cli implements the foreman admin CLI.
config
Package config loads and validates the configuration of the foreman CLI.
Package config loads and validates the configuration of the foreman CLI.
domain/backoff
Package backoff provides retry delay policies.
Package backoff provides retry delay policies.
domain/fairness
Package fairness decides how a fetch is split between concurrency keys.
Package fairness decides how a fetch is split between concurrency keys.
domain/job
Package job defines the job row, its state machine and the mapping from a work result to a completion.
Package job defines the job row, its state machine and the mapping from a work result to a completion.
domain/schedule
Package schedule provides cron and fixed-interval schedules and finds the ticks that are due.
Package schedule provides cron and fixed-interval schedules and finds the ticks that are due.
domain/unique
Package unique builds the identity of unique jobs from their options.
Package unique builds the identity of unique jobs from their options.
platform/clock
Package clock provides the injectable time source.
Package clock provides the injectable time source.
platform/metrics
Package metrics defines the Prometheus collectors of a Foreman client.
Package metrics defines the Prometheus collectors of a Foreman client.
platform/tracing
Package tracing creates OpenTelemetry spans for job work and inserts.
Package tracing creates OpenTelemetry spans for job work and inserts.
testutil
Package testutil holds helpers shared by tests.
Package testutil holds helpers shared by tests.
testutil/pgtest
Package pgtest provides Postgres for integration tests.
Package pgtest provides Postgres for integration tests.
Package migrate installs and removes the Foreman schema with embedded SQL migrations.
Package migrate installs and removes the Foreman schema with embedded SQL migrations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL