coarnotify 0.1.0

data/lib/coarnotify/server.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'factory'
+
+module Coarnotify
+  # Supporting classes for COAR Notify server implementations
+  module Server
+    # An object representing the response from a COAR Notify server.
+    #
+    # Server implementations should construct and return this object with the appropriate properties
+    # when implementing the COARNotifyServiceBinding#notification_received binding
+    class COARNotifyReceipt
+      # The status code for a created resource
+      CREATED = 201
+
+      # The status code for an accepted request
+      ACCEPTED = 202
+
+      attr_reader :status, :location
+
+      # Construct a new COARNotifyReceipt object with the status code and location URL (optional)
+      #
+      # @param status [Integer] the HTTP status code, should be one of the constants CREATED (201) or ACCEPTED (202)
+      # @param location [String, nil] the HTTP URI for the resource that was created (if present)
+      def initialize(status, location = nil)
+        @status = status
+        @location = location
+      end
+    end
+
+    # Interface for implementing a COAR Notify server binding.
+    #
+    # Server implementation should extend this class and implement the notification_received method
+    #
+    # That method will receive a NotifyPattern object, which will be one of the known types
+    # and should return a COARNotifyReceipt object with the appropriate status code and location URL
+    class COARNotifyServiceBinding
+      # Process the receipt of the given notification, and respond with an appropriate receipt object
+      #
+      # @param notification [Core::Notify::NotifyPattern] the notification object received
+      # @return [COARNotifyReceipt] the receipt object to send back to the client
+      def notification_received(notification)
+        raise NotImplementedError
+      end
+    end
+
+    # An exception class for server errors in the COAR Notify server implementation.
+    #
+    # The web layer of your server implementation should be able to intercept this from the
+    # COARNotifyServer#receive method and return the appropriate HTTP status code and message to the
+    # user in its standard way.
+    class COARNotifyServerError < StandardError
+      attr_reader :status, :message
+
+      # Construct a new COARNotifyServerError with the given status code and message
+      #
+      # @param status [Integer] HTTP Status code to respond to the client with
+      # @param msg [String] Message to send back to the client
+      def initialize(status, msg)
+        @status = status
+        @message = msg
+        super(msg)
+      end
+    end
+
+    # The main entrypoint to the COAR Notify server implementation.
+    #
+    # The web layer of your application should pass the json/raw payload of any incoming notification to the
+    # receive method, which will parse the payload and pass it to the COARNotifyServiceBinding#notification_received
+    # method of your service implementation
+    #
+    # This object should be constructed with your service implementation passed to it, for example:
+    #
+    #   server = COARNotifyServer.new(MyServiceBinding.new)
+    #   begin
+    #     response = server.receive(request.body)
+    #     # return response as JSON
+    #   rescue COARNotifyServerError => e
+    #     # return error with status e.status and message e.message
+    #   end
+    class COARNotifyServer
+      # Construct a new COARNotifyServer with the given service implementation
+      #
+      # @param service_impl [COARNotifyServiceBinding] Your service implementation
+      def initialize(service_impl)
+        @service_impl = service_impl
+      end
+
+      # Receive an incoming notification as JSON, parse and validate (optional) and then pass to the
+      # service implementation
+      #
+      # @param raw [Hash, String] The JSON representation of the data, either as a string or a hash
+      # @param validate [Boolean] Whether to validate the notification before passing to the service implementation
+      # @return [COARNotifyReceipt] The COARNotifyReceipt response from the service implementation
+      def receive(raw, validate: true)
+        raw = JSON.parse(raw) if raw.is_a?(String)
+
+        obj = Factory::COARNotifyFactory.get_by_object(raw, validate_stream_on_construct: false)
+        if validate
+          begin
+            obj.validate
+          rescue ValidationError => e
+            raise COARNotifyServerError.new(400, "Invalid notification")
+          end
+        end
+
+        @service_impl.notification_received(obj)
+      end
+    end
+  end
+end

