module DiasporaFederation

diaspora* federation library

Constants

VERSION

the gem version

Attributes

callbacks[R]

{Callbacks} instance with defined callbacks @see Callbacks#on @see Callbacks#trigger @return [Callbacks] callbacks

certificate_authorities[RW]

Set the bundle of certificate authorities (CA) certificates

@overload certificate_authorities

@return [String] path to certificate authorities

@overload certificate_authorities=

@example
  config.certificate_authorities = AppConfig.environment.certificate_authorities.get
@param [String] value path to certificate authorities
http_concurrency[RW]

Maximum number of parallel HTTP requests made to other pods (default: 20)

@overload http_concurrency

@return [Integer] max number of parallel requests

@overload http_concurrency=

@example
  config.http_concurrency = AppConfig.settings.typhoeus_concurrency.to_i
@param [Integer] value max number of parallel requests
http_redirect_limit[R]

Max redirects to follow @return [Integer] max redirects

http_timeout[RW]

Timeout in seconds for http-requests (default: 30)

@overload http_timeout

@return [Integer] http timeout in seconds

@overload http_timeout=

@param [Integer] value http timeout in seconds
http_user_agent[R]

User agent used for http-requests @return [String] user agent

http_verbose[RW]

Turn on extra verbose output when sending stuff. (default: false)

@overload http_verbose

@return [Boolean] verbose http output

@overload http_verbose=

@example
  config.http_verbose = AppConfig.settings.typhoeus_verbose?
@param [Boolean] value verbose http output
server_uri[RW]

The pod url

@overload server_uri

@return [URI] the server uri

@overload server_uri=

@example with uri
  config.server_uri = URI("http://localhost:3000/")
@example with configured pod_uri
  config.server_uri = AppConfig.pod_uri
@param [URI] value the server uri
webfinger_http_fallback[RW]

Configure if WebFinger discovery should fallback to http if https fails (default: false)

This is useful for example for development environments where https isn’t available.

This setting only applies to the WebFinger route from RFC 7033 /.well-known/webfinger. Legacy WebFinger flow unconditionally falls back to http.

@overload webfinger_http_fallback

@return [Boolean] webfinger http fallback enabled

@overload webfinger_http_fallback=

@example
  config.webfinger_http_fallback = AppConfig.server.rails_environment == "development"
@param [Boolean] value  webfinger http fallback enabled

Public Class Methods

configure() { |self| ... } click to toggle source

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_callbacks(&block) click to toggle source

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
validate_config() click to toggle source

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

Private Class Methods

configuration_error(message) click to toggle source
# File lib/diaspora_federation.rb, line 263
def configuration_error(message)
  logger.fatal "diaspora federation configuration error: #{message}"
  raise ConfigurationError, message
end
validate_http_config() click to toggle source
# File lib/diaspora_federation.rb, line 254
def validate_http_config
  configuration_error "http_concurrency: please configure a number" unless @http_concurrency.is_a?(Integer)
  configuration_error "http_timeout: please configure a number" unless @http_timeout.is_a?(Integer)

  return unless !@http_verbose.is_a?(TrueClass) && !@http_verbose.is_a?(FalseClass)

  configuration_error "http_verbose: please configure a boolean"
end