webfunction 1.0.0

data/lib/webfunction/promise.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # A promise is a placeholder for a value that will be resolved later.
+  #
+  # @example
+  #   pipeline = WebFunction::Pipeline.new("https://pipe.example/exec")
+  #   promise = pipeline.add_step({})
+  #   promise.resolve # => { "a" => 1 }
+  #
+  class Promise
+    def initialize(pipeline, path)
+      @pipeline = pipeline
+      @path = Path.new(path)
+      @value = nil
+    end
+
+    # A path is a JSONPath expression that can be used to resolve a value from a response.
+    #
+    # @example
+    #   path = WebFunction::Promise::Path.new("$[0]")
+    #   path.to_s # => "$[0]"
+    #   path[0] # => { "a" => 1 }
+    #
+    class Path
+      def initialize(path)
+        @path = path
+      end
+
+      # Returns the string representation of the path.
+      #
+      # @return [String] The string representation of the path
+      #
+      def to_s
+        @path
+      end
+
+      # Returns the JSON representation of the path.
+      #
+      # @param args [Array] The arguments to pass to the JSON.generate method
+      #
+      # @return [String] The JSON representation of the path
+      #
+      def to_json(*args)
+        @path.to_json(*args)
+      end
+
+      # Returns a new path with the given key.
+      #
+      # @param key [String, Symbol, Integer] The key to add to the path
+      #
+      # @return [Path] A new Path instance
+      #
+      def [](key)
+        case key
+        when String, Symbol
+          mutate("#{@path}.#{key}")
+        when Integer
+          mutate("#{@path}[#{key}]")
+        else
+          raise ArgumentError
+        end
+      end
+
+      # Mutates the path with the given path.
+      #
+      # @param path [String] The path to mutate
+      #
+      # @return [Path] A new Path instance
+      #
+      def mutate(path)
+        Path.new(path)
+      end
+    end
+
+    # The value of the promise.
+    #
+    # @return [Object] The value of the promise
+    #
+    attr_writer :value
+
+    # Returns the string representation of the promise.
+    #
+    # @return [String] The string representation of the promise
+    #
+    def to_s
+      if @value
+        @value.to_s
+      else
+        @path.to_s
+      end
+    end
+
+    # Returns the JSON representation of the promise.
+    #
+    # @param args [Array] The arguments to pass to the JSON.generate method
+    #
+    # @return [String] The JSON representation of the promise
+    #
+    def to_json(*args)
+      if @value
+        @value.to_json(*args)
+      else
+        @path.to_json(*args)
+      end
+    end
+
+    # Returns the value of the promise at the given key.
+    #
+    # @param key [String, Symbol, Integer] The key to resolve
+    #
+    # @return [Object] The value of the promise at the given key
+    #
+    def [](key)
+      if @value
+        @value[key]
+      else
+        @path[key]
+      end
+    end
+
+    # Returns the value of the promise.
+    #
+    # @raise [WebFunction::UnresolvedPromiseError] If the promise is not resolved
+    #
+    # @return [Object] The value of the promise
+    #
+    def value
+      unless @value
+        raise WebFunction::UnresolvedPromiseError
+      end
+
+      @value
+    end
+
+    # Resolves the promise.
+    #
+    # @return [Object] The value of the promise
+    #
+    def resolve
+      if @value
+        return @value
+      end
+
+      @pipeline.execute
+
+      value
+    end
+  end
+end

