🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

📨 धडा 01 — Partial failure: निरोप्यामार्फत बोलणाऱ्या शाखा

📍 तुम्ही इथे आहात: 12 पैकी धडा 01 · पुढे: lesson-02-clocks

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

हा संपूर्ण कोर्स ज्या एका प्रश्नाबद्दल आहे तो असा: शाळेच्या आता चार शाखा आहेत — पुणे, नाशिक, नागपूर आणि कोल्हापूर. त्या एकाच नोंदवहीच्या प्रती ठेवतात (गुण, timetables, फी). त्या खोलीच्या पलीकडे ओरडून बोलू शकत नाहीत. त्या निरोप्यामार्फत चिठ्ठ्या पाठवतात. चिठ्ठ्या हरवतात. निरोपे हळू असतात. रस्ते तुटतात. एखादी शाखा दिवसभर बंद राहू शकते. संपूर्ण कोर्सभर तुम्ही वापराल त्या खऱ्या files:

dist/sim.py — शाखांचे छोटे deterministic models, शुद्ध Python मध्ये (153 ओळी, शून्य dependencies)
dist/demo.py — प्रत्येक धडा एक छोटा program म्हणून (python3 dist/demo.py <section>; sections: failures clocks ordering detection replication quorums models cap raft locks exactlyonce backpressure)
dist/test_dist.py — शाखांच्या नियमांवर 12 checks
demo-output.txt — निरोगी run काय print करतो ते

🎒 सुरू करण्याआधी: तुम्हाला फक्त Python 3 हवे, बाकी काहीच नाही — cloud account नाही, pip install नाही. sim.py मध्ये शिकवण्यासाठीचे models आहेत, खऱ्या systems नाहीत. Randomness seeded आहे, त्यामुळे प्रत्येक run तीच गोष्ट print करतो. खऱ्या systems म्हणजे etcd आणि ZooKeeper (एकमत), Cassandra आणि DynamoDB (quorums), PostgreSQL (replication) आणि Kafka (logs). on a real account असे चिन्हांकित commands साठी त्या systems चालू असाव्या लागतात, आणि त्यांना पैसे लागू शकतात.

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

कतरिना पुणे office मध्ये काम करते. तिला जाणून घ्यायचे आहे: "Exam 10 वाजता आहे का?" उत्तर नाशिक मध्ये आहे. म्हणून ती एक चिठ्ठी लिहिते आणि निरोप्याकडे देते.

ती वाट पाहते. उत्तर येत नाही.

काय झाले? कतरिनाला कळू शकत नाही.

कदाचित निरोप्याने वाटेत चिठ्ठी हरवली. 📨❌
कदाचित आज नाशिक बंद आहे. 🏚️
कदाचित नाशिकने उत्तर दिले, आणि ते उत्तर परतीच्या वाटेवर हरवले. ↩️❌
कदाचित सगळे ठीक आहे, आणि आज रस्ता फक्त हळू आहे. 🐢

पुण्याहून पाहिले तर चारही गोष्टी अगदी सारख्याच दिसतात: शांतता. हेच partial failure. शाळेचा एक भाग बिघडलेला आहे, बाकीचे भाग अजून चालू आहेत, आणि कोणता भाग बिघडला ते कोणालाच दिसत नाही.

एकाच campus वर असे कधीच होत नाही. Office बंद असेल तर तुम्हाला कुलूप लावलेले दार दिसते. अनेक campuses असले की तुम्हाला फक्त शांतता दिसते.

🗺️ आकृती

flowchart LR
    pune["🏫 Pune<br/>Katrina asks: exam at 10?"]
    nashik["🏫 Nashik<br/>has the answer"]
    pune -->|"note 1: arrives after 5–48 ms"| nashik
    pune -.->|"note 2: lost on the road"| nashik
    nashik -.->|"the answer: lost on the way back"| pune
    x["🏚️ or Nashik is closed"]
    s["🐢 or the road is just slow"]
    q["❓ Pune sees the same thing<br/>every time: silence"]
    pune --- q
    x --- q
    s --- q

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/distributed-systems/lesson-diagrams.html#l01

❓ काय

