-
Notifications
You must be signed in to change notification settings - Fork 16
/
bayeux.html
1903 lines (1664 loc) · 134 KB
/
bayeux.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
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!-- saved from url=(0046)http://svn.cometd.com/trunk/bayeux/bayeux.html -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><!--
TODO:
* clarify role of globbing in publication. We know that clients can
subscribe to them, but can they publish to a glob?
* tighten up the language for the /service/** topic namespace
* provide examples of full, conforming Bayeux conversations
* clarify error handling and recovery for all protocol verbs
* auto-generate a TOC?
--><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>The Bayeux Protocol</title>
<script type="text/javascript" src="dojo.js"></script>
<script type="text/javascript">
<!-- Generate Table Of Contents Links -->
dojo.addOnLoad(function()
{
var ctr = 0;
dojo.query(".clause").forEach(function(n)
{
// add jump links to each of the headings in the document that we care about
var a = document.createElement("a");
a.id = "toc_" + ctr++;
dojo.place(a, n, "before");
// populate the document with a TOC that will now jump to those links
var a2 = document.createElement("a");
a2.href = "#" + a.id;
a2.appendChild(n.cloneNode(true));
dojo.place(a2, "toc", "last");
});
// if we landed on this page with a TOC hash in the URL, we should jump to it here
var url = new dojo._Url(window.location);
if (url.fragment && dojo.byId(url.fragment))
{
window.location = "#" + url.fragment;
}
});
</script>
<style type="text/css">
body
{
margin: 3em;
font: 13px sans-serif;
}
h1 { font-size: 1.5em; }
h2 { font-size: 1.2em; }
h3, h4, h5, h6 { font-size: 1em; }
h1.title { text-align: center; }
h1.intro { text-align: center; }
table.info { width: 100%; }
pre, code
{
font-family: monospace;
background-color: #efefef;
border: 1px solid #ccc;
padding: 1.5em;
}
dl { margin-left: 1em; }
dt { font-weight: bold; }
dd { margin-left: 2em; margin-bottom: 0.5em; }
.note { color: red }
#toc { margin-left: 2em; }
#toc h1, #toc h2, #toc h3, #toc h4
{
padding: 0;
margin-top: 0;
margin-bottom: 0;
font-size: 0.9em;
}
#toc h2 { margin-left: 2em; }
#toc h3 { margin-left: 4em; }
#toc h4 { margin-left: 6em; }
</style>
</head>
<body>
<h1 class="title">The Bayeux Specification</h1>
<table class="info tabular">
<tbody><tr>
<td>
<b>Request for Comments:</b> not an RFC<br>
<b>Category:</b> Standards Track<br>
</td>
<td>
Alex Russell<br>
Greg Wilkins<br>
David Davis<br>
Mark Nesbitt<br>
</td>
</tr>
</tbody></table>
<h1 class="intro">Bayeux Protocol -- Bayeux 1.0.0</h1>
<h2 class="intro">Status of this Memo</h2>
<p>
This document specifies a protocol for the Internet community, and requests
discussion and suggestions for improvement.<br>
This memo is written in the style and spirit of an IETF RFC but is not,
as of yet, an official IETF RFC.<br>
Distribution of this memo is unlimited. This memo is written in UK English.
</p>
<h2 class="intro">Copyright Notice</h2>
<p>Copyright © The Dojo Foundation (2007). All Rights Reserved</p>
<h2 class="intro">Abstract</h2>
<p>
Bayeux is a protocol for transporting asynchronous messages (primarily over HTTP),
with low latency between a web server and web clients.
</p>
<h1 class="contents">Table of Contents</h1>
<div id="toc"><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_0"><h1 class="clause">1. Introduction</h1></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_1"><h2 class="clause">1.1. Purpose</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_2"><h2 class="clause">1.2. Requirements</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_3"><h2 class="clause">1.3. Terminology</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_4"><h2 class="clause">1.4. Overall Operation</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_5"><h3 class="clause">1.4.1. HTTP Transport</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_6"><h3 class="clause">1.4.2. Non HTTP Transports</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_7"><h3 class="clause">1.4.3. Javascript</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_8"><h3 class="clause">1.4.4. Client to Server event delivery</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_9"><h3 class="clause">1.4.5. Server to Client event delivery </h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_10"><h4 class="clause">1.4.5.i Polling transports</h4></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_11"><h4 class="clause">1.4.5.ii Streaming transports</h4></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_12"><h3 class="clause">1.4.6. Two connection operation</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_13"><h3 class="clause">1.4.7. Connection Negotiation</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_14"><h3 class="clause">1.4.8. Unconnected operation</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_15"><h2 class="clause">1.5 State Tables</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_16"><h3 class="clause">1.5.1 Client State</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_17"><h1 class="clause">2. Protocol values</h1></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_18"><h2 class="clause">2.1. Common Elements</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_19"><h2 class="clause">2.2. Channels</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_20"><h3 class="clause">2.2.1 Channel Globbing</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_21"><h3 class="clause">2.2.2 Meta Channels</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_22"><h3 class="clause">2.2.3 Service Channels</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_23"><h2 class="clause">2.3. Version</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_24"><h2 class="clause">2.4. Client ID</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_25"><h2 class="clause">2.5 Messages</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_26"><h1 class="clause">3. Message Field Definitions</h1></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_27"><h2 class="clause">3.1. channel</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_28"><h2 class="clause">3.2. version</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_29"><h2 class="clause">3.3. minimumVersion</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_30"><h2 class="clause">3.4. supportedConnectionTypes</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_31"><h2 class="clause">3.5. clientId</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_32"><h2 class="clause">3.6. advice</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_33"><h3 class="clause">3.6.1. reconnect advice</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_34"><h3 class="clause">3.6.2. interval advice</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_35"><h3 class="clause">3.6.3. multiple-clients advice</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_36"><h3 class="clause">3.6.4. hosts advice</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_37"><h2 class="clause">3.7. connectionType</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_38"><h2 class="clause">3.8. id</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_39"><h2 class="clause">3.9. timestamp</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_40"><h2 class="clause">3.10. data</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_41"><h2 class="clause">3.11. connectionId</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_42"><h2 class="clause">3.12. successful</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_43"><h2 class="clause">3.13. subscription</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_44"><h2 class="clause">3.14. error</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_45"><h2 class="clause">3.15. ext</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_46"><h2 class="clause">3.16. json-comment-filtered</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_47"><h1 class="clause">4. Meta Message Definitions</h1></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_48"><h2 class="clause">4.1. Handshake</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_49"><h3 class="clause">4.1.1. Handshake Request</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_50"><h3 class="clause">4.1.2. Handshake Response</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_51"><h2 class="clause">4.2. Connect</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_52"><h3 class="clause">4.2.1. Connect Request</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_53"><h3 class="clause">4.2.2. Connect Response</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_54"><h2 class="clause">4.4. Disconnect</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_55"><h3 class="clause">4.4.1. Disconnect Request</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_56"><h3 class="clause">4.4.2. Disconnect Response</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_57"><h2 class="clause">4.5. Subscribe</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_58"><h3 class="clause">4.5.1. Subscribe Request</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_59"><h3 class="clause">4.5.2. Subscribe Response</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_60"><h2 class="clause">4.6. Unsubscribe</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_61"><h3 class="clause">4.6.1. Unsubscribe Request</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_62"><h3 class="clause">4.6.2. Unsubscribe Response</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_63"><h1 class="clause">5. Event Message Definitions</h1></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_64"><h2 class="clause">5.1. Publish</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_65"><h3 class="clause">5.1.1. Publish Request</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_66"><h3 class="clause">5.1.2. Publish Response</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_67"><h2 class="clause">5.2. Delivery of event messages</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_68"><h1 class="clause">6. Transports</h1></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_69"><h2 class="clause">6.1. long-polling</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_70"><h3 class="clause">6.1.1 long-polling request messages</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_71"><h3 class="clause">6.1.2 long-polling response messages</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_72"><h2 class="clause">6.2. callback-polling</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_73"><h3 class="clause">6.2.1 callback-polling request messages</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_74"><h3 class="clause">6.2.2 callback-polling response messages</h3></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_75"><h1 class="clause">7. Security</h1></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_76"><h2 class="clause">7.1. Authentication</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_77"><h2 class="clause">7.2. Ajax Hijacking</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_78"><h1 class="clause">8. Multiple clients operation</h1></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_79"><h2 class="clause">8.1 Server-side Multiple clients detection</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_80"><h2 class="clause">8.2 Client-side Multiple clients handling</h2></a><a href="http://svn.cometd.com/trunk/bayeux/bayeux.html#toc_81"><h1 class="clause">9. Request / Response operation with service channels</h1></a></div>
<a id="toc_0"></a><h1 class="clause">1. Introduction</h1>
<a id="toc_1"></a><h2 class="clause">1.1. Purpose</h2>
<p>
The primary purpose of Bayeux is to support responsive bidirectional interactions between
web clients, for example using using <a href="http://en.wikipedia.org/wiki/AJAX">AJAX</a>, and the web server.
</p>
<p>
Bayeux is a protocol for transporting asynchronous messages (primarily over HTTP), with low latency between a web
server and a web client.
The messages are routed via named channels and can be delivered:
</p>
<ul>
<li>server to client</li>
<li>client to server</li>
<li>client to client (via the server)</li>
</ul>
<p>
By default, publish subscribe routing semantics are applied to the channels.
</p>
<p>
Delivery of asynchronous messages from the server to a web client is often described as <em>server-push</em>.<br>
The combination of server push techniques with an Ajax web application has been called <em>Comet</em>.<br>
CometD is a project by the Dojo Foundation to provide multiple implementation of the Bayeux protocol
in several programming languages.
</p>
<p>
Bayeux seeks to reduce the complexity of developing Comet web applications
by allowing implementors to more easily interoperate, to solve common message
distribution and routing problems, and to provide mechanisms for incremental
improvements and extensions.
</p>
<a id="toc_2"></a><h2 class="clause">1.2. Requirements</h2>
<p>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC2119. An implementation is not compliant if it
fails to satisfy one or more of the MUST or REQUIRED level requirements for the
protocols it implements. An implementation that satisfies all the MUST or
REQUIRED level and all the SHOULD level requirements for its protocols is said
to be "unconditionally compliant"; one that satisfies all the MUST level
requirements but not all the SHOULD level requirements for its protocols is
said to be "conditionally compliant."
</p>
<a id="toc_3"></a><h2 class="clause">1.3. Terminology</h2>
<p>
This specification uses a number of terms to refer to the roles played by
participants in, and objects of, Bayeux communication:
</p>
<dl>
<dt>client</dt>
<dd>
A program that initiates the communication.<br>
A HTTP client is a client that initiates TCP/IP connections for the purpose of sending HTTP requests.<br>
A Bayeux client initiates the Bayeux message exchange and will typically
execute within a HTTP client, but it is likely to have Bayeux clients that
execute within HTTP servers. Implementations may distinguish between
Bayeux clients running within a HTTP client and Bayeux clients running
within the HTTP server. Specifically server-side Bayeux clients MAY be
privileged clients with access to private information about other clients
(e.g. client IDs) and subscriptions.
<!--
COMMENT:
Consider explicitly defining the terms "remote client" and "local/server-side client".
By saying implementations are allowed to distinguish between them, the spec is implicitly
ack'ing the distinction anyway. More on this later re: the handling of meta channels.
-->
</dd>
<dt>server</dt>
<dd>
An application program that accepts communications from clients.<br>
A HTTP server accepts TCP/IP connections in order to service HTTP requests by
sending back HTTP responses.<br>
A Bayeux server accepts and responds to the message exchanges initiated by a Bayeux client.
</dd>
<dt>request</dt>
<dd>
An HTTP request message as defined by section 5 of RFC 2616.
</dd>
<dt>response</dt>
<dd>
A HTTP response message as defined by section 6 of RFC 2616.
</dd>
<dt>message</dt>
<dd>
A message is a JSON encoded object exchanged between client and server for the
purpose of implementing the Bayeux protocol as defined by sections 3, 4 and 5.
</dd>
<dt>event</dt>
<dd>
Application specific data that is sent over the Bayeux protocol
</dd>
<dt>envelope</dt>
<dd>
The transport specific message format that wraps a standard Bayeux message.
</dd>
<dt>channel</dt>
<dd>
A named destination and/or source of events.<br>
Events are published to channels and subscribers to channels receive the published events.
</dd>
<dt>connection</dt>
<dd>
A communication link that is established either permanently
or transiently, for the purposes of messages exchange.<br>
A client is connected if a link is established with the server,
over which asynchronous events can be received.
</dd>
<dt>JSON</dt>
<dd>
JavaScript Object Notation (JSON) is a lightweight data-interchange format.<br>
It is easy for humans to read and write. It is easy for machines to parse
and generate. It is based on a subset of the JavaScript Programming
Language, Standard ECMA-262 3rd Edition - December 1999.<br>
JSON is described at <a href="http://www.json.org/">http://www.json.org/</a>.
</dd>
</dl>
<a id="toc_4"></a><h2 class="clause">1.4. Overall Operation</h2>
<a id="toc_5"></a><h3 class="clause">1.4.1. HTTP Transport</h3>
<p>
The HTTP protocol is a request/response protocol. A client sends a request to
the server in the form of a request method, URI, and protocol version, followed
by a MIME-like message containing request modifiers, client information, and
optional body content over a connection with a server. The server responds with
a status line, including the message's protocol version and a success or error
code, followed by a MIME-like message containing server information, entity
metainformation, and possible entity-body content.
</p>
<p>
The server may not initiate a connection with a client nor send an unrequested
response to the client, thus asynchronous events cannot be delivered from
server to client unless a previously issued request exists. In order to allow
two way asynchronous communication, Bayeux supports the use of multiple HTTP
connections between a client and server, so that previously issued requests are
available to transport server to client messages.
</p>
<p>
The recommendation of section 8.1.4 of RFC 2616 is that a single client
SHOULD NOT maintain more than 2 connection with any server, thus the Bayeux
protocol MUST NOT require any more than 2 HTTP requests to be simultaneously
handled by a server in order to handle all application (Bayeux based or
otherwise) requests from a client.
</p>
<a id="toc_6"></a><h3 class="clause">1.4.2. Non HTTP Transports</h3>
<!--
FIXME: we are currently silent on some important points:
1.) must conforming servers which don't use HTTP *also* support one or
more of the HTTP-based mechanisms?
2.) must conforming servers that aren't HTTP-based support plain-text
payloads?
-->
<p>
While HTTP is the predominant transport protocol used on the internet, it is
not intended that it will be the only transport for Bayeux. Other transports
that support a request/response paradigm may be used. However this document
assumes HTTP for reasons of clarity. When non-HTTP connection-level
transport mechanisms are employed, conforming Bayeux servers and clients MUST
still conform to the semantics of the JSON encoded messages outlined in this document.
</p>
<p>
Several of the "transport types" described in this document are distinguished
primarily by how they wrap messages for delivery over HTTP and the sequence
and content of the HTTP connections initiated by clients. While this may seem
like a set of implementation concerns to observant readers, the difficulties of
creating interoperable implementations without specifying these semantics fully
is a primary motivation for the development of this specification.<br>
Were the deployed universe of servers and clients more flexible, it may not
have been necessary to develop Bayeux.
</p>
<p>
Regardless, care has been taken in the development of this specification to
ensure that future clients and servers which implement differing
connection-level strategies and encodings may still evolve and continue to be
conforming Bayeux implementations so long as they implement the JSON-based
public/subscribe semantics outlined herein.
</p>
<p class="note">
The rest of this document speaks as though HTTP will be used for message transport.
</p>
<a id="toc_7"></a><h3 class="clause">1.4.3. Javascript</h3>
<p>
Bayeux clients implemented in JavaScript that run within the security
framework of a browser MUST adhere to the restrictions imposed
by the browser, such as the <a href="http://en.wikipedia.org/wiki/Same_origin_policy">same origin policy</a>
or the <a href="http://www.w3.org/TR/access-control/">CORS</a> specification,
or the threading model.<br>
These restrictions are normally enforced by the browser itself, but nonetheless
the client implementation must be aware of these restrictions and adhere to them.
</p>
<p>
Bayeux clients implemented in JavaScript but not running within a browser MAY
relax the restrictions imposed by browsers.
</p>
<a id="toc_8"></a><h3 class="clause">1.4.4. Client to Server event delivery</h3>
<p>
A Bayeux event is sent from the client to the server via a HTTP request
initiated by a client and transmitted to the origin server via a chain of
zero or more intermediaries (proxy, gateway or tunnel):
</p>
<pre class="example">BC ---------- U ---------- P ------------ O ---------- BS
| --M0(E)--> | | | |
| | ---HTTP request(M0(E))--> | |
| | | | --M0(E)--> |
| | | | <---M1---- |
| | <---HTTP response(M1)---- | |
| <---M1--- | | | |
| | | | |
</pre>
<p>
The figure above represents a Bayeux event E encapsulated in a Bayeux message M0
being sent from a Bayeux client BC to a Bayeux server BS via a HTTP request
transmitted from a User Agent U to to an Origin server O via a proxy P. The
HTTP response contains another Bayeux message M1 that will at least contain the
protocol response to M0, but may contain other Bayeux events initiated on the
server or on other clients.
</p>
<a id="toc_9"></a><h3 class="clause">1.4.5. Server to Client event delivery </h3>
<p>
A Bayeux event is sent from the server to the client via a HTTP response to
a HTTP request sent in anticipation by a client and transmitted to an
origin server via a chain of zero or more intermediaries (proxy, gateway or
tunnel):
</p>
<pre class="example">BC ---------- U ---------- P ------------ O ---------- BS
| ---M0---> | | | |
| | --- HTTP request(M0) ---> | |
| | | | ----M0---> |
~ ~ ~ ~ ~ wait
| | | | <--M1(E)-- |
| | <--HTTP response(M1(E))-- | |
| <--M1(E)-- | | | |
~ ~ ~ ~ ~
</pre>
<p>
The figure above represents a Bayeux message M0 being sent from a Bayeux client
BC to a Bayeux server BS via a HTTP request transmitted from a User Agent U to
to an Origin server O via a proxy P. The message M0 is sent in anticipation of
a Bayeux event to be delivered from server to client and the Bayeux server
waits for such an event before sending a response. A Bayeux event E is shown
being delivered via Bayeux message M1 in the HTTP response. M1 may contain
zero, one or more Bayeux events destined for the Bayeux client.
</p>
<p>
The transprt used to send events from the server to the client may terminate
the HTTP response (which does not imply that the connection is closed) after
delivery of M1 or use techniques to leave the HTTP response uncompleted and
stream additional messages to the client.
</p>
<a id="toc_10"></a><h4 class="clause">1.4.5.i Polling transports</h4>
<p>
Polling transports will always terminate the HTTP response after sending all
available Bayeux messages.
</p>
<pre class="example">BC ---------- U ---------- P ------------ O ---------- BS
| ---M0---> | | | |
| | --- HTTP request(M0) ---> | |
| | | | ----M0---> |
~ ~ ~ ~ ~ wait
| | | | <--M1(E)-- |
| | <--HTTP response(M1(E))-- | |
| <--M1(E)-- | | | |
| ---M2---> | | | |
| | --- HTTP request(M2) ---> | |
| | | | ----M2---> |
~ ~ ~ ~ ~ wait
</pre>
<p>
On receipt of the HTTP response containing M1, the Bayeux client issues a new
Bayeux message M2 either immediately or after an interval in anticipation of
more events to be delivered from server to client.<br>
Bayeux implementations MUST support a specific style of polling
transport called <em>long polling</em> (see sec 6.1).
</p>
<a id="toc_11"></a><h4 class="clause">1.4.5.ii Streaming transports</h4>
<p>
Some Bayeux transports use the <em>streaming technique</em> (also called the
<em>forever response</em>) that allows multiple messages to be sent within the
same HTTP response:
</p>
<pre class="example">BC ---------- U ---------- P ------------ O ---------- BS
| ---M0---> | | | |
| | --- HTTP request(M0) ---> | |
| | | | ----M0---> |
~ ~ ~ ~ ~ wait
| | | | <--M1(E0)- |
| | <--HTTP response(M1(E0))- | |
| <--M1(E0)- | | | |
~ ~ ~ ~ ~ wait
| | | | <--M1(E1)- |
| | <----(M1(E1))------------ | |
| <--M1(E1)- | | | |
~ ~ ~ ~ ~ wait
</pre>
<p>
Streaming techniques avoid the latency and extra messaging of anticipatory
requests, but are subject to the implementation of user agents and proxies as they
requires incomplete HTTP responses to be delivered to the Bayeux client.
</p>
<a id="toc_12"></a><h3 class="clause">1.4.6. Two connection operation</h3>
<p>
In order to achieve bidirectional communication, a Bayeux client uses 2
HTTP connections (see section 1.4.1) to a Bayeux server so that both server to client and
client to server messaging may occur asynchronously:
</p>
<pre class="example">BC ---------- U ---------- P ------------ O ---------- BS
| ---M0---> | | | |
| | ------ req0(M0) --------> | |
| | | | ----M0---> |
~ ~ ~ ~ ~ wait
| --M1(E1)-> | | | |
| | ----- req1(M1(E1))------> | |
| | | | --M1(E1)-> |
| | | | <---M2---- |
| | <---- resp1(M2)---------- | |
| <---M2--- | | | |
~ ~ ~ ~ ~ wait
| | | | <-M3(E2)-- |
| | <-----resp2(M3(E2))------ | |
| <-M3(E2)-- | | | |
| ---M4---> | | | |
| | ------req3(M4)----------> | |
| | | | ----M4---> |
~ ~ ~ ~ ~ wait
</pre>
<p>
HTTP requests req0 and req1 are sent on different TCP/IP connections, so that
the response to req1 may be sent before the response to req0. Implementations
MUST control HTTP pipelining so that req1 does not get queued behind req0 and
thus enforce an ordering of responses.
</p>
<a id="toc_13"></a><h3 class="clause">1.4.7. Connection Negotiation</h3>
<p>
Bayeux connections are negotiated between client and server with handshake
messages that allow the connection type, authentication and other parameters to
be agreed upon between the client and the server.
</p>
<pre class="example">BC ----------------------------------------- BS
| ------------------ handshake request ---> |
| <---- handshake response ---------------- |
| -------------------- connect request ---> |
~ ~ wait
| <------ connect response ---------------- |
</pre>
<p>
Connection negotiation may be iterative and several handshake messages may be
exchanged before a successful connection is obtained. Servers may also request
connection renegotiation by sending an unsuccessful connect response with
advice to reconnect with a handshake message.
</p>
<pre class="example">BC ----------------------------------------- BS
| ------------------ handshake request ---> |
| <-- unsuccessful handshake response ----- |
| ------------------ handshake request ---> |
| <-- successful handshake response ------- |
| -------------------- connect request ---> |
~ ~ wait
| <------ connect response ---------------- |
| -------------------- connect request ---> |
| <---- unsucessful connect response ------ |
| ------------------ handshake request ---> |
| <-- successful handshake response ------- |
| -------------------- connect request ---> |
~ ~ wait
| <------ connect response ---------------- |
</pre>
<a id="toc_14"></a><h3 class="clause">1.4.8. Unconnected operation</h3>
<p>
OPTIONALLY, messages can be sent without a prior handshake (see 5.1 Publish event messages).
</p>
<pre class="example">BC ----------------------------------------- BS
| ------------------- message request ----> |
| <---- message response ------------------ |
</pre>
<p>
This pattern is often useful when implementing non-browser clients for Bayeux
servers. These clients often simply wish to address messages to other clients
which the Bayeux server may be servicing, but do not wish to listen for events
themselves.
</p>
<a id="toc_15"></a><h2 class="clause">1.5 State Tables</h2>
<a id="toc_16"></a><h3 class="clause">1.5.1 Client State</h3>
<pre class="example"> -------------++------------+-------------+------------+------------
State/Event || handshake | Timeout | Successful | Disconnect
|| request | | connect | request
|| sent | | response | sent
-------------++------------+-------------+----------- +------------
UNCONNECTED || CONNECTING | UNCONNECTED | |
CONNECTING || | UNCONNECTED | CONNECTED | UNCONNECTED
CONNECTED || | UNCONNECTED | | UNCONNECTED
-------------++------------+-------------+------------+------------
</pre>
<a id="toc_17"></a><h1 class="clause">2. Protocol values</h1>
<a id="toc_18"></a><h2 class="clause">2.1. Common Elements</h2>
<p>
The characters used for Bayeux names and identifiers are defined by the BNF definitions:
</p>
<pre class="example">alpha = lowalpha | upalpha
lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" |
"j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" |
"s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
upalpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" |
"J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" |
"S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
alphanum = alpha | digit
mark = "-" | "_" | "!" | "~" | "(" | ")" | "$" | "@"
string = *( alphanum | mark | " " | "/" | "*" | "." )
token = ( alphanum | mark ) *( alphanum | mark )
integer = digit *( digit )
</pre>
<a id="toc_19"></a><h2 class="clause">2.2. Channels</h2>
<p>
Channels are identified by names that are styled as the absolute path component of
a URI without parameters as defined by RFC2396.
</p>
<pre class="example">channel_name = "/" channel_segments
channel_segments = channel_segment *( "/" channel_segment )
channel_segment = token
</pre>
<p>
The channel name consists of an initial "/" followed by an optional sequence of
path segments separated by a single slash "/" character. Within a path segment,
the character "/" is reserved.
</p>
<p>
Channel names commencing with "/meta/" are reserved for the Bayeux protocol.<br>
Example non-meta channel names are:
</p>
<dl>
<dt>/foo</dt>
<dt>/foo/bar</dt>
<dt>/foo-bar/(foobar)</dt>
</dl>
<a id="toc_20"></a><h3 class="clause">2.2.1 Channel Globbing</h3>
<p>
A set of channels may be specified with a channel globbing pattern:
</p>
<pre class="example">channel_pattern = *( "/" channel_segment ) "/" wild_card
wild_card = "*" | "**"
</pre>
<p>
The channel patterns support only trailing wildcards of either "*" to match a
single segment or "**" to match multiple segments. Example channel patterns are:
</p>
<dl>
<dt>/foo/*</dt>
<dd>
Matches /foo/bar and /foo/boo. Does not match /foo, /foobar or /foo/bar/boo.
</dd>
<dt>/foo/**</dt>
<dd>
Matches /foo/bar, /foo/boo and /foo/bar/boo. Does not match /foo, /foobar
or /foobar/boo
</dd>
</dl>
<a id="toc_21"></a><h3 class="clause">2.2.2 Meta Channels</h3>
<p>
The channels within the "/meta/" segment are the channels used by the Bayeux
protocol itself.<br>
Local server-side Bayeux clients MAY, and remote Bayeux clients SHOULD NOT,
subscribe (see section 4.5) to meta channels.<br>
Messages published to meta channels MUST NOT be distributed to remote clients
by Bayeux servers. A server side handler of a meta channel MAY publish response
messages that are delivered only to the client that sent the original request message.<br>
If a message published to a meta channel contains an id field, then any
response messages delivered to the client MUST contain an id field with the
same value.
</p>
<a id="toc_22"></a><h3 class="clause">2.2.3 Service Channels</h3>
<p>
The channels within the "/service/" channel segment are special channels
designed to assist request/response style messaging.<br>
Messages published to service channels are not distributed to any remote Bayeux clients.
Handlers of service channels MAY deliver response messages to the client that
published the request message. Servers SHOULD NOT record any subscriptions they
receive for service channels.<br>
If a message published to a service channel contains an id field, then any
response messages SHOULD contain an id field with the same value or a value
derived from the request id.<br>
Request/response operations are described in detail in section 9.
</p>
<a id="toc_23"></a><h2 class="clause">2.3. Version</h2>
<p>
A protocol version is a integer followed by an optional "." separated sequence
of alphanumeric elements:
</p>
<pre class="example">version = integer *( "." version_element )
version_element = alphanum *( alphanum | "-" | "_" )
</pre>
<p>
Versions are compared element by element, applying normal alphanumeric
comparison to each element.
</p>
<a id="toc_24"></a><h2 class="clause">2.4. Client ID</h2>
<p>
A client ID is an random, non predictable sequence of alpha numeric characters:
</p>
<pre class="example">clientId = alphanum *( alphanum )
</pre>
<p>
Client IDs are generated by the server and SHOULD be created with a strong
random algorithm that contains at least 128 truly random bits. Servers MUST
ensure that client IDs are unique and SHOULD attempt to avoid reuse of client
IDs. Client IDs are encoded for delivery as strings.
</p>
<a id="toc_25"></a><h2 class="clause">2.5 Messages</h2>
<p>
Bayeux messages are JSON encoded objects that contain an unordered sequence of
name value pairs representing fields and values. Values may be a simple
strings, numbers, boolean values, or complex JSON encoded objects or arrays.<br>
A Bayeux message MUST contain one and only one channel field which determines
the type of the message and the allowable fields.
</p>
<p>
All Bayeux messages SHOULD be encapsulated in a JSON encoded array so that multiple
messages may be transported together. A Bayeux client or server MUST accept
either array of messages and MAY accept a single message. The JSON encoded message or
array of messages is itself often encapsulated in transport specific formatting
and encodings. Below is an example Bayeux message in a JSON encoded array representing
an event sent from a client to a server:
</p>
<pre class="example">[
{
"channel": "/some/name",
"clientId": "83js73jsh29sjd92",
"data": { "myapp" : "specific data", value: 100 }
}
]
</pre>
<a id="toc_26"></a><h1 class="clause">3. Message Field Definitions</h1>
<a id="toc_27"></a><h2 class="clause">3.1. channel</h2>
<p>
The channel message field MUST be included in every Bayeux message to specify
the source or destination of the message. In a request, the channel specifies
the destination of the message, and in a response it specifies the source of
the message.
</p>
<a id="toc_28"></a><h2 class="clause">3.2. version</h2>
<p>
The version message field MUST be included in messages to/from the
"/meta/handshake" channel to indicate the protocol version expected by the
client/server.
</p>
<a id="toc_29"></a><h2 class="clause">3.3. minimumVersion</h2>
<p>
The minimumVersion message field MAY be included in messages to/from the
"/meta/handshake" channel to indicate the oldest protocol version that can be
handled by the client/server.
</p>
<a id="toc_30"></a><h2 class="clause">3.4. supportedConnectionTypes</h2>
<p>
The supportedConnectionTypes field is included in messages to/from the
"/meta/handshake" channel to allow clients and servers to reveal the transports
that are supported. The value is an array of strings, with each string
representing a transport name. Defined connection types include:
</p>
<dl>
<dt>long-polling</dt>
<dd>
This transport is defined in section 6.1.
</dd>
<dt>callback-polling</dt>
<dd>
This transport is defined in section 6.2.
</dd>
<dt>iframe</dt>
<dd>
OPTIONAL transport using the document content of a hidden iframe element.
</dd>
<dt>flash</dt>
<dd>
OPTIONAL transport using the capabilities of a browser flash plugin.
</dd>
</dl>
<p>
All server and client implementations MUST support the "long-polling"
connection type and SHOULD support "callback-polling".<br>
All other connection types are OPTIONAL.
</p>
<a id="toc_31"></a><h2 class="clause">3.5. clientId</h2>
<p>
The clientId message field uniquely identifies a client to the Bayeux server.
The clientId message field MUST be included in every message sent to the server
except for messages sent to the "/meta/handshake" channel and MAY be omitted in
a publish message (see section 5.1).<br>
The clientId field MUST be returned in every message response except for a
failed handshake request and for a publish message response that was send without
clientId.
</p>
<a id="toc_32"></a><h2 class="clause">3.6. advice</h2>
<p>
The advice field provides a way for servers to inform clients of their
preferred mode of client operation so that in conjunction with server-enforced
limits, Bayeux implementations can prevent resource exhaustion and inelegant
failure modes.
</p>
<p>
The advice field is a JSON encoded object containing general and transport specific values
that indicate modes of operation, timeouts and other potential transport
specific parameters. Fields may occur either in the top level of a message or
within a transport specific section.
</p>
<p>
Unless otherwise specified in sections 5 and 6, any Bayeux response message may
contain an advice field. Advice received always superceeds any previous
received advice.
</p>
<p>
An example advice field is:
</p>
<pre class="example"> "advice": {
"reconnect": "retry",
"interval": 1000,
"callback-polling": {
"reconnect": "handshake"
}
}
</pre>
<!-- FIXME: need more advice examples here! -->
<a id="toc_33"></a><h3 class="clause">3.6.1. reconnect advice</h3>
<p>
The reconnect advice field is a string that indicates how the client should
act in the case of a failure to connect. Defined reconnect values are:
</p>
<dl>
<dt>retry</dt>
<dd>
a client MAY attempt to reconnect with a /meta/connect after the interval (as defined by "interval"
advice or client-default backoff), and with the same credentials.
</dd>
<dt>handshake</dt>
<dd>
the server has terminated any prior connection status and the client MUST
reconnect with a /meta/handshake message.<br>
A client MUST NOT automatically retry if handshake reconnect has been received.
</dd>
<dt>none</dt>
<dd>
hard failure for the connect attempt. Do not attempt to reconnect at all.<br>
A client MUST respect reconnect advice of none and MUST NOT automatically
retry or handshake.
</dd>
</dl>
<p>
Any client that does not implement all defined values of reconnect MUST NOT
automatically retry or handshake.
</p>
<a id="toc_34"></a><h3 class="clause">3.6.2. interval advice</h3>
<p>
An integer representing the minimum period in milliseconds for a client to delay
subsequent requests to the /meta/connect channel.<br>
A negative period indicates that the message should not be retried.
</p>
<p>
A client MUST implement interval support, but a client MAY exceed the interval
provided by the server. A client SHOULD implement a backoff strategy to
increase the interval if requests to the server fail without new advice being
received from the server.
</p>
<a id="toc_35"></a><h3 class="clause">3.6.3. multiple-clients advice</h3>
<p>
This is a boolean field, which if true indicates that the server has detected
multiple Bayeux client instances running within the same HTTP client.
</p>
<a id="toc_36"></a><h3 class="clause">3.6.4. hosts advice</h3>
<p>
This is an array of strings field, which if present indicates a list of host
names or IP addresses that MAY be used as alternate servers with which the
client may connect. If a client receives advice to re-handshake and the
current server is not included in a supplied hosts list, then the client SHOULD
try the hosts in order until a successful connection is establish. Advice
received during handshakes with hosts in the list supercedes any previously
received advice.
</p>
<a id="toc_37"></a><h2 class="clause">3.7. connectionType</h2>
<p>
The connectionType message field specifies the type of transport the client
requires for communication. The connectionType message field MUST be included
in request messages to the "/meta/connect" channel. Connection types are
listed in section 3.4.
</p>
<a id="toc_38"></a><h2 class="clause">3.8. id</h2>
<p>
An id field MAY be included in any Bayeux message with an alpha numeric value:
</p>
<pre class="example">id = alphanum *( alphanum )
</pre>
<p>
Generation of IDs is implementation specific and may be provided by the
application. Messages published to /meta/** and /service/** SHOULD have id
fields that are unique within the the connection.
</p>
<p>
Messages sent in response to messages delivered to /meta/** channels MUST use
the same message id as the request message.
</p>
<p>
Messages sent in response to messages delivered to /service/** channels SHOULD
use the same message id as the request message or an id derived from the
request message id.
</p>
<a id="toc_39"></a><h2 class="clause">3.9. timestamp</h2>
<p>
The timestamp message field SHOULD be specified in the following ISO 8601
profile (all times SHOULD be sent in GMT time):
</p>
<pre class="example"> YYYY-MM-DDThh:mm:ss.ss
</pre>
<p>A timestamp message field is OPTIONAL in all Bayeux messages.</p>
<a id="toc_40"></a><h2 class="clause">3.10. data</h2>
<p>
The data message field is an arbitrary JSON encoded object that contains event
information. The data field MUST be included in publish messages, and a Bayeux
server MUST include the data field in an event delivery message.
</p>
<a id="toc_41"></a><h2 class="clause">3.11. connectionId</h2>
<p>
The connectionId field was used during development of the Bayeux protocol
and its use is now deprecated.
</p>
<a id="toc_42"></a><h2 class="clause">3.12. successful</h2>
<p>
The successful boolean message field is used to indicate success or failure and
MUST be included in responses to the "/meta/handshake", "/meta/connect",
"/meta/subscribe","/meta/unsubscribe", "/meta/disconnect", and publish
channels.
</p>
<a id="toc_43"></a><h2 class="clause">3.13. subscription</h2>
<p>
The subscription message field specifies the channels the client wishes to
subscribe to or unsubscribe from. The subscription message field MUST be
included in requests and responses to/from the "/meta/subscribe" or
"/meta/unsubscribe" channels.
</p>
<a id="toc_44"></a><h2 class="clause">3.14. error</h2>
<p>
The error message field is OPTIONAL in any Bayeux response.<br>
The error message field MAY indicate the type of error that occurred when a
request returns with a false successful message. The error message field should
be sent as a string in the following format:
</p>
<pre class="example">error = error_code ":" error_args ":" error_message
| error_code ":" ":" error_message
error_code = digit digit digit
error_args = string *( "," string )
error_message = string
</pre>
<p>
Example error strings are:
</p>
<pre>401::No client ID
402:xj3sjdsjdsjad:Unknown Client ID
403:xj3sjdsjdsjad,/foo/bar:Subscription denied
404:/foo/bar:Unknown Channel
</pre>
<a id="toc_45"></a><h2 class="clause">3.15. ext</h2>
<p>
An ext field MAY be included in any Bayeux message. Its value SHOULD be a
JSON encoded object with top level names distinguished by implementation names (eg.
"org.dojo.Bayeux.field").
</p>
<p>
The contents of ext may be arbitrary values that allow extensions to be
negotiated and implemented between server and client implementations.