hanami-api 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 671e8eab5f3b562214858055a272e049368bfce7524d639ffa63cd7003bab804
-  data.tar.gz: 461f4066a630f1a1bd66dbd52f4a977a79a4e09737f5861aeabfcc89d87aee04
+  metadata.gz: 11eac74d32637ac1f12ee6d7a774a80501167f46b5a51f6a66f04f4518d82476
+  data.tar.gz: b7b1801a85993adcd839e5ce9d1b460e137ebbbf2a8913af2fb583bf765c7196
 SHA512:
-  metadata.gz: e5398ddac6f97af3898faefd795bbb37f6be9d334163e90e0b68b004eab11e4923b366cc6b44504d06e16b7b67c2b3a3e46ca8a106ee694e65f2f83ab2ab1f41
-  data.tar.gz: 34ad6218b1001a4b66a4ec9512f320649843928afc98bcd968a347dae0d23df2989ebc46bbd407f93734f934cbd725ded04e8528e9f04e365c180d8748a73097
+  metadata.gz: 011cbdb50d4372d08d14d7c037599e3f0c3a6ff3838518702272969bfabf0f1692ee9a8bbbfe1f128b4bcc63d2ef6935ec01e330d78b731e264e3f9be62d9030
+  data.tar.gz: 49bec19e9eaf598b31935e02bd45dfbb2cb949f54beee482210f8a33f50b4eb5ab333915fd9d600c34773faaa4f6a8d480966192077f3428bfc7bb4a65f1a37c

data/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ name: ci
       - ".rubocop.yml"
   pull_request:
     branches:
-      - master
+      - main
   create:
 
 jobs:
@@ -22,7 +22,9 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - "2.7"
+          - "3.2"
+          - "3.1"
+          - "3.0"
     env:
       CODACY_RUN_LOCAL: true
       CODACY_PROJECT_TOKEN: ${{secrets.CODACY_PROJECT_TOKEN}}

data/.rubocop.yml

@@ -5,6 +5,10 @@
 #   * https://github.com/bbatsov/ruby-style-guide
 #   * https://rubocop.readthedocs.io/
 inherit_from:
-  - https://raw.githubusercontent.com/hanami/devtools/master/.rubocop-unstable.yml
+  - https://raw.githubusercontent.com/hanami/devtools/main/.rubocop.yml
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.0
+
+Lint/EmptyBlock:
+  Exclude:
+    - "./spec/integration/hanami/api/block_spec.rb"

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Hanami::API
 Minimal, extremely fast, lightweight Ruby framework for HTTP APIs.
 
+## v0.3.0 - 2022-12-25
+
+### Added
+- [Luca Guidi] Official support for Ruby 3.1 & 3.2
+- [Thomas Jachmann] Streamed responses
+- [Luca Guidi] Introduce `Hanami::API.helpers` to define helper methods to be used in route blocks
+- [Luca Guidi] Introduce `Hanami::API#to_inspect` to inspect app routes
+
+### Changed
+- [Luca Guidi] Drop support for Ruby 2.7
+
+## v0.2.0 - 2021-01-05
+### Added
+- [Luca Guidi] Official support for Ruby: MRI 3.0
+- [Luca Guidi] Introduce `Hanami::API::DSL` which gives the ability to other Ruby web frameworks to use the `Hanami::API` DSL
+
 ## v0.1.2 - 2020-10-21
 ### Fixed
 - [Luca Guidi] Ensure to be able to instantiate an `Hanami::API` app multiple times

data/Gemfile

@@ -4,4 +4,4 @@ source "https://rubygems.org"
 gemspec
 
 gem "byebug", require: false
-gem "hanami-router", git: "https://github.com/hanami/router.git", branch: "unstable"
+gem "hanami-router", git: "https://github.com/hanami/router.git", branch: "main"

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright © 2014-2022 - Hanami Team
+
+MIT License
+
+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

@@ -1,7 +1,53 @@
 # Hanami::API
 
 Minimal, extremely fast, lightweight Ruby framework for HTTP APIs.
