web_function 0.6.0 → 0.8.0

data/lib/web_function/object_schema.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # Represents a named object definition as described in a Web Function package.
+  #
+  # Objects are declared in a package under the `"objects"` key and can be referenced as a refined object type
+  # (`object.<name>`) anywhere a type is expected. An `object.` reference appears in one of two contexts, which
+  # determines which set of properties applies:
+  #
+  # - Argument context — the object is referenced as an argument's `type`. Its {#arguments} describe its properties.
+  # - Attribute context — the object is referenced as an endpoint's `returns` or as an attribute's `type`. Its
+  #   {#attributes} describe its properties.
+  #
+  # Because an object MAY be referenced in both contexts within the same package, it MAY define both `arguments` and
+  # `attributes`; each set is used only in its matching context.
+  #
+  # It is named `ObjectSchema` rather than `Object` to avoid clashing with Ruby's built-in `::Object`.
+  #
+  # See the [object definition documentation][0] on the Web Function website for more details.
+  #
+  # [0]: https://webfunction.org/package#object-definition
+  #
+  class ObjectSchema
+    # The contexts in which an object may be referenced. Each maps to the member set that applies in that context.
+    #
+    # @return [Array<Symbol>]
+    #
+    CONTEXTS = %i[arguments attributes].freeze
+
+    def initialize(name:, arguments: [], attributes: [])
+      @name = name
+      @arguments = arguments.to_h { |a| [a.name, a] }
+      @attributes = attributes.to_h { |a| [a.name, a] }
+    end
+
+    class << self
+      # Creates a new ObjectSchema from a hash. Typically coming from a {Package}.
+      #
+      # @param object [Hash] The object hash
+      #
+      # @return [ObjectSchema, nil] A new ObjectSchema instance, or `nil` if the hash is invalid.
+      #
+      def from_hash(object)
+        unless object.is_a?(Hash)
+          return
+        end
+
+        unless object["name"]
+          return
+        end
+
+        new(
+          name: object["name"],
+          arguments: Argument.from_array(object["arguments"]),
+          attributes: Attribute.from_array(object["attributes"]),
+        )
+      end
+
+      # Creates a new ObjectSchema from an array of hashes. Typically coming from a {Package}. Uses
+      # {ObjectSchema#from_hash} under the hood.
+      #
+      # @param objects [Array<Hash>] The object array of hashes
+      #
+      # @return [Array<ObjectSchema>] A new array of ObjectSchema instances
+      #
+      def from_array(objects)
+        Utils.normalize_array objects do |object|
+          from_hash(object)
+        end
+      end
+    end
+
+    # The name of the object. It is referenced as a refined object type (`object.<name>`) and is unique within a
+    # package.
+    #
+    # @return [String]
+    #
+    attr_reader :name
+
+    # The object's properties when it is referenced in an argument context.
+    #
+    # @return [Array<Argument>]
+    #
+    def arguments
+      @arguments.values
+    end
+
+    # Looks up a single argument member by name.
+    #
+    # @param name [String, Symbol] The name of the argument to look up.
+    #
+    # @return [Argument, nil] The matching argument, or `nil` if none is found.
+    #
+    def argument(name)
+      @arguments[name.to_s]
+    end
+
+    # The object's properties when it is referenced in an attribute context.
+    #
+    # @return [Array<Attribute>]
+    #
+    def attributes
+      @attributes.values
+    end
+
+    # Looks up a single attribute member by name.
+    #
+    # @param name [String, Symbol] The name of the attribute to look up.
+    #
+    # @return [Attribute, nil] The matching attribute, or `nil` if none is found.
+    #
+    def attribute(name)
+      @attributes[name.to_s]
+    end
+
+    # The object's properties for the given context.
+    #
+    # @param context [Symbol] The context to resolve properties for. One of {CONTEXTS}.
+    #
+    # @raise [ArgumentError] If the context is not one of {CONTEXTS}.
+    #
+    # @return [Array<Argument>, Array<Attribute>] The properties that apply in the given context.
+    #
+    def properties(context)
+      case context
+      when :arguments
+        arguments
+      when :attributes
+        attributes
+      else
+        raise ArgumentError, "context must be one of #{CONTEXTS.inspect}, got #{context.inspect}"
+      end
+    end
+  end
+end

data/lib/web_function/package.rb

@@ -16,7 +16,7 @@ module WebFunction
     include Flaggable
 
     def initialize(base_url:, pipeline_url: nil, name: nil, version: nil, docs: nil, flags: [], versions: [],
-                   endpoints: [], errors: [])
+                   endpoints: [], errors: [], objects: [])
       @base_url = base_url
       @pipeline_url = pipeline_url
       @name = name
