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 AssignStruct(pa ActionsParams, st any) error
• func EvalExpr(ex string, env any) (any, error)
• func EvaluateExprs(exprs map[string]any, env any) map[string]any
• func FlattenInterface(i any) map[string]string
• func MapToStructByTags(params map[string]any, dest any) error
• func MergeStringMaps(base map[string]string, over map[string]any) map[string]string
• func RunActions(name string, args []string, with map[string]any) (map[string]any, error)
• func ShowVerbose(i int, name string, req, res 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 Job
  • func (j *Job) Start(ctx JobContext)
• type JobContext
• type Probe
  • func New(path string) *Probe
  • func (p *Probe) Do() error
  • func (p *Probe) Load() error
• type Repeat
• type Step
• type TestContext
  • func NewTestContext(j JobContext, req, res map[string]any) TestContext
• type ValidationError
  • func (e *ValidationError) AddMessage(s string)
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) HasError() bool
• type Workflow
  • func (w *Workflow) Start()

Variables

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

Functions

func AssignStruct

func AssignStruct(pa ActionsParams, st any) error

func EvalExpr

func EvalExpr(ex string, env any) (any, error)

func EvaluateExprs

func EvaluateExprs(exprs map[string]any, env any) map[string]any

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 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) (map[string]any, error)

func ShowVerbose

func ShowVerbose(i int, name string, req, res 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 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)

type JobContext

type JobContext struct {
	Envs map[string]string `expr:"env"`
	Logs []map[string]any  `expr:"steps"`
}

type Probe

type Probe struct {
	FilePath string
	Log      io.Writer
	Verbose  bool
	// contains filtered or unexported fields
}

func New

func New(path string) *Probe

func (*Probe) Do

func (p *Probe) Do() error

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"`
	// contains filtered or unexported fields
}

type TestContext

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

func NewTestContext

func NewTestContext(j JobContext, req, res map[string]any) TestContext

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"`
}

func (*Workflow) Start

func (w *Workflow) Start()