doc_repo 0.1.1 → 1.0.0.pre.beta.1

data/lib/doc_repo/gateway_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DocRepo
+  class GatewayError < Error
+    include HttpResult
+
+    def initialize(uri, code:, cause:)
+      init_result_readers(uri, code)
+      @cause = cause
+      message = case code
+                when NetHttpAdapter::BAD_GATEWAY
+                  '502 "Bad Gateway"'
+                when NetHttpAdapter::GATEWAY_TIMEOUT
+                  '504 "Gateway Timeout"'
+                else
+                  name = if defined?(::Rack::Utils::HTTP_STATUS_CODES)
+                           ::Rack::Utils::HTTP_STATUS_CODES[code.to_i]
+                         else
+                           "Unknown Error"
+                         end
+                  "#{code} #{name.dump}"
+                end
+      super(message)
+    end
+
+    # Wrap exception as normal
+    attr_reader :cause
+
+    def details
+      cause.message
+    end
+
+    def error?
+      true
+    end
+  end
+end

data/lib/doc_repo/http_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DocRepo
+  class HttpError < Error
+    include HttpResult
+
+    def initialize(uri, http_response)
+      @http = http_response
+      init_result_readers(uri, @http.code)
+      message = @http.code
+      message += ' ' + @http.message.dump if @http.message
+      super(message)
+    end
+
+    attr_reader :http
+    private :http
+
+    def details
+      # NOTE: The Github raw site does not respond with anything other than
+      # `text/plain` for general HTTP errors.
+      http.body
+    end
+
+    def not_found?
+      404 == code
+    end
+
+    def error?
+      true
+    end
+  end
+end

data/lib/doc_repo/http_result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module DocRepo
+  module HttpResult
+    def init_result_readers(uri, code)
+      @uri = uri.to_s.freeze
+      @code = code.to_i
+    end
+    protected :init_result_readers
+
+    attr_reader :code, :uri
+
+    def error?
+      false
+    end
+
+    def not_found?
+      false
+    end
+
+    def redirect?
+      false
+    end
+
+    def success?
+      false
+    end
+  end
+end

