README
¶
Penguin Statistics - Widget backend
This is the backend project repository for the Penguin Statistics widget.
Important Concepts Outlined
Why using a different backend rather to just use the backend?
First of all, Go might bring us better performance. I used word might because there's no benchmark comparison available to give a solid proof, but given by common knowledge Go tends to have better performance. That being said, performance in this particular service is critical since we'd need to probably calculate every request we've got and that request is probably not cacheable or, is not worth to cache given by the short amount of period that the result matrix may update.
Also, adding such feature to the main backend project tends to add too much complexity to the project, which may decrease the performance of the project, and more severely after some discussion with the main contributor of such project we concluded that adding such feature to the backend project would have a high possibility to impact the readability of the code heavily. Therefore, we have decided to maintain a dedicated project that decouples the logics within that project, where the backend project would just to focus on the actual calculation of matrix and to handle other data-sensitive jobs, and this widget-backend project would to just focus on manipulating on the already calculated matrices from the backend project.
Finally, and probably the most critical reason, is that considering healthy status of caches, maintainability and the permanence nature of widget URL, the widget shall be deployed on a dedicated subdomain, and given by such need a dedicated project would be the most feasible since conditioning the Host header inside the same project doesn't always look neat. :D
Why using /matrix/:server as the prefix of all matrix requests, rather to just use a query string?
First of all, sets of records for different servers are by nature completely different sets of resources, and therefore by the semantics of REST API such resources shall have different path in order to represent the difference rather to use a query string which is often used to filter records by condition from a defined set of records.
Moreover, using a completely different path for different resources help with the HTTP-level cache servers to properly cache the request based on the request path rather than the need of parsing query string. Also, to mention that, from experiences we had with Aliyun CDN which we used for our CN mirror site, their cache-matching mechanism tends to either not match query string at all, or to match every single query strings. This leads to a vulnerability where the one could initiate a cache penetration attack towards our endpoint, which they could just use a random query string that changes everytime in order to invalidate the cache that's already stored on the CDN. Given by such experience we've got, we've decided that on the widget backend we would distinguish the server request using path rather to use a query string. This also improves the clarity and readability of the request URL itself.
And finally, given by the possibility (and a very high one) that any time in the future Penguin Statistics project may lose funds which by then, server cost would be infeasible which lead to the possibility of having a proper archive of the project. By using the path way to represent all differences across resources, we could ultimately utilize the GitHub Pages where it allows us to render all matrices at once and store them as html pages as format /matrix/:server/:data/:id.html (which is also accessible at /matrix/:server/:data/:id). Thereafter, the users of our widget wouldn't need to change anything, including the URL, and would still be able to see the archived widgets.
Given by such reasons we've concluded to use such format by a tradeoff to lose consistencies from our Public API.
Maintainers
This project has mainly being maintained by the following contributors (in alphabetical order):
The full list of active contributors of the Penguin Statistics project can be found at the Team Members page of the website.
How to contribute?
Our contribute guideline can be found at Penguin Developers. PRs are always more than welcome!
Documentation
¶
Overview ¶
widget-backend renders minimum matrix data and their corresponding data dependencies with the widget frontend all at once in order to minimize data consumption and to reduce load time for users of the widget. Usage:
go run .
Notice that default values have been set for all data controllers and their caches, and the one SHOULD be checking them before deploying such service. Please also notice that, such service which probably has already been deployed, is NOT suitable for public usage except for the render of widgets. Developers SHOULD use the Penguin Statistics public API which is documented at https://developer.penguin-stats.io/docs/ instead of hosting this service themselves in order to reduce server load.
Source Files
Directories