probe

README

Probe is a YAML-based workflow automation tool. It uses plugin-based actions to execute workflows, making it highly flexible and extensible.

Example using REST API:

name: Example http workflow
jobs:
- name: Request REST API
  defaults:
    http:
      url: http://localhost:9000
      headers:
        authorization: Bearer {env.TOKEN}
        accept: application/json
  steps:
  - name: Get a user information
    uses: http
    with:
      get: /api/v1/me
    test: res.status == 200 && res.body.uname == foobar
  - name: Update user
    uses: http
    with:
      put: /api/v1/users/{steps[0].res.body.uid}
      body:
        profile: "I'm a software engineer living in Fukuoka."
    test: res.status == 201

Example of sending repeated emails:

name: Send queue congestion experiment
jobs:
- name: Normal sender
  id: normal-sender
  repeat:
    count: 60
    interval: 10
  steps:
  - use: smtp
    with:
      addr: localhost:5871
      from: alice@msa1.local
      to: bob@mx1.local
      my-hostname: msa1-local
      subject: Experiment A
- name: Throttled sender
  id: throtteled-sender
  repeat:
    count: 60
    interval: 10
  steps:
  - use: smtp
    with:
      addr: localhost:5872
      from: carol@msa2.local
      to: bob@mx2.local
      my-hostname: msa2-local
      subject: Experiment B
- name: Export latency as CSV
  needs:
  - normal-sender
  - throtteled-sender
  waitif: sh(postqueue -p 2> /dev/null | grep -c '^[A-F0-9]') != "0"
  steps:
  - use: mail-latency
    with:
      spath: /home/vmail
      dpath: ./mail-latency.csv

Features

A probe workflow consists of jobs and steps contained in the jobs. Multiple jobs are executed asynchronously, and steps are executed in sequence. Step execution results are logged, and can be expanded in YAML using curly braces.

• Workflows can be automated using built-in http, mail, and shell actions
• Custom actions that meet your use cases can be created using protocol buffers
• Protocol-based YAML definitions provide low learning costs and high visibility

Install

Installation via various package managers is not yet supported, but will be soon.

go install github.com/linyows/probe/cmd/probe@latest

Usage

Run the workflow by passing the path to the yaml file where the workflow is defined to the workflow option.

probe --workflow ./worflow.yml

To-Do

Here are some additional features I'm considering:

• Support waitif and needs params in job
• Support rich output
• Support multipart/form-data in http actions
• Support some actions:
  • grpc actions
  • graphql actions
  • ssh actions
  • amqp actions
  • imap actions
  • udp actions
• Support post-actions
• Support pre-job and post-job

Author

linyows

Documentation

Index

• Variables
• func AnyToString(value any) (string, bool)
• func AssignStruct(pa ActionsParams, st any) error
• func DiffJSON(src, target map[string]any) string
• func EnvMap() map[string]string
• func FlattenInterface(i any) map[string]string
• func MapToStructByTags(params map[string]any, dest any) error
• func MatchJSON(src, target map[string]any) bool
• func MergeMaps(base, over map[string]any) map[string]any
• func MergeStringMaps(base map[string]string, over map[string]any) map[string]string
• func RunActions(name string, args []string, with map[string]any, verbose bool) (map[string]any, error)
• func StrmapToAnymap(strmap map[string]string) map[string]any
• func StructToMapByTags(src any) (map[string]any, error)
• func TitleCase(st string, char string) string
• func UnflattenInterface(flatMap map[string]string) map[string]any
• type Actions
• type ActionsArgs
• type ActionsClient
  • func (m *ActionsClient) Run(args []string, with map[string]string) (map[string]string, error)
