SergeychWorks/lyng
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases 21 Wiki Activity
lyng/notes/networking_handoff_2026-04-02.md

7.3 KiB
Raw Permalink Blame History

Networking Handoff

Date: 2026-04-02 Commit: 5346d15 (Add KMP networking backends)

Scope completed

The lyngio networking work now provides a uniform Lyng-facing API with capability probes and platform-specific implementations.

Implemented modules:

  • lyng.io.http
  • lyng.io.ws
  • lyng.io.net

Current support matrix

HTTP / HTTPS

  • JVM: supported
  • Android: supported
  • JS: supported
  • Linux Native: supported
  • Windows Native (mingwX64): supported
  • Apple Native: compile-verified on this Linux host

WS / WSS

  • JVM: supported
  • Android: supported
  • JS: supported
  • Linux Native: supported
  • Windows Native (mingwX64): supported
  • Apple Native: compile-verified on this Linux host

Raw networking (lyng.io.net)

  • JVM: supported
  • Android: supported
  • JS/Node: supported
  • JS/browser: unsupported by capability probe
  • Linux Native: supported
  • Apple Native: enabled via shared native backend; compile-verified, runtime not yet host-verified
  • Other Native targets: intentionally still unsupported

Important design decisions

  • Ktor is the backend for all currently implemented networking.
  • API is uniform across targets; platform variance is exposed through capability checks such as:
    • Http.isSupported()
    • Ws.isSupported()
    • Net.isSupported()
    • Net.isTcpAvailable()
    • Net.isTcpServerAvailable()
    • Net.isUdpAvailable()
  • Native support was restricted to what matches Ktor client-engine support:
    • Darwin for Apple Native
    • Curl for Linux Native
    • WinHttp for Windows Native
  • Native raw sockets use a shared Ktor socket implementation for Linux and Darwin source sets.
  • Capability probes are enabled on Linux Native and Apple Native; Apple Native is compile-verified but not yet runtime-tested on a macOS host.

Documentation and tests status

Docs updated:

  • docs/lyng.io.http.md
  • docs/lyng.io.ws.md
  • docs/lyng.io.net.md

Verified docs/tests:

  • HTTP/HTTPS docs are covered with extracted markdown tests on JVM.
  • WS/WSS docs are covered with extracted markdown tests on JVM.
  • JS/Node has both engine-level and Lyng-module-level tests for raw networking.

Key implementation files

Shared:

  • lyngio/src/commonMain/kotlin/net/sergeych/lyngio/http/LyngHttp.kt
  • lyngio/src/commonMain/kotlin/net/sergeych/lyng/io/http/LyngHttpModule.kt
  • lyngio/src/commonMain/kotlin/net/sergeych/lyngio/ws/LyngWs.kt
  • lyngio/src/commonMain/kotlin/net/sergeych/lyngio/net/LyngNet.kt
  • lyngio/build.gradle.kts
  • gradle/libs.versions.toml

Platform HTTP:

  • lyngio/src/jvmMain/kotlin/net/sergeych/lyngio/http/PlatformJvm.kt
  • lyngio/src/jsMain/kotlin/net/sergeych/lyngio/http/PlatformJs.kt
  • lyngio/src/androidMain/kotlin/net/sergeych/lyngio/http/PlatformAndroid.kt
  • lyngio/src/darwinMain/kotlin/net/sergeych/lyngio/http/PlatformDarwin.kt
  • lyngio/src/linuxMain/kotlin/net/sergeych/lyngio/http/PlatformLinux.kt
  • lyngio/src/mingwMain/kotlin/net/sergeych/lyngio/http/PlatformMingw.kt

Platform WS:

  • lyngio/src/jvmMain/kotlin/net/sergeych/lyngio/ws/PlatformJvm.kt
  • lyngio/src/jsMain/kotlin/net/sergeych/lyngio/ws/PlatformJs.kt
  • lyngio/src/androidMain/kotlin/net/sergeych/lyngio/ws/PlatformAndroid.kt
  • lyngio/src/darwinMain/kotlin/net/sergeych/lyngio/ws/PlatformDarwin.kt
  • lyngio/src/linuxMain/kotlin/net/sergeych/lyngio/ws/PlatformLinux.kt
  • lyngio/src/mingwMain/kotlin/net/sergeych/lyngio/ws/PlatformMingw.kt

Platform raw net:

  • lyngio/src/jvmMain/kotlin/net/sergeych/lyngio/net/PlatformJvm.kt
  • lyngio/src/jsMain/kotlin/net/sergeych/lyngio/net/PlatformJs.kt
  • lyngio/src/androidMain/kotlin/net/sergeych/lyngio/net/PlatformAndroid.kt
  • lyngio/src/nativeMain/kotlin/net/sergeych/lyngio/net/NativeKtorNetEngine.kt
  • lyngio/src/linuxMain/kotlin/net/sergeych/lyngio/net/PlatformLinux.kt
  • lyngio/src/darwinMain/kotlin/net/sergeych/lyngio/net/PlatformDarwin.kt
  • lyngio/src/mingwMain/kotlin/net/sergeych/lyngio/net/PlatformMingw.kt

