mountapi 0.11.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe2abc2145d2cf0648549980d8b1166b91db0eacba18b358942e15c0f12d5f3d
+  data.tar.gz: c2345f1dfb8007777184132fc94ceaa792ed595bcb77dbdf80385b0d7f29d239
+SHA512:
+  metadata.gz: 592bc1aaf96cd23782843d2f4e0f78dd0b211b0e53d161459deb0ed428bc885610ba7fde96ec8afdbbdfaebd20cb78ee67cefed1fe9a1eb3bada6de2a5260efc
+  data.tar.gz: b12ee8223f306b5c2dd6a7d776427e563502859451ccc40edde527d358bde7861ac90206b674554639dc305cb66157c0bcb908ed7a84c3bb9ccd47ddc0e74ee8

data/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.11.0] - 2022-01-13
+
+### Added
+
+- Auto-load a Rake task listing all MountAPI routes when mounted in a Rails app
+- Automatically respond with a 403 when roles are defined in handler and none
+  matches in headers
+- Add an explicit exception for missing response schema error used in spec
+
+## [0.10.1] - 2021-11-16
+
+### Fixed
+
+- one piece of the monkeypatch allowing to use custom headers was missing from the backport
+
+## [0.10.0] - 2021-11-10
+
+## [0.9.0] - 2021-11-05
+
+### Changed
+
+- update openapi3_parser dependencie on v0.9.0
+- use our own fork of json schema where missing upstream fixes are missing
+
+### Fixed
+
+- running test locally through Docker
+- do not try to parse request body when its content-type is not JSON
+
+## [0.8.0] - 2021-07-07
+
+### Added
+
+- endpoint allowing to view OpenAPI spec YAML
+- endpoint displaying human readable API doc generated from the OpenAPI spec
+
+## [0.7.0] - 2021-07-06
+
+### Added
+
+- Add documentation about auto require of handlers and hot-reloading
+
+### Fixed
+
+- Boolean casting
+- Test deprecation warnings
+- Silence internal logs during tests
+- Allow unrecognized routes to bubble into host application router
+
+## [0.6.0] - 2021-05-28
+
+### Added
+
+- Add ability to use multiple OpenAPI specs at the same in one MountAPI instance
+
+## [0.5.0] - 2021-01-18
+
+### Changed
+
+- Make code ruby >= 2.7 friendly
+- Bump OpenAPI3 parser gem to 0.8.2
+- Bump Rack to 2.0
+- MountAPI is now mountable as a Rack middleware
+
+## [0.4.0] - 2018-10-05
+
+### Added
+
+- #25 url reflection
+
+## [0.3.1] - 2018-10-02
+
+### Fixed
+
+- #21 prevent double handler call
+
+## [0.3.0] - 2018-10-01
+
+### Added
+
+- #13 Support for default parameters in open api specification
+- #20 Headers inclusion in params
+- #12 Support open api nullable parameters
+
+### Changed
+
+- #16 use OperationID to register handlers
+
+### Fixed
+
+- #14 dash are not recognized in url

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in mountapi.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,42 @@
+PATH
+  remote: .
+  specs:
+    mountapi (0.11.0)
+      addressable (~> 2.8.0)
+      openapi3_parser (~> 0.9)
+      rack (~> 2.0)
+      rack-app (~> 7.7)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    byebug (10.0.2)
+    commonmarker (0.23.2)
+    minitest (5.11.3)
+    openapi3_parser (0.9.1)
+      commonmarker (~> 0.17)
+      psych (~> 3.1)
+    psych (3.3.2)
+    public_suffix (4.0.6)
+    rack (2.0.5)
+    rack-app (7.7.0)
+      rack
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rake (13.0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.1)
+  byebug
+  minitest (~> 5.0)
+  mountapi!
+  rack-test (~> 1.1)
+  rake (~> 13.0)
+
+BUNDLED WITH
+   2.3.5

data/README.md