data/lib/coarnotify/validate.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'set'
+
+module Coarnotify
+  # This module provides a set of validation functions that can be used to validate properties on objects.
+  # It also contains a Validator class which is used to wrap the protocol-wide validation rules which
+  # are shared across all objects.
+  module Validate
+    REQUIRED_MESSAGE = "`%s` is a required field"
+
+    # A wrapper around a set of validation rules which can be used to select the appropriate validator
+    # in a given context.
+    #
+    # The validation rules are structured as follows:
+    #
+    #   {
+    #     "<property>" => {
+    #       "default" => default_validator_function,
+    #       "context" => {
+    #         "<context>" => {
+    #           "default" => default_validator_function
+    #         }
+    #       }
+    #     }
+    #   }
+    #
+    # Here the <property> key is the name of the property being validated, which may be a string (the property name)
+    # or an array of strings (the property name and the namespace for the property name).
+    #
+    # If a context is provided, then if the top level property is being validated, and it appears inside a field
+    # present in the context then the default validator at the top level is overridden by the default validator
+    # in the context.
+    class Validator
+      attr_reader :rules
+
+      # Create a new validator with the given rules
+      #
+      # @param rules [Hash] The rules to use for validation
+      def initialize(rules)
+        @rules = rules
+      end
+
+      # Get the validation function for the given property in the given context
+      #
+      # @param property [String, Array] the property to get the validation function for
+      # @param context [String, Array] the context in which the property is being validated
+      # @return [Proc] a function which can be used to validate the property
+      def get(property, context = nil)
+        default = @rules.dig(property, "default")
+        if context
+          # FIXME: down the line this might need to become recursive
+          specific = @rules.dig(property, "context", context, "default")
+          return specific if specific
+        end
+        default
+      end
+
+      # Add additional rules to this validator
+      #
+      # @param rules [Hash] additional rules to merge
+      def add_rules(rules)
+        @rules = merge_dicts_recursive(@rules, rules)
+      end
+
+      private
+
+      def merge_dicts_recursive(dict1, dict2)
+        merged = dict1.dup
+        dict2.each do |key, value|
+          if merged.key?(key) && merged[key].is_a?(Hash) && value.is_a?(Hash)
+            merged[key] = merge_dicts_recursive(merged[key], value)
+          else
+            merged[key] = value
+          end
+        end
+        merged
+      end
+    end
+
+    # URI validation regular expressions
+    URI_RE = /^(([^:\/?#]+):)?(\/\/([^\/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?/
+    SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+\-.]*$/
+    IPV6_RE = /(?:^|(?<=\s))\[{0,1}(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))\]{0,1}(?=\s|$)/
+
+    HOSTPORT_RE = /^(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+(?:[A-Z]{2,6}\.?|[A-Z0-9-]{2,}\.?)|localhost|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}|(?:^|(?<=\s))(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))(?=\s|$))(?::\d+)?$/i
+
+    MARK = "\\-_.!~*'()"
+    UNRESERVED = "a-zA-Z0-9#{MARK}"
+    PCHARS = "#{UNRESERVED}:@&=+$,%/;"
+    PATH_RE = /^#{Regexp.escape('/')}?[#{PCHARS}]*$/
+
+    RESERVED = ";/?:@&=+$,"
+    URIC = "#{RESERVED}#{UNRESERVED}%"
+    FREE_RE = /^[#{URIC}]+$/
+
+    USERINFO_RE = /^[#{UNRESERVED}%;:&=+$,]*$/
+
+    # Validate that the given string is an absolute URI
+    #
+    # @param obj [Object] The Notify object to which the property being validated belongs
+    # @param uri [String] The string that claims to be an absolute URI
+    # @return [Boolean] true if the URI is valid, otherwise ArgumentError is raised
+    def self.absolute_uri(obj, uri)
+      m = URI_RE.match(uri)
+      raise ArgumentError, "Invalid URI" unless m
+
+      # URI must be absolute, so requires a scheme
+      raise ArgumentError, "URI requires a scheme (this may be a relative rather than absolute URI)" unless m[2]
+
+      scheme = m[2]
+      authority = m[4]
+      path = m[5]
+      query = m[7]
+      fragment = m[9]
+
+      # scheme must be alpha followed by alphanum or +, -, or .
+      if scheme
+        raise ArgumentError, "Invalid URI scheme `#{scheme}`" unless SCHEME_RE.match?(scheme)
+      end
+
+      if authority
+        userinfo = nil
+        hostport = authority
+        if authority.include?("@")
+          userinfo, hostport = authority.split("@", 2)
+        end
+        if userinfo
+          raise ArgumentError, "Invalid URI authority `#{authority}`" unless USERINFO_RE.match?(userinfo)
+        end
+        # determine if the domain is ipv6
+        if hostport.start_with?("[")    # ipv6 with an optional port
+          port_separator = hostport.rindex("]:")
+          port = nil
+          if port_separator
+            port = hostport[port_separator+2..-1]
+            host = hostport[1...port_separator]
+          else
+            host = hostport[1..-2]
+          end
+          raise ArgumentError, "Invalid URI authority `#{authority}`" unless IPV6_RE.match?(host)
+          if port
+            begin
+              Integer(port)
+            rescue ArgumentError
+              raise ArgumentError, "Invalid URI port `#{port}`"
+            end
+          end
+        else
+          raise ArgumentError, "Invalid URI authority `#{authority}`" unless HOSTPORT_RE.match?(hostport)
+        end
+      end
+
+      if path
+        raise ArgumentError, "Invalid URI path `#{path}`" unless PATH_RE.match?(path)
+      end
+
+      if query
+        raise ArgumentError, "Invalid URI query `#{query}`" unless FREE_RE.match?(query)
+      end
+
+      if fragment
+        raise ArgumentError, "Invalid URI fragment `#{fragment}`" unless FREE_RE.match?(fragment)
+      end
+
+      true
+    end
+
+    # Validate that the given string is an absolute HTTP URI (i.e. a URL)
+    #
+    # @param obj [Object] The Notify object to which the property being validated belongs
+    # @param url [String] The string that claims to be an HTTP URI
+    # @return [Boolean] true if the URI is valid, otherwise ArgumentError is raised
+    def self.url(obj, url)
+      absolute_uri(obj, url)
+      o = URI.parse(url)
+      raise ArgumentError, "URL scheme must be http or https" unless %w[http https].include?(o.scheme)
+      raise ArgumentError, "Does not appear to be a valid URL" if o.host.nil? || o.host.empty?
+      true
+    end
+
+    # Closure that returns a validation function that checks that the value is one of the given values
+    #
+    # @param values [Array<String>] The list of values to choose from
+    # @return [Proc] a validation function
+    def self.one_of(values)
+      proc do |obj, x|
+        unless values.include?(x)
+          raise ArgumentError, "`#{x}` is not one of the valid values: #{values}"
+        end
+        true
+      end
+    end
+
+    # Closure that returns a validation function that checks that a list of values contains at least one
+    # of the given values
+    #
+    # @param values [Array<String>] The list of values to choose from
+    # @return [Proc] a validation function
+    def self.at_least_one_of(values)
+      proc do |obj, x|
+        x = [x] unless x.is_a?(Array)
+
+        found = x.any? { |entry| values.include?(entry) }
+
+        unless found
+          # if we don't find one of the document values in the list of "at least one of" values,
+          # raise an exception
+          raise ArgumentError, "`#{x}` is not one of the valid values: #{values}"
+        end
+
+        true
+      end
+    end
+
+    # Closure that returns a validation function that checks the provided values contain the required value
+    #
+    # @param value [String, Array<String>] The value(s) that must be present
+    # @return [Proc] a validation function
+    def self.contains(value)
+      values = value.is_a?(Array) ? value : [value]
+      values_set = values.to_set
+
+      proc do |obj, x|
+        x = [x] unless x.is_a?(Array)
+        x_set = x.to_set
+
+        intersection = x_set & values_set
+        unless intersection == values_set
+          raise ArgumentError, "`#{x}` does not contain the required value(s): #{values}"
+        end
+        true
+      end
+    end
+
+    # Validate that the given value is of the correct type for the object
+    #
+    # @param obj [Object] the notify object being validated
+    # @param value [String, Array<String>] the type being validated
+    # @return [Boolean] true if the type is valid, otherwise ArgumentError is raised
+    def self.type_checker(obj, value)
+      if obj.respond_to?(:allowed_types)
+        allowed = obj.allowed_types
+        return true if allowed.empty?
+        validator = one_of(allowed)
+        validator.call(obj, value)
+      elsif obj.respond_to?(:type_constant)
+        ty = obj.type_constant
+        validator = contains(ty)
+        validator.call(obj, value)
+      end
+      true
+    end
+  end
+end

data/lib/coarnotify/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# lib/coarnotify/version.rb
+module Coarnotify
+  # Version of the coarnotifyrb gem
+  VERSION = "0.1.0"
+end
+  

data/lib/coarnotify.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# This is the base of the coarnotifyrb module.
+#
+# In here you will find
+# a full set of model objects for all the Notify Patterns documented in
+# https://coar-notify.net/specification/1.0.1/
+#
+# You will also find a client library that will allow you to send notifications
+# to an inbox, and a server library that will allow you to write a service
+# binding to your own systems to receive notifications via an inbox.
+#
+# There are also unit tests demonstrating the various features of the system,
+# integration tests which can be run against a remote inbox, and a
+# stand-alone inbox you can use for local testing.
+
+require_relative 'coarnotify/version'
+require_relative 'coarnotify/exceptions'
+require_relative 'coarnotify/validate'
+require_relative 'coarnotify/core/activity_streams2'
+require_relative 'coarnotify/core/notify'
+require_relative 'coarnotify/http'
+require_relative 'coarnotify/patterns/accept'
+require_relative 'coarnotify/patterns/announce_endorsement'
+require_relative 'coarnotify/patterns/announce_relationship'
+require_relative 'coarnotify/patterns/announce_review'
+require_relative 'coarnotify/patterns/announce_service_result'
+require_relative 'coarnotify/patterns/reject'
+require_relative 'coarnotify/patterns/request_endorsement'
+require_relative 'coarnotify/patterns/request_review'
+require_relative 'coarnotify/patterns/tentatively_accept'
+require_relative 'coarnotify/patterns/tentatively_reject'
+require_relative 'coarnotify/patterns/undo_offer'
+require_relative 'coarnotify/patterns/unprocessable_notification'
+require_relative 'coarnotify/factory'
+require_relative 'coarnotify/client'
+require_relative 'coarnotify/server'
+
+# Main module for the COAR Notify Ruby implementation
+module Coarnotify
+  # Convenience method to create a new COAR Notify client
+  #
+  # @param inbox_url [String, nil] HTTP URI of the inbox to communicate with by default
+  # @param http_layer [Http::HttpLayer, nil] An implementation of the HttpLayer interface
+  # @return [Client::COARNotifyClient] a new client instance
+  def self.client(inbox_url: nil, http_layer: nil)
+    Client::COARNotifyClient.new(inbox_url: inbox_url, http_layer: http_layer)
+  end
+
+  # Convenience method to create a new COAR Notify server
+  #
+  # @param service_impl [Server::COARNotifyServiceBinding] Your service implementation
+  # @return [Server::COARNotifyServer] a new server instance
+  def self.server(service_impl)
+    Server::COARNotifyServer.new(service_impl)
+  end
+
+  # Convenience method to create a pattern from a hash
+  #
+  # @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
+  def self.from_hash(data, **options)
+    Factory::COARNotifyFactory.get_by_object(data, **options)
+  end
+
+  # Convenience method to create a pattern from JSON
+  #
+  # @param json [String] The JSON string 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
+  def self.from_json(json, **options)
+    data = JSON.parse(json)
+    from_hash(data, **options)
+  end
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: coarnotify
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cottage Labs
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: COAR Notify Common Library
+email:
+- us@cottagelabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/coarnotify.rb
+- lib/coarnotify/client.rb
+- lib/coarnotify/core/activity_streams2.rb
+- lib/coarnotify/core/notify.rb
+- lib/coarnotify/exceptions.rb
+- lib/coarnotify/factory.rb
+- lib/coarnotify/http.rb
+- lib/coarnotify/patterns/accept.rb
+- lib/coarnotify/patterns/announce_endorsement.rb
+- lib/coarnotify/patterns/announce_relationship.rb
+- lib/coarnotify/patterns/announce_review.rb
+- lib/coarnotify/patterns/announce_service_result.rb
+- lib/coarnotify/patterns/reject.rb
+- lib/coarnotify/patterns/request_endorsement.rb
+- lib/coarnotify/patterns/request_review.rb
+- lib/coarnotify/patterns/tentatively_accept.rb
+- lib/coarnotify/patterns/tentatively_reject.rb
+- lib/coarnotify/patterns/undo_offer.rb
+- lib/coarnotify/patterns/unprocessable_notification.rb
+- lib/coarnotify/server.rb
+- lib/coarnotify/validate.rb
+- lib/coarnotify/version.rb
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: COAR Notify Common Library
+test_files: []