Skip to main content

ThunderstoreClient

Struct ThunderstoreClient 

Source
pub struct ThunderstoreClient { /* private fields */ }
Available on crate feature io only.
Expand description

An async client for a single Thunderstore community.

Build one with ThunderstoreClient::builder.

Implementations§

Source§

impl ThunderstoreClient

Source

pub fn builder() -> ThunderstoreClientBuilder

Returns a builder for configuring a ThunderstoreClient.

cache_dir is the only required setting. Nothing is read, written, or sent over the network until a method such as get_manifest is awaited, so building is cheap and infallible apart from configuration validation.

§Examples
use thunderstore_engine::client::ThunderstoreClient;

let client = ThunderstoreClient::builder()
  .base_url("https://thunderstore.io")
  .community("valheim")
  .cache_dir("/var/cache/my-mod-manager")
  .build()
  .expect("base_url + community compose a valid index URL");

assert_eq!(client.base_url(), "https://thunderstore.io");
assert_eq!(
  client.package_index_url(),
  "https://thunderstore.io/c/valheim/api/v1/package/"
);
Source

pub fn package_index_url(&self) -> &str

The composed package-index URL this client will query.

Source

pub fn base_url(&self) -> &str

The Thunderstore host this client targets, with any trailing slash trimmed.

Source

pub fn cache_dir(&self) -> &Path

The cache directory this client reads from and writes to.

Source

pub async fn get_manifest(&self) -> Result<PackageIndex>

Retrieves the package index, loading from cache when it is fresh.

Performs a HEAD request and compares the server’s Last-Modified against the cached timestamp; if the cache is current it is loaded from disk, otherwise the index is downloaded and cached.

§Errors

A failed freshness check is not an error on its own: it is logged and a readable cache is served instead, so this succeeds offline once the index has been fetched at least once. Errors therefore mean no usable cache and a failed fetch:

Source

pub async fn cached_index(&self) -> Result<Option<PackageIndex>>

Reads the package index from the on-disk cache without any network request, however old the cache is.

Returns Ok(None) when nothing has been cached for this client’s index yet, so a caller can show the cached list at once and refresh later.

§Errors

A cache that exists but cannot be used is an error rather than None:

Source

pub async fn refresh_if_stale(&self) -> Result<Refreshed>

Downloads the package index only when the server has a newer one than the cache, for a caller that already shows cached_index.

Sends a HEAD and compares its Last-Modified with the cached marker. A current cache answers Refreshed::Unchanged without reading the cached index. A stale cache, or no cache, is replaced by a download and returned as Refreshed::Updated. A corrupt cache with a current marker still answers Unchanged, so a caller whose cached_index failed should call refresh_index instead.

§Errors

Unlike get_manifest, a failed freshness check is an error and never falls back to the cache, so the caller can tell the user the list may be out of date:

Source

pub async fn refresh_index(&self) -> Result<PackageIndex>

Forces a network refresh of the package index, bypassing the cache.

§Errors

The same set as get_manifest, minus the cache fallback: because this always goes to the network, any network failure is fatal here even when a perfectly good cached index exists.

Source

pub async fn download_files(&self, urls: HashMap<String, String>) -> Result<()>

Downloads multiple package archives concurrently into cache_dir/downloads.

Keys of urls are filenames and values are download URLs. Files that already exist are skipped. Concurrency is bounded by the configured download_concurrency, and each archive is bounded by the configured download_max_bytes. Each archive is written atomically (temp file + rename) after its full Content-Length is received. Individual download failures are logged and, if any occurred, surfaced as an aggregate error rather than silently ignored.

§Errors

Returns a single Error::Download naming each file that failed, with its reason, and how many files were attempted. This is all-or-nothing only in its reporting, not its effects: files that succeeded are still on disk, so a caller that retries should expect those to be skipped as already present. The underlying per-file causes are Error::Http, Error::SizeLimitExceeded (archive over download_max_bytes), Error::IncompleteDownload (body shorter than its Content-Length), and Error::Io.

Source

pub async fn create_profile_code(&self, payload: &[u8]) -> Result<String>

Uploads a profile-code payload and returns the server-issued key.

payload is sent verbatim as application/octet-stream; composing it (the #r2modman prefix and base64 body) belongs to crate::profile::portability. Transient failures are retried per the client’s RetryPolicy.

§Errors
  • Error::Http if the upload fails or the server returns a non-success status, after the retry policy is exhausted.
  • Error::SizeLimitExceeded if the response body is implausibly large for a profile key.
  • Error::Json if the response is not the expected { "key": ... } shape.
Source

pub async fn fetch_profile_code(&self, code: &str) -> Result<Vec<u8>>

Downloads a shared profile by its code, returning the raw response body.

Validating the #r2modman prefix and decoding the base64 body belongs to crate::profile::portability.

§Errors
  • Error::Config if code is empty or contains anything outside ASCII alphanumerics, -, and _. This is checked before any request, so a malformed code never reaches the network and can never be smuggled into the request path.
  • Error::Http if the download fails or the code is unknown to the server, after the retry policy is exhausted.
  • Error::SizeLimitExceeded if the shared profile exceeds the response cap.
Source

pub async fn get_readme( &self, owner: &str, name: &str, version: &str, ) -> Result<Option<String>>

Fetches the readme markdown for one version of a package, such as ("denikson", "BepInExPack_Valheim", "5.4.2202").

Returns Ok(None) when Thunderstore has no readme for that version, including when it does not know the package or version. Transient failures are retried per the client’s RetryPolicy.

§Errors
  • Error::Config if owner, name, or version is empty, . or .., or contains anything outside ASCII alphanumerics, -, _, and .. This is checked before any request.
  • Error::Http if the request fails or the server returns an error status other than 404, after the retry policy is exhausted.
  • Error::SizeLimitExceeded if the response body is implausibly large.
  • Error::Json if the response is not the expected { "markdown": ... } shape.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more