haveapi 0.28.3 → 0.28.4

data/spec/extensions/exception_mailer_spec.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'stringio'
+
+module ExceptionMailerSpec
+  class RequestError < StandardError; end
+  class ActionError < StandardError; end
+end
+
+describe HaveAPI::Extensions::ExceptionMailer do
+  api do
+    define_resource(:Test) do
+      version 1
+      auth false
+
+      define_action(:RequestError) do
+        route 'request_error'
+        http_method :get
+
+        authorize do
+          raise ExceptionMailerSpec::RequestError, 'request boom'
+        end
+
+        def exec
+          ok!
+        end
+      end
+
+      define_action(:InputRequestError) do
+        route 'input_request_error'
+        http_method :post
+
+        authorize do
+          raise ExceptionMailerSpec::RequestError, 'request boom'
+        end
+
+        def exec
+          ok!
+        end
+      end
+
+      define_action(:ActionError) do
+        route 'action_error'
+        http_method :get
+        authorize { allow }
+
+        def exec
+          raise ExceptionMailerSpec::ActionError, 'action boom'
+        end
+      end
+    end
+  end
+
+  default_version 1
+
+  def with_exception_mailer(mailer)
+    action_hooks = HaveAPI::Hooks.hooks[HaveAPI::Action][:exec_exception]
+    original_action_listeners = action_hooks[:listeners].dup
+    server = app.settings.api_server
+    original_server_hooks = dup_instance_hooks(server)
+
+    mailer.enabled(server)
+    yield
+  ensure
+    action_hooks[:listeners] = original_action_listeners
+    restore_instance_hooks(server, original_server_hooks)
+  end
+
+  def dup_instance_hooks(server)
+    hooks = server.instance_variable_get(HaveAPI::Hooks::INSTANCE_VARIABLE)
+    return unless hooks
+
+    hooks.transform_values do |hook|
+      hook.merge(listeners: hook[:listeners].dup)
+    end
+  end
+
+  def restore_instance_hooks(server, hooks)
+    if hooks
+      server.instance_variable_set(HaveAPI::Hooks::INSTANCE_VARIABLE, hooks)
+    elsif server.instance_variable_defined?(HaveAPI::Hooks::INSTANCE_VARIABLE)
+      server.remove_instance_variable(HaveAPI::Hooks::INSTANCE_VARIABLE)
+    end
+  end
+
+  def collect_mail_calls(mailer)
+    calls = []
+
+    allow(mailer).to receive(:mail) do |context, exception, body|
+      calls << [context, exception, body]
+    end
+
+    calls
+  end
+
+  def new_mailer
+    described_class.new(
+      from: 'from@example.test',
+      to: 'to@example.test',
+      subject: '[spec] %s',
+      smtp: false
+    )
+  end
+
+  it 'mails request-level exceptions outside action execution' do
+    mailer = new_mailer
+    calls = collect_mail_calls(mailer)
+
+    with_exception_mailer(mailer) do
+      get '/v1/tests/request_error'
+    end
+
+    expect(last_response.status).to eq(500)
+    expect(api_response).not_to be_ok
+    expect(api_response.message).to eq('Server error occurred')
+
+    expect(calls.size).to eq(1)
+    context, exception, body = calls.first
+    expect(context.action.to_s).to include('RequestError')
+    expect(exception).to be_a(ExceptionMailerSpec::RequestError)
+    expect(body).to include('request boom')
+  end
+
+  it 'redacts secrets from request-level exception emails' do
+    mailer = new_mailer
+    calls = collect_mail_calls(mailer)
+    header_secret = %w[HEADER SECRET].join('_')
+    header_token_secret = %w[HEADER TOKEN SECRET].join('_')
+    cookie_secret = %w[COOKIE SECRET].join('_')
+    query_secret = %w[QUERY SECRET].join('_')
+    body_secret = %w[BODY SECRET].join('_')
+    nested_secret = %w[NESTED SECRET].join('_')
+
+    with_exception_mailer(mailer) do
+      header 'Accept', 'application/json'
+      header 'Content-Type', 'application/json'
+      header 'Authorization', "Bearer #{header_secret}"
+      header 'Cookie', "session=#{cookie_secret}"
+      header 'X-Auth-Token', header_token_secret
+      post "/v1/tests/input_request_error?_auth_token=#{query_secret}", JSON.generate({
+        password: body_secret,
+        nested: {
+          token: nested_secret,
+          visible: 'VISIBLE_VALUE'
+        }
+      })
+    end
+
+    body = calls.first[2]
+
+    expect(body).to include('VISIBLE_VALUE')
+    expect(body).to include(HaveAPI::Extensions::ExceptionMailer::FILTERED_VALUE)
+    [
+      header_secret,
+      header_token_secret,
+      cookie_secret,
+      query_secret,
+      body_secret,
+      nested_secret
+    ].each do |secret|
+      expect(body).not_to include(secret)
+    end
+  end
+
+  it 'mails action execution exceptions' do
+    mailer = new_mailer
+    calls = collect_mail_calls(mailer)
+
+    with_exception_mailer(mailer) do
+      get '/v1/tests/action_error'
+    end
+
+    expect(last_response.status).to eq(500)
+    expect(api_response).not_to be_ok
+    expect(calls.size).to eq(1)
+    expect(calls.first[1]).to be_a(ExceptionMailerSpec::ActionError)
+    expect(calls.first[2]).to include('action boom')
+  end
+
+  it 'does not replace the API response when mail delivery fails' do
+    mailer = new_mailer
+    allow(mailer).to receive(:mail).and_raise(StandardError, 'smtp down')
+
+    with_exception_mailer(mailer) do
+      expect do
+        get '/v1/tests/request_error'
+      end.to output(/ExceptionMailer failed: StandardError: smtp down/).to_stderr
+    end
+
+    expect(last_response.status).to eq(500)
+    expect(api_response).not_to be_ok
+    expect(api_response.message).to eq('Server error occurred')
+  end
+end

