Skip to main content

coven_storage/providers/
http.rs

1use crate::{
2    ByteProgress, ByteRange, CloudProvider, HeldTokens, OAuthTokens, StorageError, StorageFailure,
3    TokenCustody,
4};
5use coven_crypto::SecretBytes;
6use coven_foundation::clock::ClockRef;
7use reqwest::{Method, Response};
8use serde_json::Value;
9use std::fmt;
10use std::sync::Arc;
11
12/// A device's provider sign-in and HTTP connection, injected into its provider.
13/// A token is used until the provider rejects it with HTTP 401; the request
14/// then refreshes once through the sign-in's custody and is retried once (§20.2).
15pub struct OAuthSession {
16    client: super::http_client::HttpClient,
17    provider: CloudProvider,
18    tokens: HeldTokens,
19    clock: ClockRef,
20}
21impl OAuthSession {
22    /// Sign in over `client`, which follows no redirect: bearer tokens must not
23    /// follow provider-returned URLs to other origins.
24    pub(crate) fn new(
25        provider: CloudProvider,
26        tokens: OAuthTokens,
27        custody: Arc<dyn TokenCustody>,
28        clock: ClockRef,
29        client: super::http_client::HttpClient,
30    ) -> Result<Self, StorageError> {
31        if !provider.signs_in_with_oauth() {
32            return Err(
33                StorageFailure::InvalidConfiguration.with_source("provider does not use OAuth")
34            );
35        }
36        Ok(Self { client, provider, tokens: HeldTokens::new(tokens, custody), clock })
37    }
38    /// Resolve the signed-in account through the provider's own identity API.
39    pub async fn account(&self) -> Result<String, StorageError> {
40        let api = super::oauth_api(self.provider).expect("checked OAuth provider");
41        self.account_at(api).await
42    }
43    pub(crate) async fn account_at(&self, api: &str) -> Result<String, StorageError> {
44        let (method, url, body) = match self.provider {
45            CloudProvider::Dropbox => (
46                Method::POST,
47                endpoint(api, &["users", "get_current_account"], &[])?,
48                Body::Json(Value::Null),
49            ),
50            CloudProvider::OneDrive => (
51                Method::GET,
52                endpoint(api, &["me"], &[("$select", "mail,userPrincipalName")])?,
53                Body::Empty,
54            ),
55            _ => unreachable!("checked OAuth provider"),
56        };
57        let value = json(self.provider, self.send(method, &url, &[], body, true).await?).await?;
58        let account = match self.provider {
59            CloudProvider::Dropbox => string(&value, "email")?,
60            CloudProvider::OneDrive => {
61                if value["mail"].is_null() {
62                    string(&value, "userPrincipalName")?
63                } else {
64                    string(&value, "mail")?
65                }
66            }
67            _ => unreachable!("checked OAuth provider"),
68        };
69        let account = coven_format::MemberAccess::normalized_account(account);
70        if account.is_empty() {
71            return Err(StorageFailure::Protocol.with_source("empty signed-in account"));
72        }
73        Ok(account)
74    }
75    /// The signed-in account's id and primary address, from the provider's
76    /// own identity API.
77    pub async fn identity(&self) -> Result<crate::ProviderAccount, StorageError> {
78        let api = super::oauth_api(self.provider).expect("checked OAuth provider");
79        self.identity_at(api).await
80    }
81    pub(crate) async fn identity_at(
82        &self,
83        api: &str,
84    ) -> Result<crate::ProviderAccount, StorageError> {
85        let (method, url, body) = match self.provider {
86            CloudProvider::Dropbox => (
87                Method::POST,
88                endpoint(api, &["users", "get_current_account"], &[])?,
89                Body::Json(Value::Null),
90            ),
91            CloudProvider::OneDrive => (
92                Method::GET,
93                endpoint(api, &["me"], &[("$select", "mail,userPrincipalName")])?,
94                Body::Empty,
95            ),
96            _ => unreachable!("checked OAuth provider"),
97        };
98        let value = json(self.provider, self.send(method, &url, &[], body, true).await?).await?;
99        let (id, address) = match self.provider {
100            CloudProvider::Dropbox => {
101                (Some(string(&value, "account_id")?), string(&value, "email")?)
102            }
103            CloudProvider::OneDrive => (
104                None,
105                if value["mail"].is_null() {
106                    string(&value, "userPrincipalName")?
107                } else {
108                    string(&value, "mail")?
109                },
110            ),
111            _ => unreachable!("checked OAuth provider"),
112        };
113        let address = coven_format::MemberAccess::normalized_account(address);
114        if address.is_empty() || id.is_some_and(str::is_empty) {
115            return Err(StorageFailure::Protocol.with_source("empty signed-in account"));
116        }
117        Ok(crate::ProviderAccount { id: id.map(str::to_owned), address })
118    }
119    /// Install tokens after their owner committed them to custody.
120    pub async fn set_tokens(&self, tokens: OAuthTokens) {
121        self.tokens.install(tokens).await;
122    }
123    pub(crate) fn provider(&self) -> CloudProvider {
124        self.provider
125    }
126    /// End once `duration` has passed, a deadline the work races.
127    pub(crate) async fn deadline(&self, duration: std::time::Duration) {
128        self.clock.deadline(duration).await;
129    }
130    /// Wait out a backoff or poll spacing before trying again.
131    pub(crate) async fn wait_out(&self, wait: std::time::Duration) {
132        self.clock.wait_out(wait).await;
133    }
134    pub(crate) async fn send(
135        &self,
136        method: Method,
137        url: &str,
138        headers: &[(&str, String)],
139        body: Body,
140        authenticated: bool,
141    ) -> Result<Response, StorageError> {
142        self.send_request(None, method, url, headers, body, authenticated).await
143    }
144    pub(crate) async fn publish(
145        &self,
146        publication: &crate::PublicationRequest,
147        method: Method,
148        url: &str,
149        headers: &[(&str, String)],
150        body: Body,
151        authenticated: bool,
152    ) -> Result<Response, StorageError> {
153        self.send_request(Some(publication), method, url, headers, body, authenticated).await
154    }
155    async fn send_request(
156        &self,
157        publication: Option<&crate::PublicationRequest>,
158        method: Method,
159        url: &str,
160        headers: &[(&str, String)],
161        body: Body,
162        authenticated: bool,
163    ) -> Result<Response, StorageError> {
164        let mut request = self.client.request(method, url);
165        for (name, value) in headers {
166            request = request.header(*name, value);
167        }
168        let (request, sent) = match body {
169            Body::Empty => (request, ByteProgress::unread()),
170            Body::Json(value) => (request.json(&value), ByteProgress::unread()),
171            Body::Bytes(bytes, sent) => (request.body(bytes), sent),
172        };
173        let request = request.build().map_err(|e| transport(self.provider, e))?;
174        if !authenticated {
175            return self.execute(publication, request, None, &sent).await;
176        }
177        // Buffered bodies clone without copying, so the one retry resends
178        // them; its bytes are heard again from the start.
179        let retry = request.try_clone();
180        let used = self.tokens.current().await;
181        let response = self.execute(publication, request, Some(&used), &sent).await?;
182        if response.status() != reqwest::StatusCode::UNAUTHORIZED {
183            return Ok(response);
184        }
185        let rejection = response_error(self.provider, response).await;
186        // Refreshing cannot cure a rejection other than the token's, such as
187        // Dropbox's missing scope or a suspended account.
188        if rejection.failure() != StorageFailure::Authentication {
189            return Err(rejection);
190        }
191        let Some(retry) = retry else {
192            return Err(rejection);
193        };
194        let replacement = self.tokens.rejected(&used).await?;
195        self.execute(publication, retry, Some(&replacement), &sent).await
196    }
197    /// Send one request with `tokens`, labelling the response with the access
198    /// they carried: a later replacement must not relabel it. `sent` hears
199    /// its body go.
200    async fn execute(
201        &self,
202        publication: Option<&crate::PublicationRequest>,
203        mut request: reqwest::Request,
204        tokens: Option<&OAuthTokens>,
205        sent: &ByteProgress,
206    ) -> Result<Response, StorageError> {
207        if let Some(tokens) = tokens {
208            let mut value = reqwest::header::HeaderValue::try_from(format!(
209                "Bearer {}",
210                tokens.access_token.as_str()
211            ))
212            .map_err(|error| StorageFailure::InvalidConfiguration.with_source(error))?;
213            value.set_sensitive(true);
214            request.headers_mut().insert(reqwest::header::AUTHORIZATION, value);
215        }
216        if let Some(publication) = publication {
217            publication.check()?;
218        }
219        let mut response = self
220            .client
221            .execute(request, sent)
222            .await
223            .map_err(|error| error.into_storage(self.provider))?;
224        if let Some(tokens) = tokens {
225            response.extensions_mut().insert(tokens.access);
226        }
227        Ok(response)
228    }
229}
230pub(crate) enum Body {
231    Empty,
232    Json(Value),
233    /// Bytes, and who hears them go: an object's, or none for a body that
234    /// carries no object's bytes.
235    Bytes(Vec<u8>, ByteProgress),
236}
237/// A request that got no reply. Its text names every cause, such as the DNS,
238/// TLS or connection failure behind reqwest's "error sending request". The
239/// kept error's URL is cut to its scheme and host first, so neither its text,
240/// its `Debug` nor a walk of its causes shows a path or query.
241pub(crate) fn transport(provider: CloudProvider, error: reqwest::Error) -> StorageError {
242    let failure = if error.is_builder() {
243        StorageFailure::InvalidConfiguration
244    } else {
245        StorageFailure::Network
246    };
247    StorageError::Provider {
248        provider,
249        failure,
250        source: Box::new(super::error_text::WithCauses(super::error_text::origin_only(error))),
251    }
252}
253
254/// The original error response. Its body is never printed; providers may echo secrets.
255pub struct ProviderResponse {
256    status: u16,
257    headers: reqwest::header::HeaderMap,
258    body: SecretBytes,
259}
260impl ProviderResponse {
261    /// The HTTP status returned by the provider.
262    pub fn status(&self) -> u16 {
263        self.status
264    }
265    /// Original response headers, including Retry-After. Inspect explicitly;
266    /// they are redacted from ordinary error formatting along with the body.
267    pub fn headers(&self) -> &reqwest::header::HeaderMap {
268        &self.headers
269    }
270    /// A response carrying `headers`, as a native adapter or fixture saw it.
271    pub(crate) fn new(status: u16, headers: reqwest::header::HeaderMap, body: Vec<u8>) -> Self {
272        Self { status, headers, body: SecretBytes::new(body) }
273    }
274    /// A `status` response, asking for `retry_after` seconds of
275    /// `Retry-After` when given, classified as `failure`, as the in-memory
276    /// provider injects it.
277    #[cfg(any(test, feature = "test-utils"))]
278    pub(crate) fn injected(
279        provider: CloudProvider,
280        failure: StorageFailure,
281        status: u16,
282        retry_after: Option<u64>,
283    ) -> StorageError {
284        let mut headers = reqwest::header::HeaderMap::new();
285        if let Some(seconds) = retry_after {
286            headers.insert(reqwest::header::RETRY_AFTER, seconds.into());
287        }
288        StorageError::Provider {
289            provider,
290            failure,
291            source: Box::new(Self::new(status, headers, Vec::new())),
292        }
293    }
294    /// The provider's requested wait: `Retry-After` as delay-seconds, or as an
295    /// HTTP-date less this response's own `Date` (§6.7). Dropbox also
296    /// states it in its error body.
297    pub(crate) fn retry_after(&self, provider: CloudProvider) -> Option<crate::RetryAfter> {
298        use reqwest::header::{DATE, RETRY_AFTER};
299        if let Some(value) = self.headers.get(RETRY_AFTER) {
300            return Some(retry_after_header(
301                value.to_str().unwrap_or_default(),
302                self.headers.get(DATE).and_then(|date| date.to_str().ok()),
303            ));
304        }
305        if provider == CloudProvider::Dropbox {
306            let value = self.json()?;
307            return value["error"]["retry_after"]
308                .as_u64()
309                .map(|seconds| crate::RetryAfter::Wait(std::time::Duration::from_secs(seconds)));
310        }
311        None
312    }
313    pub(crate) fn into_error(self, provider: CloudProvider) -> StorageError {
314        StorageError::Provider {
315            provider,
316            failure: classify(provider, self.status, self.body()),
317            source: Box::new(self),
318        }
319    }
320    /// Inspect the original provider response explicitly at the app boundary.
321    pub fn body(&self) -> &[u8] {
322        self.body.as_bytes()
323    }
324    /// The body as JSON, when it is JSON.
325    pub(crate) fn json(&self) -> Option<Value> {
326        serde_json::from_slice(self.body()).ok()
327    }
328}
329
330/// The provider response behind `error`, when a provider answered.
331pub(crate) fn provider_response(error: &StorageError) -> Option<&ProviderResponse> {
332    let StorageError::Provider { source, .. } = error else {
333        return None;
334    };
335    source.downcast_ref::<ProviderResponse>()
336}
337
338/// The JSON body of the provider response behind `error`, when it has one.
339pub(crate) fn provider_json(error: &StorageError) -> Option<Value> {
340    provider_response(error)?.json()
341}
342
343/// A Graph error and each error nested in it, under `innerError` or, in
344/// older responses, `innererror`.
345pub(crate) fn graph_errors(error: &Value) -> impl Iterator<Item = &Value> {
346    std::iter::successors(Some(error).filter(|error| error.is_object()), |error| {
347        error
348            .get("innerError")
349            .or_else(|| error.get("innererror"))
350            .filter(|inner| inner.is_object())
351    })
352}
353/// An HTTP-date header's time (RFC 9110 §5.6.7), as `Date` and
354/// `Retry-After` give it.
355pub(crate) fn http_date(value: &str) -> Option<aws_sdk_s3::primitives::DateTime> {
356    use aws_sdk_s3::primitives::{DateTime, DateTimeFormat};
357    DateTime::from_str(value.trim(), DateTimeFormat::HttpDate).ok()
358}
359/// Interpret HTTP retry timing using the response's clock, for both HTTP clients.
360pub(crate) fn retry_after_header(value: &str, date: Option<&str>) -> crate::RetryAfter {
361    use crate::RetryAfter;
362    use std::time::Duration;
363    if let Ok(seconds) = value.trim().parse::<u64>() {
364        return RetryAfter::Wait(Duration::from_secs(seconds));
365    }
366    let parse = |value: &str| http_date(value).map(|time| time.secs());
367    match (parse(value), date.and_then(parse)) {
368        (Some(retry), Some(basis)) => {
369            RetryAfter::Wait(Duration::from_secs(retry.saturating_sub(basis).max(0) as u64))
370        }
371        _ => RetryAfter::NoTimeBasis,
372    }
373}
374
375impl ProviderResponse {
376    /// The error codes the body states, from each provider's fixed
377    /// vocabulary: an OAuth `error` (RFC 6749 §5.2) and Microsoft's
378    /// `error_codes`, Dropbox's error tags, Microsoft Graph's `code` and its
379    /// inner codes, Google's `status` and `reason`s, Cloudflare's numeric
380    /// codes. Never a message, a description or anything else in the body:
381    /// those can echo credentials, paths or account names.
382    fn codes(&self) -> Vec<String> {
383        let Some(value) = self.json() else {
384            return Vec::new();
385        };
386        let mut codes = Vec::new();
387        let mut push = |code: Option<String>| {
388            if let Some(code) = code.filter(|code| !codes.contains(code)) {
389                codes.push(code);
390            }
391        };
392        // Dropbox's asynchronous job status is a tagged body of its own.
393        push(dropbox_tags(&value));
394        let error = &value["error"];
395        push(error.as_str().and_then(fixed_word));
396        push(dropbox_tags(error));
397        for inner in graph_errors(error) {
398            push(inner["code"].as_str().and_then(fixed_word));
399        }
400        push(error["status"].as_str().and_then(fixed_word));
401        for list in [&error["errors"], &error["details"]] {
402            for item in list.as_array().into_iter().flatten() {
403                push(item["reason"].as_str().and_then(fixed_word));
404            }
405        }
406        for code in value["error_codes"].as_array().into_iter().flatten() {
407            push(code.as_u64().map(|code| code.to_string()));
408        }
409        for item in value["errors"].as_array().into_iter().flatten() {
410            push(item["code"].as_u64().map(|code| code.to_string()));
411        }
412        codes
413    }
414}
415/// A word from a provider's fixed vocabulary: letters, digits, `_`, `.`,
416/// `-` and `/`, at most 64 of them. Any other text is not printed.
417pub(super) fn fixed_word(word: &str) -> Option<String> {
418    let fixed = (1..=64).contains(&word.len())
419        && word.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '.' | '-' | '/'));
420    fixed.then(|| word.to_owned())
421}
422/// Dropbox's nested union tags, such as `path/not_found`.
423fn dropbox_tags(value: &Value) -> Option<String> {
424    let mut tags = Vec::new();
425    let mut union = value;
426    while let Some(tag) = union.get(".tag").and_then(Value::as_str).and_then(fixed_word) {
427        union = &union[tag.as_str()];
428        tags.push(tag);
429    }
430    (!tags.is_empty()).then(|| tags.join("/"))
431}
432impl fmt::Debug for ProviderResponse {
433    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
434        f.debug_struct("ProviderResponse")
435            .field("status", &self.status)
436            .field("codes", &self.codes())
437            .finish_non_exhaustive()
438    }
439}
440/// The status and the body's fixed-vocabulary codes, such as "provider
441/// returned HTTP 409 (path/not_found)".
442impl fmt::Display for ProviderResponse {
443    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
444        write!(f, "provider returned HTTP {}", self.status)?;
445        let codes = self.codes();
446        if !codes.is_empty() {
447            write!(f, " ({})", codes.join(", "))?;
448        }
449        Ok(())
450    }
451}
452impl std::error::Error for ProviderResponse {}
453
454pub(crate) fn invalid_response(
455    provider: CloudProvider,
456    status: u16,
457    headers: reqwest::header::HeaderMap,
458    body: Vec<u8>,
459) -> StorageError {
460    StorageError::Provider {
461        provider,
462        failure: StorageFailure::Protocol,
463        source: Box::new(ProviderResponse::new(status, headers, body)),
464    }
465}
466
467pub(crate) async fn checked(
468    provider: CloudProvider,
469    response: Response,
470) -> Result<Response, StorageError> {
471    if response.status().is_success() {
472        return Ok(response);
473    }
474    Err(response_error(provider, response).await)
475}
476pub(crate) async fn response_error(provider: CloudProvider, response: Response) -> StorageError {
477    let status = response.status().as_u16();
478    let headers = response.headers().clone();
479    let body = match response.bytes().await {
480        Ok(body) => body.to_vec(),
481        Err(error) => return transport(provider, error),
482    };
483    ProviderResponse::new(status, headers, body).into_error(provider)
484}
485pub(crate) fn container_error(mut error: StorageError) -> StorageError {
486    match &mut error {
487        StorageError::Provider { failure, .. } if *failure == StorageFailure::NotFound => {
488            *failure = StorageFailure::ContainerNotFound;
489        }
490        _ => {}
491    }
492    error
493}
494pub(crate) fn classify(provider: CloudProvider, status: u16, body: &[u8]) -> StorageFailure {
495    let parsed = match serde_json::from_slice::<Value>(body) {
496        Ok(value) => Some(value),
497        Err(error) => {
498            tracing::debug!(%error, "provider error response is not JSON");
499            None
500        }
501    };
502    if let Some(failure) = parsed
503        .as_ref()
504        .and_then(|value| value["error"].as_str())
505        .and_then(super::oauth::classify_error)
506    {
507        return failure;
508    }
509    let native = parsed.as_ref().and_then(|value| match provider {
510        CloudProvider::Dropbox => dropbox_failure(value),
511        CloudProvider::OneDrive => onedrive_failure(value),
512        _ => None,
513    });
514    if let Some(failure) = native {
515        return failure;
516    }
517    match status {
518        401 => StorageFailure::Authentication,
519        403 => StorageFailure::PermissionDenied,
520        404 => StorageFailure::NotFound,
521        409 if provider == CloudProvider::Dropbox => StorageFailure::Refused,
522        409 | 412 => StorageFailure::AlreadyExists,
523        416 => StorageFailure::InvalidRange,
524        // Another party's lock on the item lasts only while its work runs.
525        423 => StorageFailure::Conflict,
526        429 => StorageFailure::RateLimited,
527        507 => StorageFailure::QuotaExceeded,
528        408 | 500..=599 => StorageFailure::Network,
529        _ => StorageFailure::Refused,
530    }
531}
532fn onedrive_failure(value: &Value) -> Option<StorageFailure> {
533    Some(match value["error"]["code"].as_str()? {
534        "quotaLimitReached" => StorageFailure::QuotaExceeded,
535        "InvalidAuthenticationToken" => StorageFailure::Authentication,
536        "accessDenied" => StorageFailure::PermissionDenied,
537        "itemNotFound" => StorageFailure::NotFound,
538        "nameAlreadyExists" => StorageFailure::AlreadyExists,
539        "activityLimitReached" => StorageFailure::RateLimited,
540        "resourceLocked" => StorageFailure::Conflict,
541        _ => return None,
542    })
543}
544/// What Dropbox's answer to adding a folder member says that only a person
545/// can fix, on either side: the invited address, or the inviting account's
546/// team, plan, email or member limit (§13.2). A retry is answered the same.
547fn sharing_refusal(names: &[&str]) -> Option<coven_foundation::sharing::SharingRefusal> {
548    use coven_foundation::sharing::SharingRefusal as Refusal;
549    let named = |wanted: &[&str]| names.iter().any(|name| wanted.contains(name));
550    if named(&["invalid_email"]) {
551        Some(Refusal::InvalidAddress)
552    } else if named(&["email_unverified"]) {
553        Some(Refusal::EmailUnverified)
554    } else if named(&["cant_share_outside_team"]) {
555        Some(Refusal::TeamSharingOff)
556    } else if named(&["insufficient_plan"]) {
557        Some(Refusal::PlanWithoutSharing)
558    } else if named(&["too_many_members", "too_many_pending_invites"]) {
559        Some(Refusal::TooManyMembers)
560    } else {
561        None
562    }
563}
564fn dropbox_failure(value: &Value) -> Option<StorageFailure> {
565    fn tags<'a>(value: &'a Value, result: &mut Vec<&'a str>) {
566        if let Some(object) = value.as_object() {
567            if let Some(tag) = object.get(".tag").and_then(Value::as_str) {
568                result.push(tag);
569            }
570            for child in object.values().filter(|child| child.is_object()) {
571                tags(child, result);
572            }
573        }
574    }
575    let mut names = Vec::new();
576    if let Some(summary) = value["error_summary"].as_str() {
577        names.extend(summary.trim_end_matches('.').split('/'));
578    }
579    // Dropbox reports its monthly data-transport quota as this AccessError.
580    // Other invalid-account-type cases still describe unavailable permissions.
581    let transport_limit = names.starts_with(&["invalid_account_type", "feature"])
582        || (value["error"][".tag"].as_str() == Some("invalid_account_type")
583            && value["error"]["invalid_account_type"][".tag"].as_str() == Some("feature"));
584    tags(&value["error"], &mut names);
585    tags(&value["failed"], &mut names);
586    // Specific native failures take precedence over HTTP 409's many meanings.
587    if names.iter().any(|name| {
588        matches!(*name, "too_many_requests" | "too_many_write_operations" | "rate_limit")
589    }) {
590        Some(StorageFailure::RateLimited)
591    } else if let Some(refusal) = sharing_refusal(&names) {
592        Some(StorageFailure::SharingRefused(refusal))
593    } else if names.contains(&"missing_scope") {
594        // Refreshing the same authorization cannot add a required scope.
595        Some(StorageFailure::InvalidConfiguration)
596    } else if names
597        .iter()
598        .any(|name| matches!(*name, "expired_access_token" | "invalid_access_token"))
599    {
600        Some(StorageFailure::Authentication)
601    } else if names.iter().any(|name| {
602        matches!(
603            *name,
604            "no_permission"
605                | "no_write_permission"
606                | "access_denied"
607                | "not_a_member"
608                | "invalid_member"
609                | "user_suspended"
610        )
611    }) {
612        Some(StorageFailure::PermissionDenied)
613    } else if transport_limit
614        || names.iter().any(|name| {
615            matches!(
616                *name,
617                "insufficient_space"
618                    | "team_folder_insufficient_space"
619                    | "member_folder_insufficient_space"
620                    | "upload_traffic_limit_reached"
621            )
622        })
623    {
624        Some(StorageFailure::QuotaExceeded)
625    } else if names.contains(&"conflict") {
626        Some(StorageFailure::AlreadyExists)
627    } else if names.contains(&"invalid_root")
628        || names.contains(&"invalid_namespace_id")
629        || names.contains(&"invalid_id")
630    {
631        Some(StorageFailure::ContainerNotFound)
632    } else if names.contains(&"not_found") || names.contains(&"not_folder") {
633        // `not_folder`: a file holds the name of a folder the path needs, so
634        // nothing exists beneath it.
635        Some(StorageFailure::NotFound)
636    } else {
637        None
638    }
639}
640pub(crate) async fn json(
641    provider: CloudProvider,
642    response: Response,
643) -> Result<Value, StorageError> {
644    Ok(json_response(provider, response).await?.0)
645}
646#[expect(
647    clippy::map_err_ignore,
648    reason = "the response is kept as the cause; the parse error adds nothing to it"
649)]
650pub(crate) async fn json_response(
651    provider: CloudProvider,
652    response: Response,
653) -> Result<(Value, ProviderResponse), StorageError> {
654    let response = checked(provider, response).await?;
655    let status = response.status().as_u16();
656    let headers = response.headers().clone();
657    let body = response.bytes().await.map_err(|error| transport(provider, error))?;
658    let value = serde_json::from_slice(&body)
659        .map_err(|_| invalid_response(provider, status, headers.clone(), body.to_vec()))?;
660    Ok((value, ProviderResponse::new(status, headers, body.to_vec())))
661}
662pub(crate) fn string<'a>(value: &'a Value, field: &str) -> Result<&'a str, StorageError> {
663    value[field]
664        .as_str()
665        .filter(|s| !s.is_empty())
666        .ok_or(StorageFailure::Protocol.with_source("missing string field"))
667}
668/// The cursor a Dropbox page names for the next: none, absent or null, on
669/// its last page; an empty one or one that isn't text is a protocol
670/// failure.
671pub(crate) fn page_cursor(value: &Value) -> Result<Option<&str>, StorageError> {
672    match optional_string(value, "cursor")? {
673        Some("") => Err(StorageFailure::Protocol.with_source("empty Dropbox page cursor")),
674        cursor => Ok(cursor),
675    }
676}
677/// The next page a Graph listing names in `@odata.nextLink`: none on its
678/// last page; a link that isn't text is a protocol failure.
679pub(crate) fn next_link(value: &Value) -> Result<Option<&str>, StorageError> {
680    match value.get("@odata.nextLink") {
681        None => Ok(None),
682        Some(_) => string(value, "@odata.nextLink").map(Some),
683    }
684}
685/// An optional nullable provider field must still be text when present.
686pub(crate) fn optional_string<'a>(
687    value: &'a Value,
688    field: &str,
689) -> Result<Option<&'a str>, StorageError> {
690    match value.get(field) {
691        None | Some(Value::Null) => Ok(None),
692        Some(Value::String(value)) => Ok(Some(value)),
693        Some(_) => Err(StorageFailure::Protocol.with_source("non-string optional field")),
694    }
695}
696pub(crate) fn timestamp(
697    value: &Value,
698    field: &str,
699) -> Result<coven_format::value::StorageTime, StorageError> {
700    use aws_sdk_s3::primitives::{DateTime, DateTimeFormat};
701    let timestamp = DateTime::from_str(string(value, field)?, DateTimeFormat::DateTimeWithOffset)
702        .map_err(|error| StorageFailure::Protocol.with_source(error))?;
703    storage_time(timestamp)
704}
705/// A provider's date with every returned digit; a time before the Unix epoch
706/// is a protocol error.
707#[expect(
708    clippy::map_err_ignore,
709    reason = "a time before the epoch is the protocol failure this names"
710)]
711pub(crate) fn storage_time(
712    time: aws_sdk_s3::primitives::DateTime,
713) -> Result<coven_format::value::StorageTime, StorageError> {
714    let seconds = u64::try_from(time.secs())
715        .map_err(|_| StorageFailure::Protocol.with_source("provider time precedes the epoch"))?;
716    coven_format::value::StorageTime::new(seconds, time.subsec_nanos())
717        .map_err(|error| StorageFailure::Protocol.with_source(error))
718}
719pub(crate) fn array<'a>(value: &'a Value, field: &str) -> Result<&'a Vec<Value>, StorageError> {
720    value[field].as_array().ok_or(StorageFailure::Protocol.with_source("missing array field"))
721}
722pub(crate) fn endpoint(
723    base: &str,
724    segments: &[&str],
725    query: &[(&str, &str)],
726) -> Result<String, StorageError> {
727    let mut url = url::Url::parse(base)
728        .map_err(|error| StorageFailure::InvalidConfiguration.with_source(error))?;
729    url.path_segments_mut()
730        .map_err(|()| {
731            StorageFailure::InvalidConfiguration.with_source("provider endpoint cannot hold paths")
732        })?
733        .pop_if_empty()
734        .extend(segments);
735    if !query.is_empty() {
736        url.query_pairs_mut().extend_pairs(query.iter().copied());
737    }
738    Ok(url.into())
739}
740pub(crate) fn same_origin(base: &str, target: &str) -> Result<(), StorageError> {
741    let base = url::Url::parse(base)
742        .map_err(|error| StorageFailure::InvalidConfiguration.with_source(error))?;
743    let target =
744        url::Url::parse(target).map_err(|error| StorageFailure::Protocol.with_source(error))?;
745    if target.origin() != base.origin()
746        || !target.username().is_empty()
747        || target.password().is_some()
748    {
749        return Err(StorageFailure::Protocol.with_source("provider URL crossed origins"));
750    }
751    Ok(())
752}
753pub(crate) fn validate_content_range(header: &str, range: ByteRange) -> Result<u64, StorageError> {
754    let (bounds, total) = header
755        .strip_prefix("bytes ")
756        .and_then(|h| h.split_once('/'))
757        .ok_or(StorageFailure::Protocol.with_source("invalid Content-Range"))?;
758    let total: u64 = total.parse().map_err(|error| StorageFailure::Protocol.with_source(error))?;
759    if range.start() < total
760        && range.end() > total
761        && bounds == format!("{}-{}", range.start(), total - 1)
762    {
763        return Err(StorageFailure::InvalidRange.into());
764    }
765    if bounds != format!("{}-{}", range.start(), range.end() - 1) || range.end() > total {
766        return Err(StorageFailure::Protocol.with_source("Content-Range disagrees with request"));
767    }
768    Ok(total)
769}
770
771pub(crate) async fn verify_published_part(
772    storage: &dyn crate::ProviderOps,
773    session: &mut crate::UploadSession,
774    bytes: &[u8],
775    end: u64,
776) -> Result<(), StorageError> {
777    compare_published_part(storage, session, bytes, end).await?;
778    session.confirmed = end;
779    if end == session.total {
780        session.state = crate::session::SessionState::Complete;
781    }
782    Ok(())
783}
784
785pub(crate) async fn compare_published_part(
786    storage: &dyn crate::ProviderOps,
787    session: &crate::UploadSession,
788    bytes: &[u8],
789    end: u64,
790) -> Result<(), StorageError> {
791    let range = ByteRange::new(session.confirmed, end)?;
792    let actual = storage.read_object(session.path(), Some(range)).await?;
793    actual.check(session.path(), Some(range))?;
794    if actual.metadata.size != session.total || actual.bytes != bytes {
795        return Err(StorageFailure::AlreadyExists.into());
796    }
797    Ok(())
798}
799
800#[cfg(test)]
801#[path = "http_tests.rs"]
802mod tests;