nitlink 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 76d7bf9f8436e8b45762a03ae9a73b613db238f7
+  data.tar.gz: 4af8d8f6a3c09991d4254355be30c8e9148a9551
+SHA512:
+  metadata.gz: 29b158182dad5e2199db2b2620affc893ec8af246df861ba91cf41e7119ca1515cf17d6830995fa7f6ffc478ba08faab7b067de829a03a79ec5d2ced9d80d409
+  data.tar.gz: e789dc5dafd4415e9b335be5e33b84503564b0a8db932ea203222374094e7f12ac9a840f4fc166c2e52b75e63555094e0d49f1f42a4ab261f012293df8bc3ec6

data/lib/nitlink.rb

@@ -0,0 +1,4 @@
+require_relative './nitlink/parser'
+
+module Nitlink
+end

data/lib/nitlink/exceptions.rb

@@ -0,0 +1,6 @@
+module Nitlink
+  class MalformedLinkHeaderError < StandardError; end
+  class EncodedParamSyntaxError < StandardError; end
+  class UnsupportedCharsetError < StandardError; end
+  class UnknownResponseTypeError < StandardError; end
+end

data/lib/nitlink/link.rb

@@ -0,0 +1,4 @@
+module Nitlink
+  Link = Struct.new(:target, :relation_type, :context, :target_attributes) do
+  end
+end

data/lib/nitlink/link_collection.rb

@@ -0,0 +1,16 @@
+require 'hashwithindifferentaccess'
+
+module Nitlink
+  class LinkCollection < Array
+    def by_rel(relation_type)
+      raise ArgumentError.new('relation_type cannot be blank') if (!relation_type || relation_type.empty?)
+      find { |link| link.relation_type == relation_type.downcase.to_s }
+    end
+
+    def to_h
+      hash = HashWithIndifferentAccess.new
+      each { |link| hash[link.relation_type] ||= link }
+      hash
+    end
+  end
+end

data/lib/nitlink/param_decoder.rb

@@ -0,0 +1,24 @@
+require 'cgi'
+
+module Nitlink
+  class ParamDecoder
+    def decode(param_value)
+      charset, language, value_chars = param_value.split("'")
+
+      raise syntax_error(param_value) unless charset && language && value_chars
+      raise wrong_charset(charset) unless charset.downcase == 'utf-8'
+
+      CGI.unescape(value_chars)
+    end
+
+    private
+
+    def syntax_error(val)
+      EncodedParamSyntaxError.new(%Q{Syntax error decoding encoded parameter value "#{ val }", must be in the form: charset "'" [ language ] "'" value-chars})
+    end
+
+    def wrong_charset(charset)
+      UnsupportedCharsetError.new("Invalid charset #{charset}, encoded parameter values must use the UTF-8 character encoding") 
+    end
+  end
+end

data/lib/nitlink/param_extractor.rb

@@ -0,0 +1,58 @@
+module Nitlink
+  class ParamExtractor
+    QUOTED_VALUE = /\A"(.*)"\Z/m
+    QUOTED_PAIR = /\\./m
+
+    LEADING_OWS = /\A[\x09\x20]+/
+    TRAILING_OWS = /[\x09\x20]+\Z/
+
+    def extract(rest)
+      @rest = rest
+      parameter_strings = Splitter.new(rest).split_on_unquoted(';')
+      raw_params = parameter_strings.map do |parameter_str|
+        strip_ows(parameter_str).split('=', 2)
+      end
+
+      return format(raw_params)
+    end
+
+    private
+
+    def format(raw_params)
+      raw_params.map do |raw_param_name, raw_param_value|
+        next if !raw_param_name
+        param_name = rstrip_ows(raw_param_name.downcase)
+
+        if raw_param_value
+          param_value = lstrip_ows(raw_param_value)
+          param_value = format_quoted_value(param_value) if quoted?(param_value)
+        else
+          param_value = nil
+        end
+
+        [param_name, param_value]
+      end.compact
+    end
+
+    def format_quoted_value(quoted_value)
+      without_quotes = quoted_value.strip[QUOTED_VALUE, 1]
+      without_quotes.gsub(QUOTED_PAIR) { |match| match.chars.to_a.last }
+    end
+
+    def quoted?(param_value)
+      param_value =~ QUOTED_VALUE
+    end
+
+    def lstrip_ows(str)
+      str.gsub(LEADING_OWS, '')
+    end
+
+    def rstrip_ows(str)
+      str.gsub(TRAILING_OWS, '')
+    end
+
+    def strip_ows(str)
+      rstrip_ows(lstrip_ows str)
+    end
+  end
+end

data/lib/nitlink/parser.rb