data/lib/webfunction/request.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # A request allows you to invoke a Web Function endpoint via an HTTP client.
+  #
+  # @example
+  #   request = WebFunction::Request.new("https://api.example.com/endpoint")
+  #   request.execute # => { "a" => 1 }
+  #
+  class Request
+    def initialize(url, bearer_auth: nil, version: nil, args: {})
+      @url = url
+      @bearer_auth = bearer_auth
+      @version = version
+      @args = args || {}
+    end
+
+    class << self
+      # The HTTP client used to execute the request.
+      #
+      # To provide a custom HTTP client instead of the default (which uses Excon),
+      # set this to any object responding to #call. For example, a Proc or a lambda.
+      #
+      # The contract is:
+      #
+      #     client.call(url, headers, body)
+      #
+      # - url:    [String] The full URL to post to (not just the hostname or path).
+      # - headers:[Hash<String,String>] HTTP headers, e.g. { "Content-Type" => "application/json" }
+      # - body:   [String] The JSON body to post.
+      #
+      # The client must return a two-element Array: [status, body]:
+      #
+      # - status: [Integer] HTTP status code (e.g. 200, 400, 500)
+      # - body:   [String] Raw response body as a string
+      #
+      # @example
+      #   WebFunction::Endpoint.http_client = ->(url, headers, args) {
+      #     http_response = MyHTTP.post(url, headers: headers, body: JSON.generate(args))
+      #     [http_response.status, http_response.body]
+      #   }
+      #
+      attr_accessor :http_client
+
+      # Executes a request.
+      #
+      # @param url [String] The URL of the request
+      # @param bearer_auth [String] The bearer authentication token
+      # @param version [String] The API version to use
+      # @param args [Hash] The arguments to send to the request
+      #
+      # @return [Object, Page] The response returned by the request. Paginated
+      #   responses are wrapped in a {Page}.
+      def execute(url, bearer_auth: nil, version: nil, args: {})
+        request = new(url, bearer_auth: bearer_auth, version: version, args: args)
+        request.execute
+      end
+    end
+
+    self.http_client = proc do |url, headers, body|
+      response = Excon.post(url, headers: headers, body: body)
+      [response.status, response.body]
+    end
+
+    # The URL of the request.
+    #
+    # @return [String] The URL of the request
+    #
+    attr_reader :url
+
+    # The bearer authentication token.
+    #
+    # @return [String] The bearer authentication token
+    #
+    attr_reader :bearer_auth
+
+    # The API version to use.
+    #
+    # @return [String] The API version to use
+    #
+    attr_reader :version
+
+    # The arguments to send to the request.
+    #
+    # @return [Hash] The arguments to send to the request
+    #
+    attr_reader :args
+
+    # The headers to send to the request.
+    #
+    # @return [Hash] The headers to send to the request
+    #
+    def headers
+      headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": "webfunction/#{WebFunction::VERSION}",
+        "Accept-Encoding": "gzip",
+      }
+
+      if @bearer_auth
+        headers["Authorization"] = "Bearer #{@bearer_auth}"
+      end
+
+      if @version
+        headers["Api-Version"] = @version
+      end
+
+      headers
+    end
+
+    # Returns the request as a pipeline step.
+    #
+    # @return [Hash] The request as a pipeline step
+    #
+    def as_pipeline_step
+      {
+        url: @url,
+        headers: headers,
+        body: @args,
+      }
+    end
+
+    # Executes the request.
+    #
+    # When the response matches the pagination contract (`page`, `next`, and
+    # `previous` keys), it is wrapped in a {Page} so callers can navigate with
+    # {Page#next_page} and {Page#previous_page}.
+    #
+    # @raise [WebFunction::UnexpectedStatusCodeError] If the status code is not 200 or 400
+    # @raise [WebFunction::JsonParseError] If the response is not valid JSON
+    # @raise [WebFunction::BadRequestError] If the response is a bad request
+    #
+    # @return [Object, Page] The response returned by the request
+    #
+    def execute
+      status, body = self.class.http_client.call(@url, headers, JSON.generate(@args))
+
+      unless [200, 400].include?(status)
+        raise WebFunction::UnexpectedStatusCodeError.new("Unexpected status code (#{status})",
+          details: {
+            status_code: status,
+            raw_body: body,
+          },
+        )
+      end
+
+      begin
+        result = JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise WebFunction::JsonParseError.new(e.message,
+          details: {
+            status_code: status,
+            raw_body: body,
+            original_exception: e,
+          },
+        )
+      end
+
+      if status == 400
+        code = "WFN_BAD_REQUEST_ERROR"
+        message = "Bad request"
+        details = { body: result }
+
+        if result.is_a?(Array) && result.length == 3 && result[0].is_a?(String) && result[1].is_a?(String)
+          code = result[0]
+          message = result[1]
+          details = result[2]
+        end
+
+        raise WebFunction::BadRequestError.new(message, code: code, details: details)
+      end
+
+      Page.wrap(result, request: self)
+    end
+  end
+end

data/lib/webfunction/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/webfunction/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/webfunction/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/webfunction/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/webfunction/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