Tot el mòdul hem estat envoltats de Buffer sense mirar-los de cara. Quan escrivim fs.readFile(FITXER_ESDEVENIMENTS, 'utf8') demanem una traducció; quan l'ometem —en copiar un cartell, en comprimir l'històric amb zlib— el que viatjava pel codi era un Buffer pur. Els trossos d'un stream binari són Buffer. La resposta d'una petició HTTP del Mòdul 4 arribarà en Buffer. Un hash del Mòdul 8 és un Buffer.

Aquesta lliçó obre la caixa: què és exactament un Buffer i per què Node el va haver d'inventar, com es crea sense deixar forats de seguretat, què significa cada codificació, com es llegeixen números binaris i per què importa l'ordre dels seus bytes. Veuràs també els dos errors clàssics de tractar bytes com si fossin caràcters: un subarray que comparteix memòria amb l'original i un emoji partit per la meitat entre dos trossos d'un stream. I ho aplicarem a Escena Viva: comprovar que el cartell que puja un organitzador és de debò un PNG —mirant els seus primers bytes, no la seva extensió— i generar la càrrega útil del codi QR d'una entrada en base64url, signada i comparable en temps constant.

1. Què és un Buffer i per què existeix
2. Crear buffers: from, alloc i el perill d'allocUnsafe
3. Codificacions i per a què serveix cadascuna
4. Números binaris i ordre de bytes
5. Operacions: subarray, concat, copy, compare, indexOf
6. Bytes davant de caràcters: la longitud enganyosa
7. StringDecoder: no partir un caràcter en dos
8. Escena Viva: validar el cartell pels seus nombres màgics
9. Escena Viva: el QR d'una entrada en base64url
10. Comparar secrets en temps constant
11. Buffer, TypedArray i ArrayBuffer

JavaScript va néixer al navegador per manipular text i documents. Fins al 2011 no tenia cap tipus capaç de representar dades binàries: només cadenes UTF-16, números en coma flotant i objectes. Node, en canvi, va néixer per llegir fitxers i parlar per sòcols, és a dir, per moure bytes. Necessitava un tipus que el llenguatge no li donava, i el va crear: Buffer.

Un Buffer és una seqüència de bytes de longitud fixa: cada posició guarda un enter entre 0 i 255, i no pot créixer ni encongir-se —per tenir-ne un de més gran cal crear-ne un altre i copiar—. Dos trets el distingeixen d'un array normal:

• És una Uint8Array. Literalment: Buffer.prototype hereta d'Uint8Array.prototype. Tot el que funciona sobre una Uint8Array funciona sobre un Buffer, més els mètodes que Node hi afegeix a sobre (toString, write, readUInt32BE…).
• La seva memòria viu fora del munt de V8. L'objecte Buffer que manipules sí que és al munt, però els bytes són en memòria reservada a part. Això permet que el sistema operatiu hi escrigui directament sense copiar, i que un procés mogui centenars de megabytes sense pressionar el recol·lector d'escombraries. És també la raó que a la lliçó 03-04 heapUsed amb prou feines es mogués mentre que rss sí que creixia.

Fixa't en com ho imprimeix la consola: <Buffer ...> seguit dels bytes en hexadecimal. Si veus això als teus registres on esperaves text, la causa és gairebé sempre la mateixa: has oblidat la codificació en llegir.

Compte amb les files tercera i quarta, que semblen intercanviables i no ho són: Buffer.from(altreBuffer) copia, mentre que Buffer.from(arrayBuffer) comparteix memòria, així que modificar-ne un afectaria l'altre només en el segon cas.

El nom allocUnsafe no és cap exageració de la documentació. Buffer.alloc(n) recorre els n bytes posant-los a zero; allocUnsafe(n) els lliura tal com estaven a la memòria reservada, que pot contenir restes de dades anteriors del mateix procés: fragments d'un JSON llegit fa un segon, trossos d'una contrasenya, mitja capçalera HTTP.

