libs

ridgun-libs

Pure-Ridgun (v0.9.16) standard and system library suite. Every lib compiles to portable Ridgun library bundles (.rglib / .rgc) and native ELF64 shared objects (.so) using stable and ridgunc with zero C dependencies or libc.

Overview

ridgun-libs provides 32 foundational libs across 28 domains for Ridgun applications, CLI utilities (unix-tools), and network servers (Solstice):

Requirements & Toolchain

• Compiler: ridgunc (v0.9.5+, pure-Ridgun self-hosted ELF64 compiler)
• Build & Test Runner: stable (build.rg)
• Supported Targets: Linux (X86_64, Arm64) with cross-platform PAL dispatch (Linux | MacOS | Windows)

Quick Start: Build, Check, Test & Bundle

Run all commands from the repository root:

# 1. Format all source and test files using canonical Ridgun tabular alignment
stable format

# 2. Type-check and statically analyze all 32 libs
stable check

# 3. Run all 30 automated test suites in src/test/ridgun/
stable test

# 4. Build all .rglib, .rgc, and native ELF64 .so bundles into target/ and target/bundles/
stable bundle

Expected output from stable check and stable test:

• Checked 32 lib(s) — 0 errors.
• Passed 30/30 test suite(s) — 0 failures.

Library Reference & Usage Examples

1. socket — Networking, IPC & Kernel Sockets (RGF-001)

Provides both an immutable functional Socket state machine (sock_tcp, sock_udp, sock_unix_stream, length-prefixed frames, line I/O, CIDR matching) and the descriptor-based RGF-001 TCP/Unix socket API:

import socket

fn :: run echo step => ()
      run echo step =
        -- Listen on an ephemeral loopback TCP port (port = 0)
        l_res = sys tcp listen "127.0.0.1" 0 16
        lfd   = sock fd l_res
        port  = sys local port lfd

        -- Connect client, accept peer, and exchange raw binary or text frames
        c_res = sys tcp connect "127.0.0.1" port 1000
        cfd   = sock fd c_res
        a_res = sys accept lfd 1000
        sfd   = sock accept fd a_res
        _     = sys send cfd "ping" 1000
        r_res = sys recv sfd 64 1000
        msg   = sock recv data r_res
        _     = sys shutdown write cfd
        _     = sys_close cfd
        _     = sys_close sfd
        _     = sys_close lfd
        echo msg

RGF-001 Error Status Codes:

2. crypto & argon2id — Cryptography, Argon2id & ChaCha20-Poly1305 AEAD

Provides raw byte manipulation (0..255), 32-bit unsigned bitwise operations (band, bor, bxor, shl, shr), SHA-256, HMAC-SHA-256, PBKDF2-HMAC-SHA-256, RFC 9106 Argon2id PHC hashing, and RFC 8439 ChaCha20-Poly1305 AEAD:

import crypto

fn :: demo crypto => ()
      demo crypto =
        -- 1. SHA-256, HMAC-SHA-256 & PBKDF2-HMAC-SHA-256
        digest_hex = sha256 hex "abc"
        mac_bytes  = hmac sha256 "secret-key" "message"
        dk32       = pbkdf2 hmac sha256 "password" "salt" 1000 32

        -- 2. RFC 9106 Argon2id PHC Password Hashing (OWASP m=19456 KiB, t=2, p=1)
        phc = argon2id hash "correct horse battery staple" "0123456789abcdef" 19456 2 1
        ok  = argon2id verify "correct horse battery staple" phc

        -- 3. RFC 8439 ChaCha20-Poly1305 Authenticated Encryption (AEAD)
        key32       = sha256 bytes "32-byte-session-key-material"
        nonce12     = "0123456789ab"
        sealed      = aead seal key32 nonce12 "header-aad" "confidential payload"
        (rc, plain) = aead open key32 nonce12 "header-aad" sealed
        echo ok rc plain

3. posix & io — Platform Abstraction Layer (PAL) & Timeout I/O

Uses Ridgun v0.9.5 compile-time target ADTs (sys os => SysOs, sys arch => SysArch) and lexical deadline quotas (with timeout wait_ms do):

import posix
import io

fn :: demo io => ()
      demo io =
        -- Non-blocking descriptor read bounded by a 250 ms lexical timeout quota
        res = io read with timeout 0 4096 250
        _   = echo (format io error (IoTimeout "read" 250))
        ()

4. math, list, codec, str & cli — Standard Data & CLI Libraries

import math
import list
import codec
import cli

fn :: demo std => ()
      demo std =
        -- math: modular exponentiation, modular inverse, and custom operator
        m_pow   = math mod pow 3 200 97
        m_inv   = math mod inv 3 11
        clamped = clamp 150 between 0 and 100

        -- list: O(N log N) mergesort and associative key-value map
        sorted  = list sort [42, 7, 19, 0, (0 - 5)]
        cfg     = kv put (kv put (kv empty) "host" "127.0.0.1") "port" "8080"

        -- codec: Base64, URL query strings, and lightweight JSON
        b64     = base64 encode "foobar"
        doc     = json object [("host", json quote (kv get cfg "host")), ("port", json int 8080)]
        port    = json get int doc "port" 80

        -- cli: flag and option extraction
        args    = ["serve", "-la", "--port=9090", "--", "app.rg"]
        has_all = cli has flag args "--all" "-a"
        cli_prt = cli get int opt args "--port" "-p" port
        echo m_pow m_inv clamped sorted b64 has_all cli_prt

5. path, time, log, glob, uuid & http — System, Web & Observability Libraries

import path
import time
import log
import glob
import uuid
import http

fn :: demo web sys => ()
      demo web sys =
        -- path: lexical cleaning, extension replacement, and traversal confinement
        clean_p = path replace ext (path join "/srv/www" "assets/../index.html") ".rg"
        safe_ok = path is safe subpath "/srv/www" "assets/logo.png"

        -- time: ISO-8601 UTC timestamps, human durations, and exponential backoff
        iso_ts  = time format iso8601 1792664400
        dur_str = time format duration ms 3661005
        wait_ms = time backoff ms 3 100 5000

        -- log: NDJSON structured logging with automatic secret redaction
        ndjson  = log format json "INFO" "request handled" [("req_id", uuid v4), ("api_key", "sk_live_999")]

        -- glob & uuid: wildcard filtering and CRC-32 checksums
        rg_list = glob filter "*.rg" ["main.rg", "README.md", "http.rg"]
        chk_crc = crc32 "123456789"

        -- http: RFC 3986 URI decomposition & HTTP/1.1 wire request construction
        host    = uri host "https://api.example.com:8443/v1/users?active=1"
        raw_req = http build request "GET" "/v1/users" [("Host", host)] ""
        echo clean_p safe_ok iso_ts dur_str wait_ms ndjson rg_list chk_crc raw_req

Project Layout & Documentation (AIX)

All requirements, API contracts, data models, architectural decisions, security audits, and test specifications live under docs/ and are validated by aix docs validate:

Verify documentation and traceability at any time:

aix docs coverage && aix docs validate

License

See LICENSE for license details.