Update worker documentation.

Make some corrections and add some preliminary docs for worker messages.

Change-Id: I603bac7e674c2ab667a3e9bb523d8f1c01292563

doc/worker/about.rst

@@ -77,12 +77,7 @@ directory where the PID file will be (:option:`--pid <libra_worker.py -p>`
 option) and the directory where the log files will be written
 (:option:`--logfile <libra_worker.py -l>` option) exists and is writable
 by the user/group specified with the :option:`--user <libra_worker.py --user>`
-and :option:`--group <libra_worker.py --group>` options. Also, the
+and :option:`--group <libra_worker.py --group>` options.
-Python module used to start the daemon process does not like it when the PID
-file already exists at startup.
-
-    **IF THE WORKER IMMEDIATELY EXITS WHEN STARTED IN DAEMON MODE, AND NO ERROR
-    MESSAGES ARE IN THE LOG, ONE OF THESE REASONS IS THE MOST LIKELY CAUSE!**
 
 You can verify that the worker is running by using the sample Gearman
 client in the bin/ directory::

doc/worker/code.rst

@@ -73,8 +73,9 @@ LoadBalancerDriver Class
 
    Generally, an appliance driver should queue up any configuration changes
    made via these API calls until the :py:meth:`create` method is called.
-   The :py:meth:`suspend`, :py:meth:`enable`, and :py:meth:`delete` methods
+   The :py:meth:`suspend`, :py:meth:`enable`, :py:meth:`delete`,
-   should take immediate action.
+   :py:meth:`get_stats()` and :py:meth:`archive` methods should take
+   immediate action.
 
    .. py:method:: init()
 
@@ -94,6 +95,8 @@ LoadBalancerDriver Class
 
    .. py:method:: get_stats()
 
+   .. py:method:: archive()
+
 Known Load Balancer Drivers Dictionary
 --------------------------------------
 

doc/worker/index.rst

@@ -6,3 +6,4 @@ Libra Gearman Worker
 
    about
    code
+   messages

doc/worker/messages.rst

@@ -0,0 +1,275 @@
+Worker Messages
+===============
+
+.. py:module:: libra.worker.controller
+
+The worker expects several different types of JSON messages. Below are examples
+of each. The :py:class:`~LBaaSController` class expects the messages to be
+one of the types defined below.
+
+Some things in common with all messages:
+
+* The type is determined by the **hpcs_action**
+  field of the JSON message, which is required to be present.
+* The casing of the JSON field names or values does not matter.
+* Extraneous fields are ignored.
+* Every response will return the original message with some additional fields.
+* Every response will include a **hpcs_response** field with a value of either
+  *PASS* or *FAIL*. Additional fields will vary depending on message type.
+
+
+UPDATE Message
+--------------
+
+The UPDATE message creates or updates the load balancer configuration.
+Either one or two load balancers may be defined within this message. If two
+are defined, one must be with the HTTP protocol and the other must be with
+the TCP protocol. No other exceptions are allowed.
+
+Required Fields
+^^^^^^^^^^^^^^^
+
+* hpcs_action
+* loadbalancers
+* loadbalancers.protocol
+* loadbalancers.nodes
+* loadbalancers.nodes.address
+* loadbalancers.nodes.port
+
+Example Request
+^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "UPDATE",
+    "loadbalancers": [
+      {
+        "name": "a-new-loadbalancer",
+        "protocol": "http",
+        "nodes": [
+          {
+            "address": "10.0.0.1",
+            "port": "80",
+            "weight": "1"
+          }
+        ]
+      }
+    ]
+  }
+
+Example Response
+^^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "UPDATE",
+    "loadbalancers": [
+      {
+        "name": "a-new-loadbalancer",
+        "protocol": "http",
+        "nodes": [
+          {
+            "address": "10.0.0.1",
+            "port": "80",
+            "weight": "1"
+          }
+        ]
+      }
+    ],
+    "hpcs_response": "PASS"
+  }
+
+
+SUSPEND Message
+---------------
+
+The SUSPEND message will temporarily disable a load balancer until it is
+reenabled with an ENABLE message.
+
+Required Fields
+^^^^^^^^^^^^^^^
+
+* hpcs_action
+
+Example Request
+^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "SUSPEND"
+  }
+
+Example Response
+^^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "SUSPEND",
+    "hpcs_response": "PASS"
+  }
+
+
+ENABLE Message
+--------------
+
+The ENABLE message will reenable a previously suspsended load balancer.
+
+Required Fields
+^^^^^^^^^^^^^^^
+
+* hpcs_action
+
+Example Request
+^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "ENABLE"
+  }
+
+Example Response
+^^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "ENABLE",
+    "hpcs_response": "PASS"
+  }
+
+
+DELETE Message
+--------------
+
+The DELETE message will permanently disable a load balancer. This process
+is not expected to be reversible.
+
+Required Fields
+^^^^^^^^^^^^^^^
+
+* hpcs_action
+
+Example Request
+^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "DELETE"
+  }
+
+Example Response
+^^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "DELETE",
+    "hpcs_response": "PASS"
+  }
+
+
+DISCOVER Message
+----------------
+
+The DISCOVER message allows a sender (i.e., API server) to discover the version
+of a running worker process. The version can then be used to decide which
+messages are supported.
+
+A **version** field will be returned in the JSON message.
+
+Required Fields
+^^^^^^^^^^^^^^^
+
+* hpcs_action
+
+Example Request
+^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "DISCOVER"
+  }
+
+Example Response
+^^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "DISCOVER",
+    "version": "1.0",
+    "hpcs_response": "PASS"
+  }
+
+
+ARCHIVE Message
+---------------
+
+The ARCHIVE message requests that the load balancer send any available logs
+to a destination defined within the request. Currently, the only supported
+destination is a Swift account.
+
+If the request fails, **hpcs_response** will be set to *FAIL* and a field
+named **hpcs_error** will be added with an error message explaining the
+failure.
+
+Required Fields
+^^^^^^^^^^^^^^^
+
+* hpcs_action
+* hpcs_object_store_type
+* hpcs_object_store_basepath
+* hpcs_object_store_endpoint
+* hpcs_object_store_token
+* loadbalancers
+* loadbalancers.protocol
+
+Example Request
+^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "ARCHIVE",
+    "hpcs_object_store_basepath": "lbaaslogs",
+    "hpcs_object_store_endpoint": "https://example.com/v1/80074562416143",
+    "hpcs_object_store_token": "MY_AUTH_TOKEN",
+    "hpcs_object_store_type": "swift",
+    "loadbalancers": [
+        {
+            "id": "15",
+            "name": "lb #1",
+            "protocol": "HTTP"
+        }
+    ]
+  }
+
+Example Response
+^^^^^^^^^^^^^^^^
+
+.. code-block:: json
+
+  {
+    "hpcs_action": "ARCHIVE",
+    "hpcs_object_store_basepath": "lbaaslogs",
+    "hpcs_object_store_endpoint": "https://example.com/v1/80074562416143",
+    "hpcs_object_store_token": "MY_AUTH_TOKEN",
+    "hpcs_object_store_type": "swift",
+    "loadbalancers": [
+        {
+            "id": "15",
+            "name": "lb #1",
+            "protocol": "HTTP"
+        }
+    ]
+    "hpcs_response": "FAIL",
+    "hpcs_error": "Some error string explaining the failure."
+  }
+