Refactor KMP networking backends

2026-04-02 20:04:25 +03:00
1 parent d0aaa2c256
commit cd7e001f41
@@ -0,0 +1,205 @@
+# 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