📨 धडा 11 — Backends शी बोलणे: काउंटरच्या चिठ्ठ्या भरणे

📍 तुम्ही इथे आहात: 12 पैकी धडा 11 · मागील: lesson-10-testing · पुढील: lesson-12-build-deploy-observe

📦 या ब्रँचमध्ये काय आहे

धडे 01–10, आणि त्यासोबत फलक आणि काउंटर यांच्यातली सीमा: CORS, browser मधली credentials, प्रत्येक request चे तीन चेहरे, आणि दोन सुरक्षा नियम — फलकावर कधीच विश्वास ठेवू नका, मजकूर कधीच HTML म्हणून घालू नका.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

फलक काउंटरवर चिठ्ठ्या भरतो (API शाळा). फलक एका अनोळखी माणसाच्या browser मध्ये चालतो, म्हणून चार गोष्टी वेगळ्या असतात:

CORS 🚧 — काउंटरने परवानगी दिल्याशिवाय (Access-Control-Allow-Origin) browser एका origin वरच्या page ला दुसऱ्या origin चे response वाचू देत नाही. साध्या GET पलीकडच्या कोणत्याही गोष्टीसाठी browser आधी परवानगी मागतो (एक OPTIONS preflight). आपला छोटा काउंटर दोन्हींना उत्तर देतो.
Browser मध्ये काहीच गुप्त नसते 🪪 — तुम्ही पाठवलेला प्रत्येक byte वाचता येतो. JavaScript मध्ये API keys नकोत. Users ना कमी काळ टिकणारे tokens मिळतात (किंवा JS वाचू शकत नाही अशी httpOnly cookie); दीर्घकाळ टिकणाऱ्या machine keys servers वरच राहतात.
नेहमी तीन चेहरे ⏳ — loading, यश, error. फक्त यश दाखवणारा फलक, काउंटर मंद किंवा बंद असला की कोरे पान दाखवतो.
फलकावर कधीच विश्वास ठेवू नका 🛡️ — तुमचे form validation हे users साठी केलेली मेहेरबानी आहे; कोणीही थेट request पाठवू शकतो. काउंटर पुन्हा validate करतो आणि अडचणींसह 400 परत करतो (API शाळेचा धडा 04). आणि उलट बाजूने: काउंटरचा मजकूर page मध्ये innerHTML ने कधीच घालू नका — <img src=x onerror=alert(1)> नावाचा विद्यार्थी code चालवेल. नेहमी textContent.

🗺️ आकृती

sequenceDiagram
    participant B as 📌 board (browser)
    participant C as 🏢 counter (API)
    B->>C: 1 OPTIONS /api/students (preflight — non-simple request)
    C-->>B: 2 Access-Control-Allow-Origin/Methods/Headers
    B->>C: 3 POST /api/students {name, class}  ← board validated (kindness)
    C-->>B: 4 400 {"error":{"code":"validation_failed"}}  ← counter validated (truth)
    Note over B: draw the error face · textContent, never innerHTML

❓ काय

Origin = scheme + host + port. वेगळा origin → CORS लागू होतो. Simple requests (साध्या content types सह GET/POST) थेट जातात; बाकी सगळ्यांचा OPTIONS ने preflight होतो.
Credentials: fetch(url, {credentials: 'include'}) cross-origin cookies पाठवतो — आणि मग काउंटरने नेमका origin सांगावा लागतो (* नाही) आणि Access-Control-Allow-Credentials लावावे लागते.
Token कुठे ठेवायचा: inject झालेली कोणतीही script localStorage वाचू शकते (XSS); httpOnly cookies JS वाचू शकत नाही पण त्यांना CSRF संरक्षण लागते (SameSite=Lax/Strict). दोन्हीकडे मुदत कमी ठेवा.
Code मधले तीन चेहरे: loading लावा → render; fetch ला try करा, r.ok तपासा, parse करा; catch error लावतो; finally loading काढतो आणि render करतो. Error चेहऱ्याला retry द्या.
XSS पासून बचाव: textContent/createElement (किंवा framework चे escaping), Content-Security-Policy header, आणि data सह कधीच innerHTML, eval, किंवा new Function नाही.
Timeouts आणि retries client वरही हवेत (API शाळेचा धडा 10): AbortSignal.timeout, आणि 429/5xx साठी backoff.

🤔 का

