misty 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bdf55abfb46eb97427695bde44d502dbfe21e26b
-  data.tar.gz: b6359b19815a9e30c6c1f5cce091fee7d956e73e
+  metadata.gz: ad9014122c54bf48aae6d26bfc8056ba3eca7e40
+  data.tar.gz: f0e8ad48f12c7011f84f83b460bef8651fdc0eb7
 SHA512:
-  metadata.gz: 77b92ee3e216632d8091f5dfd65bae72e794979d22a5efc3b255b7b214aefa1ebb90f4ed8ecaf1d03c9a8060b1b9734d49a828e587f7ea25e6bc45398b6dd676
-  data.tar.gz: c94d2805b9a0faa2e193d691effb9cc24a3d5b4b876bc8683084e95f3e83bf89e5250c4b7ede4617d8ce5c98fe3af7372ffa4603ea579c77ffe0779c48e6ef8f
+  metadata.gz: 9f59bba8de14cd8657b22db9eff2b63e9ee08abe4f65fba9b8e15015547a5e4d3d3032143389b44cd6c029eb3911a2a9b66056f77445b1860674456d2a72c9c2
+  data.tar.gz: 024efa940ad8cb5ec44ed28effd7fc7a399225a3a7fa592341def537d64492ac24911d480bc3e3351bd389a4ac19a75ae8a71b898e6a00edfdb24a5d9b04849d

data/README.md