El 2018 aquesta diferència va produir una família sencera de fuites d'informació en paquets d'npm que reservaven un buffer amb allocUnsafe i l'enviaven per xarxa sense omplir-lo del tot: els bytes sobrants viatjaven amb el que hi hagués abans. La regla pràctica és simple: fes servir sempre Buffer.alloc; allocUnsafe només quan la línia següent hagi de sobreescriure el buffer complet i el rendiment estigui mesurat i justificat.

Una codificació és un contracte de traducció entre bytes i caràcters. Node admet aquestes:

Dues precisions importants:

• base64 no és xifratge. És una representació reversible sense cap secret. Serveix per ficar bytes on només caben caràcters imprimibles, no per protegir res.
• base64url és la variant segura per a URL: substitueix + per -, / per _ i elimina el farciment =. És exactament el que fan servir els JWT del Mòdul 8 i el que farem servir per al QR de les entrades, perquè un + dins d'una URL s'interpreta com un espai i una / parteix la ruta.
• Una codificació desconeguda no falla en silenci: Buffer.from(x, 'utf-9') llança TypeError: Unknown encoding, i pots consultar la llista amb Buffer.isEncoding('base64url').

Un format binari no guarda «1189» com a text: guarda el número en un nombre fix de bytes. Llegir-lo requereix saber quants bytes ocupa, si té signe i en quin ordre estan els seus bytes. Aquest últim punt és l'ordre de bytes (endianness):

• BE (big endian): el byte més significatiu primer. És l'ordre de les xarxes i de la majoria de formats de fitxer (PNG, JPEG).
• LE (little endian): el menys significatiu primer. És l'ordre natiu dels processadors x86 i ARM habituals.

Els mateixos quatre bytes valen 1189 o 2768994304 segons com els interpretis. Per això l'ordre no s'endevina: el fixa el format i cal llegir-ne l'especificació. Els mètodes segueixen tots el mateix patró: read/write + U si no té signe + Int + mida en bits + BE/LE. Per a 64 bits existeixen readBigUInt64BE i companyia, que tornen BigInt. Escriure un valor fora de rang o en un desplaçament que se surt del buffer llança ERR_OUT_OF_RANGE: és un error sorollós, no una corrupció silenciosa.

L'error clàssic és a la primera fila. En un array, slice torna una còpia; en un Buffer, slice i subarray tornen una finestra sobre la mateixa memòria:

Si necessites una còpia de debò, demana-la explícitament: Buffer.from(original.subarray(3, 7)) o Buffer.copyBytesFrom(...). Aquest detall és la causa d'una fallada molt difícil de trobar: guardar trossos d'un stream amb trossos.push(dades) sense copiar-los, quan l'stream reutilitza el mateix buffer intern entre lectures; els trossos acumulats acaben contenint tots el mateix, l'últim. Quant a concat, és la manera correcta de reconstruir un contingut acumulat —Buffer.concat(trossos) després d'un for await sobre un stream— i accepta un tercer argument amb la longitud total, que evita recalcular-la si ja la coneixes. Aquest patró és exactament el que fa readFile per dins, amb la mateixa conseqüència de memòria que vam mesurar a 03-04: fes-lo servir només quan sàpigues que el contingut és petit.

String.length compta unitats UTF-16. Buffer.length compta bytes. I Buffer.byteLength(cadena) et diu quants bytes ocuparà un text abans de convertir-lo. Els tres números poden ser diferents:

Tres lliçons d'aquesta taula. Primera: una ó ocupa dos bytes en UTF-8, així que reservar un buffer amb Buffer.alloc(text.length) per guardar text accentuat el trunca. Segona: un emoji ocupa dues unitats a String.length i una en iterar-lo amb [...text], perquè JavaScript representa els caràcters fora del pla bàsic com una parella de valors substituts. Tercera, i la que trenca programes de debò: tallar un buffer per una posició arbitrària pot partir un caràcter en dos.

