runner

command module
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 4, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

README

Runner

GoDoc License

runner is a structured command executer that monitor file changes to trigger process restarts.

Create a file name Procfile in the root of the project you want to run, and add the following content:

workdir: $GOPATH/src/github.com/example/go-app
observe: *.go *.js
ignore: /vendor
build-server: make server
web: restart=fail waitfor=localhost:8888 ./server serve
web-a: group=web restart=always waitfor=localhost:8888 ./server serve alpha
web-b: group=web restart=always waitfor=localhost:8888 ./server serve bravo
db: restart=failure waitfor=web ./server db

Special process type names:

  • workdir: the working directory. Environment variables are expanded. It follows the same rules for exec.Command.Dir.

  • observe: a space separated list of file patterns to scan for. It uses filepath.Match internally. File patterns preceded with exclamation mark (!) will not trigger builds.

  • ignore: a space separated list of ignored directories relative to workdir, typically vendor directories.

  • build*: process type name prefixed by "build" are always executed first and in order of declaration. On failure, they halt the initialization.

  • waitfor (in process type): target hostname and port that the runner will probe before starting the process type.

  • restart (in process type): "always" will restart the process type at every build; "fail" will restart the process type on failure; "temporary" will start the service once and not restart it on rebuilds; "loop" will restart the process when it naturally terminates.

  • group (in process type): group of processes that depend on each other. If a process type fails, it will halt all others in the same group. If the "restart" parameter is not set to "always" or "fail", the affected process types will halt and not restart.

  • sticky (in build process types): a sticky build is not interrupted when file changes are detected.

  • optional (in process types): does not start this process unless explicit told so.

CLI parameters

runner - simple Procfile runner

usage: runner [Procfile]

Options:
  -env file
    	environment file to be loaded for all processes. (default ".env")
  -formation procTypeA=# procTypeB=# ... procTypeN=#
    	formation allows to start more than one instance of a process type, format: procTypeA=# procTypeB=# ... procTypeN=#
  -port PORT
    	base IP port used to set $`PORT` for each process type. Should be multiple of 1000. (default 5000)
  -skip procTypeA procTypeB procTypeN
    	does not run some of the process types, format: procTypeA procTypeB procTypeN

-env file loads the environment file common to all process types. It must be in the format below:

VARIABLENAME=VALUE
VARIABLENAME=VALUE

Note: one environment variable per line.

-formation procTypeA=# procTypeB=# ... procTypeN=# can be used to start more than one instance of a process type. It is commonly used to start many supporting background workers to an application.

-port PORT is the base IP port number used for each process type. It passes the port number as an environment variable named $PORT to the process, and it can be used as means to facilitate the application start up.

-skip procTypeA procTypeB procTypeN allows for partial execution of a Procfile. If a formation is given, it does not start any instance of the specified process type.

Environment variables available to processes

Each process will have three environment variables available.

PS is the name which the runner has christened the process.

PORT is the IP port which the runner has indicated to that instance of a service to bind itself to.

DISCOVERY is the HTTP service that returns a JSON describing each process type port. This assumes the process has honored the PORT variable and bound itself to the configured one.

Service discovery by environment variable

Additionally to the basic three variables above, the runner will add another one for each instance of a process type, like what follows:

# format: NAME_#_PORT
formation: web=3 worker=2
web: server back
worker: some-worker

# Extra vars injected for both web.* and worker.*
# WEB_0_PORT=localhost:5000
# WEB_1_PORT=localhost:5001
# WEB_2_PORT=localhost:5002
# WORKER_0_PORT=localhost:5100
# WORKER_1_PORT=localhost:5101

These variable names are compliant with the POSIX standards on shells section of IEEE Std 1003.1-2008 / IEEE POSIX P1003.2/ISO 9945.2 Shell and Tools. Non-compliant chars are replaced with an underscore (_) and name uniqueness is enforced.

Installation

go get cirello.io/runner

https://pkg.go.dev/cirello.io/runner

Documentation

Overview

Command runner is a very ugly and simple structured command executer that monitor file changes to trigger process restarts.

Create a file name Procfile in the root of the project you want to run, and add the following content:

workdir: $GOPATH/src/github.com/example/go-app
observe: *.go *.js
ignore: /vendor
build-server: make server
web-a: group=web restart=always waitfor=localhost:8888 ./server serve alpha
web-b: group=web restart=always waitfor=localhost:8888 ./server serve bravo
db: restart=failure waitfor=localhost:8888 ./server db

Special process types:

- workdir: the working directory. Environment variables are expanded. It follows the same rules for exec.Command.Dir.

- observe: a space separated list of file patterns to scan for. It uses filepath.Match internally. File patterns preceded with exclamation mark (!) will not trigger builds.

- ignore: a space separated list of ignored directories relative to workdir, typically vendor directories.

- build*: process type name prefixed by "build" are always executed first and in order of declaration. On failure, they halt the initialization.

- waitfor (in process type): target hostname and port that the runner will probe before starting the process type.

- restart (in process type): "always" will restart the process type at every build; "fail" will restart the process type on failure; "temporary" will start the service once and not restart it on rebuilds; "loop" will restart the process when it naturally terminates.

- group (in process type): group of processes that depend on each other. If a process type fails, it will halt all others in the same group. If the "restart" parameter is not set to "always" or "fail", the affected process types will halt and not restart.

- sticky (in build process types): a sticky build is not interrupted when file changes are detected.

- optional (in process types): does not start this process unless explicit told so. The process type must be part of a group.

Directories

Path Synopsis
internal
procfile
Package procfile provides a parser that know how read an extended version of Procfile as described by Heroku (https://devcenter.heroku.com/articles/procfile).
Package procfile provides a parser that know how read an extended version of Procfile as described by Heroku (https://devcenter.heroku.com/articles/procfile).
runner
Package runner holds the building blocks for cmd runner.
Package runner holds the building blocks for cmd runner.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL