Skip to main content

halephant_core/proto/
backend.rs

1use bytes::{BufMut, BytesMut};
2use chumsky::prelude::*;
3use chumsky::span::SimpleSpan;
4
5use crate::errors;
6use crate::proto::coding;
7use crate::proto::parser;
8use crate::proto::primitives;
9use crate::proto::types;
10
11// ---------------------------------------------------------------------------
12// Message types
13// ---------------------------------------------------------------------------
14
15/// A message sent by a PostgreSQL backend (server → client).
16#[derive(Debug, Clone, PartialEq)]
17pub enum BackendMessage {
18    // -- Authentication --
19    AuthenticationOk,
20    AuthenticationCleartextPassword,
21    AuthenticationMd5Password { salt: [u8; 4] },
22    AuthenticationSasl { mechanisms: Vec<String> },
23    AuthenticationSaslContinue { data: Vec<u8> },
24    AuthenticationSaslFinal { data: Vec<u8> },
25
26    // -- Key exchange --
27    BackendKeyData { process_id: i32, secret_key: i32 },
28
29    // -- Command lifecycle --
30    ParseComplete,
31    BindComplete,
32    CloseComplete,
33    NoData,
34    PortalSuspended,
35    EmptyQueryResponse,
36    CommandComplete(String),
37
38    // -- Query results --
39    RowDescription(Vec<FieldDescription>),
40    DataRow(Vec<Option<Vec<u8>>>),
41    ParameterDescription(Vec<types::Oid>),
42
43    // -- Session state --
44    ParameterStatus { name: String, value: String },
45    ReadyForQuery(types::TransactionStatus),
46
47    // -- COPY --
48    CopyInResponse(CopyResponse),
49    CopyOutResponse(CopyResponse),
50    CopyBothResponse(CopyResponse),
51    CopyData(Vec<u8>),
52    CopyDone,
53
54    // -- Errors and notices --
55    ErrorResponse(NoticeFields),
56    NoticeResponse(NoticeFields),
57
58    // -- Async notifications --
59    NotificationResponse(Notification),
60}
61
62#[derive(Debug, Clone, PartialEq)]
63pub struct FieldDescription {
64    pub name: String,
65    pub table_oid: types::Oid,
66    pub column_id: i16,
67    pub type_oid: types::Oid,
68    pub type_size: i16,
69    pub type_modifier: i32,
70    pub format: types::FormatCode,
71}
72
73#[derive(Debug, Clone, PartialEq)]
74pub struct CopyResponse {
75    pub format: types::FormatCode,
76    pub column_formats: Vec<types::FormatCode>,
77}
78
79#[derive(Debug, Clone, PartialEq)]
80pub struct Notification {
81    pub process_id: i32,
82    pub channel: String,
83    pub payload: String,
84}
85
86/// Tagged field list used by `ErrorResponse` and `NoticeResponse`.
87#[derive(Debug, Clone, PartialEq)]
88pub struct NoticeFields {
89    pub fields: Vec<(u8, String)>,
90}
91
92impl NoticeFields {
93    pub fn severity(&self) -> Option<&str> {
94        self.get(b'S')
95    }
96    pub fn code(&self) -> Option<&str> {
97        self.get(b'C')
98    }
99    pub fn message(&self) -> Option<&str> {
100        self.get(b'M')
101    }
102    pub fn detail(&self) -> Option<&str> {
103        self.get(b'D')
104    }
105    pub fn hint(&self) -> Option<&str> {
106        self.get(b'H')
107    }
108
109    fn get(&self, tag: u8) -> Option<&str> {
110        self.fields
111            .iter()
112            .find(|(t, _)| *t == tag)
113            .map(|(_, v)| v.as_str())
114    }
115}
116
117// ---------------------------------------------------------------------------
118// Chumsky parsers
119// ---------------------------------------------------------------------------
120
121fn authentication<'src>() -> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>> {
122    custom(|inp| {
123        let auth_type: i32 = inp.parse(primitives::pg_int32())?;
124        match auth_type {
125            0 => Ok(BackendMessage::AuthenticationOk),
126            3 => Ok(BackendMessage::AuthenticationCleartextPassword),
127            5 => {
128                let salt = [
129                    inp.parse(any())?,
130                    inp.parse(any())?,
131                    inp.parse(any())?,
132                    inp.parse(any())?,
133                ];
134                Ok(BackendMessage::AuthenticationMd5Password { salt })
135            }
136            10 => {
137                let mut mechanisms = Vec::new();
138                loop {
139                    let mech: String = inp.parse(primitives::pg_cstring())?;
140                    if mech.is_empty() {
141                        break;
142                    }
143                    mechanisms.push(mech);
144                }
145                Ok(BackendMessage::AuthenticationSasl { mechanisms })
146            }
147            11 => {
148                let data = inp.parse(any().repeated().collect::<Vec<u8>>())?;
149                Ok(BackendMessage::AuthenticationSaslContinue { data })
150            }
151            12 => {
152                let data = inp.parse(any().repeated().collect::<Vec<u8>>())?;
153                Ok(BackendMessage::AuthenticationSaslFinal { data })
154            }
155            _ => Err(Rich::custom(
156                SimpleSpan::new(0, 4),
157                format!("unknown authentication type: {auth_type}"),
158            )),
159        }
160    })
161}
162
163fn backend_key_data<'src>() -> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>>
164{
165    primitives::pg_int32()
166        .then(primitives::pg_int32())
167        .map(|(process_id, secret_key)| BackendMessage::BackendKeyData {
168            process_id,
169            secret_key,
170        })
171}
172
173fn command_complete<'src>() -> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>>
174{
175    primitives::pg_cstring().map(BackendMessage::CommandComplete)
176}
177
178fn data_row<'src>() -> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>> {
179    primitives::pg_count_prefixed(primitives::pg_nullable_bytes()).map(BackendMessage::DataRow)
180}
181
182fn row_description<'src>() -> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>> {
183    primitives::pg_count_prefixed(custom(|inp| {
184        let name = inp.parse(primitives::pg_cstring())?;
185        let table_oid = inp.parse(primitives::pg_int32())? as u32;
186        let column_id = inp.parse(primitives::pg_int16())?;
187        let type_oid = inp.parse(primitives::pg_int32())? as u32;
188        let type_size = inp.parse(primitives::pg_int16())?;
189        let type_modifier = inp.parse(primitives::pg_int32())?;
190        let format = inp.parse(primitives::pg_format_code())?;
191        Ok(FieldDescription {
192            name,
193            table_oid,
194            column_id,
195            type_oid,
196            type_size,
197            type_modifier,
198            format,
199        })
200    }))
201    .map(BackendMessage::RowDescription)
202}
203
204fn parameter_status<'src>() -> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>>
205{
206    primitives::pg_cstring()
207        .then(primitives::pg_cstring())
208        .map(|(name, value)| BackendMessage::ParameterStatus { name, value })
209}
210
211fn parameter_description<'src>()
212-> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>> {
213    primitives::pg_count_prefixed(primitives::pg_int32().map(|v| v as u32))
214        .map(BackendMessage::ParameterDescription)
215}
216
217fn ready_for_query<'src>() -> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>> {
218    any()
219        .try_map(|b, span| match b {
220            b'I' => Ok(types::TransactionStatus::Idle),
221            b'T' => Ok(types::TransactionStatus::InTransaction),
222            b'E' => Ok(types::TransactionStatus::Failed),
223            _ => Err(Rich::custom(
224                span,
225                format!("unknown transaction status: {b:#04x}"),
226            )),
227        })
228        .map(BackendMessage::ReadyForQuery)
229}
230
231fn notification<'src>() -> impl Parser<'src, &'src [u8], BackendMessage, parser::PgExtra<'src>> {
232    primitives::pg_int32()
233        .then(primitives::pg_cstring())
234        .then(primitives::pg_cstring())
235        .map(|((process_id, channel), payload)| {
236            BackendMessage::NotificationResponse(Notification {
237                process_id,
238                channel,
239                payload,
240            })
241        })
242}
243
244fn notice_fields<'src>() -> impl Parser<'src, &'src [u8], NoticeFields, parser::PgExtra<'src>> {
245    custom(|inp| {
246        let mut fields = Vec::new();
247        loop {
248            let tag: u8 = inp.parse(any())?;
249            if tag == 0 {
250                break;
251            }
252            let value: String = inp.parse(primitives::pg_cstring())?;
253            fields.push((tag, value));
254        }
255        Ok(NoticeFields { fields })
256    })
257}
258
259fn copy_response<'src>() -> impl Parser<'src, &'src [u8], CopyResponse, parser::PgExtra<'src>> {
260    any()
261        .try_map(|b, span| match b {
262            0 => Ok(types::FormatCode::Text),
263            1 => Ok(types::FormatCode::Binary),
264            _ => Err(Rich::custom(
265                span,
266                format!("invalid overall format code: {b}"),
267            )),
268        })
269        .then(primitives::pg_count_prefixed(primitives::pg_format_code()))
270        .map(|(format, column_formats)| CopyResponse {
271            format,
272            column_formats,
273        })
274}
275
276// ---------------------------------------------------------------------------
277// Public parse API
278// ---------------------------------------------------------------------------
279
280impl BackendMessage {
281    /// Parse a backend message.
282    ///
283    /// `msg_type` is the leading type byte; `payload` is everything after the
284    /// 4-byte length field.
285    pub fn parse(msg_type: u8, payload: &[u8]) -> Result<Self, errors::ProtocolError> {
286        match msg_type {
287            b'1' => Ok(BackendMessage::ParseComplete),
288            b'2' => Ok(BackendMessage::BindComplete),
289            b'3' => Ok(BackendMessage::CloseComplete),
290            b'A' => parser::run(notification(), payload),
291            b'C' => parser::run(command_complete(), payload),
292            b'c' => Ok(BackendMessage::CopyDone),
293            b'd' => Ok(BackendMessage::CopyData(payload.to_vec())),
294            b'D' => parser::run(data_row(), payload),
295            b'E' => parser::run(notice_fields().map(BackendMessage::ErrorResponse), payload),
296            b'G' => parser::run(copy_response().map(BackendMessage::CopyInResponse), payload),
297            b'H' => parser::run(
298                copy_response().map(BackendMessage::CopyOutResponse),
299                payload,
300            ),
301            b'I' => Ok(BackendMessage::EmptyQueryResponse),
302            b'K' => parser::run(backend_key_data(), payload),
303            b'n' => Ok(BackendMessage::NoData),
304            b'N' => parser::run(notice_fields().map(BackendMessage::NoticeResponse), payload),
305            b'R' => parser::run(authentication(), payload),
306            b's' => Ok(BackendMessage::PortalSuspended),
307            b'S' => parser::run(parameter_status(), payload),
308            b't' => parser::run(parameter_description(), payload),
309            b'T' => parser::run(row_description(), payload),
310            b'W' => parser::run(
311                copy_response().map(BackendMessage::CopyBothResponse),
312                payload,
313            ),
314            b'Z' => parser::run(ready_for_query(), payload),
315            _ => Err(errors::ProtocolError::UnknownMessageType(msg_type)),
316        }
317    }
318}
319
320// ---------------------------------------------------------------------------
321// Encoding
322// ---------------------------------------------------------------------------
323
324impl BackendMessage {
325    /// Encode this message into `dst` in PostgreSQL wire format.
326    pub fn encode(&self, dst: &mut BytesMut) {
327        match self {
328            BackendMessage::AuthenticationOk => coding::encode_message(dst, b'R', |dst| {
329                dst.put_i32(0);
330            }),
331            BackendMessage::AuthenticationCleartextPassword => {
332                coding::encode_message(dst, b'R', |dst| {
333                    dst.put_i32(3);
334                });
335            }
336            BackendMessage::AuthenticationMd5Password { salt } => {
337                coding::encode_message(dst, b'R', |dst| {
338                    dst.put_i32(5);
339                    dst.extend_from_slice(salt);
340                });
341            }
342            BackendMessage::AuthenticationSasl { mechanisms } => {
343                coding::encode_message(dst, b'R', |dst| {
344                    dst.put_i32(10);
345                    for mech in mechanisms {
346                        coding::encode_cstring(dst, mech);
347                    }
348                    dst.put_u8(0); // trailing null
349                });
350            }
351            BackendMessage::AuthenticationSaslContinue { data } => {
352                coding::encode_message(dst, b'R', |dst| {
353                    dst.put_i32(11);
354                    dst.extend_from_slice(data);
355                });
356            }
357            BackendMessage::AuthenticationSaslFinal { data } => {
358                coding::encode_message(dst, b'R', |dst| {
359                    dst.put_i32(12);
360                    dst.extend_from_slice(data);
361                });
362            }
363
364            BackendMessage::BackendKeyData {
365                process_id,
366                secret_key,
367            } => coding::encode_message(dst, b'K', |dst| {
368                dst.put_i32(*process_id);
369                dst.put_i32(*secret_key);
370            }),
371
372            BackendMessage::ParseComplete => coding::encode_message(dst, b'1', |_| {}),
373            BackendMessage::BindComplete => coding::encode_message(dst, b'2', |_| {}),
374            BackendMessage::CloseComplete => coding::encode_message(dst, b'3', |_| {}),
375            BackendMessage::NoData => coding::encode_message(dst, b'n', |_| {}),
376            BackendMessage::PortalSuspended => coding::encode_message(dst, b's', |_| {}),
377            BackendMessage::EmptyQueryResponse => coding::encode_message(dst, b'I', |_| {}),
378            BackendMessage::CopyDone => coding::encode_message(dst, b'c', |_| {}),
379
380            BackendMessage::CommandComplete(tag) => coding::encode_message(dst, b'C', |dst| {
381                coding::encode_cstring(dst, tag);
382            }),
383
384            BackendMessage::RowDescription(fields) => coding::encode_message(dst, b'T', |dst| {
385                coding::encode_count_prefixed(dst, fields, |dst, f| {
386                    coding::encode_cstring(dst, &f.name);
387                    dst.put_i32(f.table_oid as i32);
388                    dst.put_i16(f.column_id);
389                    dst.put_i32(f.type_oid as i32);
390                    dst.put_i16(f.type_size);
391                    dst.put_i32(f.type_modifier);
392                    dst.put_i16(f.format as i16);
393                });
394            }),
395
396            BackendMessage::DataRow(columns) => coding::encode_message(dst, b'D', |dst| {
397                coding::encode_count_prefixed(dst, columns, |dst, col| match col {
398                    None => dst.put_i32(-1),
399                    Some(data) => {
400                        dst.put_i32(data.len() as i32);
401                        dst.extend_from_slice(data);
402                    }
403                });
404            }),
405
406            BackendMessage::ParameterDescription(oids) => {
407                coding::encode_message(dst, b't', |dst| {
408                    coding::encode_count_prefixed(dst, oids, |dst, oid| {
409                        dst.put_i32(*oid as i32);
410                    });
411                });
412            }
413
414            BackendMessage::ParameterStatus { name, value } => {
415                coding::encode_message(dst, b'S', |dst| {
416                    coding::encode_cstring(dst, name);
417                    coding::encode_cstring(dst, value);
418                });
419            }
420
421            BackendMessage::ReadyForQuery(status) => coding::encode_message(dst, b'Z', |dst| {
422                dst.put_u8(match status {
423                    types::TransactionStatus::Idle => b'I',
424                    types::TransactionStatus::InTransaction => b'T',
425                    types::TransactionStatus::Failed => b'E',
426                });
427            }),
428
429            BackendMessage::CopyInResponse(cr) => coding::encode_message(dst, b'G', |dst| {
430                encode_copy_response(dst, cr);
431            }),
432            BackendMessage::CopyOutResponse(cr) => coding::encode_message(dst, b'H', |dst| {
433                encode_copy_response(dst, cr);
434            }),
435            BackendMessage::CopyBothResponse(cr) => coding::encode_message(dst, b'W', |dst| {
436                encode_copy_response(dst, cr);
437            }),
438
439            BackendMessage::CopyData(data) => coding::encode_message(dst, b'd', |dst| {
440                dst.extend_from_slice(data);
441            }),
442
443            BackendMessage::ErrorResponse(fields) => coding::encode_message(dst, b'E', |dst| {
444                encode_notice_fields(dst, fields);
445            }),
446            BackendMessage::NoticeResponse(fields) => coding::encode_message(dst, b'N', |dst| {
447                encode_notice_fields(dst, fields);
448            }),
449
450            BackendMessage::NotificationResponse(n) => coding::encode_message(dst, b'A', |dst| {
451                dst.put_i32(n.process_id);
452                coding::encode_cstring(dst, &n.channel);
453                coding::encode_cstring(dst, &n.payload);
454            }),
455        }
456    }
457}
458
459fn encode_notice_fields(dst: &mut BytesMut, fields: &NoticeFields) {
460    for (tag, value) in &fields.fields {
461        dst.put_u8(*tag);
462        coding::encode_cstring(dst, value);
463    }
464    dst.put_u8(0); // terminator
465}
466
467fn encode_copy_response(dst: &mut BytesMut, cr: &CopyResponse) {
468    dst.put_u8(cr.format as u8);
469    coding::encode_count_prefixed(dst, &cr.column_formats, |dst, fc| {
470        dst.put_i16(*fc as i16);
471    });
472}