unkn0wn-root/resterm v1.13.2

on GitHub

v1.13.2

This patch fixes ignored trace budgets, cookie API keys in OpenAPI imports, and condition handling for workflow loops. It also changes the usage error exit code for init, collection, and history from 1 to 2.

Trace budgets

Completion used to suggest request-headers<= and request-body<=, but Resterm silently ignored those budgets. They now work.

Completion now suggests request_headers<= and request_body<=. The hyphenated names are still supported, so you don't need to edit existing files. Those budgets are now enforced, though, which means a run that previously passed may fail if it exceeds them.

Unknown phases and options now produce a warning in both the editor and resterm run. For example, a typo in dns:

### Health
# @trace dsn<=50ms total<=400ms
GET {{base.url}}/health

Warnings:
  api.http:2: unknown @trace option "dsn"

See the tracing docs for supported phase names and aliases.

OpenAPI imports

API keys sent as cookies are now imported into the request's Cookie header, alongside any cookie parameters:

### getMe
# @name getMe
GET {{baseUrl}}/me
Cookie: theme={{cookie_theme}}; session_id={{auth.apiKey}}

Older imports generated # @auth apikey cookie session_id {{auth.apiKey}}, which failed when the request ran. Resterm now rejects that directive during parsing:

error[parse]: @auth apikey placement "cookie" is not supported. Use header or query

If you have one of these imports, re-import the spec or replace the directive with a Cookie header.

The importer also avoids writing a parameter when the API key already occupies the same cookie, header, or query parameter. Previously, it could send a cookie key twice. Servers that read the first value could receive the parameter placeholder instead of the key.

The import docs explain how OpenAPI security schemes map to Resterm requests.

Workflow conditions and loops

You can now combine @when or @skip-if with @for-each on a workflow step, in either order:

# @workflow sync-users
# @for-each json.file("_data/users.json") as user
# @skip-if user.disabled
# @step Sync using=SyncUser

In 1.13.0, this could fail with @for-each must be followed by @step.

Both directives above belong to the step. The condition is checked for each item and can use the loop variable. Disabled users are reported as skipped iterations; the remaining users are sent. If every user is disabled, the report still records each skipped iteration rather than a single skipped step.

When @for-each belongs to the request instead, a condition above @step is checked once, before the loop's list is evaluated. A false @when or a true @skip-if skips the whole step. This lets a step condition guard a request loop whose data file may be missing.

That step condition cannot use the request's loop variable, because the variable is not set yet. It still fails with undefined name, but Resterm now adds help explaining why and where to move the condition.

To filter each item of a request loop, put the condition inside the request:

# @workflow sync-users
# @step Sync using=SyncUser

### Sync user
# @name SyncUser
# @for-each json.file("_data/users.json") as user
# @skip-if user.disabled
POST {{base.url}}/users

Here, both directives belong to the request, so user is available when the condition runs. A step's own @for-each cannot be combined with a @for-each on the request it uses.

Parser errors are more useful here, too. A second @when or @skip-if before the same step now points to the first condition instead of saying @when must be followed by @step. A @skip-if left without a following step is now reported by its own name rather than as @when.

See the workflow docs for conditions and loops.

RestermScript errors

try now preserves timeout, cancellation, and execution-limit aborts even when another error wraps them. These aborts stop evaluation instead of becoming an ordinary failed try result. Wrapped timeout and cancellation errors also retain their diagnostic classification and source location.

CLI exit codes

resterm init, resterm collection, and resterm history now exit with 2 for invalid usage: missing flag values, unknown flags, extra arguments, unknown subcommands, or an unknown init template, as applicable.

These errors previously returned 1. Other errors still return 1, matching the convention used by run, mock, and record.

If your scripts check these commands for exit code 1, update them to handle 2 for usage errors.

Documentation

The new Headless Go API page shows how to run request files from Go.

The docs also cover previously missing details about OpenAPI security schemes, trace phase names, and exit codes for init, collection, history, and mock.

Upgrading from 1.12.1 or earlier

A few changes from 1.13.0 are worth checking if you're skipping that release:

• Digest authentication is available through @auth digest. The name digest is now reserved, so @auth Digest <value> no longer sends a custom header.
• Resterm now sends the Host header you set on a request.
• In detailed exit-code mode, resterm run returns 26 rather than 21 for malformed HTTP responses.
• WebSocket transcripts now include server pings and pongs.