50 Modules

Every module is a shared library (.so) that exports 4 functions. Each does one thing. Together, they compose into any system.

Infrastructure

`mod_cli`

CLI over UNIX socket. Full line editing with arrow keys, history (64 commands), tab completion. Per-client state: current path, auth session. Connect via portal -r or portalctl.

v0.1.0 · Infrastructure

`mod_web`

HTTP/HTTPS REST API gateway. Maps HTTP methods to Portal methods. Auto-generates API index from live paths. Three auth methods: API Key, Bearer Token, HTTP Basic Auth. CORS enabled. Configurable bind address.

v0.8.0 · Infrastructure

`mod_node`

Node federation over TCP/TLS. Connects Portal instances into a distributed network. Worker thread pool per peer. Wire protocol PORTAL02. Hub routing for NAT traversal. Federation key auth (SHA-256). Auto-reconnect.

v0.4.0 · Infrastructure

`mod_ssh`

SSH server for remote CLI access. Any standard SSH client connects and gets the full interactive CLI. Uses Portal's own user/password system.

v1.0.0 · Infrastructure

`mod_config_sqlite`

SQLite storage backend. Transparent — registers as core storage provider. Auto-creates tables. WAL mode for concurrency.

v0.6.0 · Infrastructure

`mod_config_psql`

PostgreSQL storage backend. Transparent — registers as core storage provider. Auto-creates database and tables. Parameterized queries (SQL injection safe).

v0.5.0 · Infrastructure

Data & Messaging

`mod_cache`

In-memory key-value cache with TTL expiry. Thread-safe hash table. CLI: cache set/get/del/keys/flush. Emits events on changes.

v1.0.0 · Data

`mod_kv`

Persistent key-value store. File-backed, survives restarts. Each key stored as a file. Thread-safe, path traversal protection.

v1.0.0 · Data

`mod_shm`

Named POSIX shared memory regions. Create, read, write, destroy. Emits events on create.

v1.0.0 · Data

`mod_queue`

Thread-safe FIFO message queues. Push, pop, peek. Emits events on push/pop.

v1.0.0 · Data

`mod_websocket`

WebSocket server for real-time push to browsers. Clients send path names, receive responses.

v1.0.0 · Data

`mod_mqtt`

Lightweight MQTT broker. Clients publish/subscribe to topics. MQTT publish maps to Portal event emit.

v1.0.0 · Data

`mod_email`

SMTP email sender. Configurable server and auth. Emits event on send.

v1.0.0 · Data

`mod_file`

Sandboxed filesystem operations. Read, write, list, delete, info, mkdir. Path traversal protection. Configurable max file size and base directory.

v1.0.0 · Data

Logic & Scripting

`mod_logic`

Application logic framework. Language-agnostic orchestrator. Manages scripts, routes, event handlers. Delegates execution to language engines via path messages.

v1.0.0 · Logic

`mod_logic_lua`

Lua 5.4 embedded interpreter. In-process, zero-copy. API: portal.get(), portal.call(), portal.set(), portal.route(), portal.on(), portal.log().

v1.0.0 · Logic

`mod_logic_python`

Python 3 in forked subprocess. JSON pipe bridge. import portal, same API. Avoids CPython signal conflicts with libev.

v1.1.0 · Logic

`mod_logic_c`

C scripting engine. Compiles .c files with gcc at load time, produces .so, dlopens. Native speed with hot-reload. Uses portal.h directly.

v1.0.0 · Logic

`mod_logic_pascal`

Free Pascal scripting engine. Compiles .pas files with fpc. Exports app_load, app_handle, app_unload with cdecl convention.

v1.0.0 · Logic

System & Monitoring

`mod_metrics`

Real-time system metrics from /proc: CPU usage, memory, disk space, load average, uptime.

v1.0.0 · System

`mod_health`

Liveness/readiness probes. Kubernetes/Docker compatible. CLI: health, uptime.

v1.0.0 · System

`mod_sysinfo`

System information: hostname, OS, kernel, CPU count, network interfaces, environment variables.

v1.0.0 · System

`mod_process`

Sandboxed system command execution via popen. Configurable whitelist. Rejects dangerous patterns. Admin-only.

v1.0.0 · System

`mod_log`

Access Portal instance logs via path system. Tail, search by pattern, list log files, rotate.

v1.0.0 · System

`mod_audit`

