-
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
-
1001
-
1002
-
1003
-
1004
-
1005
-
1006
-
1007
-
1008
-
1009
-
1010
-
1011
-
1012
-
1013
-
1014
-
1015
-
1016
-
1017
-
1018
-
1019
-
1020
-
1021
-
1022
-
1023
-
1024
-
1025
-
1026
-
1027
-
1028
-
1029
-
1030
-
1031
-
1032
-
1033
-
1034
-
1035
-
1036
-
1037
-
1038
-
1039
-
1040
-
1041
-
1042
-
1043
-
1044
-
1045
-
1046
-
1047
-
1048
-
1049
-
1050
-
1051
-
1052
-
1053
-
1054
-
1055
-
1056
-
1057
-
1058
-
1059
-
1060
-
1061
-
1062
-
1063
-
1064
-
1065
-
1066
-
1067
-
1068
-
1069
-
1070
-
1071
-
1072
-
1073
-
1074
-
1075
-
1076
-
1077
-
1078
-
1079
-
1080
-
1081
-
1082
-
1083
-
1084
-
1085
-
1086
-
1087
-
1088
-
1089
-
1090
-
1091
-
1092
-
1093
-
1094
-
1095
-
1096
-
1097
-
1098
-
1099
-
1100
-
1101
-
1102
-
1103
-
1104
-
1105
-
1106
-
1107
-
1108
-
1109
-
1110
-
1111
-
1112
-
1113
-
1114
-
1115
-
1116
-
1117
-
1118
-
1119
-
1120
-
1121
-
1122
-
1123
-
1124
-
1125
-
1126
-
1127
-
1128
-
1129
-
1130
-
1131
-
1132
-
1133
-
1134
-
1135
-
1136
-
1137
-
1138
-
1139
-
1140
-
1141
-
1142
-
1143
-
1144
-
1145
-
1146
-
1147
-
1148
-
1149
-
1150
-
1151
-
1152
-
1153
-
1154
-
1155
-
1156
-
1157
-
1158
-
1159
-
1160
-
1161
-
1162
-
1163
-
1164
-
1165
-
1166
-
1167
-
1168
-
1169
-
1170
-
1171
-
1172
-
1173
-
1174
-
1175
-
1176
-
1177
-
1178
-
1179
-
1180
-
1181
-
1182
-
1183
-
1184
-
1185
-
1186
-
1187
-
1188
-
1189
-
1190
-
1191
-
1192
-
1193
-
1194
-
1195
-
1196
-
1197
-
1198
-
1199
-
1200
-
1201
-
1202
-
1203
-
1204
-
1205
-
1206
-
1207
-
1208
-
1209
-
1210
-
1211
-
1212
-
1213
-
1214
-
1215
-
1216
-
1217
-
1218
-
1219
-
1220
-
1221
-
1222
-
1223
-
1224
-
1225
-
1226
-
1227
-
1228
-
1229
-
1230
-
1231
-
1232
-
1233
-
1234
-
1235
-
1236
-
1237
-
1238
-
1239
-
1240
-
1241
-
1242
-
1243
-
1244
-
1245
-
1246
-
1247
-
1248
-
1249
-
1250
-
1251
-
1252
-
1253
-
1254
-
1255
-
1256
-
1257
-
1258
-
1259
-
1260
-
1261
-
1262
-
1263
-
1264
-
1265
-
1266
-
1267
-
1268
-
1269
-
1270
-
1271
-
1272
-
1273
-
1274
-
1275
-
1276
-
1277
-
1278
-
1279
-
1280
-
1281
-
1282
-
1283
-
1284
-
1285
-
1286
-
1287
-
1288
-
1289
-
1290
-
1291
-
1292
-
1293
-
1294
-
1295
-
1296
-
1297
-
1298
-
1299
-
1300
-
1301
-
1302
-
1303
-
1304
-
1305
-
1306
-
1307
-
1308
-
1309
-
1310
-
1311
-
1312
-
1313
-
1314
-
1315
-
1316
-
1317
-
1318
-
1319
-
1320
-
1321
-
1322
-
1323
-
1324
-
1325
-
1326
-
1327
-
1328
-
1329
-
1330
-
1331
-
1332
-
1333
-
1334
-
1335
-
1336
-
1337
-
1338
-
1339
-
1340
-
1341
-
1342
-
1343
-
1344
-
1345
-
1346
-
1347
-
1348
-
1349
-
1350
-
1351
-
1352
-
1353
-
1354
-
1355
-
1356
-
1357
-
1358
-
1359
-
1360
-
1361
-
1362
-
1363
-
1364
-
1365
-
1366
-
1367
-
1368
-
1369
-
1370
-
1371
-
1372
-
1373
-
1374
-
1375
-
1376
-
1377
-
1378
-
1379
-
1380
-
1381
-
1382
-
1383
-
1384
-
1385
-
1386
-
1387
-
1388
-
1389
-
1390
-
1391
-
1392
-
1393
-
1394
-
1395
-
1396
-
1397
-
1398
-
1399
-
1400
-
1401
-
1402
-
1403
-
1404
-
1405
-
1406
-
1407
-
1408
-
1409
-
1410
-
1411
-
1412
-
1413
-
1414
-
1415
-
1416
-
1417
-
1418
-
1419
-
1420
-
1421
-
1422
-
1423
-
1424
-
1425
-
1426
-
1427
-
1428
-
1429
-
1430
-
1431
-
1432
-
1433
-
1434
-
1435
-
1436
-
1437
-
1438
-
1439
-
1440
-
1441
-
1442
-
1443
-
1444
-
1445
-
1446
-
1447
-
1448
-
1449
-
1450
-
1451
-
1452
-
1453
-
1454
-
1455
-
1456
-
1457
-
1458
-
1459
-
1460
-
1461
-
1462
-
1463
-
1464
-
1465
-
1466
-
1467
-
1468
-
1469
-
1470
-
1471
-
1472
-
1473
-
1474
-
1475
-
1476
-
1477
-
1478
-
1479
-
1480
-
1481
-
1482
-
1483
-
1484
-
1485
-
1486
-
1487
-
1488
-
1489
-
1490
-
1491
-
1492
-
1493
-
1494
-
1495
-
1496
-
1497
-
1498
-
1499
-
1500
-
1501
-
1502
-
1503
-
1504
-
1505
-
1506
-
1507
-
1508
-
1509
-
1510
-
1511
-
1512
-
1513
-
1514
-
1515
-
1516
-
1517
-
1518
-
1519
-
1520
-
1521
-
1522
-
1523
-
1524
-
1525
-
1526
-
1527
-
1528
-
1529
-
1530
-
1531
-
1532
-
1533
-
1534
-
1535
-
1536
-
1537
-
1538
-
1539
-
1540
-
1541
-
1542
-
1543
-
1544
-
1545
-
1546
-
1547
-
1548
-
1549
-
1550
-
1551
-
1552
-
1553
-
1554
-
1555
-
1556
-
1557
-
1558
-
1559
-
1560
-
1561
-
1562
-
1563
-
1564
-
1565
-
1566
-
1567
-
1568
-
1569
-
1570
-
1571
-
1572
-
1573
-
1574
-
1575
-
1576
-
1577
-
1578
-
1579
-
1580
-
1581
-
1582
-
1583
-
1584
-
1585
-
1586
-
1587
-
1588
-
1589
-
1590
-
1591
-
1592
-
1593
-
1594
-
1595
-
1596
-
1597
-
1598
-
1599
-
1600
-
1601
-
1602
-
1603
-
1604
-
1605
-
1606
-
1607
-
1608
-
1609
-
1610
-
1611
-
1612
-
1613
-
1614
-
1615
-
1616
-
1617
-
1618
-
1619
-
1620
-
1621
-
1622
-
1623
-
1624
-
1625
-
1626
-
1627
-
1628
-
1629
-
1630
-
1631
-
1632
-
1633
-
1634
-
1635
-
1636
-
1637
-
1638
-
1639
-
1640
-
1641
-
1642
-
1643
-
1644
-
1645
-
1646
-
1647
-
1648
-
1649
-
1650
-
1651
-
1652
-
1653
-
1654
-
1655
-
1656
-
1657
-
1658
-
1659
-
1660
-
1661
-
1662
-
1663
-
1664
-
1665
-
1666
-
1667
-
1668
// Copyright 2025 Shota FUJI
//
// Licensed under the Zero-Clause BSD License or the Apache License, Version 2.0, at your option.
// You may not use, copy, modify, or distribute this file except according to those terms. You can
// find a copy of the Zero-Clause BSD License at LICENSES/0BSD.txt, and a copy of the Apache License,
// Version 2.0 at LICENSES/Apache-2.0.txt. You may also obtain a copy of the Zero-Clause BSD License
// at <https://opensource.org/license/0bsd> and a copy of the Apache License, Version 2.0 at
// <https://www.apache.org/licenses/LICENSE-2.0>
//
// SPDX-License-Identifier: 0BSD OR Apache-2.0
//
// ===
//
// Zig API.
//! MOO message is a message format used for communicating with Roon Server.
//! Encodes to and decodes from newline-delimited UTF-8 encoded plain text, like HTTP.
//! Newline character is LF (0xa) without CR character.
//!
//! MOO message consists of metadata, header and body: header is a list of key-values
//! that both key and value contains UTF-8 string value, and body is single UTF-8 string.
//! Typical MOO message have "Content-Type" header that describes how the message's body
//! is encoded. (e.g. "application/json")
//! The first line of MOO message is metadata line, which is in "MOO/VERSION VERB SERVICE"
//! format. SERVICE is delimited by slash.
//!
//! ## Decoding
//!
//! Parse functions takes a whole buffer (`[]const u8`) and returns a result. To reduce
//! copy, returned structs' slice fields are pointer for a part of the input buffer.
//! **Accessing those field after freeing the input buffer is use-after-free**.
//! Even those structs that take `std.mem.Allocator` as a parameter, does not copy the
//! underlying buffer.
//!
//! Parse functions are named `parse()` but might be changed to `decode()` in a future.
//!
//! ## Encoding
//!
//! To build MOO message bytes from structs, pass a writer to `.encode()` methods.
//!
//! Each structs has `getEncodeSize(self: *const @This()) usize` function for buffer
//! allocation: allocate `[]u8` of the size of sum of `getEncodeSize` result, then
//! create `std.io.FixedBufferStream` from that.
//! Most of the time, this simple buffer creation would be enough.
// TODO: Move tests for public APIs out of this file. "lib_test.zig" or such.
const std = @import("std");
/// Context required for parsing headers section.
pub const HeaderParsingContext = struct {
start_position: usize,
};
/// Metadata contains a MOO message's version and semantics.
pub const Metadata = struct {
/// Message schema version described in metadata line.
version: u32 = 1,
/// Verb described in metadata line. Verb consists of uppercase alphabets.
/// @example: "REQUEST", "COMPLETE"
verb: []const u8,
/// Service name described in metadata line.
service: []const u8,
const signature = "MOO/";
pub const ParseError = error{
InvalidSignature,
InvalidVersionNumber,
InvalidVerb,
InvalidService,
NonUtf8ServiceName,
};
/// Tries to parse the `message` bytes as MOO message, returns metadata section and
/// parser context for header parsing.
/// **Slices in the returned struct are pointer for the input `message`**.
/// Freeing `message` then accessing slice fields is use-after-free.
///
/// This function returns a tuple of the parsed metadata and context for header parsing.
/// Pass the second one to headers struct's `parse` function.
///
/// ```zig
/// const metadata, const headers_ctx = try Metadata.parse(message);
///
/// _, _ = try WellKnownHeaders.parse(message, headers_ctx);
/// _, _ = try HashmapHeaders.parse(allocator, message, headers_ctx);
/// ```
pub fn parse(message: []const u8) ParseError!struct { @This(), HeaderParsingContext } {
var i: usize = 0;
if (!std.mem.startsWith(u8, message, signature)) {
return ParseError.InvalidSignature;
}
i += signature.len;
const version = if (std.mem.indexOfScalarPos(u8, message, i, ' ')) |space_position| blk: {
if (i == space_position) {
return ParseError.InvalidVersionNumber;
}
const parsed = std.fmt.parseInt(u32, message[i..space_position], 10) catch return ParseError.InvalidVersionNumber;
i = space_position + 1;
break :blk parsed;
} else {
return ParseError.InvalidVersionNumber;
};
const verb = if (std.mem.indexOfScalarPos(u8, message, i, ' ')) |space_position| blk: {
if (i == space_position) {
return ParseError.InvalidVerb;
}
const s = message[i..space_position];
for (s) |char| {
if (char < 'A' or char > 'Z') {
return ParseError.InvalidVerb;
}
}
i = space_position + 1;
break :blk s;
} else {
return ParseError.InvalidVerb;
};
const line_delimiter_position = std.mem.indexOfScalarPos(u8, message, i, '\n') orelse message.len;
const service = message[i..line_delimiter_position];
if (service.len == 0) {
return ParseError.InvalidService;
}
if (!std.unicode.utf8ValidateSlice(service)) {
return ParseError.NonUtf8ServiceName;
}
return .{
@This(){
.version = version,
.verb = verb,
.service = service,
},
HeaderParsingContext{
.start_position = line_delimiter_position + 1,
},
};
}
const fmt = signature ++ "{d} {s} {s}\n";
/// Returns how many bytes required for encoding.
///
/// Mainly used for allocating an output buffer.
///
/// ```zig
/// const metadata = Metadata{
/// .verb = "REQUEST",
/// .service = "com.example:1/hello",
/// };
///
/// const buf = try allocator.alloc(u8, metadata.getEncodeSize());
/// defer allocator.free(buf);
/// var fbs = std.io.fixedBufferStream(buf);
/// try meta.encode(fbs.writer());
/// ```
pub fn getEncodeSize(self: *const @This()) usize {
return std.fmt.count(fmt, .{ self.version, self.verb, self.service });
}
/// Encodes metadata to bytes and writes to `writer`.
///
/// `writer` must be `std.io.GenericWriter`.
/// Error set is inferred due to `std.fmt.format` not having explicit error set.
pub fn encode(self: *const @This(), writer: anytype) !void {
try std.fmt.format(writer, fmt, .{ self.version, self.verb, self.service });
}
};
test Metadata {
{
const metadata, _ = try Metadata.parse("MOO/1 REQUEST foo/bar\n");
try std.testing.expectEqual(1, metadata.version);
try std.testing.expectEqualStrings("REQUEST", metadata.verb);
try std.testing.expectEqualStrings("foo/bar", metadata.service);
}
{
const metadata, _ = try Metadata.parse("MOO/20 COMPLETE foo\n");
try std.testing.expectEqual(20, metadata.version);
try std.testing.expectEqualStrings("COMPLETE", metadata.verb);
try std.testing.expectEqualStrings("foo", metadata.service);
}
}
test "Metadata.parse() should reject invalid signature" {
{
const err = Metadata.parse("");
try std.testing.expectError(Metadata.ParseError.InvalidSignature, err);
}
{
const err = Metadata.parse("\n");
try std.testing.expectError(Metadata.ParseError.InvalidSignature, err);
}
{
const err = Metadata.parse("MOO1 REQUEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidSignature, err);
}
{
const err = Metadata.parse("MEOW/1 REQUEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidSignature, err);
}
}
test "Metadata.parse() should reject invalid version" {
{
const err = Metadata.parse("MOO/1.0 REQUEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVersionNumber, err);
}
{
const err = Metadata.parse("MOO/-1 REQUEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVersionNumber, err);
}
{
const err = Metadata.parse("MOO/ REQUEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVersionNumber, err);
}
{
const err = Metadata.parse("MOO/0x1 REQUEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVersionNumber, err);
}
{
const err = Metadata.parse("MOO/one REQUEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVersionNumber, err);
}
}
test "Metadata.parse() should reject invalid verb" {
{
const err = Metadata.parse("MOO/1 request foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVerb, err);
}
{
const err = Metadata.parse("MOO/1 RÉQUEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVerb, err);
}
{
const err = Metadata.parse("MOO/1 REQUEST1 foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVerb, err);
}
{
const err = Metadata.parse("MOO/1 RE❓️UEST foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVerb, err);
}
{
const err = Metadata.parse("MOO/1 \n");
try std.testing.expectError(Metadata.ParseError.InvalidVerb, err);
}
{
const err = Metadata.parse("MOO/1 foo/bar\n");
try std.testing.expectError(Metadata.ParseError.InvalidVerb, err);
}
}
test "Metadata.parse() should reject invalid service" {
{
const err = Metadata.parse("MOO/1 REQUEST \n");
try std.testing.expectError(Metadata.ParseError.InvalidService, err);
}
{
const err = Metadata.parse("MOO/1 REQUEST ");
try std.testing.expectError(Metadata.ParseError.InvalidService, err);
}
{
const err = Metadata.parse("MOO/1 REQUEST \xc3\x28\n");
try std.testing.expectError(Metadata.ParseError.NonUtf8ServiceName, err);
}
}
test "Metadata.encodeInto" {
{
const meta = Metadata{
.version = 8,
.verb = "EAT",
.service = "creature/dog",
};
const size = meta.getEncodeSize();
const buf: []u8 = try std.testing.allocator.alloc(u8, size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
try meta.encode(fbs.writer());
try std.testing.expectEqualStrings("MOO/8 EAT creature/dog\n", buf);
const parsed, _ = try Metadata.parse(buf);
try std.testing.expectEqual(meta.version, parsed.version);
try std.testing.expectEqualStrings(meta.verb, parsed.verb);
try std.testing.expectEqualStrings(meta.service, parsed.service);
}
}
const HeaderIterator = struct {
buffer: []const u8,
pub const IterateError = error{
NoHeaderDelimiterError,
EmptyHeaderKey,
NonUtf8HeaderKey,
NonUtf8HeaderValue,
};
/// Returns bytes read when a header is read, `key` and `value` is populated.
/// Returns `null` when the buffer is exhausted, `key` and `value` is untouched.
pub fn iterate(self: *HeaderIterator, key: *[]const u8, value: *[]const u8) IterateError!?usize {
if (self.buffer.len == 0) {
return null;
}
const line_end = std.mem.indexOfScalar(u8, self.buffer, '\n') orelse self.buffer.len;
const line = self.buffer[0..line_end];
if (line.len == 0) {
return null;
}
const delimiter = std.mem.indexOfScalar(u8, self.buffer, ':') orelse return IterateError.NoHeaderDelimiterError;
const key_slice = self.buffer[0..delimiter];
if (key_slice.len == 0) {
return IterateError.EmptyHeaderKey;
}
if (!std.unicode.utf8ValidateSlice(key_slice)) {
return IterateError.NonUtf8HeaderKey;
}
const value_slice = std.mem.trimLeft(u8, self.buffer[delimiter + 1 .. line_end], " ");
if (!std.unicode.utf8ValidateSlice(value_slice)) {
return IterateError.NonUtf8HeaderKey;
}
key.* = key_slice;
value.* = value_slice;
const read = @min(line_end + 1, self.buffer.len);
self.buffer = self.buffer[read..];
return read;
}
};
test "(HeaderIterator).iterate should parse a header line" {
var iter = HeaderIterator{ .buffer = "Foo: Bar\n" };
var foo: []const u8 = undefined;
var bar: []const u8 = undefined;
const read = try iter.iterate(&foo, &bar);
try std.testing.expectEqual(9, read);
try std.testing.expectEqualStrings("Foo", foo);
try std.testing.expectEqualStrings("Bar", bar);
var key: []const u8 = undefined;
var val: []const u8 = undefined;
const second_read = try iter.iterate(&key, &val);
try std.testing.expectEqual(null, second_read);
}
test "(HeaderIterator).iterate should parse header lines" {
var iter = HeaderIterator{ .buffer = "Foo: foo-value\nbar: bar-value\nbaZ: baz-value\n" };
var foo_key: []const u8 = undefined;
var foo_value: []const u8 = undefined;
const foo_read = try iter.iterate(&foo_key, &foo_value);
try std.testing.expectEqual(15, foo_read);
try std.testing.expectEqualStrings("Foo", foo_key);
try std.testing.expectEqualStrings("foo-value", foo_value);
var bar_key: []const u8 = undefined;
var bar_value: []const u8 = undefined;
const bar_read = try iter.iterate(&bar_key, &bar_value);
try std.testing.expectEqual(15, bar_read);
try std.testing.expectEqualStrings("bar", bar_key);
try std.testing.expectEqualStrings("bar-value", bar_value);
var baz_key: []const u8 = undefined;
var baz_value: []const u8 = undefined;
const baz_read = try iter.iterate(&baz_key, &baz_value);
try std.testing.expectEqual(15, baz_read);
try std.testing.expectEqualStrings("baZ", baz_key);
try std.testing.expectEqualStrings("baz-value", baz_value);
var key: []const u8 = undefined;
var val: []const u8 = undefined;
const final_read = try iter.iterate(&key, &val);
try std.testing.expectEqual(null, final_read);
}
test "(HeaderIterator).iterate should parse a header line terminated without newline" {
var iter = HeaderIterator{ .buffer = "Foo: Bar" };
var foo: []const u8 = undefined;
var bar: []const u8 = undefined;
const read = try iter.iterate(&foo, &bar);
try std.testing.expectEqual(8, read);
try std.testing.expectEqualStrings("Foo", foo);
try std.testing.expectEqualStrings("Bar", bar);
var key: []const u8 = undefined;
var val: []const u8 = undefined;
const second_read = try iter.iterate(&key, &val);
try std.testing.expectEqual(null, second_read);
}
test "(HeaderIterator).iterate should return false for blank inputs" {
{
var iter = HeaderIterator{ .buffer = "" };
var key: []const u8 = undefined;
var val: []const u8 = undefined;
const read = try iter.iterate(&key, &val);
try std.testing.expectEqual(null, read);
}
{
var iter = HeaderIterator{ .buffer = "\n" };
var key: []const u8 = undefined;
var val: []const u8 = undefined;
const read = try iter.iterate(&key, &val);
try std.testing.expectEqual(null, read);
}
{
var iter = HeaderIterator{ .buffer = "\n\n\n" };
var key: []const u8 = undefined;
var val: []const u8 = undefined;
const read = try iter.iterate(&key, &val);
try std.testing.expectEqual(null, read);
}
}
test "(HeaderIterator).iterate should return error for empty key" {
// Only zero-length slice: the official Node.js API parses space-only headers...
var iter = HeaderIterator{ .buffer = ": Value" };
var key: []const u8 = undefined;
var val: []const u8 = undefined;
try std.testing.expectError(
HeaderIterator.IterateError.EmptyHeaderKey,
iter.iterate(&key, &val),
);
}
test "(HeaderIterator).iterate should trim starting spaces" {
// Many spaces
{
var iter = HeaderIterator{ .buffer = "Foo: Bar" };
var foo: []const u8 = undefined;
var bar: []const u8 = undefined;
const read = try iter.iterate(&foo, &bar);
try std.testing.expectEqual(19, read);
try std.testing.expectEqualStrings("Foo", foo);
try std.testing.expectEqualStrings("Bar", bar);
}
// Zero space
{
var iter = HeaderIterator{ .buffer = "Foo:Bar" };
var foo: []const u8 = undefined;
var bar: []const u8 = undefined;
const read = try iter.iterate(&foo, &bar);
try std.testing.expectEqual(7, read);
try std.testing.expectEqualStrings("Foo", foo);
try std.testing.expectEqualStrings("Bar", bar);
}
// Tab is not a space
{
var iter = HeaderIterator{ .buffer = "Foo:\tBar" };
var foo: []const u8 = undefined;
var bar: []const u8 = undefined;
const read = try iter.iterate(&foo, &bar);
try std.testing.expectEqual(8, read);
try std.testing.expectEqualStrings("Foo", foo);
try std.testing.expectEqualStrings("\tBar", bar);
}
// Newline is not a space
{
var iter = HeaderIterator{ .buffer = "Foo:\nBar" };
var foo: []const u8 = undefined;
var bar: []const u8 = undefined;
const read = try iter.iterate(&foo, &bar);
try std.testing.expectEqual(5, read);
try std.testing.expectEqualStrings("Foo", foo);
try std.testing.expectEqualStrings("", bar);
}
// NULL character is not a space
{
var iter = HeaderIterator{ .buffer = "Foo:\x00Bar" };
var foo: []const u8 = undefined;
var bar: []const u8 = undefined;
const read = try iter.iterate(&foo, &bar);
try std.testing.expectEqual(8, read);
try std.testing.expectEqualStrings("Foo", foo);
try std.testing.expectEqualStrings("\x00Bar", bar);
}
}
/// Context required for body parsing and validation.
pub const BodyParsingContext = struct {
start_position: usize,
content_type: ?[]const u8,
content_length: ?usize,
};
/// WellKnownHeaders stores headers defined in the official node-roon api source code and
/// discards every other header fields.
pub const WellKnownHeaders = struct {
/// MIME type (`Content-Type` header).
content_type: []const u8,
/// Byte size of the body (`Content-Length` header).
content_length: usize,
/// An ID unique to a connection, to associate corresponding request and response.
/// (`Request-Id` header)
request_id: i64,
pub const ParseError = error{
EmptyContentType,
NonUintContentLength,
NonIntRequestID,
MissingContentType,
MissingContentLength,
MissingRequestID,
} || HeaderIterator.IterateError;
/// Tries to parse the `message` bytes as MOO message, returns headers section and
/// parser context for body parsing.
/// **Slices in the returned struct are pointer for the input `message`**.
/// Freeing `message` then accessing slice fields is use-after-free.
///
/// Headers defined as a field will be ignored.
/// If you want to read other headers, use `HashMapHeaders` instead.
///
/// This function returns a tuple of the parsed headers and context for body parsing.
/// Pass the second one to a body struct's `parse` function.
///
/// ```zig
/// const metadata, const headers_ctx = try Metadata.parse(message);
/// const headers, const body_ctx = try WellKnownHeaders.parse(message, headers_ctx);
///
/// const body = try RawBody.parse(message, body_ctx);
///
/// _ = metadata;
/// _ = headers;
/// _ = body;
/// ```
pub fn parse(message: []const u8, context: HeaderParsingContext) ParseError!struct { @This(), BodyParsingContext } {
var iter = HeaderIterator{ .buffer = message[context.start_position..] };
var content_type: ?[]const u8 = null;
var content_length: ?usize = null;
var request_id: ?i64 = null;
var i = context.start_position;
var key: []const u8 = undefined;
var val: []const u8 = undefined;
while (try iter.iterate(&key, &val)) |read| {
i += read;
// Unlike HTTP headers, MOO headers are case-sensitive.
if (std.mem.eql(u8, "Content-Type", key)) {
if (val.len == 0) {
return ParseError.EmptyContentType;
}
content_type = val;
continue;
}
if (std.mem.eql(u8, "Content-Length", key)) {
content_length = std.fmt.parseInt(usize, val, 10) catch return ParseError.NonUintContentLength;
continue;
}
if (std.mem.eql(u8, "Request-Id", key)) {
request_id = std.fmt.parseInt(i64, val, 10) catch return ParseError.NonIntRequestID;
continue;
}
}
return .{
WellKnownHeaders{
.content_type = content_type orelse return ParseError.MissingContentType,
.content_length = content_length orelse return ParseError.MissingContentLength,
.request_id = request_id orelse return ParseError.MissingRequestID,
},
BodyParsingContext{
// `i` does not include a final newline.
.start_position = i + 1,
.content_type = content_type.?,
.content_length = content_length.?,
},
};
}
const fmt =
\\Content-Type: {s}
\\Content-Length: {d}
\\Request-Id: {d}
\\
\\
;
/// Returns how many bytes required for encoding.
///
/// Mainly used for allocating an output buffer.
///
/// ```zig
/// const metadata = Metadata{
/// .verb = "REQUEST",
/// .service = "com.example:1/hello",
/// };
///
/// const headers = WellKnownHeaders{
/// .content_type = "application/json",
/// .content_length = 13,
/// .request_id = 1,
/// };
///
/// const buf = try allocator.alloc(
/// u8,
/// metadata.getEncodeSize() + headers.getEncodeSize(),
/// );
/// defer allocator.free(buf);
/// var fbs = std.io.fixedBufferStream(buf);
/// const writer = fbs.writer();
/// try metadata.encode(writer);
/// try headers.encode(writer);
/// ```
pub fn getEncodeSize(self: *const WellKnownHeaders) usize {
return std.fmt.count(fmt, .{
self.content_type,
self.content_length,
self.request_id,
});
}
/// Encodes headers to bytes and writes to `writer`.
///
/// `writer` must be `std.io.GenericWriter`.
/// Error set is inferred due to `std.fmt.format` not having explicit error set.
pub fn encode(self: *const WellKnownHeaders, writer: anytype) !void {
try std.fmt.format(writer, fmt, .{
self.content_type,
self.content_length,
self.request_id,
});
}
};
test "WellKnownHeaders.parse should parse well-known headers" {
const message = "MOO/1 REQUEST foo\nContent-Type: application/json; charset=utf-8\nContent-Length: 876\nRequest-Id: 1\n\n";
_, const meta_ctx = try Metadata.parse(message);
const header, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
try std.testing.expectEqualStrings("application/json; charset=utf-8", header.content_type);
try std.testing.expectEqual(876, header.content_length);
try std.testing.expectEqual(1, header.request_id);
try std.testing.expectEqual(message.len, header_ctx.start_position);
}
test "WellKnownHeaders.parse should return error when required header is missing" {
{
const message = "MOO/1 REQUEST foo\nContent-Length: 876\nRequest-Id: 1\n";
_, const meta_ctx = try Metadata.parse(message);
try std.testing.expectError(
WellKnownHeaders.ParseError.MissingContentType,
WellKnownHeaders.parse(message, meta_ctx),
);
}
{
const message = "MOO/1 REQUEST foo\nContent-Type: application/json; charset=utf-8\nRequest-Id: 1\n";
_, const meta_ctx = try Metadata.parse(message);
try std.testing.expectError(
WellKnownHeaders.ParseError.MissingContentLength,
WellKnownHeaders.parse(message, meta_ctx),
);
}
{
const message = "MOO/1 REQUEST foo\nContent-Type: application/json; charset=utf-8\nContent-Length: 876\n";
_, const meta_ctx = try Metadata.parse(message);
try std.testing.expectError(
WellKnownHeaders.ParseError.MissingRequestID,
WellKnownHeaders.parse(message, meta_ctx),
);
}
}
test "WellKnownHeaders.parse should return error on an unexpected format" {
{
const message = "MOO/1 REQUEST foo\nContent-Type:\nContent-Length: 1\nRequest-Id: 1\n";
_, const meta_ctx = try Metadata.parse(message);
try std.testing.expectError(
WellKnownHeaders.ParseError.EmptyContentType,
WellKnownHeaders.parse(message, meta_ctx),
);
}
{
const message = "MOO/1 REQUEST foo\nContent-Type: text/plain\nContent-Length: 0x87\nRequest-Id: 1\n";
_, const meta_ctx = try Metadata.parse(message);
try std.testing.expectError(
WellKnownHeaders.ParseError.NonUintContentLength,
WellKnownHeaders.parse(message, meta_ctx),
);
}
{
const message = "MOO/1 REQUEST foo\nContent-Type: text/plain\nContent-Length: one\nRequest-Id: 1\n";
_, const meta_ctx = try Metadata.parse(message);
try std.testing.expectError(
WellKnownHeaders.ParseError.NonUintContentLength,
WellKnownHeaders.parse(message, meta_ctx),
);
}
{
const message = "MOO/1 REQUEST foo\nContent-Type: text/plain\nContent-Length: 1\nRequest-Id: 0D8C-F91C-22BB\n";
_, const meta_ctx = try Metadata.parse(message);
try std.testing.expectError(
WellKnownHeaders.ParseError.NonIntRequestID,
WellKnownHeaders.parse(message, meta_ctx),
);
}
}
test "WellknownHeaders.encodeInto" {
const header = WellKnownHeaders{
.content_type = "text/plain; charset=utf-8",
.content_length = 2551,
.request_id = 99,
};
const size = header.getEncodeSize();
const buf: []u8 = try std.testing.allocator.alloc(u8, size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
try header.encode(fbs.writer());
try std.testing.expectEqualStrings(
\\Content-Type: text/plain; charset=utf-8
\\Content-Length: 2551
\\Request-Id: 99
\\
\\
, buf);
}
pub const NoBodyHeaders = struct {
/// An ID unique to a connection, to associate corresponding request and response.
/// (`Request-Id` header)
request_id: i64,
pub const ParseError = error{
NonIntRequestID,
MissingRequestID,
} || HeaderIterator.IterateError;
/// Tries to parse the `message` bytes as MOO message, returns headers section and
/// parser context for body parsing.
/// **Slices in the returned struct are pointer for the input `message`**.
/// Freeing `message` then accessing slice fields is use-after-free.
///
/// This function returns a tuple of the parsed headers and context for body parsing.
/// Pass the second one to a body struct's `parse` function.
///
/// ```zig
/// const metadata, const headers_ctx = try Metadata.parse(message);
/// const headers, const body_ctx = try NoBodyHeaders.parse(message, headers_ctx);
///
/// const body = try RawBody.parse(message, body_ctx);
///
/// _ = metadata;
/// _ = headers;
/// _ = body;
/// ```
pub fn parse(message: []const u8, context: HeaderParsingContext) ParseError!struct { @This(), BodyParsingContext } {
var iter = HeaderIterator{ .buffer = message[context.start_position..] };
var i = context.start_position;
var key: []const u8 = undefined;
var val: []const u8 = undefined;
while (try iter.iterate(&key, &val)) |read| {
i += read;
if (std.mem.eql(u8, "Request-Id", key)) {
const request_id = std.fmt.parseInt(i64, val, 10) catch return ParseError.NonIntRequestID;
return .{
NoBodyHeaders{
.request_id = request_id,
},
BodyParsingContext{
// `i` does not include a final newline.
.start_position = i + 1,
.content_length = null,
.content_type = null,
},
};
}
}
return ParseError.MissingRequestID;
}
const fmt =
\\Request-Id: {d}
\\
\\
;
/// Returns how many bytes required for encoding.
///
/// Mainly used for allocating an output buffer.
///
/// ```zig
/// const metadata = Metadata{
/// .verb = "REQUEST",
/// .service = "com.example:1/hello",
/// };
///
/// const headers = NoBodyHeaders{
/// .request_id = 1,
/// };
///
/// const buf = try allocator.alloc(
/// u8,
/// metadata.getEncodeSize() + headers.getEncodeSize(),
/// );
/// defer allocator.free(buf);
/// var fbs = std.io.fixedBufferStream(buf);
/// const writer = fbs.writer();
/// try metadata.encode(writer);
/// try headers.encode(writer);
/// ```
pub fn getEncodeSize(self: *const @This()) usize {
return std.fmt.count(fmt, .{self.request_id});
}
/// Encodes headers to bytes and writes to `writer`.
///
/// `writer` must be `std.io.GenericWriter`.
/// Error set is inferred due to `std.fmt.format` not having explicit error set.
pub fn encode(self: *const @This(), writer: anytype) !void {
try std.fmt.format(writer, fmt, .{self.request_id});
}
};
test "NoBodyHeaders.parse should parse well-known headers" {
const message = "MOO/1 REQUEST foo\nRequest-Id: 1\n\n";
_, const meta_ctx = try Metadata.parse(message);
const header, const header_ctx = try NoBodyHeaders.parse(message, meta_ctx);
try std.testing.expectEqual(1, header.request_id);
try std.testing.expectEqual(message.len, header_ctx.start_position);
}
test "NoBodyHeaders.parse should return error when required header is missing" {
const message = "MOO/1 REQUEST foo\n\n";
_, const meta_ctx = try Metadata.parse(message);
try std.testing.expectError(
NoBodyHeaders.ParseError.MissingRequestID,
NoBodyHeaders.parse(message, meta_ctx),
);
}
test "NoBodyHeaders.encodeInto" {
const header = NoBodyHeaders{
.request_id = 99,
};
const size = header.getEncodeSize();
const buf: []u8 = try std.testing.allocator.alloc(u8, size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
try header.encode(fbs.writer());
try std.testing.expectEqualStrings(
\\Request-Id: 99
\\
\\
, buf);
}
/// HashMapHeaders stores headers in a string-key-string-value hash map.
pub const HashMapHeaders = struct {
/// Hash map containing the headers.
map: std.hash_map.StringHashMap([]const u8),
pub const ParseError = error{
MissingContentType,
MissingContentLength,
EmptyContentType,
NonUintContentLength,
} || HeaderIterator.IterateError || std.mem.Allocator.Error;
/// Tries to parse the `message` bytes as MOO message, returns headers section and
/// parser context for body parsing.
/// **Slices in the returned hash map are pointer for the input `message`**.
/// Freeing `message` then accessing key or value is use-after-free.
/// The `allocator` is used for managing hash map entries, not copying bytes.
///
/// This function returns a tuple of the parsed headers and context for body parsing.
/// Pass the second one to a body struct's `parse` function.
///
/// ```zig
/// const metadata, const headers_ctx = try Metadata.parse(message);
/// const headers, const body_ctx = try HashMapHeaders.parse(allocator, message, headers_ctx);
///
/// const body = try RawBody.parse(message, body_ctx);
///
/// _ = metadata;
/// _ = headers;
/// _ = body;
/// ```
///
/// Call `deinit()` once you no longer use the returned struct.
pub fn parse(allocator: std.mem.Allocator, message: []const u8, context: HeaderParsingContext) ParseError!struct { @This(), BodyParsingContext } {
var map = std.hash_map.StringHashMap([]const u8).init(allocator);
var iter = HeaderIterator{ .buffer = message[context.start_position..] };
var i = context.start_position;
var content_type: ?[]const u8 = null;
var content_length: ?usize = null;
var key: []const u8 = undefined;
var val: []const u8 = undefined;
while (try iter.iterate(&key, &val)) |read| {
i += read;
if (std.mem.eql(u8, "Content-Type", key)) {
if (val.len == 0) {
return ParseError.EmptyContentType;
}
content_type = val;
} else if (std.mem.eql(u8, "Content-Length", key)) {
content_length = std.fmt.parseInt(usize, val, 10) catch return ParseError.NonUintContentLength;
}
try map.put(key, val);
}
return .{
HashMapHeaders{
.map = map,
},
BodyParsingContext{
.content_type = content_type orelse return ParseError.MissingContentType,
.content_length = content_length orelse return ParseError.MissingContentLength,
// `i` does not include a final newline.
.start_position = i + 1,
},
};
}
/// Release the hash map.
/// This does not invalidates keys and values.
pub fn deinit(self: *@This()) void {
self.map.deinit();
}
/// Returns a newly created `HashMapHeaders`, for convenience.
///
/// Call `deinit()` once you no longer use the returned struct.
pub fn init(allocator: std.mem.Allocator) HashMapHeaders {
const map = std.hash_map.StringHashMap([]const u8).init(allocator);
return HashMapHeaders{ .map = map };
}
const line_fmt = "{s}: {s}\n";
/// Returns how many bytes required for encoding.
///
/// Mainly used for allocating an output buffer.
///
/// ```zig
/// const metadata = Metadata{
/// .verb = "REQUEST",
/// .service = "com.example:1/hello",
/// };
///
/// var headers = HashMapHeaders.init(allocator);
/// defer headers.deinit();
/// try headers.map.put("Request-Id", "1");
///
/// const buf = try allocator.alloc(
/// u8,
/// metadata.getEncodeSize() + headers.getEncodeSize(),
/// );
/// defer allocator.free(buf);
/// var fbs = std.io.fixedBufferStream(buf);
/// const writer = fbs.writer();
/// try metadata.encode(writer);
/// try headers.encode(writer);
/// ```
pub fn getEncodeSize(self: *const HashMapHeaders) usize {
var size: usize = 0;
var iter = self.map.iterator();
while (iter.next()) |entry| {
size += std.fmt.count(line_fmt, .{ entry.key_ptr.*, entry.value_ptr.* });
}
return size + 1;
}
/// Encodes headers to bytes and writes to `writer`.
///
/// The order of header lines are not guaranteed.
/// You should not rely on the order.
///
/// `writer` must be `std.io.GenericWriter`.
/// Error set is inferred due to `std.fmt.format` not having explicit error set.
pub fn encode(self: *const HashMapHeaders, writer: anytype) !void {
var iter = self.map.iterator();
while (iter.next()) |entry| {
try std.fmt.format(writer, line_fmt, .{
entry.key_ptr.*,
entry.value_ptr.*,
});
}
_ = try writer.write("\n");
}
};
test "HashMapHeaders.parse should save every headers" {
const message = "MOO/1 REQUEST foo\nContent-Type: application/json; charset=utf-8\nContent-Length: 876\nRequest-Id: 1\nFoo: Bar\n\n";
_, const meta_ctx = try Metadata.parse(message);
var header, const header_ctx = try HashMapHeaders.parse(std.testing.allocator, message, meta_ctx);
defer header.deinit();
try std.testing.expectEqualStrings(header.map.get("Content-Type").?, "application/json; charset=utf-8");
try std.testing.expectEqualStrings(header.map.get("Content-Length").?, "876");
try std.testing.expectEqualStrings(header.map.get("Request-Id").?, "1");
try std.testing.expectEqualStrings(header.map.get("Foo").?, "Bar");
try std.testing.expectEqual(message.len, header_ctx.start_position);
}
test "HashMapHeaders.encodeInto" {
var header = HashMapHeaders.init(std.testing.allocator);
defer header.deinit();
try header.map.put("Content-Type", "text/plain; charset=utf-8");
try header.map.put("Content-Length", "2551");
try header.map.put("Request-Id", "99");
try header.map.put("X-Foo", "Bar");
const size = header.getEncodeSize();
const buf: []u8 = try std.testing.allocator.alloc(u8, size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
try header.encode(fbs.writer());
try std.testing.expect(
std.mem.indexOf(u8, buf, "Content-Type: text/plain; charset=utf-8\n").? >= 0,
);
try std.testing.expect(
std.mem.indexOf(u8, buf, "Content-Length: 2551\n").? >= 0,
);
try std.testing.expect(
std.mem.indexOf(u8, buf, "Request-Id: 99\n").? >= 0,
);
try std.testing.expect(
std.mem.indexOf(u8, buf, "X-Foo: Bar\n").? >= 0,
);
try std.testing.expectStringEndsWith(buf, "\n\n");
}
/// NoBody indicates a message has no body.
///
/// While you can use empty `RawBody` to achieve the same goal, this has benefits over `RawBody`:
/// * At parse time, this struct checks there is no body.
/// * Does not emit `content-type` and `content-length` headers.
/// * More space efficient (1 byte less).
pub const NoBody = struct {
pub const ParseError = error{
UnexpectedBodyPart,
};
/// Validates if body is empty and returns `NoBody`.
pub fn parse(message: []const u8, context: BodyParsingContext) ParseError!@This() {
const start = @min(context.start_position, message.len);
if (start != message.len - 1) {
return ParseError.UnexpectedBodyPart;
}
return .{};
}
/// Returns 0.
/// Being here for consistency to other body structs.
pub fn getEncodeSize(_: *const @This()) usize {
return 0;
}
/// Does nothing.
/// Being here for consistency to other body structs.
pub fn encode(_: *const @This(), writer: anytype) @TypeOf(writer).Error!void {
return;
}
/// Get minimal header for the message.
/// Handy for constructing MOO message.
pub fn getHeader(_: *const @This(), request_id: i64) NoBodyHeaders {
return NoBodyHeaders{
.request_id = request_id,
};
}
};
/// RawBody simply is bytes for body section in a MOO message.
pub const RawBody = struct {
/// Bytes for body secion in a MOO message.
bytes: []const u8,
pub const ParseError = error{
MissingContentLength,
ContentLengthMismatch,
};
/// Validates bytes length and returns fulfilled `RawBody` if the size matches.
/// **Slices in the returned struct are pointer for the input `message`**.
/// Freeing `message` then accessing slice fields is use-after-free.
pub fn parse(message: []const u8, context: BodyParsingContext) ParseError!@This() {
const content_length = context.content_length orelse return ParseError.MissingContentLength;
const start = @min(context.start_position, message.len);
const bytes = message[start..];
if (bytes.len != content_length) {
return ParseError.ContentLengthMismatch;
}
return .{ .bytes = bytes };
}
/// Returns how many bytes required for encoding.
pub fn getEncodeSize(self: *const @This()) usize {
return self.bytes.len;
}
/// Write bytes to `writer`.
///
/// `writer` must be `std.io.GenericWriter`.
pub fn encode(self: *const @This(), writer: anytype) @TypeOf(writer).Error!void {
try writer.writeAll(self.bytes);
}
/// Get minimal header for the message.
/// Handy for constructing MOO message.
pub fn getHeader(self: *const @This(), request_id: i64) WellKnownHeaders {
return WellKnownHeaders{
.content_type = "text/plain",
.content_length = self.getEncodeSize(),
.request_id = request_id,
};
}
};
test "RawBody.parse should save rest of the bytes" {
const message = "MOO/1 REQUEST foo\nContent-Type: text/plain\nContent-Length: 13\nRequest-Id: 1\n\nHello, World!";
_, const meta_ctx = try Metadata.parse(message);
_, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
const body = try RawBody.parse(message, header_ctx);
try std.testing.expectEqualStrings("Hello, World!", body.bytes);
}
test "RawBody.parse should reject mismatching Content-Length" {
{
const message = "MOO/1 REQUEST foo\nContent-Type: text/plain\nContent-Length: 12\nRequest-Id: 1\n\nHello, World!";
_, const meta_ctx = try Metadata.parse(message);
_, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
const err = RawBody.parse(message, header_ctx);
try std.testing.expectError(RawBody.ParseError.ContentLengthMismatch, err);
}
{
const message = "MOO/1 REQUEST foo\nContent-Type: text/plain\nContent-Length: 14\nRequest-Id: 1\n\nHello, World!";
_, const meta_ctx = try Metadata.parse(message);
_, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
const err = RawBody.parse(message, header_ctx);
try std.testing.expectError(RawBody.ParseError.ContentLengthMismatch, err);
}
}
test "RawBody.encodeInto" {
const body = RawBody{ .bytes = "Foo Bar" };
const size = body.getEncodeSize();
const buf: []u8 = try std.testing.allocator.alloc(u8, size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
try body.encode(fbs.writer());
try std.testing.expectEqualStrings("Foo Bar", buf);
}
/// JsonBody is a typed and structured body encoded to/decoded from JSON text.
///
/// You have to pass JSON-de/serializable type to `T`.
pub fn JsonBody(comptime T: type) type {
return struct {
/// Allocator manages `value`.
arena: ?*std.heap.ArenaAllocator = null,
/// Body data. Do not access after `deinit()`.
value: *const T,
/// Used for encoding.
stringifyOpts: std.json.StringifyOptions = .{},
pub const ParseError = error{
MissingContentType,
MissingContentLength,
ContentLengthMismatch,
ContentTypeIsNotApplicationJson,
} || std.mem.Allocator.Error || std.json.ParseError(std.json.Scanner);
/// Tries to parse the `message` bytes as MOO message, parses body section as
/// JSON using `T` as a schema, then returns the parsed data.
/// Slices (strings) inside the retured data *might* be a pointer for the
/// input message bytes. This depends on how `std.json.parseFromSliceLeaky`.
///
/// Caller owns the returned struct. Call `deinit()` once it's no longer in use.
pub fn parse(allocator: std.mem.Allocator, message: []const u8, context: BodyParsingContext, parse_options: std.json.ParseOptions) ParseError!@This() {
const content_type = context.content_type orelse return ParseError.MissingContentType;
const content_length = context.content_length orelse return ParseError.MissingContentLength;
// Same MIME checking as one in the official Node.js API.
// This does not match to "application/json; charset=utf-8" or such.
// (not doing the strict MIME check because parsing MIME is complex task)
if (!std.mem.eql(u8, "application/json", content_type)) {
return ParseError.ContentTypeIsNotApplicationJson;
}
const start = @min(context.start_position, message.len);
const bytes = message[start..];
if (bytes.len != content_length) {
return ParseError.ContentLengthMismatch;
}
var arena = try allocator.create(std.heap.ArenaAllocator);
errdefer allocator.destroy(arena);
arena.* = std.heap.ArenaAllocator.init(allocator);
errdefer arena.deinit();
const arena_allocator = arena.allocator();
const value = try arena_allocator.create(T);
errdefer arena_allocator.destroy(value);
value.* = try std.json.parseFromSliceLeaky(T, arena_allocator, bytes, parse_options);
return .{
.arena = arena,
.value = value,
};
}
/// Release `value` and temporary data made during JSON parsing.
/// If this struct is initialized using `init()`, this function is
/// no-op.
pub fn deinit(self: *const @This()) void {
if (self.arena) |arena| {
const allocator = arena.child_allocator;
arena.deinit();
allocator.destroy(arena);
}
}
/// Creates and returns JSON encodable body.
pub fn init(value: *const T, stringifyOpts: std.json.StringifyOptions) @This() {
return .{ .value = value, .stringifyOpts = stringifyOpts };
}
/// Returns how many bytes required for encoding.
///
/// Mainly used for allocating an output buffer.
///
/// ```zig
/// const metadata = Metadata{
/// .verb = "REQUEST",
/// .service = "com.example:1/hello",
/// };
///
/// const headers = WellKnownHeaders{
/// .content_type = "application/json",
/// .content_length = 13,
/// .request_id = 1,
/// };
///
/// const MyData = struct { foo: i32 };
///
/// const body = JsonBody(MyData).init(&MyData{ .foo = 3 });
///
/// const buf = try allocator.alloc(
/// u8,
/// metadata.getEncodeSize() + headers.getEncodeSize() + body.getEncodeSize(),
/// );
/// defer allocator.free(buf);
/// var fbs = std.io.fixedBufferStream(buf);
/// const writer = fbs.writer();
/// try metadata.encode(writer);
/// try headers.encode(writer);
/// try body.encode(writer);
/// ```
///
/// This function serializes `value` to JSON text to compute required byte size.
/// Use dynamic buffer (e.g. `std.ArrayList(u8)`) if the serialization cost
/// matters.
pub fn getEncodeSize(self: *const @This()) usize {
var cw = std.io.countingWriter(std.io.null_writer);
std.json.stringify(self.value, self.stringifyOpts, cw.writer()) catch return 0;
return cw.bytes_written;
}
/// Serializes `value` to JSON text and writes it to `writer`.
///
/// `writer` must be `std.io.GenericWriter`.
pub fn encode(self: *const @This(), writer: anytype) @TypeOf(writer).Error!void {
try std.json.stringify(self.value, self.stringifyOpts, writer);
}
/// Get minimal header for the message.
/// Handy for constructing MOO message.
pub fn getHeader(self: *const @This(), request_id: i64) WellKnownHeaders {
return WellKnownHeaders{
.content_length = self.getEncodeSize(),
.content_type = "application/json",
.request_id = request_id,
};
}
};
}
test "JsonBody.parse should deserialize body as JSON" {
const payload = "{\"foo\": 8}";
var message_buffer = std.ArrayList(u8).init(std.testing.allocator);
defer message_buffer.deinit();
try std.fmt.format(
message_buffer.writer(),
"MOO/1 REQUEST foo\nContent-Type: application/json\nContent-Length: {d}\nRequest-Id: 1\n\n{s}",
.{ payload.len, payload },
);
const message = try message_buffer.toOwnedSlice();
defer std.testing.allocator.free(message);
const TestData = struct {
foo: i32,
};
_, const meta_ctx = try Metadata.parse(message);
_, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
const body = try JsonBody(TestData).parse(std.testing.allocator, message, header_ctx, .{});
defer body.deinit();
try std.testing.expectEqual(body.value.foo, 8);
}
test "JsonBody.parse should respect JSON parsing options" {
const payload = "{\"foo\": 8, \"bar\": true}";
var message_buffer = std.ArrayList(u8).init(std.testing.allocator);
defer message_buffer.deinit();
try std.fmt.format(
message_buffer.writer(),
"MOO/1 REQUEST foo\nContent-Type: application/json\nContent-Length: {d}\nRequest-Id: 1\n\n{s}",
.{ payload.len, payload },
);
const message = try message_buffer.toOwnedSlice();
defer std.testing.allocator.free(message);
const TestData = struct {
foo: i32,
};
_, const meta_ctx = try Metadata.parse(message);
_, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
const body = try JsonBody(TestData).parse(std.testing.allocator, message, header_ctx, .{ .ignore_unknown_fields = true });
defer body.deinit();
try std.testing.expectEqual(body.value.foo, 8);
}
test "JsonBody.parse should reject invalid JSON text" {
const payload = "{\"foo\": 0x8}";
var message_buffer = std.ArrayList(u8).init(std.testing.allocator);
defer message_buffer.deinit();
try std.fmt.format(
message_buffer.writer(),
"MOO/1 REQUEST foo\nContent-Type: application/json\nContent-Length: {d}\nRequest-Id: 1\n\n{s}",
.{ payload.len, payload },
);
const message = try message_buffer.toOwnedSlice();
defer std.testing.allocator.free(message);
const TestData = struct {
foo: i32,
};
_, const meta_ctx = try Metadata.parse(message);
_, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
const err = JsonBody(TestData).parse(std.testing.allocator, message, header_ctx, .{});
try std.testing.expectError(JsonBody(TestData).ParseError.SyntaxError, err);
}
test "JsonBody.parse should reject mismatching Content-Length" {
const payload = "{\"foo\": 8}";
var message_buffer = std.ArrayList(u8).init(std.testing.allocator);
defer message_buffer.deinit();
try std.fmt.format(
message_buffer.writer(),
"MOO/1 REQUEST foo\nContent-Type: application/json\nContent-Length: {d}\nRequest-Id: 1\n\n{s}",
.{ payload.len + 1, payload },
);
const message = try message_buffer.toOwnedSlice();
defer std.testing.allocator.free(message);
const TestData = struct {
foo: i32,
};
_, const meta_ctx = try Metadata.parse(message);
_, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
const err = JsonBody(TestData).parse(std.testing.allocator, message, header_ctx, .{});
try std.testing.expectError(JsonBody(TestData).ParseError.ContentLengthMismatch, err);
}
test "JsonBody.parse should reject Content-Type other than application/json" {
const payload = "{\"foo\": 8}";
var message_buffer = std.ArrayList(u8).init(std.testing.allocator);
defer message_buffer.deinit();
try std.fmt.format(
message_buffer.writer(),
"MOO/1 REQUEST foo\nContent-Type: text/json\nContent-Length: {d}\nRequest-Id: 1\n\n{s}",
.{ payload.len, payload },
);
const message = try message_buffer.toOwnedSlice();
defer std.testing.allocator.free(message);
const TestData = struct {
foo: i32,
};
_, const meta_ctx = try Metadata.parse(message);
_, const header_ctx = try WellKnownHeaders.parse(message, meta_ctx);
const err = JsonBody(TestData).parse(std.testing.allocator, message, header_ctx, .{});
try std.testing.expectError(JsonBody(TestData).ParseError.ContentTypeIsNotApplicationJson, err);
}
test "JsonBody.encodeInto" {
const TestData = struct {
foo: i32,
};
const body = JsonBody(TestData){
.value = &TestData{ .foo = 29 },
};
const size = body.getEncodeSize();
const buf: []u8 = try std.testing.allocator.alloc(u8, size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
try body.encode(fbs.writer());
try std.testing.expectEqualStrings("{\"foo\":29}", buf);
}
/// Writes encoded MOO message.
///
/// `writer` must be `std.io.GenericWriter`.
/// `header` must have `.encode(writer: anytype) !void`.
/// `body` must have `.encode(writer: anytype) !void`.
pub fn encode(writer: anytype, meta: Metadata, header: anytype, body: anytype) !void {
try meta.encode(writer);
try header.encode(writer);
try body.encode(writer);
}
test encode {
const UserInfo = struct {
id: []const u8,
};
const meta = Metadata{
.version = 1,
.verb = "GET",
.service = "user/account",
};
const body = JsonBody(UserInfo).init(&UserInfo{ .id = "alice" }, .{});
const header = body.getHeader(1);
const message_size = meta.getEncodeSize() + header.getEncodeSize() + body.getEncodeSize();
const buf = try std.testing.allocator.alloc(u8, message_size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
const writer = fbs.writer();
try encode(writer, meta, header, body);
try std.testing.expectEqualStrings(
\\MOO/1 GET user/account
\\Content-Type: application/json
\\Content-Length: 14
\\Request-Id: 1
\\
\\{"id":"alice"}
, buf);
}
test "JSON stringify options" {
const UserInfo = struct {
id: []const u8,
email: ?[]const u8 = null,
};
const meta = Metadata{
.version = 1,
.verb = "GET",
.service = "user/account",
};
const body = JsonBody(UserInfo).init(&UserInfo{ .id = "alice" }, .{
.emit_null_optional_fields = false,
});
const header = body.getHeader(1);
const message_size = meta.getEncodeSize() + header.getEncodeSize() + body.getEncodeSize();
const buf = try std.testing.allocator.alloc(u8, message_size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
const writer = fbs.writer();
try encode(writer, meta, header, body);
try std.testing.expectEqualStrings(
\\MOO/1 GET user/account
\\Content-Type: application/json
\\Content-Length: 14
\\Request-Id: 1
\\
\\{"id":"alice"}
, buf);
}
test "No body encode" {
const meta = Metadata{
.version = 1,
.verb = "GET",
.service = "user/account",
};
const body = NoBody{};
const header = body.getHeader(1);
const message_size = meta.getEncodeSize() + header.getEncodeSize() + body.getEncodeSize();
const buf = try std.testing.allocator.alloc(u8, message_size);
defer std.testing.allocator.free(buf);
var fbs = std.io.fixedBufferStream(buf);
const writer = fbs.writer();
try encode(writer, meta, header, body);
try std.testing.expectEqualStrings(
\\MOO/1 GET user/account
\\Request-Id: 1
\\
\\
, buf);
}