Go Dev — Building Real Applications

From HTTP servers to REST APIs, middleware, gRPC & production patterns — with real code from actual projects.

01 HTTP Client

Go's net/http package provides a production-grade HTTP client out of the box. Unlike most languages where you need a third-party library (axios, requests, etc.), Go's standard library is all you need. The http.Client struct gives you full control over timeouts, redirects, cookies, and transport-level settings.

The pattern is straightforward: create a client, make the request, check the error, and always close the response body with defer. Forgetting to close the body is a classic Go bug that causes resource leaks.

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    // Create an HTTP client (you can configure timeouts, redirects, etc.)
    client := &http.Client{}

    // Make a GET request to the Star Wars API
    resp, err := client.Get("https://swapi.dev/api/people/1")
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()  // ALWAYS close the body to prevent resource leaks

    // Read the entire response body into a byte slice
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Read error:", err)
        return
    }

    fmt.Println(string(body))  // Convert []byte to string and print
}

Custom Requests with Headers

For anything beyond simple GET requests, use http.NewRequest to build the request manually. This gives you control over the HTTP method, headers, and body.

// Build a custom request with headers
req, err := http.NewRequest("GET", "https://api.example.com/data", nil)
if err != nil {
    log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer my-token")
req.Header.Set("Content-Type", "application/json")

client := &http.Client{Timeout: 10 * time.Second}
resp, err := client.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

// Node.js — using built-in fetch (Node 18+)
const response = await fetch('https://swapi.dev/api/people/1');
const data = await response.json();  // auto-parses JSON
console.log(data);

// Node.js — using axios
const { data } = await axios.get('https://swapi.dev/api/people/1');
console.log(data);  // axios auto-parses JSON too

// Custom headers equivalent:
const resp = await fetch('https://api.example.com/data', {
  headers: {
    'Authorization': 'Bearer my-token',
    'Content-Type': 'application/json',
  },
  signal: AbortSignal.timeout(10000),  // 10s timeout (like Go's Timeout)
});

02 HTTP Server Basics

Go's standard library includes a full-featured HTTP server. No framework needed. This is one of Go's biggest strengths: you can build production-ready servers with zero external dependencies. The net/http package handles connection pooling, keep-alive, HTTP/1.1, and graceful shutdown out of the box.

The simplest server uses http.HandleFunc to register handler functions and http.ListenAndServe to start listening. Each incoming request runs in its own goroutine automatically, so your server is concurrent by default.

package main

import (
    "fmt"
    "log"
    "net/http"
)

func main() {
    // Register a handler function for the root path
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello Server!")  // Write response to client
    })

    fmt.Println("Server on :8080")
    // ListenAndServe blocks forever. log.Fatal logs the error if it returns.
    log.Fatal(http.ListenAndServe(":8080", nil))  // nil = use DefaultServeMux
}

Understanding Every Line — What Each Function Does

Before learning multiple server methods, let's break down every piece of the basic server so nothing feels like magic.

package main

import (
    "fmt"       // Formatted I/O — Fprintln writes to any io.Writer (like http.ResponseWriter)
    "log"       // Logging with timestamps — log.Fatal = log.Print + os.Exit(1)
    "net/http"  // Full HTTP client + server, production-quality, zero dependencies
)

func main() {
    // http.HandleFunc registers a function on the GLOBAL DefaultServeMux.
    // Pattern "/" matches ALL paths (it's a catch-all in Go's mux).
    // The function signature must be: func(http.ResponseWriter, *http.Request)
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // w (ResponseWriter) — write your response here. It implements io.Writer.
        // r (*Request) — contains everything about the incoming request:
        //   r.Method, r.URL, r.Header, r.Body, r.Context()
        fmt.Fprintln(w, "Hello Server!")
    })

    fmt.Println("Server on :8080")

    // log.Fatal does TWO things:
    //   1. Logs the error with a timestamp (like log.Println)
    //   2. Calls os.Exit(1) — terminates the program immediately
    //
    // http.ListenAndServe BLOCKS forever (it runs an infinite accept loop).
    // It only returns if something goes wrong (port already in use, permission denied).
    // So if it returns at all, it's an error — and log.Fatal prints it and exits.
    log.Fatal(http.ListenAndServe(":8080", nil))
}

All Server Creation Methods — Complete Reference

Go gives you 5 ways to start an HTTP server, from simplest to most control. Each TLS method is the secure equivalent of a plain HTTP method. Here's every one of them with when and why you'd pick it.

Method 1: http.ListenAndServe — Quick Start

A package-level convenience function. Creates an http.Server internally, binds to the address, and blocks forever. You get zero configuration — no timeouts, no TLS, no graceful shutdown.

// Signature: func ListenAndServe(addr string, handler http.Handler) error

http.HandleFunc("/", homeHandler)
log.Fatal(http.ListenAndServe(":8080", nil))
//                              │         │
//                              │         └─ nil = use DefaultServeMux
//                              └─ ":8080" = listen on all interfaces, port 8080
//                                 "localhost:8080" = only local connections
//                                 ":0" = OS picks a random free port

Method 2: http.ListenAndServeTLS — Quick Start with HTTPS

Same as above but wraps the connection in TLS. You pass cert and key file paths. Still no timeouts or shutdown control.

// Signature: func ListenAndServeTLS(addr, certFile, keyFile string, handler http.Handler) error

log.Fatal(http.ListenAndServeTLS(
    ":443",        // HTTPS standard port
    "cert.pem",    // Public certificate file — sent to clients
    "key.pem",     // Private key file — NEVER share this, chmod 0600
    nil,           // Handler (nil = DefaultServeMux)
))
// Internally: creates *http.Server, loads cert+key via tls.LoadX509KeyPair,
// wraps the TCP listener in a TLS listener, then calls server.Serve()

Method 3: server.ListenAndServe — Production HTTP

Create your own *http.Server struct with full control over timeouts, handler, header limits, and graceful shutdown.

mux := http.NewServeMux()  // Your own mux — isolated from global state
mux.HandleFunc("GET /", homeHandler)

server := &http.Server{
    Addr:              ":8080",             // Listen address
    Handler:           mux,                 // Your mux (NOT nil — avoid DefaultServeMux)
    ReadTimeout:       5 * time.Second,     // Max time to read full request
    ReadHeaderTimeout: 2 * time.Second,     // Max time to read just headers
    WriteTimeout:      10 * time.Second,    // Max time to write the response
    IdleTimeout:       120 * time.Second,   // How long keep-alive connections idle
    MaxHeaderBytes:    1 << 20,             // 1 MB max header size
}

// ListenAndServe on a *http.Server: creates a TCP listener on server.Addr,
// then calls server.Serve(listener). Blocks until error.
log.Fatal(server.ListenAndServe())

Method 4: server.ListenAndServeTLS — Production HTTPS

Same as above but with TLS. This is the most common production setup. HTTP/2 is automatically enabled over TLS connections.

server := &http.Server{
    Addr:         ":443",
    Handler:      mux,
    ReadTimeout:  5 * time.Second,
    WriteTimeout: 10 * time.Second,
    IdleTimeout:  120 * time.Second,
    TLSConfig:    &tls.Config{
        MinVersion: tls.VersionTLS12,  // Reject TLS 1.0 and 1.1 (insecure)
    },
}

// Loads cert+key, wraps listener in TLS, enables HTTP/2 via ALPN
log.Fatal(server.ListenAndServeTLS("cert.pem", "key.pem"))

// If certs are already in TLSConfig.Certificates, pass empty strings:
// log.Fatal(server.ListenAndServeTLS("", ""))

Method 5: server.Serve(listener) — Maximum Control (HTTP)

You create the TCP listener yourself and pass it in. Use this for Unix sockets, dynamic port assignment, or custom connection handling.

// Create a TCP listener manually
ln, err := net.Listen("tcp", ":0")  // :0 = OS picks a free port
if err != nil {
    log.Fatal(err)
}
log.Printf("Listening on %s", ln.Addr())  // Print the actual assigned port

server := &http.Server{Handler: mux}
log.Fatal(server.Serve(ln))  // Uses YOUR listener instead of creating one

// Unix socket example — no TCP, communicates via filesystem:
// ln, _ := net.Listen("unix", "/var/run/myapp.sock")
// server.Serve(ln)

Method 6: server.ServeTLS(listener, cert, key) — Maximum Control (HTTPS)

Same as Serve but wraps your listener in TLS. Used for custom TLS listeners, mTLS setups, or when you need to control the listener lifecycle.

ln, err := net.Listen("tcp", ":443")
if err != nil {
    log.Fatal(err)
}

server := &http.Server{
    Handler: mux,
    TLSConfig: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ClientAuth: tls.RequireAndVerifyClientCert,  // mTLS — require client cert
    },
}

// ServeTLS wraps ln in a TLS listener, then calls server.Serve(tlsListener)
log.Fatal(server.ServeTLS(ln, "cert.pem", "key.pem"))

http.ListenAndServe(addr, handler)
  └─ creates &http.Server{Addr: addr, Handler: handler}
     └─ server.ListenAndServe()
        └─ net.Listen("tcp", server.Addr)   ← creates TCP listener
           └─ server.Serve(listener)        ← accept loop (blocks forever)
              └─ for each connection: go conn.serve()  ← goroutine per request

http.ListenAndServeTLS(addr, cert, key, handler)
  └─ creates &http.Server{Addr: addr, Handler: handler}
     └─ server.ListenAndServeTLS(cert, key)
        └─ tls.LoadX509KeyPair(cert, key)   ← loads certificate + private key
           └─ net.Listen("tcp", server.Addr)
              └─ tls.NewListener(ln, config) ← wraps TCP in TLS
                 └─ server.Serve(tlsListener) ← same accept loop, encrypted

// ❌ WRONG — kills the entire server for one bad request
func handler(w http.ResponseWriter, r *http.Request) {
    data, err := db.Query("SELECT ...")
    if err != nil {
        log.Fatal(err)  // DON'T — this calls os.Exit(1)!
    }
}

// ✅ CORRECT — returns error to client, server keeps running
func handler(w http.ResponseWriter, r *http.Request) {
    data, err := db.Query("SELECT ...")
    if err != nil {
        log.Printf("DB error: %v", err)  // Log it (non-fatal)
        http.Error(w, "Internal Server Error", http.StatusInternalServerError)
        return
    }
}

Handler vs HandlerFunc

Go has two ways to define handlers. http.HandlerFunc is for quick inline functions. http.Handler is an interface that any struct can implement, giving you more structure for complex handlers.

// Method 1: HandlerFunc — quick and simple
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    fmt.Fprintln(w, `{"status": "ok"}`)
})

// Method 2: Handler interface — for structured handlers
type HomeHandler struct{}

func (h *HomeHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Welcome home")
}

// Register the struct handler
http.Handle("/home", &HomeHandler{})

Different Ways to Create an HTTP Server

Go gives you several ways to spin up an HTTP server, each adding more control. Understanding when to use which is critical for writing production code.

1. http.ListenAndServe — The Simplest Way

This is a convenience wrapper that creates a default http.Server internally. It's great for prototyping but never use it in production because you get no control over timeouts, TLS, or graceful shutdown.

package main

import (
    "fmt"
    "log"
    "net/http"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello!")
    })

    // nil handler = use http.DefaultServeMux (the global mux)
    // This is essentially:
    //   server := &http.Server{Addr: ":8080", Handler: nil}
    //   server.ListenAndServe()
    log.Fatal(http.ListenAndServe(":8080", nil))
}

2. Custom http.Server — The Production Way

Creating your own *http.Server gives you full control over timeouts, TLS configuration, error logging, connection limits, and graceful shutdown. This is what every production Go service should use.

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"
    "os/signal"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello from production server!")
    })

    server := &http.Server{
        Addr:              ":8080",            // Listen address
        Handler:           mux,                // Your own mux, NOT nil/DefaultServeMux
        ReadTimeout:       5 * time.Second,    // Max time to read entire request (headers + body)
        ReadHeaderTimeout: 2 * time.Second,    // Max time to read just the headers
        WriteTimeout:      10 * time.Second,   // Max time to write the response
        IdleTimeout:       120 * time.Second,  // Max time for keep-alive connections to idle
        MaxHeaderBytes:    1 << 20,            // 1 MB max header size
    }

    // Start server in a goroutine so we can handle shutdown
    go func() {
        log.Printf("Server starting on %s", server.Addr)
        if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatalf("Server failed: %v", err)
        }
    }()

    // Wait for interrupt signal (Ctrl+C)
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, os.Interrupt)
    <-quit
    log.Println("Shutting down server...")

    // Give in-flight requests 30 seconds to finish
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    // Shutdown stops accepting new connections, waits for existing ones to finish
    if err := server.Shutdown(ctx); err != nil {
        log.Fatalf("Forced shutdown: %v", err)
    }
    log.Println("Server stopped gracefully")
}

