Industria restaurantelor din România are o obsesie: să copieze America.

Meniuri în engleză. „Fine dining." Plating fancy. Bacșiș procentual.

Doar că, evident, au copiat fix partea care le aduce mai mulți bani.

Restul… opțional.

Cum funcționează în SUA (știi, modelul pe care îl tot imită)

Hai să ne uităm pe un bon real, de la Route 66 American Kitchen, 79 Pearl Street, New York City. 24 august 2025.

Mâncare de bar (nachos, quesadilla, mac & cheese, chicken wings), câteva beri și sucuri.

Observă trei chestii:

1. Taxa (sales tax) e separată. O vezi clar, 8.875%, aplicată de stat.
2. Bacșișul se calculează la subtotal. 18% din $148 = $26.64. Nu din $148 + $13.17. Din subtotal. Fără taxe.
3. Tu alegi. Pe bon scrie clar câte procente dai. E treaba ta.

Simplu. Curat. Nu te păcălește nimeni.

Cum funcționează în România (varianta „optimizată")

Acum hai să vedem ce se întâmplă pe un bon din București. Restaurant, seara.

Și apoi, jos pe bon:

„Tipsul nu este inclus. / Tips not included."

Și sugestii: 10% → 42.80 lei / 15% → 64.20 lei / 20% → 85.60 lei.

Aha.

Problema #1: Îți iau bacșiș fără să te întrebe

Pe bon, la „produse", apare o linie interesantă: Tips — 39.00 lei.

Adică 10% din nota de mâncare. Pus acolo, între pizza și total, ca și cum ar fi un produs. Un fel de „Porție Bacșiș, 1 buc, 39 lei."

În SUA: tu alegi dacă dai.

În România: ți se pune direct pe bon.

Dar stai, că asta e doar începutul.

Problema #2: Îți sugerează să mai dai încă o dată

Ai deja 39 lei bacșiș. Pe care nu l-ai cerut.

Dar jos pe bon primești, frumos, cu bilinguism:

„Vă oferim următoarele sugestii pentru calculul tipsului."

10%, 15%, 20%.

Adică: „știm că ți-am luat deja, dar poate mai scoatem niște bani din tine."

Problema #3 (și cea mai jegoasă): Calculează bacșișul la suma cu TVA

Aici e marea țeapă pe care nu o vede aproape nimeni.

În România, prețurile de pe meniu includ TVA. Ăsta e un impozit pe care restaurantul îl colectează și îl dă statului. Nu e al lor. E al ANAF-ului.

Hai să desfacem bonul:

Apa, ceaiul, pizza, pui, cartofi = TVA 11% (mâncare și băuturi nealcoolice). Cappuccino, vin = TVA 21% (cafea + alcool).

Restaurantul primește efectiv: ~345 lei.

Statul primește: ~44 lei.

Dar bacșișul de pe bon? Se calculează la 389 lei. La suma cu TVA.

Adică tu dai bacșiș și pe taxele statului. Ceea ce e ca și cum în New York ai da tip la $148 + $13.17 în loc de $148.

Doar că în New York… nu face nimeni asta.

Hai să punem cifrele cap la cap

Bonul din New York

Bacșiș real: 18% din ce primește restaurantul. Fix atât.

Bonul din București (scenariul „sugestie acceptată")

Să zicem că faci ce scrie pe bon: ai 39 lei deja + mai lași 10%.

Bacșiș total: 81.80 lei.

Dar restaurantul primește, din mâncare, doar ~345 lei (restul e TVA).

Deci bacșișul real e: 81.80 / 345 = ~23.7%

Felicitări. Ai ajuns să dai mai mult decât în New York.

Dar nu pentru că serviciul e mai bun. Nu pentru că experiența e premium.

Ci pentru că:

• ți-au pus deja bacșiș
• l-au calculat pe suma cu TVA
• și au sperat că nu ești atent

Asta nu e „cultură de tipping"

E o combinație de:

Lene. Pentru că nu vor să explice nimic.

Lăcomie. Pentru că nu le ajunge o dată.

Și puțin dispreț față de client. Pentru că mizează pe faptul că nu te uiți pe bon.

Dacă ar fi fost transparent, ar fi scris:

„10% bacșiș inclus. Nu mai lăsați altul."

Industria restaurantelor din România, pe scurt

Vrea:

• bacșiș ca în America
• prețuri ca în Vest

Dar oferă:

• transparență zero
• reguli inventate
• și calcule făcute „în favoarea casei"

Ce faci data viitoare

Regula e simplă:

1. Vezi dacă există „tips" pe bon.

2. Dacă există → nu mai lași nimic. Ai dat deja.

3. Dacă vrei să fii corect până la capăt → calculezi bacșișul la subtotal fără TVA, nu la suma finală.

Exact ca în SUA. Știi, modelul pe care se tot pozează.

Concluzie

România nu are problemă cu bacșișul.

Are problemă cu faptul că vrea să-l încaseze de două ori și să-l calculeze greșit prima dată.

Și apropo, acel „10% standard" pe care toată lumea îl consideră rezonabil? E calculat la suma cu TVA. Adică e de fapt 11.3% din ce primește restaurantul. În America, 10% înseamnă 10%. În România, 10% înseamnă 11.3%. Că na, și la procente facem „optimizare".

Și cât timp lumea plătește fără să se uite, o să continue.

Pentru că, aparent, cel mai profitabil lucru în HoReCa nu e mâncarea.

E matematica creativă de pe bon.

Dacă faci dezvoltare software, design computerizat, editare video, gestionezi platforme online sau conduci call centere/dispecerate și te-ai săturat de bătaia de joc din România, probabil te-ai întrebat deja: există o variantă mai simplă și mai ieftină să rulezi o firmă în mod legal, dar fără să te sufoce taxele?

Răspunsul scurt: da. Se numește Moldova IT Park și vine cu un regim fiscal unic de 7% pe venituri. Fără scheme dubioase, fără complicații. În articolul ăsta îți explic concret cum funcționează și cum te poate ajuta să păstrezi mai mulți bani în buzunarul tău.

Ce e Moldova IT Park?

Republica Moldova a creat un cadru special pentru firmele din IT și activități conexe, unde:

• Plătești 7% impozit pe cifra de afaceri.
• Nu mai ai alte taxe ascunse (profit, salarii, contribuții complicate).
• Poți să-ți scoți banii ca salarii cu 0% taxe.
• IT Park are contract garantat până cel puțin în 2038 → stabilitate pe termen lung.

Flexibilitate pe salarii

• Poți seta salariile orar sau lunar, după cum vrei.
• Plata orara îți da libertatea să-ți plătești luna asta 5.000 lei, luna viitoare 8.000 lei, în funcție de cashflow.

Conversia valutară

• Toate salariile se plătesc obligatoriu în lei moldovenești (MDL).
• Dacă vrei să convertești în euro, dolari sau lei românești → există un comision de 1%.

Cum funcționează taxele (exemplu concret)

• Emiți o factură de 100.000 € către un client din SUA sau România. (TVA = 0%. În Republica Moldova TVA-ul standard e 20%, dar se aplică doar pentru tranzacții interne, adică atunci când vinzi către firme din Moldova)
• Plătești 7.000 € impozit (7%).
• Rămâi cu 93.000 €.
• Îi scoți ca salarii
• Cheltui direct cu cardul sau retragi la ATM banii

Nu trebuie să-ți schimbi rezidența fiscală

Un punct extrem de important și pe care mulți îl ratează: nu trebuie să-ți schimbi rezidența fiscală ca să beneficiezi de avantajele IT Park Moldova.

• Nu e nevoie să-ți muți domiciliul sau rezidența în Republica Moldova.
• Nu e nevoie să-ți scoți dividendele în România (care sunt supra-impozitate).
• Totul se rezolvă prin salariu.

Salariul brut = salariu net

Aici e magia sistemului:

• Salariul brut este egal cu salariul net.
• Nu există diferența absurdă pe care o știm din România, unde statul ia aproape jumătate din salariul brut sub formă de taxe și contribuții.
• În Moldova IT Park: ce îți setezi ca salariu brut → exact aia primești pe card.

Și asta nu e doar pentru tine, ca fondator:

• Toți partenerii sau angajații tăi beneficiază de același principiu.
• Exemplu: dacă acum ai un angajat cu 5.850 lei net în România, în IT Park îi poți oferi 10.225 lei fără să te coste suplimentar.
• Practic, îi crești salariul automat pentru că statul nu mai mușcă jumătate din bani.

Doar scenarii win–win

• Tu, ca antreprenor, rămâi cu mai mult profit real.
• Angajații tăi au salarii mai mari, direct în buzunar, fără taxe absurde.
• Totul e 100% legal și transparent.
• Scapi de statul bananier din România, care doar îți pune piedici și îți fură din munca ta, și îți muți businessul într-un cadru sănătos și predictibil.

Procesul de deschidere

• vii o singură zi în Moldova → semnătură digitală + cont bancar,
• restul e 100% remote: banking online, contabilitate externalizată, suport zilnic.

Costuri

• 1.500 € one-time – deschiderea firmei (acte, IT Park, semnătură digitală).
• 280 €/lună – mentenanță (contabilitate, audit, sediu legal, consultanță zilnică).
• 7% lunar pe veniturile facturate.
• 1% comision de conversie valutară (pentru toate plățile pe care le faci la comercianții români sau retrageri ATM).

Cine te poate ajuta: Bizonaire

Dacă vrei să faci pasul ăsta simplu și fără bătăi de cap, îți recomand pe Tudor Mardari, co-fondator Bizonaire.

• Bizonaire e o companie de consultanță juridică și fiscală din Republica Moldova.
• Sunt specializați în înființarea de firme în Moldova IT Park.
• Se ocupă de: acte, înregistrare, semnătura digitală, contabilitate, birou virtual, suport fiscal.
• Practic, îți dau o soluție completă „la cheie” → tu doar vii o zi în Chișinău, iar restul se rezolvă de la distanță.

Am văzut ce fac pentru antreprenorii români și mi se pare cea mai bună opțiune dacă vrei să profiți de IT Park.

Concluzie și rezumat rapid

Dacă vrei să optimizezi legal și transparent taxele pentru o activitate în IT/digital:

• 7% – taxă unică pe venituri.
• 1% – comision conversie valutară (MDL → EUR/USD/RON).
• 1.500 € – cost inițial (achitat o singură dată).
• Zbor Chișinău ↔ România – dus-întors într-o zi (sau un city break vineri–duminică, o singură dată).
• 280 €/lună – contabilitate, consultanță fiscală și mentenanță firmă
• Stabilitate garantată până în 2038.
• Flexibilitate la salarii – poți seta liber sumele lunar/orar (ex: 5.000 lei în februarie, 8.000 lei în martie).

Disclaimer: Acest articol nu constituie consultanță fiscală sau financiară. Informațiile prezentate sunt bazate pe surse proprii și experiență personală și nu reprezintă o garanție că acestea sunt sau vor fi aplicate efectiv. Textul are un scop exclusiv informativ și educativ. Pentru luarea deciziilor financiare sau fiscale importante, vă recomandăm să consultați un contabil sau un consultant autorizat. Autorul nu își asumă responsabilitatea pentru eventualele consecințe legale rezultate în urma aplicării informațiilor prezentate.

„Paradis fiscal”? Ha! Mai bine paradisul fraierilor. Cine a tradus „tax haven” în „paradis fiscal” să-și bage limba-n blender și să nu mai scoată prostii din gură. Asta e rușine națională.

Haven în engleză înseamnă adăpost — nu paradis, fraților! Dar ce să le ceri unor amărâți care habar n-au nici să pronunțe corect o frază în engleză? S-au uitat la cuvinte, au scos „heaven” din șapcă, și-au zis „mama, ce frumos, paradis fiscal!”.

Nu e paradis, e un fel de buncăr în care-ți ascunzi banii. Și na, când tu crezi că ai fost în paradis, vine ANAF-ul și-ți spune că e doar un bunker plin de capcane.

Dacă vrei să fii un adevărat maestru al optimizării fiscale offshore, ține minte un singur lucru:

NU-ȚI FACE FIRMA PE NUMELE TĂU.

Ăsta e pasul zero.

Pasul 1: Alege offshore-ul potrivit, unul „neprietenos” cu ANAF-ul

Să nu fii fraier să alegi o țară de care ANAF știe tot, cu acorduri de schimb de informații. Pentru asta, consultă lista oficială a UE cu jurisdicții necooperante. Panama? Da, încă e pe lista aia.

Adică vrei să fii într-un loc care-ți oferă o mică umbrelă de protecție, nu un spot publicitar pentru ANAF.

Pasul 2: Nu figura tu nicăieri pe documente

Foarte important! Dacă ANAF-ul caută informații despre firma din Panama și te vede pe tine ca „owner” sau „director”, e gata. Ai intrat în vizor. Tu trebuie să fii „fantoma” — invizibil, fără urme directe. Firma offshore trebuie să fie cea care apare în acte, pe site, în contracte. Ea este „actorul” de pe scenă, nu tu. Asta înseamnă că nu trebuie să apari nicăieri în mod oficial.

Pasul 3: Angajează-ți un „domn băiat” local să fie fața firmei

Nu te băga tu la semnat acte, că e nasol. Mai bine găsești un nominee director din Panama care să figureze în acte, în timp ce tu faci mișcările din spate.
Acest tip de serviciu il poti gasi de exemplu pe Global One IBC.

Practic, „domnul băiat” e reprezentantul legal al firmei.

Ce înseamnă Nominee Director?

Simplu: e un tip (sau o firmă) care, pe hârtie, apare ca directorul firmei tale. Adică el e trecut în documentele oficiale — la stat, la registre, peste tot — în locul tău. Scopul? Să-ți țină numele și identitatea în secret, să nu apari tu direct acolo, că asta ar fi primul semnal roșu pentru ANAF sau oricine altcineva.

Power of Attorney (împuternicire legală)

Tu îi dai ăstuia o împuternicire oficială (un Power of Attorney, pe scurt POA) prin care îl autorizezi să semneze acte, să vorbească în numele firmei, să bage ștampila — dar doar când îi spui tu. Adică ăla nu face ce vrea el, ci execută ce îi zici tu. Nu-i nimic liber la decizii sau gestionare zilnică, e doar o marionetă legală.

Tu controlezi totul, dar nu apari

Chiar dacă pe hârtie nominee director-ul e șeful firmei, în realitate tu tragi sforile. E ca și cum ai avea un scut în față, care te protejează, dar tu ești acolo în spate, cu mâinile pe toate butoanele.

Apropo, dacă vrei extra full privacy, îți trebuie și un nominee shareholder. Nominee director-ul ascunde cine gestionează firma, dar dacă tu apari ca acționar, tot te pot lega de ea. Așa că dacă vrei să fii invizibil cu adevărat, ia-ți și nominee shareholder.

Pasul 4: Aflarea târzie: „Firma e a ta?! Ups, nu știam!”

După câteva luni, „îți dai seama” că firma offshore era de fapt a ta. Serios, n-ai știut că trebuie să aduci banii înapoi în România și să-i declari. E o neînțelegere de bună credință, nu-i așa?

De aici începe clasicul:

• faci bani din consultanță către firma offshore,
• faci cum faci sa ajungi cu impozit pe profit 0 la SRL-ul tau local
• în Panama impozitul pe venit e 0
• deci banii de consultanță sunt ai tăi... legal!

Dar statul român te vrea pe tine impozitând acei bani, doar că tu nu i-ai adus în țară. Și asta-i „problema”.

Pasul 5: Scoți banii „din Matrix” - și începe jocul deștepților

Acum începe partea faină, unde devii cu adevărat „băiatul ultra-deștept”:

• îți faci carduri de debit pe firma offshore și cheltuiești fără să dai socoteală,
• faci micro-cheltuieli insesizabile: restaurante, hoteluri, bilete de avion
• când sumele devin mari, scoți cash din țări non-UE (ca să nu lași urme în sistemul financiar european),
• faci transferuri și conversii de crypto din wallet în wallet până se pierde urma banilor.

Finalul? ANAF-ul... n-are ce verifica!

• Banii au fost cheltuiți de o firmă străină (nu ai nicio legătură oficială).
• Nu ești beneficiar oficial, pentru că nu apari în acte.
• Banii sunt făcuți de firma din Panama, deci n-ai ce să declari în România.
• Într-un eventual control, cel mult se poate discuta despre „intenția ta”, dar fără acte concrete și dovezi clare, e doar paranoia fiscală.

Concluzie: Nu-i ilegal să fii mai deștept decât statul

Ce fac băieții ultra-deștepți nu e neapărat ilegal. E doar prea bine gândit pentru nivelul actual de vigilență al ANAF.
Și cât timp statul continuă să-i pedepsească pe cei onești și să ignore pe cei „optimiști”, o să tot apară astfel de scheme.

Disclaimer: Acest articol nu constituie consultanță fiscală sau financiară. Informațiile prezentate sunt bazate pe surse proprii și experiență personală și nu reprezintă o garanție că acestea sunt sau vor fi aplicate efectiv. Textul are un scop exclusiv informativ și educativ. Pentru luarea deciziilor financiare sau fiscale importante, vă recomandăm să consultați un contabil sau un consultant autorizat. Autorul nu își asumă responsabilitatea pentru eventualele consecințe legale rezultate în urma aplicării informațiilor prezentate.

România funcționează de multe ori ca un stat bananier: legi schimbate peste noapte, taxe inventate din pix, promisiuni de digitalizare doar pe hârtie. În tot acest haos fiscal, există însă câteva găuri în zidul sistemului. Găuri făcute special ca să nu deranjeze pe „băieții deștepți” — corporații cu influență, firme cu acces la consultanți scumpi și clienți VIP care știu exact pe ce buton să apese.

Dar iată vestea bună: una dintre aceste portițe este 100% legală și disponibilă și pentru tine. Ai o firmă de IT, software, AI, SaaS, sau faci orice proiect tehnic unde inovezi ceva? Atunci ai șanse mari să o folosești. Și crede-mă, nu o să fie scoasă prea curând din Codul Fiscal — prea mulți „băieți deștepți” și-ar pune pilele în cap.

Există o portiță legală care îți poate înjumătăți impozitul pe profit dacă o folosești cum trebuie. Nu, nu vorbim de offshore-uri, Panama sau interpuși. Vorbim de ceva scris negru pe alb în Codul Fiscal, dar pe care doar consultanții care cer 10.000 euro/an o explică pe înțelesul tău.

Dacă ai firmă în IT, e foarte probabil ca o mare parte din ceea ce faci să se califice pentru facilități fiscale R&D (cercetare-dezvoltare). Doar că trebuie să știi cum s-o ambalezi și să o justifici corect.

📜 Legea exactă

Conform Codului Fiscal - Art. 20, ai dreptul la:

• Deducere suplimentară de 50% din cheltuielile eligibile pentru R&D (peste deducerea normală)
• Amortizare accelerată pentru echipamentele dedicate activităților de cercetare-dezvoltare

🔗 Text oficial – Art. 20 din Codul Fiscal

Plus Ordinul comun care stabilește normele:

🔗 ORDIN Nr. 1056/4435/2016 din 5 iulie 2016 - stabilește criterii și modul de documentare

Și ghidul de referință:

🔗 Manualul Frascati (OECD)

Rezumat final „ca la proști” – Ce trebuie să știi

Cum să plătești mai puțin impozit dacă faci cercetare-dezvoltare

Dacă firma ta face chestii noi, experimente sau proiecte de cercetare, poți să scazi din impozit o parte din cheltuielile astea.

Ce poți scădea?

• Banii dați pe salarii pentru oamenii care fac cercetare.
• Cheltuielile cu echipamentele și spațiile folosite.
• Materiale și servicii legate direct de proiect.
• Partea din chirie și utilități pentru cercetare.

Ce trebuie să faci?

• Să ai un proiect clar, cu ce vrei să faci nou.
• Să ții evidență cheltuielilor pe care le faci.
• Să înregistrezi corect totul în contabilitate.

🪜 Pas cu pas: Cum o aplici ca să fii blindat legal

Pentru ca schema să țină la un eventual control, trebuie:

1. Să ai un experiment clar definit. Ce încerci să afli? Ce testezi?
2. Să fie repetabil. Adică oricine, dacă urmează procesul tău, să poată obține rezultate similare.
3. Documentație completă. Proces, date, rezultate. Salvează tot.
4. Scop aplicativ. Adică la final trebuie să ai o soluție practică. Nu doar ai testat ca să vezi ce iese.

Practic, trebuie să arate ca un mic proiect științific. Nu te speria, nu trebuie să publici în Nature. Trebuie doar să demonstrezi că nu e o poveste inventată retroactiv.

💡 Exemplu simplu de calcul

Să zicem că ai o firmă care face 150.000 euro venituri și 100.000 euro cheltuieli (salarii, licențe, echipamente).

Dacă demonstrezi că acele 100.000 euro au fost cheltuite pe un proiect R&D, poți deduce încă 50% din ele, adică încă 50.000 euro.

Astfel:

• Venit = 150.000 euro
• Cheltuieli normale = 100.000 euro
• Deducere suplimentară = 50.000 euro
• Rezultatul fiscal = 0
• Impozit pe profit = 0

Statul a încasat zero, tu ai reinvestit banii în firmă. Legal, frumos și elegant.

🤖 Aplicăm teoria: Proiect AI pentru recomandări în e-commerce

🎯 Scopul

Dezvoltarea unui modul AI care analizează comportamentul userului și recomandă produse relevante automat.

🔍 Experimentul

1. Alegem 3 modele AI (XGBoost, GPT-4, KNN)
2. Setăm criterii de comparare: timp de răspuns, acuratețe, conversii
3. Aplicăm pe 1.000 utilizatori dintr-un magazin online demo

📝 Documentație:

• Fiecare model testat pe aceleași date
• Loguri de performanță salvate
• Rapoarte comparative generate

🧪 Rezultatul

Modelul GPT-4 are cele mai bune recomandări pentru produse peste 150 lei. Decidem să-l integrăm în platforma noastră.

✅ Exemplu Scop aplicativ:

• Crește valoarea medie a coșului
• Scade bounce rate
• Conversie crescută cu 14%

Total cheltuieli în proiect: 70.000 lei. Deducere suplimentară: 35.000 lei. Profit impozabil scăzut cu 35.000 lei.

🧠 Concluzie

Statul român a lăsat această portiță legală deschisă nu pentru că e generos, ci pentru că nu vrea să-și enerveze corporațiile care deja profită de ea. E ca o schemă pentru băieți deștepți, dar tu poți deveni unul din ei dacă joci legal și documentat.

Dacă ai firmă în IT și încă n-ai aplicat schema asta, ori nu știai, ori n-ai fost atent. Acum știi. Ia-ți un folder în Google Drive și începe să-ți faci primul experiment.

Disclaimer: Acest articol nu constituie consultanță fiscală sau financiară. Informațiile prezentate sunt bazate pe surse proprii și experiență personală și nu reprezintă o garanție că acestea sunt sau vor fi aplicate efectiv. Textul are un scop exclusiv informativ și educativ. Pentru luarea deciziilor financiare sau fiscale importante, vă recomandăm să consultați un contabil sau un consultant autorizat. Autorul nu își asumă responsabilitatea pentru eventualele consecințe legale rezultate în urma aplicării informațiilor prezentate.

Politicienii pare că doresc să devină acționar majoritar în firma ta — fără să contribuie cu nimic. Dacă ai o microîntreprindere sau un PFA, ai totuși câteva unelte la îndemână ca să nu devii doar un intermediar între clienți și ANAF. Iată cum să optimizezi legal, eficient și strategic.

1. Folosește-ți firma ca un portofel inteligent

Dacă ai microîntreprindere, plătești impozit pe venit, nu pe profit. Asta înseamnă că deductibilitatea cheltuielilor nu mai influențează direct taxarea. Poți cumpăra pe firmă aproape orice – chiar și mici de la Kaufland – fără să-ți bați capul că „nu e deductibil”.

Dar aici vine șmecheria: chiar dacă nu e deductibilă, cheltuiala tot iese din firmă. Adică nu mai scoți banii ca dividende, deci nu mai plătești 8% impozit pe dividende. Ce înseamnă asta?

Practic, ai un „cashback fiscal” de 8% pe orice cheltuială făcută direct din firmă, în loc să scoți banii și să-i cheltuiești personal după ce te-a taxat statul.

Atenție totuși: nu abuza și nu forța nota.

2. Transformă-ți apartamentul în sediu de firmă — și în sursă de venit legală

Dacă ai o firmă, poți face un contract de închiriere între tine (persoană fizică) și firma ta (juridic). Firma îți plătește chirie, tu declari venitul ca persoană fizică și plătești doar 8% impozit. Simplu și legal.

În 2025, plafonul de CASS pentru venituri din chirii este de 6 salarii minime brute pe an, adică 24.300 lei/an sau 2.025 lei/lună.

Dacă te încadrezi sub acest plafon lunar, nu plătești CASS deloc. Doar 8% impozit pe venit. Atât.

Ce înseamnă asta, în realitate?
În loc să scoți bani din firmă ca dividende și să plătești 16% impozit dividende, îi scoți ca chirie, și plătești doar 8% impozit.

Asta înseamnă un cashback fiscal de 8% pe acei bani. Firma îi cheltuie, tu îi încasezi, și statul ia mai puțin.

3. Dividende mai rar = CASS mai mic

Nu e obligatoriu să scoți dividende trimestrial sau anual.
Dacă le scoți o dată la doi ani, plătești CASS o singură dată, pe suma totală.

Și dacă scoți mulți bani, practic vei plăti CASS 10% doar la echivalentul a 12 sau 24 de salarii minime, o dată la 2 ani — în loc să plătești în fiecare an.

Exemplu simplu și eficient:
La final de 2025, faci AGA pentru T3, scoți tot profitul deja acumulat și îl virezi ca dividende.
➡ În 2026, trăiești liniștit tot anul din acei bani, pentru că i-ai scos legal și fiscal din timp.
➡ Pe persoană fizică, plătești CASS o singură dată pentru tot profitul — nu de două ori, cum ai face dacă ai scoate dividende și în 2025, și în 2026.

4. Ai și PFA? Folosește-l ca supapă de optimizare

Dacă ai PFA pe sistem real, e important să știi că poți plăti 10% impozit și 10% CASS, fără să mai plătești CAS de 25% — însă asta este valabil doar dacă veniturile tale nu depășesc pragul de 48.600 lei pe an.

Cum se calculează impozitul?
10% din suma obținută după ce din încasările totale scazi cheltuielile deductibile, contribuția la pensie și contribuția la sănătate.

De exemplu, dacă ai un PFA fără cheltuieli și venituri de exact 48.600 lei, vei plăti:

• 10% CASS
• plus 10% impozit pe venitul net (adică venitul total minus CASS),
  adică în în jur de 19% taxe totale.

Ca să optimizezi, limitează-ți veniturile până la plafonul de CAS (echivalentul a 12 salarii minime brute pe an). E perfect legal și îți ajută cashflow-ul.

5. Profită de beneficiile pentru salariați – chiar dacă tu ești salariatul

Poți oferi bonusuri neimpozabile în valoare de 300 de lei de:

• Crăciun, Paște, 8 Martie (pentru femei),
• 1 Iunie (dacă ai copii – 300 lei/copil),

Dacă ești angajat în propria firmă, poți beneficia de ele — legal.

6. Turismul intern și delegațiile sunt deductibile

Ai deplasări prin țară? Le poți trata ca delegații de serviciu și deconta:

• cazare,
• transport,
• diurnă.

Și da, în unele cazuri, poți transforma un city break în conferință de business. Legal, dar cu măsură.

7. Masă de protocol? Dă-i cu șampania Armand de Brignac pe notă!

Mesele de afaceri pot fi deductibile parțial, până la 2% din profitul contabil.

Totuși, dacă ești microîntreprindere, nu trebuie să-ți faci prea multe griji legat de această limită de 2% din profit, pentru că la micro impozitul se aplică pe venit, nu pe profit.

Așadar, deductibilitatea cheltuielilor nu influențează impozitul pe care îl plătești, ceea ce înseamnă că poți face astfel de cheltuieli fără să-ți complici prea mult calculele fiscale.

În plus, pentru că ești taxat pe venit și nu pe profit, banii cheltuiți direct din firmă scad suma pe care o vei scoate ca dividende, iar la dividendele în valoare de 16% practic ai un „cashback” de 16% pe acești bani cheltuiți — un bonus important în optimizarea fiscală.

8. Vrei să treci pe impozit pe profit? Vinde-ți sufletul firmei!

Dacă te gândești să treci de la micro la impozit pe profit, nu uita să vinzi tot ce ai pe persoană fizică către firmă. Da, exact: casa, terenul, locul de parcare, laptopul, dulapul, biroul — tot ce poți!

Scopul? Să te asiguri că firma nu va avea profit niciodată — cheltuiești pe ce ai nevoie, iar astfel reduci impozitul pe profit.

Asta e o manevră legală și eficientă de optimizare fiscală, dar bineînțeles, trebuie făcută cu cap.

9. Card de credit + eșalonare = cash flow smart

Fă-ți un card de credit la CEC Bank, care îți oferă 24 de rate fără dobândă. Orice taxe ai de plătit pe persoană fizică către stat, plătește-le prin ghiseul.ro cu cardul ăsta. Astfel, o plată mare de CASS, de exemplu, se poate eșalona pe 2 ani, fără dobândă.

Practic, în contextul inflației uriașe din statul bananier România, câștigi bani pentru că nu plătești imediat suma imensă, iar tu păstrezi cash flow-ul în buzunar.

10. Sfaturi avansate? Le discutăm privat.

Nu pot scrie tot public aici — unele tactici cer context, profil și consultanță individuală. Dacă vrei să discutăm mai profund, îmi poți scrie în privat.

În loc de concluzie:

Statul nu va avea niciodată grijă de banii tăi mai bine decât tine. Fii atent, fii legal, dar nu fi naiv. Optimizați, nu improvizați.

Disclaimer: Acest articol nu constituie consultanță fiscală sau financiară. Informațiile prezentate sunt bazate pe surse proprii și experiență personală și nu reprezintă o garanție că acestea sunt sau vor fi aplicate efectiv. Textul are un scop exclusiv informativ și educativ. Pentru luarea deciziilor financiare sau fiscale importante, vă recomandăm să consultați un contabil sau un consultant autorizat. Autorul nu își asumă responsabilitatea pentru eventualele consecințe legale rezultate în urma aplicării informațiilor prezentate.

You’ve been there.

You find the perfect video, try to download it... and what do you get? A weird .m3u8 file. No MP4. No playback. Just confusion.

We get it — it’s frustrating. That’s why we built a better way.

🚀 Introducing: Instant M3U8 to MP4 Conversion

No installs. No extensions. No waiting. Just your browser.

Paste a link. Get your MP4. That’s it.

Here’s why it hits different:

• ✅ 100% free — and always will be
• ✅ Unlimited conversions — as long as your browser can handle it
• ✅ No file size limits — works even for big videos
• ✅ Works in-browser — no downloads, no setup
• ✅ Lightning fast — converts in seconds

🔒 Privacy-First, No Exceptions

We don’t see your files. Everything happens locally, right inside your browser tab.

• No uploads
• No snooping
• No third-party servers
• Zero data exposure

You keep your files. We just help you convert them — fast.

📦 Got a .zip of the playlist files instead of a link?

No problem. Drop it in. You’ll still get an MP4.

Try it now → https://www.m3u8-to-mp4-converter.com/

And yes — it really is that simple.

JavaScript is often described as single-threaded, which means it executes one task at a time. But does this imply that every piece of code runs in complete isolation, with no ability to handle other tasks while waiting for asynchronous operations like HTTP responses or database requests? The answer is no! In fact, JavaScript’s event loop and promises allow it to handle asynchronous tasks efficiently while other code continues to run.

The truth is javascript is indeed single-threaded, however, misunderstanding how this works can lead to common pitfalls. One such trap is managing asynchronous operations like API requests, especially when trying to control access to shared resources without causing race conditions. Let's explore a real-world example and see how poor implementation can lead to serious bugs.

I encountered a bug in an application that required logging into a backend service to update data. Upon logging in, the app would receive an access token with a specified expiration date. Once this expiration date passed, we needed to re-authenticate before making any new requests to the update endpoint. The challenge arose because the login endpoint was throttled to a maximum of one request every five minutes, while the update endpoint needed to be called more frequently within that same five-minute window. It was critical for the logic to function correctly, yet the login endpoint was occasionally triggered multiple times within the five-minute interval, leading to the update endpoint failing to work. While there were times when everything functioned as expected, this intermittent bug presented a more serious risk, as it could give a false sense of security at first, making it seem like the system was operating properly.

To illustrate this example, we're using a very basic NestJS app that includes the following services:

• AppService: Acts as a controller to simulate two variants— the bad version, which sometimes works and sometimes doesn't, and the good version, which is guaranteed to always function properly.
• BadAuthenticationService: Implementation for the bad version.
• GoodAuthenticationService: Implementation for the good version.
• AbstractAuthenticationService: Class responsible for maintaining the shared state between the GoodAuthenticationService and BadAuthenticationService.
• LoginThrottleService: Class that simulates the throttling mechanism of the login endpoint for the backend service.
• MockHttpService: Class that helps simulate HTTP requests.
• MockAwsCloudwatchApiService: Simulates an API call to the AWS CloudWatch logging system.

I won't show the code for all these classes here; you can find it directly in the GitHub repository. Instead, I will focus specifically on the logic and what needs to be changed for it to work correctly.

The Bad Approach:

@Injectable()
export class BadAuthenticationService extends AbstractAuthenticationService {
  async loginToBackendService() {
    this.loginInProgress = true; // this is BAD, we are inside a promise, it's asynchronous. it's not synchronous, javascript can execute it whenever it wants

    try {
      const response = await firstValueFrom(
        this.httpService.post(`https://backend-service.com/login`, {
          password: 'password',
        }),
      );

      return response;
    } finally {
      this.loginInProgress = false;
    }
  }

  async sendProtectedRequest(route: string, data?: unknown) {
    if (!this.accessToken) {
      if (this.loginInProgress) {
        await new Promise((resolve) => setTimeout(resolve, 1000));
        return this.sendProtectedRequest(route, data);
      }

      try {
        await this.awsCloudwatchApiService.logLoginCallAttempt();
        const { data: loginData } = await this.loginToBackendService();
        this.accessToken = loginData.accessToken;
      } catch (e: any) {
        console.error(e?.response?.data);
        throw e;
      }
    }

    try {
      const response = await firstValueFrom(
        this.httpService.post(`https://backend-service.com${route}`, data, {
          headers: {
            Authorization: `Bearer ${this.accessToken}`,
          },
        }),
      );

      return response;
    } catch (e: any) {
      if (e?.response?.data?.statusCode === 401) {
        this.accessToken = null;
        return this.sendProtectedRequest(route, data);
      }
      console.error(e?.response?.data);
      throw e;
    }
  }
}

Why This Is a Bad Approach:

In the BadAuthenticationService, the method loginToBackendService sets this.loginInProgress to true when initiating a login request. However, since this method is asynchronous, it does not guarantee that the login status will be updated immediately. This could lead to multiple concurrent calls to the login endpoint within the throttling limit.

When sendProtectedRequest detects that the access token is absent, it checks if a login is in progress. If it is, the function waits for a second and then retries. However, if another request comes in during this time, it can trigger additional login attempts. This can lead to multiple calls to the login endpoint, which is throttled to allow only one call every minute. As a result, the update endpoint may fail intermittently, causing unpredictable behavior and a false sense of security when the system appears to be functioning properly at times.

In summary, the problem lies in the improper handling of asynchronous operations, which leads to potential race conditions that can break the logic of the application.

The Good Approach:

@Injectable()
export class GoodAuthenticationService extends AbstractAuthenticationService {
  async loginToBackendService() {
    try {
      const response = await firstValueFrom(
        this.httpService.post(`https://backend-service.com/login`, {
          password: 'password',
        }),
      );

      return response;
    } finally {
      this.loginInProgress = false;
    }
  }

  async sendProtectedRequest(route: string, data?: unknown) {
    if (!this.accessToken) {
      if (this.loginInProgress) {
        await new Promise((resolve) => setTimeout(resolve, 1000));
        return this.sendProtectedRequest(route, data);
      }

      // Critical: Set the flag before ANY promise call
      this.loginInProgress = true;

      try {
        await this.awsCloudwatchApiService.logLoginCallAttempt();
        const { data: loginData } = await this.loginToBackendService();
        this.accessToken = loginData.accessToken;
      } catch (e: any) {
        console.error(e?.response?.data);
        throw e;
      }
    }

    try {
      const response = await firstValueFrom(
        this.httpService.post(`https://backend-service.com${route}`, data, {
          headers: {
            Authorization: `Bearer ${this.accessToken}`,
          },
        }),
      );

      return response;
    } catch (e: any) {
      if (e?.response?.data?.statusCode === 401) {
        this.accessToken = null;
        return this.sendProtectedRequest(route, data);
      }
      console.error(e?.response?.data);
      throw e;
    }
  }
}

Why This Is a Good Approach:

In the GoodAuthenticationService, the loginToBackendService method is structured to handle the login logic efficiently. The key improvement is the management of the loginInProgress flag. It is set after confirming that an access token is absent and before any asynchronous operations begin. This ensures that once a login attempt is initiated, no other login calls can be made concurrently, effectively preventing multiple requests to the throttled login endpoint.

Demo Instructions

Clone the Repository:

git clone https://github.com/zenstok/nestjs-singlethread-trap.git

Install the Necessary Dependencies:

cd nestjs-singlethread-trap
npm install

Run the Application:

npm run start

Simulate requests:

• To simulate two requests with the bad version, call:

http://localhost:3000/simulate-2-requests-bad-version

• To simulate two requests with the good version, call:

http://localhost:3000/simulate-2-requests-good-version

Conclusion: Avoiding JavaScript's Single-Threaded Pitfalls

While JavaScript is single-threaded, it can handle asynchronous tasks like HTTP requests efficiently using promises and the event loop. However, improper handling of these promises, particularly in scenarios involving shared resources (like tokens), can lead to race conditions and duplicate actions.

The key takeaway is to synchronize asynchronous actions like logins to avoid such traps. Always ensure that your code is aware of ongoing processes and handles requests in a way that guarantees proper sequencing, even when JavaScript is multitasking behind the scenes.

If you haven't already joined the Rabbit Byte Club, now is your chance to hop into a thriving community of software enthusiasts, tech founders, and non-tech founders. Together, we share knowledge, learn from each other, and prepare to build the next big startup. Join us today and be part of an exciting journey towards innovation and growth!

Hey, folks! Have you ever wondered if it's possible to send a file of unlimited size to your users, all while giving them real-time feedback during the download process? Well, today, we're diving into exactly that. Let’s explore how we can achieve this in NestJS using one of Node.js's most powerful features—Streams.

In this guide, I’m not just going to show you how to download files of unlimited size—I’ll also walk you through the magic of streams and how they really work behind the scenes.

The Scenario: A Manager's Report Download

Imagine a manager needs to download a dynamically generated report containing invoice data, based on a user-defined date range. The twist? We have no idea how big the report will be because the user sets the parameters. We need to stream this data efficiently without overwhelming our server’s memory. Here’s where chunked transfer encoding comes into play. By setting the Transfer-Encoding header to chunked (learn more here), we can send the data in chunks, eliminating the need for a predetermined file size.

But wait—how do we handle massive file sizes? The answer is simple: Node.js Streams.

Why Not Buffers?

At first, you might think we can handle this using file buffers. However, buffers are limited by the server’s memory. If you’re dealing with large files, buffers will quickly hit a ceiling. Instead, we turn to streams, which are the backbone of Node.js when it comes to data management.

Streams process data in small chunks, sending it out without holding everything in memory. This way, we can handle "infinite" files, or at least ones large enough to blow your mind.

What are streams?

Streams in Node.js are powerful objects that let us process batches of data without loading everything into memory. Instead of holding the entire dataset, streams process chunks of data and pass them along as they go. So, because they don’t hold all the data in memory, they can handle massive files. But where do these chunks go? They’re passed on to other streams!

There are two key types of streams you’ll be working with in Node.js: readable and writable streams.

Let’s break it down with an example:

If you’re reading a file’s contents, you’d use the fs.createReadStream method. This returns a readable stream object, which gives you chunks of the file’s data bit by bit.

But once you’ve read the data, how do you send it to the user as an HTTP response?

Well, here’s the cool part: in Node.js, the response object itself is a writable stream. What does that mean? It means you can take the data you’re reading from the readable stream and send it directly to the writable stream (the HTTP response) using a method called .pipe.

With just a few lines of code, the .pipe method lets you effortlessly stream file content directly to the client as an HTTP response—no need to worry about memory limits or large file sizes. Simple, right?

The Three Methods to Stream Large Files in NestJS

We’ll walk through three different ways to stream large files in NestJS, ranging from basic to more advanced, giving you both performance and flexibility.

1. The Easy Version: Node.js Out of the Box
2. The Performant Version: String-Based Stream Chunks
3. The Buffer Version: For When Precision Matters

1. The Easy Version

In this approach, we use Node.js's built-in interfaces to handle the heavy lifting for us. Here’s what the controller code looks like:

@Get('/simple')
@Header('Content-Disposition', `attachment; filename="bigJson.json"`)
@Header('Content-Type', 'application/json')
@Header('Transfer-Encoding', 'chunked')
getBigFileSimple(@Res() res: Response) {
  this.simpleService.getBigFile(res);
}

The @Header decorators set the file to be an attachment, specify the content type, and enable chunked transfer encoding. This allows us to send the file in parts without knowing its total size upfront.

In our service, we have the following method:

@Injectable()
export class SimpleService {
  constructor(private readonly jsonService: JsonService) {}

  getBigFile(res: Response) {
    return this.jsonService.createBigJsonFileStream().pipe(res);
  }
}

With just one line of code, we pipe the file stream to the response! This elegant solution leverages Node.js's stream piping, making it both simple and powerful.

Now, you might wonder—what exactly is this createBigJsonFileStream() method doing?

@Injectable()
export class JsonService {
  createBigJsonFileStream(rowsLength = 25000000): Readable {
    let currentRow = 1;
    rowsLength = this.getRandomLengthFromRange(rowsLength / 2, rowsLength);

    const stream = new Readable({
      read() {
        if (currentRow === 1) {
          this.push('[');
          this.push(`{"id":${currentRow},"name":"element${currentRow}"},`);
        } else if (currentRow === rowsLength) {
          this.push(`{"id":${currentRow},"name":"element${currentRow}"}`);
          this.push(']');
          this.push(null);
        } else {
          this.push(`{"id":${currentRow},"name":"element${currentRow}"},`);
        }
        currentRow++;
      },
    });

    return stream;
  }

  private getRandomLengthFromRange(min: number, max: number): number {
    return Math.floor(Math.random() * (max - min + 1) + min);
  }
}

In this case, we’re not serving a file from disk. Remember, the scenario we’re addressing is where a manager wants to download a report, choosing their own start and end dates. This means we need to dynamically generate the file based on the user's request. And how do we do that? You guessed it—with streams!

What’s happening here?

We’re creating a readable stream using Node.js’s Readable constructor (documentation here). We’re keeping things simple by focusing on the required read() method.

Here’s how it works: every time the stream has data to offer, the read() method is called. As long as we keep pushing data into the stream (and don’t push null), the stream will stay active and keep sending data.

In this example, we’ve set a rowsLength—the total number of rows our JSON file will have. (Note: We’re dynamically altering the rowsLength to simulate the manager selecting a start and end date, creating a random value to represent the report’s size.) Based on this, we push one row at a time into the stream. It’s that simple! We’re dynamically creating a huge JSON file, sending data chunk by chunk, and handling it all seamlessly without loading everything into memory.

2. The Performant Version: String-Based Chunks

In this approach, we fine-tune performance by manually controlling how the data is written to the response stream:

@Injectable()
export class PerformantService {
  constructor(private readonly jsonService: JsonService) {}

  getBigFile(res: Response) {
    const jsonStream = this.jsonService.createBigJsonFileStream();
    jsonStream.setEncoding('utf-8');
    let chunkSize = 0;
    let bigChunk = '';

    jsonStream.on('data', (chunk: string) => {
      bigChunk += chunk;
      chunkSize++;
      if (chunkSize === 1000) {
        const writable = res.write(bigChunk);
        if (!writable) {
          jsonStream.pause();
        }
        bigChunk = '';
        chunkSize = 0;
      }
    });

    res.on('drain', () => {
      jsonStream.resume();
    });

    jsonStream.on('error', (err) => {
      console.error(err);
      res.end();
    });

    jsonStream.on('end', () => {
      if (bigChunk.length) {
        res.write(bigChunk);
      }
      res.end();
    });
  }
}

So, what do we have here?

What do we have here? Well, the logic might look a bit complex, but that's because we’re handling the process of writing to the res writable stream manually. Why? We believe that our approach is faster than simply piping the stream.

So, how do we do it? First, we set the encoding of our JSON stream to UTF-8 using jsonStream.setEncoding('utf-8');. This ensures that instead of receiving default Buffer objects from the stream, we get data as UTF-8 encoded strings.

Next, we define two variables: chunkSize, initialized to 0, and bigChunk, an empty string. The cool thing about streams is that we can listen to events on them. For example, the data event gives us a data chunk every time the stream is read. But when is read called? It's triggered as soon as the readable stream is instantiated and continues until all the data is read—pretty cool, right? We know the stream has finished reading when we hit the end event.

Now, when data arrives from the stream, we want to be efficient. Instead of sending small chunks to the res stream, we batch 1,000 chunks together and send them as one large chunk to our HTTP response, which is itself a writable stream. But wait—why does the write method return a boolean? This introduces us to a crucial concept in Node.js streams: backpressure. As Node.js describes it, “backpressure occurs when data builds up behind a buffer during data transfer.” In simpler terms, it means the res stream is telling us, "Slow down! I can't keep up!"" The solution? We stop sending data! This is done by calling jsonStream.pause(), which halts the stream from reading further.

But what happens next? Now, we need to listen for another stream event—this time on the res writable stream. We need the stream to signal when it has recovered from the backpressure. This is where the "drain" event comes in. The "drain" event is emitted when it’s appropriate to resume writing data to the stream. So, once we catch this event, we simply resume reading from our big JSON stream!

Finally, when the JSON stream reaches the end event, we check if there’s any leftover data in bigChunk and write it to the res stream. After that, we call res.end() to signal that the response is complete.

And just like that, we’ve manually controlled how the data flows through the streams, handled backpressure, and delivered a dynamic file as a response!

3. The Buffer Version: Chunking with Buffers

For a more complex scenario, say we want to send large buffer chunks. Here's how we can handle it:

@Injectable()
export class BufferService {
  constructor(private readonly jsonService: JsonService) {}

  getBigFile(res: Response) {
    const jsonStream = this.jsonService.createBigJsonFileStream();

    const sendingChunkSize = 50 * 1024 * 1024; // 50 MiBs, Make sure to set the sending chunk size larger than the chunk buffer size to avoid unnecessary iterations in the while loop.
    let currentChunkSize = 0;
    let sendingChunk = Buffer.alloc(sendingChunkSize);

    jsonStream.on('data', (chunk: Buffer) => {
      while (chunk.byteLength > 0) {
        const availableSpace = sendingChunkSize - currentChunkSize;

        if (chunk.byteLength <= availableSpace) {
          // If the chunk fits within the remaining space
          chunk.copy(sendingChunk, currentChunkSize);
          currentChunkSize += chunk.byteLength;
          break;
        }

        // Fill the remaining space in the sendingChunk
        chunk.subarray(0, availableSpace).copy(sendingChunk, currentChunkSize);
        currentChunkSize += availableSpace;

        // Send the filled buffer
        const writable = res.write(sendingChunk);

        if (!writable) {
          jsonStream.pause();
        }

        // Reset for the next chunk
        sendingChunk = Buffer.alloc(sendingChunkSize);
        currentChunkSize = 0;
        chunk = chunk.subarray(availableSpace); // Process the rest of the chunk
      }
    });

    res.on('drain', () => {
      jsonStream.resume(); // Resume when writable
    });

    jsonStream.on('end', () => {
      // Send any remaining data that hasn't been flushed
      if (currentChunkSize > 0) {
        res.write(sendingChunk.subarray(0, currentChunkSize));
      }
      res.end();
    });

    jsonStream.on('error', (err) => {
      console.error(err); // Log error for debugging
      res.end();
    });
  }
}

Oh no, what’s going on here? It looks so complicated!

Well, that’s because it is a bit tricky! But here’s the backstory: we received a request from our boss to send file downloads in chunks of 50 MiB, because he has blazing-fast internet, he wants to take full advantage of it.

So, what’s the plan?

We start by setting our sending chunk size to 50 MiB. Next, we initialize a currentChunkSize variable to 0 and create a new buffer object, allocating exactly 50 MiB of memory.

Now, here’s where it gets interesting. Since we’re using fixed-size buffers, we need to ensure that all the JSON data fits perfectly within the allocated space. To do this, we calculate the available space in the current sending chunk. As long as the JSON chunk fits within the remaining space, we copy it to the sending chunk and update the currentChunkSize:

chunk.copy(sendingChunk, currentChunkSize);
currentChunkSize += chunk.byteLength;

The copy() method copies the bytes from the chunk buffer into sendingChunk, starting at the currentChunkSize (which marks the first free byte in the buffer).

What if the available space is larger than the JSON chunk?

This is where things get a bit messy! In this case, we need to extract exactly the right number of bytes from the JSON chunk to fill the available space in the sending chunk. Once it’s perfectly full, we send the chunk to the HTTP response.

After that, we reset the sendingChunk to a fresh buffer and set currentChunkSize back to 0.

But what about the rest of the JSON chunk?

Good question! Any remaining data in the JSON chunk is processed in the next iteration of our loop. The loop ensures that this remaining data is added to the new sendingChunk. This loop continues as long as the JSON chunk is larger than the available space in the buffer.

Technically, we could set the buffer size to send chunks as small as 1 byte to the response stream, but that would be incredibly inefficient. So, to avoid unnecessary iterations in the while loop, it’s important to set a reasonable chunk size.

Demo

For the demo, let's git clone the project here. After cloning, install the dependencies using npm install, and then run the project with npm run start.

On the index page, you’ll find a tutorial that explains how to call each version in action, as shown in the screenshot below:

Conclusion

By leveraging the power of Node.js streams, we can deliver files of virtually any size without consuming large amounts of memory. Whether you're aiming for simplicity, performance, or handling large buffer sizes, these approaches have you covered.

I hope this guide helped you understand how to work with large file downloads in NestJS. Have any ideas or topics you'd like me to cover next? Drop a comment! And don’t forget to subscribe to my newsletter on rabbitbyte.club for more tips!

Hello everyone,

Welcome to the final episode of our three-part series on token management in a NestJS + React application. In the first two posts, we walked through the process of implementing refresh token logic by storing tokens in local storage. Today, we’ll advance to a more secure method by implementing HTTP-only cookies for refresh tokens.

Why Use HTTP-Only Cookies?

HTTP-only cookies allow us to store sensitive data, such as refresh tokens, in a way that cannot be accessed by JavaScript. This means that even if there are vulnerabilities in your code or third-party libraries, a hacker won't be able to retrieve the refresh token.

However, even with HTTP-only cookies, there's still a risk of requests being made on behalf of the user through XSS attacks. The key advantage is that hackers will not be able to access the value of the refresh token directly; they would need to execute targeted XSS attacks on the application's endpoints, which requires prior knowledge of the system.

Why Not Store Both Access and Refresh Tokens in HTTP-Only Cookies?

By keeping the access token out of cookies, we protect against CSRF (Cross-Site Request Forgery) attacks. To mitigate XSS attacks, we set a short expiry time on the access token, limiting the damage even if it’s compromised.

Should We Worry About CSRF on the /refresh-tokens Endpoint?

Not really. Since this endpoint doesn’t compromise the system or user data, CSRF attacks here are less of a concern.

Enhancing Security: Hashing Refresh Tokens

To further improve security, we also hash the refresh tokens in the database. We use a hashing algorithm without salt, allowing us to reproduce the same hash for previously used tokens to check if they have been blacklisted. With this improvement, in case of database leaks, the hacker will not be able to read any refresh tokens!

Getting Started

To begin, ensure you've completed the guides in Part 1 and Part 2 for app installation. Afterward, follow these steps to implement the necessary changes.

If you want to jump straight into the code, you can check out the repository here on the "part-3" branch.

Step 1: Define Cookie Configuration and Helper Function

First, set up a cookie configuration and create a helper function to extract the refresh token from cookies:

import { Request } from 'express';

export const cookieConfig = {
  refreshToken: {
    name: 'refreshToken',
    options: {
      path: '/', // For production, use '/auth/api/refresh-tokens'. We use '/' for localhost in order to work on Chrome.
      httpOnly: true,
      sameSite: 'strict' as 'strict',
      secure: true,
      maxAge: 1000 * 60 * 60 * 24 * 30, // 30 days; must match Refresh JWT expiration.
    },
  },
};

export const extractRefreshTokenFromCookies = (req: Request) => {
  const cookies = req.headers.cookie?.split('; ');
  if (!cookies?.length) {
    return null;
  }

  const refreshTokenCookie = cookies.find((cookie) =>
    cookie.startsWith(`${cookieConfig.refreshToken.name}=`)
  );

  if (!refreshTokenCookie) {
    return null;
  }

  return refreshTokenCookie.split('=')[1] as string;
};

Step 2: Enable CORS to Accept Cookies

Ensure the CORS policy allows credentials so that our backend can receive cookies from the frontend:

app.enableCors({ origin: true, credentials: true }); // Set the correct origin for production.

Step 3: Update the Token Generation Method

Modify the generateTokenPair method to set the refresh token as an HTTP-only cookie whenever it's called:

async generateTokenPair(
  user: Express.User,
  res: Response,
  currentRefreshToken?: string,
  currentRefreshTokenExpiresAt?: Date,
) {
  const payload = { sub: user.id, role: user.role };

  res.cookie(
    cookieConfig.refreshToken.name,
    await this.generateRefreshToken(
      user,
      currentRefreshToken,
      currentRefreshTokenExpiresAt,
    ),
    {
      ...cookieConfig.refreshToken.options,
    },
  );

  return {
    access_token: this.jwtService.sign(payload), // JWT module is configured in auth.module.ts for access token.
  };
}

Step 4: Update JWT Strategy to Use Cookies

Modify the refresh JWT strategy to retrieve the token from cookies instead of using bearer token authentication:

jwtFromRequest: ExtractJwt.fromExtractors([
  (req: Request) => extractRefreshTokenFromCookies(req),
]),

Step 5: Adjust Token Handling and Add Cookie Clearing Endpoint

When calling the /refresh-tokens endpoint, the token should now be extracted from the HTTP-only cookie, replacing the previous method of using Bearer authorization.

Additionally, we must implement a /clear-auth-cookie endpoint to remove the cookie. This endpoint should be invoked during the logout action on the frontend. The reason for this is that HTTP-only cookies cannot be cleared programatically from the frontend, so this ensures the user is properly logged out.

@Public()
@UseGuards(JwtRefreshAuthGuard)
@Post('refresh-tokens')
refreshTokens(
  @Req() req: Request,
  @Res({ passthrough: true }) res: Response,
) {
  if (!req.user) {
    throw new InternalServerErrorException();
  }

  return this.authRefreshTokenService.generateTokenPair(
    (req.user as any).attributes,
    res,
    extractRefreshTokenFromCookies(req) as string,
    (req.user as any).refreshTokenExpiresAt,
  );
}

@Public()
@Post('clear-auth-cookie')
clearAuthCookie(@Res({ passthrough: true }) res: Response) {
  res.clearCookie(cookieConfig.refreshToken.name);
}

Step 6: Update Frontend Logic

Now regarding the frontend project, we will actually simplify the logic a little bit.

1. Remove Refresh Token from Local Storage:

Clear any references to the refresh token in the AuthClientStore class:

const ACCESS_TOKEN_KEY = "rabbit.byte.club.access.token";

class AuthClientStore {
  static getAccessToken() {
    return localStorage.getItem(ACCESS_TOKEN_KEY);
  }

  static setAccessToken(token: string) {
    localStorage.setItem(ACCESS_TOKEN_KEY, token);
  }

  static removeAccessToken(): void {
    localStorage.removeItem(ACCESS_TOKEN_KEY);
  }
}

export default AuthClientStore;

2. Update Request Methods:

Remove the refreshToken variable from the sendProtectedRequest method, as it's no longer needed.

const sendProtectedRequest = (
  method: ApiMethod,
  path: string,
  // eslint-disable-next-line
  body?: any,
  init?: RequestInit,
) => {
  const authToken = AuthClientStore.getAccessToken();
  if (!authToken) {
    throw new Error("No auth token found");
  }

  return sendRequest(method, path, body, authToken, init);
};

3. Include Credentials in Requests:

Very important: Update the login and refresh token API integration methods to include credentials, ensuring that cookies can be set and sent correctly.

const login = async (email: string, password: string) => {
 const response = await sendRequest(
   ApiMethod.POST,
   routes.auth.login,
   {
     email,
     password,
   },
   undefined,
   { credentials: "include" }, // Required update
 );

 AuthClientStore.setAccessToken(response.access_token);

 return response;
};

const refreshTokens = async () => {
 clearTimeout(timeout);
 if (!debouncedPromise) {
   debouncedPromise = new Promise((resolve, reject) => {
     debouncedResolve = resolve;
     debouncedReject = reject;
   });
 }

 timeout = setTimeout(() => {
   const executeLogic = async () => {
     const response = await sendRequest(
       ApiMethod.POST,
       routes.auth.refreshTokens,
       undefined,
       undefined,
       { credentials: "include" }, // Required update
     );

     AuthClientStore.setAccessToken(response.access_token);
   };

   executeLogic().then(debouncedResolve).catch(debouncedReject);

   debouncedPromise = null;
 }, 200);

 return debouncedPromise;
};

4. Define Clear Auth Cookie API Call:

Implement the clearAuthCookie API call:

const clearAuthCookie = () => {
  return sendRequest(
    ApiMethod.POST,
    routes.auth.clearAuthCookie,
    undefined,
    undefined,
    { credentials: "include" },
  );
};

5. Call clearAuthCookie on Logout:

Ensure the auth cookie is cleared on logout:

const logout = () => {
  AuthClientStore.removeAccessToken();
  return clearAuthCookie();
};

And that's it! With these steps, the refresh token logic is now integrated into an HTTP-only cookie. You can proceed to Part 2 of the tutorial to test the solution.

If you'd like me to cover more interesting topics about the node.js ecosystem, feel free to leave your suggestions in the comments section. Don't forget to subscribe to my newsletter on rabbitbyte.club for updates!

Hello, guys!

On the premise that our App is immune to XSS attacks, we will store both access & refresh tokens in the local storage. For this, we will use React which escapes any values embedded in JSX before rendering them, greatly helping us in countering XSS attacks.

This is the second episode in our three-part series on implementing refresh tokens. In our previous article, we explored how to implement refresh tokens in NestJS. Be sure to check it out if you're looking to easily run the demo from this tutorial.

While storing both access and refresh tokens in local storage is convenient, it does come with security risks. Even with robust XSS attack prevention, there's still a vulnerability to attacks via third-party libraries. Fortunately, in the final episode of this series, we'll demonstrate how to securely store refresh tokens using HTTP-only cookies, which enhances security.

Implementation overview

To keep the application straightforward, we've implemented only the core features necessary to demonstrate the functionality. Here’s what we aim to achieve and some potential caveats to be aware of:

Objectives:

1. Persistent Authentication: We want the user to remain authenticated even after refreshing the page.
2. Automatic Logout: The user should be logged out automatically when an API endpoint returns a 401 Unauthorized response.
3. Seamless Data Access: When calling a protected endpoint, the app should retrieve data if a valid refresh token exists. If the first request returns a 401, the app should attempt to refresh the tokens. Only if the subsequent request after refreshing also fails with a 401 should the user be logged out.

Potential Caveat:

A notable issue is that the refresh token endpoint call invalidates the previous refresh token. This can create a problem if /auth/refresh-tokens is called more than once concurrently, as it may lead to inconsistencies or failures in token handling. To mitigate this, we must ensure that the refresh token is not requested multiple times concurrently, even if multiple protected requests are made across the app.

If you want to jump directly to the GitHub repo to see how we did it, you can check it out here.

Getting started

Since the authentication state is a global concept in the app, we need to ensure that every component can access this state. The best way to manage this is by using React Context to define a global context provider. We will look into this later in the tutorial.

First, we define a class responsible for managing the manipulation of local storage keys for access and refresh tokens:

const ACCESS_TOKEN_KEY = "rabbit.byte.club.access.token";
const REFRESH_TOKEN_KEY = "rabbit.byte.club.refresh.token";

class AuthClientStore {
  static getAccessToken() {
    return localStorage.getItem(ACCESS_TOKEN_KEY);
  }

  static setAccessToken(token: string) {
    localStorage.setItem(ACCESS_TOKEN_KEY, token);
  }

  static removeAccessToken(): void {
    localStorage.removeItem(ACCESS_TOKEN_KEY);
  }

  static getRefreshToken() {
    return localStorage.getItem(REFRESH_TOKEN_KEY);
  }

  static setRefreshToken(token: string) {
    localStorage.setItem(REFRESH_TOKEN_KEY, token);
  }

  static removeRefreshToken(): void {
    localStorage.removeItem(REFRESH_TOKEN_KEY);
  }
}

export default AuthClientStore;

Next, we define a useApi hook, which abstracts how requests are sent to our app server, both protected and unprotected:

import AuthClientStore from "../../auth/client-store/auth-client-store.ts";
import { ApiMethod } from "../types.ts";

const apiUrl = import.meta.env.VITE_API_BASE_URL as string;

const sendRequest = (
  method: ApiMethod,
  path: string,
  // eslint-disable-next-line
  body?: any,
  authToken?: string | null,
  init?: RequestInit,
) => {
  return fetch(apiUrl + path, {
    method,
    ...(body && { body: JSON.stringify(body) }),
    ...init,
    headers: {
      "Content-Type": "application/json",
      ...(authToken && { Authorization: `Bearer ${authToken}` }),
      ...init?.headers,
    },
  }).then((response) => {
    if (response.status >= 400) {
      throw response;
    }
    return response.json();
  });
};

const sendProtectedRequest = (
  method: ApiMethod,
  path: string,
  // eslint-disable-next-line
  body?: any,
  useRefreshToken = false,
  init?: RequestInit,
) => {
  const authToken = useRefreshToken
    ? AuthClientStore.getRefreshToken()
    : AuthClientStore.getAccessToken();
  if (!authToken) {
    throw new Error("No auth token found");
  }

  return sendRequest(method, path, body, authToken, init);
};

export const useApi = () => {
  return { sendRequest, sendProtectedRequest };
};

Please note that the sendProtectedRequest method accepts an optional useRefreshToken parameter. This is used exclusively by routes that refresh the token, as they require the refresh token for bearer authentication. In all other cases, the default behavior is to use the access token.

Now we need to define a useAuthApi hook where the magic happens.

First, we will use useApi hook from which we need to call sendRequest and sendProtectedRequest methods:

export const useAuthApi = () => {
  const { sendRequest, sendProtectedRequest } = useApi();
}

Implementing Authentication: Login, Logout, and Token Refresh

Now, let's define the login function, which, upon successful authentication, will set the access and refresh tokens in the local storage.

export const useAuthApi = () => {
  const { sendRequest, sendProtectedRequest } = useApi();

  const login = async (email: string, password: string) => {
    const response = await sendRequest(ApiMethod.POST, routes.auth.login, {
      email,
      password,
    });

    AuthClientStore.setAccessToken(response.access_token);
    AuthClientStore.setRefreshToken(response.refresh_token);

    return response;
  };
}

Next, the logout function is straightforward: it simply removes the access and refresh tokens from local storage.

export const useAuthApi = () => {
  const { sendRequest, sendProtectedRequest } = useApi();

  const login = async (email: string, password: string) => {
    const response = await sendRequest(ApiMethod.POST, routes.auth.login, {
      email,
      password,
    });

    AuthClientStore.setAccessToken(response.access_token);
    AuthClientStore.setRefreshToken(response.refresh_token);

    return response;
  };

  const logout = () => {
    AuthClientStore.removeAccessToken();
    AuthClientStore.removeRefreshToken();
  };
}

An essential method to define is refreshTokens, which has a simple logic similar to the login function:

const refreshTokens = async () => {
  const response = await sendProtectedRequest(
    ApiMethod.POST,
    routes.auth.refreshTokens,
    undefined,
    AuthClientStore.getRefreshToken(),
  );

  AuthClientStore.setAccessToken(response.access_token);
  AuthClientStore.setRefreshToken(response.refresh_token);
};

Note that because the refresh tokens endpoint requires the refresh token as an authentication method, we pass the refresh token as a parameter to sendProtectedRequest so it uses the refresh token as the bearer instead of the default access token used for other requests.

Is this all we need for the refreshTokens method? Well, keep in mind that each call to refresh the access token will invalidate the previous refresh tokens. So, if two parts of the app concurrently need to refresh the access token, one request might fail because the first request will invalidate the refresh token being used. Therefore, it's crucial to ensure this method is called only once. To manage this logic efficiently, we need to decorate this method a little bit.

Debouncing Refresh Tokens Requests and Managing Authentication State

To handle cases where multiple parts of the app might concurrently call the refresh tokens method, we need to debounce these calls so that only one request is made. We also need to ensure that each caller receives the same access and refresh token pair. Here's how we achieve this:

First, we define some variables outside of the hook to manage the debounce logic:

/*
 * These variables are used to debounce the refreshTokens function
 */
let debouncedPromise: Promise<unknown> | null = null;
let debouncedResolve: (...args: unknown[]) => void;
let debouncedReject: (...args: unknown[]) => void;
let timeout: number;

Now, we update the refreshTokens method to include debouncing:

const refreshTokens = async () => {
  clearTimeout(timeout);
  if (!debouncedPromise) {
    debouncedPromise = new Promise((resolve, reject) => {
      debouncedResolve = resolve;
      debouncedReject = reject;
    });
  }

  timeout = setTimeout(() => {
    const executeLogic = async () => {
      const response = await sendProtectedRequest(
        ApiMethod.POST,
        routes.auth.refreshTokens,
        undefined,
        AuthClientStore.getRefreshToken(),
      );

      AuthClientStore.setAccessToken(response.access_token);
      AuthClientStore.setRefreshToken(response.refresh_token);
    };

    executeLogic().then(debouncedResolve).catch(debouncedReject);

    debouncedPromise = null;
  }, 200);

  return debouncedPromise;
};

Here’s how it works:

• We clear the timeout whenever a new caller invokes this method within a 200ms window, effectively debouncing the calls.
• The debouncedPromise ensures that all callers receive the same promise, which resolves or rejects when the token refresh logic completes.
• After processing, debouncedPromise is reset to handle new calls later.

Next, we define a method that acts as a gatekeeper for protected API routes. It attempts a request and, if it fails with a 401 (Unauthorized) error, refreshes the access token and retries the request:

const sendAuthGuardedRequest = async (
  userIsNotAuthenticatedCallback: () => void,
  method: ApiMethod,
  path: string,
  body?: any,
  init?: RequestInit,
) => {
  try {
    return await sendProtectedRequest(method, path, body, undefined, init);
  } catch (e) {
    if (e?.status === 401) {
      try {
        await refreshTokens();
      } catch (e) {
        userIsNotAuthenticatedCallback();
        throw e;
      }
      return await sendProtectedRequest(method, path, body, undefined, init);
    }

    throw e;
  }
};

The userIsNotAuthenticatedCallback parameter allows the authentication context provider to update the global auth state, which any component in the app can listen to.

Finally, we define a method for checking if the user is authenticated by calling the /auth/me endpoint. This should be executed on app startup:

const me = (userIsNotAuthenticatedCallback: () => void) => {
  return sendAuthGuardedRequest(
    userIsNotAuthenticatedCallback,
    ApiMethod.GET,
    routes.auth.me,
  ) as Promise<User>;
};

Our hook is now complete, this is the full version of it:

/*
 * These variables are used to debounce the refreshTokens function
 */
let debouncedPromise: Promise<unknown> | null;
let debouncedResolve: (...args: unknown[]) => void;
let debouncedReject: (...args: unknown[]) => void;
let timeout: number;

export const useAuthApi = () => {
  const { sendRequest, sendProtectedRequest } = useApi();

  const login = async (email: string, password: string) => {
    const response = await sendRequest(ApiMethod.POST, routes.auth.login, {
      email,
      password,
    });

    AuthClientStore.setAccessToken(response.access_token);
    AuthClientStore.setRefreshToken(response.refresh_token);

    return response;
  };

  const logout = () => {
    AuthClientStore.removeAccessToken();
    AuthClientStore.removeRefreshToken();
  };
  const refreshTokens = async () => {
    clearTimeout(timeout);
    if (!debouncedPromise) {
      debouncedPromise = new Promise((resolve, reject) => {
        debouncedResolve = resolve;
        debouncedReject = reject;
      });
    }

    timeout = setTimeout(() => {
      const executeLogic = async () => {
        const response = await sendProtectedRequest(
          ApiMethod.POST,
          routes.auth.refreshTokens,
          undefined,
          AuthClientStore.getRefreshToken(),
        );

        AuthClientStore.setAccessToken(response.access_token);
        AuthClientStore.setRefreshToken(response.refresh_token);
      };

      executeLogic().then(debouncedResolve).catch(debouncedReject);

      debouncedPromise = null;
    }, 200);

    return debouncedPromise;
  };

  const sendAuthGuardedRequest = async (
    userIsNotAuthenticatedCallback: () => void,
    method: ApiMethod,
    path: string,
    // eslint-disable-next-line
    body?: any,
    init?: RequestInit,
  ) => {
    try {
      return await sendProtectedRequest(method, path, body, undefined, init);
    } catch (e) {
      if (e?.status === 401) {
        try {
          await refreshTokens();
        } catch (e) {
          userIsNotAuthenticatedCallback();
          throw e;
        }
        return await sendProtectedRequest(method, path, body, undefined, init);
      }

      throw e;
    }
  };

  const me = (userIsNotAuthenticatedCallback: () => void) => {
    return sendAuthGuardedRequest(
      userIsNotAuthenticatedCallback,
      ApiMethod.GET,
      routes.auth.me,
    ) as Promise<User>;
  };

  return { login, logout, me, sendAuthGuardedRequest };
};

Implementing the Auth Provider component

Now let's have a look at our auth provider component, responsible with our global auth state.

type ContextType = {
  isAuthenticated: boolean;
  login(email: string, password: string): Promise<void>;
  logout(): void;
  me(): Promise<User>;
  sendAuthGuardedRequest(
    method: ApiMethod,
    path: string,
    // eslint-disable-next-line
    body?: any,
    init?: RequestInit,
  ): Promise<unknown>;
};

const AuthContext = createContext<ContextType | undefined>(undefined);

function AuthProvider({ children }: { children: ReactNode }) {
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  const {
    login: authLogin,
    logout: authLogout,
    me: authMe,
    sendAuthGuardedRequest: authSendAuthGuardedRequest,
  } = useAuthApi();

  const login = async (email: string, password: string) => {
    try {
      await authLogin(email, password);
      setIsAuthenticated(true);
    } catch (e) {
      setIsAuthenticated(false);
      throw e;
    }
  };

  const logout = () => {
    authLogout();
    setIsAuthenticated(false);
  };

  const me = async () => {
    const user = await authMe(() => {
      setIsAuthenticated(false);
    });
    setIsAuthenticated(true);

    return user;
  };

  const sendAuthGuardedRequest = async (
    method: ApiMethod,
    path: string,
    // eslint-disable-next-line
    body?: any,
    init?: RequestInit,
  ) => {
    return authSendAuthGuardedRequest(
      () => {
        setIsAuthenticated(false);
      },
      method,
      path,
      body,
      init,
    );
  };

  return (
    <AuthContext.Provider
      value={{
        isAuthenticated,
        login,
        logout,
        me,
        sendAuthGuardedRequest,
      }}
    >
      {children}
    </AuthContext.Provider>
  );
}

export { AuthProvider, AuthContext };

In this implementation, we’ve essentially wrapped the authentication API hook methods and manage the isAuthenticated state based on API responses. The final method in this component is very important: it is used by all other hooks or components that need to perform protected requests to our API. By incorporating the userIsNotAuthenticated callback, we ensure that when an endpoint call fails due to token expiration, the authentication state is updated. This approach allows the isAuthenticated state to be set to false, prompting all components across the app to adjust their behavior accordingly.

Next, we’ll define a useAuthContext hook to simplify access to the authentication state:

export const useAuthContext = () => {
  const ctx = useContext(AuthContext);

  if (!ctx) {
    throw new Error("useAuthContext must be within AuthProvider");
  }

  return ctx;
};

Wrapping Your App with AuthProvider

Ensure your application is wrapped with the AuthProvider to provide authentication state to all components.

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <AuthProvider>
      <App />
    </AuthProvider>
  </React.StrictMode>,
);

Next, we’ll define a useUserApi hook to handle API methods related to user operations:

export const useUserApi = () => {
  const { sendAuthGuardedRequest } = useAuthContext();

  const findAllUsers = async (
    limit: number,
    offset: number,
  ): Promise<FindAllUsersResponse> => {
    const queryString = buildQueryParams([
      { key: "limit", value: limit.toString() },
      { key: "offset", value: offset.toString() },
    ]);

    return sendAuthGuardedRequest(
      ApiMethod.GET,
      routes.user.findAll + queryString,
    );
  };

  const findOneUser = async (id: number): Promise<User> => {
    return sendAuthGuardedRequest(ApiMethod.GET, routes.user.findOne(id));
  };

  return { findAllUsers, findOneUser };
};

Note how we are using the sendAuthGuardedRequest method from the auth context.

Now, let's take a look at our App component.

function App() {
  const { isAuthenticated, login, logout, me } = useAuthContext();
  const [appIsLoading, setAppIsLoading] = useState(true);

  const { findAllUsers } = useUserApi();

  useEffect(() => {
    me()
      .catch(() => {})
      .finally(() => setAppIsLoading(false));
  }, []);

  if (appIsLoading) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return (
      <form
        style={ display: "flex", flexDirection: "column", gap: 16 }
        onSubmit={(e) => {
          e.preventDefault();
          login(e.target[0].value, e.target[1].value);
        }}
      >
        <div>Authentication</div>
        <input placeholder="Email" />
        <input placeholder="Password" type="password" />
        <button type="submit">Login</button>
      </form>
    );
  }

  return (
    <>
      <div>
        <a href="https://rabbitbyte.club" target="_blank">
          <img
            src={rabitByteClubLogo}
            className="logo"
            alt="logo-rabbit-byte"
          />
        </a>
      </div>
      <h1>Rabbit Byte Club</h1>
      <div style={{ display: "flex", gap: 16 }}>
        <button
          onClick={() => {
            for (let i = 0; i < 5; i++) {
              findAllUsers(10, 0);
            }
          }}
        >
          Simulate 5 concurrent requests
        </button>
        <button onClick={() => logout()}>Logout</button>
      </div>
    </>
  );
}