कारण front-end मधल्या सगळ्यात सामान्य दोन सुरक्षा घटना याच सीमेवर घडतात (bundle मध्ये पाठवलेली उघड झालेली key; user च्या मजकुरातून XSS), आणि सगळ्यात सामान्य विश्वासार्हतेची तक्रारही इथेच असते ("ते फक्त फिरत राहते" — timeout नाही, error चेहरा नाही). चारपैकी तीन नियमांची किंमत प्रत्येकी एक ओळ आहे.

🔧 कसे (या repo मध्ये)

ui/app.js: load() आणि enrol() तीन चेहरे दाखवतात; StudentCard user ने दिलेल्या प्रत्येक value साठी textContent वापरतो. ui/mock_api.py CORS headers लावतो, OPTIONS ला उत्तर देतो, form server-side वर पुन्हा validate करतो, आणि ?slow=1 व ?fail=1 देतो म्हणजे तुम्ही हवा तेव्हा प्रत्येक चेहरा पाहू शकता.

🧪 करून पाहा

python3 ui/mock_api.py
# 1) the three faces: edit API in app.js to '/api/students?slow=1' (loading), then '?fail=1' (error), then back
# 2) never trust the board — bypass the form entirely:
curl -s -X POST http://127.0.0.1:8000/api/students -H 'Content-Type: application/json' -d '{"name":"X","class":"9Z"}'
#    → 400 validation_failed. The counter refused what the board never would have sent.
# 3) XSS, safely: enrol a student named  <b>bold</b>  — the card shows the literal text (textContent).
#    Then temporarily use innerHTML in StudentCard and enrol  <img src=x onerror="alert('xss')">  — see it fire. Undo it.
# 4) CORS: open the board from a different origin (python3 -m http.server 9001 in ui/) and watch the console —
#    then notice mock_api.py's Access-Control-Allow-Origin header is what makes the fetch work at all.

✅ तपासा — तुम्हाला काय दिसायला हवे

Loading आणि error चेहरे हवे तेव्हा दिसतात आणि कधीच कोरे पान सोडत नाहीत. थेट curl ला 400 validation_failed मिळतो — काउंटर फलकावर विश्वास ठेवत नाही याचा पुरावा. <b>bold</b> विद्यार्थी textContent सह मजकूर म्हणून दिसतो आणि innerHTML सह markup म्हणून (किंवा त्याहून वाईट).

🏁 तुम्ही आत्ताच काय सिद्ध केले

फलक request चा प्रत्येक निकाल हाताळतो, आणि तुम्ही दोन्ही सुरक्षा नियम — server-side validation आणि escaping — दोन्ही बाजूंनी दाखवले.

⚠️ नेहमीच्या चुका

front-end code मध्ये किंवा bundle होणाऱ्या .env files मध्ये API keys किंवा secrets
user किंवा API ने दिलेल्या कोणत्याही गोष्टीसह innerHTML
client-side validation वर विश्वास ठेवणे (एक curl एका ओळीत त्याला वळसा घालतो)
credentials सह Access-Control-Allow-Origin: * (browsers ते नाकारतात, योग्य कारणासाठी)
timeout नाही, error चेहरा नाही, retry नाही

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: प्रत्येक security checklist वरच्या दोन front-end गोष्टी म्हणजे XSS आणि उघड झालेल्या keys, आणि "page कायम फिरत राहते" हे सगळ्यात सामान्य support ticket आहे. चार नियम, चार ओळी, बहुतेक धोका.

⏭️ पुढे

शेवटचा टप्पा: build, deploy आणि observe — लोकांना दिसेल अशा ठिकाणी फलक लावणे, आणि काय घडते त्यावर लक्ष ठेवणे.

git checkout lesson-12-build-deploy-observe

📨 Lesson 11 — Talking to backends: filling in the counter's slips

📍 You are here: Lesson 11 of 12 · Previous: lesson-10-testing · Next: lesson-12-build-deploy-observe

📦 What's in this branch

Lessons 01–10, plus the boundary between board and counter: CORS, credentials in a browser, the three faces of every request, and the two security rules — never trust the board, never inject text as HTML.

🧒 Explain like I'm 5

The board fills in slips at the counter (the API school). Four things are different because the board runs inside a stranger's browser:

