lyng/docs/lyngio.md

lyngio — Extended I/O and System Library for Lyng

lyngio is a separate library that extends the Lyng core (lynglib) with powerful, multiplatform, and secure I/O capabilities.

Important native networking limit: lyng.io.net on current native targets is suitable for modest workloads, local tools, and test servers, but not yet for high-connection-count production servers. For serious HTTP/TCP serving, prefer the JVM target for now. If native high-concurrency networking matters for your use case, please open or upvote an issue at https://github.com/sergeych/lyng/issues.

Why a separate module?

1. Security: I/O and process execution are sensitive operations. By keeping them in a separate module, we ensure that the Lyng core remains 100% safe by default. You only enable what you explicitly need.
2. Footprint: Not every script needs filesystem or process access. Keeping these as a separate module helps minimize the dependency footprint for small embedded projects.
3. Control: lyngio provides fine-grained security policies (FsAccessPolicy, ProcessAccessPolicy, ConsoleAccessPolicy) that allow you to control exactly what a script can do.

Included Modules

• lyng.io.fs: Async filesystem access. Provides the Path class for file/directory operations, streaming, and globbing.
• lyng.io.process: External process execution and shell commands. Provides Process, RunningProcess, and Platform information.
• lyng.io.console: Rich console/TTY access. Provides Console capability detection, geometry, output, and iterable events.
• lyng.io.http: HTTP/HTTPS client access. Provides Http, HttpRequest, HttpResponse, and HttpHeaders.
• lyng.io.ws: WebSocket client access. Provides Ws, WsSession, and WsMessage.
• lyng.io.net: Transport networking. Provides Net, TcpSocket, TcpServer, UdpSocket, and SocketAddress.

---

Quick Start: Embedding lyngio

1. Add Dependencies (Gradle)

repositories {
    maven("https://gitea.sergeych.net/api/packages/SergeychWorks/maven")
}

dependencies {
    // Both are required for full I/O support
    implementation("net.sergeych:lynglib:0.0.1-SNAPSHOT")
    implementation("net.sergeych:lyngio:0.0.1-SNAPSHOT")
}

2. Initialize in Kotlin (JVM or Native)

To use lyngio modules in your scripts, you must install them into your Lyng scope and provide a security policy.

import net.sergeych.lyng.EvalSession
import net.sergeych.lyng.io.fs.createFs
import net.sergeych.lyng.io.process.createProcessModule
import net.sergeych.lyng.io.console.createConsoleModule
import net.sergeych.lyng.io.http.createHttpModule
import net.sergeych.lyng.io.net.createNetModule
import net.sergeych.lyng.io.ws.createWsModule
import net.sergeych.lyngio.fs.security.PermitAllAccessPolicy
import net.sergeych.lyngio.process.security.PermitAllProcessAccessPolicy
import net.sergeych.lyngio.console.security.PermitAllConsoleAccessPolicy
import net.sergeych.lyngio.http.security.PermitAllHttpAccessPolicy
import net.sergeych.lyngio.net.security.PermitAllNetAccessPolicy
import net.sergeych.lyngio.ws.security.PermitAllWsAccessPolicy

suspend fun runMyScript() {
    val session = EvalSession()
    val scope = session.getScope()
    
    // Install modules with policies
    createFs(PermitAllAccessPolicy, scope)
    createProcessModule(PermitAllProcessAccessPolicy, scope)
    createConsoleModule(PermitAllConsoleAccessPolicy, scope)
    createHttpModule(PermitAllHttpAccessPolicy, scope)
    createNetModule(PermitAllNetAccessPolicy, scope)
    createWsModule(PermitAllWsAccessPolicy, scope)
    
    // Now scripts can import them
    session.eval("""
        import lyng.io.fs
        import lyng.io.process
        import lyng.io.console
        import lyng.io.http
        import lyng.io.net
        import lyng.io.ws
        
        println("Working dir: " + Path(".").readUtf8())
        println("OS: " + Platform.details().name)
        println("TTY: " + Console.isTty())
        println("HTTP available: " + Http.isSupported())
        println("TCP available: " + Net.isTcpAvailable())
        println("WS available: " + Ws.isSupported())
    """)
}

---

Security Tools

lyngio is built with a "Secure by Default" philosophy. Every I/O or process operation is checked against a policy.

• Filesystem Security: Implement FsAccessPolicy to restrict access to specific paths or operations (e.g., read-only access to a sandbox directory).
• Process Security: Implement ProcessAccessPolicy to restrict which executables can be run or to disable shell execution entirely.
• Console Security: Implement ConsoleAccessPolicy to control output writes, event reads, and raw mode switching.
• HTTP Security: Implement HttpAccessPolicy to restrict which requests scripts may send.
• Transport Security: Implement NetAccessPolicy to restrict DNS resolution and TCP/UDP socket operations.
• WebSocket Security: Implement WsAccessPolicy to restrict websocket connects and message flow.

For more details, see the specific module documentation:

• Filesystem Security Details
• Process Security Details
• Console Module Details
• HTTP Module Details
• Transport Networking Details
• WebSocket Module Details

---

Platform Support Overview

Platform	lyng.io.fs	lyng.io.process	lyng.io.console	lyng.io.http	lyng.io.ws	lyng.io.net
JVM	✅	✅	✅	✅	✅	✅
Linux Native	✅	✅	✅	✅	✅	✅
Apple Native	✅	✅	✅	✅	✅	⚠️
Windows Native	✅	❌	✅	✅	✅	❌
Android	✅	❌	⚠️	✅	✅	✅
JS / Node	✅	❌	⚠️	✅	✅	✅
JS / Browser	✅ (in-memory)	❌	⚠️	✅	✅	❌
Wasm	✅ (in-memory)	❌	⚠️	❌	❌	❌

Legend:

• ✅ supported
• ⚠️ available but environment-dependent or not fully host-verified yet
• ❌ unsupported