Valider un formulaire côté serveur

"""
Valider un formulaire sur le serveur : un schéma déclaratif, une erreur par
champ.

Niveau N0. Déterministe, bibliothèque standard seule. Les règles restent
lisibles, et chaque refus peut être expliqué à la personne qui a tapé le
formulaire.

Quatre décisions portent la conception.

D'abord, le schéma est une donnée, pas du code. Il peut être écrit à côté du
formulaire, lu par quelqu'un qui n'écrit pas de Python, et confié à la
version JavaScript qui garde le même formulaire dans le navigateur. Un motif
n'a le même sens des deux côtés qu'avec des classes explicites : les
raccourcis d'un chiffre et d'un caractère de mot dépassent l'ASCII en Python
et s'y arrêtent en JavaScript ; écrivez donc [0-9] et [A-Za-z].

Ensuite, la réponse associe un nom de champ à un message, jamais un booléen.
Un formulaire qui répond « non » sans dire quel champ est en faute envoie
l'utilisateur à la chasse, et le développeur dans les journaux.

Enfin, un message par champ : les vérifications s'arrêtent à la première
règle enfreinte. Dire à quelqu'un que son mot de passe est à la fois trop
court *et* mal formé, c'est du bruit ; qu'il corrige la première chose,
renvoie le formulaire, et voie la suivante.

Enfin, les blancs de bord tombent de toute chaîne avant le moindre contrôle,
et une chaîne que cela vide est traitée comme absente. Le navigateur envoie ce
que l'utilisateur a tapé, et la saisie semi-automatique d'un téléphone ajoute
une espace : sans cela, « ada@example.com » précédée d'une espace est refusée
par un motif dont personne ne voit la faute, et un champ obligatoire rempli de
deux espaces passe pour rempli. La norme HTML retire les blancs de la valeur
d'un champ de courriel pour la même raison.

Une chose que le schéma doit porter, et que ce fichier ne peut pas : une
longueur maximale sur chaque chaîne. Un champ sans « max » accepte des
mégaoctets, et le motif s'applique alors à des mégaoctets.
"""

import re
import unicodedata

# The types a form field can hold once decoded. `bool` is excluded from
# `integer` on purpose: in Python a boolean *is* an int, and a checkbox is not
# an age. 36.0 is an integer, as it is in JavaScript.
TYPES = {
    "string": lambda v: isinstance(v, str),
    "integer": lambda v: not isinstance(v, bool)
    and (isinstance(v, int) or (isinstance(v, float) and v.is_integer())),
}


def trimmed(value):
    """A string without its edge whitespace; anything else is left alone."""
    return value.strip() if isinstance(value, str) else value


def check(value, rule):
    """Return the first broken rule as a message, or None if the value passes."""
    kind = rule.get("type", "string")
    if not TYPES[kind](value):
        return f"must be of type {kind}"
    # For a string the bounds read as a length; for a number, as a value. The
    # length counts code points once composed (NFC), as the JavaScript version
    # does: "é" counts one however it was typed, and an emoji made of several
    # code points, such as a flag, still counts several.
    text = unicodedata.normalize("NFC", str(value))
    size, unit = (len(text), " characters") if kind == "string" else (value, "")
    if "min" in rule and size < rule["min"]:
        return f"must be at least {rule['min']}{unit}"
    if "max" in rule and size > rule["max"]:
        return f"must be at most {rule['max']}{unit}"
    if "pattern" in rule and not re.fullmatch(rule["pattern"], text):
        return rule.get("message", "is not in the expected format")
    return None


def validate(data, schema):
    """
    Check a submitted form against a schema, and return {field: message}.

    An empty mapping means the form is valid. A missing key, an explicit None,
    an empty string and a string of spaces are the same thing here, because
    that is what a browser posts for a field the user left alone.
    """
    # A field the schema does not declare is refused, not ignored: whoever
    # stores the submission would otherwise store it too.
    errors = {field: "is not a field of this form" for field in data if field not in schema}
    for field, rule in schema.items():
        value = trimmed(data.get(field))
        if value is None or value == "":
            if rule.get("required"):
                errors[field] = "is required"
            continue
        message = check(value, rule)
        if message is not None:
            errors[field] = message
    return errors