Convertir cada tros a text per separat destrueix el caràcter partit: el � (U+FFFD) ja no es pot desfer. Unir primer els bytes i descodificar després funciona, però exigeix tenir tot el contingut a la memòria, que és justament el que un stream evita.

El problema anterior no és teòric: és exactament el que passa quan un stream lliura trossos de 64 KB i el caràcter número 65.536 cau a cavall entre dos. La solució és a node:string_decoder, un descodificador amb estat que reté els bytes incomplets del final d'un tros fins que arriben els que falten.

El primer write torna "Sala B" sense la ó: el descodificador ha vist el primer byte del caràcter i se l'ha guardat. El segon write el completa i emet óveda. L'end() final torna el que quedés pendent —si el flux acaba amb un caràcter incomplet, allà apareix el �, senyal que l'entrada estava truncada—. Quan passes { encoding: 'utf8' } a createReadStream o crides setEncoding('utf8') sobre un stream, Node fa servir internament un StringDecoder, i per això els trossos ja arriben com a text correcte. Necessites fer-lo servir a mà només quan treballes amb els Buffer crus: en desxifrar, en descomprimir per trossos o en implementar un protocol propi.

Els organitzadors pugen el cartell del seu esdeveniment. L'extensió del fitxer no demostra res: reanomenar virus.exe a cartell.png costa un segon. El que sí que identifica un format són els seus primers bytes, l'anomenada signatura o nombre màgic.

Aprofitem l'API FileHandle de la lliçó 03-02 per llegir només els primers bytes, sense carregar una imatge de deu megues per mirar-ne vuit:

Quatre decisions que mereixen comentari: Buffer.alloc i no allocUnsafe, perquè si el fitxer té menys de 16 bytes els sobrants serien brossa de memòria comparada contra signatures reals; Buffer.from(desti.subarray(...)), que torna una còpia independent en comptes d'una vista amb accés als bytes sobrants; equals en comptes de toString, perquè comparar bytes amb bytes evita qualsevol dubte de codificació —0x89 no és text vàlid en UTF-8—; i error.codi seguint la convenció de domini del curs, amb la capçalera en hex adjunta per diagnosticar què va pujar realment l'organitzador.

La comprovació funciona. Compte amb l'abast d'aquesta tècnica: la signatura demostra el format, no que el contingut sigui inofensiu. Al Mòdul 4, en rebre pujades de debò, la combinarem amb un límit de mida i amb la ruta blindada de la lliçó 03-03.

Cada entrada d'Escena Viva porta un codi EV-2026-000123 i un QR que l'acomodador escaneja a la porta. El QR conté una URL, i dins d'aquesta URL viatja una càrrega útil: les dades de l'entrada més una signatura que impedeix fabricar-ne. Aquest contingut és binari i ha de cabre en una URL sense escapaments: el cas exacte de base64url.

sonIguals és la funció de comparació segura de l'apartat següent, que viu en aquest mateix mòdul. El cos no està xifrat —qualsevol el pot descodificar amb Buffer.from(cos, 'base64url').toString()—, i això és acceptable: al QR d'una entrada no hi ha res secret. El que protegeix la signatura és la integritat: sense conèixer el secret no es pot fabricar una entrada vàlida ni canviar-li la sessió. La comparació d'aquesta signatura, però, no es pot fer amb ===, i aquest és l'últim apartat tècnic de la lliçó.

a === b sobre cadenes compara caràcter a caràcter i s'atura al primer que difereix. Aquesta optimització, inofensiva en qualsevol altre context, filtra informació quan el que es compara és un secret: un atacant que mesura el temps de resposta pot deduir quants caràcters inicials ha encertat i reconstruir la signatura byte a byte.

crypto.timingSafeEqual compara sempre tots els bytes, trigui el que trigui a trobar la primera diferència. Té una exigència: els dos buffers han de mesurar exactament el mateix, o llança ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH, i la longitud de la dada aliena no la controles. La solució estàndard és normalitzar la longitud amb un hash abans de comparar:

