mirror of
https://code.mensbeam.com/MensBeam/Arsse.git
synced 2024-12-22 13:12:41 +00:00
Documentation for 0.2.0; fixes #108
This commit is contained in:
J. King
parent
5cd7268c0a
commit
1e0c06034b
3 changed files with 117 additions and 14 deletions
12
CHANGELOG
12
CHANGELOG
|
|
@ -1,3 +1,15 @@
|
|||
Version 0.2.0 (2017-11-30)
|
||||
==========================
|
||||
|
||||
New features:
|
||||
- Support for the Tiny Tiny RSS protocol (see README.md for details)
|
||||
- Support for HTTP OPTIONS requests in all protocols
|
||||
|
||||
Bug fixes:
|
||||
- Perform feed discovery *correctly*
|
||||
- Expose the incorrectDbCharset boolean in the NextCloud News server status
|
||||
- Give NextCloud News articles' guidHash attribute the correct type (string)
|
||||
|
||||
Version 0.1.1 (2017-09-30)
|
||||
==========================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
[a]: https://code.mensbeam.com/MensBeam/Policy/src/master/CODE-OF-CONDUCT.md
|
||||
[b]: https://code.mensbeam.com/MensBeam/arsse/issues
|
||||
[c]: http://www.php-fig.org/psr/psr-2/
|
||||
[d]: https://getcomposer.org/
|
||||
[e]: https://phpunit.de/manual/current/en/textui.html#textui.clioptions
|
||||
|
||||
# Contributing to The Arsse
|
||||
|
||||
|
|
@ -40,3 +42,20 @@ Before you submit your pull request search for an existing open or closed pull r
|
|||
We would like to ensure consistency in our source code, so we follow the [PSR-2 guidelines][c] with one notable exception (utilizing the notation used and outlined in the original document):
|
||||
|
||||
**Opening braces for classes and methods MUST go on the same line, and closing braces MUST go on the next line after the body.**
|
||||
|
||||
## Running tests
|
||||
|
||||
To run the test suite, you must have [Composer][d] installed as well as the command-line PHP interpreter (this is normally required to use Composer). Port 8000 must also be available for use by the built-in PHP Web server.
|
||||
|
||||
``` sh
|
||||
# first install dependencies
|
||||
php composer.phar install
|
||||
# run the tests
|
||||
./tests/test
|
||||
```
|
||||
|
||||
The example uses Unix syntax, but the test suite also runs in Windows. By default all tests are run; you can pass the same arguments to the test runner [as you would to PHPUnit][e]
|
||||
|
||||
``` sh
|
||||
./tests/test --testsuite "Configuration"
|
||||
```
|
||||
|
|
|
|||
100
README.md
100
README.md
|
|
@ -1,11 +1,11 @@
|
|||
# The Advanced RSS Environment
|
||||
|
||||
The Arsse is a news aggregator server which implements [version 1.2](https://github.com/nextcloud/news/blob/master/docs/externalapi/Legacy.md) of [NextCloud News](https://github.com/nextcloud/news)' client-server synchronization protocol. 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.
|
||||
The Arsse is a news aggregator server which implements multiple synchronization protocols, including [version 1.2][NCNv1] of [NextCloud News](https://github.com/nextcloud/news)' protocol and the [Tiny Tiny RSS][TTRSS] protocol ([details](#proto)). 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, though the NextCloud News protocol is fully supported, 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 (Tiny Tiny RSS, Fever, others)
|
||||
- Providing more sync protocols (Google Reader, Fever, others)
|
||||
- Complete tools for managing users
|
||||
- Better packaging and configuration samples
|
||||
|
||||
|
|
@ -68,19 +68,91 @@ The Arsse is made available under the permissive MIT license. See the `LICENSE`
|
|||
|
||||
Please refer to `CONTRIBUTING.md` for guidelines on contributing code to The Arsse.
|
||||
|
||||
### Running tests
|
||||
## <a name="proto"></a> Protocol compatibility notes
|
||||
|
||||
To run the test suite, you must have [Composer](https://getcomposer.org/) installed as well as the command-line PHP interpreter (this is normally required to use Composer). Port 8000 must also be available for use by the built-in PHP Web server.
|
||||
### <a name="proto-general"></a> General
|
||||
|
||||
``` sh
|
||||
# first install dependencies
|
||||
php composer.phar install
|
||||
# run the tests
|
||||
./tests/test
|
||||
```
|
||||
#### Type casting
|
||||
|
||||
The example uses Unix syntax, but the test suite also runs in Windows. By default all tests are run; you can pass the same arguments to the test runner [as you would to PHPUnit](https://phpunit.de/manual/current/en/textui.html#textui.clioptions):
|
||||
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.
|
||||
|
||||
``` sh
|
||||
./tests/test --testsuite "Configuration"
|
||||
```
|
||||
The Arsse _does_, however, guarantee output to be of the same type. If it is not, this is [a bug][newIssue] and should be reported.
|
||||
|
||||
#### Content sanitization
|
||||
|
||||
The Arsse makes use of the [picoFeed](https://github.com/miniflux/picoFeed/) newsfeed parsing library to sanitize article content. The exact sanitization rules may differ from those of reference implementations for protocols The Arsse supports.
|
||||
|
||||
### <a name="proto-ncnv1"></a> 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][newIssue]), but there are exception, either because the NextCloud News (hereafter "NCN") [protocol description][NCNv1] is at times ambiguous or incomplete, or because implementation details necessitate it differ; this section along with the [General section](#proto-general) above detail these differences.
|
||||
|
||||
#### Missing features
|
||||
|
||||
- The Arsse does not implement [Cross-Origin Resource Sharing][CORS]
|
||||
|
||||
#### 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 all `userId` attributes as empty strings: feeds in The Arsse are deduplicated, and have no owner
|
||||
- The updater console commands mentioned in the protocol specification are not implemented
|
||||
- The `lastLoginTimestamp` attribute of the user metadata is always the current time: The Arsse's implementation of the protocol is fully stateless
|
||||
|
||||
#### Ambiguities
|
||||
|
||||
- [The protocol][NCNv1] does not specify an output character encoding, but the reference server uses UTF-8; The Arsse also uses UTF-8
|
||||
- The protocol 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
|
||||
- The protocol does not define validity of folder and names other than to say that the empty string is invalid. The Arsse further considers any string composed only of whitesapce to be invalid
|
||||
- The protocol does not specify a return code for bulk-marking operations without a `newestItemId` provided; The Arsse returns `422`
|
||||
- The protocol 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
|
||||
- The protocol does not specify what should be done when moving a feed to a folder which does not exist; The Arsse return `422`
|
||||
- The protocol 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
|
||||
|
||||
### <a name="proto-ttrss"></a> 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][newIssue]), but there are exception, either because the Tiny Tiny RSS (hereafter "TTRSS") [protocol description][TTRSS] 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](#proto-general) above detail these differences.
|
||||
|
||||
#### Extended functionality
|
||||
|
||||
The Arsse supports both [the set of extensions](https://github.com/jangernert/FeedReader/tree/master/data/tt-rss-feedreader-plugin) to the TTRSS protocol defined by [FeedReader](https://jangernert.github.io/FeedReader/), as well as [the `getCompactHeadlines` operation](https://github.com/hrk/tt-rss-newsplus-plugin) defined by [News+](https://github.com/noinnion/newsplus/).
|
||||
|
||||
We are not aware of any other extensions to the TTRSS protocol. If you know of any more, please [let us know][newIssue].
|
||||
|
||||
#### Missing features
|
||||
|
||||
- The `getPref` operation is not implemented; it returns `UNKNOWN_METHOD`
|
||||
- The `shareToPublished` operation is not implemented; it returns `UNKNOWN_METHOD`
|
||||
- Setting an article's "published" flag with the `updateArticle` operation is not implemented and will gracefully fail
|
||||
- The `search` parameter of the `getHeadlines` operation is not implemented; the operation will proceed as if no search string were specified
|
||||
- The `sanitize`, `force_update`, and `has_sandbox` parameters of the `getHeadlines` operation are ignored
|
||||
- String `feed_id` values for the `getCompactHeadlines` operation are not supported and will yield an `INCORRECT_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-standard `MALFORMED_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
|
||||
- Log-in session lifetime is intentionally shorter in The Arsse
|
||||
- Providing the `setArticleLabel` operation with an invalid label normally silently fails; The Arsse returns an `INVALID_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 to `feed_dates` for all feeds
|
||||
|
||||
#### Errors and ambiguities
|
||||
|
||||
- TTRSS returns an incorrect count when for the `setArticleLabel`; The Arsse returns a correct count
|
||||
- TTRSS returns incorrect results when providing the `getHeadlines` operation with category ID `-3`; The Arsse retuns the correct results
|
||||
- The protocol doucmentation advises not to use `limit` or `skip` together with `unread_only` for the `getFeeds` operation as it produces unpredictable results; The Arsse's results are, by contrast, predictable
|
||||
- The protocol documentation on values for the `view_mode` parameter of the `getHeadlines` operation is out of date; The Arsse matches the actual implementation
|
||||
- The protocol documentation makes mention of a `search_mode` parameter for the `getHeadlines` operation, but this seems to be ignored; The Arsse does not implement it
|
||||
- The protocol documentation makes mention of an `output_mode` parameter for the `getCounters` operation, but this seems to be ignored; The Arsse does not implement it
|
||||
- The documentation for the `getCompactHeadlines` operation states the default value for `limit` is 20, but the default is actually unlimited; The Arsse also defaults to unlimited
|
||||
|
||||
|
||||
[newIssue]: https://code.mensbeam.com/MensBeam/arsse/issues/new
|
||||
[NCNv1]: https://github.com/nextcloud/news/blob/master/docs/externalapi/Legacy.md
|
||||
[CORS]: https://fetch.spec.whatwg.org/#http-cors-protocol
|
||||
[TTRSS]: https://git.tt-rss.org/git/tt-rss/wiki/ApiReference
|
||||
Loading…
Reference in a new issue