coarnotify 0.1.0

data/lib/coarnotify/exceptions.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Coarnotify
+  # Base class for all exceptions in the coarnotifyrb library
+  class NotifyException < StandardError
+  end
+
+  # Exception class for validation errors.
+  #
+  # This class is designed to be thrown and caught and to collect validation errors
+  # as it passes through the validation pipeline.
+  #
+  # For example an object validator may do something like this:
+  #
+  #   def validate
+  #     ve = ValidationError.new
+  #     ve.add_error(prop_name, "#{prop_name} is a required field")
+  #     raise ve if ve.has_errors?
+  #     true
+  #   end
+  #
+  # If this is called by a subclass which is also validating, then this may be used
+  # like this:
+  #
+  #   def validate
+  #     ve = ValidationError.new
+  #     begin
+  #       super
+  #     rescue ValidationError => superve
+  #       ve = superve
+  #     end
+  #
+  #     ve.add_error(prop_name, "#{prop_name} is a required field")
+  #     raise ve if ve.has_errors?
+  #     true
+  #   end
+  #
+  # By the time the ValidationError is finally raised to the top, it will contain
+  # all the validation errors from the various levels of validation that have been
+  # performed.
+  #
+  # The errors are stored as a multi-level hash with the keys at the top level
+  # being the fields in the data structure which have errors, and within the value
+  # for each key there are two possible keys:
+  #
+  # * errors: an array of error messages for this field
+  # * nested: a hash of further errors for nested fields
+  #
+  #   {
+  #     "key1" => {
+  #       "errors" => ["error1", "error2"],
+  #       "nested" => {
+  #         "key2" => {
+  #           "errors" => ["error3"]
+  #         }
+  #       }
+  #     }
+  #   }
+  class ValidationError < NotifyException
+    attr_reader :errors
+
+    # Create a new ValidationError with the given errors hash
+    #
+    # @param errors [Hash] The errors hash to initialize with
+    def initialize(errors = {})
+      super()
+      @errors = errors
+    end
+
+    # Record an error on the supplied key with the message value
+    #
+    # @param key [String] the key for which an error is to be recorded
+    # @param value [String] the error message
+    def add_error(key, value)
+      @errors[key] ||= { "errors" => [] }
+      @errors[key]["errors"] << value
+    end
+
+    # Take an existing ValidationError and add it as a nested set of errors under the supplied key
+    #
+    # @param key [String] the key under which all the nested validation errors should go
+    # @param subve [ValidationError] the existing ValidationError object
+    def add_nested_errors(key, subve)
+      @errors[key] ||= { "errors" => [] }
+      @errors[key]["nested"] ||= {}
+
+      subve.errors.each do |k, v|
+        @errors[key]["nested"][k] = v
+      end
+    end
+
+    # Are there any errors registered
+    #
+    # @return [Boolean] true if there are errors, false otherwise
+    def has_errors?
+      !@errors.empty?
+    end
+
+    # String representation of the errors
+    #
+    # @return [String] string representation of the errors hash
+    def to_s
+      @errors.to_s
+    end
+  end
+end

