Project site | Wiki | Docs
The goal of this gem is to provide a library of reusable code for the purpose of implementing the protocols used around Diaspora. This covers user discovery utilizing the XRD, HostMeta, WebFinger and hCard standards as well as the message passing implementation using a subset of the Salmon protocol.
One of the main ideas behind this lib was to avoid any dependencies toward a specific web framework. This means any app using this gem is free to set up HTTP routing and database infrastructure any way it sees fit, as long as the few required routes are handled to specification.
When Diaspora attempts to discover a remote user account, the server name is
extracted from the account handle: "[email protected]" => "server.example"
Next, a GET
request is sent to the servers host-meta route
https://server.example/.well-known/host-meta
which returns an XRD document with
the application/xrd+xml
media type.
The contained Link
element with rel="lrdd"
inside the
{DiasporaFederation::WebFinger::HostMeta HostMeta} document contains a template
URL in its template
attribute. It will be used for querying the WebFinger document.
Example: HostMeta request
GET /.well-known/host-meta HTTP/1.1
Example: HostMeta response
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Link rel="lrdd" type="application/xrd+xml" template="https://server.example/webfinger?q={uri}"/>
</XRD>
To retrieve the {DiasporaFederation::WebFinger::WebFinger WebFinger} document,
the placeholder {uri}
in the template has to be replaced by the acct
URI of
the account to look up:
https://server.example/webfinger?q=acct:[email protected]
Now this URL can be used in a GET
request to fetch the WebFinger document, which
also consists of an XRD document served with the application/xrd+xml
media type.
The document already contains some basic information associated with the queried
user account. More specific profile details are in the referenced hCard document.
The URL is contained in the href
attribute of the Link
element with
rel="http://microformats.org/profile/hcard"
Example: WebFinger request
GET /webfinger?q=acct:[email protected] HTTP/1.1
Example: WebFinger response
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Subject>acct:[email protected]</Subject>
<Alias>https://server.example/people/0123456789abcdef</Alias>
<Link rel="http://microformats.org/profile/hcard" type="text/html" href="https://server.example/hcard/users/user"/>
<Link rel="http://joindiaspora.com/seed_location" type="text/html" href="https://server.example/"/>
<Link rel="http://joindiaspora.com/guid" type="text/html" href="0123456789abcdef"/>
<Link rel="http://webfinger.net/rel/profile-page" type="text/html" href="https://server.example/u/user"/>
<Link rel="http://schemas.google.com/g/2010#updates-from" type="application/atom+xml" href="https://server.example/public/user.atom"/>
<Link rel="diaspora-public-key" type="RSA" href="ABCDEF=="/>
</XRD>
The {DiasporaFederation::WebFinger::HCard hCard} document can be accessed by
issuing a GET
request to the hCard URL extracted from the WebFinger document.
It will return a simple HTML page with the text/html
media type, containing the
public profile information of the queried user, marked up as specified in the
hCard microformat standard (using class
attributes on the elements,
thereby giving them semantic meaning).
Example: hCard request
GET /hcard/users/user HTTP/1.1
Example: hCard response
HTTP/1.1 200 OK
Content-Type: text/html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
[...]
</html>
All of the described documents can be generated and parsed by classes shipped with this gem. You can find them in the {DiasporaFederation::WebFinger} module. See the included documentation for specifics on how to use them.
(TODO)