lingara 0.1.0.pre.alpha.6

data/lib/lingara/deprecation.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "time"
+require "uri"
+
+module Lingara
+  # A Link header: its raw value, and its target resolved against the
+  # request URL (RFC 8288 §3.2), or nil when it has none.
+  DeprecationLink = Struct.new(:raw, :target)
+
+  # What a response under a deprecated version says about it (K2). An
+  # unparseable header leaves its parsed field nil, never an error.
+  # +deprecated_at+ and +sunset_at+ are Times; +headers+ are the raw
+  # Deprecation, Sunset and Link values.
+  DeprecationNotice = Struct.new(:version, :deprecated_at, :sunset_at, :link, :headers) do
+    # The notice for a response, or nil when it carries no Deprecation.
+    def self.from(response, request_url)
+      raw = response["Deprecation"]
+      return nil if raw.nil? || raw.strip.empty?
+      sunset = response["Sunset"]
+      link = response["Link"]
+      new(
+        version: response["Lingara-Version"],
+        deprecated_at: parse_deprecation(raw),
+        sunset_at: parse_sunset(sunset),
+        link: link && parse_link(link, request_url),
+        headers: {"Deprecation" => raw, "Sunset" => sunset, "Link" => link}.compact
+      )
+    end
+
+    def self.parse_deprecation(value)
+      digits = value.strip.delete_prefix("@")
+      return nil unless value.strip.start_with?("@") && digits.match?(/\A-?\d+\z/)
+      Time.at(digits.to_i).utc
+    end
+
+    # An IMF-fixdate only: Time.httpdate also reads the two obsolete formats,
+    # which Sunset does not allow.
+    def self.parse_sunset(value)
+      return nil if value.nil?
+      text = value.strip
+      return nil unless text.match?(/\A[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT\z/)
+      Time.httpdate(text)
+    rescue ArgumentError
+      nil
+    end
+
+    def self.parse_link(raw, request_url)
+      target = raw.strip[/\A<([^>]*)>/, 1]
+      resolved = target && URI.join(request_url, target)
+      DeprecationLink.new(raw: raw, target: resolved)
+    rescue URI::Error
+      DeprecationLink.new(raw: raw, target: nil)
+    end
+  end
+
+  # The default logger: #warn goes through Kernel#warn with no category, so
+  # it reaches Warning.warn and $stderr by default and `ruby -W0` silences
+  # it; #debug writes only under $DEBUG. Any object with #warn and #debug,
+  # such as Rails.logger, replaces it.
+  class DefaultLogger
+    def warn(message)
+      Kernel.warn(message)
+    end
+
+    def debug(message)
+      Kernel.warn(message) if $DEBUG
+    end
+  end
+
+  # Per client: reads the served version off each response and reports a
+  # deprecation once per response, to the hook or, with no hook, as one
+  # warning per version id. Separately, it warns once per served id that is
+  # not the version the models were generated from (ADR 30.9.26a §4).
+  class VersionObserver
+    def initialize(hook:, logger:)
+      @hook = hook
+      @logger = logger
+      @mutex = Mutex.new
+      @warned = {}
+      # Its own set: sharing @warned would let a version that is both
+      # deprecated and mismatched warn only once in total.
+      @mismatched = {}
+    end
+
+    # The Lingara-Version echo, or nil, after reporting any deprecation or
+    # mismatch.
+    def observe(response, request_url)
+      notice = DeprecationNotice.from(response, request_url)
+      report(notice) if notice
+      served = response["Lingara-Version"]
+      served = nil if served && served.empty?
+      check_generated(served) if served
+      served
+    end
+
+    private
+
+    def report(notice)
+      return warn_deprecated(notice) unless @hook
+      begin
+        @hook.call(notice)
+      rescue => e
+        @logger.debug("the Lingara deprecation hook raised #{e.class}; the call continues")
+      end
+    end
+
+    def warn_deprecated(notice)
+      # An absent echo counts as one id.
+      return unless first_time?(@warned, notice.version.to_s)
+      sunset = notice.headers["Sunset"] ? "; sunset #{notice.headers["Sunset"]}" : ""
+      @logger.warn("Lingara API version #{notice.version || "(unnamed)"} is deprecated#{sunset}. See GET /v1/versions.")
+    end
+
+    def check_generated(served)
+      return if served == GENERATED_FOR_VERSION || !first_time?(@mismatched, served)
+      @logger.warn("Lingara API version #{served} served this response, but this library's models were generated for " \
+        "#{GENERATED_FOR_VERSION}; response shapes may differ. Pin the OAuth client to #{GENERATED_FOR_VERSION} or upgrade the library.")
+    end
+
+    def first_time?(seen, id)
+      @mutex.synchronize do
+        next false if seen[id]
+        seen[id] = true
+      end
+    end
+  end
+end

data/lib/lingara/errors.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lingara
+  # K3: one error family (CONTRACT.md K3). Every failure a call raises, a
+  # caller's own interrupt aside, is one of the four subclasses below, so one
+  # `rescue Lingara::Error` handles them all.
+  class Error < StandardError
+    # The fields a subclass renders in #inspect, never a secret.
+    def inspect
+      fields = self.class::FIELDS.map { |name| "#{name}=#{public_send(name).inspect}" }
+      "#<#{self.class.name} #{fields.join(" ")}>"
+    end
+
+    alias_method :pretty_print_inspect, :inspect
+
+    def pretty_print(q)
+      q.text(inspect)
+    end
+  end
+
+  # A /v1 refusal, or a stream's error event (then +status+ is 200).
+  class ApiError < Error
+    FIELDS = %i[status code message retry_after plan_id served_version].freeze
+
+    attr_reader :status, :code, :retry_after, :plan_id, :served_version
+
+    def initialize(status:, code:, message:, retry_after: nil, plan_id: nil, served_version: nil)
+      @status = status
+      @code = code
+      @retry_after = retry_after
+      @plan_id = plan_id
+      @served_version = served_version
+      super("#{code}: #{message} (HTTP #{status})")
+      @detail = message
+    end
+
+    # The envelope's `error`, or the event's `message`. #to_s keeps the code
+    # and the status beside it.
+    def message
+      @detail || super
+    end
+  end
+
+  # A token-endpoint refusal: RFC 6749 §5.2, or `http_<status>`.
+  class OAuthError < Error
+    FIELDS = %i[status error description retry_after].freeze
+
+    attr_reader :status, :error, :description, :retry_after
+
+    def initialize(status:, error:, description: nil, retry_after: nil)
+      @status = status
+      @error = error
+      @description = description
+      @retry_after = retry_after
+      super(description ? "token endpoint: #{error}: #{description} (HTTP #{status})" : "token endpoint: #{error} (HTTP #{status})")
+    end
+  end
+
+  # A 503 whose body is not JSON: the service is in maintenance.
+  class MaintenanceError < Error
+    FIELDS = %i[body retry_after].freeze
+
+    attr_reader :body, :retry_after
+
+    def initialize(body:, retry_after: nil)
+      @body = body
+      @retry_after = retry_after
+      super("the API is under maintenance")
+    end
+  end
+
+  # A call with no usable HTTP answer. +kind+ is one of KINDS; +cause+ is the
+  # underlying failure, scrubbed when its text named a credential.
+  class TransportError < Error
+    FIELDS = %i[kind].freeze
+    KINDS = %i[connect tls reset timeout stream_ended_early malformed_response malformed_event].freeze
+
+    attr_reader :kind
+
+    def initialize(kind, detail = nil)
+      raise ArgumentError, "unknown transport kind #{kind.inspect}" unless KINDS.include?(kind)
+      @kind = kind
+      super(detail ? "transport failure: #{kind}: #{detail}" : "transport failure: #{kind}")
+    end
+  end
+
+  # Stands in for an underlying error whose text named a credential, as the
+  # +cause+ of the TransportError that replaces it.
+  class ScrubbedCause < StandardError
+    def initialize
+      super("the underlying error was withheld: it contained a credential")
+    end
+  end
+
+  # Response → error, in C2 D4's precedence.
+  module Refusal
+    MAINTENANCE_BODY_BYTES = 1024
+
+    module_function
+
+    # A non-2xx response to its K3 class. +endpoint+ is :v1 or :token; +now+
+    # reads an HTTP-date Retry-After.
+    def error(endpoint, response, body, now)
+      status = response.code.to_i
+      retry_after = RetryPolicy.parse_retry_after(response["Retry-After"], now)
+      if status == 503 && !json?(response)
+        return MaintenanceError.new(body: truncate(body.to_s, MAINTENANCE_BODY_BYTES), retry_after: retry_after)
+      end
+      fields = parse_object(body)
+      if endpoint == :token
+        return oauth_error(status, fields, retry_after)
+      end
+      api_error(status, fields, retry_after, response["Lingara-Version"])
+    end
+
+    def oauth_error(status, fields, retry_after)
+      code = fields["error"]
+      if code.is_a?(String)
+        description = fields["error_description"]
+        OAuthError.new(status: status, error: code, description: description.is_a?(String) ? description : nil, retry_after: retry_after)
+      else
+        OAuthError.new(status: status, error: "http_#{status}", retry_after: retry_after)
+      end
+    end
+
+    def api_error(status, fields, retry_after, served_version)
+      code = fields["code"]
+      message = fields["error"]
+      unless code.is_a?(String) && message.is_a?(String)
+        code = "http_#{status}"
+        message = "HTTP #{status}"
+      end
+      ApiError.new(status: status, code: code, message: message, retry_after: retry_after, served_version: served_version)
+    end
+
+    def parse_object(body)
+      value = JSON.parse(body.to_s)
+      value.is_a?(Hash) ? value : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    # The Content-Type's media type, parameters dropped and lower-cased.
+    def media_type(response)
+      response["Content-Type"].to_s.split(";").first.to_s.strip.downcase
+    end
+
+    def json?(response)
+      media = media_type(response)
+      media == "application/json" || media.end_with?("+json")
+    end
+
+    # At most +max+ bytes, cut on a character boundary.
+    def truncate(text, max)
+      text = text.dup.force_encoding(Encoding::UTF_8)
+      return text if text.bytesize <= max
+      text.byteslice(0, max).scrub("")
+    end
+  end
+end

data/lib/lingara/event_stream.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lingara
+  # K5: one stream of events (CONTRACT.md K5; D3).
+  #
+  # A stream call with a block sends at once, yields each event and returns a
+  # StreamResult. Without one it returns an EventStream, which sends nothing
+  # until its first #each or #next, and is single-use: a second #each raises
+  # IOError, as reading a closed IO does. Leaving the block by any path, or
+  # #close, closes the socket. The terminal table is the view's, generated
+  # into operations.rb (ADR 29.9.26ai): :raise, :quiet and :yield.
+  class EventStream
+    include Enumerable
+
+    # The Lingara-Version echo, or nil; nil until the first #each or #next.
+    attr_reader :served_version
+
+    # +pipeline+ is the client's: it sends the request, with its token, 401
+    # and Retry-After retries, and yields the 2xx response.
+    def initialize(pipeline:, operation:, url:, body:)
+      @pipeline = pipeline
+      @operation = operation
+      @url = url
+      @body = body
+      @mutex = Mutex.new
+      @consumed = false
+      @http = nil
+      @external = nil
+      @served_version = nil
+    end
+
+    # Yields each event, then returns self. Without a block, an Enumerator.
+    def each(&block)
+      return enum_for(:each) unless block
+      claim!
+      run(&block)
+      self
+    end
+
+    # External iteration: the next event, or StopIteration after the last.
+    # The socket stays open between calls, so call #close when done early.
+    def next
+      @mutex.synchronize do
+        unless @external
+          raise IOError, "stream already consumed" if @consumed
+          @consumed = true
+          @external = Enumerator.new { |y| run { |event| y << event } }
+        end
+      end
+      @external.next
+    end
+
+    # Closes the socket if a request is open, and marks the stream consumed.
+    # Idempotent. An abandoned enumerator fiber never runs its ensure, so this
+    # finishes the Net::HTTP session itself rather than relying on one.
+    def close
+      http = nil
+      @mutex.synchronize do
+        @consumed = true
+        @external = nil
+        http, @http = @http, nil
+      end
+      http.finish if http&.started?
+      nil
+    rescue IOError
+      nil
+    end
+
+    # Sends the request and yields each event; returns the StreamResult.
+    # Used directly by the block form of a stream call.
+    def run(&block)
+      @pipeline.call(@operation, @url, @body, on_start: ->(http) { @http = http }) do |response, phase, observe|
+        consume(response, phase, observe, &block)
+      end
+    end
+
+    private
+
+    def claim!
+      @mutex.synchronize do
+        raise IOError, "stream already consumed" if @consumed
+        @consumed = true
+      end
+    end
+
+    def consume(response, phase, observe, &block)
+      unless Refusal.media_type(response) == "text/event-stream"
+        raise TransportError.new(:malformed_response, "a 200 stream answered #{Refusal.media_type(response).inspect}")
+      end
+      # The deprecation hook runs after the headers, before the first event.
+      @served_version = observe.call(response)
+      phase.event_stream = true
+      decoder = SSEDecoder.new
+      response.read_body do |chunk|
+        decoder.feed(chunk).each { |frame| handle(frame, phase, &block) }
+      end
+      raise TransportError.new(:stream_ended_early, "the stream closed before its terminal event")
+    end
+
+    def handle(frame, phase, &block)
+      stream = @operation[:stream]
+      return unless stream[:events].key?(frame.event)
+      ending = stream[:ends][frame.event]
+      raise stream_error(frame.data) if ending == :raise
+      return finish(phase, frame) if ending == :quiet
+      event = Lingara.const_get(stream[:union]).decode(frame.event, frame.data)
+      return if event.nil?
+      phase.in_caller_block { block.call(event) }
+      phase.leave(StreamResult.new(served_version: @served_version)) if ending == :yield
+    end
+
+    # A Done payload: never yielded, but still the JSON it should be.
+    def finish(phase, frame)
+      JSON.parse(frame.data)
+      phase.leave(StreamResult.new(served_version: @served_version))
+    rescue JSON::ParserError
+      raise TransportError.new(:malformed_event, "#{frame.event}: data is not JSON")
+    end
+
+    # An error event: ApiError with status 200, never yielded or retried.
+    def stream_error(data)
+      fields = begin
+        parsed = JSON.parse(data)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+      text = ->(key, fallback) { fields[key].is_a?(String) ? fields[key] : fallback }
+      ApiError.new(status: 200, code: text.call("code", "stream_error"), message: text.call("message", "the stream reported an error"),
+        plan_id: text.call("plan_id", nil), served_version: @served_version)
+    end
+  end
+end