data/lib/doc_repo/net_http_adapter.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+require 'net/http'
+require 'time'
+
+module DocRepo
+  # @api private
+  class NetHttpAdapter
+    # Net::HTTP default timeouts of 60 seconds are too long for our purposes
+    DEFAULT_OPTS = {
+      open_timeout: 10,
+      read_timeout: 10,
+      ssl_timeout: 10,
+    }.freeze
+
+    # HTTP Status Codes
+    BAD_GATEWAY     = 502
+    GATEWAY_TIMEOUT = 504
+    UNKNOWN_ERROR   = 520
+
+    def initialize(host, cache: NullCache.instance, cache_options: {}, **opts)
+      @host = host.dup.freeze
+      @opts = DEFAULT_OPTS.dup.merge!(opts)
+      # Always force SSL
+      @opts[:use_ssl] = true
+      @opts.freeze
+      @cache = cache
+      @cache_options = cache_options.dup.freeze
+    end
+
+    attr_reader :host, :opts
+
+    attr_reader :cache, :cache_options
+    private :cache
+
+    def retrieve(uri)
+      resp = http_cache(uri)
+      case resp
+      when Net::HTTPRedirection
+        Redirect.new(
+          resp['Location'],
+          code: resp.code,
+          headers: resp.to_hash,
+        )
+      when Net::HTTPSuccess
+        Doc.new(uri, resp)
+      else
+        HttpError.new(uri, resp)
+      end
+    rescue Timeout::Error => timeout
+      # Covers Net::OpenTimeout, Net::ReadTimeout, etc.
+      GatewayError.new(uri, code: GATEWAY_TIMEOUT, cause: timeout)
+    rescue Net::HTTPBadResponse,
+           Net::ProtocolError,
+           OpenSSL::SSL::SSLError => protocol_error
+      # Docs state `Net::HTTPBadResponse` is raised when there is a protocol
+      # error. It's unclear whether all protocol errors are wrapped so we
+      # handle both here.
+      GatewayError.new(uri, code: BAD_GATEWAY, cause: protocol_error)
+    rescue => e
+      # Covers IOError, Errno::*, and SocketError
+      GatewayError.new(uri, code: UNKNOWN_ERROR, cause: e)
+    end
+
+  private
+
+    def cache_key(uri)
+      "#{host}:#{uri}"
+    end
+
+    def conditional_headers(expired)
+      # Origin servers are supposed to treat `If-None-Match` with higher
+      # precedences than `If-Modified-Since` according to the RFC:
+      #
+      # > A recipient cache or origin server MUST evaluate the request
+      # > preconditions defined by this specification in the following order:
+      # >
+      # > 1.  When recipient is the origin server and If-Match is present,
+      # >     evaluate the If-Match precondition:
+      # >
+      # >     *  if true, continue to step 3
+      # >
+      # >     *  if false, respond 412 (Precondition Failed) unless it can be
+      # >        determined that the state-changing request has already
+      # >        succeeded (see Section 3.1)
+      # >
+      # > 2.  When recipient is the origin server, If-Match is not present, and
+      # >     If-Unmodified-Since is present, evaluate the If-Unmodified-Since
+      # >     precondition:
+      # >
+      # >     *  if true, continue to step 3
+      # >
+      # >     *  if false, respond 412 (Precondition Failed) unless it can be
+      # >        determined that the state-changing request has already
+      # >        succeeded (see Section 3.4)
+      # >
+      # > 3.  When If-None-Match is present, evaluate the If-None-Match
+      # >     precondition:
+      # >
+      # >     *  if true, continue to step 5
+      # >
+      # >     *  if false for GET/HEAD, respond 304 (Not Modified)
+      # >
+      # >     *  if false for other methods, respond 412 (Precondition Failed)
+      # >
+      # > 4.  When the method is GET or HEAD, If-None-Match is not present, and
+      # >     If-Modified-Since is present, evaluate the If-Modified-Since
+      # >     precondition:
+      # >
+      # >     *  if true, continue to step 5
+      # >
+      # >     *  if false, respond 304 (Not Modified)
+      # >
+      # > -- https://tools.ietf.org/html/rfc7232#section-6
+      #
+      # This allows clients, and caches, some flexibility in how they generate
+      # the `If-Modified-Since` header:
+      #
+      # > When used for cache updates, a cache will typically use the value of
+      # > the cached message's Last-Modified field to generate the field value
+      # > of If-Modified-Since.  This behavior is most interoperable for cases
+      # > where clocks are poorly synchronized or when the server has chosen to
+      # > only honor exact timestamp matches (due to a problem with
+      # > Last-Modified dates that appear to go "back in time" when the origin
+      # > server's clock is corrected or a representation is restored from an
+      # > archived backup).  However, caches occasionally generate the field
+      # > value based on other data, such as the Date header field of the
+      # > cached message or the local clock time that the message was received,
+      # > particularly when the cached message does not contain a Last-Modified
+      # > field.
+      # >
+      # > -- https://tools.ietf.org/html/rfc7232#section-3.3
+      #
+      # However, the Github raw content server (GRC) does not respect this.
+      # This may be due to the fact that the GRC does not send a
+      # `Last-Modified` header in replies. If we take that into account this
+      # behavior _may_ make sense if we assume the GRC  is following the now
+      # obsolete HTTP/1.1 RFC 2616:
+      #
+      # > An HTTP/1.1 origin server, upon receiving a conditional request that
+      # > includes both a Last-Modified date (e.g., in an If-Modified-Since or
+      # > If-Unmodified-Since header field) and one or more entity tags (e.g.,
+      # > in an If-Match, If-None-Match, or If-Range header field) as cache
+      # > validators, MUST NOT return a response status of 304 (Not Modified)
+      # > unless doing so is consistent with all of the conditional header
+      # > fields in the request.
+      # >
+      # > -- https://tools.ietf.org/html/rfc2616#section-13.3.4
+      #
+      # So to actually receive `304 Not Modified` replies from GRC, but also
+      # try to be compatible with more current servers, this only sets
+      # `If-Modified-Since` based on the `Last-Modified` value (i.e. we no
+      # longer fall back to the `Date` value).
+      preconditions = {
+        "If-None-Match" => expired["ETag"],
+        "If-Modified-Since" => expired["Last-Modified"],
+      }
+      preconditions.compact!
+      preconditions
+    end
+
+    def expired?(resp)
+      # TODO: Use `Cache-Control` header when available
+      expires_at = resp['Expires']
+      expires_at && Time.httpdate(expires_at) < Time.now
+    rescue ArgumentError => _e
+      # Raised when `Time.parse` cannot parse the value
+      #
+      # Per the HTTP 1.1 RFC regarding the `Expires` header:
+      #
+      # > A cache recipient MUST interpret invalid date formats, especially the
+      # > value "0", as representing a time in the past (i.e., "already
+      # > expired").
+      # >
+      # > -- https://tools.ietf.org/html/rfc7234#section-5.3
+      true
+    end
+
+    def http_cache(uri)
+      uri_key = cache_key(uri)
+      resp = cache.fetch(uri_key, cache_options) {
+        Net::HTTP.start(host, opts) { |http| http.get(uri) }
+      }
+      if expired?(resp)
+        resp = refresh(uri, resp)
+        cache.write uri_key, resp, cache_options
+      end
+      resp
+    end
+
+    def refresh(uri, expired)
+      fresh = Net::HTTP.start(host, opts) { |http|
+        http.get(uri, conditional_headers(expired))
+      }
+      if Net::HTTPNotModified === fresh
+        fresh.each_header do |k, v|
+          expired[k] = v
+        end
+        fresh = expired
+      end
+      fresh
+    end
+  end
+end

