Skip to main content

sqlx_sqlserver/protocol/
token.rs

1use thiserror::Error;
2
3/// TDS tabular-result token type byte.
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5pub struct TokenType(u8);
6
7impl TokenType {
8    /// ERROR token.
9    pub const ERROR: Self = Self(0xaa);
10    /// INFO token.
11    pub const INFO: Self = Self(0xab);
12    /// LOGINACK token.
13    pub const LOGINACK: Self = Self(0xad);
14    /// ENVCHANGE token.
15    pub const ENVCHANGE: Self = Self(0xe3);
16    /// DONE token.
17    pub const DONE: Self = Self(0xfd);
18
19    /// Returns the raw token type byte.
20    pub const fn code(self) -> u8 {
21        self.0
22    }
23}
24
25impl From<u8> for TokenType {
26    fn from(value: u8) -> Self {
27        Self(value)
28    }
29}
30
31/// Parsed subset of TDS tabular-result tokens needed during login.
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub enum Token {
34    /// Server accepted the LOGIN7 request.
35    LoginAck(LoginAck),
36    /// Server returned an error.
37    Error(ServerError),
38    /// Server reported a connection environment change.
39    EnvChange(EnvChange),
40    /// Server completed the response stream.
41    Done(Done),
42}
43
44/// LOGINACK token data.
45#[derive(Debug, Clone, PartialEq, Eq)]
46pub struct LoginAck {
47    /// Accepted server interface.
48    pub interface: u8,
49    /// TDS protocol version selected by the server.
50    pub tds_version: u32,
51    /// Server program name.
52    pub program_name: String,
53    /// Server major version.
54    pub major_version: u8,
55    /// Server minor version.
56    pub minor_version: u8,
57    /// High byte of the server build number.
58    pub build_number_high: u8,
59    /// Low byte of the server build number.
60    pub build_number_low: u8,
61}
62
63/// ERROR token data.
64#[derive(Debug, Clone, PartialEq, Eq)]
65pub struct ServerError {
66    /// SQL Server error number.
67    pub number: i32,
68    /// Error state.
69    pub state: u8,
70    /// Error class / severity.
71    pub class: u8,
72    /// Human-readable error message.
73    pub message: String,
74    /// Server name.
75    pub server_name: String,
76    /// Stored procedure name, when present.
77    pub procedure_name: String,
78    /// Line number reported by the server.
79    pub line_number: u32,
80}
81
82/// ENVCHANGE token data.
83#[derive(Debug, Clone, PartialEq, Eq)]
84pub enum EnvChange {
85    /// Current database changed.
86    Database(String),
87    /// Current language changed.
88    Language(String),
89    /// Current character set changed.
90    CharacterSet(String),
91    /// Server accepted a packet size.
92    PacketSize(u32),
93    /// Unicode sorting locale changed.
94    UnicodeDataSortingLocalId(String),
95    /// Unicode sorting comparison flags changed.
96    UnicodeDataSortingComparisonFlags(String),
97    /// SQL collation changed.
98    SqlCollation(Vec<u8>),
99    /// Server started a transaction and returned its descriptor.
100    BeginTransaction(u64),
101    /// Server committed a transaction.
102    CommitTransaction(u64),
103    /// Server rolled back a transaction.
104    RollbackTransaction(u64),
105    /// ENVCHANGE type not currently interpreted by this driver.
106    Ignored {
107        /// Environment change type byte.
108        change_type: u8,
109        /// Raw change payload after the type byte.
110        data: Vec<u8>,
111    },
112}
113
114/// DONE token data.
115#[derive(Debug, Clone, Copy, PartialEq, Eq)]
116pub struct Done {
117    /// DONE status bit field.
118    pub status: u16,
119    /// Current command token.
120    pub current_command: u16,
121    /// Rows affected, valid when the DONE_COUNT status bit is set.
122    pub row_count: u64,
123}
124
125/// Result of interpreting a LOGIN7 response token stream.
126#[derive(Debug, Clone, PartialEq, Eq)]
127pub enum LoginResponse {
128    /// LOGINACK was received and no ERROR token was present.
129    Success {
130        /// Accepted login metadata returned by the server.
131        login_ack: LoginAck,
132        /// Environment changes received during login.
133        env_changes: Vec<EnvChange>,
134    },
135    /// Server returned at least one ERROR token.
136    ServerError(ServerError),
137}
138
139/// Parses the bounded token subset currently needed from a tabular-result payload.
140pub fn parse_tokens(mut input: &[u8]) -> Result<Vec<Token>, TokenParseError> {
141    let mut tokens = Vec::new();
142
143    while !input.is_empty() {
144        let token_type = TokenType::from(read_u8(&mut input)?);
145
146        let token = if token_type == TokenType::LOGINACK {
147            Token::LoginAck(parse_login_ack(read_len_prefixed_token(&mut input)?)?)
148        } else if token_type == TokenType::ERROR {
149            Token::Error(parse_error(read_len_prefixed_token(&mut input)?)?)
150        } else if token_type == TokenType::INFO {
151            let _ = read_len_prefixed_token(&mut input)?;
152            continue;
153        } else if token_type == TokenType::ENVCHANGE {
154            Token::EnvChange(parse_env_change(read_len_prefixed_token(&mut input)?)?)
155        } else if token_type == TokenType::DONE {
156            Token::Done(parse_done(&mut input)?)
157        } else {
158            return Err(TokenParseError::UnsupportedToken(token_type.code()));
159        };
160
161        tokens.push(token);
162    }
163
164    Ok(tokens)
165}
166
167/// Interprets a LOGIN7 response token stream as success or server failure.
168pub fn parse_login_response(input: &[u8]) -> Result<LoginResponse, TokenParseError> {
169    let tokens = parse_tokens(input)?;
170    let mut login_ack = None;
171    let mut done = false;
172    let mut env_changes = Vec::new();
173
174    for token in tokens {
175        match token {
176            Token::LoginAck(ack) => login_ack = Some(ack),
177            Token::Error(error) => return Ok(LoginResponse::ServerError(error)),
178            Token::Done(_) => done = true,
179            Token::EnvChange(change) => env_changes.push(change),
180        }
181    }
182
183    let login_ack = login_ack.ok_or(TokenParseError::MissingLoginAck)?;
184    if !done {
185        return Err(TokenParseError::MissingDone);
186    }
187
188    Ok(LoginResponse::Success {
189        login_ack,
190        env_changes,
191    })
192}
193
194fn parse_login_ack(mut input: &[u8]) -> Result<LoginAck, TokenParseError> {
195    let interface = read_u8(&mut input)?;
196    let tds_version = read_u32_be(&mut input)?;
197    let program_name = read_b_varchar(&mut input)?;
198    let major_version = read_u8(&mut input)?;
199    let minor_version = read_u8(&mut input)?;
200    let build_number_high = read_u8(&mut input)?;
201    let build_number_low = read_u8(&mut input)?;
202    expect_empty(input)?;
203
204    Ok(LoginAck {
205        interface,
206        tds_version,
207        program_name,
208        major_version,
209        minor_version,
210        build_number_high,
211        build_number_low,
212    })
213}
214
215pub(crate) fn parse_server_error(input: &[u8]) -> Result<ServerError, TokenParseError> {
216    parse_error(input)
217}
218
219fn parse_error(mut input: &[u8]) -> Result<ServerError, TokenParseError> {
220    let number = read_i32_le(&mut input)?;
221    let state = read_u8(&mut input)?;
222    let class = read_u8(&mut input)?;
223    let message = read_us_varchar(&mut input)?;
224    let server_name = read_b_varchar(&mut input)?;
225    let procedure_name = read_b_varchar(&mut input)?;
226    let line_number = read_u32_le(&mut input)?;
227    expect_empty(input)?;
228
229    Ok(ServerError {
230        number,
231        state,
232        class,
233        message,
234        server_name,
235        procedure_name,
236        line_number,
237    })
238}
239
240pub(crate) fn parse_env_change(mut input: &[u8]) -> Result<EnvChange, TokenParseError> {
241    let change_type = read_u8(&mut input)?;
242
243    Ok(match change_type {
244        1 => EnvChange::Database(read_b_varchar(&mut input)?),
245        2 => EnvChange::Language(read_b_varchar(&mut input)?),
246        3 => EnvChange::CharacterSet(read_b_varchar(&mut input)?),
247        4 => {
248            let size = read_b_varchar(&mut input)?;
249            EnvChange::PacketSize(
250                size.parse()
251                    .map_err(|_| TokenParseError::InvalidEnvChangePacketSize(size))?,
252            )
253        }
254        5 => EnvChange::UnicodeDataSortingLocalId(read_b_varchar(&mut input)?),
255        6 => EnvChange::UnicodeDataSortingComparisonFlags(read_b_varchar(&mut input)?),
256        7 => EnvChange::SqlCollation(read_b_varbyte(&mut input)?.to_vec()),
257        8 => EnvChange::BeginTransaction(read_b_varbyte_u64_le(&mut input)?),
258        9 => EnvChange::CommitTransaction(read_transaction_end_descriptor(&mut input)?),
259        10 => EnvChange::RollbackTransaction(read_transaction_end_descriptor(&mut input)?),
260        _ => EnvChange::Ignored {
261            change_type,
262            data: input.to_vec(),
263        },
264    })
265}
266
267fn parse_done(input: &mut &[u8]) -> Result<Done, TokenParseError> {
268    Ok(Done {
269        status: read_u16_le(input)?,
270        current_command: read_u16_le(input)?,
271        row_count: read_u64_le(input)?,
272    })
273}
274
275fn read_len_prefixed_token<'a>(input: &mut &'a [u8]) -> Result<&'a [u8], TokenParseError> {
276    let len = usize::from(read_u16_le(input)?);
277    take(input, len)
278}
279
280fn read_b_varchar(input: &mut &[u8]) -> Result<String, TokenParseError> {
281    let len_chars = usize::from(read_u8(input)?);
282    read_utf16_string(input, len_chars)
283}
284
285fn read_b_varbyte<'a>(input: &mut &'a [u8]) -> Result<&'a [u8], TokenParseError> {
286    let len = usize::from(read_u8(input)?);
287    take(input, len)
288}
289
290fn read_us_varchar(input: &mut &[u8]) -> Result<String, TokenParseError> {
291    let len_chars = usize::from(read_u16_le(input)?);
292    read_utf16_string(input, len_chars)
293}
294
295fn read_utf16_string(input: &mut &[u8], len_chars: usize) -> Result<String, TokenParseError> {
296    let len_bytes = len_chars
297        .checked_mul(2)
298        .ok_or(TokenParseError::LengthOverflow)?;
299    let bytes = take(input, len_bytes)?;
300    let units = bytes
301        .as_chunks::<2>()
302        .0
303        .iter()
304        .copied()
305        .map(u16::from_le_bytes);
306
307    String::from_utf16(&units.collect::<Vec<_>>()).map_err(|_| TokenParseError::InvalidUtf16)
308}
309
310fn read_u8(input: &mut &[u8]) -> Result<u8, TokenParseError> {
311    let bytes = take(input, 1)?;
312    Ok(bytes[0])
313}
314
315fn read_u16_le(input: &mut &[u8]) -> Result<u16, TokenParseError> {
316    let bytes = take(input, 2)?;
317    Ok(u16::from_le_bytes([bytes[0], bytes[1]]))
318}
319
320fn read_i32_le(input: &mut &[u8]) -> Result<i32, TokenParseError> {
321    let bytes = take(input, 4)?;
322    Ok(i32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
323}
324
325fn read_u32_le(input: &mut &[u8]) -> Result<u32, TokenParseError> {
326    let bytes = take(input, 4)?;
327    Ok(u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
328}
329
330fn read_u32_be(input: &mut &[u8]) -> Result<u32, TokenParseError> {
331    let bytes = take(input, 4)?;
332    Ok(u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
333}
334
335fn read_u64_le(input: &mut &[u8]) -> Result<u64, TokenParseError> {
336    let bytes = take(input, 8)?;
337    Ok(u64::from_le_bytes([
338        bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
339    ]))
340}
341
342fn read_b_varbyte_u64_le(input: &mut &[u8]) -> Result<u64, TokenParseError> {
343    let mut bytes = read_b_varbyte(input)?;
344    read_u64_le(&mut bytes)
345}
346
347fn read_transaction_end_descriptor(input: &mut &[u8]) -> Result<u64, TokenParseError> {
348    let _new_descriptor = read_b_varbyte(input)?;
349    read_u64_le(input)
350}
351
352fn take<'a>(input: &mut &'a [u8], len: usize) -> Result<&'a [u8], TokenParseError> {
353    let bytes = input.get(..len).ok_or(TokenParseError::UnexpectedEof)?;
354    *input = &input[len..];
355    Ok(bytes)
356}
357
358fn expect_empty(input: &[u8]) -> Result<(), TokenParseError> {
359    if input.is_empty() {
360        Ok(())
361    } else {
362        Err(TokenParseError::TrailingTokenBytes(input.len()))
363    }
364}
365
366/// Error returned while parsing a bounded TDS token stream.
367#[derive(Debug, Error, PartialEq, Eq)]
368pub enum TokenParseError {
369    /// The token stream ended in the middle of a token.
370    #[error("TDS token stream ended before the current token was complete")]
371    UnexpectedEof,
372    /// A token advertised a length that cannot be represented safely.
373    #[error("TDS token length overflowed")]
374    LengthOverflow,
375    /// A token contained invalid UTF-16 string data.
376    #[error("TDS token contained invalid UTF-16 string data")]
377    InvalidUtf16,
378    /// This bounded parser does not yet understand the token type.
379    #[error("unsupported TDS token 0x{0:02x}")]
380    UnsupportedToken(u8),
381    /// A length-prefixed token contained extra bytes after its expected fields.
382    #[error("TDS token contained {0} trailing bytes")]
383    TrailingTokenBytes(usize),
384    /// A LOGIN7 response did not include LOGINACK.
385    #[error("TDS login response did not include LOGINACK")]
386    MissingLoginAck,
387    /// A LOGIN7 response did not include DONE.
388    #[error("TDS login response did not include DONE")]
389    MissingDone,
390    /// ENVCHANGE packet size was not a decimal integer.
391    #[error("TDS ENVCHANGE packet size `{0}` is not a valid integer")]
392    InvalidEnvChangePacketSize(String),
393}
394
395#[cfg(test)]
396mod tests {
397    use super::*;
398
399    #[test]
400    fn parses_login_ack_envchange_and_done_as_success() {
401        let bytes = [
402            login_ack("Microsoft SQL Server"),
403            env_change(
404                4,
405                &[
406                    4, b'4', 0, b'0', 0, b'9', 0, b'6', 0, 3, b'5', 0, b'1', 0, b'2', 0,
407                ],
408            ),
409            done(0, 0, 0),
410        ]
411        .concat();
412
413        let tokens = parse_tokens(&bytes).unwrap();
414
415        assert_eq!(3, tokens.len());
416        assert_eq!(
417            LoginResponse::Success {
418                login_ack: LoginAck {
419                    interface: 1,
420                    tds_version: 0x7400_0004,
421                    program_name: "Microsoft SQL Server".to_owned(),
422                    major_version: 16,
423                    minor_version: 0,
424                    build_number_high: 0x10,
425                    build_number_low: 0x4a,
426                },
427                env_changes: vec![EnvChange::PacketSize(4096)],
428            },
429            parse_login_response(&bytes).unwrap()
430        );
431    }
432
433    #[test]
434    fn parses_transaction_envchanges() {
435        assert_eq!(
436            EnvChange::BeginTransaction(0x0102_0304_0506_0708),
437            parse_env_change(&[8, 8, 8, 7, 6, 5, 4, 3, 2, 1,]).unwrap()
438        );
439        assert_eq!(
440            EnvChange::CommitTransaction(0x1112_1314_1516_1718),
441            parse_env_change(&[9, 0, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11,]).unwrap()
442        );
443        assert_eq!(
444            EnvChange::RollbackTransaction(0x2122_2324_2526_2728),
445            parse_env_change(&[10, 0, 0x28, 0x27, 0x26, 0x25, 0x24, 0x23, 0x22, 0x21,]).unwrap()
446        );
447    }
448
449    #[test]
450    fn reports_server_error_before_done() {
451        let bytes = [
452            error(18456, 1, 14, "Login failed", "dbhost", "", 1),
453            done(0x0002, 0, 0),
454        ]
455        .concat();
456
457        assert_eq!(
458            LoginResponse::ServerError(ServerError {
459                number: 18456,
460                state: 1,
461                class: 14,
462                message: "Login failed".to_owned(),
463                server_name: "dbhost".to_owned(),
464                procedure_name: String::new(),
465                line_number: 1,
466            }),
467            parse_login_response(&bytes).unwrap()
468        );
469    }
470
471    #[test]
472    fn skips_info_tokens_during_login() {
473        let bytes = [
474            len_prefixed(
475                TokenType::INFO,
476                error_body(5701, 1, 10, "Changed database", "", "", 1),
477            ),
478            login_ack("Microsoft SQL Server"),
479            done(0, 0, 0),
480        ]
481        .concat();
482
483        assert!(matches!(
484            parse_login_response(&bytes).unwrap(),
485            LoginResponse::Success { .. }
486        ));
487    }
488
489    #[test]
490    fn rejects_truncated_login_ack() {
491        let bytes = [TokenType::LOGINACK.code(), 10, 0, 1, 0x74];
492
493        assert_eq!(
494            TokenParseError::UnexpectedEof,
495            parse_tokens(&bytes).unwrap_err()
496        );
497    }
498
499    #[test]
500    fn rejects_unsupported_tokens_in_bounded_parser() {
501        let bytes = [0xac, 0, 0];
502
503        assert_eq!(
504            TokenParseError::UnsupportedToken(0xac),
505            parse_tokens(&bytes).unwrap_err()
506        );
507    }
508
509    #[test]
510    fn login_response_requires_login_ack_when_no_error_is_present() {
511        let bytes = done(0, 0, 0);
512
513        assert_eq!(
514            TokenParseError::MissingLoginAck,
515            parse_login_response(&bytes).unwrap_err()
516        );
517    }
518
519    #[test]
520    fn login_response_success_requires_done() {
521        let bytes = login_ack("Microsoft SQL Server");
522
523        assert_eq!(
524            TokenParseError::MissingDone,
525            parse_login_response(&bytes).unwrap_err()
526        );
527    }
528
529    fn login_ack(program_name: &str) -> Vec<u8> {
530        let mut body = Vec::new();
531        body.push(1);
532        body.extend_from_slice(&0x7400_0004u32.to_be_bytes());
533        push_b_varchar(&mut body, program_name);
534        body.extend_from_slice(&[16, 0, 0x10, 0x4a]);
535
536        len_prefixed(TokenType::LOGINACK, body)
537    }
538
539    fn error(
540        number: i32,
541        state: u8,
542        class: u8,
543        message: &str,
544        server_name: &str,
545        procedure_name: &str,
546        line_number: u32,
547    ) -> Vec<u8> {
548        len_prefixed(
549            TokenType::ERROR,
550            error_body(
551                number,
552                state,
553                class,
554                message,
555                server_name,
556                procedure_name,
557                line_number,
558            ),
559        )
560    }
561
562    fn error_body(
563        number: i32,
564        state: u8,
565        class: u8,
566        message: &str,
567        server_name: &str,
568        procedure_name: &str,
569        line_number: u32,
570    ) -> Vec<u8> {
571        let mut body = Vec::new();
572        body.extend_from_slice(&number.to_le_bytes());
573        body.push(state);
574        body.push(class);
575        push_us_varchar(&mut body, message);
576        push_b_varchar(&mut body, server_name);
577        push_b_varchar(&mut body, procedure_name);
578        body.extend_from_slice(&line_number.to_le_bytes());
579        body
580    }
581
582    fn env_change(change_type: u8, data: &[u8]) -> Vec<u8> {
583        let mut body = Vec::with_capacity(1 + data.len());
584        body.push(change_type);
585        body.extend_from_slice(data);
586
587        len_prefixed(TokenType::ENVCHANGE, body)
588    }
589
590    fn done(status: u16, current_command: u16, row_count: u64) -> Vec<u8> {
591        let mut out = Vec::new();
592        out.push(TokenType::DONE.code());
593        out.extend_from_slice(&status.to_le_bytes());
594        out.extend_from_slice(&current_command.to_le_bytes());
595        out.extend_from_slice(&row_count.to_le_bytes());
596        out
597    }
598
599    fn len_prefixed(token_type: TokenType, body: Vec<u8>) -> Vec<u8> {
600        let mut out = Vec::new();
601        out.push(token_type.code());
602        out.extend_from_slice(
603            &u16::try_from(body.len())
604                .expect("test token body fits in u16")
605                .to_le_bytes(),
606        );
607        out.extend_from_slice(&body);
608        out
609    }
610
611    fn push_b_varchar(out: &mut Vec<u8>, value: &str) {
612        out.push(u8::try_from(value.encode_utf16().count()).expect("test string fits in u8"));
613        push_utf16(out, value);
614    }
615
616    fn push_us_varchar(out: &mut Vec<u8>, value: &str) {
617        out.extend_from_slice(
618            &u16::try_from(value.encode_utf16().count())
619                .expect("test string fits in u16")
620                .to_le_bytes(),
621        );
622        push_utf16(out, value);
623    }
624
625    fn push_utf16(out: &mut Vec<u8>, value: &str) {
626        for unit in value.encode_utf16() {
627            out.extend_from_slice(&unit.to_le_bytes());
628        }
629    }
630}