Beginner

// client_server_demo.go
// Self-contained simulation of client-server interaction using net/http
// No external dependencies — only standard library

package main

import (
    "encoding/json" // => JSON encoding/decoding from standard library
    "fmt"           // => Formatted I/O from standard library
    "io"            // => I/O utilities from standard library
    "net"           // => Network primitives for finding free ports
    "net/http"      // => Built-in HTTP server and client from Go standard library
)

// --- SERVER SIDE ---

func helloHandler(w http.ResponseWriter, r *http.Request) {
    // => Called automatically when a request arrives at this route
    // => r.URL.Path contains the URL path (e.g., "/api/hello")
    response := map[string]string{
        "message": "Hello from server",
        "path":    r.URL.Path,
    }
    // => response is map["message":"Hello from server" "path":"/api/hello"]

    w.Header().Set("Content-Type", "application/json")
    // => Tells client how to interpret the body bytes

    w.WriteHeader(http.StatusOK)
    // => Sends "HTTP/1.1 200 OK" status line to client

    json.NewEncoder(w).Encode(response)
    // => Serializes response map to JSON and writes to the response body
}

func main() {
    // --- SERVER SETUP ---
    mux := http.NewServeMux()
    // => Creates a new request multiplexer (router)

    mux.HandleFunc("/api/hello", helloHandler)
    // => Routes /api/hello to helloHandler function

    listener, _ := net.Listen("tcp", "localhost:0")
    // => Binds to a random available port on localhost
    port := listener.Addr().(*net.TCPAddr).Port
    // => port is the OS-assigned port number

    go http.Serve(listener, mux)
    // => Starts server in a goroutine (concurrent, non-blocking)
    // => Server is now listening on localhost:<port>

    // --- CLIENT SIDE ---
    url := fmt.Sprintf("http://localhost:%d/api/hello", port)
    // => url is "http://localhost:<port>/api/hello"

    resp, _ := http.Get(url)
    // => Opens HTTP connection, sends GET request, waits for response

    defer resp.Body.Close()
    // => Ensures response body is closed when function returns

    body, _ := io.ReadAll(resp.Body)
    // => Reads all bytes from response body

    var result map[string]string
    json.Unmarshal(body, &result)
    // => Parses JSON bytes into Go map
    // => result is map["message":"Hello from server" "path":"/api/hello"]

    fmt.Printf("Status: %d\n", resp.StatusCode) // => Output: Status: 200
    fmt.Printf("Body: %v\n", result)             // => Output: Body: map[message:Hello from server path:/api/hello]
}

# client_server_demo.py
# Self-contained simulation of client-server interaction using Python's http.server
# No external dependencies — only standard library

import http.server        # => Built-in HTTP server from Python standard library
import threading          # => Used to run server and client concurrently
import urllib.request     # => Built-in HTTP client from Python standard library
import json               # => JSON encoding/decoding from standard library

# --- SERVER SIDE ---

class SimpleHandler(http.server.BaseHTTPRequestHandler):
    # => Subclass BaseHTTPRequestHandler to define how requests are handled
    # => Each incoming connection creates a new instance of this class

    def do_GET(self):
        # => Called automatically when a GET request arrives
        # => self.path contains the URL path (e.g., "/api/hello")
        response = {"message": "Hello from server", "path": self.path}
        # => response is {"message": "Hello from server", "path": "/api/hello"}

        body = json.dumps(response).encode("utf-8")
        # => body is b'{"message": "Hello from server", "path": "/api/hello"}'
        # => .encode("utf-8") converts str to bytes — HTTP bodies are bytes

        self.send_response(200)
        # => Sends "HTTP/1.1 200 OK" status line to client

        self.send_header("Content-Type", "application/json")
        # => Tells client how to interpret the body bytes

        self.end_headers()
        # => Sends blank line separating headers from body (required by HTTP spec)

        self.wfile.write(body)
        # => Writes response body bytes to the network socket

    def log_message(self, format, *args):
        pass
        # => Suppress default request logging to keep demo output clean

# --- CLIENT SIDE ---

def run_server(port):
    server = http.server.HTTPServer(("localhost", port), SimpleHandler)
    # => Creates server bound to localhost:8080
    # => SimpleHandler will handle each incoming request

    server.handle_request()
    # => Handles exactly one request then returns
    # => In production, use serve_forever() instead

def run_client(port):
    url = f"http://localhost:{port}/api/hello"
    # => url is "http://localhost:8080/api/hello"

    with urllib.request.urlopen(url) as response:
        # => Opens HTTP connection, sends GET request, waits for response
        # => 'with' block ensures connection is closed when done

        status = response.status
        # => status is 200 (HTTP OK)

        body = json.loads(response.read().decode("utf-8"))
        # => response.read() returns raw bytes from server
        # => .decode("utf-8") converts bytes to str
        # => json.loads() parses JSON string into Python dict
        # => body is {"message": "Hello from server", "path": "/api/hello"}

    print(f"Status: {status}")       # => Output: Status: 200
    print(f"Body: {body}")           # => Output: Body: {'message': 'Hello from server', 'path': '/api/hello'}

