Skip to content
maxjaPublic

About

HTTP playbook executioner

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

HTTPlay

HTTP Playbook executioner — a single Go binary that runs playbooks: ordered, named, inter-dependent HTTP requests defined in a plain-text DSL, with captures, assertions, durable run records, and artefact flow between steps.

httplay run deploy.htpl
httplay run deploy.htpl verify --with-deps

Why

Existing tools each own one niche: Hurl is an assertion-first test tool with disposable responses; .http files are an IDE format for humans poking endpoints one request at a time; Bruno/Postman are GUI collection managers; HTTPie/xh are single-request CLIs.

Nobody owns the playbook case: a repeatable, replayable, partially re-runnable sequence of dependent requests with durable run records. HTTPlay fills that gap.

The format (.htpl)

Each step has a directive zone (structured syntax, sigil-prefixed) and a request zone (literal bytes — headers and body are transmitted exactly as written, no comment stripping, no interpretation).

### Provision a tenant and grab an admin token.
# Owner: @maxja · run: httplay run deploy.htpl login
@name login
@retry 3
$token <- jsonpath $.token
! status == 200
POST https://api.example.com/login
Content-Type: application/json

{"user": "{{env.USER}}", "pass": "{{env.PASS}}"}

###

@name upload-users
@requires login
@save users-resp.json
! status == 201
POST https://api.example.com/users?token={{token}}
Authorization: Bearer {{token}}
@{{file:users.csv}}

###

@name verify
@requires login
! jsonpath $.count > 0
@on_failure warn
GET https://api.example.com/users/count?token={{token}}

Sigils

Sigil Category Examples
@ step meta @name login, @save out.json, @retry 3, @requires login, @on_failure abort|continue|warn
$ context mutation (captures) $token <- jsonpath $.token, $sid <- xpath //SessionId/text(), $v <- regex 'v(\d+\.\d+)', $raw <- body
> external pipe > exec [protoc, --decode, mypkg.User, descriptors/user.proto]
! assertions ! status == 201, ! jsonpath $.count > 0, ! contains "OK"
# human comment (directive zone only) # TODO: rotate creds

Rules:

  • @name is required and must match [a-z0-9_-]+ — names are CLI-addressable and referenceable.
  • Comments (#) are legal only in the directive zone. Everything in the request zone is sent byte-for-byte (a # in a body is payload, not a comment).
  • No inline/trailing comments anywhere.
  • ### (and ####+) at line start = step separator.
  • Line endings are LF; a single trailing \r per line is stripped as part of the line ending (CRLF-tolerant) — bodies included.
  • > exec takes a JSON argv array — no shell, no string interpolation into commands. Captured values flow via explicit stdin:/stdout contract: stdin in, stdout captured, non-zero exit = step failure with stderr in the report.

Templates and references

{{token}} (capture), {{env.X}} (environment), {{login.response.body...}} (named response), @{{file:path}} (file as body — binary-safe). Rendering operates on bytes, never UTF-8 strings; captured values are byte slices decoded only at explicit text boundaries.

Response representations

Bodies are raw bytes until a step declares (or auto-sniffs from Content-Type) a representation via @as auto|json|xml|text|binary:

Representation Captures Content asserts
json jsonpath, regex jsonpath
xml xpath, regex xpath
text regex, substr contains, regex
binary raw body only size, sha256, bytes-contains

status, header, cookie always work regardless of representation. Exotic formats (protobuf, msgpack, avro) are handled as binary + > exec pipes through their canonical CLI tools.

CLI

httplay run [-f] <playbook> [steps...] [-e env] [-o json|text] [--dry-run] [--with-deps] [--record RUN]
httplay list [-f] <playbook> [-o json]     # steps + reference graph
httplay init [name]                        # scaffold playbook + env file
httplay fmt [-w] <playbook>...             # normalize formatting
httplay env [-e env]                       # resolved variables (secrets redacted)

Execution model: linear order; @needs injects missing predecessors (cycle-checked at load). @on_failure: abort (default) / continue / warn. --record <run> seeds context from a previous run's report so step 5 can re-run without steps 1–4. Step selectors may be names, unique prefixes, or ranges (login..verify), akin to kubectl's resource positionals.

Command options: long and short duality

Every option exists in a long (--flag) and short (-f) form — the convention popularized by docker/kubectl. The short set is deliberately tiny and closed: -f (file), -e (environment), -o (output), -w (write, for fmt). No new short flags may be added retroactively without the long form leading in docs and deprecation notes. The playbook file may be given as a bare positional or via -f, mirroring kubectl apply -f manifest.yaml.

Runs, artefacts, retention

Every execution writes a run directory:

runs/2026-10-14T10-30-00/
  report.json     # per-step: request meta, timings, captures, assert results,
                  #            content_type, size, sha256 (+base64/truncated preview)
  users-resp.json # bodies saved via @save — raw bytes, never lossily decoded

Retention policy prunes to the last N runs. Captured values live in pipeline scope (in-memory); artefacts are opt-in and explicit; the report is the audit trail.

Exit codes (CI-first)

  • 0 — all steps passed
  • 1 — step/assert failure
  • 2 — parse/usage error

--output json emits the machine-readable run report on stdout.

Security posture

  • No embedded scripting language; no raw shell strings, ever (injection-safe by construction).
  • Secrets come from env files / environment variables only; HTTPlay never stores or manages credentials; httplay env redacts.
  • --strict-tools preflight-checks that every > exec binary exists before any request fires.

Implementation notes

  • Go. Stdlib net/http, encoding/json, os/exec (argv slices).
  • Format is a real DSL: EBNF spec (below) is the contract; hand-written two-mode lexer (directive/raw) + recursive-descent parser; bodies are a single RAW token the grammar never inspects.
  • Property under test: parse → print → re-parse is an identity function.

EBNF (v0 sketch)

playbook     := step ( sep step )* ;
sep          := "###" [ "#" ] ;
step         := { directive } request_line { header } [ body ] ;
directive    := meta | capture | assert | exec | comment ;
meta         := "@" name | "@" "needs" ident | "@" "save" path
              | "@" "retry" int | "@" "as" repr | "@" "on_failure" policy ;
capture      := "$" ident "<-" cap_source ;
cap_source   := "jsonpath" jsonpath | "xpath" xpath | "regex" regex
              | "header" hname | "status" | "body" | "stdout" ;
assert       := "!" assert_expr ;
exec         := ">" "exec" json_array [ "stdin:" template ] ;
comment      := "#" any_text ;
request_line := method SP url ;
header       := hname ":" hvalue ;
body         := raw_bytes ;   (* to next sep; grammar-invisible *)

License

MIT — see LICENSE.

About

HTTP playbook executioner

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages