Crate booru_rs 

booru-rs

An async Rust client for various booru image board APIs.

This library provides a unified interface for querying multiple booru sites including Danbooru, Gelbooru, Safebooru, and Rule34.

Features

• Type-safe API: Compile-time checks ensure you use the correct rating types for each booru
• Async/await: Built on tokio and reqwest for efficient async I/O
• Connection pooling: Shared HTTP client with automatic connection reuse
• Proper error handling: No panics, all errors are returned as Result types
• Common trait: Use the Post trait for generic code across booru sites
• Async streams: Paginate through results with async iterators
• Image downloads: Download images with progress tracking and concurrent downloads
• Automatic retries: Transient failures are retried with exponential backoff
• Rate limiting: Protect against API throttling
• Response caching: Reduce redundant API calls
• Tag validation: Catch common mistakes before making requests
• Tag autocomplete: Get tag suggestions as users type

Quick Start

The easiest way to get started is with the prelude:

use booru_rs::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let posts = DanbooruClient::builder()
        .tag("cat_ears")?
        .rating(DanbooruRating::General)
        .sort(Sort::Score)
        .limit(10)
        .build()
        .get()
        .await?;

    for post in posts {
        println!("Post {}: {:?}", post.id, post.file_url);
    }

    Ok(())
}

Supported Sites

Site	Client	Tag Limit	Auth Required
Danbooru	DanbooruClient	2	No
Gelbooru	GelbooruClient	Unlimited	Yes
Safebooru	SafebooruClient	Unlimited	No
Rule34	Rule34Client	Unlimited	Yes

Pagination with Async Streams

Use stream::PostStream to iterate through all results:

use booru_rs::prelude::*;

let mut stream = SafebooruClient::builder()
    .tag("landscape")?
    .limit(100)
    .into_post_stream()
    .max_posts(500);

while let Some(post) = stream.next().await {
    println!("Post #{}", post?.id);
}

Generic Code with the Post Trait

Use the Post trait to write code that works with any booru:

use booru_rs::prelude::*;
use booru_rs::model::Post;

fn print_post(post: &impl Post) {
    println!("#{}: {}x{}", post.id(), post.width(), post.height());
}

Re-exports

pub use autocomplete::Autocomplete;

pub use autocomplete::TagSuggestion;

pub use client::Client;

pub use client::ClientBuilder;

pub use client::DanbooruClient;

pub use client::GelbooruClient;

pub use client::Rule34Client;

pub use client::SafebooruClient;

pub use client::generic::Sort;

pub use error::BooruError;

pub use error::Result;

pub use model::Post;

Modules

autocomplete

Tag autocomplete for booru sites.

cache

Response caching for booru API requests.

client

Client implementations for various booru sites.

danbooru

Danbooru client and model types.

download

Image download utilities.

error

Error types for the booru-rs library.

gelbooru

Gelbooru client and model types.

model

Data models for booru API responses.

prelude

Convenient re-exports for common usage patterns.

ratelimit

Rate limiting for API requests.

retry

Retry logic with exponential backoff for transient failures.

rule34

Rule34 client and model types.

safebooru

Safebooru client and model types.

stream

Async stream utilities for paginated results.

validation

Tag validation for booru queries.