Review copy: send the review back to reader with a POST

Open
#69 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
javascript

Research direction

Read issues #20, #40, #68 and the existing API and review import flow to understand how copies, review payloads, and host access work. The issue outlines a capability token, a restricted POST endpoint, limits, fallback behavior, and landing options, but leaves key design questions open. First agree on those choices and endpoint boundaries; done means a review can be submitted safely for an open copy and falls back to download when the reader cannot be reached.

Written by the indexing model from the issue text.

Description

enhancement P3

A case of #20: the review copy (#68) sends itself back to the writer's reader, with nothing for the reviewer to download or attach.

Idea

When the writer's reader can be reached by the reviewer (--host behind Tailscale, say: #40), the review copy's Send back button POSTs the review to it. The reviewer clicks once and they're done. The review lands in the writer's folder as story.<reviewer>.md, as an imported .review file would.

The server knows at export whether it is serving beyond localhost, so it builds the button with its URL then. It can't know whether the reviewer's network will reach it, so the button tries the POST and falls back to the download (#68) when it can't connect, telling the reviewer which happened.

The payload

Exactly what #68's .review file holds: the asides, their anchors and the copy's id. It's never the document. The server puts it through the same importReview() check as a file imported by hand. A POST is trusted no more than a file.

A door of its own

Today's API trusts its caller to read and write any file in the folder. The review endpoint is a separate, narrow door that can do one thing: accept a review for a copy that is still open.

  • A capability per copy. Export puts an unguessable token in the page, tied to that copy and its reviewer. It works once, or until the writer closes the copy, and the writer can revoke it.
  • Not the Origin. A page opened from disk sends Origin: null, so allowing that allows every local file. CORS is opened for this one endpoint only. The token is what authorizes; the origin is at most a sanity check.
  • No preflight. A text/plain or form POST is a simple request, so it works from a file without a CORS preflight.
  • Limits. The existing 413 for oversized bodies, a small cap on the number of asides, and a rate limit per token and per address.
  • The host check. --allow-host names that let the reviewer in reach this endpoint, and nothing else in the app.
  • The page's policy. #68's "no network" becomes a connect-src that allows this one URL.

Landing

A review never writes into story.md. It arrives as story.<reviewer>.md, or in an inbox of reviews, and the writer chooses to bring it in (#27). If a copy's HTML is forwarded and its token used by someone else, the worst it does is leave an unwanted review in that pile.

The writer should see that one came in: a badge on the file's row, perhaps.

Questions

  • One review per copy, or can the reviewer send again, replacing what they sent?
  • Should the reviewer see a receipt (how many asides arrived), and the writer a record of what came in when?
  • Is the token enough on a tailnet, or should the endpoint also check Tailscale's identity headers when they're present?
Dominant language
JavaScript
Stars
0
Forks
1
Avg merge
2d 4h
Merged PRs (30d)
26

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from jzheaux/reader

All issues in jzheaux/reader

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.