hook0-client 2.0.0

data/lib/hook0/transport.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "version"
+
+module Hook0
+  # A request the API never answered, and what caused that.
+  #
+  # The three causes are told apart because only one of them could end differently. A request that
+  # got no answer — a connection refused or reset, an attempt out of time, a body that stopped
+  # mid-way — says nothing about whether the API acted on it, which is exactly why a send carries an
+  # identifier the client chose itself, and why repeating it is safe and worth doing. An answer that
+  # crossed a ceiling this client set for itself draws the same answer the second time, and reading
+  # it again four times over costs the caller four times as much for the same failure. A URL nothing
+  # can be sent to was never sent at all, and a repetition builds the same unusable request, turning
+  # a misconfiguration into a message that accuses the network.
+  #
+  # The names are the ones the shared conformance corpus gives them, so the verdict a client applies
+  # and the verdict that corpus writes down are the same words.
+  class TransportError < StandardError
+    # @return [String] which of the corpus's causes this is
+    attr_reader :cause_name
+
+    # @param detail [String] what went wrong, in the words a caller is given
+    # @param cause_name [String] which of the corpus's causes this is
+    # @param retryable [Boolean] whether repeating the request could end differently
+    def initialize(detail, cause_name, retryable)
+      super(detail)
+      @cause_name = cause_name
+      @retryable = retryable
+    end
+
+    # Whether repeating the request that met this could end differently.
+    #
+    # @return [Boolean]
+    def retryable?
+      @retryable
+    end
+
+    # The API was reached for and answered nothing this client could read to its end.
+    #
+    # @param detail [String]
+    # @return [TransportError]
+    def self.no_answer(detail)
+      new(detail, "no_answer", true)
+    end
+
+    # The API answered, and what it answered crossed a ceiling this client set for itself.
+    #
+    # @param detail [String]
+    # @return [TransportError]
+    def self.answer_above_a_bound(detail)
+      new(detail, "answer_above_a_bound", false)
+    end
+
+    # There is nowhere to send the request, so nothing was sent.
+    #
+    # @param detail [String]
+    # @return [TransportError]
+    def self.unusable_api_url(detail)
+      new(detail, "unusable_api_url", false)
+    end
+  end
+
+  # How a request reaches the API, and what a server on the other end is not allowed to cost.
+  #
+  # The transport answers the status and the bytes and knows nothing of what the API declares:
+  # reading those bytes is the generated half's job, and deciding whether to send them again is the
+  # client's. That is what lets one HTTP implementation serve both the hand-written event path and
+  # every generated method — a generated group calls whatever object it is handed, and this is the
+  # one this gem ships.
+  #
+  # Nothing here reaches for a third-party HTTP library. Everything a server controls is bounded:
+  # how long one exchange may take, and how many bytes of body are read off the socket.
+  class Transport
+    # Longest one attempt at reaching the API is given before it is abandoned, in seconds.
+    #
+    # Ten seconds is far above what ingesting an event takes when the API is healthy, and short
+    # enough that a stuck connection does not hold a caller for a noticeable time.
+    DEFAULT_REQUEST_TIMEOUT = 10.0
+
+    # Largest response body read off a socket, in bytes.
+    DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+
+    # How many header lines an answer may carry before it is refused.
+    #
+    # `Net::HTTP` bounds neither how many header lines it accepts nor how long one may be: it holds
+    # fifty thousand of them, and a single value of eight megabytes, without complaint. So the head
+    # of an answer is a server-controlled way to spend a caller's memory, and the ceiling has to be
+    # this client's own. Sixty-four is well above what the API sends.
+    DEFAULT_MAX_RESPONSE_HEADERS = 64
+
+    # Longest one header line may be, name and value together, in bytes.
+    DEFAULT_MAX_HEADER_BYTES = 64 * 1024
+
+    # Largest whole head an answer may carry, every line counted together, in bytes.
+    #
+    # This is the one that bounds what a head costs. A line count and a size per line multiply:
+    # sixty-four lines of sixty-four kilobytes each is four megabytes of head, and both of the
+    # bounds above admit it. They earn their place by refusing early, on the line that crosses
+    # them rather than at the end of the head; this one sets the ceiling.
+    #
+    # Sixteen kilobytes is what Node enforces by default, and matching it is the point: a lower
+    # ceiling would refuse heads another target accepts, and a higher one would not bind there at
+    # all, leaving each language a different effective limit.
+    DEFAULT_MAX_HEAD_BYTES = 16 * 1024
+
+    # What a request body says it carries, and what an answer is asked for in.
+    JSON_MEDIA_TYPE = "application/json"
+
+    # Longest each part the User-Agent is composed out of may be, in characters.
+    #
+    # The runtime and the operating system are described by the platform rather than by this gem, so
+    # their length is not this gem's to guarantee: they are cut here so that the header cannot grow
+    # with whatever the platform feels like saying. Every part is also stripped of anything the
+    # grammar of the header uses as punctuation, so a platform cannot forge a shape it does not have.
+    MAX_USER_AGENT_PART_CHARS = 64
+    private_constant :MAX_USER_AGENT_PART_CHARS
+
+    # One part of the User-Agent, with everything the header's own grammar uses taken out of it and
+    # cut to MAX_USER_AGENT_PART_CHARS.
+    def self.clipped(part)
+      part.to_s.each_char.select { |character| character.match?(/[ -~]/) && !"();".include?(character) }
+          .first(MAX_USER_AGENT_PART_CHARS).join
+    end
+    private_class_method :clipped
+
+    # Which SDK, at which version, on which runtime and operating system, is talking to the API.
+    #
+    # The version is the constant the gemspec reads rather than a number written down again here:
+    # one remembered in two places is one that will disagree with itself the first time it is bumped.
+    USER_AGENT = "hook0-client-ruby/#{clipped(Hook0::VERSION)} " \
+                 "(#{clipped("ruby #{RUBY_VERSION}")}; #{clipped(RUBY_PLATFORM)})".freeze
+    private_constant :USER_AGENT
+
+    # Longest a duration this client states its retry policy in may be, in milliseconds.
+    #
+    # The three durations of a policy are numbers a caller set, and a header is no place for
+    # whatever arithmetic they lead to: about twenty-five days is already past any schedule a send
+    # could hold, and cutting to it is what keeps the value an integer whatever was configured.
+    MAX_STATED_MILLISECONDS = (2**31) - 1
+    private_constant :MAX_STATED_MILLISECONDS
+
+    # The schemes this transport reaches.
+    SCHEMES = %w[http https].freeze
+
+    # What the standard library reports when the API was not reached at all.
+    UNREACHABLE = [
+      IOError,
+      SocketError,
+      SystemCallError,
+      Timeout::Error,
+      Net::HTTPBadResponse,
+      Net::HTTPHeaderSyntaxError,
+      Net::ProtocolError,
+      OpenSSL::SSL::SSLError
+    ].freeze
+
+    # @param base_url [String] where the API lives, such as https://app.hook0.com/api/v1
+    # @param token [String] an authentication token valid for that API
+    # @param timeout [Float] how long one attempt is given, in seconds
+    # @param max_response_bytes [Integer] the largest answer read off a socket
+    # @param max_response_headers [Integer] how many header lines an answer may carry
+    # @param max_header_bytes [Integer] the longest one header line may be
+    # @param max_head_bytes [Integer] the largest whole head, every line counted together
+    # @param retry_policy [RetryPolicy] the policy every request states the client was built with
+    def initialize(
+      base_url,
+      token,
+      timeout: DEFAULT_REQUEST_TIMEOUT,
+      max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES,
+      max_response_headers: DEFAULT_MAX_RESPONSE_HEADERS,
+      max_header_bytes: DEFAULT_MAX_HEADER_BYTES,
+      max_head_bytes: DEFAULT_MAX_HEAD_BYTES,
+      retry_policy: RetryPolicy.new
+    )
+      @base_url = base_url
+      @token = token
+      @timeout = timeout
+      @max_response_bytes = max_response_bytes
+      @max_response_headers = max_response_headers
+      @max_header_bytes = max_header_bytes
+      @max_head_bytes = max_head_bytes
+      @retry_policy = retry_policy
+    end
+
+    # What the API answered, whether or not it answered a success.
+    #
+    # This is the shape the generated half of this gem reads, which is the status and the bytes. A
+    # caller that also needs what the answer carried beside its body — the delay a paced instance
+    # names is one — asks {#deliver} for it.
+    #
+    # @param method [String] the HTTP method the operation is issued under
+    # @param path [String] where the request lands, absolute or under the base URL
+    # @param query [Array<Array<String>>] the name and value pairs of the query string
+    # @param body [Object, nil] what to send as a JSON document, or nothing at all
+    # @return [Array(Integer, String)] the status and the body
+    # @raise [TransportError] when the API answered nothing at all
+    def request(method, path, query = [], body = nil)
+      status, _, payload = deliver(method, path, query, body)
+      [status, payload]
+    end
+
+    # What the API answered, headers included, whether or not it answered a success.
+    #
+    # Header names are lowercased and a later value wins over an earlier one under the same name, so
+    # a caller reads a header without knowing which case the server wrote it in.
+    #
+    # @param method [String] the HTTP method the operation is issued under
+    # @param path [String] where the request lands, absolute or under the base URL
+    # @param query [Array<Array<String>>] the name and value pairs of the query string
+    # @param body [Object, nil] what to send as a JSON document, or nothing at all
+    # @return [Array(Integer, Hash{String => String}, String)] the status, the headers and the body
+    # @raise [TransportError] when the API answered nothing at all
+    def deliver(method, path, query = [], body = nil)
+      target = resolved(path, query)
+      exchange(target, built(method, target, body))
+    end
+
+    private
+
+    # Where a request lands: a path of its own replaces the base's, a relative one extends it.
+    def resolved(path, query)
+      begin
+        target = URI.join("#{@base_url.to_s.chomp("/")}/", path.to_s)
+      rescue URI::Error => e
+        raise TransportError.unusable_api_url(e.message)
+      end
+      unless reachable?(target)
+        raise TransportError.unusable_api_url("`#{target}` is not somewhere this transport can send a request")
+      end
+      return target if query.nil? || query.empty?
+
+      separator = target.query.nil? || target.query.empty? ? "" : "#{target.query}&"
+      target.query = "#{separator}#{URI.encode_www_form(query)}"
+      target
+    end
+
+    def reachable?(target)
+      SCHEMES.include?(target.scheme) && !target.host.nil? && !target.host.empty?
+    end
+
+    # One request, as Net::HTTP carries it.
+    def built(method, target, body)
+      request = Net::HTTPGenericRequest.new(method.to_s.upcase, !body.nil?, true, target)
+      request["Authorization"] = "Bearer #{@token}"
+      request["Accept"] = JSON_MEDIA_TYPE
+      # Set rather than left alone: what `Net::HTTP` names itself here is the word `Ruby`, which says
+      # nothing about which SDK is talking or which version of it.
+      request["User-Agent"] = USER_AGENT
+      request["Hook0-Client-Options"] = client_options
+      unless body.nil?
+        request["Content-Type"] = JSON_MEDIA_TYPE
+        request.body = JSON.generate(body)
+      end
+      request
+    end
+
+    # The retry policy this transport was built to serve, as every request states it.
+    #
+    # What it states is what the policy holds rather than what one send went on to do: a policy
+    # allowing a single attempt still names the delays it holds, and an instance reading
+    # `attempts=1` already knows none of them will be waited. It is the one client setting the API
+    # can see the consequences of without being told — a burst of identical requests is a client
+    # repeating one send, and nothing else on the wire tells that apart from a client in a loop.
+    #
+    # The grammar is the one `X-Hook0-Signature` already travels under, parts joined by `,` and each
+    # cut at its first `=`, so nothing here is a second shape to get wrong.
+    def client_options
+      "attempts=#{@retry_policy.attempts}," \
+        "backoff=#{stated_milliseconds(@retry_policy.initial_backoff_in_force)}," \
+        "ceiling=#{stated_milliseconds(@retry_policy.max_backoff_in_force)}," \
+        "budget=#{stated_milliseconds(@retry_policy.max_total_delay_in_force)}"
+    end
+
+    # One duration of that policy, in the whole milliseconds it is stated as.
+    #
+    # What arrives here is already the duration in force, so a value no schedule could be built on
+    # has been read as its default before this sees it: what is stated and what is waited are the
+    # same number by construction rather than by two rules that agree today. All that is left is the
+    # ceiling, which keeps a finite duration nobody meant from deciding how long the header is.
+    def stated_milliseconds(seconds)
+      (seconds.to_f * 1000).round.clamp(0, MAX_STATED_MILLISECONDS)
+    end
+
+    # One exchange, bounded on every axis a server controls.
+    def exchange(target, request)
+      http = Net::HTTP.new(target.host, target.port)
+      http.use_ssl = target.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout
+
+      # `Net::HTTP#request` answers the response rather than what the block it was given answered,
+      # so what the block worked out is kept here instead of returned through it.
+      answered = nil
+      http.start do |session|
+        session.request(request) do |answer|
+          answered = [answer.code.to_i, carried(answer), bounded(answer)]
+        end
+      end
+      answered
+    rescue TransportError
+      raise
+    rescue *UNREACHABLE => e
+      raise TransportError.no_answer(e.message)
+    end
+
+    # What an answer carried beside its body, under the names a caller looks them up by.
+    #
+    # Refused before the body is read, so an abusive head costs one pass over what `Net::HTTP` has
+    # already buffered rather than that plus a megabyte-scale body on top.
+    def carried(answer)
+      held = 0
+      whole = 0
+      answer.each_header.to_h do |name, value|
+        held += 1
+        if held > @max_response_headers
+          raise TransportError.answer_above_a_bound(
+            "the API answered more than the #{@max_response_headers} header lines read at most"
+          )
+        end
+
+        line = name.to_s.bytesize + value.to_s.bytesize
+        if line > @max_header_bytes
+          raise TransportError.answer_above_a_bound(
+            "the API answered a `#{name.to_s.downcase}` header above the #{@max_header_bytes} bytes read at most"
+          )
+        end
+
+        whole += line
+        if whole > @max_head_bytes
+          raise TransportError.answer_above_a_bound(
+            "the API answered a head above the #{@max_head_bytes} bytes read at most"
+          )
+        end
+
+        [name.downcase, value.to_s.strip]
+      end
+    end
+
+    # The body of an answer, up to what this transport agrees to hold.
+    def bounded(answer)
+      payload = +""
+      answer.read_body do |chunk|
+        payload << chunk
+        if payload.bytesize > @max_response_bytes
+          raise TransportError.answer_above_a_bound(
+            "the API answered more than the #{@max_response_bytes} bytes read at most"
+          )
+        end
+      end
+      payload
+    end
+  end
+end

