Struct PreparedRequest

Source

pub struct PreparedRequest<'request> { /* private fields */ }

Expand description

Complete request, endpoint, operation metadata, and response policy.

Implementations§

Source §

impl<'request> PreparedRequest<'request>

Source

pub async fn execute_local_async<'transport, 'buffer, T>( &'transport self, transport: &'transport T, response_storage: &'buffer mut [u8], response_header_storage: &'buffer mut [u8], ) -> Result<CheckedResponseGuard<'buffer>, PreparedExecutionError<T::Error>>
where T: LocalAsyncAuthenticatedTransport + BoundTransport, 'request: 'transport,

Verifies endpoint identity, executes once on a local async transport, and validates the response.

This method owns no executor and does not require the returned future to be Send. Dropping it clears the response buffer while request delivery remains conservatively possibly sent.

Source §

impl<'request> PreparedRequest<'request>

Source

pub fn new( request: TransportRequest<'request>, service: ProviderService<'request>, metadata: OperationMetadata, response_policy: ResponsePolicy, authentication_policy: AuthenticationScopePolicy<'request>, raw_response_policy: RawResponsePolicy<'request>, body_sensitivity: RequestBodySensitivity, ) -> Result<Self, PreparedRequestPolicyError>

Creates a complete prepared request after checking cross-policy invariants.

§Errors

Returns PreparedRequestPolicyError::MissingRequestIdHeader when operation metadata protects or retains request IDs but the raw response policy does not admit x-request-id. Returns PreparedRequestPolicyError::ReadOnlyMethodMismatch when read-only metadata is paired with any method other than GET or HEAD. body_sensitivity is mandatory so provider implementations cannot omit the confidential-body review and silently receive a public default.

Examples found in repository ?

examples/prepared_request.rs (lines 100-108)

49    fn prepare<'storage>(
50        &self,
51        storage: PreparationStorage<'storage>,
52    ) -> Result<PreparedRequest<'storage>, Self::Error> {
53        let (target_storage, _body_storage) = storage.into_parts();
54        let target = target_storage
55            .get_mut(..17)
56            .ok_or(PrepareError::TargetBuffer)?;
57        target.copy_from_slice(b"/resources?page=1");
58        let target = core::str::from_utf8(target).map_err(|_| PrepareError::InvalidTarget)?;
59        let target = RequestTarget::new(target).map_err(|_| PrepareError::InvalidTarget)?;
60        let request = TransportRequest::new(Method::Get, target);
61        let metadata = OperationMetadata::new(
62            OperationImpact::ReadOnly,
63            RequestSemantics::Safe,
64            RetryEligibility::ExplicitPolicy,
65            CostIntent::NoKnownCost,
66            RequestIdPolicy::Protected,
67        )
68        .map_err(|_| PrepareError::InvalidMetadata)?;
69        let response_policy = ResponsePolicy::new(
70            &OK_STATUS,
71            ContentTypePolicy::Required(&JSON_MEDIA),
72            ResponseBodyPolicy::Required,
73            65_536,
74        )
75        .map_err(|_| PrepareError::InvalidResponsePolicy)?;
76        let endpoint =
77            EndpointIdentity::new(EndpointScheme::Https, "api.example.invalid", 443, "/v1")
78                .map_err(|_| PrepareError::InvalidEndpoint)?;
79        let authentication_policy = AuthenticationScopePolicy::new(
80            ScopeRequirement::Required(ExampleProvider::ID),
81            ScopeRequirement::Required(ComputeService::ID),
82            ScopeRequirement::Required(endpoint),
83            ScopeRequirement::Forbidden,
84            ScopeRequirement::Forbidden,
85            ScopeRequirement::Forbidden,
86        );
87        let content_type =
88            HeaderName::new("content-type").map_err(|_| PrepareError::InvalidRawResponsePolicy)?;
89        let request_id =
90            HeaderName::new("x-request-id").map_err(|_| PrepareError::InvalidRawResponsePolicy)?;
91        let raw_response_policy = RawResponsePolicy::new(
92            65_536,
93            65_536,
94            ResponseMediaPolicy::Required(&JSON_MEDIA),
95            ResponseMediaPolicy::Required(&JSON_MEDIA),
96            &[content_type, request_id],
97            8,
98        )
99        .map_err(|_| PrepareError::InvalidRawResponsePolicy)?;
100        PreparedRequest::new(
101            request,
102            ProviderService::from_marker::<ComputeService>(EndpointPolicy::fixed(endpoint)),
103            metadata,
104            response_policy,
105            authentication_policy,
106            raw_response_policy,
107            cloud_sdk::operation::RequestBodySensitivity::Public,
108        )
109        .map_err(|_| PrepareError::InvalidRawResponsePolicy)
110    }