export default App;

We define an appLoading state, which is set to false once the /auth/me endpoint completes, regardless of success or failure. While the user is not authenticated, we display the login form.

If the user is authenticated, a button is provided to simulate 5 concurrent requests, allowing you to test the logic easily in the demo.

DEMO

Prerequisites:

To test the feature quickly and easily, set the JWT access token expiration to 10 seconds in your backend application:

JwtModule.registerAsync({
  inject: [ConfigService],
  useFactory: (configService: ConfigService<EnvironmentVariables>) => ({
    secret: configService.get('jwtSecret'),
    signOptions: { expiresIn: '10s' },
  }),
}),

Set the JWT refresh token expiration to 30 seconds:

    const newRefreshToken = this.jwtService.sign(
      { sub: authUserId },
      {
        secret: this.configService.get('jwtRefreshSecret'),
        expiresIn: '30s',
      },
    );

Additionally, you may want to temporarily disable throttling on the refresh tokens endpoint:

// @Throttle({
//   short: { limit: 1, ttl: 1000 },
//   long: { limit: 2, ttl: 60000 },
// })
@ApiBearerAuth()
@Public()
@UseGuards(JwtRefreshAuthGuard)
@Post('refresh-tokens')
refreshTokens(@Request() req: ExpressRequest) {
  if (!req.user) {
    throw new InternalServerErrorException();
  }
  return this.authRefreshTokenService.generateTokenPair(
    (req.user as any).attributes,
    req.headers.authorization?.split(' ')[1],
    (req.user as any).refreshTokenExpiresAt,
  );
}