data/lib/doc_repo/rails/legacy_versioned_cache.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Monkey patches to work with-in Rails conventions
+module DocRepo
+  module Rails
+    # Prior to ActiveSupport 5.2 it is assumed the `cache_key` value contains
+    # version information.
+    module VersionedCacheKey
+      def cache_key
+        "#{super}-#{cache_version}"
+      end
+      alias_method :cache_key_with_version, :cache_key
+    end
+  end
+end
+
+DocRepo::Doc.class_exec do
+  include DocRepo::Rails::VersionedCacheKey
+end

data/lib/doc_repo/rails.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Monkey patches to work with-in Rails conventions
+module DocRepo
+  module Rails
+    module Modelish
+      # For some reason Rails _only_ calls `to_text` for the following:
+      #
+      #     render html: doc
+      #     render body: doc
+      #     render plain: doc
+      #
+      # There's no way for us to know which of these is being called so we
+      # can't conditionally provide the raw markdown for `plain`. And without
+      # this `to_s` will be called then HTML escaped:
+      #
+      #     "#<DocRepo::Doc:0x007fabefe8c360>"
+      def to_text
+        to_html.html_safe
+      end
+
+      def updated_at
+        last_modified
+      end
+    end
+  end
+end
+
+# Prior to ActiveSupport 5.2 it is assumed the `cache_key` value contains
+# version information.
+if Rails.gem_version < Gem::Version.new("5.2.0")
+  require_relative 'rails/legacy_versioned_cache'
+end
+
+DocRepo::Doc.class_exec do
+  include DocRepo::Rails::Modelish
+end

data/lib/doc_repo/redirect.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DocRepo
+  class Redirect
+    include HttpResult
+
+    def initialize(url, code: 302, headers: {})
+      init_result_readers(url, code)
+      @headers = headers.freeze
+    end
+
+    alias_method :url, :uri
+    alias_method :location, :url
+
+    def redirect?
+      true
+    end
+  end
+end

data/lib/doc_repo/repository.rb

@@ -1,31 +1,83 @@
+# frozen_string_literal: true
+require 'forwardable'
+
 module DocRepo
   class Repository
-    REDIRECT_FORMATS = %w[
-      .jpg
-      .png
-      .jpeg
-      .svg
-      .css
-      .txt
-    ]
-
-    def respond(slug, &block)
-      if REDIRECT_FORMATS.include?(File.extname(slug).downcase)
-        yield DocRepo::Response.redirect(get_redirect_url(slug))
-      else
-        yield DocRepo::Response.html(render_page(slug))
-      end
+    extend Forwardable
+
+    def initialize(config, http_adapter: nil)
+      @config = config.dup.freeze
+      @http = http_adapter
+      @http ||= NetHttpAdapter.new(
+        GITHUB_HOST,
+        cache: cache_store,
+        cache_options: cache_options,
+      )
+    end
+
+    attr_reader :config
+    def_delegators :config, :branch, :doc_root, :fallback_ext, :org, :repo
+
+    def request(slug, result_handler: ResultHandler.new)
+      yield result_handler
+      result = detect(uri_for(slug))
+      action = handler_for(result, result_handler)
+      action.call result
+    end
+
+    def uri_for(slug)
+      "/#{org}/#{repo}/#{branch}/#{doc_root}/#{ensure_ext(slug)}".squeeze("/")
     end
 
   private
 
