PeekAPI — Rust SDK

Rust SDK for PeekAPI. Thread-based buffered client with feature-gated middleware for Actix Web, Axum, and Rocket.

Install

# Cargo.toml
[dependencies]
peekapi = "0.1"

# Enable framework middleware (pick one or more)
# peekapi = { version = "0.1", features = ["actix"] }
# peekapi = { version = "0.1", features = ["axum-middleware"] }
# peekapi = { version = "0.1", features = ["rocket-fairing"] }

Quick Start

Actix Web

use peekapi::{PeekApiClient, Options};
use peekapi::middleware::actix::PeekApi;
use actix_web::{web, App, HttpServer, HttpResponse};
use std::sync::Arc;

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let client = PeekApiClient::new(Options::new("ak_live_xxx", "")).unwrap();

    HttpServer::new(move || {
        App::new()
            .wrap(PeekApi::new(Arc::clone(&client)))
            .route("/api/hello", web::get().to(|| async { HttpResponse::Ok().json(serde_json::json!({"message": "hello"})) }))
    })
    .bind("0.0.0.0:8080")?
    .run()
    .await
}

Axum

use peekapi::{PeekApiClient, Options};
use peekapi::middleware::axum::PeekApiLayer;
use axum::{Router, routing::get, Json};

#[tokio::main]
async fn main() {
    let client = PeekApiClient::new(Options::new("ak_live_xxx", "")).unwrap();

    let app = Router::new()
        .route("/api/hello", get(|| async { Json(serde_json::json!({"message": "hello"})) }))
        .layer(PeekApiLayer::new(client));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Rocket

use peekapi::{PeekApiClient, Options};
use peekapi::middleware::rocket::PeekApiFairing;
use rocket::{get, routes};

#[get("/api/hello")]
fn hello() -> &'static str {
    r#"{"message":"hello"}"#
}

#[rocket::main]
async fn main() {
    let client = PeekApiClient::new(Options::new("ak_live_xxx", "")).unwrap();

    rocket::build()
        .attach(PeekApiFairing::new(client))
        .mount("/", routes![hello])
        .launch()
        .await
        .unwrap();
}

Standalone Client

use peekapi::{PeekApiClient, Options, RequestEvent};

let client = PeekApiClient::new(Options::new("ak_live_xxx", "")).unwrap();

client.track(RequestEvent {
    method: "GET".into(),
    path: "/api/users".into(),
    status_code: 200,
    response_time_ms: 42.0,
    ..Default::default()
});

// Graceful shutdown (flushes remaining events, persists to disk)
client.shutdown();

Configuration

How It Works

1. Middleware intercepts every request/response
2. Captures method, path, status code, response time, request/response sizes, consumer ID
3. Events are buffered in memory and flushed in batches on a background thread
4. On network failure: exponential backoff with jitter, up to 5 retries
5. After max retries: events are persisted to a JSONL file on disk
6. On next startup: persisted events are recovered and re-sent
7. On shutdown: remaining buffer is flushed or persisted to disk

Consumer Identification

By default, consumers are identified by:

1. X-API-Key header — stored as-is
2. Authorization header — hashed with SHA-256 (stored as hash_<hex>)

Override with the identify_consumer option to use any header:

let mut opts = Options::new("your-api-key", "https://...");
opts.identify_consumer = Some(Box::new(|get_header| get_header("x-tenant-id")));
let client = PeekApiClient::new(opts).unwrap();

The callback receives a header-getter closure (&dyn Fn(&str) -> Option<String>) and should return an Option<String>.

Features

• Minimal dependencies — serde, serde_json, ureq, sha2 (framework deps are feature-gated)
• Background thread — dedicated flush thread with configurable interval and batch size
• Disk persistence — undelivered events saved to JSONL, recovered on restart
• Exponential backoff — with jitter on network failures
• SSRF protection — private IP blocking, HTTPS enforcement (HTTP only for localhost)
• Input sanitization — path (2048), method (16), consumer_id (256) truncation
• Per-event size limit — strips metadata first, drops if still too large (default 64KB)
• Feature-gated middleware — only compile the framework adapter you need

Feature Flags

Requirements

• Rust 2021 edition

Contributing

1. Fork & clone the repo
2. Run tests — cargo test
3. Lint — cargo clippy --all-features
4. Format — cargo fmt
5. Submit a PR

License

MIT