Circular buffer audit log. Subscribes to /events/* automatically. Searchable by user or path. Optional file persistence.

v1.0.0 · System

`mod_cron`

Interval-based job scheduler. Jobs trigger path calls. CLI: cron add/remove/trigger/jobs. Emits events.

v1.0.0 · System

`mod_scheduler`

One-shot delayed task scheduler. Tasks execute once at a specific time. Complement to mod_cron intervals.

v1.0.0 · System

`mod_worker`

Named thread pools for background task execution. Configurable thread counts, submit jobs, track completion/failure stats.

v1.0.0 · System

`mod_backup`

Create tar.gz backups of instance config and data. Restore from archives. List and delete backups. Admin-only.

v1.0.0 · System

Network & Integration

`mod_proxy`

HTTP reverse proxy with named routes. Map portal paths to upstream servers. Error tracking per route.

v1.0.0 · Network

`mod_dns`

DNS utility: resolve hostnames (A/AAAA), reverse lookup (PTR), full lookup with aliases.

v1.0.0 · Network

`mod_http_client`

Outbound HTTP/HTTPS requests. CLI: curl <url>. Used by other modules for external API calls.

v1.0.0 · Network

`mod_webhook`

v1.0.0 · Network

`mod_api_gateway`

External API routing with response caching (mod_cache), rate limiting (mod_firewall), auth header passthrough, configurable timeout.

v1.0.0 · Network

`mod_tunnel`

Raw TCP port forwarding through federation connections. Zero-overhead byte relay using select(). Enables SSH, HTTP, or any TCP service across NAT.

v1.0.0 · Network

`mod_acme`

ACME/Let's Encrypt certificate automation. Auto-detects certbot or acme.sh, falls back to self-signed. Request, check expiry, auto-renew.

v1.0.0 · Network

Security

`mod_firewall`

Source-based firewall: explicit allow/deny rules + automatic rate limiting. Configurable requests per window. Thread-safe.

v1.0.0 · Security

`mod_crypto`

SHA-256 hash, MD5 hash, Base64 encode/decode, hex encode/decode. All zero-dependency (embedded implementations).

v1.0.0 · Security

`mod_ldap`

Authenticate users against LDAP/Active Directory servers. Simple LDAP bind protocol (BER encoded). Connection test function.

v1.0.0 · Security

`mod_validator`

Validate: email, IPv4/IPv6, URL, JSON, number ranges, POSIX regex, hostnames. Returns valid/invalid with details.

v1.0.0 · Security

IoT

`mod_iot`

Complete IoT device management. Discovery (ARP scan + MAC identification + KLAP probe), control (on/off/toggle), monitoring. Drivers: MQTT (Tasmota/Shelly/Sonoff), HTTP (Shelly/Hue), Tapo KLAP v2 (TP-Link plugs, bulbs, hub, vacuum), GPIO.

v1.0.0 · IoT

`mod_gpio`

GPIO pin control via Linux sysfs. Export/unexport pins, set direction, read/write values. Simulation mode on non-GPIO hardware.

v1.0.0 · IoT

Compression

`mod_xz`

XZ/LZMA compression via liblzma. Configurable level (0-9). Buffer-based API.

v1.0.0 · System

`mod_gzip`

Gzip compression via zlib. Configurable level (1-9). Proper gzip header format.

v1.0.0 · System

Rendering

`mod_template`

Template rendering with {{variable}} syntax. Load from files, cache in memory, render with substitution.

v1.0.0 · System

`mod_admin`

Web administration dashboard (SPA). Dashboard with metrics, module browser, node federation view, user/group management, config editor, audit log viewer.

v2.0.0 · System

Examples

`mod_hello`

Minimal example module demonstrating the 4-export interface. Template for new modules.

v1.0.0 · Example

`mod_myapp`

Example application with counter, events, and ACL demonstration.

v1.0.0 · Example

Module Interface

Every module exports exactly 4 symbols:

portal_module_info_t *portal_module_info(void);     // descriptor
int portal_module_load(portal_core_t *core);         // initialize
int portal_module_unload(portal_core_t *core);       // cleanup
int portal_module_handle(portal_core_t *core,        // handle messages
                         const portal_msg_t *msg,
                         portal_resp_t *resp);

Runtime Management

portal:/> module list              # all loaded modules
portal:/> module load mymod        # hot-load
portal:/> module unload mymod      # safe unload (waits for active calls)
portal:/> module reload mymod      # atomic unload + load

Modules never call each other directly. All communication goes through the core via paths. Module A sends a message to /modB/resource. The core routes it, checks ACL, and delivers the response. If Module B is unloaded, Module A gets 503 UNAVAILABLE.