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

---