coarnotify 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c275102a17471d02d892d5fd97cef39a6de4df156789c1b39057deffb3f83b6
+  data.tar.gz: 7667b1a6ff67dab4a44bb3c0f1faac5f5baf9e4300603bc8c82883ba7a30ebb1
+SHA512:
+  metadata.gz: 389e163e70f37372f625466b213a2c67cbd7298d3166d064ad7636298741c6976818b0d0a3a3a85149c7e50b08b30996280d904bd73053bab9fd13087006094b
+  data.tar.gz: '018e0f9c74b240ab33719bda796ebd3644121307cda75a62c713bacd5440fee8a8bdf4c2bd00fd23052eb5bf50714ffc1473f7c0367e74487fc10ab4e08310f8'

data/lib/coarnotify/client.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'exceptions'
+require_relative 'http'
+require_relative 'core/notify'
+
+module Coarnotify
+  # This module contains all the client-specific code for sending notifications
+  # to an inbox and receiving the responses it may return
+  module Client
+    # An object representing the response from a COAR Notify inbox.
+    #
+    # This contains the action that was carried out on the server:
+    #
+    # * CREATED - a new resource was created
+    # * ACCEPTED - the request was accepted, but the resource was not yet created
+    #
+    # In the event that the resource is created, then there will also be a location
+    # URL which will give you access to the resource
+    class NotifyResponse
+      CREATED = "created"
+      ACCEPTED = "accepted"
+
+      attr_reader :action, :location
+
+      # Construct a new NotifyResponse object with the action (created or accepted) and the location URL (optional)
+      #
+      # @param action [String] The action which the server said it took
+      # @param location [String, nil] The HTTP URI for the resource that was created (if present)
+      def initialize(action, location = nil)
+        @action = action
+        @location = location
+      end
+    end
+
+    # The COAR Notify Client, which is the mechanism through which you will interact with external inboxes.
+    #
+    # If you do not supply an inbox URL at construction you will
+    # need to supply it via the inbox_url= setter, or when you send a notification
+    class COARNotifyClient
+      attr_accessor :inbox_url
+
+      # Initialize the 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 to use for sending HTTP requests
+      def initialize(inbox_url: nil, http_layer: nil)
+        @inbox_url = inbox_url
+        @http = http_layer || Http::NetHttpLayer.new
+      end
+
+      # Send the given notification to the inbox. If no inbox URL is provided, the default inbox URL will be used.
+      #
+      # @param notification [Core::Notify::NotifyPattern] The notification object
+      # @param inbox_url [String, nil] The HTTP URI to send the notification to
+      # @param validate [Boolean] Whether to validate the notification before sending
+      # @return [NotifyResponse] a NotifyResponse object representing the response from the server
+      def send(notification, inbox_url: nil, validate: true)
+        inbox_url ||= @inbox_url
+        inbox_url ||= notification.target&.inbox
+        
+        raise ArgumentError, "No inbox URL provided at the client, method, or notification level" if inbox_url.nil?
+
+        if validate
+          begin
+            notification.validate
+          rescue ValidationError => e
+            raise NotifyException, "Attempting to send invalid notification; to override set validate: false when calling this method"
+          end
+        end
+
+        resp = @http.post(inbox_url,
+                          JSON.generate(notification.to_jsonld),
+                          { "Content-Type" => "application/ld+json;profile=\"https://www.w3.org/ns/activitystreams\"" })
+
+        case resp.status_code
+        when 201
+          NotifyResponse.new(NotifyResponse::CREATED, resp.header("Location"))
+        when 202
+          NotifyResponse.new(NotifyResponse::ACCEPTED)
+        else
+          raise NotifyException, "Unexpected response: #{resp.status_code}"
+        end
+      end
+    end
+  end
+end

