module DiasporaFederation

Configure the federation library

@example

DiasporaFederation.configure do |config|
  config.server_uri = URI("http://localhost:3000/")

  config.define_callbacks do
    # callback configuration
  end
end

# File lib/diaspora_federation.rb, line 141
def configure
  yield self
end

Define the callbacks

In order to communicate with the application which uses the diaspora_federation gem callbacks are introduced. The callbacks are used for getting required data from the application or posting data to the application.

Callbacks are implemented at the application side and must follow these specifications:

fetch_person_for_webfinger

Fetches person data from the application to form a WebFinger reply
@param [String] diaspora* ID of the person
@return [DiasporaFederation::Discovery::WebFinger] person webfinger data

fetch_person_for_hcard

Fetches person data from the application to reply for an HCard query
@param [String] guid of the person
@return [DiasporaFederation::Discovery::HCard] person hcard data

save_person_after_webfinger

After the gem had made a person discovery using WebFinger it calls this callback
so the application saves the person data
@param [DiasporaFederation::Entities::Person] person data

fetch_private_key

Fetches a private key of a person by her diaspora* ID from the application
@param [String] diaspora* ID of the person
@return [OpenSSL::PKey::RSA] key

fetch_public_key

Fetches a public key of a person by her diaspora* ID from the application
@param [String] diaspora* ID of the person
@return [OpenSSL::PKey::RSA] key

fetch_related_entity

Fetches a related entity by a given guid
@param [String] entity_type (Post, Comment, Like, etc)
@param [String] guid of the entity
@return [DiasporaFederation::Entities::RelatedEntity] related entity

queue_public_receive

Queue a public salmon xml to process in background
@param [String] data salmon slap xml or magic envelope xml

queue_private_receive

Queue a private salmon xml to process in background
@param [String] guid guid of the receiver person
@param [String] data salmon slap xml or encrypted magic envelope json
@return [Boolean] true if successful, false if the user was not found

receive_entity

After the xml was parsed and processed the gem calls this callback to persist the entity
@param [DiasporaFederation::Entity] entity the received entity after processing
@param [Object] recipient_id identifier for the recipient of private messages or nil for public,
  see {Receiver.receive_private}

fetch_public_entity

Fetch a public entity from the database
@param [String] entity_type (Post, StatusMessage, etc)
@param [String] guid the guid of the entity

fetch_person_url_to

Fetch the url to path for a person
@param [String] diaspora_id
@param [String] path

update_pod

Update the pod status
@param [String] url the pod url
@param [Symbol, Integer] status the error as {Symbol} or the http-status as {Integer} if it was :ok

@see Callbacks#on

@example

config.define_callbacks do
  on :some_event do |arg1|
    # do something
  end
end

@param [Proc] block the callbacks to define

# File lib/diaspora_federation.rb, line 225
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

# File lib/diaspora_federation.rb, line 233
def validate_config
  configuration_error "server_uri: Missing or invalid" unless @server_uri.respond_to? :host

  unless defined?(::Rails) && !::Rails.env.production?
    configuration_error "certificate_authorities: Not configured" if @certificate_authorities.nil?
    unless File.file? @certificate_authorities
      configuration_error "certificate_authorities: File not found: #{@certificate_authorities}"
    end
  end

  validate_http_config

  unless @callbacks.definition_complete?
    configuration_error "Missing handlers for #{@callbacks.missing_handlers.join(', ')}"
  end

  logger.info "successfully configured the federation library"
end