Blyx

Swiftlet

HTTP routing framework · 0.1.0

Dispatch a method and request path against a table of literal and parameterized routes. Return a matched template and the methods a client can use.

Route a book catalog request

Pass PATCH and /books/42?preview=yes to the dispatcher. It selects /books/:id and extracts 42. Try the same method on /books/new, an explicitly read-only resource. The CGI example also serves a health check through an existing web server.

Download the standalone example

Extract the archive and run swiftlet-demo.exe on Windows or ./swiftlet-demo on Linux and macOS. Each archive includes the Blyx source and tests.

Build from source

With Blyx 0.2.1, Rust and a host linker installed, run these commands to edit and rebuild the example.

git clone --depth 1 --branch v0.1.0 https://github.com/Rahulchaube1/blyx-swiftlet.git
cd blyx-swiftlet
blyxc native-run project.blyx

Why this framework exists

A method error and a missing route mean different things to an HTTP client. If their responses share one fallback, clients lose the list of methods a resource accepts. RFC 9110 requires an Allow field on a 405 response. HTTP Semantics, §15.5.6

Install Swiftlet in your editor

Extension RahulChaube.blyx-swiftlet · 0.1.0

The extension includes a runnable Blyx example, function completions and the framework source. For the modular project, extract the starter, open its folder and run blyxc native-run main.blyx with the native toolchain installed.

Create an empty .blyx file, type blyx-swiftlet-demo and accept the completion. Choose Blyx: Run File to run the example.

For an offline installation, choose Extensions: Install from VSIX for Blyx Language first, then for Swiftlet.

Download the companion Blyx Language VSIX

Install with Conda

Create an environment containing Swiftlet 0.1.0, its Blyx source and a runnable example. Run the second command with Blyx 0.2.1, Rust and a host linker installed.

conda create -y --prefix ./blyx-env --override-channels -c https://rahulchaube1.github.io/blyx-packages blyx-swiftlet=0.1.0=0
blyxc native-run ./blyx-env/share/blyx/swiftlet/main.blyx

To use this package in your application, copy share/blyx/swiftlet/vendor/swiftlet from the environment into your project's vendor directory.

Install the full collection with Homebrew or Scoop

Import into a Blyx project

Install Blyx 0.2.1, Rust 1.85 or newer and a host linker. From the directory containing your entry file, clone this tagged release.

git clone --depth 1 --branch v0.1.0 https://github.com/Rahulchaube1/blyx-swiftlet.git vendor/swiftlet

Save this as main.blyx beside vendor and run blyxc native-run main.blyx.

use vendor::swiftlet::swiftlet;

fn main() {
    let methods = sw_enable(sw_enable(0, "GET"), "POST");
    println!(sw_status(true, methods, "GET"));
    println!(sw_status(true, methods, "DELETE"));
    println!(sw_status(false, methods, "GET"));
}

Expected output

200
405
404

API and input requirements

Register a method and an absolute path template separated by one space. GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS use explicit registrations. Literal segments outrank parameters by their count. Equally specific templates use registration order. The matcher strips the query, preserves percent encoding and treats a trailing slash as significant. Hosting, URL decoding and authentication belong to the application.

APIUse
sw_dispatch(routes, method, target)Import router. Returns status text, matched template, and the Allow value in a three-element argument list.
sw_param(template, target, name)Extract an encoded path parameter from a matching path. An absent capture returns an empty string.
sw_enable(mask, method), sw_status(found, mask, method)Build a method set and apply the same status decisions as the router. Start at zero.
sw_allow(mask)Generate the comma-separated list of registered HTTP methods.

Develop and contribute

Open the tagged source to read the implementation and examples. Include the smallest reproducible Blyx program, compiler version and expected result when reporting an issue.