web_function 0.4.1 → 0.6.0

data/lib/web_function/endpoint.rb

@@ -1,111 +1,251 @@
 # frozen_string_literal: true
 
 module WebFunction
+  # Represents an endpoint as described in a Web Function package.
+  #
+  # An endpoint defines an operation that can be performed via a Web Function API. Endpoints declare their name,
+  # documentation, arguments (inputs), attributes (outputs), and the possible errors that may occur when invoking them.
+  #
+  # Endpoints are described as objects in each package under the `"endpoints"` key. For more information, see:
+  #
+  # - [Web Function package docs](https://webfunction.org/package)
+  # - [Web Function endpoint docs](https://webfunction.org/endpoint)
+  #
+  # This class provides methods for accessing endpoint metadata (name, docs, arguments, attributes, errors) and
+  # supports invocation via HTTP.
+  #
+  # Typical tasks include:
+  #
+  # - Querying endpoint name or documentation
+  # - Enumerating the arguments or attributes definitions
+  # - Invoking the endpoint through HTTP using required inputs
+  #
+  # See: https://webfunction.org/endpoint for more details on endpoint structure and contract.
+  #
   class Endpoint
-    def initialize(endpoint)
-      @endpoint = endpoint
+    include Flaggable
+
+    def initialize(name:, returns: [], hints: [], flags: [], group: nil, docs: nil, arguments: [], attributes: [], errors: [])
+      @name = name
+      @returns = returns
+      @hints = hints
+      @flags = flags
+      @group = group
+      @docs = docs
+      @arguments = arguments.to_h { |a| [a.name, a] }
+      @attributes = attributes.to_h { |a| [a.name, a] }
+      @errors = errors.to_h { |e| [e.code, e] }
     end
 
-    def self.invoke(url, bearer_auth: nil, args: {}, as_step: false)
-      headers = {
-        "Content-Type": "application/json",
-        "Accept": "application/json",
-        "User-Agent": "webfunction/#{WebFunction::VERSION}",
-      }
-
-      if args.nil?
-        args = {}
+    class << self
+      # Invokes an endpoint through HTTP using the given URL, bearer authentication, version, and arguments.
+      #
+      # @param url [String] The URL of the endpoint to invoke
+      # @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 endpoint
+      #
+      # @return [Object] The response returned by the endpoint
+      #
+      def invoke(url, bearer_auth: nil, version: nil, args: {})
+        Request.execute(url, bearer_auth: bearer_auth, version: version, args: args)
       end
 
-      if bearer_auth
-        headers["Authorization"] = "Bearer #{bearer_auth}"
-      end
+      # Creates a new Endpoint from a hash.
+      #
+      # @param endpoint [Hash] The endpoint hash
+      #
+      # @return [Endpoint] A new Endpoint instance
+      #
+      def from_hash(endpoint)
+        unless endpoint.is_a?(Hash)
+          return
+        end
+
+        unless endpoint["name"]
+          return
+        end
 
-      if as_step
-        return {
-          url: url,
-          headers: headers,
-          body: args,
-        }
+        new(
+          name: endpoint["name"],
+          returns: Utils.normalize_array_of_strings(endpoint["returns"]),
+          hints: Utils.normalize_array_of_strings(endpoint["hints"]),
+          flags: Utils.normalize_array_of_strings(endpoint["flags"]),
+          group: endpoint["group"],
+          docs: endpoint["docs"].to_s,
+          arguments: Argument.from_array(endpoint["arguments"]),
+          attributes: Attribute.from_array(endpoint["attributes"]),
+          errors: DocumentedError.from_array(endpoint["errors"]),
+        )
       end
 
-      response = Excon.post(url,
-        headers: headers,
-        body: JSON.generate(args),
-      )
-
-      result = JSON.parse(response.body)
-
-      if response.status == 400
-        case result
-        when Array
-          if result.length == 3 && result[0].is_a?(String) && result[1].is_a?(String)
-            code = result[0]
-            message = result[1]
-            details = result[2]
-
-            raise WebFunction::Error.new(message, code: code, details: details)
-          else
-            raise WebFunction::Error.new("Bad request", details: result)
-          end
-        when String
-          raise WebFunction::Error.new(result)
-        else
-          raise WebFunction::Error.new("Bad request", details: result)
+      # Creates a new Endpoint from an array of hashes. Uses {Endpoint#from_hash} under the hood.
+      #
+      # @param endpoints [Array<Hash>] The endpoint array of hashes
+      #
+      # @return [Array<Endpoint>] A new array of Endpoint instances
+      #
+      def from_array(endpoints)
+        Utils.normalize_array endpoints do |endpoint|
+          from_hash(endpoint)
         end
       end
+    end
 
