diaspora_federation 0.0.1 → 0.0.2

data/lib/diaspora_federation/logging.rb

@@ -1,12 +1,10 @@
 module DiasporaFederation
-  ##
-  # logging module for the diaspora federation engine
+  # logging module for the diaspora federation
   #
   # it uses the logging-gem if available
   module Logging
     private
 
-    ##
     # get the logger for this class
     #
     # use the logging-gem if available, else use a default logger
@@ -17,7 +15,8 @@ module DiasporaFederation
 
                     # fallback logger
                     @logger = Logger.new(STDOUT)
-                    @logger.level = Logger.const_get(Rails.configuration.log_level.to_s.upcase)
+                    loglevel = defined?(::Rails) ? ::Rails.configuration.log_level.to_s.upcase : "INFO"
+                    @logger.level = Logger.const_get(loglevel)
                     @logger
                   end
     end

data/lib/diaspora_federation/properties_dsl.rb

@@ -0,0 +1,106 @@
+module DiasporaFederation
+  # Provides a simple DSL for specifying {Entity} properties during class
+  # definition.
+  #
+  # @example
+  #   property :prop
+  #   property :optional, default: false
+  #   property :dynamic_default, default: -> { Time.now }
+  #   entity :nested, NestedEntity
+  #   entity :multiple, [OtherEntity]
+  module PropertiesDSL
+    # @return [Array<Hash>] hash of declared entity properties
+    def class_props
+      @class_props ||= []
+    end
+
+    # Define a generic (string-type) property
+    # @param [Symbol] name property name
+    # @param [Hash] opts further options
+    # @option opts [Object, #call] :default a default value, making the
+    #   property optional
+    def property(name, opts={})
+      define_property name, String, opts
+    end
+
+    # Define a property that should contain another Entity or an array of
+    # other Entities
+    # @param [Symbol] name property name
+    # @param [Entity, Array<Entity>] type Entity subclass or
+    #                Array with exactly one Entity subclass constant inside
+    # @param [Hash] opts further options
+    # @option opts [Object, #call] :default a default value, making the
+    #   property optional
+    def entity(name, type, opts={})
+      raise InvalidType unless type_valid?(type)
+
+      define_property name, type, opts
+    end
+
+    # Return array of missing required property names
+    # @return [Array<Symbol>] missing required property names
+    def missing_props(args)
+      class_prop_names - default_props.keys - args.keys
+    end
+
+    # Return a new hash of default values, with dynamic values
+    # resolved on each call
+    # @return [Hash] default values
+    def default_values
+      default_props.each_with_object({}) { |(name, prop), hash|
+        hash[name] = prop.respond_to?(:call) ? prop.call : prop
+      }
+    end
+
+    # Returns all nested Entities
+    # @return [Array<Hash>] nested properties
+    def nested_class_props
+      @nested_class_props ||= class_props.select {|p| p[:type] != String }
+    end
+
+    # Returns all property names
+    # @return [Array] property names
+    def class_prop_names
+      @class_prop_names ||= class_props.map {|p| p[:name] }
+    end
+
+    private
+
+    def define_property(name, type, opts={})
+      raise InvalidName unless name_valid?(name)
+
+      class_props << {name: name, type: type}
+      default_props[name] = opts[:default] if opts.has_key? :default
+
+      instance_eval { attr_reader name }
+    end
+
+    # checks if the name is a +Symbol+ or a +String+
+    # @param [String, Symbol] name the name to check
+    # @return [Boolean]
+    def name_valid?(name)
+      name.instance_of?(Symbol) || name.instance_of?(String)
+    end
+
+    # checks if the type extends {Entity}
+    # @param [Class] type the type to check
+    # @return [Boolean]
+    def type_valid?(type)
+      [type].flatten.all? { |type|
+        type.respond_to?(:ancestors) && type.ancestors.include?(Entity)
+      }
+    end
+
+    def default_props
+      @default_props ||= {}
+    end
+
+    # Raised, if the name is of an unexpected type
+    class InvalidName < RuntimeError
+    end
+
+    # Raised, if the type is of an unexpected type
+    class InvalidType < RuntimeError
+    end
+  end
+end

data/lib/diaspora_federation/version.rb

@@ -1,5 +1,4 @@
 module DiasporaFederation
-  ##
   # the gem version
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/diaspora_federation/web_finger.rb

