nylas-core

Core HTTP client and infrastructure for the Nylas API v3.

This crate provides the low-level HTTP client, pagination, error handling, and resilience patterns used by the Nylas Rust SDK.

Features

• ✅ Async HTTP client with automatic retries
• ✅ Circuit breaker pattern for resilience
• ✅ Exponential backoff with jitter
• ✅ Configurable timeouts
• ✅ Rate limit detection and handling
• ✅ Automatic pagination
• ✅ Zero-copy downloads with bytes::Bytes
• ✅ Connection pooling
• ✅ Streaming support

Usage

Add this to your Cargo.toml:

[dependencies]
nylas-core = "0.1"
tokio = { version = "1.35", features = ["full"] }

Example

use nylas_core::http::{HttpClient, HttpConfig};
use nylas_core::resilience::{CircuitBreaker, RetryPolicy};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create HTTP client
    let config = HttpConfig::builder("api_key")
        .timeout(std::time::Duration::from_secs(30))
        .build()?;

    let client = HttpClient::new(config)?;

    // Use circuit breaker for resilience
    let breaker = CircuitBreaker::new(Default::default());

    let result = breaker.call(|| async {
        client.get("/v3/grants").await
    }).await?;

    Ok(())
}

Resilience Features

Circuit Breaker

Prevents cascading failures by failing fast when a service is degraded:

use nylas_core::resilience::{CircuitBreaker, CircuitBreakerConfig};
use std::time::Duration;

let config = CircuitBreakerConfig {
    failure_threshold: 5,
    success_threshold: 2,
    timeout: Duration::from_secs(60),
};

let breaker = CircuitBreaker::new(config);

// Circuit opens after 5 failures, closes after 2 successes
let result = breaker.call(|| async {
    // Your API call
    Ok::<_, std::io::Error>(())
}).await?;

Retry with Exponential Backoff

Automatically retries failed requests with intelligent backoff:

use nylas_core::resilience::RetryPolicy;
use std::time::Duration;

let policy = RetryPolicy::builder()
    .max_attempts(5)
    .initial_backoff(Duration::from_millis(100))
    .max_backoff(Duration::from_secs(10))
    .multiplier(2.0)
    .jitter(true)  // Prevents thundering herd
    .build();

Timeouts

Configurable timeouts for all operations:

use nylas_core::resilience::with_timeout;
use std::time::Duration;

let result = with_timeout(Duration::from_secs(5), async {
    // Your operation
    Ok::<_, std::io::Error>(())
}).await?;

Pagination

Automatic pagination for list operations:

use nylas_core::pagination::PageIterator;

let mut pages = PageIterator::new(
    client,
    "/v3/grants/grant_123/messages",
    None
);

while let Some(page) = pages.next_page().await? {
    for message in page.data {
        println!("Message: {:?}", message);
    }
}

Performance

• Zero-copy downloads using bytes::Bytes
• HTTP/2 connection pooling via reqwest
• Streaming support for large datasets
• Optimized serialization/deserialization

Testing

Comprehensive test coverage:

• Unit tests for all modules
• Property-based tests with proptest
• Chaos testing for resilience validation
• Benchmarks for performance critical paths

Documentation

• API Documentation
• Nylas API v3 Docs
• Main SDK Repository

License

MIT