svc

README

Starting and Stopping Services as Mage Targets

Mage is a build tool that supports writing targets in Go. This package supports configuring local services with local start and stop Mage targets.

Example

The following Magefile running a local NATS server for local testing:

// +build mage

package main

import (
    "context.Context"
    "github.com/magefile/mage/mg"
    svc "github.com/swdunlop/mage-svc"
)

// Restart stops then starts a local NATS service for testing.
func Restart(ctx context.Context) { mg.SerialCtxDeps(ctx, Stop, Start) }

// Start a local NATS testing service.
func Start(ctx context.Context) { mg.CtxDeps(ctx, nats.Start()) }

// Stop the local NATS testing service.
func Stop(ctx context.Context) { mg.CtxDeps(ctx, nats.Stop()) }

// Status returns the status of the local NATS testing service.
func Status(ctx context.Context) { nats.Status(ctx).Print() }

// nats defines our local NATS service, which will run in "var/nats"
var nats = svc.New(`nats`,
    svc.Run(`nats-server`, `-addr`, `localhost`, `-m`, `8222`, `-js`, `-sd`, `.`),
    svc.Dir(`var/nats`),
    svc.DialCheck(`tcp`, `localhost:4222`),
    svc.HTTPCheck(`http://localhost:8222`, 200),
)

Documentation

Overview

Package svc abstracts starting and stopping processes locally so they can be integrated into Mage targets.

Index

• type ErrNotReady
  • func (ErrNotReady) Error() string
• type Interface
  • func New(name string, options ...Option) Interface
• type Option
  • func Check(checks ...func(ctx context.Context) error) Option
  • func DialCheck(network, address string) Option
  • func Dir(path string) Option
  • func Env(environment ...string) Option
  • func HTTPCheck(url string, status int) Option
  • func PIDFile(path string) Option
  • func Run(name string, args ...string) Option
• type Status
  • func (nfo *Status) Print()
  • func (nfo *Status) String() string

Types

type ErrNotReady

type ErrNotReady struct{}

ErrNotReady indicates that the service is not (yet) ready. This is returned by functions used by Check to test if the service is fully ready.

func (ErrNotReady) Error

func (ErrNotReady) Error() string

type Interface

type Interface interface {
	// Start returns a Mage target that will start the service if it is not already
	// running and wait until it is ready based on the configured checks.
	Start() mg.Fn

	// Stop returns a Mage target that will stop the service if it is already running
	// and clean up its pidfile.
	Stop() mg.Fn

	// Status returns the status of the service.
	Status(context.Context) *Status
}

Interface describes the interface provided by a configured service.

func New

func New(name string, options ...Option) Interface

New defines a new service with the provided name that can be started and stopped using the returned values as Mage targets.

type Option

type Option func(*config)

An Option improves the configuration.

func Check

func Check(checks ...func(ctx context.Context) error) Option

Check specifies functions that confirms the service is actually started and ready. The check should return ErrNotReady if the service is not yet ready.

func DialCheck

func DialCheck(network, address string) Option

DialCheck specifies a check for the ability to contact the service.

func Dir

func Dir(path string) Option

Dir specifies the starting directory for the service. If the directory does not exist, it will be created.

func Env

func Env(environment ...string) Option

Env extends the OS environment when starting a service.

func HTTPCheck

func HTTPCheck(url string, status int) Option

HTTPCheck specifies that getting a HTTP URL that should return a given status as a check for service readiness.

func PIDFile

func PIDFile(path string) Option

PIDFile specifies the PID file path, which defaults to name.pid in the service directory. (The service directory itself defaults to the current directory.)

func Run

func Run(name string, args ...string) Option

Run specifies the command that should be run when starting the service.

type Status

type Status struct {
	// Name is the configured name of the service.
	Name string `json:"name"`

	// PID is nonzero if the PID file could be read.  If this is zero, then all the
	// other fields will also be zero.
	PID int `json:"pid,omitempty"`

	// Started is the time the PID file was written.
	Started time.Time `json:"started,omitempty"`

	// Running is true if the PID matches a running process and the PID file was
	// modified after the last time the system started.
	Running bool `json:"running,omitempty"`

	// Ready is true if the service passed all of its checks.
	Ready bool `json:"ready,omitempty"`
}

Status explains the status of a service, as understood by this package.

func (*Status) Print

func (nfo *Status) Print()

Print writes the status to stderr.

func (*Status) String

func (nfo *Status) String() string

String explains the status in English