19.61. Payloads Download RPC

Requests the download of a blob (file) from a known payload by its identifier and path.

19.61.1.Messages

• PayloadsDownloadRequest

• PayloadsDownloadResponse

            

            
message PayloadsDownloadRequest {
  RequestHeader header = 1;
  Identifier payload_id = 2;
  string name = 3;
}
        

type: message

Standard RPC request header.

See RequestHeader for details.

type: message

Unique identifier of the payload to download.

Required. If the identifier value is omitted from the request or does not match any known payload identifier, Clara Deploy SDK will be unable to fulfill the request.

See Identifier for details.

type: string

Unique (within a payload) name of the file, in path format.

File names are relative to the root of the payload. When a name is prefixed with a slash '/' character the prefix is ignored.

Payload file names are case preserving, and the following rules are used to find file data to fulfill a download request:

• When a single file matches a case-insensitive search, it will be downloaded.

• When multiple files match a case-insensitive search and a single file matches a case-sensitive search, it will be downloaded.

• When multiple files match a case-insensitive search and no file matches a case-sensitive search, no files will be downloaded and an error will be returned.

            

            
message PipelineDownloadResponse {
  ResponseHeader header = 1;
  PayloadFileDetails details = 2;
  bytes data = 3;
}
        

Clara Deploy SDK Payloads service will respond to any download request with a PayloadsDownloadResponse message. Requestors can use the response message to determine the result of their request.

Note that this response is streamed. The response will contain at least one chunk for each file in the payload. Files larger than the chunk size limit will be broken into multiple chunks which will need to be reassembled after download. The name property of the PayloadFileDetails message can be used to identify the destination file of each chunk. Chunks will be delivered in order.

            

            
// psuedo-code

var response = pipelines.details(request)
var files = new map<string, stream>()
var is_valid = false

for (var chunk in response) {
  // Validate the response code.
  if (!is_valid && (!chunk.header || chunk.header.code < 0))
    throw error

  is_value = true

  var name = chunk.details.name

  // Get the file stream from the map, or create one and add to the map.
  if (!files.try_get(name, out stream file)) {
    var path = fs.path.combine(root_path, name)
    file = fs.create_file(path)

    // Add the file stream to the map by name.
    files.add(name, file)
  }

  // Append the chunk's bytes to the file.
  file.write(chunk.data)
}

for (var file in files) {
  fs.close(file.value);
}
        

19.63.1.Properties

19.63.1.1.header

type: message

Standard RPC response header.

Note this response is streamed, only the first chunk is guaranteed to contain a header.

See ResponseHeader for details.

19.63.1.2.details

type: message

Details about the file being downloaded.

See PayloadFileDetails for details.

19.63.1.3.data

type: bytes

Content of the file as raw bytes.