haveapi 0.6.0 → 0.7.0

data/haveapi.gemspec

@@ -5,7 +5,7 @@ require 'haveapi/version'
 Gem::Specification.new do |s|
   s.name        = 'haveapi'
   s.version     = HaveAPI::VERSION
-  s.date        = '2016-10-18'
+  s.date        = '2016-11-24'
   s.summary     =
   s.description = 'Framework for creating self-describing APIs'
   s.authors     = 'Jakub Skokan'
@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.files       = `git ls-files -z`.split("\x0")
   s.license     = 'MIT'
 
-  s.required_ruby_version = '~> 2.0'
+  s.required_ruby_version = '>= 2.0.0'
 
   s.add_runtime_dependency 'require_all'
   s.add_runtime_dependency 'json'
@@ -24,4 +24,6 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rake'
   s.add_runtime_dependency 'github-markdown', '~> 0.6.9'
   s.add_runtime_dependency 'nesty', '~> 1.0.2'
+  s.add_runtime_dependency 'haveapi-client', '~> 0.6.0'
+  s.add_runtime_dependency 'mail'
 end

data/lib/haveapi.rb

@@ -10,18 +10,20 @@ require 'github/markdown'
 require 'json'
 
 module HaveAPI
-  module Actions
-  end
+  module Resources ; end
+  module Actions ; end
 end
 
 require_relative 'haveapi/params'
 require_rel 'haveapi/parameters/'
 require_rel 'haveapi/*.rb'
+require_rel 'haveapi/actions/*.rb'
+require_rel 'haveapi/resources/*.rb'
 require_rel 'haveapi/model_adapters/hash'
 require_rel 'haveapi/model_adapters/active_record' if ar
 require_rel 'haveapi/authentication'
-require_rel 'haveapi/actions/*.rb'
 require_rel 'haveapi/output_formatters/base.rb'
 require_rel 'haveapi/output_formatters/'
 require_rel 'haveapi/validators/'
+require_rel 'haveapi/client_examples/'
 require_rel 'haveapi/extensions'

data/lib/haveapi/action.rb

@@ -8,13 +8,14 @@ module HaveAPI
     has_attr :http_method, :get
     has_attr :auth, true
     has_attr :aliases, []
