diaspora_federation 0.1.1 → 0.1.2

data/lib/diaspora_federation/entities/related_entity.rb

@@ -4,9 +4,9 @@ module DiasporaFederation
     # another entity).
     class RelatedEntity < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the author.
+      #   The diaspora* ID of the author
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author
 
       # @!attribute [r] local
@@ -15,12 +15,12 @@ module DiasporaFederation
       property :local
 
       # @!attribute [r] public
-      #   shows whether the entity is visible to everyone or only to some aspects
+      #   Shows whether the entity is visible to everyone or only to some aspects
       #   @return [Boolean] is it public
       property :public, default: false
 
       # @!attribute [r] parent
-      #   if the entity also have a parent (Comment or Like), +nil+ if it has no parent
+      #   Parent if the entity also has a parent (Comment or Like) or +nil+ if it has no parent
       #   @return [RelatedEntity] parent entity
       entity :parent, Entities::RelatedEntity, default: nil
 

data/lib/diaspora_federation/entities/relayable.rb

@@ -1,32 +1,32 @@
 module DiasporaFederation
   module Entities
-    # this is a module that defines common properties for relayable entities
+    # This is a module that defines common properties for relayable entities
     # which include Like, Comment, Participation, Message, etc. Each relayable
-    # has a parent, identified by guid. Relayables also are signed and signing/verification
+    # has a parent, identified by guid. Relayables are also signed and signing/verification
     # logic is embedded into Salmon XML processing code.
     module Relayable
       include Logging
 
-      # digest instance used for signing
+      # Digest instance used for signing
       DIGEST = OpenSSL::Digest::SHA256.new
 
-      # order from the parsed xml for signature
+      # Order from the parsed xml for signature
       # @return [Array] order from xml
       attr_reader :xml_order
 
-      # additional properties from parsed xml
+      # Additional properties from parsed xml
       # @return [Hash] additional xml elements
       attr_reader :additional_xml_elements
 
-      # on inclusion of this module the required properties for a relayable are added to the object that includes it
+      # On inclusion of this module the required properties for a relayable are added to the object that includes it.
       #
       # @!attribute [r] author
-      #   The diaspora ID of the author.
+      #   The diaspora* ID of the author
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       #
       # @!attribute [r] guid
-      #   a random string of at least 16 chars.
+      #   A random string of at least 16 chars
       #   @see Validation::Rule::Guid
       #   @return [String] comment guid
       #
@@ -35,20 +35,20 @@ module DiasporaFederation
       #   @return [String] parent guid
       #
       # @!attribute [r] author_signature
-      #   Contains a signature of the entity using the private key of the author of a post itself.
+      #   Contains a signature of the entity using the private key of the author of a post itself
       #   The presence of this signature is mandatory. Without it the entity won't be accepted by
       #   a target pod.
       #   @return [String] author signature
       #
       # @!attribute [r] parent_author_signature
       #   Contains a signature of the entity using the private key of the author of a parent post
-      #   This signature is required only when federation from upstream (parent) post author to
+      #   This signature is required only when federating from upstream (parent) post author to
       #   downstream subscribers. This is the case when the parent author has to resend a relayable
-      #   received from one of his subscribers to all others.
+      #   received from one of their subscribers to all others.
       #   @return [String] parent author signature
       #
       # @!attribute [r] parent
-      #   meta information about the parent object
+      #   Meta information about the parent object
       #   @return [RelatedEntity] parent entity
       #
       # @param [Entity] klass the entity in which it is included
@@ -78,12 +78,12 @@ module DiasporaFederation
         super(data)
       end
 
-      # verifies the signatures (+author_signature+ and +parent_author_signature+ if needed)
+      # Verifies the signatures (+author_signature+ and +parent_author_signature+ if needed).
       # @raise [SignatureVerificationFailed] if the signature is not valid or no public key is found
       def verify_signatures
         verify_signature(author, :author_signature)
 
-        # this happens only on downstream federation
+        # This happens only on downstream federation.
         verify_signature(parent.author, :parent_author_signature) unless parent.local
       end
 
@@ -116,7 +116,7 @@ module DiasporaFederation
         logger.info "event=verify_signature signature=#{signature_key} status=valid obj=#{self}"
       end
 
-      # sign with author key
+      # Sign with author key
       # @raise [AuthorPrivateKeyNotFound] if the author private key is not found
       # @return [String] A Base64 encoded signature of #signature_data with key
       def sign_with_author