@@ -0,0 +1,101 @@
+require_relative './exceptions'
+require_relative './splitter'
+require_relative './link_collection'
+require_relative './link'
+require_relative './response_normalizer'
+require_relative './param_extractor'
+require_relative './param_decoder'
+
+module Nitlink
+  class Parser
+    SINGLE_LINK = /\A\s*<([^>]*)>(.*)/
+    RWS = /[\x09\x20]+/
+
+    attr_reader :options
+
+    def parse(response, http_method = 'GET')
+      @http_method = http_method
+      @request_uri, @status, link_header, @content_location_header = ResponseNormalizer.new.metadata(response)
+
+      links = LinkCollection.new
+      return links unless link_header
+
+      unfolded_header = link_header.gsub(/\r?\n[\x20\x09]+/, '')
+      link_strings = Splitter.new(unfolded_header).split_on_unquoted(',')
+
+      parse_links(link_strings, links)
+    end
+
+    private
+
+    def parse_links(link_strings, link_collection)
+      link_strings.each do |link_string|
+        well_formed, target_string, rest = link_string.match(SINGLE_LINK).to_a
+        raise malformed(link_string) unless well_formed
+
+        link_parameters = ParamExtractor.new.extract(rest)
+        create_links(target_string, link_parameters).each { |link| link_collection.push(link) }
+      end
+
+      link_collection
+    end
+
+    def create_links(target_string, link_parameters)
+      target, relation_types, context, target_attributes = link_attributes(target_string, link_parameters)
+      relation_types.map do |relation_type|
+        Link.new(target, relation_type, context, target_attributes)
+      end
+    end
+
+    def link_attributes(target_string, link_parameters)
+      target = @request_uri.merge(target_string)
+
+      relations_string = first_match(link_parameters, 'rel') || ''
+      relation_types = relations_string.split(RWS)
+
+      context_string = first_match(link_parameters, 'anchor') || identity
+      context = (context_string && @request_uri.scheme) ? @request_uri.merge(context_string) : nil
+
+      target_attributes = extract_target_attributes(link_parameters)
+      [target, relation_types, context, target_attributes]
+    end
+
+    def first_match(link_parameters, param_name)
+      (link_parameters.find { |name, value| name == param_name } || []).last
+    end
+
+    def extract_target_attributes(link_parameters)
+      target_attributes = []
+      link_parameters.each do |param_name, param_value|
+        next if %(rel anchor).include?(param_name)
+        next if %(media title title* type).include?(param_name) && first_match(target_attributes, param_name)
+
+        begin
+          param_value = decode(param_value) if param_name.end_with?('*')
+        rescue EncodedParamSyntaxError, UnsupportedCharsetError
+          next
+        end
+
+        target_attributes.push [param_name, param_value]
+      end
+
+      Hash[target_attributes]
+    end
+
+    def malformed(link_string)
+      MalformedLinkHeaderError.new("Malformed link header (#{ link_string })")
+    end
+
+    def decode(param_value)
+      ParamDecoder.new.decode(param_value)
+    end
+
+    def identity
+      if %w(GET HEAD).include?(@http_method.upcase) && [200, 203, 204, 206, 304].include?(@status)
+        @request_uri
+      else
+        @content_location_header
+      end
+    end
+  end
+end

data/lib/nitlink/response.rb

@@ -0,0 +1,14 @@
+require_relative '../nitlink'
+
+module Nitlink
+  module ResponseDecorator
+    def links
+      Nitlink::Parser.new.parse(self)
+    end
+  end
+end
+
+decoratable_responses = ['Curl::Easy', 'Excon::Response', 'Faraday::Response', 'HTTP::Message', 'HTTP::Response', 'HTTParty::Response', 'Net::HTTPResponse', 'Patron::Response', 'RestClient::Response', 'Typhoeus::Response', 'Unirest::HttpResponse']
+decoratable_responses.select { |klass| Object.const_defined?(klass) }.each do |klass|
+  Object.const_get(klass).class_eval { include Nitlink::ResponseDecorator }
+end

data/lib/nitlink/response_normalizer.rb

