class DiasporaFederation::Discovery::WebFinger
The WebFinger
document used for diaspora* user discovery is based on an {datatracker.ietf.org/doc/html/rfc7033 RFC 7033}.
@example Creating a WebFinger
document from a person hash
wf = WebFinger.new( acct_uri: "acct:user@server.example", hcard_url: "https://server.example/hcard/users/user", 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" ) json_string = wf.to_json
@example Creating a WebFinger
instance from an JSON document
wf = WebFinger.from_json(json_string) ... hcard_url = wf.hcard_url ...
@see www.iana.org/assignments/link-relations/link-relations.xhtml
official list of IANA link relations
Constants
- REL_ATOM
atom_url
link relation- REL_HCARD
hcard_url
link relation- REL_PROFILE
profile_url
link relation. @note This might just as well be anAlias
instead of aLink
.- REL_SALMON
salmon_url
link relation- REL_SEED
seed_url
link relation- REL_SUBSCRIBE
subscribe_url
link relation
Attributes
Additional WebFinger
data @return [Hash] additional elements
Public Class Methods
Creates a WebFinger
instance from the given data @param [Hash] data WebFinger
data hash @return [WebFinger] WebFinger
instance
# File lib/diaspora_federation/discovery/web_finger.rb, line 132 def self.from_hash(data) links = data[:links] new( acct_uri: data[:subject], hcard_url: parse_link(links, REL_HCARD), seed_url: parse_link(links, REL_SEED), profile_url: parse_link(links, REL_PROFILE), atom_url: parse_link(links, REL_ATOM), salmon_url: parse_link(links, REL_SALMON), subscribe_url: parse_link_template(links, REL_SUBSCRIBE) ) end
Creates a WebFinger
instance from the given JSON string @param [String] webfinger_json WebFinger
JSON string @return [WebFinger] WebFinger
instance
# File lib/diaspora_federation/discovery/web_finger.rb, line 125 def self.from_json(webfinger_json) from_hash(parse_json_and_validate(webfinger_json)) end
@!visibility private Parsing WebFinger
as XML is not supported anymore, use {from_json} instead.
# File lib/diaspora_federation/discovery/web_finger.rb, line 118 def self.from_xml(_webfinger_xml) raise "Parsing WebFinger as XML is not supported anymore, use 'from_json' instead." end
Initializes a new WebFinger
Entity
@param [Hash] data WebFinger
data @param [Hash] additional_data
additional WebFinger
data @option additional_data
[Array<String>] :aliases additional aliases @option additional_data
[Hash] :properties properties @option additional_data
[Array<Hash>] :links additional link elements @see DiasporaFederation::Entity#initialize
# File lib/diaspora_federation/discovery/web_finger.rb, line 99 def initialize(data, additional_data={}) @additional_data = additional_data super(data) end
Private Class Methods
# File lib/diaspora_federation/discovery/web_finger.rb, line 194 def self.find_link(links, rel) links.find {|l| l[:rel] == rel } end
Parses the JSON string to a Hash and does some rudimentary checking on the data Hash. @param [String] webfinger_json WebFinger
JSON string @return [Hash] data JSON data @raise [InvalidData] if the given JSON string is invalid or incomplete
# File lib/diaspora_federation/discovery/web_finger.rb, line 160 def self.parse_json_and_validate(webfinger_json) XrdDocument.json_data(webfinger_json).tap do |data| valid = data.key?(:subject) && data.key?(:links) raise InvalidData, "Webfinger JSON is incomplete" unless valid end end
# File lib/diaspora_federation/discovery/web_finger.rb, line 198 def self.parse_link(links, rel) element = find_link(links, rel) element ? element[:href] : nil end
# File lib/diaspora_federation/discovery/web_finger.rb, line 203 def self.parse_link_template(links, rel) element = find_link(links, rel) element ? element[:template] : nil end
Public Instance Methods
Creates the JSON string from the current WebFinger
instance @return [String] JSON string
# File lib/diaspora_federation/discovery/web_finger.rb, line 112 def to_json(*_args) to_xrd.to_json end
@return [String] string representation of this object
# File lib/diaspora_federation/discovery/web_finger.rb, line 149 def to_s "WebFinger:#{acct_uri}" end
@!visibility private Generating WebFinger
to XML is not supported anymore, use {#to_json} instead.
# File lib/diaspora_federation/discovery/web_finger.rb, line 106 def to_xml raise "Generating WebFinger to XML is not supported anymore, use 'to_json' instead." end
Private Instance Methods
# File lib/diaspora_federation/discovery/web_finger.rb, line 177 def add_links_to(doc) doc.links << {rel: REL_HCARD, type: "text/html", href: hcard_url} doc.links << {rel: REL_SEED, type: "text/html", href: seed_url} add_optional_links_to(doc) doc.links.concat(additional_data[:links]) if additional_data[:links] end
# File lib/diaspora_federation/discovery/web_finger.rb, line 186 def add_optional_links_to(doc) doc.links << {rel: REL_PROFILE, type: "text/html", href: profile_url} if profile_url doc.links << {rel: REL_ATOM, type: "application/atom+xml", href: atom_url} if atom_url doc.links << {rel: REL_SALMON, href: salmon_url} if salmon_url doc.links << {rel: REL_SUBSCRIBE, template: subscribe_url} if subscribe_url end
# File lib/diaspora_federation/discovery/web_finger.rb, line 167 def to_xrd XrdDocument.new.tap do |xrd| xrd.subject = acct_uri xrd.aliases.concat(additional_data[:aliases]) if additional_data[:aliases] xrd.properties.merge!(additional_data[:properties]) if additional_data[:properties] add_links_to(xrd) end end