@@ -127,7 +127,7 @@ module DiasporaFederation
         end
       end
 
-      # sign with parent author key, if the parent author is local (if the private key is found)
+      # Sign with parent author key, if the parent author is local (if the private key is found)
       # @return [String] A Base64 encoded signature of #signature_data with key
       def sign_with_parent_author_if_available
         privkey = DiasporaFederation.callbacks.trigger(:fetch_private_key, parent.author)
@@ -159,7 +159,7 @@ module DiasporaFederation
         end
       end
 
-      # the order for signing
+      # The order for signing
       # @return [Array]
       def signature_order
         xml_order.nil? ? self.class::LEGACY_SIGNATURE_ORDER : xml_order.reject {|name| name =~ /signature/ }
@@ -171,7 +171,7 @@ module DiasporaFederation
         signature_order.map {|name| data[name] }.join(";")
       end
 
-      # override class methods from {Entity} to parse the xml
+      # Override class methods from {Entity} to parse the xml
       module ParseXML
         private
 
@@ -181,7 +181,7 @@ module DiasporaFederation
           # Use all known properties to build the Entity (entity_data). All additional xml elements
           # are respected and attached to a hash as string (additional_xml_elements). It also remembers
           # the order of the xml-nodes (xml_order). This is needed to support receiving objects from
-          # the future versions of Diaspora, where new elements may have been added.
+          # the future versions of diaspora*, where new elements may have been added.
           entity_data = {}
           additional_xml_elements = {}
 
@@ -203,20 +203,28 @@ module DiasporaFederation
         end
 
         def fetch_parent(data)
-          type = data[:parent_type] || self::PARENT_TYPE
-          guid = data[:parent_guid]
+          type = data.fetch(:parent_type) {
+            if const_defined?(:PARENT_TYPE)
+              self::PARENT_TYPE
+            else
+              raise DiasporaFederation::Entity::ValidationError, "invalid #{self}! missing 'parent_type'."
+            end
+          }
+          guid = data.fetch(:parent_guid) {
+            raise DiasporaFederation::Entity::ValidationError, "invalid #{self}! missing 'parent_guid'."
+          }
 
           data[:parent] = DiasporaFederation.callbacks.trigger(:fetch_related_entity, type, guid)
 
           unless data[:parent]
-            # fetch and receive parent from remote, if not available locally
+            # Fetch and receive parent from remote, if not available locally
             Federation::Fetcher.fetch_public(data[:author], type, guid)
             data[:parent] = DiasporaFederation.callbacks.trigger(:fetch_related_entity, type, guid)
           end
         end
       end
 
-      # Raised, if creating the author_signature failes, because the private key was not found
+      # Raised, if creating the author_signature fails, because the private key was not found
       class AuthorPrivateKeyNotFound < RuntimeError
       end
 

data/lib/diaspora_federation/entities/relayable_retraction.rb

@@ -1,18 +1,18 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a claim of deletion of a previously federated
-    # relayable entity ({Entities::Comment}, {Entities::Like})
+    # This entity represents a claim of deletion of a previously federated
+    # relayable entity. ({Entities::Comment}, {Entities::Like})
     #
     # There are two cases of federation of the RelayableRetraction.
     # Retraction from the dowstream object owner is when an author of the
-    # relayable (e.g. Comment) deletes it himself. In this case only target_author_signature
-    # is filled and retraction is sent to the commented post's author. Here
-    # he (upstream object owner) signes it with parent's author key and fills
-    # signature in parent_author_signature and sends it to other pods where
-    # other participating people present. This is the second case - retraction
+    # relayable (e.g. Comment) deletes it themself. In this case only target_author_signature
+    # is filled and a retraction is sent to the commented post's author. Here
+    # the upstream object owner signs it with the parent's author key, puts
+    # the signature in parent_author_signature and sends it to other pods where
+    # other participating people are present. This is the second case - retraction
     # from the upstream object owner.
     # Retraction from the upstream object owner can also be performed by the
-    # upstream object owner himself - he has a right to delete comments on his posts.
+    # upstream object owner themself - they have a right to delete comments on their posts.
     # In any case in the retraction by the upstream author target_author_signature
     # is not checked, only parent_author_signature is checked.
     #
