Reading diagrams / Topic 32 of 42
Folded steps: the route’s own work
The rule
A route's own work is drawn on the line. Steps that come from elsewhere are folded into shaded boxes: a wrapper's check (guard), a wrapper's early answer (short-circuit), the platform's sign-in check or its transaction, and a wrapper's work after the handler. Each box's title says what it is and where it comes from: “declared” on the route, or “in audited” for the wrapper audited.
A folded box lists the effects its step makes before its test, then every arm that leaves early, as a stub with the effects that arm makes, then “continue” for the way on. So read · docs above no such document → ends Denied runs on that stub's path too. On the line, a read is drawn above the fork that tests it. A box with no test, such as the work after the handler, lists its effects last. The button above the tree shows the steps inline: each box unfolds onto the line under its role, with the same stubs and effects. Inline, the route's declared sign-in or role check is the map's red diamond: the first branch of the tree, its refusal on a short stem. The last picture shows /notes/save that way.
A short-circuit answers the request inside its box: its stub ends, and the route's own work never runs on that path.
The platform's transaction box, such as the one in the shared-docs /docs/edit tree of the previous topic, runs the route's work inside a transaction. Its stubs say how the transaction can fail to commit: retry exhausted saves nothing, and commit unknown cannot say whether it saved. Retry exhausted is drawn as refused, TryAgain 503 try_again. Commit unknown is drawn as may have committed, because the same 503 answer can follow a write that landed.
A box titled “after the handler” runs once the route's own work is done. “on every path that runs the handler” inside it means no path that reaches the handler skips it.
A route with more paths than one picture can hold folds part of its tree into a cable, the map's mark, with the number of paths it carries. In Icetakes' /contributions/replace, everything after the sign-in check is one cable. Select it to draw that part of the tree, with the way back above it. A cable hides nothing: every path in it is drawn once it is opened.
Under that picture, the line of names the author chose is followed by the comment the author wrote above one of them, step, marked unchecked. It is what the author says the code does; Yichus does not confirm it, so read it like any other name.
Folding is how you find the route's own work. A check in a box belongs to shared code: change it, and every route that uses that wrapper changes. How often each path is taken is not drawn.
- On the line, outside every box: the route's own work. In a box: a wrapper or the platform.
- A stub in a box that ends the request: the route's own work never runs on that path.
- “on every path that runs the handler” confirms the after step always follows it.
- retry exhausted, drawn as refused, rules out the transaction's writes. commit unknown, drawn as may have committed, cannot tell whether they landed.
audited-notes /notes/save: two wrappers around one write.
Loading the audited-notes tree.
audited-notes /notes/peek.
Loading the audited-notes tree.
policy-docs /docs/write again.
Loading the policy-docs tree.
shared-docs /docs/edit again: the platform's transaction box.
Loading the shared-docs tree.
Icetakes /contributions/replace: more paths than one picture holds.
Loading the icetakes tree.
audited-notes /notes/save again, with its wrapper and platform steps shown inline.
Loading the audited-notes tree.
How to read this: what each mark in these pictures means
Loading the worked examples and practice.