data/lib/coarnotify/factory.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative 'core/activity_streams2'
+require_relative 'core/notify'
+require_relative 'patterns/accept'
+require_relative 'patterns/announce_endorsement'
+require_relative 'patterns/announce_relationship'
+require_relative 'patterns/announce_review'
+require_relative 'patterns/announce_service_result'
+require_relative 'patterns/reject'
+require_relative 'patterns/request_endorsement'
+require_relative 'patterns/request_review'
+require_relative 'patterns/tentatively_accept'
+require_relative 'patterns/tentatively_reject'
+require_relative 'patterns/unprocessable_notification'
+require_relative 'patterns/undo_offer'
+require_relative 'exceptions'
+
+module Coarnotify
+  # Factory for producing the correct model based on the type or data within a payload
+  module Factory
+    # Factory for producing the correct model based on the type or data within a payload
+    class COARNotifyFactory
+      # The list of model classes recognised by this factory
+      MODELS = [
+        Patterns::Accept,
+        Patterns::AnnounceEndorsement,
+        Patterns::AnnounceRelationship,
+        Patterns::AnnounceReview,
+        Patterns::AnnounceServiceResult,
+        Patterns::Reject,
+        Patterns::RequestEndorsement,
+        Patterns::RequestReview,
+        Patterns::TentativelyAccept,
+        Patterns::TentativelyReject,
+        Patterns::UnprocessableNotification,
+        Patterns::UndoOffer
+      ]
+
+      # Get the model class based on the supplied types. The returned value is the class, not an instance.
+      #
+      # This is achieved by inspecting all of the known types in MODELS, and performing the following
+      # calculation:
+      #
+      # 1. If the supplied types are a subset of the model types, then this is a candidate, keep a reference to it
+      # 2. If the candidate fit is exact (supplied types and model types are the same), return the class
+      # 3. If the class is a better fit than the last candidate, update the candidate. If the fit is exact, return the class
+      # 4. Once we have run out of models to check, return the best candidate (or nil if none found)
+      #
+      # @param incoming_types [String, Array<String>] a single type or array of types
+      # @return [Class, nil] A class representing the best fit for the supplied types, or nil if no match
+      def self.get_by_types(incoming_types)
+        incoming_types = [incoming_types] unless incoming_types.is_a?(Array)
+
+        candidate = nil
+        candidate_fit = nil
+
+        MODELS.each do |m|
+          document_types = m.type_constant
+          document_types = [document_types] unless document_types.is_a?(Array)
+          
+          if document_types.to_set.subset?(incoming_types.to_set)
+            if candidate_fit.nil?
+              candidate = m
+              candidate_fit = incoming_types.length - document_types.length
+              return candidate if candidate_fit == 0
+            else
+              fit = incoming_types.length - document_types.length
+              return m if fit == 0
+              if fit.abs < candidate_fit.abs
+                candidate = m
+                candidate_fit = fit
+              end
+            end
+          end
+        end
+
+        candidate
+      end
+
+      # Get an instance of a model based on the data provided.
+      #
+      # Internally this calls get_by_types to determine the class to instantiate, and then creates an instance of that
+      # using the supplied options.
+      #
+      # If a model cannot be found that matches the data, a NotifyException is raised.
+      #
+      # @param data [Hash] The raw stream data to parse and instantiate around
+      # @param options [Hash] any options to pass to the object constructor
+      # @return [Core::Notify::NotifyPattern] A NotifyPattern of the correct type, wrapping the data
+      def self.get_by_object(data, **options)
+        stream = Core::ActivityStreams2::ActivityStream.new(data)
+
+        types = stream.get_property(Core::ActivityStreams2::Properties::TYPE)
+        raise NotifyException, "No type found in object" if types.nil?
+
+        klazz = get_by_types(types)
+        raise NotifyException, "No matching pattern found for types: #{types}" if klazz.nil?
+
+        klazz.new(stream: data, **options)
+      end
+
+      # Register a new model with the factory
+      #
+      # @param model [Class] the model class to register
+      def self.register(model)
+        existing = get_by_types(model.type_constant)
+        MODELS.delete(existing) if existing
+        MODELS << model
+      end
+    end
+  end
+end

