liminal-sdk 0.2.0

Application-facing SDK traits for liminal messaging clients
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

use alloc::string::String;
use core::future::Future;

use futures_core::Stream;
use serde::Serialize;
use serde::de::DeserializeOwned;

use crate::SdkError;

/// Application-visible identifier for a conversation.
///
/// SDK callers use this value for correlation and lifecycle observation. It is
/// not a beamr process identifier and does not require callers to manage any
/// supervised runtime process directly.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct ConversationId(String);

impl ConversationId {
    /// Creates a conversation identifier from an application-visible string.
    #[must_use]
    pub fn new(value: impl Into<String>) -> Self {
        Self(value.into())
    }

    /// Returns the identifier as a string slice.
    #[must_use]
    pub fn as_str(&self) -> &str {
        self.0.as_str()
    }
}

impl From<String> for ConversationId {
    fn from(value: String) -> Self {
        Self::new(value)
    }
}

impl From<&'static str> for ConversationId {
    fn from(value: &'static str) -> Self {
        Self::new(value)
    }
}

/// Lifecycle events emitted by a conversation.
///
/// Every event carries the application-visible conversation identifier so
/// lifecycle streams can be correlated without exposing process identifiers,
/// protocol frames, or transport details.
#[derive(Debug)]
pub enum ConversationEvent {
    /// The conversation was opened.
    Opened {
        /// Identifier for the conversation that emitted this event.
        conversation_id: ConversationId,
    },
    /// A message was observed within the conversation.
    Message {
        /// Identifier for the conversation that emitted this event.
        conversation_id: ConversationId,
    },
    /// The conversation has begun closing.
    Closing {
        /// Identifier for the conversation that emitted this event.
        conversation_id: ConversationId,
    },
    /// The conversation closed.
    Closed {
        /// Identifier for the conversation that emitted this event.
        conversation_id: ConversationId,
    },
    /// The conversation encountered an error.
    Error {
        /// Identifier for the conversation that emitted this event.
        conversation_id: ConversationId,
        /// Error reported for the conversation lifecycle.
        error: SdkError,
    },
}

/// Application-facing typed conversation API.
///
/// A conversation is the fundamental messaging unit in liminal. The handle lets
/// callers send typed messages, receive typed messages, and observe lifecycle
/// events without handling transport details or supervised runtime process IDs.
pub trait ConversationHandle: core::fmt::Debug + Send + Sync {
    /// Future returned by [`receive`](Self::receive) for message type `M`.
    type ReceiveFuture<'a, M>: Future<Output = Result<M, SdkError>> + 'a
    where
        Self: 'a,
        M: DeserializeOwned + 'a;

    /// Stream returned by [`lifecycle`](Self::lifecycle).
    type LifecycleStream: Stream<Item = ConversationEvent>;

    /// Sends a typed message within this conversation.
    ///
    /// # Errors
    ///
    /// Returns [`SdkError`] when the concrete conversation implementation cannot
    /// serialize or transmit the message in the conversation context.
    fn send<M>(&self, message: M) -> Result<(), SdkError>
    where
        M: Serialize;

    /// Receives the next typed message from this conversation.
    ///
    /// The message type is owned after deserialization so callers never borrow
    /// buffers managed by an SDK implementation.
    ///
    /// # Errors
    ///
    /// The returned future resolves to [`SdkError`] when the concrete
    /// implementation cannot receive or deserialize the next message.
    fn receive<M>(&self) -> Self::ReceiveFuture<'_, M>
    where
        M: DeserializeOwned;

    /// Observes lifecycle events for this conversation.
    fn lifecycle(&self) -> Self::LifecycleStream;
}