# Comments ## What this builds Comments that can be attached to anything in an app: a task, a document, an order. People write in a small, safe kind of Markdown, reply to each other, mention each other, and fix a typo for a short while after posting. Read `spekkr.inputs.json` first. A comment can be edited for `edit_minutes` minutes. `mentions` decides whether R4 exists and `reactions` whether R8 does. The spec attaches comments to one example record. It needs the app to know who is signed in, and two answers from the app about any record: may this person read it, and may they comment on it. ## Out of scope - Comments from people who are not signed in. - Attachments and images. - Showing new comments without a reload. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Attach to anything - A comment belongs to a subject: a kind of record and its id. - Two functions decide access, `can_read(user, subject)` and `can_comment(user, subject)`. As built, both say yes to members of the example record's workspace. The person's app replaces them. - A person who may not read a subject gets 404 for its comments, as if there were none. Accept when: a person who may read but not comment sees the comments and gets 403 on posting, and one who may not read gets 404 for both. ### R2. Write - A comment is 1 to 10,000 characters after trimming. - The browser sends an id of its own making with each new comment. A second request with the same id creates nothing and answers with the first comment, so a double click or a retry posts once. - A person posts at most 10 comments a minute. Accept when: the same request sent twice leaves one comment, and the eleventh comment in a minute is refused with a message that says when to try again. ### R3. Safe markup - Comments are written in the Markdown listed in `design.md` and stored as written. They are turned into HTML when shown. - Nothing a person writes is passed through as HTML. Tags they type are shown as text. - A link is kept only if it starts with `http://` or `https://`. Every link gets `rel="nofollow noopener"`. - The result contains only the elements and attributes listed in `design.md`. Accept when: every row of the table of cases in `design.md` gives the HTML listed, and a test that feeds 50 known script-injection strings finds no element or attribute outside the list in any result. ### R4. Mentions Only if `mentions` is on. - `@name` mentions the person with that username, by the rules in `design.md`. - Each person mentioned is told once per comment, through one function, `on_mention(comment, user)`. As built it records the mention in a table. - Only a person who may read the subject can be mentioned. A name that belongs to nobody, or to someone who may not read it, is left as plain text, and the two cases look the same. - Editing a comment tells only people the edit newly mentions. Accept when: every row of the table of mention cases in `design.md` passes, and mentioning a person who may not read the subject tells nobody. ### R5. Replies - A comment can be a reply to another comment on the same subject. - Replies go one level deep. A reply to a reply is stored as a reply to the same first comment. - A thread shows its first comment and then its replies, oldest first. Threads are shown oldest first, 50 at a time, with a cursor. Accept when: a reply to a reply sits beside it, not under it, and the cursor returns every thread once. ### R6. Edit - The author can edit a comment for `edit_minutes` minutes after posting it. After that the text is fixed. - An edited comment says "edited". The text before each edit is kept, and administrators can read it. Accept when: an edit one second before the limit is saved and one second after is refused. ### R7. Delete - The author can delete their own comment at any time. An administrator can delete any. - A deleted comment with replies stays in place as "This comment was deleted", without its text or its author's name. One without replies disappears. - Deleted text is removed from the database after 30 days. Accept when: a deleted comment's text is in no answer from the API, and its replies are still shown. ### R8. Reactions Only if `reactions` is on. - A person can add each of a fixed set of six symbols to a comment once, and take it back. - A comment shows each symbol that was added with a count, and whether this person added it. Accept when: adding the same symbol twice counts once, and a symbol outside the set is refused. ### R9. On the page - A list of threads, a box to write in with a preview, and reply, edit and delete on each comment where the person may. - A new comment appears at once and is taken back with a message if saving fails. - Times are shown as "5 minutes ago" with the exact time available. Accept when: the page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. - A README explains how to attach comments to another record, how to replace the two access functions and `on_mention`, and how to run the tests.