use crate::compliance::errors::{
classify_compliance_error, is_compliance_business_error, ComplianceErrorInfo,
ComplianceErrorKey,
};
use crate::compliance::evidence::{
CreateEvidenceAssetRequest, EvidenceAsset, EvidenceAssetPageItem, EvidencePackage,
EvidencePackagePageItem, ListEvidenceAssetsRequest, ListEvidencePackagesRequest,
PublicEvidenceVerifyResult,
};
use crate::compliance::operation::{
ComplianceCapability, ListOperationsRequest, OperationDetail, OperationPageItem,
};
use crate::compliance::provider::{ComplianceProviderRequestStatus, ProviderRequestStatusView};
use crate::compliance::report::{
ComplianceReport, CreateReportRequest, ListReportsRequest, ReportDownload, ReportPageItem,
};
use crate::compliance::seal_approval::{
ApproveSealApprovalQuery, CancelSealApprovalQuery, ListSealApprovalsRequest,
ListSealUsesRequest, RejectSealApprovalQuery, SealApproval, SealApprovalPageItem,
SealUsePageItem, SubmitSealApprovalRequest,
};
use crate::compliance::signing::{
CreateH5SigningUrlRequest, CreateSigningEnvelopeRequest, EnvelopeContractItem,
ListSigningEnvelopesRequest, SignEnvelopeRequest, SigningEnvelope, SigningEnvelopePageItem,
VoidEnvelopeRequest,
};
use crate::compliance::template::{
ContractTemplatePageItem, ContractTemplateResp, ContractTemplateVersion,
CreateContractTemplateRequest, ListContractTemplatesRequest, UpdateContractTemplateRequest,
UploadContractTemplatePdfRequest,
};
use crate::compliance::timestamp::{
ComplianceTimestampVerificationStatus, IssueTimestampRequest, ListTimestampsRequest,
TimestampPageItem, TimestampToken, TimestampVerifyResult, TsaProvider, TsaStats,
VerifyTimestampRequest,
};
use crate::compliance::types::{CompliancePollOptions, ComplianceWriteOptions};
use crate::core::client::Client;
use crate::core::http::{
parse_http_error_with_retry_after, read_limited_text, DEFAULT_JSON_TIMEOUT_MS,
MAX_ERROR_BODY_SIZE,
};
use crate::shared::pagination::PageRequest;
use crate::shared::{ApiResponse, Error, Result};
use serde::de::DeserializeOwned;
use serde::Serialize;
use std::future::Future;
use std::pin::Pin;
use std::time::{Duration, Instant};
use tokio_util::sync::CancellationToken;
const DEFAULT_POLL_TIMEOUT_MS: u64 = 60_000;
const DEFAULT_POLL_INITIAL_INTERVAL_MS: u64 = 1_000;
const DEFAULT_POLL_MAX_INTERVAL_MS: u64 = 5_000;
const DEFAULT_POLL_MULTIPLIER: f64 = 1.5;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CompliancePollErrorKind {
Timeout,
TerminalFailure,
StepUpRequired,
Unknown,
}
#[derive(Debug, Clone)]
pub struct CompliancePollError {
pub message: String,
pub kind: CompliancePollErrorKind,
pub last_info: Option<ComplianceErrorInfo>,
}
impl std::fmt::Display for CompliancePollError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.message)
}
}
impl std::error::Error for CompliancePollError {}
impl CompliancePollError {
fn new(
message: impl Into<String>,
kind: CompliancePollErrorKind,
last_info: Option<ComplianceErrorInfo>,
) -> Self {
Self {
message: message.into(),
kind,
last_info,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum PollDecision {
Continue,
Done,
Failed,
}
pub struct ComplianceClient {
client: Client,
}
impl ComplianceClient {
pub(crate) fn new(client: Client) -> Self {
Self { client }
}
pub async fn create_evidence_asset(
&self,
req: &CreateEvidenceAssetRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<EvidenceAsset> {
self.write(
"POST",
"/compliance/evidence/assets",
Some(req),
opts,
signal,
)
.await
}
pub async fn get_evidence_asset(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<EvidenceAsset> {
self.read(&format!("/compliance/evidence/assets/{id}"), None, signal)
.await
}
pub async fn list_evidence_assets(
&self,
req: &ListEvidenceAssetsRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<EvidenceAssetPageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("assetType", req.asset_type.as_deref());
q.add("status", req.status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/evidence/assets/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn verify_evidence_public(
&self,
evidence_no: Option<&str>,
public_verify_code: Option<&str>,
signal: Option<CancellationToken>,
) -> Result<PublicEvidenceVerifyResult> {
let mut parts: Vec<String> = Vec::new();
if let Some(v) = evidence_no.filter(|s| !s.is_empty()) {
parts.push(format!("evidenceNo={}", urlencode(v)));
}
if let Some(v) = public_verify_code.filter(|s| !s.is_empty()) {
parts.push(format!("publicVerifyCode={}", urlencode(v)));
}
let qs = if parts.is_empty() {
String::new()
} else {
format!("?{}", parts.join("&"))
};
self.public_read(&format!("/compliance/evidence/verify{qs}"), signal)
.await
}
pub async fn issue_timestamp(
&self,
req: &IssueTimestampRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<TimestampToken> {
self.write("POST", "/compliance/timestamps", Some(req), opts, signal)
.await
}
pub async fn issue_timestamp_for_asset(
&self,
asset_id: i64,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<TimestampToken> {
self.write::<(), _>(
"POST",
&format!("/compliance/evidence/assets/{asset_id}/timestamp"),
None,
opts,
signal,
)
.await
}
pub async fn get_timestamp(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<TimestampToken> {
self.read(&format!("/compliance/timestamps/{id}"), None, signal)
.await
}
pub async fn list_timestamps(
&self,
req: &ListTimestampsRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<TimestampPageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("provider", req.provider.as_deref());
q.add("verificationStatus", req.verification_status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/timestamps/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn verify_timestamp(
&self,
req: &VerifyTimestampRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<TimestampVerifyResult> {
self.write(
"POST",
"/compliance/timestamps/verify",
Some(req),
opts,
signal,
)
.await
}
pub async fn wait_for_timestamp_verified(
&self,
id: i64,
opts: &CompliancePollOptions,
signal: Option<CancellationToken>,
) -> std::result::Result<TimestampToken, CompliancePollError> {
self.poll(
|| self.get_timestamp(id, signal.clone()),
|t: &TimestampToken| classify_timestamp(&t.verification_status),
opts,
signal.clone(),
derive_last_info_timestamp,
)
.await
}
pub async fn list_tsa_providers(
&self,
signal: Option<CancellationToken>,
) -> Result<Vec<TsaProvider>> {
self.read("/compliance/timestamps/providers", None, signal)
.await
}
pub async fn get_tsa_stats(&self, signal: Option<CancellationToken>) -> Result<TsaStats> {
self.read("/compliance/timestamps/stats", None, signal)
.await
}
pub async fn build_evidence_package(
&self,
asset_id: i64,
timestamp_token_id: Option<i64>,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<EvidencePackage> {
let ts_param = match timestamp_token_id {
Some(id) => format!("?timestampTokenId={id}"),
None => String::new(),
};
self.write::<(), _>(
"POST",
&format!("/compliance/evidence/assets/{asset_id}/packages{ts_param}"),
None,
opts,
signal,
)
.await
}
pub async fn list_evidence_packages(
&self,
req: &ListEvidencePackagesRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<EvidencePackagePageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("status", req.status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/evidence/packages/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn create_report(
&self,
req: &CreateReportRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<ComplianceReport> {
self.write("POST", "/compliance/reports", Some(req), opts, signal)
.await
}
pub async fn get_report(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<ComplianceReport> {
self.read(&format!("/compliance/reports/{id}"), None, signal)
.await
}
pub async fn list_reports(
&self,
req: &ListReportsRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<ReportPageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("status", req.status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/reports/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn publish_report(
&self,
id: i64,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<ComplianceReport> {
self.write::<(), _>(
"POST",
&format!("/compliance/reports/{id}/publish"),
None,
opts,
signal,
)
.await
}
pub async fn download_report(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<ReportDownload> {
self.read(&format!("/compliance/reports/{id}/download"), None, signal)
.await
}
pub async fn create_signing_envelope(
&self,
req: &CreateSigningEnvelopeRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<i64> {
self.write(
"POST",
"/compliance/signing-envelopes",
Some(req),
opts,
signal,
)
.await
}
pub async fn get_signing_envelope(
&self,
envelope_id: i64,
signal: Option<CancellationToken>,
) -> Result<SigningEnvelope> {
self.read(
&format!("/compliance/signing-envelopes/{envelope_id}"),
None,
signal,
)
.await
}
pub async fn list_signing_envelopes(
&self,
req: &ListSigningEnvelopesRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<SigningEnvelopePageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("status", req.status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/signing-envelopes/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn sign_envelope(
&self,
envelope_id: i64,
req: &SignEnvelopeRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<()> {
self.write_unit(
"POST",
&format!("/compliance/signing-envelopes/{envelope_id}/sign"),
Some(req),
opts,
signal,
)
.await
}
pub async fn create_h5_signing_url(
&self,
envelope_id: i64,
req: &CreateH5SigningUrlRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<String> {
self.write(
"POST",
&format!("/compliance/signing-envelopes/{envelope_id}/h5-url"),
Some(req),
opts,
signal,
)
.await
}
pub async fn sync_signing_envelope_status(
&self,
envelope_id: i64,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<()> {
self.write_unit::<()>(
"POST",
&format!("/compliance/signing-envelopes/{envelope_id}/sync-provider-status"),
None,
opts,
signal,
)
.await
}
pub async fn list_envelope_contracts(
&self,
envelope_id: i64,
signal: Option<CancellationToken>,
) -> Result<Vec<EnvelopeContractItem>> {
self.read(
&format!("/compliance/signing-envelopes/{envelope_id}/contracts"),
None,
signal,
)
.await
}
pub async fn list_envelope_provider_requests(
&self,
envelope_id: i64,
signal: Option<CancellationToken>,
) -> Result<Vec<OperationPageItem>> {
self.read(
&format!("/compliance/signing-envelopes/{envelope_id}/provider-requests"),
None,
signal,
)
.await
}
pub async fn void_envelope(
&self,
envelope_id: i64,
req: &VoidEnvelopeRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<bool> {
self.write(
"POST",
&format!("/compliance/signing-envelopes/{envelope_id}/void"),
Some(req),
opts,
signal,
)
.await
}
pub async fn submit_seal_approval(
&self,
req: &SubmitSealApprovalRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<i64> {
self.write(
"POST",
"/compliance/seal-approvals",
Some(req),
opts,
signal,
)
.await
}
pub async fn approve_seal_approval(
&self,
id: i64,
query: &ApproveSealApprovalQuery,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<()> {
let mut parts: Vec<String> = Vec::new();
if let Some(v) = query.expires_at.as_deref().filter(|s| !s.is_empty()) {
parts.push(format!("expiresAt={}", urlencode(v)));
}
if let Some(v) = query.note.as_deref().filter(|s| !s.is_empty()) {
parts.push(format!("note={}", urlencode(v)));
}
let qs = qstr(&parts);
self.write_unit::<()>(
"POST",
&format!("/compliance/seal-approvals/{id}/approve{qs}"),
None,
opts,
signal,
)
.await
}
pub async fn reject_seal_approval(
&self,
id: i64,
query: &RejectSealApprovalQuery,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<()> {
let mut parts: Vec<String> = Vec::new();
if let Some(v) = query.reason.as_deref().filter(|s| !s.is_empty()) {
parts.push(format!("reason={}", urlencode(v)));
}
let qs = qstr(&parts);
self.write_unit::<()>(
"POST",
&format!("/compliance/seal-approvals/{id}/reject{qs}"),
None,
opts,
signal,
)
.await
}
pub async fn cancel_seal_approval(
&self,
id: i64,
query: &CancelSealApprovalQuery,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<()> {
let mut parts: Vec<String> = Vec::new();
if let Some(v) = query.reason.as_deref().filter(|s| !s.is_empty()) {
parts.push(format!("reason={}", urlencode(v)));
}
let qs = qstr(&parts);
self.write_unit::<()>(
"POST",
&format!("/compliance/seal-approvals/{id}/cancel{qs}"),
None,
opts,
signal,
)
.await
}
pub async fn list_pending_seal_approvals(
&self,
signal: Option<CancellationToken>,
) -> Result<Vec<SealApproval>> {
self.read("/compliance/seal-approvals/pending", None, signal)
.await
}
pub async fn get_seal_approval(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<SealApproval> {
self.read(&format!("/compliance/seal-approvals/{id}"), None, signal)
.await
}
pub async fn list_seal_approvals(
&self,
req: &ListSealApprovalsRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<SealApprovalPageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("status", req.status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/seal-approvals/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn list_seal_uses(
&self,
req: &ListSealUsesRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<SealUsePageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("sealId", req.seal_id.map(|v| v.to_string()).as_deref());
q.add(
"envelopeId",
req.envelope_id.map(|v| v.to_string()).as_deref(),
);
q.add("usageStatus", req.usage_status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/seal-uses/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn get_provider_request(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<ProviderRequestStatusView> {
self.read(&format!("/compliance/provider-requests/{id}"), None, signal)
.await
}
pub async fn wait_for_provider_request_terminal(
&self,
id: i64,
opts: &CompliancePollOptions,
signal: Option<CancellationToken>,
) -> std::result::Result<ProviderRequestStatusView, CompliancePollError> {
self.poll(
|| self.get_provider_request(id, signal.clone()),
|v: &ProviderRequestStatusView| classify_provider_status(&v.status),
opts,
signal.clone(),
derive_last_info_provider,
)
.await
}
pub async fn get_capabilities(
&self,
signal: Option<CancellationToken>,
) -> Result<Vec<ComplianceCapability>> {
self.read("/compliance/capabilities", None, signal).await
}
pub async fn get_feature_gate(
&self,
action: &str,
signal: Option<CancellationToken>,
) -> Result<Option<ComplianceCapability>> {
let caps = self.get_capabilities(signal).await?;
Ok(caps.into_iter().find(|c| c.action == action))
}
pub async fn list_operations(
&self,
req: &ListOperationsRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<OperationPageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("status", req.status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/operations/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn get_operation(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<OperationDetail> {
self.read(&format!("/compliance/operations/{id}"), None, signal)
.await
}
pub async fn create_contract_template(
&self,
req: &CreateContractTemplateRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<ContractTemplateResp> {
self.write(
"POST",
"/compliance/contract-templates",
Some(req),
opts,
signal,
)
.await
}
pub async fn update_contract_template(
&self,
id: i64,
req: &UpdateContractTemplateRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<ContractTemplateResp> {
self.write(
"POST",
&format!("/compliance/contract-templates/{id}"),
Some(req),
opts,
signal,
)
.await
}
pub async fn delete_contract_template(
&self,
id: i64,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<()> {
self.write_unit::<()>(
"POST",
&format!("/compliance/contract-templates/{id}/delete"),
None,
opts,
signal,
)
.await
}
pub async fn get_contract_template(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<ContractTemplateResp> {
self.read(
&format!("/compliance/contract-templates/{id}"),
None,
signal,
)
.await
}
pub async fn list_contract_templates(
&self,
req: &ListContractTemplatesRequest,
signal: Option<CancellationToken>,
) -> Result<crate::shared::pagination::PageResult<ContractTemplatePageItem>> {
let mut q = QueryBuilder::new(&req.page);
q.add("status", req.status.as_deref());
q.add("createTimeStart", req.create_time_start.as_deref());
q.add("createTimeEnd", req.create_time_end.as_deref());
let path = format!("/compliance/contract-templates/page{}", q.finish());
self.read(&path, None, signal).await
}
pub async fn upload_contract_template_pdf(
&self,
id: i64,
req: &UploadContractTemplatePdfRequest,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<ContractTemplateResp> {
self.write(
"POST",
&format!("/compliance/contract-templates/{id}/pdf"),
Some(req),
opts,
signal,
)
.await
}
pub async fn publish_contract_template(
&self,
id: i64,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<ContractTemplateResp> {
self.write::<(), _>(
"POST",
&format!("/compliance/contract-templates/{id}/publish"),
None,
opts,
signal,
)
.await
}
pub async fn archive_contract_template(
&self,
id: i64,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<ContractTemplateResp> {
self.write::<(), _>(
"POST",
&format!("/compliance/contract-templates/{id}/archive"),
None,
opts,
signal,
)
.await
}
pub async fn list_contract_template_versions(
&self,
id: i64,
signal: Option<CancellationToken>,
) -> Result<Vec<ContractTemplateVersion>> {
self.read(
&format!("/compliance/contract-templates/{id}/versions"),
None,
signal,
)
.await
}
pub fn classify_error(&self, err: &Error) -> Option<ComplianceErrorInfo> {
if !matches!(err, Error::Business { .. }) {
return None;
}
if !is_compliance_business_error(err) {
return None;
}
Some(classify_compliance_error(err))
}
async fn read<T: DeserializeOwned>(
&self,
path: &str,
body: Option<&str>,
signal: Option<CancellationToken>,
) -> Result<T> {
self.client
.compliance_execute_json(reqwest::Method::GET, path, body, signal, true, &[])
.await
}
async fn public_read<T: DeserializeOwned>(
&self,
path: &str,
signal: Option<CancellationToken>,
) -> Result<T> {
self.client.compliance_public_read(path, signal).await
}
async fn write<B: Serialize, T: DeserializeOwned>(
&self,
method: &str,
path: &str,
body: Option<&B>,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<T> {
let body_str = match body {
Some(b) => Some(
serde_json::to_string(b)
.map_err(|e| Error::other(format!("{path}: serialize body: {e}")))?,
),
None => None,
};
let m = reqwest::Method::from_bytes(method.as_bytes())
.map_err(|e| Error::other(format!("invalid method {method}: {e}")))?;
let extra = idempotency_header(opts);
self.client
.compliance_execute_json(m, path, body_str.as_deref(), signal, false, &extra)
.await
}
async fn write_unit<B: Serialize>(
&self,
method: &str,
path: &str,
body: Option<&B>,
opts: &ComplianceWriteOptions,
signal: Option<CancellationToken>,
) -> Result<()> {
let body_str = match body {
Some(b) => Some(
serde_json::to_string(b)
.map_err(|e| Error::other(format!("{path}: serialize body: {e}")))?,
),
None => None,
};
let m = reqwest::Method::from_bytes(method.as_bytes())
.map_err(|e| Error::other(format!("invalid method {method}: {e}")))?;
let extra = idempotency_header(opts);
self.client
.compliance_execute_unit(m, path, body_str.as_deref(), signal, false, &extra)
.await
}
async fn poll<T, F, Fut, C, D>(
&self,
mut fetcher: F,
classify: C,
opts: &CompliancePollOptions,
signal: Option<CancellationToken>,
derive_last: D,
) -> std::result::Result<T, CompliancePollError>
where
F: FnMut() -> Fut,
Fut: Future<Output = Result<T>>,
C: Fn(&T) -> PollDecision,
D: Fn(&T) -> ComplianceErrorInfo,
{
let timeout_ms = opts.timeout_ms.unwrap_or(DEFAULT_POLL_TIMEOUT_MS);
let initial = opts
.initial_interval_ms
.unwrap_or(DEFAULT_POLL_INITIAL_INTERVAL_MS);
let max_interval = opts.max_interval_ms.unwrap_or(DEFAULT_POLL_MAX_INTERVAL_MS);
let multiplier = opts.multiplier.unwrap_or(DEFAULT_POLL_MULTIPLIER);
let deadline = Instant::now() + Duration::from_millis(timeout_ms);
let mut interval_ms = initial;
let mut last_value: Option<T> = None;
while Instant::now() < deadline {
if signal.as_ref().map(|s| s.is_cancelled()).unwrap_or(false) {
return Err(CompliancePollError::new(
"compliance poll aborted",
CompliancePollErrorKind::Unknown,
last_value.as_ref().map(&derive_last),
));
}
let value = fetcher().await.map_err(|e| {
CompliancePollError::new(
format!("compliance poll fetch failed: {e}"),
CompliancePollErrorKind::Unknown,
None,
)
})?;
let decision = classify(&value);
match decision {
PollDecision::Done => return Ok(value),
PollDecision::Failed => {
return Err(CompliancePollError::new(
"compliance poll observed terminal failure",
CompliancePollErrorKind::TerminalFailure,
Some(derive_last(&value)),
));
}
PollDecision::Continue => {}
}
last_value = Some(value);
let remaining = deadline.saturating_duration_since(Instant::now());
let sleep_ms = interval_ms.min(remaining.as_millis() as u64);
if sleep_ms == 0 {
break;
}
match &signal {
Some(cancel) => {
tokio::select! {
_ = tokio::time::sleep(Duration::from_millis(sleep_ms)) => {}
_ = cancel.cancelled() => {
return Err(CompliancePollError::new(
"compliance poll aborted",
CompliancePollErrorKind::Unknown,
last_value.as_ref().map(&derive_last),
));
}
}
}
None => tokio::time::sleep(Duration::from_millis(sleep_ms)).await,
}
interval_ms = ((interval_ms as f64 * multiplier).floor() as u64).min(max_interval);
}
Err(CompliancePollError::new(
"compliance poll timed out",
CompliancePollErrorKind::Timeout,
last_value.as_ref().map(&derive_last),
))
}
}
impl Client {
pub fn compliance(&self) -> ComplianceClient {
ComplianceClient::new(self.clone())
}
pub fn compliance_url(&self, path: &str) -> String {
let base = match self.compliance_base_url() {
Some(b) => b.to_string(),
None => format!("{}/admin-api", self.server_url()),
};
format!("{base}{path}")
}
pub(crate) async fn compliance_execute_json<T: DeserializeOwned>(
&self,
method: reqwest::Method,
path: &str,
body: Option<&str>,
signal: Option<CancellationToken>,
retry_on_401: bool,
extra_headers: &[(String, String)],
) -> Result<T> {
let bytes = self
.compliance_execute_bytes(method, path, body, signal, retry_on_401, extra_headers)
.await?;
if bytes.is_empty() {
return Err(Error::other(format!("{path}: empty response body")));
}
let env: ApiResponse<T> = serde_json::from_slice(&bytes)
.map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
if let Some(err) = env.business_error() {
return Err(err);
}
Ok(env.data)
}
pub(crate) async fn compliance_execute_unit(
&self,
method: reqwest::Method,
path: &str,
body: Option<&str>,
signal: Option<CancellationToken>,
retry_on_401: bool,
extra_headers: &[(String, String)],
) -> Result<()> {
let bytes = self
.compliance_execute_bytes(method, path, body, signal, retry_on_401, extra_headers)
.await?;
if bytes.is_empty() {
return Ok(());
}
let env: ApiResponse<serde_json::Value> = serde_json::from_slice(&bytes)
.map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
if let Some(err) = env.business_error() {
return Err(err);
}
Ok(())
}
async fn compliance_execute_bytes(
&self,
method: reqwest::Method,
path: &str,
body: Option<&str>,
signal: Option<CancellationToken>,
retry_on_401: bool,
extra_headers: &[(String, String)],
) -> Result<Vec<u8>> {
let ctl = self.derive_timeout_token(DEFAULT_JSON_TIMEOUT_MS, signal);
self.compliance_execute_bytes_inner(
method,
path,
body,
ctl.as_ref(),
retry_on_401,
extra_headers,
false,
)
.await
}
#[allow(clippy::too_many_arguments)]
fn compliance_execute_bytes_inner<'a>(
&'a self,
method: reqwest::Method,
path: &'a str,
body: Option<&'a str>,
signal: Option<&'a CancellationToken>,
retry_on_401: bool,
extra_headers: &'a [(String, String)],
retried: bool,
) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'a>> {
Box::pin(async move {
let token = self.ensure_token(signal.cloned()).await?;
let url = self.compliance_url(path);
let mut headers: Vec<(reqwest::header::HeaderName, String)> = vec![
(reqwest::header::AUTHORIZATION, format!("Bearer {token}")),
(reqwest::header::ACCEPT, "application/json".to_string()),
];
if body.is_some() {
headers.push((
reqwest::header::CONTENT_TYPE,
"application/json".to_string(),
));
}
for (k, v) in extra_headers {
if let Ok(name) = reqwest::header::HeaderName::from_bytes(k.as_bytes()) {
headers.push((name, v.clone()));
}
}
let resp = self
.do_request(method.clone(), &url, &headers, body, signal)
.await?;
if resp.status().as_u16() == 401 && retry_on_401 && !retried {
drop(resp);
self.force_refresh(signal.cloned())
.await
.map_err(|e| Error::other(format!("unauthorized and refresh failed: {e}")))?;
return self
.compliance_execute_bytes_inner(
method,
path,
body,
signal,
retry_on_401,
extra_headers,
true,
)
.await;
}
if !resp.status().is_success() {
let status = resp.status().as_u16();
let retry_after = parse_retry_after(resp.headers());
let text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
return Err(Error::Http(parse_http_error_with_retry_after(
status,
&text,
retry_after,
)));
}
let bytes = resp
.bytes()
.await
.map_err(|e| Error::other(format!("{path}: read body: {e}")))?;
Ok(bytes.to_vec())
})
}
pub(crate) async fn compliance_public_read<T: DeserializeOwned>(
&self,
path: &str,
signal: Option<CancellationToken>,
) -> Result<T> {
let ctl = self.derive_timeout_token(DEFAULT_JSON_TIMEOUT_MS, signal);
let token = self.ensure_token(ctl.clone()).await.ok();
let url = self.compliance_url(path);
let mut headers: Vec<(reqwest::header::HeaderName, String)> =
vec![(reqwest::header::ACCEPT, "application/json".to_string())];
if let Some(t) = token.filter(|t| !t.is_empty()) {
headers.push((reqwest::header::AUTHORIZATION, format!("Bearer {t}")));
}
let resp = self
.do_request(reqwest::Method::GET, &url, &headers, None, ctl.as_ref())
.await?;
if !resp.status().is_success() {
let status = resp.status().as_u16();
let retry_after = parse_retry_after(resp.headers());
let text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
return Err(Error::Http(parse_http_error_with_retry_after(
status,
&text,
retry_after,
)));
}
let bytes = resp
.bytes()
.await
.map_err(|e| Error::other(format!("{path}: read body: {e}")))?;
if bytes.is_empty() {
return Err(Error::other(format!("{path}: empty response body")));
}
let env: ApiResponse<T> = serde_json::from_slice(&bytes)
.map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
if let Some(err) = env.business_error() {
return Err(err);
}
Ok(env.data)
}
}
fn classify_timestamp(status: &ComplianceTimestampVerificationStatus) -> PollDecision {
match status.as_str() {
ComplianceTimestampVerificationStatus::VERIFIED => PollDecision::Done,
ComplianceTimestampVerificationStatus::FAILED
| ComplianceTimestampVerificationStatus::LOCAL_VERIFY_FAILED => PollDecision::Failed,
_ => PollDecision::Continue,
}
}
fn classify_provider_status(status: &ComplianceProviderRequestStatus) -> PollDecision {
match status.as_str() {
ComplianceProviderRequestStatus::SUCCESS => PollDecision::Done,
ComplianceProviderRequestStatus::FAILED => PollDecision::Failed,
_ => PollDecision::Continue,
}
}
fn derive_last_info_timestamp(t: &TimestampToken) -> ComplianceErrorInfo {
let status = t.verification_status.as_str();
let message = t
.verification_error
.clone()
.filter(|s| !s.is_empty())
.unwrap_or_else(|| {
if status.is_empty() {
"compliance poll: last observed status (no detail)".to_string()
} else {
format!("last polled status: {status}")
}
});
last_info(message)
}
fn derive_last_info_provider(v: &ProviderRequestStatusView) -> ComplianceErrorInfo {
let status = v.status.as_str();
let message = if status.is_empty() {
"compliance poll: last observed status (no detail)".to_string()
} else {
format!("last polled status: {status}")
};
last_info(message)
}
fn last_info(message: String) -> ComplianceErrorInfo {
ComplianceErrorInfo {
code: 0,
message,
key: ComplianceErrorKey::UnknownComplianceError,
retryable: false,
terminal: false,
step_up_required: false,
}
}
struct QueryBuilder {
parts: Vec<String>,
}
impl QueryBuilder {
fn new(page: &PageRequest) -> Self {
let mut b = QueryBuilder { parts: Vec::new() };
b.add("pageNo", page.page_no.map(|v| v.to_string()).as_deref());
b.add("pageSize", page.page_size.map(|v| v.to_string()).as_deref());
b.add("sortBy", page.sort_by.as_deref());
if let Some(dir) = &page.sort_direction {
let s = match dir {
crate::shared::pagination::SortDirection::Asc => "asc",
crate::shared::pagination::SortDirection::Desc => "desc",
};
b.add("sortDirection", Some(s));
}
b
}
fn add(&mut self, key: &str, value: Option<&str>) {
if let Some(v) = value.filter(|s| !s.is_empty()) {
self.parts.push(format!("{}={}", key, urlencode(v)));
}
}
fn finish(self) -> String {
qstr(&self.parts)
}
}
fn qstr(parts: &[String]) -> String {
if parts.is_empty() {
String::new()
} else {
format!("?{}", parts.join("&"))
}
}
fn idempotency_header(opts: &ComplianceWriteOptions) -> Vec<(String, String)> {
match opts.idempotency_key.as_deref().filter(|s| !s.is_empty()) {
Some(k) => vec![("Idempotency-Key".to_string(), k.to_string())],
None => Vec::new(),
}
}
fn urlencode(s: &str) -> String {
crate::billing::entitlements::urlencoding(s)
}
fn parse_retry_after(headers: &reqwest::header::HeaderMap) -> i64 {
headers
.get(reqwest::header::RETRY_AFTER)
.and_then(|v| v.to_str().ok())
.and_then(|s| s.trim().parse::<i64>().ok())
.filter(|&s| s > 0)
.unwrap_or(0)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn query_builder_skips_empty_and_encodes() {
let page = PageRequest {
page_no: Some(2),
page_size: Some(20),
..Default::default()
};
let mut q = QueryBuilder::new(&page);
q.add("status", Some("DRAFT"));
q.add("createTimeStart", Some("2026-05-01 00:00:00"));
q.add("nope", None);
q.add("empty", Some(""));
let s = q.finish();
assert!(s.starts_with('?'));
assert!(s.contains("pageNo=2"));
assert!(s.contains("pageSize=20"));
assert!(s.contains("status=DRAFT"));
assert!(s.contains("createTimeStart=2026-05-01%2000%3A00%3A00"));
assert!(!s.contains("nope"));
assert!(!s.contains("empty"));
}
#[test]
fn query_builder_empty_is_blank() {
let q = QueryBuilder::new(&PageRequest::default());
assert_eq!(q.finish(), "");
}
#[test]
fn classify_timestamp_decisions() {
assert_eq!(
classify_timestamp(&ComplianceTimestampVerificationStatus::from("VERIFIED")),
PollDecision::Done
);
assert_eq!(
classify_timestamp(&ComplianceTimestampVerificationStatus::from("FAILED")),
PollDecision::Failed
);
assert_eq!(
classify_timestamp(&ComplianceTimestampVerificationStatus::from(
"LOCAL_VERIFY_FAILED"
)),
PollDecision::Failed
);
assert_eq!(
classify_timestamp(&ComplianceTimestampVerificationStatus::from("PENDING")),
PollDecision::Continue
);
assert_eq!(
classify_timestamp(&ComplianceTimestampVerificationStatus::from("WHATEVER")),
PollDecision::Continue
);
}
#[test]
fn classify_provider_decisions() {
assert_eq!(
classify_provider_status(&ComplianceProviderRequestStatus::from("SUCCESS")),
PollDecision::Done
);
assert_eq!(
classify_provider_status(&ComplianceProviderRequestStatus::from("FAILED")),
PollDecision::Failed
);
assert_eq!(
classify_provider_status(&ComplianceProviderRequestStatus::from("RETRYING")),
PollDecision::Continue
);
}
#[test]
fn idempotency_header_present_and_absent() {
let opts = ComplianceWriteOptions {
idempotency_key: Some("key-1".to_string()),
};
assert_eq!(
idempotency_header(&opts),
vec![("Idempotency-Key".to_string(), "key-1".to_string())]
);
assert!(idempotency_header(&ComplianceWriteOptions::default()).is_empty());
}
#[test]
fn seal_id_divergence_provider_string_vs_operation_i64() {
let pv: ProviderRequestStatusView = serde_json::from_str(
r#"{"id":1,"status":"PENDING","terminal":false,"retryable":false,"sealId":"SEAL-ABC"}"#,
)
.unwrap();
assert_eq!(pv.seal_id.as_deref(), Some("SEAL-ABC"));
let op: OperationDetail = serde_json::from_str(
r#"{"id":2,"operationId":"op-1","status":"running","terminal":false,"retryable":true,"attemptCount":1,"sealId":42,"createTime":"2026-05-01T00:00:00"}"#,
)
.unwrap();
assert_eq!(op.base.seal_id, Some(42));
let sa: SealApproval =
serde_json::from_str(r#"{"id":3,"status":"SUBMITTED","sealId":7}"#).unwrap();
assert_eq!(sa.seal_id, Some(7));
}
#[test]
fn operation_detail_and_page_item_independent_round_trip() {
let json = r#"{"id":5,"operationId":"op-x","status":"succeeded","terminal":true,"retryable":false,"attemptCount":3,"businessNo":"B1","createTime":"2026-05-01T01:02:03"}"#;
let item: OperationPageItem = serde_json::from_str(json).unwrap();
assert_eq!(item.base.operation_id, "op-x");
assert_eq!(item.base.business_no.as_deref(), Some("B1"));
let detail: OperationDetail = serde_json::from_str(json).unwrap();
assert_eq!(detail.base.attempt_count, 3);
let back = serde_json::to_value(&item).unwrap();
assert_eq!(back["operationId"], "op-x");
assert_eq!(back["attemptCount"], 3);
}
#[test]
fn evidence_asset_wire_round_trip() {
let json = r#"{"id":1,"evidenceNo":"EV-1","assetType":"CONTRACT","name":"x","hashAlgorithm":"sha256","contentHash":"abcd","digestSource":"CLIENT","privacyLevel":"private","status":"DRAFT"}"#;
let a: EvidenceAsset = serde_json::from_str(json).unwrap();
assert_eq!(a.evidence_no, "EV-1");
assert_eq!(a.asset_type.as_str(), "CONTRACT");
assert_eq!(a.hash_algorithm.as_str(), "sha256");
let back = serde_json::to_value(&a).unwrap();
assert_eq!(back["evidenceNo"], "EV-1");
assert_eq!(back["assetType"], "CONTRACT");
}
}