Appendix B. Implementation Notes (Note di implementazione)

Questa appendice fornisce consigli pratici e migliori pratiche per implementare RFC 8941.

---

Architettura di implementazione generica

Le implementazioni generiche dovrebbero (SHOULD) esporre funzioni serialize (sezione 4.1) e parse (sezione 4.2) di livello superiore.

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

// API orientata agli oggetti
const parser = new StructuredFieldParser();
const result = parser.parseList(input);

---

Completezza e coerenza

Per l'interoperabilità, le implementazioni generiche devono (MUST) essere complete e seguire rigorosamente gli algoritmi (sezione 1.1).

Suite di test della comunità

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

Copertura: serializzazione, parsing, casi limite, condizioni di errore, test di interoperabilità.

---

Mappature ordinate

I Dictionaries e i Parameters sono mappature che preservano l'ordine. Le implementazioni dovrebbero (SHOULD) mantenere quest'ordine.

// ✓ Buono - preserva l'ordine
class OrderedDict {
  constructor() {
    this.items = [];  // [{key, value}, ...]
  }
}

// ✗ Cattivo - non garantisce l'ordine
const dict = {};

---

Distinzione Token vs String

Le implementazioni dovrebbero (SHOULD) mantenere la distinzione tra Token e String.

// ✓ Buono - preserva il tipo
const value = {type: 'token', value: 'text/html'};
const value2 = {type: 'string', value: 'text/html'};

---

Gestione degli errori

In caso di fallimento del parsing, le implementazioni devono (MUST) ignorare l'intero campo.

function parseStructuredField(input, type) {
  try {
    return parse(input, type);
  } catch (error) {
    return null;  // Ignora l'intero campo
  }
}

---

Lista di controllo della sicurezza

• Limitare la dimensione massima dei campi
• Limitare il numero di membri List/Dictionary
• Limitare la lunghezza delle stringhe
• Convalidare rigorosamente tutti i tipi
• Rifiutare le chiavi duplicate
• Fallire correttamente in caso di errore

---

Migliori pratiche di test

1. Utilizzare la suite di test della comunità
2. Testare i casi limite
3. Testare i casi di errore
4. Test di andata e ritorno: serialize(parse(x)) == x
5. Test di interoperabilità

---

Punti chiave

1. Seguire gli algoritmi: Aderire rigorosamente alle specifiche
2. Utilizzare la suite di test: Convalidare con i test della comunità
3. Preservare l'ordine: Mantenere l'ordine di Dictionary e Parameter
4. Distinguere i tipi: Token vs String
5. Fallire correttamente: Ignorare l'intero campo in caso di errore
6. Limiti di sicurezza: Implementare limiti di dimensione ragionevoli

---