-* [Installation](#installation)
+
+## Version
+
+**This branch contains the code for `hanami-api` 0.3.x.**
+
+## Status
+
+[![Gem Version](https://badge.fury.io/rb/hanami-api.svg)](https://badge.fury.io/rb/hanami-api)
+[![CI](https://github.com/hanami/api/workflows/ci/badge.svg?branch=main)](https://github.com/hanami/api/actions?query=workflow%3Aci+branch%3Amain)
+[![Test Coverage](https://codecov.io/gh/hanami/api/branch/main/graph/badge.svg)](https://codecov.io/gh/hanami/api)
+[![Depfu](https://badges.depfu.com/badges/a8545fb67cf32a2c75b6227bc0821027/overview.svg)](https://depfu.com/github/hanami/api?project=Bundler)
+[![Inline Docs](http://inch-ci.org/github/hanami/api.svg)](http://inch-ci.org/github/hanami/api)
+
+## Contact
+
+* Home page: http://hanamirb.org
+* Mailing List: http://hanamirb.org/mailing-list
+* API Doc: http://rdoc.info/gems/hanami-api
+* Bugs/Issues: https://github.com/hanami/api/issues
+* Support: http://stackoverflow.com/questions/tagged/hanami
+* Chat: http://chat.hanamirb.org
+
+## Rubies
+
+__Hanami::API__ supports Ruby (MRI) 3.0+
+
+## Installation
+
+Add these lines to your application's `Gemfile`:
+
+```ruby
+gem "hanami-api"
+gem "puma" # or "webrick", or "thin", "falcon"
+```
+
+And then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install hanami-api
+```
+
 * [Performance](#performance)
   + [Runtime](#runtime)
   + [Memory](#memory)
@@ -13,9 +59,12 @@ Minimal, extremely fast, lightweight Ruby framework for HTTP APIs.
     - [Rack endpoint](#rack-endpoint)
     - [Block endpoint](#block-endpoint)
       * [String (body)](#string-body)
+      * [Enumerator (body)](#enumerator-body)
       * [Integer (status code)](#integer-status-code)
       * [Integer, String (status code, body)](#integer-string-status-code-body)
+      * [Integer, Enumerator (status code, body)](#integer-enumerator-status-code-body)
       * [Integer, Hash, String (status code, headers, body)](#integer-hash-string-status-code-headers-body)
+      * [Integer, Hash, Enumerator (status code, headers, body)](#integer-hash-enumerator-status-code-headers-body)
   + [Block context](#block-context)
     - [env](#env)
     - [status](#status)
@@ -27,31 +76,14 @@ Minimal, extremely fast, lightweight Ruby framework for HTTP APIs.
     - [back](#back)
     - [json](#json)
   + [Scope](#scope)
+  + [Helpers](#helpers)
   + [Rack Middleware](#rack-middleware)
+  + [Streamed Responses](#streamed-responses)
   + [Body Parsers](#body-parsers)
+* [Testing](#testing)
 * [Development](#development)
 * [Contributing](#contributing)
 
-## Installation
-
-Add this line to your application's `Gemfile`:
-
-```ruby
-gem "hanami-api"
-```
-
-And then execute:
-
-```shell
-$ bundle install
-```
-
-Or install it yourself as:
-
-```shell
-$ gem install hanami-api
-```
-
 ## Performance
 
 Benchmark against an app with 10,000 routes, hitting the 10,000th to measure the worst case scenario.
@@ -145,6 +177,7 @@ get "/", to: MyEndpoint.new
   * `post`
   * `patch`
   * `put`
+  * `delete`
   * `options`
   * `trace`
   * `link`
@@ -177,6 +210,16 @@ end
 
 It will return `[200, {}, ["Hello, world"]]`
 
+##### Enumerator (body)
+
+```ruby
+get "/" do
+  Enumerator.new { ... }
+end
+```
+
+It will return `[200, {}, Enumerator]`, see [Streamed Responses](#streamed-responses)
+
 ##### Integer (status code)
 
 ```ruby
@@ -197,6 +240,16 @@ end
 
 It will return `[401, {}, ["You shall not pass"]]`
 
+##### Integer, Enumerator (status code, body)
+
+```ruby
+get "/" do
+  [401, Enumerator.new { ... }]
+end
+```
+
+It will return `[401, {}, Enumerator]`, see [Streamed Responses](#streamed-responses)
+
 ##### Integer, Hash, String (status code, headers, body)
 
 ```ruby
@@ -207,6 +260,16 @@ end
 
 It will return `[401, {"X-Custom-Header" => "foo"}, ["You shall not pass"]]`
 
+##### Integer, Hash, Enumerator (status code, headers, body)
+
+```ruby
+get "/" do
+  [401, {"X-Custom-Header" => "foo"}, Enumerator.new { ... }]
+end
+```
+
+It will return `[401, {"X-Custom-Header" => "foo"}, Enumerator]`, see [Streamed Responses](#streamed-responses)
+
 ### Block context
 
 When using the block syntax there is a rich API to use.
@@ -272,6 +335,14 @@ get "/" do
 end
 ```
 
+Set HTTP response body using a [Streamed Response](#streamed-responses)
+
+```ruby
+get "/" do
+  body Enumerator.new { ... }
+end
+```
+
 #### params
 
 Access params for current request
@@ -307,6 +378,14 @@ end
 
 It sets a Rack response: `[401, {}, ["You shall not pass"]]`
 
+You can also use a [Streamed Response](#streamed-responses) here
+
+```ruby
+get "/authenticate" do
+  halt(401, Enumerator.new { ... })
+end
+```
+
 #### redirect
 
 Redirects request and immediately halts it
@@ -363,6 +442,15 @@ get "/user/:id" do
 end
 ```
 
+If you want a [Streamed Response](#streamed-responses)
+
+```ruby
+get "/users" do
+  users = Enumerator.new { ... }
+  json(users)
+end
+```
+
 ### Scope
 
 Prefixing routes is possible with routing scopes:
@@ -377,6 +465,58 @@ end
 
 It will generate a route with `"/api/v1/users"` as path.
 
+### Helpers
+
+Define helper methods available within the block context.
+Helper methods have access to default utilities available in block context (e.g. `#halt`).
+
+Helpers can be defined inline by passing a block to the `.helpers` method:
+
+```ruby
+require "hanami/api"
+
+class MyAPI < Hanami::API
+  helpers do
+    def redirect_to_root
+      # redirect method is provided by Hanami::API block context
+      redirect "/"
+    end
+  end
+
+  root { "Hello, World" }
+
+  get "/legacy" do
+    redirect_to_root
+  end
+end
+```
+
+Alternatively, `.helpers` accepts a module.
+
+```ruby
+require "hanami/api"
+
+class MyAPI < Hanami::API
+  module Authentication
+    private
+
+    def unauthorized
+      halt(401)
+    end
+  end
+
+  helpers(Authentication)
+
+  root { "Hello, World" }
+
+  get "/secrets" do
+    unauthorized
+  end
+end
+```
+
+You can use `.helpers` multiple times in the same app.
+
 ### Rack Middleware
 
 To mount a Rack middleware it's possible with `.use`
@@ -411,6 +551,56 @@ it's part of the top level scope. `ApiAuthentication` it's used for all the API
 versions, because it's defined in the `"api"` scope. `ApiV1Deprecation` is used
 only by the routes in `"v1"` scope, but not by `"v2"`.
 
+### Streamed Responses
+
+When the work to be done by the server takes time, it may be a good idea to
+stream your response. For this, you just use an `Enumerator` anywhere you would
+normally use a `String` as body or another `Object` as JSON response. Here's an
+example of streaming JSON data:
+
+```ruby
+scope "stream" do
+  use ::Rack::Chunked
+
+  get "/data" do
+    Enumerator.new do |yielder|
+      data = %w[a b c]
+      data.each do |item|
+        yielder << item
+      end
+    end
+  end
+
+  get "/to_enum" do
+    %w[a b c].to_enum
+  end
+
+  get "/json" do
+    result = Enumerator.new do |yielder|
+      data = %w[a b c]
+      data.each do |item|
+        yielder << item
+      end
+    end
+
+    json(result)
+  end
+end
+```
+
+Note:
+
+* Returning an `Enumerator` will also work without `Rack::Chunked`, it just
+  won't stream but return the whole body at the end instead.
+* Data pushed to `yielder` MUST be a `String`.
+* Streaming does not work with WEBrick as it buffers its response. We recommend
+  using `puma`, though you may find success with other servers.
+* To manual test this feature use a web browser or cURL:
+
+```shell
+$ curl --raw -i http://localhost:2300/stream/data
+```
+
 ### Body Parsers
 
 Rack ignores request bodies unless they come from a form submission.
@@ -425,6 +615,59 @@ require "hanami/middleware/body_parser"
 use Hanami::Middleware::BodyParser, :json
 ```
 
+## Testing
+
+## Unit testing
+You can unit test your `Hanami::API` app by passing a `env` hash to your app's `#call` method.
+
+The keys that (based on the Rack standard) `Hanami::API` uses for routing are:
+* `PATH_INFO`
+* `REQUEST_METHOD`
+
+
+For example, a spec for the basic app in the [Usage section](https://github.com/hanami/api#usage) could be:
+
+```ruby
+require "my_project/app"
+
+RSpec.describe App do
+  describe "#call" do
+    it "returns successfully" do
+      response = subject.call({"PATH_INFO" => "/", "REQUEST_METHOD" => "GET"})
+      expect(response).to eq([200, {}, ["Hello, world"]])
+    end
+  end
+end
+```
+
+## Integration testing
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "rack-test", group: :test
+```
+
+In a test, load `Rack::Test`:
+
+```ruby
+require "rack/test"
+```
+
+and then, inside your spec/test, include its helper methods:
+
+```ruby
+include Rack::Test::Methods
+```
+
+Then you can use its methods like `get` and `last_response`, e.g.:
+
+```ruby
+it "returns the status 200" do
+  get "/"
+  expect(last_response.status).to eq 200
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -435,3 +678,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/hanami/api.
 
+## Copyright
+
+Copyright © 2014-2022 Hanami Team – Released under MIT License.

data/hanami-api.gemspec

@@ -11,13 +11,14 @@ Gem::Specification.new do |spec|
   spec.summary       = "Hanami API"
   spec.description   = "Extremely fast and lightweight HTTP API"
   spec.homepage      = "http://rubygems.org"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
+  spec.licenses      = ["MIT"]
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/hanami/api"
-  spec.metadata["changelog_uri"] = "https://github.com/hanami/api/blob/master/CHANGELOG.md"
+  spec.metadata["changelog_uri"] = "https://github.com/hanami/api/blob/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -28,11 +29,12 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+  spec.metadata["rubygems_mfa_required"] = "true"
 
-  spec.add_dependency "hanami-router", "~> 2.0.alpha"
+  spec.add_dependency "hanami-router", "~> 2.0"
 
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.8"
-  spec.add_development_dependency "rubocop", "~> 0.86"
+  spec.add_development_dependency "rubocop", "~> 1.0"
   spec.add_development_dependency "yard", "~> 0.9"
 end

data/lib/hanami/api/block/context.rb

@@ -124,7 +124,12 @@ module Hanami
         #   end
         def json(object, mime = "application/json")
           headers["Content-Type"] = mime
-          JSON.generate(object)
+          case object
+          in Enumerator => collection
+            json_enum(collection)
+          else
+            JSON.generate(object)
+          end
         end
 
         # @since 0.1.0
@@ -132,10 +137,11 @@ module Hanami
         #
         def call
           case caught
-            in String => body
+          in String => body
             [status, headers, [body]]
-            in Integer => status
-            # rubocop:disable Style/RedundantSelf
+          in Enumerator => body
+            [status, headers, body]
+          in Integer => status
             #
             # NOTE: It must use `self.body` so it will pick the method defined above.
             #
@@ -144,12 +150,16 @@ module Hanami
             #       When that happens, the body that was manually set is ignored,
             #       which results in a bug.
             [status, headers, [self.body || http_status(status)]]
-            # rubocop:enable Style/RedundantSelf
-            in [Integer => status, String => body]
+          in [Integer => status, String => body]
             [status, headers, [body]]
-            in [Integer => status, Hash => caught_headers, String => body]
+          in [Integer => status, Enumerator => body]
+            [status, headers, body]
+          in [Integer => status, Hash => caught_headers, String => body]
             headers.merge!(caught_headers)
             [status, headers, [body]]
+          in [Integer => status, Hash => caught_headers, Enumerator => body]
+            headers.merge!(caught_headers)
+            [status, headers, body]
           end
         end
 
@@ -168,6 +178,20 @@ module Hanami
         def http_status(code)
           Rack::Utils::HTTP_STATUS_CODES.fetch(code)
         end
+
+        # @since x.x.x
+        # @api private
+        def json_enum(collection)
+          Enumerator.new do |yielder|
+            yielder << "["
+            collection.each_with_index do |item, i|
+              yielder << "," if i.positive?
+              yielder << JSON.generate(item)
+            end
+          ensure
+            yielder << "]"
+          end
+        end
       end
     end
   end

data/lib/hanami/api/dsl.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Hanami
+  class API
+    # Expose Hanami::API features to third party frameworks that need to expose
+    # a routing DSL.
+    #
+    # @since 0.2.0
+    #
+    # @example
+    #   # framework.rb
+    #    require "hanami/api"
+    #
+    #    module Framework
+    #      class App
+    #        def self.inherited(base)
+    #          super
+    #          base.extend(Hanami::API::DSL)
+    #        end
+    #      end
+    #    end
+    #
+    #    # app.rb
+    #    require "framework/app"
+    #
+    #    class MyApp < Framework::App
+    #      routes do
+    #        root { "Hello, World!" }
+    #      end
+    #    end
+    #
+    #    # config.ru
+    #    require_relative "./app"
+    #
+    #    run MyApp.new
+    module DSL
+      # @since 0.2.0
+      # @api private
+      def self.extended(app)
+        super
+
+        app.extend(ClassMethods)
+        app.extend(ClassMethods::Routes)
+        app.include(InstanceMethods)
+      end
+
+      # @since 0.2.0
+      # @api private
+      module ClassMethods
+        # @since 0.2.0
+        # @api private
+        attr_reader :router
+
+        # @since 0.2.0
+        # @api private
+        def self.extended(app)
+          super
+
+          app.class_eval do
+            klass = Block::Context.dup
+            app.const_set(:BlockContext, klass)
+
+            @router = Router.new(block_context: klass)
+          end
+        end
+
+        # @since 0.2.0
+        # @api private
+        module Routes
+          # A block to define application routes
+          #
+          # This is ONLY available for third-party frameworks that use
+          # Hanami::API DSL.
+          #
+          # If you use Hanami::API directly, this method isn't available.
+          #
+          # @param blk [Proc] the block to define the routes
+          #
+          # @see Hanami::API::Router
+          #
+          # @since 0.2.0
+          # @api public
+          def routes(&blk)
+            router.instance_eval(&blk)
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Initialize the app
+        #
+        # @param router [Hanami::API::Router] the application router
+        #
+        # @since 0.2.0
+        # @api public
+        def initialize(router: self.class.router.dup)
+          @router = router
+
+          freeze
+        end
+
+        # @since 0.2.0
+        # @api private
+        def freeze
+          @app = @router.to_rack_app
+          @url_helpers = @router.url_helpers
+          @router.remove_instance_variable(:@url_helpers)
+          remove_instance_variable(:@router)
+          @url_helpers.freeze
+          @app.freeze
+          super
+        end
+
+        # Compatibility with Rack protocol
+        #
+        # @param env [Hash] a Rack env for the current request
+        #
+        # @since 0.2.0
+        # @api public
+        def call(env)
+          @app.call(env)
+        end
+
+        # Printable routes
+        #
+        # @return [String] printable routes
+        #
+        # @since x.x.x
+        # @api public
+        def to_inspect
+          @app.to_inspect
+        end
+      end
+    end
+  end
+end

data/lib/hanami/api/middleware.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "hanami/middleware/app"
+
 module Hanami
   class API
     # Hanami::API middleware stack
@@ -7,9 +9,6 @@ module Hanami
     # @since 0.1.0
     # @api private
     module Middleware
-      require "hanami/api/middleware/app"
-      require "hanami/api/middleware/trie"
-
       # Middleware stack
       #
       # @since 0.1.0
@@ -44,7 +43,7 @@ module Hanami
           mapping = to_hash
           return app if mapping.empty?
 
-          App.new(app, mapping)
+          Hanami::Middleware::App.new(app, mapping)
         end
 
         private

data/lib/hanami/api/router.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
 require "hanami/router"
+require "hanami/router/inspector"
 require "hanami/api/block/context"
 
 module Hanami
   class API
     # @since 0.1.0
     class Router < ::Hanami::Router
+      # @since x.x.x
+      # @api private
+      attr_reader :inspector
+
       # @since 0.1.0
       # @api private
-      def initialize(block_context: Block::Context, **kwargs)
-        super(block_context: block_context, **kwargs)
+      def initialize(block_context: Block::Context, inspector: Inspector.new, **kwargs)
+        super(block_context: block_context, inspector: inspector, **kwargs)
         @stack = Middleware::Stack.new(@path_prefix.to_s)
       end
 
@@ -34,6 +39,16 @@ module Hanami
       def to_rack_app
         @stack.finalize(self)
       end
+
+      # Returns formatted routes
+      #
+      # @return [String] formatted routes
+      #
+      # @since x.x.x
+      # @api private
+      def to_inspect
+        @inspector.call
+      end
     end
   end
 end

data/lib/hanami/api/version.rb

@@ -3,6 +3,6 @@
 module Hanami
   class API
     # @since 0.1.0
-    VERSION = "0.1.2"
+    VERSION = "0.3.0"
   end
 end

data/lib/hanami/api.rb

@@ -9,21 +9,66 @@ module Hanami
     require "hanami/api/error"
     require "hanami/api/router"
     require "hanami/api/middleware"
+    require "hanami/api/dsl"
 
     # @since 0.1.0
     # @api private
     def self.inherited(app)
       super
 
-      app.class_eval do
-        @router = Router.new
-      end
+      app.extend(DSL::ClassMethods)
+      app.include(DSL::InstanceMethods)
     end
 
-    class << self
-      # @since 0.1.1
-      # @api private
-      attr_reader :router
+    # Defines helper methods available within the block context.
+    # Helper methods have access to default utilities available in block
+    # context (e.g. `#halt`).
+    #
+    # @param mod [Module] optional module to include in block context
+    # @param blk [Proc] inline helper definitions
+    #
+    # @since x.x.x
+    #
+    # @example Inline helpers definition
+    #   require "hanami/api"
+    #
+    #   class MyAPI < Hanami::API
+    #     helpers do
+    #       def redirect_to_root
+    #         # redirect method is provided by Hanami::API block context
+    #         redirect "/"
+    #       end
+    #     end
+    #
+    #     root { "Hello, World" }
+    #
+    #     get "/legacy" do
+    #       redirect_to_root
+    #     end
+    #   end
+    #
+    # @example Module helpers definition
+    #   require "hanami/api"
+    #
+    #   class MyAPI < Hanami::API
+    #     module Authentication
+    #       private
+    #
+    #       def unauthorized
+    #         halt(401)
+    #       end
+    #     end
+    #
+    #     helpers(Authentication)
+    #
+    #     root { "Hello, World" }
+    #
+    #     get "/secrets" do
+    #       unauthorized
+    #     end
+    #   end
+    def self.helpers(mod = nil, &blk)
+      const_get(:BlockContext).include(mod || Module.new(&blk))
     end
 
     # Defines a named root route (a GET route for "/")
@@ -50,8 +95,8 @@ module Hanami
     #       "Hello from Hanami!"
     #     end
     #   end
-    def self.root(*args, **kwargs, &blk)
-      @router.root(*args, **kwargs, &blk)
+    def self.root(...)
+      @router.root(...)
     end
 
     # Defines a route that accepts GET requests for the given path.
@@ -87,8 +132,8 @@ module Hanami
     #   class MyAPI < Hanami::API
     #     get "/users/:id", to: ->(*) { [200, {}, ["OK"]] }, id: /\d+/
     #   end
-    def self.get(*args, **kwargs, &blk)
-      @router.get(*args, **kwargs, &blk)
+    def self.get(...)
+      @router.get(...)
     end
 
     # Defines a route that accepts POST requests for the given path.
@@ -102,8 +147,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.post(*args, **kwargs, &blk)
-      @router.post(*args, **kwargs, &blk)
+    def self.post(...)
+      @router.post(...)
     end
 
     # Defines a route that accepts PATCH requests for the given path.
@@ -117,8 +162,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.patch(*args, **kwargs, &blk)
-      @router.patch(*args, **kwargs, &blk)
+    def self.patch(...)
+      @router.patch(...)
     end
 
     # Defines a route that accepts PUT requests for the given path.
@@ -132,8 +177,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.put(*args, **kwargs, &blk)
-      @router.put(*args, **kwargs, &blk)
+    def self.put(...)
+      @router.put(...)
     end
 
     # Defines a route that accepts DELETE requests for the given path.
@@ -147,8 +192,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.delete(*args, **kwargs, &blk)
-      @router.delete(*args, **kwargs, &blk)
+    def self.delete(...)
+      @router.delete(...)
     end
 
     # Defines a route that accepts TRACE requests for the given path.
@@ -162,8 +207,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.trace(*args, **kwargs, &blk)
-      @router.trace(*args, **kwargs, &blk)
+    def self.trace(...)
+      @router.trace(...)
     end
 
     # Defines a route that accepts OPTIONS requests for the given path.
@@ -177,8 +222,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.options(*args, **kwargs, &blk)
-      @router.options(*args, **kwargs, &blk)
+    def self.options(...)
+      @router.options(...)
     end
 
     # Defines a route that accepts LINK requests for the given path.
@@ -192,8 +237,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.link(*args, **kwargs, &blk)
-      @router.link(*args, **kwargs, &blk)
+    def self.link(...)
+      @router.link(...)
     end
 
     # Defines a route that accepts UNLINK requests for the given path.
@@ -207,8 +252,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.unlink(*args, **kwargs, &blk)
-      @router.unlink(*args, **kwargs, &blk)
+    def self.unlink(...)
+      @router.unlink(...)
     end
 
     # Defines a route that redirects the incoming request to another path.
@@ -221,8 +266,8 @@ module Hanami
     # @since 0.1.0
     #
     # @see .get
-    def self.redirect(*args, **kwargs, &blk)
-      @router.redirect(*args, **kwargs, &blk)
+    def self.redirect(...)
+      @router.redirect(...)
     end
 
     # Defines a routing scope. Routes defined in the context of a scope,
@@ -245,8 +290,8 @@ module Hanami
     #   end
     #
     #   # It generates a route with a path `/v1/users`
-    def self.scope(*args, **kwargs, &blk)
-      @router.scope(*args, **kwargs, &blk)
+    def self.scope(...)
+      @router.scope(...)
     end
 
     # Mount a Rack application at the specified path.
@@ -270,8 +315,8 @@ module Hanami
     #   class MyAPI < Hanami::API
     #     mount MyRackApp.new, at: "/foo"
     #   end
-    def self.mount(*args, **kwargs, &blk)
-      @router.mount(*args, **kwargs, &blk)
+    def self.mount(...)
+      @router.mount(...)
     end
 
     # Use a Rack middleware
@@ -292,29 +337,6 @@ module Hanami
       @router.use(middleware, *args, &blk)
     end
 
-    # @since 0.1.0
-    def initialize(router: self.class.router.dup)
-      @router = router
-
-      freeze
-    end
-
-    # @since 0.1.0
-    def freeze
-      @app = @router.to_rack_app
-      @url_helpers = @router.url_helpers
-      @router.remove_instance_variable(:@url_helpers)
-      remove_instance_variable(:@router)
-      @url_helpers.freeze
-      @app.freeze
-      super
-    end
-
-    # @since 0.1.0
-    def call(env)
-      @app.call(env)
-    end
-
     # TODO: verify if needed here on in block context
     #
     # @since 0.1.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hanami-api
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Luca Guidi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-10-21 00:00:00.000000000 Z
+date: 2022-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hanami-router
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.alpha
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.alpha
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.86'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.86'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +93,7 @@ files:
 - ".rubocop.yml"
 - CHANGELOG.md
 - Gemfile
+- LICENSE.md
 - README.md
 - Rakefile
 - bin/console
@@ -100,20 +101,20 @@ files:
 - hanami-api.gemspec
 - lib/hanami/api.rb
 - lib/hanami/api/block/context.rb
+- lib/hanami/api/dsl.rb
 - lib/hanami/api/error.rb
 - lib/hanami/api/middleware.rb
-- lib/hanami/api/middleware/app.rb
-- lib/hanami/api/middleware/node.rb
-- lib/hanami/api/middleware/trie.rb
 - lib/hanami/api/router.rb
 - lib/hanami/api/version.rb
 homepage: http://rubygems.org
-licenses: []
+licenses:
+- MIT
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: http://rubygems.org
   source_code_uri: https://github.com/hanami/api
-  changelog_uri: https://github.com/hanami/api/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/hanami/api/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -122,14 +123,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.3
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: Hanami API

data/lib/hanami/api/middleware/app.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-require "rack/builder"
-
-module Hanami
-  class API
-    module Middleware
-      # Hanami::API middleware stack
-      #
-      # @since 0.1.1
-      # @api private
-      class App
-        # @since 0.1.1
-        # @api private
-        def initialize(app, mapping)
-          @trie = Hanami::API::Middleware::Trie.new(app)
-
-          mapping.each do |path, stack|
-            builder = Rack::Builder.new
-
-            stack.each do |middleware, args, blk|
-              builder.use(middleware, *args, &blk)
-            end
-
-            builder.run(app)
-
-            @trie.add(path, builder.to_app.freeze)
-          end
-
-          @trie.freeze
-        end
-
-        # @since 0.1.1
-        # @api private
-        def call(env)
-          @trie.find(env["PATH_INFO"]).call(env)
-        end
-      end
-    end
-  end
-end

data/lib/hanami/api/middleware/node.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-module Hanami
-  class API
-    module Middleware
-      # Trie node to register scopes with custom Rack middleware
-      #
-      # @api private
-      # @since 0.1.1
-      class Node
-        # @api private
-        # @since 0.1.1
-        attr_reader :app
-
-        # @api private
-        # @since 0.1.1
-        def initialize
-          @app = nil
-          @children = {}
-        end
-
-        # @api private
-        # @since 0.1.1
-        def freeze
-          @children.each(&:freeze)
-          super
-        end
-
-        # @api private
-        # @since 0.1.1
-        def put(segment)
-          @children[segment] ||= self.class.new
-        end
-
-        # @api private
-        # @since 0.1.1
-        def get(segment)
-          @children.fetch(segment) { self if leaf? }
-        end
-
-        # @api private
-        # @since 0.1.1
-        def app!(app)
-          @app = app
-        end
-
-        # @api private
-        # @since 0.1.1
-        def app?
-          @app
-        end
-
-        # @api private
-        # @since 0.1.1
-        def leaf?
-          @children.empty?
-        end
-      end
-    end
-  end
-end

data/lib/hanami/api/middleware/trie.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-require "hanami/api/middleware/node"
-
-module Hanami
-  class API
-    module Middleware
-      # Trie to register scopes with custom Rack middleware
-      #
-      # @api private
-      # @since 0.1.1
-      class Trie
-        # @api private
-        # @since 0.1.1
-        def initialize(app)
-          @app = app
-          @root = Node.new
-        end
-
-        # @api private
-        # @since 0.1.1
-        def freeze
-          @root.freeze
-          super
-        end
-
-        # @api private
-        # @since 0.1.1
-        def add(path, app)
-          node = @root
-          for_each_segment(path) do |segment|
-            node = node.put(segment)
-          end
-
-          node.app!(app)
-        end
-
-        # @api private
-        # @since 0.1.1
-        def find(path)
-          node = @root
-
-          for_each_segment(path) do |segment|
-            break unless node
-
-            node = node.get(segment)
-          end
-
-          return node.app if node&.app?
-
-          @root.app || @app
-        end
-
-        # @api private
-        # @since 0.1.1
-        def empty?
-          @root.leaf?
-        end
-
-        private
-
-        # @api private
-        # @since 0.1.1
-        def for_each_segment(path, &blk)
-          _, *segments = path.split(/\//)
-          segments.each(&blk)
-        end
-      end
-    end
-  end
-end