flon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dcd15fb29f7a61dc56644751c6b3f3f6a6181e148a386e71b2b9d5197048f3dd
+  data.tar.gz: f12632af7ac2b14a6ba79a77fcb8cdc0d6905de5ad47bb59bc73a5d5b39d3089
+SHA512:
+  metadata.gz: c552c94ec88849cdfb0d6e68b584609154f7ff73f9d486ee95860bca47416f2bb15327a6f97890810c5c8de2cb9a0e75c8503985d000448115e9d2e518e66bd7
+  data.tar.gz: 9051e7d9f471a94b78a3731e2996eee2e61c9d7f10babc144873314a1d4cbc8cd6b2b1d1036ae99da34fd412b56411e0681d2872e91b731b3996fe914628723f

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  TargetRubyVersion: 2.5
+
+Layout/EndOfLine:
+  EnforcedStyle: lf
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.3
+before_install: gem install bundler -v 2.0.2

data/.yardopts

@@ -0,0 +1 @@
+- README.md LICENSE.txt

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in flon.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 unleashy
+
+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,212 @@
+# Flon
+
+Flon, the API maker that uses JSON. It focuses on not doing any magic: it’s
+just a thin and convenient wrapper over Rack, with a hopefully obvious DSL. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'flon'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install flon
+
+## Usage
+
+### Basic usage
+
+To use Flon, simply make a plain class extending `Flon::DSL`. This will put the
+router DSL in your class scope.
+
+```ruby
+require 'flon'
+
+class MyApi
+  extend Flon::DSL
+
+  def initialize
+    @names = []
+  end
+
+  namespace '/names' do
+    get '/'
+    attr_reader :names
+
+    post '/new'
+    def add_name(_params, body)
+      @names << body
+    end
+
+    namespace '/:index' do
+      get '/'
+      def name_by_index(params)
+        @names[params[:index]]
+      end
+
+      put '/edit'
+      def change_name(params, body)
+        @names[params[:index]] = body
+      end
+    end
+  end
+end
+```
+
+You can then create a `Flon::Api` using this:
+
+```ruby
+api = Flon::Api.new(MyApi.new)
+```
+
+Note how you initialise the `MyApi` normally—you can use this for dependency
+injection without a headache.
+
+`Flon::Api` is a bog-standard Rack app, so you can just use it in `config.ru`,
+or whatever method you use.
+
+### Routing
+
+The DSL defines methods for routing based on every HTTP request method, except
+HEAD, TRACE, OPTIONS, and CONNECT. HEAD is handled by GET routes but the body
+is discarded.
+
+When you call a routing method, the next method you define will be bound to
+that route.
+
+```ruby
+get '/route'
+def get_route
+  # matches GET /route and HEAD /route
+end
+
+post '/route'
+def post_route
+  # matches POST /route
+end
+
+put '/route'
+def put_route
+  # matches PUT /route
+end
+
+delete '/route'
+def delete_route
+  # matches DELETE /route
+end
+
+patch '/route'
+def patch_route
+  # matches PATCH /route
+end
+```
+
+Each routing DSL method takes a single route pattern as a `String`. The route
+pattern is the exact same as [Sinatra’s](https://github.com/sinatra/mustermann/blob/master/mustermann/README.md#-sinatra-pattern).
+
+The bound method is called when an HTTP request matches that route with that
+HTTP method.
+
+The method will receive two arguments, in that order:
+
+1. A parameters hash, containing the query string parameters and the route
+   parameters;
+2. A body object, containing the HTTP request’s body parsed with `JSON.parse`.
+   For GETs, HEADs, and DELETEs, this will be `nil`.
+
+#### Namespaces
+
+You can also **namespace** routes:
+
+```ruby
+namespace '/users' do
+  get '/'
+  attr_reader :users # GET /users
+
+  post '/new'
+  def add_user(_params, user) # /users/new
+    @users << user
+  end
+
+  namespace '/:id' do
+    get
+    def user_by_id(params) # GET /users/:id
+      @users[params[:id]]
+    end
+
+    put '/edit'
+    def edit_user(params, body) # PUT /users/:id/edit
+      @users[params[:id]] = body
+    end
+  end
+end
+```
+
+Namespaces are entirely “virtual”, that is, they just concatenate their route
+patterns with their children, so they’re just there for DRYness.
+
+### Versioning
+
+The `version` method applies a namespace throughout every route:
+
+```ruby
+version '/v1'
+
+get '/yes'
+def yes
+  'yes'
+end
+
+get '/no'
+def no
+  'no'
+end
+``` 
+
+Going to `/yes` will give you a 404, but going to `/v1/yes` will give you
+`"yes"`. The same thing happens with the `/no` route.
+
+In reality, `version` is just an alias for `namespace`.
+
+### Responding
+
+Whatever is returned by the route’s method is `#to_json`’d and sent back. If
+you want to return a custom status code, return a `Flon::Response` object,
+which takes the status code as the first argument and the body as the second
+argument of its constructor:
+
+```ruby
+get '/admin'
+def admin
+  Flon::Response.new(403, 'No. Go away.')
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake` to run rubocop and 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 tags, 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/unleashy/flon](https://github.com/unleashy/flon).
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[rubocop spec]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'flon'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/flon.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'flon/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'flon'
+  spec.version       = Flon::VERSION
+  spec.authors       = ['unleashy']
+  spec.email         = ['unleashy@users.noreply.github.com']
+
+  spec.summary       = 'Flon, the API maker that uses JSON'
+  spec.homepage      = 'https://github.com/unleashy/flon'
+  spec.license       = 'MIT'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  # 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.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'mustermann', '~> 1.0'
+  spec.add_dependency 'rack', '~> 2.0'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '>= 0.74.0'
+  spec.add_development_dependency 'simplecov', '>= 0.17.0'
+end

data/lib/flon.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'flon/version'
+require 'flon/router'
+require 'flon/dsl'
+require 'flon/api'
+
+# The main module.
+module Flon
+  # Flon's main error class.
+  class Error < StandardError; end
+end

data/lib/flon/api.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'rack'
+require 'json'
+
+module Flon
+  # Represents a response, with an integer status and a body that will be
+  # #to_json'd.
+  #
+  # @!attribute [r] status
+  #   @return [Integer] the status to use when responding
+  #
+  # @!attribute [r] body
+  #   @return [#to_json] the object to respond with that shall be #to_json'd
+  Response = Struct.new(:status, :body)
+
+  # This class is Flon's Rack application.
+  class Api
+    # Creates a new {Api} object with the given API.
+    #
+    # @param [Object] api the API to use; its class must respond to #router and
+    #   the result must be a {Router}.
+    # @return [Api] the newly constructed object
+    def initialize(api)
+      raise ArgumentError, "given API's class does not respond to #routes" unless valid_api?(api)
+
+      @api    = api
+      @router = api.class.router
+    end
+
+    # Implements the Rack interface.
+    #
+    # @param [Hash] env a rack environment
+    # @return [Array] a rack-suitable response
+    def call(env)
+      request = Rack::Request.new(env)
+      response = dispatch(request)
+      [response.status, { 'Content-Type' => 'application/json' }, [response.body]]
+    end
+
+    private
+
+    def dispatch(request)
+      method = http_method_to_symbol(request.request_method)
+      path   = request.path_info
+
+      match = @router.match(method, path)
+      case match
+      when :bad_path then Response.new(404, '"404 Not Found"')
+      when :bad_method then Response.new(405, '"405 Method Not Allowed"')
+      else call_action(request.params, match, receives_body?(method) ? request.body.read : nil)
+      end
+    end
+
+    def call_action(params, match, body)
+      params = params.transform_keys(&:to_sym).merge(match.params)
+      responsify(call_respect_arity(match.action.bind(@api), params, body))
+    end
+
+    def responsify(result)
+      if result.is_a?(Response)
+        result.tap { |it| it.body = it.body.to_json }
+      else
+        Response.new(200, result.to_json)
+      end
+    end
+
+    def call_respect_arity(method, *args)
+      arity = method.arity
+      arity.negative? ? method.call(*args) : method.call(*args[0...arity])
+    end
+
+    def http_method_to_symbol(http_method)
+      http_method.downcase.to_sym
+    end
+
+    def receives_body?(http_method)
+      http_method != :get && http_method != :delete
+    end
+
+    def valid_api?(api)
+      api.class.respond_to?(:router) && api.class.router.is_a?(Flon::Router)
+    end
+  end
+end

data/lib/flon/dsl.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'flon/router'
+
+module Flon
+  # This module holds Flon's DSL. You should extend it in your class.
+  #
+  # @example
+  #   class BreadApi
+  #     extend Flon::DSL
+  #
+  #     get '/bread'
+  #     def bread
+  #       'bread.'
+  #     end
+  #   end
+  module DSL
+    # @!group Routing
+
+    # @!method get(path)
+    #   Creates a GET route from path, bound to the next defined method.
+    #   @param [String] path the path to bind to
+    #   @return [void]
+    # @!method post(path)
+    #   Creates a POST route from path, bound to the next defined method.
+    #   @param [String] path the path to bind to
+    #   @return [void]
+    # @!method put(path)
+    #   Creates a PUT route from path, bound to the next defined method.
+    #   @param [String] path the path to bind to
+    #   @return [void]
+    # @!method delete(path)
+    #   Creates a DELETE route from path, bound to the next defined method.
+    #   @param [String] path the path to bind to
+    #   @return [void]
+    # @!method patch(path)
+    #   Creates a PATCH route from path, bound to the next defined method.
+    #   @param [String] path the path to bind to
+    #   @return [void]
+    %i[get post put delete patch].each do |http_method|
+      define_method(http_method) do |path|
+        @current_route = [http_method, namespaces.join + path]
+      end
+    end
+
+    # Creates a namespace of the given path. If a block is given, the namespace
+    # is local to the block. If not, it is applied to the rest of the API. You
+    # may not call this method without a block twice.
+    #
+    # @param [String] path the path to use
+    # @return [void]
+    def namespace(path)
+      if block_given?
+        namespaces.push(path)
+        yield
+        namespaces.pop
+      else
+        unless namespaces.empty?
+          raise Flon::Error, 'cannot declare a nested global namespace or declare a global namespace twice'
+        end
+
+        namespaces.push(path)
+      end
+    end
+
+    alias version namespace
+
+    # @!endgroup
+
+    # @api private
+    def router
+      @router ||= Flon::Router.new
+    end
+
+    # @api private
+    def namespaces
+      @namespaces ||= []
+    end
+
+    # @api private
+    def method_added(name)
+      return unless @current_route
+
+      http_method, path = @current_route
+      router.add_route(http_method, path, instance_method(name))
+
+      @current_route = nil
+    end
+  end
+end

data/lib/flon/router.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'mustermann/sinatra'
+
+module Flon
+  # Handles a set of routes mapped to actions. Note that the Router API is
+  # mainly for private Flon use.
+  class Router
+    # A route's match is encapsulated in this struct. {#action} has the action
+    # associated with the route matched against and {#params} has the parameters
+    # hash.
+    #
+    # @!attribute [r] action
+    #   @return the route's action
+    #
+    # @!attribute [r] params
+    #   @return [Hash{Symbol => Object}] the route's bound parameters
+    Match = Struct.new(:action, :params)
+
+    # The HTTP methods as symbols that this router will handle.
+    VALID_HTTP_METHODS = %i[get post put delete patch].freeze
+
+    # @return [Array<Mustermann::Sinatra, Hash{Symbol => Object}>] the current route set
+    attr_reader :routes
+
+    # Creates a new Router with an empty route set.
+    # @return [Router] the newly constructed object
+    def initialize
+      @routes = []
+    end
+
+    # Adds a route to this router's route set.
+    #
+    # @param [Symbol] method the method to use
+    # @param [String] path the path to use
+    # @param [Object] action the action to use
+    # @return [self] this {Router}
+    # @raise [ArgumentError] if method is not a valid HTTP method or the given
+    #   route is already registered
+    def add_route(method, path, action) # rubocop:disable Metrics/MethodLength
+      raise ArgumentError, "#{method} is not a valid HTTP method" unless valid_method?(method)
+      raise ArgumentError, "route #{method.upcase} #{path} is already registered" if routing_to?(method, path)
+
+      route = @routes.find { |it| it[0].to_s == path }
+      if route
+        route[1][method] = action
+      else
+        route = [Mustermann::Sinatra.new(path), { method => action }]
+        @routes << route
+      end
+
+      route[1][:head] = action if method == :get
+
+      self
+    end
+
+    # Matches a method and path against this router's route set.
+    #
+    # @param [Symbol] method the HTTP method to match against
+    # @param [String] path the path to match against
+    # @return [RouteMatch, :bad_path, :bad_method] if successful, a RouteMatch;
+    #   if not, :bad_method if the path exists but not bound to that HTTP
+    #   method, :bad_path otherwise
+    def match(method, path)
+      @routes.each do |route|
+        params = route[0].params(path)
+        next unless params
+
+        action = route[1][method]
+        return :bad_method unless action
+
+        return Match.new(action, params.transform_keys(&:to_sym))
+      end
+
+      :bad_path
+    end
+
+    # @return [Boolean] true if this router has a route with that method and
+    #   path in its route set, false otherwise
+    def routing_to?(method, path)
+      @routes.any? { |it| it[0].to_s == path && it[1].include?(method) }
+    end
+
+    private
+
+    def valid_method?(method)
+      VALID_HTTP_METHODS.include?(method)
+    end
+  end
+end

data/lib/flon/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Flon
+  # Flon's version.
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: flon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- unleashy
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-09-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mustermann
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.74.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.74.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.17.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.17.0
+description: 
+email:
+- unleashy@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- flon.gemspec
+- lib/flon.rb
+- lib/flon/api.rb
+- lib/flon/dsl.rb
+- lib/flon/router.rb
+- lib/flon/version.rb
+homepage: https://github.com/unleashy/flon
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/unleashy/flon
+  source_code_uri: https://github.com/unleashy/flon
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Flon, the API maker that uses JSON
+test_files: []