+    has_attr :blocking, false
 
     include Hookable
 
     has_hook :exec_exception,
         desc: 'Called when unhandled exceptions occurs during Action.exec',
         args: {
-            action: 'HaveAPI::Action instance',
+            context: 'HaveAPI::Context instance',
             exception: 'exception instance',
         },
         ret: {
@@ -86,6 +87,17 @@ module HaveAPI
         model_adapter(input.layout).used_by(:input, self)
         model_adapter(output.layout).used_by(:output, self)
 
+        if blocking
+          meta(:global) do
+            output do
+              integer :action_state_id,
+                  label: 'Action state ID',
+                  desc: 'ID of ActionState object for state querying. When null, the action '+
+                        'is not blocking for the current invocation.'
+            end
+          end
+        end
+
         if @meta
           @meta.each_value do |m|
             next unless m
@@ -193,6 +205,7 @@ module HaveAPI
             auth: @auth,
             description: @desc,
             aliases: @aliases,
+            blocking: @blocking ? true : false,
             input: @input ? @input.describe(context) : {parameters: {}},
             output: @output ? @output.describe(context) : {parameters: {}},
             meta: @meta ? @meta.merge(@meta) { |_, v| v && v.describe(context) } : nil,
@@ -319,7 +332,7 @@ module HaveAPI
           pre_exec
           exec
         rescue Exception => e
-          tmp = call_class_hooks_as_for(Action, :exec_exception, args: [self, e])
+          tmp = call_class_hooks_as_for(Action, :exec_exception, args: [@context, e])
 
           if tmp.empty?
             p e.message
@@ -327,7 +340,9 @@ module HaveAPI
             error('Server error occurred')
           end
 
-          error(tmp[:message]) unless tmp[:status]
+          unless tmp[:status]
+            error(tmp[:message], {}, http_status: tmp[:http_status] || 500)
+          end
         end
       end
 
@@ -392,6 +407,10 @@ module HaveAPI
               safe_ret = ret
           end
 
+          if self.class.blocking
+            @reply_meta[:global][:action_state_id] = state_id
+          end
+
           ns = {output.namespace => safe_ret}
           ns[Metadata.namespace] = @reply_meta[:global] unless meta[:no]
 
@@ -402,7 +421,7 @@ module HaveAPI
         end
 
       else
-        [false, @message, @errors]
+        [false, @message, @errors, @http_status]
       end
     end
 
@@ -475,13 +494,22 @@ module HaveAPI
       ret
     end
 
-    def ok(ret={})
+    # @param ret [Hash] response
+    # @param opts [Hash] options
+    # @option opts [Integer] http_status HTTP status code sent to the client
+    def ok(ret = {}, opts = {})
+      @http_status = opts[:http_status]
       throw(:return, ret)
     end
 
-    def error(msg, errs={})
+    # @param msg [String] error message sent to the client
+    # @param errs [Hash<Array>] parameter errors sent to the client
+    # @param opts [Hash] options
+    # @option opts [Integer] http_status HTTP status code sent to the client
+    def error(msg, errs = {}, opts = {})
       @message = msg
       @errors = errs
+      @http_status = opts[:http_status]
       throw(:return, false)
     end
 

data/lib/haveapi/action_state.rb

@@ -0,0 +1,92 @@
+module HaveAPI
+  # This class is an interface between APIs and HaveAPI for handling of blocking actions.
+  # Blocking actions are not executed immediately, but their execution takes an unspecified
+  # amount of time. This interface allows to list actions that are pending completion and view
+  # their status.
+  #
+  # If method `poll` is defined, it is called by action Resources::ActionState::Poll.
+  # it can provide a more sophisticated polling implementation than the implicit one, which is
+  # to create a new instance of this class every second and check its state. `poll` is passed
+  # one argument, a hash of input parameters from Resources::ActionState::Poll.
+  class ActionState
+    # Return an array of objects representing actions that are pending completion.
+    # @param [Object] user
+    # @param [Integer] offset
+    # @param [Integer] limit
+    # @param [Symbol] order (:newest or :oldest)
+    # @return [Array<ActionState>]
+    def self.list_pending(user, offset, limit, order)
+      raise NotImplementedError
+    end
+
+    # The constructor either gets parameter `id` or `state`. If `state` is not provided,
+    # the method should find it using the `id`.
+    #
+    # When the client is asking about the state of a specific action, lookup using `id`
+    # is used. When the client is listing pending actions, instances of this class are
+    # created in self.list_pending and are passed the `state` parameter to avoid double
+    # lookups. `id` should lead to the same object that would be passed as `state`.
+    #
+    # @param [Object] user
+    # @param [Integer] id action state id
+    # @param [Object] state
+    def initialize(user, id: nil, state: nil)
+      raise NotImplementedError
+    end
+
+    # @return [Boolean] true if the action exists
+    def valid?
+      raise NotImplementedError
+    end
+
+    # @return [Boolean] true of the action is finished
+    def finished?
+      raise NotImplementedError
+    end
+
+    # @return [Boolean] true if the action was/is going to be successful
+    def status
+      raise NotImplementedError
+    end
+
+    # @return [Integer] action state id
+    def id
+      raise NotImplementedError
+    end
+
+    # @return [String] human-readable label of this action state
+    def label
+      raise NotImplementedError
+    end
+
+    # @return [Hash]
+    def progress
+      raise NotImplementedError
+    end
+
+    # @return [Time]
+    def created_at
+
+    end
+
+    # @return [Time]
+    def updated_at
+
+    end
+
+    # @return [Boolean] true if the action can be cancelled
+    def can_cancel?
+      false
+    end
+
+    # Stop action execution
+    # @raise [RuntimeError] if the cancellation failed
+    # @raise [NotImplementedError] if the cancellation is not supported
+    # @return [Integer] if the cancellation succeded and is a blocking action
+    # @return [truthy] if the cancellation succeeded
+    # @return [falsy] if the cancellation failed
+    def cancel
+      raise NotImplementedError, 'action cancellation is not implemented by this API'
+    end
+  end
+end

data/lib/haveapi/authentication/basic/provider.rb

@@ -26,6 +26,13 @@ module HaveAPI::Authentication
         user
       end
 
+      def describe
+        {
+            description: "Authentication using HTTP basic. Username and password is passed "+
+                         "via HTTP header. Its use is forbidden from web browsers."
+        }
+      end
+
       protected
       # Reimplement this method. It has to return an authenticated
       # user or nil.

data/lib/haveapi/authentication/token/provider.rb

@@ -100,6 +100,11 @@ module HaveAPI::Authentication
         {
             http_header: http_header,
             query_parameter: query_parameter,
+            description: "The client authenticates with username and password and gets "+
+                         "a token. From this point, the password can be forgotten and "+
+                         "the token is used instead. Tokens can have different lifetimes, "+
+                         "can be renewed and revoked. The token is passed either via HTTP "+
+                         "header or query parameter."
         }
       end
 

data/lib/haveapi/client_example.rb

@@ -0,0 +1,83 @@
+module HaveAPI
+  module ClientExamples ; end
+
+  # All client example classes should inherit this class. Depending on the client,
+  # the subclass may choose to implement either method `example` or `request` and
+  # `response`. `example` should be implemented if the client example shows only
+  # the request or the request and response should be coupled together.
+  #
+  # Methods `example`, `request` and `response` take one argument, the example
+  # to describe.
+  class ClientExample
+    class << self
+      # All subclasses have to call this method to set their label and be
+      # registered.
+      def label(v = nil)
+        if v
+          @label = v
+          HaveAPI::ClientExample.register(self)
+        end
+
+        @label
+      end
+
+      # Code name is passed to the syntax highligher.
+      def code(v = nil)
+        @code = v if v
+        @code
+      end
+
+      # A number used for ordering client examples.
+      def order(v = nil)
+        @order = v if v
+        @order
+      end
+
+      def register(klass)
+        @clients ||= []
+        @clients << klass
+      end
+
+      # Shortcut to {ClientExample#init}
+      def init(*args)
+        new(*args).init
+      end
+
+      # Shortcut to {ClientExample#auth}
+      def auth(*args)
+        new(*args[0..-3]).auth(*args[-2..-1])
+      end
+
+      # Shortcut to {ClientExample#example}
+      def example(*args)
+        new(*args[0..-2]).example(args.last)
+      end
+
+      # @return [Array<ClientExample>] sorted array of classes
+      def clients
+        @clients.sort { |a, b| a.order <=> b.order }
+      end
+    end
+
+    attr_reader :resource_path, :resource, :action_name, :action, :host, :base_url, :version
+
+    def initialize(host, base_url, version, *args)
+      @host = host
+      @base_url = base_url
+      @version = version
+      @resource_path, @resource, @action_name, @action = args
+    end
+
+    def init
+
+    end
+
+    def auth(method, desc)
+
+    end
+
+    def version_url
+      File.join(base_url, "v#{version}", '/')
+    end
+  end
+end

data/lib/haveapi/client_examples/curl.rb

@@ -0,0 +1,86 @@
+require 'pp'
+
+module HaveAPI::ClientExamples
+  class Curl < Http
+    label 'curl'
+    code :bash
+    order 90
+
+    def init
+      "$ curl --request OPTIONS '#{version_url}'"
+    end
+
+    def auth(method, desc)
+      login = {login: 'user', password: 'password', lifetime: 'fixed'}
+
+      case method
+      when :basic
+        <<END
+# Password is asked on standard input
+$ curl --request OPTIONS \\
+       --user username \\
+       '#{base_url}'
+Password: secret
+
+# Password given on the command line
+$ curl --request OPTIONS \\
+       --user username:secret \\
+       '#{base_url}'
+END
+
+      when :token
+        <<END
+# Acquire the token
+$ curl --request POST \\
+       --header 'Content-Type: application/json' \\
+       --data-binary "#{format_data(token: login)}" \\
+       '#{File.join(base_url, '_auth', 'token', 'tokens')}'
+
+# Use a previously acquired token
+$ curl --request OPTIONS \\
+       --header '#{desc[:http_header]}: thetoken' \\
+       '#{base_url}'
+END
+      end
+    end
+
+    def request(sample)
+      url = File.join(
+          base_url,
+          resolve_path(
+              action[:method],
+              action[:url],
+              sample[:url_params] || [],
+              sample[:request]
+          )
+      )
+
+      data = format_data({
+          action[:input][:namespace] => sample[:request],
+      })
+
+      <<END
+$ curl --request #{action[:method]} \\
+       --data-binary "#{data}" \\
+       '#{url}'
+END
+    end
+
+    def response(sample)
+      JSON.pretty_generate({
+          status: sample[:status],
+          message: sample[:message],
+          response: {action[:output][:namespace] => sample[:response]},
+          errors: sample[:errors],
+      })
+    end
+
+    def format_data(data)
+      json = JSON.pretty_generate(data)
+      json.split("\n").map do |line|
+        out = ''
+        PP.pp(line, out).strip[1..-2]
+      end.join("\n")
+    end
+  end
+end

data/lib/haveapi/client_examples/fs_client.rb

@@ -0,0 +1,116 @@
+module HaveAPI::ClientExamples
+  class FsClient < HaveAPI::ClientExample
+    label 'File system'
+    code :bash
+    order 40
+
+    def init
+      "# Mount the file system\n$ haveapi-fs #{base_url} #{mountpoint} -o version=#{version}"
+    end
+
+    def auth(method, desc)
+      case method
+      when :basic
+        <<END
+# Provide credentials as file system options
+#{init} -o auth_method=basic,user=myuser,password=secret
+
+# If username or password isn't provided, the user is asked on stdin
+#{init} -o auth_method=basic,user=myuser
+Password: secret
+END
+
+      when :token
+        <<END
+# Authenticate using username and password
+#{init} -o auth_method=token,user=myuser
+Password: secret
+
+# If you have generated a token, you can use it
+#{init} -o auth_method=token,token=yourtoken
+
+# Note that the file system can read config file from haveapi-client, so if
+# you set up authentication there, the file system will use it.
+END
+      end
+    end
+
+    def example(sample)
+      cmd = [init]
+
+      path = [mountpoint].concat(resource_path)
+
+      unless class_action?
+        if !sample[:url_params] || sample[:url_params].empty?
+          fail "example {#{sample}} of action #{resource_path.join('.')}"+
+               ".#{action_name} is for an instance action but does not include "+
+               "URL parameters"
+        end
+
+        path << sample[:url_params].first.to_s
+      end
+
+      path << 'actions' << action_name
+
+      cmd << "\n# Change to action directory"
+      cmd << "$ cd #{File.join(path)}"
+
+      if sample[:request] && !sample[:request].empty?
+        cmd << "\n# Prepare input parameters"
+
+        sample[:request].each do |k, v|
+          cmd << "$ echo '#{v}' > input/#{k}"
+        end
+      end
+
+      cmd << "\n# Execute the action"
+      cmd << "$ echo 1 > exec"
+
+      cmd << "\n# Query the action's result"
+      cmd << "$ cat status"
+      cmd << (sample[:status] ? '1' : '0')
+
+      if sample[:status]
+        if sample[:response] && !sample[:response].empty? \
+           && %i(hash object).include?(action[:output][:layout])
+          cmd << "\n# Query the output parameters"
+
+          sample[:response].each do |k, v|
+            cmd << "$ cat output/#{k}"
+
+            if v === true
+              cmd << '1'
+
+            elsif v === false
+              cmd << '0'
+
+            else
+              cmd << "#{v.to_s}"
+            end
+
+            cmd << "\n"
+          end
+        end
+
+      else
+        cmd << "\n# Get the error message"
+        cmd << "$ cat message"
+        cmd << sample[:message]
+
+        cmd << "\n# Parameter errors can be seen in the `errors` directory"
+        cmd << "$ ls errors"
+        cmd << (sample[:errors] || {}).keys.join("\n")
+      end
+
+      cmd.join("\n")
+    end
+
+    def mountpoint
+      "/mnt/#{host}"
+    end
+
+    def class_action?
+      action[:url].index(/:[a-zA-Z\-_]+/).nil?
+    end
+  end
+end