Initial Implementation (#1)

src/abstract_negotiator.cr

@@ -0,0 +1,101 @@
+# Base negotiator type.  Implements logic common to all negotiators.
+abstract class Athena::Negotiation::AbstractNegotiator
+  private record OrderKey, quality : Float32, index : Int32, value : String do
+    include Comparable(self)
+
+    def <=>(other : self) : Int32
+      return @index <=> other.index if @quality == other.quality
+      @quality > other.quality ? -1 : 1
+    end
+  end
+
+  private abstract def create_header(header : String) : ANG::BaseAccept
+
+  # Returns the best `ANG::BaseAccept` type based on the provided *header* value and *priorities*.
+  #
+  # See `Athena::Negotiation` for examples.
+  def best(header : String, priorities : Indexable(String), strict : Bool = false) : ANG::BaseAccept?
+    raise ArgumentError.new "priorities should not be empty." if priorities.empty?
+    raise ArgumentError.new "The header string should not be empty." if header.blank?
+
+    accepted_headers = Array(ANG::BaseAccept).new
+
+    self.parse_header(header) do |h|
+      accepted_headers << self.create_header h
+    rescue ex
+      raise ex if strict
+    end
+
+    accepted_priorties = priorities.map &->create_header(String)
+
+    matches = self.find_matches accepted_headers, accepted_priorties
+
+    specific_matches = matches.reduce({} of Int32 => ANG::AcceptMatch) do |acc, match|
+      ANG::AcceptMatch.reduce acc, match
+    end.values
+
+    specific_matches.sort!
+
+    match = specific_matches.shift?
+
+    match.nil? ? nil : accepted_priorties[match.index]
+  end
+
+  # Returns an array of `ANG::BaseAccept` types that the provided *header* allows, ordered so that the `#best` match is first.
+  #
+  # See `Athena::Negotiation` for examples.
+  def ordered_elements(header : String) : Array(ANG::BaseAccept)
+    raise ArgumentError.new "The header string should not be empty." if header.blank?
+
+    elements = Array(ANG::BaseAccept).new
+    order_keys = Array(OrderKey).new
+
+    idx = 0
+    self.parse_header(header) do |h|
+      element = self.create_header h
+      elements << element
+      order_keys << OrderKey.new element.quality, idx, element.header
+    rescue ex
+      # skip
+    ensure
+      idx += 1
+    end
+
+    order_keys.sort!.map do |ok|
+      elements[ok.index]
+    end
+  end
+
+  protected def match(header : ANG::BaseAccept, priority : ANG::BaseAccept, index : Int32) : ANG::AcceptMatch?
+    accept_value = header.accept_value
+    priority_value = priority.accept_value
+
+    equal = accept_value.downcase == priority_value.downcase
+
+    if equal || accept_value == "*"
+      return ANG::AcceptMatch.new header.quality * priority.quality, 1 * (equal ? 1 : 0), index
+    end
+
+    nil
+  end
+
+  private def parse_header(header : String, & : String ->) : Nil
+    header.scan /(?:[^,\"]*+(?:"[^"]*+\")?)+[^,\"]*+/ do |match|
+      yield match[0].strip unless match[0].blank?
+    end
+  end
+
+  private def find_matches(headers : Array(ANG::BaseAccept), priorities : Indexable(ANG::BaseAccept)) : Array(ANG::AcceptMatch)
+    matches = [] of ANG::AcceptMatch
+
+    priorities.each_with_index do |priority, idx|
+      headers.each do |header|
+        if match = self.match(header, priority, idx)
+          matches << match
+        end
+      end
+    end
+
+    matches
+  end
+end

src/accept.cr

@@ -0,0 +1,45 @@
+require "./base_accept"
+
+# Represents an [Accept](https://tools.ietf.org/html/rfc7231#section-5.3.2) header media type.
+#
+# ```
+# accept = ANG::Accept.new "application/json; q = 0.75; charset = UTF-8"
+#
+# accept.header            # => "application/json; q = 0.9; charset = UTF-8"
+# accept.normalized_header # => "application/json; charset=UTF-8"
+# accept.parameters        # => {"charset" => "UTF-8"}
+# accept.quality           # => 0.75
+# accept.type              # => "application"
+# accept.sub_type          # => "json"
+# ```
+struct Athena::Negotiation::Accept < Athena::Negotiation::BaseAccept
+  # Returns the type for this `Accept` header.
+  # E.x. if the `#media_range` is `application/json`, the type would be `application`.
+  getter type : String
+
+  # Returns the sub type for this `Accept` header.
+  # E.x. if the `#media_range` is `application/json`, the sub type would be `json`.
+  getter sub_type : String
+
+  def initialize(value : String)
+    super value
+
+    @accept_value = "*/*" if @accept_value == "*"
+
+    parts = @accept_value.split '/'
+
+    if parts.size != 2 || !parts[0].presence || !parts[1].presence
+      raise ANG::Exceptions::InvalidMediaType.new @accept_value
+    end
+
+    @type = parts[0]
+    @sub_type = parts[1]
+  end
+
+  # Returns the media range this `Accept` header represents.
+  #
+  # I.e. `#header` minus the `#quality` and `#parameters`.
+  def media_range : String
+    @accept_value
+  end
+end

src/accept_charset.cr

@@ -0,0 +1,21 @@
+require "./base_accept"
+
+# Represents an [Accept-Charset](https://tools.ietf.org/html/rfc7231#section-5.3.3) header character set.
+#
+# ```
+# accept = ANG::AcceptCharset.new "iso-8859-1; q = 0.5; key=value"
+#
+# accept.header            # => "iso-8859-1; q = 0.5; key=value"
+# accept.normalized_header # => "iso-8859-1; key=value"
+# accept.parameters        # => {"key" => "value"}
+# accept.quality           # => 0.5
+# accept.charset           # => "iso-8859-1"
+# ```
+struct Athena::Negotiation::AcceptCharset < Athena::Negotiation::BaseAccept
+  # Returns the character set this `AcceptCharset` header represents.
+  #
+  # I.e. `#header` minus the `#quality` and `#parameters`.
+  def charset : String
+    @accept_value
+  end
+end

src/accept_encoding.cr

@@ -0,0 +1,21 @@
+require "./base_accept"
+
+# Represents an [Accept-Encoding](https://tools.ietf.org/html/rfc7231#section-5.3.4) header character set.
+#
+# ```
+# accept = ANG::AcceptEncoding.new "gzip; q = 0.5; key=value"
+#
+# accept.header            # => "gzip-1; q = 0.5; key=value"
+# accept.normalized_header # => "gzip-1; key=value"
+# accept.parameters        # => {"key" => "value"}
+# accept.quality           # => 0.5
+# accept.coding            # => "gzip"
+# ```
+struct Athena::Negotiation::AcceptEncoding < Athena::Negotiation::BaseAccept
+  # Returns the content coding this `AcceptEncoding` header represents.
+  #
+  # I.e. `#header` minus the `#quality` and `#parameters`.
+  def coding : String
+    @accept_value
+  end
+end

src/accept_language.cr

@@ -0,0 +1,55 @@
+require "./base_accept"
+
+# Represents an [Accept-Language](https://tools.ietf.org/html/rfc7231#section-5.3.5) header character set.
+#
+# ```
+# accept = ANG::AcceptLanguage.new "zh-Hans-CN; q = 0.3; key=value"
+#
+# accept.header            # => "zh-Hans-CN; q = 0.3; key=value"
+# accept.normalized_header # => "zh-Hans-CN; key=value"
+# accept.parameters        # => {"key" => "value"}
+# accept.quality           # => 0.3
+# accept.language          # => "zh"
+# accept.region            # => "cn"
+# accept.script            # => "hans"
+# ```
+struct Athena::Negotiation::AcceptLanguage < Athena::Negotiation::BaseAccept
+  # Returns the language for this `AcceptLanguage` header.
+  # E.x. if the `#language_range` is `zh-Hans-CN`, the language would be `zh`.
+  getter language : String
+
+  # Returns the region, if any, for this `AcceptLanguage` header.
+  # E.x. if the `#language_range` is `zh-Hans-CN`, the language would be `cn`
+  getter region : String? = nil
+
+  # Returns the script, if any, for this `AcceptLanguage` header.
+  # E.x. if the `#language_range` is `zh-Hans-CN`, the language would be `hans`
+  getter script : String? = nil
+
+  def initialize(value : String)
+    super value
+
+    parts = @accept_value.split '-'
+
+    case parts.size
+    when 1
+      @language = parts[0]
+    when 2
+      @language = parts[0]
+      @region = parts[1]
+    when 3
+      @language = parts[0]
+      @script = parts[1]
+      @region = parts[2]
+    else
+      raise ANG::Exceptions::InvalidLanguage.new @accept_value
+    end
+  end
+
+  # Returns the language range this `AcceptLanguage` header represents.
+  #
+  # I.e. `#header` minus the `#quality` and `#parameters`.
+  def language_range : String
+    @accept_value
+  end
+end

src/accept_match.cr

@@ -0,0 +1,30 @@
+# :nodoc:
+struct Athena::Negotiation::AcceptMatch
+  include Comparable(self)
+
+  getter quality : Float32
+  getter score : Int32
+  getter index : Int32
+
+  def self.reduce(matches : Hash(Int32, self), match : self) : Hash(Int32, self)
+    if !matches.has_key?(match.index) || matches[match.index].score < match.score
+      matches[match.index] = match
+    end
+
+    matches
+  end
+
+  def initialize(@quality : Float32, @score : Int32, @index : Int32); end
+
+  def <=>(other : self) : Int32
+    if @quality != other.quality
+      return @quality > other.quality ? -1 : 1
+    end
+
+    if @index != other.index
+      return @index > other.index ? 1 : -1
+    end
+
+    0
+  end
+end

src/athena-COMPONENT_NAME.cr

@@ -1,6 +0,0 @@
-# Convenience alias to make referencing `Athena::NAMESPACE_NAME` types easier.
-alias ALIAS_NAME = Athena::NAMESPACE_NAME
-
-module Athena::NAMESPACE_NAME
-  VERSION = "0.1.0"
-end

src/athena-negotiation.cr

@@ -0,0 +1,103 @@
+require "./accept"
+require "./accept_match"
+require "./accept_charset"
+require "./accept_encoding"
+require "./accept_language"
+require "./charset_negotiator"
+require "./encoding_negotiator"
+require "./language_negotiator"
+require "./negotiator"
+
+require "./exceptions/*"
+
+# Convenience alias to make referencing `Athena::Negotiation` types easier.
+alias ANG = Athena::Negotiation
+
+# The `Athena::Negotiation` component allows an application to support [content negotiation](https://tools.ietf.org/html/rfc7231#section-5.3).
+# The component has no dependencies and is framework agnostic; supporting various negotiators.
+#
+# ## Usage
+#
+# The main type of `Athena::Negotiation` is `ANG::AbstractNegotiator` which is used to implement negotiators for each `Accept*` header.
+# `Athena::Negotiation` exposes class level getters for each negotiator; that return a lazily initialized singleton instance.
+# Each negotiator exposes two methods: `ANG::AbstractNegotiator#best` and `ANG::AbstractNegotiator#ordered_elements`.
+#
+# ### Media Type
+#
+# ```
+# negotiator = ANG.negotiator
+#
+# accept_header = "text/html, application/xhtml+xml, application/xml;q=0.9"
+# priorities = ["text/html; charset=UTF-8", "application/json", "application/xml;q=0.5"]
+#
+# accept = negotiator.best(accept_header, priorities).not_nil!
+#
+# accept.media_range # => "text/html"
+# accept.parameters  # => {"charset" => "UTF-8"}
+# ```
+#
+# The `ANG::Negotiator` type returns an `ANG::Accept`, or `nil` if negotiating the best media type has failed.
+#
+# ### Character Set
+#
+# ```
+# negotiator = ANG.charset_negotiator
+#
+# accept_header = "ISO-8859-1, UTF-8; q=0.9"
+# priorities = ["iso-8859-1;q=0.3", "utf-8;q=0.9", "utf-16;q=1.0"]
+#
+# accept = negotiator.best(accept_header, priorities).not_nil!
+#
+# accept.charset # => "utf-8"
+# accept.quality # => 0.9
+# ```
+#
+# The `ANG::CharsetNegotiator` type returns an `ANG::AcceptCharset`, or `nil` if negotiating the best character set has failed.
+#
+# ### Encoding
+#
+# ```
+# negotiator = ANG.encoding_negotiator
+#
+# accept_header = "gzip;q=1.0, identity; q=0.5, *;q=0"
+# priorities = ["gzip", "foo"]
+#
+# accept = negotiator.best(accept_header, priorities).not_nil!
+#
+# accept.coding # => "gzip"
+# ```
+#
+# The `ANG::EncodingNegotiator` type returns an `ANG::AcceptEncoding`, or `nil` if negotiating the best character set has failed.
+#
+# ### Language
+#
+# ```
+# negotiator = ANG.language_negotiator
+#
+# accept_header = "en; q=0.1, fr; q=0.4, zh-Hans-CN; q=0.9, de; q=0.2"
+# priorities = ["de", "zh-Hans-CN", "en"]
+#
+# accept = negotiator.best(accept_header, priorities).not_nil!
+#
+# accept.language # => "zh"
+# accept.region   # => "cn"
+# accept.script   # => "hans"
+# ```
+#
+# The `ANG::LanguageNegotiator` type returns an `ANG::AcceptLanguage`, or `nil` if negotiating the best character set has failed.
+module Athena::Negotiation
+  # Returns a lazily initialized `ANG::Negotiator` singleton instance.
+  class_getter(negotiator) { ANG::Negotiator.new }
+
+  # Returns a lazily initialized `ANG::CharsetNegotiator` singleton instance.
+  class_getter(charset_negotiator) { ANG::CharsetNegotiator.new }
+
+  # Returns a lazily initialized `ANG::EncodingNegotiator` singleton instance.
+  class_getter(encoding_negotiator) { ANG::EncodingNegotiator.new }
+
+  # Returns a lazily initialized `ANG::LanguageNegotiator` singleton instance.
+  class_getter(language_negotiator) { ANG::LanguageNegotiator.new }
+
+  # Contains all custom exceptions defined within `Athena::Negotiation`.
+  module Exceptions; end
+end

src/base_accept.cr

@@ -0,0 +1,50 @@
+# Base type for properties/logic all [Accept*](https://tools.ietf.org/html/rfc7231#section-5.3) headers share.
+abstract struct Athena::Negotiation::BaseAccept
+  # Returns the full unaltered header `self` represents.
+  # E.x. `text/html` or `unicode-1-1;q=0.8` or `zh-Hans-CN`.
+  getter header : String
+
+  # Returns a normalized version of the `#header`, excluding the `#quality` parameter.
+  #
+  # This includes removing extraneous whitespace, and alphabetizing the `#parameters`.
+  getter normalized_header : String
+
+  # Returns any extension parameters included in the header `self` represents.
+  # E.x. `charset=UTF-8` or `version=2`.
+  getter parameters : Hash(String, String) = Hash(String, String).new
+
+  # Returns the [quality value](https://tools.ietf.org/html/rfc7231#section-5.3.1) of the header `self` represents.
+  getter quality : Float32 = 1.0
+
+  # Represents the base header value, e.g. `#header` minus the `#quality` and `#parameters`.
+  # This is exposed as a getter on each subtype to have a more descriptive API.
+  protected getter accept_value : String
+
+  def initialize(@header : String)
+    parts = @header.split ';'
+    @accept_value = parts.shift.strip.downcase
+
+    parts.each do |part|
+      part = part.split '='
+
+      # Skip invalid parameters
+      next unless part.size == 2
+
+      @parameters[part[0].strip.downcase] = part[1].strip(" \"")
+    end
+
+    if quality = @parameters.delete "q"
+      # RFC Only allows max of 3 decimal points.
+      @quality = quality.to_f32.round 3
+    end
+
+    @normalized_header = String.build do |io|
+      io << @accept_value
+
+      unless @parameters.empty?
+        io << "; "
+        @parameters.keys.sort!.join(io, "; ") { |k, join_io| join_io << "#{k}=#{@parameters[k]}" }
+      end
+    end
+  end
+end

src/charset_negotiator.cr

@@ -0,0 +1,8 @@
+require "./abstract_negotiator"
+
+# A `ANG::AbstractNegotiator` implementation to negotiate `ANG::AcceptCharset` headers.
+class Athena::Negotiation::CharsetNegotiator < Athena::Negotiation::AbstractNegotiator
+  private def create_header(header : String) : ANG::BaseAccept
+    ANG::AcceptCharset.new header
+  end
+end

src/encoding_negotiator.cr

@@ -0,0 +1,8 @@
+require "./abstract_negotiator"
+
+# A `ANG::AbstractNegotiator` implementation to negotiate `ANG::AcceptEncoding` headers.
+class Athena::Negotiation::EncodingNegotiator < Athena::Negotiation::AbstractNegotiator
+  private def create_header(header : String) : ANG::BaseAccept
+    ANG::AcceptEncoding.new header
+  end
+end

src/exceptions/invalid_language.cr

@@ -0,0 +1,11 @@
+require "./negotiation_exception"
+
+# Represents an invalid `ANG::AcceptLanguage` header.
+class Athena::Negotiation::Exceptions::InvalidLanguage < Athena::Negotiation::Exceptions::Negotiation
+  # Returns the invalid language code.
+  getter language : String
+
+  def initialize(@language : String, cause : Exception? = nil)
+    super "Invalid language: '#{@language}'.", cause
+  end
+end

src/exceptions/invalid_media_type.cr

@@ -0,0 +1,11 @@
+require "./negotiation_exception"
+
+# Represents an invalid `ANG::Accept` header.
+class Athena::Negotiation::Exceptions::InvalidMediaType < Athena::Negotiation::Exceptions::Negotiation
+  # Returns the invalid media range.
+  getter media_range : String
+
+  def initialize(@media_range : String, cause : Exception? = nil)
+    super "Invalid media type: '#{@media_range}'.", cause
+  end
+end

src/exceptions/negotiation_exception.cr

@@ -0,0 +1,4 @@
+# Base type of all `Athena::Negotiation` errors.
+# Can be used to rescue any exception originating from `Athena::Negotiation`.
+abstract class Athena::Negotiation::Exceptions::Negotiation < ::Exception
+end

src/language_negotiator.cr

@@ -0,0 +1,27 @@
+require "./abstract_negotiator"
+
+# A `ANG::AbstractNegotiator` implementation to negotiate `ANG::AcceptLanguage` headers.
+class Athena::Negotiation::LanguageNegotiator < Athena::Negotiation::AbstractNegotiator
+  protected def match(accept : ANG::AcceptLanguage, priority : ANG::AcceptLanguage, index : Int32) : ANG::AcceptMatch?
+    accept_base = accept.language
+    priority_base = priority.language
+
+    accept_sub = accept.region
+    priority_sub = priority.region
+
+    base_equal = accept_base.downcase == priority_base.downcase
+    sub_equal = accept_sub.try &.downcase == priority_sub.try &.downcase
+
+    if ((accept_base == "*" || base_equal) && (accept_sub.nil? || sub_equal))
+      score = 10 * (base_equal ? 1 : 0) + (sub_equal ? 1 : 0)
+
+      return ANG::AcceptMatch.new accept.quality * priority.quality, score, index
+    end
+
+    nil
+  end
+
+  private def create_header(header : String) : ANG::BaseAccept
+    ANG::AcceptLanguage.new header
+  end
+end

src/negotiator.cr

@@ -0,0 +1,70 @@
+require "./abstract_negotiator"
+
+# A `ANG::AbstractNegotiator` implementation to negotiate `ANG::Accept` headers.
+class Athena::Negotiation::Negotiator < Athena::Negotiation::AbstractNegotiator
+  # TODO: Make this method less complex.
+  #
+  # ameba:disable Metrics/CyclomaticComplexity
+  protected def match(accept : ANG::Accept, priority : ANG::Accept, index : Int32) : ANG::AcceptMatch?
+    accept_type = accept.type
+    priority_type = priority.type
+
+    accept_sub_type = accept.sub_type
+    priority_sub_type = priority.sub_type
+
+    intercection = accept.parameters.each_with_object({} of String => String) do |(k, v), params|
+      priority.parameters.tap do |pp|
+        params[k] = v if pp.has_key?(k) && pp[k] == v
+      end
+    end
+
+    type_equals = accept_type.downcase == priority_type.downcase
+    sub_type_equals = accept_sub_type.downcase == priority_sub_type.downcase
+
+    if (
+         (accept_type == "*" || type_equals) &&
+         (accept_sub_type == "*" || sub_type_equals) &&
+         intercection.size == accept.parameters.size
+       )
+      score = 100 * (type_equals ? 1 : 0) + 10 * (sub_type_equals ? 1 : 0) + intercection.size
+
+      return ANG::AcceptMatch.new accept.quality * priority.quality, score, index
+    end
+
+    return nil if !accept_sub_type.includes?('+') || !priority_sub_type.includes?('+')
+
+    accept_sub_type, accept_plus = self.split_sub_type accept_sub_type
+    priority_sub_type, priority_plus = self.split_sub_type priority_sub_type
+
+    if (
+         !(accept_type == "*" || type_equals) ||
+         !(accept_sub_type == "*" || priority_sub_type == "*" || accept_plus == "*" || priority_plus == "*")
+       )
+      return nil
+    end
+
+    sub_type_equals = accept_sub_type.downcase == priority_sub_type.downcase
+    plus_equals = accept_plus.downcase == priority_plus.downcase
+
+    if (
+         (accept_sub_type == "*" || priority_sub_type == "*" || sub_type_equals) &&
+         (accept_plus == "*" || priority_plus == '*' || plus_equals) &&
+         intercection.size == accept.parameters.size
+       )
+      score = 100 * (type_equals ? 1 : 0) + 10 * (sub_type_equals ? 1 : 0) + (plus_equals ? 1 : 0) + intercection.size
+      return ANG::AcceptMatch.new accept.quality * priority.quality, score, index
+    end
+
+    nil
+  end
+
+  private def split_sub_type(sub_type : String) : Array(String)
+    return [sub_type, ""] unless sub_type.includes? '+'
+
+    sub_type.split '+', limit: 2
+  end
+
+  private def create_header(header : String) : ANG::BaseAccept
+    ANG::Accept.new header
+  end
+end