Skip to main content

rig_core/providers/gemini/
cached_content.rs

1//! Gemini explicit context caching through the `cachedContents` resource.
2//! Upload content once and reuse its handle across requests. Storage is billed
3//! until the cache expires or is deleted.
4//!
5//! Requests using a cache must not supply their own system instruction, tools,
6//! or tool configuration. Cached function declarations require a caller-managed
7//! tool loop; provider-hosted tools execute on Gemini.
8//!
9//! ```no_run
10//! use rig_core::providers::gemini::cached_content::{CacheExpiry, NewCachedContent};
11//! use rig_core::providers::gemini::completion::GEMINI_2_5_FLASH;
12//! use std::time::Duration;
13//!
14//! let corpus = NewCachedContent::new(GEMINI_2_5_FLASH)
15//!     .content("A reusable document corpus")
16//!     .expiry(CacheExpiry::ttl(Duration::from_secs(600)));
17//! ```
18
19use 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
38/// The `cachedContents` collection path.
39const CACHED_CONTENTS_PATH: &str = "/v1beta/cachedContents";
40
41/// Gemini caps a page of `cachedContents` at 1000.
42const MAX_PAGE_SIZE: usize = 1000;
43
44/// Converts a 403 or 404 reply for the existing handle `name` to
45/// [`ProviderError::CacheExpired`], keeping the reply. Other failures are
46/// unchanged. Call only for existing handles, never for cache creation.
47pub(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/// A relative lifetime or absolute expiry time for cached content.
65#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
66#[serde(rename_all = "camelCase")]
67pub enum CacheExpiry {
68    /// Expire this long after creation. Serialized as Gemini's duration string
69    /// (`"600.000000000s"`).
70    #[serde(serialize_with = "ttl_string")]
71    Ttl(Duration),
72    /// Expire at an absolute RFC 3339 timestamp.
73    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
86/// Gemini's duration encoding: fractional seconds with an `s` suffix.
87fn 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/// Content and configuration for creating a cache.
96/// Supply content or a system instruction before creation.
97#[derive(Debug, Default, Serialize)]
98#[serde(rename_all = "camelCase")]
99pub struct NewCachedContent {
100    /// Fully qualified model name (`models/gemini-2.5-flash`). A request that
101    /// uses the cache must name the same model.
102    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    /// Start a cached content for `model`.
119    ///
120    /// Accepts either the bare id (`gemini-2.5-flash`) or the qualified name
121    /// (`models/gemini-2.5-flash`) and normalizes to the latter, which is what
122    /// the API returns and what a `generateContent` request must match.
123    pub fn new(model: impl AsRef<str>) -> Self {
124        Self {
125            model: qualify_model(model.as_ref()),
126            ..Default::default()
127        }
128    }
129
130    /// Append a user-role text content block.
131    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    /// Append a content block in Gemini's REST JSON (multimodal payloads).
139    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    /// Set the tools inherited by requests using this cache, in Gemini's
152    /// REST JSON.
153    /// Requests must not supply their own tools. Cached function declarations
154    /// require a caller-managed tool loop; provider-hosted tools do not.
155    pub fn tools(mut self, tools: Vec<Value>) -> Self {
156        self.tools = Some(tools);
157        self
158    }
159
160    /// Set the tool configuration inherited by requests using this cache,
161    /// in Gemini's REST JSON.
162    /// Requests must not supply their own tool configuration. May be set
163    /// without a tool set.
164    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    /// Set the expiry. Setting it twice replaces the previous value rather than
175    /// sending both, which the API rejects.
176    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/// Storage accounting Gemini reports for a cached content.
193#[derive(Clone, Debug, Default, Deserialize, Serialize)]
194#[serde(rename_all = "camelCase")]
195pub struct CachedContentUsage {
196    /// Tokens held by this cache. This is what storage is billed on, and it is
197    /// also the ceiling on what a request against the handle can read back.
198    #[serde(default)]
199    pub total_token_count: u64,
200}
201
202/// A cached content resource as Gemini reports it.
203#[derive(Clone, Debug, Deserialize, Serialize)]
204#[serde(rename_all = "camelCase")]
205pub struct CachedContent {
206    /// Server-assigned handle, `cachedContents/<id>`. This is what
207    /// [`super::completion::GenerateContent::with_cached_content`] takes.
208    pub name: String,
209    /// Qualified model this cache is bound to.
210    #[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    /// When this cache lapses. After it does, using the handle fails with
219    /// [`ProviderError::CacheExpired`].
220    #[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/// One `cachedContents` verb: what [`ContextCache`] sends.
227#[derive(Debug)]
228pub enum CachedContentRequest {
229    /// `POST /v1beta/cachedContents`; answers with the resource.
230    Create(NewCachedContent),
231    /// `GET /v1beta/cachedContents/<id>`; answers with the resource.
232    Get(String),
233    /// `GET /v1beta/cachedContents?pageSize=…`, after `page_token` when
234    /// continuing; answers with one page.
235    List {
236        /// The previous page's `nextPageToken`; `None` for the first page.
237        page_token: Option<String>,
238    },
239    /// `PATCH /v1beta/cachedContents/<id>?updateMask=…`; answers with the
240    /// resource.
241    UpdateExpiry { name: String, expiry: CacheExpiry },
242    /// `DELETE /v1beta/cachedContents/<id>`; answers with `{}`.
243    Delete(String),
244}
245
246/// One page of a `cachedContents` listing.
247#[derive(Clone, Debug, Deserialize)]
248#[serde(rename_all = "camelCase")]
249pub struct CachedContentPage {
250    /// Entries in arrival order, concatenated across pages when folded.
251    /// Required during deserialization to distinguish pages from resources.
252    pub cached_contents: Vec<CachedContent>,
253    /// The cursor naming the next page, when the listing has one. The
254    /// decoder takes it before the page reaches the fold, so a folded
255    /// reply's is always `None`.
256    pub next_page_token: Option<String>,
257}
258
259/// A resource, listing page, or empty acknowledgement from `cachedContents`.
260/// Malformed bodies fail decoding rather than representing absent resources.
261#[derive(Clone, Debug, Default)]
262pub enum CachedContentReply {
263    /// `create`, `get` and `update_expiry`: the resource.
264    Resource(CachedContent),
265    /// `list`: one page of the collection.
266    Page(CachedContentPage),
267    /// An empty successful reply for deletion or an empty collection.
268    /// Also the default for a fold that receives no replies.
269    #[default]
270    Acknowledged,
271}
272
273impl CachedContentReply {
274    /// Extract the resource returned by creation, lookup, or expiry update.
275    /// Return a response error for a page or acknowledgement.
276    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    /// The cursor of the page after this one. An empty cursor counts as
284    /// absent: re-sending an empty `pageToken` returns the same page forever.
285    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    /// The entries of one listing page. An empty collection is answered
296    /// with the empty object, which is [`Self::Acknowledged`].
297    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    /// Build a response error naming the actual and expected reply shapes.
306    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/// Creates, reads, lists, updates expiry, or deletes explicit context caches.
317/// Requests use [`CachedContentRequest`]; a listing reads one page per call.
318#[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/// Gemini's `cachedContents` resource: the wire for
335/// [`ContextCache`].
336///
337/// Built by [`Gemini::cached_contents`](super::Gemini::cached_contents); the
338/// calls are the inherent methods of a [`Model`](crate::Model) over it.
339#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
340pub struct CachedContents {
341    /// The provider this wire speaks to.
342    pub provider: super::GeminiConfig,
343    /// Requested entries per listing page. Defaults to Gemini's cap of 1,000.
344    pub page_size: usize,
345}
346
347impl CachedContents {
348    /// The wire over `provider`, listing a full page at a time.
349    pub fn new(provider: super::GeminiConfig) -> Self {
350        Self {
351            provider,
352            page_size: MAX_PAGE_SIZE,
353        }
354    }
355
356    /// List `page_size` entries per request.
357    pub fn with_page_size(mut self, page_size: usize) -> Self {
358        self.page_size = page_size;
359        self
360    }
361
362    /// Build a listing request, optionally continuing after `page_token`.
363    /// Percent-encoding preserves the cursor and prevents query injection.
364    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
377/// Set `name`, a `cachedContents/<id>` handle, as the prefix `body` reads.
378///
379/// # Errors
380///
381/// When `name` is not a handle, `body` names another one, or it sets a
382/// system instruction, tools or a tool choice, which the cache owns.
383pub 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    // Cached function declarations need caller-side dispatch; hosted tools
419    // run on Gemini's side.
420    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    /// Build a wire for Gemini's explicit context cache (`cachedContents`).
446    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    /// A resource call never streams, so both modes send the one request.
464    /// A handle is validated by `resource_path` before anything is built,
465    /// and an empty cache is refused before it bills.
466    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                // Handle validation prevents query injection and retargeting the patch.
483                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
502/// Decodes one `cachedContents` reply.
503pub struct CachedContentsDecoder;
504
505impl<'id> Decoder<'id, ContextCache> for CachedContentsDecoder {
506    type Event = CachedContentReply;
507
508    /// Classify a page, empty acknowledgement, or resource.
509    /// Malformed bodies remain decoding failures.
510    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    /// A reply with no body at all is an acknowledgement: the status
526    /// already answered.
527    fn eof(&mut self, out: Out<'id, ContextCache>) -> Result<Flow, ProviderError> {
528        Ok(out.end(CachedContentReply::Acknowledged))
529    }
530}
531
532/// One listing page, or a body that is not one.
533fn as_page(data: &str) -> WireEvent<CachedContentReply> {
534    classify_untyped_line::<CachedContentPage>(data.as_bytes()).map(CachedContentReply::Page)
535}
536
537/// Classify an empty object as a deletion acknowledgement; reject any fields.
538fn 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
547/// One cached content, or a body that is not one.
548fn as_resource(data: &str) -> WireEvent<CachedContentReply> {
549    classify_untyped_line::<CachedContent>(data.as_bytes()).map(CachedContentReply::Resource)
550}
551
552/// Serialize the expiry patch with an update mask naming its only field.
553fn 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
561/// `models/x` from `x`, idempotently.
562fn qualify_model(model: &str) -> String {
563    if model.starts_with("models/") {
564        model.to_owned()
565    } else {
566        format!("models/{model}")
567    }
568}
569
570/// Build `/v1beta/cachedContents/<id>` from a bare id or prefixed handle.
571/// Reject empty ids and characters other than ASCII letters, digits, `-`, and
572/// `_` to prevent path traversal, query injection, or resource retargeting.
573fn 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
586/// Whether `id` is a non-empty run of ASCII letters, digits, `-` and `_`,
587/// so it is one path segment that cannot retarget a request.
588pub(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;