Skip to content
This repository has been archived by the owner on Dec 31, 2020. It is now read-only.

Tent URL Scheme

Jump to bottom
noformnocontent edited this page Dec 18, 2012 · 34 revisions

This document will try to define what exactly a potential Tent URL Scheme could be used for.

Alternative 1

Follow an entity

tent://follow?<entity_full_uri>

Unfollow an entity

tent://unfollow?<entity_full_uri>

View an Entity’s profile

tent://profile?<entity_full_uri>

View an Entity’s post

tent://posts
  ?<entity_full_uri>
  &<post_id>

New Post

More on what can be included in POST query see in tent-schemas

tent://post
    ?type=<post_type>
    &content=<post_content>
  [ &mentions=<entities_list> ]
  [ &published_at=<timestamp> ]
  [ &permissions=
      <public=( true | false ) [ &( groups=<groups_list> | <entities_list> ) ]>
  ]
  [ &licenses=<licenses_list> ]
  [ &<all_other_possible_post_properties> ]

Alternative 2

Originally proposed by @graue/scott.mn (but see Alternative 4 below for a revised suggestion): The entity should come first, followed by the resource or action.

tent://<entity_full_uri>
tent://<entity_full_uri>/follow
tent://<entity_full_uri>/unfollow
tent://<entity_full_uri>/profile
tent://<entity_full_uri>/posts/<post_id>
tent://<entity_full_uri>/post?<all_those_post_content_and_details>

This allows links (including mentions) and transclusions from HTML ‘essay’ posts in a natural way.

Fictional example

Just got back from the first Tent conference. <a href="tent://marco.tent.is/posts/ockwsl">Marco Ferreira's talk</a> was my favorite. In addition to him, I got to hang out with <a href="tent://daniel.tent.is">Daniel Siders</a>, and here's a picture: <img src="tent://graue.tent.is/posts/jookxw/attachments/image.jpg">

A webapp can translate those links into https:// URLs for a browser. Actions could still be specified using URIs like tent://someone.tent.is/follow.

Discussion on alternative scheme

Q: Don’t we need to know if the entity URL is http or https?

A: Yes and no. If no http(s) is given in the url, it should default to https. In case https has no entity (or doesn't respond), http is used.

Unfortunately, this proposed scheme of falling back from https to http destroys the security of using https in the first place. If you're an MITM attacker, you just block access to https on the target machine, the Tent client falls back to http, and you proxy to https, spying on and altering the data. A more secure option would be to use a different protocol, like tent-http:// for non-SSL entities.

Q: How can you tell if tent://test.tent.is/posts/123456 is referring to profile of http://test.tent.is/posts/123456 or to post 123456 of http://test.tent.is?

Alternative 3

This is the summary of a discussion inside the IRC channel. This alternative is a work in progress and still open to discussion. It more or less combines both alternatives from above.

Example

  • x-tents://tobiastom.tent.is – Direct link to my profile, app is supposed to open my profile.
  • x-tents://tobiastom.tent.is#65gz6h – Direct link to a post on my profile, app is supposed to open the post with the ID 65gz6h from my profile.

Scheme

We decided that it might be a good idea to use x-tent and x-tents. Both are prefixed with the ´x-´ to make it obvious that this are not official tent schemes. If at a later point the tent core developers decide to adopt this proposal, the x might be dropped.

x-tent stands for entities that are accessible via HTTP, x-tents is the alternative for HTTPS. The removal of the HTTP or HTTPS protocol was required because they would be opened in the default browser and could not be handled with other applications. As it is quite like HTTP this could provide less confusion.

Entities

An entity will be opened with the exact same URL as the HTTP(s) link, with the protocol replaced through x-tent(s).

Posts

Unique posts can be accessed with the entity, followed by an # and the unique post ID. A # cannot be part of the entity (it would not be send to the server anyways), so it's save to use this.

Actions

We discussed if there is really a need for actions. Follow for example should not be an action. The application should open the profile. The user the could decide of he would likes to follow this entity or not.

The only real action right now would be to create new posts. A possible solution would be:

  • x-tent://intent/<action>?key=value – Applications would need to check if the host part is intent, if it is, the action is defined through the protocol. Appended are all parameters as key-value pair. Known issues: none.

This was also favored:

  • x-tent-intent://<postTypeURL>?key=value - No known issues, but a separate registered scheme.

We also discussed some other solution which all had their own issues:

  • x-tent://<action>?key=value – The action as host part. The problem is that we could not distinguish between an entity and an action. Reserved words would be a solution for that. Also having a requirement that actions only can contain [a-z0-9-_] would solve this.
  • x-tent://<postTypeURL>#publish – This could define the exact post type, but it would get quite ugly to append parameters to it: x-tent://tent.io/types/post/essay/v0.1.0?body=lala#publish

Problems

  • Applications can only register for all tent post types, or none. If an application is only able to handle status posts, but the requested post is an image post, the behavior would be undefined. This cannot easily be solved. Registering just x-tent-photo is not an option. Post types are defined as URLs, which might be different: https://tent.io/types/post/photo/v0.1.0 and https://example.com/photo/v0.1.0 define different photo types, which could not be covered by x-tent-photo. A possible solution would be to let the application forward the user to a supporting app, how that might be defined was not covered.

Alternative 4, http(s)+tent://

To refer to an entity:

https+tent://scott.mn
http+tent://longearstestaccount.tumblr.com
http+tent://an.example/that/has/slashes/in/it/and/everything/

To refer to post ID hm56kl:

https+tent://scott.mn?hm56kl
http+tent://longearstestaccount.tumblr.com?hm56kl
http+tent://an.example/that/has/slashes/in/it/and/everything/?hm56kl

Rationale: Alternative 3 above is a good start. This improves on it in two ways:

  • Using http+tent and https+tent makes it crystal clear that Tent is an additional protocol layered over HTTP(S). (Note that RFC1738 section 2.1 explicitly allows the + symbol in scheme names.)

  • Identifying posts with the fragment identifier # is semantically incorrect and seems to violate section 2.2 of RFC1738, which requires # to only appear encoded in URLs. Section 2.2 says:

The characters ";", "/", "?", ":", "@", "=" and "&" are the characters which may be reserved for special meaning within a scheme. No other characters may be reserved within a scheme.

In practice, there's unlikely to be any practical reason to allow ? in an entity URI and the use conforms with the RFC.

This scheme only addresses referring to content (entities and posts), not actions. Actions are best handled by a separate URI scheme, in this author's opinion. Since the choice of HTTP or HTTPS is not known to the linking page, the distinction between http+tent and https+tent is meaningless and misleading in such a case. For triggering actions, any of the suggestions in Alternative 3 would suffice as a stopgap.

This alternative has been suggested by https+tent://scott.mn.

Inline usage

Pretty much like with person-mentions (^entity) there should be a way to quickly refer to posts.

Hashtag usage (as it supposedly can't be part of an entity) seems like a good solution so far: ^example.com#er3Tbw

Even with ports, paths, and query strings: ^www.cs.edu.example.com:2600/~username/index.php?project=project2#er3Tbw

Clone this wiki locally