pub struct Client { /* private fields */ }Expand description
Client is the cleanlib-client HTTP transport handle. Cheap to clone;
share across verbs in the same process.
Implementations§
Source§impl Client
impl Client
Sourcepub fn from_config(config: &Config) -> Result<Self, CleanLibraryError>
pub fn from_config(config: &Config) -> Result<Self, CleanLibraryError>
Construct from a loaded Config. TLS required for non-localhost
endpoints. Returns TlsRequired for http:// on remote hosts.
Sourcepub fn new(
endpoint: &str,
api_key: Option<String>,
) -> Result<Self, CleanLibraryError>
pub fn new( endpoint: &str, api_key: Option<String>, ) -> Result<Self, CleanLibraryError>
Construct with explicit endpoint + api_key. Intended for integration
tests + ad-hoc invocations (e.g., CLI --endpoint= flag future).
Sourcepub async fn verify_attestation(
&self,
verdict: &Verdict,
) -> Result<(), CleanLibraryError>
pub async fn verify_attestation( &self, verdict: &Verdict, ) -> Result<(), CleanLibraryError>
Cosign gate 3 (Q6=a): verify a Verdict’s signed attestation.
Q14 (capability parity, not policy) — this is opt-in. Nothing else in
Client calls this; a caller that never invokes it sees no behavior
change. Returns Err(AttestationInvalid { reason_code: "ATTESTATION_ABSENT", .. }) when the verdict carries no attestation
at all (distinct from a present-but-invalid one) so callers can tell
“nothing to verify” apart from “verification failed”.
Post gate-3 redesign (2026-09-13, BD-ratified per Jira CLEANLIB-379
comment 804236): verifies against PinnedKeyMap — a compiled-in,
fail-closed key set — NOT a /v1/pubkeys fetch. See
crate::attestation_verify’s module doc for why the earlier
fetch-by-key_id design (PR #536) was architecturally circular and
got redesigned before any release shipped it as a default. No lazy
network object to build here anymore — PinnedKeyMap::default() is
a cheap, synchronous, in-memory construction.
Sourcepub async fn fetch_verdict(
&self,
ecosystem: &str,
package: &str,
version: &str,
) -> Result<Verdict, CleanLibraryError>
pub async fn fetch_verdict( &self, ecosystem: &str, package: &str, version: &str, ) -> Result<Verdict, CleanLibraryError>
Fetch a single verdict per App Rev 4 §9.3 +
GET /v1/customer/verdicts/{ecosystem}/{package}/{version}.
Sourcepub async fn scan(
&self,
req: &ScanRequest,
) -> Result<ScanResponse, CleanLibraryError>
pub async fn scan( &self, req: &ScanRequest, ) -> Result<ScanResponse, CleanLibraryError>
Submit a packages + optional-policy request to
POST /v1/scan — batch-resolve verdicts for a set of packages against
the customer’s active policy. Used by cleanlib scan. The App resolves
each package independently (partial-success: a per-package miss lands as
ScanResult.error, not a whole-batch failure), so the caller derives
the gating decision per ScanResult.verdict and aggregates the exit
code (commands::scan).
Distinct endpoint from Self::policy_preview: /v1/scan needs no
policy_yaml. Routing scan through /v1/policy/preview produced a
422 missing field policy_yaml, and the old PolicyPreviewResponse
({decisions}, #[serde(default)]) silently parsed the App’s
{results} body into an empty vec → scan_exit_code(&[]) == 0, a
fail-open on the security gate. Both are closed here.
Sourcepub async fn policy_preview(
&self,
req: &PolicyPreviewRequest,
) -> Result<PolicyPreviewResponse, CleanLibraryError>
pub async fn policy_preview( &self, req: &PolicyPreviewRequest, ) -> Result<PolicyPreviewResponse, CleanLibraryError>
POST /v1/policy/preview. Used by cleanlib policy preview (with an
explicit candidate policy override). NOTE: cleanlib scan uses
Self::scan (/v1/scan), NOT this endpoint.
CLEANLIB-305 DX-fix: corrected from /v1/customer/policy/preview
(which 404s) to /v1/policy/preview (which the App mounts via
verbs_router). Same class of bug as the cycle-14 /v1/audit
fix (see audit below): the /customer/ prefix is used only by
customer_verdicts_router (/v1/customer/verdicts/*); the
cycle-6 verb surface (scan, audit, policy/preview,
risk-accept, fetch/*) mounts flat under /v1.
Sourcepub async fn fetch_artifact(
&self,
ecosystem: &str,
package: &str,
version: &str,
) -> Result<Vec<u8>, CleanLibraryError>
pub async fn fetch_artifact( &self, ecosystem: &str, package: &str, version: &str, ) -> Result<Vec<u8>, CleanLibraryError>
Fetch the raw artifact bytes for (ecosystem, package, version) via
App’s unified catalog-proxy GET /v1/fetch/{ecosystem}/{package}/{version}
(CLEANLIB-302 / CLEANLIB-368). Returns owned Vec<u8> — caller decides
write target. Emits decision + reason headers to stderr for visibility
(binary stdout stays clean).
CLEANLIB-368 route pivot: prior cycles built per-ecosystem registry
paths (/npm/<pkg>/-/<pkg>-<ver>.tgz, /go/<pkg>/@v/<ver>.zip, …)
against the App’s cycle-3 §C.8 nested per-eco routers. Those paths are
legacy registry-mimic shapes that never surfaced the CLEANLIB-302 audit
row (gcs_hit / gcs_object_path / bytes_served) and hard-coded
pypi wheel-variant assumptions that diverge from the real serve path.
The App unifies both under verbs_router at /v1/fetch/* — that is
now the sole client-side route.
Sourcepub async fn get_remediation(
&self,
ecosystem: &str,
package: &str,
) -> Result<RemediationOutcome, CleanLibraryError>
pub async fn get_remediation( &self, ecosystem: &str, package: &str, ) -> Result<RemediationOutcome, CleanLibraryError>
CLEANLIB-733 / step-4 Rust remediation client — fetch the sparse
remediation composite via the cleanapp CUSTOMER-BOUNDARY FACADE
(GET /v1/customer/remediation/{eco}/{pkg}, the same customer key that
opens the verdict surface). Sister of the sdk-py / sdk-js / sdk-go
HttpRemediationClient.
Status mapping mirrors the other SDKs: 404 → RemediationOutcome::NotInSubstrate
(a true, final “no remediation data” answer — never conflated with a
transient, the [Degr≡Real] guard the facade 404-passthrough fix restored),
5xx/transport → RemediationOutcome::Transient, 2xx →
RemediationOutcome::Present. Internal/producer-bearer callers hit the
direct enrich host — construct the Client with that endpoint and use
Self::get_remediation_direct. Scoped npm packages (@scope/name) are
percent-encoded to a single %2F segment (CLEANLIB-737 guard; see
urlencode).
Sourcepub async fn get_remediation_direct(
&self,
ecosystem: &str,
package: &str,
) -> Result<RemediationOutcome, CleanLibraryError>
pub async fn get_remediation_direct( &self, ecosystem: &str, package: &str, ) -> Result<RemediationOutcome, CleanLibraryError>
Direct-mode remediation for internal/producer-bearer callers: hits the
pre-facade GET /api/v1/remediation/{eco}/{pkg} path on the configured
(enrich-host) endpoint. Preserves the direct path per the un-park item-3.
Sourcepub async fn fetch_artifact_stream<W>(
&self,
ecosystem: &str,
package: &str,
version: &str,
writer: &mut W,
) -> Result<u64, CleanLibraryError>where
W: AsyncWrite + Unpin,
pub async fn fetch_artifact_stream<W>(
&self,
ecosystem: &str,
package: &str,
version: &str,
writer: &mut W,
) -> Result<u64, CleanLibraryError>where
W: AsyncWrite + Unpin,
Streaming variant of Self::fetch_artifact — writes chunks to
writer without buffering the full body in memory. Per Client Rev 2
amendment §9.4 cycle-4 §D.5 streaming substrate. Returns total bytes
written. Decision + reason headers surface to stderr before stream.
Hits the same unified /v1/fetch/{ecosystem}/{package}/{version}
proxy as Self::fetch_artifact — see the CLEANLIB-368 route pivot
note there.
Sourcepub async fn audit(
&self,
filters: AuditFilters<'_>,
) -> Result<AuditResponse, CleanLibraryError>
pub async fn audit( &self, filters: AuditFilters<'_>, ) -> Result<AuditResponse, CleanLibraryError>
Query customer audit log via GET /v1/audit with optional filters.
Caller passes already-validated filter values.
Cycle-14 DX-fix: corrected from /v1/customer/audit (which 404s) to
/v1/audit (which the App mounts via verbs_router). Verified live
against cleanapp.clnstrt.dev 2026-06-05 — direct probe returns 200
with {window, records, backend_status}.
CLEANLIB-813: takes an AuditFilters options struct rather than
positional Option<&str> params. The real server
(cleanlib-app/src/verbs.rs) accepts a fourth filter, until, that
this SDK never exposed — Go’s SDK already supports it. Adding it as
a 4th positional parameter would have been a breaking signature
change today AND set up another one the next time a filter is
added; an options struct absorbs until now and any future filter
later as a purely additive field, so every existing
..Default::default()-built call site keeps compiling. This IS a
breaking change for existing positional callers (Rust has no
source-compat path from 3 positional params to a struct) — the
migration cost is paid once, here, rather than deferred to the next
filter add.
pub async fn probe_auth(&self) -> Result<(), CleanLibraryError>
Sourcepub async fn send(
&self,
method: Method,
url: Url,
) -> Result<Response, CleanLibraryError>
pub async fn send( &self, method: Method, url: Url, ) -> Result<Response, CleanLibraryError>
Low-level: send a request with auth header. Used internally by verb methods; public for advanced consumers (future).
Sourcepub async fn get_ecosystems(&self) -> Result<Vec<String>, CleanLibraryError>
pub async fn get_ecosystems(&self) -> Result<Vec<String>, CleanLibraryError>
Fetch supported ecosystems from GET /health ecosystems_mounted field.