[futurepress#13][futurepress#72] mod_alias support + deprecates webdav option of Server constructor() + adds "extraConfig" option

Author: birdofpreyru

CMakeLists.txt

@@ -129,6 +129,10 @@ set(PLUGIN_STATIC
   PLUGIN_INIT(mod_staticfile)\n
 )
 
+if(WITH_MOD_ALIAS)
+  set(PLUGIN_STATIC "${PLUGIN_STATIC}PLUGIN_INIT(mod_alias)\n")
+endif()
+
 if(WITH_MOD_WEBDAV)
   set(PLUGIN_STATIC "${PLUGIN_STATIC}PLUGIN_INIT(mod_webdav)\n")
 endif()

README.md

@@ -39,6 +39,7 @@ and [old][Old Architecture] RN architectures.
 [OLD-README.md]: https://github.com/birdofpreyru/react-native-static-server/blob/master/OLD-README.md
 [getDeviceType()]: https://www.npmjs.com/package/react-native-device-info#getDeviceType
 [MainBundlePath]: https://www.npmjs.com/package/@dr.pogodin/react-native-fs#mainbundlepath
+[mod_alias]: https://redmine.lighttpd.net/projects/lighttpd/wiki/Mod_alias
 [mod_webdav]: https://redmine.lighttpd.net/projects/lighttpd/wiki/Mod_webdav
 [react-native-device-info]: https://www.npmjs.com/package/react-native-device-info
 [react-native-fs]: https://www.npmjs.com/package/react-native-fs
@@ -50,6 +51,7 @@ and [old][Old Architecture] RN architectures.
 
 - [Getting Started](#getting-started)
   - [Bundling-in Server Assets Into an App Statically](#bundling-in-server-assets-into-an-app-statically)
+  - [Enabling Alias module]
   - [Enabling WebDAV module]
 - [API Reference](#api-reference)
 - [Project History and Roadmap](#project-history-and-roadmap)
@@ -340,6 +342,40 @@ outside platform-specific sub-folders.
     </Target>
     ```
 
+### Enabling Alias Module
+[Enabling Alias module]: #enabling-alias-module
+
+[Lighttpd]'s optional module [mod_alias] is used to specify a special document
+root for a given url-subset. To enable it:
+
+1.  **Android**: Edit `android/gradle.properties` file of your app, adding
+    this flag:
+    ```gradle
+    ReactNativeStaticServer_alias = true
+    ```
+
+    **iOS**: Use environment variable `RN_STATIC_SERVER_ALIAS=1` when
+    installing or updating the pods (_i.e._ when doing `pod install` or
+    `pod update`).
+
+    **macOS (Catalyst)**: The same as for iOS.
+
+    **Windows**: Does not require a special setup &mdash; the pre-compiled DLL
+    for [mod_alias] is always packed with the library, and loaded if opted
+    by [Server]'s [constructor()].
+
+2.  Use `extraConfig` option of [Server] [constructor()] to load and configure
+    [mod_alias], for example:
+    ```ts
+    extraConfig: `
+      server.modules += ("mod_alias")
+      alias.url = ("/sample/url" => "/special/root/path")
+    `,
+    ```
+    With this configuration incoming request `GET /sample/url/file` will be
+    routed to the `/special/root/path/file`, rather than the `FILE_DIR/sample/url/file`,
+    where `FILE_DIR` is the value you provided to the [Server]'s `fileDir` option.
+
 ### Enabling WebDAV Module
 [Enabling WebDAV module]: #enabling-webdav-module
 
@@ -348,15 +384,11 @@ HTTP extensions that provides a framework allowing to create, change, and move
 documents on a server &mdash; essentially an easy way to enable `POST`, `PUT`,
 _etc._ functionality for selected routes.
 
-**BEWARE:** _As of now, I only need it for implementing a local testing of
-network functionality inside [@dr.pogodin/react-native-fs] library, thus for
-development needs only, and I have not put efforts to build it with all features
-(support of props and locks), and have not looked much into what configuration
-is needed for its safe and flexible production use._
+**BEWARE:** _As of now, props and locks are not supported._
 
 To enable [mod_webdav] in the library you need (1) configure your host RN app
 to build Lighttpd with [mod_webdav] included; (2) opt-in to use it for selected
-routes when you create [Server] instance inside your TypeScript code.
+routes when you create [Server] instance, using `extraConfig` option.
 
 1.  **Android**: Edit `android/gradle.properties` file of your app, adding
     this flag in there:
@@ -374,8 +406,16 @@ routes when you create [Server] instance inside your TypeScript code.
     for [WebDAV] module is always packed with the library, and loaded if opted
     for by [Server]'s [constructor()].
 
-2.  Use `webdav` option of [Server]'s [constructor()] to enable [WebDAV] for
-    selected routes of the created server instance.
+2.  Use `extraConfig` option of [Server]'s [constructor()] to load [mod_webdav]
+    and use it for selected routes of the created server instance, for example:
+    ```ts
+    extraConfig: `
+      server.modules += ("mod_webdav")
+      $HTTP["url"] =~ "^/dav/($|/)" {
+        webdav.activate = "enable"
+      }
+    `,
+    ```
 
 ## API Reference
 - [Server] &mdash; Represents a server instance.
@@ -452,6 +492,12 @@ within `options` argument:
   **BEWARE:** If you opt for file logging with this option, it is up to you
   to control and purge the [ERROR_LOG_FILE] as needed.
 
+- `extraConfig` &mdash; **string** &mdash; Optional. If given, it should be
+  a valid piece of
+  [Lighttpd configuration](https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_Configuration),
+  and it will be appended to the base Lighttpd config generated by this
+  library according to the other server options.
+
 - `hostname` &mdash; **string** &mdash; Optional. Sets the address for server
   to bind to.
   - By default, when `nonLocal` option is **false**, `hostname` is set equal
@@ -502,20 +548,9 @@ within `options` argument:
   `details` values set equal "_App entered background_",
    and "_App entered foreground_" strings.
 
-- `webdav` &mdash; **string[]** &mdash; Optional. Enables [WebDAV] for specified
-  server routes. To use this option, first read [Enabling WebDAV module]. Each
-  string inside provided `webdav` array is expected to be a Perl-style regular
-  expression for the route(s) on which [WebDAV] should be enabled. For example,
-  to enable [WebDAV] for `/dav` directory and everything below it, you should
-  give `webdav = ["^/dav($|/)"]`, which will add the following configuration
-  to the internal [Lighttpd] config of the server:
-  ```perl
-  $HTTP["url"] =~ "^/dav($|/)" {
-    webdav.activate = "enable"
-  }
-  ```
-  As of now, we don't yet support more advanced features and configurations for
-  [mod_webdav].
+- **DEPRECATED**: `webdav` &mdash; **string[]** &mdash; It still works, but it
+  will be removed in future versions. Instead of it use `extraConfig` option to
+  enable and configure [WebDAV] as necessary (see [Enabling WebDAV module]).
 
 #### .addStateListener()
 [.addStateListener()]: #addstatelistener

android/build.gradle

@@ -43,6 +43,7 @@ android {
           // TODO: I guess, there should be a more elegant way to append
           // arguments here based on flags set in project Gradle properties,
           // but for now this will do.
+          (project.properties["ReactNativeStaticServer_alias"] ? "-DWITH_MOD_ALIAS=ON" : "-DWITH_MOD_ALIAS=OFF"),
           (project.properties["ReactNativeStaticServer_webdav"] ? "-DWITH_MOD_WEBDAV=ON" : "-DWITH_MOD_WEBDAV=OFF")
         targets "lighttpd"
       }

example/README.md

@@ -29,7 +29,7 @@ to prepare and run the example:
   - `npm run android`
 - On **iOS**:
   - ```sh
-    cd ios && RCT_NEW_ARCH_ENABLED=1 pod install
+    cd ios && RCT_NEW_ARCH_ENABLED=1 RN_STATIC_SERVER_ALIAS=1 pod install
     ```
     Here `RCT_NEW_ARCH_ENABLED=1` is optional, omit it to build for the old RN
     architecture.

example/android/gradle.properties

@@ -43,4 +43,5 @@ newArchEnabled=true
 # If set to false, you will be using JSC instead.
 hermesEnabled=true
 
+ReactNativeStaticServer_alias = true
 ReactNativeStaticServer_webdav = true

example/src/App.tsx

@@ -76,6 +76,13 @@ export default function App() {
       // opt-in for building the library with WebDAV support enabled
       // (see README for details).
       // webdav: ['^/dav($|/)'],
+
+      extraConfig: `
+        server.modules += ("mod_alias")
+        alias.url = (
+          "/some/path" => "${fileDir}"
+        )
+      `,
     });
     const serverId = server.id;
 
@@ -198,6 +205,11 @@ export default function App() {
           source={origin ? { uri: origin } : { html: '' }}
         />
       </View>
+      <View style={styles.webview}>
+        <WebView
+          source={origin ? { uri: `${origin}/some/path` } : { html: '' }}
+        />
+      </View>
     </SafeAreaView>
   );
 }

src/config.ts

@@ -48,10 +48,11 @@ export type ErrorLogOptions = {
  */
 export type StandardConfigOptions = {
   errorLog?: ErrorLogOptions;
+  extraConfig: string;
   fileDir: string;
   hostname: string;
   port: number;
-  webdav?: string[];
+  webdav?: string[]; // DEPRECATED
 };
 
 /**
@@ -91,19 +92,15 @@ function errorLogConfig(errorLogOptions?: ErrorLogOptions): string {
  */
 function standardConfig({
   errorLog,
+  extraConfig,
   fileDir,
   hostname,
   port,
-  webdav,
+  webdav, // DEPRECATED
 }: StandardConfigOptions) {
-  const modules: string[] = [];
-  if (webdav) modules.push('mod_webdav');
-  const modulesString: string = modules.length
-    ? `server.modules += ( "${modules.join('", "')}")`
-    : '';
-
   let webdavConfig = '';
   if (webdav) {
+    webdavConfig += 'server.modules += ("mod_webdav")';
     for (let i = 0; i < webdav.length; ++i) {
       webdavConfig += `$HTTP["url"] =~ "${webdav[i]}" { webdav.activate = "enable" }`;
     }
@@ -116,8 +113,8 @@ function standardConfig({
   ${errorLogConfig(errorLog)}
   index-file.names += ("index.xhtml", "index.html", "index.htm", "default.htm", "index.php")
 
-  ${modulesString}
-  ${webdavConfig}`;
+  ${webdavConfig}
+  ${extraConfig}`;
 }
 
 /**

src/index.tsx

@@ -83,6 +83,7 @@ class StaticServer {
   _appStateSub?: NativeEventSubscription;
   _configPath?: string;
   _errorLog?: ErrorLogOptions;
+  _extraConfig: string;
   _fileDir: string;
   _hostname = '';
 
@@ -161,15 +162,18 @@ class StaticServer {
    */
   constructor({
     errorLog = false,
+    extraConfig = '',
     fileDir,
     hostname,
 
     /* DEPRECATED */ nonLocal = false,
 
     port = 0,
     stopInBackground = false,
-    webdav,
+
+    /* DEPRECATED */ webdav,
   }: {
+    extraConfig?: string;
     errorLog?: boolean | ErrorLogOptions;
     fileDir: string;
     hostname?: string;
@@ -179,10 +183,12 @@ class StaticServer {
     port?: number;
     stopInBackground?: boolean;
 
-    webdav?: string[];
+    /* DEPRECATED */ webdav?: string[];
   }) {
     if (errorLog) this._errorLog = errorLog === true ? {} : errorLog;
 
+    this._extraConfig = extraConfig;
+
     this._nonLocal = nonLocal;
     this._hostname = hostname || (nonLocal ? '' : LOOPBACK_ADDRESS);
 
@@ -288,6 +294,7 @@ class StaticServer {
       await this._removeConfigFile();
       this._configPath = await newStandardConfigFile({
         errorLog: this._errorLog,
+        extraConfig: this._extraConfig,
         fileDir: this._fileDir,
         hostname: this._hostname,
         port: this._port,