Pipelining

Introduction

This specification defines how a Web Function package can signal that it supports function pipelining, and how clients can use this feature to execute a sequence of function calls where the input of a subsequent call depends on the output of previous calls.

Discovery

A package supports pipelining if it includes a pipeline_url in its definition. Clients send a pipeline request to this URL via POST. The pipeline request MUST use Content-Type: application/json and Accept: application/json; these headers apply to the pipeline request as a whole. The server applies the same JSON content negotiation to every step it executes on the client's behalf, so steps do not repeat these headers (see Headers).

Referencing

Clients reference results from earlier steps using JSONPath, where the root $ represents the array of results gathered so far in the current pipeline. This specification uses the JSONPath syntax standardized in RFC 9535, including both bracket notation ($[0]['key']) and dot notation ($[0].key).

A reference MUST be a singular query as defined by RFC 9535, that is, an expression composed solely of name and index selectors that selects at most one node. The reference resolves to the single value held by that node; if the query selects no node, the reference cannot be resolved and is an error (see Error handling).

A reference is recognized only when the entire string value is a JSONPath expression that begins with an unescaped $. References embedded within a larger string are not resolved; for example, "Bearer $[0]" is treated as a literal string, not as a reference. To inject a composed value such as an Authorization header, the referenced step should return that value ready to use (see the example below).

A reference MUST target an already-completed earlier step, that is, a step whose index is strictly less than the index of the step in which the reference appears. Referencing the current step or any later step is invalid and is an error.

References MAY appear wherever a string value is expected, within either a step's body or its headers. Placing a reference in a header allows, for example, a temporary access token captured from an earlier step (such as an endpoint using the capture_bearer flag) to be injected into a later step's Authorization header.

Example syntax

$[index]['path']['to']['key']
$[index].path.to.key

Escaping

If an argument value is a string that must literally start with a $ (and should not be interpreted as a JSONPath), it MUST be escaped with a backslash: \$. For example, "\$100" is interpreted as the literal string "$100".

A string that begins with an unescaped $ but is not a valid RFC 9535 JSONPath expression (for example "$100") is an error: the server MUST halt the pipeline and return an error (see Error handling).

Execution logic

A pipeline request is a JSON object with the following keys:

Each element of steps is an object with the following keys:

Headers

Content negotiation is fixed for the whole pipeline: the pipeline request carries Content-Type: application/json and Accept: application/json, and the server reuses these when invoking each step. The per-step headers object is therefore reserved for headers that vary between steps, most notably Authorization (a bearer token) and Api-Version.

Example pipeline request

{
  "steps": [
    {
      "url": "https://auth.example.com/issue-token",
      "headers": {},
      "body": { "api_key": "ak_live_123" }
    },
    {
      "url": "https://stats.example.com/get-user-stats",
      "headers": { "Authorization": "$[0]['authorization']" },
      "body": {
        "user_id": "$[0].user_id",
        "category": "performance"
      }
    }
  ],
  "returns": "$[-1:]"
}

In this example the first step issues a token and returns an object such as { "authorization": "Bearer tok_abc", "user_id": "user_123" }. Because references must be whole strings, the token is returned in a ready-to-use authorization key that already includes the Bearer scheme; the second step references that already-completed step verbatim in its Authorization header. The header reference uses bracket notation and the body reference uses dot notation; both are valid RFC 9535 singular queries.

Processing rules

• The server executes the steps in order, beginning at index 0, and stores each step's result in a results array at the position matching its index.

• Before executing a step, the server resolves the references in its headers and body:

  • The server inspects each string value in headers and body.

  • If a string starts with \$, the \ is removed and the remainder is treated as a literal string.

  • If the entire string is a JSONPath beginning with an unescaped $, the server evaluates it as an RFC 9535 singular query against the results array gathered so far and replaces the string with the single value it selects. The expression MUST resolve against an already-completed earlier step. A $ that appears anywhere other than the start of the string is not a reference and the string is left as a literal.

  • If the expression is not a valid JSONPath, or it targets the current or a later step, the server halts the pipeline and returns an error.

• The server invokes the step using POST, sending Content-Type: application/json and Accept: application/json together with the step's headers.

• Upon successful completion of every step, the server responds with status 200. The response body is the full results array, or—when returns is present—the result of evaluating returns against that array.

Error handling

If any step fails, or a reference cannot be resolved, the server MUST halt the pipeline immediately and MUST NOT execute any further steps. The pipeline responds with status 400, and the body is the error describing the failure. Partial results are not returned.

If the pipeline endpoint itself uses the error_triple flag, the error MUST be returned as an error triple. In that case the ERROR_DETAILS MAY include diagnostic context, such as the index of the failing step and the underlying error it returned.

Security

Because the server issues HTTP requests to the url of each step on the client's behalf, an unrestricted pipeline server behaves as an open proxy and a server-side request forgery (SSRF) vector. A server implementing this specification MUST maintain an explicit allow-list of permitted URLs or hosts, and MUST reject any step whose url is not permitted, halting the pipeline with an error.