ur 0.0.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06e6df921036d0111ac6b57e937508d5689d30bbb702ebfc691749a9c31884ed
-  data.tar.gz: d160635a422395081f510059b7916aa9264c3289c3cc1d9170769c32c6d1cbb3
+  metadata.gz: 1161e5f2e2219053fc4c54e541feb0d4c6efa1c1af930365e526a88bc0973e1b
+  data.tar.gz: b42e166ae62f0a651d5425147e64b1d200c09862869188b8f95e52454f7b8e97
 SHA512:
-  metadata.gz: 41b9e773174eb1beaa88b128ebde4e75830e4c9bc9ee907bcbf24e9be7157ba0cff8a980bdc8b18a978a02d990d7933dcd3ae88fdacba81ed59f87046d36a559
-  data.tar.gz: 42dc377e5da9acccb960e35dea7d7d874c5a90b5965b025b0dd2a8c6443b89eae282f1f034bcee450dd8962bb06470d7016cbeaebf24871e3851853db83654ff
+  metadata.gz: 17187f65ff16035e72fc7d7e0b9468bd970d337b1f8173fbc2dde15f420ad406aa33ecb440b4b65e0dffb921279660fdedb48b4bb320ce3e4e9a411eec3a21da
+  data.tar.gz: 8c8d0f0c86af8a97c18dc794e69b84634421607a7e6715120b90fd3d9f74bdd1848a5c422598dbc06fdb0ea7ce4ac474e76b761ec7e2243fdb87b2aa812af292

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+# v0.2.1
+
+- JSI v0.6.0
+
+# v0.2.0
+
+- Ur uses JSI schema modules instead of classes
+
+# v0.1.1
+- minor fixes
+
+# v0.1.0
+- rename processing to metadata
+- Ur::ContentType
+
 # v0.0.4
 - bump JSI v0.2.0
 

data/LICENSE.md

@@ -0,0 +1,169 @@
+Copright © [Ethan](https://github.com/notEthan/)
+
+[<img align="right" src="https://github.com/notEthan/ur/raw/master/resources/icons/LGPL-3.0.png">](https://www.gnu.org/licenses/lgpl-3.0.html)
+
+Ur is Open Source Software licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/lgpl-3.0.html).
+
+GNU Lesser General Public License
+=================================
+
+_Version 3, 29 June 2007_  
+_Copyright © 2007 Free Software Foundation, Inc. &lt;<https://fsf.org/>&gt;_
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+### 0. Additional Definitions
+
+As used herein, “this License” refers to version 3 of the GNU Lesser
+General Public License, and the “GNU GPL” refers to version 3 of the GNU
+General Public License.
+
+“The Library” refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An “Application” is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A “Combined Work” is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the “Linked
+Version”.
+
+The “Minimal Corresponding Source” for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The “Corresponding Application Code” for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+### 1. Exception to Section 3 of the GNU GPL
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+### 2. Conveying Modified Versions
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+* **a)** under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+* **b)** under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+### 3. Object Code Incorporating Material from Library Header Files
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+* **a)** Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+* **b)** Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+### 4. Combined Works
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+* **a)** Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+* **b)** Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+* **c)** For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+* **d)** Do one of the following:
+    - **0)** Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+    - **1)** Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that **(a)** uses at run time
+a copy of the Library already present on the user's computer
+system, and **(b)** will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version.
+
+* **e)** Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option **4d0**, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option **4d1**, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+### 5. Combined Libraries
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+* **a)** Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+* **b)** Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+### 6. Revised Versions of the GNU Lesser General Public License
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License “or any later version”
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -4,13 +4,13 @@ Ur: Unified Request/Response Representation in Ruby
 
 ## Properties
 
-An ur primarily consists of a request, a response, and additional processing information.
+An ur primarily consists of a request, a response, and additional metadata.
 
 The request consists of the request method, uri, headers, and body.
 
 The response consists of the response status, headers, and body.
 
-The processing information consists of the time the request began, the duration of the request, or tag strings. This is optional.
+The metadata consist of the time the request began, the duration of the request, or tag strings. This is optional.
 
 Other attributes may be present, and are ignored by this library.
 
@@ -30,7 +30,7 @@ class MyRackMiddleware
     ur = Ur.from_rack_request(env)
 
     # set additional properties of the ur, for example:
-    ur.logger = my_logger
+    ur.logger_tags(my_logger)
 
     rack_response = ur.with_rack_response(@app, env) do
       # do things after the response
@@ -50,7 +50,7 @@ class MyFaradayMiddleware < ::Faraday::Middleware
     ur = Ur.from_faraday_request(request_env)
 
     # set additional properties of the ur, for example:
