Asynchronous Invocations

Boltic enables long-running tasks or function invocations to run in the background through the use of NATS JetStream or NATS Streaming. This decouples the HTTP transaction between the caller and the function.

• The HTTP request is serialized to NATS through the gateway as a "producer".
• The queue-worker acts as a subscriber and deserializes the HTTP request and uses it to invoke the function directly

Why might you want to use an asynchronous invocation?

You're working with a partner's webhook. They send you data, but if you don't send a HTTP 200 OK within 1 second, they assume failure and retry the message. This works well if your application/function can complete in less than a second on every invocation, but if there's any risk that it can't, you need another solution. So you will give your partner a URL to the asynchronous invocation URL instead and it will reply within several milliseconds whilst still processing the data.

Synchronous vs asynchronous invocation

• Sync

  A synchronous invocation of a user requesting a PDF would be as follows, where connections are established between each component from the beginning to the end of the invocation.

  

If the whole process takes less than a few seconds, this may be the ideal approach, given that it's simple to implement.

• Async

  An asynchronous invocation of a user requesting a PDF would be as follows: an initial connection is formed to the gateway, the user's request is serialized to a queue via the queue-worker and NATS. At a later time, the queue-worker then dequeues the request, deserializes it and makes it to the function using a synchronous call.

  

  This is beneficial if there are for instance 100 requests that all take 2 minutes to execute. It means the client / caller needs to wait only for a new milliseconds.

How it works

Any function can be invoked asynchronously by changing the URL from <INVOCATION_URL> to <INVOCATION_URL>/async. A 202 Accepted message will be issued in response to asynchronous calls.

tip

Note: that asynchronous invocations do not make sense with a HTTP GET method since they are queued and deferred, there is nothing to GET. For this reason, any HTTP method other than GET is required.

If you would like to receive a value from an asynchronous call you should pass a HTTP header with the URL to be used for the call-back.

curl -kv -H "X-Callback-Url=https://request.bin/mybin" <INVOCATION_URL>/async>

It will pass back the X-Request-Id you had when you sent the initial request.

You can use netcat to check the Call Id during invocation:

curl <INVOCATION_URL>/async> \
  --data "Hi" \
  --header "X-Callback-Url: http://<your-ip>:8888"

nc -l 8888

HTTP/1.1 200 OK
Content-Length: 174
Content-Type: application/x-www-form-urlencoded
Date: Tue, 04 Dec 2018 09:24:55 GMT
X-Request-ID: eb8283f5-1679-48e0-afec-194544b054aa
X-Duration-Seconds: 0.002885
X-Serverless-Status: 200
X-Serverless-ID: a0a856fd-5da6-43cd-8880-52587b37aa0b

 _   _      _ _       
| | | | ___| | | ___  
| |_| |/ _ \ | |/ _ \ 
|  _  |  __/ | | (_) |
|_| |_|\___|_|_|\___/ 

Alternatively you can specify another asynchronous or synchronous serverless to run instead.

Configuration & Limits

There are limits for asynchronous invocation, which you should understand before using them:

• Timeouts - the timeout for any asynchronous invocation must "agree" with all other timeouts within the system, including the proxy and the function.
• Concurrency / parallelism - the amount of invocations processed at any one time.
• Payload size - the maximum size is configured to be 1MB. The limit is defined by NATS, but can be changed. Use a database, or S3 bucket for storing large payloads, and pass an identifier to function calls.

The queue-worker uses a single timeout for how long it will spend processing a message, this timeout is equal to the timeout of the proxy and cannot currently be adjusted.

Callback request headers

The following additional request headers will be set when invoking the call back URL:

Header	Description
X-Request-ID	The original serverless call's tracing UUID
X-Duration-Seconds	Time taken in seconds to execute the original serverless call
X-Serverless-Status	HTTP status code returned by the original serverless call
X-Serverless-ID	The ID of the original serverless that was executed