gaper

README

gaper

Used to build and restart a Go project when it crashes or some watched file changes
Aimed to be used in development only.

---

Installation

go get -u github.com/maxcnunes/gaper/cmd/gaper

Changelog

See Releases for detailed history changes.

Usage

NAME:
   gaper - Used to build and restart a Go project when it crashes or some watched file changes

USAGE:
   gaper [global options] command [command options] [arguments...]

VERSION:
   version

COMMANDS:
     help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --bin-name value                 name for the binary built by gaper for the executed program (default current directory name)
   --build-path value               path to the program source code (default: ".")
   --build-args value               arguments used on building the program
   --program-args value             arguments used on executing the program
   --verbose                        turns on the verbose messages from gaper
   --disable-default-ignore         turns off default ignore for hidden files and folders, "*_test.go" files, and vendor folder
   --watch value, -w value          list of folders or files to watch for changes
   --ignore value, -i value         list of folders or files to ignore for changes
   --poll-interval value, -p value  how often in milliseconds to poll watched files for changes (default: 500)
   --extensions value, -e value     a comma-delimited list of file extensions to watch for changes (default: "go")
   --no-restart-on value, -n value  don't automatically restart the supervised program if it ends:
                                      if "error", an exit code of 0 will still restart.
                                      if "exit", no restart regardless of exit code.
                                      if "success", no restart only if exit code is 0.
   --help, -h                       show help
   --version, -v                    print the version

Since in most projects there is no need to watch changes of:

• hidden files and folders
• test files (*_test.go)
• vendor folder

Gaper by default ignores those cases already. Although, if you need Gaper to watch those files anyway it is possible to disable this setting with --disable-default-ignore argument.

Examples

Using all defaults provided by Gaper:

gaper

Ignore watch over all test files:

no need for this in case if you are not using --disable-default-ignore

--ignore './**/*_test.go'

Contributing

See the Contributing guide for steps on how to contribute to this project.

Reference

This package was heavily inspired by gin and node-supervisor.

Basically, Gaper is a mixing of those projects above. It started from gin code base and I rewrote it aiming to get something similar to node-supervisor (but simpler). A big thanks for those projects and for the people behind it! 👏👏

How is Gaper different of Gin

The main difference is that Gaper removes a layer of complexity from Gin which has a proxy running on top of the executed server. It allows to postpone a build and reload the server when the first call hits it. With Gaper we don't care about that feature, it just restarts your server whenever a change is made.

Documentation

Overview

Package gaper implements a supervisor restarts a go project when it crashes or a watched file changes

Index

• Constants
• Variables
• func Run(cfg *Config, chOSSiginal chan os.Signal) error
• type Builder
  • func NewBuilder(dir string, bin string, wd string, buildArgs []string) Builder
• type Config
• type LoggerEntity
  • func Logger() *LoggerEntity
  • func (l *LoggerEntity) Debug(v ...interface{})
  • func (l *LoggerEntity) Debugf(format string, v ...interface{})
  • func (l *LoggerEntity) Error(v ...interface{})
  • func (l *LoggerEntity) Errorf(format string, v ...interface{})
  • func (l *LoggerEntity) Info(v ...interface{})
  • func (l *LoggerEntity) Verbose(verbose bool)
• type Runner
  • func NewRunner(wStdout io.Writer, wStderr io.Writer, bin string, args []string) Runner
• type Watcher
  • func NewWatcher(cfg WatcherConfig) (Watcher, error)
• type WatcherConfig

Constants

const OSWindows = "windows"

OSWindows is used to check if current OS is a Windows

Variables

var (
	NoRestartOnError   = "error"
	NoRestartOnSuccess = "success"
	NoRestartOnExit    = "exit"
)

No restart types

var DefaultBuildPath = "."

DefaultBuildPath is the default build and watched path

var DefaultExtensions = []string{"go"}

DefaultExtensions is the default watched extension

var DefaultPoolInterval = 500

DefaultPoolInterval is the time in ms used by the watcher to wait between scans

Functions

func Run

func Run(cfg *Config, chOSSiginal chan os.Signal) error

Run starts the whole gaper process watching for file changes or exit codes and restarting the program

Types

type Builder

type Builder interface {
	Build() error
	Binary() string
}

Builder is a interface for the build process

func NewBuilder

func NewBuilder(dir string, bin string, wd string, buildArgs []string) Builder

NewBuilder creates a new builder

type Config

type Config struct {
	BinName              string
	BuildPath            string
	BuildArgs            []string
	BuildArgsMerged      string
	ProgramArgs          []string
	ProgramArgsMerged    string
	WatchItems           []string
	IgnoreItems          []string
	PollInterval         int
	Extensions           []string
	NoRestartOn          string
	DisableDefaultIgnore bool
	WorkingDirectory     string
}

Config contains all settings supported by gaper

type LoggerEntity

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

LoggerEntity used by gaper

func Logger

func Logger() *LoggerEntity

Logger give access to external packages to use gaper logger

func (*LoggerEntity) Debug

func (l *LoggerEntity) Debug(v ...interface{})

Debug logs a debug message

func (*LoggerEntity) Debugf

func (l *LoggerEntity) Debugf(format string, v ...interface{})

Debugf logs a debug message with format

func (*LoggerEntity) Error

func (l *LoggerEntity) Error(v ...interface{})

Error logs an error message

func (*LoggerEntity) Errorf

func (l *LoggerEntity) Errorf(format string, v ...interface{})

Errorf logs and error message with format

func (*LoggerEntity) Info

func (l *LoggerEntity) Info(v ...interface{})

Info logs a info message

func (*LoggerEntity) Verbose

func (l *LoggerEntity) Verbose(verbose bool)

Verbose toggle this logger verbosity

type Runner

type Runner interface {
	Run() (*exec.Cmd, error)
	Kill() error
	Errors() chan error
	Exited() bool
	IsRunning() bool
	ExitStatus(err error) int
}

Runner is a interface for the run process

func NewRunner

func NewRunner(wStdout io.Writer, wStderr io.Writer, bin string, args []string) Runner

NewRunner creates a new runner

type Watcher

type Watcher interface {
	Watch()
	Errors() chan error
	Events() chan string
}

Watcher is a interface for the watch process

func NewWatcher

func NewWatcher(cfg WatcherConfig) (Watcher, error)

NewWatcher creates a new watcher

type WatcherConfig

type WatcherConfig struct {
	DefaultIgnore bool
	PollInterval  int
	WatchItems    []string
	IgnoreItems   []string
	Extensions    []string
}

WatcherConfig defines the settings available for the watcher