yake 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7f5484562df0ab45af1304729d8f5c6edc2a66082ba4bcd4ca718bcfdba1d96
+  data.tar.gz: c63cb492e9a31e9cd29a06c93493bb28f7f1823eae6eb8f06a4d889b204048bc
+SHA512:
+  metadata.gz: fec877aefb902caa3b64562c255ac9d8f33dbbe878de88af3bfc985dacac7f4e7f2ad8c02dbc873987defb1c64f85695d2d6da035596ad5e3ee1c168a5303f27
+  data.tar.gz: 5641f87b78f5fce7c1eec4cfd8c422afa56247ad27ab936587840563998feb98f1198e291c2b9c508f30414cf282a6f988ed0d79db18c639b21e6560266deba6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Alexander Mancevice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Alexander Mancevice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,181 @@
+# λake
+
+Write your AWS Lambda function handlers using a Rake-like declarative syntax:
+
+```ruby
+# ./lambda_function.rb
+require "yake"
+
+handler :lambda_handler do |event|
+  # Your code here
+end
+
+# Handler signature: `lambda_function.lambda_handler`
+```
+
+You can even declare Sinatra-like API Gateway routes for a main entrypoint:
+
+```ruby
+# ./lambda_function.rb
+require "yake/api"
+
+header "content-type" => "application/json"
+
+get "/fizz" do |handler|
+  respond 200, { ok: true }.to_json
+end
+
+handler :lambda_handler do |event|
+  route event
+rescue => err
+  respond 500, { message: err.message }.to_json
+end
+
+# Handler signature: `lambda_function.lambda_handler`
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "yake"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install yake
+```
+
+## Why Use It?
+
+So why use `yake` for your Lambda functions?
+
+#### Zero Dependencies
+
+`yake` does not depend on any other gems, using the Ruby stdlib only. This helps keep your Lambda packages slim & speedy.
+
+#### Event Logging
+
+By default, the `handler` function wraps its block in log lines formatted to match the style of Amazon's native Lambda logs sent to CloudWatch. Each invocation of the handler logs the input event and the returned value prefixed with the ID of the request.
+
+Example log lines:
+
+```
+START RequestId: 149c500f-028a-4b57-8977-0ef568cf8caf Version: $LATEST
+INFO RequestId: 149c500f-028a-4b57-8977-0ef568cf8caf EVENT { … }
+…
+INFO RequestId: 149c500f-028a-4b57-8977-0ef568cf8caf RETURN { … }
+END RequestId: 149c500f-028a-4b57-8977-0ef568cf8caf
+REPORT RequestId: 149c500f-028a-4b57-8977-0ef568cf8caf	Duration: 43.97 ms	Billed Duration: 44 ms	Memory Size: 128 MB	Max Memory Used: 77 MB
+```
+
+This makes gathering logs lines for a particular execution in CloudWatch much easier.
+
+This feature can be disabled by adding a declaration in your handler:
+
+```ruby
+logging :off
+```
+
+#### API Routes
+
+A common use of Lambda functions is as a proxy for API Gateway. Oftentimes users will deploy a single Lambda function to handle all requests coming from API Gateway.
+
+Requiring the `yake/api` module will add the API-specific DSL into your handler.
+
+Define API routes using Sinatra-like syntax
+
+```ruby
+# Declare 'DELETE /…' route key
+delete "/…" do |event|
+  # …
+end
+
+# Declare 'GET /…' route key
+get "/…" do |event|
+  # …
+end
+
+# Declare 'HEAD /…' route key
+head "/…" do |event|
+  # …
+end
+
+# Declare 'OPTIONS /…' route key
+options "/…" do |event|
+  # …
+end
+
+# Declare 'PATCH /…' route key
+patch "/…" do |event|
+  # …
+end
+
+# Declare 'POST /…' route key
+post "/…" do |event|
+  # …
+end
+
+# Declare 'PUT /…' route key
+put "/…" do |event|
+  # …
+end
+
+```
+
+Helper methods are also made available to help produce a response for API Gateway:
+
+Set a default header for ALL responses:
+
+```ruby
+header "content-type" => "application/json; charset=utf-8"
+```
+
+Produce an API Gateway-style response object:
+
+```ruby
+respond 200, { ok: true }.to_json, "x-extra-header" => "fizz"
+# {
+#   "statusCode" => 200,
+#   "body" => '{"ok":true}',
+#   "headers" => { "x-extra-header" => "fizz" }
+# }
+```
+
+Route an event to one of the declared routes:
+
+```ruby
+begin
+  route event
+rescue Yake::UndeclaredRoute => err
+  respond 404, { message: err.message }.to_json
+rescue => err
+  respond 500 { message: err.message }.to_json
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/amancevice/yake.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+```
+
+```

data/lib/yake.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "yake/version"
+require_relative "yake/logger"
+require_relative "yake/errors"
+require_relative "yake/dsl"

data/lib/yake/api.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+
+require "yake"
+require_relative "errors"
+
+module Yake
+  module API
+    module DSL
+      ##
+      # Proxy handler for HTTP requests from Slack
+      def route(event, context = nil)
+        # Extract route method
+        method = event["routeKey"]
+        raise Yake::Errors::UndeclaredRoute, method unless respond_to?(method)
+
+        # Normalize headers
+        event["headers"]&.transform_keys!(&:downcase)
+
+        # Decode body if Base64-encoded
+        if event["isBase64Encoded"]
+          body = Base64.strict_decode64(event["body"])
+          event.update("body" => body, "isBase64Encoded" => false)
+        end
+
+        # Execute request
+        send(method, event, context)
+      end
+
+      ##
+      # Transform to API Gateway response
+      def respond(status_code, body = nil, **headers)
+        # Log response
+        log = "RESPONSE [#{ status_code }] #{ body }"
+        Yake.logger&.send(status_code.to_i >= 400 ? :error : :info, log)
+
+        # Set headers
+        content_length = (body&.length || 0).to_s
+        to_s_downcase  = -> (key) { key.to_s.downcase }
+        headers = {
+          "content-length" => content_length,
+          **(@headers || {}),
+          **headers,
+        }.transform_keys(&to_s_downcase).compact
+
+        # Send response
+        { statusCode: status_code, headers: headers, body: body }.compact
+      end
+
+      ##
+      # Set default header
+      def header(headers)
+        (@headers ||= {}).update(headers)
+      end
+
+      ##
+      # Define DELETE route
+      def delete(path, &block)
+        define_singleton_method("DELETE #{ path }") { |*args| instance_exec(*args, &block) }
+      end
+
+      ##
+      # Define GET route
+      def get(path, &block)
+        define_singleton_method("GET #{ path }") { |*args| instance_exec(*args, &block) }
+      end
+
+      ##
+      # Define HEAD route
+      def head(path, &block)
+        define_singleton_method("HEAD #{ path }") { |*args| instance_exec(*args, &block) }
+      end
+
+      ##
+      # Define OPTIONS route
+      def options(path, &block)
+        define_singleton_method("OPTIONS #{ path }") { |*args| instance_exec(*args, &block) }
+      end
+
+      ##
+      # Define PATCH route
+      def patch(path, &block)
+        define_singleton_method("PATCH #{ path }") { |*args| instance_exec(*args, &block) }
+      end
+
+      ##
+      # Define POST route
+      def post(path, &block)
+        define_singleton_method("POST #{ path }") { |*args| instance_exec(*args, &block) }
+      end
+
+      ##
+      # Define PUT route
+      def put(path, &block)
+        define_singleton_method("PUT #{ path }") { |*args| instance_exec(*args, &block) }
+      end
+    end
+  end
+end
+
+extend Yake::API::DSL

data/lib/yake/dsl.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "logger"
+
+module Yake
+  module DSL
+    ##
+    # Lambda handler task wrapper
+    def handler(name, &block)
+      define_method(name) do |event:nil, context:nil|
+        Yake.logger.nil? ? yield(event, context) : Yake.logger.wrap(event, context, &block)
+      end
+    end
+
+    ##
+    # Turn logging on/off
+    def logging(switch, **options)
+      if switch == :on
+        Yake.logger = Yake::Logger.new
+      elsif switch == :off
+        Yake.logger = nil
+      else
+        raise Errors::UnknownLoggingSetting, switch
+      end
+    end
+  end
+end
+
+extend Yake::DSL
+Yake.logger = Yake::Logger.new

data/lib/yake/errors.rb

@@ -0,0 +1,61 @@
+module Yake
+  module Errors
+    class Error < StandardError; end
+
+    class UndeclaredRoute < Error
+      def initialize(method = nil)
+        super("No route declared for '#{ method }'")
+      end
+    end
+
+    class UnknownLoggingSetting < Error
+      def initialize(method = nil)
+        super("Unknown logging setting '#{ method }'. Use :on or :off")
+      end
+    end
+
+    # HTTP Errors
+
+    class BadRequest < Error; end                    # HTTP 400
+    class Unauthorized < Error; end                  # HTTP 401
+    class PaymentRequired < Error; end               # HTTP 402
+    class Forbidden < Error; end                     # HTTP 403
+    class NotFound < Error; end                      # HTTP 404
+    class MethodNotAllowed < Error; end              # HTTP 405
+    class NotAcceptable < Error; end                 # HTTP 406
+    class ProxyAuthenticationRequired < Error; end   # HTTP 407
+    class RequestTimeout < Error; end                # HTTP 408
+    class Conflict < Error; end                      # HTTP 409
+    class Gone < Error; end                          # HTTP 410
+    class LengthRequired < Error; end                # HTTP 410
+    class PreconditionFailed < Error; end            # HTTP 412
+    class PayloadTooLarge < Error; end               # HTTP 413
+    class UriTooLong < Error; end                    # HTTP 414
+    class UnsupportedMediaType < Error; end          # HTTP 415
+    class RangeNotSatisfiable < Error; end           # HTTP 416
+    class ExpectationFailed < Error; end             # HTTP 417
+    class ImATeapot < Error; end                     # HTTP 418
+    class EnhanceYourCalm < Error; end               # HTTP 420
+    class MisdirectedRequest < Error; end            # HTTP 421
+    class UnprocessableEntity < Error; end           # HTTP 422
+    class Locked < Error; end                        # HTTP 423
+    class FailedDependency < Error; end              # HTTP 424
+    class TooEarly < Error; end                      # HTTP 425
+    class UpgradeRequired < Error; end               # HTTP 426
+    class PreconditionRequired < Error; end          # HTTP 428
+    class TooManyRequests < Error; end               # HTTP 429
+    class RequestHeaderFieldsTooLarge < Error; end   # HTTP 431
+    class UnavailableForLegalReasons < Error; end    # HTTP 451
+    class InternalServerError < Error; end           # HTTP 500
+    class NotImplemented < Error; end                # HTTP 501
+    class BadGateway < Error; end                    # HTTP 502
+    class ServiceUnavailable < Error; end            # HTTP 503
+    class GatewayTimeout < Error; end                # HTTP 504
+    class HttpVersionNotSupported < Error; end       # HTTP 505
+    class VariantAlsoNegotiates < Error; end         # HTTP 506
+    class InsufficientStorage < Error; end           # HTTP 507
+    class LoopDetected < Error; end                  # HTTP 508
+    class NotExtended < Error; end                   # HTTP 510
+    class NetworkAuthenticationRequired < Error; end # HTTP 507
+  end
+end

data/lib/yake/logger.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+
+module Yake
+  class Logger < ::Logger
+    def initialize(logdev = $stdout, *)
+      super
+      @progname  = "-"
+      @formatter = LambdaFormatter.new
+    end
+
+    def wrap(event = nil, context = nil, &block)
+      @progname = "RequestId: #{ context.aws_request_id }" if context.respond_to?(:aws_request_id)
+      info("EVENT #{ event.to_json }")
+      yield(event, context).tap { |res| info("RETURN #{ res.to_json }") }
+    ensure
+      @progname = "-"
+    end
+  end
+
+  class LambdaFormatter < ::Logger::Formatter
+    Format = "%s %s %s\n"
+
+    def call(severity, time, progname, msg)
+      Format % [ severity, progname, msg2str(msg).strip ]
+    end
+  end
+
+  module Loggable
+    attr_accessor :logger
+  end
+
+  extend Loggable
+end

data/lib/yake/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Yake
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: yake
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexander Mancevice
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-04-27 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- alexander.mancevice@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- LICENSE.txt
+- README.md
+- lib/yake.rb
+- lib/yake/api.rb
+- lib/yake/dsl.rb
+- lib/yake/errors.rb
+- lib/yake/logger.rb
+- lib/yake/version.rb
+homepage: https://github.com/amancevice/yake
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Rake-like DSL for declaring AWS Lambda function handlers
+test_files: []