Voilà ce que j’ai mis longtemps à comprendre :

Lorsqu’un client envoie quelque chose à httpd, le serveur Web commence à créer des seaux qu’il remplit au fur et à mesure : et quand un seau est plein, il en remplit un autre etc jusqu’à ce qu’il ait un nombre de seaux suffisants. Ces seaux sont rangés dans une brigade. Une brigade de seaux. Une bucket brigade, en Anglais. Et là, il les fait passer au premier filtre qu’il a sur sa liste. Ce filtre peut à son tour, ajouter d’autres seaux, en enlever, ou même, tout supprimer et créer toute une série d’autres seaux. Toujours est-il que quand on développe un filtre, il faut toujours avoir en tête plusieurs choses :

• Il va toujours y avoir une série de seaux qu’il va falloir parcourir, ce ne sera jamais un seul seau simple et seul. La boucle de parcours sera toujours de la forme :
  /* on demande à lire une série de seaux : */
rv = ap_get_brigade(f->next, bb, AP_MODE_READBYTES, APR_BLOCK_READ, readbytes);
/* si erreur, la gérer, sinon boucle pour lire seau après seau : */
for (b = APR_BRIGADE_FIRST(bb);
     b != APR_BRIGADE_SENTINEL(bb);
     b = nextb) {
    nextb = APR_BUCKET_NEXT(b);
    ...
    traitement de ce qu'on a reçu
    ...
}
• Le serveur Apache gère une chaine de filtres, qui se suivent dans un ordre qu’il est impossible à connaitre du point de vue d’un filtre. En résumé, on ne sait jamais, quand on programme un filtre, quels sont les filtres qui ont été appelés avant le nôtre, ou quels sont les filtres le seront après. Bon ok. Il y a quand même une possibilité de dire grossièrement où on veut que le filtre soit, dans la chaine. En réalité il est possible de préciser l’un cinq niveaux grossiers parmi :
  1. APR_HOOK_REALLY_FIRST
  2. APR_HOOK_FIRST
  3. APR_HOOK_MIDDLE
  4. APR_HOOK_LAST
  5. APR_HOOK_REALLY_LAST

  Revenons à notre brigade, pleine de seaux, mais dont on ne sait pas exactement ce qu’elle contient, mais on le suppose. Lorsque celle-ci arrive et que notre filtre est appelé, on ne sait que grossièrement où est placé le filtre dans la chaine, donc il se peut que la brigade arrive avec des données en plus qui proviennent d’autres filtres mais qui ne nous concernent pas (entre autres des données personnelles qui vont d’un filtre à l’autre, des méta-données, en Anglais METADATA). C’est pour cela qu’il faut toujours s’assurer que ce ne sont pas des métadonnées qui ne nous concernent pas : c’est la macro APR_BUCKET_IS_METADATA :
  /* on demande à lire une série de seaux : */
rv = ap_get_brigade(f->next, bb, AP_MODE_READBYTES, APR_BLOCK_READ, readbytes);
/* si erreur, la gérer, sinon boucle pour lire seau après seau : */
for (b = APR_BRIGADE_FIRST(bb);
     b != APR_BRIGADE_SENTINEL(bb);
     b = nextb) {
    nextb = APR_BUCKET_NEXT(b);
    if ( ! APR_BUCKET_IS_METADATA(b) ) {
        ...
        traitement de ce qu'on a reçu
        ...
    }
}