1use std::time::Duration;
20
21use serde::{Deserialize, Serialize, Serializer};
22
23use serde_json::{Value, json};
24
25use crate::error::EncodeError;
26use crate::error::ProviderError;
27use crate::json_utils::Lenient;
28use crate::operation::Whole;
29use crate::providers::internal::{
30 wire::{classify_or, classify_untyped_line},
31 with_query_pairs,
32};
33use crate::wire::{
34 Body, Call, Decoder, Descriptor, Encoded, Flow, Framing, Free, Mode, Operation, Out, Wire,
35 WireEvent, WireFrame,
36};
37
38const CACHED_CONTENTS_PATH: &str = "/v1beta/cachedContents";
40
41const MAX_PAGE_SIZE: usize = 1000;
43
44pub(crate) fn on_handle(error: ProviderError, name: &str) -> ProviderError {
48 match error {
49 ProviderError::ProviderResponse(response)
50 if matches!(
51 response.status,
52 Some(http::StatusCode::FORBIDDEN | http::StatusCode::NOT_FOUND)
53 ) =>
54 {
55 ProviderError::CacheExpired {
56 name: name.to_owned(),
57 response,
58 }
59 }
60 other => other,
61 }
62}
63
64#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
66#[serde(rename_all = "camelCase")]
67pub enum CacheExpiry {
68 #[serde(serialize_with = "ttl_string")]
71 Ttl(Duration),
72 ExpireTime(String),
74}
75
76impl CacheExpiry {
77 pub fn ttl(ttl: Duration) -> Self {
78 Self::Ttl(ttl)
79 }
80
81 pub fn expire_time(timestamp: impl Into<String>) -> Self {
82 Self::ExpireTime(timestamp.into())
83 }
84}
85
86fn ttl_string<S: Serializer>(ttl: &Duration, serializer: S) -> Result<S::Ok, S::Error> {
88 serializer.collect_str(&format_args!(
89 "{}.{:09}s",
90 ttl.as_secs(),
91 ttl.subsec_nanos()
92 ))
93}
94
95#[derive(Debug, Default, Serialize)]
98#[serde(rename_all = "camelCase")]
99pub struct NewCachedContent {
100 model: String,
103 #[serde(skip_serializing_if = "Vec::is_empty")]
104 contents: Vec<Value>,
105 #[serde(skip_serializing_if = "Option::is_none")]
106 system_instruction: Option<Value>,
107 #[serde(skip_serializing_if = "Option::is_none")]
108 tools: Option<Vec<Value>>,
109 #[serde(skip_serializing_if = "Option::is_none")]
110 tool_config: Option<Value>,
111 #[serde(skip_serializing_if = "Option::is_none")]
112 display_name: Option<String>,
113 #[serde(flatten)]
114 expiry: Option<CacheExpiry>,
115}
116
117impl NewCachedContent {
118 pub fn new(model: impl AsRef<str>) -> Self {
124 Self {
125 model: qualify_model(model.as_ref()),
126 ..Default::default()
127 }
128 }
129
130 pub fn content(mut self, text: impl Into<String>) -> Self {
132 let text = text.into();
133 self.contents
134 .push(json!({ "parts": [{ "text": text, "thought": false }], "role": "user" }));
135 self
136 }
137
138 pub fn content_block(mut self, content: Value) -> Self {
140 self.contents.push(content);
141 self
142 }
143
144 pub fn system_instruction(mut self, text: impl Into<String>) -> Self {
145 let text = text.into();
146 self.system_instruction =
147 Some(json!({ "parts": [{ "text": text, "thought": false }], "role": "model" }));
148 self
149 }
150
151 pub fn tools(mut self, tools: Vec<Value>) -> Self {
156 self.tools = Some(tools);
157 self
158 }
159
160 pub fn tool_config(mut self, tool_config: Value) -> Self {
165 self.tool_config = Some(tool_config);
166 self
167 }
168
169 pub fn display_name(mut self, name: impl Into<String>) -> Self {
170 self.display_name = Some(name.into());
171 self
172 }
173
174 pub fn expiry(mut self, expiry: CacheExpiry) -> Self {
177 self.expiry = Some(expiry);
178 self
179 }
180
181 fn validate(&self) -> Result<(), EncodeError> {
182 if self.contents.is_empty() && self.system_instruction.is_none() {
183 return Err(EncodeError::request(
184 "a cached content needs contents or a system instruction; an empty cache would \
185 bill for storage and cache nothing",
186 ));
187 }
188 Ok(())
189 }
190}
191
192#[derive(Clone, Debug, Default, Deserialize, Serialize)]
194#[serde(rename_all = "camelCase")]
195pub struct CachedContentUsage {
196 #[serde(default)]
199 pub total_token_count: u64,
200}
201
202#[derive(Clone, Debug, Deserialize, Serialize)]
204#[serde(rename_all = "camelCase")]
205pub struct CachedContent {
206 pub name: String,
209 #[serde(default)]
211 pub model: String,
212 #[serde(default, skip_serializing_if = "Option::is_none")]
213 pub display_name: Option<String>,
214 #[serde(default, skip_serializing_if = "Option::is_none")]
215 pub create_time: Option<String>,
216 #[serde(default, skip_serializing_if = "Option::is_none")]
217 pub update_time: Option<String>,
218 #[serde(default, skip_serializing_if = "Option::is_none")]
221 pub expire_time: Option<String>,
222 #[serde(default, skip_serializing_if = "Option::is_none")]
223 pub usage_metadata: Option<CachedContentUsage>,
224}
225
226#[derive(Debug)]
228pub enum CachedContentRequest {
229 Create(NewCachedContent),
231 Get(String),
233 List {
236 page_token: Option<String>,
238 },
239 UpdateExpiry { name: String, expiry: CacheExpiry },
242 Delete(String),
244}
245
246#[derive(Clone, Debug, Deserialize)]
248#[serde(rename_all = "camelCase")]
249pub struct CachedContentPage {
250 pub cached_contents: Vec<CachedContent>,
253 pub next_page_token: Option<String>,
257}
258
259#[derive(Clone, Debug, Default)]
262pub enum CachedContentReply {
263 Resource(CachedContent),
265 Page(CachedContentPage),
267 #[default]
270 Acknowledged,
271}
272
273impl CachedContentReply {
274 pub fn resource(self) -> Result<CachedContent, ProviderError> {
277 match self {
278 Self::Resource(resource) => Ok(resource),
279 other => Err(other.mismatch("one cached content")),
280 }
281 }
282
283 pub fn next_page_token(&self) -> Option<String> {
286 match self {
287 Self::Page(page) => page
288 .next_page_token
289 .clone()
290 .filter(|token| !token.is_empty()),
291 _ => None,
292 }
293 }
294
295 pub fn entries(self) -> Result<Vec<CachedContent>, ProviderError> {
298 match self {
299 Self::Page(page) => Ok(page.cached_contents),
300 Self::Acknowledged => Ok(Vec::new()),
301 other => Err(other.mismatch("a listing page")),
302 }
303 }
304
305 fn mismatch(&self, wanted: &str) -> ProviderError {
307 let carried = match self {
308 Self::Resource(_) => "one cached content",
309 Self::Page(_) => "a listing page",
310 Self::Acknowledged => "nothing to read, only a success status",
311 };
312 ProviderError::Response(format!("the reply carried {carried}, not {wanted}"))
313 }
314}
315
316#[derive(Debug, Clone, Copy, PartialEq, Eq)]
319pub struct ContextCache;
320
321impl Operation for ContextCache {
322 type Request = CachedContentRequest;
323 type Event = std::convert::Infallible;
324 type End = CachedContentReply;
325 type Response = CachedContentReply;
326 type Fold = Whole<Self>;
327 type Emit = Free;
328
329 fn fold(_request: &Self::Request, _call: &mut Call<'_>) -> Self::Fold {
330 Whole::new()
331 }
332}
333
334#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
340pub struct CachedContents {
341 pub provider: super::GeminiConfig,
343 pub page_size: usize,
345}
346
347impl CachedContents {
348 pub fn new(provider: super::GeminiConfig) -> Self {
350 Self {
351 provider,
352 page_size: MAX_PAGE_SIZE,
353 }
354 }
355
356 pub fn with_page_size(mut self, page_size: usize) -> Self {
358 self.page_size = page_size;
359 self
360 }
361
362 fn list_request(&self, page_token: Option<&str>) -> Result<http::Request<Body>, http::Error> {
365 let page_size = self.page_size.to_string();
366 let mut pairs = vec![("pageSize", page_size.as_str())];
367 if let Some(token) = page_token {
368 pairs.push(("pageToken", token));
369 }
370 let path = with_query_pairs(CACHED_CONTENTS_PATH, &pairs);
371 self.provider
372 .request(http::Method::GET, &path)
373 .body(Body::empty())
374 }
375}
376
377pub fn with_cached_content(
384 body: &mut serde_json::Map<String, Value>,
385 name: &str,
386) -> Result<(), EncodeError> {
387 let fail = |message: String| Err(EncodeError::request(message));
388 if !name.starts_with("cachedContents/") {
389 return fail(format!(
390 "gemini cached content handle should look like `cachedContents/<id>`, got `{name}`"
391 ));
392 }
393 if let Some(existing) = body
394 .get("cachedContent")
395 .and_then(Value::as_str)
396 .filter(|existing| *existing != name)
397 {
398 return fail(format!(
399 "a Gemini request set cached content twice, to `{existing}` and `{name}`: set it \
400 one way or the other"
401 ));
402 }
403 let conflicts: Vec<&str> = [
404 (
405 &super::completion::SYSTEM_INSTRUCTION[..],
406 "a system instruction (preamble)",
407 ),
408 (&["tools"][..], "tools"),
409 (&super::completion::TOOL_CONFIG[..], "a tool choice"),
410 ]
411 .into_iter()
412 .filter_map(|(spellings, what)| super::completion::present(body, spellings).map(|_| what))
413 .collect();
414 if conflicts.is_empty() {
415 body.insert("cachedContent".to_owned(), Value::String(name.to_owned()));
416 return Ok(());
417 }
418 let tools = body
421 .get("tools")
422 .and_then(Value::as_array)
423 .map_or(&[][..], Vec::as_slice);
424 let declares_functions = tools.iter().any(|tool| {
425 !tool.arr("functionDeclarations").is_empty()
426 || !tool.arr("function_declarations").is_empty()
427 });
428 let caveat = match declares_functions {
429 true => {
430 " Function declarations in a cache are declarations only: an `Agent` dispatches \
431 only tools it advertised, so a cached function tool runs only when you drive \
432 `GenerateContent` yourself. Hosted tools such as `codeExecution` are fine to cache."
433 }
434 false => "",
435 };
436 fail(format!(
437 "a Gemini request using cached content `{name}` also set {}. The cached content owns \
438 the system instruction, tools and tool choice of every request that uses it: move \
439 them into the cache, or drop the cache handle.{caveat}",
440 conflicts.join(" and ")
441 ))
442}
443
444impl super::GeminiConfig {
445 pub(crate) fn cached_contents(&self) -> CachedContents {
447 CachedContents::new(self.clone())
448 }
449}
450
451impl Wire for CachedContents {
452 type Op = ContextCache;
453 type Payload = crate::wire::Encoded;
454 type Frame = crate::wire::WireFrame;
455 type Event = CachedContentReply;
456 type Decoder<'id> = CachedContentsDecoder;
457 type Reassembler = crate::wire::document::Unreassembled;
458
459 fn describe(&self) -> Descriptor<'_> {
460 Descriptor::new(super::PROVIDER_NAME)
461 }
462
463 fn encode(&self, request: CachedContentRequest, _mode: Mode) -> Result<Encoded, EncodeError> {
467 let request = match request {
468 CachedContentRequest::Create(new) => {
469 new.validate()?;
470 self.provider
471 .post_json(CACHED_CONTENTS_PATH, Body::Bytes(serde_json::to_vec(&new)?))?
472 }
473 CachedContentRequest::Get(name) => self
474 .provider
475 .request(http::Method::GET, &resource_path(&name)?)
476 .body(Body::empty())?,
477 CachedContentRequest::List { page_token } => {
478 self.list_request(page_token.as_deref())?
479 }
480 CachedContentRequest::UpdateExpiry { name, expiry } => {
481 let (patch, mask) = expiry_patch(expiry)?;
482 let path = format!("{}?updateMask={mask}", resource_path(&name)?);
484 self.provider
485 .request(http::Method::PATCH, &path)
486 .header(http::header::CONTENT_TYPE, "application/json")
487 .body(Body::Bytes(patch))?
488 }
489 CachedContentRequest::Delete(name) => self
490 .provider
491 .request(http::Method::DELETE, &resource_path(&name)?)
492 .body(Body::empty())?,
493 };
494 Ok(Encoded::new(request, Framing::Whole))
495 }
496
497 fn decoder<'id>(&self) -> Self::Decoder<'id> {
498 CachedContentsDecoder
499 }
500}
501
502pub struct CachedContentsDecoder;
504
505impl<'id> Decoder<'id, ContextCache> for CachedContentsDecoder {
506 type Event = CachedContentReply;
507
508 fn classify(&self, frame: WireFrame) -> WireEvent<Self::Event> {
511 let body = frame.as_str();
512 classify_or(&body, as_page, |data| {
513 classify_or(data, as_acknowledgement, as_resource)
514 })
515 }
516
517 fn decode(
518 &mut self,
519 reply: Self::Event,
520 out: Out<'id, ContextCache>,
521 ) -> Result<Flow, ProviderError> {
522 Ok(out.end(reply))
523 }
524
525 fn eof(&mut self, out: Out<'id, ContextCache>) -> Result<Flow, ProviderError> {
528 Ok(out.end(CachedContentReply::Acknowledged))
529 }
530}
531
532fn as_page(data: &str) -> WireEvent<CachedContentReply> {
534 classify_untyped_line::<CachedContentPage>(data.as_bytes()).map(CachedContentReply::Page)
535}
536
537fn as_acknowledgement(data: &str) -> WireEvent<CachedContentReply> {
539 #[derive(Deserialize)]
540 #[serde(deny_unknown_fields)]
541 struct Acknowledgement {}
542
543 classify_untyped_line::<Acknowledgement>(data.as_bytes())
544 .map(|_| CachedContentReply::Acknowledged)
545}
546
547fn as_resource(data: &str) -> WireEvent<CachedContentReply> {
549 classify_untyped_line::<CachedContent>(data.as_bytes()).map(CachedContentReply::Resource)
550}
551
552fn expiry_patch(expiry: CacheExpiry) -> Result<(Vec<u8>, &'static str), EncodeError> {
554 let field = match expiry {
555 CacheExpiry::Ttl(_) => "ttl",
556 CacheExpiry::ExpireTime(_) => "expireTime",
557 };
558 Ok((serde_json::to_vec(&expiry)?, field))
559}
560
561fn qualify_model(model: &str) -> String {
563 if model.starts_with("models/") {
564 model.to_owned()
565 } else {
566 format!("models/{model}")
567 }
568}
569
570fn resource_path(name: &str) -> Result<String, EncodeError> {
574 let id = name.strip_prefix("cachedContents/").unwrap_or(name);
575 if !is_resource_id(id) {
576 return Err(EncodeError::request(format!(
577 "`{name}` is not a cached content handle; expected `cachedContents/<id>` or a bare \
578 `<id>` of letters, digits, `-` and `_`. The id is spliced into the request path, \
579 where a `?`, `#` or `/` silently retargets the call at a different resource — \
580 and this is the path that deletes"
581 )));
582 }
583 Ok(format!("{CACHED_CONTENTS_PATH}/{id}"))
584}
585
586pub(super) fn is_resource_id(id: &str) -> bool {
589 !id.is_empty()
590 && id
591 .chars()
592 .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_'))
593}
594
595#[cfg(test)]
596mod tests;
597
598#[cfg(test)]
599mod exhaustive_validation_tests;
600
601#[cfg(test)]
602mod status_triage_tests;