@@ -1,5 +1,4 @@
 module DiasporaFederation
-  ##
   # This module provides the namespace for the various classes implementing
   # WebFinger and other protocols used for metadata discovery on remote servers
   # in the Diaspora* network.

data/lib/diaspora_federation/web_finger/exceptions.rb

@@ -1,18 +1,14 @@
 module DiasporaFederation
   module WebFinger
-    ##
     # Raised, if the XML structure is invalid
     class InvalidDocument < RuntimeError
     end
 
-    ##
     # Raised, if something is wrong with the webfinger data
     #
     # * if the +webfinger_url+ is missing or malformed in {HostMeta.from_base_url} or {HostMeta.from_xml}
-    # * if the +data+ given to {WebFinger.from_person} is an invalid type or doesn't contain all required entries
     # * if the parsed XML from {WebFinger.from_xml} is incomplete
-    # * if the params passed to {HCard.from_profile} or {HCard.from_html}
-    #   are in some way malformed, invalid or incomplete.
+    # * if the html passed to {HCard.from_html} in some way is malformed, invalid or incomplete.
     class InvalidData < RuntimeError
     end
   end

data/lib/diaspora_federation/web_finger/h_card.rb

@@ -1,6 +1,5 @@
 module DiasporaFederation
   module WebFinger
-    ##
     # This class provides the means of generating an parsing account data to and
     # from the hCard format.
     # hCard is based on +RFC 2426+ (vCard) which got superseded by +RFC 6350+.
@@ -14,20 +13,20 @@ module DiasporaFederation
     #   correctly nested according to the hCard standard and class names are
     #   partially wrong. Also, apart from that, it's just ugly.
     #
-    # @example Creating a hCard document from account data
-    #   hc = HCard.from_profile({
-    #     guid:             "0123456789abcdef",
-    #     nickname:         "user",
-    #     full_name:        "User Name",
-    #     url:              "https://server.example/",
-    #     photo_large_url:  "https://server.example/uploads/l.jpg",
-    #     photo_medium_url: "https://server.example/uploads/m.jpg",
-    #     photo_small_url:  "https://server.example/uploads/s.jpg",
-    #     pubkey:           "-----BEGIN PUBLIC KEY-----\nABCDEF==\n-----END PUBLIC KEY-----",
-    #     searchable:       true,
-    #     first_name:       "User",
-    #     last_name:        "Name"
-    #   })
+    # @example Creating a hCard document from a person hash
+    #   hc = HCard.new(
+    #     guid:                  "0123456789abcdef",
+    #     nickname:              "user",
+    #     full_name:             "User Name",
+    #     seed_url:              "https://server.example/",
+    #     photo_large_url:       "https://server.example/uploads/l.jpg",
+    #     photo_medium_url:      "https://server.example/uploads/m.jpg",
+    #     photo_small_url:       "https://server.example/uploads/s.jpg",
+    #     serialized_public_key: "-----BEGIN PUBLIC KEY-----\nABCDEF==\n-----END PUBLIC KEY-----",
+    #     searchable:            true,
+    #     first_name:            "User",
+    #     last_name:             "Name"
+    #   )
     #   html_string = hc.to_html
     #
     # @example Create a HCard instance from an hCard document
@@ -40,65 +39,77 @@ module DiasporaFederation
     # @see http://microformats.org/wiki/h-card "h-card" (draft)
     # @see http://www.ietf.org/rfc/rfc2426.txt "vCard MIME Directory Profile" (obsolete)
     # @see http://www.ietf.org/rfc/rfc6350.txt "vCard Format Specification"
-    class HCard
-      private_class_method :new
-
-      # This is just the guid. When a user creates an account on a pod, the pod
-      # MUST assign them a guid - a random hexadecimal string of at least 8
-      # hexadecimal digits.
-      # @return [String] guid
-      attr_reader :guid
-
-      # the first part of the diaspora handle
-      # @return [String] nickname
-      attr_reader :nickname
-
-      # @return [String] display name of the user
-      attr_reader :full_name
-
-      # @deprecated should be changed to the profile url. The pod url is in
-      #   the WebFinger (see {WebFinger#seed_url}, will affect older Diaspora*
-      #   installations).
+    class HCard < Entity
+      # @!attribute [r] guid
+      #   This is just the guid. When a user creates an account on a pod, the pod
+      #   MUST assign them a guid - a random hexadecimal string of at least 8
+      #   hexadecimal digits.
+      #   @return [String] guid
+      property :guid
+
+      # @!attribute [r] nickname
+      #   the first part of the diaspora handle
+      #   @return [String] nickname
+      property :nickname
+
+      # @!attribute [r] full_name
+      #  @return [String] display name of the user
+      property :full_name
+
+      # @!attribute [r] url
+      #   @deprecated should be changed to the profile url. The pod url is in
+      #     the WebFinger (see {WebFinger#seed_url}, will affect older Diaspora*
+      #     installations).
       #
