oasis_client/
api.rs

1use serde::{Deserialize, Serialize};
2
3/// Holds the necessary information to make api calls.
4#[derive(Debug)]
5pub struct DeveloperGatewayApi<'a> {
6    /// Resource locator of the api.
7    pub url: &'a str,
8
9    /// Http method expected by the api call.
10    pub method: RequestMethod,
11}
12
13#[derive(Debug, Clone, Copy)]
14pub enum RequestMethod {
15    GET,
16    POST,
17}
18
19/// This is the main api call which allows the execution of a secure service function.
20pub const SERVICE_EXECUTE_API: DeveloperGatewayApi = DeveloperGatewayApi {
21    url: "v0/api/service/execute",
22    method: RequestMethod::POST,
23};
24
25/// This api call allows deploying a new service.
26pub const SERVICE_DEPLOY_API: DeveloperGatewayApi = DeveloperGatewayApi {
27    url: "v0/api/service/deploy",
28    method: RequestMethod::POST,
29};
30
31/// This api allows users to poll for the status of submitted asynchronous requests.
32pub const SERVICE_POLL_API: DeveloperGatewayApi = DeveloperGatewayApi {
33    url: "v0/api/service/poll",
34    method: RequestMethod::POST,
35};
36
37#[derive(Debug, Serialize, Deserialize)]
38#[serde(untagged, rename_all = "camelCase")]
39pub enum GatewayRequest {
40    ///  Used to trigger a service deployment with provided initcode.
41    Deploy {
42        /// Hex-encoded initcode.
43        data: String,
44    },
45
46    ///  Used to trigger a service execution with user provided arguments.
47    Execute {
48        /// Hex-encoded address where the service can be found.
49        address: String,
50
51        /// Hex-encoded data that the user wants to pass to the service.
52        data: String,
53    },
54
55    /// Request that allows the user to poll for the status asynchronous responses
56    Poll {
57        /// Offset at which events need to be provided. Events are all ordered
58        /// with sequence numbers and it is up to the user to specify which
59        /// events it wants to receive from an offset in the sequence.
60        offset: u64,
61
62        /// The maximum number of items the user would prefer to receive in a single response.
63        count: u32,
64
65        /// If this option is set, the server will discard the events that have a
66        /// sequence number lower than the Offset.
67        #[serde(skip_serializing_if = "std::ops::Not::not", default)]
68        discard_previous: bool,
69    },
70}
71
72#[derive(Debug, Serialize, Deserialize)]
73pub struct ExecuteGatewayRequest {
74    pub data: String,
75}
76
77/// Response returned by requests that are asynchronous.
78#[derive(Debug, Deserialize)]
79pub struct AsyncResponse {
80    /// The response identifier. It uniquely identifies the event and
81    /// orders it in the sequence of events expected by the user. The
82    /// identifier can be used by the user to receive a response to the
83    /// request once it is ready.
84    pub id: u64,
85}
86
87/// Response returned by a poll request containing a list of events.
88#[derive(Debug, Serialize, Deserialize)]
89pub struct PollEventResponse {
90    /// The offset at which the list of events start.
91    pub offset: u64,
92
93    /// The list of events starting from the provided offset.
94    pub events: Vec<Event>,
95}
96
97/// Structure of events that can be returned from the server.
98#[derive(Clone, Debug, Serialize, Deserialize)]
99#[serde(untagged)]
100pub enum Event {
101    /// The event as a result of a request that has failed.
102    Error {
103        /// Identifier of the asynchronous response.
104        id: u64,
105
106        /// Numeric representation fo the error.
107        error_code: i32,
108
109        /// Description of the error.
110        description: String,
111    },
112
113    /// The event as a result of an asynchronous service request that has succeeded.
114    // This needs to be defined before `DeployService` due to field ambiguity.
115    ExecuteService {
116        /// Identifier of the asynchronous response.
117        id: u64,
118
119        /// Hex-encoded address of the service that emitted the event.
120        address: String,
121
122        /// Output generated by the service at the end of its execution.
123        output: String,
124    },
125
126    /// The event as a result of an asynchronous service request that has succeeded.
127    DeployService {
128        /// Identifier of the asynchronous response.
129        id: u64,
130
131        /// Hex-encoded address of the deployed service.
132        address: String,
133    },
134}
oasis_client/api.rs

oasis_client/
api.rs
