Document route key and plugin prefix. Version check fixes.

nzlosh · Nov 25, 2019 · a57faee · a57faee
1 parent a920610
commit a57faee
Show file tree

Hide file tree

Showing 7 changed files with 75 additions and 28 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+##  [2.1.2] 2019-11-24
+### Added
+  - Added CircleCI build badge to README.
+  - Added route key to be defined by user to allow mutliple bots attached to a single StackStorm instance.
+  - Added version check on start-up to log if newer version of the plugin are available.
+
+### Changed
+  - Updated curl example in troubleshooting section.
+  - Changed all bot commands to be registered dynamically to allow user defined plugin prefix.
+
+##  [2.1.1] 2019-07-19
+### Added
+  - Added configuration for mattermost, rocketchat, discord, gitter and slack to docker build.
+
+### Changed
+  - Improved Discord Chat Adapter formatting.
+  - Corrected configuration name handling which caused exceptions to be raised.
+  - Updated documentation to direct readers to readthedocs.
+
+### Removed
+  - Removed old readme file.
+
 ## [2.1.0] 2019-07-08
 ### Added
   - Added `deactivate` method to correctly handle errbot reload and stop process.

diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -21,7 +21,8 @@ Here's a sample err-stackstorm configuration:
         'auth_url': 'https://your.stackstorm.com/auth/v1',
         'api_url': 'https://your.stackstorm.com/api/v1',
         'stream_url': 'https://your.stackstorm.com/stream/v1',
