thrift/protocol/
mod.rs

Help
1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Types used to send and receive primitives between a Thrift client and server.
19//!
20//! # Examples
21//!
22//! Create and use a `TInputProtocol`.
23//!
24//! ```no_run
25//! use thrift::protocol::{TBinaryInputProtocol, TInputProtocol};
26//! use thrift::transport::TTcpChannel;
27//!
28//! // create the I/O channel
29//! let mut channel = TTcpChannel::new();
30//! channel.open("127.0.0.1:9090").unwrap();
31//!
32//! // create the protocol to decode bytes into types
33//! let mut protocol = TBinaryInputProtocol::new(channel, true);
34//!
35//! // read types from the wire
36//! let field_identifier = protocol.read_field_begin().unwrap();
37//! let field_contents = protocol.read_string().unwrap();
38//! let field_end = protocol.read_field_end().unwrap();
39//! ```
40//!
41//! Create and use a `TOutputProtocol`.
42//!
43//! ```no_run
44//! use thrift::protocol::{TBinaryOutputProtocol, TFieldIdentifier, TOutputProtocol, TType};
45//! use thrift::transport::TTcpChannel;
46//!
47//! // create the I/O channel
48//! let mut channel = TTcpChannel::new();
49//! channel.open("127.0.0.1:9090").unwrap();
50//!
51//! // create the protocol to encode types into bytes
52//! let mut protocol = TBinaryOutputProtocol::new(channel, true);
53//!
54//! // write types
55//! protocol.write_field_begin(&TFieldIdentifier::new("string_thing", TType::String, 1)).unwrap();
56//! protocol.write_string("foo").unwrap();
57//! protocol.write_field_end().unwrap();
58//! ```
59
60use std::convert::{From, TryFrom};
61use std::fmt;
62use std::fmt::{Display, Formatter};
63
64use crate::transport::{TReadTransport, TWriteTransport};
65use crate::{ProtocolError, ProtocolErrorKind};
66
67#[cfg(test)]
68macro_rules! assert_eq_written_bytes {
69    ($o_prot:ident, $expected_bytes:ident) => {{
70        assert_eq!($o_prot.transport.write_bytes(), &$expected_bytes);
71    }};
72}
73
74// FIXME: should take both read and write
75#[cfg(test)]
76macro_rules! copy_write_buffer_to_read_buffer {
77    ($o_prot:ident) => {{
78        $o_prot.transport.copy_write_buffer_to_read_buffer();
79    }};
80}
81
82#[cfg(test)]
83macro_rules! set_readable_bytes {
84    ($i_prot:ident, $bytes:expr) => {
85        $i_prot.transport.set_readable_bytes($bytes);
86    };
87}
88
89mod binary;
90mod compact;
91mod multiplexed;
92mod stored;
93
94pub use self::binary::{
95    TBinaryInputProtocol, TBinaryInputProtocolFactory, TBinaryOutputProtocol,
96    TBinaryOutputProtocolFactory,
97};
98pub use self::compact::{
99    TCompactInputProtocol, TCompactInputProtocolFactory, TCompactOutputProtocol,
100    TCompactOutputProtocolFactory,
101};
102pub use self::multiplexed::TMultiplexedOutputProtocol;
103pub use self::stored::TStoredInputProtocol;
104
105/// Reads and writes the struct to Thrift protocols.
106///
107/// It is implemented in generated code for Thrift `struct`, `union`, and `enum` types.
108pub trait TSerializable: Sized {
109    fn read_from_in_protocol(i_prot: &mut dyn TInputProtocol) -> crate::Result<Self>;
110    fn write_to_out_protocol(&self, o_prot: &mut dyn TOutputProtocol) -> crate::Result<()>;
111}
112
113// Default maximum depth to which `TInputProtocol::skip` will skip a Thrift
114// field. A default is necessary because Thrift structs or collections may
115// contain nested structs and collections, which could result in indefinite
116// recursion.
117const MAXIMUM_SKIP_DEPTH: i8 = 64;
118
119/// Converts a stream of bytes into Thrift identifiers, primitives,
120/// containers, or structs.
121///
122/// This trait does not deal with higher-level Thrift concepts like structs or
123/// exceptions - only with primitives and message or container boundaries. Once
124/// bytes are read they are deserialized and an identifier (for example
125/// `TMessageIdentifier`) or a primitive is returned.
126///
127/// All methods return a `thrift::Result`. If an `Err` is returned the protocol
128/// instance and its underlying transport should be terminated.
129///
130/// # Examples
131///
132/// Create and use a `TInputProtocol`
133///
134/// ```no_run
135/// use thrift::protocol::{TBinaryInputProtocol, TInputProtocol};
136/// use thrift::transport::TTcpChannel;
137///
138/// let mut channel = TTcpChannel::new();
139/// channel.open("127.0.0.1:9090").unwrap();
140///
141/// let mut protocol = TBinaryInputProtocol::new(channel, true);
142///
143/// let field_identifier = protocol.read_field_begin().unwrap();
144/// let field_contents = protocol.read_string().unwrap();
145/// let field_end = protocol.read_field_end().unwrap();
146/// ```
147pub trait TInputProtocol {
148    /// Read the beginning of a Thrift message.
149    fn read_message_begin(&mut self) -> crate::Result<TMessageIdentifier>;
150    /// Read the end of a Thrift message.
151    fn read_message_end(&mut self) -> crate::Result<()>;
152    /// Read the beginning of a Thrift struct.
153    fn read_struct_begin(&mut self) -> crate::Result<Option<TStructIdentifier>>;
154    /// Read the end of a Thrift struct.
155    fn read_struct_end(&mut self) -> crate::Result<()>;
156    /// Read the beginning of a Thrift struct field.
157    fn read_field_begin(&mut self) -> crate::Result<TFieldIdentifier>;
158    /// Read the end of a Thrift struct field.
159    fn read_field_end(&mut self) -> crate::Result<()>;
160    /// Read a bool.
161    fn read_bool(&mut self) -> crate::Result<bool>;
162    /// Read a fixed-length byte array.
163    fn read_bytes(&mut self) -> crate::Result<Vec<u8>>;
164    /// Read a word.
165    fn read_i8(&mut self) -> crate::Result<i8>;
166    /// Read a 16-bit signed integer.
167    fn read_i16(&mut self) -> crate::Result<i16>;
168    /// Read a 32-bit signed integer.
169    fn read_i32(&mut self) -> crate::Result<i32>;
170    /// Read a 64-bit signed integer.
171    fn read_i64(&mut self) -> crate::Result<i64>;
172    /// Read a 64-bit float.
173    fn read_double(&mut self) -> crate::Result<f64>;
174    /// Read a fixed-length string (not null terminated).
175    fn read_string(&mut self) -> crate::Result<String>;
176    /// Read the beginning of a list.
177    fn read_list_begin(&mut self) -> crate::Result<TListIdentifier>;
178    /// Read the end of a list.
179    fn read_list_end(&mut self) -> crate::Result<()>;
180    /// Read the beginning of a set.
181    fn read_set_begin(&mut self) -> crate::Result<TSetIdentifier>;
182    /// Read the end of a set.
183    fn read_set_end(&mut self) -> crate::Result<()>;
184    /// Read the beginning of a map.
185    fn read_map_begin(&mut self) -> crate::Result<TMapIdentifier>;
186    /// Read the end of a map.
187    fn read_map_end(&mut self) -> crate::Result<()>;
188    /// Skip a field with type `field_type` recursively until the default
189    /// maximum skip depth is reached.
190    fn skip(&mut self, field_type: TType) -> crate::Result<()> {
191        self.skip_till_depth(field_type, MAXIMUM_SKIP_DEPTH)
192    }
193    /// Skip a field with type `field_type` recursively up to `depth` levels.
194    fn skip_till_depth(&mut self, field_type: TType, depth: i8) -> crate::Result<()> {
195        if depth == 0 {
196            return Err(crate::Error::Protocol(ProtocolError {
197                kind: ProtocolErrorKind::DepthLimit,
198                message: format!("cannot parse past {:?}", field_type),
199            }));
200        }
201
202        match field_type {
203            TType::Bool => self.read_bool().map(|_| ()),
204            TType::I08 => self.read_i8().map(|_| ()),
205            TType::I16 => self.read_i16().map(|_| ()),
206            TType::I32 => self.read_i32().map(|_| ()),
207            TType::I64 => self.read_i64().map(|_| ()),
208            TType::Double => self.read_double().map(|_| ()),
209            TType::String => self.read_string().map(|_| ()),
210            TType::Struct => {
211                self.read_struct_begin()?;
212                loop {
213                    let field_ident = self.read_field_begin()?;
214                    if field_ident.field_type == TType::Stop {
215                        break;
216                    }
217                    self.skip_till_depth(field_ident.field_type, depth - 1)?;
218                }
219                self.read_struct_end()
220            }
221            TType::List => {
222                let list_ident = self.read_list_begin()?;
223                for _ in 0..list_ident.size {
224                    self.skip_till_depth(list_ident.element_type, depth - 1)?;
225                }
226                self.read_list_end()
227            }
228            TType::Set => {
229                let set_ident = self.read_set_begin()?;
230                for _ in 0..set_ident.size {
231                    self.skip_till_depth(set_ident.element_type, depth - 1)?;
232                }
233                self.read_set_end()
234            }
235            TType::Map => {
236                let map_ident = self.read_map_begin()?;
237                for _ in 0..map_ident.size {
238                    let key_type = map_ident
239                        .key_type
240                        .expect("non-zero sized map should contain key type");
241                    let val_type = map_ident
242                        .value_type
243                        .expect("non-zero sized map should contain value type");
244                    self.skip_till_depth(key_type, depth - 1)?;
245                    self.skip_till_depth(val_type, depth - 1)?;
246                }
247                self.read_map_end()
248            }
249            u => Err(crate::Error::Protocol(ProtocolError {
250                kind: ProtocolErrorKind::Unknown,
251                message: format!("cannot skip field type {:?}", &u),
252            })),
253        }
254    }
255
256    // utility (DO NOT USE IN GENERATED CODE!!!!)
257    //
258
259    /// Read an unsigned byte.
260    ///
261    /// This method should **never** be used in generated code.
262    fn read_byte(&mut self) -> crate::Result<u8>;
263}
264
265/// Converts Thrift identifiers, primitives, containers or structs into a
266/// stream of bytes.
267///
268/// This trait does not deal with higher-level Thrift concepts like structs or
269/// exceptions - only with primitives and message or container boundaries.
270/// Write methods take an identifier (for example, `TMessageIdentifier`) or a
271/// primitive. Any or all of the fields in an identifier may be omitted when
272/// writing to the transport. Write methods may even be noops. All of this is
273/// transparent to the caller; as long as a matching `TInputProtocol`
274/// implementation is used, received messages will be decoded correctly.
275///
276/// All methods return a `thrift::Result`. If an `Err` is returned the protocol
277/// instance and its underlying transport should be terminated.
278///
279/// # Examples
280///
281/// Create and use a `TOutputProtocol`
282///
283/// ```no_run
284/// use thrift::protocol::{TBinaryOutputProtocol, TFieldIdentifier, TOutputProtocol, TType};
285/// use thrift::transport::TTcpChannel;
286///
287/// let mut channel = TTcpChannel::new();
288/// channel.open("127.0.0.1:9090").unwrap();
289///
290/// let mut protocol = TBinaryOutputProtocol::new(channel, true);
291///
292/// protocol.write_field_begin(&TFieldIdentifier::new("string_thing", TType::String, 1)).unwrap();
293/// protocol.write_string("foo").unwrap();
294/// protocol.write_field_end().unwrap();
295/// ```
296pub trait TOutputProtocol {
297    /// Write the beginning of a Thrift message.
298    fn write_message_begin(&mut self, identifier: &TMessageIdentifier) -> crate::Result<()>;
299    /// Write the end of a Thrift message.
300    fn write_message_end(&mut self) -> crate::Result<()>;
301    /// Write the beginning of a Thrift struct.
302    fn write_struct_begin(&mut self, identifier: &TStructIdentifier) -> crate::Result<()>;
303    /// Write the end of a Thrift struct.
304    fn write_struct_end(&mut self) -> crate::Result<()>;
305    /// Write the beginning of a Thrift field.
306    fn write_field_begin(&mut self, identifier: &TFieldIdentifier) -> crate::Result<()>;
307    /// Write the end of a Thrift field.
308    fn write_field_end(&mut self) -> crate::Result<()>;
309    /// Write a STOP field indicating that all the fields in a struct have been
310    /// written.
311    fn write_field_stop(&mut self) -> crate::Result<()>;
312    /// Write a bool.
313    fn write_bool(&mut self, b: bool) -> crate::Result<()>;
314    /// Write a fixed-length byte array.
315    fn write_bytes(&mut self, b: &[u8]) -> crate::Result<()>;
316    /// Write an 8-bit signed integer.
317    fn write_i8(&mut self, i: i8) -> crate::Result<()>;
318    /// Write a 16-bit signed integer.
319    fn write_i16(&mut self, i: i16) -> crate::Result<()>;
320    /// Write a 32-bit signed integer.
321    fn write_i32(&mut self, i: i32) -> crate::Result<()>;
322    /// Write a 64-bit signed integer.
323    fn write_i64(&mut self, i: i64) -> crate::Result<()>;
324    /// Write a 64-bit float.
325    fn write_double(&mut self, d: f64) -> crate::Result<()>;
326    /// Write a fixed-length string.
327    fn write_string(&mut self, s: &str) -> crate::Result<()>;
328    /// Write the beginning of a list.
329    fn write_list_begin(&mut self, identifier: &TListIdentifier) -> crate::Result<()>;
330    /// Write the end of a list.
331    fn write_list_end(&mut self) -> crate::Result<()>;
332    /// Write the beginning of a set.
333    fn write_set_begin(&mut self, identifier: &TSetIdentifier) -> crate::Result<()>;
334    /// Write the end of a set.
335    fn write_set_end(&mut self) -> crate::Result<()>;
336    /// Write the beginning of a map.
337    fn write_map_begin(&mut self, identifier: &TMapIdentifier) -> crate::Result<()>;
338    /// Write the end of a map.
339    fn write_map_end(&mut self) -> crate::Result<()>;
340    /// Flush buffered bytes to the underlying transport.
341    fn flush(&mut self) -> crate::Result<()>;
342
343    // utility (DO NOT USE IN GENERATED CODE!!!!)
344    //
345
346    /// Write an unsigned byte.
347    ///
348    /// This method should **never** be used in generated code.
349    fn write_byte(&mut self, b: u8) -> crate::Result<()>; // FIXME: REMOVE
350}
351
352impl<P> TInputProtocol for Box<P>
353where
354    P: TInputProtocol + ?Sized,
355{
356    fn read_message_begin(&mut self) -> crate::Result<TMessageIdentifier> {
357        (**self).read_message_begin()
358    }
359
360    fn read_message_end(&mut self) -> crate::Result<()> {
361        (**self).read_message_end()
362    }
363
364    fn read_struct_begin(&mut self) -> crate::Result<Option<TStructIdentifier>> {
365        (**self).read_struct_begin()
366    }
367
368    fn read_struct_end(&mut self) -> crate::Result<()> {
369        (**self).read_struct_end()
370    }
371
372    fn read_field_begin(&mut self) -> crate::Result<TFieldIdentifier> {
373        (**self).read_field_begin()
374    }
375
376    fn read_field_end(&mut self) -> crate::Result<()> {
377        (**self).read_field_end()
378    }
379
380    fn read_bool(&mut self) -> crate::Result<bool> {
381        (**self).read_bool()
382    }
383
384    fn read_bytes(&mut self) -> crate::Result<Vec<u8>> {
385        (**self).read_bytes()
386    }
387
388    fn read_i8(&mut self) -> crate::Result<i8> {
389        (**self).read_i8()
390    }
391
392    fn read_i16(&mut self) -> crate::Result<i16> {
393        (**self).read_i16()
394    }
395
396    fn read_i32(&mut self) -> crate::Result<i32> {
397        (**self).read_i32()
398    }
399
400    fn read_i64(&mut self) -> crate::Result<i64> {
401        (**self).read_i64()
402    }
403
404    fn read_double(&mut self) -> crate::Result<f64> {
405        (**self).read_double()
406    }
407
408    fn read_string(&mut self) -> crate::Result<String> {
409        (**self).read_string()
410    }
411
412    fn read_list_begin(&mut self) -> crate::Result<TListIdentifier> {
413        (**self).read_list_begin()
414    }
415
416    fn read_list_end(&mut self) -> crate::Result<()> {
417        (**self).read_list_end()
418    }
419
420    fn read_set_begin(&mut self) -> crate::Result<TSetIdentifier> {
421        (**self).read_set_begin()
422    }
423
424    fn read_set_end(&mut self) -> crate::Result<()> {
425        (**self).read_set_end()
426    }
427
428    fn read_map_begin(&mut self) -> crate::Result<TMapIdentifier> {
429        (**self).read_map_begin()
430    }
431
432    fn read_map_end(&mut self) -> crate::Result<()> {
433        (**self).read_map_end()
434    }
435
436    fn read_byte(&mut self) -> crate::Result<u8> {
437        (**self).read_byte()
438    }
439}
440
441impl<P> TOutputProtocol for Box<P>
442where
443    P: TOutputProtocol + ?Sized,
444{
445    fn write_message_begin(&mut self, identifier: &TMessageIdentifier) -> crate::Result<()> {
446        (**self).write_message_begin(identifier)
447    }
448
449    fn write_message_end(&mut self) -> crate::Result<()> {
450        (**self).write_message_end()
451    }
452
453    fn write_struct_begin(&mut self, identifier: &TStructIdentifier) -> crate::Result<()> {
454        (**self).write_struct_begin(identifier)
455    }
456
457    fn write_struct_end(&mut self) -> crate::Result<()> {
458        (**self).write_struct_end()
459    }
460
461    fn write_field_begin(&mut self, identifier: &TFieldIdentifier) -> crate::Result<()> {
462        (**self).write_field_begin(identifier)
463    }
464
465    fn write_field_end(&mut self) -> crate::Result<()> {
466        (**self).write_field_end()
467    }
468
469    fn write_field_stop(&mut self) -> crate::Result<()> {
470        (**self).write_field_stop()
471    }
472
473    fn write_bool(&mut self, b: bool) -> crate::Result<()> {
474        (**self).write_bool(b)
475    }
476
477    fn write_bytes(&mut self, b: &[u8]) -> crate::Result<()> {
478        (**self).write_bytes(b)
479    }
480
481    fn write_i8(&mut self, i: i8) -> crate::Result<()> {
482        (**self).write_i8(i)
483    }
484
485    fn write_i16(&mut self, i: i16) -> crate::Result<()> {
486        (**self).write_i16(i)
487    }
488
489    fn write_i32(&mut self, i: i32) -> crate::Result<()> {
490        (**self).write_i32(i)
491    }
492
493    fn write_i64(&mut self, i: i64) -> crate::Result<()> {
494        (**self).write_i64(i)
495    }
496
497    fn write_double(&mut self, d: f64) -> crate::Result<()> {
498        (**self).write_double(d)
499    }
500
501    fn write_string(&mut self, s: &str) -> crate::Result<()> {
502        (**self).write_string(s)
503    }
504
505    fn write_list_begin(&mut self, identifier: &TListIdentifier) -> crate::Result<()> {
506        (**self).write_list_begin(identifier)
507    }
508
509    fn write_list_end(&mut self) -> crate::Result<()> {
510        (**self).write_list_end()
511    }
512
513    fn write_set_begin(&mut self, identifier: &TSetIdentifier) -> crate::Result<()> {
514        (**self).write_set_begin(identifier)
515    }
516
517    fn write_set_end(&mut self) -> crate::Result<()> {
518        (**self).write_set_end()
519    }
520
521    fn write_map_begin(&mut self, identifier: &TMapIdentifier) -> crate::Result<()> {
522        (**self).write_map_begin(identifier)
523    }
524
525    fn write_map_end(&mut self) -> crate::Result<()> {
526        (**self).write_map_end()
527    }
528
529    fn flush(&mut self) -> crate::Result<()> {
530        (**self).flush()
531    }
532
533    fn write_byte(&mut self, b: u8) -> crate::Result<()> {
534        (**self).write_byte(b)
535    }
536}
537
538/// Helper type used by servers to create `TInputProtocol` instances for
539/// accepted client connections.
540///
541/// # Examples
542///
543/// Create a `TInputProtocolFactory` and use it to create a `TInputProtocol`.
544///
545/// ```no_run
546/// use thrift::protocol::{TBinaryInputProtocolFactory, TInputProtocolFactory};
547/// use thrift::transport::TTcpChannel;
548///
549/// let mut channel = TTcpChannel::new();
550/// channel.open("127.0.0.1:9090").unwrap();
551///
552/// let factory = TBinaryInputProtocolFactory::new();
553/// let protocol = factory.create(Box::new(channel));
554/// ```
555pub trait TInputProtocolFactory {
556    // Create a `TInputProtocol` that reads bytes from `transport`.
557    fn create(&self, transport: Box<dyn TReadTransport + Send>) -> Box<dyn TInputProtocol + Send>;
558}
559
560impl<T> TInputProtocolFactory for Box<T>
561where
562    T: TInputProtocolFactory + ?Sized,
563{
564    fn create(&self, transport: Box<dyn TReadTransport + Send>) -> Box<dyn TInputProtocol + Send> {
565        (**self).create(transport)
566    }
567}
568
569/// Helper type used by servers to create `TOutputProtocol` instances for
570/// accepted client connections.
571///
572/// # Examples
573///
574/// Create a `TOutputProtocolFactory` and use it to create a `TOutputProtocol`.
575///
576/// ```no_run
577/// use thrift::protocol::{TBinaryOutputProtocolFactory, TOutputProtocolFactory};
578/// use thrift::transport::TTcpChannel;
579///
580/// let mut channel = TTcpChannel::new();
581/// channel.open("127.0.0.1:9090").unwrap();
582///
583/// let factory = TBinaryOutputProtocolFactory::new();
584/// let protocol = factory.create(Box::new(channel));
585/// ```
586pub trait TOutputProtocolFactory {
587    /// Create a `TOutputProtocol` that writes bytes to `transport`.
588    fn create(&self, transport: Box<dyn TWriteTransport + Send>)
589        -> Box<dyn TOutputProtocol + Send>;
590}
591
592impl<T> TOutputProtocolFactory for Box<T>
593where
594    T: TOutputProtocolFactory + ?Sized,
595{
596    fn create(
597        &self,
598        transport: Box<dyn TWriteTransport + Send>,
599    ) -> Box<dyn TOutputProtocol + Send> {
600        (**self).create(transport)
601    }
602}
603
604/// Thrift message identifier.
605#[derive(Clone, Debug, Eq, PartialEq)]
606pub struct TMessageIdentifier {
607    /// Service call the message is associated with.
608    pub name: String,
609    /// Message type.
610    pub message_type: TMessageType,
611    /// Ordered sequence number identifying the message.
612    pub sequence_number: i32,
613}
614
615impl TMessageIdentifier {
616    /// Create a `TMessageIdentifier` for a Thrift service-call named `name`
617    /// with message type `message_type` and sequence number `sequence_number`.
618    pub fn new<S: Into<String>>(
619        name: S,
620        message_type: TMessageType,
621        sequence_number: i32,
622    ) -> TMessageIdentifier {
623        TMessageIdentifier {
624            name: name.into(),
625            message_type,
626            sequence_number,
627        }
628    }
629}
630
631/// Thrift struct identifier.
632#[derive(Clone, Debug, Eq, PartialEq)]
633pub struct TStructIdentifier {
634    /// Name of the encoded Thrift struct.
635    pub name: String,
636}
637
638impl TStructIdentifier {
639    /// Create a `TStructIdentifier` for a struct named `name`.
640    pub fn new<S: Into<String>>(name: S) -> TStructIdentifier {
641        TStructIdentifier { name: name.into() }
642    }
643}
644
645/// Thrift field identifier.
646#[derive(Clone, Debug, Eq, PartialEq)]
647pub struct TFieldIdentifier {
648    /// Name of the Thrift field.
649    ///
650    /// `None` if it's not sent over the wire.
651    pub name: Option<String>,
652    /// Field type.
653    ///
654    /// This may be a primitive, container, or a struct.
655    pub field_type: TType,
656    /// Thrift field id.
657    ///
658    /// `None` only if `field_type` is `TType::Stop`.
659    pub id: Option<i16>,
660}
661
662impl TFieldIdentifier {
663    /// Create a `TFieldIdentifier` for a field named `name` with type
664    /// `field_type` and field id `id`.
665    ///
666    /// `id` should be `None` if `field_type` is `TType::Stop`.
667    pub fn new<N, S, I>(name: N, field_type: TType, id: I) -> TFieldIdentifier
668    where
669        N: Into<Option<S>>,
670        S: Into<String>,
671        I: Into<Option<i16>>,
672    {
673        TFieldIdentifier {
674            name: name.into().map(|n| n.into()),
675            field_type,
676            id: id.into(),
677        }
678    }
679}
680
681/// Thrift list identifier.
682#[derive(Clone, Debug, Eq, PartialEq)]
683pub struct TListIdentifier {
684    /// Type of the elements in the list.
685    pub element_type: TType,
686    /// Number of elements in the list.
687    pub size: i32,
688}
689
690impl TListIdentifier {
691    /// Create a `TListIdentifier` for a list with `size` elements of type
692    /// `element_type`.
693    pub fn new(element_type: TType, size: i32) -> TListIdentifier {
694        TListIdentifier { element_type, size }
695    }
696}
697
698/// Thrift set identifier.
699#[derive(Clone, Debug, Eq, PartialEq)]
700pub struct TSetIdentifier {
701    /// Type of the elements in the set.
702    pub element_type: TType,
703    /// Number of elements in the set.
704    pub size: i32,
705}
706
707impl TSetIdentifier {
708    /// Create a `TSetIdentifier` for a set with `size` elements of type
709    /// `element_type`.
710    pub fn new(element_type: TType, size: i32) -> TSetIdentifier {
711        TSetIdentifier { element_type, size }
712    }
713}
714
715/// Thrift map identifier.
716#[derive(Clone, Debug, Eq, PartialEq)]
717pub struct TMapIdentifier {
718    /// Map key type.
719    pub key_type: Option<TType>,
720    /// Map value type.
721    pub value_type: Option<TType>,
722    /// Number of entries in the map.
723    pub size: i32,
724}
725
726impl TMapIdentifier {
727    /// Create a `TMapIdentifier` for a map with `size` entries of type
728    /// `key_type -> value_type`.
729    pub fn new<K, V>(key_type: K, value_type: V, size: i32) -> TMapIdentifier
730    where
731        K: Into<Option<TType>>,
732        V: Into<Option<TType>>,
733    {
734        TMapIdentifier {
735            key_type: key_type.into(),
736            value_type: value_type.into(),
737            size,
738        }
739    }
740}
741
742/// Thrift message types.
743#[derive(Clone, Copy, Debug, Eq, PartialEq)]
744pub enum TMessageType {
745    /// Service-call request.
746    Call,
747    /// Service-call response.
748    Reply,
749    /// Unexpected error in the remote service.
750    Exception,
751    /// One-way service-call request (no response is expected).
752    OneWay,
753}
754
755impl Display for TMessageType {
756    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
757        match *self {
758            TMessageType::Call => write!(f, "Call"),
759            TMessageType::Reply => write!(f, "Reply"),
760            TMessageType::Exception => write!(f, "Exception"),
761            TMessageType::OneWay => write!(f, "OneWay"),
762        }
763    }
764}
765
766impl From<TMessageType> for u8 {
767    fn from(message_type: TMessageType) -> Self {
768        match message_type {
769            TMessageType::Call => 0x01,
770            TMessageType::Reply => 0x02,
771            TMessageType::Exception => 0x03,
772            TMessageType::OneWay => 0x04,
773        }
774    }
775}
776
777impl TryFrom<u8> for TMessageType {
778    type Error = crate::Error;
779    fn try_from(b: u8) -> Result<Self, Self::Error> {
780        match b {
781            0x01 => Ok(TMessageType::Call),
782            0x02 => Ok(TMessageType::Reply),
783            0x03 => Ok(TMessageType::Exception),
784            0x04 => Ok(TMessageType::OneWay),
785            unkn => Err(crate::Error::Protocol(ProtocolError {
786                kind: ProtocolErrorKind::InvalidData,
787                message: format!("cannot convert {} to TMessageType", unkn),
788            })),
789        }
790    }
791}
792
793/// Thrift struct-field types.
794#[derive(Clone, Copy, Debug, Eq, PartialEq)]
795pub enum TType {
796    /// Indicates that there are no more serialized fields in this Thrift struct.
797    Stop,
798    /// Void (`()`) field.
799    Void,
800    /// Boolean.
801    Bool,
802    /// Signed 8-bit int.
803    I08,
804    /// Double-precision number.
805    Double,
806    /// Signed 16-bit int.
807    I16,
808    /// Signed 32-bit int.
809    I32,
810    /// Signed 64-bit int.
811    I64,
812    /// UTF-8 string.
813    String,
814    /// UTF-7 string. *Unsupported*.
815    Utf7,
816    /// Thrift struct.
817    Struct,
818    /// Map.
819    Map,
820    /// Set.
821    Set,
822    /// List.
823    List,
824    /// UTF-8 string.
825    Utf8,
826    /// UTF-16 string. *Unsupported*.
827    Utf16,
828}
829
830impl Display for TType {
831    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
832        match *self {
833            TType::Stop => write!(f, "STOP"),
834            TType::Void => write!(f, "void"),
835            TType::Bool => write!(f, "bool"),
836            TType::I08 => write!(f, "i08"),
837            TType::Double => write!(f, "double"),
838            TType::I16 => write!(f, "i16"),
839            TType::I32 => write!(f, "i32"),
840            TType::I64 => write!(f, "i64"),
841            TType::String => write!(f, "string"),
842            TType::Utf7 => write!(f, "UTF7"),
843            TType::Struct => write!(f, "struct"),
844            TType::Map => write!(f, "map"),
845            TType::Set => write!(f, "set"),
846            TType::List => write!(f, "list"),
847            TType::Utf8 => write!(f, "UTF8"),
848            TType::Utf16 => write!(f, "UTF16"),
849        }
850    }
851}
852
853/// Compare the expected message sequence number `expected` with the received
854/// message sequence number `actual`.
855///
856/// Return `()` if `actual == expected`, `Err` otherwise.
857pub fn verify_expected_sequence_number(expected: i32, actual: i32) -> crate::Result<()> {
858    if expected == actual {
859        Ok(())
860    } else {
861        Err(crate::Error::Application(crate::ApplicationError {
862            kind: crate::ApplicationErrorKind::BadSequenceId,
863            message: format!("expected {} got {}", expected, actual),
864        }))
865    }
866}
867
868/// Compare the expected service-call name `expected` with the received
869/// service-call name `actual`.
870///
871/// Return `()` if `actual == expected`, `Err` otherwise.
872pub fn verify_expected_service_call(expected: &str, actual: &str) -> crate::Result<()> {
873    if expected == actual {
874        Ok(())
875    } else {
876        Err(crate::Error::Application(crate::ApplicationError {
877            kind: crate::ApplicationErrorKind::WrongMethodName,
878            message: format!("expected {} got {}", expected, actual),
879        }))
880    }
881}
882
883/// Compare the expected message type `expected` with the received message type
884/// `actual`.
885///
886/// Return `()` if `actual == expected`, `Err` otherwise.
887pub fn verify_expected_message_type(
888    expected: TMessageType,
889    actual: TMessageType,
890) -> crate::Result<()> {
891    if expected == actual {
892        Ok(())
893    } else {
894        Err(crate::Error::Application(crate::ApplicationError {
895            kind: crate::ApplicationErrorKind::InvalidMessageType,
896            message: format!("expected {} got {}", expected, actual),
897        }))
898    }
899}
900
901/// Check if a required Thrift struct field exists.
902///
903/// Return `()` if it does, `Err` otherwise.
904pub fn verify_required_field_exists<T>(field_name: &str, field: &Option<T>) -> crate::Result<()> {
905    match *field {
906        Some(_) => Ok(()),
907        None => Err(crate::Error::Protocol(crate::ProtocolError {
908            kind: crate::ProtocolErrorKind::Unknown,
909            message: format!("missing required field {}", field_name),
910        })),
911    }
912}
913
914/// Extract the field id from a Thrift field identifier.
915///
916/// `field_ident` must *not* have `TFieldIdentifier.field_type` of type `TType::Stop`.
917///
918/// Return `TFieldIdentifier.id` if an id exists, `Err` otherwise.
919pub fn field_id(field_ident: &TFieldIdentifier) -> crate::Result<i16> {
920    field_ident.id.ok_or_else(|| {
921        crate::Error::Protocol(crate::ProtocolError {
922            kind: crate::ProtocolErrorKind::Unknown,
923            message: format!("missing field in in {:?}", field_ident),
924        })
925    })
926}
927
928#[cfg(test)]
929mod tests {
930
931    use std::io::Cursor;
932
933    use super::*;
934    use crate::transport::{TReadTransport, TWriteTransport};
935
936    #[test]
937    fn must_create_usable_input_protocol_from_concrete_input_protocol() {
938        let r: Box<dyn TReadTransport> = Box::new(Cursor::new([0, 1, 2]));
939        let mut t = TCompactInputProtocol::new(r);
940        takes_input_protocol(&mut t)
941    }
942
943    #[test]
944    fn must_create_usable_input_protocol_from_boxed_input() {
945        let r: Box<dyn TReadTransport> = Box::new(Cursor::new([0, 1, 2]));
946        let mut t: Box<dyn TInputProtocol> = Box::new(TCompactInputProtocol::new(r));
947        takes_input_protocol(&mut t)
948    }
949
950    #[test]
951    fn must_create_usable_output_protocol_from_concrete_output_protocol() {
952        let w: Box<dyn TWriteTransport> = Box::new(vec![0u8; 10]);
953        let mut t = TCompactOutputProtocol::new(w);
954        takes_output_protocol(&mut t)
955    }
956
957    #[test]
958    fn must_create_usable_output_protocol_from_boxed_output() {
959        let w: Box<dyn TWriteTransport> = Box::new(vec![0u8; 10]);
960        let mut t: Box<dyn TOutputProtocol> = Box::new(TCompactOutputProtocol::new(w));
961        takes_output_protocol(&mut t)
962    }
963
964    fn takes_input_protocol<R>(t: &mut R)
965    where
966        R: TInputProtocol,
967    {
968        t.read_byte().unwrap();
969    }
970
971    fn takes_output_protocol<W>(t: &mut W)
972    where
973        W: TOutputProtocol,
974    {
975        t.flush().unwrap();
976    }
977}
thrift/protocol/mod.rs

thrift/protocol/
mod.rs
