shark-on-lambda 1.0.0.rc2 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 404addc89268452b9ffbc6bb94ad7133dcac67f9df3f419abf0b673a5de20493
-  data.tar.gz: 328a87cf1a29c0e0322731ec83b94e4a0f029f87a8e37c1615062fc132da7b4d
+  metadata.gz: 642998e593034c083639724031920edfe7568de50d276cc3c58932c099d94a0e
+  data.tar.gz: 8101e725e3ef4f710422625726f87c7a324e986b9eb6184a988e0fdd3812bdda
 SHA512:
-  metadata.gz: 7874706fa45ad80560518176e9a5ee6f6f61c0e139ec785f6ce90e8aeed04e023a8fa890c121ca93b53203d25589b0d6a8cefdc5eb82f590eb040010d4c13890
-  data.tar.gz: 70fb9f45d5ad2c92d6643c1d20bf5aa70ff1883233814604870b2993501b761df588e577aa119d5b089c573fa86220183d10f4b076bf5587b5b3be9fc0e82e3a
+  metadata.gz: d23eac59ce2797aac609444509d571a54ffb22024f11070a54dd43d600ceeeb2b527e421c1c9463ac08cceb4fa2b9ad6a366e496cebb47c2873276e9abf4a9ec
+  data.tar.gz: 8932eeb3134b88fb0da09b35a3a70eb1b4d1bfb5b2a1f522b9f4bc23c07890b4c6c9cd061374aebf4eb80c09695ef69420da95cc7f608c415b81692724f41e56

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/.rubocop.yml

@@ -1,4 +1,5 @@
 AllCops:
+  NewCops: enable
   TargetRubyVersion: 2.5
 
 Metrics/BlockLength:
@@ -6,6 +7,9 @@ Metrics/BlockLength:
     - 'spec/**/*_spec.rb'
     - 'spec/factories/*.rb'
 
+Layout/LineLength:
+  Max: 80
+
 Naming/FileName:
   Exclude:
     - lib/shark-on-lambda.rb

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,22 @@
 ## Changelog
 
-#### Unreleaesed
+#### Unreleased
+
+#### 2.0.0
+- [Deprecate] Requiring `shark-on-lambda` is marked as deprecated in favour of requiring `shark_on_lambda`.
+- [Break] `SharkOnLambda::Dispatcher` was removed in favour of routing via `ActionDispatch::Routing`.
+- [Break] `SharkOnLambda::BaseController` now renders _JSON API_-compliant responses.
+- [Break] `SharkOnLambda::JsonapiController` was removed.
+- [Break] Support for `path_parameters` in RSpec helpers was removed.
+- [Break] Configuration files are not loaded automatically anymore.
+- Added support for routing.
+- Use `rack-on-lambda` as an adapter for events from the (REST API flavoured) API Gateway.
+
+#### 1.0.1
+
+- [Fix] `Jsonapi::Renderer#render` should always return a hash.
+
+#### 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.rb

@@ -1,3 +1,12 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/string'
+require 'active_support/deprecation'
+
+deprecation_message = <<-MESSAGE.squish
+  Requiring `shark-on-lambda` is deprecated and will be removed in version 3.0. 
+  Please require `shark_on_lambda` instead.
+MESSAGE
+ActiveSupport::Deprecation.warn(deprecation_message, caller(2))
+
 require 'shark_on_lambda'

data/lib/shark_on_lambda.rb

@@ -2,6 +2,7 @@
 
 require 'pry' if Gem.loaded_specs.key?('pry')
 
+require 'erb'
 require 'forwardable'
 require 'ostruct'
 require 'pathname'
@@ -14,6 +15,7 @@ require 'active_support/all'
 require 'jsonapi/deserializable'
 require 'jsonapi/serializable'
 require 'rack/utils'
+require 'rack-on-lambda'
 require 'yaml'
 require 'zeitwerk'
 
@@ -22,6 +24,7 @@ module SharkOnLambda; end
 
 Zeitwerk::Loader.for_gem.tap do |loader|
   loader.ignore(File.expand_path('shark-on-lambda.rb', __dir__))
+  loader.ignore(File.expand_path('shark_on_lambda/rake_tasks.rb', __dir__))
   loader.inflector.inflect(
     'rspec' => 'RSpec',
     'version' => 'VERSION'
@@ -35,67 +38,24 @@ module SharkOnLambda
   class << self
     extend Forwardable
 
-    attr_writer :logger
+    attr_writer :application, :env, :logger
 
-    def_instance_delegators :config, :root, :stage
+    def_instance_delegators :application, :initialize!, :root
 
     def application
       @application ||= Application.new
     end
 
-    def config
-      Configuration.instance
+    def configuration
+      application.config
     end
 
-    def configure
-      yield(config, secrets)
-    end
-
-    def initialize!
-      yield(config, secrets)
-
-      Configuration.load(stage)
-      Secrets.load(stage)
-      run_initializers
-
-      true
-    end
-
-    def load_configuration
-      Configuration.load(stage)
-      Secrets.load(stage)
-
-      true
+    def env
+      @env || ENV['STAGE'].presence || 'development'
     end
 
     def logger
-      @logger ||= Logger.new(STDOUT)
-    end
-
-    def reset_configuration
-      known_stage = config.stage
-      known_root = config.root
-
-      Configuration.reset
-      Secrets.reset
-
-      config.root = known_root
-      config.stage = known_stage
-
-      true
-    end
-
-    def secrets
-      Secrets.instance
-    end
-
-    protected
-
-    def run_initializers
-      initializers_path = root.join('config', 'initializers')
-      Dir.glob(initializers_path.join('*.rb')).each do |path|
-        load path
-      end
+      @logger ||= Logger.new($stdout)
     end
   end
 end