echo

Comprehensive patterns for building production Go web servers with Echo framework.

Core Structural Invariants

1. Context envelope — echo.Context wraps request/response for the entire lifecycle
2. Middleware chain — Composable interceptors with next(c) pass-through; each must call next(c) unless short-circuiting
3. Protocol abstraction — HTTP/1.1, HTTP/2, WebSocket, SSE share a unified interface
4. Graceful degradation — Features check capability and fall back (e.g., HTTP/2 push)
5. Orthogonal features — TLS, auth, routing, proxying are independent layers

---

Quick Decision Matrix

| Need | Pattern | Reference | |------|---------|-----------| | REST API | CRUD handlers + JSON binding | references/examples/cookbook-crud.md | | Real-time updates | SSE (server-push) | references/examples/cookbook-sse.md | | Bidirectional real-time | WebSocket | references/examples/cookbook-websocket.md | | Auth | JWT middleware | references/examples/cookbook-jwt.md | | File upload | FormFile/MultipartForm | references/examples/cookbook-file-upload.md | | File download | Attachment/Inline | references/examples/cookbook-file-download.md | | TLS production | Auto TLS (Let's Encrypt) | references/examples/cookbook-auto-tls.md | | TLS dev | Manual cert + HTTP/2 | references/examples/cookbook-http2.md | | Proxy/LB | Proxy middleware | references/examples/cookbook-reverse-proxy.md | | Production shutdown | Graceful shutdown + context timeout | references/examples/cookbook-graceful-shutdown.md | | Chunked response | Streaming + Flush | references/examples/cookbook-streaming-response.md | | Embedded assets | //go:embed + http.FS | references/examples/cookbook-embed-resources.md |

---

Reference Index

Cookbooks (working examples)

• Core patterns with code → references/examples/core-patterns.md
• Individual recipes → references/examples/cookbook-*.md

Framework Guides (API reference)

• Routing, binding, request/response, error handling → references/api/guide-*.md

Middleware

• Built-in and community middleware → references/patterns/middleware-*.md

---

Execution Checklist

When implementing an Echo server:

1. Define protocol → HTTP/1.1, HTTP/2, WebSocket, SSE
2. Security layer → TLS config, CORS, JWT if needed
3. Middleware chain order → Logger → Recover → Auth → Custom
4. Route structure → Group by resource or subdomain
5. Error handling → Custom HTTPErrorHandler if needed
6. Graceful shutdown → Signal handling + context timeout
7. Testing → httptest.NewRecorder() for unit tests
8. Deployment → Reverse proxy (Nginx) or standalone with Auto TLS

---

Common Pitfalls

Middleware Order Matters

Logger must come before Recover so all requests are logged, including recovered panics.

Context Goroutine Safety

echo.Context is not goroutine-safe. Copy values before launching goroutines.

SSE Flushing

Must call w.Flush() after each write. Monitor c.Request().Context().Done() for client disconnect.

WebSocket Lifecycle

Handler owns the connection loop after upgrade. Must manage cleanup with defer ws.Close().

---

When Echo Fits

• Need HTTP/2, WebSocket, SSE out of the box
• Want minimalist routing without reflection magic
• Prefer explicit middleware chains over implicit globals
• Building microservices or API gateways

When to Consider Alternatives

• Need built-in ORM → Gin + GORM
• Want opinionated MVC structure → Beego
• Require extensive plugin ecosystem → Fiber