PORT = 8080
server_thread = threading.Thread(target=run_server, args=(PORT,))
# => Creates thread to run server without blocking main thread

server_thread.start()
# => Server is now listening on localhost:8080

run_client(PORT)
# => Client sends request, server handles it, client prints response

server_thread.join()
# => Waits for server thread to finish before program exits

// http_semantics.go
// Demonstrates HTTP method semantics and status code meanings
// Uses only Go standard library

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "strings"
    "sync"
)

// In-memory "database" — a simple map simulating a resource store
var (
    users = map[string]map[string]string{
        "1": {"id": "1", "name": "Alice", "email": "alice@example.com"},
    }
    // => users is map["1":map["id":"1" "name":"Alice" "email":"alice@example.com"]]
    mu sync.Mutex
    // => Mutex protects concurrent map access
)

func parseID(path string) string {
    // => Extracts resource ID from URL path like "/users/1"
    parts := strings.Split(strings.Trim(path, "/"), "/")
    // => parts is ["users", "1"] for path "/users/1"
    if len(parts) >= 2 {
        return parts[1]
    }
    return ""
    // => Returns "1", or "" if no ID in path
}

func sendJSON(w http.ResponseWriter, status int, data interface{}) {
    body, _ := json.Marshal(data)
    // => Serializes data to JSON bytes
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status) // => Sends HTTP status line
    w.Write(body)
}

func usersHandler(w http.ResponseWriter, r *http.Request) {
    mu.Lock()
    defer mu.Unlock()

    switch r.Method {
    case http.MethodGet:
        // => GET: retrieve a resource — safe (no side effects) and idempotent
        userID := parseID(r.URL.Path) // => userID is "1"
        if user, ok := users[userID]; ok {
            sendJSON(w, http.StatusOK, user)
            // => 200 OK: resource found and returned
        } else {
            sendJSON(w, http.StatusNotFound, map[string]string{"error": "Not Found"})
            // => 404 Not Found: valid request but resource doesn't exist
        }

    case http.MethodPost:
        // => POST: create a new resource — NOT idempotent (each call creates another)
        body, _ := io.ReadAll(r.Body)
        var data map[string]string
        json.Unmarshal(body, &data)
        // => data is map["name":"Bob" "email":"bob@example.com"]

        newID := fmt.Sprintf("%d", len(users)+1)
        // => newID is "2" (simple auto-increment)
        data["id"] = newID
        users[newID] = data
        // => users["2"] = map["name":"Bob" "email":"bob@example.com" "id":"2"]

        sendJSON(w, http.StatusCreated, users[newID])
        // => 201 Created: new resource created; body contains the created resource

    case http.MethodPut:
        // => PUT: replace a resource entirely — idempotent (same result every time)
        userID := parseID(r.URL.Path)
        if _, ok := users[userID]; !ok {
            sendJSON(w, http.StatusNotFound, map[string]string{"error": "Not Found"})
            return
        }
        body, _ := io.ReadAll(r.Body)
        var data map[string]string
        json.Unmarshal(body, &data)
        data["id"] = userID
        users[userID] = data
        // => Replaces ALL fields — fields not in body are lost
        sendJSON(w, http.StatusOK, users[userID])
        // => 200 OK: replacement successful

    case http.MethodDelete:
        // => DELETE: remove a resource — idempotent
        userID := parseID(r.URL.Path)
        if _, ok := users[userID]; ok {
            delete(users, userID) // => Removes user from map
            sendJSON(w, http.StatusNoContent, nil)
            // => 204 No Content: success but nothing to return
        } else {
            sendJSON(w, http.StatusNotFound, map[string]string{"error": "Not Found"})
        }
    }
}

func main() {
    // Key status code groups:
    // 2xx => Success (200 OK, 201 Created, 204 No Content)
    // 3xx => Redirection (301 Moved Permanently, 304 Not Modified)
    // 4xx => Client error (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict)
    // 5xx => Server error (500 Internal Server Error, 503 Service Unavailable)

    fmt.Println("HTTP Methods: GET (safe, idempotent), POST (not idempotent),")
    fmt.Println("PUT (idempotent), DELETE (idempotent)")
}

# http_semantics.py
# Demonstrates HTTP method semantics and status code meanings
# Uses only Python standard library

from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import urllib.parse

# In-memory "database" — a simple dict simulating a resource store
USERS = {
    "1": {"id": "1", "name": "Alice", "email": "alice@example.com"}
}
# => USERS is {"1": {"id": "1", "name": "Alice", "email": "alice@example.com"}}