data/lib/coarnotify/http.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Coarnotify
+  # HTTP layer interface and default implementation using Net::HTTP
+  module Http
+    # Interface for the HTTP layer
+    #
+    # This defines the methods which need to be implemented in order for the client to fully operate
+    class HttpLayer
+      # Make an HTTP POST request to the supplied URL with the given body data, and headers
+      #
+      # args and kwargs can be used to pass implementation-specific parameters
+      #
+      # @param url [String] the request URL
+      # @param data [String] the body data
+      # @param headers [Hash] HTTP headers as a hash to include in the request
+      # @param args [Array] argument list to pass on to the implementation
+      # @param kwargs [Hash] keyword arguments to pass on to the implementation
+      # @return [HttpResponse] the HTTP response
+      def post(url, data, headers = {}, *args, **kwargs)
+        raise NotImplementedError
+      end
+
+      # Make an HTTP GET request to the supplied URL with the given headers
+      #
+      # args and kwargs can be used to pass implementation-specific parameters
+      #
+      # @param url [String] the request URL
+      # @param headers [Hash] HTTP headers as a hash to include in the request
+      # @param args [Array] argument list to pass on to the implementation
+      # @param kwargs [Hash] keyword arguments to pass on to the implementation
+      # @return [HttpResponse] the HTTP response
+      def get(url, headers = {}, *args, **kwargs)
+        raise NotImplementedError
+      end
+    end
+
+    # Interface for the HTTP response object
+    #
+    # This defines the methods which need to be implemented in order for the client to fully operate
+    class HttpResponse
+      # Get the value of a header from the response
+      #
+      # @param header_name [String] the name of the header
+      # @return [String] the header value
+      def header(header_name)
+        raise NotImplementedError
+      end
+
+      # Get the status code of the response
+      #
+      # @return [Integer] the status code
+      def status_code
+        raise NotImplementedError
+      end
+    end
+
+    #######################################
+    ## Implementations using Net::HTTP
+
+    # Implementation of the HTTP layer using Net::HTTP. This is the default implementation
+    # used when no other implementation is supplied
+    class NetHttpLayer < HttpLayer
+      # Make an HTTP POST request to the supplied URL with the given body data, and headers
+      #
+      # args and kwargs can be used to pass additional parameters to the Net::HTTP request,
+      # such as authentication credentials, etc.
+      #
+      # @param url [String] the request URL
+      # @param data [String] the body data
+      # @param headers [Hash] HTTP headers as a hash to include in the request
+      # @param args [Array] argument list (unused in this implementation)
+      # @param kwargs [Hash] keyword arguments (unused in this implementation)
+      # @return [NetHttpResponse] the HTTP response
+      def post(url, data, headers = {}, *args, **kwargs)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        headers.each { |key, value| request[key] = value }
+        request.body = data
+
+        response = http.request(request)
+        NetHttpResponse.new(response)
+      end
+
+      # Make an HTTP GET request to the supplied URL with the given headers
+      #
+      # args and kwargs can be used to pass additional parameters to the Net::HTTP request,
+      # such as authentication credentials, etc.
+      #
+      # @param url [String] the request URL
+      # @param headers [Hash] HTTP headers as a hash to include in the request
+      # @param args [Array] argument list (unused in this implementation)
+      # @param kwargs [Hash] keyword arguments (unused in this implementation)
+      # @return [NetHttpResponse] the HTTP response
+      def get(url, headers = {}, *args, **kwargs)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+
+        request = Net::HTTP::Get.new(uri.request_uri)
+        headers.each { |key, value| request[key] = value }
+
+        response = http.request(request)
+        NetHttpResponse.new(response)
+      end
+    end
+
+    # Implementation of the HTTP response object using Net::HTTP
+    #
+    # This wraps the Net::HTTP response object and provides the interface required by the client
+    class NetHttpResponse < HttpResponse
+      # Construct the object as a wrapper around the original Net::HTTP response object
+      #
+      # @param resp [Net::HTTPResponse] response object from Net::HTTP
+      def initialize(resp)
+        @resp = resp
+      end
+
+      # Get the value of a header from the response
+      #
+      # @param header_name [String] the name of the header
+      # @return [String] the header value
+      def header(header_name)
+        @resp[header_name]
+      end
+
+      # Get the status code of the response
+      #
+      # @return [Integer] the status code
+      def status_code
+        @resp.code.to_i
+      end
+
+      # Get the original Net::HTTP response object
+      #
+      # @return [Net::HTTPResponse] the original response object
+      def net_http_response
+        @resp
+      end
+    end
+  end
+end