digest() sense argument torna un Buffer —amb 'hex' tornaria una cadena—, i dos SHA-256 mesuren 32 bytes cadascun passi el que passi. Reprendrem aquesta funció tal qual al Mòdul 8, on el mateix raonament s'aplica a claus d'API i a testimonis de sessió.

Les tres peces encaixen així: un ArrayBuffer és un bloc de memòria en brut que no es pot llegir ni escriure directament; un TypedArray (Uint8Array, Int16Array, Float64Array…) és una vista que interpreta aquest bloc com a números de cert tipus, i diverses vistes poden mirar el mateix bloc; un Buffer és una Uint8Array amb mètodes afegits per Node.

Aquí hi ha la trampa més subtil del mòdul. Node reserva els buffers petits (menys de 4 KB) dins d'un pool compartit de 8 KB, així que buf.buffer no és la memòria del teu buffer: és la del pool sencer, i buf.byteOffset indica on comença la teva porció. Passar buf.buffer a una API que espera les dades exactes lliura 8 KB de memòria aliena. La manera correcta de convertir:

A la pràctica això apareix en interoperar amb API d'estàndard web dins de Node —fetch, crypto.subtle, WebSocket, els worker threads del Mòdul 10—, que parlen Uint8Array i ArrayBuffer, no Buffer.

• Veure <Buffer 7b 0a ...> on esperaves text. Falta la codificació: readFile(ruta, 'utf8') o .toString('utf8'). No facis servir mai String(buf) amb l'esperança que faci el correcte amb dades binàries.
• Fer servir allocUnsafe per costum. Si no omples el buffer sencer, publiques memòria antiga del procés. alloc per defecte, sempre.
• Creure que slice copia. Comparteix memòria, al revés que als arrays. Còpia explícita amb Buffer.from(vista) si l'original ha de canviar o reutilitzar-se.
• Reservar amb text.length en comptes de Buffer.byteLength(text). Amb un sol accent ja et falta un byte i el text surt truncat.
• Concatenar trossos com a cadenes. tros.toString() per cada tros d'un stream parteix els caràcters multibyte: acumula Buffer i descodifica al final, o fes servir StringDecoder.
• Comparar signatures amb ===. Filtra informació per temps. timingSafeEqual sobre buffers d'igual longitud, normalitzada amb un hash.
• Consell: treballa amb Buffer fins a l'últim moment possible i converteix a text una sola vegada, a la frontera del teu sistema. Cada conversió d'anada i tornada costa CPU i és una oportunitat de corrompre dades.

Escriu src/laboratori/inventari-cartells.js que recorri un directori (per defecte dades/cartells/) i, per cada fitxer, imprimeixi en una taula el seu nom, la seva extensió declarada, el tipus real detectat amb detectarTipus i si coincideixen. Ha de marcar clarament els fitxers l'extensió dels quals menteix. Fes servir readdir amb withFileTypes de la lliçó 03-02 i les rutes de src/config/rutes.js.

Escriu una funció trossejarText(text, bytesMaxims) que torni un array de Buffer de com a màxim bytesMaxims bytes cadascun sense partir cap caràcter. Verifica amb 'Noche de Monólogos 🎭 en la Sala Bóveda' i bytesMaxims = 10 que en concatenar els trossos i descodificar recuperes el text original i que cap tros no produeix � per separat.

Dissenya un format binari mínim per a l'informe diari d'ocupació: 4 bytes de signatura 'EVIV', 1 byte de versió, 2 bytes big endian amb el nombre de sessions, 4 bytes big endian amb les entrades venudes i la resta en JSON UTF-8. Escriu escriureInformeBinari(ruta, informe) i llegirInformeBinari(ruta), i comprova que el cicle complet torna les dades originals i que un fitxer amb signatura incorrecta llança un error amb codi: 'FORMAT_NO_ACCEPTAT'.

Solució 1. La comparació entre extensió declarada i tipus real és el nucli:

