Plugin hooks (#1452)

* Refactor session and plugin code
* Add context to job tasks
* Show hooks in plugins page
* Refactor session management

ui/v2.5/src/docs/en/EmbeddedPlugins.md

@@ -78,22 +78,6 @@ For embedded plugins, the `exec` field is a list with the first element being th
 For embedded plugins, the `interface` field must be set to one of the following values:
 * `js`
 
-# Task configuration
-
-Tasks are configured using the following structure:
-
-```
-tasks:
-  - name: <operation name>
-    description: <optional description>
-    defaultArgs:
-      argKey: argValue
-```
-
-A plugin configuration may contain multiple tasks. 
-
-The `defaultArgs` field is used to add inputs to the plugin input sent to the plugin.
-
 # Javascript API
 
 ## Logging

ui/v2.5/src/docs/en/ExternalPlugins.md

@@ -89,20 +89,14 @@ The `errLog` field tells stash what the default log level should be when the plu
 
 # Task configuration
 
-Tasks are configured using the following structure:
+In addition to the standard task configuration, external tags may be configured with an optional `execArgs` field to add extra parameters to the execution arguments for the task.
+
+For example:
 
 ```
 tasks:
   - name: <operation name>
     description: <optional description>
-    defaultArgs:
-      argKey: argValue
     execArgs:
       - <arg to add to the exec line>
 ```
-
-A plugin configuration may contain multiple tasks. 
-
-The `defaultArgs` field is used to add inputs to the plugin input sent to the plugin.
-
-The `execArgs` field allows adding extra parameters to the execution arguments for this task.

ui/v2.5/src/docs/en/Plugins.md

@@ -2,6 +2,8 @@
 
 Stash supports the running tasks via plugins. Plugins can be implemented using embedded Javascript, or by calling an external binary.
 
+Stash also supports triggering of plugin hooks from specific stash operations.
+
 > **⚠️ Note:** Plugin support is still experimental and is likely to change.
 
 # Adding plugins
@@ -67,3 +69,108 @@ Plugin output is expected in the following structure (presented here as JSON for
 ```
 
 The `error` field is logged in stash at the `error` log level if present. The `output` is written at the `debug` log level.
+
+## Task configuration
+
+Tasks are configured using the following structure:
+
+```
+tasks:
+  - name: <operation name>
+    description: <optional description>
+    defaultArgs:
+      argKey: argValue
+```
+
+A plugin configuration may contain multiple tasks. 
+
+The `defaultArgs` field is used to add inputs to the plugin input sent to the plugin.
+
+## Hook configuration
+
+Stash supports executing plugin operations via triggering of a hook during a stash operation.
+
+Hooks are configured using a similar structure to tasks:
+
+```
+hooks:
+  - name: <operation name>
+    description: <optional description>
+    triggeredBy:
+      - <trigger types>...
+    defaultArgs:
+      argKey: argValue
+```
+
+**Note:** it is possible for hooks to trigger eachother or themselves if they perform mutations. For safety, hooks will not be triggered if they have already been triggered in the context of the operation. Stash uses cookies to track this context, so it's important for plugins to send cookies when performing operations.
+
+### Trigger types
+
+Trigger types use the following format:
+`<object type>.<operation>.<hook type>`
+
+For example, a post-hook on a scene create operation will be `Scene.Create.Post`.
+
+The following object types are supported:
+* `Scene`
+* `SceneMarker`
+* `Image`
+* `Gallery`
+* `Movie`
+* `Performer`
+* `Studio`
+* `Tag`
+
+The following operations are supported:
+* `Create`
+* `Update`
+* `Destroy`
+
+Currently, only `Post` hook types are supported. These are executed after the operation has completed and the transaction is committed.
+
+### Hook input
+
+Plugin tasks triggered by a hook include an argument named `hookContext` in the `args` object structure. The `hookContext` is structured as follows:
+
+```
+{
+    "id": <object id>,
+    "type": <trigger type>,
+    "input": <operation input>,
+    "inputFields": <fields included in input>
+}
+```
+
+The `input` field contains the JSON graphql input passed to the original operation. This will differ between operations. For hooks triggered by operations in a scan or clean, the input will be nil. `inputFields` is populated in update operations to indicate which fields were passed to the operation, to differentiate between missing and empty fields.
+
+For example, here is the `args` values for a Scene update operation:
+
+```
+{
+    "hookContext": {
+        "type":"Scene.Update.Post",
+        "id":45,
+        "input":{
+            "clientMutationId":null,
+            "id":"45",
+            "title":null,
+            "details":null,
+            "url":null,
+            "date":null,
+            "rating":null,
+            "organized":null,
+            "studio_id":null,
+            "gallery_ids":null,
+            "performer_ids":null,
+            "movies":null,
+            "tag_ids":["21"],
+            "cover_image":null,
+            "stash_ids":null
+        },
+        "inputFields":[
+            "tag_ids",
+            "id"
+        ]
+    }
+}
+```