Client connects
  ├── ReadHeaderTimeout ──→ headers must arrive within this window
  ├── ReadTimeout ─────────→ entire request (headers + body) must arrive
  ├── Handler executes...
  ├── WriteTimeout ────────→ response must be fully written
  └── IdleTimeout ─────────→ if keep-alive, how long to wait for next request

3. DefaultServeMux vs Custom ServeMux

Understanding the difference between these two is important for both security and code organization.

// ❌ DefaultServeMux — global, shared, risky
// When you call http.HandleFunc() or http.Handle(), you're registering
// on the GLOBAL http.DefaultServeMux. Any imported package can also
// register on it. If you pass nil to ListenAndServe, it uses this.
http.HandleFunc("/secret", secretHandler)  // Goes to DefaultServeMux
http.ListenAndServe(":8080", nil)          // nil = DefaultServeMux

// Imagine an imported package does this in its init():
// func init() {
//     http.HandleFunc("/debug/pprof/", pprof.Index)  // Now exposed!
// }
// You just accidentally exposed profiling data to the internet.

// ✅ Custom ServeMux — isolated, explicit, safe
// You control exactly what's registered. Nothing else can touch it.
mux := http.NewServeMux()
mux.HandleFunc("GET /users", usersHandler)   // Only what YOU register
mux.HandleFunc("POST /users", createUser)    // Method-based routing (Go 1.22+)

server := &http.Server{
    Addr:    ":8080",
    Handler: mux,  // Explicit — no surprises
}
server.ListenAndServe()

4. Running Multiple Servers (Public + Admin)

A common pattern is running two servers in the same process: one public-facing and one for internal admin/metrics. Each gets its own mux and can run on different ports.

func main() {
    // Public API server
    publicMux := http.NewServeMux()
    publicMux.HandleFunc("GET /api/products", listProducts)
    publicMux.HandleFunc("GET /api/products/{id}", getProduct)

    publicServer := &http.Server{
        Addr:         ":8080",
        Handler:      publicMux,
        ReadTimeout:  5 * time.Second,
        WriteTimeout: 10 * time.Second,
    }

    // Internal admin/metrics server (not exposed to internet)
    adminMux := http.NewServeMux()
    adminMux.HandleFunc("GET /healthz", healthCheck)
    adminMux.HandleFunc("GET /metrics", metricsHandler)
    adminMux.HandleFunc("GET /debug/pprof/", pprofHandler)

    adminServer := &http.Server{
        Addr:    ":9090",           // Different port, firewalled from public
        Handler: adminMux,
    }

    // Run both servers concurrently
    go func() {
        log.Println("Public server on :8080")
        log.Fatal(publicServer.ListenAndServe())
    }()

    go func() {
        log.Println("Admin server on :9090")
        log.Fatal(adminServer.ListenAndServe())
    }()

    // Block forever (or use signal handling for graceful shutdown)
    select {}
}

5. Custom net.Listener — Maximum Control

For advanced use cases, you can create your own TCP listener and pass it to server.Serve(). This gives you control over the listener itself — useful for Unix sockets, custom connection limits, or dynamic port assignment.

import (
    "net"
    "net/http"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /", homeHandler)

    // Create a TCP listener manually
    ln, err := net.Listen("tcp", ":0")  // :0 = OS picks a free port
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Listening on %s", ln.Addr())  // Print the actual port

    server := &http.Server{Handler: mux}
    server.Serve(ln)  // Use Serve() instead of ListenAndServe()

    // Unix socket example:
    // ln, _ := net.Listen("unix", "/var/run/myapp.sock")
    // server.Serve(ln)
}

6. http.ListenAndServe vs http.Server Summary

// These two are EQUIVALENT:

// Version 1: The shortcut (what http.ListenAndServe does internally)
http.ListenAndServe(":8080", mux)

// Version 2: What it actually expands to
server := &http.Server{
    Addr:    ":8080",
    Handler: mux,
    // ReadTimeout:  0  ← DANGER: no timeouts!
    // WriteTimeout: 0  ← DANGER!
    // IdleTimeout:  0  ← DANGER!
}
server.ListenAndServe()

// The ONLY difference: with http.Server{} you can set
// timeouts, TLS config, error logger, max header bytes,
// base context, and call Shutdown() for graceful termination.
// http.ListenAndServe gives you NONE of that.

// --- BASIC SERVER (like Go's http.ListenAndServe) ---
const http = require('http');
const server = http.createServer((req, res) => {
  res.end('Hello Server!');
});
server.listen(8080, () => console.log('Server on :8080'));

// --- PRODUCTION SERVER (like Go's custom *http.Server) ---
const server = http.createServer(app);
server.timeout = 10000;         // Like Go's WriteTimeout (10s)
server.headersTimeout = 5000;  // Like Go's ReadHeaderTimeout (5s)
server.keepAliveTimeout = 120000; // Like Go's IdleTimeout (120s)
server.maxHeadersCount = 100;   // Limit header count
server.listen(8080);

// --- GRACEFUL SHUTDOWN (like Go's server.Shutdown(ctx)) ---
process.on('SIGINT', () => {
  console.log('Shutting down...');
  server.close(() => {  // Waits for in-flight requests
    console.log('Server stopped gracefully');
    process.exit(0);
  });
  // Force kill after 30s
  setTimeout(() => process.exit(1), 30000);
});

03 Modern Routing (Go 1.22+)

Before Go 1.22, the standard library router was limited: no method-based routing, no path parameters. You had to use third-party routers like gorilla/mux or chi. Go 1.22 changed everything by adding method-based routing, path parameters, and wildcards directly into the standard library.

This means for most applications, you no longer need an external router. The syntax is clean: prefix your pattern with the HTTP method, use {name} for parameters, and {name...} for catch-all wildcards.

package main

import (
    "fmt"
    "net/http"
)

func main() {
    mux := http.NewServeMux()

    // Method-based routing — only matches the specified HTTP method
    mux.HandleFunc("POST /items/create", createItem)
    mux.HandleFunc("DELETE /items/create", deleteItem)

    // Path parameters with {id} — extracted via r.PathValue()
    mux.HandleFunc("GET /teachers/{id}", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Teacher ID: %s", r.PathValue("id"))
    })

    // Wildcard catch-all with {path...} — matches any remaining path
    mux.HandleFunc("/files/{path...}", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Path: %s", r.PathValue("path"))
    })

    http.ListenAndServe(":8080", mux)
}

PathValue vs Query Parameters

Don't confuse path parameters with query parameters. Path values are part of the URL structure (/users/42), while query parameters come after ? (/users?id=42).

// Path parameter: /users/42
id := r.PathValue("id")  // "42"

// Query parameter: /users?page=2&limit=10
page := r.URL.Query().Get("page")    // "2"
limit := r.URL.Query().Get("limit")  // "10"

// Express.js — the same routing patterns
const express = require('express');
const app = express();

// Method-based routing (same as Go's "POST /items/create")
app.post('/items/create', createItem);
app.delete('/items/create', deleteItem);

// Path parameters (same as Go's /teachers/{id})
app.get('/teachers/:id', (req, res) => {
  res.send(`Teacher ID: ${req.params.id}`);
  //                      ^^^^^^^^^^^^^^
  // Express: req.params.id
  // Go:      r.PathValue("id")
});

// Wildcard catch-all (same as Go's /files/{path...})
app.get('/files/*', (req, res) => {
  res.send(`Path: ${req.params[0]}`);
  // Express uses * for catch-all; Go uses {name...}
});

// Query parameters — identical concept
app.get('/users', (req, res) => {
  const page = req.query.page;    // Express: req.query.page
  const limit = req.query.limit;  // Go: r.URL.Query().Get("limit")
});

04 Sub-Routing & Route Groups

As your application grows, you'll want to organize routes into logical groups. Go's http.ServeMux supports this through sub-routing using http.StripPrefix. This pattern lets you build modular routers and mount them under prefixes, similar to Express.js app.use("/api", router).

The key insight is that http.StripPrefix removes the prefix before passing the request to the inner handler, so your sub-router's patterns don't need to include the prefix.

func main() {
    // Create a sub-router with its own routes
    mux := http.NewServeMux()
    mux.HandleFunc("GET /users", usersHandler)
    mux.HandleFunc("GET /items", itemsHandler)

    // Mount under /app prefix
    app := http.NewServeMux()
    app.Handle("/app/", http.StripPrefix("/app", mux))

    // Now these routes work:
    // /app/users  -> usersHandler
    // /app/items  -> itemsHandler

    http.ListenAndServe(":8080", app)
}

Multiple API Versions

This pattern is especially useful for API versioning. You can maintain separate routers for /v1 and /v2, each with their own handlers.

// Version 1 routes
v1 := http.NewServeMux()
v1.HandleFunc("GET /users", getUsersV1)

// Version 2 routes (different implementation)
v2 := http.NewServeMux()
v2.HandleFunc("GET /users", getUsersV2)

// Mount both under /api
api := http.NewServeMux()
api.Handle("/api/v1/", http.StripPrefix("/api/v1", v1))
api.Handle("/api/v2/", http.StripPrefix("/api/v2", v2))

// Express.js — Sub-routing with express.Router()
const express = require('express');
const app = express();

// Create sub-routers (like Go's http.NewServeMux())
const usersRouter = express.Router();
usersRouter.get('/', getUsers);        // Handles /app/users
usersRouter.get('/:id', getUser);      // Handles /app/users/:id

const itemsRouter = express.Router();
itemsRouter.get('/', getItems);        // Handles /app/items

// Mount under /app prefix — Express strips the prefix automatically!
app.use('/app/users', usersRouter);
app.use('/app/items', itemsRouter);

// --- API Versioning ---
const v1Router = express.Router();
v1Router.get('/users', getUsersV1);

const v2Router = express.Router();
v2Router.get('/users', getUsersV2);

app.use('/api/v1', v1Router);  // No StripPrefix needed!
app.use('/api/v2', v2Router);  // Express handles it automatically

05 TLS, HTTPS & HTTP/2

Production servers must use TLS (Transport Layer Security) to encrypt traffic. Go makes this straightforward with ListenAndServeTLS. Here's a complete breakdown of how TLS, certificates, HTTPS, and HTTP/2 work in Go.

How TLS/HTTPS Works (The Big Picture)

Browser                                 Go Server (:443)
   │                                         │
   │──── 1. ClientHello ────────────────────→│  "I support TLS 1.3, these ciphers"
   │                                         │
   │←─── 2. ServerHello + Certificate ──────│  "Let's use TLS 1.3. Here's my cert"
   │                                         │
   │──── 3. Verify cert against CA ─────────│  Browser checks cert chain
   │                                         │
   │──── 4. Key Exchange ───────────────────→│  Establish shared secret
   │                                         │
   │←──→ 5. Encrypted HTTP traffic ────────→│  All data encrypted from here
   │                                         │
   │     (ALPN negotiation happens at step 2:
   │      both sides agree on h2 = HTTP/2)

Generating Certificates

Before you can serve HTTPS, you need a certificate (public) and a private key. There are three ways to get them:

1. Self-Signed Certificate (Development Only)

# Generate a self-signed cert valid for 365 days
# -x509: output a self-signed cert instead of a CSR
# -nodes: don't encrypt the private key with a passphrase
# -newkey rsa:4096: generate a new 4096-bit RSA key
openssl req -x509 -newkey rsa:4096 \
    -keyout key.pem \
    -out cert.pem \
    -days 365 \
    -nodes \
    -subj "/CN=localhost"

# For testing with multiple domains (Subject Alternative Names):
openssl req -x509 -newkey rsa:4096 \
    -keyout key.pem -out cert.pem -days 365 -nodes \
    -subj "/CN=localhost" \
    -addext "subjectAltName=DNS:localhost,DNS:*.localhost,IP:127.0.0.1"

2. Generate Certs Programmatically in Go (Tests & Dev)

Go can generate certificates at runtime — useful for test servers and development tools that need TLS without external files.

package main

import (
    "crypto/ecdsa"
    "crypto/elliptic"
    "crypto/rand"
    "crypto/tls"
    "crypto/x509"
    "crypto/x509/pkix"
    "encoding/pem"
    "fmt"
    "log"
    "math/big"
    "net"
    "net/http"
    "time"
)

