b8f8a617fe
The user manager no longer differentiates between the internal driver and other drivers, making the duplication unnecessary |
||
---|---|---|
dist | ||
lib | ||
locale | ||
sql/SQLite3 | ||
tests | ||
vendor-bin | ||
www/tt-rss/images | ||
.gitattributes | ||
.gitignore | ||
.php_cs.dist | ||
arsse.php | ||
AUTHORS | ||
CHANGELOG | ||
composer.json | ||
composer.lock | ||
CONTRIBUTING.md | ||
LICENSE | ||
phpdoc.dist.xml | ||
README.md | ||
robo | ||
robo.bat | ||
RoboFile.php | ||
UPGRADING |
The Advanced RSS Environment
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:
- Support for more database engines (PostgreSQL, MySQL, MariaDB)
- Providing more sync protocols (Google Reader, Fever, others)
- Complete tools for managing users
- Better packaging and configuration samples
Requirements
The Arsse has the following requirements:
- A Linux server utilizing systemd and Nginx (tested on Ubuntu 16.04)
- PHP 7.0.7 or later with the following extensions:
- Privileges to create and run daemon processes on the server
Installation
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.
Initial setup
- Extract the tar archive to
/usr/share
- If desired, create
/usr/share/arsse/config.php
usingconfig.defaults.php
as a guide. The file you create only needs to contain non-default settings. TheuserPreAuth
setting may be of particular interest - Copy
/usr/share/arsse/dist/arsse.service
to/lib/systemd/system
- In a terminal, execute the following to start the feed fetching service:
sudo systemctl enable arsse
sudo systemctl start arsse
Configuring the Web server and PHP
Sample configuration parameters for Nginx can be found in arsse/dist/nginx.conf
and 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.
Adding users
The Arsse currently includes a user add <username> [<password>]
console command to add users to the database; other user management tasks require manual database edits. Alternatively, if the Web server is configured to handle authentication, you may set the configuration option userPreAuth
to true
and The Arsse will defer to the server and automatically add any missing users as it encounters them.
Installation from source
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"
License
The Arsse is made available under the permissive MIT license. See the LICENSE
and 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.
Contributing
Please refer to CONTRIBUTING.md
for guidelines on contributing code to The Arsse.
Protocol compatibility notes
General
Type casting
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.
Content sanitization
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.
NextCloud News v1.2
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.
Differences
- Article GUID hashes are not hashes like in NCN; they are integers rendered as strings
- Article fingerprints are a combination of hashes rather than a single hash
- When marking articles as starred the feed ID is ignored, as they are not needed to establish uniqueness
- The feed updater ignores the
userId
parameter: feeds in The Arsse are deduplicated, and have no owner - The
/feeds/all
route lists only feeds which should be checked for updates, and it also returns alluserId
attributes as empty strings: feeds in The Arsse are deduplicated, and have no owner - The API's "updater" routes do not require administrator priviledges as The Arsse has no concept of user classes
- The "updater" console commands mentioned in the protocol specification are not implemented, as The Arsse does not implement the required NextCloud subsystems
- The
lastLoginTimestamp
attribute of the user metadata is always the current time: The Arsse's implementation of the protocol is fully stateless
Ambiguities
- NCN specifies that GET parameters are treated "the same" as request body parameters; it does not specify what to do in cases where they conflict. The Arsse chooses to give GET parameters precedence
- NCN does not define validity of folder and names other than to specify that the empty string is invalid. The Arsse further considers any string composed only of whitesapce to be invalid
- NCN does not specify a return code for bulk-marking operations without a
newestItemId
provided; The Arsse returns422
- NCN does not specify what should be done when creating a feed in a folder which does not exist; the Arsse adds the feed to the root folder
- NCN does not specify what should be done when moving a feed to a folder which does not exist; The Arsse return
422
- NCN does not specify what should be done when renaming a feed to an invalid title, nor what constitutes an invalid title; The Arsse uses the same rules as it does for folders, and returns
422
in cases of rejection
Tiny Tiny RSS
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.
Extended functionality
The Arsse supports both the set of extensions to the TTRSS protocol defined by FeedReader, as well as the getCompactHeadlines
operation defined by News+.
We are not aware of any other extensions to the TTRSS protocol. If you know of any more, please let us know.
Missing features
- The
getPref
operation is not implemented; it returnsUNKNOWN_METHOD
- The
shareToPublished
operation is not implemented; it returnsUNKNOWN_METHOD
- Setting an article's "published" flag with the
updateArticle
operation is not implemented and will gracefully fail - The
search
parameter of thegetHeadlines
operation is not implemented; the operation will proceed as if no search string were specified - The
sanitize
,force_update
, andhas_sandbox
parameters of thegetHeadlines
operation are ignored - String
feed_id
values for thegetCompactHeadlines
operation are not supported and will yield anINCORRECT_USAGE
error - Articles are limited to a single attachment rather than multiple attachments
Differences
- Input that cannot be parsed as JSON normally returns a
NOT_LOGGED_IN
error; The Arsse returns a non-standardMALFORMED_INPUT
error instead - Feed, category, and label names are normally unrestricted; The Arsse rejects empty strings, as well as strings composed solely of whitespace
- Discovering multiple feeds during
subscribeToFeed
processing normally produces an error; The Arsse instead chooses the first feed it finds - Providing the
setArticleLabel
operation with an invalid label normally silently fails; The Arsse returns anINVALID_USAGE
error instead - Article hashes are normally SHA1; The Arsse uses SHA256 hashes
- Article attachments normally have unique IDs; The Arsse always gives attachments an ID of
"0"
- The default sort order of the
getHeadlines
operation normally uses custom sorting for "special" feeds; The Arsse's default sort order is equivalent tofeed_dates
for all feeds - The
getCounters
operation normally omits members with zero unread; The Arsse includes everything to appease some clients
Other notes
- TTRSS accepts base64-encoded passwords, though this is undocumented; The Arsse accepts base64-encoded passwords as well
- TTRSS sometimes returns an incorrect count from the
setArticleLabel
operation; The Arsse returns a correct count in all cases - TTRSS sometimes returns out-of-date cached information; The Arsse does not use caches as TTRSS does, so information is always current
- TTRSS returns results for feed ID
-3
when providing thegetHeadlines
operation with category ID-3
; The Arsse retuns the correct results - The protocol doucmentation advises not to use
limit
orskip
together withunread_only
for thegetFeeds
operation as it produces unpredictable results; The Arsse produces predictable results by first retrieving all unread feeds and then applyingskip
andlimit
- The protocol documentation on values for the
view_mode
parameter of thegetHeadlines
operation is out of date; The Arsse matches the actual implementation and supports the undocumentedpublished
andhas_note
values exposed by the Web user interface - The protocol documentation makes mention of a
search_mode
parameter for thegetHeadlines
operation, but this seems to be ignored; The Arsse does not implement it - The protocol documentation makes mention of an
output_mode
parameter for thegetCounters
operation, but this seems to be ignored; The Arsse does not implement it - The documentation for the
getCompactHeadlines
operation states the default value forlimit
is 20, but the reference implementation defaults to unlimited; The Arsse also defaults to unlimited - It is assumed TTRSS exposes undocumented behaviour; unless otherwise noted The Arsse only implements documented behaviour
Interaction with HTTP authentication
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. Behaviour is summarized below:
- With default settings:
- Clients may optionally provide HTTP credentials; API authentication then proceeds as normal
- All feed icons are visible to unauthenticated clients
- If the
userHTTPAuthRequired
setting istrue
:- Clients must pass HTTP authentication; API authentication then proceeds as normal
- Feed icons are visible only to their owners
- If the
userSessionEnforced
setting isfalse
:- Clients may optionally provide HTTP credentials; if they are valid API authentication is skipped: tokens are issued upon login, but ignored for HTTP-authenticated requests
- All feed icons are visible to unauthenticated clients
- If the
userHTTPAuthRequired
setting istrue
and theuserSessionEnforced
setting isfalse
:- Clients must pass HTTP authentication; API authentication is skipped: tokens are issued upon login, but thereafter ignored
- Feed icons are visible only to their owners
- If the
userPreAuth
setting istrue
:- The Web server asserts authentication was successful; API authentication only checks that HTTP and API user names match
- Feed icons are visible only to their owners
- If the
userPreAuth
setting istrue
and theuserSessionEnforced
setting isfalse
:- The Web server asserts authentication was successful; API authentication is skipped: tokens are issued upon login, but thereafter ignored
- Feed icons are visible only to their owners
In all cases, supplying invalid HTTP credentials will result in a 401 response.