Network Stack | HTTP and TCP/IP

server {
    # ==============================================================================
    # REVERSE PROXY: DNS to Internal Port Mapping
    # ==============================================================================
    # KEY CONCEPT: This nginx server acts as a REVERSE PROXY
    #
    # THE FLOW:
    # 1. DNS Resolution: flask.opencodingsociety.com → opencodingsociety.com → 3.233.212.71
    # 2. Nginx listens on port 80/443 (standard HTTP/HTTPS ports)
    # 3. Nginx receives the request for flask.opencodingsociety.com
    # 4. Nginx FORWARDS (proxies) the request to localhost:8587 (Flask app)
    # 5. Flask processes the request and returns response to nginx
    # 6. Nginx sends the response back to the client
    #
    # NETWORK LAYERS: How data travels across the internet
    # When browser sends request → travels DOWN the OSI layers:
    #   Layer 7 (Application): HTTP/HTTPS request created
    #   Layer 6 (Presentation): Encryption (TLS/SSL)
    #   Layer 5 (Session): Connection management
    #   Layer 4 (Transport): TCP segments with ports (443)
    #   Layer 3 (Network): IP packets with addresses (24.18.xxx.xxx → 3.233.212.71)
    #   Layer 2 (Data Link): Ethernet frames (MAC addresses)
    #   Layer 1 (Physical): Electrical signals on wire/fiber
    #
    # At server → travels UP the layers:
    #   Physical signals → Ethernet → IP packets → TCP → HTTP → NGINX processes
    #
    # Response follows same path backwards (down on server, up at client)
    #
    # WHY USE A REVERSE PROXY? (Key Teaching Points)
    # - SECURITY: Flask app only listens on localhost (not exposed to internet)
    # - SSL/TLS: Nginx handles HTTPS encryption (certbot/Let's Encrypt integration)
    # - PORT MAPPING: Users access standard port 80/443, not obscure port 8587
    # - MULTIPLE APPS: One server can host many apps on different ports
    #   Example: flask.opencodingsociety.com → localhost:8587, spring.opencodingsociety.com → localhost:8585
    # - LOAD BALANCING: Can distribute requests across multiple backend servers
    # - CACHING: Nginx can cache responses to improve performance
    #
    # WITHOUT REVERSE PROXY: Users would need flask.opencodingsociety.com:8587
    # WITH REVERSE PROXY: Users access clean URL flask.opencodingsociety.com
    # ==============================================================================
    listen 80;
    listen [::]:80;
    server_name flask.opencodingsociety.com;

    # ==============================================================================
    # WEBSOCKET PROXY: Real-Time Bidirectional Communication
    # ==============================================================================
    # Socket.IO enables REAL-TIME features: live chat, notifications, collaborative editing
    # 
    # WEBSOCKET vs HTTP:
    #   HTTP: Request → Response → Connection closes (like a letter)
    #   WebSocket: Persistent connection, bidirectional (like a phone call)
    #
    # UPGRADE HANDSHAKE (How HTTP becomes WebSocket):
    #   1. Browser sends HTTP request with "Upgrade: websocket" header
    #   2. Server responds "101 Switching Protocols"
    #   3. Same TCP connection is now upgraded to WebSocket protocol
    #   4. Both sides can now send messages anytime (no request/response pattern)
    #
    # WHY SEPARATE location /socket.io/ BLOCK?
    #   - Socket.IO connections need special headers: Upgrade, Connection
    #   - Without these headers, WebSocket upgrade fails → falls back to polling (slower)
    #   - This block ensures WebSocket connections are properly proxied
    #
    # TEACHING EXAMPLE: Student joins collaborative coding session
    #   - Initial HTTP request to /socket.io/?transport=websocket
    #   - Nginx proxies with Upgrade headers → Flask Socket.IO server
    #   - Connection upgraded to WebSocket
    #   - Now students see each other's code changes in real-time!
    # ==============================================================================
    location /socket.io/ {
        # Forward Socket.IO traffic to Socket.IO server on port 8500
        proxy_pass http://localhost:8500;
        
        # Use HTTP/1.1 (required for WebSocket support)
        proxy_http_version 1.1;
        
        # CRITICAL: Pass upgrade headers from client to Flask
        # $http_upgrade = client's Upgrade header value (e.g., "websocket")
        proxy_set_header Upgrade $http_upgrade;
        
        # CRITICAL: Tell Flask to upgrade the connection
        # "upgrade" value signals connection should be upgraded
        proxy_set_header Connection "upgrade";
        
        # Preserve original domain for Flask
        proxy_set_header Host $host;
        
        # Preserve student's real IP address
        proxy_set_header X-Real-IP $remote_addr;
    }

    # ==============================================================================
    # PROXY CONFIGURATION: Forwarding to Backend Application
    # ==============================================================================
    # location / means "match ALL paths" (/, /api/users, /api/posts, etc.)
    # Everything (except /socket.io/) goes to the Flask application on port 8587
    # ==============================================================================
    location / {
        # CRITICAL LINE: Forward all requests to Flask on localhost:8587
        # localhost = this same server (internal communication only)
        # 8587 = the port where Flask is listening (configured in app.py or main.py)
        proxy_pass http://localhost:8587;
        
        # Use HTTP/1.1 for better connection reuse and performance
        proxy_http_version 1.1;
        
        # Preserve original domain: flask.opencodingsociety.com
        proxy_set_header Host $host;

        # ==============================================================================
        # THE COMPLETE REQUEST/RESPONSE STORY
        # ==============================================================================
        # SCENARIO: Student at home visits pages.opencodingsociety.com
        #
        # FORWARD PATH (Request):
        #   1. Student's browser (IP: 24.18.xxx.xxx from home ISP)
        #      → Visits pages.opencodingsociety.com (GitHub Pages: 185.199.110.153)
        #      → Downloads HTML/JavaScript to browser
        #
        #   2. JavaScript in browser makes API call:
        #      GET https://flask.opencodingsociety.com/api/users
        #      → Student's home router → ISP network → Internet
        #      → DNS: flask.opencodingsociety.com → opencodingsociety.com → 3.233.212.71
        #      → Arrives at flask.opencodingsociety.com (3.233.212.71)
        #
        #   3. NGINX (3.233.212.71) receives request at port 443:
        #      Request headers from browser:
        #        Host: flask.opencodingsociety.com
        #        Origin: https://pages.opencodingsociety.com
        #        Client IP: 24.18.xxx.xxx
        #
        #   4. NGINX proxies to localhost:8587 (Flask)
        #      WITHOUT proxy_set_header, Flask would see:
        #        Host: localhost:8587              ← WRONG! Lost the domain
        #        IP: 127.0.0.1                     ← WRONG! Shows nginx, not student
        #
        #      WITH proxy_set_header, Flask correctly sees:
        #        Host: flask.opencodingsociety.com      ← Original domain preserved
        #
        # REVERSE PATH (Response):
        #   Flask → NGINX → Internet → ISP → Home Router → Student's Browser
        #   (Same path backwards)
        #
        # WHY THIS MATTERS:
        # - Flask can log the real student IP for security and analytics
        # - Flask knows the original domain for generating correct URLs
        # - Enables proper CORS validation against pages.opencodingsociety.com
        # ==============================================================================

        # ==============================================================================
        # CORS SECURITY: Origin Validation - BLOCKS UNAUTHORIZED REQUESTERS
        # ==============================================================================
        # This configuration implements a whitelist approach to CORS (Cross-Origin Resource Sharing).
        # In DEPLOYMENT, only requests from approved origins can access this API.
        # 
        # REAL EXAMPLE: pages.opencodingsociety.com (GitHub Pages) → flask.opencodingsociety.com (API)
        #   - Different subdomains = different origins = CORS required!
        #   - Without CORS headers, browser BLOCKS the request (security feature)
        #   - With proper CORS setup, browser allows pages to call flask API
        #
        # This prevents unauthorized websites from making requests to your API.
        # ==============================================================================
        
        set $cors_origin "";  # Start with empty string - deny all by default
        
        # Approve all requests from opencodingsociety.com subdomains
        # Examples: pages.opencodingsociety.com, flask.opencodingsociety.com, dev.opencodingsociety.com
        # Pattern breakdown:
        #   ^https://           - Must use HTTPS (for production security)
        #   (.*\.)?             - Optional subdomain (e.g., "pages.", "dev.", or none)
        #   opencodingsociety\.com$ - Must end with opencodingsociety.com
        if ($http_origin ~* "^https://(.*\.)?opencodingsociety\.com$") {
            set $cors_origin $http_origin;
        }
        
        # Approve GitHub Pages deployments from open-coding-society organization
        # Example: https://open-coding-society.github.io
        if ($http_origin = "https://open-coding-society.github.io") {
            set $cors_origin $http_origin;
        }

        # ==============================================================================
        # CORS HEADERS: Tell browser this origin is allowed
        # ==============================================================================
        # These headers are sent with EVERY response (not just OPTIONS)
        # 'always' ensures headers are added even on error responses (4xx, 5xx)
        # ==============================================================================
        
        # Tell browser: yes, this origin can access the response
        # $cors_origin is set above (only if origin was approved)
        add_header "Access-Control-Allow-Origin" "$cors_origin" always;
        
        # Tell browser: yes, include cookies/auth tokens in cross-origin requests
        # Required for maintaining user sessions across pages → flask
        add_header "Access-Control-Allow-Credentials" "true" always;

        # ==============================================================================
        # CROSS-ORIGIN REQUESTS: 2-PART PROCESS
        # ==============================================================================
        # PART 1: PREFLIGHT CHECK (handled here by nginx)
        #   - Browser sends OPTIONS request to check permissions
        #   - Nginx validates origin and responds with CORS headers
        #   - Never reaches Flask application - handled entirely by nginx
        #   - If origin not approved, browser blocks the entire sequence
        #
        # PART 2: ACTUAL REQUEST (handled by Flask application)
        #   - After preflight succeeds, browser sends the real request (GET, POST, etc.)
        #   - Nginx proxies this request to Flask on localhost:8587
        #   - Flask application processes the business logic and returns response
        #   - Flask may also add CORS headers for non-preflight responses
        #
        # WHY PREFLIGHT? Browser sends OPTIONS when request has:
        #   - Custom headers (like Authorization)
        #   - Methods other than GET/POST
        #   - Content-Type other than simple types
        #
        # This separation improves security (nginx blocks bad origins before they reach app)
        # and performance (nginx handles lightweight preflight checks efficiently).
        # ==============================================================================
        
        if ($request_method = OPTIONS) {
            # Tell browser: these HTTP methods are permitted for cross-origin requests
            # GET/POST = read/create data, PUT = update, DELETE = remove, HEAD = metadata
            add_header "Access-Control-Allow-Methods" "GET, POST, PUT, DELETE, OPTIONS, HEAD" always;
            
            # Cache preflight response for 10 minutes (600 seconds)
            # Browser won't send OPTIONS again for same endpoint during this time
            # Reduces overhead - fewer preflight requests = better performance
            add_header "Access-Control-Allow-MaxAge" 600 always;
            
            # Tell browser: these request headers are allowed in actual request
            # Authorization = JWT tokens, API keys
            # Content-Type = JSON, form data
            # Accept = response format preferences
            add_header "Access-Control-Allow-Headers" "Authorization, Origin, X-Origin, X-Requested-With, Content-Type, Accept" always;
            
            # Return 204 No Content - preflight successful (if origin was approved)
            # Browser now knows it's safe to send the actual request
            return 204;
        }
    }
}