Skip to main content

cpa_plugin/store/
client.rs

1//! The store client (internal/pluginstore/github.go, direct.go,
2//! request_identity.go): registry, release and artifact downloads with manual
3//! redirects, per-hop store authentication and the GitHub rate limiter.
4
5use cpa_core::gostr::GoStr;
6use std::sync::Arc;
7use std::time::SystemTime;
8
9use bytes::Bytes;
10use futures_util::StreamExt;
11use futures_util::future::BoxFuture;
12use futures_util::stream::BoxStream;
13use sha2::{Digest, Sha256};
14
15use super::auth::{self, AuthConfig, Headers, ResolvedAuthConfig};
16use super::rate_limit::{GitHubRateLimiter, RateLimitError, github_rate_limit_key};
17use super::registry::{
18    Artifact, DEFAULT_REGISTRY_URL, INSTALL_TYPE_DIRECT, InstallPlan, Plugin, Registry, github_repository_parts,
19    normalize_install_plan, parse_registry, validate_artifact,
20};
21use super::url;
22use super::{REQUEST_KIND_ARTIFACT, REQUEST_KIND_METADATA, REQUEST_KIND_REGISTRY};
23use crate::go_struct;
24use crate::gojson;
25
26const USER_AGENT: &str = "CLIProxyAPI";
27const MAX_REDIRECTS: usize = 10;
28/// The most any store response may hold. Go reads registry, release and asset
29/// responses without a bound and direct artifacts up to their declared size; here a
30/// declared size can only lower this.
31pub const MAX_DOWNLOAD_BYTES: u64 = 256 << 20;
32
33/// One response from a [`Doer`]: status, headers (canonical keys) and the body.
34pub struct DoerResponse {
35    pub status: u16,
36    pub headers: Headers,
37    pub body: BoxStream<'static, Result<Bytes, String>>,
38}
39
40/// Go `httpfetch.Doer` as the store uses it: one GET without following redirects.
41/// The error is the transport's cause (Go's `url.Error.Err` text).
42pub trait Doer: Send + Sync {
43    fn get(&self, url: &str, headers: &Headers) -> BoxFuture<'_, Result<DoerResponse, String>>;
44}
45
46/// Why a store request failed: GitHub's rate limit (the routes answer 429), an install
47/// that would overwrite a loaded library (Go `ErrLoadedPluginLocked`, 409), or anything
48/// else.
49#[derive(Debug, Clone, PartialEq, Eq)]
50pub enum StoreError {
51    RateLimited(RateLimitError),
52    LoadedPluginLocked,
53    Other(String),
54}
55
56impl std::fmt::Display for StoreError {
57    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
58        match self {
59            Self::RateLimited(e) => e.fmt(f),
60            Self::LoadedPluginLocked => f.write_str(super::LOADED_PLUGIN_LOCKED),
61            Self::Other(e) => f.write_str(e),
62        }
63    }
64}
65
66impl From<String> for StoreError {
67    fn from(e: String) -> Self {
68        Self::Other(e)
69    }
70}
71
72impl From<RateLimitError> for StoreError {
73    fn from(e: RateLimitError) -> Self {
74        Self::RateLimited(e)
75    }
76}
77
78impl StoreError {
79    /// Go `fmt.Errorf("<prefix>: %w", err)`: wraps the text, keeps a rate limit
80    /// recognisable.
81    pub fn context(self, prefix: &str) -> Self {
82        match self {
83            Self::Other(e) => Self::Other(format!("{prefix}: {e}")),
84            // ponytail: Go's wrapped text is not kept; only the kind is ever read.
85            typed => typed,
86        }
87    }
88
89    pub fn rate_limit(&self) -> Option<&RateLimitError> {
90        match self {
91            Self::RateLimited(e) => Some(e),
92            _ => None,
93        }
94    }
95}
96
97go_struct! {
98    pub struct ReleaseAsset("pluginstore.ReleaseAsset") {
99        "url" => api_url: String,
100        "name" => name: String,
101        "browser_download_url" => browser_download_url: String,
102    }
103}
104
105go_struct! {
106    pub struct Release("pluginstore.Release") {
107        "tag_name" => tag_name: String,
108        "assets" => assets: Vec<ReleaseAsset>,
109    }
110}
111
112#[derive(Clone)]
113struct Prepared {
114    request_url: String,
115    kind: String,
116    headers: Headers,
117    authenticated: bool,
118}
119
120/// Go `pluginstore.Client`.
121#[derive(Clone)]
122pub struct Client {
123    pub http: Arc<dyn Doer>,
124    /// Distinguishes request state for different proxy/egress configurations.
125    pub network_scope: String,
126    pub rate_limiter: Option<Arc<GitHubRateLimiter>>,
127    pub registry_url: String,
128    pub user_agent: String,
129    pub auth: Vec<AuthConfig>,
130    pub resolved_auth: Vec<ResolvedAuthConfig>,
131    pub resolved_auth_expires_at: Option<SystemTime>,
132    prepared: Option<Prepared>,
133}
134
135impl Client {
136    pub fn new(http: Arc<dyn Doer>) -> Self {
137        Self {
138            http,
139            network_scope: String::new(),
140            rate_limiter: None,
141            registry_url: String::new(),
142            user_agent: String::new(),
143            auth: Vec::new(),
144            resolved_auth: Vec::new(),
145            resolved_auth_expires_at: None,
146            prepared: None,
147        }
148    }
149
150    fn limiter(&self) -> &GitHubRateLimiter {
151        match self.rate_limiter.as_deref() {
152            Some(limiter) => limiter,
153            None => GitHubRateLimiter::shared(),
154        }
155    }
156
157    /// Go `FetchRegistry`.
158    pub async fn fetch_registry(&self) -> Result<Registry, StoreError> {
159        let registry_url = match self.registry_url.trim() {
160            "" => DEFAULT_REGISTRY_URL,
161            u => u,
162        };
163        let data = self
164            .get(registry_url, "application/json", REQUEST_KIND_REGISTRY, 0)
165            .await?;
166        Ok(parse_registry(&data)?)
167    }
168
169    fn release_url(plugin: &Plugin, tail: &str) -> Result<String, String> {
170        let (owner, repo) = github_repository_parts(&plugin.repository)?;
171        Ok(format!(
172            "https://api.github.com/repos/{}/{}/releases/{tail}",
173            url::path_escape(&owner),
174            url::path_escape(&repo)
175        ))
176    }
177
178    async fn fetch_release(&self, release_url: &str) -> Result<Release, StoreError> {
179        let data = self
180            .get(release_url, "application/vnd.github+json", REQUEST_KIND_METADATA, 0)
181            .await?;
182        gojson::from_slice(&data).map_err(|e| StoreError::Other(format!("decode release: {e}")))
183    }
184
185    /// Go `FetchLatestRelease`.
186    pub async fn fetch_latest_release(&self, plugin: &Plugin) -> Result<Release, StoreError> {
187        let release_url = Self::release_url(plugin, "latest")?;
188        self.fetch_release(&release_url).await
189    }
190
191    /// Go `FetchReleaseByTag`.
192    pub async fn fetch_release_by_tag(&self, plugin: &Plugin, tag: &str) -> Result<Release, StoreError> {
193        github_repository_parts(&plugin.repository)?;
194        let tag = tag.trim();
195        if tag.is_empty() {
196            return Err(StoreError::Other("release tag is required".into()));
197        }
198        let release_url = Self::release_url(plugin, &format!("tags/{}", url::path_escape(tag)))?;
199        self.fetch_release(&release_url).await
200    }
201
202    /// Go `PrepareLatestRelease`: binds the cache key and the first release request
203    /// to one credential snapshot.
204    pub fn prepare_latest_release(&self, plugin: &Plugin) -> Result<(Client, String), StoreError> {
205        let request_url = Self::release_url(plugin, "latest")?;
206        let (headers, authenticated) = self.auth_headers(&request_url, REQUEST_KIND_METADATA)?;
207        let key = format!(
208            "{}/{}",
209            request_url.go_lower(),
210            request_identity(&self.network_scope, &headers, authenticated)
211        );
212        let mut client = self.clone();
213        client.prepared = Some(Prepared {
214            request_url,
215            kind: REQUEST_KIND_METADATA.into(),
216            headers,
217            authenticated,
218        });
219        Ok((client, key))
220    }
221
222    /// Go `LatestReleaseCacheKey`.
223    pub fn latest_release_cache_key(&self, plugin: &Plugin) -> Result<String, StoreError> {
224        self.prepare_latest_release(plugin).map(|(_, key)| key)
225    }
226
227    /// Go `DownloadAsset`: the browser URL, or the API URL when there is none or
228    /// credentials apply to it.
229    pub async fn download_asset(&self, asset: &ReleaseAsset) -> Result<Bytes, StoreError> {
230        let api_url = asset.api_url.trim();
231        let mut download_url = asset.browser_download_url.trim();
232        if (download_url.is_empty() || self.release_asset_api_authenticated(api_url)) && !api_url.is_empty() {
233            download_url = api_url;
234        }
235        if download_url.is_empty() {
236            return Err(StoreError::Other(format!(
237                "asset {} missing download url",
238                cpa_common::gostr::quote(&asset.name)
239            )));
240        }
241        self.get(download_url, "application/octet-stream", REQUEST_KIND_ARTIFACT, 0)
242            .await
243    }
244
245    fn release_asset_api_authenticated(&self, api_url: &str) -> bool {
246        if api_url.is_empty() {
247            return false;
248        }
249        match auth::matching_resolved_auth_config(&self.resolved_auth, api_url, REQUEST_KIND_ARTIFACT) {
250            Some(item) => auth::resolved_auth_configured(item),
251            None => auth::auth_configured(&self.auth, api_url, REQUEST_KIND_ARTIFACT),
252        }
253    }
254
255    /// Go `DownloadArtifact`: bounded by the declared size.
256    pub async fn download_artifact(&self, artifact: &Artifact) -> Result<Bytes, StoreError> {
257        let artifact = normalize_install_plan(&InstallPlan {
258            install_type: INSTALL_TYPE_DIRECT.into(),
259            artifacts: vec![artifact.clone()],
260        })
261        .artifacts
262        .remove(0);
263        validate_artifact(&artifact)?;
264        let max = artifact.size.max(0) as u64;
265        let data = self
266            .get(&artifact.url, "application/octet-stream", REQUEST_KIND_ARTIFACT, max)
267            .await?;
268        if max > 0 && data.len() as u64 > max {
269            return Err(StoreError::Other("artifact exceeds declared size".into()));
270        }
271        Ok(data)
272    }
273
274    /// Go `authHeaders`: the URL checked, then the prepared or freshly applied
275    /// credentials for it.
276    fn auth_headers(&self, request_url: &str, kind: &str) -> Result<(Headers, bool), String> {
277        auth::validate_request_url(&self.auth, request_url, kind)?;
278        auth::validate_resolved_auth_expiry(
279            &self.resolved_auth,
280            self.resolved_auth_expires_at,
281            SystemTime::now(),
282            request_url,
283            kind,
284        )?;
285        if let Some(prepared) = &self.prepared
286            && prepared.request_url == request_url
287            && prepared.kind == kind
288        {
289            return Ok((prepared.headers.clone(), prepared.authenticated));
290        }
291        let mut headers = Headers::new();
292        let authenticated = auth::apply_auth(&mut headers, &self.resolved_auth, &self.auth, request_url, kind)?;
293        Ok((headers, authenticated))
294    }
295
296    /// Go `get`: follows up to ten redirects itself, authenticating each hop on its
297    /// own URL; GitHub API hops go through the rate limiter.
298    pub(super) async fn get(
299        &self,
300        request_url: &str,
301        accept: &str,
302        kind: &str,
303        max_size: u64,
304    ) -> Result<Bytes, StoreError> {
305        let mut current = request_url.trim().to_owned();
306        let limiter = self.limiter();
307        let mut redirects = 0;
308        loop {
309            let (mut headers, authenticated) = self.auth_headers(&current, kind)?;
310            let rate_key = github_rate_limit_key(&current, &self.network_scope, &headers, authenticated);
311            limiter.check(&rate_key)?;
312            if !headers.contains_key("Accept") {
313                headers.insert("Accept".into(), vec![accept.into()]);
314            }
315            if !headers.contains_key("User-Agent") {
316                let ua = match self.user_agent.trim() {
317                    "" => USER_AGENT,
318                    ua => ua,
319                };
320                headers.insert("User-Agent".into(), vec![ua.into()]);
321            }
322            let response = self.http.get(&current, &headers).await;
323            if authenticated {
324                headers.clear();
325            }
326            let response = response.map_err(|cause| request_error(&current, &cause))?;
327            if matches!(response.status, 301 | 302 | 303 | 307 | 308) {
328                let _ = limiter.observe(&rate_key, response.status, &response.headers, None);
329                let next = redirect_url(&response.headers, &current)?;
330                if redirects >= MAX_REDIRECTS {
331                    return Err(StoreError::Other(format!("stopped after {MAX_REDIRECTS} redirects")));
332                }
333                redirects += 1;
334                current = next;
335                continue;
336            }
337            return read_response(response, max_size, authenticated, limiter, &rate_key).await;
338        }
339    }
340}
341
342/// Go `pluginStoreRedirectURL`.
343fn redirect_url(headers: &Headers, request_url: &str) -> Result<String, String> {
344    let location = headers
345        .get("Location")
346        .and_then(|v| v.first())
347        .map(|v| v.trim().to_owned())
348        .unwrap_or_default();
349    if location.is_empty() {
350        return Err("redirect missing Location header".into());
351    }
352    let base = url::parse_err(request_url).map_err(|e| format!("parse redirect base: {e}"))?;
353    let next = url::resolve(&base, &location).map_err(|e| format!("parse redirect location: {e}"))?;
354    if next.scheme.is_empty() || next.host.is_empty() {
355        return Err("redirect location is not absolute".into());
356    }
357    Ok(url::string(&next))
358}
359
360/// Go `readPluginStoreResponse`.
361async fn read_response(
362    response: DoerResponse,
363    max_size: u64,
364    authenticated: bool,
365    limiter: &GitHubRateLimiter,
366    rate_key: &str,
367) -> Result<Bytes, StoreError> {
368    let DoerResponse {
369        status,
370        headers,
371        mut body,
372    } = response;
373    if !(200..300).contains(&status) {
374        limiter.observe(rate_key, status, &headers, None)?;
375        if authenticated && (rate_key.is_empty() || status != 403) {
376            return Err(StoreError::Other(format!("unexpected status {status}")));
377        }
378        let mut text = Vec::new();
379        while text.len() < 4096 {
380            match body.next().await {
381                Some(Ok(chunk)) => text.extend_from_slice(&chunk[..chunk.len().min(4096 - text.len())]),
382                _ => break,
383            }
384        }
385        limiter.observe(rate_key, status, &headers, Some(&text))?;
386        if authenticated {
387            return Err(StoreError::Other(format!("unexpected status {status}")));
388        }
389        return Err(StoreError::Other(format!(
390            "unexpected status {status}: {}",
391            String::from_utf8_lossy(&text).trim()
392        )));
393    }
394    let _ = limiter.observe(rate_key, status, &headers, None);
395    let max_size = match max_size {
396        0 => MAX_DOWNLOAD_BYTES,
397        declared => declared.min(MAX_DOWNLOAD_BYTES),
398    };
399    let limit = max_size + 1;
400    let mut data = bytes::BytesMut::new();
401    while (data.len() as u64) < limit {
402        match body.next().await {
403            Some(Ok(chunk)) => {
404                let room = (limit - data.len() as u64).min(chunk.len() as u64) as usize;
405                data.extend_from_slice(&chunk[..room]);
406            }
407            Some(Err(e)) => return Err(StoreError::Other(format!("read response: {e}"))),
408            None => break,
409        }
410    }
411    if data.len() as u64 > max_size {
412        return Err(StoreError::Other(format!(
413            "response exceeds maximum allowed size of {max_size} bytes"
414        )));
415    }
416    Ok(data.freeze())
417}
418
419/// Go `pluginStoreRequestError`: the URL without user info, query or fragment.
420fn request_error(request_url: &str, cause: &str) -> String {
421    let safe = match url::parse(request_url.trim()) {
422        Some(mut u) if !u.scheme.is_empty() && !u.host.is_empty() => {
423            u.has_user = false;
424            u.raw_query.clear();
425            u.force_query = false;
426            u.fragment.clear();
427            url::string(&u)
428        }
429        _ => "plugin store url".into(),
430    };
431    format!("request {safe} failed: {cause}")
432}
433
434/// Go `requestIdentity`: SHA-256 of the network scope, whether credentials apply,
435/// and (if so) the headers as `Header.Write` renders them.
436pub(super) fn request_identity(network_scope: &str, headers: &Headers, authenticated: bool) -> String {
437    let mut hash = Sha256::new();
438    hash.update(format!("{network_scope}\x00{authenticated}\x00").as_bytes());
439    if authenticated {
440        for (name, values) in headers {
441            for value in values {
442                let value = value.replace(['\n', '\r'], " ");
443                hash.update(format!("{name}: {}\r\n", value.trim_matches([' ', '\t'])).as_bytes());
444            }
445        }
446    }
447    hash.finalize().iter().map(|b| format!("{b:02x}")).collect()
448}
449
450/// Go `SelectReleaseAssets`: the platform archive and `checksums.txt`.
451pub fn select_release_assets(
452    release: &Release,
453    id: &str,
454    version: &str,
455    goos: &str,
456    goarch: &str,
457) -> Result<(ReleaseAsset, ReleaseAsset), String> {
458    let archive_name = archive_name(id, version, goos, goarch);
459    let mut archive = None;
460    let mut checksums = None;
461    for asset in &release.assets {
462        match asset.name.trim() {
463            n if n == archive_name => archive = Some(asset.clone()),
464            "checksums.txt" => checksums = Some(asset.clone()),
465            _ => {}
466        }
467    }
468    let archive = archive
469        .filter(|a| !a.name.trim().is_empty())
470        .ok_or_else(|| format!("release asset {archive_name} not found"))?;
471    let checksums = checksums
472        .filter(|a| !a.name.trim().is_empty())
473        .ok_or_else(|| "release asset checksums.txt not found".to_owned())?;
474    Ok((archive, checksums))
475}
476
477/// Go `ArchiveName`: `{id}_{version}_{goos}_{goarch}.zip`.
478pub fn archive_name(id: &str, version: &str, goos: &str, goarch: &str) -> String {
479    format!("{}_{}_{}_{}.zip", id.trim(), version.trim(), goos.trim(), goarch.trim())
480}
481
482#[cfg(test)]
483mod tests {
484    use super::*;
485
486    /// An endless 200 response; nothing leaves the process.
487    struct Endless;
488
489    impl Doer for Endless {
490        fn get(&self, _: &str, _: &Headers) -> BoxFuture<'_, Result<DoerResponse, String>> {
491            Box::pin(async {
492                let chunk = Bytes::from(vec![b'x'; 1 << 20]);
493                Ok(DoerResponse {
494                    status: 200,
495                    headers: Headers::new(),
496                    body: futures_util::stream::repeat(Ok(chunk)).boxed(),
497                })
498            })
499        }
500    }
501
502    #[tokio::test]
503    async fn downloads_stop_at_the_ceiling() {
504        let mut client = Client::new(Arc::new(Endless));
505        client.registry_url = "https://registry.example.invalid/plugins.json".into();
506        let err = client.fetch_registry().await.unwrap_err();
507        assert_eq!(
508            err.to_string(),
509            format!("response exceeds maximum allowed size of {MAX_DOWNLOAD_BYTES} bytes")
510        );
511        // A declared size lowers the ceiling; one above it does not raise it.
512        let url = "https://cdn.example.invalid/p.zip";
513        let err = client
514            .get(url, "application/octet-stream", REQUEST_KIND_ARTIFACT, 10)
515            .await
516            .unwrap_err();
517        assert_eq!(err.to_string(), "response exceeds maximum allowed size of 10 bytes");
518        let err = client
519            .get(url, "application/octet-stream", REQUEST_KIND_ARTIFACT, u64::MAX / 2)
520            .await
521            .unwrap_err();
522        assert_eq!(
523            err.to_string(),
524            format!("response exceeds maximum allowed size of {MAX_DOWNLOAD_BYTES} bytes")
525        );
526    }
527}