ran

README

ran

ran is a task runner with the concept of event driven.

Install

$ go get github.com/morikuni/ran/cmd/ran

Usage

ran's task file is written in YAML.

Here is an example of task file.

env:
  GO111MODULE: on

commands:
  test:
    description: Run test
    tasks:
    - script: go test -v -race ./...

  install:
    description: Install command into your $GOBIN dir.
    tasks:
    - name: test
      call:
        command: test

    - script: go install github.com/morikuni/ran/cmd/ran
      when:
      - test.succeeded

There are 2 kind of top-level key env and commands. You can define environment variables which is used in a execution time on env key. You can also define commands on commands key. In this example, there are 2 command, test and install. These are used as the sub-commands of ran command.

Each commands have a list of tasks. Task is defined as a bash script or it calls another command. The install is defined by 2 tasks. First one is named test and it calls another command test. Second one has no name, but it has a when key. You can define dependencies on when key. In this example, the second go install script is executed only when the first task test was succeeded.

Let's execute the task file. At the first, call help command.

$ ran help
Usage:
  ran [command]

Available Commands:
  help          Help about any command
  install       Install command into your $GOBIN dir.
  test          Run test

Flags:
  -f, --file string        ran definition file. (default "ran.yaml")
  -h, --help               help for ran
      --log-level string   log level. (debug, info, error, discard) (default "info")

Use "ran [command] --help" for more information about a command.

All commands in task file is printed. It's very useful when you don't know much about the project yet.

At next, call test command.

$ ran test
> go test -v -race ./...
=== RUN   TestStdLogger
--- PASS: TestStdLogger (0.00s)
=== RUN   TestTaskRunner
=== RUN   TestTaskRunner/defer
=== RUN   TestTaskRunner/no_events
=== RUN   TestTaskRunner/success
=== RUN   TestTaskRunner/error
=== RUN   TestTaskRunner/call
--- PASS: TestTaskRunner (0.02s)
    --- PASS: TestTaskRunner/defer (0.00s)
    --- PASS: TestTaskRunner/no_events (0.00s)
    --- PASS: TestTaskRunner/success (0.01s)
    --- PASS: TestTaskRunner/error (0.01s)
    --- PASS: TestTaskRunner/call (0.00s)
=== RUN   Test_EventsToParams
--- PASS: Test_EventsToParams (0.00s)
PASS
ok      github.com/morikuni/ran (cached)
?       github.com/morikuni/ran/cmd/ran [no test files]

go test script is executed. Next, install command.

$ ran install
> go test -v -race ./...
=== RUN   TestStdLogger
--- PASS: TestStdLogger (0.00s)
=== RUN   TestTaskRunner
=== RUN   TestTaskRunner/defer
=== RUN   TestTaskRunner/no_events
=== RUN   TestTaskRunner/success
=== RUN   TestTaskRunner/error
=== RUN   TestTaskRunner/call
--- PASS: TestTaskRunner (0.02s)
    --- PASS: TestTaskRunner/defer (0.00s)
    --- PASS: TestTaskRunner/no_events (0.00s)
    --- PASS: TestTaskRunner/success (0.01s)
    --- PASS: TestTaskRunner/error (0.01s)
    --- PASS: TestTaskRunner/call (0.00s)
=== RUN   Test_EventsToParams
--- PASS: Test_EventsToParams (0.00s)
PASS
ok      github.com/morikuni/ran (cached)
?       github.com/morikuni/ran/cmd/ran [no test files]
> go install github.com/morikuni/ran/cmd/ran

go install script is executed after go test script.

Event

There are 4 types of the event in ran.

event	when triggered
started	on the script is started
finished	on the script is finished (does not depends on success or fail)
succeeded	on the script is succeeded
failed	on the script is failed

Documentation

Index

• type App
  • func NewApp() App
  • func (app App) Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int
• type Command
• type CommandCall
• type CommandRunner
• type Definition
  • func LoadDefinition(filename string) (Definition, error)
  • func ParseDefinition(r io.Reader) (Definition, error)
• type Dispatcher
  • func NewDispatcher(logger Logger) *Dispatcher
  • func (d *Dispatcher) Receive(e Event)
  • func (d *Dispatcher) Register(tr *TaskRunner)
• type EnvironmentVariables
• type Event
  • func NewEvent(topic string, payload map[string]string) Event
• type EventReceiver
• type LogLevel
  • func NewLogLevel(level string) (LogLevel, error)
  • func (l LogLevel) String() string
• type Logger
• type RuntimeEnvironment
• type Script
• type Stack
  • func NewStack() Stack