class ResourceHandler(BaseHTTPRequestHandler):

    def _parse_id(self):
        # => Extracts resource ID from URL path like "/users/1"
        parts = self.path.strip("/").split("/")
        # => parts is ["users", "1"] for path "/users/1"
        return parts[1] if len(parts) >= 2 else None
        # => Returns "1", or None if no ID in path

    def _send_json(self, status, data):
        body = json.dumps(data).encode("utf-8")
        # => Serializes data dict to JSON bytes
        self.send_response(status)    # => Sends HTTP status line
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self):
        # => GET: retrieve a resource — safe (no side effects) and idempotent
        user_id = self._parse_id()   # => user_id is "1"
        if user_id in USERS:
            self._send_json(200, USERS[user_id])
            # => 200 OK: resource found and returned
        else:
            self._send_json(404, {"error": "Not Found"})
            # => 404 Not Found: valid request but resource doesn't exist

    def do_POST(self):
        # => POST: create a new resource — NOT idempotent (each call creates another)
        length = int(self.headers.get("Content-Length", 0))
        body = json.loads(self.rfile.read(length))
        # => Reads exactly Content-Length bytes from request body
        # => body is {"name": "Bob", "email": "bob@example.com"}

        new_id = str(len(USERS) + 1)
        # => new_id is "2" (simple auto-increment)
        USERS[new_id] = {**body, "id": new_id}
        # => USERS["2"] = {"name": "Bob", "email": "bob@example.com", "id": "2"}

        self._send_json(201, USERS[new_id])
        # => 201 Created: new resource created; body contains the created resource

    def do_PUT(self):
        # => PUT: replace a resource entirely — idempotent (same result every time)
        user_id = self._parse_id()
        length = int(self.headers.get("Content-Length", 0))
        body = json.loads(self.rfile.read(length))

        if user_id not in USERS:
            self._send_json(404, {"error": "Not Found"})
            return

        USERS[user_id] = {**body, "id": user_id}
        # => Replaces ALL fields — fields not in body are lost
        self._send_json(200, USERS[user_id])
        # => 200 OK: replacement successful

    def do_DELETE(self):
        # => DELETE: remove a resource — idempotent
        user_id = self._parse_id()
        if user_id in USERS:
            del USERS[user_id]           # => Removes user from dict
            self._send_json(204, {})
            # => 204 No Content: success but nothing to return
        else:
            self._send_json(404, {"error": "Not Found"})

    def log_message(self, format, *args):
        pass

# Key status code groups:
# 2xx => Success (200 OK, 201 Created, 204 No Content)
# 3xx => Redirection (301 Moved Permanently, 304 Not Modified)
# 4xx => Client error (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict)
# 5xx => Server error (500 Internal Server Error, 503 Service Unavailable)

// rest_api_design.go
// Demonstrates REST API URL design principles
// No external dependencies

package main

import "fmt"

// REST URL design principles encoded as a routing table
// Each entry shows: method, url_pattern, operation, notes

type RouteExample struct {
    Method    string
    Pattern   string
    Operation string
    Notes     string
}

func main() {
    restDesignExamples := []RouteExample{
        // --- RESOURCE COLLECTIONS ---
        {"GET", "/users", "List all users", "Returns array of user objects"},
        {"POST", "/users", "Create new user", "Body contains new user data"},

        // --- INDIVIDUAL RESOURCES ---
        {"GET", "/users/{id}", "Get specific user", "Returns single user object"},
        {"PUT", "/users/{id}", "Replace user", "Body contains full replacement"},
        {"PATCH", "/users/{id}", "Partial update", "Body contains only changed fields"},
        {"DELETE", "/users/{id}", "Delete user", "Returns 204 No Content"},

        // --- NESTED RESOURCES (relationships) ---
        {"GET", "/users/{id}/orders", "List user's orders", "Scoped to specific user"},
        {"POST", "/users/{id}/orders", "Create order for user", "Order belongs to user"},
        {"GET", "/users/{id}/orders/{oid}", "Specific order", "Fully qualified resource"},
    }

    // PASS: GOOD URL patterns
    goodPatterns := map[string]string{
        "/users":           "Plural noun — represents the collection",
        "/users/42":        "ID identifies specific resource in collection",
        "/users/42/orders": "Nested resource shows relationship",
        "/search?q=alice":  "Query parameters for filtering/searching",
    }
    // => Each URL is a noun; HTTP method provides the verb

    // FAIL: BAD URL patterns (common anti-patterns)
    badPatterns := map[string]string{
        "/getUser":         "Verb in URL — method is already GET",
        "/deleteUser/42":   "Verb in URL — method is already DELETE",
        "/user":            "Singular noun for collection is confusing",
        "/users/getOrders": "Mixed resource + action — use /users/{id}/orders",
        "/createNewOrder":  "Action in URL — use POST /orders instead",
    }
    // => URLs should identify resources, not actions

    fmt.Println("=== REST URL Design ===")
    for _, r := range restDesignExamples {
        fmt.Printf("%-6s %-30s | %s\n", r.Method, r.Pattern, r.Operation)
        // => Prints e.g.: "GET    /users                         | List all users"
    }

    fmt.Println("\n=== PASS: Good Patterns ===")
    for url, reason := range goodPatterns {
        fmt.Printf("  %-30s => %s\n", url, reason)
    }

    fmt.Println("\n=== FAIL: Anti-Patterns ===")
    for url, reason := range badPatterns {
        fmt.Printf("  %-30s => %s\n", url, reason)
    }
}

