update documentation/examples; use PluginContent

Author: mplsgrant

docs/plugins.md

@@ -1,55 +1,72 @@
 # Plugins
 
-Plugins allow users to extend Warnet. Plugin authors can import commands from Warnet and plugin users can run plugin commands from the command line or on each invocation of `warnet deploy`.
+Plugins extend Warnet. Plugin authors can import commands from Warnet and interact with the kubernetes cluster, and plugin users can run plugins from the command line or from the `network.yaml` file.
 
-## Activating plugins from 'network.yaml'
+## Activating plugins from `network.yaml`
 
-You can activate a plugin command by placing it in the `plugin` section at the bottom of each `network.yaml` file like so:
+You can activate a plugin command by placing it in the `plugins` section at the bottom of each `network.yaml` file like so:
+
+````yaml
+nodes:
+  <<snip>>
+
+plugins:  # This marks the beginning of the plugin section
+  preDeploy:  # This is a hook. This particular hook will call plugins before deploying anything else.
+    hello:  # This is the name of the plugin.
+      entrypoint: "../plugins/hello"  # Every plugin must specify a path to its entrypoint.
+      podName: "hello-pre-deploy"  # Plugins can have their own particular configurations, such as how to name a pod.
+      helloTo: "preDeploy!"  # This configuration tells the hello plugin who to say "hello" to.
+````
+
+## Many kinds of hooks
+There are many hooks to the Warnet `deploy` command. The example below specifies them:
 
 ````yaml
 nodes:
   <<snip>>
 
 plugins:
-  preDeploy:
+  preDeploy:  # Plugins will run before any other `deploy` code.
     hello:
       entrypoint: "../plugins/hello"
       podName: "hello-pre-deploy"
       helloTo: "preDeploy!"
-  postDeploy:
+  postDeploy:  # Plugins will run after all the `deploy` code has run.
     simln:
-      entrypoint: "../../../resources/plugins/simln"
+      entrypoint: "../plugins/simln"
       activity: '[{"source": "tank-0003-ln", "destination": "tank-0005-ln", "interval_secs": 1, "amount_msat": 2000}]'
     hello:
       entrypoint: "../plugins/hello"
       podName: "hello-post-deploy"
       helloTo: "postDeploy!"
-  preNode:
+  preNode:  # Plugins will run before `deploy` launches a node (once per node).
     hello:
       entrypoint: "../plugins/hello"
       helloTo: "preNode!"
-  postNode:
+  postNode:  # Plugins will run after `deploy` launches a node (once per node).
     hello:
       entrypoint: "../plugins/hello"
       helloTo: "postNode!"
-  preNetwork:
+  preNetwork:  # Plugins will run before `deploy` launches the network (essentially between logging and when nodes are deployed)
     hello:
       entrypoint: "../plugins/hello"
       helloTo: "preNetwork!"
       podName: "hello-pre-network"
-  postNetwork:
+  postNetwork:  # Plugins will run after the network deploy threads have been joined.
     hello:
       entrypoint: "../plugins/hello"
       helloTo: "postNetwork!"
       podName: "hello-post-network"
 ````
 
-Warnet will execute these plugin commands after each invocation of `warnet deploy`.
+Warnet will execute these plugin commands during each invocation of `warnet deploy`.
+
+
 
-## Example: SimLN
+## A "hello" example
 
-To get started with an example plugin, review the `README` of the `simln` plugin found in any initialized Warnet directory:
+To get started with an example plugin, review the `README` of the `hello` plugin found in any initialized Warnet directory:
 
 1. `warnet init`
-2. `cd plugins/simln/`
+2. `cd plugins/hello/`
 

resources/plugins/hello/README.md

@@ -1,10 +1,10 @@
 # Hello Plugin
 
 ## Hello World!
-*Hello* is an example plugin to demonstrate the features of Warnet's plugin architecture.
+*Hello* is an example plugin to demonstrate the features of Warnet's plugin architecture. It uses each of the hooks available in the `warnet deploy` command (see the example below for details).
 
 ## Usage
-In your python virtual environment with Warnet installed and started, create a new Warnet user folder (follow the prompts):
+In your python virtual environment with Warnet installed and setup, create a new Warnet user folder (follow the prompts):
 
 `$ warnet new user_folder`
 