-      if response.status != 200
-        raise WebFunction::Error.new("Unexpected status code [#{response.status}]")
+    # The {Client} used to invoke this endpoint. It is assigned when the endpoint is loaded from a package and is
+    # required by {#call}.
+    #
+    # @return [Client, nil]
+    #
+    attr_accessor :client
+
+    # The suffix for the endpoint URL, appended to the package's base URL to form the full endpoint URL. Endpoint names
+    # are unique within a package; overloading (two endpoints sharing the same name) is not permitted.
+    #
+    # @return [String]
+    #
+    attr_reader :name
+
+    # The JSON type(s) returned by the endpoint. A non-empty array whose entries are each one of:
+    #
+    # - object
+    # - array
+    # - string
+    # - number
+    # - boolean
+    # - null
+    #
+    # @return [Array<String>]
+    #
+    attr_reader :returns
+
+    # Hints for the endpoint's return value. Each hint's base JSON type matches one of the endpoint's {#returns} types,
+    # and at most one hint is supplied per base JSON type. See the [hints section][1] on the Web Function website for
+    # the complete list of allowed hints.
+    #
+    # @return [Array<String>]
+    #
+    # [1]: https://webfunction.org/package#hints
+    #
+    attr_reader :hints
+
+    # A name used to categorize or group similar endpoints together. This should be used by documentation tools to
+    # organize related endpoints.
+    #
+    # @return [String, nil]
+    #
+    attr_reader :group
+
+    # Documentation for the endpoint. It must be formatted as markdown.
+    #
+    # @return [String]
+    #
+    attr_reader :docs
+
+    # Invokes the endpoint through its assigned {#client}, passing the given arguments.
+    #
+    # @param args [Hash] The arguments to send to the endpoint.
+    #
+    # @raise [RuntimeError] If no client has been assigned to the endpoint.
+    #
+    # @return [Object] The decoded response returned by the endpoint.
+    #
+    def call(args = {})
+      unless client
+        raise "Client must be set to invoke an endpoint"
       end
 
-      result
-    rescue JSON::ParserError => e
-      raise WebFunction::Error.new("Response cannot be parsed", details: {})
-    end
-
-    def name
-      @endpoint["name"]
+      client.call(name, args)
     end
 
-    def returns
-      @endpoint["returns"]
+    # The list of errors specific to this endpoint. Clients SHOULD only refer to this list if the endpoint uses the
+    # `error_triple` flag. See the error specification for more information.
+    #
+    # @return [Array<DocumentedError>]
+    #
+    def errors
+      @errors.values
     end
 
-    def flags
-      @endpoint["flags"]
+    # Looks up a single endpoint 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 group
-      @endpoint["group"]
+    # The attributes of the object returned by the endpoint. Relevant when the endpoint returns an `object`.
+    #
+    # @return [Array<Attribute>]
+    #
+    def attributes
+      @attributes.values
     end
 
-    def docs
-      @endpoint["docs"]
+    # Looks up a single returned attribute 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 arguments required by the endpoint. The array is empty when the endpoint requires no arguments.
+    #
+    # @return [Array<Argument>]
+    #
     def arguments
-      unless @endpoint["arguments"].is_a?(Array)
-        return []
-      end
+      @arguments.values
+    end
 
-      @endpoint["arguments"].map { |argument| Argument.new(argument) }
+    # Looks up a single argument 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
 
-    def attributes
-      unless @endpoint["attributes"].is_a?(Array)
-        return []
-      end
+    # Whether the endpoint requires authentication via a bearer token, i.e. whether it declares the `bearer_auth` flag.
+    #
+    # @return [Boolean]
+    #
+    def bearer_auth?
+      flag?("bearer_auth")
+    end
 
-      @endpoint["attributes"].map { |attribute| Attribute.new(attribute) }
+    # Whether the endpoint returns a bearer token in its response, i.e. whether it declares the `capture_bearer` flag.
+    # See the authentication specification for more information.
+    #
+    # @return [Boolean]
+    #
+    def capture_bearer?
+      flag?("capture_bearer")
     end
 
-    def errors
-      unless @endpoint["errors"].is_a?(Array)
-        return []
-      end
+    # Whether the endpoint supports pagination, i.e. whether it declares the `paginated` flag.
+    #
+    # @return [Boolean]
+    #
+    def paginated?
+      flag?("paginated")
+    end
 
-      @endpoint["errors"].map { |error| DocumentedError.new(error) }
+    # Whether the endpoint is intended for internal use and is not part of the public API, i.e. whether it declares the
+    # `private` flag. Documentation tooling SHOULD omit endpoints with this flag from generated or
+    # published documentation.
+    #
+    # @return [Boolean]
+    #
+    def private?
+      flag?("private")
     end
   end
 end

data/lib/web_function/flaggable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # A module that provides a flaggable interface. Flags are used to define the behavior of an object.
+  #
+  # @example
+  #   class Endpoint
+  #     include Flaggable
+  #
+  #     def initialize(name:, flags: [])
+  #       @name = name
+  #       @flags = flags
+  #     end
+  #   end
+  #
+  #   endpoint = Endpoint.new(name: "get_user", flags: ["private"])
+  #   endpoint.flag?("private") # => true
+  #   endpoint.flag?("public") # => false
+  #
+  module Flaggable
+    # List of flags. See the [available flags section][2] on the Web Function
+    # website for a complete list of flags available.
+    #
+    # @return [Array<String>]
+    #
+    # [2]: https://webfunction.org/package#available-flags
+    #
+    attr_reader :flags
+
+    # Whether the endpoint declares the given flag.
+    #
+    # @param flag [String] The flag to check for.
+    #
+    # @return [Boolean]
+    #
+    def flag?(flag)
+      @flags.include?(flag)
+    end
+  end
+end

data/lib/web_function/package.rb

@@ -1,41 +1,156 @@
 # 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: [])
+      @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] }
     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"]),
+        )
+      end
     end
 
-    def flags
-      @package["flags"]
-    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
+
+    # 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
 
-    def docs
-      @package["docs"]
+    # 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
+
+      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 { |endpoint| Endpoint.new(endpoint) }
+    # 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
 
+    # 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
-      unless @package["errors"].is_a?(Array)
-        return []
-      end
+      @errors.values
+    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
 
-      @package["errors"].map { |error| DocumentedError.new(error) }
+    # 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 = []