diff --git a/Gemfile b/Gemfile index de2d5ec..b64b012 100644 --- a/Gemfile +++ b/Gemfile @@ -16,3 +16,4 @@ gem 'adsf' gem 'builder' gem 'tent-schemas', :git => 'git://github.com/tent/tent-schemas.git', :branch => 'master' gem 'pygments.rb', :git => 'git://github.com/akzhan/pygments.rb.git', :branch => 'rubypython-0.6' +gem 'fssm', :groups => :development diff --git a/Gemfile.lock b/Gemfile.lock index 79289ff..d81911d 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -27,6 +27,7 @@ GEM cri (2.3.0) colored (>= 1.2) ffi (1.0.11) + fssm (0.2.9) json-schema (1.0.9) mime-types (1.19) nanoc (3.4.0) @@ -56,6 +57,7 @@ DEPENDENCIES adsf builder clogger + fssm mime-types nanoc nanoc-cachebuster diff --git a/content/assets/images/diagram.png b/content/assets/images/diagram.png new file mode 100644 index 0000000..92cef04 Binary files /dev/null and b/content/assets/images/diagram.png differ diff --git a/content/docs/app-auth.md b/content/docs/app-auth.md index 7c8a01e..25cab87 100644 --- a/content/docs/app-auth.md +++ b/content/docs/app-auth.md @@ -5,17 +5,16 @@ title: App Authentication ## App Authentication Tent uses [OAuth 2](http://tools.ietf.org/html/draft-ietf-oauth-v2-31) for app -authentication. Because of the distributed nature of Tent, it is necessary for -apps to register with the Tent entity before doing the authentication flow. +authentication. Because of the distributed nature of Tent, +apps must register with the Tent entity before starting the authentication flow. -After the authentication flow, requests are authenticated using the credentials +After the authentication flow is complete, requests are authenticated using the credentials with [MAC Access Authentication](http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01). ### App Registration - Before authenticating a user, the application must be registered with the specified Tent entity. The first step is to perform discovery on the provided entity url. diff --git a/content/docs/index.md b/content/docs/index.md index 2ea8bc6..a361e26 100644 --- a/content/docs/index.md +++ b/content/docs/index.md @@ -1,14 +1,6 @@ --- title: Protocol Introduction --- - -## The Tent Protocol - -Tent is a protocol for decentralized social networking. It allows you to control your data, who has access to it, and what can be done with it. - -Anyone can run a Tent server or write a Tent app. There are Tent hosts for users who do not want to manage a server. - - ### API Overview Tent is a social layer over HTTP using [JSON](http://en.wikipedia.org/wiki/JSON). @@ -30,8 +22,8 @@ a Tent profile (e.g. `https://tent.johnsmith.me/profile`) ### Servers -Tent servers are the protocol core. They represent the users and maintain their data and relationships. Servers also handle these responsibilities: - +Tent **servers** are the protocol core. They represent the users and maintain their data and relationships. Servers also handle these responsibilities: + - Persisting data - Notifying other servers about new data - Ensuring content is only pushed to recipients accepting associated licences @@ -40,40 +32,60 @@ Tent servers are the protocol core. They represent the users and maintain their - Authorizing apps to access data - Notifying apps about new or modified data to which they have access -tentd is the current reference Tent server. +[tentd](https://github.com/tent/tentd) is the current reference Tent server. ### Apps -Users create and view content on apps. Apps must authenticate with the user's server before content can be posted or viewed. +Users create and view **posts** and **profiles** on **apps**. Apps must authenticate with the user's server before content can be posted or viewed. -For example: +The Process: -1. ian-hanson.me (Ian) posts a status update (post) from a micro blogging app authenticated with his server. -2. The app publishes the post to his server. -3. His server sends a notification to every server following him or mentioned in the post with permission to see the post. -4. If anna-collins.me (Anna) is following Ian, her server will receive a notification from Ian’s server containing the post. -5. If Anna has an app setup for consuming status updates, her server will send it a notification with Ian’s post. -6. Anna can now read Ian’s post from the status app. -7. If Anna decides to reply, her response will follow a path inverse to Ian’s post. +1. User A creates a `status` post on her app. +2. App sends posts to user A's server. +3. User A's Server sends post notifications to all users who follow User A's `status` posts and users mentioned in this post. The server will not send notifications to users not allowed in the post's permissions. +4. The servers operated by user A's followers each receive this notification. +5. These servers each send the post to the appropriate app(s). +6. The following users can view the post on their apps. TentStatus is an open source Tent app for creating and viewing status posts. ### Posts -Posts are at the core of Tent. They are sent to followers immediately after being created. Users set permissions on each post that determine which other users can access them. Other users can fetch public posts individually or over a date range. Posts each have a post type which describes its data. Tent posts can be used to describe anything, and developers can create new post types for different kinds of media, interactions, or applications. This documentation describes four basic post types: **status**, short messages of 140 characters or less, **essay**, longer form writing, **photo**, pictures, and **album**, a collection of **photo** posts. +**Posts** are at the core of Tent. Posts are sent to followers immediately after being created. + +Users set permissions on each post that determine which other users can access them. Other users can fetch public posts individually or over a date range. + +Post types describe the format and content of each post. Tent posts can be used for almost anything, and developers can create new post types for different kinds of media, interactions, or applications. + +This documentation describes four basic post types: `status`, short messages of 140 characters or less, `essay`, longer form writing, `photo`, pictures, and `album`, a collection of `photo` posts. ### Profiles -Every Tent entity's server has a profile JSON file describing it. They store information about the user, specifically static information that should always be accessible. +Every Tent entity's server has a **profile** JSON file describing it. Profiles store information about the user, specifically static information that should always be accessible. -The most basic profile -has a single object containing the Tent version, the entity name (e.g. +The most basic profile has a single object containing the Tent version, the entity name (e.g. johnsmith.me), an array of supported licences, and an array of servers containing canonical API roots. -A user may have multiple versions of the same info type in your profile. +A user may have multiple versions of the same info type in their profile. ### Notifications -Tent notifications are used when a server needs to let another server or app -know about new content updates. This includes new posts and profile changes. Notifications are JSON POST requests containing posts. \ No newline at end of file +Tent **notifications** are used when a server needs to let another server or app +know about new content updates. This includes new posts and profile changes. Notifications are JSON POST requests containing posts. A new notification is sent for event (post, following event, profile change). + +### Example + +https://cloudmir.com/ (Lindsay) and https://titanous.com (Jonathan) are both following https://daniel.tent.is (Daniel) and have requested all his status posts. + +2. https://daniel.tent.is creates a `status` post on TentStatus in which he mentions another user, https://jesse.tent.is (Jesse). + +3. TentStatus sends this post to Daniel's server. + +4. Daniel's server sends post notifications to Lindsay and Jonathan, because they follow Daniel and requested all `status` posts he creates, and Jesse, because the post mentions him. + +5. Lindsay, Jonathan, and Jesse's servers receive the post and send a copy of the post to TentStatus, the application they each have configures to read `status` posts. + +6. Lindsay, Jonathan, and Jesse can each read, reply to, repost, or ignore the post as they wish. + +![diagram](/assets/images/diagram.png) \ No newline at end of file diff --git a/content/docs/server-protocol.md b/content/docs/server-protocol.md index b315294..192cf3a 100644 --- a/content/docs/server-protocol.md +++ b/content/docs/server-protocol.md @@ -3,7 +3,7 @@ This document describes the protocol that Tent servers use to communicate with each other. -###Basics +### Basics Every Tent user is represented by a server. Servers establish and maintain relationships and exchange content between users. @@ -28,7 +28,10 @@ Link: ; rel="https://tent.io/rels/profile" ``` or ```text -Link: ; rel="https://tent.io/rels/profile", ; rel="https://tent.io/rels/profile", ; rel="https://tent.io/rels/profile" +Link: ; rel="https://tent.io/rels/profile", +; rel="https://tent.io/rels/profile", + +; rel="https://tent.io/rels/profile" ``` #### HTML `link` tag diff --git a/layouts/doc.slim b/layouts/doc.slim index 6ca5a9f..85d1690 100644 --- a/layouts/doc.slim +++ b/layouts/doc.slim @@ -16,6 +16,8 @@ html lang='en' li == nav_link_with_active 'Post Types', '/docs/post-types' li == nav_link_with_active 'Profile Info Types', '/docs/info-types' .span8 + .lead + p Tent is a protocol for decentralized social networking. .alert.alert-block h4 Alpha Documentation p These docs are very rough, incorrect, and incomplete. They will be modified heavily over the next few weeks.