func generateSelfSignedCert() (tls.Certificate, error) {
    // Generate ECDSA private key (faster than RSA, smaller keys)
    privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
    if err != nil {
        return tls.Certificate{}, err
    }

    // Create certificate template
    template := &x509.Certificate{
        SerialNumber: big.NewInt(1),
        Subject:      pkix.Name{Organization: []string{"Dev"}},
        NotBefore:    time.Now(),
        NotAfter:     time.Now().Add(24 * time.Hour),  // 1 day validity
        KeyUsage:     x509.KeyUsageDigitalSignature,
        ExtKeyUsage:  []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
        IPAddresses:  []net.IP{net.ParseIP("127.0.0.1")},
        DNSNames:     []string{"localhost"},
    }

    // Self-sign: certificate signs itself (template == parent)
    certDER, err := x509.CreateCertificate(rand.Reader, template, template,
        &privateKey.PublicKey, privateKey)
    if err != nil {
        return tls.Certificate{}, err
    }

    // Encode to PEM format in memory (no files needed)
    certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: certDER})
    keyDER, _ := x509.MarshalECPrivateKey(privateKey)
    keyPEM := pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER})

    return tls.X509KeyPair(certPEM, keyPEM)
}

func main() {
    cert, err := generateSelfSignedCert()
    if err != nil {
        log.Fatal(err)
    }

    mux := http.NewServeMux()
    mux.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "TLS: %s, Protocol: %s", r.TLS.Version, r.Proto)
    })

    server := &http.Server{
        Addr:    ":8443",
        Handler: mux,
        TLSConfig: &tls.Config{
            Certificates: []tls.Certificate{cert},  // Use the in-memory cert
            MinVersion:   tls.VersionTLS12,
        },
    }

    log.Println("HTTPS server on :8443")
    // Pass empty strings — certs are already in TLSConfig
    log.Fatal(server.ListenAndServeTLS("", ""))
}

3. Let's Encrypt with autocert (Production)

The autocert package automatically provisions and renews TLS certificates from Let's Encrypt. Zero manual cert management.

import (
    "crypto/tls"
    "net/http"
    "golang.org/x/crypto/acme/autocert"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /", homeHandler)

    // autocert manager handles everything:
    // - Requests certs from Let's Encrypt on first connection
    // - Caches them in /var/www/.cache
    // - Auto-renews before expiry (certs last 90 days)
    certManager := autocert.Manager{
        Prompt:     autocert.AcceptTOS,                            // Accept Let's Encrypt TOS
        HostPolicy: autocert.HostWhitelist("example.com", "www.example.com"),  // Only these domains
        Cache:      autocert.DirCache("/var/www/.cache"),           // Where to store certs
    }

    server := &http.Server{
        Addr:    ":443",
        Handler: mux,
        TLSConfig: &tls.Config{
            GetCertificate: certManager.GetCertificate,  // Dynamic cert lookup
            MinVersion:     tls.VersionTLS12,
        },
    }

    // IMPORTANT: Also run HTTP on port 80 for two reasons:
    // 1. Let's Encrypt needs port 80 for HTTP-01 challenge verification
    // 2. Redirect all HTTP traffic to HTTPS
    go http.ListenAndServe(":80", certManager.HTTPHandler(nil))

    log.Fatal(server.ListenAndServeTLS("", ""))  // Certs come from certManager
}

Basic HTTPS Server with TLS Config

The most common production setup: load cert files, configure TLS, serve HTTPS.

import (
    "crypto/tls"
    "fmt"
    "log"
    "net/http"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Protocol: %s, TLS: %v\n", r.Proto, r.TLS != nil)
    })

    tlsConfig := &tls.Config{
        MinVersion:               tls.VersionTLS12,  // Minimum TLS 1.2
        MaxVersion:               tls.VersionTLS13,  // Allow TLS 1.3 (default anyway)
        PreferServerCipherSuites: true,              // Server chooses the cipher
        CurvePreferences: []tls.CurveID{
            tls.X25519,     // Fastest, most secure
            tls.CurveP256,  // Widely supported fallback
        },
        CipherSuites: []uint16{
            // TLS 1.3 ciphers (always used for TLS 1.3, this list is for TLS 1.2)
            tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
            tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
            tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
            tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
            tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
            tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
        },
    }

    server := &http.Server{
        Addr:              ":443",
        Handler:           mux,
        TLSConfig:         tlsConfig,
        ReadTimeout:       5 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       120 * time.Second,
        ReadHeaderTimeout: 2 * time.Second,
    }

    log.Println("HTTPS server starting on :443")
    // cert.pem = your certificate (public), key.pem = your private key
    log.Fatal(server.ListenAndServeTLS("cert.pem", "key.pem"))
}

HTTP to HTTPS Redirect

In production, you should always redirect HTTP traffic to HTTPS. Run a small server on port 80 that 301-redirects everything.

// Run this alongside your HTTPS server
go func() {
    redirectServer := &http.Server{
        Addr: ":80",
        Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // Build HTTPS URL from the original request
            target := "https://" + r.Host + r.RequestURI
            http.Redirect(w, r, target, http.StatusMovedPermanently)  // 301
        }),
        ReadTimeout:  5 * time.Second,
        WriteTimeout: 5 * time.Second,
    }
    log.Fatal(redirectServer.ListenAndServe())
}()

HTTP/2 — Automatic with TLS

Go enables HTTP/2 automatically when you serve over TLS. No configuration needed — the ALPN (Application-Layer Protocol Negotiation) during the TLS handshake handles it. Both client and server agree on "h2" (HTTP/2) during step 2 of the TLS handshake.

// HTTP/2 is AUTOMATIC with TLS. Just use ListenAndServeTLS and you get:
// - Multiplexed streams (many requests on one connection)
// - Header compression (HPACK)
// - Stream prioritization
// - Binary framing (faster parsing than HTTP/1.1 text)

// You can verify the protocol in your handler:
mux.HandleFunc("GET /protocol", func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Protocol: %s\n", r.Proto)
    // With TLS:    "Protocol: HTTP/2.0"
    // Without TLS: "Protocol: HTTP/1.1"
})

Explicit HTTP/2 Configuration

For advanced control (max concurrent streams, upload limits), use golang.org/x/net/http2:

import "golang.org/x/net/http2"

server := &http.Server{
    Addr:      ":443",
    Handler:   mux,
    TLSConfig: tlsConfig,
}

// Configure HTTP/2 settings
http2.ConfigureServer(server, &http2.Server{
    MaxConcurrentStreams:         250,                 // Max simultaneous streams per connection
    MaxUploadBufferPerConnection: 1 << 20,             // 1 MB flow control window
    MaxUploadBufferPerStream:     1 << 20,             // 1 MB per stream
})

log.Fatal(server.ListenAndServeTLS("cert.pem", "key.pem"))

HTTP/2 Cleartext (h2c) — Without TLS

Sometimes you need HTTP/2 without TLS — typically behind a reverse proxy (Nginx, Envoy) that handles TLS termination. Go supports this via h2c:

import (
    "net/http"
    "golang.org/x/net/http2"
    "golang.org/x/net/http2/h2c"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Protocol: %s (no TLS!)\n", r.Proto)
    })

    // h2c.NewHandler wraps your mux to handle HTTP/2 cleartext upgrades
    h2s := &http2.Server{}
    handler := h2c.NewHandler(mux, h2s)

    server := &http.Server{
        Addr:    ":8080",
        Handler: handler,  // Supports both HTTP/1.1 and HTTP/2 without TLS
    }

    // No TLS, but HTTP/2 works via cleartext upgrade
    log.Fatal(server.ListenAndServe())

    // Test with: curl --http2-prior-knowledge http://localhost:8080/
}

Mutual TLS (mTLS) — Both Sides Verify

In mTLS, both the server AND the client present certificates. The server verifies the client's cert before allowing the connection. This is used in service-to-service communication (Kubernetes, service meshes, internal APIs).

import (
    "crypto/tls"
    "crypto/x509"
    "log"
    "net/http"
    "os"
)

func main() {
    // Load the CA certificate that signed client certificates
    caCert, err := os.ReadFile("ca-cert.pem")
    if err != nil {
        log.Fatal(err)
    }

    // Create a cert pool with the CA cert
    caCertPool := x509.NewCertPool()
    caCertPool.AppendCertsFromPEM(caCert)

    tlsConfig := &tls.Config{
        // RequireAndVerifyClientCert = client MUST present a valid cert
        // Other options:
        //   NoClientCert              — don't ask for client cert (default)
        //   RequestClientCert         — ask but don't verify
        //   RequireAnyClientCert      — require but don't verify against CA
        //   VerifyClientCertIfGiven   — verify only if client sends one
        ClientAuth: tls.RequireAndVerifyClientCert,
        ClientCAs:  caCertPool,  // Only accept client certs signed by this CA
        MinVersion: tls.VersionTLS12,
    }

    mux := http.NewServeMux()
    mux.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
        // Access client certificate info
        if len(r.TLS.PeerCertificates) > 0 {
            clientCert := r.TLS.PeerCertificates[0]
            fmt.Fprintf(w, "Hello %s (verified client)\n", clientCert.Subject.CommonName)
        }
    })

    server := &http.Server{
        Addr:      ":8443",
        Handler:   mux,
        TLSConfig: tlsConfig,
    }

    // Server's own cert and key
    log.Fatal(server.ListenAndServeTLS("server-cert.pem", "server-key.pem"))
}

// mTLS Client — must present its own certificate:
// cert, _ := tls.LoadX509KeyPair("client-cert.pem", "client-key.pem")
// client := &http.Client{
//     Transport: &http.Transport{
//         TLSClientConfig: &tls.Config{
//             Certificates: []tls.Certificate{cert},
//             RootCAs:      caCertPool,  // Trust the server's CA
//         },
//     },
// }
// resp, err := client.Get("https://localhost:8443/")

SNI — Multiple Domains on One Server

Server Name Indication (SNI) lets one server serve different certificates for different hostnames. Go supports this via the GetCertificate callback.

// Load certificates for different domains
certExample, _ := tls.LoadX509KeyPair("example.com.pem", "example.com-key.pem")
certAPI, _ := tls.LoadX509KeyPair("api.example.com.pem", "api.example.com-key.pem")

certs := map[string]tls.Certificate{
    "example.com":     certExample,
    "api.example.com": certAPI,
}

tlsConfig := &tls.Config{
    GetCertificate: func(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
        // hello.ServerName contains the hostname the client requested
        if cert, ok := certs[hello.ServerName]; ok {
            return &cert, nil
        }
        return &certExample, nil  // Default fallback
    },
    MinVersion: tls.VersionTLS12,
}

HTTP/1.1 vs HTTP/2 vs HTTP/3

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /api/health", healthHandler)
    mux.HandleFunc("GET /api/users/{id}", getUserHandler)

    tlsConfig := &tls.Config{
        MinVersion: tls.VersionTLS12,
        CurvePreferences: []tls.CurveID{tls.X25519, tls.CurveP256},
    }

    httpsServer := &http.Server{
        Addr:              ":443",
        Handler:           mux,
        TLSConfig:         tlsConfig,
        ReadTimeout:       5 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       120 * time.Second,
        ReadHeaderTimeout: 2 * time.Second,
    }

    // HTTP/2 is automatic with TLS — this line is optional for tuning
    http2.ConfigureServer(httpsServer, &http2.Server{})

    // HTTP → HTTPS redirect on port 80
    go http.ListenAndServe(":80", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        http.Redirect(w, r, "https://"+r.Host+r.RequestURI, http.StatusMovedPermanently)
    }))

    // Graceful shutdown
    go func() {
        quit := make(chan os.Signal, 1)
        signal.Notify(quit, os.Interrupt)
        <-quit
        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
        defer cancel()
        httpsServer.Shutdown(ctx)
    }()

    log.Println("HTTPS on :443, HTTP redirect on :80")
    log.Fatal(httpsServer.ListenAndServeTLS("cert.pem", "key.pem"))
}

// Node.js — HTTPS server (like Go's ListenAndServeTLS)
const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync('key.pem'),     // Go: passed to ListenAndServeTLS
  cert: fs.readFileSync('cert.pem'),   // Go: passed to ListenAndServeTLS
  minVersion: 'TLSv1.2',              // Go: tls.Config{MinVersion: tls.VersionTLS12}
};

const server = https.createServer(options, app);
server.listen(443);

// HTTP → HTTPS redirect (same concept as Go)
const http = require('http');
http.createServer((req, res) => {
  res.writeHead(301, { Location: `https://${req.headers.host}${req.url}` });
  res.end();
}).listen(80);