data/lib/coarnotify/core/activity_streams2.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Coarnotify
+  module Core
+    # This module contains everything COAR Notify needs to know about ActivityStreams 2.0
+    # https://www.w3.org/TR/activitystreams-core/
+    #
+    # It provides knowledge of the essential AS properties and types, and a class to wrap
+    # ActivityStreams objects and provide a simple interface to work with them.
+    #
+    # **NOTE** this is not a complete implementation of AS 2.0, it is **only** what is required
+    # to work with COAR Notify patterns.
+    module ActivityStreams2
+      # Namespace for Activity Streams, to be used to construct namespaced properties used in COAR Notify Patterns
+      ACTIVITY_STREAMS_NAMESPACE = "https://www.w3.org/ns/activitystreams"
+
+      # ActivityStreams 2.0 properties used in COAR Notify Patterns
+      #
+      # These are provided as arrays, where the first element is the property name, and the second element is the namespace.
+      #
+      # These are suitable to be used as property names in all the property getters/setters in the notify pattern objects
+      # and in the validation configuration.
+      module Properties
+        # id property
+        ID = ["id", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # type property
+        TYPE = ["type", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # origin property
+        ORIGIN = ["origin", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # object property
+        OBJECT = ["object", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # target property
+        TARGET = ["target", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # actor property
+        ACTOR = ["actor", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # inReplyTo property
+        IN_REPLY_TO = ["inReplyTo", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # context property
+        CONTEXT = ["context", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # summary property
+        SUMMARY = ["summary", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # as:subject property
+        SUBJECT_TRIPLE = ["as:subject", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # as:object property
+        OBJECT_TRIPLE = ["as:object", ACTIVITY_STREAMS_NAMESPACE].freeze
+
+        # as:relationship property
+        RELATIONSHIP_TRIPLE = ["as:relationship", ACTIVITY_STREAMS_NAMESPACE].freeze
+      end
+
+      # List of all the Activity Streams types COAR Notify may use.
+      #
+      # Note that COAR Notify also has its own custom types and they are defined in
+      # Coarnotify::Core::Notify::NotifyTypes
+      module ActivityStreamsTypes
+        # Activities
+        ACCEPT = "Accept"
+        ANNOUNCE = "Announce"
+        REJECT = "Reject"
+        OFFER = "Offer"
+        TENTATIVE_ACCEPT = "TentativeAccept"
+        TENTATIVE_REJECT = "TentativeReject"
+        FLAG = "Flag"
+        UNDO = "Undo"
+
+        # Objects
+        ACTIVITY = "Activity"
+        APPLICATION = "Application"
+        ARTICLE = "Article"
+        AUDIO = "Audio"
+        COLLECTION = "Collection"
+        COLLECTION_PAGE = "CollectionPage"
+        RELATIONSHIP = "Relationship"
+        DOCUMENT = "Document"
+        EVENT = "Event"
+        GROUP = "Group"
+        IMAGE = "Image"
+        INTRANSITIVE_ACTIVITY = "IntransitiveActivity"
+        NOTE = "Note"
+        OBJECT = "Object"
+        ORDERED_COLLECTION = "OrderedCollection"
+        ORDERED_COLLECTION_PAGE = "OrderedCollectionPage"
+        ORGANIZATION = "Organization"
+        PAGE = "Page"
+        PERSON = "Person"
+        PLACE = "Place"
+        PROFILE = "Profile"
+        QUESTION = "Question"
+        SERVICE = "Service"
+        TOMBSTONE = "Tombstone"
+        VIDEO = "Video"
+      end
+
+      # The sub-list of ActivityStreams types that are also objects in AS 2.0
+      ACTIVITY_STREAMS_OBJECTS = [
+        ActivityStreamsTypes::ACTIVITY,
+        ActivityStreamsTypes::APPLICATION,
+        ActivityStreamsTypes::ARTICLE,
+        ActivityStreamsTypes::AUDIO,
+        ActivityStreamsTypes::COLLECTION,
+        ActivityStreamsTypes::COLLECTION_PAGE,
+        ActivityStreamsTypes::RELATIONSHIP,
+        ActivityStreamsTypes::DOCUMENT,
+        ActivityStreamsTypes::EVENT,
+        ActivityStreamsTypes::GROUP,
+        ActivityStreamsTypes::IMAGE,
+        ActivityStreamsTypes::INTRANSITIVE_ACTIVITY,
+        ActivityStreamsTypes::NOTE,
+        ActivityStreamsTypes::OBJECT,
+        ActivityStreamsTypes::ORDERED_COLLECTION,
+        ActivityStreamsTypes::ORDERED_COLLECTION_PAGE,
+        ActivityStreamsTypes::ORGANIZATION,
+        ActivityStreamsTypes::PAGE,
+        ActivityStreamsTypes::PERSON,
+        ActivityStreamsTypes::PLACE,
+        ActivityStreamsTypes::PROFILE,
+        ActivityStreamsTypes::QUESTION,
+        ActivityStreamsTypes::SERVICE,
+        ActivityStreamsTypes::TOMBSTONE,
+        ActivityStreamsTypes::VIDEO
+      ].freeze
+
+      # A simple wrapper around an ActivityStreams hash object
+      #
+      # Construct it with a ruby hash that represents an ActivityStreams object, or
+      # without to create a fresh, blank object.
+      class ActivityStream
+        attr_reader :doc, :context
+
+        # Construct a new ActivityStream object
+        #
+        # @param raw [Hash] the raw ActivityStreams object, as a hash
+        def initialize(raw = nil)
+          @doc = raw || {}
+          @context = []
+          if @doc.key?("@context")
+            @context = @doc["@context"]
+            @context = [@context] unless @context.is_a?(Array)
+            @doc.delete("@context")
+          end
+        end
+
+        # Set the document hash
+        #
+        # @param doc [Hash] the document hash to set
+        def doc=(doc)
+          @doc = doc
+        end
+
+        # Set the context
+        #
+        # @param context [Array, String] the context to set
+        def context=(context)
+          @context = context
+        end
+
+        # Register a namespace in the context of the ActivityStream
+        #
+        # @param namespace [String, Array] the namespace to register
+        def register_namespace(namespace)
+          entry = namespace
+          if namespace.is_a?(Array)
+            url = namespace[1]
+            short = namespace[0]
+            entry = { short => url }
+          end
+
+          @context << entry unless @context.include?(entry)
+        end
+
+        # Set an arbitrary property on the object. The property name can be one of:
+        #
+        # * A simple string with the property name
+        # * An array of the property name and the full namespace ["name", "http://example.com/ns"]
+        # * An array containing the property name and another array of the short name and the full namespace ["name", ["as", "http://example.com/ns"]]
+        #
+        # @param property [String, Array] the property name
+        # @param value [Object] the value to set
+        def set_property(property, value)
+          prop_name = property
+          namespace = nil
+          if property.is_a?(Array)
+            prop_name = property[0]
+            namespace = property[1]
+          end
+
+          @doc[prop_name] = value
+          register_namespace(namespace) if namespace
+        end
+
+        # Get an arbitrary property on the object. The property name can be one of:
+        #
+        # * A simple string with the property name
+        # * An array of the property name and the full namespace ["name", "http://example.com/ns"]
+        # * An array containing the property name and another array of the short name and the full namespace ["name", ["as", "http://example.com/ns"]]
+        #
+        # @param property [String, Array] the property name
+        # @return [Object] the value of the property, or nil if it does not exist
+        def get_property(property)
+          prop_name = property
+          namespace = nil
+          if property.is_a?(Array)
+            prop_name = property[0]
+            namespace = property[1]
+          end
+
+          @doc[prop_name]
+        end
+
+        # Get the activity stream as a JSON-LD object
+        #
+        # @return [Hash] the JSON-LD representation
+        def to_jsonld
+          {
+            "@context" => @context,
+            **@doc
+          }
+        end
+      end
+    end
+  end
+end