web_function 0.5.0 → 0.8.0

data/lib/web_function/package.rb

@@ -1,67 +1,196 @@
 # frozen_string_literal: true
 
 module WebFunction
+  # Organize, document, and validate endpoints. A package facilitates {Endpoint} discovery and integration by providing
+  # standardized metadata about them.
+  #
+  # A package bundles a base URL together with the endpoints it exposes, as well as optional metadata such as a name,
+  # version information, top-level documentation, and a list of common errors.
+  #
+  # See the [package specification][0] on the Web Function website for the full description of every recognized key and
+  # its constraints.
+  #
+  # [0]: https://webfunction.org/package
+  #
   class Package
-    def initialize(package)
-      @package = package
-    end
+    include Flaggable
 
-    def base_url
-      @package["base_url"]
+    def initialize(base_url:, pipeline_url: nil, name: nil, version: nil, docs: nil, flags: [], versions: [],
+                   endpoints: [], errors: [], objects: [])
+      @base_url = base_url
+      @pipeline_url = pipeline_url
+      @name = name
+      @version = version
+      @docs = docs.to_s
+      @flags = flags
+      @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
 
-    def name
-      @package["name"]
+    class << self
+      # Instantiate a new Package from a hash.
+      #
+      # @param package [Hash] The package hash
+      #
+      # @return [Package] A new Package instance
+      #
+      def from_hash(package)
+        new(
+          base_url: package["base_url"],
+          pipeline_url: package["pipeline_url"],
+          name: package["name"],
+          version: package["version"],
+          docs: package["docs"],
+          flags: Utils.normalize_array_of_strings(package["flags"]),
+          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
 
-    def flags
-      unless @package["flags"].is_a?(Array)
-        return []
-      end
+    # The base URL for the package. Endpoint URLs are formed by joining this base URL with each endpoint's name.
+    #
+    # This is required for the package to be valid and MUST use the HTTP or HTTPS scheme.
+    #
+    # @return [String]
+    #
+    attr_reader :base_url
+
+    # A function pipelining URL used to batch several endpoint invocations into a single request. See the pipelining
+    # specification for more information.
+    #
+    # @return [String, nil]
+    #
+    attr_reader :pipeline_url
+
+    # The name of the package.
+    #
+    # @return [String, nil]
+    #
+    attr_reader :name
+
+    # The version that this package describes. An opaque string.
+    #
+    # This MUST be present when the `versioned` flag is set. See the versioning specification for more information.
+    #
+    # @return [String, nil]
+    #
+    attr_reader :version
 
-      @package["flags"].each do |flag|
-        flag.to_s
+    # Top-level documentation for the package. It must be formatted as markdown.
+    #
+    # @return [String]
+    #
+    attr_reader :docs
+
+    # The versions that are available. Each entry is an opaque string.
+    #
+    # This MUST be present when the `versioned` flag is set. See the versioning specification for more information.
+    #
+    # @return [Array<String>]
+    #
+    attr_reader :versions
+
+    # The {Pipeline} for this package, built from {#pipeline_url}, or `nil` when the package does not declare a
+    # pipeline URL.
+    #
+    # @return [Pipeline, nil]
+    #
+    def pipeline
+      unless pipeline_url
+        return
       end
-    end
 
-    def docs
-      @package["docs"].to_s
+      Pipeline.new(pipeline_url)
     end
 
+    # The endpoints declared by this package.
+    #
+    # @return [Array<Endpoint>]
+    #
     def endpoints
-      unless @package["endpoints"].is_a?(Array)
-        return []
-      end
+      @endpoints.values
+    end
 
-      @package["endpoints"].map do |endpoint|
-        unless endpoint.is_a?(Hash)
-          next
-        end
+    # Looks up a single endpoint by name. Underscores in the given name are converted to hyphens so that Ruby-style
+    # names (e.g. `:find_user_by`) match the hyphenated endpoint names used in packages (e.g. `find-user-by`).
+    #
+    # @param name [String, Symbol] The name of the endpoint to look up.
+    #
+    # @return [Endpoint, nil] The matching endpoint, or `nil` if none is found.
+    #
+    def endpoint(name)
+      @endpoints[name.to_s.gsub("_", "-")]
+    end
 
-        unless endpoint["name"]
-          next
-        end
+    # The list of common errors that can be returned by any endpoint in this package. Only refer to this list if an
+    # endpoint uses the `error_triple` flag. See the error specification for more information.
+    #
+    # @return [Array<DocumentedError>]
+    #
+    def errors
+      @errors.values
+    end
 
-        Endpoint.new(endpoint)
-      end
+    # Looks up a single common error by its machine-readable code.
+    #
+    # @param code [String, Symbol] The error code to look up.
+    #
+    # @return [DocumentedError, nil] The matching error, or `nil` if none is found.
+    #
+    def error(code)
+      @errors[code.to_s]
     end
 
-    def errors
-      unless @package["errors"].is_a?(Array)
-        return []
-      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
 
-      @package["errors"].map do |error|
-        unless error.is_a?(Hash)
-          next
-        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 error["code"]
-          next
-        end
+      unless object
+        return
+      end
 
-        DocumentedError.new(error)
+      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.
+    #
+    # @return [Boolean]
+    #
+    def versioned?
+      flag?("versioned")
     end
   end
 end

data/lib/web_function/pipeline.rb

@@ -1,4 +1,14 @@
+# frozen_string_literal: true
+
 module WebFunction
+  # A pipeline is a sequence of steps that are executed in order.
+  #
+  # @example
+  #   pipeline = WebFunction::Pipeline.new("https://pipe.example/exec")
+  #   pipeline.add_step({ url: "https://a", headers: {}, body: {} })
+  #   pipeline.add_step({ url: "https://b", headers: {}, body: {} })
+  #   pipeline.execute(returns: :all) # => [{ "a" => 1 }, { "b" => 2 }]
+  #
   class Pipeline
     def initialize(url)
       @url = url
@@ -6,6 +16,12 @@ module WebFunction
       @promises = []
     end
 
+    # Adds a step to the pipeline.
+    #
+    # @param step [Hash] The step to add
+    #
+    # @return [Promise] A new Promise instance
+    #
     def add_step(step)
       n = @promises.count
       promise = Promise.new(self, "$[#{n}]")
@@ -16,13 +32,20 @@ module WebFunction
       promise
     end
 
+    # Executes the pipeline.
+    #
+    # @param returns [String, Symbol] The return type or a JSONPath expression to return a specific value.
+    #
+    # @return [Object] The response returned by the pipeline.
+    #
     def execute(returns: :all)
       case returns
       when :all
-        responses = Endpoint.invoke(@url, args: {
+        responses = Request.execute(@url, args: {
           steps: @steps,
           returns: "$",
-        })
+        },
+        )
 
         responses.each_with_index do |response, index|
           @promises[index].value = response
@@ -32,10 +55,11 @@ module WebFunction
 
         responses
       when :last
-        response = Endpoint.invoke(@url, args: {
+        response = Request.execute(@url, args: {
           steps: @steps,
           returns: "$[-1:]",
-        })
+        },
+        )
 
         @promises.last.value = response
 
@@ -43,10 +67,11 @@ module WebFunction
 
         response
       else
-        response = Endpoint.invoke(@url, args: {
+        response = Request.execute(@url, args: {
           steps: @steps,
           returns: returns,
-        })
+        },
+        )
 
         reset!
 
@@ -54,6 +79,10 @@ module WebFunction
       end
     end
 
+    # Resets the pipeline.
+    #
+    # @return [void]
+    #
     def reset!
       @steps = []
       @promises = []

data/lib/web_function/promise.rb

@@ -1,4 +1,13 @@
+# 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
@@ -6,19 +15,42 @@ module WebFunction
       @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
@@ -30,13 +62,27 @@ module WebFunction
         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
@@ -45,6 +91,12 @@ module WebFunction
       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)
@@ -53,6 +105,12 @@ module WebFunction
       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]
@@ -61,6 +119,12 @@ module WebFunction
       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
@@ -69,6 +133,10 @@ module WebFunction
       @value
     end
 
+    # Resolves the promise.
+    #
+    # @return [Object] The value of the promise
+    #
     def resolve
       if @value
         return @value

data/lib/web_function/request.rb

@@ -0,0 +1,172 @@
+# 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] The response returned by the request
+      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.
+    #
+    # @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] 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
+
+      result
+    end
+  end
+end

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