Pipeline requirements for Instant Tasks
An Instant Task pipeline uses a request-response design. The pipeline has one unconnected input view and one or more unconnected output views. When a request arrives, the Snaplex routes it directly to an available pipeline instance, which processes the input document and returns a response to the caller.
Use cases
Instant Tasks are appropriate when your integration must respond to inbound HTTP requests with low latency and you can tolerate occasional message loss. Common use cases include:
- Real-time APIs: Expose integration logic as an always-on HTTP endpoint that external systems can call directly.
- Lightweight event processing: Process inbound events or webhooks with minimal overhead when guaranteed delivery is not required.
- Request validation and transformation: Continuously validate incoming requests, apply business logic, and return structured responses.
- High-concurrency endpoints: Handle concurrent requests by running multiple pipeline instances in parallel across Snaplex nodes.
Pipeline design
An Instant Task pipeline must have one unconnected input view and one or more unconnected output views. HTTP requests arrive at the Snaplex node and are routed directly to an available pipeline instance. The pipeline processes the input document and returns a response to the caller. No FeedMaster is involved in routing or queuing.
Input document structure
When the input view type is a document, HTTP request headers are included in the
root of the input document and the request body is in the
content field. Header keys are always received in lowercase.
The following fields are also injected into the input document:
- uri: The original URI of the request.
- method: The HTTP request method.
- query: The parsed query string, where each key maps to a list of values.
- task_name: The name of the task.
- path_info: The portion of the path after the task URL.
- server_ip and server_port: The IP address and TCP port of the Snaplex node that received the request.
- client_ip and client_port: The IP address and TCP port of the client that sent the request.
Output document structure
To customize the HTTP response, map the response body to the
$content field, custom headers to the root
$, and the HTTP status code to the $status
field. If no $content field is present, the entire output
document is JSON-encoded and returned as the response body.
Design considerations
- Avoid spaces in pipeline names used as task invocation endpoints.
- Error views are implicitly added to all Snaps when the pipeline runs in Instant Task mode, regardless of individual Snap configuration.
- Pipeline parameters cannot be changed at runtime. They are set at pipeline startup and remain fixed for the life of the instance.
- During Snaplex state transitions, more than one instance may run simultaneously even if the configured count is one. Design the pipeline to handle this condition.
- Because Instant Tasks do not use a FeedMaster queue, in-flight requests are not preserved if a pipeline instance fails. Callers should implement retry logic if needed.
Snap support
Not all Snaps support Instant Task mode. The pipeline requirements for Instant Tasks limit the use of certain Snaps. Before building a pipeline for an Instant Task, verify that the Snaps you intend to use are compatible with this mode.
Snaps that support Ultra Task mode are generally compatible with Instant Tasks. Refer to Snap support for Ultra Tasks for guidance while a dedicated Instant Task compatibility reference is being developed.