| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337 |
- <!doctype html>
- <html lang="en-nz">
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>Astralis — Astrologue Developer</title>
- <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.">
- <meta name="color-scheme" content="light dark">
- <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
- <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
- <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">
- <meta property="og:title" content="Astralis — Astrologue Developer">
- <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.">
- <meta property="og:type" content="website">
- <link rel="stylesheet" href="../../assets/css/style.css">
- </head>
- <body>
- <a class="skip-link" href="#main">Skip to content</a>
- <header class="masthead">
- <div class="container masthead__inner">
- <a class="brand" href="../../">
- <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
- <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
- </a>
- <nav class="site-nav" aria-label="Primary">
- <ul class="site-nav__list">
- <li><a href="../../">Home</a></li>
- <li><a href="../../#news">News</a></li>
- <li><a href="../../#download">Download</a></li>
- <li><a href="../" aria-current="page">Developer</a></li>
- <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
- </ul>
- </nav>
- </div>
- </header>
- <main id="main">
- <nav class="breadcrumb" aria-label="Breadcrumb">
- <div class="container">
- <ol>
- <li><a href="../../">Astrologue</a></li>
- <li><a href="../">Developer</a></li>
- <li aria-current="page">Astralis</li>
- </ol>
- </div>
- </nav>
- <section class="docs-header">
- <div class="container">
- <p class="kicker"><span>Web stack · Where a request lands</span></p>
- <h1>Astralis</h1>
- <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>
- <dl class="docs-facts">
- <div><dt>Version</dt> <dd><code>0.1</code></dd></div>
- <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
- <div><dt>Package</dt> <dd><code>usm install astralis</code></dd></div>
- <div><dt>Language</dt> <dd>Vala</dd></div>
- </dl>
- </div>
- </section>
- <section class="band band--plain" id="docs">
- <div class="container docs-layout">
- <nav class="docs-toc" aria-label="On this page">
- <h2>On this page</h2>
- <ul>
- <li><a href="#overview">Overview</a></li>
- <li><a href="#features">Features</a></li>
- <li><a href="#installation">Installation</a></li>
- <li><a href="#usage">Usage & documentation</a></li>
- <li><a href="#package">Package & source</a></li>
- </ul>
- </nav>
- <div class="docs-prose">
- <header class="section-head" id="overview">
- <p class="kicker"><span>Overview</span></p>
- <h2>The server the stack stands on</h2>
- </header>
- <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>
- <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>
- <figure class="code-plate">
- <pre><code>class HelloEndpoint : Object, Endpoint {
- public async HttpResult handle_request(HttpContext http_context, RouteContext route) throws Error {
- return new HttpStringResult("Hello from Astralis!");
- }
- }
- void main() {
- var application = new WebApplication(8080);
- application.add_endpoint<HelloEndpoint>(new EndpointRoute("/hello"));
- application.run();
- }</code></pre>
- <figcaption>From <code>examples/SimpleApi.vala</code> — a complete server.</figcaption>
- </figure>
- <p>Routes can carry named segments, resolved for you into the route context:</p>
- <figure class="code-plate">
- <pre><code>class HelloNameEndpoint : Object, Endpoint {
- public async HttpResult handle_request(HttpContext http_context, RouteContext route_info) throws Error {
- string? name = null;
- route_info.mapped_parameters.try_get("name", out name);
- return new HttpStringResult(@"Hello, $(name ?? "Unknown")!");
- }
- }
- // registered as:
- application.add_endpoint<HelloNameEndpoint>(new EndpointRoute("/hello/{name}"));</code></pre>
- <figcaption>From <code>examples/PathRouting.vala</code> — the router's named-segment feature.</figcaption>
- </figure>
- <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>
- <header class="section-head" id="features">
- <p class="kicker"><span>Features</span></p>
- <h2>What it hands you</h2>
- </header>
- <ul class="docs-features">
- <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>
- <li><strong>Headers and cookies.</strong> Request headers and cookies as enumerable collections; response headers set fluently on the result value.</li>
- <li><strong>Form data.</strong> An async <code>FormDataParser</code> yields fields and files with typed getters and defaults for absent fields.</li>
- <li><strong>Server-sent events.</strong> <code>SseEndpoint</code> subclasses broadcast to every open stream, greet new connections, and set a retry interval.</li>
- <li><strong>A document builder.</strong> <code>MarkupDocument</code> parses, builds and queries markup with XPath selectors — HTML without a template engine.</li>
- <li><strong>Response compression.</strong> gzip, brotli and zstd compressors with encoding negotiation; <code>FastResource</code> serves pre-loaded content straight from memory.</li>
- <li><strong>Layered configuration.</strong> A <code>web-config.json</code> system with per-environment overlays merged over the base file.</li>
- </ul>
- <header class="section-head" id="installation">
- <p class="kicker"><span>Installation</span></p>
- <h2>Getting the library</h2>
- </header>
- <p>With USM on your machine, one command acquires, builds and installs the library together with its C header, Vala binding and introspection:</p>
- <figure class="code-plate">
- <pre><code>usm install astralis</code></pre>
- <figcaption>Installs from the Astrologue package repository.</figcaption>
- </figure>
- <p>From source, the build lives at the repository root:</p>
- <figure class="code-plate">
- <pre><code>git clone <the astralis repository>
- cd astralis
- meson setup . build
- ninja -C build
- ninja -C build install</code></pre>
- <figcaption>The same meson invocation the package's own build script uses.</figcaption>
- </figure>
- <p>Then compile against it with Vala's usual package mechanism:</p>
- <figure class="code-plate">
- <pre><code>valac --pkg astralis-0.1 my-server.vala</code></pre>
- <figcaption>The installed <code>astralis-0.1.deps</code> resolves the Invercargill and Inversion bindings for you.</figcaption>
- </figure>
- <header class="section-head" id="usage">
- <p class="kicker"><span>Usage & documentation</span></p>
- <h2>Working with requests</h2>
- </header>
- <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>
- <h3>Responses are values</h3>
- <p>An <code>HttpResult</code> carries body, status and headers together, so handlers stay pure and testable — headers chain onto the constructor:</p>
- <figure class="code-plate">
- <pre><code>return new HttpStringResult(user.to_json())
- .set_header("Content-Type", "application/json")
- .set_header("Access-Control-Allow-Origin", "*");</code></pre>
- <figcaption>From <code>examples/JsonApi.vala</code> and <code>PathRouting.vala</code>.</figcaption>
- </figure>
- <p>Failures use the same vocabulary — a helper returns the status you name:</p>
- <figure class="code-plate">
- <pre><code>return error_response(@"Resource with ID $id not found", StatusCode.NOT_FOUND);</code></pre>
- <figcaption>From <code>examples/ErrorHandling.vala</code>.</figcaption>
- </figure>
- <h3>Headers, cookies and queries</h3>
- <p>Request headers and cookies arrive as Invercargill collections, so the whole Enumerable toolkit applies — count, iterate, filter — with single-field getters alongside:</p>
- <figure class="code-plate">
- <pre><code>var value = http_context.request.get_header(header_name);
- http_context.request.cookies.to_immutable_buffer()
- .iterate(kv => parts.add(@"$(kv.key): $(kv.value)"));
- if (http_context.request.cookies.to_immutable_buffer().count() == 0) {
- parts.add("(No cookies sent)");
- }</code></pre>
- <figcaption>From <code>examples/HeadersAndCookies.vala</code>.</figcaption>
- </figure>
- <p>Form bodies parse asynchronously, with getters that take defaults for absent fields:</p>
- <figure class="code-plate">
- <pre><code>FormData form_data = yield FormDataParser.parse(
- http_context.request, upload_path);
- var name = form_data.get_field_or_default("name", "Anonymous");
- var email = form_data.get_field_or_default("email", "no-email@example.com");
- var country = form_data.get_field_or_default("country", "us");</code></pre>
- <figcaption>From <code>examples/FormData.vala</code> — fields and uploaded files arrive together.</figcaption>
- </figure>
- <h3>Server-sent events</h3>
- <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>
- <figure class="code-plate">
- <pre><code>public class CounterEndpoint : SseEndpoint {
- private int counter = 0;
- private Mutex counter_mutex = Mutex();
- public override uint retry_interval { get { return 2000; } }
- public override async void new_connection(HttpContext http_context,
- RouteContext route_context, SseStream stream) {
- yield stream.send_event(
- new SseEvent.with_type("counter", counter.to_string()));
- }
- public async void increment() {
- counter++;
- yield broadcast_event(
- new SseEvent.with_type("counter", counter.to_string()));
- }
- }</code></pre>
- <figcaption>From <code>examples/SseExample.vala</code> — a mutex-guarded counter broadcast to all tabs.</figcaption>
- </figure>
- <h3>Building documents</h3>
- <p>When a handler must produce HTML rather than JSON, the markup subsystem parses, edits and queries documents without string templates:</p>
- <figure class="code-plate">
- <pre><code>var doc = new MarkupDocument.from_string(page_html);
- var header_card = body.append_child_element("div");
- header_card.append_child_with_text("h1", "A heading");
- var toggle_form = item_div.append_child_element("form");
- var toggle_btn = toggle_form.append_child_element("button");</code></pre>
- <figcaption>From <code>examples/DocumentBuilder.vala</code> — elements are built by appending children; XPath selectors find them again.</figcaption>
- </figure>
- <p><code>MarkupTemplate</code> composes documents, and XPath results come back as lazy Enumerables over the tree.</p>
- <h3>Static content and compression</h3>
- <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>
- <figure class="code-plate">
- <pre><code>FastResource.from_string(content) // load from a string
- FastResource.from_byte_array(bytes) // load from bytes
- FastResource(path) // load from the filesystem</code></pre>
- <figcaption>From <code>examples/FastResources.vala</code> — the three constructors.</figcaption>
- </figure>
- <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>
- <figure class="code-plate">
- <pre><code>Available compression: gzip, brotli, zstd
- Try:
- curl http://localhost:$port/
- curl --compressed http://localhost:$port/style.css</code></pre>
- <figcaption>From <code>examples/FileServer.vala</code>, a complete static server in 141 lines.</figcaption>
- </figure>
- <h3>Configuration</h3>
- <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>
- <figure class="code-plate">
- <pre><code>var config = inject<WebConfig>();
- var port = config.get_int("port", 8080);
- var app_name = config.get_string("app_name", "Unknown App");
- var debug = config.get_bool("debug", false);</code></pre>
- <figcaption>From <code>examples/WebConfigExample.vala</code> — every getter carries a default.</figcaption>
- </figure>
- <h3>Inside the box</h3>
- <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>
- <header class="section-head" id="package">
- <p class="kicker"><span>Package & source</span></p>
- <h2>The ledger</h2>
- </header>
- <dl class="docs-package">
- <div><dt>Version</dt><dd><code>0.1</code> (from <code>MANIFEST.usm</code>)</dd></div>
- <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>
- <div><dt>Package</dt><dd><code>usm install astralis</code></dd></div>
- <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>
- <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>
- <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>
- </dl>
- <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>
- <nav class="docs-siblings" aria-label="Built on Astralis">
- <p>The libraries that stand on it directly:</p>
- <ul>
- <li><a href="../statum/">Statum</a></li>
- <li><a href="../spry/">Spry</a></li>
- </ul>
- </nav>
- <nav class="docs-pager" aria-label="Project pages">
- <a class="docs-pager__link docs-pager__link--prev" href="../invercargill-sql-inversion/">
- <span>Previous</span>
- <strong>Invercargill-Sql-Inversion</strong>
- </a>
- <p class="docs-pager__up"><a href="../">All eleven</a></p>
- <a class="docs-pager__link docs-pager__link--next" href="../statum/">
- <span>Next in the catalogue</span>
- <strong>Statum</strong>
- </a>
- </nav>
- </div>
- </div>
- </section>
- </main>
- <footer class="site-footer">
- <div class="container">
- <div class="footer-grid">
- <div class="foot-brand">
- <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
- <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>
- </div>
- <nav aria-label="The four freedoms">
- <p class="foot-title">The Four Freedoms</p>
- <ol class="freedoms">
- <li><strong>Run</strong> the software as you wish, for any purpose.</li>
- <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
- <li><strong>Share</strong> copies so you can help others.</li>
- <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
- </ol>
- </nav>
- <nav aria-label="Site">
- <p class="foot-title">Site</p>
- <ul class="foot-list">
- <li><a href="../../">Home</a></li>
- <li><a href="../../#news">News</a></li>
- <li><a href="../../#download">Download</a></li>
- <li><a href="../">Developer</a></li>
- </ul>
- </nav>
- </div>
- <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>
- </div>
- </footer>
- </body>
- </html>
|