-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathclient.html
498 lines (461 loc) · 35.7 KB
/
client.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Creating frontends — HappyPanda X 0.13.3#170 documentation</title>
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/style.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<script src="https://platform.twitter.com/widgets.js"></script>
<script src="_static/script.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Plugins" href="plugin.html" />
<link rel="prev" title="Contributing" href="env.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.11.0.min.js "></script>
<script type="text/javascript" src="_static/js/jquery-fix.js "></script>
<script type="text/javascript" src="_static/bootstrap-3.3.7/js/bootstrap.min.js "></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js "></script>
</head><body>
<div id="navbar" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html"><span><img src="_static/hpx_logo.svg"></span>
HappyPanda X</a>
<span class="navbar-text navbar-version pull-left"><b>0.13.3#170</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="index.html">Contents <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc"><ul>
<li class="toctree-l1"><a class="reference internal" href="install.html">Installing</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Using HappyPanda X</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html#installing-plugins">Installing plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html#securing-happypanda-x">Securing HappyPanda X</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html#exposing-happypanda-x">Exposing HappyPanda X</a></li>
<li class="toctree-l1"><a class="reference internal" href="translation.html">Translations</a></li>
<li class="toctree-l1"><a class="reference internal" href="settings.html">Settings</a></li>
<li class="toctree-l1"><a class="reference internal" href="switches.html">Command-Line Arguments</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="env.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="env.html#editing-the-documentation">Editing the documentation</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Creating frontends</a></li>
<li class="toctree-l1"><a class="reference internal" href="plugin.html">Plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="todo.html">TODO</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="api_general.html">General</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">Server API</a></li>
<li class="toctree-l1"><a class="reference internal" href="api_plugin.html">Plugin API</a></li>
</ul>
</ul>
</li>
<li>
<a href="env.html" title="Previous Chapter: Contributing"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Contributing</span>
</a>
</li>
<li>
<a href="plugin.html" title="Next Chapter: Plugins"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Plugins »</span>
</a>
</li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<ul class="quick-links">
<li>
<strong>Quick links</strong>
</li>
<li class="quick-link">
<a class="github-button" href="https://github.com/twiddli" aria-label="Follow @twiddli on GitHub">Follow @twiddli</a>
</li>
<li class="quick-link">
<a class="github-button" href="https://github.com/happypandax/happypandax/issues" data-icon="octicon-issue-opened" data-show-count="true" aria-label="Issue happypandax/happypandax on GitHub">Issue</a>
</li>
<li class="divider">·</li>
<li class="quick-link">
<a class="github-button" href="https://github.com/happypandax/happypandax" data-icon="octicon-star" data-show-count="true" aria-label="Star happypandax/happypandax on GitHub">Star</a>
</li>
<li class="quick-link">
<a class="github-button" href="https://github.com/happypandax/happypandax/fork" data-icon="octicon-repo-forked" data-show-count="true" aria-label="Fork happypandax/happypandax on GitHub">Fork</a>
</li>
<li class="divider">·</li>
<li class="quick-link">
<a href="https://twitter.com/twiddly_"
class="twitter-follow-button" data-width="145px"
data-link-color="#0069D6" data-show-count="false">
Follow
@twiddly_
</a>
</li>
<li class="quick-link">
<a href="https://twitter.com/share" class="twitter-share-button"
data-url="" data-count="horizontal"
data-via="twbootstrap"
data-related="twiddly_:Creator of HappyPanda X">Tweet</a>
</li>
</ul>
<div class="container">
<div class="row">
<div class="col-md-3">
<div id="sidebar" class="bs-sidenav" role="complementary"><ul>
<li><a class="reference internal" href="#">Creating frontends</a><ul>
<li><a class="reference internal" href="#client-libraries">Client libraries</a></li>
<li><a class="reference internal" href="#exchanging-messages">Exchanging messages</a></li>
<li><a class="reference internal" href="#authenticating">Authenticating</a></li>
<li><a class="reference internal" href="#session">Session</a></li>
<li><a class="reference internal" href="#calling-a-function">Calling a function</a></li>
<li><a class="reference internal" href="#errors">Errors</a></li>
<li><a class="reference internal" href="#server-commands">Server commands</a></li>
<li><a class="reference internal" href="#playing-with-the-api">Playing with the API</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="col-md-9 content">
<div class="section" id="creating-frontends">
<h1>Creating frontends<a class="headerlink" href="#creating-frontends" title="Permalink to this headline">¶</a></h1>
<p>HPX exposes an RPC interface over TCP making it possible to create a client in any programming language.</p>
<p>For exchanging data between the server and client <code class="docutils literal notranslate"><span class="pre">JSON</span></code> is used. Make sure you’re familiar with <code class="docutils literal notranslate"><span class="pre">JSON</span></code> and its datatypes.</p>
<p>Before wanting to talk to a HPX server, make sure you have one running. Note that there’s no need to run HPX from source if you just want to create a client.</p>
<p>It is recommended that you run the server with the <code class="docutils literal notranslate"><span class="pre">--debug</span></code> and <code class="docutils literal notranslate"><span class="pre">--dev</span></code> commandline switches so that you can see what’s going on while you’re connected.
See <a class="reference internal" href="switches.html#command-line-arguments"><span class="std std-ref">Command-Line Arguments</span></a>.</p>
<div class="section" id="client-libraries">
<h2>Client libraries<a class="headerlink" href="#client-libraries" title="Permalink to this headline">¶</a></h2>
<p>There currently exists a couple of client libraries that can handle the communication part for you.</p>
<p>Here are the known ones:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/happypandax/js-client">js-client</a> (javascript)</p></li>
<li><p><a class="reference external" href="https://github.com/happypandax/py-client">py-client</a> (python)</p></li>
</ul>
<p>It is however a good idea to read this through so that you understand how HPX communicates.</p>
</div>
<div class="section" id="exchanging-messages">
<h2>Exchanging messages<a class="headerlink" href="#exchanging-messages" title="Permalink to this headline">¶</a></h2>
<p>Needless to say, to start exchanging messages with the server, you need a basic understanding of TCP.</p>
<p>To communicate with the server you need to instantiate a TCP socket.</p>
<p>In your chosen programming language instantiate a TCP socket and connect it to the server.</p>
<p>In pseudocode:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">sock</span> <span class="o">=</span> <span class="n">tcpsocket</span><span class="p">();</span>
<span class="n">sock</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">server_address</span><span class="p">,</span> <span class="n">server_port</span><span class="p">);</span>
</pre></div>
</div>
<p>The server will try to talk to you after connecting successfully.</p>
<p>You receive this message.</p>
<p>In pseudocode:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">msg</span> <span class="o">=</span> <span class="n">sock</span><span class="o">.</span><span class="n">receive</span><span class="p">();</span>
</pre></div>
</div>
<p><strong>Now, the most important thing you need to understand is that the data you received just now might just be a part of the full message</strong>.</p>
<p>The message is delimited so you keep receving data until you meet the EOF sequence. For HPX this EOF is <code class="docutils literal notranslate"><span class="pre"><EOF></span></code> (in byte-form).</p>
<p>HPX requires that all data, <strong>not including the EOF sequence</strong>, to be gzipped.</p>
<p>A very crude example on how to receive a message from HPX in pseudocode:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">msg</span> <span class="o">=</span> <span class="n">none</span>
<span class="n">var</span> <span class="n">buffer</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="s2">""</span><span class="p">)</span>
<span class="k">while</span> <span class="n">true</span><span class="p">:</span>
<span class="n">buffer</span> <span class="o">+=</span> <span class="n">sock</span><span class="o">.</span><span class="n">receive</span><span class="p">()</span> <span class="c1"># might want to set a timeout so it doesn't wait forever</span>
<span class="c1"># loop through buffer and check for EOF tag</span>
<span class="k">if</span> <span class="nb">bytes</span><span class="p">(</span><span class="s2">"<EOF>"</span><span class="p">)</span> <span class="ow">in</span> <span class="n">buffer</span><span class="p">:</span>
<span class="n">msg</span> <span class="o">=</span> <span class="n">buffer</span>
<span class="k">break</span> <span class="c1"># break loop</span>
<span class="c1"># remove the EOF sequence from the data</span>
<span class="n">buffer</span> <span class="o">=</span> <span class="n">buffer</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s2">"<EOF>"</span><span class="p">)</span>
<span class="c1"># decompress the data</span>
<span class="n">var</span> <span class="n">data</span> <span class="o">=</span> <span class="n">gzip</span><span class="o">.</span><span class="n">decompress</span><span class="p">(</span><span class="n">buffer</span><span class="p">)</span>
</pre></div>
</div>
<p>Now that we got a message from the server, we convert it into valid <code class="docutils literal notranslate"><span class="pre">JSON</span></code>.
The decompressed data is <cite>UTF-8</cite> encoded.</p>
<p>In pseudocode:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">json_data</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">convert</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"utf-8"</span><span class="p">);</span>
</pre></div>
</div>
<p>And that’s the end of it. You’ve successfully received a message from the server.</p>
<p>Sending a message is even easier. Just make sure it’s valid <code class="docutils literal notranslate"><span class="pre">JSON</span></code>, converted to bytes encoded in <code class="docutils literal notranslate"><span class="pre">UTF-8</span></code> and lastly gzip compressed before you send.</p>
<p><strong>Remember to suffix the message with the EOF tag so the server knows when your message is complete</strong>.</p>
<p>In pseudocode:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">msg_to_send</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">valid_json</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"utf-8"</span><span class="p">)</span> <span class="c1"># make sure it's UTF-8 encoded</span>
<span class="n">var</span> <span class="n">eof_tag</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="s2">"<EOF>"</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"utf-8"</span><span class="p">)</span>
<span class="c1"># compress the msg before sending</span>
<span class="n">msg_to_send</span> <span class="o">=</span> <span class="n">gzip</span><span class="o">.</span><span class="n">compress</span><span class="p">(</span><span class="n">msg_to_send</span><span class="p">)</span>
<span class="n">sock</span><span class="o">.</span><span class="n">send_everything</span><span class="p">(</span><span class="n">msg_to_send</span><span class="p">)</span>
<span class="n">sock</span><span class="o">.</span><span class="n">send_everything</span><span class="p">(</span><span class="n">eof_tag</span><span class="p">)</span> <span class="c1"># remember not to compress the EOF sequence!</span>
</pre></div>
</div>
<p>For every message you send the server, a response is sent back, that is, unless the server has crashed or something.</p>
<p>(<strong>Please note that if you ran the server with the –dev switch, the server will not respond to messages if an unhandled exception was raised</strong>)</p>
<p>The structure of the messages exchanged between the server and the client is consistent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"session"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="p">{},</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In <code class="docutils literal notranslate"><span class="pre">name</span></code> is a string value. This value is just an arbitrarily chosen name for the sever/client. It has some use, see <a class="reference internal" href="api.html#configuration"><span class="std std-ref">Configuration</span></a> when you’re done reading this.</p>
<p>In <code class="docutils literal notranslate"><span class="pre">data</span></code> is the real message. <code class="docutils literal notranslate"><span class="pre">session</span></code> will be explained in <a class="reference internal" href="#session"><span class="std std-ref">Session</span></a>.</p>
<p><strong>Every message should look like this</strong>.</p>
<p>For the sake of brevity, from now on only messages meant to be put in the <code class="docutils literal notranslate"><span class="pre">data</span></code> key will be shown.</p>
<p>Generally, the server is very helpful and will tell you if your message is invalid and/or if you’ve misused or missed some keys.</p>
</div>
<div class="section" id="authenticating">
<h2>Authenticating<a class="headerlink" href="#authenticating" title="Permalink to this headline">¶</a></h2>
<p>Remember that the server always sent a message after you’ve successfully connected?</p>
<p>This is part of the authentication process or a so-called “handshake”.</p>
<p>The server will send you a message that looks like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"version"</span><span class="p">:</span>
<span class="p">{</span>
<span class="s2">"core"</span><span class="p">:</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span> <span class="s2">", # [major, minor, patch]</span>
<span class="s2">"db"</span><span class="p">:</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span>
<span class="s2">"torrent"</span><span class="p">:</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span>
<span class="p">}</span>
<span class="s2">"guest_allowed"</span><span class="p">:</span> <span class="n">true</span>
<span class="p">}</span>
</pre></div>
</div>
<p>You can use this message to determine if the HPX server is supported or not.</p>
<p>Notice the <code class="docutils literal notranslate"><span class="pre">guest_allowed</span></code> key. The value of this key informs if it’s possible to connect to the server <em>without</em> providing any credentials.</p>
<p>The server expects a response from the client that completes the handshake before any further processing is done.</p>
<p>To authenticate as a <strong>guest</strong> the client responds with an empty object <code class="docutils literal notranslate"><span class="pre">{}</span></code>.</p>
<p>To authenticate as a <strong>user</strong> the client responds with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"user"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"password"</span><span class="p">:</span> <span class="s2">""</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The server will respond with <code class="docutils literal notranslate"><span class="pre">"Authenticated"</span></code> and assign a <code class="docutils literal notranslate"><span class="pre">session</span></code> for a successful handshake (this is the whole message):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"session"</span><span class="p">:</span> <span class="s2">"long_random_string"</span><span class="p">,</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="s2">"Authenticated"</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If otherwise, it responds with an error. See … for possible errors.</p>
<p>This handshake is only required <em>once</em> per initial connection.
Additional connections can be established without doing a handshake with the use of the newly-assigned <code class="docutils literal notranslate"><span class="pre">session</span></code> value.
See <a class="reference internal" href="#session"><span class="std std-ref">Session</span></a>.</p>
<p>Additional connections</p>
<div class="admonition-todo admonition" id="id1">
<p class="admonition-title">Todo</p>
<p>authentication errors</p>
</div>
</div>
<div class="section" id="session">
<h2>Session<a class="headerlink" href="#session" title="Permalink to this headline">¶</a></h2>
<p>After a successful handshake, a <em>session</em> is created:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"session"</span><span class="p">:</span> <span class="s2">"a_new_unique_session_string"</span><span class="p">,</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">"server"</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="s2">"Authenticated"</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The session is tied to the context of the client who did the handshake.</p>
<p>The session is <em>not</em> tied to any particular connection, meaning multiple independent connections
can use the same session.</p>
<p>This allows for multiple independent connections to be made within the same or different app while sharing the same context:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">socketA</span> <span class="p">(</span><span class="n">connects</span><span class="p">)</span> <span class="o">--></span> <span class="n">server</span>
<span class="n">socketA</span> <span class="o"><--</span> <span class="p">(</span><span class="n">asking</span> <span class="k">for</span> <span class="n">handshake</span><span class="p">)</span> <span class="n">server</span>
<span class="n">socketA</span> <span class="p">(</span><span class="n">handshakes</span><span class="p">)</span> <span class="o">--></span> <span class="n">server</span>
<span class="n">socketA</span> <span class="o"><--</span> <span class="p">(</span><span class="n">accepted</span><span class="p">,</span> <span class="n">have</span> <span class="n">a</span> <span class="n">sessionid</span><span class="p">)</span> <span class="n">server</span>
<span class="n">socketB</span> <span class="p">(</span><span class="n">connects</span><span class="p">)</span> <span class="o">--></span> <span class="n">server</span>
<span class="n">socketB</span> <span class="o"><--</span> <span class="p">(</span><span class="n">asking</span> <span class="k">for</span> <span class="n">handshake</span><span class="p">)</span> <span class="n">server</span>
<span class="n">socketB</span> <span class="p">(</span><span class="n">normal</span> <span class="n">msg</span> <span class="k">with</span> <span class="n">session</span> <span class="nb">id</span><span class="p">)</span> <span class="o">--></span> <span class="n">server</span>
<span class="n">socketB</span> <span class="o"><--</span> <span class="p">(</span><span class="n">normal</span> <span class="n">response</span><span class="p">)</span> <span class="n">server</span>
</pre></div>
</div>
<p>Think of it as threads in a computer program.</p>
<p>As shown above, the server will <em>always</em> send a message when a client connects.
This message should thus always be consumed when connecting with additional sockets before sending the intended message with a session.</p>
<p><strong>Sessions have a limited lifespan</strong>. Whenever you send a message using a session, you extend that particular session’s lifespan.</p>
<p>Sessions expire when their lifespan runs out (shocking, isn’t it? :) ), requiring the client to do a <em>new</em> handshake.</p>
<p>The extent of a single session’s lifespan is set by the server (in the server settings).</p>
<div class="admonition-todo admonition" id="id2">
<p class="admonition-title">Todo</p>
<p>explain session expired error</p>
</div>
</div>
<div class="section" id="calling-a-function">
<h2>Calling a function<a class="headerlink" href="#calling-a-function" title="Permalink to this headline">¶</a></h2>
<p>Now that you’ve perfomed a successful handshake, you can start using the <a class="reference internal" href="api.html#server-api"><span class="std std-ref">Server API</span></a>.</p>
<p>A <em>function-call</em> object in its simplest looks like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"fname"</span><span class="p">:</span> <span class="s2">""</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">fname</span></code> value is the name of the function you want to call. This particular object has no function arguments.</p>
<p>To add additional function arguments you just define the arguments in the <em>function-call</em> object like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"fname"</span><span class="p">:</span> <span class="s2">"func1"</span><span class="p">,</span>
<span class="s2">"arg1"</span><span class="p">:</span> <span class="n">value1</span><span class="p">,</span>
<span class="s2">"arg2"</span><span class="p">:</span> <span class="n">value2</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This <em>function-call</em> object will call <code class="docutils literal notranslate"><span class="pre">func1(arg1=value1,</span> <span class="pre">arg2=value2)</span></code> on the server.</p>
<p>It is possible to call multiple functions in a single message, which is why it is required that
<em>function-call</em> objects are put in a list before sending the message:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
<span class="p">{</span>
<span class="s2">"fname"</span><span class="p">:</span> <span class="s2">"func1"</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="s2">"fname"</span><span class="p">:</span> <span class="s2">"func2"</span>
<span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
<p>The server will respond with a list of <em>function-data</em> objects:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
<span class="p">{</span>
<span class="s2">"fname"</span><span class="p">:</span> <span class="s2">"func1"</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="p">{}</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="s2">"fname"</span><span class="p">:</span> <span class="s2">"func2"</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="p">{}</span>
<span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
<p>In case of errors raised by the function, the <em>function-data</em> gains an <code class="docutils literal notranslate"><span class="pre">error</span></code> key. See <a class="reference internal" href="#errors"><span class="std std-ref">Errors</span></a>.</p>
<p>If you’re unsure on what data a function will return, see <a class="reference internal" href="#playing-with-the-api"><span class="std std-ref">Playing with the API</span></a></p>
<div class="admonition-todo admonition" id="id3">
<p class="admonition-title">Todo</p>
<p>reference message objects here</p>
</div>
</div>
<div class="section" id="errors">
<h2>Errors<a class="headerlink" href="#errors" title="Permalink to this headline">¶</a></h2>
<p>An <em>error</em> object looks like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"code"</span><span class="p">:</span> <span class="n">integer</span><span class="p">,</span>
<span class="s2">"msg"</span><span class="p">:</span> <span class="s2">""</span>
<span class="p">}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">code</span></code> is the error code. See … for available errors and error codes.</p>
<p>Errors occuring will be put in an <code class="docutils literal notranslate"><span class="pre">error</span></code> key.</p>
<p>Server-level errors (unhandled exceptions or errors not occuring in api-functions) will add
the <code class="docutils literal notranslate"><span class="pre">error</span></code> key at the root level of the payload:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"session"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="p">{},</span>
<span class="s2">"error"</span><span class="p">:</span> <span class="p">{}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Likewise, errors occuring in api-functions will add the <code class="docutils literal notranslate"><span class="pre">error</span></code> key in the <em>function-data</em> object:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"fname"</span><span class="p">:</span> <span class="s2">"func2"</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="p">{},</span>
<span class="s2">"error"</span><span class="p">:</span> <span class="p">{}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="server-commands">
<h2>Server commands<a class="headerlink" href="#server-commands" title="Permalink to this headline">¶</a></h2>
<p>The server implements server commands to control the server remotely: <a class="reference internal" href="api_general.html#happypanda.interface.enums.ServerCommand" title="happypanda.interface.enums.ServerCommand"><code class="xref py py-class docutils literal notranslate"><span class="pre">ServerCommand</span></code></a></p>
<p>Server commands are invoked like this (this is the whole payload):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"session"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="n">server_command</span>
<span class="p">}</span>
</pre></div>
</div>
<p>For example, if we want to shut down the server we use the <a class="reference internal" href="api_general.html#happypanda.interface.enums.ServerCommand.ServerQuit" title="happypanda.interface.enums.ServerCommand.ServerQuit"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ServerCommand.ServerQuit</span></code></a> command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"session"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">"clientname"</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="s2">"serverquit"</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Some server commands will be broadcasted to all connected clients before executing.</p>
<p>For example, when the server recieves a shut down command, the exact command will be propogated and broadcasted to all connected clients:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"session"</span><span class="p">:</span> <span class="s2">""</span><span class="p">,</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">"servername"</span><span class="p">,</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="s2">"serverquit"</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition-todo admonition" id="id4">
<p class="admonition-title">Todo</p>
<p>server commands broadcasting (shutting down gracefully)</p>
</div>
</div>
<div class="section" id="playing-with-the-api">
<h2>Playing with the API<a class="headerlink" href="#playing-with-the-api" title="Permalink to this headline">¶</a></h2>
<p>The default webclient has a place for watching and testing the exchanges between the server and the client.</p>
<p>Start the webclient with the <code class="docutils literal notranslate"><span class="pre">--debug</span></code> switch and go to <code class="docutils literal notranslate"><span class="pre">/api</span></code>.</p>
</div>
</div>
</div>
</div>
<div class="row">
<script src="https://utteranc.es/client.js"
repo="happypandax/happypandax.github.io"
issue-term="pathname"
label="💬 docs"
theme="github-light"
crossorigin="anonymous"
async>
</script>
</div>
</div>
<script async defer src="https://buttons.github.io/buttons.js"></script>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
<br/>
</p>
<p>
© Copyright Twiddly.<br/>
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 3.2.1.<br/>
</p>
</div>
</footer>
</body>
</html>