@@ -0,0 +1,75 @@
+require 'uri'
+require 'hashwithindifferentaccess'
+
+module Nitlink
+  class ResponseNormalizer
+    def metadata(response)
+      response_class = response.class.name
+
+      uri, status, (link, content_location) = case response_class
+      when 'Curl::Easy'
+        [response.url, response.response_code, grab_headers(headers_from_string response.header_str)]
+      when 'Excon::Response'
+        scheme = response.port == 443 ? 'https' : 'http'
+        # We have to reconstruct to URL annoyingly
+        uri = URI::HTTP.new(scheme, nil, response.host, nil, nil, response.path, nil, nil, nil)
+
+        [uri, response.status, grab_headers(response.headers)]
+      when 'Faraday::Response'
+        response = response.to_hash
+        [response[:url], response[:status], grab_headers(response[:response_headers])]
+      when 'HTTP::Message'
+        [response.header.request_uri, response.status, grab_headers(Hash[response.header.all])]
+      when 'HTTP::Response'
+        [response.uri, response.status, grab_headers(response.headers.to_h)]
+      when 'HTTParty::Response'
+        [response.request.uri, response.code, grab_headers(response.response.to_hash)]
+      when 'Patron::Response'
+        [response.url, response.status, grab_headers(response.headers)]
+      when 'RestClient::Response'
+        [response.request.url, response.code, grab_headers(response.net_http_res.to_hash)]
+      when 'Tempfile', 'StringIO'
+        # ↑ returned by OpenURI
+        [response.base_uri, response.status[0], grab_headers(response.meta)]
+      when 'Typhoeus::Response'
+        [response.request.base_url, response.code, grab_headers(response.headers)]
+      # :nocov:
+      when 'Unirest::HttpResponse'
+        return metadata(response.raw_body)
+      # :nocov:
+      when 'Hash'
+        response = HashWithIndifferentAccess.new(response)
+        response[:headers] = headers_from_string(response[:headers]) if String === response[:headers]
+
+        [response[:request_uri], response[:status], grab_headers(response[:headers])]
+      else
+        if defined?(Net::HTTPResponse) && Net::HTTPResponse === response
+          [response.uri, response.code, grab_headers(response.to_hash)]
+        else
+          raise unknown_type(response)
+        end
+      end
+
+      [URI.parse(uri.to_s), (status ? Integer(status) : status), link, content_location]
+    end
+
+    private
+
+    def headers_from_string(header_str)
+      headers = header_str.split("\n").map do |header|
+        header.strip.split(/\s*:\s*/, 2)
+      end
+
+      Hash[headers.reject(&:empty?)]
+    end
+
+    def grab_headers(headers)
+      normalized_headers = Hash[headers.map { |key, value| [key.to_s.downcase, Array(value).join(',')] }]
+      [normalized_headers['link'], normalized_headers['content-location']]
+    end
+
+    def unknown_type(response)
+      UnknownResponseTypeError.new("Unknown response type #{response.class.name}")
+    end
+  end
+end

data/lib/nitlink/splitter.rb

@@ -0,0 +1,40 @@
+require 'strscan'
+
+module Nitlink
+  class Splitter
+    def initialize(string)
+      @string = string
+      @scanner = StringScanner.new(string)
+    end
+
+    def split_on_unquoted(seperator)
+      # 0 = start of string
+      split_positions, ignored_split_positions = [0], [] 
+      in_quote = false
+
+      until @scanner.eos?
+        char = @scanner.getch
+        @scanner.getch if in_quote && char == "\\"
+
+        in_quote = !in_quote if char == '"'
+        @scanner.skip_until(/>/) and next if char == '<' && in_url?
+
+        if char == seperator
+          ignored_split_positions = []
+          (in_quote ? ignored_split_positions : split_positions) << @scanner.pos
+        end
+      end
+      split_positions << @string.length # end of string
+      split_positions += ignored_split_positions if in_quote # dangling quote
+
+      split_positions.sort.each_cons(2).inject([]) do |split_parts, (start_pos, end_pos)|
+        split_parts << @string[start_pos...end_pos].chomp(seperator)
+      end
+    end
+
+    def in_url?
+      preceeding = @scanner.string[0...(@scanner.pos - 1)].strip
+      preceeding.end_with?(',') || preceeding.empty?
+    end
+  end
+end

data/lib/nitlink/version.rb

@@ -0,0 +1,3 @@
+module Nitlink
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: nitlink
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alex Peattie
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-11-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashwithindifferentaccess
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !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.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+- !ruby/object:Gem::Dependency
+  name: simplecov-shield
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: |-
+  Nitlink is a nice, nitpicky gem for parsing Link headers, which aims to stick
+   as closely as possible to RFC 5988. Has support for UTF-8 encoded parameters, URI resolution, boolean parameters,
+   weird edge cases and more.
+email:
+- me@alexpeattie.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/nitlink.rb
+- lib/nitlink/exceptions.rb
+- lib/nitlink/link.rb
+- lib/nitlink/link_collection.rb
+- lib/nitlink/param_decoder.rb
+- lib/nitlink/param_extractor.rb
+- lib/nitlink/parser.rb
+- lib/nitlink/response.rb
+- lib/nitlink/response_normalizer.rb
+- lib/nitlink/splitter.rb
+- lib/nitlink/version.rb
+homepage: https://github.com/alexpeattie/nitlink
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Nitlink is a nitpicky gem for parsing Link headers (per RFC 5988)
+test_files: []