mirror/Arsse
1
1
Fork 0
mirror of https://code.mensbeam.com/MensBeam/Arsse.git synced 2024-12-22 21:22:40 +00:00
Code Issues Activity

Merge branch 'manual'

Browse source
This commit is contained in:
J. King 2019-08-25 13:21:44 -04:00
commit e5696fdf44
52 changed files with 5949 additions and 262 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored
View file

@ -2,12 +2,14 @@
/vendor/
/vendor-bin/*/vendor
/node_modules
/documentation/
/manual/
/tests/coverage/
/arsse.db*
/config.php
/.php_cs.cache
yarn-error.log
# Windows files

266
README.md
View file

@ -1,235 +1,121 @@
# The Advanced RSS Environment
The Arsse is a news aggregator server which implements multiple synchronization protocols. 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. Supported protocols are:
The Arsse is a news aggregator server, written in PHP, which implements multiple synchronization protocols. 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.
- [NextCloud News][NCNv1]
- [Tiny Tiny RSS][TTRSS]
- [Fever][Fever]
Information on how to install and use the software can be found in [the manual](https://thearsse.com/manual/), which is available online as well as with every copy of the software. This readme file instead focuses on how to set up a programming environment to modify the source code.
At present the software should be considered in an "alpha" state: many features one would expect from other similar software have yet to be implemented. Areas of future work include:
# Installing from source
- Providing more sync protocols (Google Reader, others)
- Better packaging and configuration samples
- A user manual
The main repository for The Arsse can be found at [code.mensbeam.com](https://code.mensbeam.com/MensBeam/arsse/), with a mirror also available [at GitHub](https://github.com/meansbeam/arsse/). The main repository is preferred, as the GitHub mirror can sometimes be out of date.
## Requirements
[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install --no-dev` is recommended.
The Arsse has the following requirements:
# Repository structure
- A Linux server utilizing systemd and Nginx (tested on Ubuntu 16.04)
- PHP 7.0.7 or later with the following extensions:
- [intl](http://php.net/manual/en/book.intl.php), [json](http://php.net/manual/en/book.json.php), [hash](http://php.net/manual/en/book.hash.php), and [dom](http://php.net/manual/en/book.dom.php)
- [simplexml](http://php.net/manual/en/book.simplexml.php), and [iconv](http://php.net/manual/en/book.iconv.php) (for picoFeed)
- One of:
- [sqlite3](http://php.net/manual/en/book.sqlite3.php) or [pdo_sqlite](http://php.net/manual/en/ref.pdo-sqlite.php) for SQLite databases
- [pgsql](http://php.net/manual/en/book.pgsql.php) or [pdo_pgsql](http://php.net/manual/en/ref.pdo-pgsql.php) for PostgreSQL 10 or later databases
- [mysqli](http://php.net/manual/en/book.mysqli.php) or [pdo_mysql](http://php.net/manual/en/ref.pdo-mysql.php) for MySQL 8.0.7 or later databases
- Privileges to create and run daemon processes on the server
## Library code
## Installation
The code which runs The Arsse, contained in `/arsse.php`, is only a short stub: the application itself is composed of the classes found under `/lib/`, with the main ones being:
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.
| Path | Description |
|----------------|---------------------------------------------------------|
| `CLI.php` | The command-line interface, including its documentation |
| `Conf.php` | Configuration handling |
| `Database.php` | High-level database interface |
| `Db/` | Low-level database abstraction layer |
| `REST/` | Protocol implementations |
| `REST.php` | General protocol handler for CORS, HTTP auth, etc. |
| `Arsse.php` | Singleton glueing the parts together |
### Initial setup
The `/lib/Database.php` file is the heart of the application, performing queries on behalf of protocol implementations or the command-line interface.
1. Extract the tar archive to `/usr/share`
2. If desired, create `/usr/share/arsse/config.php` using `config.defaults.php` as a guide. The file you create only needs to contain non-default settings. The `userPreAuth` setting may be of particular interest
3. Copy `/usr/share/arsse/dist/arsse.service` to `/lib/systemd/system`
4. In a terminal, execute the following to start the feed fetching service:
Also necessary to the functioning of the application is the `/vendor/` directory, which contains PHP libraries which The Arsse depends upon. These are managed by Composer.
``` sh
sudo systemctl enable arsse
sudo systemctl start arsse
```
## Supporting data files
### Configuring the Web server and PHP
The `/locale/` and `/sql/` directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The `/www/` directory serves as a document root for a few static files to be made available to users by a Web server.
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](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) 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 `/dist/` directory, on the other hand, contains samples of configuration for Web servers and init systems. These are not used by The Arsse itself, but are merely distributed with it for reference.
### Adding users
## Documentation
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.
The source text for The Arsse's manual can be found in `/docs/`, with pages written in [Markdown](https://spec.commonmark.org/current/) and converted to HTML [with Daux](#building-the-manual). If a static manual is generated its files will appear under `/manual/`.
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 Web server and automatically add any missing users as it encounters them.
In addition to the manual the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
Console commands are also available to import from and export to OPML files. Consult `php arsse.php --help` for full details.
## Tests
## Installation from source
The `/tests/` directory contains everything related to automated testing. It is itself organized as follows:
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.
| Path | Description |
|--------------------|------------------------------------------------------------------------------------|
| `cases/` | The test cases themselves, organized in roughly the same structure as the code |
| `coverage/` | (optional) Generated code coverage reports |
| `docroot/` | Sample documents used in some tests, to be returned by the PHP's basic HTTP server |
| `lib/` | Supporting classes which do not contain test cases |
| `bootstrap.php` | Bootstrap script, equivalent to `/arsse.php`, but for tests |
| `phpunit.dist.xml` | PHPUnit configuration file |
| `server.php` | Simple driver for the PHP HTTP server used during testing |
First, you must install [Composer] to fetch required PHP libraries. Once Composer is installed, dependencies may be downloaded with the following command:
PHPUnit's configuration can be customized by copying its configuration file to `/tests/phpunit.xml` and modifying the copy accordingly.
``` sh
php composer.phar install -o --no-dev --no-scripts
```
## Tooling
Second, you may wish to create an example configuration file using the following command:
The `/vendor-bin/` directory houses the files needed for the tools used in The Arsse's programming environment. These are managed by the Composer ["bin" plugin](https://github.com/bamarni/composer-bin-plugin) and are not used by The Arsse itself. The following files are also related to various programming tools:
``` sh
php ./arsse.php conf save-defaults "./config.defaults.php"
```
| Path | Description |
|-------------------|----------------------------------------------------------|
| `/.gitattributes` | Git settings for handling files |
| `/.gitignore` | Git file exclusion patterns |
| `/.php_cs.dist` | Configuration for [php-cs-fixer](https://cs.symfony.com) |
| `/.php_cs.cache` | Cache for php-cs-fixer |
| `/composer.json` | Configuration for Composer |
| `/composer.lock` | Version synchronization data for Composer |
| `/RoboFile.php` | Task definitions for [Robo](https://robo.li/) |
| `/robo` | Simple wrapper for executing Robo on POSIX systems |
| `/robo.bat` | Simple wrapper for executing Robo on Windows |
## License
In addition the files `/package.json`, `/yarn.lock`, and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
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.
# Common tasks
## Contributing
We use a tool called [Robo](https://robo.li/) to simplify the execution of common tasks. It is installed with The Arsse's other dependencies, and its configured tasks can be listed by executing `./robo` without arguments.
Please refer to `CONTRIBUTING.md` for guidelines on contributing code to The Arsse.
## Running tests
## Database compatibility notes
The Arsse has an extensive [PHPUnit](https://phpunit.de/) test suite; tests can be run by executing `./robo test`, which can be supplemented with any arguments understoof by PHPUnit. For example, to test only the Tiny Tiny RSS protocol, one could run `./robo test --testsuite TTRSS`.
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.
There is also a `test:quick` Robo task which excludes slower tests, and a `test:full` task which includes redundant tests in addition to the standard test suite
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.
### Test coverage
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.
Computing the coverage of tests can be done by running `./robo coverage`. Either [phpdbg](https://php.net/manual/en/book.phpdbg.php) or [Xdebug](https://xdebug.org) is required for this. An HTML-format coverage report will be written to `/tests/coverage/`.
## Protocol compatibility notes
## Enforcing coding style
### General
The [php-cs-fixer](https://cs.symfony.com) tool, executed via `./robo clean`, can be used to rewrite code to adhere to The Arsse's coding style. The style largely follows [PSR-2](https://www.php-fig.org/psr/psr-2/) with some exceptions:
#### Type casting
- Classes, methods, and functions should have their opening brace on the same line as the signature
- Anonymous functions should have no space before the parameter list
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.
## Building the manual
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.
The Arsse's user manual, made using [Daux](https://daux.io/), can be compiled by running `./robo manual`, which will output files to `/manual/`. It is also possible to serve the manual from a test HTTP server on port 8085 by running `./robo manual:live`.
#### Content sanitization
### Rebuilding the manual theme
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.
The manual employs a custom theme derived from the standard Daux theme. If the standard Daux theme receives improvements, the custom theme can be rebuilt by running `./robo manual:theme`. This requires that [NodeJS](https://nodejs.org) and [Yarn](https://yarnpkg.com/) be installed, but JavaScript tools are not required to modify The Arsse itself, nor the content of the manual.
### NextCloud News v1.2
The Robo task `manual:css` will recompile the theme's stylesheet without rebuilding the entire theme.
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 above detail these differences.
## Packaging a release
#### Differences
Producing a release package is done by running `./robo package`. This performs the following operations:
- 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
- Duplicates a working tree with the commit (usually a release tag) to package
- Generates the manual
- Installs runtime Composer dependencies with an optimized autoloader
- Deletes numerous unneeded files
- Exports the default configuration of The Arsse to a file
- Compresses the remaining files into a tarball
### 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 above detail these differences.
#### Extended functionality
The Arsse supports both [the set of extensions][ext-feedreader] to the TTRSS protocol defined by [FeedReader], as well as [the `getCompactHeadlines` operation][ext-newsplus] 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][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 `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
- Providing the `setArticleLabel` operation with an invalid label normally silently fails; The Arsse returns an `INVALID_USAGE` error instead
- Processing of the `search` parameter of the `getHeadlines` operation differs in the following ways:
- Values other than `"true"` or `"false"` for the `unread`, `star`, and `pub` special keywords treat the entire token as a search term rather than as `"false"`
- Invalid dates are ignored rather than assumed to be `"1970-01-01"`
- Only a single negative date is allowed (this is a known bug rather than intentional)
- Dates are always relative to UTC
- Full-text search is not yet employed with any database, including PostgreSQL
- 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 `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 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 TTRSS 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 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:
- 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.
### Fever
Unlike other protocols thus far supported by The Arsse, a reference implementation of [the Fever protocol][Fever] is no longer available: Fever was witdrawn from sale in 2016. Consequently the Arsse's implementation may not replicate all of Fever's functionality correctly. Moreover, some features have been deliberately omitted.
#### Special considerations
- Because of Fever's insecure authentication protocol, a Fever-specific password must be created before a user can communicate via the Fever protocol. Consult The Arsse's online help (`php arsse.php --help`) for instructions on how to set the necessary password
- The Fever protocol does not allow for adding or modifying feeds. Another protocol or OPML importing must be used to manage feeds
- Unlike other protocols supported by The Arsse, Fever uses "groups" (more commonly known as tags or labels) instead of folders to organize feeds. Currently OPML importing is the only means of managing groups
#### Missing features
- All feeds are considered "Kindling"
- The "Hot Links" feature is not implemented; when requested, an empty array will be returned. As there is no way to classify a feed as a "Spark" in the protocol itself and no documentation exists on how link temperature was calculated, an implementation is unlikely to appear in the future
- Favicons are not currently supported; all feeds have a simple blank image as their favicon
#### Other notes
- The undocumented `group_ids`, `feed_ids`, and `as=unread` parameters are all supported
- XML output is supported, but may not behave as Fever did. JSON output is highly recommended
[newIssue]: https://code.mensbeam.com/MensBeam/arsse/issues/new
[Composer]: https://getcomposer.org/
[picoFeed]: https://github.com/miniflux/picoFeed/
[NCN]: https://github.com/nextcloud/news
[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
[FeedReader]: https://jangernert.github.io/FeedReader/
[News+]: https://github.com/noinnion/newsplus/
[ext-feedreader]: https://github.com/jangernert/FeedReader/tree/master/data/tt-rss-feedreader-plugin
[ext-newsplus]: https://github.com/hrk/tt-rss-newsplus-plugin
[Fever]: https://web.archive.org/web/20161217042229/https://feedafever.com/api
Due to the first step, [Git](https://git-scm.com/) is required to package a release.

168
RoboFile.php
View file

@ -2,12 +2,21 @@
use Robo\Result;
class RoboFile extends \Robo\Tasks {
const BASE = __DIR__.\DIRECTORY_SEPARATOR;
const BASE_TEST = self::BASE."tests".\DIRECTORY_SEPARATOR;
/**
* Runs the typical test suite
const BASE = __DIR__.\DIRECTORY_SEPARATOR;
const BASE_TEST = BASE."tests".\DIRECTORY_SEPARATOR;
define("IS_WIN", defined("PHP_WINDOWS_VERSION_MAJOR"));
function norm(string $path): string {
$out = realpath($path);
if (!$out) {
$out = str_replace(["/", "\\"], \DIRECTORY_SEPARATOR, $path);
}
return $out;
}
class RoboFile extends \Robo\Tasks {
/** Runs the typical test suite
*
* Arguments passed to the task are passed on to PHPUnit. Thus one may, for
* example, run the following command and get the expected results:
@ -17,17 +26,16 @@ class RoboFile extends \Robo\Tasks {
* Please see the PHPUnit documentation for available options.
*/
public function test(array $args): Result {
return $this->runTests("php", "typical", $args);
return $this->runTests(escapeshellarg(\PHP_BINARY), "typical", $args);
}
/**
* Runs the full test suite
/** Runs the full test suite
*
* This includes pedantic tests which may help to identify problems.
* See help for the "test" task for more details.
*/
public function testFull(array $args): Result {
return $this->runTests("php", "full", $args);
return $this->runTests(escapeshellarg(\PHP_BINARY), "full", $args);
}
/**
@ -36,7 +44,7 @@ class RoboFile extends \Robo\Tasks {
* See help for the "test" task for more details.
*/
public function testQuick(array $args): Result {
return $this->runTests("php", "quick", $args);
return $this->runTests(escapeshellarg(\PHP_BINARY), "quick", $args);
}
/** Produces a code coverage report
@ -52,7 +60,7 @@ class RoboFile extends \Robo\Tasks {
public function coverage(array $args): Result {
// run tests with code coverage reporting enabled
$exec = $this->findCoverageEngine();
return $this->runTests($exec, "coverage", array_merge(["--coverage-html", self::BASE_TEST."coverage"], $args));
return $this->runTests($exec, "coverage", array_merge(["--coverage-html", BASE_TEST."coverage"], $args));
}
/** Produces a code coverage report, with redundant tests
@ -67,12 +75,12 @@ class RoboFile extends \Robo\Tasks {
public function coverageFull(array $args): Result {
// run tests with code coverage reporting enabled
$exec = $this->findCoverageEngine();
return $this->runTests($exec, "typical", array_merge(["--coverage-html", self::BASE_TEST."coverage"], $args));
return $this->runTests($exec, "typical", array_merge(["--coverage-html", BASE_TEST."coverage"], $args));
}
/** Runs the coding standards fixer */
public function clean($opts = ['demo|d' => false]): Result {
$t = $this->taskExec(realpath(self::BASE."vendor/bin/php-cs-fixer"));
$t = $this->taskExec(norm(BASE."vendor/bin/php-cs-fixer"));
$t->arg("fix");
if ($opts['demo']) {
$t->args("--dry-run", "--diff")->option("--diff-format", "udiff");
@ -81,7 +89,7 @@ class RoboFile extends \Robo\Tasks {
}
protected function findCoverageEngine(): string {
if ($this->isWindows()) {
if (IS_WIN) {
$dbg = dirname(\PHP_BINARY)."\\phpdbg.exe";
$dbg = file_exists($dbg) ? $dbg : "";
} else {
@ -94,12 +102,8 @@ class RoboFile extends \Robo\Tasks {
}
}
protected function isWindows(): bool {
return defined("PHP_WINDOWS_VERSION_MAJOR");
}
protected function blackhole(bool $all = false): string {
$hole = $this->isWindows() ? "nul" : "/dev/null";
$hole = IS_WIN ? "nul" : "/dev/null";
return $all ? ">$hole 2>&1" : "2>$hole";
}
@ -120,9 +124,9 @@ class RoboFile extends \Robo\Tasks {
default:
throw new \Exception;
}
$execpath = realpath(self::BASE."vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit");
$confpath = realpath(self::BASE_TEST."phpunit.xml");
$this->taskServer(8000)->host("localhost")->dir(self::BASE_TEST."docroot")->rawArg("-n")->arg(self::BASE_TEST."server.php")->rawArg($this->blackhole())->background()->run();
$execpath = norm(BASE."vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit");
$confpath = realpath(BASE_TEST."phpunit.dist.xml") ?: norm(BASE_TEST."phpunit.xml");
$this->taskServer(8000)->host("localhost")->dir(BASE_TEST."docroot")->rawArg("-n")->arg(BASE_TEST."server.php")->rawArg($this->blackhole())->background()->run();
return $this->taskExec($executor)->arg($execpath)->option("-c", $confpath)->args(array_merge($set, $args))->run();
}
@ -138,15 +142,19 @@ class RoboFile extends \Robo\Tasks {
*/
public function package(string $version = null): Result {
// establish which commit to package
$version = $version ?? $this->askDefault("Commit to package:", "head");
$archive = self::BASE."arsse-$version.tar.gz";
$version = $version ?? $this->askDefault("Commit to package:", "HEAD");
$archive = BASE."arsse-$version.tar.gz";
// start a collection
$t = $this->collectionBuilder();
// create a temporary directory
$dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
// create a Git worktree for the selected commit in the temp location
$t->taskExec("git worktree add ".escapeshellarg($dir)." ".escapeshellarg($version));
// perform Composer installation in the temp location
// perform Composer installation in the temp location with dev dependencies
$t->taskComposerInstall()->dir($dir);
// generate the manual
$t->taskExec(escapeshellarg($dir."robo")." manual")->dir($dir);
// perform Composer installation in the temp location for final output
$t->taskComposerInstall()->dir($dir)->noDev()->optimizeAutoloader()->arg("--no-scripts");
// delete unwanted files
$t->taskFilesystemStack()->remove([
@ -160,13 +168,18 @@ class RoboFile extends \Robo\Tasks {
$dir."build.xml",
$dir."RoboFile.php",
$dir."CONTRIBUTING.md",
$dir."docs",
$dir."tests",
$dir."vendor-bin",
$dir."vendor/bin",
$dir."robo",
$dir."robo.bat",
$dir."package.json",
$dir."yarn.lock",
$dir."postcss.config.js",
]);
// generate a sample configuration file
$t->taskExec("php arsse.php conf save-defaults config.defaults.php")->dir($dir);
$t->taskExec(escapeshellarg(\PHP_BINARY)." arsse.php conf save-defaults config.defaults.php")->dir($dir);
// package it all up
$t->taskPack($archive)->addDir("arsse", $dir);
// execute the collection
@ -175,4 +188,107 @@ class RoboFile extends \Robo\Tasks {
$this->_exec("git worktree prune");
return $out;
}
/** Generates static manual pages in the "manual" directory
*
* The resultant files are suitable for offline viewing and inclusion into release builds
*/
public function manual(array $args): Result {
$execpath = escapeshellarg(norm(BASE."vendor/bin/daux"));
$t = $this->collectionBuilder();
$t->taskExec($execpath)->arg("generate")->option("-d", BASE."manual")->args($args);
$t->taskDeleteDir(BASE."manual/theme");
$t->taskDeleteDir(BASE."manual/themes/src");
return $t->run();
}
/** Serves a live view of the manual using the built-in Web server */
public function manualLive(array $args): Result {
$execpath = escapeshellarg(norm(BASE."vendor/bin/daux"));
return $this->taskExec($execpath)->arg("serve")->args($args)->run();
}
/** Rebuilds the entire manual theme
*
* This requires Node and Yarn to be installed, and only needs to be done when
* Daux's theme changes
*/
public function manualTheme(array $args): Result {
$languages = ["php", "bash", "shell", "xml", "nginx", "apache"];
$themeout = norm(BASE."docs/theme/arsse/").\DIRECTORY_SEPARATOR;
$dauxjs = norm(BASE."vendor-bin/daux/vendor/daux/daux.io/themes/daux/js/").\DIRECTORY_SEPARATOR;
// start a collection; this stops after the first failure
$t = $this->collectionBuilder();
$tmp = $t->tmpDir().\DIRECTORY_SEPARATOR;
// rebuild the stylesheet
$t->addCode([$this, "manualCss"]);
// copy JavaScript files from the Daux theme
foreach(glob($dauxjs."daux*") as $file) {
$t->taskFilesystemStack()->copy($file, $themeout.basename($file), true);
}
// download highlight.js
$t->addCode(function() use ($languages, $tmp, $themeout) {
// compile the list of desired language (enumerated above) into an application/x-www-form-urlencoded body
$post = http_build_query((function($langs) {
$out = [];
foreach($langs as $l) {
$out[$l.".js"] = "on";
}
return $out;
})($languages));
// get the two cross-site request forgery tokens the Highlight.js Web site requires
$conn = @fopen("https://highlightjs.org/download/", "r");
if ($conn === false) {
throw new Exception("Unable to download Highlight.js");
}
foreach (stream_get_meta_data($conn)['wrapper_data'] as $field) {
if (preg_match("/^Set-Cookie: csrftoken=([^;]+)/i", $field, $cookie)) {
break;
}
}
$token = stream_get_contents($conn);
preg_match("/<input type='hidden' name='csrfmiddlewaretoken' value='([^']*)'/", $token, $token);
// add the form CSRF token to the POST body
$post = "csrfmiddlewaretoken={$token[1]}&$post";
// download a copy of Highlight.js with the desired languages to a temporary file
$hljs = @file_get_contents("https://highlightjs.org/download/", false, stream_context_create(['http' => [
'method' => "POST",
'content' => $post,
'header' => [
"Referer: https://highlightjs.org/download/",
"Cookie: csrftoken={$cookie[1]}",
"Content-Type: application/x-www-form-urlencoded",
],
]]));
if ($hljs === false) {
throw new Exception("Unable to download Highlight.js");
} else {
file_put_contents($tmp."highlightjs.zip", $hljs);
}
// extract the downloaded zip file and keep only the JS file
$this->taskExtract($tmp."highlightjs.zip")->to($tmp."hljs")->run();
$this->taskFilesystemStack()->copy($tmp."hljs".\DIRECTORY_SEPARATOR."highlight.pack.js", $themeout."highlight.pack.js")->run();
}, "downloadHighlightjs");
// execute the collection
return $t->run();
}
/** Rebuilds the manual theme's stylesheet only
*
* This requires Node and Yarn to be installed.
*/
public function manualCss(): Result {
// start a collection; this stops after the first failure
$t = $this->collectionBuilder();
$tmp = $t->tmpDir().\DIRECTORY_SEPARATOR;
// install dependencies via Yarn
$t->taskExec("yarn install");
// compile the stylesheet
$postcss = escapeshellarg(norm(BASE."node_modules/.bin/postcss"));
$themesrc = norm(BASE."docs/theme/src/").\DIRECTORY_SEPARATOR;
$themeout = norm(BASE."docs/theme/arsse/").\DIRECTORY_SEPARATOR;
$t->taskExec($postcss)->arg($themesrc."arsse.scss")->option("-o", $themeout."arsse.css");
// execute the collection
return $t->run();
}
}

23
dist/apache.conf vendored Normal file
View file

@ -0,0 +1,23 @@
# N.B. the unix:/var/run/php/php7.2-fpm.sock path used repeatedly below will
# vary from system to system and will be probably need to be changed
<VirtualHost *:80>
ServerName localhost
# adjust according to your installation path
DocumentRoot /usr/share/arsse/www
# adjust according to your installation path
ProxyFCGISetEnvIf "true" SCRIPT_FILENAME "/usr/share/arsse/arsse.php"
ProxyPreserveHost On
# NextCloud News v1.2, Tiny Tiny RSS API, TT-RSS newsfeed icons
<LocationMatch "(/index\.php/apps/news/api/?.+|/tt-rss/(api|feed-icons))">
ProxyPass "unix:/var/run/php/php7.2-fpm.sock|fcgi://localhost/usr/share/arsse"
</LocationMatch>
# NextCloud News API detection, Fever API
<LocationMatch "(/index\.php/apps/news/api/?$|/fever)">
# these locations should not be behind HTTP authentication
ProxyPass "unix:/var/run/php/php7.2-fpm.sock|fcgi://localhost/usr/share/arsse"
</LocationMatch>
</VirtualHost>

13
dist/nginx-fcgi.conf vendored
View file

@ -1,13 +0,0 @@
fastcgi_pass php; # PHP is assumed to already be configured for FastCGI operation
fastcgi_pass_header Authorization; # required if the Arsse is to perform its own HTTP authentication
fastcgi_pass_request_body on;
fastcgi_pass_request_headers on;
fastcgi_intercept_errors off;
fastcgi_buffering off;
fastcgi_param SCRIPT_FILENAME /usr/share/arsse/arsse.php;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param REQUEST_URI $uri;
fastcgi_param HTTPS $https if_not_empty;
fastcgi_param REMOTE_USER $remote_user;

49
dist/nginx.conf vendored
View file

@ -1,56 +1,57 @@
server {
server_name news.example.com;
server_name example.com;
listen 80; # adding HTTPS configuration is highly recommended
# redirect to HTTPS, if desired
#if ($https != "on") {rewrite ^ https://$host$request_uri;}
# the userPreAuth setting should be enabled if the Web server is handling authentication
#auth_basic "Advanced RSS Environment";
root /usr/share/arsse/www;
index index.html;
root /usr/share/arsse/www; # adjust according to your installation path
location / {
try_files $uri $uri/ =404;
}
location @arsse_auth {
# the userPreAuth setting should be enabled if the Web server is handling authentication
#auth_basic "Advanced RSS Environment";
include /usr/share/arsse/dist/nginx-fcgi.conf;
}
location @arsse_no_auth {
auth_basic off;
include /usr/share/arsse/dist/nginx-fcgi.conf;
location @arsse {
fastcgi_pass unix:/var/run/php/php7.2-fpm.sock; # adjust according to your system configuration
fastcgi_pass_header Authorization; # required if the Arsse is to perform its own HTTP authentication
fastcgi_pass_request_body on;
fastcgi_pass_request_headers on;
fastcgi_intercept_errors off;
fastcgi_buffering off;
fastcgi_param SCRIPT_FILENAME /usr/share/arsse/arsse.php; # adjust according to your installation path
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param REQUEST_URI $uri;
fastcgi_param HTTPS $https if_not_empty;
fastcgi_param REMOTE_USER $remote_user;
}
# NextCloud News protocol
location /index.php/apps/news/api {
try_files $uri @arsse_auth;
try_files $uri @arsse;
location ~ ^/index\.php/apps/news/api/?$ {
try_files $uri @arsse_no_auth;
# this path should not be behind HTTP authentication
try_files $uri @arsse;
}
}
# Tiny Tiny RSS protocol
location /tt-rss/api {
try_files $uri @arsse_no_auth;
try_files $uri @arsse;
}
# Tiny Tiny RSS feed icons
location /tt-rss/feed-icons/ {
try_files $uri @arsse_no_auth;
try_files $uri @arsse;
}
# Tiny Tiny RSS special-feed icons
# Tiny Tiny RSS special-feed icons; these are static files
location /tt-rss/images/ {
auth_basic off;
root /usr/share/arsse/www;
# this path should not be behind HTTP authentication
try_files $uri =404;
}
# Fever protocol
location /fever/ {
try_files $uri @arsse_no_auth;
# this path should not be behind HTTP authentication
try_files $uri @arsse;
}
}

15
docs/config.json Normal file
View file

@ -0,0 +1,15 @@
{
"title": "The Advanced RSS Environment",
"tagline": "The clean & modern RSS server that doesn't give you any crap.",
"author": "J. King",
"languages": {
"en": "English"
},
"themes_directory": "docs/theme",
"html": {
"theme": "arsse",
"float": false,
"toggle_code": false,
"search": false
}
}

14
docs/en/010_About.md Normal file
View file

@ -0,0 +1,14 @@
The Advanced RSS Environment (affectionately called "The Arsse") is a news aggregator server which implements multiple synchronization protocols. 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](Supported_Protocols) to maximize compatibility with [existing clients](Compatible_Clients). Supported protocols are:
- NextCloud News
- Tiny Tiny RSS
- Fever
The primary goal of The Arsse is to bridge the many isolated ecosystems of client software for the various news synchronization protocols currently in existence. We want people to be able to use the best client software for whatever operating system they use, regardless of the protocols the client supports.
Though The Arsse currently supports only a few protocols, many more are within scope for inclusion, as long as the protocol is not specific to a single service and has clients available.
At present the software should be considered in an "alpha" state: many features one would expect from other similar software have yet to be implemented. Areas of future work include:
- Providing more sync protocols (Google Reader, others)
- Better packaging and configuration samples

15
docs/en/020_Getting_Started/010_Requirements.md Normal file
View file

@ -0,0 +1,15 @@
The Arsse has the following requirements:
- A Linux server running Nginx or Apache 2.4 (tested on Ubuntu 16.04 and 18.04)
- PHP 7.0.7 or later with the following extensions:
- [intl](http://php.net/manual/en/book.intl.php), [json](http://php.net/manual/en/book.json.php), [hash](http://php.net/manual/en/book.hash.php), and [dom](http://php.net/manual/en/book.dom.php)
- [simplexml](http://php.net/manual/en/book.simplexml.php), and [iconv](http://php.net/manual/en/book.iconv.php)
- One of:
- [sqlite3](http://php.net/manual/en/book.sqlite3.php) or [pdo_sqlite](http://php.net/manual/en/ref.pdo-sqlite.php) for SQLite databases
- [pgsql](http://php.net/manual/en/book.pgsql.php) or [pdo_pgsql](http://php.net/manual/en/ref.pdo-pgsql.php) for PostgreSQL 10 or later databases
- [mysqli](http://php.net/manual/en/book.mysqli.php) or [pdo_mysql](http://php.net/manual/en/ref.pdo-mysql.php) for MySQL/Percona 8.0.11 or later databases
- Privileges either to create and run systemd services, or to run cron jobs
Instructions for how to satisfy the PHP extension requirements for Debian systems are included in the next section.
It is also be possible to run The Arsse on other operating systems (including Windows) and with other Web servers, but the configuration required to do so is not documented in this manual.

41
docs/en/020_Getting_Started/020_Download_and_Installation.md Normal file
View file

@ -0,0 +1,41 @@
[TOC]
# Downloading The Arse
The latest version of The Arsse can be downloaded [from our releases page](https://code.mensbeam.com/MensBeam/arsse/releases). The attachments named _arsse-x.x.x.tar.gz_ should be used rather than those marked "Source Code".
Installation from source code is also possible, but the release packages are recommended.
# Installation
In order for The Arsse to function correctly, [its requirements](Requirements) must first be satisfied. The process of installing the required PHP extensions differs from one system to the next, but on Debian the following series of commands should do:
```sh
# Install PHP; this assumes the FastCGI process manager will be used
sudo apt install php-cli php-fpm
# Install the needed PHP extensions; php-curl is optional
sudo apt install php-intl php-json php-xml php-curl
# Install any one of the required database extensions
sudo apt install php-sqlite3 php-pgsql php-mysql
```
Then, it's a simple matter of unpacking the archive someplace (`/usr/share/arsse` is the recommended location on Debian systems, but it can be anywhere) and setting permissions:
```sh
# Unpack the archive
sudo tar -xzf arsse-x.x.x.tar.gz -C "/usr/share"
# Make the user running the Web server the owner of the files
sudo chown -R www-data:www-data "/usr/share/arsse"
# Ensure the owner can create files such as the SQLite database
sudo chmod o+rwX "/usr/share/arsse"
```
# Next steps
If using a database other than SQLite, you will likely want to [set it up](Database_Setup) before doing anything else.
In order for the various synchronization protocols to work, a Web server [must be configured](Web_Server_Configuration), and in order for The Arsse to serve users, those users [must be created](/en/Using_The_Arsse/Managing_Users).
You may also want to review the `config.defaults.php` file included in the download package and create [a configuration file](Configuration), though The Arsse can function even without using a configuration file.
Finally, The Arsse's [newsfeed refreshing service](/en/Using_The_Arsse/Keeping_Newsfeeds_Up_to_Date) needs to be installed in order for news to actually be fetched from the Internet.

106
docs/en/020_Getting_Started/030_Web_Server_Configuration.md Normal file
View file

@ -0,0 +1,106 @@
[TOC]
# Preface
As a PHP application, The Arsse requires the aid of a Web server in order to communicate with clients. How to install and configure a Web server in general is outside the scope of this document, but this section provides examples and advice for Web server configuration specific to The Arsse. Any server capable of interfacing with PHP should work, though we have only tested Nginx and Apache 2.4.
Samples included here only cover the bare minimum for configuring a virtual host. In particular, configuration for HTTPS (which is highly recommended) is omitted for the sake of clarity
# Configuration for Nginx
```nginx
server {
server_name example.com;
listen 80; # adding HTTPS configuration is highly recommended
root /usr/share/arsse/www; # adjust according to your installation path
location / {
try_files $uri $uri/ =404;
}
location @arsse {
fastcgi_pass unix:/var/run/php/php7.2-fpm.sock; # adjust according to your system configuration
fastcgi_pass_header Authorization; # required if the Arsse is to perform its own HTTP authentication
fastcgi_pass_request_body on;
fastcgi_pass_request_headers on;
fastcgi_intercept_errors off;
fastcgi_buffering off;
fastcgi_param SCRIPT_FILENAME /usr/share/arsse/arsse.php; # adjust according to your installation path
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param REQUEST_URI $uri;
fastcgi_param HTTPS $https if_not_empty;
fastcgi_param REMOTE_USER $remote_user;
}
# NextCloud News protocol
location /index.php/apps/news/api {
try_files $uri @arsse;
location ~ ^/index\.php/apps/news/api/?$ {
# this path should not be behind HTTP authentication
try_files $uri @arsse;
}
}
# Tiny Tiny RSS protocol
location /tt-rss/api {
try_files $uri @arsse;
}
# Tiny Tiny RSS feed icons
location /tt-rss/feed-icons/ {
try_files $uri @arsse;
}
# Tiny Tiny RSS special-feed icons; these are static files
location /tt-rss/images/ {
# this path should not be behind HTTP authentication
try_files $uri =404;
}
# Fever protocol
location /fever/ {
# this path should not be behind HTTP authentication
try_files $uri @arsse;
}
}
```
# Configuration for Apache2
There are many ways for Apache to interface with PHP, but the recommended way today is to use `mod_proxy` and `mod_proxy_fcgi` to communicate with PHP-FPM. If necessary you can enable these modules on Debian systems using the following commands:
```sh
sudo a2enmod proxy proxy_fcgi
sudo systemctl restart apache2
```
Afterward the follow virtual host configuration should work, after modifying path as appropriate:
```apache
# N.B. the unix:/var/run/php/php7.2-fpm.sock path used repeatedly below will
# vary from system to system and will be probably need to be changed
<VirtualHost *:80>
ServerName localhost
# adjust according to your installation path
DocumentRoot /usr/share/arsse/www
# adjust according to your installation path
ProxyFCGISetEnvIf "true" SCRIPT_FILENAME "/usr/share/arsse/arsse.php"
ProxyPreserveHost On
# NextCloud News v1.2, Tiny Tiny RSS API, TT-RSS newsfeed icons
<LocationMatch "(/index\.php/apps/news/api/?.+|/tt-rss/(api|feed-icons))">
ProxyPass "unix:/var/run/php/php7.2-fpm.sock|fcgi://localhost/usr/share/arsse"
</LocationMatch>
# NextCloud News API detection, Fever API
<LocationMatch "(/index\.php/apps/news/api/?$|/fever)">
# these locations should not be behind HTTP authentication
ProxyPass "unix:/var/run/php/php7.2-fpm.sock|fcgi://localhost/usr/share/arsse"
</LocationMatch>
</VirtualHost>
```

16
docs/en/020_Getting_Started/040_Database_Setup/000_SQLite.md Normal file
View file

@ -0,0 +1,16 @@
# About
<dl>
<dt>Supported since</dt>
<dd>0.1.0</dd>
<dt>dbDriver identifier</dt>
<dd>sqlite3</dd>
<dt>Minimum version</dt>
<dd>3.8.3</dd>
<dt>Configuration</dt>
<dd><a href="../Configuration.html#page_Database-settings">General</a>, <a href="../Configuration.html#page_Database-settings-specific-to-SQLite-3">Specific</a></dd>
</dl>
SQLite requires very little set-up. By default the database will be created at the root of The Arsse's program directory (e.g. `/usr/share/arsse/arsse.db`), but this can be changed with the [`dbSQLite3File` setting](/en/Getting_Started/Configuration#page_dbSQLite3File).
Regardless of the location chosen, The Arsse **must** be able to both read from and write to the database file, as well as create files in its directory. This is because SQLite also creates a write-ahead log file and a shared-memory file during operation.

37
docs/en/020_Getting_Started/040_Database_Setup/010_PostgreSQL.md Normal file
View file

@ -0,0 +1,37 @@
# About
<dl>
<dt>Supported since</dt>
<dd>0.6.0</dd>
<dt>dbDriver identifier</dt>
<dd>postgresql</dd>
<dt>Minimum version</dt>
<dd>10</dd>
<dt>Configuration</dt>
<dd><a href="../Configuration.html#page_Database-settings">General</a>, <a href="../Configuration.html#page_Database-settings-specific-to-PostgreSQL">Specific</a></dd>
</dl>
If for whatever reason an SQLite database does not suit your configuration, PostgreSQL is the best alternative. It is functionally equivalent to SQLite in every way.
# Set-up
In order to use a PostgreSQL database for The Arsse, the database must already exist. The procedure for creating a database can differ between systems, but a typical Linux procedure is as follows:
```sh
sudo -u postgres psql -c "CREATE USER arsseuser WITH PASSWORD 'super secret password'"
sudo -u postgres psql -c "CREATE DATABASE arssedb WITH OWNER arsseuser"
```
Tha Arsse must then be configured to use the created database. A suitable [configuration file](/en/Getting_Started/Configuration) might look like this:
```php
<?php
return [
'dbDriver' => "postgresql",
'dbPostgreSQLUser' => "arsseuser",
'dbPostgreSQLPass' => "super secret password",
'dbPostgreSQLDb' => "arssedb",
];
```
Numerous alternate configurations are possible; the above is merely the simplest.

40
docs/en/020_Getting_Started/040_Database_Setup/020_MySQL.md Normal file
View file

@ -0,0 +1,40 @@
# About
<dl>
<dt>Supported since</dt>
<dd>0.6.0</dd>
<dt>dbDriver identifier</dt>
<dd>mysql</dd>
<dt>Minimum version</dt>
<dd>8.0.11</dd>
<dt>Configuration</dt>
<dd><a href="../Configuration.html#page_Database-settings">General</a>, <a href="../Configuration.html#page_Database-settings-specific-to-MySQL">Specific</a></dd>
</dl>
While MySQL can be used as a database for The Arsse, this is **not recommended** due to MySQL's technical limitations. It is fully functional, but may fail with some newsfeeds where other database systems do not. Additionally, it is particularly important before upgrading from one version of The Arsse to the next to back up your database: a failure in a database upgrade can corrupt your database much more easily than when using other database systems.
Please note that as of this writing MariaDB cannot be used in place of MySQL as it lacks features of MySQL 8 which The Arsse requires. The awkwardly-named [_Percona Server for MySQL_](https://www.percona.com/software/mysql-database/percona-server), on the other hand, should work, though this has not been tested.
# Set-up
In order to use a MySQL database for The Arsse, the database must already exist. The procedure for creating a database can differ between systems, but a typical Linux procedure is as follows:
```sh
sudo mysql -e "CREATE USER 'arsseuser'@'localhost' IDENTIFIED BY 'super secret password'"
sudo mysql -e "CREATE DATABASE arssedb"
sudo mysql -e "GRANT ALL ON arssedb.* TO 'arsseuser'@'localhost'"
```
Tha Arsse must then be configured to use the created database. A suitable [configuration file](/en/Getting_Started/Configuration) might look like this:
```php
<?php
return [
'dbDriver' => "mysql",
'dbMySQLUser' => "arsseuser",
'dbMySQLPass' => "super secret password",
'dbMySQLDb' => "arssedb",
];
```
Numerous alternate configurations are possible; the above is merely the simplest.

11
docs/en/020_Getting_Started/040_Database_Setup/index.md Normal file
View file

@ -0,0 +1,11 @@
The Arsse supports the following database backends:
- [SQLite 3.8.3](SQLite) and later
- [PostgreSQL 10](PostgreSQL) and later
- [MySQL 8.0.11](MySQL) and later
All of the above are supported both via their PDO driver extensions as well as their native PHP extensions. One or the other is selected based on availability in your PHP installation.
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 various technical limitations.

418
docs/en/020_Getting_Started/050_Configuration.md Normal file
View file

@ -0,0 +1,418 @@
# The configuration file
The Arsse looks for configuration in a file named `config.php` in the directory where it is installed. For example, if The Arsse is installed at `/usr/share/arsse`, it will look for configuration in the file `/usr/share/arsse/config.php`. It is not an error for this file not to exist or to be empty: The Arsse will function with no configuration whatsoever, provided other conditions allow.
The configuration file is a PHP script which returns an associative array with keys and values for one or more settings. Any settings which are not specified in the configuration file will be set to their defaults. Invalid values will cause an error on start-up, while unknown keys are ignored. A basic configuration file might look like this:
```php
<?php return [
'lang' => "en",
'dbDriver' => "sqlite3",
'dbSQLite3File' => "/var/lib/arsse/arsse.db",
];
```
The `config.defaults.php` file included with copies of The Arsse contains an annotated listing of every configuration setting with its default value. The settings are also documented in more detail below.
# List of all settings
## General settings
### lang
| Type | Default |
|--------|---------|
| string | `"en"` |
The default language locale, mostly used when reporting errors on the command line or in logs. Currently only `"en"` (English) is available.
## Database settings
### dbDriver
| Type | Default |
|--------|-------------|
| string | `"sqlite3"` |
The database driver to use. The following values are understood:
- `"sqlite3"` for SQLite databases
- `"postgresql"` for PostgreSQL databases
- `"mysql"` for MySQL databases
It is also possible to specify the fully-qualified name of a class which implements the database driver interface. For example, specifying `"JKingWeb\Arsse\Db\SQLite3\PDODriver"` would use the PDO driver for SQLite 3.
### dbAutoUpdate
| Type | Default |
|---------|---------|
| boolean | `true` |
Whether to attempt to automatically upgrade the database schema when upgrading The Arsse to a new version with schema changes.
If set to `false`, the database schema must be manually upgraded. Schema files can be found under `sql/<backend>/#.sql`; the `UPGRADING` file will advise when a schema upgrade is required.
### dbTimeoutConnect
| Type | Default |
|------------------|---------|
| interval or null | `5.0` |
The number of seconds to wait before returning a timeout error when connecting to a database server. The special value `null` waits the maximum amount of time, while `0.0` waits the minimum amount of time. The minimums are maximums for each backend are as follows:
| Backend | Minimum | Maximum |
|------------|----------|----------|
| SQLite 3 | *(does not apply)* | *(does not apply)* |
| PostgreSQL | 1 second | forever |
| MySQL | 1 second | forever |
Note that in practice neither PostgreSQL nor MySQL will wait indefinitely: they are still subject to PHP's socket timeouts. Consult [PostgreSQL's documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-CONNECT-TIMEOUT) for details on how the timeout is interpreted by PostgreSQL.
### dbTimeoutExec
| Type | Default |
|----------|---------|
| interval | `null` |
The number of seconds to wait before returning a timeout error when executing a database operation (i.e. computing results). The special value `null` waits the maximum amount of time, while `0.0` waits the minimum amount of time. The minimums are maximums for each backend are as follows:
| Backend | Minimum | Maximum |
|------------|---------------|----------|
| SQLite 3 | *(does not apply)* | *(does not apply)* |
| PostgreSQL | 1 millisecond | forever |
| MySQL | 1 second | forever |
With MySQL this timeout only applies to read operations, whereas PostgreSQL will time out write operations as well.
### dbTimeoutLock
| Type | Default |
|----------|---------|
| interval | `60.0` |
The number of seconds to wait before returning a timeout error when acquiring database locks. The special value `null` waits the maximum amount of time, while `0.0` waits the minimum amount of time. The minimums are maximums for each backend are as follows:
| Backend | Minimum | Maximum |
|------------|----------------|-----------------------|
| SQLite 3 | 0 milliseconds | at least 24 days |
| PostgreSQL | 1 millisecond | forever |
| MySQL | 1 second | approximately 1 year |
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
### dbSQLite3File
| Type | Default |
|----------------|---------|
| string or null | `null` |
The full path and file name of SQLite database. The special value `null` evaluates to a file named `"arsse.db"` in the directory where The Arsse is installed.
### dbSQLite3Key
| Type | Default |
|--------|---------|
| string | `""` |
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
### dbPostgreSQLHost
| Type | Default |
|--------|---------|
| string | `""` |
The host name, address, or socket path of the PostgreSQL database server.
Consult [PostgreSQL's documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-HOST) for more details.
### dbPostgreSQLUser
| Type | Default |
|--------|-----------|
| string | `"arsse"` |
The log-in user name for the PostgreSQL database server.
### dbPostgreSQLPass
| Type | Default |
|--------|---------|
| string | `""` |
The log-in password for the PostgreSQL database server.
### dbPostgreSQLPort
| Type | Default |
|---------|---------|
| integer | `5432` |
The TCP port on which to connect to the PostgreSQL database server, if connecting via TCP.
### dbPostgreSQLDb
| Type | Default |
|--------|-----------|
| string | `"arsse"` |
The name of the database used by The Arsse on the PostgreSQL database server.
### dbPostgreSQLSchema
| Type | Default |
|--------|---------|
| string | `""` |
The name of the schema used by The Arsse on the PostgreSQL database server. When not set to the empty string, the PostgreSQL search path is modified to consist of the specified schema with a fallback to the public schema.
Consult [PostgreSQL's documentation](https://www.postgresql.org/docs/current/ddl-schemas.html) for more details.
### dbPostgreSQLService
| Type | Default |
|--------|---------|
| string | `""` |
A PostgreSQL service file entry to use *instead of* the above configuration; if using a service entry all above PostgreSQL-specific parameters except schema are ignored.
Consult [PostgreSQL's documentation](https://www.postgresql.org/docs/current/libpq-pgservice.html) for more details.
## Database settings specific to MySQL
### dbMySQLHost
| Type | Default |
|--------|---------------|
| string | `"localhost"` |
The host name or address of the MySQL database server. The values `"localhost"` and `"."` are special.
Consult [MySQL's documentation](https://dev.mysql.com/doc/refman/8.0/en/connecting.html) for more details.
### dbMySQLUser
| Type | Default |
|--------|-----------|
| string | `"arsse"` |
The log-in user name for the MySQL database server.
### dbMySQLPass
| Type | Default |
|--------|---------|
| string | `""` |
The log-in password for the MySQL database server.
### dbMySQLPort
| Type | Default |
|---------|---------|
| integer | `3306` |
The TCP port on which to connect to the MySQL database server, if connecting via TCP.
### dbMySQLDb
| Type | Default |
|--------|-----------|
| string | `"arsse"` |
The name of the database used by The Arsse on the MySQL database server.
### dbMySQLSocket
| Type | Default |
|--------|---------|
| string | `""` |
A Unix domain socket or named pipe to use for the MySQL database server when not connecting via TCP.
## User management settings
### userDriver
| Type | Default |
|--------|--------------|
| string | `"internal"` |
The user management driver to use. Currently only `"internal"` is available, which stores user IDs and hashed passwords in the configured database.
It is also possible to specify the fully-qualified name of a class which implements the user management driver interface. For example, specifying `"JKingWeb\Arsse\User\Internal\Driver"` would use the internal driver.
### userPreAuth
| Type | Default |
|---------|---------|
| boolean | `false` |
Whether users are authenticated by the Web server before requests are passed to The Arsse. If set to `true` The Arsse will perform no HTTP-level authentication and assume that the user ID supplied in either the `REMOTE_USER` CGI variable or the `Authorization` HTTP header-field (if `Basic` authentication was used) is authentic.
For synchronization protocols which implement their own authentication (such as Tiny Tiny RSS), this setting may or may not affect how protocol-level authentication is handled; consult the section on The Arsse's [supported protocols](/en/Supported_Protocols) for more information.
If the user has not previously logged in, an entry is created for them in the database automatically. If the Web server uses `Basic` HTTP authentication and passes along the `Authorization` field, a hash of the user's password will also be stored in The Arsse's database.
### userHTTPAuthRequired
| Type | Default |
|---------|---------|
| boolean | `false` |
Whether to require successful HTTP authentication before processing API-level authentication, for protocol which implement their own authentication.
### userSessionEnforced
| Type | Default |
|---------|---------|
| boolean | `true` |
Whether invalid or expired API session tokens should prevent logging in when HTTP authentication is used, for protocol which implement their own authentication.
### userSessionTimeout
| Type | Default |
|----------|-----------|
| interval | `"PT24H"` |
The period of inactivity after which log-in sessions should be considered invalid. Session timeouts should not be made too long, to guard against session hijacking.
### userSessionLifetime
| Type | Default |
|----------|-----------|
| interval | `"P7D"` |
The maximum lifetime of log-in sessions regardless of recent activity. Session lifetimes should not be made too long, to guard against session hijacking.
### userTempPasswordLength
| Type | Default |
|---------|---------|
| integer | `20` |
The desired length in characters of randomly-generated user passwords. When [adding users](/en/Using_The_Arsse/Managing_Users), omitting a desired password generates a random one; this setting controls the length of these passwords.
## Newsfeed fetching service settings
### serviceDriver
| Type | Default |
|--------|----------------|
| string | `"subprocess"` |
The newsfeed fetching service driver to use. The following values are understood:
- `"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.
### serviceFrequency
| Type | Default |
|----------|----------|
| interval | `"PT2M"` |
The interval the newsfeed fetching service observes between checks for new articles. Note that requests to foreign servers are not necessarily made at this frequency: each newsfeed is assigned its own time at which to be next retrieved. This setting instead defines the length of time the fetching service will sleep between periods of activity.
Consult "[How Often Newsfeeds Are Fetched](/en/Using_The_Arsse/Keeping_Newsfeeds_Up_to_Date#page_Appendix-How-Often-Newsfeeds-Are-Fetched)" for details on how often newsfeeds are fetched.
### serviceQueueWidth
| Type | Default |
|---------|---------|
| integer | `5` |
The maximum number of concurrent newsfeed updates to perform, if a concurrent service driver is used.
### fetchTimeout
| Type | Default |
|----------|---------|
| interval | `10.0` |
The maximum number of seconds to wait for data when fetching newsfeeds from foreign servers.
### fetchSizeLimit
| Type | Default |
|---------|-------------------|
| integer | `2 * 1024 * 1024` |
The maximum size, in bytes, of data to accept when fetching a newsfeed. Newsfeeds larger than this will be rejected to guard against denial-of-servioce attacks.
The default value is equal to two megabytes.
### fetchEnableScraping
| Type | Default |
|---------|---------|
| boolean | `true` |
Whether to allow the possibility of fetching full article contents from an article's source, if a newsfeed only provides excerpts. Whether fetching will actually happen is governed by a per-newsfeed toggle (defaulting to `false`) which currently can only be changed by manually editing the database.
### fetchUserAgentString
| Type | Default |
|----------------|---------|
| string or null | `null` |
The [user agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) The Arsse will identify as when fetching newsfeeds. The special value null will use an identifier similar to the following:
```
Arsse/0.6.0 (Linux 4.15.0; x86_64; https://thearsse.com/)
```
## Housekeeping settings
### purgeFeeds
| Type | Default |
|------------------|-----------|
| interval or null | `"PT24H"` |
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 newsfeeds are still subject to the `purgeArticleUnread` threshold below.
### purgeArticlesRead
| Type | Default |
|------------------|---------|
| interval or null | `"P7D"` |
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.
This setting also governs when an article is hidden from a user after being read by that user, regardless of its actual presence in the database.
### purgeArticlesUnread
| Type | Default |
|------------------|----------|
| interval or null | `"P21D"` |
How long to keep a an article in the database regardless of whether any users have read it. Specifying `null` will retain articles forever, 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.
# Obsolete settings
### dbSQLite3Timeout
| Type | Historical Default |
|----------|--------------------|
| interval | `60.0` |
*This setting has been replaced by [dbTimeoutLock](#page_dbTimeoutLock).*
The number of seconds for SQLite to wait before returning a timeout error when trying to acquire a write lock on the database file. Setting this to a low value may cause operations to fail with an error.
Consult [SQLite's documentation](https://sqlite.org/c3ref/busy_timeout.html) for more details.

3
docs/en/020_Getting_Started/index.md Normal file
View file

@ -0,0 +1,3 @@
Presently installing and setting up The Arsse is a manual process. We hope to have pre-configured installation packages available for various operating systems eventually, but for now the pages in this section should help get you up and running.
Though The Arsse itself makes no assumptions about the operating system which hosts it, we use and have the most experience with Debian; the instructions contained here therefore are for Debian systems will will probably either not work with other systems or not be consistent with their conventions. Nevertheless, they should still serve as a useful guide.

55
docs/en/025_Using_The_Arsse/010_Managing_Users.md Normal file
View file

@ -0,0 +1,55 @@
[TOC]
# Preface
This section describes in brief some CLI commands. Please read [the general notes on the command line interface](index) before continuing.
# Adding users
When first installed, The Arsse has no users configured. You may add users by executing the following command:
```sh
sudo -u www-data php arsse.php user add "user@example.com" "example password"
```
The password argument is optional: if no password is provided, a random one is generated and printed out:
```console
$ sudo -u www-data php arsse.php user add "jane.doe"
Ji0ivMYqi6gKxQK1MHuE
```
# Setting and changing passwords
Setting's a user's password is practically identical to adding a password:
```sh
sudo -u www-data php arsse.php user set-pass "user@example.com" "new password"
```
As when adding a user, the password argument is optional: if no password is provided, a random one is generated and printed out:
```console
$ sudo -u www-data php arsse.php user set-pass "jane.doe"
Ummn173XjbJT4J3Gnx0a
```
## Setting and changing passwords for Fever
Before a user can make use of [the Fever protocol](/en/Supported_Protocols/Fever), a Fever-specific password for that user must be set. It is _highly recommended_ that this not be the samer as the user's main password. The password can be set by adding the `--fever` option to the normal password-changing command:
```sh
sudo -u www-data php arsse.php user set-pass --fever "user@example.com" "fever password"
```
As when setting a main password, the password argument is optional: if no password is provided, a random one is generated and printed out:
```console
$ sudo -u www-data php arsse.php user set-pass --fever "jane.doe"
YfZJHq4fNTRUKDYhzQdR
```

54
docs/en/025_Using_The_Arsse/020_Importing_and_Exporting.md Normal file
View file

@ -0,0 +1,54 @@
[TOC]
# Preface
This section describes in brief some CLI commands. Please read [the general notes on the command line interface](index) before continuing.
# Importing newsfeeds from OPML
It's possible to import not only newsfeeds but also folders and Fever groups using OPML files. The process is simple:
```sh
sudo -u www-data php arsse.php import "user@example.com" "subscriptions.opml"
```
The importer is forgiving, but some OPML files may fail, with the reason printed out. Files are either imported in total, or not at all.
# Exporting newsfeeds to OPML
It's possible to export not only newsfeeds but also folders and Fever groups to OPML files. The process is simple:
```sh
sudo -u www-data php arsse.php export "user@example.com" "subscriptions.opml"
```
The output might look like this:
```xml
<opml version="2.0">
<head/>
<body>
<outline text="Folder">
<outline text="Subfolder">
<outline type="rss" text="Feed 1" xmlUrl="http://example.com/feed1"/>
</outline>
<outline type="rss" text="Feed 2" xmlUrl="http://example.com/feed2" category="group 1,group 2"/>
<outline type="rss" text="Feed 3" xmlUrl="http://example.com/feed3" category="group 1"/>
</outline>
<outline type="rss" text="Feed 4" xmlUrl="http://example.com/feed4" category="group 2,group 3"/>
</body>
</opml>
```
# Managing newsfeeds via OPML
Not all protocols supported by The Arsse allow modifying newsfeeds or folders, et cetera; additionally, not all clients support these capabilities even if the protocol has the necessary features. An OPML export/import sequence with the `--replace` import option specified, however, makes any kind of modification possible. For example:
```sh
# export your newsfeeds
sudo -u www-data php arsse.php export "user@example.com" "subscriptions.opml"
# make any changes you want in your editor of choice
nano "subscriptions.opml"
# re-import the modified information
sudo -u www-data php arsse.php import "user@example.com" "subscriptions.opml" --replace
```

49
docs/en/025_Using_The_Arsse/030_Keeping_Newsfeeds_Up_to_Date.md Normal file
View file

@ -0,0 +1,49 @@
[TOC]
# Preface
In normal operation The Arsse is expected to regularly check whether newsfeeds might have new articles, then fetch them and process them to present new or updated articles to clients. This can be achieved either by having The Arsse operate a persistent background process (termed a [daemon](https://en.wikipedia.org/wiki/Daemon_(computing)) or service), or by using an external scheduler to periodically perform single checks. Normally a daemon is preferred.
There are many ways to administer daemons, and many schedulers can be used. This section outlines a few, but many other arrangements are possible.
# As a daemon via systemd
The Arsse includes a sample systemd service unit file which can be used to quickly get a daemon running with the following procedure:
```sh
# Copy the service unit
sudo cp "/usr/share/arsse/dist/arsse.service" "/etc/systemd/system"
# Modify the unit file if needed
sudoedit "/etc/systemd/system/arsse.service"
# Enable and start the service
sudo systemctl enable --now arsse
```
The Arsse's feed updater can then be manipulated as with any other service. Consult [the `systemctl` manual](https://www.freedesktop.org/software/systemd/man/systemctl.html) for details.
# As a cron job
Keeping newsfeeds updated with [cron](https://en.wikipedia.org/wiki/Cron) is not difficult. Simply run the following command:
```sh
sudo crontab -u www-data -e
```
And add a line such as this one:
```cron
*/2 * * * * /usr/bin/env php /usr/share/arsse/arsse.php refresh-all
```
Thereafter The Arsse's will be scheduled to check newsfeeds every two minutes. Consult the manual pages for the `crontab` [format](http://man7.org/linux/man-pages/man5/crontab.5.html) and [command](http://man7.org/linux/man-pages/man1/crontab.1.html) for details.
# Appendix: how often newsfeeds are fetched
Though by default The Arsse will wake up every two minutes, newsfeeds are not actually downloaded so frequently. Instead, each newsfeed is assigned a time at which it should next be fetched, and once that time is reached a [conditional request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests) is made. The interval between requests for a particular newsfeed can vary from 15 minutes to 24 hours based on multiple factors such as:
- The length of time since the newsfeed last changed
- The interval between publishing of articles in the newsfeed
- Whether the last fetch or last several fetches resulted in error
As a general rule, newsfeeds which changed frequently are checked frequently, and those which change seldom are fetched at most daily.

12
docs/en/025_Using_The_Arsse/040_Upgrading_to_a_New_Version.md Normal file
View file

@ -0,0 +1,12 @@
Upgrading The Arsse is usually simple:
1. Download the latest release
2. Check the `UPGRADING` file for any special notes
3. Stop the newsfeed refreshing service if it is running
4. Extract the new version on top of the old one
5. Ensure permissions are still correct
6. Restart the newsfeed refreshing service
By default The Arsse will perform any required database schema upgrades when the new version is executed, and release packages contain all newly required library dependencies.
Occasionally changes to Web server configuration have been required, when new protocols become supported; such changes are always explicit in the `UPGRADING` file

20
docs/en/025_Using_The_Arsse/index.md Normal file
View file

@ -0,0 +1,20 @@
# Preface
This section details a few administrative tasks which may need to be performed after installing The Arsse. As no Web-based administrative interface is included, these tasks are generally performed via command line interface.
Though this section describes some commands briefly, complete documentation of The Arsse's command line interface is not included in this manual. Documentation for CLI commands can instead be viewed with the CLI itself by executing `php arsse.php --help`.
# A Note on Command Invocation
Particularly if using an SQLite database, it's important that administrative commands be executed as the same user who owns The Arsse's files. To that end the examples in this section all use the verbose formulation `sudo -u www-data php arsse.php` (with `www-data` being the user under which Web servers run in Debian), but it is possible to simplify invocation to `sudo arsse` if an executable file named `arsse` is created somewhere in the sudo path with the following content:
```php
#! /usr/bin/env php
<?php
if (posix_geteuid() == 0) {
$info = posix_getpwnam("www-data");
posix_setegid($info['gid']);
posix_seteuid($info['uid']);
}
include "/usr/share/arsse/arsse.php";
```

39
docs/en/030_Supported_Protocols/010_NextCloud_News.md Normal file
View file

@ -0,0 +1,39 @@
[TOC]
# About
<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>
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.
# 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 newsfeeds are placed into nested folders, they simply appear in the top-level folder when accessed via the NextCloud News protocol.

95
docs/en/030_Supported_Protocols/020_Tiny_Tiny_RSS.md Normal file
View file

@ -0,0 +1,95 @@
[TOC]
# About
<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://git.tt-rss.org/fox/tt-rss/wiki/SearchSyntax">search syntax</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>
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 an odd patchwork subset of Tiny Tiny RSS' full capabilities. The FeedReader extensions round out the protocol with significantly more features. Unlike with TT-RSS itself, API access is always enabled with The Arsse.
# 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 `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
- Processing of the `search` parameter of the `getHeadlines` operation differs in the following ways:
- Values other than `"true"` or `"false"` for the `unread`, `star`, and `pub` special keywords treat the entire token as a search term rather than as `"false"`
- Invalid dates are ignored rather than assumed to be `"1970-01-01"`
- Only a single negative date is allowed (this is a known bug rather than intentional)
- Dates are always relative to UTC
- Full-text search is not yet employed with any database, including PostgreSQL
- 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 `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
- Analogous to multi-user mode
- If the `userHTTPAuthRequired` setting is `true`:
- Clients must pass HTTP authentication
- API authentication proceeds as normal
- Feed icons are visible only to their owners
- Analoguous to multi-user mode with additional HTTP authentication
- 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
- Analogous to single-user mode if using HTTP authentication, and to multi-user mode otherwise
- 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
- Analogous to single-user mode
- 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
- Analoguous to multi-user mode with additional HTTP authentication
- 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
- Analogous to single-user mode
In all cases, supplying invalid HTTP credentials will result in a 401 response.

45
docs/en/030_Supported_Protocols/030_Fever.md Normal file
View file

@ -0,0 +1,45 @@
[TOC]
# About
<dl>
<dt>Supported since</dt>
<dd>0.8.0</dd>
<dt>Base URL</dt>
<dd>/fever/</dd>
<dt>API endpoint</dt>
<dd>/fever/?api</dd>
<dt>Specifications</dt>
<dd><a href="https://web.archive.org/web/20161217042229/https://feedafever.com/api">"Public beta"</a> (at the Internet Archive)</dd>
</dl>
The Fever protocol is a basic protocol which has historically been popular with iOS and macOS clients.
It allows marking articles as read or starred, but does not allow adding or modifying newsfeeds. Moreover, instead of being classified into folders, newfeeds may belong to multiple groups, which do not nest.
# Missing features
The Fever protocol is incomplete, unusual, _and_ a product of proprietary software which is no longer available. Conssequently some features have been omitted either out of necessity or because implementation details made the effort required too great.
- All feeds are considered "Kindling"
- The "Hot Links" feature is not implemented; when requested, an empty array will be returned. As there is no way to classify a feed as a "Spark" in the protocol itself and no documentation exists on how link temperature was calculated, an implementation is unlikely to appear in the future
- Favicons are not currently supported; all feeds have a simple blank image as their favicon unless the client finds the icons itself
# Special considerations
- Because of Fever's unusual and insecure authentication scheme, a Fever-specific password [must be created](/en/Using_The_Arsse/Managing_Users) before a user can communicate via the Fever protocol
- The Fever protocol does not allow for adding or modifying feeds. Another protocol or OPML importing must be used to manage feeds
- Unlike other protocols supported by The Arsse, Fever uses "groups" (more commonly known as tags or labels) instead of folders to organize feeds. Currently [OPML importing](/en/Using_The_Arsse/Importing_and_Exporting) is the only means of managing groups
# Other notes
- The undocumented `group_ids`, `feed_ids`, and `as=unread` parameters are all supported
- XML output is supported, but may not behave as Fever did. Its use by clients is discouraged
# Interaction with HTTP Authentication
We are not aware of any Fever clients which respond to HTTP authentication challenges. If the Web server or The Arsse is configured to require successful HTTP authentication, Fever clients are not likely to be able to connect properly.
# Interaction with Folders
Unlike other protocols supported by The Arsse, Fever uses "groups" (more commonly known as tags or labels) to organize newsfeeds. These are fully supported and are exposed as categories in OPML import and export. They are treated separately from folders.

7
docs/en/030_Supported_Protocols/index.md Normal file
View file

@ -0,0 +1,7 @@
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)
- [Fever](Fever)
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, however, sometimes the interactions between them are not obvious. These interactions are documented here when warranted.

258
docs/en/040_Compatible_Clients.md Normal file
View file

@ -0,0 +1,258 @@
The Arsse does not at this time have any first party clients. However, because The Arsse [supports existing protocols](/en/Supported_Protocols), most clients built for these protocols are compatible with The Arsse. Below are those that we personally know of and have tested with The Arsse.
<table class="clients">
<thead>
<tr>
<th rowspan="2">Name</th>
<th rowspan="2">OS</th>
<th colspan="3">Protocol</th>
<th rowspan="2">Notes</th>
</tr>
<tr>
<th>Nextcloud News</th>
<th>Tiny Tiny RSS</th>
<th>Fever</th>
</tr>
</thead>
<tbody>
<tr>
<th colspan="6">Desktop</th>
</tr>
<tr>
<td><a href="https://jangernert.github.io/FeedReader/">FeedReader</a></td>
<td>Linux</td>
<td class="Y">✔</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p>Excellent reader; one of the best on any platform.</p>
<p>Not compatible with HTTP authentication when using TT-RSS.</p>
</td>
</tr>
<tr>
<td><a href="https://lzone.de/liferea/">Liferea</a></td>
<td>Linux</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p>Not compatible with HTTP authentication.</p>
</td>
</tr>
<tr>
<td><a href="https://newsboat.org/">Newsboat</a></td>
<td>Linux, macOS</td>
<td class="Y">✔</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p>Terminal-based client.</p>
</td>
</tr>
<tr>
<td><a href="https://apps.apple.com/app/id1449412482">Reeder</a></td>
<td>macOS</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td>
<p>Also available for iOS.</p>
</td>
</tr>
<tr>
<td><a href="https://github.com/martinrotter/rssguard/">RSS Guard</a></td>
<td>Windows, macOS, Linux</td>
<td class="Y">✔</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p>Very basic client; now discontinued.</p>
</td>
</tr>
</tr>
<tr>
<td><a href="https://www.microsoft.com/store/apps/9wzdncrdmbn3">Tiny Tiny RSS Reader</td>
<td>Windows</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p>Does not deal well with expired sessions; discontinued.</p>
</td>
</tr>
</tbody>
<tbody>
<tr>
<th colspan="6">Mobile</th>
</tr>
<tr>
<td><a href="https://peterandlinda.com/cloudnews/">CloudNews</a></td>
<td>iOS</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td>
<p>Very bland looking application, but it functions well.</p>
</td>
</tr>
<tr>
<td><a href="https://play.google.com/store/apps/details?id=com.seazon.feedme">FeedMe</a></td>
<td>Android</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p>Not compatible with HTTP authentication.</p>
</td>
</tr>
<tr>
<td><a href="http://cocoacake.net/apps/fiery/">Fiery Feeds</a></td>
<td>iOS</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td class="Y">✔</td>
<td>
<p>Rentalware - For the software to be usable (you can't even add feeds otherwise) a subscription fee must be paid.</p>
<p>Currently keeps showing items in the unread badge which have already been read.</p>
</td>
</tr>
<tr>
<td><a href="https://github.com/SimonSchubert/NewsOut">Newsout</a></td>
<td>Android, iOS</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td>
<p>iOS version only as source code.</p>
</td>
</tr>
<tr>
<td><a href="https://github.com/nextcloud/news-android/">NextCloud News</a></td>
<td>Android</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td>
<p>Official Android client for NextCloud News.</p>
</td>
</tr>
<tr>
<td><a href="https://github.com/schaal/ocreader/">OCReader</a></td>
<td>Android</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td></td>
</tr>
<tr>
<td><a href="https://play.google.com/store/apps/details?id=com.isaiasmatewos.readably">Readably</a></td>
<td>Android</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td>
<p>Fetches favicons independently.</p>
</td>
</tr>
<tr>
<td><a href="https://apps.apple.com/app/id1449412357">Reeder</a></td>
<td>iOS</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td>
<p>Also available for macOS.</p>
</td>
</tr>
<tr>
<td><a href="http://tt-rss.org/">Tiny Tiny RSS</a></td>
<td>Android</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p>Official Android client for Tiny Tiny RSS.</p>
</td>
</tr>
<tr>
<td><a href="http://github.com/nilsbraden/ttrss-reader-fork/">TTRSS-Reader</a></td>
<td>Android</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p></p>
</td>
</tr>
<tr>
<td><a href="https://apps.apple.com/app/id1252376153">Unread</a></td>
<td>iOS</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td>
<p>Trialware with one-time purchase.</p>
</td>
</tr>
</tbody>
</table>
## Untested clients
<table class="clients">
<thead>
<tr>
<th rowspan="2">Name</th>
<th rowspan="2">OS</th>
<th colspan="3">Protocol</th>
<th rowspan="2">Notes</th>
</tr>
<tr>
<th>Nextcloud News</th>
<th>Tiny Tiny RSS</th>
<th>Fever</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://github.com/jeena/feedthemonkey">FeedTheMonkey</a></td>
<td>Linux</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p></p>
</td>
</tr>
<tr>
<td><a href="https://apps.apple.com/app/id588726889">ReadKit</a></td>
<td>macOS</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td>
<p>Requires purchase. Presumed to work.</p>
</td>
</tr>
<tr>
<td><a href="https://github.com/matoung/SparkReader">SparkReader</a></td>
<td>Windows</td>
<td class="N">✘</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td>
<p>Requires manual configuration.</p>
</td>
</tr>
<tr>
<td><a href="http://www.pluchon.com/en/tiny_reader_rss.php">tiny Reader RSS</a></td>
<td>iOS</td>
<td class="N">✘</td>
<td class="Y">✔</td>
<td class="N">✘</td>
<td>
<p>Does not support HTTP authentication.</p>
</td>
</tr>
</tbody>
</table>

1
docs/index.md Normal file
View file

@ -0,0 +1 @@
Welcome to the user manual for The Advanced RSS Environment. It is included with each copy of the software, and is also [available online](https://thearsse.com/manual/en/). Please select a language above.

2
docs/theme/arsse/arsse.css vendored Normal file
View file

File diff suppressed because one or more lines are too long

10
docs/theme/arsse/config.json vendored Normal file
View file

@ -0,0 +1,10 @@
{
"favicon": "<theme_url>favicon.png",
"js": [
"<theme_url>highlight.pack.js",
"<theme_url>daux.js"
],
"css": [
"<theme_url>arsse.css"
]
}

182
docs/theme/arsse/daux.js vendored Normal file
View file

@ -0,0 +1,182 @@
/** global localStorage, hljs */
if (hljs) {
hljs.initHighlightingOnLoad();
}
(function() {
var codeBlocks = document.querySelectorAll(".s-content pre");
var toggleCodeSection = document.querySelector(".CodeToggler");
if (!toggleCodeSection) {
return;
} else if (!codeBlocks.length) {
toggleCodeSection.classList.add("Hidden");
return;
}
var toggleCodeBlockBtnList = toggleCodeSection.querySelectorAll(".CodeToggler__button");
var toggleCodeBlockBtnSet = toggleCodeSection.querySelector(".CodeToggler__button--main"); // available when floating is disabled
var toggleCodeBlockBtnHide = toggleCodeSection.querySelector(".CodeToggler__button--hide");
var toggleCodeBlockBtnBelow = toggleCodeSection.querySelector(".CodeToggler__button--below");
var toggleCodeBlockBtnFloat = toggleCodeSection.querySelector(".CodeToggler__button--float");
var codeBlockView = document.querySelector(".Columns__right");
var floating = document.body.classList.contains("with-float");
function setCodeBlockStyle(codeBlockState) {
for (var a = 0; a < toggleCodeBlockBtnList.length; a++) {
toggleCodeBlockBtnList[a].classList.remove("Button--active");
}
switch (codeBlockState) {
case true: // Show code blocks below (flowed); checkbox
var hidden = false;
break;
case false: // Hidden code blocks; checkbox
var hidden = true;
break;
case 2: // Show code blocks inline (floated)
toggleCodeBlockBtnFloat.classList.add("Button--active");
codeBlockView.classList.add("Columns__right--float");
codeBlockView.classList.remove("Columns__right--full");
var hidden = false;
break;
case 1: // Show code blocks below (flowed)
case "checked":
toggleCodeBlockBtnBelow.classList.add("Button--active");
codeBlockView.classList.remove("Columns__right--float");
codeBlockView.classList.add("Columns__right--full");
var hidden = false;
break;
case 0: // Hidden code blocks
default:
toggleCodeBlockBtnHide.classList.add("Button--active");
codeBlockView.classList.remove("Columns__right--float");
codeBlockView.classList.add("Columns__right--full");
var hidden = true;
break;
}
for (var a = 0; a < codeBlocks.length; a++) {
if (hidden) {
codeBlocks[a].classList.add("Hidden");
} else {
codeBlocks[a].classList.remove("Hidden");
}
}
try {
localStorage.setItem("codeBlockState", +codeBlockState);
} catch (e) {
// local storage operations can fail with the file:// protocol
}
}
if (!floating) {
toggleCodeBlockBtnSet.addEventListener("change", function(ev) {setCodeBlockStyle(ev.target.checked);}, false);
} else {
toggleCodeBlockBtnHide.addEventListener("click", function() {setCodeBlockStyle(0);}, false);
toggleCodeBlockBtnBelow.addEventListener("click", function() {setCodeBlockStyle(1);}, false);
toggleCodeBlockBtnFloat.addEventListener("click", function() {setCodeBlockStyle(2);}, false);
}
try {
var codeBlockState = localStorage.getItem("codeBlockState");
} catch (e) {
// local storage operations can fail with the file:// protocol
var codeBlockState = null;
}
if (!codeBlockState) {
codeBlockState = floating ? 2 : 1;
} else {
codeBlockState = parseInt(codeBlockState);
}
if (!floating) {
codeBlockState = !!codeBlockState;
}
setCodeBlockStyle(codeBlockState);
})();
(function() {
function debounce(func, wait) {
var timeout;
return function() {
var context = this, args = arguments;
var later = function() {
timeout = null;
};
clearTimeout(timeout);
timeout = setTimeout(later, wait);
};
};
var navItems = document.querySelectorAll('.Nav__item.has-children i.Nav__arrow');
function _toggleSubMenu(ev) {
if (ev.preventDefault !== undefined) {
ev.preventDefault();
}
var parent = ev.target.parentNode.parentNode;
var subNav = parent.querySelector('ul.Nav');
if (ev.preventDefault !== undefined && parent.classList.contains('Nav__item--open')) {
// Temporarily set the height so the transition can work.
subNav.style.height = subNav.scrollHeight + 'px';
subNav.style.transitionDuration = Math.max(subNav.scrollHeight, 150) + 'ms';
subNav.style.height = '0px';
parent.classList.remove('Nav__item--open');
} else {
if (ev.preventDefault !== undefined) {
subNav.style.transitionDuration = Math.max(subNav.scrollHeight, 150) + 'ms';
// After the transition finishes set the height to auto so child
// menus can expand properly.
subNav.addEventListener('transitionend', _setHeightToAuto);
subNav.style.height = subNav.scrollHeight + 'px';
parent.classList.add('Nav__item--open');
} else {
// When running at page load the transitions don't need to fire and
// the classList doesn't need to be altered.
subNav.style.height = 'auto';
}
}
}
function _setHeightToAuto(ev) {
if (ev.target.style.height !== '0px') {
ev.target.style.height = 'auto';
}
ev.target.removeEventListener('transitionend', _setHeightToAuto);
}
// Go in reverse here because on page load the child nav items need to be
// opened first before their parents so the height on the parents can be
// calculated properly.
for (var i = navItems.length - 1, cur; i >= 0; i--) {
cur = navItems[i];
cur.addEventListener('click', _toggleSubMenu);
if (cur.parentNode.parentNode.classList.contains('Nav__item--open')) {
_toggleSubMenu({ target: cur });
}
}
})();
(function() {
var trigger = document.querySelector('.Collapsible__trigger');
if (!trigger) {
return;
}
content = document.querySelector('.Collapsible__content');
trigger.addEventListener('click', function(ev) {
if (content.classList.contains('Collapsible__content--open')) {
content.style.height = 0;
content.classList.remove('Collapsible__content--open');
} else {
content.style.transitionDuration = Math.max(content.scrollHeight, 150) + 'ms';
content.style.height = content.scrollHeight + 'px';
content.classList.add('Collapsible__content--open');
}
});
})();

BIN
docs/theme/arsse/fonts/cabin-bold.woff vendored Executable file
View file

Binary file not shown.

BIN
docs/theme/arsse/fonts/cabin-bold.woff2 vendored Executable file
View file

Binary file not shown.

BIN
docs/theme/arsse/fonts/cabin-italic.woff vendored Executable file
View file

Binary file not shown.

BIN
docs/theme/arsse/fonts/cabin-italic.woff2 vendored Executable file
View file

Binary file not shown.

BIN
docs/theme/arsse/fonts/cabin-regular.woff vendored Executable file
View file

Binary file not shown.

BIN
docs/theme/arsse/fonts/cabin-regular.woff2 vendored Executable file
View file

Binary file not shown.

BIN
docs/theme/arsse/fonts/leaguegothic.woff vendored Normal file
View file

Binary file not shown.

BIN
docs/theme/arsse/fonts/leaguegothic.woff2 vendored Normal file
View file

Binary file not shown.

2
docs/theme/arsse/highlight.pack.js vendored Normal file
View file

File diff suppressed because one or more lines are too long

328
docs/theme/src/arsse.scss vendored Normal file
View file

@ -0,0 +1,328 @@
/* Daux imports; fonts are omitted */
@import "../../../vendor-bin/daux/vendor/daux/daux.io/themes/daux/scss/vendor/normalize.scss";
@import "../../../vendor-bin/daux/vendor/daux/daux.io/themes/daux/scss/_variables.scss";
@import "../../../vendor-bin/daux/vendor/daux/daux.io/themes/daux/scss/_mixins.scss";
@import "../../../vendor-bin/daux/vendor/daux/daux.io/themes/daux/scss/_structure.scss";
@import "../../../vendor-bin/daux/vendor/daux/daux.io/themes/daux/scss/_typography.scss";
@import "../../../vendor-bin/daux/vendor/daux/daux.io/themes/daux/scss/_components.scss";
@import "../../../vendor-bin/daux/vendor/daux/daux.io/themes/daux/scss/_homepage.scss";
@import "../../../vendor-bin/daux/vendor/daux/daux.io/themes/daux/scss/_print.scss" print;
/* The Arsse overrides */
@font-face {
font-family: 'League Gothic';
src: url('fonts/leaguegothic.woff2') format('woff2'),
url('fonts/leaguegothic.woff') format('woff');
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Cabin';
src: url('fonts/cabin-regular.woff2') format('woff2'),
url('fonts/cabin-regular.woff') format('woff');
font-weight: normal;
font-style: normal;
font-display: swap;
}
@font-face {
font-family: 'Cabin';
src: url('fonts/cabin-italic.woff2') format('woff2'),
url('fonts/cabin-italic.woff') format('woff');
font-style: italic;
font-display: swap;
}
@font-face {
font-family: 'Cabin';
src: url('fonts/cabin-bold.woff2') format('woff2'),
url('fonts/cabin-bold.woff') format('woff');
font-weight: bold;
font-style: normal;
font-display: swap;
}
:root {
--font-family-text: "Cabin", "Trebuchet MS", -apple-system, ".SFNSText-Regular", "San Francisco",
"Roboto", "Segoe UI", "Helvetica Neue", "Lucida Grande", Arial,
sans-serif;
--font-family-monospace: Monaco, Menlo, Consolas, "Lucida Console",
"Courier New", monospace;
--font-family-heading: "League Gothic", -apple-system, ".SFNSText-Regular", "San Francisco",
"Roboto", "Segoe UI", "Helvetica Neue", "Lucida Grande", Arial,
sans-serif;
--type-size-1: 4rem;
--type-size-2: 3.236rem;
--type-size-3: 2.618rem;
--type-size-4: 2rem;
--type-size-5: 1.618rem;
--type-size-6: 1.309rem;
--red: #e63c2f;
--blue: #15284b;
--light-blue: #93b7bb;
--beige: #e8d5d3;
--green: #2c9a42;
--dark-gray: color(var(--beige) blend(var(--blue) 50%));
--gray: color(var(--beige) blend(var(--blue) 25%));
--light-gray: color(var(--beige) blend(var(--blue) 12.5%));
--lighter-gray: var(--beige);
--lightest-gray: color(var(--beige) blend(#fff 75%));
--dark: var(--blue);
--light: var(--light-blue);
--sidebar-background: var(--beige);
--sidebar-link-active-background: var(--light-blue);
--sidebar-collapsible--hamburger-color: var(--beige);
--text: var(--blue);
--link-color: var(--red);
--brand-color: var(--blue);
--brand-background: var(--red);
--code-tag-background-color: var(--lightest-gray);
--code-tag-border-radius: 0;
--code-tag-box-shadow: none;
--homepage-navbar-background: var(--red);
--hero-button-block-background: var(--beige);
--homepage-hero-background: #fff;
--content-floating-blocks-background: var(--blue);
}
body {
line-height: 1.618;
}
a.Link--external::after {
content: '';
}
.s-content {
code {
display: inline-block;
padding-top: 0;
padding-bottom: 0;
padding: 0.5ch;
border: 0;
&::before, &::after {
content: '';
}
pre & {
display: inline;
}
}
table {
border-collapse: separate;
border-spacing: 2px;
border: 2px solid var(--gray);
thead, tbody {
background-color: #fff;
}
tr {
border-top: 0;
&:nth-child(2n) {
background-color: transparent;
td {
background-color: var(--lightest-gray);
}
}
}
th, td {
border: 0;
}
}
}
.s-content table, .Nav__item .Nav__item {
font-size: 1rem;
}
.Brand, h1, h2, h3, h4, h5, h6 {
font-weight: normal;
}
.Button {
border-radius: 0;
}
.HomepageButtons .Button--hero {
font-weight: normal;
font-size: var(--type-size-6);
}
.Page__header {
border-bottom: 2px solid var(--lighter-gray);
}
.Pager li > a {
border: 2px solid var(--lighter-gray);
border-radius: 0;
&:hover, &:focus {
background-color: var(--lighter-gray);
}
}
.Pager--prev a::before {
content: "\2190\00a0";
}
.Pager--next a::after {
content: "\00a0\2192";
}
.Navbar {
height: auto;
box-shadow: none;
.Brand {
float: none;
line-height: inherit;
height: auto;
}
}
.Homepage {
padding-top: 10px !important;
}
.Nav__item {
font-size: var(--type-size-6);
}
.Nav__arrow:before, .Nav .Nav .Nav__item a .Nav__arrow:before {
font-family: var(--font-family-heading);
width: 1ch;
height: 1ch;
}
.TableOfContentsContainer__title {
border-bottom: 4px solid var(--lighter-gray);
}
ul.TableOfContents {
border-left: 6px solid var(--lighter-gray);
}
.Columns__right--full .TableOfContentsContainer {
.TableOfContentsContainer__content > .TableOfContents {
border-right: 2px solid var(--lighter-gray);
}
a {
border-bottom: 1px solid var(--lighter-gray);
}
}
.clients {
thead tr:first-child th {
text-align: left;
&:first-child {
width: 15%;
}
&:nth-child(3) {
width: 50%;
text-align: center;
}
}
thead tr + tr th {
width: 16.66%;
text-align: center;
}
tbody td {
&:nth-child(3), &:nth-child(4), &:nth-child(5) {
text-align: center;
}
&.Y {
color: var(--green);
}
&.N {
color: var(--red);
}
}
}
.hljs, .s-content pre {
background: var(--blue);
color: var(--beige);
}
.hljs {
display: block;
overflow-x: auto;
padding: 0.5em;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}
.hljs-comment, .hljs-quote {
color: #978e9c;
}
/* Green */
.hljs-keyword, .hljs-selector-tag, .hljs-addition {
color: #acb39a;
}
/* Cyan */
.hljs-number, .hljs-string, .hljs-meta .hljs-meta-string, .hljs-literal, .hljs-doctag, .hljs-regexp {
color: var(--light-blue);
}
/* Blue */
.hljs-title, .hljs-section, .hljs-name, .hljs-selector-id, .hljs-selector-class {
color: #82b7e5;
}
/* Yellow */
.hljs-attribute, .hljs-attr, .hljs-variable, .hljs-template-variable, .hljs-class .hljs-title, .hljs-type {
color: #c5b031;
}
/* Orange */
.hljs-symbol, .hljs-bullet, .hljs-subst, .hljs-meta, .hljs-meta .hljs-keyword, .hljs-selector-attr, .hljs-selector-pseudo, .hljs-link {
color: #ea8031;
}
/* Red */
.hljs-built_in, .hljs-deletion {
color: var(--red);
}
.hljs-formula {
background: #686986;
}
@media (--viewport-large) {
.Columns__left {
border: 0;
}
}

2
lib/CLI.php
View file

@ -99,7 +99,7 @@ Commands:
user auth <username> <password>
Tests logging in as <username> with password <password>. This only checks
that the user's password is currectly recognized; it has no side effects.
that the user's password is correctly recognized; it has no side effects.
The --fever option may be used to test the user's Fever protocol password,
if any.

2
lib/Db/PostgreSQL/Driver.php
View file

@ -42,7 +42,7 @@ class Driver extends \JKingWeb\Arsse\Db\AbstractDriver {
$base = [
'client_encoding' => "UTF8",
'application_name' => "arsse",
'connect_timeout' => (string) ceil(Arsse::$conf->dbTimeoutConnect),
'connect_timeout' => (string) (int) ceil(Arsse::$conf->dbTimeoutConnect),
];
$out = [];
if ($service != "") {

16
package.json Normal file
View file

@ -0,0 +1,16 @@
{
"devDependencies": {
"autoprefixer": "^9.6.1",
"postcss-cli": "^6.1.3",
"postcss-color-function": "^4.1.0",
"postcss-csso": "^3.0.0",
"postcss-custom-media": "^7.0.8",
"postcss-custom-properties": "^9.0.2",
"postcss-discard-comments": "^4.0.2",
"postcss-import": "^12.0.1",
"postcss-media-minmax": "^4.0.0",
"postcss-nested": "^4.1.2",
"postcss-sassy-mixins": "^2.1.0",
"postcss-scss": "^2.0.0"
}
}

17
postcss.config.js Normal file
View file

@ -0,0 +1,17 @@
module.exports = ctx => ({
//map: ctx.options.map,
parser: 'postcss-scss',
//syntax: 'postcss-scss',
plugins: {
'postcss-import': { root: ctx.file.dirname },
'postcss-discard-comments': {},
'postcss-sassy-mixins': {},
'postcss-custom-media': {preserve: false},
'postcss-media-minmax': {},
'postcss-custom-properties': {preserve: false},
'postcss-color-function': {},
'postcss-nested': {},
'autoprefixer': {},
'postcss-csso': {},
}
})

5
robo
View file

@ -1,11 +1,14 @@
#! /bin/sh
base=`dirname "$0"`
roboCommand="$1"
if [ $# -eq 0 ]; then
"$base/vendor/bin/robo"
else
shift
ulimit -n 2048
if [ "$1" = "clean" ]; then
"$base/vendor/bin/robo" "$roboCommand" "$@"
else
"$base/vendor/bin/robo" "$roboCommand" -- "$@"
fi
fi

0
tests/phpunit.xml → tests/phpunit.dist.xml
View file

11
vendor-bin/daux/composer.json Normal file
View file

@ -0,0 +1,11 @@
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/mensbeam/daux.io/"
}
],
"require": {
"daux/daux.io": "dev-sans-jquery"
}
}

1502
vendor-bin/daux/composer.lock generated Normal file
View file

File diff suppressed because it is too large Load diff

2
vendor-bin/robo/composer.json
View file

@ -3,5 +3,7 @@
"consolidation/robo": "^1.1",
"pear/archive_tar": "^1.4",
"symfony/process": "^3.0"
},
"require-dev": {
}
}

2
vendor-bin/robo/composer.lock generated
View file

@ -4,7 +4,7 @@
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "87a37068875d67919f797af9dc08e108",
"content-hash": "d95cf402fed434140db8ae87c3c8bf32",
"packages": [
{
"name": "consolidation/annotated-command",

2246
yarn.lock Normal file
View file

File diff suppressed because it is too large Load diff