calmlens 0.1.0

data/lib/calmlens/response.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # An HTTP response. {CDN#serve} returns one; custom transports and the mock produce them.
+  #
+  # The body is read at most once: either stream it with {#each_chunk} or read it with {#body}.
+  class Response
+    # @return [Integer] the HTTP status code.
+    attr_reader :status
+    # @return [Hash{String => String}] headers with lowercase names.
+    attr_reader :headers
+
+    # @param status [Integer]
+    # @param headers [Hash{String => String}]
+    # @param body [String, nil] a complete body. Give a block instead to stream chunks.
+    # @yield [chunk] a block that yields each body chunk to its block argument.
+    def initialize(status:, headers: {}, body: nil, &reader)
+      @status = Integer(status)
+      @headers = headers.to_h { |name, value| [name.to_s.downcase, value.is_a?(Array) ? value.join(', ') : value.to_s] }.freeze
+      @body = body&.b
+      @reader = reader
+      @consumed = false
+    end
+
+    # @return [String, nil] the `X-Request-Id` header.
+    def request_id = headers['x-request-id']
+    # @return [String, nil] the `Content-Type` header.
+    def content_type = headers['content-type']
+
+    # @return [Integer, nil] the `Content-Length` header.
+    def content_length
+      Integer(headers['content-length'], 10, exception: false)
+    end
+
+    # @return [Boolean] true for a 2xx status.
+    def success? = status.between?(200, 299)
+
+    # Streams the body in chunks without holding it in memory.
+    # @yieldparam chunk [String] binary bytes
+    # @return [void]
+    def each_chunk(&block)
+      return enum_for(:each_chunk) unless block
+
+      if @body
+        block.call(@body) unless @body.empty?
+      else
+        raise InvalidArgumentError.new(SdkErrorCodes::INVALID_ARGUMENT, 'The response body was already read') if @consumed
+
+        @reader&.call(&block)
+      end
+      @consumed = true
+      nil
+    end
+
+    # Reads the whole body into memory.
+    # @param limit [Integer, nil] maximum bytes; a longer body raises {InvalidResponseError}.
+    # @return [String] binary bytes
+    def body(limit: nil)
+      if @body
+        too_large!(limit) if limit && @body.bytesize > limit
+        return @body
+      end
+
+      buffer = String.new(capacity: [content_length || 0, 1 << 20].min, encoding: Encoding::BINARY)
+      each_chunk do |chunk|
+        buffer << chunk
+        too_large!(limit) if limit && buffer.bytesize > limit
+      end
+      @body = buffer
+    end
+
+    # @return [String]
+    def inspect = "#<#{self.class.name} status=#{status} content_type=#{content_type.inspect}>"
+
+    private
+
+    def too_large!(limit)
+      raise InvalidResponseError.new(SdkErrorCodes::RESPONSE_TOO_LARGE, "Response body exceeds #{limit} bytes",
+                                     headers: headers)
+    end
+  end
+end

