the_garage 2.0.0

data/lib/garage/app_responder.rb

@@ -0,0 +1,22 @@
+if Rails::VERSION::MAJOR > 4 ||
+    (Rails::VERSION::MAJOR == 4 && Rails::VERSION::MINOR >= 2)
+  require 'action_controller/responder'
+else
+  require 'action_controller'
+end
+
+require "garage/hypermedia_responder"
+require "garage/resource_casting_responder"
+require "garage/paginating_responder"
+require "garage/optional_response_body_responder"
+
+class Garage::AppResponder < ActionController::Responder
+  # like Rack middleware, responders are applied outside in, bottom to the top
+  include Garage::HypermediaResponder
+  include Garage::ResourceCastingResponder
+  include Garage::PaginatingResponder
+  include Garage::OptionalResponseBodyResponder
+
+  # in case someone tries to do Object#to_msgpack
+  undef_method(:to_msgpack) if method_defined?(:to_msgpack)
+end

data/lib/garage/authorizable.rb

@@ -0,0 +1,26 @@
+# Public: include this module to make the resource authorizable in Garage::RestfulActions
+#
+# Examples
+#
+#   class Post
+#     include Garage::Authorizable
+#     def build_permissions(perms, other); end
+#     def self.build_permissions(perms, other, target); end
+#   end
+module Garage
+  module Authorizable
+    def build_permissions(perms, subject)
+      raise NotImplementedError, "#{self.class}#build_permissions must be implemented"
+    end
+
+    def effective_permissions(subject)
+      Garage::Permissions.new(subject, resource_class).tap do |perms|
+        build_permissions(perms, subject)
+      end
+    end
+
+    def authorize!(subject, action)
+      effective_permissions(subject).authorize!(action)
+    end
+  end
+end

data/lib/garage/config.rb

@@ -0,0 +1,76 @@
+require 'garage/docs/config'
+
+module Garage
+  def self.configure(&block)
+    @config = Config::Builder.new(&block).build
+  end
+
+  def self.configuration
+    @config
+  end
+
+  class Config
+    DEFAULT_RESCUE_ERROR = true
+
+    attr_writer :cast_resource, :docs, :rescue_error, :strategy, :cache_acceess_token_validation
+    attr_accessor :auth_server_url, :auth_server_host, :auth_server_timeout, :ttl_for_access_token_cache
+
+    def initialize
+      @cache_acceess_token_validation = false
+      @ttl_for_access_token_cache = 5.minutes
+    end
+
+    # Set false if you want to rescue errors by yourself
+    # @return [true, false] A flag to rescue Garage::HTTPError in ControllerHelper (default: true)
+    # @example
+    #   Garage.configuration.rescue_error = false
+    def rescue_error
+      instance_variable_defined?(:@rescue_error) ? @rescue_error : DEFAULT_RESCUE_ERROR
+    end
+
+    # Set authentication strategy module which must satisfy Strategy interface.
+    # @return [Module] A auth strategy. default is NoAuthentication strategy.
+    # @example
+    #   Garage.configuration.strategy = Garage::Strategy::AuthServer
+    def strategy
+      instance_variable_defined?(:@strategy) ? @strategy : Garage::Strategy::NoAuthentication
+    end
+
+    def docs
+      @docs ||= Docs::Config.new
+    end
+
+    def cast_resource
+      @cast_resource ||= proc { |resource|
+        if resource.respond_to?(:map) && resource.respond_to?(:to_a)
+          resource.map(&:to_resource)
+        else
+          resource.to_resource
+        end
+      }
+    end
+
+    def cache_acceess_token_validation?
+      !!@cache_acceess_token_validation
+    end
+
+    class Builder
+      def initialize(&block)
+        @config = Config.new
+        instance_eval(&block)
+      end
+
+      def build
+        @config
+      end
+
+      def cast_resource(&block)
+        @config.cast_resource = block
+      end
+
+      def docs
+        @docs_builder ||= Docs::Config::Builder.new(@config.docs)
+      end
+    end
+  end
+end

data/lib/garage/controller_helper.rb

