MuranoCLI 2.2.4 → 3.0.0

data/TODO.taskpaper

@@ -10,8 +10,8 @@ Commands:
 	- Empty sub-commands should return help. @done(2016-11-21)
 	There are a bunch of empty sub-commands that prefix another layer. Such as
 	assign, content, product, and others.  Those should be impemented as a ‘help’
-	only command.  That is they should return help like the plain `mr` command, but
-	just for their sub-section of things
+	only command.  That is they should return help like the plain `murano` command,
+	but just for their sub-section of things
 	- Errors and Warnings should get sent to STDERR @done(2016-11-03)
 	- Need a more consistent output format. 'pp' is still used in many places. @done(2016-11-03)
 	Maybe have a tool setting for output format? json, yaml, pp, csv, table ?

data/bin/murano

@@ -1,71 +1,61 @@
 #!/usr/bin/env ruby
+# Last Modified: 2017.08.16 /coding: utf-8
+# frozen_string_literal: true
+
+# Copyright © 2016-2017 Exosite LLC.
+# License: MIT. See LICENSE.txt.
+#  vim:tw=0:ts=2:sw=2:et:ai
 
-require 'rubygems'
 require 'commander/import'
+require 'dotenv'
+require 'highline'
 require 'pathname'
+#require 'pp'
+require 'rainbow'
+require 'rubygems'
 require 'MrMurano'
-require 'pp'
-require 'dotenv'
+require 'MrMurano/Config'
+require 'MrMurano/ProjectFile'
+
+# DEVs: Store environs in an .env file that gets loaded here. Alternatively,
+#   run a Bash or similar script before you start developing.
 Dotenv.load
 
-Signal.trap('INT', 'EXIT') # Don't drop traces on ^C
+# Don't drop traces on ^C.
+# EXPLAIN/2017-06-30: [lb] not sure what "drop traces" means.
+#   What happens if we don't trap Ctrl-C?
+# NOTE: The second parameter is either a string, or a command or block to
+#   call or run. Ruby honors certain special strings, like 'EXIT':
+#   "If the command is “EXIT”, the script will be terminated by the signal."
+#   Per https://ruby-doc.org/core-2.2.0/Signal.html
+Signal.trap('INT', 'EXIT')
 
 program :version, MrMurano::VERSION
