lib.rs1//! The Jev API over HTTPS for a native process: `jev-client`'s policy on 2//! this crate's transport (`transport.rs`: HTTP/2 over pure-Rust TLS on 3//! tokio) and runtime, and the shared spend ledger in front of both. 4//! 5//! WHAT to ask is `jev-protocol`'s; how to retry is `jev-client`'s. This is 6//! only how the bytes get there, and what they cost. The browser build cannot 7//! reach the API directly anyway (`api.typesafe.ai` refuses browser 8//! origins), so a web page gets a relay and never links this. 9//! 10//! **Every request is checked against [`ledger::Ledger`] before it is sent.** 11//! This account's credit is finite, so a client that could be built and used 12//! without a shared, on-disk record of what has already been spent would make 13//! overspending a matter of which binary you happened to run - see `ledger`'s 14//! own doc comment for why the record has to be a file and not a number kept 15//! in memory. `Jev::new`/`Jev::from_env` are the only ways to get a client, 16//! and both build the ledger check into it, so there is no path to `ask` that 17//! skips it. There is no self-imposed lifetime cap here (removed 2026-09-22, 18//! the user's own ruling) - the only hard stop is the vendor's own 19//! out-of-credit answer, which is a fact about the account, not a guess. 20 21pub mod ledger; 22mod runtime; 23mod transport; 24 25use std::sync::{Arc, Mutex, PoisonError}; 26use std::time::{Duration, Instant}; 27 28use jev_client::{Client, ClientError}; 29use jev_protocol::{ApiErrorKind, DOLLARS_PER_MTOK, Json, ModelId, Questions, Response, request_bytes, retry}; 30 31pub use ledger::{Entry, Guards, Hold, Ledger, NoCredit, Refusal, Status, Window}; 32pub use runtime::TokioRuntime; 33pub use transport::{ENDPOINT, Endpoint, HttpsTransport}; 34 35/// The environment variable the key arrives in. On this machine it reaches a 36/// process through `op-env-run` and nowhere else - never a dotfile, never a 37/// command line (see the repository README). 38pub const KEY: &str = "TYPESAFE_API_KEY"; 39 40/// The documented per-request input ceiling (digest §4), so a huge `state` 41/// cannot make a worst case run away. 42const MAX_REQUEST_TOKENS: f64 = 64_000.0; 43 44/// What a response's headers said about how much of the vendor's own rate 45/// limit is left, when they said anything at all. Digest §10: as of 46/// 2026-09-20 the vendor documents no such headers on a successful response - 47/// only `Retry-After`/`retry-after-ms` on a `429`/`529` - so every field here 48/// is commonly `None`. It stays a typed, if usually-empty, snapshot rather 49/// than nothing at all so that the day the vendor adds one, this starts 50/// reporting it with no code changed at every call site. 51#[derive( 52 Debug, Clone, Copy, Default, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema, 53)] 54pub struct RateLimit { 55 pub limit: Option<u64>, 56 pub remaining: Option<u64>, 57 /// Seconds until the window resets, exactly as the header gave it - not 58 /// resolved to a clock time, since that would claim a precision about 59 /// when the header was actually read that nothing here can back up. 60 pub reset_seconds: Option<f64>, 61} 62 63/// A client, and one to reuse: it holds the connection, and a warm 64/// connection is worth hundreds of milliseconds per decision. 65pub struct Jev { 66 client: Client<HttpsTransport, TokioRuntime>, 67 /// Which binary this is, for the ledger's records - `native`, `player`, 68 /// `jevprobe`, ... 69 binary: String, 70 ledger: Ledger, 71 guards: Guards, 72 /// The most recent parsed [`RateLimit`], kept for [`Jev::last_rate_limit`] 73 /// so a caller (the `budget` MCP tool, in particular) does not have to 74 /// wait for the next request to see what the last one learned. 75 last_rate_limit: Mutex<Option<RateLimit>>, 76} 77 78/// What one answered request cost in time as well as tokens. 79#[derive(Debug)] 80pub struct Answered { 81 /// The answers, verified against the questions asked. 82 pub response: Response, 83 /// The whole round trip, retries and waits included. 84 pub took: Duration, 85 /// How many times the request had to be sent. 1 is the happy path. 86 pub attempts: u32, 87 /// The response exactly as it arrived. Kept so that a field the protocol 88 /// does not know about is visible rather than silently dropped by the 89 /// parse - which is how the digest gets corrected. 90 pub body: String, 91 /// Every response header, name and value, with anything that looks like 92 /// a credential redacted. `apps/jevprobe --headers` exists to print this. 93 pub headers: Vec<(String, String)>, 94 /// `x-typesafe-request-id`, if the response carried one (digest §1). 95 pub request_id: Option<String>, 96 pub rate_limit: Option<RateLimit>, 97} 98 99/// Why an ask produced no answer. The first two never touch the network. 100#[derive(Debug)] 101pub enum Failure { 102 /// A shared guard that clears itself refused: the same request would be 103 /// admitted after `retry_in`. The caller goes on without an answer. 104 Throttled { why: String, retry_in: Duration }, 105 /// Nothing is admitted until a human acts: the vendor said the account is 106 /// out of credit, or the ledger cannot be read or written (a guard that 107 /// cannot see the spend fails closed). 108 Budget(String), 109 /// The request went out and failed, as `jev-client` judged it after its 110 /// retries. 111 Client(ClientError), 112} 113 114impl std::fmt::Display for Failure { 115 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 116 match self { 117 Self::Throttled { why, retry_in } => { 118 write!(f, "not sent, throttled: {why}; clears in {:.0}s", retry_in.as_secs_f64()) 119 } 120 Self::Budget(why) => write!(f, "not sent: {why}"), 121 Self::Client(e) => e.fmt(f), 122 } 123 } 124} 125 126impl std::error::Error for Failure {} 127 128impl Jev { 129 /// Read the key from the environment and build a client for the API, its 130 /// ledger opened from `$XDG_STATE_HOME` (see `ledger::Ledger::open`). 131 /// `None` when the key is not there, which is not an error: the app runs 132 /// without it and says on screen that it cannot play. 133 pub fn from_env(binary: impl Into<String>, model: ModelId) -> Option<Result<Self, String>> { 134 let key = std::env::var(KEY).ok().filter(|key| !key.trim().is_empty())?; 135 Some( 136 Ledger::open() 137 .map_err(|e| format!("opening the spend ledger: {e}")) 138 .and_then(|ledger| Self::new(key.trim(), binary, ledger, model, Endpoint::api())), 139 ) 140 } 141 142 /// Build a client against an already-open [`Ledger`]. Every real caller 143 /// wants [`Self::from_env`]; this is the constructor that makes the 144 /// dependency explicit rather than reached for internally, so a test can 145 /// hand it a ledger rooted in a private directory instead of the real 146 /// `$XDG_STATE_HOME/jev` - and so there is no `Jev` value anywhere that 147 /// was not required, at construction, to say where its spend is kept. 148 pub fn new( 149 key: &str, 150 binary: impl Into<String>, 151 ledger: Ledger, 152 model: ModelId, 153 endpoint: Endpoint, 154 ) -> Result<Self, String> { 155 // The trust anchors are compiled in rather than read from the host, so 156 // what this trusts is the same on every machine and in a sandbox with 157 // no /etc/ssl at all. The provider is RustCrypto: pure Rust, no ring, 158 // no aws-lc, nothing to cross-compile for the web build later. 159 let mut roots = rustls::RootCertStore::empty(); 160 roots.extend(webpki_roots::TLS_SERVER_ROOTS.iter().cloned()); 161 if let Some(path) = endpoint.ca_file() { 162 use rustls::pki_types::CertificateDer; 163 use rustls::pki_types::pem::PemObject; 164 let shown = path.display(); 165 for cert in CertificateDer::pem_file_iter(path).map_err(|e| format!("CA file {shown}: {e}"))? { 166 let cert = cert.map_err(|e| format!("CA file {shown}: {e}"))?; 167 roots.add(cert).map_err(|e| format!("CA file {shown}: {e}"))?; 168 } 169 } 170 let mut tls = rustls::ClientConfig::builder_with_provider(Arc::new(rustls_rustcrypto::provider())) 171 .with_safe_default_protocol_versions() 172 .map_err(|e| format!("rustls protocol versions: {e}"))? 173 .with_root_certificates(roots) 174 .with_no_client_auth(); 175 tls.alpn_protocols = vec![b"h2".to_vec()]; 176 let transport = HttpsTransport::new(endpoint, Arc::new(tls)); 177 let client = Client::new(transport, TokioRuntime, model, key).map_err(|e| e.to_string())?; 178 Ok(Self { 179 client, 180 binary: binary.into(), 181 ledger, 182 guards: Guards::from_env(), 183 last_rate_limit: Mutex::new(None), 184 }) 185 } 186 187 /// The same client under other guards than the environment's. 188 #[must_use] 189 pub fn with_guards(mut self, guards: Guards) -> Self { 190 self.guards = guards; 191 self 192 } 193 194 pub fn model(&self) -> &ModelId { 195 self.client.model() 196 } 197 198 pub fn ledger(&self) -> &Ledger { 199 &self.ledger 200 } 201 202 pub fn guards(&self) -> Guards { 203 self.guards 204 } 205 206 /// What the shared guards say right now - every process's questions, not 207 /// only this one's. 208 pub fn status(&self) -> Result<Status, String> { 209 self.ledger.status(ledger::now(), self.guards) 210 } 211 212 /// The most recent [`RateLimit`] this client has seen, if any response 213 /// ever carried one. 214 pub fn last_rate_limit(&self) -> Option<RateLimit> { 215 *self.last_rate_limit.lock().unwrap_or_else(PoisonError::into_inner) 216 } 217 218 /// Ask, under `jev-client`'s retry policy - but first, have the shared 219 /// ledger admit it ([`Ledger::admit`]: question bucket, hour breaker, out 220 /// of credit - there is no lifetime cap, per the user's own ruling, 221 /// 2026-09-22), before a single byte goes over the network. A refusal 222 /// that clears itself is [`Failure::Throttled`], one that does not (out 223 /// of credit) is [`Failure::Budget`]; neither is retried here. 224 /// 225 /// `why` is recorded against the spend in the ledger's `reason`. It is a 226 /// required argument, not an option, so that every line of the ledger can 227 /// say why the money went: the breaker trip of 2026-09-20 had to be 228 /// reconstructed from token counts because no line said. 229 pub async fn ask(&self, state: &Json, questions: &Questions, why: &str) -> Result<Answered, Failure> { 230 let worst_case = worst_case_usd(self.client.model(), state, questions); 231 let hold = self.ledger.admit(ledger::now(), &self.guards, worst_case, &self.binary, why).map_err( 232 |refusal| match refusal { 233 Refusal::Throttled { why, retry_in } => Failure::Throttled { 234 why, 235 retry_in: Duration::try_from_secs_f64(retry_in).unwrap_or(Duration::MAX), 236 }, 237 other => Failure::Budget(other.to_string()), 238 }, 239 )?; 240 241 let started = Instant::now(); 242 match self.client.ask(state, questions).await { 243 Ok(answered) => { 244 let rate_limit = parse_rate_limit(&answered.headers); 245 if let Some(rate_limit) = rate_limit { 246 *self.last_rate_limit.lock().unwrap_or_else(PoisonError::into_inner) = Some(rate_limit); 247 if let Err(e) = self.ledger.note_rate_limit(&rate_limit) { 248 eprintln!("jev ledger: could not record a rate-limit snapshot: {e}"); 249 } 250 } 251 let usage = answered.response.usage(); 252 let cost = usage.dollars(); 253 let entry = Entry { 254 time: ledger::now(), 255 binary: self.binary.clone(), 256 input_tokens: usage.input_tokens, 257 output_tokens: usage.output_tokens, 258 cost_usd: cost, 259 request_id: answered.request_id.clone(), 260 estimated: false, 261 reason: Some(why.to_owned()), 262 hold: None, 263 }; 264 if let Err(e) = self.ledger.settle(&hold, entry) { 265 // The request already happened and was paid for 266 // whether or not this write succeeds; refusing to 267 // return the answer would not undo that, it would 268 // just also lose the decision. The hold stays 269 // unsettled, so the ledger goes on counting its 270 // worst case - more than it cost. Loudly logged, 271 // since a ledger that cannot be written to is a 272 // problem worth a human's attention on its own. 273 eprintln!("jev ledger: could not record a ${cost:.6} spend: {e}"); 274 } 275 Ok(Answered { 276 took: started.elapsed(), 277 attempts: answered.attempts, 278 body: String::from_utf8_lossy(&answered.body).into_owned(), 279 headers: collect_headers(&answered.headers), 280 request_id: answered.request_id, 281 rate_limit, 282 response: answered.response, 283 }) 284 } 285 Err(error) => { 286 if let ClientError::Api { error: api, .. } = &error 287 && api.kind == ApiErrorKind::OutOfCredit 288 && let Err(e) = self.ledger.mark_out_of_credit("the vendor reports no credit remaining") 289 { 290 eprintln!("jev ledger: could not record the vendor's out-of-credit answer: {e}"); 291 } 292 // `release` books the hold at nothing, which is true only 293 // when nothing can have been billed: the request was never 294 // built, or its one attempt was refused outright. After an 295 // interrupted or timed-out attempt the cost is unknown (the 296 // vendor reports usage only on success), so the hold stays 297 // and goes on counting its worst case, as a crashed 298 // process's does. 299 if nothing_billed(&error) 300 && let Err(e) = self.ledger.release(&hold, ledger::now(), &error.to_string()) 301 { 302 eprintln!("jev ledger: could not release an unanswered hold: {e}"); 303 } 304 Err(Failure::Client(error)) 305 } 306 } 307 } 308} 309 310fn nothing_billed(error: &ClientError) -> bool { 311 match error { 312 ClientError::Invalid(_) => true, 313 ClientError::Api { attempts, .. } => *attempts == 1, 314 _ => false, 315 } 316} 317 318/// A conservative worst case, in tokens, for what one attempt could cost - 319/// used to check the guards BEFORE sending, when the true count (which only 320/// the response carries) is not yet known. 321/// 322/// A UTF-8 character is never shorter than one token can be cheaper than, so 323/// counting characters can only overstate the token count - which is exactly 324/// what a worst case should do. The documented 64k-token ceiling per request 325/// caps it either way. 326fn worst_case_tokens(model: &ModelId, state: &Json, questions: &Questions) -> f64 { 327 let chars = request_bytes(model, state, questions) 328 .map(|bytes| String::from_utf8_lossy(&bytes).chars().count() as f64) 329 .unwrap_or(MAX_REQUEST_TOKENS); 330 chars.min(MAX_REQUEST_TOKENS) 331} 332 333/// Every attempt `jev-client` may make (`1 + retry::MAX_RETRIES`) billed in 334/// full. 335fn worst_case_usd(model: &ModelId, state: &Json, questions: &Questions) -> f64 { 336 let attempts = f64::from(1 + retry::MAX_RETRIES); 337 worst_case_tokens(model, state, questions) * attempts / 1e6 * DOLLARS_PER_MTOK 338} 339 340/// Any of the conventional rate-limit header spellings, read opportunistically. 341/// Digest §10: none of these are documented anywhere in the vendor's own 342/// reference as of 2026-09-20, so this is expected to return `None` on every 343/// real response; it stays general rather than named after one convention so 344/// that if the vendor starts sending any of them, this starts reporting it 345/// with no code changed anywhere that calls `ask`. 346fn parse_rate_limit(headers: &http::HeaderMap) -> Option<RateLimit> { 347 let text = |name: &str| headers.get(name)?.to_str().ok().map(str::to_owned); 348 let as_u64 = |name: &str| text(name)?.trim().parse::<u64>().ok(); 349 let as_f64 = |name: &str| text(name)?.trim().parse::<f64>().ok(); 350 let limit = as_u64("x-ratelimit-limit-requests") 351 .or_else(|| as_u64("x-ratelimit-limit")) 352 .or_else(|| as_u64("ratelimit-limit")); 353 let remaining = as_u64("x-ratelimit-remaining-requests") 354 .or_else(|| as_u64("x-ratelimit-remaining")) 355 .or_else(|| as_u64("ratelimit-remaining")); 356 let reset_seconds = as_f64("x-ratelimit-reset-requests") 357 .or_else(|| as_f64("x-ratelimit-reset")) 358 .or_else(|| as_f64("ratelimit-reset")); 359 (limit.is_some() || remaining.is_some() || reset_seconds.is_some()) 360 .then_some(RateLimit { limit, remaining, reset_seconds }) 361} 362 363/// Every header name and value, redacting anything that could be a 364/// credential by name - a bearer token echoed back, a cookie, anything with 365/// "key"/"token"/"secret" in it. `apps/jevprobe --headers` is the one caller 366/// that prints this; `Answered` always carries it so that mode needs no 367/// separate request. 368fn collect_headers(headers: &http::HeaderMap) -> Vec<(String, String)> { 369 let sensitive = |name: &str| { 370 let lower = name.to_ascii_lowercase(); 371 ["authorization", "cookie", "token", "secret", "-key", "api-key"] 372 .iter() 373 .any(|word| lower.contains(word)) 374 }; 375 headers 376 .iter() 377 .map(|(name, value)| { 378 let name = name.as_str().to_owned(); 379 let value = if sensitive(&name) { 380 "«redacted»".to_owned() 381 } else { 382 value.to_str().unwrap_or("«non-utf8»").to_owned() 383 }; 384 (name, value) 385 }) 386 .collect() 387} 388 389#[cfg(test)] 390mod tests { 391 use super::*; 392 393 fn model() -> ModelId { 394 ModelId::pinned("jev-1.13.0").expect("a pinned model") 395 } 396 397 fn sandbox_ledger() -> Ledger { 398 let dir = std::env::temp_dir() 399 .join(format!("jev-http-test-{}", std::process::id())) 400 .join(ledger::now().to_string()); 401 Ledger::at(dir).expect("opening a sandbox ledger") 402 } 403 404 #[test] 405 fn a_missing_key_is_not_an_error() { 406 // Whatever this machine's environment happens to hold, an empty one 407 // means "no client", not "a broken client". 408 assert!( 409 Jev::new("", "test", sandbox_ledger(), model(), Endpoint::api()).is_ok(), 410 "an empty key still builds; the API refuses it" 411 ); 412 } 413 414 #[test] 415 fn rate_limit_headers_are_read_when_present_and_absent_otherwise() { 416 let empty = http::HeaderMap::new(); 417 assert_eq!(parse_rate_limit(&empty), None, "no header, no snapshot"); 418 419 let mut headers = http::HeaderMap::new(); 420 headers.insert("x-ratelimit-remaining-requests", "37".parse().expect("a header value")); 421 let rate_limit = parse_rate_limit(&headers).expect("a snapshot"); 422 assert_eq!(rate_limit.remaining, Some(37)); 423 assert_eq!(rate_limit.limit, None, "only what was actually sent is filled in"); 424 } 425 426 #[test] 427 fn a_bearer_token_echoed_back_would_be_redacted() { 428 let mut headers = http::HeaderMap::new(); 429 headers.insert("x-typesafe-request-id", "req_abc123".parse().expect("a header value")); 430 headers.insert("set-cookie", "session=deadbeef".parse().expect("a header value")); 431 let collected = collect_headers(&headers); 432 let value_of = |name: &str| { 433 collected.iter().find(|(n, _)| n == name).map(|(_, v)| v.clone()).unwrap() 434 }; 435 assert_eq!(value_of("x-typesafe-request-id"), "req_abc123"); 436 assert_eq!(value_of("set-cookie"), "«redacted»"); 437 } 438 439 #[test] 440 fn a_huge_state_is_capped_at_the_documented_ceiling_not_left_unbounded() { 441 let huge = Json::text(&"x".repeat(1_000_000)); 442 let mut questions = Questions::new(); 443 questions.noul("q", jev_protocol::Noul::new(Json::text("long?"))).expect("a question"); 444 assert_eq!(worst_case_tokens(&model(), &huge, &questions), 64_000.0); 445 } 446}