ligo/README.md

Ligo

Ligo is a C++23 networking and transport library. It provides HTTP JSON calls, framed TCP JSON calls, reliable UDP datagrams, TCP/TLS handoff helpers, timeout handling, and std::expected-based error reporting.

Ligo uses Modulus for shared build tooling, Boost.JSON, and OpenSSL integration. Product-specific routes and workflows belong in consuming applications.

UDP reliability and socket lifecycle use separate private DTLS and wire-protocol adapters. Session-drain waits serialize timer registration and notifications on a waiter strand and retain one absolute shutdown deadline, including when notifications arrive before a wait is armed.

Build

Code style is managed by Modulus: run ./modulus.py format or ./modulus.py format --check. The generated Neovim integration uses the same pinned container formatter for C++ and Python, including existing format-on-save toggles. Configure first to prepare tooling; customize tooling.editor.clang_format and tooling.format.exclude in modulus.json, not generated editor files. See the shared Modulus README for the compact layout and no-alias policy.

Configure, build, and test the default target:

python3 modulus.py configure
python3 modulus.py build
python3 modulus.py test

Release verification:

python3 modulus.py configure --target x86_64_gcc12_release
python3 modulus.py build --target x86_64_gcc12_release
python3 modulus.py test --target x86_64_gcc12_release

Create packages:

python3 modulus.py package --all

Configure/build/test can read public packages anonymously from the khodo Conan registry. Publishing requires credentials only on the upload step:

CONAN_USER=<user> \
CONAN_TOKEN=<token> \
LIGO_CONAN_UPLOAD=1 \
MODULUS_ALLOW_PACKAGE_REPLACE=1 \
python3 modulus.py package --all --replace

License

Ligo is released under the MIT License.

HTTP metadata and raw responses

request_context includes lowercase HTTP headers and a query map. Set http::server_options::parse_query = true to route on the path and decode query parameters (+ for spaces, percent escapes); malformed escapes and duplicate keys return a bad-request response. The default remains false, preserving existing exact-target routing. Request cookies retain semicolon separation when repeated.

service_response accepts an HTTP status (default 200) and repeated response headers, for example Set-Cookie. Existing json_response, text_response, and aggregate initialization continue to work. http::request accepts additional headers and an optional raw body. http::client::exchange() returns status, lowercase headers, and an uninterpreted body, including non-2xx and 304 responses; call() retains the original JSON-envelope behavior. Repeated raw response headers are comma-joined in the map; callers needing multiple Set-Cookie values must not treat that combined value as a single cookie. TLS verification and body/time limits apply to both client paths.