@@ -26,6 +26,7 @@ module WebFunction
       @versions = versions
       @endpoints = endpoints.to_h { |e| [e.name, e] }
       @errors = errors.to_h { |e| [e.code, e] }
+      @objects = objects.to_h { |o| [o.name, o] }
     end
 
     class << self
@@ -46,6 +47,7 @@ module WebFunction
           versions: Utils.normalize_array_of_strings(package["versions"]),
           endpoints: Endpoint.from_array(package["endpoints"]),
           errors: DocumentedError.from_array(package["errors"]),
+          objects: ObjectSchema.from_array(package["objects"]),
         )
       end
     end
@@ -144,6 +146,44 @@ module WebFunction
       @errors[code.to_s]
     end
 
+    # The named object definitions declared by this package. Each can be referenced as a refined object type
+    # (`object.<name>`) anywhere a type is expected.
+    #
+    # @return [Array<ObjectSchema>]
+    #
+    def objects
+      @objects.values
+    end
+
+    # Looks up a single object definition by name, resolved for the given context.
+    #
+    # An `object.` reference appears in either an argument or attribute context, which determines which set of members
+    # applies. The `context` selects the member set that is relevant; an object that does not define members for the
+    # requested context is treated as absent and `nil` is returned.
+    #
+    # @param name [String, Symbol] The name of the object to look up.
+    # @param context [Symbol] The context the object is referenced in. One of {ObjectSchema::CONTEXTS}
+    #   (`:arguments` or `:attributes`).
+    #
+    # @raise [ArgumentError] If the context is not one of {ObjectSchema::CONTEXTS}.
+    #
+    # @return [ObjectSchema, nil] The matching object, or `nil` if none is found or it defines no members for the
+    #   given context.
+    #
+    def object(name, context:)
+      object = @objects[name.to_s]
+
+      unless object
+        return
+      end
+
+      if object.properties(context).empty?
+        return
+      end
+
+      object
+    end
+
     # Whether the package is versioned, i.e. whether it declares the `versioned` flag. A versioned package is selected
     # using the `Api-Version` header.
     #

data/lib/web_function/request.rb

@@ -94,6 +94,7 @@ module WebFunction
         "Content-Type": "application/json",
         "Accept": "application/json",
         "User-Agent": "webfunction/#{WebFunction::VERSION}",
+        "Accept-Encoding": "gzip",
       }
 
       if @bearer_auth

data/lib/web_function/type/any.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module WebFunction
+  module Type
+    class Any
+      def base_type
+        "any"
+      end
+
+      def refinement
+        nil
+      end
+
+      def inspect
+        "#<any>"
+      end
+
+      def format(_format = :default)
+        "any"
+      end
+
+      def to_s
+        format(:default)
+      end
+
+      def ==(other)
+        other.is_a?(Any)
+      end
+      alias eql? ==
+
+      def hash
+        Any.hash
+      end
+
+      def objects
+        []
+      end
+
+      def without_refinements
+        self
+      end
+
+      def valid?(_value)
+        true
+      end
+    end
+  end
+end

data/lib/web_function/type/array_of.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module WebFunction
+  module Type
+    class ArrayOf
+      attr_reader :base_type, :of
+
+      def initialize(of)
+        @base_type = "array"
+        @of = of
+      end
+
+      def refinement
+        nil
+      end
+
+      def inspect
+        "#<ArrayOf #{@of.inspect}>"
+      end
+
+      def format(format = :default)
+        case format
+        when :base
+          "array"
+        when :compact, :default
+          "array<#{@of.format(format)}>"
+        else
+          raise ArgumentError, "unknown format: #{format.inspect}"
+        end
+      end
+
+      def to_s
+        format(:default)
+      end
+
+      def ==(other)
+        other.is_a?(ArrayOf) && other.of == @of
+      end
+      alias eql? ==
+
+      def hash
+        [ArrayOf, @of].hash
+      end
+
+      def objects
+        @of.objects
+      end
+
+      def without_refinements
+        ArrayOf.new(@of.without_refinements)
+      end
+
+      def valid?(value)
+        value.is_a?(Array) && value.all? { |element| @of.valid?(element) }
+      end
+    end
+  end
+end

