beatfx

README

beatfx

Run recurring or one-shot beat work with Uber Fx. The beat module owns execution, scheduling and cluster assignment. Beatfx owns Fx wiring and lifecycle. Configuration loading through confx is optional.

Install · Choose an adapter · Reference

Installation

Requires Go 1.27.0 or later and uses beat v0.8.0.

go get github.com/uchaloop/beatfx@latest

The module includes the scheduler adapter and the jobfx subpackage for one-shot execution. Both use github.com/uchaloop/beat/job types. Types from the former standalone job module are not interchangeable with these types.

Quick start

Scenario	Entry point	Guide
Long-lived scheduler	beatfx.Module() inside fx.New(...).Run()	Scheduler adapter
Kubernetes Job / CronJob or another one-shot process	jobfx.Execute(...)	One-shot execution
Manual one-shot lifecycle	jobfx.MakeApp or jobfx.New, then Start/Stop	App lifecycle

Import github.com/uchaloop/beatfx/jobfx for one-shot helpers. It is a package inside this module, not the former standalone jobfx module. Execute accepts ordinary Fx options, a lazy confx.App, or a configured jobfx.App; it exits only after cleanup. Use manual Start/Stop when caller-owned cleanup or error handling is needed. For a daemon, use Fx.Run or confx.New(...).Run with beatfx.Module.

Reference

• beat: execution and scheduling contracts
• API reference
• Scheduler example and one-shot example
• CHANGELOG

License

MIT

Documentation

Overview

Package beatfx connects one beat.Beat to an Fx lifecycle. Module requires beat.Config and a *job.Runner. beat.Handler and Options are optional. Provide Options once as an ordered slice; static Module options are applied first, followed by the slice. Repeated setter options use their last value.

A ready set can be supplied with fx.Supply(beatfx.Options{...}). A constructor returning Options can use dependencies from the container. The application owns Fx startup and shutdown budgets. Use one Module per Fx application.

Index

• func Module(opts ...beat.Option) fx.Option
• type Options

Examples

• Module

Functions

func Module

func Module(opts ...beat.Option) fx.Option

Module provides a private Beat and registers its Start and Stop hooks. Static opts are copied and applied before container-provided Options. Referenced option state remains shared.

Example

package main

import (
	"context"
	"log/slog"
	"time"

	"github.com/uchaloop/beat"
	"github.com/uchaloop/beat/job"
	"github.com/uchaloop/beat/job/middleware/recovery"
	"github.com/uchaloop/beatfx"
	"go.uber.org/fx"
)

func main() {
	app := fx.New(
		fx.Supply(beat.Config{Period: time.Minute}),
		fx.Supply(slog.Default()),

		// The runner carries the work, its middleware and its timeout.
		fx.Provide(func(log *slog.Logger) (*job.Runner, error) {
			return job.MakeRunner(
				job.Config{Timeout: 45 * time.Second},
				func(ctx context.Context) (int64, error) { return 0, ctx.Err() },
				job.WithMiddleware(recovery.MakeMiddleware(recovery.WithLogger(log))),
			)
		}),

		fx.Provide(func() beatfx.Options {
			return beatfx.Options{beat.WithGracefulStop()}
		}),

		beatfx.Module(),
		fx.StopTimeout(time.Minute),
		fx.NopLogger,
	)

	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	if err := app.Start(ctx); err != nil {
		panic(err)
	}
	if err := app.Stop(ctx); err != nil {
		panic(err)
	}
}

Types

type Options

type Options []beat.Option

Options is the ordered set of beat options an application builds from the container. Provide it once, and the order inside it is the order applied:

fx.Provide(func(db *sql.DB) beatfx.Options {
	return beatfx.Options{beat.WithOnStart(db.PingContext)}
})

A set that needs nothing from the container can be supplied outright with fx.Supply(beatfx.Options{...}), though such options can also go straight to Module.