-      # @return [String] link to the pod
-      attr_reader :url
-
-      # When a user is created on the pod, the pod MUST generate a pgp keypair
-      # for them. This key is used for signing messages. The format is a
-      # DER-encoded PKCS#1 key beginning with the text
-      # "-----BEGIN PUBLIC KEY-----" and ending with "-----END PUBLIC KEY-----".
-      # @return [String] public key
-      attr_reader :pubkey
-
-      # @return [String] url to the big avatar (300x300)
-      attr_reader :photo_large_url
-      # @return [String] url to the medium avatar (100x100)
-      attr_reader :photo_medium_url
-      # @return [String] url to the small avatar (50x50)
-      attr_reader :photo_small_url
-
-      # @deprecated We decided to only use one name field, these should be removed
-      #   in later iterations (will affect older Diaspora* installations).
+      #   @return [String] link to the pod
+      property :url
+
+      # @!attribute [r] public_key
+      #   When a user is created on the pod, the pod MUST generate a pgp keypair
+      #   for them. This key is used for signing messages. The format is a
+      #   DER-encoded PKCS#1 key beginning with the text
+      #   "-----BEGIN PUBLIC KEY-----" and ending with "-----END PUBLIC KEY-----".
       #
-      # @see #full_name
-      # @return [String] first name
-      attr_reader :first_name
+      #   @note the public key is new in the hcard and is optional now.
+      #
+      #   @return [String] public key
+      property :public_key, default: nil
+
+      # @!attribute [r] photo_large_url
+      #   @return [String] url to the big avatar (300x300)
+      property :photo_large_url
+      # @!attribute [r] photo_medium_url
+      #   @return [String] url to the medium avatar (100x100)
+      property :photo_medium_url
+      # @!attribute [r] photo_small_url
+      #   @return [String] url to the small avatar (50x50)
+      property :photo_small_url
+
+      # @!attribute [r] first_name
+      #   @deprecated We decided to only use one name field, these should be removed
+      #     in later iterations (will affect older Diaspora* installations).
+      #
+      #   @see #full_name
+      #   @return [String] first name
+      property :first_name
 
-      # @deprecated We decided to only use one name field, these should be removed
-      #   in later iterations (will affect older Diaspora* installations).
+      # @!attribute [r] last_name
+      #   @deprecated We decided to only use one name field, these should be removed
+      #     in later iterations (will affect older Diaspora* installations).
       #
-      # @see #full_name
-      # @return [String] last name
-      attr_reader :last_name
-
-      # @deprecated As this is a simple property, consider move to WebFinger instead
-      #   of HCard. vCard has no comparable field for this information, but
-      #   Webfinger may declare arbitrary properties (will affect older Diaspora*
-      #   installations).
+      #   @see #full_name
+      #   @return [String] last name
+      property :last_name
+
+      # @!attribute [r] searchable
+      #   @deprecated As this is a simple property, consider move to WebFinger instead
+      #     of HCard. vCard has no comparable field for this information, but
+      #     Webfinger may declare arbitrary properties (will affect older Diaspora*
+      #     installations).
       #