data/lib/web_function/type/base.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module WebFunction
+  module Type
+    class Base
+      attr_reader :base_type, :refinement
+
+      def initialize(base_type:, refinement: nil)
+        @base_type = base_type
+        @refinement = refinement
+      end
+
+      def inspect
+        if @refinement
+          "#<#{@base_type} #{@refinement}>"
+        else
+          "#<#{@base_type}>"
+        end
+      end
+
+      def format(format = :default)
+        case format
+        when :compact
+          @refinement || @base_type
+        when :base
+          @base_type
+        when :default
+          if @refinement
+            "#{@base_type}.#{@refinement}"
+          else
+            @base_type
+          end
+        else
+          raise ArgumentError, "unknown format: #{format.inspect}"
+        end
+      end
+
+      def to_s
+        format(:default)
+      end
+
+      def ==(other)
+        other.is_a?(Base) && other.base_type == @base_type && other.refinement == @refinement
+      end
+      alias eql? ==
+
+      def hash
+        [Base, @base_type, @refinement].hash
+      end
+
+      def objects
+        if @base_type == "object" && @refinement
+          [@refinement]
+        else
+          []
+        end
+      end
+
+      def without_refinements
+        return self if @refinement.nil?
+
+        Base.new(base_type: @base_type)
+      end
+
+      def valid?(value)
+        case @base_type
+        when "string"
+          value.is_a?(String) && refinement_valid?(value)
+        when "number"
+          value.is_a?(Numeric) && !value.is_a?(Complex) && refinement_valid?(value)
+        when "object"
+          value.is_a?(Hash)
+        when "boolean"
+          value == true || value == false
+        when "null"
+          value.nil?
+        else
+          false
+        end
+      end
+
+      private
+
+      def refinement_valid?(value)
+        @refinement.nil? || REFINEMENT_VALIDATORS.fetch(@refinement).call(value)
+      end
+    end
+  end
+end

data/lib/web_function/type/union.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module WebFunction
+  module Type
+    class Union
+      attr_reader :members
+
+      def initialize(members)
+        @members = members
+      end
+
+      def base_type
+        nil
+      end
+
+      def refinement
+        nil
+      end
+
+      def inspect
+        "#<Union #{@members.map(&:inspect).join(" | ")}>"
+      end
+
+      def format(format = :default)
+        @members.map { |member| member.format(format) }.join(" | ")
+      end
+
+      def to_s
+        format(:default)
+      end
+
+      def ==(other)
+        other.is_a?(Union) && other.members == @members
+      end
+      alias eql? ==
+
+      def hash
+        [Union, @members].hash
+      end
+
+      def objects
+        @members.flat_map(&:objects).uniq
+      end
+
+      def without_refinements
+        Type.union(@members.map(&:without_refinements))
+      end
+
+      def valid?(value)
+        @members.any? { |member| member.valid?(value) }
+      end
+    end
+  end
+end