# rest_api_design.py
# Demonstrates REST API URL design principles
# No external dependencies

# REST URL design principles encoded as a routing table
# Each entry shows: (method, url_pattern, operation, notes)

REST_DESIGN_EXAMPLES = [
    # --- RESOURCE COLLECTIONS ---
    ("GET",    "/users",          "List all users",          "Returns array of user objects"),
    ("POST",   "/users",          "Create new user",         "Body contains new user data"),

    # --- INDIVIDUAL RESOURCES ---
    ("GET",    "/users/{id}",     "Get specific user",       "Returns single user object"),
    ("PUT",    "/users/{id}",     "Replace user",            "Body contains full replacement"),
    ("PATCH",  "/users/{id}",     "Partial update",          "Body contains only changed fields"),
    ("DELETE", "/users/{id}",     "Delete user",             "Returns 204 No Content"),

    # --- NESTED RESOURCES (relationships) ---
    ("GET",    "/users/{id}/orders",     "List user's orders",    "Scoped to specific user"),
    ("POST",   "/users/{id}/orders",     "Create order for user", "Order belongs to user"),
    ("GET",    "/users/{id}/orders/{oid}", "Specific order",      "Fully qualified resource"),
]

# PASS: GOOD URL patterns
GOOD_PATTERNS = {
    "/users":           "Plural noun — represents the collection",
    "/users/42":        "ID identifies specific resource in collection",
    "/users/42/orders": "Nested resource shows relationship",
    "/search?q=alice":  "Query parameters for filtering/searching",
}
# => Each URL is a noun; HTTP method provides the verb

# FAIL: BAD URL patterns (common anti-patterns)
BAD_PATTERNS = {
    "/getUser":          "Verb in URL — method is already GET",
    "/deleteUser/42":    "Verb in URL — method is already DELETE",
    "/user":             "Singular noun for collection is confusing",
    "/users/getOrders":  "Mixed resource + action — use /users/{id}/orders",
    "/createNewOrder":   "Action in URL — use POST /orders instead",
}
# => URLs should identify resources, not actions

def demonstrate_rest_convention():
    print("=== REST URL Design ===")
    for method, pattern, operation, notes in REST_DESIGN_EXAMPLES:
        print(f"{method:6} {pattern:30} | {operation}")
        # => Prints e.g.: "GET    /users                         | List all users"

    print("\n=== PASS: Good Patterns ===")
    for url, reason in GOOD_PATTERNS.items():
        print(f"  {url:30} => {reason}")

    print("\n=== FAIL: Anti-Patterns ===")
    for url, reason in BAD_PATTERNS.items():
        print(f"  {url:30} => {reason}")

demonstrate_rest_convention()
# => Output: REST URL Design table followed by good/bad pattern examples

// dns_simulation.go
// Simulates the DNS resolution chain with caching
// No external dependencies

package main

import (
    "fmt"
    "strings"
    "time"
)

// Simulated DNS hierarchy
var dnsRoot = map[string]string{
    "com": "tld-ns-com.example",
    "org": "tld-ns-org.example",
}

// => ROOT knows which server handles each top-level domain (TLD)

var dnsTLDCom = map[string]string{
    "example.com": "ns1.example.com",
    "stripe.com":  "ns1.stripe.com",
}

// => TLD server knows which authoritative nameserver handles each domain

var dnsAuthoritative = map[string]string{
    "api.example.com":  "203.0.113.42",
    "www.example.com":  "203.0.113.43",
    "mail.example.com": "203.0.113.44",
}

// => Authoritative server stores the actual A records (name -> IP)

type cacheEntry struct {
    ip      string
    expires time.Time
}

type DNSCache struct {
    cache map[string]cacheEntry
    // => cache is empty map
}

func newDNSCache() *DNSCache {
    return &DNSCache{cache: make(map[string]cacheEntry)}
}

func (c *DNSCache) get(name string) (string, bool) {
    entry, ok := c.cache[name]
    // => Returns zero value if not cached
    if ok && entry.expires.After(time.Now()) {
        return entry.ip, true
        // => Cache hit: return IP if TTL not expired
    }
    return "", false
    // => Cache miss
}

func (c *DNSCache) set(name, ip string, ttl time.Duration) {
    c.cache[name] = cacheEntry{
        ip:      ip,
        expires: time.Now().Add(ttl),
    }
    // => Stores IP with expiry timestamp
    // => After ttl, the entry is considered stale
}

type RecursiveResolver struct {
    cache   *DNSCache
    queries int
    // => Track how many upstream queries we make
}

func newResolver() *RecursiveResolver {
    return &RecursiveResolver{cache: newDNSCache()}
}