// Node.js HTTP/2 — requires separate module (NOT automatic like Go!)
const http2 = require('http2');
const h2Server = http2.createSecureServer({
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem'),
  allowHTTP1: true,  // Fallback to HTTP/1.1
});

// Let's Encrypt (like Go's autocert)
// npm install greenlock-express
require('greenlock-express').init({
  packageRoot: __dirname,
  maintainerEmail: 'admin@example.com',
  configDir: './greenlock.d',
  cluster: false,
}).serve(app);

06 REST API Project Structure

Go projects follow a conventional layout using cmd/, internal/, and pkg/ directories. This structure comes from the Go community standard and is used by most production Go applications. The key idea: internal/ packages cannot be imported by external projects (enforced by the Go compiler), while pkg/ packages are shareable.

# Go Project Structure          →  Node.js/Express Equivalent
───────────────────────────────────────────────────────────
rest_api_go/                       my-express-app/
├── cmd/api/server.go              ├── src/index.js          # entry point
├── internal/                      ├── src/                  # no enforced privacy
│   ├── models/student.go          │   ├── models/Student.js # Mongoose/Prisma schema
│   ├── api/handlers/              │   ├── controllers/      # request handlers
│   ├── api/router/                │   ├── routes/           # route definitions
│   ├── api/middlewares/           │   ├── middleware/        # Express middleware
│   └── repository/sqlconnect/     │   ├── services/         # business logic
├── pkg/utils/                     │   └── utils/            # shared utilities
├── go.mod                         ├── package.json          # like go.mod
├── go.sum                         ├── package-lock.json     # like go.sum
└── Makefile                       └── node_modules/         # 500MB+ of deps

07 Models

Models define the shape of your data. In Go, we use struct tags to control how data is serialized to JSON and mapped to database columns. The json tag controls JSON field names, and the db tag (used by libraries like sqlx) maps to database columns.

Student Model

package models

type Student struct {
    ID        int    `json:"id,omitempty" db:"id,omitempty"`
    FirstName string `json:"first_name,omitempty" db:"first_name,omitempty"`
    LastName  string `json:"last_name,omitempty" db:"last_name,omitempty"`
    Email     string `json:"email,omitempty" db:"email,omitempty"`
    Class     string `json:"class,omitempty" db:"class,omitempty"`
}

Exec Model (with nullable fields)

Real databases have nullable columns. Go's sql.NullString handles this by wrapping a string with a Valid boolean. When the database value is NULL, Valid is false and String is empty.

package models

import "database/sql"

type Exec struct {
    ID         int            `json:"id,omitempty" db:"id,omitempty"`
    FirstName  sql.NullString `json:"first_name,omitempty" db:"first_name,omitempty"`
    LastName   sql.NullString `json:"last_name,omitempty" db:"last_name,omitempty"`
    Email      sql.NullString `json:"email,omitempty" db:"email,omitempty"`
    Department sql.NullString `json:"department,omitempty" db:"department,omitempty"`
}

// Usage: checking if a NullString has a value
if exec.Email.Valid {
    fmt.Println("Email:", exec.Email.String)
} else {
    fmt.Println("Email is NULL")
}

// --- Mongoose Schema (like Go struct with tags) ---
const studentSchema = new mongoose.Schema({
  firstName: { type: String, required: true },  // Go: `json:"first_name" validate:"required"`
  lastName:  { type: String },
  email:     { type: String, required: true },
  class:     { type: String },
}, {
  toJSON: {                           // Like Go's json:"..." tags
    transform: (doc, ret) => {
      ret.id = ret._id;              // Like Go's json:"id"
      delete ret._id;
      delete ret.__v;
    }
  }
});

// --- Prisma Model (schema-first, like Go structs) ---
// In prisma/schema.prisma:
// model Student {
//   id        Int    @id @default(autoincrement())
//   firstName String @map("first_name")   // Like Go's db:"first_name"
//   lastName  String @map("last_name")
//   email     String
//   class     String?                     // ? = nullable (like sql.NullString)
// }

// --- TypeScript Interface (type-safe but no runtime) ---
interface Student {
  id?: number;          // ? = optional (like omitempty)
  first_name: string;
  last_name?: string;
  email: string;
  class?: string;
}

08 Database Connection (MySQL)

Go's database/sql package provides a generic interface for SQL databases. The actual driver (MySQL, PostgreSQL, SQLite) is imported as a side effect using the blank identifier _. The connection pool is managed automatically — sql.Open doesn't actually connect; it prepares the pool. The first real query triggers the connection.

package sqlconnect

import (
    "database/sql"
    "fmt"
    "os"

    _ "github.com/go-sql-driver/mysql"  // Import driver as side effect
)

const (
    host   = "localhost"
    dbport = "3306"
)

func ConnectDb() (*sql.DB, error) {
    // Read credentials from environment variables (never hardcode!)
    user := os.Getenv("DB_USER")
    password := os.Getenv("DB_PASSWORD")
    dbname := os.Getenv("DB_NAME")

    // Build the MySQL connection string: user:password@tcp(host:port)/dbname
    connectionString := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s",
        user, password, host, dbport, dbname)

    // sql.Open doesn't connect — it prepares the connection pool
    db, err := sql.Open("mysql", connectionString)
    if err != nil {
        return nil, fmt.Errorf("failed to open database: %w", err)
    }

    // Ping to verify the connection actually works
    if err := db.Ping(); err != nil {
        return nil, fmt.Errorf("failed to ping database: %w", err)
    }

    // Configure the connection pool
    db.SetMaxOpenConns(25)                  // Max open connections
    db.SetMaxIdleConns(5)                   // Max idle connections in pool
    db.SetConnMaxLifetime(5 * time.Minute)  // Max lifetime of a connection

    return db, nil
}

// --- mysql2 (closest to Go's database/sql) ---
const mysql = require('mysql2/promise');

// Create a connection pool (like Go's sql.Open + SetMaxOpenConns)
const pool = mysql.createPool({
  host: 'localhost',
  port: 3306,
  user: process.env.DB_USER,         // Like Go's os.Getenv("DB_USER")
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  connectionLimit: 25,               // Like Go's SetMaxOpenConns(25)
  idleTimeout: 300000,               // Like Go's SetConnMaxIdleTime
  waitForConnections: true,
});

// Test connection (like Go's db.Ping())
await pool.query('SELECT 1');

// --- Prisma (ORM approach — no direct Go stdlib equivalent) ---
const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();  // Pool managed internally

// --- Knex.js (query builder, similar to sqlx) ---
const knex = require('knex')({
  client: 'mysql2',
  connection: { host: 'localhost', user: 'root', database: 'mydb' },
  pool: { min: 5, max: 25 },       // Like Go's SetMaxIdleConns/SetMaxOpenConns
});

09 CRUD Operations

CRUD (Create, Read, Update, Delete) operations form the backbone of any REST API. Each operation maps to an HTTP method: POST (Create), GET (Read), PUT/PATCH (Update), DELETE (Delete). Let's build real handlers that talk to a MySQL database.

GET with Pagination

Always paginate list endpoints. Without pagination, a table with millions of rows will crash your server. Use page and limit query parameters with sensible defaults.

func GetStudents(w http.ResponseWriter, r *http.Request) {
    // Parse pagination parameters with defaults
    page, _ := strconv.Atoi(r.URL.Query().Get("page"))
    limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))
    if page < 1 { page = 1 }
    if limit < 1 || limit > 100 { limit = 10 }

    offset := (page - 1) * limit

    // Query the database with LIMIT and OFFSET
    query := "SELECT id, first_name, last_name, email, class FROM students LIMIT ? OFFSET ?"
    rows, err := db.Query(query, limit, offset)
    if err != nil {
        http.Error(w, "Database error", http.StatusInternalServerError)
        return
    }
    defer rows.Close()

    var students []models.Student
    for rows.Next() {
        var s models.Student
        if err := rows.Scan(&s.ID, &s.FirstName, &s.LastName, &s.Email, &s.Class); err != nil {
            http.Error(w, "Scan error", http.StatusInternalServerError)
            return
        }
        students = append(students, s)
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(students)
}

POST with Validation

func CreateStudent(w http.ResponseWriter, r *http.Request) {
    var s models.Student

    // Decode JSON body into struct
    if err := json.NewDecoder(r.Body).Decode(&s); err != nil {
        http.Error(w, "Invalid JSON", http.StatusBadRequest)
        return
    }

    // Validate required fields
    if s.FirstName == "" || s.Email == "" {
        http.Error(w, "first_name and email are required", http.StatusBadRequest)
        return
    }

    // Insert into database
    result, err := db.Exec(
        "INSERT INTO students (first_name, last_name, email, class) VALUES (?, ?, ?, ?)",
        s.FirstName, s.LastName, s.Email, s.Class,
    )
    if err != nil {
        http.Error(w, "Insert failed", http.StatusInternalServerError)
        return
    }

    // Get the auto-generated ID
    id, _ := result.LastInsertId()
    s.ID = int(id)

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)  // 201 for resource creation
    json.NewEncoder(w).Encode(s)
}

PUT — Full Update

PUT replaces the entire resource. All fields must be provided. If a field is missing, it gets set to its zero value.

func UpdateStudent(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    var s models.Student
    if err := json.NewDecoder(r.Body).Decode(&s); err != nil {
        http.Error(w, "Invalid JSON", http.StatusBadRequest)
        return
    }

    // Update ALL fields — this is what makes it PUT, not PATCH
    _, err := db.Exec(
        "UPDATE students SET first_name=?, last_name=?, email=?, class=? WHERE id=?",
        s.FirstName, s.LastName, s.Email, s.Class, id,
    )
    if err != nil {
        http.Error(w, "Update failed", http.StatusInternalServerError)
        return
    }

    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]string{"status": "updated"})
}

PATCH — Partial Update (using Reflection)

PATCH is trickier than PUT. You only update the fields that were sent in the request. Using Go's reflect package, you can dynamically build the SQL SET clause based on which fields have non-zero values.

func PatchStudent(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    var s models.Student
    if err := json.NewDecoder(r.Body).Decode(&s); err != nil {
        http.Error(w, "Invalid JSON", http.StatusBadRequest)
        return
    }

    // Use reflection to build dynamic SET clause
    v := reflect.ValueOf(s)
    t := v.Type()
    var setClauses []string
    var values []interface{}

    for i := 0; i < v.NumField(); i++ {
        field := v.Field(i)
        // Skip zero-value fields (they weren't in the JSON body)
        if !field.IsZero() {
            dbTag := t.Field(i).Tag.Get("db")
            column := strings.Split(dbTag, ",")[0]
            if column != "" && column != "id" {
                setClauses = append(setClauses, column+"=?")
                values = append(values, field.Interface())
            }
        }
    }

    if len(setClauses) == 0 {
        http.Error(w, "No fields to update", http.StatusBadRequest)
        return
    }

    values = append(values, id)
    query := fmt.Sprintf("UPDATE students SET %s WHERE id=?",
        strings.Join(setClauses, ", "))
    db.Exec(query, values...)
}

DELETE with Transaction

For destructive operations, use transactions. This ensures either all operations succeed or none do. If deleting a student also requires cleaning up related records, a transaction keeps your data consistent.

func DeleteStudent(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    // Begin a transaction
    tx, err := db.Begin()
    if err != nil {
        http.Error(w, "Transaction start failed", http.StatusInternalServerError)
        return
    }

    // Delete related records first (foreign key constraints)
    _, err = tx.Exec("DELETE FROM enrollments WHERE student_id = ?", id)
    if err != nil {
        tx.Rollback()  // Undo everything if this fails
        http.Error(w, "Failed to delete enrollments", http.StatusInternalServerError)
        return
    }

    // Delete the student
    result, err := tx.Exec("DELETE FROM students WHERE id = ?", id)
    if err != nil {
        tx.Rollback()
        http.Error(w, "Failed to delete student", http.StatusInternalServerError)
        return
    }

    rowsAffected, _ := result.RowsAffected()
    if rowsAffected == 0 {
        tx.Rollback()
        http.Error(w, "Student not found", http.StatusNotFound)
        return
    }

    // Commit the transaction — all operations succeed together
    tx.Commit()
    w.WriteHeader(http.StatusNoContent)  // 204 — deleted, no body
}

// --- GET with Pagination (Express + mysql2) ---
app.get('/students', async (req, res) => {
  let page = parseInt(req.query.page) || 1;    // Go: strconv.Atoi(r.URL.Query().Get("page"))
  let limit = parseInt(req.query.limit) || 10;
  const offset = (page - 1) * limit;

  const [rows] = await pool.query(
    'SELECT * FROM students LIMIT ? OFFSET ?',  // Same SQL!
    [limit, offset]                               // Same parameterized query
  );
  res.json(rows);  // Go: json.NewEncoder(w).Encode(students)
});

