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