reql

README

reql

reql is a command line HTTP request runner that uses HCL for request definitions and provides a REPL for easy usage.

Installation

reql can be directly installed with the following command

go install github.com/mattmeyers/req/cmd/req@latest

Configuration

When the req command is invoked, it looks for a file named .reqrc in the current working directory. If found, it is loaded into memory and used to configure the session. If not found, req falls back to a default configuration. The .reqrc file is a TOML file that allows the following values.

# Sets the root directory that req uses to look for reqfiles in.
root = ''

# Sets the default environment to use in the REPL. This env must be defined
# below.
default_env = ''

# A table of request aliases. These values can be used to quickly refer
# to a specific request. Aliases must be defined with a full path relative
# to the directory containing the .reqrc file. The root configuration value
# is not applied to alias paths.
[aliases]

# A list of environments. An environment is a table of key/value pairs that
# can be accessed in request templates. For simplicity, all values MUST be
# strings.
[environments.<env_name>]

A sample .reqrc is as follows.

root = './requests/'
default_env = 'local'

[aliases]
echo = './requests/echo.hcl'
ping = './requests/ping.hcl'

[environments.local]
base_url = 'http://localhost:8080'

[environments.prod]
base_url = 'http://localhost:9001'

Reqfiles

A reqfile is an HCL file that contains a request definition. This file can be loaded by req to build and send a request object. The file takes the following schema.

request {
    # The HTTP request method.
    method = ""

    # The full URL to make the request to.
    url = ""

    # A map of key/value pairs that define the request headers. Note that
    # all values are expected to be strings.
    headers = {}

    # The request body. This value is a string and is delivered as is without
    # any manipulation. To minimize size, this can be a minified string. To
    # maximize readability, this can take advantage of heredoc syntax.
    body = <<-BODY
    BODY
}

To make these request definitions dynamic, HIL interpolation can be used to inject values. At this time, the following variables are injected into the template's context.

• env: The current environment's values.

A sample reqfile follows.

request {
    method = "POST"
    url = "${env.base_url}/echo"
    headers = {
        Content-Type = "application/json"
    }
    body = <<-BODY
        {
            "foo": "bar"
        }
    BODY
}

Usage

The req tool can be used in CLI or REPL mode. Core functionality is available in either mode, but the overall usage differs slightly. CLI mode is intended for single, quick requests. As such, the majority of its configuration is delegated to editing the reqfiles. REPL mode, on the other hand, is intended for longer, multi-request sessions. As such, this mode provides additional commands to manipulate the configuration.

CLI Usage

NAME:
   req - A CLI/REPL HTTP request runner

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

COMMANDS:
   send     Send a request by alias or glob
   list     List all available requests
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --config value, -c value  Point to a reqrc config file (default: "./.reqrc")
   --help, -h                show help (default: false)

REPL Usage

The REPL prompt takes the form

[env]>> command [args...]

The prompt shows the current environment name on the left if an environment is selected. Note that an environment is not required to use the REPL. The available commands can be retrieved by typing help or h and hitting enter. The current list of commands is

Available commands:
  h, help              Display this help message.
  list                 List all available requests including aliases.
  send {alias|glob}    Send a request.
  new                                    Interactively define a new request.
  env                  Display all values in the current env.
  env-select {env}     Change the current env.
  env-new {env}        Create a new env and switch to it.
  env-set {key} {val}  Set a value in the current env.
  env-delete {key}     Delete a value from the current env.
  q, quit, exit        Exit the REPL.

Examples

This repository ships with a complete example including a server, .reqrc, and reqfiles. To spin up the server, ensure the go binary is in your PATH, then run

$ cd examples
$ go run main.go

This will spin up a basic server on 127.0.0.1:8080 with two endpoints:

• GET /ping
• POST /echo

Assuming req has been installed and is available in the PATH, The CLI mode can be used to run commands such as