Distributed system — अनेक machines (nodes) जी मिळून काम करतात आणि फक्त network वरून messages पाठवून बोलतात. इथे: चार शाखा आणि त्यांचे निरोपे.
Partial failure — काही भाग बंद पडतात तर बाकीचे चालू राहतात. हरवलेले उत्तर म्हणजे हरवलेली request, crash झालेला node, हरवलेला reply की हळू network हे node ला सांगता येत नाही. एका computer मध्ये गोष्टी सहसा एकत्र चालतात किंवा एकत्र बंद पडतात. Distributed system मध्ये partial failure ही नेहमीची गोष्ट आहे.
Timeout — पाठवणाऱ्याकडे असलेले एकमेव साधन: "2 सेकंदांत उत्तर आले नाही तर ते failed समजा". Timeout काय झाले ते सांगत नाही. Request दुसऱ्या बाजूला तरीही पूर्ण झालेली असू शकते.
Network partition — network असे गटांमध्ये विभागले जाते जे एकमेकांपर्यंत पोहोचू शकत नाहीत. प्रत्येक गट आपल्या आत अजून काम करतो. Lab मधले Net.partition(a, b) एक रस्ता तोडते.
Distributed computing चे आठ गैरसमज (eight fallacies) — नवीन distributed programs अनेकदा गृहीत धरतात अशा आठ चुकीच्या समजुती (Sun Microsystems मध्ये L. Peter Deutsch आणि इतरांनी 1990s मध्ये गोळा केल्या):
1. network विश्वासार्ह आहे
2. latency शून्य आहे
3. bandwidth अमर्याद आहे
4. network सुरक्षित आहे
5. topology बदलत नाही
6. एकच administrator आहे
7. transport ची किंमत शून्य आहे
8. network homogeneous आहे (सगळे एकाच प्रकारचे)
Demo त्यापैकी चार print करतो. हा कोर्स मुख्यतः पहिल्या दोनबद्दल आहे.

🤔 का

कारण बहुतेक खऱ्या systems आधीच distributed असतात: browser आणि API, API आणि database, service आणि queue, तीन इमारतींमध्ये तीन database प्रती. दोन boxes मधला प्रत्येक बाण म्हणजे रस्त्यावरचा एक निरोप्या. Code जर "मी विचारले, म्हणून मला उत्तर मिळेल" असे गृहीत धरत असेल, तर तो कायम वाट पाहील, चुकीच्या वेळी retry करेल, किंवा तेच payment दोनदा करेल. कोर्सचा उरलेला भाग प्रत्येक प्रश्नासाठी साधने देतो. पहिली पायरी म्हणजे हे मान्य करणे की शांततेतून जवळजवळ काहीच कळत नाही.

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

dist/sim.py मधले Net(loss, min_ms, max_ms, seed) म्हणजे रस्ता. send(a, b) milliseconds मध्ये delay परत देते, किंवा चिठ्ठी कधीच पोहोचत नाही तेव्हा None — कारण ती हरवली (loss म्हणजे त्याची शक्यता) किंवा रस्ता तुटलेला आहे (partition(a, b); heal() प्रत्येक रस्ता दुरुस्त करते). एक छोटा seeded random generator (Rng) प्रत्येक run मध्ये तेच numbers print करायला लावतो. dist/demo.py मधले failures() 10% loss rate ने पुण्याहून नाशिकला 20 चिठ्ठ्या पाठवते.

🧪 करून पाहा

python3 dist/demo.py failures
python3 - <<'EOF'
import sys; sys.path.insert(0, "dist"); from sim import Net
for loss in (0.0, 0.1, 0.3, 0.5):
    net = Net(loss=loss, seed=3)
    notes = [net.send("pune", "nashik") for _ in range(20)]
    print(f"loss {loss:.0%} → arrived {20 - notes.count(None):>2} of 20 · lost {notes.count(None)}")
net = Net(seed=3); net.partition("pune", "nashik")
print("road cut  → pune→nashik:", net.send("pune", "nashik"), "· pune→nagpur:", net.send("pune", "nagpur"))
net.heal(); print("road healed → pune→nashik:", net.send("pune", "nashik"), "ms")
EOF
python3 dist/test_dist.py

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

failures हे print करते:

── Pune sends 20 notes to Nashik by messenger (10% get lost, 5–50 ms each)
   arrived 18 of 20 · delays 5–48 ms · lost 2

तुमचा snippet हे print करतो:

loss 0% → arrived 20 of 20 · lost 0
loss 10% → arrived 18 of 20 · lost 2
loss 30% → arrived 16 of 20 · lost 4
loss 50% → arrived  8 of 20 · lost 12
road cut  → pune→nashik: None · pune→nagpur: 15
road healed → pune→nashik: 16 ms

Tests शेवटी 12/12 passed दाखवतात.

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

हरवलेली चिठ्ठी आणि तुटलेला रस्ता दोन्ही पुण्याला एकच उत्तर देतात: None. पाठवणाऱ्याच्या बाजूने काहीच फरक नाही. आणि पुणे–नाशिक रस्ता तुटलेला असतानाही पुणे–नागपूर रस्ता अजून चालतो (15 ms) — शाळा अंशतः बिघडलेली आहे, पूर्ण नाही. हेच partial failure.

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

