5pm 0.1.0

data/lib/five_pm/response.rb

@@ -0,0 +1,212 @@
+require "json"
+
+module FivePM
+  # Resolve the JSON data wrapper against the operation's declared response part.
+  # This is a reader view only; callers retain the complete original wire JSON.
+  module Envelope
+    def self.parts(payload, contract)
+      raise ProtocolError, "expected a response object" unless payload.is_a?(Hash)
+
+      APIResult.check!(payload)
+      return payload unless payload.key?("data")
+
+      primary = contract.fetch("response").keys - ["sessionId"]
+      unless primary.length == 1 && primary.none? { |part| payload.key?(part) }
+        raise ProtocolError, "ambiguous response envelope"
+      end
+      if payload["success"].equal?(false) || payload["error"] || payload["errors"] || payload["fault"]
+        raise ProtocolError, "API returned an error envelope"
+      end
+
+      payload.merge(primary.first => payload.fetch("data"))
+    end
+  end
+
+  module Models
+    TYPES = JSON.parse(::File.read(::File.join(__dir__, "types.json")))
+
+    TYPES.each_value do |fields|
+      fields.each_value do |definition|
+        definition.each_value(&:freeze)
+        definition.freeze
+      end
+      fields.freeze
+    end
+    TYPES.freeze
+
+    # Models keep a frozen snapshot of the original JSON and expose typed readers.
+    # No fields are discarded, and date/time strings never acquire a guessed zone.
+    class Record
+      def initialize(payload, fields: self.class::FIELDS, reader_payload: nil)
+        raise ProtocolError, "expected a JSON object for #{self.class.name}" unless payload.is_a?(Hash)
+
+        @raw = snapshot(payload)
+        @values = (reader_payload ? snapshot(reader_payload) : @raw).to_h do |key, value|
+          definition = fields[key]
+          [key, definition ? convert_field(key, value, definition) : value]
+        rescue SchemaError
+          raise
+        rescue ProtocolError
+          raise SchemaError.new(field: key, expected_type: definition.fetch("type"), value: value), cause: nil
+        end.freeze
+        freeze
+      end
+
+      def [](key)
+        @values[key.to_s]
+      end
+
+      def key?(key)
+        @raw.key?(key.to_s)
+      end
+
+      def to_h
+        @raw
+      end
+      alias raw to_h
+
+      def to_json(*)
+        @raw.to_json(*)
+      end
+
+      # Never print payloads: User and AuthToken can contain secrets, and unknown
+      # fields may also hold sensitive data.
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      def convert_field(_key, value, definition)
+        convert(value, definition)
+      end
+
+      def snapshot(value)
+        case value
+        when Hash
+          value.to_h { |key, item| [key.dup.freeze, snapshot(item)] }.freeze
+        when Array
+          value.map { |item| snapshot(item) }.freeze
+        when String
+          value.dup.freeze
+        else
+          value
+        end
+      end
+
+      def convert(value, definition)
+        return nil if value.nil?
+        return scalar(value, definition.fetch("type")) unless definition.fetch("repeated", false)
+
+        raise ProtocolError, "expected an array for a repeated schema field" unless value.is_a?(Array)
+
+        value.map { |item| scalar(item, definition.fetch("type")) }.freeze
+      end
+
+      def numeric_value?(value)
+        value.is_a?(Numeric) ||
+          (value.is_a?(String) && /\A[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\z/.match?(value))
+      end
+
+      def boolean(value)
+        return value if value.equal?(true) || value.equal?(false)
+        return value == 1 if value.is_a?(Integer) && [0, 1].include?(value)
+        return true if %w[1 true].include?(value)
+        return false if %w[0 false].include?(value)
+
+        raise ProtocolError, "invalid value for schema type boolean"
+      end
+
+      def scalar(value, type)
+        return Models.const_get(type, false).new(value) if TYPES.key?(type)
+
+        case type
+        when "integer"
+          return value if value.is_a?(Integer)
+          return Integer(value, 10) if value.is_a?(String) && /\A[+-]?\d+\z/.match?(value)
+        when "float"
+          if numeric_value?(value)
+            number = Float(value)
+            return number if number.finite?
+          end
+        when "boolean"
+          return boolean(value)
+        when "string", "dateTime"
+          return value if value.is_a?(String)
+        end
+        raise ProtocolError, "invalid value for schema type #{type}"
+      rescue ArgumentError, RangeError
+        raise ProtocolError, "invalid value for schema type #{type}", cause: nil
+      end
+    end
+
+    TYPES.each do |name, fields|
+      model = Class.new(Record)
+      model.const_set(:FIELDS, fields)
+      if fields.dig("items", "repeated")
+        model.include(Enumerable)
+        # Enumerable#to_h would otherwise shadow Record's lossless JSON view.
+        model.define_method(:to_h, Record.instance_method(:to_h))
+        model.define_method(:each) do |&block|
+          return enum_for(:each) unless block
+
+          (self["items"] || []).each(&block)
+        end
+      end
+      fields.each_key do |wire_name|
+        reader = wire_name.gsub(/([a-z0-9])([A-Z])/, '\\1_\\2').downcase
+        model.define_method(reader) { self[wire_name] }
+      end
+      const_set(name, model)
+    end
+
+    class User
+      private
+
+      # The test tenant returns a JSON boolean for this XSD string field.
+      # Keep both observed booleans and legacy strings in their original form.
+      def convert_field(key, value, definition)
+        return value if key == "canViewProfiles" && (value.equal?(true) || value.equal?(false))
+
+        super
+      end
+    end
+  end
+
+  class Response < Models::Record
+    def initialize(payload, contract:)
+      @parts = contract.fetch("response").keys.freeze
+      fields = contract.fetch("response").to_h do |key, type|
+        [key, { "type" => type.split(":").last }]
+      end
+      super(payload, fields: fields, reader_payload: Envelope.parts(payload, contract))
+    end
+
+    def key?(key)
+      @values.key?(key.to_s)
+    end
+
+    # Only declared response parts get convenience readers. Unknown keys remain
+    # accessible through [] and the original JSON snapshot through #to_h.
+    def method_missing(name, *arguments)
+      wire_name = @parts.find { |part| part.gsub(/([a-z0-9])([A-Z])/, '\\1_\\2').downcase == name.to_s }
+      return self[wire_name] if wire_name && arguments.empty?
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @parts.any? { |part| part.gsub(/([a-z0-9])([A-Z])/, '\\1_\\2').downcase == name.to_s } || super
+    end
+
+    private
+
+    def convert_field(key, value, definition)
+      # Live project/task deletions return an integer marker, not an XSD boolean.
+      # Preserve that result rather than guessing its meaning or coercing it.
+      return value if key == "status" && definition["type"] == "boolean" && value.is_a?(Integer) && value >= 0
+
+      super
+    end
+  end
+end

data/lib/five_pm/retry_policy.rb

@@ -0,0 +1,48 @@
+module FivePM
+  class RetryPolicy
+    READS = {
+      "authentication" => %w[getAuthorizedUser isSsl],
+      "projects" => %w[getById getAll getList], "projectsgroups" => %w[getById getAll],
+      "tasks" => %w[getById getList], "users" => %w[getById getByEmail getAll getAuthorizedUser],
+      "activity" => %w[getById getList getFilesList downloadFile]
+    }.transform_values(&:freeze).freeze
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    def initialize(max_retries: 0, max_delay: 30, sleeper: ->(seconds) { sleep(seconds) }, random: -> { rand })
+      unless max_retries.is_a?(Integer) && (0..3).cover?(max_retries) &&
+             max_delay.is_a?(Numeric) && max_delay.real? && max_delay.finite? && max_delay.positive?
+        raise ConfigurationError, "read retries must be 0..3 and maximum delay positive and finite"
+      end
+
+      @max_retries = max_retries
+      @max_delay = max_delay
+      @sleeper = sleeper
+      @random = random
+    end
+
+    def call(service, operation)
+      retries = 0
+      begin
+        yield
+      rescue TransportError, HTTPError => e
+        allowed = READS.fetch(service, []).include?(operation) && retries < @max_retries
+        allowed &&= e.is_a?(TransportError) || RETRY_STATUSES.include?(e.status)
+        raise unless allowed
+
+        # Never retry earlier than Retry-After. HTTP-date and malformed header values
+        # cannot be honored without guessing; the transport marks these non-retryable.
+        raise if e.is_a?(RateLimitError) && (!e.retryable? || (e.retry_after && e.retry_after > @max_delay))
+
+        delay = [0.5 * (2**retries) * (0.5 + @random.call), @max_delay].min
+        delay = [delay, e.retry_after || 0].max if e.is_a?(RateLimitError)
+        @sleeper.call(delay)
+        retries += 1
+        retry
+      end
+    end
+
+    def inspect
+      "#<FivePM::RetryPolicy>"
+    end
+  end
+end

data/lib/five_pm/services.rb

@@ -0,0 +1,40 @@
+module FivePM
+  class Authentication < Service
+    def authorized_user
+      call("getAuthorizedUser")
+    end
+
+    def ssl?
+      call("isSsl")
+    end
+  end
+
+  class Users < Resource
+    def find_by_email(email)
+      call("getByEmail", email: email)
+    end
+  end
+
+  class Activity < Resource
+    def files(filter: nil, offset: nil, count: nil)
+      call("getFilesList", filter: filter, offset: offset, count: count)
+    end
+
+    # Preserve the WSDL FileList representation; never infer content encoding or
+    # follow URLs returned inside records. Actual attachment behavior needs a tenant.
+    def attach_files(activity_id:, files:)
+      files = files.to_h if files.is_a?(Models::Record)
+      raise ArgumentError, "files must be a FileList object" unless files.is_a?(Hash)
+
+      call("attachFiles", activityId: activity_id, files: files)
+    end
+
+    def delete_file(id)
+      call("removeFile", id: id)
+    end
+
+    def download_file(id)
+      @client.download_file(id)
+    end
+  end
+end

data/lib/five_pm/transport.rb

@@ -0,0 +1,147 @@
+require "net/http"
+require "json"
+require "ipaddr"
+require "socket"
+require "openssl"
+require "timeout"
+
+module FivePM
+  class Transport
+    # Restrict requests to account hosts. Resolve and pin a public address per request
+    # to prevent a DNS change between validation and connection. Proxies are disabled.
+    BLOCKED = %w[0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 127.0.0.0/8 169.254.0.0/16
+                 172.16.0.0/12 192.0.0.0/24 192.0.2.0/24 192.168.0.0/16
+                 198.18.0.0/15 198.51.100.0/24 203.0.113.0/24 224.0.0.0/4
+                 240.0.0.0/4].map { |cidr| IPAddr.new(cidr) }.freeze
+
+    def initialize(host:, open_timeout: 5, read_timeout: 30, write_timeout: 30, max_response_bytes: 5 * 1024 * 1024)
+      unless host.is_a?(String) && /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.5pmweb\.com\z/.match?(host)
+        raise ConfigurationError, "host must be an account hostname such as example.5pmweb.com"
+      end
+
+      unless max_response_bytes.is_a?(Integer) && max_response_bytes.positive?
+        raise ConfigurationError, "maximum response bytes must be a positive integer"
+      end
+
+      @max_response_bytes = max_response_bytes
+      @host = host.dup.freeze
+      @timeouts = { open_timeout: open_timeout, read_timeout: read_timeout, write_timeout: write_timeout }
+      return if @timeouts.values.all? do |value|
+        value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+      end
+
+      raise ConfigurationError, "timeouts must be positive finite numbers"
+    end
+
+    def post(service, operation, parameters)
+      perform(service, operation, parameters, binary: false)
+    end
+
+    def download_file(parameters)
+      perform("activity", "downloadFile", parameters, binary: true)
+    end
+
+    def inspect
+      "#<FivePM::Transport>"
+    end
+
+    private
+
+    def perform(service, operation, parameters, binary:)
+      raise ArgumentError, "unsupported 5pm operation" unless OPERATIONS.dig(service, operation)
+
+      raise ArgumentError, "parameters must be an object" unless parameters.is_a?(Hash)
+
+      Request.validate!(parameters)
+      addresses = Timeout.timeout(@timeouts.fetch(:open_timeout)) do
+        Addrinfo.getaddrinfo(@host, 443, Socket::AF_INET, :STREAM).map(&:ip_address).uniq
+      end
+      if addresses.empty? || addresses.any? { |address| BLOCKED.any? { |network| network.include?(address) } }
+        raise ConfigurationError, "account must resolve to public IPv4 addresses"
+      end
+
+      http = Net::HTTP.new(@host, 443, nil)
+      http.ipaddr = addresses.first
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.max_retries = 0
+      @timeouts.each { |key, value| http.public_send("#{key}=", value) }
+      request = Net::HTTP::Post.new("/api/v2/service/post/#{service}/#{operation}")
+      request["Accept"] = "application/json"
+      request.set_form_data(flatten(parameters.merge("retType" => "json")))
+      body = +"".b
+      content_type = nil
+      disposition = nil
+      http.start do |connection|
+        connection.request(request) do |response|
+          check_status!(response)
+          content_type = response["Content-Type"]
+          disposition = response["Content-Disposition"]
+          response.read_body do |chunk|
+            if body.bytesize + chunk.bytesize > @max_response_bytes
+              raise ProtocolError,
+                    "5pm response exceeded configured size limit"
+            end
+
+            body << chunk
+          end
+        end
+      end
+      if binary
+        check_download_error!(body) unless disposition.to_s.match?(/\battachment\b/i)
+        Download.new(bytes: body, content_type: content_type)
+      else
+        APIResult.check!(parse_json(body))
+      end
+    rescue JSON::ParserError
+      raise ProtocolError, "5pm returned invalid JSON", cause: nil
+    rescue SocketError, SystemCallError, IOError, Timeout::Error, OpenSSL::SSL::SSLError
+      raise TransportError, "5pm connection failed", cause: nil
+    end
+
+    def check_download_error!(body)
+      payload = parse_json(body)
+      APIResult.check!(payload)
+    rescue JSON::ParserError
+      # Ordinary file bytes need not be JSON. Never decode or follow file URLs.
+      nil
+    end
+
+    def parse_json(body)
+      # Validate only after all chunks arrive: UTF-8 characters may span chunks.
+      # Duplicate the buffer so probing a download never changes its binary bytes.
+      text = body.dup.force_encoding(Encoding::UTF_8)
+      raise JSON::ParserError, "invalid UTF-8" unless text.valid_encoding?
+
+      JSON.parse(text)
+    end
+
+    def check_status!(response)
+      status = response.code.to_i
+      raise AuthenticationError, "5pm authentication failed" if [401, 403].include?(status)
+
+      if status == 429
+        header = response["Retry-After"]
+        seconds = header.to_i if header && /\A[0-9]+\z/.match?(header)
+        raise RateLimitError.new(retry_after: seconds, retryable: header.nil? || !seconds.nil?)
+      end
+      raise NotFoundError, status if status == 404
+      raise ServerError, status if (500..599).cover?(status)
+      raise HTTPError, status unless (200..299).cover?(status)
+    end
+
+    def flatten(value, prefix = nil, result = [])
+      case value
+      when Hash
+        value.each { |key, item| flatten(item, prefix ? "#{prefix}[#{key}]" : key.to_s, result) }
+      when Array
+        value.each_with_index { |item, index| flatten(item, "#{prefix}[#{index}]", result) }
+      when nil
+        # Omit optional values rather than turning them into empty strings.
+      else
+        result << [prefix, value.to_s]
+      end
+      result
+    end
+  end
+end