• type ActionsParams
• type ActionsPlugin
  • func (p *ActionsPlugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (any, error)
  • func (p *ActionsPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error
• type ActionsServer
  • func (m *ActionsServer) Run(ctx context.Context, req *pb.RunRequest) (*pb.RunResponse, error)
• type Config
• type Expr
  • func (e *Expr) Eval(input string, env any) (any, error)
  • func (e *Expr) EvalOrEvalTemplate(input string, env any) (string, error)
  • func (e *Expr) EvalTemplate(input string, env any) (string, error)
  • func (e *Expr) EvalTemplateMap(input map[string]any, env any) map[string]any
  • func (e *Expr) Options(env any) []ex.Option
• type Job
  • func (j *Job) Start(ctx JobContext) bool
• type JobContext
  • func (j *JobContext) SetFailed()
• type Probe
  • func New(path string, v bool) *Probe
  • func (p *Probe) Do() error
  • func (p *Probe) ExitStatus() int
  • func (p *Probe) Load() error
• type Repeat
• type Step
  • func (s Step) SetCtx(j JobContext, req, res map[string]any) TestContext
• type TestContext
• type ValidationError
  • func (e *ValidationError) AddMessage(s string)
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) HasError() bool
• type Workflow
  • func (w *Workflow) Env() map[string]string
  • func (w *Workflow) SetExitStatus(isErr bool)
  • func (w *Workflow) Start(c Config) error

Variables

var (
	BuiltinCmd = "builtin-actions"
	Handshake  = plugin.HandshakeConfig{ProtocolVersion: 1, MagicCookieKey: "probe", MagicCookieValue: "actions"}
	PluginMap  = map[string]plugin.Plugin{"actions": &ActionsPlugin{}}
)

Functions

func AnyToString

func AnyToString(value any) (string, bool)

AnyToString attempts to convert any type to a string.

func AssignStruct

func AssignStruct(pa ActionsParams, st any) error

func DiffJSON

func DiffJSON(src, target map[string]any) string

DiffJSON compares two `map[string]any` objects strictly and collects differences.

func EnvMap

func EnvMap() map[string]string

func FlattenInterface

func FlattenInterface(i any) map[string]string

func MapToStructByTags

func MapToStructByTags(params map[string]any, dest any) error

converting from a map[string]any to a struct

func MatchJSON

func MatchJSON(src, target map[string]any) bool

MatchJSON compares two `map[string]any` objects strictly. All fields in `src` and `target` must match, including structure and values.

func MergeMaps

func MergeMaps(base, over map[string]any) map[string]any

MergeMaps merges two maps of type map[string]any. If keys conflict, the values from over override those in base. Nested maps are merged recursively.

func MergeStringMaps

func MergeStringMaps(base map[string]string, over map[string]any) map[string]string

merge string maps

func RunActions

func RunActions(name string, args []string, with map[string]any, verbose bool) (map[string]any, error)

func StrmapToAnymap

func StrmapToAnymap(strmap map[string]string) map[string]any

func StructToMapByTags

func StructToMapByTags(src any) (map[string]any, error)

converting from a struct to a map[string]any

func TitleCase

func TitleCase(st string, char string) string

func UnflattenInterface

func UnflattenInterface(flatMap map[string]string) map[string]any

Recursively convert a map[string]string to a map[string]any

Types

type Actions

type Actions interface {
	Run(args []string, with map[string]string) (map[string]string, error)
}

type ActionsArgs

type ActionsArgs []string

type ActionsClient

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

func (*ActionsClient) Run

func (m *ActionsClient) Run(args []string, with map[string]string) (map[string]string, error)

type ActionsParams

type ActionsParams map[string]string

type ActionsPlugin

type ActionsPlugin struct {
	plugin.Plugin
	Impl Actions
}

func (*ActionsPlugin) GRPCClient

func (p *ActionsPlugin) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (any, error)

func (*ActionsPlugin) GRPCServer

func (p *ActionsPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type ActionsServer

type ActionsServer struct {
	Impl Actions
}

func (*ActionsServer) Run

func (m *ActionsServer) Run(ctx context.Context, req *pb.RunRequest) (*pb.RunResponse, error)

type Config

type Config struct {
	Log     io.Writer
	Verbose bool
}

type Expr

type Expr struct{}

func (*Expr) Eval

func (e *Expr) Eval(input string, env any) (any, error)

func (*Expr) EvalOrEvalTemplate

func (e *Expr) EvalOrEvalTemplate(input string, env any) (string, error)

func (*Expr) EvalTemplate

func (e *Expr) EvalTemplate(input string, env any) (string, error)

func (*Expr) EvalTemplateMap

func (e *Expr) EvalTemplateMap(input map[string]any, env any) map[string]any

func (*Expr) Options

func (e *Expr) Options(env any) []ex.Option

type Job

type Job struct {
	Name     string  `yaml:"name",validate:"required"`
	Steps    []Step  `yaml:"steps",validate:"required"`
	Repeat   *Repeat `yaml:"repeat"`
	Defaults any     `yaml:"defaults"`
	// contains filtered or unexported fields
}

func (*Job) Start

func (j *Job) Start(ctx JobContext) bool

type JobContext

type JobContext struct {
	Vars map[string]any   `expr:"vars"`
	Logs []map[string]any `expr:"steps"`
	Config
	Failed bool
}

func (*JobContext) SetFailed

func (j *JobContext) SetFailed()

type Probe

type Probe struct {
	FilePath string
	// contains filtered or unexported fields
}

func New

func New(path string, v bool) *Probe

func (*Probe) Do

func (p *Probe) Do() error

func (*Probe) ExitStatus

func (p *Probe) ExitStatus() int

func (*Probe) Load

func (p *Probe) Load() error

type Repeat

type Repeat struct {
	Count    int `yaml:"count",validate:"required,gte=0,lt=100"`
	Interval int `yaml:"interval,validate:"gte=0,lt=600"`
}

type Step

type Step struct {
	Name string         `yaml:"name"`
	Uses string         `yaml:"uses" validate:"required"`
	With map[string]any `yaml:"with"`
	Test string         `yaml:"test"`
	Echo string         `yaml:"echo"`
	Vars map[string]any `yaml:"vars"`
	// contains filtered or unexported fields
}

func (Step) SetCtx

func (s Step) SetCtx(j JobContext, req, res map[string]any) TestContext

type TestContext

type TestContext struct {
	Vars map[string]any   `expr:"vars"`
	Logs []map[string]any `expr:"steps"`
	Res  map[string]any   `expr:"res"`
	Req  map[string]any   `expr:"req"`
}

type ValidationError

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

func (*ValidationError) AddMessage

func (e *ValidationError) AddMessage(s string)

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) HasError

func (e *ValidationError) HasError() bool

type Workflow

type Workflow struct {
	Name string         `yaml:"name",validate:"required"`
	Jobs []Job          `yaml:"jobs",validate:"required"`
	Vars map[string]any `yaml:"vars"`
	// contains filtered or unexported fields
}

func (*Workflow) Env

func (w *Workflow) Env() map[string]string

func (*Workflow) SetExitStatus

func (w *Workflow) SetExitStatus(isErr bool)

func (*Workflow) Start

func (w *Workflow) Start(c Config) error