Source

pub const fn with_operation_id(self, operation_id: OperationId) -> Self

Binds a validated provider operation identifier to this request.

Source

pub const fn with_replayable_body(self) -> Self

Marks the immutable prepared body snapshot as byte-for-byte replayable.

Providers must call this only after preparation has completed and when the borrowed body bytes cannot change for the prepared request lifetime.

Source

pub const fn with_sensitive_body(self) -> Self

Upgrades the explicit body classification to sensitive.

This cannot downgrade a sensitive body. Providers should classify the body at construction; this helper supports reviewed wrapper policies.

Source

pub const fn transport_request(self) -> TransportRequest<'request>

Returns the validated transport request.

Examples found in repository ?

examples/prepared_request.rs (line 119)

113fn main() {
114    let mut target = [0_u8; MAX_REQUEST_TARGET_BYTES];
115    let mut body = [0_u8; 1];
116    let prepared = ListResources.prepare(PreparationStorage::new(&mut target, &mut body));
117    let Ok(prepared) = prepared else { return };
118
119    assert_eq!(prepared.transport_request().method(), Method::Get);
120    assert_eq!(prepared.metadata().impact(), OperationImpact::ReadOnly);
121    assert_eq!(prepared.response_policy().max_body_bytes(), 65_536);
122}

Source

pub const fn service(self) -> ProviderService<'request>

Returns the bound provider service.

Source

pub const fn metadata(self) -> OperationMetadata

Returns complete safety and retry metadata.

Examples found in repository ?

examples/prepared_request.rs (line 120)

113fn main() {
114    let mut target = [0_u8; MAX_REQUEST_TARGET_BYTES];
115    let mut body = [0_u8; 1];
116    let prepared = ListResources.prepare(PreparationStorage::new(&mut target, &mut body));
117    let Ok(prepared) = prepared else { return };
118
119    assert_eq!(prepared.transport_request().method(), Method::Get);
120    assert_eq!(prepared.metadata().impact(), OperationImpact::ReadOnly);
121    assert_eq!(prepared.response_policy().max_body_bytes(), 65_536);
122}

Source

pub const fn response_policy(self) -> ResponsePolicy

Returns complete checked-response policy.

Examples found in repository ?

examples/prepared_request.rs (line 121)

113fn main() {
114    let mut target = [0_u8; MAX_REQUEST_TARGET_BYTES];
115    let mut body = [0_u8; 1];
116    let prepared = ListResources.prepare(PreparationStorage::new(&mut target, &mut body));
117    let Ok(prepared) = prepared else { return };
118
119    assert_eq!(prepared.transport_request().method(), Method::Get);
120    assert_eq!(prepared.metadata().impact(), OperationImpact::ReadOnly);
121    assert_eq!(prepared.response_policy().max_body_bytes(), 65_536);
122}

Source

pub const fn authentication_policy(self) -> AuthenticationScopePolicy<'request>

Returns the complete provider-owned authentication-scope policy.

Source

pub const fn raw_response_policy(self) -> RawResponsePolicy<'request>

Returns the complete status-class raw response policy.

Source

pub const fn operation_id(self) -> Option<OperationId>

Returns the provider operation identifier when one was bound.

Source

pub const fn body_replayability(self) -> BodyReplayability

Returns the explicit request-body replay capability.

Source

pub const fn body_sensitivity(self) -> RequestBodySensitivity

Returns the provider-declared request-body sensitivity.

Source

pub fn validate_response<'buffer>( self, response: ResponseBuffer<'buffer>, ) -> Result<CheckedResponseGuard<'buffer>, ResponsePolicyError>

Applies the complete prepared response policy without executing transport.

Source

pub fn apply_response_metadata_policy( self, response: &mut ResponseBuffer<'_>, ) -> Result<(), ResponsePolicyError>

Applies operation-owned metadata policy before provider error decoding.

This is the error-status counterpart to Self::validate_response. It extracts and protects, discards, or admits retention of the provider request identifier without applying success-status or body policy.

Source