Merge branch 'dev-0.10'

Author: birdofpreyru

.nvmrc

@@ -1 +1 @@
-v18
+v20.10.0

README.md

@@ -66,6 +66,7 @@ and [old][Old Architecture] RN architectures.
   - [Enabling Alias module]
   - [Enabling Rewrite module]
   - [Enabling WebDAV module]
+  - [Connecting to an Active Server in the Native Layer]
 - [API Reference](#api-reference)
   - [Server] — Represents a server instance.
     - [constructor()] — Creates a new [Server] instance.
@@ -89,7 +90,9 @@ and [old][Old Architecture] RN architectures.
   - [extractBundledAssets()] — Extracts bundled assets into a regular folder
     (Android-specific).
   - [getActiveServer()] — Gets currently active, starting, or stopping
-    server instance, if any.
+    server instance, if any, according to the TS layer data.
+  - [getActiveServerId()] — Gets ID of the currently active, starting, or
+    stopping server instance, if any, according to the Native layer data.
   - [resolveAssetsPath()] — Resolves relative paths for bundled assets.
   - [ERROR_LOG_FILE] — Location of the error log file.
   - [STATES] — Enumerates possible states of [Server] instance.
@@ -485,6 +488,50 @@ routes when you create [Server] instance, using `extraConfig` option.
     `,
     ```
 
+### Connecting to an Active Server in the Native Layer
+[Connecting to an Active Server in the Native Layer]: #connecting-to-an-active-server-in-the-native-layer
+
+When this library is used the regular way, the [Lighttpd] server in the native
+layer is launched when the [.start()] method of a [Server] instance is triggered
+on the JavaScript (TypeScript) side, and the native server is terminated when
+the [.stop()] method is called on the JS side. In the JS layer we hold most of
+the server-related information (`hostname`, `port`, `fileDir`, _etc._),
+and take care of the high-level server control (_i.e._ the optional
+pause / resume of the server when the app enters background / foreground).
+If JS engine is restarted (or just related JS modules are reloaded) the regular
+course of action is to explictly terminate the active server just before it,
+and to re-create, and re-launch it afterwards. If it is not done, the [Lighttpd]
+server will remain active in the native layer across the JS engine restart,
+and it won't be possible to launch a new server instance after the restart,
+as the library only supports at most one active [Lighttpd] server, and it
+throws an error if the server launch command arrives to the native layer while
+[Lighttpd] server is already active.
+
+However, in response to
+[the ticket #95](https://github.com/birdofpreyru/react-native-static-server/issues/95)
+we provide a way to reuse an active native server across JS engine restarts,
+without restarting the server. To do so you:
+- Use [getActiveServerId()] method to check whether the native server is active
+  (if so, this method resolves to a non-_null_ ID).
+- Create a new [Server] instance passing into its [constructor()] that server ID
+  as the `id` option, and [STATES]`.ACTIVE` as the `state` option. These options
+  (usually omitted when creating a regular [Server] instance) ensure that
+  the created [Server] instance is able to communicate with the already running
+  native server, and to correctly handle subsequent [.stop()] and [.start()]
+  calls. Beside these, it is up-to-you to set all other options to the values
+  you need (_i.e._ setting `id`, and `state` just «connects»
+  the newly created [Server] instance to the active native server, but it
+  does not restore any other information about the server — you should
+  restore or redefine it the way you see fit).
+
+Note, this way it is possible to create multiple [Server] instances connected
+to the same active native server. As they have the same `id`, they all will
+represent the same server, thus calling [.stop()] and [.start()] commands
+on any of them will operate the same server, and update the states of all
+these JS server instances, without triggering the error related to
+the «at most one active server a time» (though, it has not been
+carefully tested yet).
+
 ## API Reference
 ### Server
 [Server]: #server
@@ -551,6 +598,12 @@ within `options` argument:
   special `hostname` values to ask the library to automatically select
   appropriate non-local address._
 
+- `id` — **number** — Optional. Allows to enforce a specific ID,
+  used to communicate with the server instance within the Native layer, thus
+  it allows to re-connect to an existing native server instance.
+  See «[Connecting to an Active Server in the Native Layer]»
+  for details. By default, an `id` is selected by the library.
+
 - `nonLocal` — **boolean** — Optional. By default, if `hostname`
   option was not provided, the server starts at the "`127.0.0.1`" (loopback)
   address, and it is only accessible within the host app.
@@ -565,6 +618,15 @@ within `options` argument:
 - `port` — **number** — Optional. The port at which to start the server.
   If 0 (default) an available port will be automatically selected.
 
+- `state` — [STATES] — Optional. Allows to enforce the initial
+  server state value, which is necessary [when connecting to an existing
+  native server instance][Connecting to an Active Server in the Native Layer].
+  Note, it only influence the logic behind subsequent [.start()] and [.stop()]
+  calls, _i.e._ the constructor does not attempt to put the server in this
+  state, nor does it check the value is consistent with the active server,
+  if any, in the native layer. By default, the state is initialized
+  to `STATES.INACTIVE`.
+
 - `stopInBackground` — **boolean** — Optional.
 
   By default, the server continues to work as usual when its host app enters
@@ -795,17 +857,43 @@ This is an Android-specific function; it does nothing on other platforms.
 
 ### getActiveServer()
 [getActiveServer()]: #getactiveserver
-```js
+```ts
 import {getActiveServer} from '@dr.pogodin/react-native-static-server';
 
-getActiveServer(): Server;
+getActiveServer(): Server | undefined;
 ```
 Returns currently active, starting, or stopping [Server] instance, if any exist
 in the app. It does not return, however, any inactive server instance which has
 been stopped automatically because of `stopInBackground` option, when the app
 entered background, and might be automatically started in future if the app
 enters foreground again prior to an explicit [.stop()] call for that instance.
 
+**NOTE:** The result of this function is based on the TypeScript layer data
+(that's why it is synchronous), in contrast to the [getActiveServerId()]
+function below, which calls into the Native layer, and returns ID of the active
+server based on that.
+
+### getActiveServerId()
+[getActiveServerId()]: #getactiveserverid
+```ts
+import {getActiveServerId} from '@dr.pogodin/react-native-static-server';
+
+getActiveServerId(): Promise<number | null>;
+```
+Returns ID of the currently active, starting, or stopping server instance,
+if any exist in the Native layer.
+
+This function is provided in response to
+[the ticket #95](https://github.com/birdofpreyru/react-native-static-server/issues/95),
+to allow &laquo;[Connecting to an Active Server in the Native Layer]&raquo;.
+The ID returned by this function can be passed in into [Server] instance
+[constructor()] to create server instance communicating to the existing native
+layer server.
+
+**NOTE:** It is different from [getActiveServer()] function above, which
+returns the acurrently active, starting, or stopping [Server] instance based on
+TypeScript layer data.
+
 ### resolveAssetsPath()
 [resolveAssetsPath()]: #resolveassetspath
 ```ts

android/src/main/java/com/drpogodin/reactnativestaticserver/ReactNativeStaticServerModule.kt

@@ -34,6 +34,11 @@ class ReactNativeStaticServerModule internal constructor(context: ReactApplicati
         return constants
     }
 
+    @ReactMethod
+    override fun getActiveServerId(promise: Promise) {
+      promise.resolve(server?.id)
+    }
+
     @ReactMethod
     override fun getLocalIpAddress(promise: Promise) {
         try {
@@ -65,9 +70,9 @@ class ReactNativeStaticServerModule internal constructor(context: ReactApplicati
     @ReactMethod
     override fun start(
             id: Double,  // Server ID for backward communication with JS layer.
-            configPath: String?,
-            errlogPath: String?,
-            promise: Promise?
+            configPath: String,
+            errlogPath: String,
+            promise: Promise
     ) {
         Log.i(LOGTAG, "Starting...")
         try {
@@ -90,10 +95,8 @@ class ReactNativeStaticServerModule internal constructor(context: ReactApplicati
         pendingPromise = promise
         val emitter: DeviceEventManagerModule.RCTDeviceEventEmitter = getReactApplicationContext()
                 .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
-        server = Server(
-                configPath,
-                errlogPath
-        ) { signal, details ->
+
+        server = Server(id, configPath, errlogPath) { signal, details ->
             if (signal !== Server.LAUNCHED) server = null
             if (pendingPromise == null) {
                 val event = Arguments.createMap()

android/src/main/java/com/lighttpd/Server.java

@@ -0,0 +1,85 @@
+package com.lighttpd
+
+import android.util.Log
+import com.drpogodin.reactnativestaticserver.Errors
+import java.util.function.BiConsumer
+
+/**
+ * Java interface for native Lighttpd server running in a dedicated Thread.
+ * Use Thread methods to operate the server:
+ * .start() - To launch it;
+ * .isActive() - To check its current status;
+ * .interrupt() - To gracefully terminate it.
+ * Also, `signalConsumer` callback provided to Server instance upon construction
+ * will provide you with server state change Signals.
+ *
+ * As Java Thread instances may be executed only once, to restart the server
+ * you should create and launch a new instance of Server object.
+ *
+ * BEWARE: With the current Lighttpd implementation,
+ * and the way it is integrated into this library, it is not safe to run
+ * multiple server instances in parallel! Be sure the previous server instance,
+ * if any, has terminated or crashed before launching a new one!
+ */
+class Server(
+        var id: Double,
+        var configPath: String,
+        var errlogPath: String,
+        private val signalConsumer: BiConsumer<String, String?>
+) : Thread() {
+    override fun interrupt() {
+        Log.i(LOGTAG, "Server.interrupt() triggered")
+        gracefulShutdown()
+        // No need to call super.interrupt() here, the native this.shutdown()
+        // method will set within the native layer necessary flags that will
+        // cause graceful termination of the thread.
+    }
+
+    private external fun gracefulShutdown()
+    external fun launch(configPath: String, errlogPath: String): Int
+    override fun run() {
+        Log.i(LOGTAG, "Server.run() triggered")
+        if (activeServer != null) {
+            val msg = "Another Server instance is active"
+            Log.e(LOGTAG, msg)
+            signalConsumer.accept(CRASHED, msg)
+            return
+        }
+        try {
+            activeServer = this
+            val res = launch(configPath, errlogPath)
+            if (res != 0) {
+                throw Exception("Native server exited with status $res")
+            }
+
+            // NOTE: It MUST BE set "null" prior to sending out TERMINATED or CRASHED
+            // signals.
+            activeServer = null
+            Log.i(LOGTAG, "Server terminated gracefully")
+            signalConsumer.accept(TERMINATED, null)
+        } catch (error: Exception) {
+            activeServer = null
+            Log.e(LOGTAG, "Server crashed", error)
+            signalConsumer.accept(CRASHED, error.message)
+        }
+    }
+
+    companion object {
+        init {
+            System.loadLibrary("lighttpd")
+        }
+
+        // NOTE: Tried to use enum, but was not able to make it work with JNI.
+        const val CRASHED = "CRASHED"
+        const val LAUNCHED = "LAUNCHED"
+        const val TERMINATED = "TERMINATED"
+        private var activeServer: Server? = null
+        private const val LOGTAG = Errors.LOGTAG
+
+        // NOTE: @JvmStatic annotation is needed to make this function
+        // visible via JNI in C code.
+        @JvmStatic fun onLaunchedCallback() {
+            activeServer!!.signalConsumer.accept(LAUNCHED, null)
+        }
+    }
+}