JS tests:

  • lyngio/src/jsTest/kotlin/net/sergeych/lyngio/PlatformCapabilityJsTest.kt
  • lyngio/src/jsTest/kotlin/net/sergeych/lyngio/NetJsNodeTest.kt
  • lyngio/src/jsTest/kotlin/net/sergeych/lyng/io/net/LyngNetModuleJsNodeTest.kt

JVM tests:

  • lyngio/src/jvmTest/kotlin/LyngioBookTest.kt
  • lyngio/src/jvmTest/kotlin/net/sergeych/lyng/io/http/LyngHttpModuleTest.kt
  • lyngio/src/jvmTest/kotlin/net/sergeych/lyng/io/ws/LyngWsModuleTest.kt
  • lyngio/src/jvmTest/kotlin/net/sergeych/lyng/io/net/LyngNetModuleTest.kt

Linux Native tests:

  • lyngio/src/linuxTest/kotlin/net/sergeych/lyngio/net/NetLinuxNativeTest.kt

Verification already run

JVM / docs:

  • ./gradlew :lyngio:jvmTest --tests LyngioBookTest
  • ./gradlew :lyngio:jvmTest --tests net.sergeych.lyng.io.http.LyngHttpModuleTest
  • ./gradlew :lyngio:jvmTest --tests net.sergeych.lyng.io.ws.LyngWsModuleTest
  • ./gradlew :lyngio:jvmTest --tests net.sergeych.lyng.io.net.LyngNetModuleTest

JS:

  • ./gradlew :lyngio:compileKotlinJs
  • ./gradlew :lyngio:compileTestKotlinJs
  • ./gradlew :lyngio:jsNodeTest
  • ./gradlew kotlinUpgradeYarnLock

Android:

  • ./gradlew :lyngio:compileDebugKotlinAndroid
  • ./gradlew :lyngio:compileReleaseKotlinAndroid

Native:

  • ./gradlew :lyngio:compileKotlinLinuxX64
  • ./gradlew :lyngio:compileKotlinLinuxArm64
  • ./gradlew :lyngio:compileKotlinMingwX64
  • ./gradlew :lyngio:compileKotlinIosX64
  • ./gradlew :lyngio:compileKotlinIosArm64
  • ./gradlew :lyngio:compileKotlinIosSimulatorArm64
  • ./gradlew :lyngio:compileKotlinMacosArm64
  • ./gradlew :lyngio:compileTestKotlinLinuxX64
  • ./gradlew :lyngio:compileTestKotlinLinuxArm64
  • ./gradlew :lyngio:linkDebugTestLinuxX64
  • ./gradlew :lyngio:linuxX64Test
  • ./gradlew :lyngio:linuxX64Test --tests net.sergeych.lyngio.net.NetLinuxNativeTest
  • ./gradlew :lyngio:linuxX64Test --tests net.sergeych.lyngio.net.NetLinuxNativeTest.testLinuxNativeTcpAndUdpLoopback
  • ./lyngio/build/bin/linuxX64/debugTest/test.kexe --ktest_filter='net.sergeych.lyngio.net.NetLinuxNativeTest.*'

Known intentional gaps

  • Native raw sockets are enabled on Linux Native and Apple Native.
  • Apple Native raw networking is enabled based on shared-backend compile verification; runtime verification on macOS is still pending.
  • No Android device/instrumented runtime tests were added; only compile verification was done.

Worktree state after commit

Current HEAD:

  • 5346d15 Add KMP networking backends

Unrelated remaining change:

  • examples/tetris_console.lyng

That file was not touched by the networking work and was intentionally left out of the commit.

Recommended next steps

  1. Add Native raw socket support only per target that compiles and passes a smoke test.
  2. Keep capability probes false on non-Linux Native targets until each raw-socket backend is proven.
  3. If Apple Native work continues, compile Darwin targets on a macOS host before claiming support.
  4. Run a macOS-hosted runtime smoke test when available to verify the already-enabled Darwin backend.
  5. Optionally add Android runtime tests later; compile-only verification exists now.

Suggested first task for the next chat

Continue Native raw lyng.io.net incrementally from the verified Linux baseline:

  • keep Linux Native enabled
  • keep Apple Native enabled unless runtime verification disproves the shared-backend assumption
  • keep other Native targets capability-gated off until compiled and smoke-tested
  • use only ktor-network support that actually compiles
  • do not change the Lyng-facing API