README.md
1# Rust Thrift library
2
3## Overview
4
5This crate implements the components required to build a working Thrift server
6and client. It is divided into the following modules:
7
8 1. errors
9 2. protocol
10 3. transport
11 4. server
12 5. autogen
13
14The modules are layered as shown. The `generated` layer is code generated by the
15Thrift compiler's Rust plugin. It uses the components defined in this crate to
16serialize and deserialize types and implement RPC. Users interact with these
17types and services by writing their own code on top.
18
19 ```text
20 +-----------+
21 | app dev |
22 +-----------+
23 | generated | <-> errors/results
24 +-----------+
25 | protocol |
26 +-----------+
27 | transport |
28 +-----------+
29 ```
30
31## Using this crate
32
33Add `thrift = "x.y.z"` to your `Cargo.toml`, where `x.y.z` is the version of the
34Thrift compiler you're using.
35
36## API Documentation
37
38Full [Rustdoc](https://docs.rs/thrift/)
39
40## Compatibility
41
42The Rust library and auto-generated code targets Rust versions 1.28+.
43It does not currently use any Rust 2018 features.
44
45### Breaking Changes
46
47Breaking changes are minimized. When they are made they will be outlined below with transition guidelines.
48
49##### Thrift 0.14.0
50
51* **[THRIFT-5158]** - Rust library and generator now support Rust 2018 only. Required rust 1.40.0 or higher
52
53 The Rust `thrift` library was updated to Rust 2018 via `cargo fix --edition`.
54 All test code in the repo was updated as well. The code generator was also updated
55 to support Rust 2018 only.
56
57##### Thrift 0.13.0
58
59* **[THRIFT-4536]** - Use TryFrom from std, required rust 1.34.0 or higher
60
61 Previously TryFrom was from try_from crate, it is now from the std library,
62 but this functionality is only available in rust 1.34.0. Additionally,
63 ordered-float is now re-exported under the thrift module to reduce
64 possible dependency mismatches.
65
66##### Thrift 0.12.0
67
68* **[THRIFT-4529]** - Rust enum variants are now camel-cased instead of uppercased to conform to Rust naming conventions
69
70 Previously, enum variants were uppercased in the auto-generated code.
71 For example, the following thrift enum:
72
73 ```thrift
74 // THRIFT
75 enum Operation {
76 ADD,
77 SUBTRACT,
78 MULTIPLY,
79 DIVIDE,
80 }
81 ```
82
83 used to generate:
84
85 ```rust
86 // OLD AUTO-GENERATED RUST
87 pub enum Operation {
88 ADD,
89 SUBTRACT,
90 MULTIPLY,
91 DIVIDE,
92 }
93 ```
94 It *now* generates:
95 ```rust
96 // NEW AUTO-GENERATED RUST
97 pub enum Operation {
98 Add,
99 Subtract,
100 Multiply,
101 Divide,
102 }
103 ```
104
105 You will have to change all enum variants in your code to use camel-cased names.
106 This should be a search and replace.
107
108## Contributing
109
110Bug reports and PRs are always welcome! Please see the
111[Thrift website](https://thrift.apache.org/) for more details.
112
113Thrift Rust support requires code in several directories:
114
115* `compiler/cpp/src/thrift/generate/t_rs_generator.cc`: binding code generator
116* `lib/rs`: runtime library
117* `lib/rs/test`: supplemental tests
118* `tutorial/rs`: tutorial client and server
119* `test/rs`: cross-language test client and server
120
121All library code, test code and auto-generated code compiles and passes clippy
122without warnings. All new code must do the same! When making changes ensure that:
123
124* `rustc` does does output any warnings
125* `clippy` with default settings does not output any warnings (includes auto-generated code)
126* `cargo test` is successful
127* `make precross` and `make check` are successful
128* `tutorial/bin/tutorial_client` and `tutorial/bin/tutorial_server` communicate
129