Aller au contenu principal

Appendix B. Implementation Notes (Notes d'implémentation)

Cette annexe fournit des conseils pratiques et des meilleures pratiques pour implémenter RFC 8941.

Architecture d'implémentation générique​

Les implémentations génériques devraient (SHOULD) exposer des fonctions serialize (section 4.1) et parse (section 4.2) de niveau supérieur.

// API fonctionnelle
const result = parseList(input);
const output = serializeDict(dict);

// API orientée objet
const parser = new StructuredFieldParser();
const result = parser.parseList(input);

Complétude et cohérence​

Pour l'interopérabilité, les implémentations génériques doivent (MUST) être complètes et suivre strictement les algorithmes (section 1.1).

Suite de tests communautaire​

URL: https://github.com/httpwg/structured-field-tests

Couvre : sérialisation, analyse, cas limites, conditions d'erreur, tests d'interopérabilité.

Mappages ordonnés​

Les Dictionaries et Parameters sont des mappages préservant l'ordre. Les implémentations devraient (SHOULD) maintenir cet ordre.

// ✓ Bon - préserve l'ordre
class OrderedDict {
  constructor() {
    this.items = [];  // [{key, value}, ...]
  }
}

// ✗ Mauvais - ne garantit pas l'ordre
const dict = {};

Distinction Token vs String​

Les implémentations doivent (SHOULD) maintenir la distinction entre Token et String.

// ✓ Bon - préserve le type
const value = {type: 'token', value: 'text/html'};
const value2 = {type: 'string', value: 'text/html'};

Gestion des erreurs​

En cas d'échec d'analyse, les implémentations doivent (MUST) ignorer le champ entier.

function parseStructuredField(input, type) {
  try {
    return parse(input, type);
  } catch (error) {
    return null;  // Ignorer le champ entier
  }
}

Liste de contrôle de sécurité​

  • Limiter la taille maximale des champs
  • Limiter le nombre de membres List/Dictionary
  • Limiter la longueur des chaînes
  • Valider strictement tous les types
  • Rejeter les clés en double
  • Échouer correctement sur erreur

Bonnes pratiques de test​

  1. Utiliser la suite de tests communautaire
  2. Tester les cas limites
  3. Tester les cas d'erreur
  4. Tests aller-retour : serialize(parse(x)) == x
  5. Tests d'interopérabilité

Points clés​

  1. Suivre les algorithmes : Adhérer strictement à la spécification
  2. Utiliser la suite de tests : Valider avec les tests communautaires
  3. Préserver l'ordre : Maintenir l'ordre Dictionary et Parameter
  4. Distinguer les types : Token vs String
  5. Échouer correctement : Ignorer le champ entier en cas d'erreur
  6. Limites de sécurité : Implémenter des limites de taille raisonnables