1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
//! The verbs for the parts of HEY the model does not describe. They take a path rather
//! than a route and hand back the answer undecoded, but everything else is what a modelled
//! call gets: the credentials, the account scope, the hooks, the retries and the resend
//! after a refreshed 401.
//!
//! A path here goes out as it was written — no `.json` suffix is added — since a caller
//! reaching past the model is naming a path HEY serves, not one Smithy had to spell
//! around.
use bytes::Bytes;
use serde::Serialize;
use tokio::io::{AsyncWrite, AsyncWriteExt};
use url::Url;
use crate::client::{Client, Response};
use crate::error::Error;
use crate::form::FormResponse;
use crate::http::{HeaderMap, Method};
use crate::operation::Operation;
use crate::security::is_same_origin;
impl Client {
/// Reads a path the model does not cover.
pub async fn get(&self, path: &str) -> Result<Response, Error> {
self.execute(self.raw(Method::GET, path)?).await
}
/// Reads the HTML representation, for the pages HEY serves no JSON for.
pub async fn get_html(&self, path: &str) -> Result<Response, Error> {
let mut operation = self.raw(Method::GET, path)?;
operation.accept("text/html");
self.execute(operation).await
}
/// Reads an export, which HEY streams as a file rather than a document.
pub async fn get_csv(&self, path: &str) -> Result<Response, Error> {
self.execute(self.csv(path)?).await
}
/// A request for one of the exports HEY streams as a file. This and [`Client::get_csv`]
/// stand to each other as [`Client::form`] does to [`Client::post_form`]: a call that
/// has something to say about itself builds the operation here and gives it an
/// [`Operation::info`] before sending it.
pub fn csv(&self, path: &str) -> Result<Operation, Error> {
let mut operation = self.raw(Method::GET, path)?;
operation.accept("text/csv");
Ok(operation)
}
/// Reads a file whole. [`Client::download_blob`] writes one out as it arrives instead,
/// for a file too large to want in memory.
pub async fn get_blob(&self, path: &str) -> Result<Response, Error> {
self.execute(self.blob(path)?).await
}
/// Writes a file to `destination` as it arrives, and answers how many bytes went and
/// what headers came with them. Nothing is read into memory, and nothing is resent:
/// once bytes are on their way to the destination a second attempt would double them.
pub async fn download_blob(
&self,
path: &str,
destination: &mut (impl AsyncWrite + Unpin),
) -> Result<(u64, HeaderMap), Error> {
let deadline = self.deadline();
let response = self.stream(self.blob(path)?, deadline).await?;
let headers = response.headers().clone();
let mut body = response.into_body();
// The hooks heard the operation end when the answer arrived; the operation's one
// deadline still holds over the bytes that follow it.
let written = self
.within_deadline(deadline, async {
let mut written = 0;
while let Some(chunk) = body.chunk().await? {
destination
.write_all(&chunk)
.await
.map_err(Error::from_std)?;
written += chunk.len() as u64;
}
Ok(written)
})
.await?;
Ok((written, headers))
}
/// Posts a JSON body to a path the model does not cover.
pub async fn post(&self, path: &str, body: &impl Serialize) -> Result<Response, Error> {
self.send_json(Method::POST, path, body, "application/json")
.await
}
/// Posts to an endpoint that may answer with something other than JSON.
pub async fn post_mutation(
&self,
path: &str,
body: &impl Serialize,
) -> Result<Response, Error> {
self.send_json(Method::POST, path, body, "*/*").await
}
/// Puts a JSON body to a path the model does not cover.
pub async fn put(&self, path: &str, body: &impl Serialize) -> Result<Response, Error> {
self.send_json(Method::PUT, path, body, "application/json")
.await
}
/// Patches a path the model does not cover with a JSON body.
pub async fn patch(&self, path: &str, body: &impl Serialize) -> Result<Response, Error> {
self.send_json(Method::PATCH, path, body, "application/json")
.await
}
/// Patches an endpoint that may answer with something other than JSON.
pub async fn patch_mutation(
&self,
path: &str,
body: &impl Serialize,
) -> Result<Response, Error> {
self.send_json(Method::PATCH, path, body, "*/*").await
}
/// Deletes at a path the model does not cover.
pub async fn delete(&self, path: &str) -> Result<Response, Error> {
self.execute(self.raw(Method::DELETE, path)?).await
}
/// Posts a form the way a browser would, and captures the redirect HEY answers with
/// rather than following it. [`FormResponse::extract_id`] reads the created record's
/// id out of that redirect.
///
/// This and the three below are [`Client::form`] and [`Client::send_form`] together. A
/// call that has something to say about itself builds the operation with those two
/// instead, and gives it an [`Operation::info`] on the way.
pub async fn post_form(
&self,
path: &str,
fields: &[(&str, &str)],
) -> Result<FormResponse, Error> {
let mut operation = self.form(Method::POST, path)?;
operation.form(fields);
self.send_form(operation).await
}
/// Patches through the form endpoint, the way a browser's edit form would.
pub async fn patch_form(
&self,
path: &str,
fields: &[(&str, &str)],
) -> Result<FormResponse, Error> {
let mut operation = self.form(Method::PATCH, path)?;
operation.form(fields);
self.send_form(operation).await
}
/// Deletes through the form endpoint, which answers a redirect. The request carries no
/// body, and so no content type either.
pub async fn delete_form(&self, path: &str) -> Result<FormResponse, Error> {
self.send_form(self.form(Method::DELETE, path)?).await
}
/// Posts a multipart body the caller assembled, for the endpoints that take a file.
pub async fn post_multipart(
&self,
path: &str,
content_type: String,
body: Bytes,
) -> Result<FormResponse, Error> {
let mut operation = self.form(Method::POST, path)?;
operation.multipart(content_type, body);
self.send_form(operation).await
}
/// An operation for a path the model does not cover. An absolute URL is sent as it
/// stands, provided the credentials may travel to it; anything else is resolved
/// against the base URL.
pub(crate) fn raw(&self, method: Method, path: &str) -> Result<Operation, Error> {
let mut operation = match self.absolute(path)? {
Some(url) => Operation::at(method, url),
None => Operation::raw(method, path.to_string()),
};
operation.without_json_suffix();
Ok(operation)
}
/// The URL a path names when it already is one. HTTPS goes anywhere; plain HTTP only
/// back to the base URL's own host, which is how a HEY running on this machine is
/// reached, and nowhere else — the credentials would go with it.
fn absolute(&self, path: &str) -> Result<Option<Url>, Error> {
if path.starts_with("https://") || path.starts_with("http://") {
let url = Url::parse(path)?;
if url.scheme() == "https" || is_same_origin(&url, self.base_url()) {
Ok(Some(url))
} else {
Err(Error::usage(format!("URL must use HTTPS, got: {path}")))
}
} else {
Ok(None)
}
}
/// A blob is read from the HEY origin and nowhere else: the request carries the
/// credentials, and only a redirect — which the client strips them before following —
/// may lead off it. The response cache is for JSON documents, so a blob goes past it.
fn blob(&self, path: &str) -> Result<Operation, Error> {
let mut operation = self.raw(Method::GET, path)?;
if let Some(url) = &operation.url
&& !is_same_origin(url, self.base_url())
{
return Err(Error::usage("a blob URL must start on the HEY origin"));
}
operation.accept("*/*").no_cache();
Ok(operation)
}
async fn send_json(
&self,
method: Method,
path: &str,
body: &impl Serialize,
accept: &'static str,
) -> Result<Response, Error> {
let mut operation = self.raw(method, path)?;
operation.json(body)?.accept(accept);
self.execute(operation).await
}
}