Struct MeowClient 

pub struct MeowClient { /* private fields */ }

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 MeowConfigBuilder::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 try_enqueue<PCB, CCB>( &self, task: PounceTask, progress_cb: PCB, complete_cb: CCB, ) -> Result<TaskId, MeowError>

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

Submits a transfer task to the internal scheduler 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.

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

Back-pressure semantics (why the try_ prefix)

Internally this method uses tokio::sync::mpsc::Sender::try_send to hand the Enqueue command to the scheduler worker, not send().await. That means:

• The await point in this function is used for task normalization (e.g. resolving upload breakpoints, building [InnerTask]), not for waiting on command-queue capacity.
• If the command queue is momentarily full (bursty enqueue under MeowConfig::command_queue_capacity), this method returns an immediate CommandSendFailed error instead of suspending the caller until a slot frees up.
• Other control APIs (Self::pause, Self::resume, Self::cancel, Self::snapshot) use send().await and do wait for queue capacity. Only enqueue is fail-fast.

Callers that want to batch-enqueue under burst load should either:

1. size MeowConfig::command_queue_capacity appropriately, or
2. retry on CommandSendFailed with their own back-off, or
3. rate-limit enqueue calls on the caller side.

The name explicitly carries try_ so this fail-fast behavior is visible at the call site. If a fully-awaiting variant is introduced later it should be named enqueue (without the try_ prefix).

Parameters

• task: Built by upload/download task builders.
• progress_cb: Per-task callback invoked with transfer progress.
• complete_cb: 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.
• try_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.
• CommandSendFailed if the scheduler command queue is full at the moment of submission (see back-pressure semantics above).
• Any runtime initialization errors from the executor.

Examples

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",
)
.build();

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

pub async fn enqueue_and_wait<PCB>( &self, task: PounceTask, progress_cb: PCB, ) -> Result<TaskOutcome, MeowError>

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

Enqueues a task and awaits until it reaches a terminal status.

Wraps Self::try_enqueue with an internal oneshot channel so callers do not have to write the channel + double-callback + single-send-guard boilerplate themselves.

Returns

• Ok(TaskOutcome) when the task reaches TransferStatus::Complete.
• Err(MeowError) carrying the underlying failure for TransferStatus::Failed.
• Err(MeowError) with code InnerErrorCode::TaskCanceled for TransferStatus::Canceled.

Progress

progress_cb receives every FileTransferRecord update, identical to the per-task progress callback in Self::try_enqueue.

Cancellation / timeout

Dropping the returned future does not cancel the underlying transfer; the task continues running in the executor. Use Self::cancel with the task id (obtainable from progress_cb’s record.task_id()) to abort an in-flight transfer.

To cap wall-clock waiting time, wrap this future:

let outcome = tokio::time::timeout(
    std::time::Duration::from_secs(60),
    client.enqueue_and_wait(task, |_| {}),
)
.await??;

Errors

In addition to the terminal-status errors above, propagates any error from Self::try_enqueue (e.g. ClientClosed, ParameterEmpty, CommandSendFailed).

Examples

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",
)
.build();

let outcome = client
    .enqueue_and_wait(task, |record| {
        println!(
            "task={} progress={:.2}",
            record.task_id(),
            record.progress()
        );
    })
    .await?;
println!("task {} complete, payload={:?}", outcome.task_id, outcome.payload);

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.

close is the terminal lifecycle operation for a MeowClient. After it succeeds, this client stays permanently closed; submit more work by constructing a new MeowClient and enqueueing tasks there.

After a successful close:

• New task and control operations on this client are rejected with ClientClosed.
• All known unfinished task groups (queued, paused, or active) receive a Paused progress notification through their task callback and all registered global listeners.
• In-flight transfers are cancelled and the scheduler state is cleared.
• Already submitted callback jobs are drained before returning.
• The internal scheduler thread is joined, which drops its Tokio runtime and releases SDK-owned background execution resources.

Paused is used for shutdown notifications rather than Canceled so callers can recreate a client later and re-enqueue the same logical transfer when they want to resume from available breakpoint state.

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. A successful close is not restartable.

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 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();

Trait Implementations

impl Debug for MeowClient

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

Formats the value using the given formatter.