From 40cc7d82295c0d7c4d6fd8927e32c57061394884 Mon Sep 17 00:00:00 2001 From: Benjamin Neff Date: Sun, 21 Jun 2015 04:40:45 +0200 Subject: [PATCH] MOAR documentation --- README.md | 3 +- .../webfinger_controller.rb | 13 ++++ lib/diaspora_federation.rb | 22 ++++++- .../web_finger/exceptions.rb | 2 +- .../web_finger/web_finger.rb | 61 +++++++++++++++---- 5 files changed, 87 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ef437d2..16e2bf9 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,11 @@ [![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) ## License -This gem is published under the terms of the "GNU Affero General Public License". See the LICENSE file for the exact wording. \ No newline at end of file +This gem is published under the terms of the "GNU Affero General Public License". See the LICENSE file for the exact wording. diff --git a/app/controllers/diaspora_federation/webfinger_controller.rb b/app/controllers/diaspora_federation/webfinger_controller.rb index e387b3b..33a33b3 100644 --- a/app/controllers/diaspora_federation/webfinger_controller.rb +++ b/app/controllers/diaspora_federation/webfinger_controller.rb @@ -21,6 +21,19 @@ module DiasporaFederation ## # @deprecated this is the pre RFC 7033 webfinger # + # example: + # + # + # acct:alice@localhost:3000 + # http://localhost:3000/people/c8e87290f6a20132963908fbffceb188 + # + # + # + # + # + # + # + # # GET /webfinger?q= def legacy_webfinger person = find_person(params[:q]) if params[:q] diff --git a/lib/diaspora_federation.rb b/lib/diaspora_federation.rb index f6fcbf8..45f5214 100644 --- a/lib/diaspora_federation.rb +++ b/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( diff --git a/lib/diaspora_federation/web_finger/exceptions.rb b/lib/diaspora_federation/web_finger/exceptions.rb index 9e21972..1b34db8 100644 --- a/lib/diaspora_federation/web_finger/exceptions.rb +++ b/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 diff --git a/lib/diaspora_federation/web_finger/web_finger.rb b/lib/diaspora_federation/web_finger/web_finger.rb index 724d494..278b363 100644 --- a/lib/diaspora_federation/web_finger/web_finger.rb +++ b/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 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 - # the +vCard+ specification (will affect older Diaspora* installations). - attr_reader :guid, :pubkey + # +hCard+, which actually has fields for an +UID+ defined in the +vCard+ + # specification (will affect older Diaspora* installations). + # + # 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