Steps to Run the Demo:

1. Clone the Github Project:

git clone https://github.com/zenstok/react-auth-refresh-token-example

2. Install dependencies:

npm install

3. Run the App:

npm run dev

4. Ensure Backend is Running:
   Navigate to the backend directory and run:

yarn dc up

5. Fill in users in the database if needed:
   In a new terminal in backend directory run:

 yarn dc-db-init

6. Log in:
   Enter the following credentials on the login screen:
   
   Email: admin@admin.com
   Password: 1234

7. Test Functionality:
   After logging in, you will see two buttons: Simulate 5 Concurrent Requests and Log Out.

Open your browser's Network tab.

Click Simulate 5 Concurrent Requests.

You will see the effect of the refresh token logic in action.

The app will wait for a single call to the refresh tokens endpoint and then rerun the requests. Success!

Verification of Objectives:

1. Persistent Authentication: Refresh the page and ensure you remain authenticated. ✅
2. Automatic Logout: Log in and wait for more than 30 seconds. After pressing Simulate 5 Concurrent Requests, confirm that you are logged out. ✅
   
   
   
   

3. Seamless Data Access: When calling a protected endpoint, the app should return data if a valid refresh token exists. ✅

Conclusion

I hope this tutorial has been helpful in your journey to implement refresh tokens in React. Stay tuned for the final episode of this series, where we'll swap the backend and frontend logic to use HTTP-only cookies for the refresh token.