timeout शिवाय दुसऱ्या machine ला call करणे — call करणारा कायम वाट पाहतो
timeout चा अर्थ "दुसऱ्या बाजूने काहीच केले नाही" असा घेणे — त्याने काम केलेले असू शकते
duplicate ओळखण्याचा मार्ग नसताना timeout नंतर payment retry करणे (धडा 11)
फक्त एका laptop वर test करणे, जिथे network कधीच काही हरवत नाही
"एका data center च्या आत network विश्वासार्ह असते" असे समजणे — तिथेही switches आणि cables बिघडतात

🏭 प्रत्यक्ष वापरात

प्रत्येक network call ला timeout हवा. On a real account — connect timeout आणि total timeout सह curl:

curl --connect-timeout 2 --max-time 5 https://api.school.example/exam-time

Python मध्ये, तुम्ही दिला नाही तर requests ला कोणताही timeout नसतो:

import requests
r = requests.get("https://api.school.example/exam-time", timeout=(2, 5))  # (connect, read) seconds

gRPC calls सोबत एक deadline असते जी request बरोबर प्रवास करते, त्यामुळे वाटेवरच्या प्रत्येक service ला किती वेळ उरला आहे ते कळते:

stub.GetExamTime(request, timeout=5.0)   # the call fails with DEADLINE_EXCEEDED after 5 s

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: तुमच्या services मधला प्रत्येक बाण काढा. प्रत्येकासाठी लिहा: त्याचा timeout, शांतता असल्यास काय होते, आणि call पुन्हा करणे सुरक्षित आहे का. ज्या बाणाला उत्तरे नाहीत, तिथूनच पुढचे outage सुरू होते.

⏭️ पुढे

शांतता हा एक प्रश्न. वेळ हा पुढचा: प्रत्येक शाखेचे स्वतःचे घड्याळ असते, आणि कोणतीही दोन घड्याळे जुळत नाहीत.

git checkout lesson-02-clocks

📨 Lesson 01 — Partial failure: branches that talk by messenger

📍 You are here: Lesson 01 of 12 · Next: lesson-02-clocks

📦 What's in this branch

The one problem this whole course is about: the school now has four branch campuses — Pune, Nashik, Nagpur and Kolhapur. They keep copies of one register (grades, timetables, fees). They cannot shout across the room. They send notes by messenger. Notes get lost. Messengers are slow. Roads get cut. A branch can close for the day. Real files you will use all the way through:

dist/sim.py — the branch campuses as small deterministic models, in pure Python (153 lines, zero dependencies)
dist/demo.py — every lesson as a small program (python3 dist/demo.py <section>; sections: failures clocks ordering detection replication quorums models cap raft locks exactlyonce backpressure)
dist/test_dist.py — 12 checks on the branches' rules
demo-output.txt — what a healthy run prints

🎒 Before you start: you need Python 3 and nothing else — no cloud account, no pip install. sim.py holds teaching models, not real systems. Randomness is seeded, so every run prints the same story. The real systems are etcd and ZooKeeper (agreement), Cassandra and DynamoDB (quorums), PostgreSQL (replication) and Kafka (logs). Commands marked on a real account need those systems running, and they can cost money.

🧒 Explain like I'm 5

Katrina works in the Pune office. She needs to know: "Is the exam at 10?" The answer is in Nashik. So she writes a note and gives it to a messenger.

She waits. No answer comes.

What happened? Katrina cannot know.

Maybe the messenger lost the note on the way. 📨❌
Maybe Nashik is closed today. 🏚️
Maybe Nashik answered, and the answer was lost on the way back. ↩️❌
Maybe everything is fine, and the road is just slow today. 🐢

From Pune, all four look exactly the same: silence. That is partial failure. One part of the school is broken, the other parts still work, and nobody can see which part.

On one campus this never happens. If the office is closed, you see the locked door. With many campuses, you only see silence.

🗺️ Diagram

flowchart LR
    pune["🏫 Pune<br/>Katrina asks: exam at 10?"]
    nashik["🏫 Nashik<br/>has the answer"]
    pune -->|"note 1: arrives after 5–48 ms"| nashik
    pune -.->|"note 2: lost on the road"| nashik
    nashik -.->|"the answer: lost on the way back"| pune
    x["🏚️ or Nashik is closed"]
    s["🐢 or the road is just slow"]
    q["❓ Pune sees the same thing<br/>every time: silence"]
    pune --- q
    x --- q
    s --- q

🗺️ Drawn version + a lab: https://school-edh.pages.dev/distributed-systems/lesson-diagrams.html#l01

❓ What