// --- POST (Express + mysql2) ---
app.post('/students', async (req, res) => {
  const { first_name, email, last_name, class: cls } = req.body;
  // Go: json.NewDecoder(r.Body).Decode(&s)

  if (!first_name || !email) {
    return res.status(400).json({ error: 'first_name and email required' });
  }

  const [result] = await pool.query(
    'INSERT INTO students (first_name, last_name, email, class) VALUES (?, ?, ?, ?)',
    [first_name, last_name, email, cls]
  );
  res.status(201).json({ id: result.insertId, first_name, email });
  // Go: w.WriteHeader(http.StatusCreated)
});

// --- DELETE with Transaction ---
app.delete('/students/:id', async (req, res) => {
  const conn = await pool.getConnection();
  try {
    await conn.beginTransaction();               // Go: db.Begin()
    await conn.query('DELETE FROM enrollments WHERE student_id = ?', [req.params.id]);
    const [result] = await conn.query('DELETE FROM students WHERE id = ?', [req.params.id]);
    if (result.affectedRows === 0) {
      await conn.rollback();                     // Go: tx.Rollback()
      return res.status(404).json({ error: 'Not found' });
    }
    await conn.commit();                          // Go: tx.Commit()
    res.status(204).end();
  } catch (err) {
    await conn.rollback();
    res.status(500).json({ error: 'Delete failed' });
  } finally {
    conn.release();                              // Go: automatic with pool
  }
});

10 Routing & Router Setup

In a real project, you don't define all routes in main(). Instead, you create router functions for each domain (students, teachers, execs) and compose them together. This keeps each file focused and makes it easy to add new route groups without touching existing code.

package router

import "net/http"

// MainRouter composes all sub-routers into one
func MainRouter() *http.ServeMux {
    tRouter := teachersRouter()  // handles /teachers/*
    sRouter := studentsRouter()  // handles /students/*

    // Mount execs router under students router
    sRouter.Handle("/", execsRouter())

    // Mount students router (with execs) under teachers router
    tRouter.Handle("/", sRouter)

    return tRouter
}

// Each sub-router defines its own routes
func studentsRouter() *http.ServeMux {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /students", handlers.GetStudents)
    mux.HandleFunc("GET /students/{id}", handlers.GetStudent)
    mux.HandleFunc("POST /students", handlers.CreateStudent)
    mux.HandleFunc("PUT /students/{id}", handlers.UpdateStudent)
    mux.HandleFunc("PATCH /students/{id}", handlers.PatchStudent)
    mux.HandleFunc("DELETE /students/{id}", handlers.DeleteStudent)
    return mux
}

func teachersRouter() *http.ServeMux {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /teachers", handlers.GetTeachers)
    mux.HandleFunc("GET /teachers/{id}", handlers.GetTeacher)
    return mux
}

// routes/students.js (like Go's studentsRouter function)
const router = require('express').Router();
router.get('/', handlers.getStudents);
router.get('/:id', handlers.getStudent);
router.post('/', handlers.createStudent);
router.put('/:id', handlers.updateStudent);
router.patch('/:id', handlers.patchStudent);
router.delete('/:id', handlers.deleteStudent);
module.exports = router;

// routes/teachers.js
const router = require('express').Router();
router.get('/', handlers.getTeachers);
router.get('/:id', handlers.getTeacher);
module.exports = router;

// app.js — main router composition (like Go's MainRouter)
const app = require('express')();
app.use('/students', require('./routes/students'));
app.use('/teachers', require('./routes/teachers'));
app.use('/execs', require('./routes/execs'));

11 Middleware Pattern

Middleware is the backbone of any production Go server. A middleware is simply a function that wraps an http.Handler, does something before/after the request, and calls the next handler in the chain. This pattern is composable: you stack middlewares like layers, and each request passes through all of them in order.

The signature is always the same: take a handler, return a handler. This makes every middleware interchangeable and stackable.

package utils

import "net/http"

// Middleware is a function that wraps an http.Handler
type Middleware func(http.Handler) http.Handler

// ApplyMiddlewares chains multiple middlewares around a handler.
// Middlewares are applied in reverse order so they execute left-to-right.
func ApplyMiddlewares(handler http.Handler, middlewares ...Middleware) http.Handler {
    for _, mw := range middlewares {
        handler = mw(handler)
    }
    return handler
}

Using the Middleware Chain

func main() {
    router := router.MainRouter()

    // Stack middlewares — order matters!
    // Outermost (first listed) runs first on request, last on response
    secureMux := utils.ApplyMiddlewares(router,
        mw.SecurityHeaders,         // Set security headers on every response
        mw.Compression,             // Gzip compress responses
        mw.XSSMiddleware,           // Sanitize input
        jwtMiddleware,              // Authenticate requests
        mw.ResponseTimeMiddleware,  // Track response times
        mw.Cors,                    // Handle CORS preflight
    )

    http.ListenAndServe(":8080", secureMux)
}

Express vs Go Middleware — Side by Side

If you're coming from Node/Express, Go middleware looks unfamiliar at first because it uses a wrapper pattern instead of a callback chain. Both accomplish the same goal — run code before/after handlers — but the mental model is different.

Express: Callback-style Chain

In Express, middleware is a function that receives (req, res, next). You call next() to hand control to the next middleware. The framework keeps an internal array of middleware and calls them in registration order — you never see the chain itself.

// Express: middleware is a function you register
app.use((req, res, next) => {
  console.log('before');
  next();              // hand off to the next middleware
  console.log('after');
});

app.get('/hello', (req, res) => res.send('hi'));

Go: Wrapper-style (Decorator Pattern)

In Go, middleware is a function that takes a handler and returns a new handler. You build the chain explicitly by wrapping: logger(auth(mux)). There's no hidden array — the stack is literally the code you wrote.

// Go: middleware wraps a handler, returns a handler
func logger(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    log.Println("before")
    next.ServeHTTP(w, r)   // call the wrapped handler
    log.Println("after")
  })
}

mux := http.NewServeMux()
mux.HandleFunc("/hello", helloHandler)

// You explicitly build the stack by wrapping:
http.ListenAndServe(":8080", logger(auth(mux)))

Concept-by-Concept Mapping

Short-circuiting: Auth Rejection Example

Both frameworks support early return — just skip calling the "next" step.

// Express: don't call next(), just respond
app.use((req, res, next) => {
  if (!req.headers.authorization) {
    return res.status(401).send('unauthorized');
  }
  next();
});

// Go: don't call next.ServeHTTP, just write
func auth(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    if r.Header.Get("Authorization") == "" {
      http.Error(w, "unauthorized", http.StatusUnauthorized)
      return
    }
    next.ServeHTTP(w, r)
  })
}

12 Security Headers Middleware

Security headers tell the browser how to behave when handling your site's content. Without these headers, your application is vulnerable to clickjacking, XSS, MIME sniffing, and other attacks. This middleware sets all recommended headers on every response.

package middlewares

import "net/http"

func SecurityHeaders(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Prevent the page from being embedded in an iframe (clickjacking)
        w.Header().Set("X-Frame-Options", "SAMEORIGIN")

        // Prevent MIME type sniffing — browser must trust Content-Type
        w.Header().Set("X-Content-Type-Options", "nosniff")

        // Enable browser's built-in XSS filter
        w.Header().Set("X-XSS-Protection", "1; mode=block")

        // HSTS — force HTTPS for 1 year, include subdomains
        w.Header().Set("Strict-Transport-Security",
            "max-age=31536000; includeSubDomains; preload")

        // Content Security Policy — restrict resource origins
        w.Header().Set("Content-Security-Policy",
            "default-src 'self'; script-src 'self'; style-src 'self'")

        // Control how much referrer info is sent with requests
        w.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin")

        // Restrict browser features (camera, microphone, etc.)
        w.Header().Set("Permissions-Policy",
            "camera=(), microphone=(), geolocation=()")

        // Remove server identification header
        w.Header().Del("Server")

        next.ServeHTTP(w, r)  // Pass to next handler
    })
}

// Express + Helmet — same headers, one line
const helmet = require('helmet');
app.use(helmet());  // Sets ALL the same headers Go sets manually!

// What helmet() does internally (same as Go's SecurityHeaders):
app.use(helmet({
  frameguard: { action: 'sameorigin' },          // X-Frame-Options: SAMEORIGIN
  noSniff: true,                                 // X-Content-Type-Options: nosniff
  xssFilter: true,                                // X-XSS-Protection: 1; mode=block
  hsts: { maxAge: 31536000, includeSubDomains: true },
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'"],
      styleSrc: ["'self'"],
    }
  },
  referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
  permittedCrossDomainPolicies: false,
}));

// Without helmet (manual, like Go's approach):
app.use((req, res, next) => {
  res.setHeader('X-Frame-Options', 'SAMEORIGIN');
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('X-XSS-Protection', '1; mode=block');
  res.removeHeader('X-Powered-By');  // Like Go's w.Header().Del("Server")
  next();
});

<!-- evil.com -->
<iframe src="https://bank.example.com/transfer"
        style="opacity:0.01;position:absolute;top:0;left:0;"></iframe>
<button style="position:absolute;top:50px;left:50px">Claim prize</button>

# User uploads "profile.png" whose bytes begin with:
<html><script>fetch('/api/me').then(r=>r.json()).then(send)</script>

# Server replies:   Content-Type: image/png
# Without nosniff:  browser sniffs "looks like HTML", renders & runs the script
# With nosniff:     browser treats it as a broken image. Safe.

# Target page has:
<script>if (!isAdmin) document.body.innerHTML = '';</script>
<div>secret admin data</div>

# Attacker links to:  /page?q=<script>if (!isAdmin)
# Auditor sees matching script in URL + body → strips the defensive script
# Secret div remains visible. Leak.

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

# User opens: https://app.example.com/reset?token=abc123
# Page loads:  https://cdn.ads.com/pixel.gif

# Without Referrer-Policy (old default):
#   Referer: https://app.example.com/reset?token=abc123  ← leaked to ad network

# With strict-origin-when-cross-origin:
#   Referer: https://app.example.com                     ← token stripped

Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(),
  usb=(), accelerometer=(), gyroscope=(), clipboard-read=()

13 CORS Middleware

CORS (Cross-Origin Resource Sharing) is a browser security mechanism. When your frontend at localhost:3000 calls your API at localhost:8080, the browser blocks the request unless your API explicitly allows it via CORS headers. Without proper CORS, your SPA cannot talk to your API.

The browser sends a preflight request (OPTIONS) before the actual request to check if the origin is allowed. Your middleware must handle this preflight and respond with the appropriate headers.

package middlewares

import "net/http"

func Cors(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        origin := r.Header.Get("Origin")

        // Define allowed origins
        allowedOrigins := map[string]bool{
            "http://localhost:3000": true,
            "https://myapp.com":      true,
        }

        if allowedOrigins[origin] {
            // Echo the allowed origin (not "*" — needed for credentials)
            w.Header().Set("Access-Control-Allow-Origin", origin)
            w.Header().Set("Access-Control-Allow-Methods",
                "GET, POST, PUT, PATCH, DELETE, OPTIONS")
            w.Header().Set("Access-Control-Allow-Headers",
                "Content-Type, Authorization, X-Requested-With")
            w.Header().Set("Access-Control-Allow-Credentials", "true")
            w.Header().Set("Access-Control-Max-Age", "86400")  // Cache preflight for 24h
        }

        // Handle preflight (OPTIONS) — return immediately, don't hit handler
        if r.Method == http.MethodOptions {
            w.WriteHeader(http.StatusNoContent)  // 204
            return
        }

        next.ServeHTTP(w, r)
    })
}

// Express + cors package (npm install cors)
const cors = require('cors');

app.use(cors({
  origin: ['http://localhost:3000', 'https://myapp.com'],  // Like Go's allowedOrigins map
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,                                       // Allow-Credentials: true
  maxAge: 86400,                                             // Cache preflight 24h
}));

