@marktiderman/genesis-forms 0.4.0 → 0.4.2

package/README.md

@@ -164,8 +164,35 @@ The formula language is small and is parsed and evaluated by this package, never
 An unanswered question is blank, and arithmetic with a blank is blank, so a total stays empty until
 its answers are in; dividing by zero is blank too. The functions skip blanks (`sum` of nothing is
 `0`). Text holding a number (`"12"`, `"1,200"`) counts as that number, and yes / no as 1 / 0.
-A list or table of more than `MAX_FORMULA_ITEMS` (10,000) items reads as blank. A formula is at
-most `MAX_FORMULA_LENGTH` characters and 64 levels of parentheses, calls, signs and `? :` deep.
+
+Limits, so a large submission can't make the server slow:
+
+- A calculated field that reads a list or table of more than `MAX_FORMULA_ITEMS` (10,000) items
+  has no value: it is blank, never `0` or a partial total. The same goes for one that reads an
+  answer past `MAX_SETTLE_ITEMS` (50,000) items read by all of a form's formulas together (each
+  list or table counted once, however many of its columns are read, in form order; an answer over
+  10,000 items counts for none).
+  Nothing else reports this, so give a table a `maxRows` well under these if its total matters.
+- A formula is at most `MAX_FORMULA_LENGTH` characters and 64 levels of parentheses, calls, signs
+  and `? :` deep, and all of a form's formulas together at most `MAX_FORM_FORMULA_LENGTH` (20,000).
+- Lists are read once per answer, so treat an engine's answers as immutable: pass `setValue` a new
+  array (the engine and the built-in renderers never change one in place). `setValue` with the
+  array it already holds works it out again. Each engine, and so each `validateSubmission` call,
+  keeps its own lists, so the same object passed again after a change is read afresh.
+- `validateSubmission` refuses a submission that would be too much work, with an error under `""`,
+  and never cuts one short. It doesn't rely on the host's request size limit. Each limit is an
+  option for a host that needs more:
+
+  | Limit | Default | Option | Counts |
+  | --- | --- | --- | --- |
+  | `MAX_EVENTS` | 10,000 | `maxEvents` | Events, after `compactEvents`; at most `RAW_EVENTS_PER_EVENT` (10) times as many may be sent |
+  | `MAX_SUBMISSION_VALUES` | 200,000 | `maxValues` | JSON values in the answers, answer events and hidden inputs: each number, text, true / false, list item, row and cell. A run of answers to one field (a table sends itself on every keystroke) counts its last only |
+  | `MAX_REPLAY_WORK` | 1,000,000 | `maxReplayWork` | Replaying the events: one unit per block each time the path is walked, one per calculated field each time the answers settle, and a formula's size (its numbers, answers and operators) each time it is worked out. The submit after the replay isn't counted |
+
+  A respondent filling in a long form with formulas uses about 400,000 units of replay work at
+  most; the limit stops a log built to make every step work out every formula. After a refusal,
+  sending the same body again gets the same answer, so show the `""` message rather than offer
+  "Try again".
 
 The engine works the values out from the answers on the path (an answer hidden by logic reads as
 blank), again whenever an answer it reads changes, and stores them with the answers, so `engine.answers()` and a
@@ -203,8 +230,8 @@ await store(result.submission); // answers, hidden, context, ending
 ```
 
 Errors are keyed by field id. The `""` key is for the whole submission: `"Malformed submission."`
-(a body of the wrong shape), a definition that fails `parseForm`, or more than `maxEvents` events
-(default 10 000, counted after `compactEvents`). Events of an unknown type are dropped, so a newer
+(a body of the wrong shape), a definition that fails `parseForm`, or a submission past one of the
+limits above (`maxEvents`, `maxValues`, `maxReplayWork`). Events of an unknown type are dropped, so a newer
 client's log still replays. With `settings.clearHiddenValues: false`, a hidden field's value is kept
 only if its format is valid.