mssql-client 0.8.0

High-level async SQL Server client with type-state connection management
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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

//! Connection state types for type-state pattern.
//!
//! The type-state pattern ensures at compile time that certain operations
//! can only be performed when the connection is in the appropriate state.
//!
//! ## State Transitions
//!
//! ```text
//! Disconnected -> Connected (via TCP connect)
//! Connected -> Ready (via authentication)
//! Ready -> InTransaction (via begin_transaction())
//! Ready -> Streaming (via query() that returns stream)
//! InTransaction -> Ready (via commit() or rollback())
//! InTransaction -> Streaming (via query() within transaction)
//! Streaming -> Ready (via stream completion or cancellation)
//! Streaming -> InTransaction (via stream completion within transaction)
//! ```

use std::marker::PhantomData;

/// Marker trait for connection states.
///
/// This trait is sealed to prevent external implementations,
/// ensuring that only the states defined in this crate are valid.
pub trait ConnectionState: private::Sealed {}

/// Connection is not yet established.
///
/// In this state, only `connect()` can be called.
pub struct Disconnected;

/// TCP connection established, awaiting authentication.
///
/// In this intermediate state:
/// - TCP connection is open
/// - TLS negotiation may be in progress or complete
/// - Login/authentication has not yet completed
///
/// This state is mostly internal; users typically go directly from
/// `Disconnected` to `Ready` via `Client::connect()`.
pub struct Connected;

/// Connection is established and ready for queries.
///
/// In this state, queries can be executed and transactions can be started.
pub struct Ready;

/// Connection is in a transaction.
///
/// In this state, queries execute within the transaction context.
/// The transaction must be explicitly committed or rolled back.
pub struct InTransaction;

/// Connection is actively streaming results.
///
/// In this state, the connection is processing a result set.
/// No other operations can be performed until the stream is
/// consumed or cancelled.
pub struct Streaming;

impl ConnectionState for Disconnected {}
impl ConnectionState for Connected {}
impl ConnectionState for Ready {}
impl ConnectionState for InTransaction {}
impl ConnectionState for Streaming {}

mod private {
    pub trait Sealed {}
    impl Sealed for super::Disconnected {}
    impl Sealed for super::Connected {}
    impl Sealed for super::Ready {}
    impl Sealed for super::InTransaction {}
    impl Sealed for super::Streaming {}
}

/// Type-level state transition marker.
///
/// This is used internally to track state transitions at compile time.
#[derive(Debug)]
pub struct StateMarker<S: ConnectionState> {
    _state: PhantomData<S>,
}

impl<S: ConnectionState> StateMarker<S> {
    pub(crate) fn new() -> Self {
        Self {
            _state: PhantomData,
        }
    }
}

impl<S: ConnectionState> Default for StateMarker<S> {
    fn default() -> Self {
        Self::new()
    }
}

impl<S: ConnectionState> Clone for StateMarker<S> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<S: ConnectionState> Copy for StateMarker<S> {}

/// Internal protocol state for runtime management.
///
/// While connection states are tracked at compile-time via type-state,
/// the protocol layer has runtime state that must be managed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ProtocolState {
    /// Awaiting response from server.
    AwaitingResponse,
    /// Processing token stream.
    ProcessingTokens,
    /// Draining remaining tokens after cancellation.
    Draining,
}

impl Default for ProtocolState {
    fn default() -> Self {
        Self::AwaitingResponse
    }
}

impl ProtocolState {
    /// Check if the connection is in a usable state.
    ///
    /// Currently all protocol states are usable. This method exists for
    /// forward compatibility if a broken/poisoned state is added later.
    #[must_use]
    pub fn is_usable(&self) -> bool {
        // All current states are usable
        matches!(
            self,
            Self::AwaitingResponse | Self::ProcessingTokens | Self::Draining
        )
    }

    /// Check if the connection is actively processing.
    #[must_use]
    pub fn is_busy(&self) -> bool {
        matches!(self, Self::ProcessingTokens | Self::Draining)
    }
}