// Without cors package (manual, like Go's approach):
app.use((req, res, next) => {
  const origin = req.headers.origin;
  const allowed = ['http://localhost:3000', 'https://myapp.com'];
  if (allowed.includes(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type,Authorization');
    res.setHeader('Access-Control-Allow-Credentials', 'true');
  }
  if (req.method === 'OPTIONS') return res.sendStatus(204);
  next();
});

14 JWT Authentication Middleware

JWT (JSON Web Token) is the standard for stateless authentication in REST APIs. The token is signed by the server and contains claims (user ID, role, expiration). The middleware reads the token from an httpOnly cookie (more secure than localStorage), validates the signature, checks expiration, and passes the claims to downstream handlers via context.

package middlewares

import (
    "context"
    "net/http"
    "os"

    "github.com/golang-jwt/jwt/v5"
)

type contextKey string
const UserClaimsKey contextKey = "userClaims"

func JWTMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Read token from httpOnly cookie (not from Authorization header)
        cookie, err := r.Cookie("auth_token")
        if err != nil {
            http.Error(w, "Unauthorized: no token", http.StatusUnauthorized)
            return
        }

        // Parse and validate the JWT
        secret := []byte(os.Getenv("JWT_SECRET"))
        token, err := jwt.Parse(cookie.Value, func(t *jwt.Token) (interface{}, error) {
            // Ensure the signing method is HMAC (prevent algorithm switching attack)
            if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
                return nil, fmt.Errorf("unexpected signing method")
            }
            return secret, nil
        })

        if err != nil || !token.Valid {
            http.Error(w, "Unauthorized: invalid token", http.StatusUnauthorized)
            return
        }

        // Extract claims and add to request context
        claims, ok := token.Claims.(jwt.MapClaims)
        if !ok {
            http.Error(w, "Unauthorized: invalid claims", http.StatusUnauthorized)
            return
        }

        // Pass claims downstream via context
        ctx := context.WithValue(r.Context(), UserClaimsKey, claims)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// In a handler, retrieve the claims:
func ProfileHandler(w http.ResponseWriter, r *http.Request) {
    claims := r.Context().Value(UserClaimsKey).(jwt.MapClaims)
    userID := claims["user_id"]  // extracted from the JWT
    fmt.Fprintf(w, "Hello user %v", userID)
}

// Express JWT Middleware (npm install jsonwebtoken)
const jwt = require('jsonwebtoken');

const authMiddleware = (req, res, next) => {
  // Read from httpOnly cookie (like Go's r.Cookie("auth_token"))
  const token = req.cookies?.auth_token;
  if (!token) return res.status(401).json({ error: 'No token' });

  try {
    // Verify signature + expiry (like Go's jwt.Parse with keyfunc)
    const claims = jwt.verify(token, process.env.JWT_SECRET, {
      algorithms: ['HS256'],  // Pin algorithm (like Go's SigningMethodHMAC check)
    });
    req.user = claims;    // Go: context.WithValue(ctx, UserClaimsKey, claims)
    next();
  } catch (err) {
    res.status(401).json({ error: 'Invalid token' });
  }
};

// Usage in handler:
app.get('/profile', authMiddleware, (req, res) => {
  const userId = req.user.user_id;  // Go: r.Context().Value(UserClaimsKey)
  res.json({ userId });
});

// Creating a JWT (sign):
const token = jwt.sign(
  { user_id: 42, role: 'admin' },
  process.env.JWT_SECRET,
  { expiresIn: '24h', algorithm: 'HS256' }
);

15 Password Hashing (Argon2)

Never store passwords in plain text. Argon2 is the winner of the 2015 Password Hashing Competition and is the recommended algorithm for password hashing. It's resistant to GPU/ASIC attacks because it requires significant memory, unlike bcrypt which is compute-bound only.

The pattern: generate a random salt, hash the password with Argon2id, store the salt+hash together. To verify, extract the salt, re-hash the input, and compare using constant-time comparison (to prevent timing attacks).

package utils

import (
    "crypto/rand"
    "crypto/subtle"
    "encoding/base64"
    "fmt"

    "golang.org/x/crypto/argon2"
)

const (
    argonTime    = 1       // Number of iterations
    argonMemory  = 64 * 1024  // 64 MB memory cost
    argonThreads = 4       // Parallelism factor
    argonKeyLen  = 32      // Output hash length
    saltLen      = 16      // Salt length in bytes
)

// HashPassword generates a salt and returns salt$hash (both base64)
func HashPassword(password string) (string, error) {
    // Generate a random salt
    salt := make([]byte, saltLen)
    if _, err := rand.Read(salt); err != nil {
        return "", err
    }

    // Hash with Argon2id (recommended variant)
    hash := argon2.IDKey([]byte(password), salt,
        argonTime, argonMemory, argonThreads, argonKeyLen)

    // Encode both as base64 and combine with $ separator
    saltB64 := base64.RawStdEncoding.EncodeToString(salt)
    hashB64 := base64.RawStdEncoding.EncodeToString(hash)

    return fmt.Sprintf("%s$%s", saltB64, hashB64), nil
}

// VerifyPassword checks a password against a stored hash
func VerifyPassword(password, stored string) bool {
    // Split stored value into salt and hash
    parts := strings.SplitN(stored, "$", 2)
    if len(parts) != 2 {
        return false
    }

    salt, _ := base64.RawStdEncoding.DecodeString(parts[0])
    expectedHash, _ := base64.RawStdEncoding.DecodeString(parts[1])

    // Re-hash the input with the same salt
    computedHash := argon2.IDKey([]byte(password), salt,
        argonTime, argonMemory, argonThreads, argonKeyLen)

    // Constant-time comparison prevents timing attacks
    return subtle.ConstantTimeCompare(expectedHash, computedHash) == 1
}

// Node.js — argon2 (npm install argon2)
const argon2 = require('argon2');

// Hash — argon2 handles salt generation internally
const hash = await argon2.hash(password, {
  type: argon2.argon2id,   // Like Go's argon2.IDKey (recommended variant)
  memoryCost: 65536,        // 64 MB (like Go's argonMemory = 64 * 1024)
  timeCost: 1,              // Like Go's argonTime = 1
  parallelism: 4,           // Like Go's argonThreads = 4
});
// Returns: "$argon2id$v=19$m=65536,t=1,p=4$salt$hash"

// Verify — constant-time comparison built in
const isValid = await argon2.verify(hash, password);
// Go: subtle.ConstantTimeCompare(expectedHash, computedHash) == 1

// --- bcrypt alternative (simpler, older, still acceptable) ---
const bcrypt = require('bcrypt');
const bcryptHash = await bcrypt.hash(password, 12);  // 12 rounds
const valid = await bcrypt.compare(password, bcryptHash);

16 Rate Limiting Middleware

Rate limiting prevents abuse by restricting how many requests a client can make in a given time window. This implementation tracks requests per IP address using a map protected by a mutex. A background goroutine periodically resets the counters.

package middlewares

import (
    "net/http"
    "sync"
    "time"
)

type visitor struct {
    count    int
    lastSeen time.Time
}

var (
    visitors = make(map[string]*visitor)
    mu       sync.Mutex
    rateLimit = 100  // Max requests per window
)

// Background goroutine: clean up stale entries every minute
func init() {
    go func() {
        for {
            time.Sleep(1 * time.Minute)
            mu.Lock()
            for ip, v := range visitors {
                if time.Since(v.lastSeen) > 3*time.Minute {
                    delete(visitors, ip)
                }
            }
            mu.Unlock()
        }
    }()
}

func RateLimiter(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ip := r.RemoteAddr

        mu.Lock()
        v, exists := visitors[ip]
        if !exists {
            visitors[ip] = &visitor{count: 1, lastSeen: time.Now()}
            mu.Unlock()
            next.ServeHTTP(w, r)
            return
        }

        // Reset count if window has passed
        if time.Since(v.lastSeen) > 1*time.Minute {
            v.count = 0
            v.lastSeen = time.Now()
        }

        v.count++
        if v.count > rateLimit {
            mu.Unlock()
            http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)
            return
        }
        mu.Unlock()

        next.ServeHTTP(w, r)
    })
}

// Express + express-rate-limit (npm install express-rate-limit)
const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 60 * 1000,      // 1 minute window (like Go's 1*time.Minute)
  max: 100,                  // 100 requests per window (like Go's rateLimit = 100)
  message: 'Rate limit exceeded',
  standardHeaders: true,    // Returns X-RateLimit-* headers
  legacyHeaders: false,
  keyGenerator: (req) => req.ip,  // Like Go's r.RemoteAddr
});
app.use(limiter);

// Stricter limit for login (like Go's per-route limiting):
const loginLimiter = rateLimit({ windowMs: 900000, max: 5 });
app.post('/login', loginLimiter, loginHandler);

17 Compression Middleware

Gzip compression can reduce response sizes by 70-90% for text-based content (JSON, HTML, CSS). The middleware checks if the client supports gzip (via Accept-Encoding header), wraps the response writer with a gzip writer, and sets the appropriate headers.

The key challenge is that you need a custom ResponseWriter that writes to the gzip stream instead of the raw connection.

package middlewares

import (
    "compress/gzip"
    "net/http"
    "strings"
)

// gzipResponseWriter wraps http.ResponseWriter to write through gzip
type gzipResponseWriter struct {
    http.ResponseWriter
    Writer *gzip.Writer
}

// Write sends data through the gzip compressor
func (grw *gzipResponseWriter) Write(b []byte) (int, error) {
    return grw.Writer.Write(b)
}

func Compression(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Check if client accepts gzip
        if !strings.Contains(r.Header.Get("Accept-Encoding"), "gzip") {
            next.ServeHTTP(w, r)
            return
        }

        // Set headers BEFORE writing any response
        w.Header().Set("Content-Encoding", "gzip")
        w.Header().Set("Vary", "Accept-Encoding")

        // Create gzip writer and wrap the ResponseWriter
        gz := gzip.NewWriter(w)
        defer gz.Close()  // Flush and close when handler returns

        grw := &gzipResponseWriter{ResponseWriter: w, Writer: gz}
        next.ServeHTTP(grw, r)  // Downstream writes go through gzip
    })
}

// Express + compression (npm install compression)
const compression = require('compression');

app.use(compression({
  level: 6,                   // Compression level (1=fast, 9=smallest)
  threshold: 1024,             // Don't compress below 1KB
  filter: (req, res) => {    // Skip already-compressed types
    if (req.headers['x-no-compression']) return false;
    return compression.filter(req, res);
  },
}));
// That's it! Handles Accept-Encoding, Vary header, Content-Encoding automatically

18 XSS Protection Middleware

XSS (Cross-Site Scripting) attacks inject malicious scripts into your application. This middleware sanitizes all JSON request bodies by recursively walking the parsed JSON structure and stripping dangerous HTML/JavaScript using the bluemonday library.

The key idea: parse the JSON body, recursively sanitize every string value, then re-encode the sanitized body and replace the original request body.

package middlewares

import (
    "bytes"
    "encoding/json"
    "io"
    "net/http"

    "github.com/microcosm-cc/bluemonday"
)

var policy = bluemonday.UGCPolicy()  // User-Generated Content policy

// sanitizeValue recursively sanitizes all strings in a JSON structure
func sanitizeValue(v interface{}) interface{} {
    switch val := v.(type) {
    case string:
        return policy.Sanitize(val)  // Strip dangerous HTML/JS
    case map[string]interface{}:
        for k, v := range val {
            val[k] = sanitizeValue(v)  // Recurse into objects
        }
        return val
    case []interface{}:
        for i, v := range val {
            val[i] = sanitizeValue(v)  // Recurse into arrays
        }
        return val
    default:
        return v  // Numbers, booleans, null — pass through
    }
}

func XSSMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Only process requests with JSON bodies
        if r.Body != nil && r.Header.Get("Content-Type") == "application/json" {
            body, err := io.ReadAll(r.Body)
            if err == nil && len(body) > 0 {
                var data interface{}
                if json.Unmarshal(body, &data) == nil {
                    sanitized := sanitizeValue(data)
                    clean, _ := json.Marshal(sanitized)
                    r.Body = io.NopCloser(bytes.NewReader(clean))
                } else {
                    // Not valid JSON — restore original body
                    r.Body = io.NopCloser(bytes.NewReader(body))
                }
            }
        }
        next.ServeHTTP(w, r)
    })
}

// Express + xss-clean or sanitize-html
const sanitizeHtml = require('sanitize-html');  // Like Go's bluemonday

// Middleware to sanitize all string fields in req.body
app.use((req, res, next) => {
  if (req.body && typeof req.body === 'object') {
    const sanitize = (obj) => {
      for (const key in obj) {
        if (typeof obj[key] === 'string') {
          obj[key] = sanitizeHtml(obj[key], {
            allowedTags: ['b', 'i', 'em', 'strong', 'a'],  // Like bluemonday.UGCPolicy()
            allowedAttributes: { a: ['href'] },
          });
        } else if (typeof obj[key] === 'object') {
          sanitize(obj[key]);  // Recurse (like Go's sanitizeValue)
        }
      }
    };
    sanitize(req.body);
  }
  next();
});