@@ -1 +1,222 @@
-# Misty is coming soon!
+# Introduction
+Misty is a HTTP client for OpenStack APIs, aiming to be fast and to provide a flexible and at same time exhaustive
+APIs experience.
+
+## Features
+* Exhaustive and latest Openstack APIs
+* Multiple Service versions
+* Microversions
+* Based upon Net/HTTP
+* Minimalistic gem dependencies - Only json is required
+* Dynamic services by autoloading only required service's version
+* Token automatically refreshed when expired
+* Raw JSON or Ruby format for queries and responses
+* Persistent HTTP connections (default since HTTP 1.1 anyway) but for the authentication bootstrapping
+* Direct HTTP Methods for custom needs
+
+## A solid KISS
+For REST transactions, Misty uses only Net/HTTP from the Ruby Standard Library.  So besides 'json', no other gem are
+required.  
+Because OpenStack authentication and Service Catalog management are very specific and shared by all the APIs, once taken
+care of, there is no need for a complex HTTP framework.  
+This offers a solid foundation with reduced dependencies.
+
+## APIs Definitions
+The rich variety of OpenStack projects requires lots of Application Program Interfaces to handle.  
+Maintaining and extending those APIs is a structural complexity challenge.  
+Therefore the more automated the process, the better.  
+Thanks to the help of Phoenix project, the OpenStack API-ref [1] provides standardization of the OpenStack APIs.  
+The APIs can be processed almost automatically from the API-ref reference manuals (misty-builder).  
+This allows:
+* More consistent APIs using automated control
+* More recent APIs definitions
+* Easier to add APIs
+
+[1] https://developer.openstack.org/api-guide/quick-start/
+
+# Install & Use
+
+## Fetch and install
+``` ruby
+gem install misty
+```
+
+## Quick start
+```ruby
+require 'misty'
+
+auth_v3 = {
+  :url      => "http://localhost:5000",
+  :user     => "admin",
+  :password => "secret",
+  :project  => "admin",
+  :domain   => "default"
+}
+
+openstack = Misty::Cloud.new(:auth => auth_v3)
+
+puts openstack.compute.list_servers.body
+puts openstack.compute.list_flavors.body
+networks = openstack.network.list_networks
+network_id = networks.body["networks"][0]['id']
+network = openstack.network.show_network_details(network_id)
+puts network.body
+```
+
+## Services
+Once the Misty::Cloud object is created, the Openstack services can be used.
+
+The Cloud object authenticates against the identity server (bootstrap process) and obtains the service catalog.
+When an OpenStack API service is used, its endpoint is determined from the catalog and the service is dynamically called
+by Misty so only the services used are loaded.
+
+The service generic name, such as `compute`, is used to submit requests with an OpenStack service API.
+
+ ```ruby
+openstack = Misty::Cloud.new(:auth => { ... })
+openstack.compute.list_servers
+openstack.network.list_networks
+openstack.network.create_network("network": {"name": "my-network"})
+```
+
+To obtain the list of supported services:
+```ruby
+require 'misty'
+puts Misty.services
+```
+
+Which produces the equivalent of the following:  
+
+name | project | versions
+--- | --- | ---
+alarming | aodh | ["v2"]
+baremetal | ironic | ["v1"]
+block_storage | cinder | ["v3", "v1"]
+clustering | senlin | ["v1"]
+compute | nova | ["v2.1"]
+container | magnum | ["v1"]
+data_processing | sahara | ["v1.1"]
+data_protection | karbor | ["v1"]
+database | trove | ["v1.0"]
+dns | designate | ["v2"]
+identity | keystone | ["v3", "v2.0"]
+image | glance | ["v2", "v1"]
+messaging | zaqar | ["v2"]
+metering | ceilometer | ["v2"]
+network | neutron | ["v2.0"]
+object_storage | swift | ["v1"]
+orchestration | heat | ["v1"]
+search | searchlight | ["v1"]
+shared_file_systems | manila | ["v2"]
+
+* Notes  
+  When an Openstack service requires a different service name, the :service_names option can be used (see below).
+
+The #requests method provides the available requests for a service, for example:
+```ruby
+openstack.compute.requests
+```
+
+## Setup
+
+### Authentication
+The URL and credentials details are necessary to authenticate with the identity server (Keystone).
+
+To provide a Keystone V3, which is the default recommended version:
+```ruby
+auth = {
+  :url      => "http://localhost:5000",
+  :user     => "admin",
+  :password => "secret",
+  :project  => "admin",
+  :domain   => "default"
+  }
+}
+```
+Alternatively, for Keystone V2, just provide the tenant details, Misty will detect it's using Keystone V2:
+```ruby
+auth = {
+  :url      => "http://localhost:5000",
+  :user     => "admin",
+  :password => "secret",
+  :tenant   => "admin",
+}
+```
+
+### Global options
+Besides the authentication details, the following options which apply for the whole cloud
+
+* :content_type  
+  Format of the body of the successful HTTP responses to be JSON or Ruby structures.  
+  Value is symbol. Allowed value is `:json`.  
+  By default response body are converted to Ruby structures.
+* :log_file  
+  File name and path for log file.  
+  Value is file path or IO object - Default is `./misty.log`.  
+  For example: use STDOUT for terminal output or alternatively use '/dev/null' to avoid the logs entirely.
+* :log_level  
+  Value is Fixnum - Default is 1 (Logger::INFO) - See Logger from Ruby standard Library
+
+```ruby
+openstack = Misty::Cloud.new(:auth => auth, :content_type => :ruby, :log_file => STDOUT)
+```
+
+### Services Options
+Each service can get options specifically:
+
+```ruby
+openstack = Misty::Cloud.new(:auth => auth, :identity => {}, :compute => {})
+```
+
+The following options are available:
+* :api_version  
+  The latest supported version is used by default. See Misty.services to use another version.  
+  Value is a STRING  
+* :base_path  
+  Allows to force the base path for every URL requests.  
+  Value is a STRING
+* :base_url  
+  Allows to force the base URL for every requests.  
+  Value is a STRING
+* :interface  
+  Allows to provide an alternate interface. Allowed values are "public", "internal" or "admin"  
+  Value is a STRING - Default = "public"
+* :region_id  
+  Value is a STRING  
+  Default "regionOne"
+* :service_names  
+  Value is a STRING - Default is defined by Misty.services  
+  Allows to use a difference name for the service. For instance "identity3" for the identity service.
+* :ssl_verify_mode  
+  Used in SSL mode (detected from the URI)  
+  Value is a BOOLEAN - Default is `true`
+* :version  
+  Version to be used when microversion is supported by the service.  
+  Value is a STRING - Default is `"CURRENT"`  
+  Allowed values are "CURRENT", "LATEST", "SUPPORTED", or a version number such as "2.0" or "3"
+
+Example:
+```ruby
+openstack = Misty::Cloud.new(:auth => auth, :log_level => 0, :identity => {:region_id => "regionTwo"}, :compute => {:version => "2.27", :interface => "admin"})
+```
+
+## Direct REST HTTP Methods
+To send requests directly use the 'get', 'delete', 'post' and 'put' methods directly:
+```ruby
+openstack.network.post("/v2.0/qos/policies/48985e6b8da145699d411f12a3459fca/dscp_marking_rules", data)
+```
+# Requirements
+
+## Ruby versions tested
+* Ruby 2.4.0
+* Ruby 2.3.3
+* Ruby 2.3.0
+* Ruby 2.2.0
+
+# Contributing
+Contributors are welcome and must adhere to the [Contributor covenant code of conduct](http://contributor-covenant.org/).
+
+Please submit issues/bugs and patches on the [Misty repository](https://github.com/flystack/misty).
+
+# Copyright
+Copyright © 2007 Free Software Foundation, Inc. See [LICENSE](LICENSE.md) for details.

data/lib/misty.rb

@@ -0,0 +1,8 @@
+require 'logger'
+require 'json'
+require 'net/http'
+require 'time'
+require 'uri'
+require 'misty/misty'
+require 'misty/autoload'
+require 'misty/cloud'

data/lib/misty/auth.rb

@@ -0,0 +1,60 @@
+module Misty
+  class Auth
+    class AuthenticationError < StandardError; end
+    class CatalogError        < StandardError; end
+    class TokenError          < StandardError; end
+
+    class ExpiryError      < RuntimeError; end
+    class CredentialsError < RuntimeError; end
+    class InitError        < RuntimeError; end
+    class URLError         < RuntimeError; end
+
+    def self.factory(options = {})
+      if options[:project]
+        return Misty::AuthV3.new(options)
+      elsif options[:tenant]
+        return Misty::AuthV2.new(options)
+      else
+        raise CredentialsError, "Cannot identify version from credentials"
+      end
+    end
+
+    attr_reader :catalog
+
+    def initialize(options)
+      raise CredentialsError unless credentials_valid?(options)
+      @credentials = scoped_credentials(options)
+      raise URLError, "No URL provided" unless options[:url] && !options[:url].empty?
+      @uri = URI.parse(options[:url])
+      @token = nil
+      setup(authenticate)
+      raise CatalogError, "No catalog provided during authentication" if @catalog.empty?
+    end
+
+    def authenticate
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      response = http.post(self.class.path, @credentials.to_json, Misty::HEADER_JSON)
+      raise AuthenticationError, "Response code=#{response.code}, Msg=#{response.msg}" unless response.code =~ /200|201/
+      response
+    end
+
+    def expired?
+      raise ExpiryError, "Missing token expiration data" if @expires.nil? || @expires.empty?
+      Time.parse(@expires) < Time.now.utc
+    end
+
+    def get_endpoint(service_names, region, interface)
+      @catalog.each do |catalog|
+        if service_names.include? catalog["type"]
+          return catalog_endpoints(catalog["endpoints"], region, interface)
+        end
+      end
+      raise CatalogError, "No service found with either #{service_names} name, region #{region}, interface #{interface}"
+    end
+
+    def get_token
+      authenticate if expired?
+      @token
+    end
+  end
+end

data/lib/misty/auth/auth_v2.rb

@@ -0,0 +1,46 @@
+require 'misty/auth'
+
+module Misty
+  class AuthV2 < Misty::Auth
+    def self.path
+      "/v2.0/tokens"
+    end
+
+    def catalog_endpoints(endpoints, region, interface)
+      endpoints.each do |endpoint|
+        if endpoint["region"] == region && endpoint["#{interface}URL"]
+          return endpoint["#{interface}URL"]
+        end
+      end
+    end
+
+    def credentials_valid?(creds)
+      true if creds[:user] && creds[:password] && creds[:tenant]
+    end
+
+    def get_endpoint_url(endpoints, region, interface)
+      endpoint = endpoints.select { |ep| !ep[interface].empty? }
+      raise CatalogError, "No endpoint available for region '#{region}' and interface '#{interface}'" unless endpoint
+      endpoint[0][interface]
+    end
+
+    def setup(response)
+      payload = JSON.load(response.body)
+      @token   = payload["access"]["token"]["id"]
+      @catalog = payload["access"]["serviceCatalog"]
+      @expires = payload["access"]["token"]["expires"]
+    end
+
+    def scoped_credentials(creds)
+      {
+        "auth": {
+          "passwordCredentials": {
+            "username": creds[:user],
+            "password": creds[:password]
+          },
+          "tenantName": creds[:tenant]
+        }
+      }
+    end
+  end
+end

data/lib/misty/auth/auth_v3.rb

@@ -0,0 +1,58 @@
+require 'misty/auth'
+
+module Misty
+  class AuthV3 < Misty::Auth
+    def self.path
+      "/v3/auth/tokens"
+    end
+
+    def catalog_endpoints(endpoints, region, interface)
+      endpoints.each do |endpoint|
+        if endpoint["region_id"] == region && endpoint["interface"] == interface
+          return endpoint["url"]
+        end
+      end
+    end
+
+    def credentials_valid?(creds)
+      true if creds[:user] && creds[:password] && creds[:project]
+    end
+
+    def get_endpoint_url(endpoints, region, interface)
+      endpoint = endpoints.select { |ep| ep["region_id"] == region && ep["interface"] == interface }
+      raise CatalogError, "No endpoint available for region '#{region}' and interface '#{interface}'" unless endpoint
+      endpoint[0]["url"]
+    end
+
+    def setup(response)
+      payload = JSON.load(response.body)
+      @token = response["x-subject-token"]
+      @catalog = payload["token"]["catalog"]
+      @expires = payload["token"]["expires_at"]
+    end
+
+    def scoped_credentials(creds)
+      creds[:domain] ||= "default"
+      {
+        "auth": {
+          "identity": {
+            "methods": ["password"],
+            "password": {
+              "user": {
+                "name": creds[:user],
+                "domain": { "id": "default" },
+                "password": creds[:password]
+              }
+            }
+          },
+          "scope": {
+            "project": {
+              "name": creds[:project],
+              "domain": { "id": creds[:domain] }
+            }
+          }
+        }
+      }
+    end
+  end
+end

data/lib/misty/autoload.rb

@@ -0,0 +1,82 @@
+module Misty
+  module Openstack
+    module Aodh
+      autoload :V2, "misty/openstack/aodh/v2"
+    end
+
+    module Ceilometer
+      autoload :V2, "misty/openstack/ceilometer/v2"
+    end
+
+    module Cinder
+      autoload :V1, "misty/openstack/cinder/v1"
+      autoload :V3, "misty/openstack/cinder/v3"
+    end
+
+    module Designate
+      autoload :V2, "misty/openstack/designate/v2"
+    end
+
+    module Glance
+      autoload :V1, "misty/openstack/glance/v1"
+      autoload :V2, "misty/openstack/glance/v2"
+    end
+
+    module Heat
+      autoload :V1, "misty/openstack/heat/v1"
+    end
+
+    module Ironic
+      autoload :V1, "misty/openstack/ironic/v1"
+    end
+
+    module Karbor
+      autoload :V1, "misty/openstack/karbor/v1"
+    end
+
+    module Keystone
+      autoload :V3,   "misty/openstack/keystone/v3"
+      autoload :V2_0, "misty/openstack/keystone/v2_0"
+    end
+
+    module Magnum
+      autoload :V1, "misty/openstack/magnum/v1"
+    end
+
+    module Manila
+      autoload :V2, "misty/openstack/manila/v2"
+    end
+
+    module Neutron
+      autoload :V2_0, "misty/openstack/neutron/v2_0"
+    end
+
+    module Nova
+      autoload :V2_1, "misty/openstack/nova/v2_1"
+    end
+
+    module Sahara
+      autoload :V1_1, "misty/openstack/sahara/v1_1"
+    end
+
+    module Searchlight
+      autoload :V1, "misty/openstack/searchlight/v1"
+    end
+
+    module Senlin
+      autoload :V1, "misty/openstack/senlin/v1"
+    end
+
+    module Swift
+      autoload :V1, "misty/openstack/swift/v1"
+    end
+
+    module Trove
+      autoload :V1_0, "misty/openstack/trove/v1_0"
+    end
+
+    module Zaqar
+      autoload :V2, "misty/openstack/zaqar/v2"
+    end
+  end
+end