data/lib/calmlens/server_client.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module CalmLens
+  # The CalmLens API client. Create one per process (or per project) and reuse it: it keeps
+  # keep-alive connections, is safe to share between threads, and reconnects after `fork`.
+  #
+  # @example
+  #   client = CalmLens::ServerClient.new(api_key: ENV.fetch('CALMLENS_API_KEY'),
+  #                                 project_id: ENV.fetch('CALMLENS_PROJECT_ID'))
+  #   asset = client.text.moderate(text: 'Hello world')
+  #   client.close
+  class ServerClient
+    DEFAULT_BASE_URL = 'https://api.calmlens.com/v1'
+    DEFAULT_CDN_BASE_URL = 'https://cdn.calmlens.com/v1'
+
+    # @return [Assets]
+    attr_reader :assets
+    # @return [Folders]
+    attr_reader :folders
+    # @return [Text]
+    attr_reader :text
+    # @return [UploadTokens]
+    attr_reader :upload_tokens
+    # @return [Events]
+    attr_reader :events
+    # @return [CDN]
+    attr_reader :cdn
+
+    # @param api_key [String] a project API key. Keep it on your server.
+    # @param project_id [String]
+    # @param base_url [String] the API base URL.
+    # @param cdn_base_url [String] the CDN base URL.
+    # @param timeout [Numeric] seconds allowed for each socket read or write, including waiting for a
+    #   moderation decision. It is not a deadline for a whole transfer, so large uploads and downloads
+    #   are not cut off. Override per call with `request_options: {timeout:}`.
+    # @param open_timeout [Numeric] seconds allowed to open a connection.
+    # @param max_retries [Integer] retries of requests that are safe to repeat: GET/HEAD, and uploads,
+    #   which carry an `Idempotency-Key`. Connection failures, timeouts, 429, 502, 503, 504 and
+    #   `idempotency/request-in-progress` are retried with jittered exponential backoff, honouring
+    #   `Retry-After`. Other writes are never retried. 0 disables retries.
+    # @param retry_base_delay [Numeric] seconds before the first retry when the API gives no
+    #   `Retry-After`; later retries wait up to twice as long each time, at most 8 seconds.
+    # @param transport [#call, nil] a custom {Transport}; defaults to {Transport::NetHTTP}.
+    # @raise [ConfigurationError] `sdk/invalid-config` for a missing or malformed setting.
+    def initialize(api_key:, project_id:, base_url: DEFAULT_BASE_URL, cdn_base_url: DEFAULT_CDN_BASE_URL,
+                   timeout: 120, open_timeout: 10, max_retries: 2, retry_base_delay: 0.5, transport: nil)
+      check_config(api_key, project_id, timeout, open_timeout, max_retries, retry_base_delay, transport)
+      @project_id = project_id
+      @base_url = ServerClient.check_url(base_url, 'base_url')
+      @cdn_base_url = ServerClient.check_url(cdn_base_url, 'cdn_base_url')
+      @session = Session.new(api_key: api_key, project_id: project_id, base_url: @base_url,
+                             cdn_base_url: @cdn_base_url, timeout: timeout, open_timeout: open_timeout,
+                             max_retries: max_retries, retry_base_delay: retry_base_delay,
+                             transport: transport || Transport::NetHTTP.new)
+      @assets = Assets.new(@session)
+      @folders = Folders.new(@session)
+      @text = Text.new(@session, @assets)
+      @upload_tokens = UploadTokens.new(@session, api_key)
+      @events = Events.new(@session)
+      @cdn = CDN.new(@session)
+      @lenses = Lenses.new(@session)
+    end
+
+    # @return [String]
+    attr_reader :project_id
+    # @return [String] the API base URL, without a trailing slash.
+    attr_reader :base_url
+    # @return [String] the CDN base URL, without a trailing slash.
+    attr_reader :cdn_base_url
+
+    # Never shows the API key, including in resource objects that reference the client.
+    def inspect = "#<#{self.class.name} project_id=#{@project_id.inspect} base_url=#{@base_url.inspect} api_key=[REDACTED]>"
+
+    def pretty_print(printer) = printer.text(inspect)
+
+    # Closes pooled connections. Requests made afterwards fail with `sdk/transport-error`.
+    # @return [void]
+    def close
+      @session.close
+      nil
+    end
+
+    # Creates or updates named lenses (saved transform pipelines) and returns them. Definitions
+    # this client already saved are not sent again. Supplying the same definition and version is
+    # idempotent; changing a lens needs a higher `version`. More than 100 new definitions are sent in
+    # consecutive requests, in order.
+    # @option options [Array<Hash>] :lenses `[{identifier:, name:, type:, version:, transforms:, ...}]`
+    # @return [Array<Hash>] the saved lenses, in the given order.
+    def ensure_lenses(options) = @lenses.ensure_lenses(options)
+
+    # Creates or updates one lens. Takes one lens definition; see {#ensure_lenses}.
+    # @return [Hash] the saved lens
+    def ensure_lens(options) = @lenses.ensure_lens(options)
+
+    # @api private
+    def self.check_url(value, name)
+      uri = URI.parse(value.to_s)
+      unless %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty? && uri.userinfo.nil? &&
+             uri.query.nil? && uri.fragment.nil?
+        raise ConfigurationError.new(SdkErrorCodes::INVALID_CONFIG,
+                                     "#{name} must be an http(s) URL without credentials, query or fragment")
+      end
+
+      value.to_s.sub(%r{/+\z}, '')
+    rescue URI::Error
+      raise ConfigurationError.new(SdkErrorCodes::INVALID_CONFIG, "#{name} is not a valid URL")
+    end
+
+    private
+
+    def check_config(api_key, project_id, timeout, open_timeout, max_retries, retry_base_delay, transport)
+      unless api_key.is_a?(String) && !api_key.empty? && api_key.match?(/\A[\x21-\x7e]+\z/)
+        raise ConfigurationError.new(SdkErrorCodes::INVALID_CONFIG, 'api_key must be a non-empty printable ASCII String')
+      end
+      unless project_id.is_a?(String) && !project_id.empty? && !%w[. ..].include?(project_id)
+        raise ConfigurationError.new(SdkErrorCodes::INVALID_CONFIG, 'project_id is required')
+      end
+      unless Internal.positive?(timeout) && Internal.positive?(open_timeout)
+        raise ConfigurationError.new(SdkErrorCodes::INVALID_CONFIG, 'timeout and open_timeout must be positive numbers of seconds')
+      end
+      unless max_retries.is_a?(Integer) && max_retries >= 0
+        raise ConfigurationError.new(SdkErrorCodes::INVALID_CONFIG, 'max_retries must be a non-negative Integer')
+      end
+      unless retry_base_delay.is_a?(Numeric) && retry_base_delay.real? && retry_base_delay.to_f.finite? && retry_base_delay >= 0
+        raise ConfigurationError.new(SdkErrorCodes::INVALID_CONFIG, 'retry_base_delay must be a non-negative number')
+      end
+      return if transport.nil? || transport.respond_to?(:call)
+
+      raise ConfigurationError.new(SdkErrorCodes::INVALID_CONFIG, 'transport must respond to call')
+    end
+  end
+end

