shark-on-lambda 1.0.0.rc4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6a831332c510a5977edd5ca1db24a68a9cf7cc323433fb807f5b65a707df0e7
-  data.tar.gz: 9beabc2ae1d3d81d9a6b10d80b69668629d902726c535dc3aec403db4ac38c36
+  metadata.gz: e858c687476151fddf9bc5d464c7845f09680b389fe2a31fe2d72f21c7d2403d
+  data.tar.gz: 4fb28a197425d9f26c28fe4c807d0548add701b8b2cea902987c1244c0ac1318
 SHA512:
-  metadata.gz: b607fdff10e8ff558fb85e3d92bc9697e783aaf2f856822fe84591101f974d89af3cd9a11c41640409c5f0590fb9ef0bf9b0c86e68029112388cd0a110283a08
-  data.tar.gz: 4ea5be6f0d30ce7b6f4a05632a9b9c1c96ce18673cb52be4907cdf726fb56982052a06f16874eeb772947ad387b2472d3079e585087146aee7865035ef6a42f7
+  metadata.gz: 3a420db54811cc256092094caa222be976d525ffd0d0b64da5fe0640b0d98287894c114ca1d16c6f735132bfe59f0480f0191902a8c9bfef296bd3cb0c70ae81
+  data.tar.gz: 4fbd6882b0dba434fc6781f3a831db2fddb10f38501d90008a09ce0ca1aa5e44294e34ba4f4ab4e103fb334e983531fef740f59d6fe868a3f28173b2079f169f

data/.gitignore

@@ -2,15 +2,14 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/
 
