Review copy: send the review back to reader with a POST
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
- Domain
- backend-api-design, security
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
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 sendsOrigin: 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/plainor 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-hostnames 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-srcthat 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
- Ships a Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from jzheaux/reader
-
polish
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Maintainers usually reply within 1 day
-
accessibility bug good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
enhancement
Difficulty 3/5 1-2 days Newbie friendliness 55/100
Maintainers usually reply within 1 day
-
enhancement
Difficulty 4/5 3-5 days Newbie friendliness 35/100
Maintainers usually reply within 1 day
-
polish
Difficulty 3/5 1-2 days Newbie friendliness 64/100
Maintainers usually reply within 1 day
Similar issues
-
Radix number block generates NaN after switching a negative or decimal number to binary, octal or hexPossibly taken @matthewalberto claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
mit-cml/appinventor-sources#4246 · 1 comment ·
Maintainers usually reply within 1 day
-
marketing
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
accessibility good first issue languages
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
Maintainers usually reply within 2 days
-
bug help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 78/100