func (r *RecursiveResolver) resolve(hostname string) string {
    // => Main resolution method: check cache first, then query hierarchy
    if ip, ok := r.cache.get(hostname); ok {
        fmt.Printf("  Cache hit: %s => %s\n", hostname, ip)
        return ip
        // => Avoids all upstream queries when cached
    }

    fmt.Printf("  Cache miss: %s — querying DNS hierarchy\n", hostname)

    // Step 1: Ask root for TLD nameserver
    parts := strings.Split(hostname, ".")
    tld := parts[len(parts)-1]
    // => tld is "com" for "api.example.com"
    _ = dnsRoot[tld]
    // => tldNS is "tld-ns-com.example"
    r.queries++

    // Step 2: Ask TLD for authoritative nameserver
    domain := strings.Join(parts[len(parts)-2:], ".")
    // => domain is "example.com" for "api.example.com"
    _ = dnsTLDCom[domain]
    // => authNS is "ns1.example.com"
    r.queries++

    // Step 3: Ask authoritative server for actual IP
    ip := dnsAuthoritative[hostname]
    // => ip is "203.0.113.42"
    r.queries++

    if ip != "" {
        r.cache.set(hostname, ip, 300*time.Second)
        // => Cache for 300 seconds (5 minutes) — TTL from DNS record
        fmt.Printf("  Resolved and cached: %s => %s\n", hostname, ip)
    }
    return ip
}

func main() {
    resolver := newResolver()

    // First resolution — cold cache, requires full hierarchy traversal
    ip1 := resolver.resolve("api.example.com")
    // => Cache miss: queries root, TLD, authoritative (3 upstream queries)
    fmt.Printf("Result: %s, Queries made: %d\n", ip1, resolver.queries)
    // => Output: Result: 203.0.113.42, Queries made: 3

    // Second resolution — warm cache, zero upstream queries
    ip2 := resolver.resolve("api.example.com")
    // => Output: Cache hit: api.example.com => 203.0.113.42
    fmt.Printf("Result: %s, Queries made: %d\n", ip2, resolver.queries)
    // => Output: Result: 203.0.113.42, Queries made: 3 (unchanged — served from cache)
}

# dns_simulation.py
# Simulates the DNS resolution chain with caching
# No external dependencies

import time

# Simulated DNS hierarchy
DNS_ROOT = {
    "com": "tld-ns-com.example",
    "org": "tld-ns-org.example",
}
# => ROOT knows which server handles each top-level domain (TLD)

DNS_TLD_COM = {
    "example.com": "ns1.example.com",
    "stripe.com":  "ns1.stripe.com",
}
# => TLD server knows which authoritative nameserver handles each domain

DNS_AUTHORITATIVE = {
    "api.example.com":  "203.0.113.42",
    "www.example.com":  "203.0.113.43",
    "mail.example.com": "203.0.113.44",
}
# => Authoritative server stores the actual A records (name -> IP)

class DNSCache:
    def __init__(self):
        self._cache = {}
        # => cache is empty dict: {}

    def get(self, name):
        entry = self._cache.get(name)
        # => Returns None if not cached
        if entry and entry["expires"] > time.time():
            return entry["ip"]
            # => Cache hit: return IP if TTL not expired
        return None
        # => Cache miss: None

    def set(self, name, ip, ttl_seconds=300):
        self._cache[name] = {
            "ip": ip,
            "expires": time.time() + ttl_seconds,
        }
        # => Stores IP with expiry timestamp
        # => After ttl_seconds, the entry is considered stale

class RecursiveResolver:
    def __init__(self):
        self.cache = DNSCache()
        # => Each resolver maintains its own cache
        self.queries = 0
        # => Track how many upstream queries we make

    def resolve(self, hostname):
        # => Main resolution method: check cache first, then query hierarchy
        cached = self.cache.get(hostname)
        if cached:
            print(f"  Cache hit: {hostname} => {cached}")
            return cached
            # => Avoids all upstream queries when cached

        print(f"  Cache miss: {hostname} — querying DNS hierarchy")

        # Step 1: Ask root for TLD nameserver
        tld = hostname.split(".")[-1]
        # => tld is "com" for "api.example.com"
        tld_ns = DNS_ROOT.get(tld)
        # => tld_ns is "tld-ns-com.example"
        self.queries += 1

        # Step 2: Ask TLD for authoritative nameserver
        domain = ".".join(hostname.split(".")[-2:])
        # => domain is "example.com" for "api.example.com"
        auth_ns = DNS_TLD_COM.get(domain)
        # => auth_ns is "ns1.example.com"
        self.queries += 1

        # Step 3: Ask authoritative server for actual IP
        ip = DNS_AUTHORITATIVE.get(hostname)
        # => ip is "203.0.113.42"
        self.queries += 1

        if ip:
            self.cache.set(hostname, ip, ttl_seconds=300)
            # => Cache for 300 seconds (5 minutes) — TTL from DNS record
            print(f"  Resolved and cached: {hostname} => {ip}")
        return ip