@@ -0,0 +1,110 @@
+module Garage
+  module ControllerHelper
+    extend ActiveSupport::Concern
+    include Utils
+
+    included do
+      use Rack::AcceptDefault
+
+      around_action :notify_request_stats
+
+      include Garage.configuration.strategy
+
+      if Garage.configuration.rescue_error
+        rescue_from Garage::HTTPError do |exception|
+          render json: { status_code: exception.status_code, error: exception.message }, status: exception.status
+        end
+      end
+
+      before_action Garage::HypermediaFilter
+
+      respond_to :json # , :msgpack
+      self.responder = Garage::AppResponder
+    end
+
+    # For backword compatiblility.
+    def doorkeeper_token
+      access_token
+    end
+
+    def resource_owner_id
+      access_token.try(:resource_owner_id)
+    end
+
+    # Use this method to render 'unauthorized'.
+    # Garage user may overwrite this method to response custom unauthorized response.
+    # @return [Hash]
+    def unauthorized_render_options(error: nil)
+      { json: { status_code: 401, error: "Unauthorized (invalid token)" } }
+    end
+
+    # Implement by using `resource_owner_id` like:
+    #
+    #   def current_resource_owner
+    #     @current_resource_owner ||= User.find(resource_owner_id) if resource_owner_id
+    #   end
+    #
+    def current_resource_owner
+      raise "Your ApplicationController needs to implement current_resource_owner!"
+    end
+
+    # Check if the current resource is the same as the requester.
+    # The resource must respond to `resource.id` method.
+    def requested_by?(resource)
+      user = resource.respond_to?(:owner) ? resource.owner : resource
+      case
+      when current_resource_owner.nil?
+        false
+      when !user.is_a?(current_resource_owner.class)
+        false
+      when current_resource_owner.id == user.id
+        true
+      else
+        false
+      end
+    end
+
+    # Public: returns if the current request includes the given OAuth scope
+    def has_scope?(scope)
+      access_token && access_token.scopes.include?(scope)
+    end
+
+    def cache_context
+      { t: access_token.try(:id) }
+    end
+
+    attr_accessor :representation, :field_selector
+
+    def allow_access?(klass, action = :read)
+      ability_from_token.allow?(klass, action)
+    end
+
+  private
+
+    def ability_from_token
+      Garage::TokenScope.ability(current_resource_owner, access_token.try(:scopes) || [])
+    end
+
+    def notify_request_stats
+      yield
+    ensure
+      begin
+        payload = {
+          :controller => self,
+          :token => access_token,
+          :resource_owner => current_resource_owner,
+        }
+        ActiveSupport::Notifications.instrument("garage.request", payload)
+      rescue Exception
+      end
+    end
+
+    def verify_auth
+      if !access_token || !access_token.accessible?
+        error_status = :unauthorized
+        options = unauthorized_render_options
+        render options.merge(status: error_status)
+      end
+    end
+  end
+end

data/lib/garage/docs/anchor_building.rb

@@ -0,0 +1,28 @@
+module Garage
+  module Docs
+    module AnchorBuilding
+      def preprocess(full_document)
+        reset
+        full_document
+      end
+
+      def postprocess(full_document)
+        reset
+        full_document
+      end
+
+      private
+
+      def reset
+        @anchors = Hash.new(0)
+      end
+
+      def to_anchor(text)
+        unique_text = text + @anchors[text].to_s
+        @anchors[text] += 1
+
+        unique_text.gsub(/\s+/, '-').gsub(/<\/?[^>]*>/, '').downcase
+      end
+    end
+  end
+end

data/lib/garage/docs/application.rb

@@ -0,0 +1,24 @@
+module Garage
+  module Docs
+    class Application
+      def initialize(application)
+        @application = application
+      end
+
+      def name
+        @application.class.name.split("::")[0]
+      end
+
+      def documents
+        cached = Garage.configuration.docs.docs_cache_enabled
+        @documents ||= pathnames.map {|pathname| Garage::Docs::Document.new(pathname, cached) }
+      end
+
+      private
+
+      def pathnames
+        Pathname.glob("#{Garage.configuration.docs.document_root}/resources/**/*.md").sort
+      end
+    end
+  end
+end

data/lib/garage/docs/config.rb

@@ -0,0 +1,61 @@
+module Garage
+  module Docs
+    class Config
+      attr_accessor :document_root, :current_user_method, :authenticate,
+        :console_app_uid, :console_app_secret, :remote_server,
+        :docs_authorization_method, :docs_cache_enabled
+
+      def initialize
+        reset
+      end
+
+      def reset
+        @document_root = Rails.root.join('doc/garage')
+        @current_user_method = Proc.new { current_user }
+        @authenticate = Proc.new {}
+        @console_app_uid = ''
+        @remote_server = Proc.new {|request| "#{request.protocol}#{request.host_with_port}" }
+        @docs_authorization_method = nil
+        @docs_cache_enabled = true
+      end
+
+      class Builder
+        def initialize(config)
+          @config = config
+        end
+
+        def document_root=(value)
+          @config.document_root = value
+        end
+
+        def current_user_method(&block)
+          @config.current_user_method = block
+        end
+
+        def authenticate(&block)
+          @config.authenticate = block
+        end
+
+        def console_app_uid=(value)
+          @config.console_app_uid = value
+        end
+
+        def console_app_secret=(value)
+          @config.console_app_secret = value
+        end
+
+        def remote_server=(value)
+          @config.remote_server = value
+        end
+
+        def docs_cache_enabled=(value)
+          @config.docs_cache_enabled = value
+        end
+
+        def docs_authorization_method(&block)
+          @config.docs_authorization_method = block
+        end
+      end
+    end
+  end
+end

