cloud-sdk 0.55.0

no_std-first provider-neutral cloud SDK foundations.
Documentation 
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

use crate::rate_limit::{RateLimit, WallClockTimestamp};
use crate::retry::MonotonicDuration;

use super::{ProgressChange, ProgressObservation};

/// Caller decision made independently from delay policy.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PollControl {
    /// Continue the bounded workflow.
    Continue,
    /// Cancel before another request is admitted.
    Cancel,
}

/// Provider-owned wall-clock telemetry carried without driving local budgets.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct ProviderTimeObservation {
    observed_at: Option<WallClockTimestamp>,
    expires_at: Option<WallClockTimestamp>,
}

impl ProviderTimeObservation {
    /// Creates coherent provider timestamps.
    pub const fn new(
        observed_at: Option<WallClockTimestamp>,
        expires_at: Option<WallClockTimestamp>,
    ) -> Result<Self, ProviderTimeError> {
        if let (Some(observed), Some(expires)) = (observed_at, expires_at)
            && expires.get() < observed.get()
        {
            return Err(ProviderTimeError::ExpiryBeforeObservation);
        }
        Ok(Self {
            observed_at,
            expires_at,
        })
    }

    /// Returns the provider-reported observation timestamp.
    #[must_use]
    pub const fn observed_at(self) -> Option<WallClockTimestamp> {
        self.observed_at
    }

    /// Returns the provider-reported expiry timestamp.
    #[must_use]
    pub const fn expires_at(self) -> Option<WallClockTimestamp> {
        self.expires_at
    }
}

/// Invalid provider wall-clock telemetry.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ProviderTimeError {
    /// The provider expiry precedes its observation timestamp.
    ExpiryBeforeObservation,
}

impl_static_error!(ProviderTimeError,
    Self::ExpiryBeforeObservation => "provider expiry precedes its observation timestamp",
);

/// Redacted context supplied to caller-owned backoff policy.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PollContext {
    pub(crate) observation: u32,
    pub(crate) progress: ProgressObservation,
    pub(crate) progress_change: ProgressChange,
    pub(crate) rate_limit: Option<RateLimit>,
    pub(crate) provider_time: ProviderTimeObservation,
}

impl PollContext {
    /// Returns the one-based accepted observation count.
    #[must_use]
    pub const fn observation(self) -> u32 {
        self.observation
    }

    /// Returns provider progress without inferring missing values.
    #[must_use]
    pub const fn progress(self) -> ProgressObservation {
        self.progress
    }

    /// Returns the validated progress transition.
    #[must_use]
    pub const fn progress_change(self) -> ProgressChange {
        self.progress_change
    }

    /// Returns provider quota telemetry when supplied.
    #[must_use]
    pub const fn rate_limit(self) -> Option<RateLimit> {
        self.rate_limit
    }

    /// Returns provider wall-clock telemetry.
    #[must_use]
    pub const fn provider_time(self) -> ProviderTimeObservation {
        self.provider_time
    }
}

/// Next caller action before another provider request.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PollRequestStep {
    /// One provider action request is admitted now.
    Request,
    /// Wait this monotonic duration before asking again.
    Delay(MonotonicDuration),
    /// Caller cancellation made the workflow terminal.
    Cancelled,
    /// The monotonic elapsed budget made the workflow terminal.
    TimedOut,
}