`HttpDefinition`

Type, in @jr2/orchestrator/src/http-effect.ts. The signature of an export, or a type that it names, names this type. The Authoring surface page lists each export. This type is not an export of @jr2/orchestrator, so a workflow module does not import it by name.

type HttpDefinition<S extends z.ZodType | undefined = undefined> = {
  method: HttpMethod;
  url: string | Text | typeof open;
  headers?: Readonly<Record<string, string | Text>>;
  auth?: { readonly bearer: Secret } | { readonly basic: { user: Text; password: Text } } | Text;
  input?: S;
  request?: (input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts;
  body?: FileBody<S>;
  timeout?: Duration;
  maxBody?: number;
  idempotent?: boolean;
};

An http Effect's definition.

Fields

method: HttpMethod
The HTTP method: GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS. It refuses another: http({ method: "<method>" }): the method is one of GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS.
url: string | Text | typeof open
The url: http:// or https://, then a literal host. No input, param or Effect secret can change where the call goes. An Effect secret can be only in the path: text`https://api.telegram.org/bot${secret("tg")}/sendMessage`.
Or open: a packaged Machine that cannot know the host leaves the url Open, and the composer binds it one time with customize(machine, { effects: { <slot>: { url } } }).
It refuses:
- a scheme or host that is not literal: http({ url }): the url is an http:// or https:// url whose scheme and host are literal — a secret may sit only in its path, after a "/": text`https://api.example.com/bot${secret("tg")}/send` (ADR-0068)
- an Effect secret after ? or #: http({ url }): secret("<name>") sits in the url's query or fragment — a secret may sit only in its path; send it in `auth` or a header instead: headers: { "x-api-key": text`${secret("...")}` } (ADR-0068)
- a host that is not a host: http({ url }): "<scheme>://<host>" is not a host
- a user name or password in the url: http({ url }): the url carries userinfo — use `auth`
headers (optional): Readonly<Record<string, string | Text>>
Headers that are the same for each run. Each name is lowercase. A value is a string, or a text with an Effect secret.
It refuses:
- a name that is not lowercase, or that frames or routes the request (host, content-length, transfer-encoding, connection, upgrade, te, trailer, keep-alive, proxy-*): http({ headers }): "<name>" is not a header an Effect sets — a lowercase name that does not frame or route the request (ADR-0068)
- an authorization header beside auth: http({ headers }): "authorization" is set by `auth` — write one of them
auth (optional): { readonly bearer: Secret; } | { readonly basic: { user: Text; password: Text; }; } | Text
The Authorization header: bearer(secret("x")), basic(user, password), or a text that is the whole value.
input (optional): S
The zod schema of the input of the Effect: what the input of the invoke, or fromPick, gives it. jr2 parses the input with it before the call. When it starts, input that does not agree with it makes the Effect fail (its onError route): http "<slot>": its input does not match the definition's input schema — <path>: <message>, one <path>: <message> for each problem, joined by ; .
request (optional): (input: S extends z.ZodType ? z.infer<S> : void) => HttpRequestParts
A function that makes the part of the request that changes for each run, from the input: path segments, and a json or text body. It cannot change the host, a header or an Effect secret. Do not write it beside body.
body (optional): FileBody<S>
A Worktree file as the body: file(path, { slot?, segments?, contentType? }). The Effect then runs in the Sandbox Effector of its Workspace. Do not write request beside it: the segments of file are the path. It refuses another body: http({ body }): a body is file(path, { slot?, segments?, contentType? }) — json and text come from `request` .
timeout (optional): Duration
How long jr2 waits for the answer: a number and a unit, such as "30s" or "2m". Default "30s". With no answer in that time, the output is unknown. It refuses a value that is not a positive duration: http: timeout "<timeout>" is not a positive duration (like "30s", "2m").
maxBody (optional): number
The largest number of bytes of a text response body that the output keeps. Default 65536. When jr2 cuts the body, truncated is true. It refuses a value that is not a positive whole number: http({ maxBody }): a positive number of bytes.
idempotent (optional): boolean
true when it is safe to send the call two times: it has its own idempotency key, or it only reads. Default false. After an Orchestrator restart, jr2 cannot always tell if the call went out. Then it sends an idempotent call again, and gives any other call the output unknown.

HttpDefinition ​

`HttpDefinition`