# http

> The http identity: an HTTP exchange. Every directive, what is required, and how the payload travels.

`http` is an HTTP exchange. The step's directives shape the request. The target is a base URL; the scheme (`http` or `https`) comes from it.

## Write it in English

An http step reads as English sentences, and the program does the heavy lifting. These are the voice of a step:

| directive | the request it makes |
| --- | --- |
| `get <path>` | GET the path (the path may be quoted) |
| `get with <value>` | GET the target itself with the value in a query parameter |
| `get <path> with <value>` | GET the path with the value in a query parameter |
| `put <path>`, `patch <path>`, `delete <path>`, `head <path>`, `options <path>` | the verb is the HTTP method; `with <value>` rides in a query parameter |
| `post <path> with <value>` | POST a raw form body |
| `post <path> as a form field <name> with <value>` | POST one `name=value` form field |
| `post <path> as json with <value>` | POST a JSON object |
| `post <path> as a raw form with <value>` | POST the body verbatim as form data |
| `post <path> as a raw json with <value>` | POST the body verbatim as JSON |
| `post <path> as a raw multipart with <value>` | POST the body verbatim as multipart/form-data; the runtime reads the boundary from the body's first line and sets the Content-Type. Next.js Server Action requests are multipart, so a forged action writes its parts (with `\r\n` line endings) as one quoted value |
| `set <var> = aesgcm of "<plaintext>" with "<base64-key>"` | a deterministic data transform: runs after the step's captures, seals the plaintext with AES-GCM under the base64 key, and stores `base64(iv + ciphertext)` for later steps. Used to forge Next.js Server Action bound arguments |
| `with the header "<name>" set to <value>` | set one request header |
| `with the cookie "<name>" set to <value>` | add one cookie; all cookies join into one `Cookie` header |

A value may be written `base64 of "<text>"` to base64-encode it after `{var}` substitution. The `expect` directive is the assert, in English: `expect "<text>" in the response`, `expect the response to match "<regex>"`, `expect the target to call back "<expect>"`, `expect a flag`, `expect no response`. Captures use the English forms on this page. The SAML flow below is written entirely in English.

## The value, the path, and the headers

A value may be written `base64 of "<text>"` to base64-encode it after `{var}` substitution. A SAML flow delivers its response as a base64-encoded form field, so the step writes the XML and lets the runtime encode it:

```text
http deliver
  post "/acs" as a form field SAMLResponse with base64 of "<samlp:Response InResponseTo=\"{reqid}\"/>"
  expect "accepted" in the response
```

The request body becomes `SAMLResponse=<url-encoded base64 of the XML>`.

The `get "<path>"` and `post "<path>"` forms append the path to the target URL, and `{var}` references in it are substituted. This lets a captured session code or token ride in the query string of a later request.

`with the header "<name>" set to <value>` sets one request header; `with the cookie "<name>" set to <value>` adds cookies that join into a single `Cookie` header (sorted by name).

A solution-level `headers:` or `cookies:` block before the first step sets defaults applied to every http step; a step's own values add to or override them. The keycloak session flow captures two cookies once and replays them on every request via one solution-level `cookies:` block.

## Capture

`capture` pulls a value out of the response for later steps, and it reads as English. The program knows page shapes, so you name the value and it finds the bytes: `capture the json field "access_token" as token`, `capture the cookie "AUTH_SESSION_ID" as sid`. The pattern runs over the full response text: the status line, the headers (including a redirect's `Location`), and the body. A step may carry several `capture` lines; each runs against the same response in order. This is how a stateful flow replays cookies and rotating session codes.

```text
http sso
  get "/login"
  capture the form field "SAMLRequest" as saml_b64
  capture the attribute "ID" of saml_b64 base64 as reqid
  capture the attribute "AssertionConsumerServiceURL" of saml_b64 base64 as acs
```

Reads: capture the `SAMLRequest` form value as `saml_b64`, then from its base64-decoded value capture the `ID` attribute as `reqid` and the `AssertionConsumerServiceURL` attribute as `acs`. The shapes are `form field` (an HTML input's value), `attribute` (XML or HTML), `json field` (a JSON string, raw or HTML-escaped), `query parameter` (a URL query value, raw or HTML-escaped), `cookie` (a `Set-Cookie` value), and `input name after` (the tail of an HTML input's name after a prefix, the way a Next.js Server Action reference index rides in an input's name). `of <source>` searches an earlier variable instead of the response; `base64` decodes the source first.

The regex form is still available when no shape fits:

```text
http get-token
  post "/api/session" as json
  capture csrf: "\"csrf\"\\s*:\\s*\"([^\"]+)\""
  expect "\"csrf\"" in the response
```

Later steps reference `{csrf}`.

## param, on the solution

The solution-level `param` names the input parameter used by `get with`, `get "<path>" with`, the `as a form field`, and the `as json` forms. For example, a template renderer solution sets `param` to `template` so the value reaches the right field.

## Example

```text
http reflect
  get with "REFLECTED_7x7"
  # send a unique marker in the template param and confirm it comes back
  expect "REFLECTED_7x7" in the response
```