Struct InternetArchiveClient

Source

pub struct InternetArchiveClient { /* private fields */ }

Expand description

Typed async client for Internet Archive metadata, search, uploads, and downloads.

Implementations§

Source §

impl InternetArchiveClient

Source

pub fn builder() -> InternetArchiveClientBuilder

Starts building a client.

Source

pub fn new() -> Result<Self, InternetArchiveError>

Builds an unauthenticated client.

§Errors

Returns an error if the underlying HTTP clients cannot be built.

Source

pub fn with_auth(auth: Auth) -> Result<Self, InternetArchiveError>

Builds a client with explicit credentials.

§Errors

Returns an error if the underlying HTTP clients cannot be built.

Source

pub fn from_env() -> Result<Self, InternetArchiveError>

Builds a client from the standard Internet Archive environment variables.

§Errors

Returns an error if the environment variables are missing or if the underlying HTTP clients cannot be built.

Source

pub fn endpoint(&self) -> &Endpoint

Returns the configured endpoint roots.

Source

pub fn poll_options(&self) -> &PollOptions

Returns the configured workflow polling options.

Source

pub fn request_timeout(&self) -> Option<Duration>

Returns the request timeout.

Source

pub fn connect_timeout(&self) -> Option<Duration>

Returns the connect timeout.

Source

pub fn has_auth(&self) -> bool

Returns whether the client currently has credentials configured.

Source

pub async fn get_item( &self, identifier: &ItemIdentifier, ) -> Result<Item, InternetArchiveError>

Fetches a full item metadata record by identifier.

§Errors

Returns an error if the request fails or the item does not exist.

Source

pub async fn get_item_by_str( &self, identifier: impl AsRef<str>, ) -> Result<Item, InternetArchiveError>

Fetches a full item metadata record from a string identifier.

§Errors

Returns an error if the identifier is invalid, the request fails, or the item does not exist.

Source

pub async fn search( &self, query: &SearchQuery, ) -> Result<SearchResponse, InternetArchiveError>

Runs an advanced search query.

§Errors

Returns an error if the request fails or the response is invalid.

Source

pub async fn check_upload_limit( &self, identifier: &ItemIdentifier, ) -> Result<S3LimitCheck, InternetArchiveError>

Checks whether the S3 queue is currently over its documented upload limit.

§Errors

Returns an error if the client has no credentials or if the request fails.

Source

pub async fn apply_metadata_patch( &self, identifier: &ItemIdentifier, target: MetadataTarget, patch: &[PatchOperation], ) -> Result<MetadataWriteResponse, InternetArchiveError>

Applies a single-target metadata patch document.

§Errors

Returns an error if the client has no credentials, the request fails, or MDAPI rejects the patch.

Source

pub async fn apply_metadata_changes( &self, identifier: &ItemIdentifier, changes: &[MetadataChange], ) -> Result<MetadataWriteResponse, InternetArchiveError>

Applies an atomic multi-target metadata write.

§Errors

Returns an error if the client has no credentials, the request fails, or MDAPI rejects the patch document.

Source

pub async fn update_item_metadata( &self, identifier: &ItemIdentifier, metadata: &ItemMetadata, ) -> Result<MetadataWriteResponse, InternetArchiveError>

Updates the item-level metadata document by overlaying the provided keys onto the current metadata and diffing the result.

Missing keys in metadata are left untouched. Existing entries within list-valued fields (for example collection, subject, language) are also preserved; the update set is unioned into them. Use Self::apply_metadata_patch when you want exact JSON Patch behavior, including removing individual list entries or whole keys.

If there are no effective changes, the method returns a synthetic successful response with no task id and does not require authentication.

§Errors

Returns an error if the client has no credentials, the item cannot be fetched, or the patch cannot be applied.

Source

pub async fn upload_file( &self, identifier: &ItemIdentifier, spec: &UploadSpec, options: &UploadOptions, ) -> Result<(), InternetArchiveError>

Uploads a file to an existing item.

§Errors

Returns an error if the client has no credentials, the request fails, or IA rejects the upload.

Source

