Document supported protocols

Also standardize some stylistic conventions

docs/en/030_Supported_Protocols/010_NextCloud_News.md

@@ -0,0 +1,39 @@
+[TOC]
+
+# About
+
+The NextCloud News protocol was the first supported by The Arsse, and has been supported in full since version 0.3.0.
+
+It allows organizing newsfeeds into single-level folders, and supports a wide range of operations on newsfeeds, folders, and articles.
+
+<dl>
+    <dt>Supported since</dt>
+        <dd>0.1.0</dd>
+    <dt>Base URL</dt>
+        <dd>/</dd>
+    <dt>API endpoint</dt>
+        <dd>/index.php/apps/news/api/v1-2/</dd>
+    <dt>Specifications</dt>
+        <dd><a href="https://github.com/nextcloud/news/blob/master/docs/externalapi/Legacy.md">Version 1.2</a></dd>
+</dl>
+
+# 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 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
+- Syntactically invalid JSON input will yield a `400 Bad Request` response instead of falling back to GET parameters
+- Folder names consisting only of whitespace are rejected along with the empty string
+- Feed titles consisting only of whitespace or the empty string are rejected with a `422 Unprocessable Entity` reponse instead of being accepted
+- Bulk-marking operations without a `newestItemId` argument result in a `422 Unprocessable Entity` reponse instead of silently failing
+- Creating a feed in a folder which does not exist places the feed in the root folder rather than suppressing the feed
+- Moving a feed to a folder which does not exist results in a `422 Unprocessable Entity` reponse rather than suppressing the feed
+
+# Interaction with nested folders
+
+Tiny Tiny RSS is unique in allowing newsfeeds to be grouped into folders nested to arbitrary depth. When nesfeeds are placed into nested folders, they simply appear in the top-level folder when accessed via the NextCloud News protocol.

docs/en/030_Supported_Protocols/020_Tiny_Tiny_RSS.md

@@ -0,0 +1,85 @@
+[TOC]
+
+# About
+
+The Arsse supports not only the Tiny Tiny RSS protocol, but also extensions required by the FeedReader client and the more commonly supported `getCompactHeadlines` extension.
+
+It allows organizing newsfeeds into nested folders, and supports odd patchwork subset of Tiny Tiny RSS' full capabilities. The FeedReader extensions round out the protocol with significantly more features. Unlike TT-RSS itself, API access is always enabled with The Arsse.
+
+<dl>
+    <dt>Supported since</dt>
+        <dd>0.2.0</dd>
+    <dt>Base URL</dt>
+        <dd>/tt-rss/</dd>
+    <dt>API endpoint</dt>
+        <dd>/tt-rss/api</dd>
+    <dt>Specifications</dt>
+        <dd><a href="https://git.tt-rss.org/git/tt-rss/wiki/ApiReference">Main</a>, <a href="https://github.com/jangernert/FeedReader/blob/master/data/tt-rss-feedreader-plugin/README.md">FeedReader extensions</a>, <a href="https://github.com/hrk/tt-rss-newsplus-plugin/blob/master/README.md">News+ extension</a></dd>
+</dl>
+
+# Missing features
+
+The Arsse does not currently support the entire protocol. Notably missing features include manipulation of the special "Published" newsfeed, as well as searching. The full list of missing features is as follows:
+
+- 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
+- The `getPref` operation is not implemented; it returns `UNKNOWN_METHOD`
+
+# 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
+- 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
+- The `getCounters` operation normally omits members with zero unread; The Arsse includes everything to appease some clients
+
+# Other notes
+
+- TT-RSS accepts base64-encoded passwords, though this is undocumented; The Arsse accepts base64-encoded passwords as well
+- TT-RSS sometimes returns an incorrect count from the `setArticleLabel` operation; The Arsse returns a correct count in all cases
+- TT-RSS sometimes returns out-of-date cached information; The Arsse does not use caches as TT-RSS does, so information is always current
+- TT-RSS returns results for _feed_ ID `-3` 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 produces predictable results by first retrieving all unread feeds and then applying `skip` and `limit`
+- The protocol documentation on values for the `view_mode` parameter of the `getHeadlines` operation is out of date; The Arsse matches the actual implementation and supports the undocumented `published` and `has_note` values exposed by the Web user interface
+- 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 reference implementation defaults to unlimited; The Arsse also defaults to unlimited
+- It is assumed TT-RSS exposes other 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 TT-RSS as well. In a default configuration The Arsse functions in the same way as TT-RSS: HTTP authentication and API authentication are completely separate and independent. Alternative behaviour is summarized below:
+
+- With default settings:
+    - Clients may optionally provide HTTP credentials
+    - API authentication proceeds as normal
+    - All feed icons are visible to unauthenticated clients
+- If the `userHTTPAuthRequired` setting is `true`:
+    - Clients must pass HTTP authentication
+    - API authentication proceeds as normal
+    - Feed icons are visible only to their owners
+- If the `userSessionEnforced` setting is `false`:
+    - Clients may optionally provide HTTP credentials
+    - If HTTP authentication succeeded 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 is `true` and the `userSessionEnforced` setting is `false`:
+    - 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 is `true`:
+    - The Web server asserts HTTP 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 is `true` and the `userSessionEnforced` setting is `false`:
+    - The Web server asserts HTTP 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.

docs/en/030_Supported_Protocols/index.md