+gems.locked
+
 # rspec failure tracking
 .rspec_status
 
 # Add gems to `vendor/cache`
 vendor/cache/*
-!vendor/cache/bima*.gem
-!vendor/cache/shark*.gem

data/README.md

@@ -25,12 +25,19 @@ maintaining a smaller memory footprint.
 
 Have a look at the [actual changelog](changelog.md).
 
+## Upgrading?
+
+If you are upgrading from a previous version of `shark-on-lambda`, these
+upgrade guides might be of some help to you.
+
+* [Upgrading from `v0.6.x` to `v1.x`](doc/upgrade-from-0.6.x-to-1.x.md)
+
 ## Installation
 
 Add this line to your application's `gems.rb`:
 
 ```ruby
-gem 'shark_on_lambda'
+gem 'shark-on-lambda'
 ```
 
 And then execute:
@@ -39,7 +46,7 @@ And then execute:
 
 Or install it yourself:
 
-    $ gem install shark_on_lambda
+    $ gem install shark-on-lambda
 
 ## Handlers
 
@@ -48,11 +55,11 @@ are triggered by HTTP requests on the API Gateway. They also are responsible for
 responding with a well-formed response to the caller.
 
 ```ruby
-class MyHandler < SharkOnLambda::BaseHandler
+class MyHandler < SharkOnLambda::ApiGatewayHandler
 end
 ```
 
-By inheriting from `SharkOnLambda::BaseHandler`, your own handler
+By inheriting from `SharkOnLambda::ApiGatewayHandler`, your own handler
 class is indirectly tied to your controller class by convention: It assumes 
 the controller name is `MyController` and it will dispatch events to that
 controller.
@@ -78,7 +85,7 @@ class MyController < SharkOnLambda::BaseController
   end
 end
 
-class MyHandler < SharkOnLambda::BaseHandler
+class MyHandler < SharkOnLambda::ApiGatewayHandler
 end
 ```
 
@@ -89,16 +96,13 @@ handler class method is called.
 
 ## Controllers
 
-Controllers are similar to Rails controllers: In addition to having access to 
-the AWS Lambda `event` and `context` objects, you also have access to `params`, 
-`request`, and `response` objects that are derived from the `event` object.
+Controllers are similar to Rails controllers: You have access to `params`, 
+`request`, and `response` objects that contain informatoni retrieved from the
+AWS Lambda `event` object.
 
 ### "Basic" controllers
 
-You also have access to the `render` and `redirect_to` methods __that are not as
-powerful as the Rails equivalent by far__. There are none of the `render_*`
-functions you may know from Rails and `render` does not really support multiple
-renderers (yet).
+You also have access to the `render` and `redirect_to`.
 
 ```ruby
 class MyController < SharkOnLambda::BaseController
@@ -113,17 +117,19 @@ class MyController < SharkOnLambda::BaseController
   def show
     # Does what you think it does.
     #
-    # The default status code for `redirect_to` is 307.    
-    redirect_to 'https://github.com', status: 302
+    # The default status code for `redirect_to` is 302.    
+    redirect_to 'https://github.com', status: 307
   end
 end
 ```
 
+`before_action`, `around_action`, and `after_action` filters also are available,
+as well as `rescue_from`.
+
 ### _JSON API_-compliant controllers
 
-If you inherit your controller from 
-`SharkOnLambda::JsonapiController`, `render` and `redirect_to` will
-create _JSON API_-compliant responses.
+If you inherit your controller from `SharkOnLambda::JsonapiController`, 
+`render` and `redirect_to` will create _JSON API_-compliant responses.
 
 You however __must__ have a serialiser for the objects you want to render.
 Otherwise, rendering will fail and you will receive an _Internal Server Error_
@@ -196,6 +202,53 @@ If `SharkOnLambda.config.stage` was set inside the block passed to
 the default set (the `default` node in the YAML files) of configuration and 
 secrets, overwriting values where applicable.
 
+## Test helpers
+
+By including `SharkOnLambda::RSpec::Helpers` in your RSpec test suite, you can 
+use `delete`, `get`, `patch`, `post`, and `put` methods, which will return
+a `Rack::MockResponse` object. You can also access that response object in your
+test examples by calling `response`, but only after you've called either of the
+aforementioned methods. Otherwise, an exception will be raised.
+
+You can include the test helpers like this in your `spec/spec_helper.rb`.
+
+```ruby
+RSpec.configure do |config|
+  config.include SharkOnLambda::RSpec::Helpers
+end
+```
+
+### _JSON API_ helpers
+
+By including `SharkOnLambda::RSpec::JsonapiHelpers`, you gain all the goodies
+from `SharkOnLambda::RSpec::Helpers` _and_ access to `jsonapi_data` and
+`jsonapi_errors` methods, which contain the `data` and `errors` keys of the
+parsed response body respectively. In addition to that, there is
+`jsonapi_attributes`, which returns the `attributes` key from `jsonapi_data`.
+
+## _Rack_ compatibility
+
+As `SharkOnLambda.application` is a _Rack_-compatible application, treating it
+as such and using existing _Rack_ middleware is straightforward. 
+
+### Using _Rack_ middleware
+
+The middleware stack can be found at `SharkOnLambda.config.middleware`. Adding
+middleware to your stack can be either done by calling `#use`:
+
+```ruby
+SharkOnLambda.config.middleware.use Your::Middleware
+```
+
+You can also just set up your middleware stack during your 
+`SharkOnLambda.initialize!` call:
+
+```ruby
+SharkOnLambda.initialize! do |config, secrets|
+  config.middleware.use Your::Middleware
+end
+```
+
 ## Development
 
 Clone this repository and change away. Then, once you are done, please submit

data/changelog.md

@@ -1,6 +1,6 @@
 ## Changelog
 
-#### Unreleaesed
+#### 1.0.0
 
 - [Break] HTTP redirection now uses the status code `302`.
 - [Break] Remove the `ApiGateway` namespace, move all items from that namespace up by one level.

data/doc/upgrade-from-0.6.x-to-1.x.md

@@ -0,0 +1,122 @@
+# Upgrading from version `0.6.x` to version `1.x`
+
+## Mandatory changes
+
+### `SharkOnLambda::ApiGateway::*` => `SharkOnLambda::*`
+
+The `ApiGateway` module was removed in favour of a shallower hierarchy, because
+`shark-on-lambda` only really does lifting work in an HTTP request context.
+
+### `SharkOnLambda::ApiGateway::BaseHandler` => `SharkOnLambda::ApiGatewayHandler`
+
+In an attempt to make the ties to the _API Gateway_ a bit more explicit, the
+handler base class now is `SharkOnLambda::ApiGatewayHandler` instead of what
+might be expected to be `SharkOnLambda::BaseHandler`.  
+
+### Use `SharkOnLambda::RSpec::JsonapiHelpers` (or `SharkOnLambda::RSpec::Helpers`)
+
+Until now, making a request to your application has involved building your own
+_API Gateway_ event object and then passing it to your handler/controller.
+
+If you have been passing the event object to your handlers solely, this change
+is optional. If you however have been passing the event object to your 
+controllers, upgrading `shark-on-lambda` to `v1.x` makes changing the way your
+tests run a necessity, because controller do not know about _API Gateway_ events
+anymore and thus cannot handle them properly.
+
+The recommended way to test controllers is to use 
+`SharkOnLambda::RSpec::JsonapiHelpers` (or `SharkOnLambda::RSpec::Helpers`) in
+your RSpec tests and then use the methods `delete`, `get`, `patch`, `post`, or
+`put` to test your controllers like this:
+
+```ruby
+RSpec.describe MyController do
+  let!(:service_token) { 'my-super-secret-service-token' }
+  let!(:headers) do
+    {
+      'authorization' => "Bearer #{service_token}"
+    }
+  end    
+  let!(:params) do
+    {
+      id: 1
+    }
+  end
+
+  subject { get :show, headers: headers, params: params }
+
+  it { expect(subject.status).to eq(200) }
+end
+```
+
+If you, for some reason, want to distinguish between `params` and 
+`path_parameters`, you can also pass in `path_parameters` using the
+`path_parameters:` keyword argument like this:
+
+```ruby
+get :show, headers: headers, params: params, path_parameters: path_parameters
+```
+
+Using `SharkOnLambda::RSpec::JsonapiHelpers` or `SharkOnLambda::RSpec::Helpers`
+also lets you access the `response` object in your test examples. This object
+is an instance of `Rack::MockResponse`, which you might be familiar with from
+e. g. controller testing in Rails.
+
+You can use these helpers by e. g. setting them up in `spec/spec_helper.rb`:
+
+```ruby
+RSpec.configure do |config|
+  config.include SharkOnLambda::RSpec::JsonapiHelpers
+end
+```
+
+## Recommended changes
+
+### Move to a _Rack_-compatible implementation for CORS headers
+
+Until now, the way to add CORS headers prior to sending the response to the 
+_API Gateway_ has been to "decorate" the `#call` method in your handler, e. g.
+using a module like
+
+```ruby
+module CORS
+  def call(action, event:, context:)
+    response = super
+    response[:headers].reverse_merge!(
+      'access-control-allow-origin' => '*',
+      'access-control-allow-credentials' => 'true'
+    )
+    response
+  end
+end
+```  
+
+and then including it in your handler:
+
+```ruby
+class MyHandler < SharkOnLambda::ApiGateway::BaseHandler
+  include CORS
+end
+```
+
+This _still_ works for the time being, but it is recommended to switch to an
+approach based on using _Rack_ middleware, e. g. `rack-cors` or implementing
+your own middleware.
+
+### Use `SharkOnLambda::Middleware::JsonapiRescuer` (or `SharkOnLambda::Middleware::Rescuer`)
+
+Until now, `shark-on-lambda` has caught all uncaught exceptions before building
+the response object for _API Gateway_, turning those exceptions into sensible
+response objects.
+
+This behaviour changes drastically with `v1.0.0`: Exceptions are not being
+caught by the main application anymore. Therefore, it is recommended to add
+`SharkOnLambda::Middleware::JsonapiRescuer`
+(or `SharkOnLambda::Middleware::Rescuer`) to your middleware stack to restore
+this kind of behaviour.
+
+```ruby
+SharkOnLambda.initialize! do |config, secrets|
+  config.middleware.use SharkOnLambda::Middleware::JsonapiRescuer
+end
+``` 

data/lib/shark_on_lambda/application.rb

@@ -3,12 +3,10 @@
 module SharkOnLambda
   class Application
     def call(env)
-      dup.send('_call', env)
+      dup.call!(env)
     end
 
-    private
-
-    def _call(env)
+    def call!(env)
       dispatcher = SharkOnLambda.config.dispatcher
       middleware_stack = SharkOnLambda.config.middleware.build(dispatcher)
       middleware_stack.call(env)

data/lib/shark_on_lambda/jsonapi_controller.rb

@@ -7,10 +7,13 @@ module SharkOnLambda
       return { data: {} }.to_json if object.nil?
 
       jsonapi_params = JsonapiParameters.new(params)
-      jsonapi_renderer = JsonapiRenderer.new
+      jsonapi_renderer = JsonapiRenderer.new(object)
       render_options = jsonapi_params.to_h.deep_merge(options)
 
-      jsonapi_renderer.render(object, render_options)
+      jsonapi_object = jsonapi_renderer.render(render_options)
+      response.status = jsonapi_renderer.status
+
+      jsonapi_object.to_json
     end
 
     def redirect_to(options = {}, response_status = {})

data/lib/shark_on_lambda/jsonapi_renderer.rb

@@ -2,21 +2,27 @@
 
 module SharkOnLambda
   class JsonapiRenderer
-    def initialize(renderer: nil)
+    attr_reader :object, :status
+
+    def initialize(object, renderer: nil)
+      @object = object
       @renderer = renderer || JSONAPI::Serializable::Renderer.new
+
+      @status = 200
     end
 
-    def render(object, options = {})
-      object = transform_active_model_errors(object)
+    def render(options = {})
+      @status = options[:status] if options[:status]
+      object_to_render = transform_active_model_errors(object)
 
-      unless renderable?(object, options)
-        return handle_unrenderable_objects(object, options)
+      unless renderable?(object_to_render, options)
+        return handle_unrenderable_objects(object_to_render, options)
       end
 
-      if error?(object)
-        render_errors(object, options).to_json
+      if error?(object_to_render)
+        render_errors(object_to_render, options).to_json
       else
-        render_success(object, options).to_json
+        render_success(object_to_render, options).to_json
       end
     end
 
@@ -54,6 +60,7 @@ module SharkOnLambda
         Errors[500].new("Could not find serializer for: #{item.name}.")
       end
 
+      @status = 500
       render_errors(errors, options)
     end
 

data/lib/shark_on_lambda/middleware/base.rb

@@ -10,12 +10,10 @@ module SharkOnLambda
       end
 
       def call(env)
-        dup.send('_call', env)
+        dup.call!(env)
       end
 
-      private
-
-      def _call(_env)
+      def call!(_env)
         raise NotImplementedError
       end
     end

data/lib/shark_on_lambda/middleware/honeybadger.rb

@@ -11,24 +11,27 @@ module SharkOnLambda
         @tags = tags
       end
 
-      private
-
-      def _call(env)
-        @env = env
+      def call!(env)
         app.call(env)
       rescue StandardError => e
-        notify(e) unless shark_error?(e)
+        notify(e, env) unless shark_error?(e) && client_error?(e)
 
         raise e
       end
 
-      def notify(error)
+      private
+
+      def client_error?(error)
+        error.respond_to?(:status) && error.status < 500
+      end
+
+      def notify(error, env)
         ::Honeybadger.notify(
           error,
           tags: tags,
-          controller: @env['shark.controller'],
-          action: @env['shark.action'],
-          parameters: @env['action_dispatch.request.parameters']
+          controller: env['shark.controller'],
+          action: env['shark.action'],
+          parameters: env['action_dispatch.request.parameters']
         )
       end
 

data/lib/shark_on_lambda/middleware/lambda_logger.rb

@@ -10,9 +10,7 @@ module SharkOnLambda
         @logger = logger
       end
 
-      private
-
-      def _call(env)
+      def call!(env)
         start_time = Time.now
         response = app.call(env)
         end_time = Time.now
@@ -27,6 +25,8 @@ module SharkOnLambda
         response
       end
 
+      private
+
       def body_size(body)
         size = 0
         body.each { |chunk| size += chunk.bytesize }

data/lib/shark_on_lambda/middleware/rescuer.rb

@@ -3,9 +3,7 @@
 module SharkOnLambda
   module Middleware
     class Rescuer < Base
-      private
-
-      def _call(env)
+      def call!(env)
         app.call(env)
       rescue Errors::Base => e
         rescue_shark_error(e)
@@ -13,6 +11,8 @@ module SharkOnLambda
         rescue_standard_error(e)
       end
 
+      private
+
       def error_response(status, headers, message)
         response_body = Rack::BodyProxy.new([message]) do
           message.close if message.respond_to?(:close)

data/lib/shark_on_lambda/rack_adapters/api_gateway.rb

@@ -19,7 +19,7 @@ module SharkOnLambda
           'body' => body_content
         }
         response['isBase64Encoded'] = false if elb?
-        response
+        response.with_indifferent_access
       end
 
       def env

data/lib/shark_on_lambda/rspec/env_builder.rb

@@ -3,7 +3,8 @@
 module SharkOnLambda
   module RSpec
     class EnvBuilder
-      attr_reader :action, :controller, :headers, :method, :params
+      attr_reader :action, :controller, :headers, :method
+      attr_reader :params, :path_parameters
 
       def initialize(options = {})
         @method = options.fetch(:method).to_s.upcase
@@ -12,7 +13,8 @@ module SharkOnLambda
 
         @headers = (options[:headers] || {}).deep_stringify_keys
         @headers.transform_keys!(&:downcase)
-        @params = options[:params]
+        @params = options[:params] || {}
+        @path_parameters = options[:path_parameters] || {}
 
         initialize_env
         add_headers
@@ -56,7 +58,8 @@ module SharkOnLambda
           method: method,
           params: params,
           'shark.controller' => controller,
-          'shark.action' => action
+          'shark.action' => action,
+          'shark.path_parameters' => path_parameters
         )
       end
 

data/lib/shark_on_lambda/rspec/helpers.rb

@@ -39,7 +39,8 @@ module SharkOnLambda
           controller: controller_name,
           action: action,
           headers: options[:headers],
-          params: options[:params]
+          params: options[:params],
+          path_parameters: options[:path_parameters]
         )
         env_builder.build
       end

data/lib/shark_on_lambda/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SharkOnLambda
-  VERSION = '1.0.0.rc4'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shark-on-lambda
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc4
+  version: 1.0.0
 platform: ruby
 authors:
 - Huy Dinh
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-03-03 00:00:00.000000000 Z
+date: 2020-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -260,6 +260,7 @@ files:
 - bin/console
 - bin/setup
 - changelog.md
+- doc/upgrade-from-0.6.x-to-1.x.md
 - gems.rb
 - lib/shark-on-lambda.rb
 - lib/shark_on_lambda.rb
@@ -307,9 +308,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.7.6.2