-
Notifications
You must be signed in to change notification settings - Fork 1
/
tsconfig-lua.en.html
661 lines (628 loc) · 64.4 KB
/
tsconfig-lua.en.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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>TSConfig / Lua — AMC Traffic Server Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/sphinxdoc.css" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Apache Traffic Control" href="atc/atc-index.html" />
<link rel="prev" title="Delain" href="delain.en.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="atc/atc-index.html" title="Apache Traffic Control"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="delain.en.html" title="Delain"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">SWOC Docs</a> »</li>
<li class="nav-item nav-item-1"><a href="ats-projects.en.html" accesskey="U">Traffic Server Projects</a> »</li>
<li class="nav-item nav-item-this"><a href="">TSConfig / Lua</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="tsconfig-lua">
<span id="id1"></span><h1>TSConfig / Lua<a class="headerlink" href="#tsconfig-lua" title="Permalink to this headline">¶</a></h1>
<p>Traffic Server has committed to moving configuration files to be Lua based. While conversion of existing files
to Lua isn’t required, the current view based on mailing list discussions is that new configuration
files are required to be in Lua. In the long run it is expected all configuration files will be
converted use Lua. This project is about providing that technology in a generic way to make it
easier to add configuration for new features.</p>
<section id="current-practice">
<h2>Current Practice<a class="headerlink" href="#current-practice" title="Permalink to this headline">¶</a></h2>
<p>The primary example current is the custom logging configuration file <code class="file docutils literal notranslate"><span class="pre">logging.config</span></code> which is
processed as a Lua file. The interface to the Traffic Server core is done by creating Lua types in the core
and exposing them to the Lua interpretor (see <a class="reference external" href="https://github.com/apache/trafficserver/blob/master/proxy/logging/LogBindings.cc">LogBindings.cc</a>). Data is
transfered by the Lua interpretor executing calls to the extended Lua types and then invoking the
Traffic Server core. The provided instances from the core are invoked with arguments passed by the
interpretor, which are then stored in logging configuration data structures. This works but the
downside that every subsystem that needs a configuration file will need to write specialized Lua
types to get its data.</p>
</section>
<section id="design">
<h2>Design<a class="headerlink" href="#design" title="Permalink to this headline">¶</a></h2>
<p>An alternative is to provide a more generic facility that has the Lua file construct a forest of
data and then copy that forest over to a C++ container. In order to provide appropriate feedback for
configurations a description of expected values is needed, in the flavor of the current
<code class="docutils literal notranslate"><span class="pre">RecordsConfig.cc</span></code>. Because the data is more complex this takes the form of a schema to describe
the data. The schema is a data object written in Lua, modeled on the standard <cite>JSON schema
<http://json-schema.org></cite>. <a class="footnote-reference brackets" href="#fn-schema" id="id2">1</a></p>
<p>The schema drives the rest of the implementation. A C++ structure to hold the configuration values
is generated which contains both the configuration and schema based metadata. This makes schema
information available for validation and error reporting.</p>
<p>To use this configuration a schema is written to describe the expected configuration data. During
build time a C++ container, a “configuration class”, is generated from the schema. At run time an
instance of the configuation class is created and the passed the path to the Lua configuration file.
The file is read and the data loaded into the configuration class instance. Any errors of the
configuration data is returned for logging. The calling code needs to do very little validation
because most or all of that is done by the configuration loading, based on the schema.</p>
</section>
<section id="implementation">
<h2>Implementation<a class="headerlink" href="#implementation" title="Permalink to this headline">¶</a></h2>
<p>The schema is processed to generate the configuration class. Its structure parallels that of the
configuration data, as descibed by the schema. <a class="reference internal" href="#_CPPv412TsConfigBase" title="TsConfigBase"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">TsConfigBase</span></code></a> is the abstract base class for
the configuration class. it provides a base uniform interface for operating on elements of the
configuration class. Each configuration data element in the base configuration class it also a
subclass of <a class="reference internal" href="#_CPPv412TsConfigBase" title="TsConfigBase"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">TsConfigBase</span></code></a> and as the client calls the <a class="reference internal" href="#_CPPv4N12TsConfigBase6loaderERKNSt6stringE" title="TsConfigBase::loader"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">TsConfigBase::loader()</span></code></a> method
to load the overall configuration, that class calls the same method on each of its elements, and so
recursively on down until primitives are reached which load themselves.</p>
<p>This style requires that each element have access to data from the schema for validation and error
reporting. To avoid the expense of constructing this data repeatedly it is split off into classes
based on <a class="reference internal" href="#_CPPv418TsConfigDescriptor" title="TsConfigDescriptor"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">TsConfigDescriptor</span></code></a>. Instances of subclasses of this are intended to be declared
staticly and the elements of the configuration class are initialized with references to these static
instances. The <a class="reference internal" href="#_CPPv412TsConfigBase" title="TsConfigBase"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">TsConfigBase</span></code></a> class hierarchy is for dynamic, per configuration data and the
<a class="reference internal" href="#_CPPv418TsConfigDescriptor" title="TsConfigDescriptor"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">TsConfigDescriptor</span></code></a> class hierarchy is for static schema data.</p>
<p>All of this is description and operations. The actual configuration data is stored directly as
members of the configuration class for easier access. Consider a schema that is a single integer.</p>
<div class="highlight-lua notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="n">cname</span><span class="o">=</span><span class="s2">"CounterConfig"</span><span class="p">,</span>
<span class="n">global</span><span class="o">=</span><span class="s2">"ItemCounter"</span><span class="p">,</span>
<span class="n">name</span><span class="o">=</span><span class="s2">"counter"</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s2">"integer"</span><span class="p">.</span>
<span class="n">description</span><span class="o">=</span><span class="s2">"Number of items to track."</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This creates a container class.</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">CounterConfig</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="k">public</span><span class="w"> </span><span class="n">TsConfigBase</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="n">CounterConfig</span><span class="p">()</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">TsConfigbase</span><span class="p">{</span><span class="n">_DESCRIPTOR</span><span class="p">},</span><span class="w"></span>
<span class="w"> </span><span class="n">_meta_counter</span><span class="p">{</span><span class="n">counter</span><span class="p">,</span><span class="w"> </span><span class="n">COUNTER_DESCRIPTOR</span><span class="p">}</span><span class="w"></span>
<span class="w"> </span><span class="p">{}</span><span class="w"></span>
<span class="w"> </span><span class="c1">/// Load from the file at @a path.</span>
<span class="w"> </span><span class="n">ts</span><span class="o">::</span><span class="n">Errata</span><span class="w"> </span><span class="n">load</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="w"> </span><span class="k">const</span><span class="o">&</span><span class="w"> </span><span class="n">path</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="c1">/// Data loader method.</span>
<span class="w"> </span><span class="n">ts</span><span class="o">::</span><span class="n">Errata</span><span class="w"> </span><span class="nf">loader</span><span class="p">(</span><span class="n">lua_State</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">s</span><span class="p">)</span><span class="w"> </span><span class="k">override</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="c1">/// Number of items to track.</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">counter</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="c1">/// Descriptor for schema / CounterConfig</span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigSchemaDescriptor</span><span class="w"> </span><span class="n">_DESCRIPTOR</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="c1">/// Static schema data for @a counter.</span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigDescriptor</span><span class="w"> </span><span class="n">COUNTER_DESCRIPTOR</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="c1">/// Dynamic data for @a counter.</span>
<span class="w"> </span><span class="n">TsConfigInt</span><span class="w"> </span><span class="n">_meta_counter</span><span class="p">;</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
<p>The schema static data is defined as</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigSchemaDescriptor</span><span class="w"> </span><span class="n">CounterConfig</span><span class="o">::</span><span class="n">_DESCRIPTOR</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="n">TsConfigDescriptor</span><span class="o">::</span><span class="n">SCHEMA</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">"CounterConfig"</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">""</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">""</span><span class="w"></span>
<span class="p">};</span><span class="w"></span>
<span class="k">static</span><span class="w"> </span><span class="n">TsConfigDescriptor</span><span class="w"> </span><span class="n">CounterConfig</span><span class="o">::</span><span class="n">COUNT_DESCRIPTOR</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="n">TsConfigDescriptor</span><span class="o">::</span><span class="n">INT</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">"integer"</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">"count"</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">""</span><span class="w"></span>
<span class="p">};</span><span class="w"></span>
</pre></div>
</div>
<p>Loading the configuration is done by</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">CounterConfig</span><span class="w"> </span><span class="n">config</span><span class="p">;</span><span class="w"></span>
<span class="n">config</span><span class="o">-></span><span class="n">load</span><span class="p">(</span><span class="s">"counter.config"</span><span class="p">);</span><span class="w"></span>
<span class="c1">// ...</span>
<span class="n">tracker</span><span class="p">.</span><span class="n">resize</span><span class="p">(</span><span class="n">config</span><span class="p">.</span><span class="n">counter</span><span class="p">);</span><span class="w"> </span><span class="c1">// Use loaded value.</span>
</pre></div>
</div>
<p>A valid configuration example</p>
<div class="highlight-lua notranslate"><div class="highlight"><pre><span></span><span class="n">ItemCounter</span> <span class="o">=</span> <span class="mi">17</span><span class="p">;</span>
</pre></div>
</div>
<section id="enumerations">
<h3>Enumerations<a class="headerlink" href="#enumerations" title="Permalink to this headline">¶</a></h3>
<p>Being able to contrain primitive values to a specific set of values is critical to providing good
feedback for configurations. Data for an enumeration is stored in a static instance of
<a class="reference internal" href="#_CPPv422TsConfigEnumDescriptor" title="TsConfigEnumDescriptor"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">TsConfigEnumDescriptor</span></code></a>. This contains two mappings, from string keys to numeric values and
from numeric values to string keys. These values should be available in C++ and in Lua.</p>
<p>For Lua enumerations are stored as tables attached to predefined global variables. The schema
supports defining such enumerations and specifying the global variable. Note this can be a nested
path so that a schema could have a single top level global for its enumerations with each
enumeration an entry in the global table. The presumption is the enumeration values are integers and
these are the values passed to the configuration loader, specified by the global value. This is
intended to minimize undetected typographic errors in the configuration file.</p>
<p>Enumerations are defined in a top level key of the schema named <code class="docutils literal notranslate"><span class="pre">definitions</span></code>. Enumerations are
restricted to mappings between strings (“keys”) and integers (“values”). The mapping can be defined
in multiple ways.</p>
<dl class="simple">
<dt>Lua array of strings</dt><dd><p>The keys are the strings in the array and the corresponding values the index of the string in the array.</p>
</dd>
<dt>Lua table</dt><dd><p>This must be a map between strings and integers, in either direction. A mapping from integers to
strings is flipped to its dual. Duplicated keys or values are an error.</p>
</dd>
</dl>
<p>The schema data for an enumeration is stored in a static instance of
<a class="reference internal" href="#_CPPv422TsConfigEnumDescriptor" title="TsConfigEnumDescriptor"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">TsConfigEnumDescriptor</span></code></a>. The internal maps are initialized by the constructor.</p>
</section>
</section>
<section id="generic-data">
<h2>Generic Data<a class="headerlink" href="#generic-data" title="Permalink to this headline">¶</a></h2>
<p>Not all data can be explicitly described in the configuration schema due to the names or structure
being generic. In this case an array or object can use set <code class="docutils literal notranslate"><span class="pre">additionalProperties</span></code> (for an object)
or <code class="docutils literal notranslate"><span class="pre">additionalItems</span></code> (for an array) to <code class="docutils literal notranslate"><span class="pre">true</span></code> to enable generic data. For an object a member is
generated that contains a mapping from strings to generic values.</p>
</section>
<section id="interface">
<h2>Interface<a class="headerlink" href="#interface" title="Permalink to this headline">¶</a></h2>
<dl class="cpp class">
<dt class="sig sig-object cpp" id="_CPPv412TsConfigBase">
<span id="_CPPv312TsConfigBase"></span><span id="_CPPv212TsConfigBase"></span><span id="TsConfigBase"></span><span class="k"><span class="pre">class</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">TsConfigBase</span></span></span><a class="headerlink" href="#_CPPv412TsConfigBase" title="Permalink to this definition">¶</a><br /></dt>
<dd><dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4N12TsConfigBase12TSConfigBaseEv">
<span id="_CPPv3N12TsConfigBase12TSConfigBaseEv"></span><span id="_CPPv2N12TsConfigBase12TSConfigBaseEv"></span><span id="TsConfigBase::TSConfigBase"></span><span class="sig-name descname"><span class="n"><span class="pre">TSConfigBase</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N12TsConfigBase12TSConfigBaseEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Default constructor. The configuration is populated with defaults, if specified.</p>
</dd></dl>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4N12TsConfigBase6loaderERKNSt6stringE">
<span id="_CPPv3N12TsConfigBase6loaderERKNSt6stringE"></span><span id="_CPPv2N12TsConfigBase6loaderERKNSt6stringE"></span><span id="TsConfigBase::loader__ssCR"></span><a class="reference internal" href="external-types.en.html#_CPPv42ts" title="ts"><span class="n"><span class="pre">ts</span></span></a><span class="p"><span class="pre">::</span></span><a class="reference internal" href="external-types.en.html#_CPPv4N2ts6ErrataE" title="ts::Errata"><span class="n"><span class="pre">Errata</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">loader</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="external-types.en.html#_CPPv4St" title="std"><span class="n"><span class="pre">std</span></span></a><span class="p"><span class="pre">::</span></span><a class="reference internal" href="external-types.en.html#_CPPv4NSt6stringE" title="std::string"><span class="n"><span class="pre">string</span></span></a><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="p"><span class="pre">&</span></span><span class="n sig-param"><span class="pre">path</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N12TsConfigBase6loaderERKNSt6stringE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Load data from the Lua config specified by <em>path</em>.</p>
</dd></dl>
<dl class="cpp enum">
<dt class="sig sig-object cpp" id="_CPPv4N12TsConfigBase6SourceE">
<span id="_CPPv3N12TsConfigBase6SourceE"></span><span id="_CPPv2N12TsConfigBase6SourceE"></span><span class="k"><span class="pre">enum</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Source</span></span></span><a class="headerlink" href="#_CPPv4N12TsConfigBase6SourceE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Which type of source of configuration data.</p>
<dl class="c macro">
<dt class="sig sig-object c" id="c.NONE">
<span class="sig-name descname"><span class="n"><span class="pre">NONE</span></span></span><a class="headerlink" href="#c.NONE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>No explicit source, data is default constructed.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.SCHEMA">
<span class="sig-name descname"><span class="n"><span class="pre">SCHEMA</span></span></span><a class="headerlink" href="#c.SCHEMA" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Data was taken from defaults in the schema.</p>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.CONFIG">
<span class="sig-name descname"><span class="n"><span class="pre">CONFIG</span></span></span><a class="headerlink" href="#c.CONFIG" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Data was read from the configuration file. This value has priority - if the source is
<a class="reference internal" href="#c.CONFIG" title="CONFIG"><code class="xref c c-macro docutils literal notranslate"><span class="pre">CONFIG</span></code></a> for a non-primitive that means at least one nested primitive value was read
from the configuration file.</p>
</dd></dl>
</dd></dl>
<dl class="cpp member">
<dt class="sig sig-object cpp" id="_CPPv4N12TsConfigBase6sourceE">
<span id="_CPPv3N12TsConfigBase6sourceE"></span><span id="_CPPv2N12TsConfigBase6sourceE"></span><span id="TsConfigBase::source__Source"></span><a class="reference internal" href="#_CPPv4N12TsConfigBase6SourceE" title="TsConfigBase::Source"><span class="n"><span class="pre">Source</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">source</span></span></span><a class="headerlink" href="#_CPPv4N12TsConfigBase6sourceE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>The source for the configuration data associated with this instance.</p>
</dd></dl>
<dl class="cpp member">
<dt class="sig sig-object cpp" id="_CPPv4N12TsConfigBase10descriptorE">
<span id="_CPPv3N12TsConfigBase10descriptorE"></span><span id="_CPPv2N12TsConfigBase10descriptorE"></span><span id="TsConfigBase::descriptor__TsConfigDescriptorCR"></span><a class="reference internal" href="#_CPPv418TsConfigDescriptor" title="TsConfigDescriptor"><span class="n"><span class="pre">TsConfigDescriptor</span></span></a><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="p"><span class="pre">&</span></span><span class="sig-name descname"><span class="n"><span class="pre">descriptor</span></span></span><a class="headerlink" href="#_CPPv4N12TsConfigBase10descriptorE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Static schema data for the configuration value.</p>
</dd></dl>
</dd></dl>
<dl class="cpp class">
<dt class="sig sig-object cpp" id="_CPPv418TsConfigDescriptor">
<span id="_CPPv318TsConfigDescriptor"></span><span id="_CPPv218TsConfigDescriptor"></span><span id="TsConfigDescriptor"></span><span class="k"><span class="pre">class</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">TsConfigDescriptor</span></span></span><a class="headerlink" href="#_CPPv418TsConfigDescriptor" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Base class for schema element descriptions.</p>
</dd></dl>
<dl class="cpp class">
<dt class="sig sig-object cpp" id="_CPPv422TsConfigEnumDescriptor">
<span id="_CPPv322TsConfigEnumDescriptor"></span><span id="_CPPv222TsConfigEnumDescriptor"></span><span id="TsConfigEnumDescriptor"></span><span class="k"><span class="pre">class</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">TsConfigEnumDescriptor</span></span></span><span class="w"> </span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="k"><span class="pre">public</span></span><span class="w"> </span><a class="reference internal" href="#_CPPv418TsConfigDescriptor" title="TsConfigDescriptor"><span class="n"><span class="pre">TsConfigDescriptor</span></span></a><a class="headerlink" href="#_CPPv422TsConfigEnumDescriptor" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Schema data for an enumeration type.</p>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4NK22TsConfigEnumDescriptorixEi">
<span id="_CPPv3NK22TsConfigEnumDescriptorixEi"></span><span id="_CPPv2NK22TsConfigEnumDescriptorixEi"></span><span id="TsConfigEnumDescriptor::subscript-operator__iC"></span><a class="reference internal" href="external-types.en.html#_CPPv42ts" title="ts"><span class="n"><span class="pre">ts</span></span></a><span class="p"><span class="pre">::</span></span><a class="reference internal" href="external-types.en.html#_CPPv4N2ts11string_viewE" title="ts::string_view"><span class="n"><span class="pre">string_view</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="k"><span class="pre">operator</span></span><span class="o"><span class="pre">[]</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">value</span></span><span class="sig-paren">)</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><a class="headerlink" href="#_CPPv4NK22TsConfigEnumDescriptorixEi" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Find the key for the <em>value</em>. An <code class="code docutils literal notranslate"><span class="pre">std::out_of_range</span></code> exception is thrown if <em>value</em> is not valid.</p>
</dd></dl>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4NK22TsConfigEnumDescriptorixEN2ts11string_viewE">
<span id="_CPPv3NK22TsConfigEnumDescriptorixEN2ts11string_viewE"></span><span id="_CPPv2NK22TsConfigEnumDescriptorixEN2ts11string_viewE"></span><span id="TsConfigEnumDescriptor::subscript-operator__ts::string_viewC"></span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="k"><span class="pre">operator</span></span><span class="o"><span class="pre">[]</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="external-types.en.html#_CPPv42ts" title="ts"><span class="n"><span class="pre">ts</span></span></a><span class="p"><span class="pre">::</span></span><a class="reference internal" href="external-types.en.html#_CPPv4N2ts11string_viewE" title="ts::string_view"><span class="n"><span class="pre">string_view</span></span></a><span class="w"> </span><span class="n sig-param"><span class="pre">key</span></span><span class="sig-paren">)</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><a class="headerlink" href="#_CPPv4NK22TsConfigEnumDescriptorixEN2ts11string_viewE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Find the value for the <em>key</em>. An <code class="code docutils literal notranslate"><span class="pre">std:out_of_range</span></code> exception is thrown if <em>key</em> is not valid.</p>
</dd></dl>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4NK22TsConfigEnumDescriptor8is_validEi">
<span id="_CPPv3NK22TsConfigEnumDescriptor8is_validEi"></span><span id="_CPPv2NK22TsConfigEnumDescriptor8is_validEi"></span><span id="TsConfigEnumDescriptor::is_valid__iC"></span><span class="kt"><span class="pre">bool</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">is_valid</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">value</span></span><span class="sig-paren">)</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><a class="headerlink" href="#_CPPv4NK22TsConfigEnumDescriptor8is_validEi" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Check if <em>value</em> is valid.</p>
</dd></dl>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4NK22TsConfigEnumDescriptor8is_validEN2ts11string_viewE">
<span id="_CPPv3NK22TsConfigEnumDescriptor8is_validEN2ts11string_viewE"></span><span id="_CPPv2NK22TsConfigEnumDescriptor8is_validEN2ts11string_viewE"></span><span id="TsConfigEnumDescriptor::is_valid__ts::string_viewC"></span><span class="kt"><span class="pre">bool</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">is_valid</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="external-types.en.html#_CPPv42ts" title="ts"><span class="n"><span class="pre">ts</span></span></a><span class="p"><span class="pre">::</span></span><a class="reference internal" href="external-types.en.html#_CPPv4N2ts11string_viewE" title="ts::string_view"><span class="n"><span class="pre">string_view</span></span></a><span class="w"> </span><span class="n sig-param"><span class="pre">key</span></span><span class="sig-paren">)</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><a class="headerlink" href="#_CPPv4NK22TsConfigEnumDescriptor8is_validEN2ts11string_viewE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Check if <em>key</em> is vald.</p>
</dd></dl>
</dd></dl>
</section>
<section id="schema">
<h2>Schema<a class="headerlink" href="#schema" title="Permalink to this headline">¶</a></h2>
<p>A Lua configuration schema has its own schema.</p>
<div class="highlight-lua notranslate"><div class="highlight"><pre><span></span><span class="n">schema</span> <span class="o">=</span>
<span class="p">{</span>
<span class="p">[</span><span class="s1">'$schema'</span><span class="p">]</span><span class="o">=</span> <span class="s2">"http://trafficsever.apache.org/config/meta-schema"</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s2">"Lua Configuration MetaSchema"</span><span class="p">,</span>
<span class="n">global</span> <span class="o">=</span> <span class="s1">'schema'</span><span class="p">,</span>
<span class="n">class</span> <span class="o">=</span> <span class="s1">'TsLuaMetaConfig'</span><span class="p">,</span>
<span class="n">properties</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">[</span><span class="s1">'$schema'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span><span class="o">=</span> <span class="s2">"string"</span><span class="p">,</span>
<span class="n">description</span><span class="o">=</span> <span class="s2">"Schema identifier."</span>
<span class="p">},</span>
<span class="n">description</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span><span class="o">=</span> <span class="s2">"string"</span><span class="p">,</span>
<span class="n">description</span><span class="o">=</span> <span class="s2">"Description of the schema."</span><span class="p">,</span>
<span class="p">},</span>
<span class="n">global</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'string'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Lua global variable in which the schema will be stored.'</span>
<span class="p">},</span>
<span class="n">class</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'string'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'C++ class for configuration.'</span>
<span class="p">},</span>
<span class="n">properties</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'object'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'The members of the object.'</span><span class="p">,</span>
<span class="n">additionalProperties</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>
<span class="n">minProperties</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
<span class="n">properties</span> <span class="o">=</span> <span class="p">{}</span>
<span class="p">},</span>
<span class="n">items</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'object'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'The items in the array.'</span><span class="p">,</span>
<span class="n">additionalItems</span> <span class="o">=</span> <span class="kc">true</span><span class="p">,</span>
<span class="n">minItems</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
<span class="n">items</span> <span class="o">=</span> <span class="p">{}</span>
<span class="p">},</span>
<span class="n">dependencies</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">OBJECT</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'List of optional properties for an object.'</span>
<span class="p">},</span>
<span class="n">one_of</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">OBJECT</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Set of mutually exclusive properties, exactly one of which must be present.'</span><span class="p">,</span>
<span class="n">items</span> <span class="o">=</span> <span class="n">STRING</span>
<span class="p">},</span>
<span class="n">definitions</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'array'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Sub schema definitions.'</span><span class="p">,</span>
<span class="n">items</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'object'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Description of the definition.'</span><span class="p">,</span>
<span class="n">additionalProperties</span> <span class="o">=</span> <span class="kc">true</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="n">dependencies</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">properties</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">[</span><span class="s1">'not'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">required</span> <span class="o">=</span> <span class="p">{</span> <span class="s1">'items'</span> <span class="p">}</span>
<span class="p">},</span>
<span class="n">items</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">[</span><span class="s1">'not'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">required</span> <span class="o">=</span> <span class="p">{</span> <span class="s1">'properties'</span> <span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="n">definitions</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">object</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">class</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">STRING</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'C++ struct name.'</span>
<span class="p">},</span>
<span class="n">description</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">STRING</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Object description.'</span>
<span class="p">},</span>
<span class="n">properties</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">[</span><span class="s1">'$ref'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'#/definitions/object'</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="cm">--[[</span>
<span class="cm"> It should be possible to specify how to set up an enumeration with just an array,</span>
<span class="cm"> filling the other values with defaults. E.g. an array of strings or an array of integers.</span>
<span class="cm"> ]]</span>
<span class="n">enum</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">OBJECT</span><span class="p">,</span>
<span class="n">typeName</span> <span class="o">=</span> <span class="s1">'EnumType'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Enumeration'</span><span class="p">,</span>
<span class="n">properties</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">typeName</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'string'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'C++ type name.'</span>
<span class="p">},</span>
<span class="n">global</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">STRING</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Global variable that contains the enumeration values.'</span>
<span class="p">},</span>
<span class="n">kv</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">ARRAY</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Enumeration keys and values'</span><span class="p">,</span>
<span class="n">items</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'object'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Enumeration value'</span><span class="p">,</span>
<span class="n">properties</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'string'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Enumeration key'</span>
<span class="p">},</span>
<span class="n">value</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'integer'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Enumeration value'</span>
<span class="p">},</span>
<span class="n">description</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="s1">'string'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Meaning of this value'</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="n">ValueType</span> <span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">ENUM</span><span class="p">,</span>
<span class="n">typeName</span> <span class="o">=</span> <span class="s1">'ValueType'</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Type of data'</span><span class="p">,</span>
<span class="n">global</span> <span class="o">=</span> <span class="s1">'.'</span><span class="p">,</span>
<span class="n">kv</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="s1">'nil'</span><span class="p">,</span>
<span class="n">value</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Null / invalid value.'</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="s1">'boolean'</span><span class="p">,</span>
<span class="n">value</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Boolean (true/false) value.'</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="s1">'string'</span><span class="p">,</span>
<span class="n">value</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'String value.'</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="s1">'integer'</span><span class="p">,</span>
<span class="n">value</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Integral value.'</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="s1">'number'</span><span class="p">,</span>
<span class="n">value</span> <span class="o">=</span> <span class="mi">4</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Numeric value.'</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="s1">'object'</span><span class="p">,</span>
<span class="n">value</span> <span class="o">=</span> <span class="mi">5</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Object - collection of key / value pairs.'</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="s1">'array'</span><span class="p">,</span>
<span class="n">value</span> <span class="o">=</span> <span class="mi">6</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Array of values.'</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="n">key</span> <span class="o">=</span> <span class="s1">'enum'</span><span class="p">,</span>
<span class="n">value</span> <span class="o">=</span> <span class="mi">7</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s1">'Enumeration'</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<section id="example">
<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
<p>An example project using TsLuaConfig is SNI remap. An example configuration looks like</p>
<div class="highlight-lua notranslate"><div class="highlight"><pre><span></span><span class="n">sni_config</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">{</span> <span class="n">fqdn</span><span class="o">=</span><span class="s2">"one.com"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">TLS</span><span class="p">.</span><span class="n">ACTION</span><span class="p">.</span><span class="n">TUNNEL</span><span class="p">,</span> <span class="n">upstream_cert_verification</span><span class="p">:</span><span class="n">TLS</span><span class="p">.</span><span class="n">VERIFY</span><span class="p">.</span><span class="n">REQUIRED</span><span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The schema to describe this configuration is</p>
<div class="highlight-lua notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="p">[</span><span class="s2">"$schema"</span><span class="p">]</span><span class="o">=</span> <span class="s2">"http://trafficserver.apache.org/config/sni-remap"</span><span class="p">,</span>
<span class="n">name</span><span class="o">=</span> <span class="s2">"SNIConfig"</span><span class="p">,</span>
<span class="n">global</span><span class="o">=</span> <span class="s2">"sni_config"</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s2">"object"</span><span class="p">,</span>
<span class="n">properties</span><span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span><span class="o">=</span><span class="s2">"array"</span><span class="p">,</span>
<span class="n">items</span><span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span><span class="o">=</span> <span class="s2">"object"</span><span class="p">,</span>
<span class="n">properties</span><span class="o">=</span> <span class="p">{</span>
<span class="n">fqdn</span><span class="o">=</span> <span class="p">{</span>
<span class="nb">type</span><span class="o">=</span> <span class="s2">"string"</span><span class="p">,</span>
<span class="n">validators</span><span class="o">=</span> <span class="p">{</span> <span class="s2">"fqdn-check"</span> <span class="p">}</span>
<span class="p">}.</span>
<span class="n">client_cert_verify</span><span class="o">=</span><span class="p">{</span>
<span class="p">[</span><span class="s1">'$ref'</span><span class="p">]</span><span class="o">=</span><span class="s1">'#/definitions/cert_verification'</span><span class="p">,</span>
<span class="n">description</span><span class="o">=</span><span class="s1">'Level of verification for client certificate.'</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="n">definitions</span><span class="o">=</span><span class="p">{</span>
<span class="n">tls_action</span><span class="o">=</span><span class="p">{</span>
<span class="n">key</span><span class="o">=</span><span class="s1">'string'</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s1">'integer'</span><span class="p">,</span>
<span class="n">lua</span><span class="o">=</span><span class="s1">'TLS.ACTION'</span><span class="p">,</span>
<span class="n">kv</span><span class="o">=</span><span class="p">{</span><span class="n">NONE</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span><span class="n">TUNNEL</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span><span class="n">CLOSE</span><span class="o">=</span><span class="mi">2</span><span class="p">}</span>
<span class="p">},</span>
<span class="n">cert_verification</span><span class="o">=</span><span class="p">{</span>
<span class="n">key</span><span class="o">=</span><span class="s1">'string'</span><span class="p">,</span>
<span class="nb">type</span><span class="o">=</span><span class="s1">'integer'</span><span class="p">,</span>
<span class="n">lua</span><span class="o">=</span><span class="s1">'TLS.VERIFICATION'</span><span class="p">,</span>
<span class="n">kv</span><span class="o">=</span><span class="p">{</span><span class="n">NONE</span><span class="p">,</span> <span class="n">WARN</span><span class="p">,</span> <span class="n">REQUIRE</span><span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This generates a config class.</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nc">LuaSNIConfig</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="k">public</span><span class="w"> </span><span class="n">TsConfigBase</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="k">using</span><span class="w"> </span><span class="n">self</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">LuaSNIConfig</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="k">enum</span> <span class="k">class</span><span class="w"> </span><span class="nc">Action</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">CLOSE</span><span class="p">,</span><span class="w"> </span><span class="n">TUNNEL</span><span class="w"> </span><span class="p">};</span><span class="w"></span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigArrayDescriptor</span><span class="w"> </span><span class="n">DESCRIPTOR</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="n">LuaSNIConfig</span><span class="p">()</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">TsConfigBase</span><span class="p">(</span><span class="n">DESCRIPTOR</span><span class="p">),</span><span class="w"> </span><span class="n">DESCRIPTOR</span><span class="p">(</span><span class="n">Item</span><span class="o">::</span><span class="n">DESCRIPTOR</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span><span class="w"></span>
<span class="w"> </span><span class="k">struct</span> <span class="nc">Item</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="k">public</span><span class="w"> </span><span class="n">TsConfigBase</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="n">Item</span><span class="p">()</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">TsConfigBase</span><span class="p">(</span><span class="n">DESCRIPTOR</span><span class="p">),</span><span class="w"></span>
<span class="w"> </span><span class="n">FQDN_CONFIG</span><span class="p">(</span><span class="n">FQDN_DESCRIPTOR</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">self</span><span class="o">::</span><span class="n">fqdn</span><span class="p">),</span><span class="w"></span>
<span class="w"> </span><span class="n">LEVEL_CONFIG</span><span class="p">(</span><span class="n">LEVEL_DESCRIPTOR</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">self</span><span class="o">::</span><span class="n">level</span><span class="p">),</span><span class="w"></span>
<span class="w"> </span><span class="n">ACTION_CONFIG</span><span class="p">(</span><span class="n">ACTION_DESCRIPTOR</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="n">self</span><span class="o">::</span><span class="n">action</span><span class="p">)</span><span class="w"></span>
<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">}</span><span class="w"></span>
<span class="w"> </span><span class="n">Errata</span><span class="w"> </span><span class="n">loader</span><span class="p">(</span><span class="n">lua_State</span><span class="o">*</span><span class="w"> </span><span class="n">s</span><span class="p">)</span><span class="w"> </span><span class="k">override</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="w"> </span><span class="n">fqdn</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">level</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="n">Action</span><span class="w"> </span><span class="n">action</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="c1">// These need to be initialized statically.</span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigObjectDescriptor</span><span class="w"> </span><span class="n">DESCRIPTOR</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigBaseDescriptor</span><span class="w"> </span><span class="n">FQDN_DESCRIPTOR</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigString</span><span class="o"><</span><span class="n">Item</span><span class="o">></span><span class="w"> </span><span class="n">FQDN_CONFIG</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigBaseDescriptor</span><span class="w"> </span><span class="n">LEVEL_DESCRIPTOR</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigInt</span><span class="o"><</span><span class="n">Item</span><span class="o">></span><span class="w"> </span><span class="n">LEVEL_CONFIG</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigEnumDescriptor</span><span class="w"> </span><span class="n">ACTION_DESCRIPTOR</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="n">TsConfigEnum</span><span class="o"><</span><span class="n">Item</span><span class="p">,</span><span class="w"> </span><span class="n">ACTION</span><span class="o">></span><span class="w"> </span><span class="n">ACTION_CONFIG</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="p">};</span><span class="w"></span>
<span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">Item</span><span class="o">></span><span class="w"> </span><span class="n">items</span><span class="p">;</span><span class="w"></span>
<span class="w"> </span><span class="n">ts</span><span class="o">::</span><span class="n">Errata</span><span class="w"> </span><span class="nf">loader</span><span class="p">(</span><span class="n">lua_State</span><span class="o">*</span><span class="w"> </span><span class="n">s</span><span class="p">)</span><span class="w"> </span><span class="k">override</span><span class="p">;</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
</section>
</section>
<section id="future-work">
<h2>Future Work<a class="headerlink" href="#future-work" title="Permalink to this headline">¶</a></h2>
<p>In the long run it would desirable to have a single Lua configuration file for all configurations.</p>
<p>There is a difficult question on how <code class="docutils literal notranslate"><span class="pre">traffic_ctl</span></code> interacts with Lua based configuration. That is
not specific to this configuration system but is a more general problem.</p>
<p>Some consideration must be given to whether variants should be supported. This would allow a
configuration value to be listed as multiple types and any of the types would be acceptable. It’s
unclear how useful this would be. The most common case I can think of is enabling singletons vs.
arrays, but it would be easier to just do that directly in the validation stage. That is, if a type
is described as “array of T” and the value is a single T, convert it to an array of size 1. This
seems obvious and non confusing and I’m not sure there are any other good use cases.</p>
</section>
<section id="history">
<h2>History<a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h2>
<p>Originally this work was intended to be based on the existing TsConfig library. This was eventually
abandoned due to concerns about configuration error feedback. TsConfig provides detailed reporting
for errors but can do that only because it also does the parsing. With the loss of control text
parsing providing useful feedback becomes effectively impossible. Related to this was the ability to
detect “excess” configuration that didn’t match what was expected. This is most commonly the result
of typographic errors and the operator should be informed of this rather the configuration silently
using defaults. This is something possible with the current system - it can at least warn of ignored
configuration variables. Once there is a mechanismm for describing which values are expected there
are many things that can be added to it at low marginal cost. The eventual result is the schema
system described here.</p>
<p class="rubric">Footnotes</p>
<dl class="footnote brackets">
<dt class="label" id="fn-schema"><span class="brackets"><a class="fn-backref" href="#id2">1</a></span></dt>
<dd><p>While some consideration was given to using the JSON schema directly, over all it
was considered overall better to use Lua for consistency so all of the configuration related data is
in the same language.</p>
</dd>
</dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/balcora-gate-400x400.jpg" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">TSConfig / Lua</a><ul>
<li><a class="reference internal" href="#current-practice">Current Practice</a></li>
<li><a class="reference internal" href="#design">Design</a></li>
<li><a class="reference internal" href="#implementation">Implementation</a><ul>
<li><a class="reference internal" href="#enumerations">Enumerations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#generic-data">Generic Data</a></li>
<li><a class="reference internal" href="#interface">Interface</a></li>
<li><a class="reference internal" href="#schema">Schema</a><ul>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#future-work">Future Work</a></li>
<li><a class="reference internal" href="#history">History</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="delain.en.html"
title="previous chapter">Delain</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="atc/atc-index.html"
title="next chapter">Apache Traffic Control</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/tsconfig-lua.en.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="atc/atc-index.html" title="Apache Traffic Control"
>next</a> |</li>
<li class="right" >
<a href="delain.en.html" title="Delain"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">SWOC Docs</a> »</li>
<li class="nav-item nav-item-1"><a href="ats-projects.en.html" >Traffic Server Projects</a> »</li>
<li class="nav-item nav-item-this"><a href="">TSConfig / Lua</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2017, [email protected].
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.1.2.
</div>
</body>
</html>