If you'd like me to cover more interesting topics about the node.js ecosystem, feel free to leave your suggestions in the comments section. Don't forget to subscribe to my newsletter on rabbitbyte.club for updates!

Post Creation:
Check out Part 3 of this series, where we update the app to use HTTP-only cookies for refresh tokens.

In this episode, we will learn how to implement refresh tokens using local storage as a strategy for storing both access and refresh tokens. If you want to jump directly to the GitHub repo, you can access it here.

Prerequisites

Before diving into this guide, it's important to have some experience with NestJS and the implementation of Passport strategies in NestJS. If you're not familiar with these topics, please visit the following articles from the NestJS documentation:

• Passport Integration

Why Do We Use Refresh Tokens?

Even though we use HTTPS to encrypt network traffic, there are additional steps we can take to prevent malicious users from stealing access tokens through methods like social engineering or library hacks. Refresh tokens allow a user to stay logged in for a long time without needing to log in again, provided they are active users. We can log them out after a set period, such as six months, if they have been inactive.

Why use refresh tokens instead of a single access token with a long or no expiration date? Because we want to counter token theft with short-lived access tokens, so attackers are likely to obtain expired tokens. Additionally, refresh tokens can provide a way to revoke user access without resetting the JWT signing key and logging out all users.

Implementation Overview