resolver = RecursiveResolver()

# First resolution — cold cache, requires full hierarchy traversal
ip1 = resolver.resolve("api.example.com")
# => Cache miss: queries root, TLD, authoritative (3 upstream queries)
# => Output: Cache miss: api.example.com — querying DNS hierarchy
# => Output: Resolved and cached: api.example.com => 203.0.113.42
print(f"Result: {ip1}, Queries made: {resolver.queries}")
# => Output: Result: 203.0.113.42, Queries made: 3

# Second resolution — warm cache, zero upstream queries
ip2 = resolver.resolve("api.example.com")
# => Output: Cache hit: api.example.com => 203.0.113.42
print(f"Result: {ip2}, Queries made: {resolver.queries}")
# => Output: Result: 203.0.113.42, Queries made: 3 (unchanged — served from cache)

// round_robin_lb.go
// Simulates a round-robin load balancer
// No external dependencies

package main

import "fmt"

type RoundRobinLoadBalancer struct {
    servers       []string
    index         int
    requestCounts map[string]int
}

func newRoundRobinLB(servers []string) *RoundRobinLoadBalancer {
    counts := make(map[string]int)
    for _, s := range servers {
        counts[s] = 0
    }
    return &RoundRobinLoadBalancer{
        servers:       servers,
        index:         0,
        requestCounts: counts,
    }
    // => servers is ["server-1:8080", "server-2:8080", "server-3:8080"]
    // => requestCounts is map["server-1:8080":0 "server-2:8080":0 "server-3:8080":0]
}

func (lb *RoundRobinLoadBalancer) nextServer() string {
    server := lb.servers[lb.index%len(lb.servers)]
    // => Returns next server in rotation
    // => After server-3, wraps back to server-1
    lb.index++
    lb.requestCounts[server]++
    // => Tracks how many requests each server received
    return server
}

func (lb *RoundRobinLoadBalancer) distributionReport() {
    total := 0
    for _, count := range lb.requestCounts {
        total += count
    }
    // => total is total number of requests dispatched
    fmt.Printf("\nLoad distribution (%d requests):\n", total)
    for _, s := range lb.servers {
        count := lb.requestCounts[s]
        pct := float64(count) / float64(total) * 100
        fmt.Printf("  %s: %d requests (%.1f%%)\n", s, count, pct)
        // => Each server should receive ~33.3% of traffic
    }
}

func main() {
    // Initialize balancer with three backend servers
    lb := newRoundRobinLB([]string{
        "server-1:8080",
        "server-2:8080",
        "server-3:8080",
    })

    // Simulate 9 incoming requests
    for i := 0; i < 9; i++ {
        server := lb.nextServer()
        fmt.Printf("Request %d => %s\n", i+1, server)
        // => Request 1 => server-1:8080
        // => Request 2 => server-2:8080
        // => Request 3 => server-3:8080
        // => Request 4 => server-1:8080  (wraps around)
        // => Request 5 => server-2:8080
        // => Request 6 => server-3:8080
        // => Request 7 => server-1:8080
        // => Request 8 => server-2:8080
        // => Request 9 => server-3:8080
    }

    lb.distributionReport()
    // => Load distribution (9 requests):
    // =>   server-1:8080: 3 requests (33.3%)
    // =>   server-2:8080: 3 requests (33.3%)
    // =>   server-3:8080: 3 requests (33.3%)
    // => Perfect even distribution for uniform workloads
}

# round_robin_lb.py
# Simulates a round-robin load balancer
# No external dependencies

import itertools

class RoundRobinLoadBalancer:
    def __init__(self, servers):
        self.servers = servers
        # => servers is ["server-1:8080", "server-2:8080", "server-3:8080"]

        self._cycle = itertools.cycle(servers)
        # => Creates an infinite iterator: 1, 2, 3, 1, 2, 3, 1, ...
        # => itertools.cycle wraps around automatically

        self.request_counts = {s: 0 for s in servers}
        # => request_counts is {"server-1:8080": 0, "server-2:8080": 0, "server-3:8080": 0}

    def next_server(self):
        server = next(self._cycle)
        # => Returns next server in rotation
        # => After server-3, wraps back to server-1

        self.request_counts[server] += 1
        # => Tracks how many requests each server received

        return server

    def distribution_report(self):
        total = sum(self.request_counts.values())
        # => total is total number of requests dispatched
        print(f"\nLoad distribution ({total} requests):")
        for server, count in self.request_counts.items():
            pct = (count / total * 100) if total > 0 else 0
            print(f"  {server}: {count} requests ({pct:.1f}%)")
            # => Each server should receive ~33.3% of traffic

# Initialize balancer with three backend servers
lb = RoundRobinLoadBalancer([
    "server-1:8080",
    "server-2:8080",
    "server-3:8080",
])

