flex

README

flex

A collection of packages for building Go services.

Quick Start

Below is an example for how to get running quickly.
This code can be found in the examples folder.

package main

import (
 "context"
 "fmt"
 "log"
 "net/http"

 "github.com/go-flexible/flex"
)

func main() {
        router := http.NewServeMux()
        router.HandleFunc("/", func(rw http.ResponseWriter, r *http.Request) {
                fmt.Fprint(rw, "hello, world\n")
        })

        srv := &http.Server{
                Addr:    ":8080",
                Handler: router,
        }

        flex.MustStart(
                context.Background(),
                NewHTTPServer(srv),
        )
}

// TODO: this functionality should be provided by a plugin.
// for now this is an example on how to implement our interfaces.
type Server struct{ *http.Server }

func NewHTTPServer(s *http.Server) *Server {
        return &Server{Server: s}
}

func (s *Server) Run(_ context.Context) error {
        log.Printf("serving on: http://localhost%s\n", s.Addr)
        return s.ListenAndServe()
}

func (s *Server) Halt(ctx context.Context) error {
        return s.Shutdown(ctx)
}

Contributors

Contributors listed in alphabetical order.

• Ben Cable: Author & Maintainer
• Zee Philip Vieira: Author & Maintainer

Documentation

Overview

Package flex provides a service lifecycle manager for Go applications.

It manages the concurrent startup, running, and graceful shutdown of service workers. Workers are started concurrently and run until one of the following occurs:

• A worker returns an error from Run()
• A signal (SIGINT, SIGKILL, SIGTERM) is received
• The provided context is canceled

When shutdown is triggered, all workers' Halt() methods are called concurrently with a fresh context that has DefaultHaltTimeout as its deadline, ensuring a graceful shutdown.

Start a service:

flex.MustStart(ctx, worker1, worker2)

Or with error handling:

if err := flex.Start(ctx, worker1, worker2); err != nil {
    log.Fatal(err)
}

With options:

err := flex.StartOpts(ctx, []flex.Worker{w1, w2}, flex.WithoutSignals())

Index

• Constants
• func MustStart(ctx context.Context, workers ...Worker)
• func SetLogger(l *log.Logger)
• func Start(ctx context.Context, workers ...Worker) error
• func StartOpts(ctx context.Context, workers []Worker, opts ...Option) error
• type Halter
• type Option
  • func WithoutSignals() Option
• type Runner
• type Worker

Constants

const DefaultHaltTimeout = 30 * time.Second

DefaultHaltTimeout is the default timeout for graceful shutdown of workers. This provides workers with a grace period to close connections, flush data, and clean up resources during the halt phase.

Functions

func MustStart

func MustStart(ctx context.Context, workers ...Worker)

MustStart is like Start, but panics if there is an error.

func SetLogger

func SetLogger(l *log.Logger)

SetLogger sets the package-level logger used by MustStart.

func Start

func Start(ctx context.Context, workers ...Worker) error

Start is a blocking operation that will start processing the workers.

Workers are started concurrently and run until one of the following occurs: 1. A worker returns an error from Run() 2. A signal (SIGINT, SIGKILL, SIGTERM) is received 3. The provided context is canceled

When shutdown is triggered, all workers' Halt() methods are called concurrently with a fresh context that has DefaultHaltTimeout as its deadline. This ensures workers have a grace period to perform graceful shutdown operations such as closing connections or flushing data.

func StartOpts

func StartOpts(ctx context.Context, workers []Worker, opts ...Option) error

StartOpts is like Start but accepts configuration options.

Types

type Halter

type Halter interface {
	// Halt should tell the worker to stop doing work.
	Halt(context.Context) error
}

Halter represents the behaviour for stopping a service worker.

type Option

type Option func(*options)

Option configures Start behavior.

func WithoutSignals

func WithoutSignals() Option

WithoutSignals disables signal-based shutdown via signal.NotifyContext. Useful when running inside a testing/synctest bubble or when signal handling is managed externally.

type Runner

type Runner interface {
	// Run should run start processing the worker and be a blocking operation.
	Run(context.Context) error
}

Runner represents the behaviour for running a service worker.

type Worker

type Worker interface {
	Runner
	Halter
}

Worker represents the behaviour for a service worker.