🚀 Add GraphQL subscriptions support for wasmJs target (#6637)

* Initial working implementation of WebSocket engine for wasmJs platform

* Improve WebSocket engine for wasmJs: refine exceptions, adjust helper functions, clarify binary data handling constraints, and add comprehensive documentation

* refactor wasmJs websocket engine to handle binary data properly using ArrayBufferView and Uint8Array, improving binary message support and documentation

* Only add wasm support to the `.websocket` package

* Factor String.toWebSocketUrl()

* Escape the stack frame

* Add a test for JS websockets

* Simplify code and increase timeout

* Increase test runner timeout as well

* unbreak production wasm

* unbreak production wasm

---------

Co-authored-by: Martin Bonnin <[email protected]>

Author: aryapreetam

.gitignore

@@ -45,3 +45,4 @@ docs.json
 
 # Local Netlify folder
 .netlify
+/ref-docs/

build-logic/build.gradle.kts

@@ -19,6 +19,9 @@ dependencies {
   compileOnly(libs.dgp)
 
   implementation(libs.okhttp)
+  implementation(libs.ktor.server.netty)
+  implementation(libs.ktor.server.cors)
+  implementation(libs.ktor.server.websockets)
 
   implementation(libs.kotlinx.benchmark)
   implementation(libs.dokka)

build-logic/gradle.properties

@@ -5,3 +5,4 @@ org.gradle.jvmargs=-Xmx8g
 org.gradle.caching=true
 # Enable the configuration cache
 # org.gradle.unsafe.configuration-cache=true
+ksp.allow.all.target.configuration=false

build-logic/src/main/kotlin/Mpp.kt

@@ -1,4 +1,3 @@
-
 import org.gradle.api.Action
 import org.gradle.api.Project
 import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
@@ -34,42 +33,27 @@ private val enableJs = System.getenv("APOLLO_JVM_ONLY")?.toBoolean()?.not() ?: t
 private val enableApple = System.getenv("APOLLO_JVM_ONLY")?.toBoolean()?.not() ?: true
 
 
-fun Project.configureMpp(
+fun defaultTargets(
     withJvm: Boolean,
     withJs: Boolean,
     withLinux: Boolean,
     withAndroid: Boolean,
     withWasm: Boolean,
     appleTargets: Collection<String>,
-    browserTest: Boolean,
-) {
-  val kotlinExtension = extensions.findByName("kotlin") as? KotlinMultiplatformExtension
-  check(kotlinExtension != null) {
-    "No multiplatform extension found"
-  }
-  kotlinExtension.apply {
+): KotlinMultiplatformExtension.() -> Unit {
+  return {
     if (withJvm) {
       jvm()
     }
 
     if (enableJs && withJs) {
       js(IR) {
-        if (browserTest) {
-          browser {
-            testTask(Action {
-              useKarma {
-                useChromeHeadless()
-              }
-            })
-          }
-        } else {
-          nodejs {
-            testTask(Action {
-              useMocha {
-                // Override default 2s timeout
-                timeout = "120s"
-              }
-            })
+        nodejs {
+          testTask {
+            useMocha {
+              // Override default 2s timeout
+              timeout = "120s"
+            }
           }
         }
       }
@@ -108,8 +92,6 @@ fun Project.configureMpp(
         }
       }
     }
-
-    configureSourceSetGraph()
   }
 }
 
@@ -143,7 +125,7 @@ fun Project.configureMpp(
  * ```
  */
 @OptIn(ExperimentalKotlinGradlePluginApi::class)
-private fun KotlinMultiplatformExtension.configureSourceSetGraph() {
+internal fun KotlinMultiplatformExtension.configureSourceSetGraph() {
   applyDefaultHierarchyTemplate {
     group("common") {
       group("filesystem") {

build-logic/src/main/kotlin/api.kt

@@ -27,11 +27,7 @@ fun Project.version(): String {
 fun Project.apolloLibrary(
     namespace: String,
     jvmTarget: Int? = null,
-    withJs: Boolean = true,
-    withLinux: Boolean = true,
-    withApple: Boolean = true,
-    withJvm: Boolean = true,
-    withWasm: Boolean = true,
+    defaultTargets: (KotlinMultiplatformExtension.() -> Unit),
     androidOptions: AndroidOptions? = null,
     publish: Boolean = true,
     kotlinCompilerOptions: KotlinCompilerOptions = KotlinCompilerOptions(),
@@ -69,15 +65,11 @@ fun Project.apolloLibrary(
   }
 
   if (extensions.findByName("kotlin") is KotlinMultiplatformExtension) {
-    configureMpp(
-        withJvm = withJvm,
-        withJs = withJs,
-        browserTest = false,
-        withLinux = withLinux,
-        appleTargets = if (!withApple) emptySet() else allAppleTargets,
-        withAndroid = extensions.findByName("android") != null,
-        withWasm = withWasm
-    )
+    val kotlinExtension = extensions.findByName("kotlin") as? KotlinMultiplatformExtension
+    if (kotlinExtension != null) {
+      kotlinExtension.defaultTargets()
+      kotlinExtension.configureSourceSetGraph()
+    }
   }
 
   configureTesting()
@@ -105,12 +97,52 @@ fun Project.apolloLibrary(
   }
 }
 
+fun Project.apolloLibrary(
+    namespace: String,
+    jvmTarget: Int? = null,
+    withJs: Boolean = true,
+    withLinux: Boolean = true,
+    withApple: Boolean = true,
+    withJvm: Boolean = true,
+    withWasm: Boolean = true,
+    androidOptions: AndroidOptions? = null,
+    publish: Boolean = true,
+    kotlinCompilerOptions: KotlinCompilerOptions = KotlinCompilerOptions(),
+) {
+  val defaultTargets = defaultTargets(
+      withJvm = withJvm,
+      withJs = withJs,
+      withLinux = withLinux,
+      appleTargets = if (!withApple) emptySet() else allAppleTargets,
+      withAndroid = androidOptions != null,
+      withWasm = withWasm
+  )
+
+  apolloLibrary(
+      namespace,
+      jvmTarget,
+      defaultTargets,
+      androidOptions,
+      publish,
+      kotlinCompilerOptions
+  )
+}
+
 fun Project.apolloTest(
     withJs: Boolean = true,
     withJvm: Boolean = true,
     appleTargets: Set<String> = setOf(hostTarget),
-    browserTest: Boolean = false,
     kotlinCompilerOptions: KotlinCompilerOptions = KotlinCompilerOptions(),
+) {
+  apolloTest(
+      kotlinCompilerOptions,
+      defaultTargets(withJvm = withJvm, withJs = withJs, withLinux = false, withAndroid = false, withWasm = false, appleTargets = appleTargets),
+  )
+}
+
+fun Project.apolloTest(
+    kotlinCompilerOptions: KotlinCompilerOptions = KotlinCompilerOptions(),
+    block: KotlinMultiplatformExtension.() -> Unit,
 ) {
   commonSetup()
   configureJavaAndKotlinCompilers(
@@ -123,16 +155,10 @@ fun Project.apolloTest(
       )
   )
 
-  if (extensions.findByName("kotlin") is KotlinMultiplatformExtension) {
-    configureMpp(
-        withJvm = withJvm,
-        withJs = withJs,
-        browserTest = browserTest,
-        withLinux = false,
-        withAndroid = false,
-        appleTargets = appleTargets,
-        withWasm = false
-    )
+  val kotlinExtension = extensions.findByName("kotlin") as? KotlinMultiplatformExtension
+  if (kotlinExtension != null) {
+    kotlinExtension.block()
+    kotlinExtension.configureSourceSetGraph()
   }
   configureTesting()
 }

build-logic/src/main/kotlin/websocket_server/ServerBuildService.kt

@@ -0,0 +1,86 @@
+package websocket_server
+
+import io.ktor.server.application.*
+import io.ktor.server.engine.*
+import io.ktor.server.netty.*
+import io.ktor.server.plugins.cors.routing.*
+import io.ktor.server.routing.routing
+import io.ktor.server.websocket.WebSockets
+import io.ktor.server.websocket.webSocket
+import io.ktor.websocket.CloseReason
+import io.ktor.websocket.Frame
+import io.ktor.websocket.close
+import io.ktor.websocket.readText
+import io.ktor.websocket.send
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.coroutineScope
+import kotlinx.io.files.Path
+import org.gradle.api.services.BuildService
+import org.gradle.api.services.BuildServiceParameters
+import java.lang.AutoCloseable
+
+private val port = 18923
+
+private fun server(): EmbeddedServer<NettyApplicationEngine, NettyApplicationEngine.Configuration> {
+  return embeddedServer(Netty, port = port) {
+    install(CORS) {
+      /**
+       * This is very permissive. It's only for tests but feel free to restrict if needed.
+       */
+      anyMethod()
+      anyHost()
+      allowHeaders { true }
+      allowNonSimpleContentTypes = true
+    }
+    install(WebSockets)
+    routing {
+      webSocket("/echo") {
+        for (frame in incoming) {
+          if (frame is Frame.Text && frame.readText() == "bye") {
+            close(CloseReason(4400, "bye"))
+          } else {
+            if (frame is Frame.Text) {
+              send(frame.readText())
+            } else {
+              send(frame.data)
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+abstract class ServerBuildService : BuildService<BuildServiceParameters.None>, AutoCloseable {
+  private var server: EmbeddedServer<NettyApplicationEngine, NettyApplicationEngine.Configuration>? = null
+  private var refcount = 0
+
+  @Synchronized
+  fun startServer() {
+    if (refcount == 0) {
+      println("Starting echo server")
+      server = server().start(wait = false)
+    }
+    refcount++
+  }
+
+  fun stopServer() {
+    check(refcount > 0) {
+      "Server not started"
+    }
+    refcount--
+    if (refcount == 0) {
+      close()
+    }
+  }
+
+  @Synchronized
+  override fun close() {
+    if (server != null) {
+      println("Stopping echo server")
+      server!!.stop(1000, 1000)
+      server = null
+      refcount = 0
+    }
+  }
+}

build-logic/src/main/kotlin/websocket_server/server-tasks.kt

@@ -0,0 +1,28 @@
+package websocket_server
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.provider.Property
+import org.gradle.api.services.ServiceReference
+import org.gradle.api.tasks.TaskAction
+
+
+abstract class StartServerTask: DefaultTask() {
+  @get:ServiceReference
+  abstract val buildService: Property<ServerBuildService>
+
+  @TaskAction
+  fun taskAction() {
+    buildService.get().startServer()
+  }
+}
+
+abstract class StopServerTask: DefaultTask() {
+  @get:ServiceReference
+  abstract val buildService: Property<ServerBuildService>
+
+  @TaskAction
+  fun taskAction() {
+    buildService.get().stopServer()
+  }
+}
+

build-logic/src/main/kotlin/websocket_server/wiring.kt

@@ -0,0 +1,23 @@
+package websocket_server
+
+import org.gradle.api.Project
+import org.gradle.api.tasks.testing.AbstractTestTask
+import org.jetbrains.kotlin.gradle.targets.js.testing.KotlinJsTest
+import org.jetbrains.kotlin.gradle.targets.js.webpack.KotlinWebpack
+import org.jetbrains.kotlin.gradle.tasks.KotlinTest
+
+fun Project.configureWebSocketServer() {
+  val startServer = tasks.register("startServer", StartServerTask::class.java)
+  val stopServer = tasks.register("stopServer", StartServerTask::class.java)
+
+  gradle.sharedServices.registerIfAbsent("websocketServer", ServerBuildService::class.java)
+  tasks.withType(AbstractTestTask::class.java).configureEach {
+    dependsOn(startServer)
+    finalizedBy(stopServer)
+  }
+  // For development
+  tasks.withType(KotlinWebpack::class.java).configureEach {
+    dependsOn(startServer)
+    finalizedBy(stopServer)
+  }
+}

gradle/libraries.toml

@@ -153,7 +153,9 @@ ktor-client-darwin = { group = "io.ktor", name = "ktor-client-darwin", version.r
 ktor-client-js = { group = "io.ktor", name = "ktor-client-js", version.ref = "ktor" }
 ktor-client-websockets = { group = "io.ktor", name = "ktor-client-websockets", version.ref = "ktor" }
 ktor-server-core = { group = "io.ktor", name = "ktor-server-core", version.ref = "ktor" }
+ktor-server-cors = { group = "io.ktor", name = "ktor-server-cors", version.ref = "ktor" }
 ktor-server-cio = { group = "io.ktor", name = "ktor-server-cio", version.ref = "ktor" }
+ktor-server-netty = { group = "io.ktor", name = "ktor-server-netty", version.ref = "ktor" }
 ktor-server-websockets = { group = "io.ktor", name = "ktor-server-websockets", version.ref = "ktor" }
 ktor-network = { module = "io.ktor:ktor-network", version.ref = "ktor" }
 okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }

libraries/apollo-runtime/build.gradle.kts

@@ -1,4 +1,6 @@
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
 import org.jetbrains.kotlin.gradle.plugin.KotlinDependencyHandler
+import websocket_server.configureWebSocketServer
 
 plugins {
   id("org.jetbrains.kotlin.multiplatform")