Struct CyclesClient 

pub struct CyclesClient { /* private fields */ }

Async client for the Cycles budget authority API.

The client is cheaply cloneable (uses Arc internally) and can be shared across tasks. It is Send + Sync.

Example

use runcycles::{CyclesClient, models::*};

let client = CyclesClient::builder("my-api-key", "http://localhost:7878")
    .tenant("acme")
    .build();

let guard = client.reserve(
    ReservationCreateRequest::builder()
        .subject(Subject { tenant: Some("acme".into()), ..Default::default() })
        .action(Action::new("llm.completion", "gpt-4o"))
        .estimate(Amount::usd_microcents(5000))
        .build()
).await?;

// ... do work ...

guard.commit(
    CommitRequest::builder()
        .actual(Amount::usd_microcents(3200))
        .build()
).await?;

Implementations

impl CyclesClient

pub fn builder( api_key: impl Into<String>, base_url: impl Into<String>, ) -> CyclesClientBuilder

Create a new client builder.

pub fn new(config: CyclesConfig) -> Self

Create a client from a pre-built config.

pub fn config(&self) -> &CyclesConfig

Access the client configuration.

pub async fn reserve( &self, req: ReservationCreateRequest, ) -> Result<ReservationGuard, Error>

Reserve budget and return an RAII guard.

The guard must be committed or released. If dropped without either, a best-effort release is attempted.

Returns Err(Error::BudgetExceeded) if the decision is Deny.

pub async fn create_reservation( &self, req: &ReservationCreateRequest, ) -> Result<ReservationCreateResponse, Error>

Create a budget reservation.

pub async fn create_reservation_with_metadata( &self, req: &ReservationCreateRequest, ) -> Result<ApiResponse<ReservationCreateResponse>, Error>

Create a reservation and return the response with metadata.

pub async fn commit_reservation( &self, id: &ReservationId, req: &CommitRequest, ) -> Result<CommitResponse, Error>

Commit actual spend against a reservation.

pub async fn release_reservation( &self, id: &ReservationId, req: &ReleaseRequest, ) -> Result<ReleaseResponse, Error>

Release (cancel) a reservation, returning reserved budget.

pub async fn extend_reservation( &self, id: &ReservationId, req: &ExtendRequest, ) -> Result<ExtendResponse, Error>

Extend a reservation’s TTL (heartbeat).

pub async fn decide( &self, req: &DecisionRequest, ) -> Result<DecisionResponse, Error>

Preflight budget decision check (no reservation created).

pub async fn create_event( &self, req: &EventCreateRequest, ) -> Result<EventCreateResponse, Error>

Create a direct-debit event (no prior reservation).

pub async fn list_reservations( &self, params: &ListReservationsParams, ) -> Result<ReservationListResponse, Error>

List reservations with optional filters.

pub async fn get_reservation( &self, id: &ReservationId, ) -> Result<ReservationDetail, Error>

Get details of a single reservation.

pub async fn get_balances( &self, params: &BalanceParams, ) -> Result<BalanceResponse, Error>

Query budget balances for scopes.

Trait Implementations

impl Clone for CyclesClient

fn clone(&self) -> CyclesClient

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CyclesClient

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

Formats the value using the given formatter.