data/lib/hook0/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Hook0
+  # What this gem is released as, which the gemspec reads rather than repeats.
+  VERSION = "2.0.0"
+end

data/lib/hook0.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "hook0/version"
+require_relative "hook0/errors"
+require_relative "hook0/runtime"
+require_relative "hook0/transport"
+require_relative "hook0/signature"
+require_relative "hook0/client"
+require_relative "hook0/generated/all"
+
+# The Ruby SDK for Hook0.
+#
+# Two halves live here. This one is hand-written: sending an event, upserting the event types an
+# application uses, and verifying that a webhook came from Hook0 unchanged. The other is generated
+# from the OpenAPI snapshot the API commits — one class per schema it declares, one exception per
+# problem it can report, one method per operation — and is reached through {Hook0::Generated}, over
+# the transport this half exports.
+#
+# The gem reaches the network, verifies signatures and decodes what the API answers with the
+# standard library alone, so installing it never drags a transitive dependency into an application
+# that only wanted to send an event.
+module Hook0
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: hook0-client
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- David Sferruzza
+- François-Guillaume Ribreau
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.89'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.89'
+description: |
+  Send events to Hook0, upsert the event types your application uses, verify the signature of an
+  incoming webhook, and call every operation the API declares through generated, documented
+  classes. Sending is idempotent and retried under bounds the caller sets.
+email:
+- david@hook0.com
+- fg@hook0.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- assets/ruby-flow.svg
+- lib/hook0.rb
+- lib/hook0/client.rb
+- lib/hook0/errors.rb
+- lib/hook0/generated/all.rb
+- lib/hook0/generated/api.rb
+- lib/hook0/generated/errors.rb
+- lib/hook0/generated/models.rb
+- lib/hook0/runtime.rb
+- lib/hook0/signature.rb
+- lib/hook0/transport.rb
+- lib/hook0/version.rb
+homepage: https://www.hook0.com/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.hook0.com/
+  documentation_uri: https://documentation.hook0.com/
+  source_code_uri: https://gitlab.com/hook0/hook0
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby SDK for Hook0, open-source Webhooks as a service for SaaS
+test_files: []