ASYNC — Messages related to asynchronous operations

The messages in this chapter are related to the handling of asynchronous operations; please read that chapter for more details.

ASYNC-CANCEL — Cancellation of an asynchronous operation

A client sends this request to the server when it is not interested in the result of an asynchronous operation any more. It is up to the server to decide whether the cancellation is supported and what its effect would be; in certain cases it can be safer to continue with the operation and simply not inform the client about further progress and results, while in other cases it might make more sense to terminate the operation altogether.

The server responds to an ASYNC-CANCEL request with an ASYNC-CANCEL response, listing the receipt IDs of all the operations that have been cancelled successfully and also the IDs of all the operations where cancellation was not possible. For operations that have been cancelled prematurely, the server will also need to dispatch an appropriate ASYNC-RESP response with a cancellation error to make it easier for clients to handle cancellations the same way as any other error condition. In other words, the response to ASYNC-CANCEL simply acknowledges that the server has received and processed the cancellation request, and the actual cancellation will result in an ASYNC-RESP notification. This way it is guaranteed that each receipt ID appears sooner or later in either an ASYNC-RESP or an ASYNC-TIMEOUT notification.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of receipt IDs of the operations that the client wishes to cancel

Example request

{
  "type": "ASYNC-CANCEL",
  "ids": ["0badcafedeadbeef:1", "0badcafedeadbeef:2", "beer"]
}

Response fields

Name Required? Type Description

success

no

list of strings

The list of receipt IDs where the corresponding operation was successfully cancelled

error

no

object

Object mapping receipt IDs to explanations about why the cancellation failed for these receipt IDs.

Example response

{
  "type": "ASYNC-CANCEL",
  "success": ["0badcafedeadbeef:1", "0badcafedeadbeef:2"],
  "error": {
    "beer": "Invalid receipt ID"
  }
}

ASYNC-RESP — Result of an asynchronous operation

A server sends this notification to a client when an asynchronous operation initiated earlier by the client has finished, either successfully or with an error.

Notification fields

Name Required? Type Description

id

yes

string

The receipt ID that the message refers to

result

no

object

The result of the asynchronous operation identified by the receipt ID

error

no

string

The error message returned by the asynchronous operation identified by the receipt ID

Exactly one of the result and the error keys MUST be present in the message.

Example notification

{
  "type": "ASYNC-RESP",
  "id": "0badcafedeadbeef",
  "result": 1234
}

ASYNC-RESUME — Resume a suspended asynchronous operation

A client sends this request to the server when it wishes to resume the execution of an asynchronous operation.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of receipt IDs of the operations that the client wishes to resume

values

no

object

Mapping from receipt IDs to objects to post to the operations represented by the receipts

Example request

{
  "type": "ASYNC-RESUME",
  "ids": ["0badcafedeadbeef:1", "0badcafedeadbeef:2", "beer"],
  "values": {
    "0badcafedeadbeef:2": {
      "spam": "ham",
      "bacon": 42
    }
  }
}

Response fields

Name Required? Type Description

success

no

list of strings

The list of receipt IDs where the corresponding operation was successfully resumed

error

no

object

Object mapping receipt IDs to explanations about why resuming the operation failed for these receipt IDs.

Example response

{
  "type": "ASYNC-RESUME",
  "success": ["0badcafedeadbeef:1", "0badcafedeadbeef:2"],
  "error": {
    "beer": "Invalid receipt ID"
  }
}

ASYNC-ST — Status information for an asynchronous operation

A server sends this notification to a client to update the client about the progress of an asynchronous operation or to inform the client that the execution of the operation has been suspended and is waiting for additional input from the client.

Notification fields

Name Required? Type Description

id

yes

string

The receipt ID that the message refers to

progress

yes

Progress

The progress of the asynchronous operation identified by the receipt ID

suspended

no

boolean

Whether the operation is suspended and is waiting for input from the user

Example notification

{
  "type": "ASYNC-ST",
  "id": "0badcafedeadbeef",
  "progress": {
    "percentage": 80,
    "message": "Almost ready, press any key"
  },
  "suspended": true
}

ASYNC-TIMEOUT — Timeout notification for one or more asynchronous operations

A server sends this notification to a client when an asynchronous operation initiated earlier by the client has timed out.

Notification fields

Name Required? Type Description

ids

yes

list of strings

The list of receipt IDs of the operations that have timed out

Example notification

{
  "type": "ASYNC-TIMEOUT",
  "ids": ["0badcafedeadbeef:1", "0badcafedeadbeef:2"]
}