mssql-codec

Part of the rust-mssql-driver project.

Async framing layer for TDS packet handling.

Overview

This crate transforms raw byte streams into high-level TDS packets, handling packet reassembly across TCP segment boundaries and packet continuation for large messages. It sits between the raw TCP/TLS stream and the higher-level client.

Architecture

TCP Stream -> TdsCodec (packet framing) -> MessageAssembler -> Client

Features

• Packet reassembly - Handles packets split across TCP segments
• Message reassembly - Combines multi-packet messages (EOM bit handling)
• IO splitting - Separate read/write halves for cancellation safety (ADR-005)
• Tokio-util codec - Integrates with tokio-util's codec framework
• Zero-copy where possible - Minimizes buffer copies

Cancellation Safety

Per ADR-005, the connection splits the TCP stream into read and write halves. This allows sending Attention packets for query cancellation even while blocked reading a large result set.

use mssql_codec::Connection;

let conn = Connection::new(tcp_stream);
let cancel = conn.cancel_handle();

// Cancel from another task
tokio::spawn(async move {
    cancel.cancel().await?;
});

Usage

This crate is primarily used internally by mssql-client. Direct usage is for advanced scenarios:

use mssql_codec::{TdsCodec, Packet, Message, MessageAssembler};
use tokio_util::codec::Framed;

// Create a framed codec over a TCP stream
let framed = Framed::new(tcp_stream, TdsCodec::new());

// Or use the Connection wrapper for more features
let conn = Connection::new(tcp_stream);

Modules

Key Types

TDS Packet Structure

+--------+--------+--------+--------+--------+--------+--------+--------+
| Type   | Status | Length (2)      | SPID (2)        | Pkt# | Window |
+--------+--------+--------+--------+--------+--------+--------+--------+
|                           Payload Data                                |
|                              ...                                      |
+-----------------------------------------------------------------------+

• Type: Packet type (PreLogin, Login7, SQLBatch, RPC, etc.)
• Status: Flags including EOM (End of Message)
• Length: Total packet length including header
• SPID: Server Process ID
• Packet Number: For multi-packet messages
• Window: Reserved (always 0)

License

MIT OR Apache-2.0