CORS 🚧 — the browser will not let a page at one origin read a response from another unless the counter says it may (Access-Control-Allow-Origin). For anything beyond a simple GET, the browser asks permission first (an OPTIONS preflight). Our little counter answers both.
Nothing in the browser is secret 🪪 — every byte you ship can be read. No API keys in JavaScript. Users get short-lived tokens (or an httpOnly cookie the JS cannot read); long-lived machine keys stay on servers.
Three faces, always ⏳ — loading, success, error. A board that only draws success shows a blank page whenever the counter is slow or down.
Never trust the board 🛡️ — your form validation is a kindness to users; anyone can send a raw request. The counter validates again and returns 400 with problems (API school lesson 04). And the reverse: never put counter text into the page with innerHTML — a student named <img src=x onerror=alert(1)> would run code. textContent, always.

🗺️ Diagram

sequenceDiagram
    participant B as 📌 board (browser)
    participant C as 🏢 counter (API)
    B->>C: 1 OPTIONS /api/students (preflight — non-simple request)
    C-->>B: 2 Access-Control-Allow-Origin/Methods/Headers
    B->>C: 3 POST /api/students {name, class}  ← board validated (kindness)
    C-->>B: 4 400 {"error":{"code":"validation_failed"}}  ← counter validated (truth)
    Note over B: draw the error face · textContent, never innerHTML

❓ What

Origin = scheme + host + port. Different origin → CORS applies. Simple requests (GET/POST with basic content types) go straight out; anything else preflights with OPTIONS.
Credentials: fetch(url, {credentials: 'include'}) sends cookies cross-origin — and then the counter must name the exact origin (not *) and set Access-Control-Allow-Credentials.
Token storage: localStorage is readable by any script that gets injected (XSS); httpOnly cookies are not readable by JS but need CSRF protection (SameSite=Lax/Strict). Short expiry either way.
The three faces in code: set loading → render; try the fetch, check r.ok, parse; catch sets error; finally clears loading and renders. Give the error face a retry.
XSS defences: textContent/createElement (or a framework's escaping), a Content-Security-Policy header, and never innerHTML, eval, or new Function with data.
Timeouts and retries belong on the client too (API school lesson 10): AbortSignal.timeout, and backoff for 429/5xx.

🤔 Why

Because this boundary is where the two most common front-end security incidents live (a leaked key shipped in a bundle; an XSS through user text), and where the most common reliability complaint lives ("it just spins" — no timeout, no error face). Three of the four rules cost one line each.

🔧 How (in this repo)

ui/app.js: load() and enrol() show the three faces; StudentCard uses textContent for every user-supplied value. ui/mock_api.py sets the CORS headers, answers OPTIONS, re-validates the form server-side, and offers ?slow=1 and ?fail=1 so you can see each face on demand.

🧪 Try it

python3 ui/mock_api.py
# 1) the three faces: edit API in app.js to '/api/students?slow=1' (loading), then '?fail=1' (error), then back
# 2) never trust the board — bypass the form entirely:
curl -s -X POST http://127.0.0.1:8000/api/students -H 'Content-Type: application/json' -d '{"name":"X","class":"9Z"}'
#    → 400 validation_failed. The counter refused what the board never would have sent.
# 3) XSS, safely: enrol a student named  <b>bold</b>  — the card shows the literal text (textContent).
#    Then temporarily use innerHTML in StudentCard and enrol  <img src=x onerror="alert('xss')">  — see it fire. Undo it.
# 4) CORS: open the board from a different origin (python3 -m http.server 9001 in ui/) and watch the console —
#    then notice mock_api.py's Access-Control-Allow-Origin header is what makes the fetch work at all.

✅ Verify — what you should see

Loading and error faces appear on demand and never leave a blank page. The raw curl gets 400 validation_failed — proof the counter does not trust the board. The <b>bold</b> student renders as text with textContent and as markup (or worse) with innerHTML.

🏁 What you just proved

The board handles every outcome of a request, and you demonstrated both security rules — server-side validation and escaping — from both sides.

⚠️ Common mistakes

API keys or secrets in front-end code or .env files that get bundled
innerHTML with anything a user or API supplied
trusting client-side validation (a curl bypasses it in one line)
Access-Control-Allow-Origin: * together with credentials (browsers refuse it, for good reason)
no timeout, no error face, no retry

🏭 Why this matters in production: XSS and leaked keys are the two front-end items on every security checklist, and "the page spins forever" is the most common support ticket. Four rules, four lines, most of the risk.

⏭️ Next

The last mile: build, deploy and observe — pinning the board up where people can see it, and watching what happens.

git checkout lesson-12-build-deploy-observe

← Previoustesting Next →build deploy observe

This page is the lesson's README from the lesson-11-talking-to-backends branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.