diff --git a/docs/assignment-feedback.md b/docs/assignment-feedback.md index 2c211f4..c70e142 100644 --- a/docs/assignment-feedback.md +++ b/docs/assignment-feedback.md @@ -16,7 +16,7 @@ LE 1.93) and the RichText definition in `basic/conventions.html`: | Preflight | `GET .../dropbox/folders/{folder}/submissions/user/{user}` (EntityDropbox, 1.88+) | Exactly one block for this user (`EntityType` User, integer `EntityId`); at least one submission; a `Feedback` key present (null or an object); `Status` 1 (Submitted) or 2 (Draft) as an integer or digit string, never 3 (Published), 0 or unknown; existing feedback must be a complete DropboxFeedbackOut with `IsGraded` exactly `false`, no `Score` or `GradedSymbol`, and empty rubric assessments, files and links; existing draft text, or an existing feedback object whose comment is null or empty (`{}`), only with `--replace-draft` | | Re-check | Both reads again, after an interactive confirmation | A digest of the record's status and existing feedback must match the first preflight; otherwise nothing is sent | | Save | `POST .../feedback/user/{user}`, one attempt, CSRF header fetched before the preflight | Body `{"Score": null, "Feedback": {"Text": ..., "Html": ...}, "RubricAssessments": [], "IsGraded": false, "GradedSymbol": null}`. The reference marks `Feedback` as RichText. Only HTTP 200, the documented success, counts; the response body is undocumented and ignored | -| Readback 1 | `GET .../feedback/user/{user}` (DropboxFeedbackOut) | The same draft-only checks as the preflight. Every comment part that is present, even an empty string, must match: `Text` equal to the comment (line endings normalized), `Html` equal to what was sent, or markup made only of `
` and `
` whose text is the comment (entities decoded, non-breaking spaces as spaces, outer line breaks ignored). Any other markup is a mismatch, and at least one part must be present |
+| Readback 1 | `GET .../feedback/user/{user}` (DropboxFeedbackOut) | The same draft-only checks as the preflight. Every comment part that is present, even an empty string, must match: `Text` equal to the comment (line endings normalized), `Html` equal to what was sent, or the same structure: exactly one `
` with no attributes holding only text and attribute-free `
` line breaks, whose text is the comment. Only harmless reformatting is allowed: whitespace outside the paragraph, one line break next to a `
`, `
` or `
" + html.escape(text, quote=True).replace("\n", "
") + "
]*>", re.IGNORECASE) -_CLOSE = re.compile(r"
\s*$", re.IGNORECASE) -_BREAK = re.compile(r"]*>", re.IGNORECASE)
+# ASCII whitespace after line-ending normalization.
+_HTML_SPACE = " \t\n\f"
+
+
+class _RejectedMarkupError(Exception):
+ """The readback Html is not the structure the command sent."""
+
+
+def _bare_tag(raw: str, prefix: str, name: str, *, slash: bool = False) -> bool:
+ """``raw`` is ``
``, one slash) before ``>``."""
+ head = prefix + name
+ if raw[:len(head)].lower() != head or not raw.endswith(">"):
+ return False
+ rest = raw[len(head):-1].strip(_HTML_SPACE)
+ return rest == "" or (slash and rest == "/")
+
+
+class _CommentMarkup(HTMLParser):
+ """Raw token spans of markup that may be one attribute-free ``
`` holding only ``
``.
+
+ The parser finds the tokens; the raw text of every tag is then checked
+ exactly, and the text between tags is sliced from the source, so a token
+ the parser drops or rewrites cannot slip through. Comments, declarations,
+ processing instructions and any other tag raise :class:`_RejectedMarkupError`.
+ """
+
+ def __init__(self, markup: str) -> None:
+ super().__init__(convert_charrefs=False)
+ self.markup = markup
+ self._line_starts = [0] + [index + 1 for index, char in enumerate(markup) if char == "\n"]
+ self.tags: list[tuple[str, int, int]] = [] # (token, start, end)
+
+ def _add(self, token: str, raw: str) -> None:
+ line, offset = self.getpos()
+ start = self._line_starts[line - 1] + offset
+ end = start + len(raw)
+ if self.markup[start:end] != raw or (self.tags and start < self.tags[-1][2]):
+ raise _RejectedMarkupError
+ self.tags.append((token, start, end))
+
+ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+ raw = self.get_starttag_text() or ""
+ if attrs or tag not in ("p", "br") or not _bare_tag(raw, "<", tag, slash=tag == "br"):
+ raise _RejectedMarkupError
+ self._add(tag, raw)
+
+ def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+ if tag != "br":
+ raise _RejectedMarkupError
+ self.handle_starttag(tag, attrs)
+
+ def handle_endtag(self, tag: str) -> None:
+ line, offset = self.getpos()
+ start = self._line_starts[line - 1] + offset
+ raw = self.markup[start:self.markup.find(">", start) + 1]
+ if tag != "p" or not _bare_tag(raw, "", tag):
+ raise _RejectedMarkupError
+ self._add("/p", raw)
+
+ def handle_comment(self, data: str) -> None:
+ raise _RejectedMarkupError
+
+ def handle_decl(self, decl: str) -> None:
+ raise _RejectedMarkupError
+
+ def handle_pi(self, data: str) -> None:
+ raise _RejectedMarkupError
+
+ def unknown_decl(self, data: str) -> None:
+ raise _RejectedMarkupError
+
+
+def _character(reference: str) -> str | None:
+ """The character a complete ``&...;`` reference renders as, or ``None`` if it is not a plain, valid one."""
+ body = reference[1:-1]
+ if not body.startswith("#"):
+ return html.entities.html5.get(body + ";")
+ digits, base = (body[2:], 16) if body[1:2] in ("x", "X") else (body[1:], 10)
+ allowed = "0123456789abcdefABCDEF" if base == 16 else "0123456789"
+ if not 0 < len(digits) <= 8 or any(char not in allowed for char in digits):
+ return None
+ number = int(digits, base)
+ if number == 9 or 0x20 <= number < 0x7F or (
+ 0xA0 <= number <= 0x10FFFF and not 0xD800 <= number <= 0xDFFF
+ and not 0xFDD0 <= number <= 0xFDEF and number & 0xFFFE != 0xFFFE
+ ):
+ return chr(number)
+ return None
+
+
+def _decode_text(raw: str) -> str | None:
+ """Text content of raw paragraph text, or ``None`` for markup or an unclear reference.
+
+ A ``<`` that would open a tag, comment or declaration is refused; a ``<``
+ or ``&`` that browsers show as-is stays literal. A reference must be
+ complete (with ``;``) and name a valid, printable character.
+ """
+ out: list[str] = []
+ index = 0
+ while index < len(raw):
+ char, following = raw[index], raw[index + 1:index + 2]
+ if char == "<" and (following == "" or (following.isascii() and (following.isalpha() or following in "/!?"))):
+ return None
+ if char != "&" or not (following == "#" or (following.isascii() and following.isalnum())):
+ out.append(char)
+ index += 1
+ continue
+ end = index + 1
+ while end < len(raw) and raw[end].isascii() and (raw[end].isalnum() or (raw[end] == "#" and end == index + 1)):
+ end += 1
+ if raw[end:end + 1] != ";":
+ return None
+ value = _character(raw[index:end + 1])
+ if value is None:
+ return None
+ out.append(value)
+ index = end + 1
+ return "".join(out)
def _comparable(text: str) -> str:
- return text.replace("\xa0", " ").strip("\n")
+ return text.replace("\xa0", " ")
def _html_text(markup: str) -> str | None:
- """The text of paragraph/line-break-only markup, or ``None`` if it has any other markup."""
- body = _BREAK.sub("\n", _CLOSE.sub("", _OPEN.sub("", _normalize(markup), count=1), count=1))
- if "<" in body:
+ """The text of markup shaped exactly like :func:`_html` output, or ``None`` for any other structure.
+
+ Allowed reformatting: whitespace outside the paragraph, one line break
+ directly after ``
``/``
`` or before ``
``/``
Synthetic draft note: revisit the second proof.
Line two.
Synthetic draft note: revisit the second proof.
\nLine two.
", - 'Synthetic draft note: revisit the second proof.
Line two.
Synthetic draft note: revisit the second proof.
Line two.
\nSynthetic draft note: revisit the second proof.
\nLine two.\n
hello
"}, "hello\n"), ({"Text": None, "Html": "a & b
c
a b
"}, "a\u00a0b"), -], ids=["trailing-newline-dropped-in-html", "html-only-escaped", "nbsp"]) +], ids=["html-only-escaped", "nbsp"]) def test_saved_comment_check_accepts_equivalent_parts(rich, text): _check_saved_comment(draft_feedback_out(Feedback=rich), text) +_REJECTED_HTML = { + "p-hidden": ("hello
", "hello"), + "p-style": ('', "hello"), + "p-class": ('hello
', "hello"), + "p-id": ("hello
", "hello"), + "br-attribute": ('a
b
hello
", "hello"), + "nested-p-in-div": ("hello
hello
hello
", "hello"), + "script-after": ("hello
", "hello"), + "style-inside": ("hello
", "hello"), + "comment-inside": ("hello
", "hello"), + "comment-before": ("hello
", "hello"), + "unfinished-comment": ("hello
", "& literal", + "x", "
", 1) + fake = FakeLMS(happy_routes(get_feedback=[ + lambda: response(200, draft_feedback_out(Feedback={"Text": TEXT, "Html": hidden}))])) + result = invoke(fake, "--file", str(feedback_file), "--yes", "--json") + assert result.exit_code == 1 + assert json.loads(result.stdout)["outcome"] == "unknown" + assert "saved-draft" not in result.stdout + + def test_csrf_bootstrap_failure_means_nothing_was_sent(feedback_file): fake = FakeLMS(happy_routes())