data/lib/garage/docs/console_link_building.rb

@@ -0,0 +1,14 @@
+module Garage
+  module Docs
+    module ConsoleLinkBuilding
+      def build_console_link(text)
+        if text.match(/^(POST|GET|PUT|DELETE)\s+(\/.*)$/)
+          query = Rack::Utils.build_query(method: $1, location: $2)
+          "<a href='console?#{query}'><small>(console)</small></a>"
+        else
+          ''
+        end
+      end
+    end
+  end
+end

data/lib/garage/docs/document.rb

@@ -0,0 +1,141 @@
+module Garage
+  module Docs
+    class Document
+      class << self
+        def all
+          application.documents
+        end
+
+        def find_by_name(name)
+          all.find {|document| document.name == name }
+        end
+
+        def renderer
+          @renderer ||= Redcarpet::Markdown.new(
+            Garage::Docs::Renderer.new(with_toc_data: true),
+            fenced_code_blocks: true,
+            no_intra_emphasis: true,
+            tables: true,
+          )
+        end
+
+        def toc_renderer
+          @toc_renderer ||= Redcarpet::Markdown.new(
+            Garage::Docs::TocRenderer.new,
+            no_intra_emphasis: true
+          )
+        end
+
+        def build_permissions(perms, other, target)
+          perms.permits! :read
+        end
+
+        private
+
+        def application
+          Garage::Docs.application
+        end
+      end
+
+      include Garage::Authorizable
+      include Garage::Representer
+
+      property :name
+      property :toc
+      property :rendered_body
+
+      attr_reader :pathname
+      attr_accessor :cached
+
+      def initialize(pathname, cached = false)
+        @pathname = pathname
+        @cached = cached
+      end
+
+      def name
+        relative_base_name.to_s.gsub('/', '-')
+      end
+
+      def humanized_name
+        name.split('-').map(&:humanize).join(' / ')
+      end
+
+      def cache_key(type)
+        "garage-doc-#{type}-#{pathname}"
+      end
+
+      def toc
+        if cached
+          Rails.cache.fetch(cache_key(:toc)) do
+            self.class.toc_renderer.render(body).html_safe
+          end
+        else
+          self.class.toc_renderer.render(body).html_safe
+        end
+      end
+
+      def render
+        if cached
+          Rails.cache.fetch(cache_key(:render)) do
+            self.class.renderer.render(body).html_safe
+          end
+        else
+          self.class.renderer.render(body).html_safe
+        end
+      end
+
+      alias :rendered_body :render
+
+      def body
+        pathname.read
+      end
+
+      def resource_class
+        @resource_class ||= extract_resource_class || relative_base_name.camelize.singularize.constantize
+      rescue NameError
+        nil
+      end
+
+      def examples(*args)
+        if resource_class && resource_class.respond_to?(:garage_examples)
+          resource_class.garage_examples(*args)
+        else
+          []
+        end
+      end
+
+      # If you need authentication logic,
+      # assign a Proc to Garage.docs.configuration.docs_authorization_method.
+      #
+      # Example:
+      #
+      #   Garage.docs.configuration.docs_authorization_method do |args|
+      #     if name.start_with?("admin_")
+      #       args[:user].admin?
+      #     else
+      #       true
+      #     end
+      #   end
+      #
+      def visible_to?(user)
+        if method = Garage.configuration.docs.docs_authorization_method
+          method.call(document: self, user: user)
+        else
+          true
+        end
+      end
+
+      private
+
+      def extract_resource_class
+        if /<!-- resource_class: (\S+)/ === body
+          $1.constantize
+        end
+      end
+
+      def relative_base_name
+        pathname.relative_path_from(Pathname.new("#{Garage.configuration.docs.document_root}/resources")).to_s.sub('.md', '')
+      end
+    end
+  end
+end