Skip to main content

halephant_core/proto/
backend.rs

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