diff --git a/Rewritten-docs.md b/Rewritten-docs.md index 529fea0..8f010f3 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -288,8 +288,8 @@ addons (mostly administrative features). supervisor - _solution resubmission_ -- teachers should be able edit student's solutions and privately resubmit them, optionally saving all results (including - temporary ones); this feature can be used to quickly fix errors in the - solution + temporary ones); this feature can be used to quickly fix obvious errors in the + solution and see if it is otherwise viable - _localization_ -- all texts (UI and exercises) should be translatable - _formatted exercise texts_ -- Markdown or another lightweight markup language should be supported for formatting exercise texts @@ -958,10 +958,6 @@ rules out ZeroMQ -- while it is very useful for asynchronous communication between backend components, it is practically impossible to use it from a web browser. There are several other options: -- *TCP sockets* -- TCP sockets give a reliable means of a full-duplex - communication. All major operating systems support this protocol and there are - libraries which simplify the implementation. On the other side, it is not - possible to initiate a TCP socket from a web browser. - *WebSockets* -- The WebSocket standard is built on top of TCP. It enables a web browser to connect to a server over a TCP socket. WebSockets are implemented in recent versions of all modern web browsers and there are @@ -1401,26 +1397,33 @@ development. Users want to view real time evaluation progress of their solution. It can be easily done with established double-sided connection stream, but it is hard to -achieve with web technologies. HTTP protocol works differently on separate -requests basis with no long term connection. However, there is widely used -technology to solve this problem, WebSocket protocol. - -Working with WebSocket protocol from the backend is possible, but not ideal from -design point of view. Backend should be hidden from public internet to minimize -surface for possible attacks. With this in mind, there are two possible options: - -- send progress messages through API -- make separate component for progress messages - -Each of the two possibilities has some pros and cons. The first one is good -because there is no additional component and API is already publicly visible. On -the other side, working with WebSocket protocol from PHP is not much pleasant -(but it is possible) and embedding this functionality into API is not -extendable. The second approach is better for future changing the protocol or -implementing extensions like caching of messages. Also, the progress feature is -considered only optional, because there may be clients for which this feature is -useless. Major drawback of separate component is another part, which needs to -be publicly exposed. +achieve with plain HTTP. HTTP itself works on a separate request basis with no +long term connection. The HTML5 specification contains Server-Sent Events - a +means of sending text messages unidirectionally from an HTTP server to a +subscribed website. Sadly, it is not supported in Internet Explorer and Edge. + +However, there is another widely used technology that can solve this problem -- +the WebSocket protocol. It is more general than necessary (it enables +bidirectional communication) and requires additional web server configuration, +but it is supported in recent versions of all major web browsers. + +Working with the WebSocket protocol from the backend is possible, but not ideal +from the design point of view. Backend should be hidden from public internet to +minimize surface for possible attacks. With this in mind, there are two possible +options: + +- send progress messages through the API +- make a separate component that forwards progress messages to clients + +Both of the two possibilities have their benefits and drawbacks. The first one +requires no additional component and the API is already publicly visible. On the +other side, working with WebSockets from PHP is complicated (but it is possible +with the help of third-party libraries) and embedding this functionality into +API is not extendable. The second approach is better for future changing the +protocol or implementing extensions like caching of messages. Also, the progress +feature is considered only optional, because there may be clients for which this +feature is useless. Major drawback of separate component is another part, which +needs to be publicly exposed. We decided to make a separate component, mainly because it is smaller component with only one role, better maintainability and optional demands for progress