-      # flag if a user is searchable by name
-      # @return [Boolean] searchable flag
-      attr_reader :searchable
+      #   flag if a user is searchable by name
+      #   @return [Boolean] searchable flag
+      property :searchable
 
       # CSS selectors for finding all the hCard fields
       SELECTORS = {
@@ -128,7 +139,7 @@ module DiasporaFederation
         add_simple_property(content, :searchable, "searchable", @searchable)
 
         add_property(content, :key) do |html|
-          html.pre(@pubkey.to_s, class: "key")
+          html.pre(@public_key.to_s, class: "key")
         end
 
         # TODO: remove me!  ###################
@@ -145,33 +156,6 @@ module DiasporaFederation
         builder.doc.to_xhtml(indent: 2, indent_text: " ")
       end
 
-      # Creates a new HCard instance from the given Hash containing profile data
-      # @param [Hash] data account data
-      # @return [HCard] HCard instance
-      # @raise [InvalidData] if the account data Hash is invalid or incomplete
-      def self.from_profile(data)
-        raise InvalidData unless account_data_complete?(data)
-
-        hc = allocate
-        hc.instance_eval {
-          @guid             = data[:guid]
-          @nickname         = data[:nickname]
-          @full_name        = data[:full_name]
-          @url              = data[:url]
-          @photo_large_url   = data[:photo_large_url]
-          @photo_medium_url = data[:photo_medium_url]
-          @photo_small_url  = data[:photo_small_url]
-          @pubkey           = data[:pubkey]
-          @searchable       = data[:searchable]
-
-          # TODO: remove me!  ###################
-          @first_name       = data[:first_name]
-          @last_name        = data[:last_name]
-          #######################################
-        }
-        hc
-      end
-
       # Creates a new HCard instance from the given HTML string.
       # @param html_string [String] HTML string
       # @return [HCard] HCard instance
@@ -179,24 +163,24 @@ module DiasporaFederation
       def self.from_html(html_string)
         doc = parse_html_and_validate(html_string)
 
-        hc = allocate
-        hc.instance_eval {
-          @guid             = content_from_doc(doc, :uid)
-          @nickname         = content_from_doc(doc, :nickname)
-          @full_name        = content_from_doc(doc, :fn)
-          @url              = element_from_doc(doc, :url)["href"]
-          @photo_large_url  = photo_from_doc(doc, :photo)
-          @photo_medium_url = photo_from_doc(doc, :photo_medium)
-          @photo_small_url  = photo_from_doc(doc, :photo_small)
-          @pubkey           = content_from_doc(doc, :key) unless element_from_doc(doc, :key).nil?
-          @searchable       = content_from_doc(doc, :searchable) == "true"
+        data = {
+          guid:             content_from_doc(doc, :uid),
+          nickname:         content_from_doc(doc, :nickname),
+          full_name:        content_from_doc(doc, :fn),
+          url:              element_from_doc(doc, :url)["href"],
+          photo_large_url:  photo_from_doc(doc, :photo),
+          photo_medium_url: photo_from_doc(doc, :photo_medium),
+          photo_small_url:  photo_from_doc(doc, :photo_small),
+          searchable:       (content_from_doc(doc, :searchable) == "true"),
 
           # TODO: change me!  ###################
-          @first_name       = content_from_doc(doc, :given_name)
-          @last_name        = content_from_doc(doc, :family_name)
+          first_name:       content_from_doc(doc, :given_name),
+          last_name:        content_from_doc(doc, :family_name)
           #######################################
         }
-        hc
+        # TODO: public key is new and can be missing
+        data[:public_key] = content_from_doc(doc, :key) unless element_from_doc(doc, :key).nil?
+        new(data)
       end
 
       private
@@ -271,19 +255,6 @@ module DiasporaFederation
         end
       end
 
-      # Checks the given account data Hash for correct type and completeness.
-      # @param [Hash] data account data
-      # @return [Boolean] validation result
-      def self.account_data_complete?(data)
-        data.instance_of?(Hash) &&
-          %i(
-            guid nickname full_name url
-            photo_large_url photo_medium_url photo_small_url
-            pubkey searchable first_name last_name
-          ).all? {|k| data.key? k }
-      end
-      private_class_method :account_data_complete?
-
       # Make sure some of the most important elements are present in the parsed
       # HTML document.
       # @param [LibXML::XML::Document] doc HTML document
@@ -303,17 +274,20 @@ module DiasporaFederation
       end
       private_class_method :parse_html_and_validate
 
-      def element_from_doc(doc, selector)
+      def self.element_from_doc(doc, selector)
         doc.at_css(SELECTORS[selector])
       end
+      private_class_method :element_from_doc
 
-      def content_from_doc(doc, content_selector)
+      def self.content_from_doc(doc, content_selector)
         element_from_doc(doc, content_selector).content
       end
+      private_class_method :content_from_doc
 
-      def photo_from_doc(doc, photo_selector)
+      def self.photo_from_doc(doc, photo_selector)
         element_from_doc(doc, photo_selector)["src"]
       end
+      private_class_method :photo_from_doc
     end
   end
 end