/
index.xml
368 lines (368 loc) · 15.1 KB
/
index.xml
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
<!DOCTYPE html>
<html lang="en" prefix="og: http://ogp.me/ns#">
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta charset="utf-8" />
<title>openradtool | application source generator</title>
<link rel="alternate" href="atom.xml" type="application/atom+xml" title="openradtool version feed" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Alegreya+Sans:400,400italic,500" />
<link rel="stylesheet" href="https://www.bsd.lv/css/style.css" />
<link rel="stylesheet" href="highlight.css" />
<link rel="stylesheet" href="index.css" />
<meta property="og:title" content="openradtool: application source generator" />
<meta property="og:url" content="https://kristaps.bsd.lv/openradtool/index.html" />
<meta property="og:type" content="website" />
<meta property="og:description" content="An open source rapid application development utility." />
<meta name="description" content="An open source rapid application development utility." />
</head>
<body itemscope="itemscope" itemtype="http://schema.org/SoftwareApplication">
<header>
<section id="breadcrumbs">
<div>
<div>
BSD.lv tools for <a href="https://learnbchs.org">BCHS</a>:
<a href="https://kristaps.bsd.lv/kcgi">kcgi</a>,
<a href="https://kristaps.bsd.lv/sqlbox">sqlbox</a>,
<a href="https://kristaps.bsd.lv/openradtool">ort</a>
</div>
</div>
</section>
<section id="header">
<div class="intro">
<h1 itemprop="name">openradtool</h1>
<span>—
<span itemprop="description">application source generator</span>
<nav data-sblg-nav="1" data-sblg-navsort="date" data-sblg-navtag="version"
data-sblg-navsz="1" data-sblg-navxml="1">
${sblg-titletext}
</nav>
</span>
</div>
<nav>
<a href="https://github.com/kristapsdz/openradtool">github</a>
<a href="snapshots/openradtool.tar.gz">source</a>
<a href="snapshots">archive</a>
<a href="archive.html">releases</a>
<a href="atom.xml">feed</a>
</nav>
</section>
</header>
<article>
<nav>
<span>introduction…</span>
</nav>
<section class="text">
<div id="intro">
<figure>
<img src="index-fig7.svg" alt="ort(5) to output" />
</figure>
<p class="intro">
<span class="nm">openradtool</span> (<q class="nm">ort</q>) is an
<a href="https://opensource.org/licenses/ISC">open source</a> RAD tool generating front-end code
(TypeScript) and back-end code (SQL, C, Rust, Node.js) from a straightforward data model.
</p>
</div>
<p>
The system consists of a set of source generators and analytical tools, each accepting a
<a href="ort.5.html">ort(5)</a> configuration that describes your data and how it is accessed, modified,
created, deleted. It runs on <a href="https://www.openbsd.org">OpenBSD</a>,
<a href="https://www.netbsd.org">NetBSD</a>, <a href="https://www.freebsd.org">FreeBSD</a>, Linux (glibc
and musl),
<a href="https://www.apple.com">Mac OS X</a>,
<a href="https://www.oracle.com/solaris/solaris11">Solaris</a> (SunOS), and
<a href="https://omniosce.org">OmniOS</a> (IllumOS). The generated sources run on the same.
Development is on OpenBSD, which has the highest level of built-in security.
</p>
<p>
The tools manage or generate the following application components.
</p>
<ul id="topicboxes">
<li>
<span class="topic">
Database
</span>
<span class="contents">
<a href="#gen-sql">SQL schema</a> generation (and <a href="#gen-sqldiff">schema
upgrade</a> commands) for your SQLite database.
</span>
</li>
<li>
<span class="topic">
Data Layer
</span>
<span class="contents">
Node.js, C, and Rust <a href="#gen-backend">back-end source code</a>—API and
implementation—for manipulating and exporting from the database. This must be
driven by your program code.
</span>
</li>
<li>
<span class="topic">
Presentation Layer
</span>
<span class="contents">
Front-end <a href="#gen-js">TypeScript</a> source code populating HTML5
trees with exported data. This must be driven by your front-end code.
</span>
</li>
<li>
<span class="topic">
Internationalisation
</span>
<span class="contents">
<a href="#gen-xliff">Translation files</a> for front-end TypeScript labels.
</span>
</li>
<li>
<span class="topic">
Access Controls
</span>
<span class="contents">
Security and accountability: <a href="#gen-audit">role audits</a> for studying the data
accessable by user roles.
</span>
</li>
</ul>
<p>
See the <a href="https://github.com/kristapsdz/openradtool">GitHub</a> repository for installation and issue
tracking.
<span class="nm">openradtool</span> is a <a href="https://www.bsd.lv">BSD.lv</a> project, née
<span class="nm">kwebapp</span>.
</p>
</section>
<nav id="usage">
<span>usage…</span>
</nav>
<section id="usage-box" class="text">
<p class="explain">
<span class="nm">ort</span> tools are designed to be operated by <a
href="https://man.openbsd.org/make.1">make(1)</a> or other build tool.
During development, these tools continuously keep C sources, TypeScript, translations, and so on up to
date from a single <a href="ort.5.html">ort(5)</a> file.
These files are in turn compiled or bundled into your application.
</p>
<figure>
<img src="index.svg" alt="ort(5) productions" />
</figure>
<h2>
<span>1.</span> validate configuration
</h2>
<code>
% <a href="ort.1.html">ort</a> <a href="db.ort.html">db.ort</a>
</code>
<section>
<figure>
<img src="index-fig1.svg" alt="ort(1) functionality" />
</figure>
<p>
Consider an example <a href="ort.5.html">ort(5)</a> configuration <a
href="db.ort.html">db.ort</a>. It defines three data objects—a <code>user</code>,
<code>company</code>, and <code>session</code>—with relations between the three.
Each <code>session</code> refers to a <code>user</code> by the <code>userid</code> field.
Then each <code>user</code> refers to a <code>company</code> by its <code>cid</code>.
</p>
<p>
The <a href="ort.1.html">ort(1)</a> utility parses and validates the configuration.
To <em>do</em> something with this configuration, we need to have code.
Most applications start by creating an API from the data configuration as described in the next
section.
</p>
<p>
<em>This validation is superfluous, as all other tools validate during parse.</em>
</p>
</section>
<h2 id="gen-backend">
<span>2.</span> generate back-end code
</h2>
<code>
% <a href="ort-c-header.1.html">ort-c-header</a> -jv
<a href="db.ort.html">db.ort</a> > <a href="db.h.html">db.h</a>
<br />
% <a href="ort-c-source.1.html">ort-c-source</a> -jv
-h <a href="db.h.html">db.h</a> <a href="db.ort.html">db.ort</a> > <a href="db.c.html">db.c</a>
<br />
% <a href="ort-nodejs.1.html">ort-nodejs</a>
<a href="db.ort.html">db.ort</a> > <a href="db.node.ts.html">db.node.ts</a>
<br />
% <a href="ort-rust.1.html">ort-rust</a>
<a href="db.ort.html">db.ort</a> > <a href="db.rust.rs.html">db.rust.rs</a>
</code>
<section>
<p>
C, Rust, and <a href="https://nodejs.org">Node.js</a> back-ends are available.
The Rust output is still somewhat experimental.
</p>
<figure>
<img src="index-fig8.svg" alt="ort-nodejs(1) functionality" />
</figure>
<p>
The Node.js backend currently lacks many of the security benefits of using the C API, such as
privilege separation, but is the more widely-used of languages.
The generated TypeScript code is built to work within <a href="https://npmjs.com">npm</a>
applications.
A full application example is available in <a href="ort-nodejs.1.html">ort-nodejs(1)</a>.
</p>
<figure>
<img src="index-fig2.svg" alt="ort-c-header(1) and ort-c-source(1) functionality" />
</figure>
<p>
The C API files may be linked to sources (usually, but not necessarily) driving
a <a href="https://kristaps.bsd.lv/kcgi">kcgi(3)</a> CGI script.
Each function and structure in the header file is documented thoroughly.
The source files are also documented, though more sparsely.
</p>
<figure>
<img src="index-fig9.svg" alt="ort-c-rust(1) functionality" />
</figure>
<p>
The <a href="https://rust-lang.org">Rust</a> output is still experimental, but is able to
interface with data models in a manner similar to the Node.js output.
It does not yet have integrated documentation or validation.
</p>
</section>
<h2 id="gen-sql">
<span>3.</span> generate and initialise database
</h2>
<code>
% <a href="ort-sql.1.html">ort-sql</a> <a href="db.ort.html">db.ort</a> > <a href="db.sql.html">db.sql</a>
<br />
% sqlite3 db.db < <a href="db.sql.html">db.sql</a>
</code>
<section>
<figure>
<img src="index-fig3.svg" alt="ort-sql(1) functionality" />
</figure>
<div>
<p>
Some object fields, such as the <code>user</code> structure inside of the section, are
not part of the SQL schema, but required for creating the SQL queries during runtime.
For the most part, however, all <a href="ort.5.html">ort(5)</a> fields map into database
columns.
</p>
<p>
The SQL schema file is thoroughly documented.
Use <a href="https://kristaps.bsd.lv/sqliteconvert">sqliteconvert</a> or similar tool
to browse the SQL documentation for any non-trivial application.
</p>
</div>
</section>
<h2 id="gen-sqldiff">
<span>4.</span> update database
</h2>
<code>
% <a href="ort-sqldiff.1.html">ort-sqldiff</a>
<a href="db.old.ort.html">db.old.ort</a> <a href="db.ort.html">db.ort</a> >
<a href="db.update.sql.html">db.update.sql</a>
<br />
% sqlite3 db.db < <a href="db.sql.html">db.update.sql</a>
</code>
<section>
<figure>
<img src="index-fig4.svg" alt="ort-sqldiff(1) functionality" />
</figure>
<p>
Database upgrades are a pain: <a href="ort-sqldiff.1.html">ort-sqldiff(1)</a> programmatically
tracks differences in the database schema.
This allows for continuous testing of database compatibility.
It also generates the correct SQL commands for properly upgrading an existing database without
fear of ordering or missing field attributes.
</p>
<p>
(Update scripts should, however, always be perused for correctness.)
</p>
</section>
<h2 id="gen-js">
<span>5.</span> generate typescript front-end
</h2>
<code>
% <a href="ort-javascript.1.html">ort-javascript</a>
<a href="db.ort.html">db.ort</a> > <a href="db.ts.html">db.ts</a>
</code>
<section>
<figure>
<img src="index-fig5.svg" alt="ort-javascript(1) functionality" />
</figure>
<p>
The last part of the toolchain is to handle the JSON-export output in the browser itself.
The <a href="ort-javascript.1.html">ort-javascript(1)</a> tool will also generate
TypeScript files to assist in filling in data for your front-end web application code.
</p>
<p>
Both are the same, and provide an easy interface for replacing elements (noted by class names)
in HTML DOM trees with data.
All of this is documented using <a href="https://typedoc.org">tsdoc</a> notation.
For example, consider the following:
</p>
<article data-sblg-permlink="0" data-sblg-article="1"></article>
<p>
A TypeScript file may invoke
<code>new ort.user(res).fill<wbr />(document.getElementById<wbr />('foobar'))</code>,
where <code>res</code> is the JSON object parsed from an AJAX call to the CGI script.
This will recursively replace text (classes ending with <code>-text</code>), fill in input
values, and allow for extensive customisation.
</p>
</section>
<h2 id="gen-xliff">
<span>6.</span> translate javascript labels
</h2>
<code>
% <a href="ort-xliff.1.html">ort-xliff</a>
<a href="db.ort.html">db.ort</a> > <a href="db.fr.xml.html">db.fr.xml</a>
<br />
% <a href="ort-xliff.1.html">ort-xliff</a> -j
<a href="db.ort.html">db.ort</a> <a href="db.fr.xml.html">db.fr.xml</a> >
<a href="db.trans.ort.html">db.trans.ort</a>
</code>
<section>
<figure>
<img src="index-fig6.svg" alt="ort-xliff(1) functionality" />
</figure>
<p>
The <a href="ort-javascript.1.html">ort-javascript(1)</a> tool is capable of filling in labels
of exported enumeration and bitfield values.
For example, if an exported field is of the <code>enum foo</code> type, and the enumeration's
items have <code>jslabel</code> tags, integral enumeration values can be programmatically
converted to the labels by invoking the <code>ort.foo.format()</code> method as a custom
callback.
</p>
<p>
These strings may be translated by using the <a href="ort-xliff.1.html">ort-xliff(1)</a>
utility, which extracts translatable strings into the industry-standard <a
href="http://docs.oasis-open.org/xliff/v1.2/os/xliff-core.html">XLIFF 1.2</a> format.
The translation files may then be merged back into the configuration file, with the output piped
into <a href="ort-javascript.1.html">ort-javascript(1)</a>, for a full translation sequence.
</p>
</section>
<h2 id="gen-audit">
<span>7.</span> audit role-based access
</h2>
<code>
% <a href="ort-audit.1.html">ort-audit</a>
<a href="audit-example.ort.html">audit-example.ort</a> user
</code>
<section>
<p>
Arguably the most powerful feature of <span class="nm">ort</span>.
Audit <a href="https://learnbchs.org/rbac.html">role-based access control</a> access with <a
href="ort-audit.1.html">ort-audit(1)</a> and <a
href="ort-audit-json.1.html">ort-audit-json(1)</a>:
see the full availability of data and operations available to the role.
Role compliance in <span class="nm">ort</span> is guaranteed by having separate jailed database
and application processes.
</p>
<p>
In the example role-backed <a href="audit-example.ort.html">audit-example.ort</a> with roles
<code>user</code> and <code>admin</code>, for example, these tools can fully audit for the
<code>user</code> role as seen in the exemplar <a href="audit.html">audit.html</a> created with
<a href="ort-audit-json.1.html">ort-audit-json(1)</a>.
This visualisation breaks down access by structures (the foundational objects of <a
href="ort.5.html">ort(5)</a>) and then grouped by operation.
</p>
</section>
</section>
</article>
<footer>
Copyright © 2017–2021, <a href="https://github.com/kristapsdz">Kristaps Dzonsons</a>
</footer>
</body>
</html>