@@ -18,14 +18,14 @@ While that is launching, take a look inside the `networks/hello/network.yaml` fi
 
 Also, take a look at the `plugins/hello/plugin.py` file to see how plugins work and to find out how to author your own plugin.
 
-To view the pods that the *hello* network launched, run `kubectl get all -A`
+Once `deploy` completes, view the pods of the *hello* network by invoking `kubectl get all -A`.
 
 To view the various "Hello World!" messages, run `kubectl logs pod/POD_NAME`
 
 ### A `network.yaml` example
 When you initialize a new Warnet network, Warnet will create a new `network.yaml` file. You can modify these files to fit your needs.
 
-For example, example `network.yaml` file includes the *hello* plugin, lightning nodes and the *simln* plugin.
+For example, the `network.yaml` file below includes the *hello* plugin, lightning nodes, and the *simln* plugin.
 
 <details>
 <summary>network.yaml</summary>

resources/plugins/hello/plugin.py

@@ -10,7 +10,7 @@
 from warnet.constants import PLUGIN_ANNEX, AnnexMember, HookValue, WarnetContent
 from warnet.process import run_command
 
-# Tt is common for Warnet objects to have a "mission" tag to query them in the cluster.
+# Tt is common for Warnet objects to have a "mission" label to help query for them in the cluster.
 MISSION = "hello"
 PRIMARY_CONTAINER = MISSION
 
@@ -32,7 +32,7 @@ class PluginError(Exception):
 log.propagate = True
 
 
-# Plugins look like this in the network.yaml file:
+# Plugins look like this in the `network.yaml` file:
 #
 # plugins:
 #   hello:
@@ -42,7 +42,7 @@ class PluginError(Exception):
 # "podName" and "helloTo" are essentially dictionary keys, and it helps to keep those keys in an
 # enum in order to prevent typos.
 class PluginContent(Enum):
-    POD_NAME = ("podName",)
+    POD_NAME = "podName"
     HELLO_TO = "helloTo"
 
 
@@ -113,7 +113,9 @@ def _entrypoint(ctx, plugin_content: dict, warnet_content: dict):
 
 def get_data(plugin_content: dict) -> Optional[dict]:
     data = {
-        key: plugin_content.get(key) for key in ("podName", "helloTo") if plugin_content.get(key)
+        key: plugin_content.get(key)
+        for key in (PluginContent.POD_NAME.value, PluginContent.HELLO_TO.value)
+        if plugin_content.get(key)
     }
     return data or None
 

resources/plugins/simln/plugin.py

@@ -2,6 +2,7 @@
 import json
 import logging
 import time
+from enum import Enum
 from pathlib import Path
 
 import click
@@ -37,6 +38,10 @@ class PluginError(Exception):
 log.addHandler(console_handler)
 
 
+class PluginContent(Enum):
+    ACTIVITY = "activity"
+
+
 @click.group()
 @click.pass_context
 def simln(ctx):
@@ -75,7 +80,7 @@ def entrypoint(ctx, plugin_content: str, warnet_content: str):
 def _entrypoint(ctx, plugin_content: dict, warnet_content: dict):
     """Called by entrypoint"""
     # write your plugin startup commands here
-    activity = plugin_content.get("activity")
+    activity = plugin_content.get(PluginContent.ACTIVITY.value)
     activity = json.loads(activity)
     print(activity)
     _launch_activity(activity, ctx.obj.get(PLUGIN_DIR_TAG))
@@ -114,7 +119,7 @@ def get_example_activity():
 
 
 @simln.command()
-@click.argument("activity", type=str)
+@click.argument(PluginContent.ACTIVITY.value, type=str)
 @click.pass_context
 def launch_activity(ctx, activity: str):
     """Deploys a SimLN Activity which is a JSON list of objects"""
@@ -164,7 +169,7 @@ def _generate_activity_json(activity: list[dict]) -> str:
         }
         nodes.append(node)
 
-    data = {"nodes": nodes, "activity": activity}
+    data = {"nodes": nodes, PluginContent.ACTIVITY.value: activity}
 
     return json.dumps(data, indent=2)