When we log in for the first time, we receive a token pair that includes an access token and a refresh token. As the access token approaches expiration, we can obtain a new token pair by requesting a new set of tokens from our authentication server. The server will provide the new token pair only if the refresh token is provided.

Why do you think I mentioned receiving a new token pair consisting of both access token and refresh token? If I have the refresh token with a long expiration date, wouldn't it have been sufficient to just get a new access token? Well, storing the refresh token with long expiration date invalidates the logic that hackers obtain short-lived tokens that are likely to be expired. Furthermore, this approach eliminates the possibility of implementing the 'permanently logged in' users feature, even if they are active. So, what we do is when we request a new token pair, we immediately invalidate the previous refresh token through a mechanism called refresh token rotation.

Refresh Token Rotation

Refresh token rotation operates by generating a blacklist which will "force invalidate" previously used refresh tokens. When a new token pair is requested, we utilize a refresh token and then include this used refresh token in our blacklist. This means that if a hacker gains control of a refresh token, it will already be invalid if the user has refreshed their token pair.

But what if the hacker gets a fresh, valid refresh token? You've got two options: if you spot the hack right away, though that's unlikely, you can quickly get a new token pair to make the hacker's refresh token worthless. If the hacker uses your refresh token and it's marked invalid, there's not much you can do. They might have access to your app indefinitely until you change the JWT signing key. To stop this, we can store the refresh token in an HTTP-only cookie and guard against CSRF attacks. That way, even if your app has XSS vulnerabilities, the hacker can't read the refresh token. If you're interested in an article about storing refresh tokens in HTTP-only cookies, leave a comment, and I'll get right on it.