-
+        'route_key': 'errbot',
+        'plugin_prefix': 'st2',
         'verify_cert': True,
         'secrets_store': 'cleartext',
         'api_auth': {
@@ -52,6 +53,7 @@ Edit the ``/<st2>/packs/chatops/actions/post_message.yaml`` file and replace `ch
   route:
     default: "errbot"
 
+.. note:: See Route Key below for information on customising the route.
 
 Authentication
 ---------------
@@ -105,14 +107,19 @@ Cleartext
 
 The cleartext store maintains the cache in memory and does not encrypt the contents to disk. It **does not** protect the stored secrets in memory.
 
+Route Key
+---------
+
+StackStorm ChatOps uses `routes` to indicate where a notification should be sent to.  By default the StackStorm ChatOps pack uses **chatops** for the send message action.
+
 Locale
 -------
 
 Errbot uses the system's locale for handling text. If you're getting unicode errors like this::
 
   UnicodeEncodeError: 'ascii' codec can't encode character '\xe9' in position 83: ordinal not in range(128)
 
-Make sure the systems locale is configured for unicode encoding. In the example below, the machine has set the English (en) New Zealand (NZ) with utf-8 encoding (.UTF8).
+Make sure the systems locale is configured for unicode encoding. In the example below, the machine has been set to English (en) New Zealand (NZ) with utf-8 encoding (.UTF8).
 
 .. code-block:: bash
 
@@ -142,15 +149,17 @@ Reference
     :header: "Option", "Description"
     :widths: 25, 40
 
-    "auth_url", "StackStorm's authentication url end point. Used to authenticate credentials against StackStorm."
-    "api_url", "StackStorm's API url end point. Used to execute action aliases received from the chat back-end."
-    "stream_url", "StackStorm's Stream url end point. Used to received ChatOps notifications."
-    "verify_cert", "Default is *True*. Verify the SSL certificate is valid when using https end points. Applies to all end points."
+    "auth_url", "StackStorm's authentication url end point.  Used to authenticate credentials against StackStorm."
+    "api_url", "StackStorm's API url end point.  Used to execute action aliases received from the chat back-end."
+    "stream_url", "StackStorm's Stream url end point.  Used to received ChatOps notifications."
+    "verify_cert", "Default is *True*.  Verify the SSL certificate is valid when using https end points. Applies to all end points."
+    "route_key", "Default is *errbot*. The name of the route to bot will listen for and submit action-alias executions with."
+    "plugin_prefix", "Default is *st2*. Text used to prefix action-alias commands with to avoid name collisions between StackStorm Action-Aliases and Errbot plugin commands."
     "api_auth.user.name", "Errbot's username to authenticate with StackStorm."
     "api_auth.user.password", "Errbot's password to authenticate with StackStorm."
     "api_auth.token", "Errbot's user token to authenticate with StackStorm. Used instead of a username/password pair."
     "api_auth.apikey", "Errbot API key to authenticate with StackStorm. Used instead of a username/password pair or user token."
-    "timer_update", "Unit: seconds. Default is 60. Interval for err-stackstorm to the user token is valid."
+    "timer_update", "Unit: seconds. Default is 60. Interval to test if err-stackstorm's user token is valid."
     "rbac_auth.standalone", "Standalone authentication."
     "rbac_auth.clientside", "Clientside authentication, a chat user will supply StackStorm credentials to err-stackstorm via an authentication page."
     "rbac_auth.clientside.url", "Url to the authentication web page."

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -9,33 +9,34 @@ Getting Started
 Overview
 =========
 
-`err-stackstorm` is an unofficial community project to bring StackStorm ChatOps to Errbot. Using `err-stackstorm` you will be able to leverage `Errbot <http://errbot.io/en/latest/index.html>`_ as the `ChatOps <https://docs.stackstorm.com/chatops/index.html>`_ of your choice for controlling Stackstorm using **conversation-driven development** by using Stackstorm's `Action Aliases <https://docs.stackstorm.com/chatops/aliases.html>`_.
+`err-stackstorm` is a community project to bring StackStorm `ChatOps <https://docs.stackstorm.com/chatops/index.html>`_ to `Errbot <http://errbot.io/en/latest/index.html>`_.  No commercial support is provided by StackStorm.  `err-stackstorm` exposes Stackstorm's `Action Aliases <https://docs.stackstorm.com/chatops/aliases.html>`_ to your chat environment, where you and your team can manage aspects of infrastructure and code.
 
+The objectives for err-stackstorm project are:
  1. Emulate hubot-stackstorm features.
  2. Provide a Python friendly ChatOps solution.
  3. Respect StackStorm's enterprise offering.
  4. Maintain the same high quality as the StackStorm project.
  5. Collaborate with the StackStorm community to evolve ChatOps features.
 
-.. important:: `st2chatops` does not have to be running on your StackStorm instance. This plugin *replaces* `st2chatops`.
-
 Features
 ========
 
 err-stackstorm communicates directly with the StackStorm API from with an errbot instance.
 
-     - List action-alias help dynamically. When StackStorm action-aliases are updated, they are immediately available in the err-stackstorm output. Filtering by pack name and keyword can be used when look for help.
+     - List action-alias help dynamically.  When StackStorm action-aliases are updated, they are immediately available in the err-stackstorm output.  Filtering by pack name and keyword can be used when looking for help.
      - Access-Control Lists based on any combination of chat username, command and room. ACLs are defined in the errbot configuration file.
-     - Associate StackStorm user credentials with chat usernames.  Client-Side authenticate lets err-stackstorm dynamically map chat user accounts with StackStorm authenicated users via an authenticationn web page.
+     - Associate StackStorm user credentials with chat usernames.  Client-Side authenticate lets err-stackstorm dynamically map chat user accounts with StackStorm authenicated users.  Credentials are passed via an out of band authentication web page.
      - Trigger action-aliases directly from the bot.
      - Support for multiple chat backends, as provided by errbot.
+     - Customise plugin prefix.
+     - Customise StackStorm route key to allow more than one bot to be connected to a single StackStorm instance.
      - Docker image available to get up and running quickly and easily.
      - Python based using modern 3.6 features.
 
 Compatibility
 ==============
 
-The plugin has been developed and tested against the below software combinations. Because you might be running different Python or Errbot versions, we provide here the combinations to achieve optimal operation:
+The plugin has been developed and tested against the below software combinations. Because you might be running different Python or Errbot versions, the below are the optimal combinations:
 
 
    .. csv-table:: Ideal Combination of Versions

diff --git a/docs/index.rst b/docs/index.rst
@@ -8,7 +8,7 @@
 Welcome to err-stackstorm's documentation!
 ==========================================
 
-err-stackstorm is an unofficial community project to bring StackStorm ChatOps to Errbot.
+err-stackstorm is a community project to bring StackStorm ChatOps to Errbot.  No commercial support is provided by StackStorm.
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -48,7 +48,8 @@ Paste the sample configuration below in Errbot's ``config.py`` file adjusting th
         'auth_url': 'https://your.stackstorm.com/auth/v1',
         'api_url': 'https://your.stackstorm.com/api/v1',
         'stream_url': 'https://your.stackstorm.com/stream/v1',
-
+        'route_key': 'errbot',
+        'plugin_prefix': 'st2',
         'verify_cert': True,
         'secrets_store': 'cleartext',
         'api_auth': {
@@ -62,8 +63,7 @@ Paste the sample configuration below in Errbot's ``config.py`` file adjusting th
         'rbac_auth': {
             'standalone': {},
         },
-        'timer_update': 900, #  Unit: second.  Interval to check the user token
-        is still valid.
+        'timer_update': 900, #  Unit: second.  Interval to check the user token is still valid.
     }
 
 

diff --git a/docs/quick_start.rst b/docs/quick_start.rst
@@ -18,7 +18,8 @@ If you are familiar with Errbot and Stackstorm, this guide will get you up and r
         'auth_url': 'https://your.stackstorm.com/auth/v1',
         'api_url': 'https://your.stackstorm.com/api/v1',
         'stream_url': 'https://your.stackstorm.com/stream/v1',
-
+        'route_key': 'errbot',
+        'plugin_prefix': 'st2',
         'verify_cert': True,
         'secrets_store': 'cleartext',
         'api_auth': {
@@ -49,3 +50,5 @@ If you are familiar with Errbot and Stackstorm, this guide will get you up and r
 7. Sending ``!st2help`` to your bot will list the available Stackstorms's aliases.
 
 8. Aliases can be run like this: ``!st2 run date on 192.168.5.1``
+
+.. important:: `st2chatops` does not have to be running on your StackStorm instance. This plugin *replaces* `st2chatops`.
diff --git a/st2.py b/st2.py
@@ -38,6 +38,7 @@
 )
 
 LOG = logging.getLogger("errbot.plugin.st2")
+ERR_STACKSTORM_VERSION = "2.1.2"
 
 
 class St2(BotPlugin):
@@ -73,20 +74,31 @@ def __init__(self, bot, name):
 
         self.run_listener = True
         self.st2events_listener = None
-        self.check_latest_version()
         self.dynamic_commands()
+        self.check_latest_version()
 
     def check_latest_version(self):
         url = "https://raw.githubusercontent.com/nzlosh/err-stackstorm/master/version.json"
-        response = requests.get(url)
-        if response.status_code == 200:
-            latest = response.json.get("version")
-            with open("version.json", "r") as f:
-                buf = f.read()
-                local_version = json.loads(buf)
-                current = local_version.get("version")
-                if current != latest:
-                    LOG.info("A newer version of err-stackstorm is available.")
+        response = requests.get(url, timeout=5)
+
+        if response.status_code != 200:
+            LOG.warning(
+                "Unable to fetch err-stackstorm version from {}. HTTP code: {}".format(
+                    url,
+                    response.status_code
+                )
+            )
+            return True
+
+        latest = response.json().get("version")
+        if latest is None:
+            LOG.warning("Failed to read err-stackstorm 'version' from {}.".format(url))
+            return True
+
+        if ERR_STACKSTORM_VERSION != latest:
+            LOG.info("err-stackstorm can be updated to {}.".format(latest))
+        else:
+            LOG.info("err-stackstorm {} is up to date.".format(ERR_STACKSTORM_VERSION))
 
     def authenticate_bot_credentials(self):
         """