data/lib/calmlens/session.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'timeout'
+require 'uri'
+
+module CalmLens
+  # Sends API and CDN requests: authentication, JSON encoding, retries and error mapping.
+  # The resources share one session per client. It never prints the API key.
+  # @api private
+  class Session
+    MAX_JSON_BYTES = 32 * 1024 * 1024
+    MAX_ERROR_BYTES = 1024 * 1024
+    MAX_RETRY_DELAY = 60
+    MAX_BACKOFF = 8
+    ENSURE_LENSES_MAX_PER_REQUEST = 100
+    USER_AGENT = "calmlens-ruby/#{VERSION} (ruby #{RUBY_VERSION})".freeze
+
+    # Raised through the transport so an exception from the caller's streaming block is
+    # re-raised unchanged instead of being mistaken for a network failure.
+    class CallerError < Exception # rubocop:disable Lint/InheritException
+      attr_reader :error
+
+      def initialize(error)
+        super(error.message)
+        @error = error
+      end
+    end
+
+    attr_reader :project_id, :base_url, :cdn_base_url
+
+    def initialize(api_key:, project_id:, base_url:, cdn_base_url:, timeout:, open_timeout:, max_retries:,
+                   retry_base_delay:, transport:)
+      @api_key = api_key
+      @project_id = project_id
+      @base_url = base_url
+      @cdn_base_url = cdn_base_url
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @max_retries = max_retries
+      @retry_base_delay = retry_base_delay
+      @transport = transport
+      @lenses = {}
+      @lens_lock = Mutex.new
+    end
+
+    def inspect = "#<#{self.class.name} project_id=#{@project_id.inspect} api_key=[REDACTED]>"
+
+    def close
+      @transport.close if @transport.respond_to?(:close)
+    end
+
+    def project(path) = "/projects/#{Internal.segment(@project_id)}/#{path}"
+
+    # Sends an API request and returns the parsed JSON body.
+    #
+    # @param idempotent [Boolean] send an `Idempotency-Key` (generated unless the caller gave one),
+    #   reused across retries so the API runs the request at most once.
+    def request(method, path, request_options:, query: {}, body: nil, raw: nil, headers: {}, idempotent: false)
+      url = @base_url + path
+      params = Internal.query(query)
+      url += "?#{URI.encode_www_form(params)}" unless params.empty?
+      headers = headers.merge('Accept' => 'application/json')
+      unless body.nil?
+        raw = JSON.generate(body)
+        headers['Content-Type'] = 'application/json'
+      end
+      if raw.is_a?(UploadBody)
+        headers['Content-Length'] = raw.size.to_s
+      elsif raw
+        raw = UploadBody.new(raw)
+      end
+      headers['Idempotency-Key'] = request_options[:idempotency_key] || SecureRandom.uuid if idempotent || request_options[:idempotency_key]
+      execute(method, url, headers, raw, request_options) { |response| parse(response) }
+    end
+
+    # Sends a CDN request. With a block, yields the streaming {Response} and returns the block's
+    # value; otherwise returns the response with its body read.
+    def cdn(method, url, headers, request_options, &block)
+      execute(method, url, headers, nil, request_options, stream: !block.nil?) do |response|
+        next response.tap(&:body) unless block
+
+        streaming = Response.new(status: response.status, headers: response.headers) do |&sink|
+          response.each_chunk do |chunk|
+            sink.call(chunk)
+          rescue StandardError => e
+            raise CallerError, e
+          end
+        end
+        begin
+          block.call(streaming)
+        rescue CallerError
+          raise
+        rescue StandardError => e
+          raise CallerError, e
+        end
+      end
+    end
+
+    # Resolves lens definitions, sending only definitions this client has not saved before, at most
+    # ENSURE_LENSES_MAX_PER_REQUEST per request, in order.
+    def ensure_lenses(lenses, request_options)
+      if !lenses.is_a?(Array) || lenses.empty? || lenses.any? { |lens| !lens.is_a?(Hash) || lens['identifier'].to_s.empty? }
+        raise Internal.invalid('At least one lens with an identifier is required')
+      end
+
+      @lens_lock.synchronize do
+        keys = lenses.map { |lens| JSON.generate(lens.sort.to_h) }
+        missing = keys.zip(lenses).to_h.reject { |key, _| @lenses.key?(key) }
+        resolved = @lenses.dup
+        missing.each_slice(ENSURE_LENSES_MAX_PER_REQUEST) do |slice|
+          chunk = slice.to_h
+          returned = request('PUT', project('lenses'), body: { 'lenses' => chunk.values },
+                                                       request_options: request_options)
+          returned = returned['lenses'] if returned.is_a?(Hash)
+          unless lenses_match?(returned, chunk.values)
+            raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'Unexpected lens response')
+          end
+
+          resolved.merge!(chunk.keys.zip(returned).to_h)
+          # A new version of a lens replaces the cached definition with the same identifier.
+          chunk.keys.zip(returned).each do |key, lens|
+            @lenses.delete_if { |_, saved| saved['identifier'] == lens['identifier'] }
+            @lenses[key] = lens
+          end
+        end
+        JSON.parse(JSON.generate(keys.map { |key| resolved.fetch(key) }))
+      end
+    end
+
+    # Whether the saved lenses line up, one for one and in order, with the definitions that were sent.
+    def lenses_match?(returned, sent)
+      returned.is_a?(Array) && returned.size == sent.size &&
+        returned.zip(sent).all? { |saved, definition| saved.is_a?(Hash) && saved['identifier'] == definition['identifier'] }
+    end
+
+    def headers_for(extra)
+      extra.reject { |name, _| %w[x-api-key user-agent].include?(name.downcase) }
+           .merge('X-Api-Key' => @api_key, 'User-Agent' => USER_AGENT)
+    end
+
+    private
+
+    def execute(method, url, headers, body, request_options, stream: false, &handler)
+      retries = request_options.fetch(:max_retries, @max_retries)
+      retry_allowed = %w[GET HEAD].include?(method) || headers.key?('Idempotency-Key')
+      request = Transport::Request.new(method: method, url: url, headers: headers_for(headers), body: body&.content,
+                                       open_timeout: request_options.fetch(:open_timeout, @open_timeout),
+                                       timeout: request_options.fetch(:timeout, @timeout))
+      attempt = 0
+      begin
+        body&.rewind if attempt.positive?
+        delivered = false
+        send_request(request) do |response|
+          delivered = true if stream
+          handler.call(response)
+        end
+      rescue Error => e
+        raise unless retry_allowed && !delivered && attempt < retries && e.retryable? && (body.nil? || body.replayable?)
+
+        delay = retry_delay(attempt, e.retry_after)
+        raise if delay.nil?
+
+        sleep(delay)
+        attempt += 1
+        retry
+      end
+    end
+
+    def send_request(request, &handler)
+      yielded = false
+      result = nil
+      returned = @transport.call(request) do |response|
+        yielded = true
+        result = handler.call(response)
+      end
+      if yielded
+        result
+      else
+        handler.call(returned.is_a?(Response) ? returned : adapt(returned))
+      end
+    rescue CallerError => e
+      raise e.error
+    rescue Error
+      raise
+    rescue ::Timeout::Error => e
+      raise TimeoutError.new(SdkErrorCodes::TIMEOUT, e.message), cause: e
+    rescue *Transport::ERRORS => e
+      raise ConnectionError.new(SdkErrorCodes::TRANSPORT_ERROR, e.message), cause: e
+    rescue ArgumentError, URI::Error => e
+      raise InvalidArgumentError.new(SdkErrorCodes::INVALID_ARGUMENT, e.message), cause: e
+    end
+
+    # Accepts any response object with a status (or code), headers and body.
+    def adapt(value)
+      raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'The transport returned no response') if value.nil?
+
+      status = value.respond_to?(:status) ? value.status : value.code
+      headers = value.respond_to?(:to_hash) ? value.to_hash : (value.respond_to?(:headers) && value.headers) || {}
+      Response.new(status: status, headers: headers, body: value.body.to_s)
+    end
+
+    def retry_delay(attempt, retry_after)
+      return (retry_after <= MAX_RETRY_DELAY ? retry_after : nil) if retry_after
+
+      rand * [@retry_base_delay * (2**attempt), MAX_BACKOFF].min
+    end
+
+    def parse(response)
+      text = response.body(limit: response.success? ? MAX_JSON_BYTES : MAX_ERROR_BYTES).dup.force_encoding(Encoding::UTF_8)
+      begin
+        data = text.empty? ? nil : JSON.parse(text)
+      rescue JSON::ParserError
+        raise invalid_body(response) if response.success?
+
+        data = nil
+      end
+      return data if response.success?
+
+      raise api_error(response, data)
+    rescue InvalidResponseError
+      raise if response.success?
+
+      raise api_error(response, nil)
+    end
+
+    def invalid_body(response)
+      InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, "Invalid JSON response (HTTP #{response.status})",
+                               headers: response.headers)
+    end
+
+    def api_error(response, data)
+      unless data.is_a?(Hash) && data['code'].is_a?(String)
+        return Error.build(SdkErrorCodes::HTTP_ERROR, "HTTP #{response.status}", status: response.status,
+                                                                                 headers: response.headers)
+      end
+
+      details = (data['details'].is_a?(Hash) ? data['details'] : {}).merge('network' => true)
+      details['traceId'] = data['traceId'] if data.key?('traceId')
+      Error.build(data['code'], data['message'].is_a?(String) ? data['message'] : nil,
+                  status: response.status, details: details, headers: response.headers)
+    end
+  end
+  private_constant :Session
+end