@@ -20,33 +20,33 @@ module DiasporaFederation
     # @deprecated will be replaced with {Entities::Retraction}
     class RelayableRetraction < Entity
       # @!attribute [r] parent_author_signature
-      #   Contains a signature of the entity using the private key of the author of a parent post
-      #   This signature is mandatory only when federation from an upstream author to the subscribers.
+      #   Contains a signature of the entity using the private key of the author of a parent post.
+      #   This signature is mandatory only when federating from an upstream author to the subscribers.
       #   @see Relayable#parent_author_signature
       #   @return [String] parent author signature
       property :parent_author_signature, default: nil
 
       # @!attribute [r] target_guid
-      #   guid of a relayable to be deleted
+      #   Guid of a relayable to be deleted
       #   @see Comment#guid
       #   @return [String] target guid
       property :target_guid
 
       # @!attribute [r] target_type
-      #   a string describing a type of the target
+      #   A string describing a type of the target
       #   @see Retraction#target_type
       #   @return [String] target type
       property :target_type
 
       # @!attribute [r] author
-      #   The diaspora ID of the person who deletes a relayable
+      #   The diaspora* ID of the person who deletes a relayable
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, xml_name: :sender_handle
 
       # @!attribute [r] target_author_signature
       #   Contains a signature of the entity using the private key of the
-      #   author of a federated relayable entity ({Entities::Comment}, {Entities::Like})
+      #   author of a federated relayable entity. ({Entities::Comment}, {Entities::Like})
       #   This signature is mandatory only when federation from the subscriber to an upstream
       #   author is done.
       #   @see Relayable#author_signature
@@ -54,11 +54,11 @@ module DiasporaFederation
       property :target_author_signature, default: nil
 
       # @!attribute [r] target
-      #   target entity
+      #   Target entity
       #   @return [RelatedEntity] target entity
       entity :target, Entities::RelatedEntity
 
-      # use only {Retraction} for receive
+      # Use only {Retraction} for receive
       # @return [Retraction] instance as normal retraction
       def to_retraction
         Retraction.new(author: author, target_guid: target_guid, target_type: target_type, target: target)

data/lib/diaspora_federation/entities/request.rb

@@ -1,24 +1,24 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a sharing request for a user. A user issues it
-    # when he starts sharing with another user.
+    # This entity represents a sharing request for a user. A user issues it
+    # when they start sharing with another user.
     #
     # @see Validators::RequestValidator
     # @deprecated will be replaced with {Contact}
     class Request < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the person who shares his profile
+      #   The diaspora* ID of the person who share their profile
       #   @see Person#author
       #   @return [String] sender ID
       property :author, xml_name: :sender_handle
 
       # @!attribute [r] recipient
-      #   The diaspora ID of the person who will be shared with
+      #   The diaspora* ID of the person who will be shared with
       #   @see Validation::Rule::DiasporaId
       #   @return [String] recipient ID
       property :recipient, xml_name: :recipient_handle
 
-      # use only {Contact} for receive
+      # Use only {Contact} for receive
       # @return [Contact] instance as contact
       def to_contact
         Contact.new(author: author, recipient: recipient)

data/lib/diaspora_federation/entities/reshare.rb

@@ -1,25 +1,25 @@
 module DiasporaFederation
   module Entities
-    # this entity represents the fact the a user reshared some other user's post
+    # This entity represents the fact that a user reshared another user's post.
     #
     # @see Validators::ReshareValidator
     class Reshare < Entity
       include Post
 
       # @!attribute [r] root_author
-      #   The diaspora ID of the person who posted the original post
+      #   The diaspora* ID of the person who posted the original post
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :root_author, xml_name: :root_diaspora_id
 
       # @!attribute [r] root_guid
-      #   guid of the original post
+      #   Guid of the original post
       #   @see StatusMessage#guid
       #   @return [String] root guid
       property :root_guid
 
       # @!attribute [r] public
-      #   has no meaning at the moment
+      #   Has no meaning at the moment
       #   @return [Boolean] public
       property :public, default: true # always true? (we only reshare public posts)
 
@@ -28,13 +28,13 @@ module DiasporaFederation
         "#{super}:#{root_guid}"
       end
 
-      # fetch and receive root post from remote, if not available locally.
+      # Fetch and receive root post from remote, if not available locally
       def fetch_root
         root = DiasporaFederation.callbacks.trigger(:fetch_related_entity, "Post", root_guid)
         Federation::Fetcher.fetch_public(root_author, "Post", root_guid) unless root
       end
 
