diaspora_federation 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35ffb28db27478325eaf2f2d61290b125f2e20e2
-  data.tar.gz: cfaca21b0289d178044895bbb91326b51520fed7
+  metadata.gz: 3b3836cd6caf68ffba2a101eb90c98932a7cfc1e
+  data.tar.gz: 87fcf932a0f7c2b9151af3bd12c72a1acaf6c935
 SHA512:
-  metadata.gz: 0ef15d9756b8174572d54d926388e8dffbeabea94f342ceb62ef536f5c52f6c9003e904b208c22a277c4c4906c1723ea7bf7f82181dae3726a9b5aeaa51b77a0
-  data.tar.gz: 1e77ba30e7745f64927b58ab0c110fa9467f0b8981e539ce24500754d5a61f548ac63e362c84ad5cfb7b6bbbca92ac065b1aa1e4a9debf1599150dbad27a1f5b
+  metadata.gz: 94783e21640104926dac495d63976435dee0e47f99cf0d6e9d71a07615cd645e2aecee0a3cb73f98f46fc974e4a6835d32999906824610a607fd598557cc0848
+  data.tar.gz: 13a49b3cb39df94c54c67289da76fb41f2c8a9db3ec44ad865ce88a4439cd9487cdf3f796a341c85293437b3a330fd40b2510f48908d8b422eb927a59ca857e0

data/README.md

@@ -1,18 +1,68 @@
-# diaspora* federation rails engine
+# diaspora* federation library
 