-program :description, %{Manage a Solution and Product in Exosite's Murano}
 
-global_option('-V', '--verbose', 'Be chatty') {
-  $cfg['tool.verbose'] = true
-}
-global_option('-n', '--dry', %{Don't run actions that make changes}) {
-  $cfg['tool.dry'] = true
-  $cfg['tool.verbose'] = true # dry implies verbose
-}
-global_option('-L', '--curl', 'Print out a curl command for each network call') {
-  $cfg['tool.curldebug'] = true
-}
-global_option '--skip-plugins', %{Don't load plugins. Good for when one goes bad.}
+program :description, %(
+  Manage Applications and Products in Exosite's Murano
+).strip
 
-global_option('-C', '--configfile FILE', %{Load additional configuration file}) {|file|
-  # this is called after all of the top level code in this file.
-  $cfg.load_specific(file)
-}
-global_option('-c', '--config KEY=VALUE', %{Set a single config key}) {|param|
-  key, value = param.split('=', 2)
-  # a=b :> ["a","b"]
-  # a= :> ["a",""]
-  # a :> ["a"]
-  raise "Bad config '#{param}'" if key.nil?
-  if value.nil? then
-    $cfg[key] = 'true'
-  else
-    $cfg[key] = value
-  end
-}
+# The Commander defaults to paged help.
+# The user can disable with --no-page, e.g.,
+#   alias murano='murano --no-page'
+if ARGV.include?('--no-page')
+  program :help_paging, false
+  ARGV.delete('--no-page')
+end
 
 default_command :help
-#default_command :syncup
 
-$cfg = MrMurano::Config.new
-$cfg.load
-$project = MrMurano::ProjectFile.new
-$project.load
-
-# Basic command support is:
-# - read/write config file in [Project, User, System] (all are optional)
-# - TODO: Introspection for tab completion.
-# - TODO: Look for tools in PATH that are +x and "mr-foo..."
-
-
-# Look for plug-ins
+# Look for plug-ins.
 pgds = [
   Pathname.new(Dir.home) + '.mrmurano' + 'plugins',
-  Pathname.new(Dir.home) + '.murano' + 'plugins'
+  Pathname.new(Dir.home) + '.murano' + 'plugins',
 ]
 # Add plugin dirs from configs
 # This is run before the command line options are parsed, so need to check old way.
-if not ARGV.include? '--skip-plugins' then
-  pgds << Pathname.new(ENV['MR_MURANO_PLUGIN_DIR']) if ENV.has_key? 'MR_MURANO_PLUGIN_DIR'
-  pgds << Pathname.new(ENV['MURANO_PLUGIN_DIR']) if ENV.has_key? 'MURANO_PLUGIN_DIR'
+unless ARGV.include? '--skip-plugins'
+  pgds << Pathname.new(ENV['MR_MURANO_PLUGIN_DIR']) if ENV.key? 'MR_MURANO_PLUGIN_DIR'
+  pgds << Pathname.new(ENV['MURANO_PLUGIN_DIR']) if ENV.key? 'MURANO_PLUGIN_DIR'
   pgds.each do |path|
     next unless path.exist?
     path.each_child do |plugin|
@@ -74,11 +64,20 @@ if not ARGV.include? '--skip-plugins' then
       next if plugin.basename.fnmatch('.*') # don't read anything starting with .
       begin
         require plugin.to_s
-      rescue Exception => e
-        $stderr.puts "Failed to load plugin at #{plugin} because #{e}"
+      #rescue Exception => err
+      rescue StandardError => err
+        $stderr.puts "Failed to load plugin at #{plugin} because #{err}"
       end
     end
   end
 end
 
-#  vim: set ai et sw=2 ts=2 :
+# Look for .murano/config files.
+$cfg = MrMurano::Config.new(::Commander::Runner.instance)
+$cfg.load
+$cfg.validate_cmd
+
+# Look for a (legacy) Solutionfile.json.
+$project = MrMurano::ProjectFile.new
+$project.load
+

data/docs/basic_example.rst

@@ -0,0 +1,436 @@
+#######################
+Basic MuranoCLI Example
+#######################
+
+Learn Murano the Easy Way
+=========================
+
+This document illustrates how to setup a very basic Murano project.
+
+It shows how to use the Murano CLI tool (also called "MuranoCLI", or
+just "MurCLI") to create an Application and Product, and how to send
+data to the Product that gets processed by the Application.
+
+Prerequisites
+=============
+
+It is assumed that you have already created a Murano business account,
+and that you have installed MurCLI on your local machine.
+
+- To sign up for a free Murano business account, visit:
+
+  https://exosite.com/signup/
+
+- To install MurCLI, run:
+
+  ``gem install MuranoCLI``
+
+If you need installation help, look at the `README
+<https://github.com/exosite/MuranoCLI#install>`__.
+
+Start Fresh
+===========
+
+You can skip this section if you've never setup a business before.
+
+But if you've already created a business, and if you've already
+created an Application and/or Product for it, you can clean up
+that business so we can start over.
+
+First, list your businesses and find the one you want to reset. E.g.,
+
+.. code-block:: text
+
+    $ murano business list
+
+    +------------------+-------+-------------------+
+    | bizid            | role  | name              |
+    +------------------+-------+-------------------+
+    | 4o54fc55olth85mi | owner | My First Business |
+    | fu5rse4xdww2ke29 | admin | Collaborative Biz |
+    | ct7rmoz3hu34ygb9 | owner | Another of My Biz |
+    +------------------+-------+-------------------+
+
+NOTE: If you have never used MurCLI before, or if you've logged out
+of Murano, MurCLI will tell you to logon first. E.g.,
+
+.. code-block:: text
+
+    $ murano business list
+
+    No Murano user account found.
+    Please login using `murano login` or `murano init`.
+    Or set your password with `murano password set <username>`.
+
+Next, remove all solutions (Applications and Products) from that project.
+
+.. code-block:: text
+
+    $ murano solutions expunge -y -c business.id=ct7rmoz3hu34ygb9
+
+    Deleted 2 solutions
+
+Logout of Murano. This removes your username and password so
+that MurCLI will ask you to reenter your username and password.
+
+.. code-block:: text
+
+    $ murano logout
+
+You might also have environment variables set. Clear those for
+the sake of this walk-through.
+
+.. code-block:: text
+
+    $ export MURANO_CONFIGFILE=
+    $ export MURANO_PASSWORD=
+
+Create a New Project
+====================
+
+Create a new directory for your project.
+
+.. code-block:: text
+
+    $ mkdir ~/murano/projects/basic_test
+
+    $ cd ~/murano/projects/basic_test
+
+You can run MurCLI commands now, but they won't be useful until you ``init``. E.g.,
+
+.. code-block:: text
+
+    $ murano show
+
+    No Murano user account found.
+    Please login using `murano login` or `murano init`.
+    Or set your password with `murano password set <username>`.
+
+Run the init command to easily wire the new project to your existing business,
+to create an Application and Product, and to setup local directories and files.
+
+The init command will link the Product to the Application so that data sent
+to the Product is passed along to the Application.
+
+Here's an example use of the init command.
+
+.. code-block:: text
+
+    $ murano init
+
+    Creating project at /user/home/murano/projects/basic_test
+
+    No Murano user account found. Please login.
+    User name: exositement@exosite.com
+    Password: *************
+    1. My First Business  2. Collaborative Biz  3. Another of My Biz
+    Please select the Business to use:
+    3
+
+    This business does not have any applications. Let's create one
+
+    Please enter the Application name: basicexample
+
+    Created new Application: basicexample <v3sl941hifticggc0>
+
+    This business does not have any products. Let's create one
+
+    Please enter the Product name: exampleprod
+
+    Created new Product: exampleprod <n51cq3fea5zc40cs4>
+
+    Linked ‘exampleprod’ to ‘basicexample’
+
+    Created default event handler
+
+    Writing Project file to basictest.murano
+
+    Created default directories
+
+    Synced 4 items
+
+    Success!
+
+             Business ID: ct7rmoz3hu34ygb9
+          Application ID: v3sl941hifticggc0
+              Product ID: n51cq3fea5zc40cs4
+
+You'll notice that ``init`` downloaded a few files from Murano that are
+automatically created when you create solutions and link them.
+
+For instance, you should see a handful of Lua scripts in the ``services``
+directory.
+
+.. code-block:: text
+
+    $ ls services
+
+    n51cq3fea5zc40cs4_event.lua  timer_timer.lua  tsdb_exportJob.lua  user_account.lua
+
+Update the Data Event Handler
+=============================
+
+Let's edit the Product data event handler so that it spits out a log message
+when it gets data from the Product. The event handler is named using the
+Product ID, so grab that, and use the ID to make the name of the Lua script.
+
+.. code-block:: text
+
+    $ PRODUCT_ID=$(murano config product.id)
+
+    $ PROD_EVENT="services/${PRODUCT_ID}_event.lua"
+
+    $ echo ${PROD_EVENT}
+
+    services/n51cq3fea5zc40cs4_event.lua
+
+You'll notice that Murano already created a simple event handler.
+
+.. code-block:: text
+
+    $ cat ${PROD_EVENT}
+
+    --#EVENT n51cq3fea5zc40cs4 event
+    print(event)
+
+Now, overwrite the event handler with something similar. We just
+want to show how easy it is to update the event handler.
+
+.. code-block:: text
+
+    $ cat > ${PROD_EVENT} << EOF
+    --#EVENT ${PRODUCT_ID} event
+    print("EVENT: " .. to_json(event))
+    EOF
+
+NOTE: The ``--#EVENT`` header is mandatory. It tells Murano
+how to interpret the snippet of Lua code.
+
+If you run the ``status`` command, you should see that there's now one
+file modified locally (the event handler that we just edited) that is
+not synced with the corresponding event handler on Murano.
+
+.. code-block:: text
+
+    $ murano status
+
+    Nothing new locally
+    Nothing new remotely
+    Items that differ:
+     M E  services/n51cq3fea5zc40cs4_event.lua
+
+Run the ``syncup`` command to upload any modified files to Murano,
+overwriting what is on Murano.
+
+.. code-block:: text
+
+    $ murano syncup
+
+Create and Provision a New Device
+=================================
+
+In order to do something useful, we need to create a device,
+that is attached to the Product, that can generate data.
+
+You'll notice that the new Product does not have any devices.
+
+.. code-block:: text
+
+    $ murano device list
+
+    Did not find any devices
+
+Create a device. We can use whatever identifier we want, so
+just grab a random UUID.
+
+.. code-block:: text
+
+    $ SOME_ID=$(uuidgen)
+
+    $ murano device enable ${SOME_ID}
+
+    $ murano device list
+
+    +--------------------------------------+-------------+--------+
+    | Identifier                           | Status      | Online |
+    +--------------------------------------+-------------+--------+
+    | 1af384dd-57ba-4f13-9d89-45dbcbf207de | whitelisted | false  |
+    +--------------------------------------+-------------+--------+
+
+Provision the device. Murano generates and returns a CIK
+that we need to remember so that we can authenticate as
+the device when making calls on its behalf.
+
+.. code-block:: text
+
+    $ CIK=$(murano product device activate ${SOME_ID})
+
+    $ echo ${CIK}
+
+    MJzNuMqPDs7UADLriMlHK10dClv7cx46uLSkJLSw
+
+    $ murano device list
+
+    +--------------------------------------+-------------+--------+
+    | Identifier                           | Status      | Online |
+    +--------------------------------------+-------------+--------+
+    | 1af384dd-57ba-4f13-9d89-45dbcbf207de | provisioned | false  |
+    +--------------------------------------+-------------+--------+
+
+Generate Device Data
+====================
+
+Each solution (Application or Product) has its own URI.
+We need the Product's URI in order to interact with Murano
+on behalf of the device.
+
+Make a local variable for the Product URI.
+
+.. code-block:: text
+
+    $ PRODUCT_URI=$(murano domain product --brief --no-progress)
+
+NOTE: We need to use the ``--no-progress`` option, otherwise MurCLI
+will display a progress bar that contaminates the captured output.
+
+Write data to the device. E.g., let's write a very cold temperature value.
+
+.. code-block:: text
+
+    $ curl -si -k https://${PRODUCT_URI}/onep:v1/stack/alias \
+        -H "X-Exosite-CIK: ${CIK}" \
+        -H "Accept: application/x-www-form-urlencoded; charset=utf-8" \
+        -d reports='{"temperature": -40.0}' \
+        -i -v -w "%{http_code}"
+
+    [VERBOSE OUTPUT OMITTED]
+    204
+
+Verify that the data was passed from the Product to the Application and
+processed how we indicated in the event handler (which is to log it).
+
+.. code-block:: text
+
+    $ murano logs --application
+
+    DEBUG [n51cq3fea5zc40cs4_event] 2017-07-26T11:44:57.000-05:00:
+    EVENT: {
+        "connection_id":"D2bzFD6HSV3ih56dbswY",
+        "identity":"1af384dd-57ba-4f13-9d89-45dbcbf207de",
+        "ip":"123.234.012.234",
+        "protocol":"onep",
+        "timestamp":1.501087497424287e+15,
+        "type":"provisioned"
+        }
+
+    DEBUG [n51cq3fea5zc40cs4_event] 2017-07-26T14:09:30.000-05:00:
+    EVENT: {
+        "connection_id":"QWJeZcpXej5h5f5hwdLY",
+        "identity":"1af384dd-57ba-4f13-9d89-45dbcbf207de",
+        "ip":"123.234.012.234",
+        "payload":[{
+            "timestamp":1.501096170486053e+15,
+            "values":{
+                "reports":"{\"temperature\": -40.0}"}
+        }],
+        "protocol":"onep",
+        "timestamp":1.501096170487898e+15,
+        "type":"data_in"
+        }
+
+Success! You should see the ``temperature`` value in the last log message.
+
+You'll notice that the Product does not generate any log messages.
+
+.. code-block:: text
+
+    $ murano logs --product
+
+    # [NO OUTPUT]
+
+Create a Resource
+=================
+
+Bonus step! Create a resource for your data.
+
+NOTE: The write operation works regardless of having a resource defined.
+
+Create a resources file that describes the data. E.g.,
+
+.. code-block:: text
+
+    $ cat > specs/resources.yaml << EOF
+    ---
+    temperature:
+      allowed: []
+      format: number
+      settable: false
+      unit: ''
+    EOF
+
+Upload the resources to Murano.
+
+.. code-block:: text
+
+    $ murano syncup
+
+And write more data.
+
+.. code-block:: text
+
+    $ curl -si -k https://${PRODUCT_URI}/onep:v1/stack/alias \
+        -H "X-Exosite-CIK: ${CIK}" \
+        -H "Accept: application/x-www-form-urlencoded; charset=utf-8" \
+        -d raw_data='{"temperature": -19.9}' \
+        -i -v -w "%{http_code}"
+
+Verify that you see a new event in the log.
+
+.. code-block:: text
+
+    $ murano logs --application
+
+    DEBUG [n51cq3fea5zc40cs4_event] 2017-07-26T11:44:57.000-05:00:
+    EVENT: {
+        "connection_id":"D2bzFD6HSV3ih56dbswY",
+        "identity":"1af384dd-57ba-4f13-9d89-45dbcbf207de",
+        "ip":"123.234.012.234",
+        "protocol":"onep",
+        "timestamp":1.501087497424287e+15,
+        "type":"provisioned"
+        }
+
+    DEBUG [n51cq3fea5zc40cs4_event] 2017-07-26T14:09:30.000-05:00:
+    EVENT: {
+        "connection_id":"QWJeZcpXej5h5f5hwdLY",
+        "identity":"1af384dd-57ba-4f13-9d89-45dbcbf207de",
+        "ip":"123.234.012.234",
+        "payload":[{
+            "timestamp":1.501096170486053e+15,
+            "values":{
+                "reports":"{\"temperature\": -40.0}"}
+        }],
+        "protocol":"onep",
+        "timestamp":1.501096170487898e+15,
+        "type":"data_in"
+        }
+
+    DEBUG [n51cq3fea5zc40cs4_event] 2017-07-26T14:16:00.000-05:00:
+    EVENT: {
+        "connection_id":"3DD9rAZ95bgro5O0kGGD",
+        "identity":"1af384dd-57ba-4f13-9d89-45dbcbf207de",
+        "ip":"123.234.012.234",
+        "payload":[{
+            "timestamp":1.501096560116624e+15,
+            "values":{
+                "raw_data":"{\"temperature\": -19.9}"}
+        }],
+        "protocol":"onep",
+        "timestamp":1.501096560118335e+15,
+        "type":"data_in"
+        }
+
+*Et Voilà!*
+
+Congratulations of your first, very basic Murano project!
+