Getting Started

For this article, we'll focus on the core logic and keep the app simple.

Clone the project from GitHub and start the Docker containers:

yarn dc up

Pre-fill your database with two users:

yarn dc-db-init

Access Swagger at localhost:3000/docs to log in. For the admin user, use:
Email: admin@admin.com
Password: 1234

Our app allows refreshing the token pair by calling the /refresh-tokens endpoint. When called with a refresh token as bearer auth, it invalidates the previous token. Try calling the endpoint twice with the same token to see the 401 Unauthorized error on the second call.

The core logic is in the authentication module. We have three guards:

• Local Auth Guard: For initial authentication with email and password.
• JWT Auth Guard: Protects all app routes globally, defined as an APP_GUARD in app.module.ts, uses access token for validation.
• JWT Refresh Auth Guard: Guards the /refresh-tokens endpoint, uses refresh token for validation.

The critical aspect here is the interaction between access tokens and refresh tokens, so I'll skip discussing the local auth guard. For the JWT auth guard, we utilize the JWT strategy from the 'passport-jwt' package.

In the following section, we define how to extract the JWT from the request and the JWT signature key, which we set in the environment. In the validate method, we receive the payload of the JWT, which we use to retrieve the user ID and verify if the user exists in the database before granting access if true.

export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(
    private userService: UserService,
    configService: ConfigService<EnvironmentVariables>,
  ) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get('jwtSecret'),
    });
  }

  async validate(payload: any): Promise<User | null> {
    const authUser = await this.userService.findOne(payload.sub);
    if (!authUser) {
      throw new UnauthorizedException();
    }
    return authUser;
  }
}

Similarly, for the JWT refresh auth guard, we employ the same JWT strategy from the 'passport-jwt' package. The distinction here from the JWT strategy file is that we utilize a different secret key for JWT token generation, and we return both the user attributes and the refresh token expiration date. This expiration date becomes necessary later in the process.

@Injectable()
export class JwtRefreshStrategy extends PassportStrategy(Strategy, 'jwt-refresh') {
  constructor(
    private userService: UserService,
    configService: ConfigService<EnvironmentVariables>,
  ) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get('jwtRefreshSecret'),
    });
  }

  async validate(payload: any) {
    const authUser = await this.userService.findOne(payload.sub);
    if (!authUser) {
      throw new UnauthorizedException();
    }
    return {
      attributes: authUser,
      refreshTokenExpiresAt: new Date(payload.exp * 1000),
    };
  }
}

In the authentication.controller's login method, we observe that we call the login method, which, in turn, invokes the generateTokenPair from our AuthRefreshTokenService. It's important to note that we also implement a throttle mechanism to limit the number of requests on the login route, thereby preventing brute force attacks, with a maximum of 2 requests per second and a maximum of 5 login attempts per 60 seconds.

@Throttle({ short: { limit: 2, ttl: 1000 }, long: { limit: 5, ttl: 60000 } })
@ApiBody({ type: UserLoginDto })
@Public()
@UseGuards(LocalAuthGuard)
@Post('login')
login(@Request() req: any) {
  return this.authenticationService.login(req.user);
}

From within authentication service:

login(user: User) {
  return this.authRefreshTokenService.generateTokenPair(user);
}

The auth.refresh.token.service.ts looks like this:

export class AuthRefreshTokenService {
  constructor(
    private jwtService: JwtService,
    private configService: ConfigService<EnvironmentVariables>,
    @InjectRepository(AuthRefreshToken)
    private authRefreshTokenRepository: Repository<AuthRefreshToken>,
  ) {}

  async generateRefreshToken(authUserId: number, currentRefreshToken?: string, currentRefreshTokenExpiresAt?: Date) {
    const newRefreshToken = this.jwtService.sign(
      { sub: authUserId },
      { secret: this.configService.get('jwtRefreshSecret'), expiresIn: '30d' },
    );

    if (currentRefreshToken && currentRefreshTokenExpiresAt) {
      if (await this.isRefreshTokenBlackListed(currentRefreshToken, authUserId)) {
        throw new UnauthorizedException('Invalid refresh token.');
      }

      await this.authRefreshTokenRepository.insert({
        refreshToken: currentRefreshToken,
        expiresAt: currentRefreshTokenExpiresAt,
        userId: authUserId,
      });
    }

    return newRefreshToken;
  }

  private isRefreshTokenBlackListed(refreshToken: string, userId: number) {
    return this.authRefreshTokenRepository.existsBy({ refreshToken, userId });
  }

  async generateTokenPair(user: User, currentRefreshToken?: string, currentRefreshTokenExpiresAt?: Date) {
    const payload = { email: user.email, sub: user.id };
    return {
      access_token: this.jwtService.sign(payload),
      refresh_token: await this.generateRefreshToken(user.id, currentRefreshToken, currentRefreshTokenExpiresAt),
    };
  }

  @Cron(CronExpression.EVERY_DAY_AT_6AM)
  async clearExpiredRefreshTokens() {
    await this.authRefreshTokenRepository.delete({ expiresAt: LessThanOrEqual(new Date()) });
  }
}

Looking at generateRefreshToken method, we generate a new refresh token with a 30-days expiration. If we don't receive the optional currentRefreshToken and currentRefreshTokenExpiresAt parameters, we simply return the newly created refresh token, as expected after a successful login.

Examining the refreshTokens method below in the authentication controller, we notice the implementation of a throttle mechanism: a maximum of 1 request per second or 2 requests per 60 seconds. We invoke generateTokenPair with user attributes, the used refresh token, and its expiration date:

@Throttle({
  short: { limit: 1, ttl: 1000 },
  long: { limit: 2, ttl: 60000 },
})
@ApiBearerAuth()
@Public()
@UseGuards(JwtRefreshAuthGuard)
@Post('refresh-tokens')
refreshTokens(@Request() req: ExpressRequest) {
  if (!req.user) {
    throw new InternalServerErrorException();
  }
  return this.authRefreshTokenService.generateTokenPair(
    (req.user as any).attributes,
    req.headers.authorization?.split(' ')[1],
    (req.user as any).refreshTokenExpiresAt,
  );
}

The generateTokenPair method of AuthRefreshTokenService, when invoked with currentRefreshToken and currentRefreshTokenExpiresAt, checks if the current token is blacklisted and throws an error if it's reused. For the first-time usage, it inserts this token into our auth refresh tokens database table, effectively acting as our blacklist.

In the final method of our service, we have a cron job responsible for deleting all refresh tokens whose expiration date has passed, as we no longer need to retain them in the database.

This is part 1 of a 3-episode series. In the next episode, I will show you how to manage access and refresh tokens easily in a React app. In episode 3, we'll delve deeper into storing the refresh token in an HTTP-only cookie instead of local storage. This approach prevents attackers from reading the refresh token, even if your app is vulnerable to XSS attacks.

If you'd like me to cover more interesting topics about the node.js ecosystem, feel free to leave your suggestions in the comments section. Don't forget to subscribe to my newsletter on rabbitbyte.club for updates!

Post Creation:
Check out Part 2 of this series, where we integrate this backend with a React App.

There may be cases when you need to do CPU-intensive tasks on the backend like big JSON parsing, video encoding, compression, etc. If you have at least 2 cores in your processor's configuration you can run javascript in parallel for these tasks and not block the main thread of the NestJS app that handles client requests.

