README.rst
1.. zephyr:code-sample:: thrift-hello
2 :name: Apache Thrift Hello World
3
4 Implement a simple Apache Thrift client-server application.
5
6Overview
7********
8
9.. figure:: thrift-layers.png
10 :align: center
11 :alt: Thrift Layers
12
13What is Thrift?
14***************
15
16`Apache Thrift`_ is an `IDL`_ specification, `RPC`_ framework, and
17`code generator`_. It works across all major operating systems, supports over
1827 programming languages, 7 protocols, and 6 low-level transports. Thrift was
19originally developed at `Facebook in 2006`_ and then shared with the
20`Apache Software Foundation`_. Thrift supports a rich set of types and data
21structures, and abstracts away transport and protocol details, which lets
22developers focus on application logic.
23
24.. _Apache Thrift:
25 https://github.com/apache/thrift
26
27.. _IDL:
28 https://en.wikipedia.org/wiki/Interface_description_language
29
30.. _RPC:
31 https://en.wikipedia.org/wiki/Remote_procedure_call
32
33.. _code generator:
34 https://en.wikipedia.org/wiki/Automatic_programming
35
36.. _Facebook in 2006:
37 https://thrift.apache.org/static/files/thrift-20070401.pdf
38
39.. _Apache Software Foundation:
40 https://www.apache.org
41
42Overview
43********
44
45This sample application includes a client and server implementing the RPC
46interface described in :zephyr_file:`samples/modules/thrift/hello/hello.thrift`.
47The purpose of this example is to demonstrate how components at different
48layers in thrift can be combined to build an application with desired features.
49
50
51Requirements
52************
53
54- Optional Modules
55
56.. code-block:: console
57 :caption: Download optional modules with west
58
59 west config manifest.group-filter -- +optional
60 west update
61
62- QEMU Networking (described in :ref:`networking_with_qemu`)
63- Thrift dependencies installed for your host OS
64
65.. tabs::
66
67 .. group-tab:: Ubuntu
68
69 .. code-block:: bash
70 :caption: Install thrift dependencies in Ubuntu
71
72 sudo apt install -y libboost-all-dev thrift-compiler libthrift-dev
73
74 .. group-tab:: macOS
75
76 .. code-block:: bash
77 :caption: Install thrift dependencies in macOS
78
79 brew install boost openssl thrift
80
81Building and Running
82********************
83
84This application can be run on a Linux host, with either the server or the
85client in the QEMU environment, and the peer is built and run natively on
86the host.
87
88Building the Native Client and Server
89=====================================
90
91.. code-block:: console
92
93 $ make -j -C samples/modules/thrift/hello/client/
94 $ make -j -C samples/modules/thrift/hello/server/
95
96Under ``client/``, 3 executables will be generated, and components
97used in each layer of them are listed below:
98
99+----------------------+------------+--------------------+------------------+
100| hello_client | TSocket | TBufferedTransport | TBinaryProtocol |
101+----------------------+------------+--------------------+------------------+
102| hello_client_compact | TSocket | TBufferedTransport | TCompactProtocol |
103+----------------------+------------+--------------------+------------------+
104| hello_client_ssl | TSSLSocket | TBufferedTransport | TBinaryProtocol |
105+----------------------+------------+--------------------+------------------+
106
107The same applies for the server. Only the client and the server with the
108same set of stacks can communicate.
109
110Additionally, there is a ``hello_client.py`` Python script that can be used
111interchangeably with the ``hello_client`` C++ application to illustrate the
112cross-language capabilities of Thrift.
113
114+----------------------+------------+--------------------+------------------+
115| hello_client.py | TSocket | TBufferedTransport | TBinaryProtocol |
116+----------------------+------------+--------------------+------------------+
117
118Running the Zephyr Server in QEMU
119=================================
120
121Build the Zephyr version of the ``hello/server`` sample application like this:
122
123.. zephyr-app-commands::
124 :zephyr-app: samples/modules/thrift/hello/server
125 :board: board_name
126 :goals: build
127 :compact:
128
129To enable advanced features, extra arguments should be passed accordingly:
130
131- TCompactProtocol: ``-DCONFIG_THRIFT_COMPACT_PROTOCOL=y``
132- TSSLSocket: ``-DCONF_FILE="prj.conf ../overlay-tls.conf"``
133
134For example, to build for ``qemu_x86_64`` with TSSLSocket support:
135
136.. zephyr-app-commands::
137 :zephyr-app: samples/modules/thrift/hello/server
138 :host-os: unix
139 :board: qemu_x86_64
140 :conf: "prj.conf ../overlay-tls.conf"
141 :goals: run
142 :compact:
143
144In another terminal, run the ``hello_client`` sample app compiled for the
145host OS:
146
147.. code-block:: console
148
149 $ ./hello_client 192.0.2.1
150 $ ./hello_client_compact 192.0.2.1
151 $ ./hello_client_ssl 192.0.2.1 ../native-cert.pem ../native-key.pem ../qemu-cert.pem
152
153You should observe the following in the original ``hello/server`` terminal:
154
155.. code-block:: console
156
157 ping
158 echo: Hello, world!
159 counter: 1
160 counter: 2
161 counter: 3
162 counter: 4
163 counter: 5
164
165In the client terminal, run ``hello_client.py`` app under the host OS (not
166described for compact or ssl variants for brevity):
167
168.. code-block:: console
169
170 $ ./hello_client.py
171
172You should observe the following in the original ``hello/server`` terminal.
173Note that the server's state is not discarded (the counter continues to
174increase).
175
176.. code-block:: console
177
178 ping
179 echo: Hello, world!
180 counter: 6
181 counter: 7
182 counter: 8
183 counter: 9
184 counter: 10
185
186Running the Zephyr Client in QEMU
187=================================
188
189In another terminal, run the ``hello_server`` sample app compiled for the
190host OS:
191
192.. code-block:: console
193
194 $ ./hello_server 0.0.0.0
195 $ ./hello_server_compact 0.0.0.0
196 $ ./hello_server_ssl 0.0.0.0 ../native-cert.pem ../native-key.pem ../qemu-cert.pem
197
198
199Then, in annother terminal, run the corresponding ``hello/client`` sample:
200
201.. zephyr-app-commands::
202 :zephyr-app: samples/modules/thrift/hello/client
203 :board: qemu_x86_64
204 :goals: run
205 :compact:
206
207The additional arguments for advanced features are the same as
208``hello/server``.
209
210You should observe the following in the original ``hello_server`` terminal:
211
212.. code-block:: console
213
214 ping
215 echo: Hello, world!
216 counter: 1
217 counter: 2
218 counter: 3
219 counter: 4
220 counter: 5
221
