skill.md described only the hosted cloud. An outside adopter's agents vendored it and had to note that its paid-cloud commands did not apply, and the local lines it did carry did not work: `hanzo up cloud` forwards to `hanzo host serve`, which needs a cloud binary it does not build, and `brew install hanzoai/tap/hanzo` installs CLI 1.9.57 against 8.5.158. "On your own machine" gives one start command each for Base, the cloud, zip, the MCP server and the engine, each run against current main or the published package, and lists what only the hosted cloud has. cloud-host starts from the command that runs and says what `hanzo host serve`, `hanzo host start` and `hanzo up` expect. app-port and the Go coursework point at the same commands instead of an invented compose file; llms.txt opens with the entry, and the site's lede no longer promises a complete local copy. Two README commands fail on main, so these pages do not use them: the cloud's `make dev` stops with `cek: this build cannot encrypt a store`, and Base's `go install .../examples/base@latest` is refused for its replace directive. public/ is regenerated with HIPs from hanzoai/hips main (0eedbe1). The last build read a working tree, so it served uncommitted HIP edits and six HIPs that are not on main (1191-1195, 1329); those leave the index, and their pages stay where they were. Co-authored-by: Hanzo Dev <[email protected]>
9.8 KiB
Coursework: Fullstack Cloud Engineering with Go & Hanzo Base
Category: Hanzo Ecosystem & Engineering Curriculum
Level: Intermediate to Advanced
Prerequisites: Familiarity with web services, basic understanding of concurrency.
Related Skills: hanzo/hanzo-migrate-backend-to-go.md, hanzo/hanzo-base.md, hanzo/hanzo-cloud.md, hanzo/hanzo-tutorial-realtime-sse-backend.md, hanzo/hanzo-examples-native-cloud.md
Curriculum Overview
This coursework trains engineering teams migrating from slow, interpreted, memory-heavy environments (Python, Next.js, Node.js, Ruby on Rails) to Hanzo's high-performance native stack (Go, Rust, C++).
┌─────────────────────────────────────────────────────────────────────────────┐
│ CURRICULUM: FULLSTACK CLOUD ENGINEERING WITH GO │
│ │
│ [MODULE 1] Architectural Foundations & Runtime Shift │
│ - Why native compiled code wins: Go, Rust & C++ │
│ - Benchmarking: 15ms cold starts vs 6s Next.js SSR │
│ │
│ [MODULE 2] Running Your Own Cloud Locally │
│ - Base and the open-source cloud, from a checkout │
│ - start commands: skill.md, On your own machine │
│ │
│ [MODULE 3] Realtime SSE Streaming & State Synchronization │
│ - Native Server-Sent Events (SSE) in Go │
│ - Zero-overhead streaming without Pusher / external SaaS │
│ │
│ [MODULE 4] Extending Hanzo Cloud with `/v1/*` Subsystems │
│ - Plugin host architecture & ZAP binary transport (HIP-0114) │
│ - Wiring routes in `manifest/apps.go` │
│ │
│ [MODULE 5] Production Observability, Storage & Deployment │
│ - Embedded SQLite + ClickHouse datastore hybrid │
│ - Zero-dependency static binary deployments (`CGO_ENABLED=0`) │
└─────────────────────────────────────────────────────────────────────────────┘
Module 1: The Runtime Shift (Python/Next.js to Native Go)
1.1 The Cost of Interpreted Runtimes
Interpreted runtimes impose hidden taxes in enterprise environments:
- Python: The Global Interpreter Lock (GIL) serializes threads; async runtimes (
asyncio) suffer from event-loop starvation and heavy memory fragmentation. - Node.js / Next.js: Gigabytes of
node_modules, cold start latencies (1.5s - 8s), high idle footprint (250MB+ per SSR container), and fragile build tooling. - Java / Spring: High JVM memory overhead and slow warmup periods.
1.2 The Hanzo Triad
- Go (
github.com/hanzoai/base,github.com/hanzoai/cloud):- Compiles to a single static binary (
CGO_ENABLED=0). - Memory footprint: ~15MB idle.
- Concurrency: Goroutines scheduled on
M:Nruntime with non-blocking network pollers.
- Compiles to a single static binary (
- Rust (
hanzoai/engine,hanzoai/reth):- Zero-cost abstractions, deterministic memory safety without GC pauses.
- Inference execution and cryptographic settlement.
- C++ (Metal, CUDA, ANE):
- Bare-metal hardware kernels for Apple Silicon and NVIDIA tensor cores.
1.3 Lab 1: Profiling Memory & Cold Starts
Compare a basic Next.js / FastAPI endpoint against a Go Hanzo Base endpoint:
# Build Go binary statically
CGO_ENABLED=0 go build -ldflags="-s -w" -o ./bin/server ./main.go
# Inspect size and launch time
ls -lh ./bin/server
time ./bin/server --healthcheck
Expected Result: Binary size < 25MB, startup time < 15 milliseconds.
Module 2: Run It Locally
Base and the open-source cloud start from a checkout, with no account.
The Philosophy
Never mock third-party cloud APIs. Run the actual Hanzo services in-process.
Lab 2: Launch & Healthcheck
# Base, in a checkout of github.com/hanzoai/base
go run ./examples/base serve
curl -i http://127.0.0.1:8090/v1/health # from a second terminal
# the cloud, in a checkout of github.com/hanzoai/cloud
make build && CLOUD_DEV_UNENCRYPTED=1 CLOUD_LISTEN=127.0.0.1:8080 CLOUD_DATA_DIR=.dev/data ./cloud
curl -s http://127.0.0.1:8080/v1/openapi.json # from a second terminal
The cloud runs unencrypted this way, for local development only. Every part that
runs locally, and what needs the hosted cloud, is in skill.md under
On your own machine.
Module 3: Realtime Native SSE (Server-Sent Events)
3.1 Why Native SSE Over WebSockets?
- Built directly on HTTP/1.1 and HTTP/2 (RFC 8895).
- Automatic browser reconnection via
Last-Event-ID. - Zero firewall or proxy websocket-upgrade friction.
- Efficient unidirectional event delivery for LLM tokens, notifications, and analytics.
3.2 Implementing the Hub in Go
A lock-free, concurrent SSE multiplexer:
package realtime
import (
"fmt"
"net/http"
"sync"
"time"
)
type Event struct {
ID string
Event string
Data []byte
}
type Hub struct {
mu sync.RWMutex
clients map[chan Event]struct{}
}
func NewHub() *Hub {
return &Hub{
clients: make(map[chan Event]struct{}),
}
}
func (h *Hub) Subscribe() chan Event {
ch := make(chan Event, 64)
h.mu.Lock()
h.clients[ch] = struct{}{}
h.mu.Unlock()
return ch
}
func (h *Hub) Unsubscribe(ch chan Event) {
h.mu.Lock()
delete(h.clients, ch)
close(ch)
h.mu.Unlock()
}
func (h *Hub) Broadcast(e Event) {
h.mu.RLock()
defer h.mu.RUnlock()
for ch := range h.clients {
select {
case ch <- e:
default:
// Client channel full; drop or handle slow consumer
}
}
}
func (h *Hub) Handler() http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
flusher, ok := w.(http.Flusher)
if !ok {
http.Error(w, "Streaming unsupported", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "text/event-stream")
w.Header().Set("Cache-Control", "no-cache")
w.Header().Set("Connection", "keep-alive")
w.Header().Set("X-Accel-Buffering", "no")
ch := h.Subscribe()
defer h.Unsubscribe(ch)
ticker := time.NewTicker(15 * time.Second)
defer ticker.Stop()
for {
select {
case <-r.Context().Done():
return
case <-ticker.C:
fmt.Fprintf(w, ": heartbeat\n\n")
flusher.Flush()
case e := <-ch:
if e.ID != "" {
fmt.Fprintf(w, "id: %s\n", e.ID)
}
if e.Event != "" {
fmt.Fprintf(w, "event: %s\n", e.Event)
}
fmt.Fprintf(w, "data: %s\n\n", e.Data)
flusher.Flush()
}
}
}
}
3.3 Lab 3: Verifying SSE Streams with cURL
# Listen to live stream
curl -N http://localhost:8090/v1/events/stream
Module 4: Extending Hanzo Cloud with /v1/* Subsystems
Hanzo Cloud (hanzoai/cloud) uses a host + plugin registry architecture connected via ZAP Transport (HIP-0114).
4.1 Subsystem Interface
Every subsystem implements cloud.Plugin:
package custom
import (
"net/http"
"github.com/hanzoai/cloud"
)
func init() {
cloud.Register("analytics-custom", NewPlugin)
}
type Plugin struct{}
func NewPlugin(cfg *cloud.Config) (cloud.Plugin, error) {
return &Plugin{}, nil
}
func (p *Plugin) Mount(mux *http.ServeMux) {
mux.HandleFunc("POST /v1/custom/ingest", p.HandleIngest)
mux.HandleFunc("GET /v1/custom/stats", p.HandleStats)
}
func (p *Plugin) HandleIngest(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusAccepted)
w.Write([]byte(`{"status":"queued"}`))
}
func (p *Plugin) HandleStats(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.Write([]byte(`{"active_workers":16,"throughput_per_sec":124000}`))
}
Module 5: Storage & Observability
5.1 Hybrid Storage
- Transactional State: Embedded SQLite (
modernc.org/sqlite) for single-binary zero-dependency nodes or PostgreSQL (pgx/v5). - Telemetry & Logs: Columnar ClickHouse datastore.
5.2 Test-Driven Development (TDD)
Every module must ship with automated tests proving correctness:
// hub_test.go
package realtime_test
import (
"context"
"net/http"
"net/http/httptest"
"testing"
"time"
"github.com/hanzoai/base/realtime"
)
func TestSSEHub(t *testing.T) {
hub := realtime.NewHub()
server := httptest.NewServer(hub.Handler())
defer server.Close()
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, "GET", server.URL, nil)
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatalf("Failed to connect to SSE stream: %v", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
t.Errorf("Expected status 200, got %d", resp.StatusCode)
}
if ct := resp.Header.Get("Content-Type"); ct != "text/event-stream" {
t.Errorf("Expected Content-Type text/event-stream, got %s", ct)
}
}
Conclusion & Certification
By completing this coursework, your engineering team possesses the patterns, tooling, and architectural foundation to:
- Eliminate legacy interpreted runtimes in favor of compiled Go and Rust.
- Build and run offline-ready local cloud environments.
- Stream realtime data natively via SSE.
- Scale seamlessly against Hanzo AI Cloud (
hanzo.aiandapi.hanzo.ai).