• type StdCommandRunner
  • func NewStdCommandRunner(commands map[string]Command, workDir string, logger Logger) StdCommandRunner
  • func (cr StdCommandRunner) RunCommand(command string, renv RuntimeEnvironment) error
• type StdLogger
  • func NewStdLogger(w io.Writer, level LogLevel) *StdLogger
  • func (l *StdLogger) Debug(msg string, args ...interface{})
  • func (l *StdLogger) Error(msg string, args ...interface{})
  • func (l *StdLogger) Info(msg string, args ...interface{})
• type Supervisor
  • func NewSupervisor() *Supervisor
  • func (s *Supervisor) Start(f func() error)
  • func (s *Supervisor) Wait() error
• type Task
• type TaskRunner
  • func NewTaskRunner(task Task, commandRunner CommandRunner, starter WorkerStarter, ...) *TaskRunner
  • func (tr *TaskRunner) Receive(e Event)
  • func (tr *TaskRunner) Run()
• type WorkerStarter

Types

type App

type App struct {
}

func NewApp

func NewApp() App

func (App) Run

func (app App) Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int

type Command

type Command struct {
	Name        string
	Description string
	Tasks       []Task
}

type CommandCall

type CommandCall struct {
	Command string
}

type CommandRunner

type CommandRunner interface {
	RunCommand(command string, renv RuntimeEnvironment) error
}

type Definition

type Definition struct {
	Env      EnvironmentVariables
	Commands map[string]Command
}

func LoadDefinition

func LoadDefinition(filename string) (Definition, error)

func ParseDefinition

func ParseDefinition(r io.Reader) (Definition, error)

type Dispatcher

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

func NewDispatcher

func NewDispatcher(logger Logger) *Dispatcher

func (*Dispatcher) Receive

func (d *Dispatcher) Receive(e Event)

func (*Dispatcher) Register

func (d *Dispatcher) Register(tr *TaskRunner)

type EnvironmentVariables

type EnvironmentVariables []string

type Event

type Event struct {
	Topic   string
	Payload map[string]string
}

func NewEvent

func NewEvent(topic string, payload map[string]string) Event

type EventReceiver

type EventReceiver interface {
	Receive(e Event)
}

type LogLevel

type LogLevel int

const (
	Debug LogLevel = iota
	Info
	Error
	Discard
)

func NewLogLevel

func NewLogLevel(level string) (LogLevel, error)

func (LogLevel) String

func (l LogLevel) String() string

type Logger

type Logger interface {
	Debug(msg string, args ...interface{})
	Info(msg string, args ...interface{})
	Error(msg string, args ...interface{})
}

type RuntimeEnvironment

type RuntimeEnvironment struct {
	Stdin            io.Reader
	Stdout           io.Writer
	Stderr           io.Writer
	Env              EnvironmentVariables
	WorkingDirectory string
}

type Script

type Script interface {
	PID() string
	Start() error
	Wait() error
	Run() error
}

type Stack

type Stack interface {
	Push(script Script)
	Pop() (Script, bool)
}

func NewStack

func NewStack() Stack

type StdCommandRunner

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

func NewStdCommandRunner

func NewStdCommandRunner(
	commands map[string]Command,
	workDir string,
	logger Logger,
) StdCommandRunner

func (StdCommandRunner) RunCommand

func (cr StdCommandRunner) RunCommand(command string, renv RuntimeEnvironment) error

type StdLogger

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

func NewStdLogger

func NewStdLogger(w io.Writer, level LogLevel) *StdLogger

func (*StdLogger) Debug

func (l *StdLogger) Debug(msg string, args ...interface{})

func (*StdLogger) Error

func (l *StdLogger) Error(msg string, args ...interface{})

func (*StdLogger) Info

func (l *StdLogger) Info(msg string, args ...interface{})

type Supervisor

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

func NewSupervisor

func NewSupervisor() *Supervisor

func (*Supervisor) Start

func (s *Supervisor) Start(f func() error)

func (*Supervisor) Wait

func (s *Supervisor) Wait() error

type Task

type Task struct {
	Name   string
	Script string
	When   []string
	Env    map[string]string
	Defer  string
	Call   CommandCall
}

type TaskRunner

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

func NewTaskRunner

func NewTaskRunner(
	task Task,
	commandRunner CommandRunner,
	starter WorkerStarter,
	receiver EventReceiver,
	stack Stack,
	logger Logger,
	env RuntimeEnvironment,
) *TaskRunner

func (*TaskRunner) Receive

func (tr *TaskRunner) Receive(e Event)

func (*TaskRunner) Run

func (tr *TaskRunner) Run()

type WorkerStarter

type WorkerStarter interface {
	Start(f func() error)
}