El cas .jpeg/.jpg recorda que un format pot tenir diverses extensions legítimes: la comprovació no ha de generar falses alarmes. Un desconegut no sempre és un atac —pot ser un format que no és a SIGNATURES—, però sí que és motiu per no acceptar-lo.

Solució 2. La clau és no tallar a cegues, sinó recular fins al principi d'un caràcter. En UTF-8, els bytes de continuació tenen la forma 10xxxxxx, és a dir, (byte & 0xc0) === 0x80:

El Buffer.from(...) al voltant del subarray és imprescindible: sense ell, els trossos serien vistes del mateix buffer i qualsevol modificació posterior els afectaria tots. Una alternativa més curta si només vols text: recórrer [...text] acumulant per Buffer.byteLength de cada caràcter.

Solució 3. El format s'escriu i es llegeix en el mateix ordre en què està definit:

Amb les dades de la llavor, readUInt32BE(7) torna 1811 i readUInt16BE(5) torna 7. Fixa't en el byte de versió: és el que permetrà llegir fitxers antics quan el format canviï, i ometre'l és l'error més freqüent en dissenyar un format binari propi. writeUInt16BE amb més de 65.535 sessions llançaria ERR_OUT_OF_RANGE, un recordatori que cada camp binari té un sostre que cal triar a consciència.

Ja saps què hi ha dins de la caixa. Un Buffer és una Uint8Array sobre memòria aliena al munt de V8, de longitud fixa, que existeix perquè JavaScript no tenia tipus binari quan Node el va necessitar. El crees amb Buffer.from —copiant des de text, array o un altre buffer, compartint des d'un ArrayBuffer— o amb Buffer.alloc, mai amb allocUnsafe llevat que l'hagis de sobreescriure sencer, perquè el seu contingut inicial és memòria feta servir pel procés mateix.

Coneixes les codificacions i el seu repartiment de papers: utf8 per a text, latin1 per tractar bytes com a caràcters un a un, hex per depurar i hashes, base64 per ficar binari en JSON i base64url per ficar-lo en una URL. Saps llegir i escriure enters amb readUInt32BE i companyia, i que l'ordre de bytes el fixa el format, no la teva màquina. Domines les operacions i les seves trampes: subarray comparteix memòria —l'error clàssic—, concat copia, equals compara sense ambigüitat de codificació. I tens clar per què String.length, Buffer.byteLength i [...text].length donen tres números diferents, per què tallar un buffer per una posició arbitrària produeix un � irrecuperable i com ho evita el StringDecoder guardant-se els bytes incomplets entre tros i tros.

Escena Viva s'emporta dos mòduls nous: src/utils/tipus-fitxer.js, que valida el cartell d'un esdeveniment pel seu nombre màgic llegint només setze bytes amb FileHandle, i src/utils/qr-entrada.js, que codifica la càrrega útil del QR en base64url amb una signatura HMAC comparada en temps constant amb timingSafeEqual sobre resums d'igual longitud. I saps que buf.buffer no és el teu buffer, sinó el pool de 8 KB on viu: byteOffset i byteLength no són opcionals. Amb això tanques el Mòdul 3. Escena Viva ha passat de tenir les dades incrustades al codi a llegir el seu catàleg del disc de manera asíncrona, organitzar informes per mes, resoldre rutes que funcionen des de qualsevol directori i en qualsevol sistema, processar un històric de vendes amb memòria constant mitjançant canonades amb pipeline, i entendre els bytes que circulen per tot l'anterior. El projecte sap llegir i escriure; el que encara no sap és parlar amb ningú. Això comença al Mòdul 4: HTTP, i veuràs de seguida que no és cap territori nou: un servidor HTTP de Node és un EventEmitter que emet request; la petició que reps és un stream de lectura i la resposta que tornes és un stream d'escriptura; el cos JSON d'un POST arriba en trossos de Buffer que cal acumular amb cura; i servir un fitxer estàtic és exactament createReadStream més la ruta blindada de la lliçó 03-03. Tot el d'aquest mòdul torna, aquesta vegada connectat a la xarxa.