data/lib/web_function/type.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "uri"
+
+require_relative "type/base"
+require_relative "type/array_of"
+require_relative "type/union"
+require_relative "type/any"
+
+module WebFunction
+  module Type
+    ALLOWED_REFINEMENTS = {
+      "number" => %w[u32 u64 i32 i64 f32 f64 timestamp].freeze,
+      "string" => %w[date time datetime uuid base64 email phone url uri ipv4 ipv6 hostname].freeze,
+    }.freeze
+
+    # Value-level validators for each refinement, keyed by refinement name. Refinement names are unique across base
+    # types, so a flat table is enough. Must stay in sync with {ALLOWED_REFINEMENTS}.
+    REFINEMENT_VALIDATORS = {
+      "u32" => ->(v) { v.is_a?(Integer) && v.between?(0, 0xFFFFFFFF) },
+      "u64" => ->(v) { v.is_a?(Integer) && v.between?(0, 0xFFFFFFFFFFFFFFFF) },
+      "i32" => ->(v) { v.is_a?(Integer) && v.between?(-0x80000000, 0x7FFFFFFF) },
+      "i64" => ->(v) { v.is_a?(Integer) && v.between?(-0x8000000000000000, 0x7FFFFFFFFFFFFFFF) },
+      "f32" => ->(v) { v.is_a?(Numeric) && v.to_f.finite? && v.to_f.abs <= 3.4028235e38 },
+      "f64" => ->(v) { v.is_a?(Numeric) && v.to_f.finite? },
+      "timestamp" => ->(v) { v.is_a?(Integer) && v >= 0 },
+      "date" => ->(v) { v.match?(/\A\d{4}-\d{2}-\d{2}\z/) },
+      "time" => ->(v) { v.match?(/\A\d{2}:\d{2}:\d{2}(\.\d+)?\z/) },
+      "datetime" => ->(v) { v.match?(/\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?\z/) },
+      "uuid" => ->(v) { v.match?(/\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/) },
+      "base64" => ->(v) { (v.length % 4).zero? && v.match?(%r{\A[A-Za-z0-9+/]*={0,2}\z}) },
+      "email" => ->(v) { v.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/) },
+      "phone" => ->(v) { v.match?(/\A\+[1-9]\d{1,14}\z/) },
+      "url" => ->(v) { (uri = URI.parse(v)).is_a?(URI::HTTP) && !uri.host.nil? rescue false },
+      "uri" => ->(v) { !URI.parse(v).scheme.nil? rescue false },
+      "ipv4" => ->(v) { IPAddr.new(v).ipv4? rescue false },
+      "ipv6" => ->(v) { IPAddr.new(v).ipv6? rescue false },
+      "hostname" => lambda do |v|
+        v.match?(%r{\A(?=.{1,253}\z)([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\z})
+      end,
+    }.freeze
+
+    def self.parse(raw)
+      types = [*raw].map { |type| Type.detect(type) }.compact
+
+      if types.empty?
+        return Type.any
+      end
+
+      Type.union(types)
+    end
+
+    def self.detect(raw)
+      case raw
+      when String
+        Type.base(raw)
+      when Array
+        types = raw.map { |type| Type.detect(type) }.compact
+
+        if types.empty?
+          return Type.array(Type.any)
+        end
+
+        Type.array(Type.union(types))
+      else
+        return nil
+      end
+    end
+
+    def self.base(type)
+      base_type, refinement = type.split(".", 2)
+
+      case base_type
+      when "string"
+        if refinement && !ALLOWED_REFINEMENTS["string"].include?(refinement)
+          return Type.string
+        end
+
+        Type.string(refinement)
+      when "number"
+        if refinement && !ALLOWED_REFINEMENTS["number"].include?(refinement)
+          return Type.number
+        end
+
+        Type.number(refinement)
+      when "object"
+        Type.object(refinement)
+      when "array"
+        Type.array
+      when "boolean"
+        Type.boolean
+      when "null"
+        Type.null
+      when "any"
+        Type.any
+      else
+        nil
+      end
+    end
+
+    def self.string(refinement = nil)
+      Base.new(base_type: "string", refinement: refinement)
+    end
+
+    def self.number(refinement = nil)
+      Base.new(base_type: "number", refinement: refinement)
+    end
+
+    def self.object(refinement = nil)
+      Base.new(base_type: "object", refinement: refinement)
+    end
+
+    def self.array(of = any)
+      ArrayOf.new(of)
+    end
+
+    def self.boolean
+      Base.new(base_type: "boolean")
+    end
+
+    def self.null
+      Base.new(base_type: "null")
+    end
+
+    def self.union(types)
+      types = types.uniq
+
+      if types.length > 1
+        Union.new(types)
+      else
+        types.first
+      end
+    end
+
+    def self.any
+      Any.new
+    end
+  end
+end

data/lib/web_function/utils.rb

@@ -40,5 +40,28 @@ module WebFunction
     def normalize_array_of_strings(collection)
       normalize_array(collection) { |item| item.to_s }
     end
+
+    def get_body_from_url(url, extra_query_params: {})
+      url = add_query_params(url, extra_query_params)
+      response = ::Excon.get(url, headers: {
+        "User-Agent": "webfunction/#{::WebFunction::VERSION}",
+        "Accept-Encoding": "gzip",
+      })
+
+      response.body
+    end
+
+    def add_query_params(url, params = {})
+      uri = ::URI.parse(url)
+      existing_params = ::URI.decode_www_form(uri.query || "").to_h
+      new_params = params.reject { |_, value| value.nil? }.transform_keys(&:to_s)
+      merged_params = existing_params.merge(new_params)
+
+      unless merged_params.empty?
+        uri.query = ::URI.encode_www_form(merged_params)
+      end
+
+      uri.to_s
+    end
   end
 end

data/lib/web_function/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WebFunction
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/web_function.rb

@@ -12,9 +12,11 @@ require_relative "web_function/package"
 require_relative "web_function/endpoint"
 require_relative "web_function/argument"
 require_relative "web_function/attribute"
+require_relative "web_function/object_schema"
 require_relative "web_function/documented_error"
 require_relative "web_function/pipeline"
 require_relative "web_function/promise"
+require_relative "web_function/type"
 require_relative "web_function/utils"
 
 module WebFunction