$ req list
$ req send echo
$ req send requests/*

REPL mode can also be entered with

$ req

Documentation

Index

• type Assertion
  • func (a Assertion) Assert(request *http.Request, response *http.Response) error
• type AssertionFunc
  • func ParseAssertion(cond string) AssertionFunc
• type Client
  • func NewClient() *Client
  • func (c *Client) Do(req Request) (*http.Request, *http.Response, error)
• type Config
  • func ParseConfig(path string) (*Config, error)
  • func (c *Config) DeleteEnvValue(env, key string) error
  • func (c *Config) NewEnv(env string) error
  • func (c *Config) SetEnvValue(env, key, value string) error
• type Env
• type Headers
• type Level
  • func ParseLevel(l string) (Level, error)
  • func (l Level) String() string
• type LevelLogger
  • func NewLevelLogger(level Level, out io.Writer) (*LevelLogger, error)
  • func (l *LevelLogger) Debug(format string, args ...interface{})
  • func (l *LevelLogger) Error(format string, args ...interface{})
  • func (l *LevelLogger) Fatal(format string, args ...interface{})
  • func (l *LevelLogger) Info(format string, args ...interface{})
  • func (l *LevelLogger) Warn(format string, args ...interface{})
• type Logger
• type Reqfile
  • func ParseReqfile(path string, env map[string]string) (Reqfile, error)
• type Request
  • func NewRequest() Request
• type Response

Types

type Assertion

type Assertion struct {
	Name string `hcl:"name,label"`
	Expr string `hcl:"expr"`
	// contains filtered or unexported fields
}

func (Assertion) Assert

func (a Assertion) Assert(request *http.Request, response *http.Response) error

type AssertionFunc

type AssertionFunc func(*http.Request, *http.Response) bool

func ParseAssertion

func ParseAssertion(cond string) AssertionFunc

type Client

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

func NewClient

func NewClient() *Client

func (*Client) Do

func (c *Client) Do(req Request) (*http.Request, *http.Response, error)

type Config

type Config struct {
	Root         string            `toml:"root"`
	DefaultEnv   string            `toml:"default_env"`
	Aliases      map[string]string `toml:"aliases"`
	Environments map[string]Env    `toml:"environments"`
}

func ParseConfig

func ParseConfig(path string) (*Config, error)

func (*Config) DeleteEnvValue

func (c *Config) DeleteEnvValue(env, key string) error

func (*Config) NewEnv

func (c *Config) NewEnv(env string) error

func (*Config) SetEnvValue

func (c *Config) SetEnvValue(env, key, value string) error

type Env

type Env map[string]string

type Headers

type Headers struct {
	Values map[string]string `hcl:",remain"`
}

type Level

type Level int

Level represents a logging level. This restricts the logger to print only messages with at least this level.

const (
	LevelDebug Level = iota
	LevelInfo
	LevelWarn
	LevelError
	LevelFatal
)

The available logging levels.

func ParseLevel

func ParseLevel(l string) (Level, error)

ParseLevel converts a string to the corresponding Level. Comparisons are case insensitive. If an unknown level is provided, then an error will be returned.

func (Level) String

func (l Level) String() string

type LevelLogger

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

LevelLogger implements the Logger interface using the defined Level constants. The provided level is treated as the minimum. Any messages passed to a level that is at least the defined level will be printed.

Every log message is treated as a single line. If there is no newline at the end of the message, then one will be added.

func NewLevelLogger

func NewLevelLogger(level Level, out io.Writer) (*LevelLogger, error)

NewLevelLogger constructs a new logger. An error will be returned if an invalid level is provided. If no output writer is provided, then os.Stdout will be used.

func (*LevelLogger) Debug

func (l *LevelLogger) Debug(format string, args ...interface{})

Logs at the LevelDebug level.

func (*LevelLogger) Error

func (l *LevelLogger) Error(format string, args ...interface{})

Logs at the LevelError level.

func (*LevelLogger) Fatal

func (l *LevelLogger) Fatal(format string, args ...interface{})

Logs at the LevelFatal level then calls os.Exit(1).

func (*LevelLogger) Info

func (l *LevelLogger) Info(format string, args ...interface{})

Logs at the LevelInfo level.

func (*LevelLogger) Warn

func (l *LevelLogger) Warn(format string, args ...interface{})

Logs at the LevelWarn level.

type Logger

type Logger interface {
	// Logs at the LevelDebug level.
	Debug(format string, args ...interface{})
	// Logs at the LevelInfo level.
	Info(format string, args ...interface{})
	// Logs at the LevelWarn level.
	Warn(format string, args ...interface{})
	// Logs at the LevelError level.
	Error(format string, args ...interface{})
	// Logs at the LevelFatal level then calls os.Exit(1).
	Fatal(format string, args ...interface{})
}

Logger represents a standard level logging interface. Every method logs the provided message using fmt.Printf with a timestamp and level prefix. Fatal logs the message like the other methods, but calls os.Exit(1) afterwards.

type Reqfile

type Reqfile struct {
	Request  Request  `hcl:"request,block"`
	Response Response `hcl:"response,block"`
}

func ParseReqfile

func ParseReqfile(path string, env map[string]string) (Reqfile, error)

type Request

type Request struct {
	HTTPVersion string
	Method      string `hcl:"method"`
	URL         string `hcl:"url"`

	Headers map[string]string `hcl:"headers,optional"`

	Body string `hcl:"body,optional"`
}

func NewRequest

func NewRequest() Request

type Response

type Response struct {
	Assertions []Assertion `hcl:"assert,block"`
}