Skip to content

Latest commit

 

History

History
126 lines (106 loc) · 7.22 KB

request-response.md

File metadata and controls

126 lines (106 loc) · 7.22 KB
Raw

View Requests and Responses

  • RFC: 03-007
  • Authors: Venkatraman Ramakrishna, Sandeep Nishad, Krishnasuri Narayanam, Dhinakaran Vinayagamurthy
  • Status: Proposed
  • Since: 02-Jan-2023

Summary

This document specifies the data structure formats for view requests and responses as well as data sharing protocol session status information.

Query

Query message is used to define the data that is being requested. This is used in relay-relay and relay-driver communication, where destination relay requests response for this query from source relay, and source relay requests response from the driver identified by the view address provided in this payload. This is different from NetworkQuery as that message is used by client application at destination to initiate the data sharing query request to the destination relay. This message additionally contains request_id generated by the destination relay to uniquely identify and track this query request.

message Query {
  repeated string policy = 1;
  string address = 2;
  string requesting_relay = 3;
  string requesting_network = 4;
  string certificate = 5;
  string requestor_signature = 6;
  string nonce = 7;
  string request_id = 8;
  string requesting_org = 9;
  bool confidential = 10;
}

The attributes are defined below:

  • policy The policy array outlines which orgs need to sign the payload.
  • address is the view address that uniquely identifies the resource that the requesting network is querying.
  • requesting_relay is the identity of the requesting relay
  • requesting_network is the identity of the requesting network
  • certificate is a valid identity certificate of the requesting entity. This is used by the responding network to authenticate the requestor.
  • requestor_signature is the signature of the requestor used by the responding network to verify that the request came from a party they trust. The signature is signed on the view address segment of the address field concatenated with the nonce field (see below). The signature is provided as a Base64-encoded string.
  • nonce is a unique number that is created on a per-request basis. It ensures that if a request is intercepted by a malicious party, the request cannot be reused in a replay attack.
  • request_id is the identifier given to the request to enable the requesting network and relays to track the request.
  • requesting_org is the org from the requesting network that initiated the request.
  • confidential is a Boolean flag indicating whether the requestor expects the resource information within the view response to be encrypted.

State

The following messages are used in communicating resource state (i.e., within a view) or the state of the data sharing protocol session across network components.

ViewPayload

Encapsulates either error or the response view of the query request identified by request_id. The driver uses this payload to encapsulate the response view or error (depending upon the query response from the ledger) into ViewPayload message, and send it to the source relay using the SendDriverState API. Source relay will send the same payload to the destination relay using SendState API. The destination relay then stores the state in the database indexed by request_id.

// View represents the response from a remote network
message ViewPayload {
  string request_id = 1;
  oneof state {
    View view = 2;
    string error = 3;
  };
}

The attributes are defined below:

  • request_id is the unique identifier (for the destination relay) of the original request.
  • state either contains a view (an instance of View) if the data sharing request was succesful, or an error report if the request was unsuccessful.
  • view contains the metadata and data associated with the requested view.
  • error contains a message reporting the cause of the error.

RequestState

message RequestState {
  enum STATUS {
    // pending ACK from remote relay
    PENDING_ACK = 0;
    // Received ACK, waiting for data to be sent from remote relay
    PENDING = 1;
    ERROR = 2;                // View is not there, received error from remote relay
    COMPLETED = 3;            // Data Sharing completed Successfully
    EVENT_RECEIVED = 4;       // View is there and event is received from remote relay
    EVENT_WRITTEN = 5;        // Driver Successfully wrote the view to ledger
    EVENT_WRITE_ERROR = 6;    // View is there but driver failed to write
    DELETED = 7;              // Once network fetches this request state, mark it delete for cleanup later on
  };
  string request_id = 1;
  STATUS status = 2;
  oneof state {
    View view = 3;
    string error = 4;
  };
}

This payload is used for the communication between the destination relay and the client application. When client polls the destination relay for response for the query identified by request_id, using GetState API, passing GetStateMessage as an argument, which contains the request_id, the relay returns above payload, which consists of request_id (uniquely identifying the query for which the client polled for) and the status of request i.e. one of the following enumerations: * PENDING_ACK: Ack pending from the remote relay to the RequestState API call. * PENDING: Ack recieved but waiting the response data from remote relay. * ERROR: signifying error occurred during remote query, and state is the error message. * COMPLETED: signifying successful completion, and state is the response view, that is an instance of View defined here.

Ack

In a data sharing protocol session, Ack is sent in response to the following:

  • Client app sending NetworkQuery to destination relay.
  • Relay sending Query to source relay.
  • Source relay sending Query to driver.
  • Driver sending ViewPayload to the source relay.
  • Source relay sending ViewPayload to the destination relay.
message Ack {
  enum STATUS {
    OK = 0;
    ERROR = 1;
  };
  STATUS status = 2;
  string request_id = 3;
  // an error can have an associated string
  // this is the best way to represent this in protobuf
  string message = 4;
}

Ack status is OK for positive acknowledgement. For negative acknowledgement, Ack status is ERROR, and an error message can also be passed in the message field. The request_id field is used to uniquely track/identify the query for which is Ack is produced for. The request_id is same as the one generated by destination relay on receiving the query from client application. The same value for request_id is referred in all the protobuf messages (defined above) in a protocol session to uniquely track/identify the query request.