Merge branch 'master' of https://github.com/ReCodEx/wiki.wiki

Rewritten-docs.md

@@ -457,18 +457,10 @@ designing user interfaces on top of them.
 The application interacts with users. From the project assignment is clear, that
 the system has to keep personalized data about users and adapt presented content
 according to this knowledge. User data cannot be publicly visible, so that
-implies necessity of user authentication. There are several way of
+implies necessity of user authentication. The application also has to support
-authentication user in web applications. HTTP basic authentication has a few
+multiple ways of authentication (university authentication systems, a company
-drawbacks like sending plain credentials in every request or no logout option,
+LDAP server, an OAuth server...) and permit adding more security measures in the
-so it is not recommended to use. Using cookies is possible, but it is
+future, such as two-factor authentication.
-susceptible to various types of attacks including stealing and also brings state
-into stateless protocols as REST. Another option is using tokens, OAuth2 or JWT
-(JSON Web Token). Nowadays it is widely used and has only a few cons (need to
-make extra effort to mitigate XSS attacks). Additional option is usage of
-one-time passwords. These can be time or counter based and are mostly used for
-two-factor authentication. Since ReCodEx does not need to have military grade
-security, JWT tokens are used for authentication. However, two-factor
-authentication may come in next releases.
 
 User data also includes a privilege level. From the assignment it is required to
 have at least two roles, _student_ and _supervisor_. However, it is wise to add
@@ -1404,6 +1396,9 @@ We considered several technologies which could be used:
   servers. It is a suitable technology for this kind of a project. It has all
   the features we need when some additional extensions are installed (to support
   LDAP or ZeroMQ).
+- Ruby on Rails, Python (Django), etc. -- popular web technologies that appeared
+  in the last decade. Both support ZeroMQ and LDAP via extensions and have large
+  developer communities.
 - ASP.NET (C#), JSP (Java) -- these technologies are very robust and are used to
   create server technologies in many big enterprises. Both can run on Windows
   and Linux servers (ASP.NET using the .NET Core).
@@ -1420,21 +1415,45 @@ technologies superior to PHP in all other aspects - PHP 7 is a mature language
 with a huge community and a wide range of tools, libraries, and frameworks.
 
 We decided to use an ORM framework to manage the database, namely the widely
-used PHP ORM Doctrine 2.  This framework has a robust abstraction layer DBAL so
+used PHP ORM Doctrine 2. Using an ORM tool means we do not have to write SQL
-the database engine is not very important and it can be changed without any need
+queries by hand. Instead, we work with persistent objects, which provides a
-for changing the code. We chose an open-source database MariaDB.
+higher level of abstraction. Doctrine also has a robust database abstraction
+layer so the database engine is not very important and it can be changed without
+any need for changing the code. MariaDB was chosen as the storage backend.
 
 To speed up the development process of the PHP server application we decided to
-use an MVC framework.  After evaluating and trying several frameworks, such as
+use a web framework. After evaluating and trying several frameworks, such as
-Lumen, Laravel, and Symfony, we ended up using the framework Nette. This
+Lumen, Laravel, and Symfony, we ended up using Nette. This framework is very
-framework is very common in the Czech Republic -- its main developer is a
+common in Czech Republic -- its lead developer is a well-known Czech programmer
-well-known Czech programmer David Grudl -- and we were already familiar with the
+David Grudl -- and we were already familiar with the patterns used in this
-patterns used in this framework (e.g., dependency injection, authentication,
+framework, such as dependency injection, authentication, routing. These concepts
-routing). There is a good extension for the Nette framework which makes usage of
+are useful even when developing a REST application, which might be a surprise
-Doctrine 2 very straightforward.
+considering that Nette focuses on "traditional" web applications. There is also
-
+a Nette extension which makes integartion of Doctrine 2 very straightforward.
-@todo: authentication, some possibilities and describe used jwt (mentioned in
+
-basic concepts, maybe elaborate more or just remove this item from todo list)
+#### Request handling
+
+@todo Nette Router, how we exploit presenters to act as api endpoints
+
+#### Authentication
+
+Because Nette is focused on building web applications that render a new
+page for (almost) every request, it uses PHP sessions (based on cookies) for
+authentication. This method is unsuitable for REST APIs where clients do not
+typically store cookies. However, it is common that RESTful services provide
+access tokens that are then sent with every request by the client.
+
+JWT (JSON web tokens), an open standard for access tokens, was chosen for our
+authentication implementation. Support libraries exist for all major languages
+used in web developments that facilitate straightforward usage. The tokens use
+asymmetric cryptography for signing, which provides a satisfactory level of
+security.
+
+To implement JWT in Nette, we have to implement some of its security-related
+interfaces such as IAuthenticator and IUserStorage, which is rather easy
+thanks to the simple authentication flow. Replacing these services in a Nette
+application is also straightforward, thanks to its dependency injection
+container implementation.
 
 @todo: solution of forgotten password, why this in particular
 
@@ -1448,6 +1467,8 @@ basic concepts, maybe elaborate more or just remove this item from todo list)
 within instance and how it is implemented and how it could be implemented
 (describe only implementation if it is something what to say)
 
+@todo permission handling, roles, etc.
+
 @todo: where is stored which workers can be used by supervisors and which runtimes are available, describe possibilities and why is not implemented automatic solution
 
 @todo: on demand loading of students submission, in-time loading of every other submission, why