An excellent way of doing this is by using node.js worker threads.

You shouldn't use worker threads for I/O operations as node.js already gracefully handles this for you.

If you're eager to dive into the complete example right away, you can check out the GitHub repo for the full example. 

In order to illustrate this, we will use a very simple service that calculates the fibonacci sum, which is a CPU-intensive task, a great candidate for node.js worker threads!

import { Injectable } from '@nestjs/common';

@Injectable()
export class FibonacciService {
  fibonacci(n) {
    if (n <= 1) {
      return 1;
    }
    return this.fibonacci(n - 1) + this.fibonacci(n - 2);
  }
}

Now, let's dive into the code snippet that launches the worker thread:

import { Injectable, Logger } from '@nestjs/common';
import { Worker, isMainThread } from 'worker_threads';
import workerThreadFilePath from './worker-threads/config';

@Injectable()
export class AppService {
  private readonly logger = new Logger(AppService.name);

  checkMainThread() {
    this.logger.debug(
      'Are we on the main thread here?',
      isMainThread ? 'Yes.' : 'No.',
    );
  }

  // do not run this from the worker thread or you will spawn an infinite number of threads in cascade
  runWorker(fibonacci: number): string {
    this.checkMainThread();
    
    const thisService = this;
    const worker = new Worker(workerThreadFilePath, {
      workerData: fibonacci,
    });
    worker.on('message', (fibonacciSum) => {
      thisService.logger.verbose('Calculated sum', fibonacciSum);
    });
    worker.on('error', (e) => console.log('on error', e));
    worker.on('exit', (code) => console.log('on exit', code));

    return 'Processing the fibonacci sum... Check NestJS app console for the result.';
  }
}

As we can see from the snippet above, we defined a new worker, gave it a path to a file to be executed by the worker, and gave it as param the workerData. Worker data is data sent from the main thread to the other thread.

We are using the constant workerThreadFilePath from associated config file on the same level in the directory tree so we can safely use the path for the worker thread regardless of where the app is deployed.

// it will import the compiled js file from dist directory
const workerThreadFilePath = __dirname + '/findFibonacciSum.js';

export default workerThreadFilePath;

Take a note that we are using the js extension here because the transpiled output of typescript, as we know, it's javascript.

Let's explore the file which will be executed in the worker thread:

import { NestFactory } from '@nestjs/core';
import { workerData, parentPort } from 'worker_threads';
import { AppModule } from '../app.module';
import { FibonacciService } from '../fibonacci/fibonacci.service';
import { AppService } from '../app.service';

async function run() {
  const app = await NestFactory.createApplicationContext(AppModule);
  const appService = app.get(AppService);
  const fibonacciService = app.get(FibonacciService);

  const fibonacciNumber: number = workerData; // this is data received from main thread


  // here we apply business logic inside the worker thread
  appService.checkMainThread();
  const fibonacciSum = fibonacciService.fibonacci(fibonacciNumber);
  parentPort.postMessage(fibonacciSum);
}

run();

In order to have access to dependency injection in our NestJs app in the thread, we leverage Nest standalone application which is a wrapper around the Nest IoC container, which holds all instantiated classes.

Now, we can execute any method from any service.

Caveats: 

• Be cautious when using dependency injection from NestJS in a worker thread, as it comes with a cost. The startup process of the NestJS app must be awaited before accessing the dependency injection. Therefore, utilize this method only if absolutely necessary, or if the startup bottleneck is negligible in terms of overall performance.
• If your app setup is starting processes that you don't want to run on the separate thread you will need to configure your app module into a dynamic module to accept a parameter to not initiate the setup.
  Example:
  const app = await NestFactory.createApplicationContext(
  AppModule.register({ attachRabbitMqConsumers: false }),
  );
  

Github repository:

nestjs-worker-thread-example/src/app.service.ts at master · zenstok/nestjs-worker-thread-example

This project illustrates how to use node.js worker thread in a NestJS app and have access to dependency injection. - zenstok/nestjs-worker-thread-example

GitHubzenstok

If you'd like me to cover more interesting topics about the node.js ecosystem, feel free to leave your suggestions in the comments section. Don't forget to subscribe to my newsletter on rabbitbyte.club for updates!

Introduction:
This blog post is the final installment of a three-part series dedicated to scaling a NestJS chat app to handle millions of users. In the first two episodes, we discussed the scaling process and demonstrated how to deploy it locally using Docker and Minikube. However, in this final episode, our focus shifts to deploying the app in a production environment on Google Kubernetes Engine (GKE). If you want to jump directly to a working solution, you can check out the deploy-on-gke branch of the GitHub repository here.

While it is recommended to read the previous episodes for a comprehensive understanding of the scaling process, this post can also serve as a standalone guide specifically for deploying the app to GKE in a production-ready manner. By the end of this episode, you will possess all the necessary tools and knowledge to successfully deploy your NestJS chat app on GKE, ready to handle high user loads.

Section 1: Prerequisites
Before diving into the deployment process, ensure you have the following prerequisites in place:

• A Google Cloud account.
• The Google Cloud SDK installed on your local machine (you can find installation instructions here).
• Basic familiarity with Docker and Kubernetes concepts.

Section 2: Creating a GKE Cluster
The first step is to set up a GKE cluster, which will serve as the runtime environment for your application. Here are the steps:

• Create a new Google Cloud project through the GUI and ensure billing is activated.

• Enable the Kubernetes Engine API for the newly created project (billing should be activated).

• Switch to the Google Cloud CLI and authenticate using the command gcloud auth login.
• Make sure your active project with billing activated is set to the correct one by running gcloud config set project <YOUR-PROJECT-ID>.
• Create a Kubernetes cluster using the command gcloud container clusters create scale-chat-app-cluster.

This process may take a little time. Afterward, create a static external IP address, which is needed to make your app accessible over the internet:

gcloud compute addresses create tutorial-ip --global

Check the details of the newly created IP address:

gcloud compute addresses describe --global tutorial-ip

Now, update your DNS records for your chosen domain to point to this IP address.

Section 3: Containerizing Your Application
To deploy your application to Kubernetes, it must be packaged into a container image. For this tutorial, we've already published the Docker image on Docker Hub as a public image here. Docker Hub serves as a container registry from which your Kubernetes app will retrieve the container image. If you want to use a private image, you can do so. If you're interested in learning how to publish your own image, you can follow a Docker tutorial here.

Section 4: Defining Kubernetes Deployment and Service YAML
In this section, we'll delve into the Kubernetes Deployment and Service YAML files. These files define how your application should be deployed and exposed. We'll discuss key parameters and provide examples to help you create your own YAML files.

• To start, use the Kubernetes YAML files from the previous tutorial. What you'll need to add:
• A GKE Ingress Controller. An ingress controller receives and load-balances traffic from outside Kubernetes to pods running in a Kubernetes cluster.
• A default backend for this Ingress. Any requests that don't match the paths in the rules field are sent to the Service and port specified in the defaultBackend field. We will have an Ingress with no rules so that all requests are sent to this default backend.
• Annotations for the Ingress to capture the IP address set above.
• A managed certificate service where we will define the domains we own so that the app can point to that domain and have SSL.
• A frontend config that will automatically redirect all requests to HTTPS.
• A readiness probe configuration in our deployment config to inform GKE about pod health (for this, you will also need to implement a health route, which is a route that always returns a 200 status on GET).

The ingress config looks like this:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: backend-ingress
  annotations:
    kubernetes.io/ingress.global-static-ip-name: tutorial-ip
    networking.gke.io/managed-certificates: managed-cert
    kubernetes.io/ingress.class: "gce"
    networking.gke.io/v1beta1.FrontendConfig: ssl-redirect
  labels:
    app: backend
spec:
  defaultBackend:
    service:
      name: backend-service
      port:
        number: 3000

The backend config looks like this:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backendconfig
spec:
  timeoutSec: 120

The backend service should be annotated with your backend config:

apiVersion: v1
kind: Service
metadata:
  name: backend-service
  labels:
    app: backend
  annotations:
    cloud.google.com/backend-config: '{"ports": {"3000":"my-backendconfig"}}'

The frontend config looks like this:

apiVersion: networking.gke.io/v1beta1
kind: FrontendConfig
metadata:
  name: ssl-redirect
spec:
  redirectToHttps:
    enabled: true

The managed certificate looks like this:

apiVersion: networking.gke.io/v1
kind: ManagedCertificate
metadata:
  name: managed-cert
spec:
  domains:
    - subdomain.put-your-domain-here.com

The readiness probe looks like this: (It has to be added in backend-deployment.yaml at spec.template.spec.containers)

          readinessProbe:
            httpGet:
              path: "/health"
              port: 3000
            initialDelaySeconds: 10
            timeoutSeconds: 5

If your Docker image is private, you will need to create a Kubernetes secret to store your Docker private image credentials. However, for the purpose of this tutorial, we will continue using the public image we've used in our previous episodes.

Here's how to create a Kubernetes secret for private Docker images:

kubectl create secret docker-registry regcred \
    --docker-server=https://index.docker.io/v1 \
    --docker-username=<your-name> \
    --docker-password=<your-password> \
    --docker-email=<your-email>

Please note that this example assumes you are using Docker Hub as your registry. If you are using a different Docker registry, make sure to set the --docker-server option accordingly to match your registry's URL.

In your backend-deployment yaml spec (spec.template.spec.imagePullSecrets), you will have to add this secret in order to be able to pull the image:

      imagePullSecrets:
        - name: regcred

Section 5: Deploying Your Application to GKE
Now, it's time to deploy your application to the GKE cluster. Follow these steps:

• Ensure you are in the correct Kubernetes context:

kubectl config get-contexts

If necessary, switch to the appropriate context:

kubectl config use-context <YOUR-CONTEXT-NAME>

• Run the following command in your project directory:

kubectl apply -f k8s

You will need to wait for the Google-managed certificate to finish provisioning, which may take up to 60 minutes. You can check the status of the certificate using this command:

kubectl describe managedcertificate managed-cert

Section 6: Scaling and Managing Your Application
Kubernetes

GKE offers powerful scaling and management capabilities. For example, you can update the number of replicas or resources used per pod.

• Add a resources variable to the containers in backend-deployment.yaml: (make sure the cluster has sufficient resources)

resources:
  limits:
    cpu: "2000m"    # Maximum CPU limit
    memory: "4Gi"   # Maximum memory limit
  requests:
    cpu: "1000m"    # Minimum CPU request
    memory: "1Gi"   # Minimum memory request

Section 7: Conclusion
In conclusion, Kubernetes GKE offers a scalable and reliable environment for deploying applications. Throughout this blog post, we've explored the essential configuration options necessary to successfully deploy your application in a production-ready environment.

In our previous blog post, we explored how to write a scalable NestJS chat app using a distributed architecture and WebSockets for real-time communication. Building upon that, we will now dive deeper into improving the app's efficiency and deploying it on Kubernetes using minikube. If you're eager to check out the source code, you can find it in the GitHub repository here (make sure you check out on improved-version+deploy-on-kubernetes branch). Additionally, if you find this post useful, let me know in the comments, and I'll create another tutorial focusing on deploying a production app with Google Kubernetes Engine (GKE). This tutorial will cover essential features like configuring a static IP, associating a domain name, obtaining a TLS certificate for secure communication, and setting up a load balancer for distributing traffic between instances.

Improving the Previous Model

In the previous post, we stored an array of connected clients in each instance and triggered events to notify all instances about new messages. In this paradigm, we broadcast messages to all instances regardless if they have associated ws clients which needs to receive the message or not. To enhance this model and optimize the broadcasting process, we can leverage Redis. Here's how we can achieve this improvement:

Consolidating Redis Channels:
Instead of having three channels for different types of messages (send to all, send to many, send to one), we will use a single global channel for broadcasting global messages (send to all). Additionally, we will dynamically create user-specific channels in the format: ws_socket_client/{USER_ID}. Each instance that holds WebSocket clients will basically subscribe to these channels. This helps optimize the broadcasting process and ensures that messages are only sent to the relevant instances with the corresponding clients.

Implementation Changes:
To implement this change, we need to listen for WebSocket connect and disconnect events and subscribe/unsubscribe the Redis client to each client's respective channel. Here are the code changes:

• In the constructor, we now subscribe only to the channel for sending messages to all clients:

this.subscriberRedis.subscribe(this.sendWsMessageToAllClientsRedisChannel);

• Create a new private method to generate the user-specific channel name:

private getClientIdRedisChannel(userId: string) {
  return `${this.wsSocketClientRedisChannel}/${userId}`;
}

• Subscribe to the user-specific channel in the addConnection method:

this.subscriberRedis.subscribe(this.getClientIdRedisChannel(userId));

• Unsubscribe from the user-specific channel in the removeConnection method:

this.subscriberRedis.unsubscribe(this.getClientIdRedisChannel(client.userId));

• Update the subscriber client to listen to the global channel for sending messages to all clients, as well as the user-specific channels:

this.subscriberRedis.on('message', (channel, message) => {
  const data = JSON.parse(message) as RedisPubSubMessage;
  if (data.from !== this.redisClientId) {
    switch (true) {
      case channel === this.sendWsMessageToAllClientsRedisChannel:
        this.sendMessageToAllClients(data.message, false);
        break;
      case channel.startsWith(this.wsSocketClientRedisChannel):
        this.sendMessageToClient(
          (data as RedisPubSubMessageWithClientId).clientId,
          data.message,
          false,
        );
        break;
      // no default
    }
  }
});

You will also notice that on this branch,  I updated the chat gateway class, now it has 3 types of messages it subscribes to:

enum SubscribeMessageType {
  SendChatMessageToOneParticipant = 'send_chat_message_to_one_participant',
  SendChatMessageToManyParticipants = 'send_chat_message_to_many_participants',
  SendChatMessageToAllParticipant = 'send_chat_message_to_all_participants',
}

In order to test it in the browser, you can follow the previous tutorial where I discussed how to set up the database and how to obtain bearer tokens for authenticated users.
Also, the content of the websocket message should follow the format of our DTO classes so it can be received correctly:

export class SendMessageToAllDto {
  @IsString()
  @Length(1, 5000)
  message: string;
}

export class SendMessageToManyDto extends SendMessageToAllDto {
  @IsArray()
  @IsUUID(undefined, { each: true })
  participantIds: string[];
}

export class SendMessageToOneDto extends SendMessageToAllDto {
  @IsUUID()
  participantId: string;
}

For example if you want to send multiple messages you can use something like this in the browser:

users.forEach(user => ws.send(JSON.stringify({event: 'send_chat_message_to_one_participant', data: {message: 'test', participantId: user.id}})));

To test this improvement, connect and disconnect multiple clients in the browser and observe the behavior in the Docker console.

Deploying the Stack on Minikube

To deploy the chat app on Minikube for local development and testing, follow these steps:

Install Minikube by referring to the official tutorial at
https://kubernetes.io/docs/tasks/tools/.

