xrun

README

xrun

Utilities around running multiple components which are long-running components, example: an HTTP server or a background worker

Install

$ go get github.com/gojekfarm/xrun

Usage

Minimum Required Go Version: 1.20.x

• API reference
• Blog post explaining motivation behind xrun
• Reddit post

Credits

Manager source modified from sigs.k8s.io/controller-runtime

Documentation

Overview

Package xrun provides utilities around running multiple components which are long-running components, example: an HTTP server or a background worker

package main

import (
	"net/http"
	"os"
	"os/signal"

	"github.com/gojekfarm/xrun"
	"github.com/gojekfarm/xrun/component"
)

func main() {
	m := xrun.NewManager()
	server := http.Server{
		Addr: ":9090",
	}
	_ = m.Add(component.HTTPServer(component.HTTPServerOptions{Server: &server}))

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()

	if err := m.Run(ctx); err != nil {
		os.Exit(1)
	}
}

Index

• Constants
• type Component
• type ComponentFunc
  • func All(shutdownTimeout time.Duration, components ...Component) ComponentFunc
  • func (f ComponentFunc) Run(ctx context.Context) error
• type Manager
  • func NewManager(opts ...Option) *Manager
  • func (m *Manager) Add(c Component) error
  • func (m *Manager) Run(ctx context.Context) (err error)
• type Option
• type ShutdownTimeout

Examples

• All
• NewManager
• NewManager (Nested)

Constants

const (
	// NoTimeout waits indefinitely and never times out
	NoTimeout = time.Duration(0)
)

Types

type Component

type Component interface {
	// Run starts running the component. The component will stop running
	// when the context is closed. Run blocks until the context is closed or
	// an error occurs.
	Run(context.Context) error
}

Component allows a component to be started. It's very important that Run blocks until it's done running.

type ComponentFunc

type ComponentFunc func(ctx context.Context) error

ComponentFunc is a helper to implement Component inline. The component will stop running when the context is closed. ComponentFunc must block until the context is closed or an error occurs.

func All

func All(shutdownTimeout time.Duration, components ...Component) ComponentFunc

All is a utility function which creates a new Manager and adds all the components to it. Calling .Run() on returned ComponentFunc will call Run on the Manager

Example

package main

import (
	"context"
	"net/http"
	"os"
	"os/signal"

	"github.com/gojekfarm/xrun"
	"github.com/gojekfarm/xrun/component"
)

func main() {
	// ctx is marked done (its Done channel is closed) when one of the listed signals arrives
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, os.Kill)
	defer stop()

	if err := xrun.All(xrun.NoTimeout,
		component.HTTPServer(component.HTTPServerOptions{Server: &http.Server{}}),
		xrun.ComponentFunc(func(ctx context.Context) error {
			// Start something here in a blocking way and continue on ctx.Done
			<-ctx.Done()
			// Call Stop on component if cleanup is required
			return nil
		}),
	).Run(ctx); err != nil {
		os.Exit(1)
	}
}

func (ComponentFunc) Run

func (f ComponentFunc) Run(ctx context.Context) error

Run starts running the component. The component will stop running when the context is closed. Run blocks until the context is closed or an error occurs.

type Manager

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

Manager helps to run multiple components and waits for them to complete

func NewManager

func NewManager(opts ...Option) *Manager

NewManager creates a Manager and applies provided Option

Example

package main

import (
	"context"
	"net/http"
	"os"
	"os/signal"

	"github.com/gojekfarm/xrun"
	"github.com/gojekfarm/xrun/component"
)

func main() {
	m := xrun.NewManager(xrun.ShutdownTimeout(xrun.NoTimeout))

	if err := m.Add(component.HTTPServer(component.HTTPServerOptions{Server: &http.Server{}})); err != nil {
		panic(err)
	}

	if err := m.Add(xrun.ComponentFunc(func(ctx context.Context) error {
		// Start something here in a blocking way and continue on ctx.Done
		<-ctx.Done()
		// Call Stop on component if cleanup is required
		return nil
	})); err != nil {
		panic(err)
	}

	// ctx is marked done (its Done channel is closed) when one of the listed signals arrives
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, os.Kill)
	defer stop()

	if err := m.Run(ctx); err != nil {
		os.Exit(1)
	}
}

Example (Nested)

package main

import (
	"context"
	"net/http"
	"os"
	"os/signal"

	"github.com/gojekfarm/xrun"
	"github.com/gojekfarm/xrun/component"
)

func main() {
	m1 := xrun.NewManager()
	if err := m1.Add(component.HTTPServer(component.HTTPServerOptions{Server: &http.Server{}})); err != nil {
		panic(err)
	}

	m2 := xrun.NewManager()
	if err := m2.Add(xrun.ComponentFunc(func(ctx context.Context) error {
		// Start something here in a blocking way and continue on ctx.Done
		<-ctx.Done()
		// Call Stop on component if cleanup is required
		return nil
	})); err != nil {
		panic(err)
	}

	gm := xrun.NewManager()
	if err := gm.Add(m1); err != nil {
		panic(err)
	}
	if err := gm.Add(m2); err != nil {
		panic(err)
	}

	// ctx is marked done (its Done channel is closed) when one of the listed signals arrives
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, os.Kill)
	defer stop()

	// Run will start m1 and m2 simultaneously
	if err := gm.Run(ctx); err != nil {
		os.Exit(1)
	}
}

func (*Manager) Add

func (m *Manager) Add(c Component) error

Add will enqueue the Component to run it, last added component will be started first

func (*Manager) Run

func (m *Manager) Run(ctx context.Context) (err error)

Run starts running the registered components. The components will stop running when the context is closed. Run blocks until the context is closed or an error occurs.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option changes behaviour of Manager

type ShutdownTimeout

type ShutdownTimeout time.Duration

ShutdownTimeout allows max timeout after which Manager exits.