data/lib/coarnotify/patterns/accept.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../core/notify'
+require_relative '../core/activity_streams2'
+require_relative '../exceptions'
+
+module Coarnotify
+  module Patterns
+    # Pattern to represent an Accept notification
+    # https://coar-notify.net/specification/1.0.0/accept/
+    class Accept < Core::Notify::NotifyPattern
+      include Core::Notify::NestedPatternObjectMixin
+
+      # The Accept type
+      def self.type_constant
+        Core::ActivityStreams2::ActivityStreamsTypes::ACCEPT
+      end
+
+      # Validate the Accept pattern.
+      #
+      # In addition to the base validation, this:
+      #
+      # * Makes inReplyTo required
+      # * Requires the inReplyTo value to be the same as the object.id value
+      #
+      # @return [Boolean] true if valid, otherwise raises ValidationError
+      def validate
+        ve = ValidationError.new
+        begin
+          super
+        rescue ValidationError => superve
+          ve = superve
+        end
+
+        # Technically, no need to validate the value, as this is handled by the superclass,
+        # but leaving it in for completeness
+        required_and_validate(ve, Core::ActivityStreams2::Properties::IN_REPLY_TO, in_reply_to)
+
+        objid = object&.id
+        if in_reply_to != objid
+          ve.add_error(Core::ActivityStreams2::Properties::IN_REPLY_TO,
+                       "Expected inReplyTo id to be the same as the nested object id. inReplyTo: #{in_reply_to}, object.id: #{objid}")
+        end
+
+        raise ve if ve.has_errors?
+        true
+      end
+    end
+  end
+end

data/lib/coarnotify/patterns/announce_endorsement.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative '../core/notify'
+require_relative '../core/activity_streams2'
+
+module Coarnotify
+  module Patterns
+    # Pattern to represent an AnnounceEndorsement notification
+    class AnnounceEndorsement < Core::Notify::NotifyPattern
+      def self.type_constant
+        [Core::ActivityStreams2::ActivityStreamsTypes::ANNOUNCE, Core::Notify::NotifyTypes::ENDORSEMENT_ACTION]
+      end
+
+      # Get a context specific to Announce Endorsement
+      #
+      # @return [AnnounceEndorsementContext, nil] The Announce Endorsement context object
+      def context
+        c = get_property(Core::ActivityStreams2::Properties::CONTEXT)
+        if c
+          AnnounceEndorsementContext.new(stream: c, validate_stream_on_construct: false,
+                                         validate_properties: @validate_properties, validators: @validators,
+                                         validation_context: Core::ActivityStreams2::Properties::CONTEXT,
+                                         properties_by_reference: @properties_by_reference)
+        end
+      end
+
+      # Set the context property of the notification
+      #
+      # @param value [AnnounceEndorsementContext] the context to set
+      def context=(value)
+        set_property(Core::ActivityStreams2::Properties::CONTEXT, value.doc)
+      end
+
+      # Extends the base validation to make `context` required
+      #
+      # @return [Boolean] true if valid, otherwise raises ValidationError
+      def validate
+        ve = Core::Notify::ValidationError.new
+
+        begin
+          super
+        rescue Core::Notify::ValidationError => superve
+          ve = superve
+        end
+
+        required_and_validate(ve, Core::ActivityStreams2::Properties::CONTEXT, context)
+
+        raise ve if ve.has_errors?
+        true
+      end
+    end
+
+    # Announce Endorsement context object, which extends the base NotifyObject
+    # to allow us to pass back a custom AnnounceEndorsementItem
+    class AnnounceEndorsementContext < Core::Notify::NotifyObject
+      # Get a custom AnnounceEndorsementItem
+      #
+      # @return [AnnounceEndorsementItem, nil] the Announce Endorsement Item
+      def item
+        i = get_property(Core::Notify::NotifyProperties::ITEM)
+        if i
+          AnnounceEndorsementItem.new(stream: i, validate_stream_on_construct: false,
+                                      validate_properties: @validate_properties, validators: @validators,
+                                      validation_context: Core::Notify::NotifyProperties::ITEM,
+                                      properties_by_reference: @properties_by_reference)
+        end
+      end
+
+      # Set the item property
+      #
+      # @param value [AnnounceEndorsementItem] the item to set
+      def item=(value)
+        set_property(Core::Notify::NotifyProperties::ITEM, value.doc)
+      end
+    end
+
+    # Announce Endorsement Item, which extends the base NotifyItem to provide
+    # additional validation
+    class AnnounceEndorsementItem < Core::Notify::NotifyItem
+      # Extends the base validation with validation custom to Announce Endorsement notifications
+      #
+      # * Adds type validation, which the base NotifyItem does not apply
+      # * Requires the mediaType value
+      #
+      # @return [Boolean] true if valid, otherwise raises a ValidationError
+      def validate
+        ve = Core::Notify::ValidationError.new
+
+        begin
+          super
+        rescue Core::Notify::ValidationError => superve
+          ve = superve
+        end
+
+        required_and_validate(ve, Core::ActivityStreams2::Properties::TYPE, type)
+        required(ve, Core::Notify::NotifyProperties::MEDIA_TYPE, media_type)
+
+        raise ve if ve.has_errors?
+        true
+      end
+    end
+  end
+end