/**
 * Valider un formulaire sur le serveur : un schéma déclaratif, une erreur par
 * champ.
 *
 * Niveau N0. Déterministe, aucune dépendance. Les règles restent lisibles, et
 * chaque refus peut être expliqué à la personne qui a tapé le formulaire.
 *
 * Quatre décisions portent la conception.
 *
 * D'abord, le schéma est une donnée, pas du code. Il peut être écrit à côté du
 * formulaire, lu par quelqu'un qui n'écrit pas de JavaScript, et confié à la
 * version Python qui garde le même formulaire de l'autre côté. Un motif n'a le
 * même sens des deux côtés qu'avec des classes explicites : les raccourcis d'un
 * chiffre et d'un caractère de mot dépassent l'ASCII en Python et s'y arrêtent
 * en JavaScript ; écrivez donc [0-9] et [A-Za-z].
 *
 * Ensuite, la réponse associe un nom de champ à un message, jamais un booléen.
 * Un formulaire qui répond « non » sans dire quel champ est en faute envoie
 * l'utilisateur à la chasse, et le développeur dans les journaux.
 *
 * Enfin, un message par champ : les vérifications s'arrêtent à la première
 * règle enfreinte. Dire à quelqu'un que son mot de passe est à la fois trop
 * court *et* mal formé, c'est du bruit ; qu'il corrige la première chose,
 * renvoie le formulaire, et voie la suivante.
 *
 * Enfin, les blancs de bord tombent de toute chaîne avant le moindre contrôle,
 * et une chaîne que cela vide est traitée comme absente. Le navigateur envoie ce
 * que l'utilisateur a tapé, et la saisie semi-automatique d'un téléphone ajoute
 * une espace : sans cela, « ada@example.com » précédée d'une espace est refusée
 * par un motif dont personne ne voit la faute, et un champ obligatoire rempli de
 * deux espaces passe pour rempli. La norme HTML retire les blancs de la valeur
 * d'un champ de courriel pour la même raison.
 *
 * Une chose que le schéma doit porter, et que ce fichier ne peut pas : une
 * longueur maximale sur chaque chaîne. Un champ sans « max » accepte des
 * mégaoctets, et le motif s'applique alors à des mégaoctets.
 */

// The types a form field can hold once decoded. `Number.isInteger` rejects
// NaN, Infinity and 1.5 in one go, which is what a form needs.
const TYPES = {
  string: (v) => typeof v === 'string',
  integer: (v) => Number.isInteger(v),
};

/** A string without its edge whitespace; anything else is left alone. */
export function trimmed(value) {
  return typeof value === 'string' ? value.trim() : value;
}

/** Return the first broken rule as a message, or null if the value passes. */
export function check(value, rule) {
  const kind = rule.type ?? 'string';
  if (!TYPES[kind](value)) return `must be of type ${kind}`;
  // For a string the bounds read as a length; for a number, as a value.
  // The length counts code points once composed (NFC), as the Python version
  // does: "é" counts one however it was typed, and an emoji made of several
  // code points, such as a flag, still counts several.
  const text = String(value).normalize('NFC');
  const [size, unit] = kind === 'string' ? [[...text].length, ' characters'] : [value, ''];
  if (rule.min !== undefined && size < rule.min) return `must be at least ${rule.min}${unit}`;
  if (rule.max !== undefined && size > rule.max) return `must be at most ${rule.max}${unit}`;
  // Anchored, so a pattern matches the whole field and not a fragment of it.
  if (rule.pattern !== undefined && !new RegExp(`^(?:${rule.pattern})$`).test(text)) {
    return rule.message ?? 'is not in the expected format';
  }
  return null;
}

/**
 * Check a submitted form against a schema, and return {field: message}.
 *
 * An empty object means the form is valid. A missing key, an explicit null, an
 * empty string and a string of spaces are the same thing here, because that is
 * what a browser posts for a field the user left alone.
 */
export function validate(data, schema) {
  // A field the schema does not declare is refused, not ignored: whoever
  // stores the submission would otherwise store it too.
  const errors = {};
  for (const field of Object.keys(data)) {
    if (!Object.hasOwn(schema, field)) errors[field] = 'is not a field of this form';
  }
  for (const [field, rule] of Object.entries(schema)) {
    const value = trimmed(data[field]);
    if (value === undefined || value === null || value === '') {
      if (rule.required) errors[field] = 'is required';
      continue;
    }
    const message = check(value, rule);
    if (message !== null) errors[field] = message;
  }
  return errors;
}