NAME

Review::Helper::Server - The review web app.

DESCRIPTION

A PSGI application serving one review file: the static page from the share directory and a JSON API over the review and its repository. Diffs and file contents are read live from the repository (Review::Helper::VCS).

Every request must carry a Host header naming 127.0.0.1, localhost, [::1], or one of allow_hosts (any port, any case, an IPv6 address in any spelling); anything else gets 403. This keeps DNS-rebinding pages out: they reach the server under the attacker's own name.

Without a token (the server listens on loopback only) nothing more is asked: any local user can open the page, which shows whose review it is. With one, a client whose address is loopback still needs nothing; any other needs the token. A request carrying ?token=TOKEN is answered with 303 to /, whatever its path and the rest of its query, setting the rh_token_PORT cookie (HttpOnly, SameSite=Lax, Path=/; PORT is the server's port, so servers on different ports keep separate cookies); later requests carry that cookie. Anything else gets 401 and a short text page saying to open the printed URL. Tokens are compared in constant time. A reverse proxy on this machine reaches the server from loopback, so everyone who can reach the proxy gets in without the token and sees internal error details.

POST requests must have Content-Type: application/json (415 otherwise), and an Origin header, when present, must be http:// plus the Host (403 otherwise). This keeps pages served from other local ports from posting to the API.

Routes

GET  /                    the page (ux/html/index.html in the share directory)
GET  /static/PATH         a file under ux/css, ux/js or ux/html in the share directory
GET  /api/review          the review, an iteration and everything in it
GET  /api/file/ID         a file change and the sections its commit changed
GET  /api/diff/ID         the file's hunks; ?section=ID gives that section's diff
GET  /api/resolution/ID   a merge's conflict resolutions, per file
GET  /api/content/REV/PATH  a file's raw content at a revision
GET  /api/feedback        the feedback export, as review-helper feedback prints it
POST /api/feedback        add feedback: {target, commit, topic, path, section, flag, line, side, body}
POST /api/feedback/ID     edit feedback: {body, status}, either or both
POST /api/request         add a request: {kind, target, commit, topic, path, section, note}
POST /api/flag/ID         mark a flag seen or not: {seen}
POST /api/close           close the review

GET /api/review takes ?iteration=N (default: the latest). The POST routes for feedback and requests accept an optional iteration in the body, also defaulting to the latest; the commit and path given must exist in it, and a section given must be one the commit changed (touched), the only sections the page shows. In a squashed iteration split into topics, every topic's entry has the head's revision: a commit target names its topic, or none for the files not yet in a topic (400 without one otherwise), and a path picks the topic holding it; topic is stored only on a commit target, or a flag target on a whole-commit flag. Bad input gets 400 and {"error": "..."}; unknown ids get 404. A split request must name a file the fill sheet gives a split item: a text file its commit added or changed a line of, not one only renamed or with only its mode changed (400 otherwise). A flag target gives only flag, the note id of a flag of the iteration; the server stores that flag's sentence, commit and path (and topic, for a whole-commit flag) with it, and marks the flag seen by its reviewer.

GET /api/review also gives standard_version, the version of the standard this server implements ("STANDARD_VERSION" in Review::Helper); identity: user (the login name the server runs as), host (the host name), repo (the repository root) and reviewer (see reviewer below), and journal: the iteration's journal entries, oldest first, each with id, kind, path, unit, sentence, detail and created. Each flag carries seen: the reviewers who have seen it, as [{reviewer, at}], oldest first; pending, true while the agent has still to decide on a flag carried onto changed code; and entry, the id of the commit entry it is on (commit is its revision id, which every topic of a squashed iteration shares). Each commit carries its topic, null outside a squashed iteration split into topics. content_kinds gives the kind of each file the page may show whole at a commit that did not change it (a view guide step's, a flag's), as {"REV:PATH": kind}: the kind a file change would get (see Review::Helper::Split), binary for content with a NUL byte in its first 8000 bytes, null when the file is not at that commit, and text when it cannot be read.

New feedback and requests record the server's reviewer. POST /api/feedback/ID edits only feedback that reviewer wrote, or feedback with no reviewer (written before reviewers were recorded); anyone else's gets 403 and {"error": "..."}. There is no route to delete feedback or to edit a request.

POST /api/flag/ID takes seen, true or false: it sets or removes the reviewer's seen mark on flag ID (a mark already there keeps its time). It returns {seen} as above, and 404 for an unknown flag.

Each commit carries resolution, true for a merge with resolutions ("resolution_changes" in Review::Helper::VCS): hand-made conflict resolutions or other changes made in the merge. GET /api/resolution/ID takes a commit id and returns {commit, files}, each file a path, old_path, status, binary and hunks as /api/diff gives them; ID must be a merge in the repository (404 otherwise). When the VCS cannot show them, or the commit is not in the repository, a merge has no resolutions. They are computed once per server and kept, and follow the iteration's path specs.

Each file in GET /api/review also has section_names: name and package of each section the page shows for it (those the commit changed), so the page can tell section feedback it has no card for.

Feedback and request entries use the shape of the feedback export; requests also carry iteration, case_for and case_against. GET /api/review lists them from every iteration, whichever iteration is selected.

A section's diff is Review::Helper::Diff's section_hunks: its whole code and whole documentation, each hunk with a part of code or docs.

In a Perl file, GET /api/file/ID gives each unit whose doc_ranges are POD (each range's first line starts with = and a letter) a doc_html: its documentation lines rendered by Pod::Simple::XHTML, with html targets refused, every link reduced to its text and no element ids, since reviewed POD is untrusted.

File content is served with an image content type by extension, else as text/plain; charset=utf-8 unless they contain a NUL byte. They carry Content-Security-Policy: sandbox so reviewed content never runs as part of the page.

SYNOPSIS

use Review::Helper::Server;

my $server = Review::Helper::Server->new(db_path => $file);
my $app    = $server->to_app;

ATTRIBUTES

$path = $server->db_path()

The review file. Required.

$db = $server->db()

The open Review::Helper::DB. Defaults to opening db_path.

$repo = $server->repo()

The repository holding the review file, a Review::Helper::VCS. Defaults to the one detect finds from db_path.

$dir = $server->share_dir()

The share directory; the page's assets are under its ux directory. Defaults to "share_dir" in Review::Helper::Util.

$who = $server->reviewer()

Who is reviewing, recorded on feedback, requests and seen marks the page writes. Defaults to the REVIEW_HELPER_REVIEWER environment variable, else the repository's user ("user" in Review::Helper::VCS), else the login name, else unknown. A blank value counts as not given.

$hosts = $server->allow_hosts()

Host names and addresses to accept in the Host header besides the loopback ones, as an array ref; IPv6 addresses with or without brackets. Default: none. Review::Helper::CLI::Serve fills it when listening beyond loopback.

$token = $server->token()

The secret that clients other than loopback must present. Default: none, and then every client is let in.

$router = $server->router()

The Router::Simple holding the routes. Built by the constructor.

PUBLIC METHODS

$bool = Review::Helper::Server->is_loopback($addr)

True for a loopback address: 127.0.0.0/8, ::1, or 127.0.0.0/8 mapped into IPv6. False for undef.

$app = $server->to_app()

The PSGI application.

$res = $server->handle($env)

Answer one PSGI request. to_app calls this. An unexpected error is warned to STDERR and answered with a 500 that carries its text only for a loopback client.

$res = $server->page_index($req, $match)
$res = $server->page_static($req, $match)
$res = $server->api_review($req, $match)
$res = $server->api_file($req, $match)
$res = $server->api_diff($req, $match)
$res = $server->api_resolution($req, $match)
$res = $server->api_content($req, $match)
$res = $server->api_feedback_export($req, $match)
$res = $server->api_feedback_add($req, $match)
$res = $server->api_feedback_edit($req, $match)
$res = $server->api_request_add($req, $match)
$res = $server->api_flag($req, $match)
$res = $server->api_close($req, $match)

The route handlers. Each takes the Plack::Request and the router's match and returns a PSGI response. They die with {status, message} on bad input, which handle turns into an error response.

SOURCE

The source code repository for Review-Helper can be found at https://github.com/exodist/Review-Helper.

MAINTAINERS

Chad Granum <exodist7@gmail.com>

AUTHORS

Chad Granum <exodist7@gmail.com>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See https://dev.perl.org/licenses/