data/lib/coarnotify/patterns/announce_relationship.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative '../core/notify'
+require_relative '../core/activity_streams2'
+
+module Coarnotify
+  module Patterns
+    # Pattern to represent an AnnounceRelationship notification
+    class AnnounceRelationship < Core::Notify::NotifyPattern
+      def self.type_constant
+        [Core::ActivityStreams2::ActivityStreamsTypes::ANNOUNCE, Core::Notify::NotifyTypes::RELATIONSHIP_ACTION]
+      end
+
+      # Custom getter to retrieve the object property as an AnnounceRelationshipObject
+      #
+      # @return [AnnounceRelationshipObject, nil] the object
+      def object
+        o = get_property(Core::ActivityStreams2::Properties::OBJECT)
+        if o
+          AnnounceRelationshipObject.new(stream: o, validate_stream_on_construct: false,
+                                         validate_properties: @validate_properties, validators: @validators,
+                                         validation_context: Core::ActivityStreams2::Properties::OBJECT,
+                                         properties_by_reference: @properties_by_reference)
+        end
+      end
+
+      # Set the object property of the notification
+      #
+      # @param value [AnnounceRelationshipObject] the object to set
+      def object=(value)
+        set_property(Core::ActivityStreams2::Properties::OBJECT, value.doc)
+      end
+
+      # Extends the base validation to make `context` required
+      #
+      # @return [Boolean] true if valid, otherwise raises ValidationError
+      def validate
+        ve = Core::Notify::ValidationError.new
+
+        begin
+          super
+        rescue Core::Notify::ValidationError => superve
+          ve = superve
+        end
+
+        required_and_validate(ve, Core::ActivityStreams2::Properties::CONTEXT, context)
+
+        raise ve if ve.has_errors?
+        true
+      end
+    end
+
+    # Custom object class for Announce Relationship to apply the custom validation
+    class AnnounceRelationshipObject < Core::Notify::NotifyObject
+      # Extend the base validation to include the following constraints:
+      #
+      # * The object type is required and must validate
+      # * The as:subject property is required
+      # * The as:object property is required
+      # * The as:relationship property is required
+      #
+      # @return [Boolean] true if validation passes, otherwise raise a ValidationError
+      def validate
+        ve = Core::Notify::ValidationError.new
+
+        begin
+          super
+        rescue Core::Notify::ValidationError => superve
+          ve = superve
+        end
+
+        required_and_validate(ve, Core::ActivityStreams2::Properties::TYPE, type)
+        required_and_validate(ve, Core::ActivityStreams2::Properties::SUBJECT_TRIPLE, subject)
+        required_and_validate(ve, Core::ActivityStreams2::Properties::OBJECT_TRIPLE, object_triple)
+        required_and_validate(ve, Core::ActivityStreams2::Properties::RELATIONSHIP_TRIPLE, relationship)
+
+        raise ve if ve.has_errors?
+        true
+      end
+    end
+  end
+end