Once Minikube is installed, start the Minikube cluster using the command:

minikube start

Inside the k8s directory, you'll find the deployment files for the backend, Redis, and PostgreSQL, along with the corresponding services and volumes. We have set up environment variables within the backend deployment to ensure connectivity with Redis and PostgreSQL. The deployment is configured with five replicas to create a total of five backend pods. To test the deployment locally, the backend service is set as a node port, allowing it to be exposed to your local machine.

To deploy the app, navigate to the project directory and run the following command:

kubectl apply -f k8s

This will set up the entire app along with its dependencies. Please note that we are using the zenstok/scalable-chat-app-example-backend image, which is built from the improved-version+deploy-on-kubernetes branch available at https://github.com/zenstok/nestjs-scalable-chat-app-example.

Initiate database inside kubernetes

Find a backend pod name:

kubectl get pods

Access a shell inside a backend pod:

kubectl exec -it backend-deployment-7ddd9c4769-fxqxg -- sh

Run db init command:

yarn db-init

If you want to port-forward kubernetes db to inspect it, you can do so by running:

kubectl port-forward deployment/postgres-deployment 5432:5432

To access the deployed service locally, expose it using the command:

minikube service backend-service

Interact with the deployed app locally and verify its behavior.

You will get something like this in the console:

It will start a tunnel for backend-service which can be accessed locally at this address (beware that the port might be different on your machine):

http://127.0.0.1:61939

Now you can interact with the app exactly as you interacted with the docker configured app.
For example, to access swagger docs, you just hit this in the browser:

http://127.0.0.1:61939/docs

Also, if you want to inspect the logs from all backend pods, you can do so by running:

kubectl logs -l app=backend -f

Once you have finished testing, clean up the Minikube cluster by deleting it:

minikube delete

In this blog post, we explored how to enhance the scalability of a NestJS chat app by leveraging Redis and implementing user-specific channels. By optimizing the broadcasting process, we reduced networking costs and improved overall efficiency. Additionally, we learned how to deploy the app on Kubernetes using Minikube for local development and testing.

Your feedback and comments are highly appreciated, so please share your thoughts and experiences. Stay tuned for new posts!

Hello, in this guide, I will teach you how to scale a NestJS app to millions of users.

Prerequisites:

• Experience with JavaScript.
• Experience with NestJS.
• Experience as a backend engineer.

Access the GitHub repository for this project here.

To scale your app, you will need to scale horizontally by creating multiple instances of your NestJS app.

Each instance of your app should have the following features:

1. WebSocket integrations that keep track of connected clients through websockets in a singleton memory array. (this is done by default when using nestjs, reference: Injection Scopes)
2. A Redis database publisher that announces new requests received by all other instances and a subscriber that listents to these requests. This is necessary because a client may send a request to one instance (e.g., instance number 3) and be registered as a websocket client there. However, the client may then send a request to another instance because you will have a load balancer installed (e.g., instance number 32), triggering a websocket chat notification. Unfortunately, this instance does not have the connected client in its singleton memory array. To handle this, the instance needs to announce the request to all other instances through Redis. The other instances can then look up their array of connected clients and notify them if a match is found.

Here's how you can achieve this:

1. Install websockets in your NestJS app. Follow the official NestJS guide. If you'd like to quickly jump out and see the GitHub repo for the full example, you can find it here.

2. Create the WebSocket client manager service (explained below).

After setting up websockets in your app, we need to define an entrypoint gateway for websockets.

@WebSocketGateway({ path: '/entrypoint' })
export class EntrypointGateway {}

Then, create a new lifecycle gateway that extends this entrypoint. This lifecycle gateway contains the logic to insert clients into the WebSocket client manager.

@Injectable()
export class LifecycleGateway
  extends EntrypointGateway
  implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect
{
  private readonly logger = new Logger(LifecycleGateway.name);

  constructor(
    private readonly jwtService: JwtService,
    private readonly wsClientManager: WsClientManager,
  ) {
    super();
  }

  afterInit() {
    this.logger.debug('Websockets initialized ' + this.constructor.name);
  }

  handleConnection(client: any) {
    const authUserTokenData = this.getDecodedAuthToken(client);

    if (!authUserTokenData) {
      client.close();
      return;
    }

    this.wsClientManager.addConnection(client, authUserTokenData);
  }

  handleDisconnect(client: any) {
    this.wsClientManager.removeConnection(client);
  }

  getDecodedAuthToken(client: any) {
    let decodedJwt: DecodedAuthToken | null = null;

    try {
      if (client.protocol) {
        decodedJwt = this.jwtService.verify(client.protocol, {
          secret: jwtConstants.secret,
        }) as DecodedAuthToken;
      }
    } catch (e) {}

    return decodedJwt;
  }
}

To inject the Redis connection into our app, we utilize @liaoliaots/nestjs-redis package with the following yarn command:

 yarn add @liaoliaots/nestjs-redis

Moving forward, we will add the Redis module configuration for subscriber and publisher channels.

RedisModule.forRootAsync({
  inject: [ConfigService],
  useFactory: async (config: ConfigService) => ({
    config: [
      {
        namespace: 'subscriber',
        host: config.get('REDIS_HOST'),
        port: config.get('REDIS_PORT'),
      },
      {
        namespace: 'publisher',
        host: config.get('REDIS_HOST'),
        port: config.get('REDIS_PORT'),
      },
    ],
  }),
}),

In the WebSocket client manager, you will find the following:

• We generate a random Redis client using the crypto module's randomUUID from the official Node.js package.

Each NestJS app instance subscribes to the three Redis channels we defined:

• SendWsMessageToAllClients
• SendWsMessageToSomeClients
• SendWsMessageToOneClient

When a NestJS instance receives a message, it first checks that the publisher is not the same as the subscriber. Then, it proceeds to send the message. However, this time, we set the shouldPublishToRedis parameter to false to avoid an infinite loop. The received message will be sent by each instance if it finds the clients in its singleton memory array.

This approach also handles cases where a single user uses the app through multiple devices simultaneously (e.g., PC, mobile app). The user will receive chat notifications on all devices because, upon inspecting the code, you will notice that we are utilizing a map object. For every user ID, we store all associated WebSocket connected clients.

@Injectable()
export class WsClientManager {
  private readonly connectedClients = new Map<string, any[]>();
  private readonly redisClientId = `ws_socket_client-${crypto.randomUUID()}`;

  constructor(
    @InjectRedis('subscriber') private readonly subscriberRedis: Redis,
    @InjectRedis('publisher') private readonly publisherRedis: Redis,
  ) {
    this.subscriberRedis.subscribe(
      RedisSubscribeChannel.SendWsMessageToAllClients,
    );
    this.subscriberRedis.subscribe(
      RedisSubscribeChannel.SendWsMessageToSomeClients,
    );
    this.subscriberRedis.subscribe(
      RedisSubscribeChannel.SendWsMessageToOneClient,
    );

    this.subscriberRedis.on('message', (channel, message) => {
      const data = JSON.parse(message) as RedisPubSubMessage;
      if (data.from !== this.redisClientId) {
        switch (channel) {
          case RedisSubscribeChannel.SendWsMessageToAllClients:
            this.sendMessageToAllClients(data.message, false);
            break;
          case RedisSubscribeChannel.SendWsMessageToSomeClients:
            this.sendMessageToClients(
              (data as RedisPubSubMessageWithClientIds).clientIds,
              data.message,
              false,
            );
            break;
          case RedisSubscribeChannel.SendWsMessageToOneClient:
            this.sendMessageToClient(
              (data as RedisPubSubMessageWithClientId).clientId,
              data.message,
              false,
            );
            break;
        }
      }
    });
  }

  addConnection(client: any, authUserTokenData: DecodedAuthToken) {
    const userId = authUserTokenData.sub;

    this.setUserIdOnClient(client, userId);
    const clientsPool = this.getClientsPool(client);
    this.connectedClients.set(
      userId,
      clientsPool ? [...clientsPool, client] : [client],
    );

    setTimeout(() => {
      client.close(); // This will trigger removeConnection from the LifecycleGateway's handleDisconnect
    }, this.getConnectionLimit(authUserTokenData));
  }

  removeConnection(client: any) {
    const clientsPool = this.getClientsPool(client);
    const newPool = clientsPool!.filter((c) => c !== client);

    if (!newPool.length) {
      this.connectedClients.delete(client.userId);
    } else {
      this.connectedClients.set(client.userId, newPool);
    }
  }

  private setUserIdOnClient(client: any, userId: string) {
    client.userId = userId;
  }

  private getClientsPool(client: any) {
    return this.connectedClients.get(client.userId);
  }

  private getConnectionLimit(tokenData: DecodedAuthToken) {
    return tokenData.exp * 1000 - Date.now();
  }

  getConnectedClientIds() {
    const clientIds: string[] = [];

    const iterator = this.connectedClients.keys();
    let current = iterator.next();
    while (!current.done)

 {
      clientIds.push(current.value);
      current = iterator.next();
    }

    return clientIds;
  }

  sendMessageToClient(
    clientId: string,
    message: string,
    shouldPublishToRedis = true,
  ) {
    if (shouldPublishToRedis) {
      this.publisherRedis.publish(
        RedisSubscribeChannel.SendWsMessageToOneClient,
        JSON.stringify({
          message,
          clientId,
          from: this.redisClientId,
        }),
      );
    }

    const clientPool = this.connectedClients.get(clientId);

    if (clientPool) {
      clientPool.forEach((client) => {
        client.send(message);
      });
    }
  }

  sendMessageToClients(
    clientIds: string[],
    message: string,
    shouldPublishToRedis = true,
  ) {
    if (shouldPublishToRedis) {
      this.publisherRedis.publish(
        RedisSubscribeChannel.SendWsMessageToSomeClients,
        JSON.stringify({
          message,
          clientIds,
          from: this.redisClientId,
        }),
      );
    }

    this.connectedClients.forEach((clientPool, clientId) => {
      if (clientIds.includes(clientId)) {
        clientPool.forEach((client) => {
          client.send(message);
        });
      }
    });
  }

  sendMessageToAllClients(message: string, shouldPublishToRedis = true) {
    if (shouldPublishToRedis) {
      this.publisherRedis.publish(
        RedisSubscribeChannel.SendWsMessageToAllClients,
        JSON.stringify({
          message,
          from: this.redisClientId,
        }),
      );
    }

    this.connectedClients.forEach((clientPool) => {
      clientPool.forEach((client) => {
        client.send(message);
      });
    });
  }
}

Now it's time to test our app. First, clone the project. Make sure you have Docker installed.

This is the Dockerfile for our NestJS app (represents a single instance):

Dockerfile:

FROM node:18.13.0-alpine AS development

WORKDIR /usr/src/app
COPY package.json ./
COPY yarn.lock ./

RUN yarn install --frozen-lockfile \
&& yarn cache clean

COPY . .

RUN yarn build

CMD yarn install; yarn start:debug;

In the docker-compose file, we use our backend image generated from the Dockerfile above. We also have an Nginx server to act as a load balancer between app instances, Postgres as the database, and Redis as the centralized database used for communication between app instances. In this example, we simulate the presence of five NestJS app instances.

docker-compose.yml:

version: '3.7'

services:
  backend:
    image: scalable-chat-app-example-backend
    build:
      context: ./../
      dockerfile: ./docker/Dockerfile
      target: development
    volumes:
      - ./../:/usr/src/app
      - scalable-chat-app-example-backend-node-modules:/usr/src/app/node_modules
      - scalable-chat-app-example-backend-dist:/usr/src/app/dist
    ports:
      - '3000'
    networks:
      - mainnet
    depends_on:
      - postgres
      - redis
    restart: unless-stopped
    scale: 5

  nginx:
    container_name: scalable-chat-app-example-nginx-load-balancer
    image: nginx:latest
    volumes:
      - ./../nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - backend
    networks:
      - mainnet
    ports:
      - '3000:3000'

  postgres:
    container_name: scalable-chat-app-example-postgres-db
    image: postgres:15.0
    networks:
      - mainnet
    environment:
      TZ: ${DB_TIMEZONE}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
      PG_DATA: /var/lib/postgresql/data
    ports:
      - '5432:5432'
    volumes:
      - scalable-chat-app-example-pgdata:/var/lib/postgresql/data

  redis:
    container_name: scalable-chat-app-example-redis-db
    image: redis:7.0.7
    networks:
      - mainnet
    expose:
      - '6379'
    volumes:
      - scalable-chat-app-example-redisdata:/data

networks:
  mainnet:

volumes:
  scalable-chat-app-example-pgdata:
  scalable-chat-app-example-backend-node-modules:
  scalable-chat-app-example-backend-dist:
  scalable-chat-app-example-redisdata:

We also need the following Nginx configuration to handle WebSocket connections:

nginx.conf:

user nginx;
events {

	worker_connections 1000;
}
http {

	upstream app {

		server scalable-chat-app-example-backend-1:3000;
		server scalable-chat-app-example-backend-2:3000;
		server scalable-chat-app-example-backend-3:3000;
		server scalable-chat-app-example-backend-4:3000;
		server scalable-chat-app-example-backend-5:3000;
	}

	server {

		listen 3000;
		location / {

			proxy_pass http://app;
			# WebSocket support
			proxy_http_version 1.1;
			proxy_set_header Upgrade $http_upgrade;
			proxy_set_header Connection $http_connection;

		}
		client_max_body_size 1000M;
	}
}

To set up the example, navigate to the repository directory and execute the following three commands:

Copy sample.env:

cp sample.env .env

Run containers:

yarn dc up 

Initiate docker database:

yarn dc-db-init

If you want to clean the project you can run the following command:

yarn dc-clean

Your database has 5 users initiated:

• test@test.com
• test2@test.com
• test3@test.com
• test4@test.com

Each one of them has 1234 as password.

Open swagger at http://localhost:3000/docs.

Login multiple users so you obtain the bearer token needed for ws authentication.

Open as many browser tabs as you want and write the following code in each of them:

const ws = new WebSocket('ws://localhost:3000/entrypoint', 'introduceHereBearerTokenFromAuthLogin')

Check out your users table from docker database and extract them as a json so you can use the array of users in the browser.

Now, type the following in any browser window:

 users.forEach(user => ws.send(JSON.stringify({event: 'send_chat_message_to_participant', data: {message: 'test', participantId: user.id}})));

This will send individual chat message to all participants. You can also check docker logs to see it in action.

Regardless of which NestJS instance grabs the WebSocket connection, the messages are consistently sent to participants. This is how you scale a NestJS chat app to millions of users.

If you are interested in learning how to deploy this stack on Kubernetes, leave a comment and i will do the tutorial.

If you want to collaborate on potential start-up projects, you can reach me at: rares.tarabega27@gmail.com

If you want to check out an improved and more efficient model for broadcasting messages between instances, as well as how to deploy this stack on Kubernetes, you can find Part 2 of this series here.