Day 08 Theory — Streaming with SSE, Cancellation and Partial Failure

Lesson Overview

This is the applied companion for Day 08. Read DAY_08_THEORY.md first for the beginner-first teaching of Streaming with SSE, Cancellation & Partial Failure. Then use the real service-desk-day-08/ project to trace, run, debug, and explain the concept.

Service Desk Alignment

Day 08 adds Streaming with SSE, Cancellation & Partial Failure to the running Service Desk. Start with app.py, stream.py, services.py, models.py, then follow imports and tests to identify the actual runtime path.

Why This Topic Matters

The theory chapter explains why Streaming with SSE, Cancellation & Partial Failure is needed. Here the goal is evidence: identify where the capability is implemented, what observable behavior changes, and how the repository proves both success and failure behavior.

System Architecture

graph TD
    A[Client EventSource] --> B[GET /api/v1/stream]
    B --> C[Async Token Generator]
    C -->|Chunk 1| A
    C -->|Chunk 2| A
    A -.->|Client Abort| D[is_disconnected() == True]
    D --> E[Terminate Generator & Release Resources]

Worked Code Example: SSE Streaming

import asyncio
from fastapi import FastAPI, Request
from sse_starlette.sse import EventSourceResponse

app = FastAPI()

async def token_generator(request: Request):
    tokens = ["Resolving", " Service", " Desk", " Ticket", " #1042...", " Done!"]
    try:
        for token in tokens:
            if await request.is_disconnected():
                print("Client disconnected! Cleaning up token generator...")
                break
            yield {"event": "token", "data": token}
            await asyncio.sleep(0.2)
    except asyncio.CancelledError:
        print("Streaming task cancelled by client disconnect.")

@app.get("/api/v1/stream")
async def stream_resolution(request: Request):
    return EventSourceResponse(token_generator(request))

Code Walkthrough & Mechanics

Read app.py, stream.py, services.py, models.py with these theory sections beside you:

• Why streaming changes the user experience — locate its implementation and evidence.
• Ordinary HTTP response versus streaming response — locate its implementation and evidence.
• What SSE provides — locate its implementation and evidence.
• SSE is one-way — locate its implementation and evidence.
• Streaming introduces a protocol of events — locate its implementation and evidence.

For each concept identify the real function/class/protocol boundary, its input/state, its observable result, and the assertion in tests/test_streaming.py that proves the behavior. If a concept has no implementation or evidence, record that as a gap rather than inventing one.

Common Mistakes & Debugging Guidance

Use the theory—not generic timeout or .env advice—to decide what can fail today.

Failure lens: revisit SSE is one-way, Streaming introduces a protocol of events.

• Reproduce the smallest case that violates one of those expectations.
• Trace the real Day 08 modules until you find the first incorrect state/output/decision.
• Use tests/test_streaming.py as executable evidence.
• Add a regression test if the failure is not already represented.
• Fix the smallest responsible boundary and rerun the relevant test before the full suite.

Your debugging explanation must name the topic-specific invariant that failed, not merely say “an exception occurred.”

Practical Lab Instructions

1. Summarize these theory ideas before opening the implementation:
   • Why streaming changes the user experience
   • Ordinary HTTP response versus streaming response
   • What SSE provides
   • SSE is one-way
2. Inspect the most relevant real Day 08 modules first:
   • service_desk/app.py
   • service_desk/stream.py
   • service_desk/services.py
   • service_desk/models.py
3. Inspect the automated evidence:
   • tests/test_streaming.py
4. Establish the baseline:

   cd service-desk-day-08
   PYTHONPATH=. pytest tests/test_streaming.py -q
   

5. Trace one theory concept through the actual nested modules and tests.
6. Run one success case and record input → mechanism → observable result.
7. Exercise one topic-specific failure/boundary case and name the invariant that protects the system.
8. Re-run the relevant tests and explain theory → implementation → evidence.

Done when: another student can reproduce your trace without relying on an invented sample.

Key Takeaways

1. Be able to explain Why streaming changes the user experience and point to its implementation/evidence in Day 08.
2. Be able to explain Ordinary HTTP response versus streaming response and point to its implementation/evidence in Day 08.
3. Be able to explain What SSE provides and point to its implementation/evidence in Day 08.

Knowledge Check & Scenario Questions

1. Concept: Using Why streaming changes the user experience, explain the engineering problem Day 08 is solving without naming a framework as the answer.
2. Mechanism: How does Ordinary HTTP response versus streaming response appear in the real project? Start from service_desk/app.py and name the observable state/output/event that changes.
3. Failure: For What SSE provides, describe one incorrect implementation or boundary condition and the evidence you would expect in tests/test_streaming.py.
4. Design review: Which assumption in today's design would you verify before reusing this implementation in a different production system?

Official References

• FastAPI Custom Responses & Streaming: https://fastapi.tiangolo.com/advanced/custom-response/#streamingresponse
• MDN Server-Sent Events Standard: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events