data/spec/server/integration_spec.rb

@@ -37,6 +37,19 @@ describe HaveAPI::Server do
             { msg: params.dig(:test, :msg) }
           end
         end
+
+        define_action(:AuthorizeError) do
+          route 'authorize_error'
+          http_method :get
+
+          authorize do
+            raise 'authorize boom'
+          end
+
+          def exec
+            ok!
+          end
+        end
       end
 
       define_resource(:Transfer) do
@@ -143,6 +156,27 @@ describe HaveAPI::Server do
       expect(api_response).not_to be_ok
     end
 
+    it 'routes request-level exceptions through hook' do
+      calls = []
+
+      app.settings.api_server.connect_hook(:request_exception) do |ret, context, exception|
+        calls << [context, exception]
+        ret
+      end
+
+      header 'Accept', 'application/json'
+      get '/v1/tests/authorize_error'
+
+      expect(last_response.status).to eq(500)
+      expect(api_response).not_to be_ok
+      expect(api_response.message).to eq('Server error occurred')
+
+      expect(calls.size).to eq(1)
+      context, exception = calls.first
+      expect(context.action.to_s).to include('AuthorizeError')
+      expect(exception.message).to eq('authorize boom')
+    end
+
     it 'handles CORS preflight OPTIONS' do
       header 'Accept', 'application/json'
       header 'Origin', 'https://example.com'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi
 version: !ruby/object:Gem::Version
-  version: 0.28.3
+  version: 0.28.4
 platform: ruby
 authors:
 - Jakub Skokan
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.3
+        version: 0.28.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.28.3
+        version: 0.28.4
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -190,12 +190,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- doc/create-client.md
 - doc/hooks.erb
 - doc/index.md
-- doc/json-schema.html
-- doc/protocol.md
-- doc/protocol.png
 - haveapi.gemspec
 - lib/haveapi.rb
 - lib/haveapi/action.rb