pub async fn upload_file_with_progress( &self, identifier: &ItemIdentifier, spec: &UploadSpec, options: &UploadOptions, progress: &ProgressBar, ) -> Result<(), InternetArchiveError>

Uploads a file to an existing item while updating an indicatif progress bar.

Available when the indicatif feature is enabled.

§Errors

Returns an error if the client has no credentials, the request fails, or IA rejects the upload.

Source

pub async fn create_item( &self, identifier: &ItemIdentifier, metadata: &ItemMetadata, spec: &UploadSpec, options: &UploadOptions, ) -> Result<(), InternetArchiveError>

Creates a new item by uploading the first file with automatic bucket creation headers and initial metadata.

§Errors

Returns an error if the identifier is not valid for IA-S3 bucket creation, the client has no credentials, the request fails, or IA rejects the upload.

Source

pub async fn create_item_with_progress( &self, identifier: &ItemIdentifier, metadata: &ItemMetadata, spec: &UploadSpec, options: &UploadOptions, progress: &ProgressBar, ) -> Result<(), InternetArchiveError>

Creates a new item while updating an indicatif progress bar for the initial upload step.

Available when the indicatif feature is enabled.

§Errors

Returns an error if the identifier is not valid for IA-S3 bucket creation, the client has no credentials, the request fails, or IA rejects the upload.

Source

pub async fn delete_file( &self, identifier: &ItemIdentifier, filename: &str, options: &DeleteOptions, ) -> Result<(), InternetArchiveError>

Deletes a file from an item through the S3-like API.

§Errors

Returns an error if the client has no credentials, the request fails, or IA rejects the delete.

Source

pub async fn make_dark( &self, identifier: &ItemIdentifier, comment: &str, ) -> Result<TaskSubmission, InternetArchiveError>

Submits a make_dark.php task to the Internet Archive catalog tasks API, hiding the item from public view.

Darkening makes the item unavailable to all users, including the uploader and IA’s metadata and search subsystems; the item’s metadata stub remains with is_dark: true, but /details/{id} returns 404 and search no longer indexes it. The caller must have uploaded the item or otherwise have edit permission. The comment argument is recorded in the task log; supply a short rationale (for example "live test cleanup").

§Errors

Returns an error if the client has no credentials, the request fails, or IA rejects the task submission (for example with 401 when the caller does not own the item).

Source

pub fn resolve_download( &self, identifier: &ItemIdentifier, filename: &str, ) -> Result<ResolvedDownload, InternetArchiveError>

Resolves the public download URL for a file.

§Errors

Returns an error if URL construction fails.

Source

pub async fn download_bytes( &self, identifier: &ItemIdentifier, filename: &str, ) -> Result<Bytes, InternetArchiveError>

Downloads a file into memory.

§Errors

Returns an error if the request fails.

Source

pub async fn download_bytes_with_progress( &self, identifier: &ItemIdentifier, filename: &str, progress: &ProgressBar, ) -> Result<Bytes, InternetArchiveError>

Downloads a file into memory while updating an indicatif progress bar.

Available when the indicatif feature is enabled.

§Errors

Returns an error if the request fails.

Source

pub async fn download_to_path( &self, identifier: &ItemIdentifier, filename: &str, path: impl AsRef<Path>, ) -> Result<(), InternetArchiveError>

Downloads a file to a local path.

§Errors

Returns an error if the request or local file write fails.

Source

pub async fn download_to_path_with_progress( &self, identifier: &ItemIdentifier, filename: &str, path: impl AsRef<Path>, progress: &ProgressBar, ) -> Result<(), InternetArchiveError>

Downloads a file to a local path while updating an indicatif progress bar.

Available when the indicatif feature is enabled.

§Errors

Returns an error if the request or local file write fails.

Source §

impl InternetArchiveClient

Source

pub async fn publish_item( &self, request: PublishRequest, ) -> Result<PublishOutcome, InternetArchiveError>

Creates a brand-new item and uploads all requested files.

§Errors

Returns an error if the identifier is not valid for IA-S3 bucket creation, the item already exists, the request has no files, or any network step fails.

Source