Struct MeowClient 

pub struct MeowClient { /* private fields */ }

Main entry point of the rusty-cat SDK.

MeowClient owns runtime state and provides high-level operations: enqueue, pause, resume, cancel, snapshot, and close.

Usage pattern

1. Create MeowConfig.
2. Construct MeowClient::new(config).
3. Build tasks with upload/download builders.
4. Call Self::enqueue and store returned TaskId.
5. Control task lifecycle with pause/resume/cancel.
6. Call Self::close during shutdown.

Implementations

impl MeowClient

pub fn new(config: MeowConfig) -> Self

Creates a new client with the provided configuration.

The internal executor is initialized lazily on first task operation.

Examples

use rusty_cat::api::{MeowClient, MeowConfig};

let config = MeowConfig::default();
let client = MeowClient::new(config);
let _ = client;

pub fn http_client(&self) -> Result<Client, MeowError>

Returns a reqwest::Client aligned with this client’s configuration.

• If MeowConfig::with_http_client injected a custom client, this returns its clone.
• Otherwise, this builds a new client from http_timeout and tcp_keepalive.

Errors

Returns MeowError with HttpClientBuildFailed when client creation fails.

Examples

use rusty_cat::api::{MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
let http = client.http_client()?;
let _ = http;

pub fn register_global_progress_listener<F>( &self, listener: F, ) -> Result<GlobalProgressListenerId, MeowError>

where F: Fn(FileTransferRecord) + Send + Sync + 'static,

Registers a global progress listener for all tasks.

Parameters

• listener: Callback receiving FileTransferRecord updates.

Returns

Returns a listener ID used by Self::unregister_global_progress_listener.

Usage rules

Keep callback execution short and panic-free. A heavy callback can slow down global event delivery.

Errors

Returns LockPoisoned when listener storage lock is poisoned.

Examples

use rusty_cat::api::{MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
let listener_id = client.register_global_progress_listener(|record| {
    println!("task={} progress={:.2}", record.task_id(), record.progress());
})?;
let _ = listener_id;

pub fn unregister_global_progress_listener( &self, id: GlobalProgressListenerId, ) -> Result<bool, MeowError>

Unregisters one previously registered global progress listener.

Returns Ok(false) when the ID does not exist.

Errors

Returns LockPoisoned when listener storage lock is poisoned.

Examples

use rusty_cat::api::{MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
let id = client.register_global_progress_listener(|_| {})?;
let removed = client.unregister_global_progress_listener(id)?;
assert!(removed);

pub fn clear_global_listener(&self) -> Result<(), MeowError>

Removes all registered global progress listeners.

Errors

Returns LockPoisoned when listener storage lock is poisoned.

Examples

use rusty_cat::api::{MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
client.clear_global_listener()?;

pub fn set_debug_log_listener( &self, listener: Option<DebugLogListener>, ) -> Result<(), DebugLogListenerError>

Sets or clears the global debug log listener.

• Pass Some(listener) to set/replace.
• Pass None to clear.

This affects all MeowClient instances in the current process.

Errors

Returns DebugLogListenerError when the internal global listener lock is poisoned.

Examples

use std::sync::Arc;
use rusty_cat::api::{Log, MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
client.set_debug_log_listener(Some(Arc::new(|log: Log| {
    println!("{log}");
})))?;

// Clear listener when no longer needed.
client.set_debug_log_listener(None)?;

impl MeowClient

pub async fn enqueue<PCB, CCB>( &self, task: PounceTask, progress_cb: PCB, complete_cb: Option<CCB>, ) -> Result<TaskId, MeowError>

where PCB: Fn(FileTransferRecord) + Send + Sync + 'static, CCB: Fn(TaskId, Option<String>) + Send + Sync + 'static,

Enqueues a transfer task and returns its TaskId.

The actual upload/download execution is dispatched to an internal worker system thread. This method only performs lightweight validation and submission, so it does not block the caller thread waiting for full transfer completion.

enqueue is also the recovery entrypoint after process restart. If the application was killed during a previous upload/download, restart your process and call enqueue again to resume that transfer workflow.

Parameters

• task: Built by upload/download task builders.
• progress_cb: Per-task callback invoked with transfer progress.
• complete_cb: Optional callback fired once when task reaches crate::transfer_status::TransferStatus::Complete. The second argument is provider-defined payload returned by upload protocol complete_upload; download tasks usually receive None.

Usage rules

• task must be non-empty (required path/name/url and valid upload size).
• Callback should be lightweight and non-blocking.
• Store returned task ID for subsequent task control operations.
• enqueue is asynchronous task submission, not synchronous transfer.
• For restart recovery, re-enqueue the same logical task (same upload/download target and compatible checkpoint context) so the runtime can continue from existing local/remote progress.

Errors

Returns:

• ClientClosed if the client was closed.
• ParameterEmpty if the task is invalid/empty.
• Any runtime initialization or enqueue errors from the executor.

Examples

use reqwest::Method;
use rusty_cat::api::{DownloadPounceBuilder, MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
let task = DownloadPounceBuilder::new(
    "example.bin",
    "./downloads/example.bin",
    1024 * 1024,
    "https://example.com/example.bin",
    Method::GET,
)
.build();

let task_id = client
    .enqueue(
        task,
        |record| {
            println!("status={:?} progress={:.2}", record.status(), record.progress());
        },
        Some(|task_id, payload| {
            println!("task {task_id} completed, payload={payload:?}");
        }),
    )
    .await?;
println!("enqueued task: {task_id}");

pub async fn pause(&self, task_id: TaskId) -> Result<(), MeowError>

Pauses a running or pending task by ID.

This API sends a control command to the internal scheduler worker thread. It does not execute transfer pause logic on the caller thread.

Usage rules

Call this with a valid task ID returned by Self::enqueue.

Errors

Returns ClientClosed, TaskNotFound, or state-transition errors.

Examples

use rusty_cat::api::{MeowClient, MeowConfig, TaskId};

let client = MeowClient::new(MeowConfig::default());
client.pause(task_id).await?;

pub async fn resume(&self, task_id: TaskId) -> Result<(), MeowError>

Resumes a previously paused task.

The same TaskId continues to identify the task after resume. The resume command is forwarded to the internal scheduler worker thread, so caller thread is not responsible for running transfer logic.

Errors

Returns ClientClosed, TaskNotFound, or InvalidTaskState.

Examples

use rusty_cat::api::{MeowClient, MeowConfig, TaskId};

let client = MeowClient::new(MeowConfig::default());
client.resume(task_id).await?;

pub async fn cancel(&self, task_id: TaskId) -> Result<(), MeowError>

Cancels a task by ID.

Cancellation is requested through the internal scheduler worker thread. Transfer cancellation execution happens in background runtime workers.

Usage rules

Cancellation is best-effort; protocol-specific cleanup may run.

Errors

Returns ClientClosed, TaskNotFound, or runtime cancellation errors.

Examples

use rusty_cat::api::{MeowClient, MeowConfig, TaskId};

let client = MeowClient::new(MeowConfig::default());
client.cancel(task_id).await?;

pub async fn snapshot(&self) -> Result<TransferSnapshot, MeowError>

Returns a snapshot of queue and active transfer groups.

Useful for diagnostics and external monitoring dashboards. Snapshot collection is coordinated by internal scheduler worker state.

Errors

Returns ClientClosed, runtime command delivery errors, or scheduler snapshot retrieval errors.

Examples

use rusty_cat::api::{MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
let snap = client.snapshot().await?;
println!("queued={}, active={}", snap.queued_groups, snap.active_groups);

pub async fn close(&self) -> Result<(), MeowError>

Closes this client and its underlying executor.

After a successful close:

• New task operations are rejected.
• Existing runtime resources are released.

Idempotency

Calling close more than once returns ClientClosed.

Retry behavior

If executor close fails, the closed flag is rolled back so caller can retry close.

Errors

Returns ClientClosed when already closed, or underlying executor close errors when shutdown is not completed.

Examples

use rusty_cat::api::{MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
client.close().await?;

pub async fn is_closed(&self) -> bool

Returns whether this client is currently closed.

Examples

use rusty_cat::api::{MeowClient, MeowConfig};

let client = MeowClient::new(MeowConfig::default());
let _closed = client.is_closed().await;

Trait Implementations

impl Clone for MeowClient

fn clone(&self) -> MeowClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MeowClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.