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>, ) -> 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.

Examples found in repository ?

examples/prepared_request.rs (lines 100-107)

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        )
108        .map_err(|_| PrepareError::InvalidRawResponsePolicy)
109    }

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 transport_request(self) -> TransportRequest<'request>

Returns the validated transport request.

Examples found in repository ?

examples/prepared_request.rs (line 118)

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

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 119)

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

Source

pub const fn response_policy(self) -> ResponsePolicy

Returns complete checked-response policy.

Examples found in repository ?

examples/prepared_request.rs (line 120)

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

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 authenticated_request( self, ) -> AuthenticatedRequest<'request, 'request>

Returns the request with its mandatory authentication and raw wire 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 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