An introduction to the Diaspora source: Difference between revisions
m (Updated links to cucumber framework and Jasmine framework) |
(+ood notice) |
||
| (6 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Out of date}}{{Note|1=This page got updates some minor updates recently, but please check if everything is correct. If the content of this page is sufficiently described elsewhere (in the [[installation]] guides or [[FAQ for pod maintainers]] or [[FAQ for developers]]..) it can be deleted without replacement.<br /> | |||
If this page is to keep, to me it looks like this page could perhaps be merged with [[Diasporas components explained]] (although they describe different parts of diaspora.. hm.). At the moment, both pages look somehow lost. --[[User:Waithamai|waithamai]] <sup>[[User talk:Waithamai|talk]]</sup> 07:08, 17 August 2017 (UTC)}} | |||
== Framework and Tools == | == Framework and Tools == | ||
| Line 8: | Line 11: | ||
* '''Haml'''<br /> | * '''Haml'''<br /> | ||
Our view templates are written in HAML (a templating language) instead of the default ERB (HTML with inline Ruby code).<br /> | Our view templates are written in HAML (a templating language) instead of the default ERB (HTML with inline Ruby code).<br /> | ||
The HAML docs can be found [http://haml | The HAML docs can be found [http://haml.info/docs.html here]. The corresponding files under <tt>app/views</tt>. | ||
* '''Sass'''<br /> | * '''Sass'''<br /> | ||
Our CSS is written in [http://sass-lang.com/ | Our CSS is written in [http://sass-lang.com/documentation/file.SASS_REFERENCE.html SASS] (specifically, the ‘scss’ dialect), which generates the actual CSS via the [http://guides.rubyonrails.org/asset_pipeline.html Rails asset pipeline]. The syntax is inspired by CSS, and quite similar, but it offers some additional features like nesting and variables. If you want to edit the stylesheets, have a look in <tt>app/assets/stylesheets/</tt>.<br /> | ||
'''''Note:''''' Both HAML and SASS are whitespace sensitive. | '''''Note:''''' Both HAML and SASS are whitespace sensitive. | ||
* '''Backbone.js & Handlebars.js'''<br /> | * '''Backbone.js & Handlebars.js'''<br /> | ||
The client-side functionality and rendering is mostly coordinated with [http:// | The client-side functionality and rendering is mostly coordinated with [http://backbonejs.org/ Backbone.js], which communicates [https://en.wikipedia.org/wiki/Representational_state_transfer REST]-fully with the server with JSON and triggers the rendering of the [http://handlebarsjs.com/ Handlebars.js] templates. The logic is found in <tt>app/assets/javascripts/app</tt> and the Handlebars templates are located in <tt>app/assets/templates</tt> | ||
== Testing == | == Testing == | ||
Our goal is to test ''everything''. If you find a bug, you first expose it by writing a tests that fails because of the bug. Only then you start fixing the actual code. This is called [https://en.wikipedia.org/wiki/Test-driven_development Test Driven | Our goal is to test ''everything''. If you find a bug, you first expose it by writing a tests that fails because of the bug. Only then you start fixing the actual code. This is called [https://en.wikipedia.org/wiki/Test-driven_development Test Driven Development] (TDD).<br /> | ||
We write our unit tests for ruby code in [http://blog.davidchelimsky.net/2007/05/14/an-introduction-to-rspec-part-i/ Rspec], the JavaScript test are in [http://jasmine.github.io/ Jasmine] and integration tests in [https://github.com/cucumber/cucumber-rails Cucumber]. Specs are in <tt>spec</tt>, and Cucumber features are in <tt>features</tt>. For more details see our page on [[Testing Workflow]]. | We write our unit tests for ruby code in [http://blog.davidchelimsky.net/2007/05/14/an-introduction-to-rspec-part-i/ Rspec], the JavaScript test are in [http://jasmine.github.io/ Jasmine] and integration tests in [https://github.com/cucumber/cucumber-rails Cucumber]. Specs are in <tt>spec</tt>, and Cucumber features are in <tt>features</tt>. For more details see our page on [[Testing Workflow]]. | ||
| Line 30: | Line 33: | ||
[[Profile]] – This contains information about the person. Currently, a profile looks the same to anyone looking at it. | [[Profile]] – This contains information about the person. Currently, a profile looks the same to anyone looking at it. | ||
[[Contact]] – Defines the relationship between a [[User]] and another | [[Contact]] – Defines the relationship between a [[User]] and another user's [[Person]]. | ||
[[Request]] – This is a friend request object that gets sent to another person. | [[Request]] – This is a friend request object that gets sent to another person. | ||
| Line 45: | Line 48: | ||
Retraction – this is an object that gets sent out when a post creator deletes a post. It is not a model, but it serializes for dispatch to other Diaspora servers the same way our models do. | Retraction – this is an object that gets sent out when a post creator deletes a post. It is not a model, but it serializes for dispatch to other Diaspora servers the same way our models do. | ||
==== Posting something (app/models/user) ==== | ==== Posting something (app/models/user) ==== | ||
# When a user posts anything, | # When a user posts anything, they posts it to an aspect or all aspects. | ||
# Assuming the post is valid, the post created and its id is stored in raw_visible_posts for that user | # Assuming the post is valid, the post is created and its id is stored in '''raw_visible_posts''' for that user | ||
# The html for that post is rendered on the server and is pushed to the user through the websocket | # The html for that post is rendered on the server and is pushed to the user through the websocket | ||
# The post is then serialized to xml, wrapped in an encrypted and signed | # The post is then serialized to xml, wrapped in an encrypted and signed Salmon envelope and POSTed to the receive urls (http://pod.location/receive/users/:id[person_id]) for the recipients' Person objects. | ||
==== Receiving a post (app/controllers/publics_controller.rb & lib/diaspora/user/receiving.rb) ==== | ==== Receiving a post (app/controllers/publics_controller.rb & lib/diaspora/user/receiving.rb) ==== | ||
| Line 64: | Line 66: | ||
[[Category:Developers]] | [[Category:Developers]] | ||
[[Category:Technical]] | [[Category:Technical]] | ||
Latest revision as of 07:08, 17 August 2017
 Out of date: | This page's accuracy may be compromised due to out-of-date information. Please help improve the page by updating it. There may be additional information on the talk page. |
 Note: | This page got updates some minor updates recently, but please check if everything is correct. If the content of this page is sufficiently described elsewhere (in the installation guides or FAQ for pod maintainers or FAQ for developers..) it can be deleted without replacement. If this page is to keep, to me it looks like this page could perhaps be merged with Diasporas components explained (although they describe different parts of diaspora.. hm.). At the moment, both pages look somehow lost. --waithamai talk 07:08, 17 August 2017 (UTC) |
Framework and Tools
Diaspora is written in Ruby on Rails, a web framework for the Ruby programming language.
If you’ve never looked at a Rails project, you may want to check out a Rails guide like this one.
There are a few tools we’re using that aren’t in every rails project:
- Haml
Our view templates are written in HAML (a templating language) instead of the default ERB (HTML with inline Ruby code).
The HAML docs can be found here. The corresponding files under app/views.
- Sass
Our CSS is written in SASS (specifically, the ‘scss’ dialect), which generates the actual CSS via the Rails asset pipeline. The syntax is inspired by CSS, and quite similar, but it offers some additional features like nesting and variables. If you want to edit the stylesheets, have a look in app/assets/stylesheets/.
Note: Both HAML and SASS are whitespace sensitive.
- Backbone.js & Handlebars.js
The client-side functionality and rendering is mostly coordinated with Backbone.js, which communicates REST-fully with the server with JSON and triggers the rendering of the Handlebars.js templates. The logic is found in app/assets/javascripts/app and the Handlebars templates are located in app/assets/templates
Testing
Our goal is to test everything. If you find a bug, you first expose it by writing a tests that fails because of the bug. Only then you start fixing the actual code. This is called Test Driven Development (TDD).
We write our unit tests for ruby code in Rspec, the JavaScript test are in Jasmine and integration tests in Cucumber. Specs are in spec, and Cucumber features are in features. For more details see our page on Testing Workflow.
The Models
Our Models can be found in the app/models folder:
User – Users, of course, come first. A User object represents the private information and capabilities of a user on that server. The user object is able to friend people, post updates, and update his profile. A User has a Person.
Person – A Person is a User viewed from the outside. When a user friends another user, they friend that user’s Person object. Person objects are replicated across servers, and they are where a User’s public key lives. A Person has many Posts. A Person has a Profile.
Profile – This contains information about the person. Currently, a profile looks the same to anyone looking at it.
Contact – Defines the relationship between a User and another user's Person.
Request – This is a friend request object that gets sent to another person.
Aspect – This contains a list of people, and posts which are for that aspect. Aspects are private to Users, and we might embed the Aspect documents in the User document.
Post – A Post belongs to a Person. This is a parent class for different types of posts, it contains comment ids and a few other attributes common to all Posts.
- Status Message inherits from Post
- Album inherits from Post
- Photo inherits from Post
Comment – a comment belongs to a Post
Retraction – this is an object that gets sent out when a post creator deletes a post. It is not a model, but it serializes for dispatch to other Diaspora servers the same way our models do.
Posting something (app/models/user)
- When a user posts anything, they posts it to an aspect or all aspects.
- Assuming the post is valid, the post is created and its id is stored in raw_visible_posts for that user
- The html for that post is rendered on the server and is pushed to the user through the websocket
- The post is then serialized to xml, wrapped in an encrypted and signed Salmon envelope and POSTed to the receive urls (http://pod.location/receive/users/:id[person_id]) for the recipients' Person objects.
Receiving a post (app/controllers/publics_controller.rb & lib/diaspora/user/receiving.rb)
- The user receives the salmon, decrypts the headers.
- If the signature on the salmon data is from the person who claims to have sent the post is marshaled into an object and saved into the database.
- That post id is stored in the visible posts for the receiving user as well as posts for the aspect the sender is in.
Here’s the autogenerated documentation http://rubydoc.info/github/diaspora/diaspora/master