-    ur.logger = my_logger
+    ur.logger_tags(my_logger)
 
     ur.faraday_on_complete(@app, request_env) do |response_env|
       # do things after the response
@@ -61,4 +61,6 @@ end
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+[<img align="right" src="https://github.com/notEthan/ur/raw/master/resources/icons/LGPL-3.0.png">](https://www.gnu.org/licenses/lgpl-3.0.html)
+
+Ur is Open Source Software licensed under the terms of the [GNU Lesser General Public License version 3](https://www.gnu.org/licenses/lgpl-3.0.html).

data/lib/ur/content_type.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require 'ur' unless Object.const_defined?(:Ur)
+
+module Ur
+  # Ur::ContentType represents a Content-Type header field.
+  # it parses the media type and its components, as well as any parameters.
+  #
+  # this class aims to be permissive in what it will parse. it will not raise any
+  # error when given a malformed or syntactically invalid Content-Type string.
+  # fields and parameters parsed from invalid Content-Type strings are undefined,
+  # but this class generally tries to make the most sense of what it's given.
+  #
+  # this class is based on RFCs:
+  # - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
+  #   Section 3.1.1.1. Media Type
+  #   https://tools.ietf.org/html/rfc7231#section-3.1.1.1
+  # - Media Type Specifications and Registration Procedures https://tools.ietf.org/html/rfc6838
+  # - Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies.
+  #   Section 5.1. Syntax of the Content-Type Header Field
+  #   https://tools.ietf.org/html/rfc2045#section-5.1
+  # - Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
+  #   https://tools.ietf.org/html/rfc2046
+  # - Additional Media Type Structured Syntax Suffixes
+  #   https://tools.ietf.org/html/rfc6839
+  class ContentType < String
+    # the character ranges in this SHOULD be significantly more restrictive,
+    # and the `/<subtype>` construct should not be optional. however, we'll aim
+    # to match whatever media type we are given.
+    #
+    # example:
+    #
+    #     MEDIA_TYPE_REGEXP.match('application/vnd.github+json').named_captures
+    #     =>
+    #     {
+    #       "media_type" => "application/vnd.github+json",
+    #       "type" => "application",
+    #       "subtype" => "vnd.github+json",
+    #       "facet" => "vnd",
+    #       "suffix" => "json",
+    #     }
+    #
+    # example of being more permissive than the spec allows:
+    #
+    #     MEDIA_TYPE_REGEXP.match('where the %$*! am I').named_captures
+    #     =>
+    #     {
+    #       "media_type" => "where the %$*! am I",
+    #       "type" => "where the %$*! am I",
+    #       "subtype" => nil,
+    #       "facet" => nil,
+    #       "suffix" => nil
+    #     }
+    MEDIA_TYPE_REGEXP = %r{
+      (?<media_type>       # the media type includes the type and subtype
+        (?<type>[^\/;\"]*) # the type precedes the first slash
+        (?:\/              # slash
+          (?<subtype>      # the subtype includes the facet, the suffix, and bits in between
+            (?:
+              (?<facet>[^.+;\"]*) # the facet name comes before the first . in the subtype
+              \.             # dot
+            )?
+            [^\+;\"]*      # anything between facet and suffix
+            (?:\+          # plus
+              (?<suffix>[^;\"]*) # optional suffix
+            )?
+          )
+        )? # the subtype should not be optional, but we will match a type without subtype anyway
+      )
+    }x
+
+    def initialize(*a)
+      super
+
+      scanner = StringScanner.new(self)
+
+      if scanner.scan(MEDIA_TYPE_REGEXP)
+        @media_type = scanner[:media_type].strip.freeze if scanner[:media_type]
+        @type      = scanner[:type].strip.freeze       if scanner[:type]
+        @subtype  = scanner[:subtype].strip.freeze    if scanner[:subtype]
+        @facet   = scanner[:facet].strip.freeze      if scanner[:facet]
+        @suffix = scanner[:suffix].strip.freeze     if scanner[:suffix]
+      end
+
+      @parameters = Hash.new do |h, k|
+        if k.respond_to?(:downcase) && k != k.downcase
+          h[k.downcase]
+        else
+          nil
+        end
+      end
+
+      while scanner.scan(/(;\s*)+/)
+        key = scanner.scan(/[^;=\"]*/)
+        if key && scanner.scan(/=/)
+          value = String.new
+          until scanner.eos? || scanner.check(/;/)
+            if scanner.scan(/\s+/)
+              ws = scanner[0]
+              # discard trailing whitespace.
+              # other whitespace isn't technically valid but we are permissive so we put it in the value.
+              value << ws unless scanner.eos? || scanner.check(/;/)
+            elsif scanner.scan(/"/)
+              until scanner.eos? || scanner.scan(/"/)
+                if scanner.scan(/\\/)
+                  value << scanner.getch unless scanner.eos?
+                end
+                value << scanner.scan(/[^\"\\]*/)
+              end
+            else
+              value << scanner.scan(/[^\s;\"]*/)
+            end
+          end
+          @parameters[key.downcase.freeze] = value.freeze
+        end
+      end
+
+      @parameters.freeze
+
+      freeze
+    end
+
+    # the media type of this content type.
+    # e.g. `"application/vnd.github+json"` in `content-type: application/vnd.github+json; charset="utf-8"`
+    # @return [String, nil]
+    attr_reader :media_type
+
+    # the 'type' portion of our media type.
+    # e.g. `"application"` in `content-type: application/vnd.github+json; charset="utf-8"`
+    # @return [String, nil]
+    attr_reader :type
+
+    # the 'subtype' portion of our media type.
+    # e.g. `"vnd.github+json"` in `content-type: application/vnd.github+json; charset="utf-8"`
+    # @return [String, nil]
+    attr_reader :subtype
+
+    # the 'facet' portion of our media type.
+    # e.g. `"vnd"` in `content-type: application/vnd.github+json; charset="utf-8"`
+    # @return [String, nil]
+    attr_reader :facet
+
+    # the 'suffix' portion of our media type.
+    # e.g. `"json"` in `content-type: application/vnd.github+json; charset="utf-8"`
+    # @return [String, nil]
+    attr_reader :suffix
+
+    # parameters of this content type.
+    # e.g. `{"charset" => "utf-8"}` in `content-type: application/vnd.github+json; charset="utf-8"`
+    # @return [Hash<String, String>]
+    attr_reader :parameters
+
+    # is the 'type' portion of our media type equal (case-insensitive) to the given other_type
+    # @param other_type
+    # @return [Boolean]
+    def type?(other_type)
+      type && type.casecmp?(other_type)
+    end
+
+    # is the 'subtype' portion of our media type equal (case-insensitive) to the given other_subtype
+    # @param other_subtype
+    # @return [Boolean]
+    def subtype?(other_subtype)
+      subtype && subtype.casecmp?(other_subtype)
+    end
+
+    # is the 'suffix' portion of our media type equal (case-insensitive) to the given other_suffix
+    # @param other_suffix
+    # @return [Boolean]
+    def suffix?(other_suffix)
+      suffix && suffix.casecmp?(other_suffix)
+    end
+
+    SOME_TEXT_SUBTYPES = %w(
+      x-www-form-urlencoded
+      json
+      json-seq
+      jwt
+      jose
+      yaml
+      x-yaml
+      xml
+      html
+      css
+      javascript
+      ecmascript
+    ).map(&:freeze).freeze
+
+    # does this content type appear to be binary?
+    # this library makes its best guess based on a very incomplete knowledge
+    # of which media types indicate binary or text.
+    # @param unknown [Boolean] return this value when we have no idea whether
+    #   our media type is binary or text.
+    # @return [Boolean]
+    def binary?(unknown: true)
+      return false if type_text?
+
+      SOME_TEXT_SUBTYPES.each do |cmpsubtype|
+        return false if (suffix ? suffix.casecmp?(cmpsubtype) : subtype ? subtype.casecmp?(cmpsubtype) : false)
+      end
+
+      # these are generally binary
+      return true if type_image? || type_audio? || type_video?
+
+      # we're out of ideas
+      return unknown
+    end
+
+    # is this a JSON content type?
+    # @return [Boolean]
+    def json?
+      suffix ? suffix.casecmp?('json') : subtype ? subtype.casecmp?('json') : false
+    end
+
+    # is this an XML content type?
+    # @return [Boolean]
+    def xml?
+      suffix ? suffix.casecmp?('xml'): subtype ? subtype.casecmp?('xml') : false
+    end
+
+    # is this a `x-www-form-urlencoded` content type?
+    # @return [Boolean]
+    def form_urlencoded?
+      suffix ? suffix.casecmp?('x-www-form-urlencoded'): subtype ? subtype.casecmp?('x-www-form-urlencoded') : false
+    end
+
+    # is the 'type' portion of our media type 'text'
+    # @return [Boolean]
+    def type_text?
+      type && type.casecmp?('text')
+    end
+
+    # is the 'type' portion of our media type 'image'
+    # @return [Boolean]
+    def type_image?
+      type && type.casecmp?('image')
+    end
+
+    # is the 'type' portion of our media type 'audio'
+    # @return [Boolean]
+    def type_audio?
+      type && type.casecmp?('audio')
+    end
+
+    # is the 'type' portion of our media type 'video'
+    # @return [Boolean]
+    def type_video?
+      type && type.casecmp?('video')
+    end
+
+    # is the 'type' portion of our media type 'application'
+    # @return [Boolean]
+    def type_application?
+      type && type.casecmp?('application')
+    end
+
+    # is the 'type' portion of our media type 'message'
+    # @return [Boolean]
+    def type_message?
+      type && type.casecmp?('message')
+    end
+
+    # is the 'type' portion of our media type 'multipart'
+    # @return [Boolean]
+    def type_multipart?
+      type && type.casecmp?('multipart')
+    end
+  end
+end

data/lib/ur/faraday/yield_ur.rb

@@ -1,20 +1,12 @@
-class Ur
+# frozen_string_literal: true
+
+module Ur
   module Faraday
-    class YieldUr < ::Faraday::Middleware
-      def initialize(app, options = {}, &block)
+    # Faraday middleware which yields an Ur to the given block
+    class YieldUr < ::Ur::FaradayMiddleware
+      def initialize(app, **options, &block)
         raise(ArgumentError, "no block given to yield ur") unless block
-        raise(TypeError, "options must be a Hash") unless options.respond_to?(:to_hash)
-        @app = app
-        @options = options
-        @yield_to = block
-      end
-
-      def call(request_env)
-        ur = (@options[:ur_class] || Ur).from_faraday_request(request_env)
-        ur.logger = @options[:logger] if @options[:logger]
-        ur.faraday_on_complete(@app, request_env) do |response_env|
-          @yield_to.call(ur)
-        end
+        super(app, options.merge(after_response: block))
       end
     end
   end

data/lib/ur/faraday.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 require 'faraday'
 
-class Ur
+module Ur
   module Faraday
     autoload :YieldUr, 'ur/faraday/yield_ur'
   end

data/lib/ur/{processing.rb → metadata.rb}

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require 'ur' unless Object.const_defined?(:Ur)
 
-class Ur
-  class Processing
+module Ur
+  module Metadata
     include SubUr
 
     def began_at
@@ -13,10 +15,13 @@ class Ur
 
     attr_accessor :began_at_ns
 
+    # sets began_at from the current time
     def begin!
-      self.began_at ||= Time.now
-      self.began_at_ns ||= Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+      self.began_at = Time.now
+      self.began_at_ns = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
     end
+
+    # sets the duration from the current time and began_at
     def finish!
       return if duration
       if began_at_ns

data/lib/ur/middleware.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 require 'ur' unless Object.const_defined?(:Ur)
 
-class Ur
+module Ur
   module Middleware
     def initialize(app, options = {})
       @app = app
@@ -9,6 +11,15 @@ class Ur
     attr_reader :app
     attr_reader :options
 
+    def begin_request(ur)
+      ur.metadata.begin!
+    end
+
+    def finish_request(ur)
+      ur.logger_tags(@options[:logger])
+      ur.metadata.finish!
+    end
+
     def invoke_callback(name, *a, &b)
       if @options[name]
         @options[name].call(*a, &b)
@@ -19,10 +30,11 @@ class Ur
   class FaradayMiddleware < ::Faraday::Middleware
     include Ur::Middleware
     def call(request_env)
-      ur = Ur.from_faraday_request(request_env)
+      ur = Ur.from_faraday_request(request_env, @options.select { |k, _| [:schemas].include?(k) })
       invoke_callback(:before_request, ur)
-      ur.logger = options[:logger] if options[:logger]
+      begin_request(ur)
       ur.faraday_on_complete(@app, request_env) do |response_env|
+        finish_request(ur)
         invoke_callback(:after_response, ur)
       end
     end
@@ -31,10 +43,11 @@ class Ur
   class RackMiddleware
     include Ur::Middleware
     def call(env)
-      ur = Ur.from_rack_request(env)
+      ur = Ur.from_rack_request(env, @options.select { |k, _| [:schemas].include?(k) })
       invoke_callback(:before_request, ur)
-      ur.logger = options[:logger] if options[:logger]
+      begin_request(ur)
       ur.with_rack_response(@app, env) do
+        finish_request(ur)
         invoke_callback(:after_response, ur)
       end
     end

data/lib/ur/request.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require 'ur' unless Object.const_defined?(:Ur)
 
-class Ur
-  class Request
+module Ur
+  module Request
     include RequestAndResponse
     include SubUr