MOAR documentation

README.md

@@ -7,6 +7,7 @@
 [![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)
 
+[Documentation](http://www.rubydoc.info/github/SuperTux88/diaspora_federation/master) |
 [Project site](https://diasporafoundation.org) |
 [Wiki](https://wiki.diasporafoundation.org) |
 [Bugtracker](http://github.com/SuperTux88/diaspora_federation/issues)

app/controllers/diaspora_federation/webfinger_controller.rb

@@ -21,6 +21,19 @@ module DiasporaFederation
     ##
     # @deprecated this is the pre RFC 7033 webfinger
     #
+    # example:
+    #   <?xml version="1.0" encoding="UTF-8"?>
+    #   <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
+    #     <Subject>acct:alice@localhost:3000</Subject>
+    #     <Alias>http://localhost:3000/people/c8e87290f6a20132963908fbffceb188</Alias>
+    #     <Link rel="http://microformats.org/profile/hcard" type="text/html" href="http://localhost:3000/hcard/users/c8e87290f6a20132963908fbffceb188"/>
+    #     <Link rel="http://joindiaspora.com/seed_location" type="text/html" href="http://localhost:3000/"/>
+    #     <Link rel="http://joindiaspora.com/guid" type="text/html" href="c8e87290f6a20132963908fbffceb188"/>
+    #     <Link rel="http://webfinger.net/rel/profile-page" type="text/html" href="http://localhost:3000/u/alice"/>
+    #     <Link rel="http://schemas.google.com/g/2010#updates-from" type="application/atom+xml" href="http://localhost:3000/public/alice.atom"/>
+    #     <Link rel="salmon" href="http://localhost:3000/receive/users/c8e87290f6a20132963908fbffceb188"/>
+    #     <Link rel="diaspora-public-key" type="RSA" href="LS0tLS1CRU......"/>
+    #   </XRD>
     # GET /webfinger?q=<uri>
     def legacy_webfinger
       person = find_person(params[:q]) if params[:q]

lib/diaspora_federation.rb

@@ -19,10 +19,29 @@ module DiasporaFederation
     attr_accessor :server_uri
 
     ##
-    # the class to use as person.
+    # the class to use as +Person+
     #
     # Example:
     #   config.person_class = Person.to_s
+    #
+    # This class must have the following methods:
+    #
+    # *find_local_by_diaspora_handle*
+    # This should return a +Person+, which is on this pod.
+    #
+    # *webfinger_hash*
+    # This should return a +Hash+ with the followong informations:
+    #   {
+    #     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-----"
+    #   }
     attr_accessor :person_class
     def person_class
       const_get(@person_class)
@@ -42,6 +61,7 @@ module DiasporaFederation
     # validates if the engine is configured correctly
     #
     # called from after_initialize
+    # @raise [ConfigurationError] if the configuration is incomplete or invalid
     def validate_config
       raise ConfigurationError, "missing server_uri" unless @server_uri.respond_to? :host
       validate_class(@person_class, "person_class", %i(

lib/diaspora_federation/web_finger/exceptions.rb

@@ -9,7 +9,7 @@ module DiasporaFederation
     # Raised, if something is wrong with the webfinger data
     #
     # * if the +webfinger_url+ is missing or malformed in {HostMeta.from_base_url} or {HostMeta.from_xml}
-    # * if the +data+ given to {WebFinger.from_account} is an invalid type or doesn't contain all required entries
+    # * if the +data+ given to {WebFinger.from_person} is an invalid type or doesn't contain all required entries
     # * if the parsed XML from {WebFinger.from_xml} is incomplete
     class InvalidData < RuntimeError
     end

lib/diaspora_federation/web_finger/web_finger.rb

@@ -13,7 +13,7 @@ module DiasporaFederation
     #   wf = WebFinger.from_person({
     #     acct_uri:    "acct:user@server.example",
     #     alias_url:   "https://server.example/people/0123456789abcdef",
-    #     hcard_url:   "https://server.example/hcard/users/user",
+    #     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",
@@ -37,17 +37,56 @@ module DiasporaFederation
     class WebFinger
       private_class_method :new
 
-      attr_reader :acct_uri, :alias_url, :hcard_url, :seed_url, :profile_url, :atom_url, :salmon_url
+      # The Subject element should contain the webfinger address that was asked
+      # for. If it does not, then this webfinger profile MUST be ignored.
+      attr_reader :acct_uri
+
+      # Link to the users profile
+      attr_reader :alias_url, :profile_url
+
+      # Link to the +hCard+
+      attr_reader :hcard_url
+
+      # Link to the pod
+      attr_reader :seed_url
+
+      # This atom feed is an Activity Stream of the user's public posts. Diaspora
+      # pods SHOULD publish an Activity Stream of public posts, but there is
+      # currently no requirement to be able to read Activity Streams.
+      # @see http://activitystrea.ms/ Activity Streams specification
+      #
+      # Note that this feed MAY also be made available through the PubSubHubbub
+      # mechanism by supplying a <link rel="hub"> in the atom feed itself.
+      attr_reader :atom_url
+
+      # The salmon endpoint URL
+      # @see http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-salmon-00.html#SMLR
+      #   Panzer draft for Salmon, paragraph 3.3
+      attr_reader :salmon_url
 
       # @deprecated Either convert these to +Property+ elements or move to the
-      #   +hCard+, which actually has fields for an +UID+ and +KEY+ defined in
+      #   +hCard+, which actually has fields for an +UID+ defined in the +vCard+
-      #   the +vCard+ specification (will affect older Diaspora* installations).
+      #   specification (will affect older Diaspora* installations).
-      attr_reader :guid, :pubkey
+      #
+      # This is just the guid. When a user creates an account on a pod, the pod
+      # MUST assign them a guid - a random hexadecimal string of at least 8
+      # hexadecimal digits.
+      attr_reader :guid
 
-      # +hcard+ link relation
+      # @deprecated Either convert these to +Property+ elements or move to the
+      #   +hCard+, which actually has fields for an +KEY+ defined in the +vCard+
+      #   specification (will affect older Diaspora* installations).
+      #
+      # When a user is created on the pod, the pod MUST generate a pgp keypair
+      # for them. This key is used for signing messages. The format is a
+      # DER-encoded PKCS#1 key beginning with the text
+      # "-----BEGIN PUBLIC KEY-----" and ending with "-----END PUBLIC KEY-----".
+      attr_reader :pubkey
+
+      # +hcard_url+ link relation
       REL_HCARD = "http://microformats.org/profile/hcard"
 
-      # +seed_location+ link relation
+      # +seed_url+ link relation
       REL_SEED = "http://joindiaspora.com/seed_location"
 
       # @deprecated This should be a +Property+ or moved to the +hCard+, but +Link+
@@ -56,20 +95,20 @@ module DiasporaFederation
       # +guid+ link relation
       REL_GUID = "http://joindiaspora.com/guid"
 
-      # +profile-page+ link relation.
+      # +profile_url+ link relation.
       # @note This might just as well be an +Alias+ instead of a +Link+.
       REL_PROFILE = "http://webfinger.net/rel/profile-page"
 
-      # Atom feed link relation
+      # +atom_url+ link relation
       REL_ATOM = "http://schemas.google.com/g/2010#updates-from"
 
-      # +salmon+ endpoint link relation
+      # +salmon_url+ link relation
       REL_SALMON = "salmon"
 
       # @deprecated This should be a +Property+ or moved to the +hcard+, but +Link+
       #   is inappropriate according to the specification (will affect older
       #   Diaspora* installations).
-      # +diaspora-public-key+ link relation
+      # +pubkey+ link relation
       REL_PUBKEY = "diaspora-public-key"
 
       # Create the XML string from the current WebFinger instance