@@ -0,0 +1,6 @@
+The Arsse was designed from the start as a server for multiple synchronization protocols which clients can make use of. Currently the following protocols are supported:
+
+- [NextCloud News](NextCloud_News)
+- [Tiny Tiny RSS](Tiny_Tiny_RSS)
+
+The protocols are merely different ways of accessing and manipulating the same data: subscribing to a newsfeed using one protocol will see the newsfeed also present when later connecting via another protocol, for example. Because not all protocols work according to the same concepts, sometimes the interactions between them are not obvious. These interactions are documented here when warranted.

docs/en/050_Configuring_The_Arsse.md

@@ -8,7 +8,7 @@
 
 The default language locale, mostly used when reporting errors on the command line or in logs. Currently only `"en"` (English) is available.
 
-## Database Settings
+## Database settings
 
 ### dbDriver
 
@@ -82,7 +82,7 @@ The number of seconds to wait before returning a timeout error when acquiring da
 
 Note that PostgreSQL counts time spent waiting for locks as part of the above execution timeout. The maximum timeout for SQLite is `PHP_INT_MAX` milliseconds, which on 32-bit systems is just under 25 days, and on 64-bit systems is billions of years.
 
-## Database Settings Specific to SQLite 3
+## Database settings specific to SQLite 3
 
 ### dbSQLite3File
 
@@ -100,7 +100,7 @@ The full path and file name of SQLite database. The special value `null` evaluat
 
 The key used to encrypt/decrypt the SQLite database. This is only relevant if using the [SQLite Encryption Extension](https://www.sqlite.org/see/).
 
-## Database Settings Specific to PostgreSQL
+## Database settings specific to PostgreSQL
 
 ### dbPostgreSQLHost
 
@@ -164,7 +164,7 @@ A PostgreSQL service file entry to use *instead of* the above configuration; if
 
 Consult [PostgreSQL's documentation](https://www.postgresql.org/docs/current/libpq-pgservice.html) for more details.
 
-## Database Settings Specific to MySQL
+## Database settings specific to MySQL
 
 ### dbMySQLHost
 
@@ -216,7 +216,7 @@ The name of the database used by The Arsse on the MySQL database server.
 
 A Unix domain socket or named pipe to use for the MySQL database server when not connecting via TCP.
 
-## User Management Settings
+## User management settings
 
 ### userDriver
 
@@ -280,7 +280,7 @@ The maximum lifetime of log-in sessions regardless of recent activity. Session l
 
 The desired length in characters of randomly-generated user passwords. When [adding users](/en/Command-Line_Functionality), omitting a desired password generates a random one; this setting controls the length of these passwords.
 
-## Newsfeed Fetching Service Settings
+## Newsfeed fetching service settings
 
 ### serviceDriver
 
@@ -290,8 +290,8 @@ The desired length in characters of randomly-generated user passwords. When [add
 
 The newsfeed fetching service driver to use. The following values are understood:
 
-- `"serial"`: Fetches feeds and processed them one at a time. This is the slowest method, but is simple and reliable.
-- `"subprocess"`: Fetches and processes multiple feeds concurrently by starting a separate process for each feed using PHP's [`popen`](https://php.net/manual/en/function.popen.php) function. This uses more memory and processing power, but takes less total time.
+- `"serial"`: Fetches newsfeeds and processed them one at a time. This is the slowest method, but is simple and reliable.
+- `"subprocess"`: Fetches and processes multiple newsfeeds concurrently by starting a separate process for each newsfeed using PHP's [`popen`](https://php.net/manual/en/function.popen.php) function. This uses more memory and processing power, but takes less total time.
 
 It is also possible to specify the fully-qualified name of a class which implements the service driver interface. For example, specifying `"JKingWeb\Arsse\Service\Serial\Driver"` would use the serial driver.
 
@@ -311,7 +311,7 @@ Consult "[Newsfeed Refresh Schedule](/en/Installation/Using_the_Daemon#Newsfeed_
 |---------|---------|
 | integer | `5`     |
 
-The maximum number of concurrent feed updates to perform, if a concurrent service driver is used. 
+The maximum number of concurrent newsfeed updates to perform, if a concurrent service driver is used. 
 
 ### fetchTimeout
 
@@ -361,7 +361,7 @@ Arsse/0.6.0 (Linux 4.15.0; x86_64; https://thearsse.com/)
 
 How long to keep a newsfeed and its articles in the database after all its subscriptions have been deleted. Specifying `null` will retain unsubscribed newsfeeds forever, whereas an interval evaluating to zero (e.g. `"PT0S"`) will delete them immediately.
 
-Note that articles of orphaned feeds are still subject to the `purgeArticleUnread` threshold below.
+Note that articles of orphaned newsfeeds are still subject to the `purgeArticleUnread` threshold below.
 
 ### purgeArticlesRead
 
@@ -369,7 +369,7 @@ Note that articles of orphaned feeds are still subject to the `purgeArticleUnrea
 |------------------|---------|
 | interval or null | `"P7D"` |
 
-How long to keep a an article in the database after all users subscribed to its feed have read it. Specifying `null` will retain articles up to the `purgeArticlesUnread` threshold below, whereas an interval evaluating to zero (e.g. `"PT0S"`) will delete them immediately. 
+How long to keep a an article in the database after all users subscribed to its newsfeed have read it. Specifying `null` will retain articles up to the `purgeArticlesUnread` threshold below, whereas an interval evaluating to zero (e.g. `"PT0S"`) will delete them immediately. 
 
 If an article is starred by any user, it is retained indefinitely regardless of this setting.
 
@@ -385,7 +385,7 @@ How long to keep a an article in the database regardless of whether any users ha
 
 If an article is starred by any user, it is retained indefinitely regardless of this setting.
 
-# Obsolete Settings
+# Obsolete settings
 
 ### dbSQLite3Timeout