19 HPP Protection

HTTP Parameter Pollution (HPP) is an attack where the attacker sends duplicate query parameters to confuse your application. For example: /search?category=books&category=admin. Depending on how the server handles duplicates, this can bypass security filters or alter query logic.

This middleware keeps only the last value for each query parameter, preventing pollution. You can also configure a whitelist of parameters that are allowed to have multiple values (like tags or ids).

package middlewares

import (
    "net/http"
    "net/url"
)

// Parameters that are allowed to have multiple values
var allowedDuplicates = map[string]bool{
    "tags": true,
    "ids":  true,
}

func HPPProtection(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        query := r.URL.Query()
        clean := url.Values{}

        for key, values := range query {
            if allowedDuplicates[key] {
                clean[key] = values  // Keep all values for whitelisted params
            } else {
                // Keep only the last value for non-whitelisted params
                clean.Set(key, values[len(values)-1])
            }
        }

        r.URL.RawQuery = clean.Encode()
        next.ServeHTTP(w, r)
    })
}

// Express + hpp (npm install hpp)
const hpp = require('hpp');

app.use(hpp({
  whitelist: ['tags', 'ids'],  // Like Go's allowedDuplicates map
}));
// ?role=user&role=admin → req.query.role = "admin" (last value)
// ?tags=go&tags=node   → req.query.tags = ["go", "node"] (whitelisted)

// Without hpp — Express behavior by default:
// ?role=user&role=admin → req.query.role = ["user", "admin"] (array!)
// This is DIFFERENT from Go, where Query().Get() returns the FIRST value

20 Response Time Middleware

Tracking response time is essential for monitoring and debugging. This middleware records when the request started, lets the handler run, then calculates the elapsed time and adds it as a response header. You can also log slow requests for alerting.

package middlewares

import (
    "fmt"
    "log"
    "net/http"
    "time"
)

func ResponseTimeMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()

        // Run the actual handler
        next.ServeHTTP(w, r)

        // Calculate elapsed time
        duration := time.Since(start)

        // Add response time header (useful for debugging)
        w.Header().Set("X-Response-Time",
            fmt.Sprintf("%dms", duration.Milliseconds()))

        // Log slow requests (> 500ms)
        if duration > 500*time.Millisecond {
            log.Printf("SLOW REQUEST: %s %s took %v",
                r.Method, r.URL.Path, duration)
        }
    })
}

// Express + response-time (npm install response-time)
const responseTime = require('response-time');
app.use(responseTime());
// Automatically sets X-Response-Time: 12.345ms header

// Express + morgan for logging (npm install morgan)
const morgan = require('morgan');
app.use(morgan('dev'));  // Logs: GET /api/users 200 12.345 ms

// Manual version (same as Go's approach):
app.use((req, res, next) => {
  const start = Date.now();        // Go: time.Now()
  res.on('finish', () => {          // Go: code after next.ServeHTTP()
    const duration = Date.now() - start;
    if (duration > 500) {
      console.warn(`SLOW: ${req.method} ${req.url} ${duration}ms`);
    }
  });
  next();
});

21 Middleware Route Exclusion

Not every route needs every middleware. For example, your login and register endpoints shouldn't require JWT authentication, and your health check endpoint probably doesn't need rate limiting. This helper wraps a middleware and skips it for specified paths.

package utils

import (
    "net/http"
    "strings"
)

// MiddlewaresExcludePaths wraps a middleware to skip it for certain paths
func MiddlewaresExcludePaths(mw Middleware, excludePaths ...string) Middleware {
    return func(next http.Handler) http.Handler {
        // Apply the middleware to the handler
        wrapped := mw(next)

        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // Check if current path should be excluded
            for _, path := range excludePaths {
                if strings.HasPrefix(r.URL.Path, path) {
                    next.ServeHTTP(w, r)  // Skip middleware
                    return
                }
            }
            wrapped.ServeHTTP(w, r)  // Apply middleware
        })
    }
}

// Usage: JWT middleware skips login and register routes
jwtMiddleware := utils.MiddlewaresExcludePaths(
    mw.JWTMiddleware,
    "/auth/login",
    "/auth/register",
    "/health",
)

// Express — Method 1: express-unless (npm install express-unless)
const unless = require('express-unless');

const authMiddleware = (req, res, next) => { /* JWT logic */ };
authMiddleware.unless = unless;

app.use(authMiddleware.unless({
  path: ['/auth/login', '/auth/register', '/health'],
  // Same paths Go's MiddlewaresExcludePaths skips!
}));

// Express — Method 2: Per-route middleware (cleaner, no package needed)
// Public routes — no auth
app.post('/auth/login', loginHandler);
app.post('/auth/register', registerHandler);
app.get('/health', healthHandler);

// Protected routes — auth middleware applied per-route
app.get('/api/users', authMiddleware, usersHandler);
app.get('/api/profile', authMiddleware, profileHandler);

// Express — Method 3: Route groups (most common in Express)
const protectedRouter = express.Router();
protectedRouter.use(authMiddleware);  // Applied to all routes in this group
protectedRouter.get('/profile', profileHandler);
protectedRouter.get('/settings', settingsHandler);
app.use('/api', protectedRouter);

const publicRouter = express.Router();  // No auth middleware
publicRouter.post('/login', loginHandler);
app.use('/auth', publicRouter);

22 Utility Functions

These are the helper functions that keep your handlers clean. Instead of repeating SQL generation, error handling, and reflection logic in every handler, extract them into reusable utilities.

GenerateInsertQuery

Dynamically builds an INSERT SQL query from a struct, using reflection to read struct tags.

// GenerateInsertQuery builds "INSERT INTO table (col1, col2) VALUES (?, ?)"
// from any struct using its `db` tags
func GenerateInsertQuery(table string, model interface{}) string {
    t := reflect.TypeOf(model)
    v := reflect.ValueOf(model)

    var columns []string
    var placeholders []string

    for i := 0; i < t.NumField(); i++ {
        field := t.Field(i)
        value := v.Field(i)

        // Skip zero-value fields and ID (auto-increment)
        if value.IsZero() { continue }

        dbTag := field.Tag.Get("db")
        column := strings.Split(dbTag, ",")[0]
        if column == "id" { continue }

        columns = append(columns, column)
        placeholders = append(placeholders, "?")
    }

    return fmt.Sprintf("INSERT INTO %s (%s) VALUES (%s)",
        table,
        strings.Join(columns, ", "),
        strings.Join(placeholders, ", "),
    )
}

GetStructValues (Reflection-based)

// GetStructValues extracts non-zero field values from a struct
// Returns values in the same order as GenerateInsertQuery columns
func GetStructValues(model interface{}) []interface{} {
    v := reflect.ValueOf(model)
    t := reflect.TypeOf(model)

    var values []interface{}
    for i := 0; i < v.NumField(); i++ {
        field := v.Field(i)
        dbTag := t.Field(i).Tag.Get("db")
        column := strings.Split(dbTag, ",")[0]

        if !field.IsZero() && column != "id" {
            values = append(values, field.Interface())
        }
    }
    return values
}

AddSorting & AddFilters

// AddSorting appends ORDER BY to a query from ?sort=name&order=desc
func AddSorting(query string, r *http.Request, allowedColumns map[string]bool) string {
    sortBy := r.URL.Query().Get("sort")
    order := r.URL.Query().Get("order")

    // Whitelist columns to prevent SQL injection
    if allowedColumns[sortBy] {
        if order != "desc" { order = "asc" }
        query += fmt.Sprintf(" ORDER BY %s %s", sortBy, order)
    }
    return query
}

// AddFilters appends WHERE clauses from query parameters
func AddFilters(query string, r *http.Request,
    allowedFilters map[string]string) (string, []interface{}) {

    var conditions []string
    var values []interface{}

    for param, column := range allowedFilters {
        if val := r.URL.Query().Get(param); val != "" {
            conditions = append(conditions, column+" = ?")
            values = append(values, val)
        }
    }

    if len(conditions) > 0 {
        query += " WHERE " + strings.Join(conditions, " AND ")
    }
    return query, values
}

ErrorHandler

// ErrorHandler sends a consistent JSON error response
func ErrorHandler(w http.ResponseWriter, status int, message string) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(map[string]string{
        "error":   http.StatusText(status),
        "message": message,
    })
}

// AuthorizeUser checks if the JWT user matches the requested resource
func AuthorizeUser(r *http.Request, resourceOwnerID int) bool {
    claims := r.Context().Value(UserClaimsKey).(jwt.MapClaims)
    userID := int(claims["user_id"].(float64))
    return userID == resourceOwnerID
}

// --- JSON Response Helper (like Go's ErrorHandler) ---
// In Express, res.json() and res.status() are built in!
const sendError = (res, status, message) => {
  res.status(status).json({
    error: http.STATUS_CODES[status],  // Like Go's http.StatusText(status)
    message,
  });
};

// --- Dynamic INSERT (Go uses reflect; Node uses Object.keys!) ---
const generateInsert = (table, model) => {
  const keys = Object.keys(model).filter(k => k !== 'id' && model[k] != null);
  const columns = keys.join(', ');
  const placeholders = keys.map(() => '?').join(', ');
  const values = keys.map(k => model[k]);
  return { sql: `INSERT INTO ${table} (${columns}) VALUES (${placeholders})`, values };
  // No reflect needed! JS objects are introspectable by default
};

// --- Sorting (like Go's AddSorting) ---
const addSorting = (query, reqQuery, allowedColumns) => {
  const { sort, order = 'asc' } = reqQuery;
  if (sort && allowedColumns.includes(sort)) {
    query += ` ORDER BY ${sort} ${order === 'desc' ? 'desc' : 'asc'}`;
  }
  return query;
};

23 Protocol Buffers

Protocol Buffers (protobuf) is Google's language-neutral, platform-neutral mechanism for serializing structured data. Think of it as JSON, but binary, smaller, faster, and with a strict schema. You define your data structures in .proto files, then the protoc compiler generates Go code (structs and methods) automatically.

Protobuf is the foundation of gRPC. While REST APIs use JSON over HTTP, gRPC uses protobuf over HTTP/2 for much better performance.

.proto File Syntax

// calculator.proto
syntax = "proto3";         // Use proto3 syntax (latest)
package calculator;         // Package namespace
option go_package = "/proto/gen;mainpb";  // Go package path

// Service defines the RPC methods
service Calculate {
    rpc Add (AddRequest) returns (AddResponse);
}

// Messages define the data structures
message AddRequest {
    int32 a = 1;  // Field number 1 (not value — used for binary encoding)
    int32 b = 2;  // Field number 2
}

message AddResponse {
    int32 sum = 1;
}

Generating Go Code

# Install the protoc compiler and Go plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Generate Go code from .proto file
protoc --go_out=. --go-grpc_out=. calculator.proto

# This generates:
#   calculator.pb.go       — message structs (AddRequest, AddResponse)
#   calculator_grpc.pb.go  — service interface & client stub

Common Protobuf Types

// Node.js — protobuf with @grpc/proto-loader (dynamic loading)
const protoLoader = require('@grpc/proto-loader');
const grpc = require('@grpc/grpc-js');

const packageDef = protoLoader.loadSync('calculator.proto');
const proto = grpc.loadPackageDefinition(packageDef);
// proto.calculator.Calculate — service definition

// Node.js — protobuf with protobufjs (static generation)
// npx pbjs -t static-module -w commonjs -o proto.js calculator.proto
const { calculator } = require('./proto.js');
const msg = calculator.AddRequest.create({ a: 10, b: 20 });
const buffer = calculator.AddRequest.encode(msg).finish();
// buffer is the same binary wire format as Go's proto.Marshal()

// JSON equivalent for comparison:
// JSON: {"a": 10, "b": 20}              → ~18 bytes (text)
// Protobuf: 0x08 0x0A 0x10 0x14         → 4 bytes (binary!)

24 gRPC Server

gRPC is a high-performance RPC framework that uses HTTP/2 for transport and Protocol Buffers for serialization. Unlike REST where you manually serialize/deserialize JSON and define URL patterns, gRPC generates the entire client-server boilerplate from your .proto file. You just implement the business logic.

package main

import (
    "context"
    "crypto/tls"
    "log"
    "net"

    pb "myapp/proto/gen"  // Import generated protobuf code

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
)

// Server implements the Calculate service interface
type Server struct {
    pb.UnimplementedCalculateServer  // Embed for forward compatibility
}