@@ -312,6 +308,7 @@ files:
 - spec/documentation_spec.rb
 - spec/envelope_spec.rb
 - spec/extensions/action_exceptions_spec.rb
+- spec/extensions/exception_mailer_spec.rb
 - spec/hooks_spec.rb
 - spec/model_adapters/active_record_spec.rb
 - spec/parameters/typed_spec.rb

data/doc/create-client.md

@@ -1,107 +0,0 @@
-# Client definition
-It is necessary to differentiate between clients for HaveAPI based APIs
-and clients to work with your API instance. This document describes
-the former. If you only want to use your API, you should check a list
-of available clients and pick the one in the right language. Only when
-there isn't a client already available in the language you want, then
-continue reading.
-
-# Design rules
-The client must completely depend on the API description:
-
- - it has no assumptions and API-specific code,
- - it does not know any resources, actions and parameters,
- - everything the client knows must be found out from the API description.
-
-All clients should use a similar paradigm, so that it is possible to use
-clients in different languages in the same way, as far as the language syntax
-allows. Clients bundled with HaveAPI may serve as a model. A client should
-use all the advantages and coding styles of the language it is written
-in (e.g. use objects in object oriented languages).
-
-A model paradigm (in no particular language):
-
-    // Create client instance
-    api = new HaveAPI.Client("https://your.api.tld")
-
-    // Authenticate
-    api.authenticate("basic", {"user": "yourname", "password": "yourpassword"})
-
-    // Access resources and actions
-    api.<resource>.<action>( { <parameters> } )
-    api.user.new({"name": "Very Name", "password": "donottellanyone"})
-    api.user.list()
-    api.nested.resource.deep.list()
-
-    // Pass IDs to resources
-    api.nested(1).resource(2).deep.list()
-
-    // Object-like access
-    user = api.user.show(1)
-    user.id
-    user.name
-    user.destroy()
-
-    // Logout
-    api.logout()
-
-# Necessary features to implement
-A client should implement all of the listed features in order to be useful.
-
-## Resource tree
-The client gives access to all listed resources and their actions.
-
-In scripting languages, resources and actions are usually defined as dynamic
-properties/objects/methods, depending on the language.
-
-## Input/output parameters
-Allow sending input parameters and accessing the response.
-
-## Input/output formats
-A client must send appropriate HTTP header `Accept`. As only JSON is by now built-in
-in HaveAPI, it should send `application/json`.
-
-## Authentication
-All authentication methods that are built-in the HaveAPI should be supported
-if possible. The client should choose suitable authentication method
-for its purpose and allow the developer to select the authentication method
-if it makes sense to do so.
-
-It is a good practise to implement authentication methods as plugins,
-so that developers may add custom authentication providers easily.
-
-## Object-like access
-A client must interpret the API response according to action output layout.
-Layouts `object` and `object_list` should be handled as object instances,
-if the language allows it.
-
-Object instances represent the object fetched from the database. Received
-parameters are accessed via object attributes/properties. Actions are defined
-as instance methods. Objects may have associations to other resources which
-must be made available and be easy to access.
-
-# Supplemental features
-Following features are supplemental. It is good to support them,
-but is not necessary.
-
-## Client-side validations
-Client may make use of described validators and validate the input before
-sending it to the API, to lessen the API load and make it more user-friendly.
-
-However, as the input is validated on the server anyway, it does not have
-to be implemented.
-
-## Metadata channel
-Metadata channel is currently used to specify what associated resources should
-be prefetched and whether an object list should contain total number of items.
-
-Metadata is nothing more than a hash in input parameters under key `_meta`.
-
-## Blocking actions
-Useful for APIs with long-running actions. Clients can check state of such actions
-using resource `ActionState`. Because this resource is automatically present in all
-APIs that use blocking actions, client libraries expose this resource to the developer
-just as any other resource in the API.
-
-However, you may wish to integrate it in your client and provide ways for the action
-call to block/accept callbacks.