[WJ-1187] Automatic reload on configuration change

.github/workflows/deepwell.yaml

@@ -45,8 +45,11 @@ jobs:
       - name: System Dependencies
         run: sudo apt update && sudo apt install libmagic-dev
 
-      - name: Build
-        run: cd deepwell && cargo build
+      - name: Build (local)
+        run: cd deepwell && cargo build --features local
+
+      - name: Build (deploy)
+        run: cd deepwell && cargo build --features deploy
 
       - name: Check Configuration
         run: cd deepwell && cargo run -- config.example.toml ../install/files/local/deepwell.toml

deepwell/Cargo.toml

@@ -12,11 +12,17 @@ version = "2023.5.14"
 authors = ["Emmie Maeda <[email protected]>"]
 edition = "2021" # this is *not* the same as the current year
 
+[features]
+local = ["watch"]
+deploy = []
+watch = ["notify"]
+
 [dependencies]
 anyhow = "1"
 arraystring = "0.3"
 argon2 = "0.5"
 async-std = { version = "1", features = ["attributes"] }
+cfg-if = "1"
 clap = "4"
 color-backtrace = "0.6"
 crossfire = "1.0"
@@ -32,6 +38,7 @@ hex = "0.4"
 hostname = "0.3"
 intl-memoizer = "0.5"
 lazy_static = "1"
+notify = { version = "6", optional = true }
 otp = { git = "https://github.com/TimDumol/rust-otp" }
 rand = "0.8"
 ref-map = "0.1"

deepwell/README.md

@@ -36,7 +36,7 @@ $ scripts/generate-models.sh
 The primary organization of the crate is as follows:
 
 * `api/` — Web server definition, such as its routes and related structures.
-  * Each API is namespaced based on its version. The primary version of interest is the "internal" API, which is consumed by PHP and not meant for outside consumption due to it providing unguarded access.
+  * Exposes the internal API for use by Framerail.
 * `endpoints/` — Implementations for individual endpoints described above.
 * `services/` — "Services", or logical encapsulations of different concepts or operations.
   * For instance, the `ParentService` allows retrieving and storing data related to parent-child page relationships. You can think of it as "wrapping" the `page_parent` table.
@@ -54,10 +54,36 @@ The routes are defined in `api/`, with their implementations in `methods/`, and
 
 This executable targets the latest stable Rust. At time of writing, that is `1.72.0`.
 
+There are two features supported by DEEPWELL, along with what they add:
+
+* `local` — Intended for local development, where frequent compilation is likely.
+ * Tracks the locale directory and configuration file, reloading them if they are modified.
+* `deploy` — Intended for "deployed" environments, i.e. `dev` and `prod`.
+
+Thus for a _release build_ (being deployed somewhere) you would want to run:
+
+```sh
+$ cargo build --release --features deploy
+```
+
+And for a _local build_ you would want:
+
 ```sh
-$ cargo build --release
+$ cargo build --features local
 ```
 
+### Execution
+
+```sh
+$ cargo build --features <deploy|local> -- [-q] [-p <port>] <config-file>
+```
+
+There are a number of arguments beyond the ones shown. Run with `--help` for all relevant information.
+
+This runs a local instance of DEEPWELL with the given configuration file. When debugging (i.e. on `--features local` only), you can also pass in `-w` or `--watch-files` to have the process to restart automatically when the configuration file or any localization files change.
+
+This does not seem to work with Docker, so you should instead manually stop the `api` container and run it locally with the flag. That will properly watch changes and restart itself.
+
 ### Testing
 
 Tests have not yet been implemented, but when they are, run:

deepwell/config.example.toml

@@ -63,7 +63,7 @@ authentication-fail-delay-ms = 100
 [security.session]
 
 # All session tokens are prefixed with this string.
-# It makes a session token immediately reecognizable
+# It makes a session token immediately recognizable
 # as it is otherwise a long random string.
 token-prefix = "wj:"
 
@@ -246,7 +246,7 @@ maximum-name-changes = 3
 # The minimum length for a user's name in bytes.
 # A user who attempts to register must have a slug which is at least this long.
 #
-#  The intent is to prevent the proliferation of very short, unidentifiable usernames
+# The intent is to prevent the proliferation of very short, unidentifiable usernames
 # such as single Latin letters (e.g. "N"). However, we check *bytes* specifically to
 # avoid Anglo-centricism, as many full names in other languages fit within two letters
 # (consider CJK for instance). Single characters outside of the main ASCII block

deepwell/src/api.rs

@@ -126,6 +126,7 @@ fn build_routes(mut app: ApiServer) -> ApiServer {
     app.at("/version/full").get(full_version);
     app.at("/hostname").get(hostname);
     app.at("/config").get(config_dump);
+    app.at("/config/path").get(config_path);
     app.at("/normalize/:input").all(normalize_method);
     app.at("/teapot")
         .all(|_| async { error_response(StatusCode::ImATeapot, "🫖") });

deepwell/src/config/args.rs

@@ -69,6 +69,13 @@ pub fn parse_args() -> Config {
                 .action(ArgAction::Set)
                 .help("What port to listen on."),
         )
+        .arg(
+            Arg::new("watch-config")
+                .short('w')
+                .long("watch")
+                .action(ArgAction::SetTrue)
+                .help("Whether to auto-restart when configuration or localization files change."),
+        )
         .arg(
             Arg::new("run-migrations")
                 .short('M')
@@ -119,7 +126,7 @@ pub fn parse_args() -> Config {
         .remove_one::<PathBuf>("config-file")
         .expect("Required argument not provided");
 
-    let mut config = match Config::load(&config_path) {
+    let mut config = match Config::load(config_path) {
         Ok(config) => config,
         Err(error) => {
             eprintln!("Unable to load configuration from file: {error}");
@@ -151,6 +158,10 @@ pub fn parse_args() -> Config {
         config.address.set_port(value);
     }
 
+    if matches.remove_one::<bool>("watch-config") == Some(true) {
+        config.watch_files = true;
+    }
+
     if let Some(value) = matches.remove_one::<bool>("run-migrations") {
         config.run_migrations = value;
     }