webfunction 1.0.0

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

@@ -0,0 +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
+    include Flaggable
+
+    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
+
+    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
+
+    # 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
+
+    # 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
+      @endpoints.values
+    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
+
+    # 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
+
+    # 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
+
+    # 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.
+    #
+    # @return [Boolean]
+    #
+    def versioned?
+      flag?("versioned")
+    end
+  end
+end

data/lib/webfunction/page.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # A page of results from a paginated endpoint.
+  #
+  # Paginated responses follow the Web Function pagination contract: a JSON object with
+  # `page`, `next`, and `previous` keys. {Request} detects this shape and returns a {Page}
+  # instead of a bare Hash. The `next` and `previous` values are opaque request bodies —
+  # call {#next_page} or {#previous_page} to fetch the adjacent page; do not construct or modify them.
+  #
+  # @example
+  #   page = WebFunction::Request.execute(
+  #     "https://api.example.com/list-people",
+  #     args: { filters: { first_name: "Joe" } },
+  #   )
+  #   page.page        # => [{ "person_id" => "...", ... }, ...]
+  #   page.next?       # => true
+  #   next_page = page.next_page
+  #   next_page.previous? # => true
+  #
+  # See the [pagination specification][0] for the full contract.
+  #
+  # [0]: https://webfunction.org/pagination
+  #
+  class Page
+    include Enumerable
+
+    def initialize(page:, next_body:, previous_body:, url:, bearer_auth: nil, version: nil)
+      @page = page
+      @next_body = next_body
+      @previous_body = previous_body
+      @url = url
+      @bearer_auth = bearer_auth
+      @version = version
+    end
+
+    class << self
+      # Whether +response+ matches the paginated response shape.
+      #
+      # @param response [Object] A parsed JSON response
+      #
+      # @return [Boolean]
+      #
+      def paginated?(response)
+        response.is_a?(Hash) &&
+          response.key?("page") &&
+          response.key?("next") &&
+          response.key?("previous") &&
+          response["page"].is_a?(Array) &&
+          (response["next"].nil? || response["next"].is_a?(Hash)) &&
+          (response["previous"].nil? || response["previous"].is_a?(Hash))
+      end
+
+      # Wraps a paginated response in a {Page}, or returns +response+ unchanged.
+      #
+      # @param response [Object] A parsed JSON response
+      # @param request [Request] The request that produced the response
+      #
+      # @return [Page, Object]
+      #
+      def wrap(response, request:)
+        return response unless paginated?(response)
+
+        new(
+          page: response["page"],
+          next_body: response["next"],
+          previous_body: response["previous"],
+          url: request.url,
+          bearer_auth: request.bearer_auth,
+          version: request.version,
+        )
+      end
+    end
+
+    # The items on the current page.
+    #
+    # @return [Array]
+    #
+    attr_reader :page
+
+    # Whether a next page is available.
+    #
+    # @return [Boolean]
+    #
+    def next?
+      !@next_body.nil?
+    end
+
+    # Whether a previous page is available.
+    #
+    # @return [Boolean]
+    #
+    def previous?
+      !@previous_body.nil?
+    end
+
+    # Fetches the next page by posting the opaque `next` body to the same endpoint.
+    #
+    # @return [Page, nil] The next page, or `nil` if there is none
+    #
+    def next_page
+      fetch(@next_body)
+    end
+
+    # Fetches the previous page by posting the opaque `previous` body to the same endpoint.
+    #
+    # @return [Page, nil] The previous page, or `nil` if there is none
+    #
+    def previous_page
+      fetch(@previous_body)
+    end
+
+    # Iterates over the items on the current page.
+    #
+    # @yield [Object] Each item in {#page}
+    #
+    # @return [Enumerator, Page]
+    #
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @page.each(&block)
+      self
+    end
+
+    private
+
+    def fetch(body)
+      return nil if body.nil?
+
+      Request.execute(@url, bearer_auth: @bearer_auth, version: @version, args: body)
+    end
+  end
+end

data/lib/webfunction/pipeline.rb

@@ -0,0 +1,91 @@
+# 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
+      @steps = []
+      @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}]")
+
+      @steps << step
+      @promises << promise
+
+      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 = Request.execute(@url, args: {
+          steps: @steps,
+          returns: "$",
+        },
+        )
+
+        responses.each_with_index do |response, index|
+          @promises[index].value = response
+        end
+
+        reset!
+
+        responses
+      when :last
+        response = Request.execute(@url, args: {
+          steps: @steps,
+          returns: "$[-1:]",
+        },
+        )
+
+        @promises.last.value = response
+
+        reset!
+
+        response
+      else
+        response = Request.execute(@url, args: {
+          steps: @steps,
+          returns: returns,
+        },
+        )
+
+        reset!
+
+        response
+      end
+    end
+
+    # Resets the pipeline.
+    #
+    # @return [void]
+    #
+    def reset!
+      @steps = []
+      @promises = []
+    end
+  end
+end