web_function 0.5.0 → 0.8.0

data/lib/web_function/endpoint.rb

@@ -1,23 +1,21 @@
 # frozen_string_literal: true
 
 module WebFunction
-  # # Endpoint
-  #
   # 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.
+  # 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:
   #
-  # 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.
+  # 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
@@ -25,209 +23,221 @@ module WebFunction
   # 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:, flags: [], group: nil, docs: nil, arguments: [], attributes: [], errors: [])
+      @name = name
+      @returns = Type.parse(returns)
+      @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
 
     class << self
-      # ## HTTP client getter
+      # Invokes an endpoint through HTTP using the given URL, bearer authentication, version, and arguments.
       #
-      # The HTTP client used to invoke the endpoint.
+      # @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 [Proc]
+      # @return [Object] The response returned by the endpoint
       #
-      def http_client
-        @http_client ||= proc do |url, headers, body|
-          response = Excon.post(url,
-            headers: headers,
-            body: body,
-          )
-          [response.status, response.body]
-        end
+      def invoke(url, bearer_auth: nil, version: nil, args: {})
+        Request.execute(url, bearer_auth: bearer_auth, version: version, args: args)
       end
 
-      # ## HTTP client setter
-      #
-      # Sets the HTTP client used to invoke the endpoint.
-      #
-      # To provide a custom HTTP client instead of the default (which uses Excon),
-      # set this to any object responding to #call or a Proc/lambda.
-      #
-      # The contract is:
-      #   client.call(url, headers, body)
+      # Creates a new Endpoint from a hash.
       #
-      # - 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.
+      # @param endpoint [Hash] The endpoint hash
       #
-      # 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
+      # @return [Endpoint] A new Endpoint instance
       #
-      # 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]
-      #   }
-      #
-      # @param http_client [Proc,#call] The new HTTP client to use.
-      #
-      attr_writer :http_client
-
-      def step(url, bearer_auth: nil, args: {})
-        headers = {
-          "Content-Type": "application/json",
-          "Accept": "application/json",
-          "User-Agent": "webfunction/#{WebFunction::VERSION}",
-        }
-
-        if args.nil?
-          args = {}
+      def from_hash(endpoint)
+        unless endpoint.is_a?(Hash)
+          return
         end
 
-        if bearer_auth
-          headers["Authorization"] = "Bearer #{bearer_auth}"
+        unless endpoint["name"]
+          return
         end
 
-        {
-          url: url,
-          headers: headers,
-          body: args,
-        }
-      end
-
-      def invoke(url, bearer_auth: nil, args: {})
-        headers = {
-          "Content-Type": "application/json",
-          "Accept": "application/json",
-          "User-Agent": "webfunction/#{WebFunction::VERSION}",
-        }
-
-        if args.nil?
-          args = {}
+        unless endpoint["returns"]
+          return
         end
 
-        if bearer_auth
-          headers["Authorization"] = "Bearer #{bearer_auth}"
-        end
-
-        status, body = 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 = "BAD_REQUEST"
-          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
+        new(
+          name: endpoint["name"],
+          returns: endpoint["returns"],
+          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
 
-          raise WebFunction::BadRequestError.new(message, code: code, details: details)
+      # 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
-
-        result
       end
     end
 
-    def name
-      @endpoint["name"]
-    end
+    # 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
+
+    # 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
 
-    def returns
-      [*@endpoint["returns"]].map { |type| type.to_s }
+      client.call(name, args)
     end
 
-    def hints
-      [*@endpoint["hints"]].map { |hint| hint.to_s }
+    # 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"]].map { |flag| flag.to_s }
+    # 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"].to_s
+    # 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
-
-      @endpoint["arguments"].map do |argument|
-        unless argument.is_a?(Hash)
-          next
-        end
-
-        unless argument["name"]
-          next
-        end
-
-        Argument.new(argument)
-      end
+      @arguments.values
     end
 
-    def attributes
-      unless @endpoint["attributes"].is_a?(Array)
-        return []
-      end
-
-      @endpoint["attributes"].map do |attribute|
-        unless attribute.is_a?(Hash)
-          next
-        end
-
-        unless attribute["name"]
-          next
-        end
-
-        Attribute.new(attribute)
-      end
+    # 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 errors
-      unless @endpoint["errors"].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["errors"].map do |error|
-        unless error.is_a?(Hash)
-          next
-        end
+    # 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
 
-        unless error["code"]
-          next
-        end
+    # Whether the endpoint supports pagination, i.e. whether it declares the `paginated` flag.
+    #
+    # @return [Boolean]
+    #
+    def paginated?
+      flag?("paginated")
+    end
 
-        DocumentedError.new(error)
-      end
+    # 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/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