index.html 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337
  1. <!doctype html>
  2. <html lang="en-nz">
  3. <head>
  4. <meta charset="utf-8">
  5. <meta name="viewport" content="width=device-width, initial-scale=1">
  6. <title>Astralis — Astrologue Developer</title>
  7. <meta name="description" content="Astralis is the library for writing HTTP backends in Vala — routing, headers, cookies, form data, server-sent events, document markup and layered web-config.json settings, on Inversion and Invercargill. Free software, LGPL-3.0-or-later.">
  8. <meta name="color-scheme" content="light dark">
  9. <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
  10. <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
  11. <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Ccircle cx='32' cy='32' r='27' fill='none' stroke='%23a8801f' stroke-width='4'/%3E%3Cpath d='M32 8l6 18 18 6-18 6-6 18-6-18-18-6 18-6z' fill='%23a8801f'/%3E%3Ccircle cx='32' cy='32' r='4' fill='%23003078'/%3E%3C/svg%3E">
  12. <meta property="og:title" content="Astralis — Astrologue Developer">
  13. <meta property="og:description" content="The library for writing HTTP backends in Vala: endpoints and routing, headers and cookies, form data, server-sent events, a document builder — and a web-config.json settings layer.">
  14. <meta property="og:type" content="website">
  15. <link rel="stylesheet" href="../../assets/css/style.css">
  16. </head>
  17. <body>
  18. <a class="skip-link" href="#main">Skip to content</a>
  19. <header class="masthead">
  20. <div class="container masthead__inner">
  21. <a class="brand" href="../../">
  22. <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
  23. <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
  24. </a>
  25. <nav class="site-nav" aria-label="Primary">
  26. <ul class="site-nav__list">
  27. <li><a href="../../">Home</a></li>
  28. <li><a href="../../#news">News</a></li>
  29. <li><a href="../../#download">Download</a></li>
  30. <li><a href="../" aria-current="page">Developer</a></li>
  31. <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
  32. </ul>
  33. </nav>
  34. </div>
  35. </header>
  36. <main id="main">
  37. <nav class="breadcrumb" aria-label="Breadcrumb">
  38. <div class="container">
  39. <ol>
  40. <li><a href="../../">Astrologue</a></li>
  41. <li><a href="../">Developer</a></li>
  42. <li aria-current="page">Astralis</li>
  43. </ol>
  44. </div>
  45. </nav>
  46. <section class="docs-header">
  47. <div class="container">
  48. <p class="kicker"><span>Web stack · Where a request lands</span></p>
  49. <h1>Astralis</h1>
  50. <p class="lede">The library for writing HTTP backends in Vala. An endpoint is a class, a route is metadata, a response is a value — and beneath it sit header and cookie handling, form parsing, server-sent events, a document builder and a layered JSON configuration system, all wired through Inversion and written with Invercargill.</p>
  51. <dl class="docs-facts">
  52. <div><dt>Version</dt> <dd><code>0.1</code></dd></div>
  53. <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
  54. <div><dt>Package</dt> <dd><code>usm&nbsp;install&nbsp;astralis</code></dd></div>
  55. <div><dt>Language</dt> <dd>Vala</dd></div>
  56. </dl>
  57. </div>
  58. </section>
  59. <section class="band band--plain" id="docs">
  60. <div class="container docs-layout">
  61. <nav class="docs-toc" aria-label="On this page">
  62. <h2>On this page</h2>
  63. <ul>
  64. <li><a href="#overview">Overview</a></li>
  65. <li><a href="#features">Features</a></li>
  66. <li><a href="#installation">Installation</a></li>
  67. <li><a href="#usage">Usage &amp; documentation</a></li>
  68. <li><a href="#package">Package &amp; source</a></li>
  69. </ul>
  70. </nav>
  71. <div class="docs-prose">
  72. <header class="section-head" id="overview">
  73. <p class="kicker"><span>Overview</span></p>
  74. <h2>The server the stack stands on</h2>
  75. </header>
  76. <p>Astralis takes an HTTP request from the socket to your code and back. It is built on GNU libmicrohttpd — driven in epoll mode from the GLib main loop, with suspend/resume so slow clients do not occupy a thread — and everything above that is Vala: routing by endpoint class, a pipeline of request values, results as values rather than writes to a socket.</p>
  77. <p>The design is deliberately small. You implement the <code>Endpoint</code> interface, one async method that receives an <code>HttpContext</code> and returns an <code>HttpResult</code>:</p>
  78. <figure class="code-plate">
  79. <pre><code>class HelloEndpoint : Object, Endpoint {
  80. public async HttpResult handle_request(HttpContext http_context, RouteContext route) throws Error {
  81. return new HttpStringResult("Hello from Astralis!");
  82. }
  83. }
  84. void main() {
  85. var application = new WebApplication(8080);
  86. application.add_endpoint&lt;HelloEndpoint&gt;(new EndpointRoute("/hello"));
  87. application.run();
  88. }</code></pre>
  89. <figcaption>From <code>examples/SimpleApi.vala</code> — a complete server.</figcaption>
  90. </figure>
  91. <p>Routes can carry named segments, resolved for you into the route context:</p>
  92. <figure class="code-plate">
  93. <pre><code>class HelloNameEndpoint : Object, Endpoint {
  94. public async HttpResult handle_request(HttpContext http_context, RouteContext route_info) throws Error {
  95. string? name = null;
  96. route_info.mapped_parameters.try_get("name", out name);
  97. return new HttpStringResult(@"Hello, $(name ?? "Unknown")!");
  98. }
  99. }
  100. // registered as:
  101. application.add_endpoint&lt;HelloNameEndpoint&gt;(new EndpointRoute("/hello/{name}"));</code></pre>
  102. <figcaption>From <code>examples/PathRouting.vala</code> — the router's named-segment feature.</figcaption>
  103. </figure>
  104. <p>Endpoints are registered into the <a href="../inversion/">Inversion</a> container — scoped by default, so one instance serves one request — and the stack above builds on exactly this: <a href="../statum/">Statum</a>'s pages, actions and channels are Astralis endpoints, and <a href="../spry/">Spry</a>'s authentication rides inside them.</p>
  105. <header class="section-head" id="features">
  106. <p class="kicker"><span>Features</span></p>
  107. <h2>What it hands you</h2>
  108. </header>
  109. <ul class="docs-features">
  110. <li><strong>Endpoints and routing.</strong> Classes with route metadata; named segments like <code>/users/{id}/posts</code> arrive pre-parsed in the route context.</li>
  111. <li><strong>Headers and cookies.</strong> Request headers and cookies as enumerable collections; response headers set fluently on the result value.</li>
  112. <li><strong>Form data.</strong> An async <code>FormDataParser</code> yields fields and files with typed getters and defaults for absent fields.</li>
  113. <li><strong>Server-sent events.</strong> <code>SseEndpoint</code> subclasses broadcast to every open stream, greet new connections, and set a retry interval.</li>
  114. <li><strong>A document builder.</strong> <code>MarkupDocument</code> parses, builds and queries markup with XPath selectors — HTML without a template engine.</li>
  115. <li><strong>Response compression.</strong> gzip, brotli and zstd compressors with encoding negotiation; <code>FastResource</code> serves pre-loaded content straight from memory.</li>
  116. <li><strong>Layered configuration.</strong> A <code>web-config.json</code> system with per-environment overlays merged over the base file.</li>
  117. </ul>
  118. <header class="section-head" id="installation">
  119. <p class="kicker"><span>Installation</span></p>
  120. <h2>Getting the library</h2>
  121. </header>
  122. <p>With USM on your machine, one command acquires, builds and installs the library together with its C header, Vala binding and introspection:</p>
  123. <figure class="code-plate">
  124. <pre><code>usm install astralis</code></pre>
  125. <figcaption>Installs from the Astrologue package repository.</figcaption>
  126. </figure>
  127. <p>From source, the build lives at the repository root:</p>
  128. <figure class="code-plate">
  129. <pre><code>git clone &lt;the astralis repository&gt;
  130. cd astralis
  131. meson setup . build
  132. ninja -C build
  133. ninja -C build install</code></pre>
  134. <figcaption>The same meson invocation the package's own build script uses.</figcaption>
  135. </figure>
  136. <p>Then compile against it with Vala's usual package mechanism:</p>
  137. <figure class="code-plate">
  138. <pre><code>valac --pkg astralis-0.1 my-server.vala</code></pre>
  139. <figcaption>The installed <code>astralis-0.1.deps</code> resolves the Invercargill and Inversion bindings for you.</figcaption>
  140. </figure>
  141. <header class="section-head" id="usage">
  142. <p class="kicker"><span>Usage &amp; documentation</span></p>
  143. <h2>Working with requests</h2>
  144. </header>
  145. <p>Astralis has no README; its documentation is its examples. Seventeen runnable programs cover the API surface, and each idiom below is lifted from them.</p>
  146. <h3>Responses are values</h3>
  147. <p>An <code>HttpResult</code> carries body, status and headers together, so handlers stay pure and testable — headers chain onto the constructor:</p>
  148. <figure class="code-plate">
  149. <pre><code>return new HttpStringResult(user.to_json())
  150. .set_header("Content-Type", "application/json")
  151. .set_header("Access-Control-Allow-Origin", "*");</code></pre>
  152. <figcaption>From <code>examples/JsonApi.vala</code> and <code>PathRouting.vala</code>.</figcaption>
  153. </figure>
  154. <p>Failures use the same vocabulary — a helper returns the status you name:</p>
  155. <figure class="code-plate">
  156. <pre><code>return error_response(@"Resource with ID $id not found", StatusCode.NOT_FOUND);</code></pre>
  157. <figcaption>From <code>examples/ErrorHandling.vala</code>.</figcaption>
  158. </figure>
  159. <h3>Headers, cookies and queries</h3>
  160. <p>Request headers and cookies arrive as Invercargill collections, so the whole Enumerable toolkit applies — count, iterate, filter — with single-field getters alongside:</p>
  161. <figure class="code-plate">
  162. <pre><code>var value = http_context.request.get_header(header_name);
  163. http_context.request.cookies.to_immutable_buffer()
  164. .iterate(kv =&gt; parts.add(@"$(kv.key): $(kv.value)"));
  165. if (http_context.request.cookies.to_immutable_buffer().count() == 0) {
  166. parts.add("(No cookies sent)");
  167. }</code></pre>
  168. <figcaption>From <code>examples/HeadersAndCookies.vala</code>.</figcaption>
  169. </figure>
  170. <p>Form bodies parse asynchronously, with getters that take defaults for absent fields:</p>
  171. <figure class="code-plate">
  172. <pre><code>FormData form_data = yield FormDataParser.parse(
  173. http_context.request, upload_path);
  174. var name = form_data.get_field_or_default("name", "Anonymous");
  175. var email = form_data.get_field_or_default("email", "no-email@example.com");
  176. var country = form_data.get_field_or_default("country", "us");</code></pre>
  177. <figcaption>From <code>examples/FormData.vala</code> — fields and uploaded files arrive together.</figcaption>
  178. </figure>
  179. <h3>Server-sent events</h3>
  180. <p><code>SseEndpoint</code> is the base class for push. A singleton instance holds shared state; <code>new_connection</code> greets each client and <code>broadcast_event</code> reaches every open stream:</p>
  181. <figure class="code-plate">
  182. <pre><code>public class CounterEndpoint : SseEndpoint {
  183. private int counter = 0;
  184. private Mutex counter_mutex = Mutex();
  185. public override uint retry_interval { get { return 2000; } }
  186. public override async void new_connection(HttpContext http_context,
  187. RouteContext route_context, SseStream stream) {
  188. yield stream.send_event(
  189. new SseEvent.with_type("counter", counter.to_string()));
  190. }
  191. public async void increment() {
  192. counter++;
  193. yield broadcast_event(
  194. new SseEvent.with_type("counter", counter.to_string()));
  195. }
  196. }</code></pre>
  197. <figcaption>From <code>examples/SseExample.vala</code> — a mutex-guarded counter broadcast to all tabs.</figcaption>
  198. </figure>
  199. <h3>Building documents</h3>
  200. <p>When a handler must produce HTML rather than JSON, the markup subsystem parses, edits and queries documents without string templates:</p>
  201. <figure class="code-plate">
  202. <pre><code>var doc = new MarkupDocument.from_string(page_html);
  203. var header_card = body.append_child_element("div");
  204. header_card.append_child_with_text("h1", "A heading");
  205. var toggle_form = item_div.append_child_element("form");
  206. var toggle_btn = toggle_form.append_child_element("button");</code></pre>
  207. <figcaption>From <code>examples/DocumentBuilder.vala</code> — elements are built by appending children; XPath selectors find them again.</figcaption>
  208. </figure>
  209. <p><code>MarkupTemplate</code> composes documents, and XPath results come back as lazy Enumerables over the tree.</p>
  210. <h3>Static content and compression</h3>
  211. <p><code>FastResource</code> holds content pre-loaded in memory — the example notes it should be registered as a startup or singleton since it keeps its bytes for the process lifetime:</p>
  212. <figure class="code-plate">
  213. <pre><code>FastResource.from_string(content) // load from a string
  214. FastResource.from_byte_array(bytes) // load from bytes
  215. FastResource(path) // load from the filesystem</code></pre>
  216. <figcaption>From <code>examples/FastResources.vala</code> — the three constructors.</figcaption>
  217. </figure>
  218. <p><code>FilesystemResource</code> serves a directory tree, and the compressor components negotiate gzip, brotli and zstd against what the client accepts — the file-server example announces exactly that:</p>
  219. <figure class="code-plate">
  220. <pre><code>Available compression: gzip, brotli, zstd
  221. Try:
  222. curl http://localhost:$port/
  223. curl --compressed http://localhost:$port/style.css</code></pre>
  224. <figcaption>From <code>examples/FileServer.vala</code>, a complete static server in 141 lines.</figcaption>
  225. </figure>
  226. <h3>Configuration</h3>
  227. <p>Settings live in a <code>web-config.json</code> at the application root, and an environment overlay — <code>web-config.staging.json</code>, selected with <code>ASTRALIS_ENV=staging</code> — merges over it. Inside a handler, the configuration is injected through Inversion and read with typed getters:</p>
  228. <figure class="code-plate">
  229. <pre><code>var config = inject&lt;WebConfig&gt;();
  230. var port = config.get_int("port", 8080);
  231. var app_name = config.get_string("app_name", "Unknown App");
  232. var debug = config.get_bool("debug", false);</code></pre>
  233. <figcaption>From <code>examples/WebConfigExample.vala</code> — every getter carries a default.</figcaption>
  234. </figure>
  235. <h3>Inside the box</h3>
  236. <p>The source tree names its own layers: <strong>Core</strong> holds <code>WebApplication</code>, the pipeline, <code>HttpContext</code> and the <code>WebConfig</code> family; <strong>Server</strong> holds the libmicrohttpd integration and socket monitor; <strong>Components</strong> holds routing and the three compressors; <strong>Endpoints</strong> holds the endpoint contracts and resource servers; <strong>Data</strong> holds form parsing; and <strong>Markup</strong> holds the document builder. The examples directory doubles as a guided tour of each.</p>
  237. <header class="section-head" id="package">
  238. <p class="kicker"><span>Package &amp; source</span></p>
  239. <h2>The ledger</h2>
  240. </header>
  241. <dl class="docs-package">
  242. <div><dt>Version</dt><dd><code>0.1</code> (from <code>MANIFEST.usm</code>)</dd></div>
  243. <div><dt>Licence</dt><dd>LGPL-3.0-or-later — free to run, study, share and improve; the LGPL keeps it free to link from any program.</dd></div>
  244. <div><dt>Package</dt><dd><code>usm install astralis</code></dd></div>
  245. <div><dt>Provides</dt><dd><code>libastralis-0.1.so</code>, <code>astralis-0.1.h</code>, <code>astralis-0.1.vapi</code> + <code>.deps</code>, <code>astralis-0.1.gir</code>, <code>astralis-0.1.typelib</code>, <code>astralis-0.1.pc</code></dd></div>
  246. <div><dt>Needs at runtime</dt><dd>GLib and GObject, libmicrohttpd, json-glib, libxml2, zlib, brotli and zstd encoders, plus the stack beneath: <code>libinvercargill-1.so</code> and <code>libinversion-0.1.so</code>.</dd></div>
  247. <div><dt>Source</dt><dd>The repository <code>Tilo15/astralis</code> on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.</dd></div>
  248. </dl>
  249. <p>The typelib ships as <code>astralis-0.1.typelib</code>, matching the GIR's namespace — an earlier package installed it under a lib-prefixed name that introspection consumers could never resolve; the mismatch is fixed and the manifest now names the file the build actually produces.</p>
  250. <nav class="docs-siblings" aria-label="Built on Astralis">
  251. <p>The libraries that stand on it directly:</p>
  252. <ul>
  253. <li><a href="../statum/">Statum</a></li>
  254. <li><a href="../spry/">Spry</a></li>
  255. </ul>
  256. </nav>
  257. <nav class="docs-pager" aria-label="Project pages">
  258. <a class="docs-pager__link docs-pager__link--prev" href="../invercargill-sql-inversion/">
  259. <span>Previous</span>
  260. <strong>Invercargill-Sql-Inversion</strong>
  261. </a>
  262. <p class="docs-pager__up"><a href="../">All eleven</a></p>
  263. <a class="docs-pager__link docs-pager__link--next" href="../statum/">
  264. <span>Next in the catalogue</span>
  265. <strong>Statum</strong>
  266. </a>
  267. </nav>
  268. </div>
  269. </div>
  270. </section>
  271. </main>
  272. <footer class="site-footer">
  273. <div class="container">
  274. <div class="footer-grid">
  275. <div class="foot-brand">
  276. <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
  277. <p>An operating system for change — kept for self sufficiency, resilience, and software freedom, so regular people can hold the power of general purpose computers in their own hands.</p>
  278. </div>
  279. <nav aria-label="The four freedoms">
  280. <p class="foot-title">The Four Freedoms</p>
  281. <ol class="freedoms">
  282. <li><strong>Run</strong> the software as you wish, for any purpose.</li>
  283. <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
  284. <li><strong>Share</strong> copies so you can help others.</li>
  285. <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
  286. </ol>
  287. </nav>
  288. <nav aria-label="Site">
  289. <p class="foot-title">Site</p>
  290. <ul class="foot-list">
  291. <li><a href="../../">Home</a></li>
  292. <li><a href="../../#news">News</a></li>
  293. <li><a href="../../#download">Download</a></li>
  294. <li><a href="../">Developer</a></li>
  295. </ul>
  296. </nav>
  297. </div>
  298. <p class="colophon">Set in Cinzel and EB Garamond (SIL Open Font License). Astrologue is free software, licensed GPL-3.0-or-later: take it, tend it, pass it on. The libraries are LGPL-3.0-or-later, so they remain free to link.</p>
  299. </div>
  300. </footer>
  301. </body>
  302. </html>