Files
skills/public/hanzo-coursework-fullstack-go-cloud.md
zeekayandHanzo Dev dc9194a5ac Say what runs locally, with a start command that works
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]>
2026-09-11 10:36:35 -07:00

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

  1. 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:N runtime with non-blocking network pollers.
  2. Rust (hanzoai/engine, hanzoai/reth):
    • Zero-cost abstractions, deterministic memory safety without GC pauses.
    • Inference execution and cryptographic settlement.
  3. 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:

  1. Eliminate legacy interpreted runtimes in favor of compiled Go and Rust.
  2. Build and run offline-ready local cloud environments.
  3. Stream realtime data natively via SSE.
  4. Scale seamlessly against Hanzo AI Cloud (hanzo.ai and api.hanzo.ai).