-      # Fetch root post after parse.
+      # Fetch root post after parse
       # @see Entity.populate_entity
       # @param [Nokogiri::XML::Element] root_node xml nodes
       # @return [Entity] instance

data/lib/diaspora_federation/entities/retraction.rb

@@ -1,27 +1,27 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a claim of deletion of a previously federated entity
+    # This entity represents a claim of deletion of a previously federated entity.
     #
     # @see Validators::RetractionValidator
     class Retraction < Entity
       # @!attribute [r] author
-      #   The diaspora ID of the person who deletes the entity
+      #   The diaspora* ID of the person who deletes the entity
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, xml_name: :diaspora_handle
 
       # @!attribute [r] target_guid
-      #   guid of the entity to be deleted
+      #   Guid of the entity to be deleted
       #   @return [String] target guid
       property :target_guid, xml_name: :post_guid
 
       # @!attribute [r] target_type
-      #   A string describing the type of the target.
+      #   A string describing the type of the target
       #   @return [String] target type
       property :target_type, xml_name: :type
 
       # @!attribute [r] target
-      #   target entity
+      #   Target entity
       #   @return [RelatedEntity] target entity
       entity :target, Entities::RelatedEntity
 

data/lib/diaspora_federation/entities/signed_retraction.rb

@@ -1,27 +1,27 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a claim of deletion of a previously federated
-    # entity of post type ({Entities::StatusMessage})
+    # This entity represents a claim of deletion of a previously federated
+    # entity of post type. ({Entities::StatusMessage})
     #
     # @see Validators::SignedRetractionValidator
     # @deprecated will be replaced with {Entities::Retraction}
     class SignedRetraction < Entity
       # @!attribute [r] target_guid
-      #   guid of a post to be deleted
+      #   Guid of a post to be deleted
       #   @see Retraction#target_guid
       #   @return [String] target guid
       property :target_guid
 
       # @!attribute [r] target_type
-      #   A string describing the type of the target.
+      #   A string describing the type of the target
       #   @see Retraction#target_type
       #   @return [String] target type
       property :target_type
 
       # @!attribute [r] author
-      #   The diaspora ID of the person who deletes a post
+      #   The diaspora* ID of the person who deletes a post
       #   @see Person#author
-      #   @return [String] diaspora ID
+      #   @return [String] diaspora* ID
       property :author, xml_name: :sender_handle
 
       # @!attribute [r] author_signature
@@ -31,11 +31,11 @@ module DiasporaFederation
       property :target_author_signature, default: nil
 
       # @!attribute [r] target
-      #   target entity
+      #   Target entity
       #   @return [RelatedEntity] target entity
       entity :target, Entities::RelatedEntity
 
-      # use only {Retraction} for receive
+      # Use only {Retraction} for receive
       # @return [Retraction] instance as normal retraction
       def to_retraction
         Retraction.new(author: author, target_guid: target_guid, target_type: target_type, target: target)

data/lib/diaspora_federation/entities/status_message.rb

@@ -1,33 +1,33 @@
 module DiasporaFederation
   module Entities
-    # this entity represents a status message sent by a user
+    # This entity represents a status message sent by a user.
     #
     # @see Validators::StatusMessageValidator
     class StatusMessage < Entity
       include Post
 
-      # @!attribute [r] raw_message
-      #   text of the status message composed by the user
+      # @!attribute [r] text
+      #   Text of the status message composed by the user
       #   @return [String] text of the status message
-      property :raw_message
+      property :text, xml_name: :raw_message
 
       # @!attribute [r] photos
-      #   optional photos attached to the status message
+      #   Optional photos attached to the status message
       #   @return [[Entities::Photo]] photos
       entity :photos, [Entities::Photo], default: []
 
       # @!attribute [r] location
-      #   optional location attached to the status message
+      #   Optional location attached to the status message
       #   @return [Entities::Location] location
       entity :location, Entities::Location, default: nil
 
       # @!attribute [r] poll
-      #   optional poll attached to the status message
+      #   Optional poll attached to the status message
       #   @return [Entities::Poll] poll
       entity :poll, Entities::Poll, default: nil
 
       # @!attribute [r] public
-      #   shows whether the status message is visible to everyone or only to some aspects
+      #   Shows whether the status message is visible to everyone or only to some aspects
       #   @return [Boolean] is it public
       property :public, default: false