Distributed system — several machines (nodes) that work together and talk only by sending messages over a network. Here: four branches and their messengers.
Partial failure — some parts fail while others keep working. A node cannot tell whether a missing answer means a lost request, a crashed node, a lost reply or a slow network. In one computer, things usually work or fail together. In a distributed system, partial failure is normal.
Timeout — the only tool a sender has: "if no answer in 2 seconds, treat it as failed". A timeout does not tell you what happened. The request may still have been done on the other side.
Network partition — the network splits into groups that cannot reach each other. Each group still works inside itself. Net.partition(a, b) in the lab cuts one road.
The eight fallacies of distributed computing — eight false beliefs that new distributed programs often assume (collected at Sun Microsystems by L. Peter Deutsch and others in the 1990s):
1. the network is reliable
2. latency is zero
3. bandwidth is infinite
4. the network is secure
5. topology does not change
6. there is one administrator
7. transport cost is zero
8. the network is homogeneous (all the same kind)
The demo prints four of them. This course is mostly about the first two.

🤔 Why

Because most real systems are already distributed: a browser and an API, an API and a database, a service and a queue, three database copies in three buildings. Every arrow between two boxes is a messenger on a road. If the code assumes "I asked, so I will get an answer", it will wait forever, retry at the wrong time, or do the same payment twice. The rest of the course gives you tools for each problem. The first step is to accept that silence tells you almost nothing.

🔧 How (in this repo)

Net(loss, min_ms, max_ms, seed) in dist/sim.py is the road. send(a, b) returns a delay in milliseconds, or None when the note never arrives — because it was lost (loss is the chance of that) or because the road is cut (partition(a, b); heal() repairs every road). A tiny seeded random generator (Rng) makes every run print the same numbers. failures() in dist/demo.py sends 20 notes from Pune to Nashik with a 10% loss rate.

🧪 Try it

python3 dist/demo.py failures
python3 - <<'EOF'
import sys; sys.path.insert(0, "dist"); from sim import Net
for loss in (0.0, 0.1, 0.3, 0.5):
    net = Net(loss=loss, seed=3)
    notes = [net.send("pune", "nashik") for _ in range(20)]
    print(f"loss {loss:.0%} → arrived {20 - notes.count(None):>2} of 20 · lost {notes.count(None)}")
net = Net(seed=3); net.partition("pune", "nashik")
print("road cut  → pune→nashik:", net.send("pune", "nashik"), "· pune→nagpur:", net.send("pune", "nagpur"))
net.heal(); print("road healed → pune→nashik:", net.send("pune", "nashik"), "ms")
EOF
python3 dist/test_dist.py

✅ Verify — what you should see

failures prints:

── Pune sends 20 notes to Nashik by messenger (10% get lost, 5–50 ms each)
   arrived 18 of 20 · delays 5–48 ms · lost 2

Your snippet prints:

loss 0% → arrived 20 of 20 · lost 0
loss 10% → arrived 18 of 20 · lost 2
loss 30% → arrived 16 of 20 · lost 4
loss 50% → arrived  8 of 20 · lost 12
road cut  → pune→nashik: None · pune→nagpur: 15
road healed → pune→nashik: 16 ms

The tests end with 12/12 passed.

🏁 What you just proved

A lost note and a cut road both give Pune the same answer: None. From the sender's side there is no difference. And while the Pune–Nashik road is cut, the Pune–Nagpur road still works (15 ms) — the school is partly broken, not fully broken. That is partial failure.

⚠️ Common mistakes

calling another machine with no timeout — the caller waits forever
reading a timeout as "the other side did nothing" — it may have done the work
retrying a payment after a timeout without a way to spot a duplicate (lesson 11)
testing only on one laptop, where the network never loses anything
thinking "the network is reliable inside one data center" — switches and cables fail there too

🏭 In production

Every network call needs a timeout. On a real account — curl with a connect timeout and a total timeout:

curl --connect-timeout 2 --max-time 5 https://api.school.example/exam-time

In Python, requests has no timeout unless you give one:

import requests
r = requests.get("https://api.school.example/exam-time", timeout=(2, 5))  # (connect, read) seconds

gRPC calls carry a deadline that travels with the request, so every service on the path knows how much time is left:

stub.GetExamTime(request, timeout=5.0)   # the call fails with DEADLINE_EXCEEDED after 5 s

🏭 Why this matters in production: draw every arrow between your services. For each one, write: its timeout, what happens on silence, and whether the call is safe to repeat. An arrow with no answers is where the next outage starts.

⏭️ Next

Silence is one problem. Time is the next one: each branch has its own clock, and no two clocks agree.

git checkout lesson-02-clocks

← Course homeall lessons Next →clocks

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