adk_session/
session.rs

1use crate::{Events, State};
2use adk_core::Result;
3use adk_core::identity::{AdkIdentity, AppName, SessionId, UserId};
4use chrono::{DateTime, Utc};
5
6/// Trait representing a conversation session with state and event history.
7pub trait Session: Send + Sync {
8    /// Returns the session identifier.
9    fn id(&self) -> &str;
10    /// Returns the application name that owns this session.
11    fn app_name(&self) -> &str;
12    /// Returns the user identifier for the session owner.
13    fn user_id(&self) -> &str;
14    /// Returns a reference to the session's state store.
15    fn state(&self) -> &dyn State;
16    /// Returns a reference to the session's event history.
17    fn events(&self) -> &dyn Events;
18    /// Returns the timestamp of the last update to this session.
19    fn last_update_time(&self) -> DateTime<Utc>;
20
21    /// Returns the application name as a typed [`AppName`].
22    ///
23    /// Parses the value returned by [`app_name()`](Self::app_name). Returns an
24    /// error if the raw string fails validation (empty, null bytes, or exceeds
25    /// the maximum length).
26    ///
27    /// # Errors
28    ///
29    /// Returns [`AdkError::config`](adk_core::AdkError::config) when the
30    /// underlying string is not a valid identifier.
31    fn try_app_name(&self) -> Result<AppName> {
32        Ok(AppName::try_from(self.app_name())?)
33    }
34
35    /// Returns the user identifier as a typed [`UserId`].
36    ///
37    /// Parses the value returned by [`user_id()`](Self::user_id). Returns an
38    /// error if the raw string fails validation.
39    ///
40    /// # Errors
41    ///
42    /// Returns [`AdkError::config`](adk_core::AdkError::config) when the
43    /// underlying string is not a valid identifier.
44    fn try_user_id(&self) -> Result<UserId> {
45        Ok(UserId::try_from(self.user_id())?)
46    }
47
48    /// Returns the session identifier as a typed [`SessionId`].
49    ///
50    /// Parses the value returned by [`id()`](Self::id). Returns an error if
51    /// the raw string fails validation.
52    ///
53    /// # Errors
54    ///
55    /// Returns [`AdkError::config`](adk_core::AdkError::config) when the
56    /// underlying string is not a valid identifier.
57    fn try_session_id(&self) -> Result<SessionId> {
58        Ok(SessionId::try_from(self.id())?)
59    }
60
61    /// Returns the stable session-scoped [`AdkIdentity`] triple.
62    ///
63    /// Combines [`try_app_name()`](Self::try_app_name),
64    /// [`try_user_id()`](Self::try_user_id), and
65    /// [`try_session_id()`](Self::try_session_id) into a single composite
66    /// identity value.
67    ///
68    /// # Errors
69    ///
70    /// Returns an error if any of the three constituent identifiers fail
71    /// validation.
72    fn try_identity(&self) -> Result<AdkIdentity> {
73        Ok(AdkIdentity {
74            app_name: self.try_app_name()?,
75            user_id: self.try_user_id()?,
76            session_id: self.try_session_id()?,
77        })
78    }
79}
80
81/// Key prefix for application-scoped state entries.
82pub const KEY_PREFIX_APP: &str = "app:";
83/// Key prefix for temporary state entries (stripped on event append).
84pub const KEY_PREFIX_TEMP: &str = "temp:";
85/// Key prefix for user-scoped state entries.
86pub const KEY_PREFIX_USER: &str = "user:";
adk_session/session.rs

adk_session/
session.rs