// Add implements the Add RPC method
func (s *Server) Add(ctx context.Context, req *pb.AddRequest) (*pb.AddResponse, error) {
    sum := req.GetA() + req.GetB()
    return &pb.AddResponse{Sum: sum}, nil
}

func main() {
    // Load TLS certificate
    creds, err := credentials.NewServerTLSFromFile("cert.pem", "key.pem")
    if err != nil {
        log.Fatalf("Failed to load TLS: %v", err)
    }

    // Create gRPC server with TLS
    grpcServer := grpc.NewServer(grpc.Creds(creds))

    // Register our service implementation
    pb.RegisterCalculateServer(grpcServer, &Server{})

    // Listen on TCP port
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("Failed to listen: %v", err)
    }

    log.Println("gRPC server listening on :50051")
    if err := grpcServer.Serve(lis); err != nil {
        log.Fatalf("Server failed: %v", err)
    }
}

// Node.js gRPC Server (@grpc/grpc-js + @grpc/proto-loader)
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const packageDef = protoLoader.loadSync('calculator.proto');
const proto = grpc.loadPackageDefinition(packageDef);

// Implement the Add RPC (like Go's func (s *Server) Add(...))
const server = new grpc.Server();
server.addService(proto.calculator.Calculate.service, {
  Add: (call, callback) => {
    const sum = call.request.a + call.request.b;
    callback(null, { sum });
    // Go: return &pb.AddResponse{Sum: sum}, nil
  },
});

// Start server (like Go's grpcServer.Serve(lis))
server.bindAsync(
  '0.0.0.0:50051',
  grpc.ServerCredentials.createInsecure(),
  (err, port) => {
    console.log(`gRPC server on :${port}`);
  }
);

25 gRPC Client

The gRPC client is auto-generated from the same .proto file. You create a connection, get a typed client stub, and call methods as if they were local function calls. The serialization, HTTP/2 framing, and error handling are all handled by the framework.

package main

import (
    "context"
    "log"
    "time"

    pb "myapp/proto/gen"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

func main() {
    // Load TLS credentials
    creds, err := credentials.NewClientTLSFromFile("cert.pem", "")
    if err != nil {
        log.Fatalf("Failed to load TLS: %v", err)
    }

    // Connect to gRPC server
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(creds))
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()

    // Create a typed client stub
    client := pb.NewCalculateClient(conn)

    // Add metadata (like HTTP headers)
    md := metadata.New(map[string]string{
        "authorization": "Bearer my-token",
    })
    ctx := metadata.NewOutgoingContext(context.Background(), md)

    // Set a timeout
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    // Call the Add RPC — looks like a local function call!
    resp, err := client.Add(ctx, &pb.AddRequest{A: 10, B: 20})
    if err != nil {
        log.Fatalf("RPC failed: %v", err)
    }

    log.Printf("10 + 20 = %d", resp.GetSum())  // Output: 10 + 20 = 30
}

// Node.js gRPC Client
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const packageDef = protoLoader.loadSync('calculator.proto');
const proto = grpc.loadPackageDefinition(packageDef);

// Create client (like Go's grpc.Dial + pb.NewCalculateClient)
const client = new proto.calculator.Calculate(
  'localhost:50051',
  grpc.credentials.createInsecure()
);

// Call the RPC — callback-style (traditional Node)
client.Add({ a: 10, b: 20 }, (err, response) => {
  if (err) throw err;
  console.log(`10 + 20 = ${response.sum}`);
});

// With promisify (modern async/await style):
const { promisify } = require('util');
const addAsync = promisify(client.Add).bind(client);
const resp = await addAsync({ a: 10, b: 20 });
// Go: resp, err := client.Add(ctx, &pb.AddRequest{A: 10, B: 20})

// Metadata (like Go's gRPC metadata)
const metadata = new grpc.Metadata();
metadata.add('authorization', 'Bearer my-token');
client.Add({ a: 10, b: 20 }, metadata, callback);

26 gRPC Streaming

gRPC supports four communication patterns. Unary (request-response) is the simplest. But gRPC's real power comes from its three streaming modes: server-side, client-side, and bidirectional. Streaming is ideal for real-time data, large file transfers, and chat applications.

Proto Definitions for Streaming

service StreamService {
    // Server-side streaming: client sends one request, server sends many responses
    rpc Fibonacci (FibRequest) returns (stream FibResponse);

    // Client-side streaming: client sends many requests, server sends one response
    rpc SendNumbers (stream NumberRequest) returns (SumResponse);

    // Bidirectional streaming: both sides send streams simultaneously
    rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

message FibRequest { int32 count = 1; }
message FibResponse { int64 value = 1; }
message NumberRequest { int32 number = 1; }
message SumResponse { int64 total = 1; }
message ChatMessage { string user = 1; string text = 2; }

Server-Side Streaming (Fibonacci)

The server sends multiple responses for a single request. The client reads from the stream until it receives an EOF (End of File) signal.

// Server implementation: sends N Fibonacci numbers
func (s *Server) Fibonacci(req *pb.FibRequest, stream pb.StreamService_FibonacciServer) error {
    a, b := int64(0), int64(1)
    for i := int32(0); i < req.GetCount(); i++ {
        // Send each number as a separate message
        if err := stream.Send(&pb.FibResponse{Value: a}); err != nil {
            return err
        }
        a, b = b, a+b
    }
    return nil  // Returning nil closes the stream
}

// Client: reads the stream
stream, err := client.Fibonacci(ctx, &pb.FibRequest{Count: 10})
for {
    resp, err := stream.Recv()
    if err == io.EOF {
        break  // Server closed the stream
    }
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.GetValue())
}

Client-Side Streaming (SendNumbers)

The client sends multiple messages, and the server responds once after the client finishes.

// Server: receives numbers and returns the sum
func (s *Server) SendNumbers(stream pb.StreamService_SendNumbersServer) error {
    var total int64
    for {
        req, err := stream.Recv()
        if err == io.EOF {
            // Client finished sending — return the result
            return stream.SendAndClose(&pb.SumResponse{Total: total})
        }
        if err != nil {
            return err
        }
        total += int64(req.GetNumber())
    }
}

// Client: sends numbers one by one
stream, _ := client.SendNumbers(ctx)
for _, n := range []int32{1, 2, 3, 4, 5} {
    stream.Send(&pb.NumberRequest{Number: n})
}
resp, _ := stream.CloseAndRecv()
fmt.Println("Sum:", resp.GetTotal())  // 15

Bidirectional Streaming (Chat)

Both sides send and receive simultaneously. This is ideal for chat, gaming, and real-time collaboration.

// Server: echoes messages back with a prefix
func (s *Server) Chat(stream pb.StreamService_ChatServer) error {
    for {
        msg, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }

        // Echo back with modification
        reply := &pb.ChatMessage{
            User: "server",
            Text: fmt.Sprintf("Echo: %s", msg.GetText()),
        }
        if err := stream.Send(reply); err != nil {
            return err
        }
    }
}

// Client: send and receive concurrently using goroutines
stream, _ := client.Chat(ctx)

// Goroutine to receive messages
go func() {
    for {
        msg, err := stream.Recv()
        if err == io.EOF { return }
        fmt.Printf("[%s]: %s\n", msg.GetUser(), msg.GetText())
    }
}()

// Send messages from main goroutine
messages := []string{"Hello", "How are you?", "Goodbye"}
for _, text := range messages {
    stream.Send(&pb.ChatMessage{User: "client", Text: text})
}
stream.CloseSend()

// --- Node.js Server-Side Streaming ---
// Server implementation:
Fibonacci: (call) => {
  let a = 0, b = 1;
  for (let i = 0; i < call.request.count; i++) {
    call.write({ value: a });  // Go: stream.Send(&pb.FibResponse{...})
    [a, b] = [b, a + b];
  }
  call.end();                  // Go: return nil (closes stream)
}

// Client reads stream:
const call = client.Fibonacci({ count: 10 });
call.on('data', (resp) => console.log(resp.value));
call.on('end', () => console.log('done'));
// Go: for { resp, err := stream.Recv(); if err == io.EOF { break } }

// --- Node.js Bidirectional Streaming (Chat) ---
const call = client.Chat();
call.on('data', (msg) => {
  console.log(`[${msg.user}]: ${msg.text}`);
});
call.write({ user: 'client', text: 'Hello' });
call.write({ user: 'client', text: 'Goodbye' });
call.end();  // Go: stream.CloseSend()

27 gRPC Gateway

Sometimes you need both gRPC and REST on the same server. The grpc-gateway project generates a reverse proxy that translates RESTful JSON API calls into gRPC calls. This lets you serve gRPC clients (internal microservices) and REST clients (web browsers, mobile apps) from the same backend.

How It Works

You annotate your .proto file with HTTP rules, then protoc generates a REST proxy that forwards requests to your gRPC server.

import "google/api/annotations.proto";

service Calculate {
    rpc Add (AddRequest) returns (AddResponse) {
        option (google.api.http) = {
            post: "/v1/add"
            body: "*"
        };
    }
}

Running gRPC + REST Together

package main

import (
    "context"
    "log"
    "net"
    "net/http"

    "github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"

    pb "myapp/proto/gen"
)

func main() {
    // 1. Start gRPC server on port 50051
    go func() {
        lis, _ := net.Listen("tcp", ":50051")
        grpcServer := grpc.NewServer()
        pb.RegisterCalculateServer(grpcServer, &Server{})
        log.Println("gRPC server on :50051")
        grpcServer.Serve(lis)
    }()

    // 2. Start REST gateway on port 8080
    ctx := context.Background()
    mux := runtime.NewServeMux()

    // Connect the gateway to the gRPC server
    opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}
    err := pb.RegisterCalculateHandlerFromEndpoint(ctx, mux, "localhost:50051", opts)
    if err != nil {
        log.Fatal(err)
    }

    log.Println("REST gateway on :8080")
    http.ListenAndServe(":8080", mux)

    // Now both work:
    // gRPC:  client.Add(ctx, &AddRequest{A: 10, B: 20})
    // REST:  POST http://localhost:8080/v1/add {"a": 10, "b": 20}
}

// Node.js alternatives to grpc-gateway:

// 1. grpc-web — browser-compatible gRPC (Envoy proxy translates)
//    npm install @improbable-eng/grpc-web
//    Browser → Envoy (HTTP/1.1→HTTP/2 proxy) → gRPC Server

// 2. Connect-Web (connectrpc.com) — modern, browser-native gRPC
//    Works directly from browser without Envoy proxy
//    Server speaks gRPC + Connect + gRPC-Web all on one port

// 3. Manual REST wrapper (most common in Node):
const express = require('express');
const app = express();

// REST endpoint that calls the gRPC service internally
app.post('/v1/add', async (req, res) => {
  const { a, b } = req.body;
  // Call gRPC service
  grpcClient.Add({ a, b }, (err, response) => {
    if (err) return res.status(500).json({ error: err.message });
    res.json(response);  // {sum: 30}
  });
});

// 4. NestJS with gRPC — framework that supports both natively:
// @GrpcMethod('Calculate', 'Add')
// add(data: AddRequest): AddResponse {
//   return { sum: data.a + data.b };
// }

28 Go vs Node.js

Both Go and Node.js are popular for building web servers, but they take fundamentally different approaches. Go compiles to a single binary with built-in concurrency. Node.js runs on V8 with an event loop and requires external packages for most functionality. Let's compare them head-to-head.

HTTP Server Comparison

Go — net/http (standard library)

package main

import (
    "fmt"
    "net/http"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello from Go!")
    })
    http.ListenAndServe(":8080", nil)
}
// Build: go build -o server . (single binary, ~6MB)
// Deploy: copy binary to server, run it. Done.

Node.js — Native http module

const http = require('http');

http.createServer((req, res) => {
    res.end('Hello from Node!');
}).listen(8080);
// Requires: Node.js runtime installed
// No routing, no middleware — need Express/Fastify

Node.js — Express (most popular framework)

const express = require('express');
const app = express();

app.get('/', (req, res) => {
    res.send('Hello from Express!');
});
app.listen(8080);
// Requires: npm install express + node_modules (~30MB)

Key Differences

Concurrency: Goroutines vs Event Loop

This is the fundamental difference. Go creates a new goroutine for each request automatically. Node.js processes all requests on a single thread with callbacks.

// Go: Each request runs in its own goroutine automatically
// 10,000 concurrent requests = 10,000 goroutines (~20KB each = ~200MB)
// CPU-heavy work in one goroutine doesn't block others

http.HandleFunc("/heavy", func(w http.ResponseWriter, r *http.Request) {
    // This runs in its own goroutine — doesn't block other requests
    result := heavyComputation()
    fmt.Fprintln(w, result)
})