SWAT0 - strawman protocol flow

Summary

This is a strawman protocol flow to solve SWAT0. This flow is based on Activitystreams, PuSH, Salmon and Webfinger. I assume (but not looked at the spec in a while) that it matches the OStatus approach at solving it. If we get agreement on the high level flow, I propose to document every transaction with example requests and payloads.

Note that it is only one possibility amongst many others. As far as I understand SWAT0, it does not mandate a specific technology. So, other can come up with other HTTP flows, or even XMPP, etc.

This is a rough early draft, I rushed it due to time constraint and will iterate. Don't take this as a reference.

References

The flow below is based on the following four proposals. Here are the links I used as reference, please update would you be aware of newer versions.

• Activitystreams: atom-activity-01
• PubSubHubBub: pubsubhubbub-core-0.3
• Webfinger: WebFinger Protocol
• Salmon: draft-panzer-salmon-00

Open issues

Below is the list of the points where people disagree and link to the mailing list discussion on the topic. Please do not use this page as a place for debate (or fork your own page from this one if you want to illustrate a point).

• [Step 2] domain only identifiers: should they be supported (and how) or not ? [1]
• [Step 6] commenting flow: who is pushng which comment to whom ? [2]
• Thoughts on Federation Models

High level flow

1. With his phone, Dave takes a photo of Tantek and uploads it using a service

This is done with the specific client (and API) of the service Dave is using.

Outcome: the server is now in a position to construct an Atom entry representing the object, augmented with activitystreams info. It will be a post of a photo object. The entry must have the properties defined in activity-schema-01.

Notes:

• This entry should already be pushed to Evan but that is not made really clear in SWAT0
• It may be interesting to also standardize client-server APIs (AtomPub could be a starting point, or one of the existing API like the Google Buzz one). I like it that in the email world, I can use any POP3/IMAP email client to connect to any email server.

2. Dave tags the photo with Tantek

This is also done with the specific client provided by Dave service provider. Since this might be the first time Dave may mention Tantek, Dave has to enter the identifier Tantek provides as his, e.g. tantek.com. This identifier may also be the same form as an email address (user@domain.com). For the sake of this example, it is tantek.com.

• It may be worth noting that like Flickr and Facebook, the application may choose to limit a user to being able to tag a photo with someone from their contacts. This constraint means that the user's proper identifier (user@service or example.org) can be filled in by the application, while David just finds Tantek in the UI for selecting the contact to use for the tag/mention. Steveivy
  • Note that Flickr does allow you to tag a photo with a Flickr user *outside* your contacts (you just have to click "Search all Flickr users"), and you also have the option of tagging a non-Flickr user with an email address, and then I think Flickr sends email to that person to confirm that they are in the photo (and are ok with being tagged) before showing the tag. Not sure of the exact flow, but it is possible to tag non-Flickr users in Flickr photos. — Tantek 19:17, 27 July 2010 (UTC)

Outcome: the server can now create a second Atom entry representing the tagging action using activitystreams [3]. It will be a tag verb, the object will be a representation of Tantek, and the target is the previously created photo object. In addition, since Tantek is 'mentioned' in this entry and must be made aware of it, it enhances the entry with a salmon link relation as per draft-panzer-salmon-00.html#SALR. The entry can now be signed by salmon draft-panzer-salmon-00.html#Signing.

Notes:

• There is a strong debate here on the identifier to use. Some implementations are limiting to user@domain but some participants would still like to permit users to use single domains (e.g. tantek.com) as well. No general agreement yet. See domain-identifiers for more.

3. Tantek gets a notification on another service that he's been tagged in a photo

Dave service provider must now disover who is tantek.com and how a notification can be pushed to him. This may be done via salmon discovery Salmon Discovery. Which for mention endpoint can use the Webfinger protocol. WebFinger Protocol.

The flow is then:

1. Host-meta discovery and verification on tantek.com domain. Obtaining host meta document
2. Retrieving the lrdd link from the host meta document. The LRDD Relation type
3. Get the user XRD document using LRDD and search for the salmon link relation in the document, defining the salmon endpoint where the mention should be pushed.
4. Post the entry containing the mention to the discovered salmon endpoint. Replies Protocol Flow

Outcome: Tantek's service is now aware of the mention and can notify Tantek by a service specific means (e.g. mobile client push, IM, email, newsfeed, ...).

Note:

• There was so much debate on the webfinger mailing list lately that I'm not sure this reflect the last thinking on this topic.

4. Evan, who is subscribed to Dave, sees the photo on yet another service

Evan (e.g. evan@status.net) has already subscribed to Dave's feed. This was done prior to this test (but exact flow may have to be added and documented in preconditions to the test ?).

This subscription could be simply a subscription to Dave's feed and Evan see the new object in his feed reader. It is preferably a PubSubHubBub flow so that Evan's server gets realtime notification of updates and can push that notification to Evan's client if he is online (using a service specific means).

5. Evan comments on the photo

This is done using Evan service specific UI. The server then constructs an Activitystream entry of verb post and object type comment. It also adds the thr: in-reply-to atom threading extensions The thr:in-reply-to Extension Element. The entry is then salmon signed. Since the photo entry contains a salmon reply endpoint link (see (2)), Evan's service can post the reply to the salmon reply endpoint of Dave's entry.

6. David and Tantek receive notifications that Evan has commented on the photo

Upon receiving the comment, Dave's service can update the thr:count & thr:updated of the entry and add a thr:replies element if it was not present already. Since the entry has been updated, it can now push the update to the subscribers (and everyone mentioned in the entry). This is used through salmon for the mentions (see 3.) and through Atom/PuSH for the subscribers (see 4.). Upon receiving the updated entry, Evan and Tantek can fetch the latest replies following the thr:replies link.