sillydev 1.0.0

data/lib/sillydev/client.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "uri"
+
+module SillyDev
+  # Client for the Silly Development API.
+  #
+  # api_key defaults to the SILLYDEV_API_KEY environment variable and base_url to SILLYDEV_BASE_URL
+  # or https://sillydev.co.uk/panel/api/client. Requests answered 429 are retried up to max_retries
+  # times, and reads answered 502, 503 or 504 too, waiting as long as Retry-After asks.
+  #
+  #   client = SillyDev::Client.new
+  #   client.panel.servers.list.each { |server| puts "#{server["identifier"]} #{server["name"]}" }
+  class Client
+    DEFAULT_BASE_URL = "https://sillydev.co.uk/panel/api/client"
+    DEFAULT_TIMEOUT = 60
+    DEFAULT_MAX_RETRIES = 2
+    RETRY_STATUSES = [429, 502, 503, 504].freeze
+    # A POST answered 502, 503 or 504 may still have reached the server: the node can have run the
+    # command or the power action before the gateway gave up. Only 429, which is refused before
+    # anything runs, is safe to retry for those, unless the request carries an Idempotency-Key
+    # the panel uses to recognise a repeat.
+    UNSAFE_RETRY_STATUSES = [429].freeze
+    SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+    MAX_RETRY_AFTER = 60.0
+
+    attr_reader :api_key, :base_url, :max_retries, :panel
+    # How the client waits between retries and checks; replaceable in tests.
+    attr_accessor :sleeper
+
+    def initialize(api_key = nil, base_url: nil, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES,
+                   default_headers: {}, transport: nil)
+      key = api_key || ENV.fetch("SILLYDEV_API_KEY", nil)
+      if key.nil? || key.empty?
+        raise Error, "No API key. Pass one to SillyDev::Client.new or set the SILLYDEV_API_KEY environment " \
+                     "variable. Create a key in the panel under Account, API keys."
+      end
+
+      @api_key = key
+      base = base_url || ENV.fetch("SILLYDEV_BASE_URL", nil)
+      base = DEFAULT_BASE_URL if base.nil? || base.empty?
+      @base_url = base.chomp("/")
+      @max_retries = [max_retries.to_i, 0].max
+      @default_headers = default_headers.to_h
+      @transport = transport || NetHTTPTransport.new(timeout: timeout)
+      @sleeper = ->(seconds) { sleep(seconds) }
+      @panel = Panel.new(self)
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+
+    # Quotes one path parameter so that a slash or space in it cannot change the route.
+    def self.segment(value)
+      value.to_s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |c| format("%%%02X", c.ord) }
+    end
+
+    # Sends one request and returns the unwrapped answer.
+    #
+    # json: is sent as a JSON body; content: as text (String) or binary (a String in
+    # Encoding::BINARY). raw: true skips unwrapping, text: true returns the body as a String.
+    def request(method, path, params: nil, json: :none, content: nil, headers: nil, raw: false, text: false)
+      method = method.to_s.upcase
+      attempt = 0
+      loop do
+        req = build(method, path, params, json, content, headers)
+        begin
+          response = @transport.call(req)
+        rescue ConnectFailed => e
+          if attempt < @max_retries
+            @sleeper.call(retry_delay(attempt, nil))
+            attempt += 1
+            next
+          end
+          raise APIConnectionError, "Could not reach #{@base_url}: #{e.message}"
+        rescue *Errors::TRANSPORT_ERRORS => e
+          raise APIConnectionError, "Could not reach #{@base_url}: #{e.message}"
+        end
+        if retry?(req, response, attempt)
+          @sleeper.call(retry_delay(attempt, response))
+          attempt += 1
+          next
+        end
+        return parse(response, raw: raw, text: text)
+      end
+    end
+
+    # One page of a paginated list.
+    def page(path, params = nil)
+      Page.from_response(request("GET", path, params: params, raw: true))
+    end
+
+    # Every item of a paginated list, fetching each page when it is reached.
+    def paginate(path, params = nil)
+      params = (params || {}).dup
+      first = (params.delete(:page) || params.delete("page") || 1).to_i
+      Enumerator.new do |yielder|
+        number = first
+        loop do
+          result = page(path, params.merge(page: number))
+          result.each { |item| yielder << item }
+          break unless result.next_page?
+
+          number = result.current_page + 1
+        end
+      end
+    end
+
+    private
+
+    def url(path)
+      return @base_url if path.nil? || path == "" || path == "/"
+
+      @base_url + (path.start_with?("/") ? path : "/#{path}")
+    end
+
+    def build(method, path, params, json, content, headers)
+      extra = (headers || {}).to_h { |k, v| [k.to_s, v.to_s] }
+      body = nil
+      if json != :none
+        body = JSON.generate(json)
+        extra["Content-Type"] ||= "application/json"
+      elsif !content.nil?
+        body = content
+        extra["Content-Type"] ||= content.encoding == Encoding::BINARY ? "application/octet-stream" : "text/plain"
+      end
+      full = url(path)
+      query = encode_params(params)
+      full += "?#{query}" unless query.empty?
+      Request.new(verb: method, url: full, headers: request_headers(extra), body: body)
+    end
+
+    def request_headers(extra)
+      {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "sillydev-ruby/#{VERSION}",
+      }.merge(@default_headers.to_h { |k, v| [k.to_s, v.to_s] }).merge(extra)
+    end
+
+    def encode_params(params)
+      pairs = (params || {}).filter_map do |key, value|
+        next if value.nil?
+
+        value = case value
+                # Laravel's boolean rule accepts 1 and 0 but not the strings "true" and "false".
+                when true then "1"
+                when false then "0"
+                when Array then value.join(",")
+                else value.to_s
+                end
+        [key.to_s, value]
+      end
+      URI.encode_www_form(pairs)
+    end
+
+    def retry?(request, response, attempt)
+      return false if attempt >= @max_retries
+
+      safe = SAFE_METHODS.include?(request.verb) || !request.header("Idempotency-Key").nil?
+      (safe ? RETRY_STATUSES : UNSAFE_RETRY_STATUSES).include?(response.status)
+    end
+
+    def retry_delay(attempt, response)
+      if response
+        retry_after = Errors.parse_retry_after(response.header("retry-after"))
+        return [retry_after, MAX_RETRY_AFTER].min unless retry_after.nil?
+      end
+      [0.5 * (2**attempt), 8.0].min * rand(0.75..1.25)
+    end
+
+    def parse(response, raw:, text:)
+      raise Errors.for_response(response) unless response.success?
+      return response.body.to_s if text
+      return nil if response.status == 204 || response.body.nil? || response.body.empty?
+
+      begin
+        body = JSON.parse(response.body)
+      rescue JSON::ParserError
+        return response.body
+      end
+      # Endpoints that answer 202 with an empty JSON array (reinstall, run a schedule).
+      return nil if body == []
+
+      raw ? body : Envelope.unwrap(body)
+    end
+  end
+
+  module Errors
+    # Failures after the connection was made: the request may have reached the panel, so they are
+    # not retried.
+    TRANSPORT_ERRORS = [
+      IOError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, Net::ProtocolError, EOFError
+    ].freeze
+  end
+end