# Simulate 9 incoming requests
for i in range(9):
    server = lb.next_server()
    print(f"Request {i+1} => {server}")
    # => Request 1 => server-1:8080
    # => Request 2 => server-2:8080
    # => Request 3 => server-3:8080
    # => Request 4 => server-1:8080  (wraps around)
    # => Request 5 => server-2:8080
    # => Request 6 => server-3:8080
    # => Request 7 => server-1:8080
    # => Request 8 => server-2:8080
    # => Request 9 => server-3:8080

lb.distribution_report()
# => Load distribution (9 requests):
# =>   server-1:8080: 3 requests (33.3%)
# =>   server-2:8080: 3 requests (33.3%)
# =>   server-3:8080: 3 requests (33.3%)
# => Perfect even distribution for uniform workloads

// least_connections_lb.go
// Simulates least-connections load balancing
// No external dependencies

package main

import "fmt"

type Server struct {
    Name              string
    ActiveConnections int
    // => Tracks currently in-flight requests
    TotalHandled int
    // => Tracks total requests processed (for reporting)
}

type LeastConnectionsLB struct {
    Servers []*Server
    // => servers is slice of Server pointers
}

func (lb *LeastConnectionsLB) pickServer() *Server {
    // => Select server with fewest active connections
    chosen := lb.Servers[0]
    for _, s := range lb.Servers[1:] {
        if s.ActiveConnections < chosen.ActiveConnections {
            chosen = s
        }
    }
    // => chosen is Server with lowest ActiveConnections value
    // => If tie, picks first in slice (acceptable for this algorithm)

    chosen.ActiveConnections++
    // => Increment BEFORE dispatching — connection is "active" now
    chosen.TotalHandled++
    return chosen
}

func (lb *LeastConnectionsLB) completeRequest(server *Server) {
    server.ActiveConnections--
    // => Decrement AFTER response sent — connection is "released" now
    // => Must always be called to prevent connection count leak
}

func (lb *LeastConnectionsLB) status() {
    fmt.Println("Server status (active connections | total handled):")
    for _, s := range lb.Servers {
        fmt.Printf("  %s: %d active | %d total\n", s.Name, s.ActiveConnections, s.TotalHandled)
    }
}

func main() {
    lb := &LeastConnectionsLB{
        Servers: []*Server{
            {Name: "server-A"},
            {Name: "server-B"},
            {Name: "server-C"},
        },
    }

    // Simulate a slow request to server-A
    slowServer := lb.pickServer()
    fmt.Printf("Slow request => %s\n", slowServer.Name)
    // => Slow request => server-A  (first request, all at 0, picks server-A)
    // => server-A now has 1 active connection; B and C have 0

    // Next two requests should go to B and C (fewer connections than A)
    r2 := lb.pickServer()
    fmt.Printf("Request 2 => %s\n", r2.Name)
    // => Request 2 => server-B  (0 connections vs server-A's 1)

    r3 := lb.pickServer()
    fmt.Printf("Request 3 => %s\n", r3.Name)
    // => Request 3 => server-C  (0 connections vs A's 1 and B's 1)

    // Request 4: all at 1 (A=1, B=1, C=1) — picks first (A)
    r4 := lb.pickServer()
    fmt.Printf("Request 4 => %s\n", r4.Name)
    // => Request 4 => server-A  (tie broken by slice order)

    // Now complete the slow request on server-A
    lb.completeRequest(slowServer)
    // => server-A.ActiveConnections decremented: 2 -> 1

    lb.status()
    // => Server status:
    // =>   server-A: 1 active | 2 total
    // =>   server-B: 1 active | 1 total
    // =>   server-C: 1 active | 1 total

    _, _, _ = r2, r3, r4
}

# least_connections_lb.py
# Simulates least-connections load balancing
# No external dependencies

import random
import time
from dataclasses import dataclass, field

@dataclass
class Server:
    name: str
    active_connections: int = 0
    # => Tracks currently in-flight requests
    total_handled: int = 0
    # => Tracks total requests processed (for reporting)

class LeastConnectionsLB:
    def __init__(self, servers):
        self.servers = servers
        # => servers is list of Server objects

    def pick_server(self):
        # => Select server with fewest active connections
        chosen = min(self.servers, key=lambda s: s.active_connections)
        # => min() returns Server with lowest active_connections value
        # => If tie, min() picks first in list (acceptable for this algorithm)

        chosen.active_connections += 1
        # => Increment BEFORE dispatching — connection is "active" now
        chosen.total_handled += 1
        return chosen

    def complete_request(self, server):
        server.active_connections -= 1
        # => Decrement AFTER response sent — connection is "released" now
        # => Must always be called to prevent connection count leak

    def status(self):
        print("Server status (active connections | total handled):")
        for s in self.servers:
            print(f"  {s.name}: {s.active_connections} active | {s.total_handled} total")

lb = LeastConnectionsLB([
    Server("server-A"),
    Server("server-B"),
    Server("server-C"),
])

