Merge branch 'document-running-plugins' into 'dev'

Document how Plugins are started

See merge request memri/pod!202

docs/Plugins.md

@@ -11,7 +11,75 @@ This page explains how Pod runs plugins.
 Plugins are automatically started when Pod certain items are requested to be created in Pod.
 This is done via [HTTP API](./HTTP_API.md).
 
-You can also manually trigger a plugin by just emulating the below steps
+You can also try it out locally, see section below
+
+# Manually trigger a plugin via Pod API
+During development, you can use the following script to make Pod start a new Plugin (container)
+```sh
+owner="$SRANDOM$SRANDOM$SRANDOM"  # replace with desired owner, or leave as-is for tests
+dbkey=  # note that the Plugin will not have access to this key, it'll only have `POD_AUTH_JSON`
+container="test"
+
+data=$(cat <<-END
+{
+    "auth": {
+        "type": "ClientAuth",
+        "databaseKey": "$dbkey"
+    },
+    "payload": {
+        "createItems": [
+            {"type": "Person", "id": "38583224e56e6d2385d36e05af9caa5e"},
+            {"type": "StartPlugin", "container": "$container", "targetItemId": "38583224e56e6d2385d36e05af9caa5e"}
+        ],
+        "updateItems": [],
+        "deleteItems": []
+    }
+}
+END
+)
+
+curl -X POST -H "Content-Type: application/json" --insecure "http://localhost:3030/v3/$owner/bulk" -d "$data"
+```
+
+# Manually trigger a plugin from the command line
+TL&DR; please use other test methods for simplicity.
+However, if you need to know how it works, you can read below.
+
+As described in [HTTP API](./HTTP_API.md), there are two authorization keys that a Plugin can use.
+
+* `ClientAuth`, which requires knowing the `database_key`
+* `PluginAuth`, which is how Pod really starts the Plugins
+
+For Plugins that means:
+
+* `ClientAuth` will never be *really* passed to the Plugin, but during tests,
+  you can just use this auth because you have access to the (fake/test) `database_key` anyway.
+* `PluginAuth` will actually be passed to the Plugin in a real system,
+  but it is impossible to emulate it because the Pod keeps relevant encryption keys in-memory,
+  generates then on startup and intentionally loses them on restart (for security reasons).
+  In short, you cannot emulate `PluginAuth`, you can only call `Pod` to generate this Auth for you.
+
+So regardless of which auth you use, the script below will give you an idea
+of the basic structure of the docker command:
+```sh
+container="test"
+owner="357535074912050791323416133896"
+target_item='{"type":"Person","id":"38583224e56e6d2385d36e05af9caa5e","dateCreated":1623241923508,"dateModified":1623241923508",dateServerModified":1623241923508,"deleted":false}'
+trigger_item_id="05abe8e2ef2d0fb4992239944a71bde5"  # the id of the item that started the Plugin (the StartPlugin item)
+your_auth_json='{???}'  # depends on whether you use test auth or real system auth
+network="localhost"  # "localhost" on linux, "host.docker.internal" on Mac and Windows
+
+docker run \
+  --network=host \
+  --env=POD_FULL_ADDRESS="http://$network:3030" \
+  --env=POD_TARGET_ITEM="$target_item" \
+  --env=POD_OWNER="$owner" \
+  --env=POD_AUTH_JSON="$your_auth" \
+  --rm \
+  --name="$container-$trigger_item_id" \
+  -- \
+  "$container"
+```
 
 # How are plugins started
 Plugins are started via **docker** (or a dedicated container in production environment).

src/plugin_run.rs

@@ -9,6 +9,19 @@ use rusqlite::Transaction;
 use std::process::Command;
 use warp::http::status::StatusCode;
 
+/// Run a plugin container in docker.
+///
+/// Example command that this function could run:
+///     docker run \
+///     --network=host \
+///     --env=POD_FULL_ADDRESS="http://localhost:3030" \
+///     --env=POD_TARGET_ITEM="{...json...}" \
+///     --env=POD_OWNER="...64-hex-chars..." \
+///     --env=POD_AUTH_JSON="{...json...}" \
+///     --rm \
+///     --name="$container-$trigger_item_id" \
+///     -- \
+///     "$container"
 #[allow(clippy::too_many_arguments)]
 pub fn run_plugin_container(
     tx: &Transaction,
@@ -45,6 +58,7 @@ pub fn run_plugin_container(
     args.push(format!("--env=POD_AUTH_JSON={}", auth));
     args.push("--rm".to_string());
     args.push(format!("--name={}-{}", &container, triggered_by_item_id));
+    args.push("--".to_string());
     args.push(container);
     log::info!("Starting plugin docker command {:?}", args);
     let command = Command::new("docker").args(&args).spawn();