-    def render_page(slug)
-      DocRepo::Page.new(slug).to_html
+    GITHUB_HOST = "raw.githubusercontent.com"
+
+    attr_reader :http
+    def_delegators :config, :doc_formats, :cache_store, :cache_options
+
+    def redirect_type?(ext)
+      !doc_formats.include?(ext)
     end
 
-    def get_redirect_url(slug)
-      GithubFile.new(slug).redirect_url
+    def detect(uri)
+      if redirect_type?(File.extname(uri))
+        Redirect.new("https://#{GITHUB_HOST}#{uri}")
+      else
+        http.retrieve(uri)
+      end
+    end
+
+    def ensure_ext(slug)
+      if File.extname(slug).empty?
+        "#{slug}#{fallback_ext}"
+      else
+        slug
+      end
+    end
+
+    def handler_for(result, result_handler)
+      case
+      when result.redirect?
+        result_handler.fetch(:redirect) {
+          raise UnhandledAction.new(:redirect, <<~MSG.chomp)
+            no result redirect handler defined for #{result_handler.inspect}
+          MSG
+        }
+      when result.success?
+        result_handler.fetch(:complete) {
+          raise UnhandledAction.new(:complete, <<~MSG.chomp)
+            no result completion handler defined for #{result_handler.inspect}
+          MSG
+        }
+      when result.not_found?
+        result_handler.fetch(:not_found) {
+          result_handler.fetch(:error) { raise result }
+        }
+      else
+        # TODO: Are we missing other cases?
+        result_handler.fetch(:error) { raise result }
+      end
     end
   end
 end
-

data/lib/doc_repo/result_handler.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+require 'forwardable'
+
+module DocRepo
+  class ResultHandler
+    extend Forwardable
+
+    def self.handler(*types)
+      types.each do |type|
+        define_method(type) do |&block|
+          raise ArgumentError, "Result handler block required" unless block
+          @actions[type] = block
+        end
+      end
+    end
+    private_class_method :handler
+
+    handler :complete, :error, :not_found, :redirect
+
+    def initialize
+      @actions = {}
+      yield self if block_given?
+    end
+
+    def_delegators :actions, :[], :each, :fetch
+
+    attr_reader :actions
+    private :actions
+  end
+end

data/lib/doc_repo/version.rb

@@ -1,3 +1,3 @@
 module DocRepo
-  VERSION = "0.1.1"
+  VERSION = "1.0.0-beta.1"
 end

data/lib/doc_repo.rb

@@ -1,23 +1,27 @@
+# frozen_string_literal: true
 require "doc_repo/version"
 
 module DocRepo
-  autoload :Configuration, "doc_repo/configuration"
-  autoload :GithubFile, "doc_repo/github_file"
-  autoload :Page, "doc_repo/page"
+  require_relative "doc_repo/configuration"
+  require_relative "doc_repo/error"
+
+  # HTTP Adapter and Results
+  autoload :NetHttpAdapter, "doc_repo/net_http_adapter"
+  autoload :HttpResult, "doc_repo/http_result"
+  autoload :Doc, "doc_repo/doc"
+  autoload :Redirect, "doc_repo/redirect"
+  autoload :HttpError, "doc_repo/http_error"
+  autoload :GatewayError, "doc_repo/gateway_error"
+
   autoload :Repository, "doc_repo/repository"
-  autoload :Response, "doc_repo/response"
-
-  BadPageFormat = Class.new(StandardError)
-  class NotFound < StandardError
-    attr_reader :base
-    def initialize(*args, base: $!)
-      @base = base
-      super(*args)
-    end
+  autoload :ResultHandler, "doc_repo/result_handler"
+
+  if defined?(Rails)
+    require_relative "doc_repo/rails"
   end
 
   class << self
-    attr_reader :configuration
+    attr_writer :configuration
 
     def configuration
       @configuration ||= Configuration.new
@@ -25,11 +29,10 @@ module DocRepo
   end
 
   def self.configure
-    yield(configuration) if block_given?
+    yield(configuration)
   end
 
-  def self.respond_with(slug, &block)
-    Repository.new.respond(slug, &block)
+  def self.request(slug, &block)
+    Repository.new(configuration).request(slug, &block)
   end
 end
-