# Simulate a slow request to server-A
slow_server = lb.pick_server()
print(f"Slow request => {slow_server.name}")
# => Slow request => server-A  (first request, all at 0, picks server-A)
# => server-A now has 1 active connection; B and C have 0

# Next two requests should go to B and C (fewer connections than A)
r2 = lb.pick_server()
print(f"Request 2 => {r2.name}")
# => Request 2 => server-B  (0 connections vs server-A's 1)

r3 = lb.pick_server()
print(f"Request 3 => {r3.name}")
# => Request 3 => server-C  (0 connections vs A's 1 and B's 1)

# Request 4: all at 1 (A=1, B=1, C=1) — picks first (A)
r4 = lb.pick_server()
print(f"Request 4 => {r4.name}")
# => Request 4 => server-A  (tie broken by list order)

# Now complete the slow request on server-A
lb.complete_request(slow_server)
# => server-A.active_connections decremented: 2 -> 1

lb.status()
# => Server status:
# =>   server-A: 1 active | 2 total
# =>   server-B: 1 active | 1 total
# =>   server-C: 1 active | 1 total

// in_memory_cache.go
// Implements a simple TTL-based in-memory cache
// No external dependencies

package main

import (
    "fmt"
    "time"
)

type cacheEntry struct {
    value   interface{}
    expires time.Time
}

type TTLCache struct {
    store      map[string]cacheEntry
    defaultTTL time.Duration
    // => defaultTTL is 300 seconds (5 minutes)
    hits   int
    misses int
    // => Track hit/miss ratio for monitoring
}

func newTTLCache(defaultTTL time.Duration) *TTLCache {
    return &TTLCache{
        store:      make(map[string]cacheEntry),
        defaultTTL: defaultTTL,
    }
    // => store is empty map; will hold key -> {value, expires}
}

func (c *TTLCache) get(key string) (interface{}, bool) {
    entry, ok := c.store[key]
    // => Returns zero value if key never set

    if !ok {
        c.misses++
        return nil, false
        // => Cache miss: key not present
    }

    if time.Now().After(entry.expires) {
        delete(c.store, key)
        // => Evict expired entry (lazy eviction on access)
        c.misses++
        return nil, false
        // => Cache miss: key existed but TTL expired
    }

    c.hits++
    return entry.value, true
    // => Cache hit: return stored value
}

func (c *TTLCache) set(key string, value interface{}, ttl ...time.Duration) {
    t := c.defaultTTL
    if len(ttl) > 0 {
        t = ttl[0]
    }
    // => Use provided TTL or fall back to default
    c.store[key] = cacheEntry{
        value:   value,
        expires: time.Now().Add(t),
    }
    // => Stores value with absolute expiry timestamp
}

func (c *TTLCache) del(key string) {
    delete(c.store, key)
    // => Remove key if exists; no-op if not
}

func (c *TTLCache) hitRate() float64 {
    total := c.hits + c.misses
    if total == 0 {
        return 0.0
    }
    return float64(c.hits) / float64(total) * 100
    // => Returns percentage of requests served from cache
}

// Simulate expensive database query
func fetchUserFromDB(userID int) map[string]interface{} {
    time.Sleep(10 * time.Millisecond)
    // => Simulate 10ms DB query latency
    return map[string]interface{}{
        "id":   userID,
        "name": fmt.Sprintf("User%d", userID),
        "role": "member",
    }
    // => Returns map["id":1 "name":"User1" "role":"member"]
}

func main() {
    cache := newTTLCache(5 * time.Second)
    // => Cache with 5-second TTL for this demo (use 300+ in production)

    // First call — cold cache, must hit database
    key := "user:1"
    user, ok := cache.get(key)
    // => user is nil, ok is false (cache miss)
    if !ok {
        user = fetchUserFromDB(1)
        // => user is map["id":1 "name":"User1" "role":"member"]
        cache.set(key, user)
        // => Stored in cache; expires in 5 seconds
    }
    fmt.Printf("First call: %v\n", user) // => Output: First call: map[id:1 name:User1 role:member]

    // Second call — warm cache, instant response from memory
    user, _ = cache.get(key)
    // => user is map["id":1 "name":"User1" "role":"member"] (cache hit)
    fmt.Printf("Second call: %v\n", user) // => Output: Second call: map[id:1 name:User1 role:member]

    fmt.Printf("Cache hit rate: %.1f%%\n", cache.hitRate())
    // => Output: Cache hit rate: 50.0% (1 hit / 2 total)

    // Simulate TTL expiry
    time.Sleep(6 * time.Second)
    // => 6 seconds pass; TTL was 5 seconds so entry is now expired

    user, ok = cache.get(key)
    // => user is nil, ok is false (cache miss: TTL expired, entry evicted)
    fmt.Printf("After TTL: %v\n", user) // => Output: After TTL: <nil>
    fmt.Printf("Cache hit rate: %.1f%%\n", cache.hitRate())
    // => Output: Cache hit rate: 33.3% (1 hit / 3 total)
}