-#### A rails engine that adds the diaspora* federation protocol to a rails app
+**A library that provides functionalities needed for the diaspora* federation protocol**
 
 [![Build Status](https://travis-ci.org/SuperTux88/diaspora_federation.svg?branch=master)](https://travis-ci.org/SuperTux88/diaspora_federation)
 [![Code Climate](https://codeclimate.com/github/SuperTux88/diaspora_federation/badges/gpa.svg)](https://codeclimate.com/github/SuperTux88/diaspora_federation)
 [![Test Coverage](https://codeclimate.com/github/SuperTux88/diaspora_federation/badges/coverage.svg)](https://codeclimate.com/github/SuperTux88/diaspora_federation/coverage)
 [![Dependency Status](https://gemnasium.com/SuperTux88/diaspora_federation.svg)](https://gemnasium.com/SuperTux88/diaspora_federation)
 [![Inline docs](https://inch-ci.org/github/SuperTux88/diaspora_federation.svg?branch=master)](https://inch-ci.org/github/SuperTux88/diaspora_federation)
+[![Gem Version](https://badge.fury.io/rb/diaspora_federation.svg)](https://badge.fury.io/rb/diaspora_federation)
 
-[Documentation](http://www.rubydoc.info/github/SuperTux88/diaspora_federation/master) |
-[Project site](https://diasporafoundation.org) |
-[Wiki](https://wiki.diasporafoundation.org) |
+[Documentation](http://www.rubydoc.info/gems/diaspora_federation/) |
 [Bugtracker](https://github.com/SuperTux88/diaspora_federation/issues)
 
+## Library
+
+The ```diaspora_federation``` gem provides the functionality for de-/serialization and de-/encryption of Entities
+in the protocols used for communication among the various installations of Diaspora*
+
+## Rails Engine
+
+The ```diaspora_federation-rails``` gem is a rails engine that adds the diaspora* federation protocol to a rails app.
+
+### Usage
+
+Add the gem to your ```Gemfile```:
+
+```ruby
+gem "diaspora_federation-rails"
+```
+
+Mount the routes in your ```config/routes.rb```:
+
+```ruby
+mount DiasporaFederation::Engine => "/"
+```
+
+Configure the engine in ```config/initializers/diaspora_federation.rb```:
+
+```ruby
+DiasporaFederation.configure do |config|
+  # the pod url
+  config.server_uri = AppConfig.pod_uri
+
+  # the class to be used for a person
+  config.person_class = Person
+end
+```
+
+## Development
+
+**!!! This gem is currently under heavy development, so every release can contain breaking changes !!!**
+
+If you want to help, please contact me, help is welcome.
+
+After the first stable release, this repo will be moved to the [diaspora organization](https://github.com/diaspora/).
+
+## Diaspora
+
+A privacy-aware, distributed, open source social network
+
+Links:
+[Project site](https://diasporafoundation.org) |
+[Wiki](https://wiki.diasporafoundation.org)
+
 ## License
 
 This gem is published under the terms of the "GNU Affero General Public License". See the LICENSE file for the exact wording.

data/lib/diaspora_federation.rb

@@ -1,113 +1,77 @@
-require "diaspora_federation/engine"
 require "diaspora_federation/logging"
 
+require "diaspora_federation/callbacks"
+require "diaspora_federation/properties_dsl"
+require "diaspora_federation/entity"
+
 require "diaspora_federation/web_finger"
 
-##
-# diaspora* federation rails engine
+# diaspora* federation library
 module DiasporaFederation
   extend Logging
 
+  @callbacks = Callbacks.new %i(
+    person_webfinger_fetch
+    person_hcard_fetch
+  )
+
   class << self
-    ##
+    # {Callbacks} instance with defined callbacks
+    # @see Callbacks#on
+    # @see Callbacks#trigger
+    #
+    attr_reader :callbacks
+
     # the pod url
     #
-    # Example:
+    # @example with uri
     #   config.server_uri = URI("http://localhost:3000/")
-    # or
+    # @example with configured pod_uri
     #   config.server_uri = AppConfig.pod_uri
     attr_accessor :server_uri
 
-    ##
-    # the class to use as +Person+
-    #
-    # Example:
-    #   config.person_class = Person.to_s
-    #
-    # This class must have the following methods:
+    # configure the federation library
     #
-    # *find_local_by_diaspora_handle*
-    # This should return a +Person+, which is on this pod and the account is not closed.
-    #
-    # *find_local_by_guid*
-    # This should return a +Person+, which is on this pod and the account is not closed.
-    #
-    # *webfinger_hash*
-    # This should return a +Hash+ with the following information:
-    #   {
-    #     acct_uri:    "acct:user@server.example",
-    #     alias_url:   "https://server.example/people/0123456789abcdef",
-    #     hcard_url:   "https://server.example/hcard/users/0123456789abcdef",
-    #     seed_url:    "https://server.example/",
-    #     profile_url: "https://server.example/u/user",
-    #     atom_url:    "https://server.example/public/user.atom",
-    #     salmon_url:  "https://server.example/receive/users/0123456789abcdef",
-    #     guid:        "0123456789abcdef",
-    #     pubkey:      "-----BEGIN PUBLIC KEY-----\nABCDEF==\n-----END PUBLIC KEY-----"
-    #   }
+    # @example
+    #   DiasporaFederation.configure do |config|
+    #     config.server_uri = URI("http://localhost:3000/")
     #
-    # *hcard_profile_hash*
-    # This should return a +Hash+ with the following information:
-    #   {
-    #     guid:             "0123456789abcdef",
-    #     nickname:         "user",
-    #     full_name:        "User Name",
-    #     url:              "https://server.example/",
-    #     photo_large_url:  "https://server.example/uploads/f.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"
-    #   }
-    attr_accessor :person_class
-    def person_class
-      const_get(@person_class)
+    #     config.define_callbacks do
+    #       # callback configuration
+    #     end
+    #   end
+    def configure
+      yield self
     end
 
-    ##
-    # configure the federation engine
+    # define the callbacks
     #
-    #   DiasporaFederation.configure do |config|
-    #     config.server_uri = "http://localhost:3000/"
+    # @example
+    #   config.define_callbacks do
+    #     on :some_event do |arg1|
+    #       # do something
+    #     end
     #   end
-    def configure
-      yield self
+    #
+    # @param [Proc] block the callbacks to define
+    def define_callbacks(&block)
+      @callbacks.instance_eval(&block)
     end
 
-    ##
     # validates if the engine is configured correctly
     #
     # called from after_initialize
     # @raise [ConfigurationError] if the configuration is incomplete or invalid
     def validate_config
-      configuration_error "missing server_uri" unless @server_uri.respond_to? :host
-      validate_class(@person_class, "person_class", %i(
-        find_local_by_diaspora_handle
-        find_local_by_guid
-        webfinger_hash
-        hcard_profile_hash
-      ))
-      logger.info "successfully configured the federation engine"
+      configuration_error "Missing server_uri" unless @server_uri.respond_to? :host
+      unless @callbacks.definition_complete?
+        configuration_error "Missing handlers for #{@callbacks.missing_handlers.join(', ')}"
+      end
+      logger.info "successfully configured the federation library"
     end
 
     private
 
-    def validate_class(klass, name, methods)
-      configuration_error "missing #{name}" unless klass
-      entity = const_get(klass)
-
-      return logger.warn "table for #{entity} doesn't exist, skip validation" unless entity.table_exists?
-
-      methods.each {|method| entity_respond_to?(entity, name, method) }
-    end
-
-    def entity_respond_to?(entity, name, method)
-      valid = entity.respond_to?(method) || entity.column_names.include?(method.to_s) || entity.method_defined?(method)
-      configuration_error "the configured class #{entity} for #{name} doesn't respond to #{method}" unless valid
-    end
-
     def configuration_error(message)
       logger.fatal("diaspora federation configuration error: #{message}")
       raise ConfigurationError, message

data/lib/diaspora_federation/callbacks.rb

@@ -0,0 +1,62 @@
+module DiasporaFederation
+  # Callbacks are used to communicate with the application. They are called to
+  # fetch data and after data is received.
+  class Callbacks
+    # Initializes a new Callbacks object with the event-keys that need to be defined.
+    #
+    # @example
+    #   Callbacks.new %i(
+    #     some_event
+    #     another_event
+    #   )
+    #
+    # @param [Hash] events event keys
+    def initialize(events)
+      @events   = events
+      @handlers = {}
+    end
+
+    # defines a callback
+    #
+    # @example
+    #   callbacks.on :some_event do |arg1|
+    #     # do something
+    #   end
+    #
+    # @param [Symbol] event the event key
+    # @param [Proc] callback the callback block
+    # @raise [ArgumentError] if the event key is undefined or has already a handler
+    def on(event, &callback)
+      raise ArgumentError, "Undefined event #{event}" unless @events.include? event
+      raise ArgumentError, "Already defined event #{event}" if @handlers.has_key? event
+
+      @handlers[event] = callback
+    end
+
+    # triggers a callback
+    #
+    # @example
+    #   callbacks.trigger :some_event, "foo"
+    #
+    # @param [Symbol] event the event key
+    # @return [Object] the return-value of the callback
+    # @raise [ArgumentError] if the event key is undefined
+    def trigger(event, *args)
+      raise ArgumentError, "Undefined event #{event}" unless @events.include? event
+
+      @handlers[event].call(*args)
+    end
+
+    # checks if all callbacks are defined
+    # @return [Boolean]
+    def definition_complete?
+      missing_handlers.empty?
+    end
+
+    # Returns all undefined callbacks
+    # @return [Hash] callback keys
+    def missing_handlers
+      @events - @handlers.keys
+    end
+  end
+end

data/lib/diaspora_federation/entity.rb

@@ -0,0 +1,146 @@
+module DiasporaFederation
+  # +Entity+ is the base class for all other objects used to encapsulate data
+  # for federation messages in the Diaspora* network.
+  # Entity fields are specified using a simple {PropertiesDSL DSL} as part of
+  # the class definition.
+  #
+  # Any entity also provides the means to serialize itself and all nested
+  # entities to XML (for deserialization from XML to +Entity+ instances, see
+  # {XmlPayload}).
+  #
+  # @abstract Subclass and specify properties to implement various entities.
+  #
+  # @example Entity subclass definition
+  #   class MyEntity < Entity
+  #     property :prop
+  #     property :optional, default: false
+  #     property :dynamic_default, default: -> { Time.now }
+  #     entity :nested, NestedEntity
+  #     entity :multiple, [OtherEntity]
+  #   end
+  #
+  # @example Entity instantiation
+  #   nentity = NestedEntity.new
+  #   oe1 = OtherEntity.new
+  #   oe2 = OtherEntity.new
+  #
+  #   entity = MyEntity.new(prop: 'some property',
+  #                         nested: nentity,
+  #                         multiple: [oe1, oe2])
+  #
+  # @note Entity properties can only be set during initialization, after that the
+  #   entity instance becomes frozen and must not be modified anymore. Instances
+  #   are intended to be immutable data containers, only.
+  class Entity
+    extend PropertiesDSL
+
+    # Initializes the Entity with the given attribute hash and freezes the created
+    # instance it returns.
+    #
+    # @note Attributes not defined as part of the class definition ({PropertiesDSL#property},
+    #       {PropertiesDSL#entity}) get discarded silently.
+    #
+    # @param [Hash] data
+    # @return [Entity] new instance
+    def initialize(data)
+      raise ArgumentError, "expected a Hash" unless data.is_a?(Hash)
+      missing_props = self.class.missing_props(data)
+      unless missing_props.empty?
+        raise ArgumentError, "missing required properties: #{missing_props.join(', ')}"
+      end
+
+      self.class.default_values.merge(data).each do |k, v|
+        instance_variable_set("@#{k}", v) if setable?(k, v)
+      end
+      freeze
+    end
+
+    # Returns a Hash representing this Entity (attributes => values)
+    # @return [Hash] entity data (mostly equal to the hash used for initialization).
+    def to_h
+      self.class.class_prop_names.each_with_object({}) do |prop, hash|
+        hash[prop] = send(prop)
+      end
+    end
+
+    # Returns the XML representation for this entity constructed out of
+    # {http://www.rubydoc.info/gems/nokogiri/Nokogiri/XML/Element Nokogiri::XML::Element}s
+    #
+    # @see Nokogiri::XML::Node.to_xml
+    # @see XmlPayload.pack
+    #
+    # @return [Nokogiri::XML::Element] root element containing properties as child elements
+    def to_xml
+      entity_xml
+    end
+
+    # some of this is from Rails "Inflector.demodulize" and "Inflector.undersore"
+    def self.entity_name
+      word = name.dup
+      i = word.rindex("::")
+      word = word[(i + 2)..-1] if i
+
+      word.gsub!("::", "/")
+      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+      word.tr!("-", "_")
+      word.downcase!
+      word
+    end
+
+    private
+
+    def setable?(name, val)
+      prop_def = self.class.class_props.find {|p| p[:name] == name }
+      return false if prop_def.nil? # property undefined
+
+      setable_string?(prop_def, val) || setable_nested?(prop_def, val) || setable_multi?(prop_def, val)
+    end
+
+    def setable_string?(definition, val)
+      (definition[:type] == String && val.respond_to?(:to_s))
+    end
+
+    def setable_nested?(definition, val)
+      t = definition[:type]
+      (t.is_a?(Class) && t.ancestors.include?(Entity) && val.is_a?(Entity))
+    end
+
+    def setable_multi?(definition, val)
+      t = definition[:type]
+      (t.instance_of?(Array) &&
+        val.instance_of?(Array) &&
+        val.all? {|v| v.instance_of?(t.first) })
+    end
+
+    # Serialize the Entity into XML elements
+    # @return [Nokogiri::XML::Element] root node
+    def entity_xml
+      doc = Nokogiri::XML::DocumentFragment.new(Nokogiri::XML::Document.new)
+      root_element = Nokogiri::XML::Element.new(self.class.entity_name, doc)
+
+      self.class.class_props.each do |prop_def|
+        name = prop_def[:name]
+        type = prop_def[:type]
+        if type == String
+          root_element << simple_node(doc, name)
+        else
+          # call #to_xml for each item and append to root
+          [*send(name)].compact.each do |item|
+            root_element << item.to_xml
+          end
+        end
+      end
+
+      root_element
+    end
+
+    # create simple node, fill it with text and append to root
+    def simple_node(doc, name)
+      node = Nokogiri::XML::Element.new(name.to_s, doc)
+      data = send(name).to_s
+      node.content = data unless data.empty?
+      node
+    end
+  end
+end