The Arsse is a news aggregator server which implements multiple synchronization protocols, including version 1.2 of NextCloud News’ protocol and the Tiny Tiny RSS protocol (details below). Unlike most other aggregator servers, The Arsse does not include a Web front-end (though one is planned as a separate project), and it relies on existing protocols to maximize compatibility with existing clients.
At present the software should be considered in an “alpha” state: though its core subsystems are covered by unit tests and should be free of major bugs, not everything has been rigorously tested. Additionally, many features one would expect from other similar software have yet to be implemented. Areas of future work include:
The Arsse has the following requirements:
At present, installation of The Arsse is rather manual. We hope to improve this in the future, but for now the steps below should help get you started. The instructions and configuration samples assume you will be using Ubuntu 16.04 (or equivalent Debian) and Nginx; we hope to expand official support for different configurations in the future as well.
config.defaults.phpas a guide. The file you create only needs to contain non-default settings. The
userPreAuthsetting may be of particular interest
sudo systemctl enable arsse sudo systemctl start arsse
Sample configuration parameters for Nginx can be found in
arsse/dist/nginx-fcgi.conf; the samples assume a server group has already been defined for PHP. How to configure an Nginx service to use PHP and install the required PHP extensions is beyond the scope of this document, however.
The Arsse includes a
user add <username> [<password>] console command to add users to the database; for example running
php arsse.php user add admin password will add the user
admin with the password
pasword to the database. Other commands for managing users are also available.
Alternatively, if the Web server is configured to handle authentication, you may set the configuration option
true and The Arsse will defer to the Web server and automatically add any missing users as it encounters them.
If installing from the Git repository rather than a download package, you will need to follow extra steps before the instructions in the section above.
First, you must install Composer to fetch required PHP libraries. Once Composer is installed, dependencies may be downloaded with the following command:
php composer.phar install -o --no-dev --no-scripts
Second, you may wish to create an example configuration file using the following command:
php ./arsse.php conf save-defaults "./config.defaults.php"
The Arsse is made available under the permissive MIT license. See the
AUTHORS files included with the distribution or source code for exact legal text and copyright holders. Dependencies included in the distribution may be governed by other licenses.
Please refer to
CONTRIBUTING.md for guidelines on contributing code to The Arsse.
Functionally there is no reason to prefer either SQLite or PostgreSQL over the other. SQLite is significantly simpler to set up in most cases, requiring only read and write access to a containing directory in order to function; PostgreSQL may perform better than SQLite when serving hundreds of users or more, though this has not been tested.
MySQL, on the other hand, is not recommended due to its relatively constrained index prefix limits which may cause some newsfeeds which would otherwise work to be rejected. If using MySQL, special care should also be taken when performing schema upgrades, as errors during the process can leave the database in a half-upgraded state which The Arsse cannot itself recover from.
Note that MariaDB is not compatible with The Arsse: its support for common table expressions is, as of this writing, not sufficient for our needs.
The Arsse does not guarantee it will handle type casting of input in the same way as reference implementations for its supported protocols. As a general rule, clients should endeavour to send only correct input.
The Arsse does, however, guarantee output to be of the same type. If it is not, this is a bug and should be reported.
The Arsse makes use of the picoFeed newsfeed parsing library to sanitize article content. The exact sanitization parameters may differ from those of reference implementations for protocols The Arsse supports.
As a general rule, The Arsse should yield the same output as the reference implementation for all valid inputs (otherwise you’ve found a bug), but there are exception, either because the NextCloud News (hereafter “NCN”) protocol description is at times ambiguous or incomplete, or because implementation details necessitate it differ; this section along with the General section above detail these differences.
userIdparameter: feeds in The Arsse are deduplicated, and have no owner
/feeds/allroute lists only feeds which should be checked for updates, and it also returns all
userIdattributes as empty strings: feeds in The Arsse are deduplicated, and have no owner
lastLoginTimestampattribute of the user metadata is always the current time: The Arsse’s implementation of the protocol is fully stateless
400 Bad Requestresponse instead of falling back to GET parameters
422 Unprocessable Entityreponse instead of being accepted
newestItemIdargument result in a
422 Unprocessable Entityreponse instead of silently failing
422 Unprocessable Entityreponse rather than suppressing the feed
As a general rule, The Arsse should yield the same output as the reference implementation for all valid inputs (otherwise you’ve found a bug), but there are exception, either because the Tiny Tiny RSS (hereafter “TTRSS”) protocol description is incomplete, erroneous, or out of date, or because TTRSS itself is buggy, or because implementation details necessitate The Arsse differ; this section along with the General section above detail these differences.
We are not aware of any other extensions to the TTRSS protocol. If you know of any more, please let us know.
getPrefoperation is not implemented; it returns
shareToPublishedoperation is not implemented; it returns
updateArticleoperation is not implemented and will gracefully fail
has_sandboxparameters of the
getHeadlinesoperation are ignored
feed_idvalues for the
getCompactHeadlinesoperation are not supported and will yield an
NOT_LOGGED_INerror; The Arsse returns a non-standard
subscribeToFeedprocessing normally produces an error; The Arsse instead chooses the first feed it finds
setArticleLabeloperation with an invalid label normally silently fails; The Arsse returns an
searchparameter of the
getHeadlinesoperation differs in the following ways:
pubspecial keywords treat the entire token as a search term rather than as
getHeadlinesoperation normally uses custom sorting for “special” feeds; The Arsse’s default sort order is equivalent to
feed_datesfor all feeds
getCountersoperation normally omits members with zero unread; The Arsse includes everything to appease some clients
setArticleLabeloperation; The Arsse returns a correct count in all cases
-3when providing the
getHeadlinesoperation with category ID
-3; The Arsse retuns the correct results
getFeedsoperation as it produces unpredictable results; The Arsse produces predictable results by first retrieving all unread feeds and then applying
view_modeparameter of the
getHeadlinesoperation is out of date; The Arsse matches the actual implementation and supports the undocumented
has_notevalues exposed by the Web user interface
search_modeparameter for the
getHeadlinesoperation, but this seems to be ignored; The Arsse does not implement it
output_modeparameter for the
getCountersoperation, but this seems to be ignored; The Arsse does not implement it
getCompactHeadlinesoperation states the default value for
limitis 20, but the reference implementation defaults to unlimited; The Arsse also defaults to unlimited
Tiny Tiny RSS itself is unaware of HTTP authentication: if HTTP authentication is used in the server configuration, it has no effect on authentication in the API. The Arsse, however, makes use of HTTP authentication for NextCloud News, and can do so for TTRSS as well. In a default configuration The Arsse functions in the same way as TTRSS: HTTP authentication and API authentication are completely separate and independent. Alternative behaviour is summarized below:
In all cases, supplying invalid HTTP credentials will result in a 401 response.