@@ -0,0 +1,404 @@
+# Mountapi
+
+Given an OpenAPI 3 spec:
+
+- expose routes through rack http endpoints
+- type cast request parameters against specs
+- validate request parameters against specs
+- call handler with nice parameter hash
+- format responses
+- handle parameters failure, and route not found errors with details and status codes
+
+For examples see [example](example/) and [test/mountapi/rack_app_test.rb](test/mountapi/rack_app_test.rb)
+
+## Important warning
+
+If you found this gem while browsing Rubygems, be aware that this release is
+still experimental and meant to be use [internally
+only](https://www.synbioz.com).
+
+We will not provide any support regarding this gem. There are some issues we
+want to sort out before releasing a real public version.
+
+For instance, we had to fork the
+[json-schema](https://github.com/voxpupuli/json-schema) gem to include a fix. We
+can't reference this fork from github since gemspec doesn't allow this. As a
+result, we put our fork in `vendor` directory which is not the cleanest thing to
+do but the only one working at the moment.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mountapi'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mountapi
+
+## Usage
+
+### Tutorial
+
+#### Rails
+
+```ruby
+# Var env BUNDLE_LOCAL__XXX is no longer used by bundler
+# because we don't have a specified branch
+# But we use it manually to set the local path
+def private_gem(name, tag: nil, path: nil)
+  var_env = ENV["BUNDLE_LOCAL__#{name.upcase}"]
+
+  if var_env.nil? || var_env.empty?
+    gem name, tag
+  elsif File.directory?(path)
+    gem name, path: path
+  end
+end
+
+source "https://gems.synbioz.com" do
+  private_gem "mountapi", tag: "0.6.0", path: "/mountapi"
+end
+```
+
+With this helper you can work with the gem locally in the context.
+You have to specify the variable `BUNDLE_LOCAL__MOUNTAPI=/mountapi` in `ops/dev/app_env` and mount a specific volume in the docker-compose of dev:
+
+```yaml
+services:
+  app:
+  ...
+  volumes:
+    - app_data:/app
+    - mountapi:/mountapi
+  ...
+
+volumes:
+  ...
+  mountapi:
+    driver_opts:
+      type: none
+      device: "/Users/jonathanfrancois/code/synbioz/mountapi" # CHANGE ME
+      o: bind
+  ...
+```
+
+Add a dedicated initializer:
+
+```ruby
+Rails.application.configure do
+  require "mountapi"
+
+  config.before_initialize do
+    config.middleware.insert_before Warden::Manager, Mountapi::RackApp
+  end
+
+  HANDLERS = "#{Rails.root}/app/mount_api/handlers"
+  require "#{HANDLERS}/base_handler.rb"
+
+  unless Rails.env.production?
+    Dir.glob("#{HANDLERS}/**/*.rb") { |f| require f }
+
+    config.to_prepare do
+      Dir.glob("#{HANDLERS}/**/*.rb") { |f| load f }
+    end
+  end
+end
+
+Mountapi.configure do |config|
+  config.open_api_spec = File.read(File.expand_path("../../api.yaml", __dir__))
+end
+
+# Enable documentation
+# You must add `mount Mountapi::DocRackApp, at: "/apidoc"` in routes.rb
+require "mountapi/doc_rack_app"
+```
+
+Add a valid OpenAPI 3 spec file to rails root directory `#{Rails.root}/api.yml`.
+And add your handlers in specific directory `#{Rails.root}/app/mount_api/handlers/`.
+It is important to use this folder and to use a `Handler` module in order to allow Zeitwerk to auto-load the classes.
+
+We will usually use a basic handler and include `Mountapi::Handler::Behaviour`.
+By the way, this file is explicitly required in the initializer.
+
+```ruby
+module Handlers
+  class BaseHandler
+    include Mountapi::Handler::Behaviour
+
+  end
+end
+```
+
+One can list all routes detected and handled by MountAPI by using the
+`mountapi:routes` Rake task.
+
+#### Ruby app
+
+Given a powerful micro-service that just return the parameters it receive:
+
+```ruby
+#lib/slice_array.rb
+
+# A dumb service example
+module SliceArray
+  def self.call(array:, start:, length:)
+    array.slice(start, length)
+  end
+end
+
+```
+
+And a valid OpenAPI 3 spec file to expose the service
+
+```yaml
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Test
+paths:
+  /array/slicer:
+    get:
+      operationId: SliceArray
+      parameters:
+        - name: target
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          required: true
+        - name: offset
+          in: query
+          required: true
+          schema:
+            type: integer
+
+      responses:
+        "200":
+          description: success
+        "400":
+          description: error in request
+```
+
+In order to serve your endpoint specification through HTTP, you just need two things:
+
+First Create a handler
+
+```ruby
+#/lib/slice_array/mountapi_handler
+
+module SliceArray
+  class MountapiHandler
+    include Mountapi::Handler::Behaviour # add the behaviour to the class
+    operation_id "SliceArray"
+    # You must define a call instance method
+    # `ok` and `params` are provided by Handler::Behaviour
+    def call
+      data = SliceArray.call(params)
+      ok(data: data)
+    end
+  end
+end
+```
+
+Second, add a rackup file in order to boot your rack endpoint
+
+```ruby
+#config.ru
+
+require "bundler"
+Bundler.require
+
+require "slice-array"
+require "slice-array/handler/behaviour"
+require "mountapi"
+require "mountapi/rack_app"
+
+Mountapi.configure do |config|
+  config.open_api_spec = ["../open_api_v1.yml", "../open_api_v2.yml"].map { |path| File.read(File.expand_path("../open_api.yml", __FILE__)) }
+end
+
+run Mountapi::RackApp.new
+```
+
+If you `rackup` you'll get your service wired through HTTP !
+
+```
+curl "localhost:9292/1.0.0/array/slicer?target[]=a&target[]=b&target[]=c&limit=1&offset=1"
+
+{"data":["b"]}%
+```
+
+```
+curl localhost:9292/1.0.0/array/slicer
+
+{"errors":"[\"The property '#/' did not contain a required property of 'target' in schema ca7afc0e-f3a0-5416-92fa-3a72ffff7fe2\", \"The property '#/' did not contain a required property of 'limit' in schema ca7afc0e-f3a0-5416-92fa-3a72ffff7fe2\", \"The property '#/' did not contain a required property of 'offset' in schema ca7afc0e-f3a0-5416-92fa-3a72ffff7fe2\"]"}
+```
+
+```
+curl "localhost:9292/1.0.0/array/slicer?limit=foo&offset=1.0"
+
+{"errors":"[{:message=>\"can't cast \\\"foo\\\" as Mountapi::Schema::Integer\"}]"}%
+```
+
+Play with the example in `example/`
+
+### Requests conventions
+
+- A JSON request body root MUST be an object
+- Default values will be filled in your parameters only for the root level. Default values in nested object are not supported yet (and should not be, because it would add complexity to applications design and API).
+
+### Responses schema and validations
+
+If you define responses payload in the YAML, your hanlder response payload must match this definition.
+If you don't define a response schema, your response will be validated against JSON API schema.
+
+If the response payload is not valid, Mountapi will raise a Mountapi::Error::InvalidResponse
+
+### URL reflection
+
+Within a handler the following methods are available :
+
+- `base_url`, that returns current request base URL
+- `url_for(operation_id, url_params)` that return the URL for a given operation and parameters (eg. `url_for("ShowRevision", uid: revision.uid)`)
+
+### Handler implementation
+
+#### Why a handler ?
+
+The handler is responsible for the integration between infrastructure detail (using Mountapi) and the application services (aka use cases).
+
+Because application code does not know anything about the way you deliver the application to the end user.
+You could deliver the content through Mountapi , HTML, Terminal or a mobile phone endpoint. Your application business remain the same, only the transport protocol and representation would change.
+
+#### Implementation
+
+A Moutapi handler is really a dumb but valuable piece of code.
+It has to transform the inbound parameters from Mountapi to a set of parameters required by your use case.
+
+Then will call an application service to fulfill the request, and translate the execution result to Mountapi response.
+
+see `lib/mountapi/handler/behaviour`
+
+example :
+
+```ruby
+require "gtc/app/show_revision"
+
+module Gtc
+  module Infra
+    module Mountapi
+      class ShowRevision
+        include ::Mountapi::Handler::Behaviour
+
+        operation_id "ShowRevision"
+
+        def call
+          data = Gtc::App::ShowRevision.call(params.fetch("gtc_uid"))
+          data && ok(data.to_h) || not_found
+        end
+      end
+    end
+  end
+end
+```
+
+#### Roles handling
+
+If your API is behind an HTTP proxy which provides headers with current user
+info then you can take advantage of the `user_info_adapter` to automatically
+handle authorization before reaching handler `call` method.
+
+To take advantage of this, you need to configure `user_info_adapter`. This must
+be a callable that must return a boolean. If the return value is `true` then
+`call` method will be run otherwise a `403 Forbidden` response will be returned.
+
+```ruby
+Mountapi.configure do |config|
+  config.user_info_adapter = Mountapi::Adapters::UserInfoAdapter.new("x-user-info", { roles: "roles" })
+end
+```
+
+In the previous example, we're using the provided `UserInfoAdapter`. It takes
+two arguments, the first one is the name of the HTTP header the adapter will
+read to gather info about the user. The second argument is a mapping of adapter
+internal info and its corresponding name in the header value.
+
+`UserInfoAdapter` is expecting the header value to be a base64 encoded JSON
+string. This JSON must contain at least a key which value will be an array of
+the current user roles.
+
+So in our example we're expecting a `x-user-info` HTTP header which is a JSON
+string including a key named `roles`.
+
+If you need to use HTTP headers in an other way then you can write your own
+adapter.
+
+Now that our adapter is configured, we can specify allowed roles in our handler:
+
+```ruby
+class SomeHandler
+  include Mountapi::Handler::Behaviour
+  operation_id "operationId"
+  allowed_roles "admin"
+
+  def call
+   # do something if user has one of allowed roles
+  end
+end
+```
+
+In this example, we use the `allowed_roles` method to specify that only user
+with role `admin` should be allowed to execute the action. If one of the current
+user roles is `admin` then we run `call` method. If roles aren't matching then
+we shortcut the execution by returning a 403 response.
+
+## 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.
+
+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).
+
+To run containerized tests locally, run `ops/test/compose run --rm runner rake test`.
+
+## API Documentation
+
+Mountapi allows you to generate the documentation associated with your APIs.
+It uses the Redoc service: https://github.com/Redocly/redoc
+
+To do this you need to require the dedicated app rack and mount it in your routes.
+For example in the context of a rails project:
+
+```ruby
+# config/initializer/mountapi.rb
+...
+Mountapi.configure do |config|
+  config.open_api_spec = File.read(File.expand_path("../../api.yml", __dir__))
+end
+# You absolutely must require it after the configuration of the Mountapi gem
+require "mountapi/doc_rack_app"
+```
+
+and mount the rack app in your router by specifying the namespace (here `apidoc`):
+
+```
+# config/routes.rb
+mount Mountapi::DocRackApp, at: "/apidoc"
+```
+
+You then can access the documentation of all your versions from the main page `/apidoc`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitLab at <https://git.synbioz.com/synbioz/mountapi>.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+task default: :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "mountapi"
+
+# 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/lib/mountapi/adapters/user_info_adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Mountapi::Adapters
+  class UserInfoAdapter
+    def initialize(header_name, options)
+      @header_name = header_name
+      @options = options
+    end
+
+    def call(params, roles)
+      roles_key = options[:roles]
+      user_info = JSON.parse(Base64.decode64(params[header_name]))
+
+      user_info[roles_key].any? { |role| roles.include?(role) }
+    end
+
+    private
+
+    attr_reader :header_name, :options
+  end
+end

data/lib/mountapi/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Mountapi
+  # Config management
+  class Config
+    attr_accessor :version_in_path, :logger, :user_info_adapter
+    attr_reader :open_api_spec
+
+    # Constructor setting the version path prefix to true by default and registering the logger
+    def initialize
+      @version_in_path = true
+      @logger = Logger.new(STDOUT)
+    end
+
+    # Allow to assign one or more OpenAPI specs to MountAPI
+    #
+    # @param specs [String, Array<String>] a string (or an array of strings) representing an OpenAPI definition
+    # @return [Array] an array of OpenAPI definitions
+    def open_api_spec=(specs)
+      @open_api_spec = Array(specs)
+    end
+  end
+end

data/lib/mountapi/doc_rack_app.rb

@@ -0,0 +1,29 @@
+require "rack/app"
+require "yaml"
+require "erb"
+
+module Mountapi
+  class DocRackApp < Rack::App
+
+    spec_by_version = Mountapi.config.open_api_spec.map do |spec|
+      version = YAML.safe_load(spec, symbolize_names: true).fetch(:info).fetch(:version)
+      [version, spec]
+    end
+    doc_template = ERB.new(File.read(File.expand_path("templates/redoc.html.erb", __dir__)), trim_mode: "-")
+    list_template = ERB.new(File.read(File.expand_path("templates/list.html.erb", __dir__)), trim_mode: "-")
+
+    get "/" do
+      list_template.result_with_hash(spec_by_version: spec_by_version, original_fullpath: request.env["ORIGINAL_FULLPATH"])
+    end
+
+    spec_by_version.each do |version, spec|
+      get "/#{version}.yaml" do
+        spec
+      end
+
+      get "/#{version}" do
+        doc_template.result_with_hash(open_api_url: "./#{version}.yaml")
+      end
+    end
+  end
+end