create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/services/go-svc/cmd/server/main.go

@@ -0,0 +1,105 @@
+// go-svc — activity API (epic FI-62, SF-4 / Linear FI-72).
+// Go 1.24 + chi; conventions: platform/conventions/.
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/api"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/config"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/consumer"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/logging"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/resolve"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/store"
+)
+
+// svcActivityEmail — fixture service user (users.json SF-1) cho service-token.
+const svcActivityEmail = "svc-activity@demo.local"
+
+func main() {
+	cfg, err := config.Load(os.Getenv)
+	if err != nil {
+		// Fail-fast (conventions/06 rule 6) — không fallback im lặng.
+		fmt.Fprintln(os.Stderr, "config error:", err)
+		os.Exit(1)
+	}
+	log := logging.New(cfg.LogLevel)
+
+	// DB — 2 pool: owner (go_svc, schema activity) + readonly (go_readonly, schema tasks)
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	st, err := store.Open(ctx, cfg.DatabaseURL, cfg.DatabaseReadonlyURL, log)
+	if err != nil {
+		log.Error("store open failed", "err", err.Error())
+		os.Exit(1)
+	}
+	defer st.Close()
+
+	// Migration schema activity (go-svc OWNS — context pack item 4)
+	if err := st.Migrate(ctx); err != nil {
+		log.Error("migration failed", "err", err.Error())
+		os.Exit(1)
+	}
+
+	// Service-token (SF-3): login svc-activity lấy JWT cho resolver enrich
+	// userName lúc consume. Warmup retry backoff — KHÔNG chặn boot, KHÔNG
+	// crash khi auth-mock chưa lên (go chỉ depends_on postgres — conventions/09).
+	tokenSource := resolve.NewTokenSource(cfg.AuthMockURL, svcActivityEmail, cfg.SvcActivityPassword)
+	go tokenSource.Warmup(context.Background(), log)
+
+	resolver := resolve.New(cfg.SpringSvcURL).WithServiceToken(tokenSource)
+
+	// Kafka consumer (SF-3 — ADR-0008): lazy-connect, broker chưa lên chỉ log
+	// warn + retry vòng kế; KHÔNG vào readyz, KHÔNG depends_on.
+	publisher := consumer.NewKafkaPublisher(cfg.KafkaBrokers...)
+	defer publisher.Close()
+	runner := &consumer.Runner{
+		Reader:    consumer.NewReader(cfg.KafkaBrokers, cfg.KafkaGroup, cfg.KafkaTopic),
+		Handler:   &consumer.Handler{Store: st, Tasks: st, Resolver: resolver, Log: log},
+		Publisher: publisher,
+		Topic:     cfg.KafkaTopic,
+		DLQTopic:  cfg.KafkaDLQTopic,
+		Log:       log,
+	}
+	consumerCtx, stopConsumer := context.WithCancel(context.Background())
+	defer stopConsumer()
+	go runner.Run(consumerCtx)
+
+	handler := api.NewRouter(api.Deps{
+		Log:         log,
+		Readiness:   st, // Ready() = migration xong + SELECT probe schema tasks
+		CORSOrigins: cfg.CORSDevOrigins,
+		JWTSecret:   []byte(cfg.JWTSecret),
+		Feed:        &api.FeedHandler{Store: st, Resolver: resolver, Tasks: st, Log: log},
+		Stats:       &api.StatsHandler{Store: st, Tasks: st, Log: log},
+	})
+
+	srv := &http.Server{
+		Addr:              ":" + cfg.Port,
+		Handler:           handler,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+
+	go func() {
+		log.Info("go-svc starting", "port", cfg.Port)
+		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			log.Error("server exited", "err", err.Error())
+			os.Exit(1)
+		}
+	}()
+
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)
+	<-stop
+	log.Info("shutting down")
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	_ = srv.Shutdown(shutdownCtx)
+}

package/stack-template/services/go-svc/go.mod

@@ -0,0 +1,12 @@
+module github.com/wakii-dev/architecture-overview/services/go-svc
+
+go 1.24
+
+require (
+	github.com/go-chi/chi/v5 v5.3.2
+	github.com/golang-jwt/jwt/v5 v5.3.1
+	github.com/google/uuid v1.6.0
+	github.com/jackc/pgx/v5 v5.7.5
+	github.com/rs/cors v1.11.1
+	github.com/segmentio/kafka-go v0.4.47 // ADR-0008: demo consumer — production path là franz-go
+)

package/stack-template/services/go-svc/internal/api/auth.go

@@ -0,0 +1,83 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"strings"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+// JWT enforcement lớp 2 (contracts/auth/token-contract.md §4):
+// go-svc TỰ verify signature (HS256 + JWT_SECRET) + expiry (exp) + iss=auth-mock.
+// KHÔNG tin presence-check của gateway — sai/hết hạn → 401 envelope.
+const expectedJWTIssuer = "auth-mock"
+
+// ctxKeyClaims holds verified JWT claims.
+const ctxKeyClaims ctxKey = 1
+
+// Claims là tập claim go-svc dùng (token contract §1).
+type Claims struct {
+	Sub   string   // user id UUID (khớp users fixture)
+	Email string
+	Roles []string
+}
+
+// ClaimsFromContext trả claims đã verify, nil nếu route không qua JWT middleware.
+func ClaimsFromContext(ctx context.Context) *Claims {
+	if v, ok := ctx.Value(ctxKeyClaims).(*Claims); ok {
+		return v
+	}
+	return nil
+}
+
+// JWTMiddleware verify Bearer token trên business routes.
+func JWTMiddleware(secret []byte) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			claims, err := verifyJWT(r.Header.Get("Authorization"), secret)
+			if err != nil {
+				WriteError(w, r, http.StatusUnauthorized, CodeUnauthorized, "invalid or expired token", nil)
+				return
+			}
+			next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), ctxKeyClaims, claims)))
+		})
+	}
+}
+
+// verifyJWT parse + validate token theo token contract. Exported cho test.
+func verifyJWT(header string, secret []byte) (*Claims, error) {
+	const prefix = "Bearer "
+	if !strings.HasPrefix(header, prefix) {
+		return nil, jwt.ErrTokenMalformed
+	}
+	tokenStr := strings.TrimPrefix(header, prefix)
+
+	parsed, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
+		return secret, nil
+	},
+		jwt.WithValidMethods([]string{"HS256"}), // chống alg-swap
+		jwt.WithIssuer(expectedJWTIssuer),
+		jwt.WithExpirationRequired(), // exp bắt buộc (contract TTL 8h)
+	)
+	if err != nil || !parsed.Valid {
+		return nil, err
+	}
+	mc, ok := parsed.Claims.(jwt.MapClaims)
+	if !ok {
+		return nil, jwt.ErrTokenInvalidClaims
+	}
+	sub, _ := mc["sub"].(string)
+	if sub == "" {
+		return nil, jwt.ErrTokenInvalidClaims
+	}
+	email, _ := mc["email"].(string)
+	rawRoles, _ := mc["roles"].([]interface{})
+	roles := make([]string, 0, len(rawRoles))
+	for _, rr := range rawRoles {
+		if s, ok := rr.(string); ok {
+			roles = append(roles, s)
+		}
+	}
+	return &Claims{Sub: sub, Email: email, Roles: roles}, nil
+}

package/stack-template/services/go-svc/internal/api/auth_test.go

@@ -0,0 +1,92 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+const testSecret = "test-secret-at-least-32-characters!"
+
+// mintToken ký JWT HS256 theo token contract (dùng chung cho auth tests).
+func mintToken(sub, iss string, iat, exp int64, secret []byte) string {
+	claims := jwt.MapClaims{
+		"sub":   sub,
+		"email": "alice@demo.local",
+		"roles": []string{"admin"},
+		"iss":   iss,
+		"iat":   iat,
+		"exp":   exp,
+	}
+	tok := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	s, _ := tok.SignedString(secret)
+	return s
+}
+
+func TestJWTMiddleware_TokenMatrix(t *testing.T) {
+	now := time.Now().Unix()
+	valid := mintToken("11111111-1111-4111-8111-111111111111", "auth-mock", now-10, now+3600, []byte(testSecret))
+	expired := mintToken("11111111-1111-4111-8111-111111111111", "auth-mock", now-7200, now-3600, []byte(testSecret))
+	wrongIss := mintToken("11111111-1111-4111-8111-111111111111", "other-issuer", now-10, now+3600, []byte(testSecret))
+	wrongSig := mintToken("11111111-1111-4111-8111-111111111111", "auth-mock", now-10, now+3600, []byte("another-secret-at-least-32-chars"))
+
+	// alg-swap: HS256 token nhưng header khai none — phải bị chặn bởi WithValidMethods
+	noneTok := jwt.NewWithClaims(jwt.SigningMethodNone, jwt.MapClaims{
+		"sub": "x", "iss": "auth-mock", "exp": now + 3600,
+	})
+	noneStr, _ := noneTok.SignedString(jwt.UnsafeAllowNoneSignatureType)
+
+	cases := []struct {
+		name   string
+		header string
+		want   int
+	}{
+		{"valid token", "Bearer " + valid, http.StatusOK},
+		{"missing header", "", http.StatusUnauthorized},
+		{"not bearer", "Basic " + valid, http.StatusUnauthorized},
+		{"garbage token", "Bearer abc.def.ghi", http.StatusUnauthorized},
+		{"expired", "Bearer " + expired, http.StatusUnauthorized},
+		{"wrong issuer", "Bearer " + wrongIss, http.StatusUnauthorized},
+		{"wrong signature", "Bearer " + wrongSig, http.StatusUnauthorized},
+		{"alg none", "Bearer " + noneStr, http.StatusUnauthorized},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			srv := httptest.NewServer(JWTMiddleware([]byte(testSecret))(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				c := ClaimsFromContext(r.Context())
+				if c == nil || c.Sub != "11111111-1111-4111-8111-111111111111" {
+					t.Errorf("claims not propagated: %+v", c)
+				}
+				w.WriteHeader(http.StatusOK)
+			})))
+			defer srv.Close()
+
+			req, _ := http.NewRequest(http.MethodGet, srv.URL, nil)
+			if tc.header != "" {
+				req.Header.Set("Authorization", tc.header)
+			}
+			res, err := http.DefaultClient.Do(req)
+			if err != nil {
+				t.Fatalf("request: %v", err)
+			}
+			defer res.Body.Close()
+			if res.StatusCode != tc.want {
+				t.Errorf("status = %d, want %d", res.StatusCode, tc.want)
+			}
+			if tc.want == http.StatusUnauthorized {
+				assertEnvelope(t, readAll(t, res), CodeUnauthorized, "")
+			}
+		})
+	}
+}
+
+func readAll(t *testing.T, res *http.Response) string {
+	t.Helper()
+	buf := make([]byte, 4096)
+	n, _ := res.Body.Read(buf)
+	return string(buf[:n])
+}

package/stack-template/services/go-svc/internal/api/envelope.go

@@ -0,0 +1,61 @@
+// Package api — HTTP handlers của go-svc.
+// envelope.go: error envelope chung (platform/conventions/04).
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+)
+
+// ctxKey holds context keys used across middlewares/handlers.
+type ctxKey int
+
+const ctxKeyRequestID ctxKey = iota
+
+// RequestID trả request id từ context (đặt bởi RequestIDMiddleware).
+func RequestID(ctx context.Context) string {
+	if v, ok := ctx.Value(ctxKeyRequestID).(string); ok {
+		return v
+	}
+	return ""
+}
+
+func contextWithRequestID(r *http.Request, id string) context.Context {
+	return context.WithValue(r.Context(), ctxKeyRequestID, id)
+}
+
+// Envelope là shape lỗi chung — mirror components.schemas.Error trong
+// contracts/openapi/activity.yaml + platform/conventions/04-error-envelope.md.
+type Envelope struct {
+	Error ErrorBody `json:"error"`
+}
+
+type ErrorBody struct {
+	Code      string      `json:"code"`
+	Message   string      `json:"message"`
+	RequestID string      `json:"requestId"`
+	Details   interface{} `json:"details"` // nullable
+}
+
+// Error codes — catalog tối thiểu conventions/04.
+const (
+	CodeValidationError  = "VALIDATION_ERROR"
+	CodeUnauthorized     = "UNAUTHORIZED"
+	CodeNotFound         = "NOT_FOUND"
+	CodeDependencyDown   = "DEPENDENCY_DOWN"
+	CodeInternal         = "INTERNAL"
+)
+
+// WriteError ghi error envelope + status. Không bao giờ lộ stack trong message.
+func WriteError(w http.ResponseWriter, r *http.Request, status int, code, message string, details interface{}) {
+	body := Envelope{Error: ErrorBody{
+		Code:      code,
+		Message:   message,
+		RequestID: RequestID(r.Context()),
+		Details:   details,
+	}}
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(body)
+}

package/stack-template/services/go-svc/internal/api/envelope_test.go

@@ -0,0 +1,51 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestWriteError_EnvelopeShape(t *testing.T) {
+	req := httptest.NewRequest(http.MethodGet, "/x", nil)
+	req = req.WithContext(contextWithRequestID(req, "req-42"))
+	rec := httptest.NewRecorder()
+	WriteError(rec, req, http.StatusBadRequest, CodeValidationError, "bad payload", map[string]string{"field": "action"})
+
+	var got Envelope
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("body not valid JSON: %v — %s", err, rec.Body.String())
+	}
+	if rec.Code != http.StatusBadRequest {
+		t.Errorf("status = %d, want 400", rec.Code)
+	}
+	if got.Error.Code != "VALIDATION_ERROR" {
+		t.Errorf("code = %q, want VALIDATION_ERROR", got.Error.Code)
+	}
+	if got.Error.RequestID != "req-42" {
+		t.Errorf("requestId = %q, want req-42", got.Error.RequestID)
+	}
+	if got.Error.Details == nil {
+		t.Error("details should be carried through")
+	}
+	// requestId + code đứng cạnh message theo đúng thứ tự field của conventions/04
+	if !strings.Contains(rec.Body.String(), "\"requestId\":\"req-42\"") {
+		t.Error("requestId missing in JSON body")
+	}
+}
+
+func assertEnvelope(t *testing.T, body, code, requestID string) {
+	t.Helper()
+	var got Envelope
+	if err := json.Unmarshal([]byte(body), &got); err != nil {
+		t.Fatalf("body not valid JSON: %v — %s", err, body)
+	}
+	if got.Error.Code != code {
+		t.Errorf("code = %q, want %q", got.Error.Code, code)
+	}
+	if got.Error.RequestID != requestID {
+		t.Errorf("requestId = %q, want %q", got.Error.RequestID, requestID)
+	}
+}

package/stack-template/services/go-svc/internal/api/fakes_test.go

@@ -0,0 +1,105 @@
+package api
+
+// fakes_test.go — fake store/resolver/tasks cho unit test handlers (không DB).
+
+import (
+	"context"
+	"sync"
+
+	"github.com/google/uuid"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/apperr"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+type fakeStore struct {
+	mu     sync.Mutex
+	events []model.Event
+	// lỗi inject được
+	insertErr error
+	listErr   error
+	recentErr error
+	// eventsLenForRecent — override CountRecent24h (test stats không cần seed)
+	eventsLenForRecent int
+}
+
+func (f *fakeStore) InsertEvent(_ context.Context, e *model.Event) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.insertErr != nil {
+		return f.insertErr
+	}
+	f.events = append(f.events, *e)
+	return nil
+}
+
+func (f *fakeStore) ListEvents(_ context.Context, limit, offset int) ([]model.Event, int, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.listErr != nil {
+		return nil, 0, f.listErr
+	}
+	total := len(f.events)
+	// events giữ thứ tự insert; feed cần mới nhất trước — reverse slice
+	out := make([]model.Event, 0, limit)
+	for i := total - 1 - offset; i >= 0 && len(out) < limit; i-- {
+		out = append(out, f.events[i])
+	}
+	return out, total, nil
+}
+
+func (f *fakeStore) CountRecent24h(context.Context) (int, error) {
+	if f.recentErr != nil {
+		return 0, f.recentErr
+	}
+	if f.eventsLenForRecent > 0 {
+		return f.eventsLenForRecent, nil
+	}
+	return len(f.events), nil
+}
+
+type fakeTasks struct {
+	titles map[uuid.UUID]string
+	stats  model.TaskStats
+	err    error // nếu non-nil → trả cho Stats/TaskTitle (unavail=true → ErrTasksUnavailable)
+	unavail bool
+	probeErr error
+}
+
+func (f *fakeTasks) TaskTitle(_ context.Context, id uuid.UUID) (string, error) {
+	if f.unavail {
+		return "", apperr.ErrTasksUnavailable
+	}
+	if f.err != nil {
+		return "", f.err
+	}
+	return f.titles[id], nil
+}
+
+func (f *fakeTasks) Stats(context.Context) (model.TaskStats, error) {
+	if f.unavail {
+		return model.TaskStats{}, apperr.ErrTasksUnavailable
+	}
+	if f.err != nil {
+		return model.TaskStats{}, f.err
+	}
+	return f.stats, nil
+}
+
+func (f *fakeTasks) Probe(context.Context) error {
+	if f.unavail {
+		return apperr.ErrTasksUnavailable
+	}
+	return f.probeErr
+}
+
+type fakeResolver struct {
+	name string
+}
+
+func (f fakeResolver) UserName(context.Context, string, uuid.UUID) string { return f.name }
+
+// mustUUID helper — parse uuid trong test, panic nếu sai literal.
+func mustUUID(s string) uuid.UUID {
+	return uuid.MustParse(s)
+}

package/stack-template/services/go-svc/internal/api/feed.go

@@ -0,0 +1,98 @@
+package api
+
+// feed.go — GET /api/activity/feed: feed mới nhất trước + total.
+// User-display fields (userName, taskTitle) BẮT BUỘC trong item (activity.yaml
+// ActivityFeedItem required) — FE render trực tiếp, không tự bịa placeholder.
+
+import (
+	"log/slog"
+	"net/http"
+	"strconv"
+	"time"
+)
+
+const (
+	feedDefaultLimit = 20
+	feedMaxLimit     = 100
+)
+
+// feedItem mirror ActivityFeedItem (all required).
+type feedItem struct {
+	ID        string `json:"id"`
+	TaskID    string `json:"taskId"`
+	UserID    string `json:"userId"`
+	Action    string `json:"action"`
+	Timestamp string `json:"timestamp"`
+	UserName  string `json:"userName"`
+	TaskTitle string `json:"taskTitle"`
+}
+
+type feedResponse struct {
+	Items []feedItem `json:"items"`
+	Total int        `json:"total"`
+}
+
+// FeedHandler deps cho GET /feed.
+type FeedHandler struct {
+	Store    EventStore
+	Resolver DisplayResolver
+	Tasks    TaskReader
+	Log      *slog.Logger
+}
+
+// List xử lý GET /feed (mount sau JWTMiddleware).
+func (h *FeedHandler) List(w http.ResponseWriter, r *http.Request) {
+	limit := clampInt(r.URL.Query().Get("limit"), 1, feedMaxLimit, feedDefaultLimit)
+	offset, err := strconv.Atoi(r.URL.Query().Get("offset"))
+	if err != nil || offset < 0 {
+		offset = 0
+	}
+
+	events, total, err := h.Store.ListEvents(r.Context(), limit, offset)
+	if err != nil {
+		h.Log.Error("list events failed", "requestId", RequestID(r.Context()), "err", err.Error())
+		WriteError(w, r, http.StatusInternalServerError, CodeInternal, "failed to list events", nil)
+		return
+	}
+
+	authz := r.Header.Get("Authorization")
+	items := make([]feedItem, 0, len(events))
+	for _, ev := range events {
+		item := feedItem{
+			ID:        ev.ID.String(),
+			TaskID:    ev.TaskID.String(),
+			UserID:    ev.UserID.String(),
+			Action:    ev.Action,
+			Timestamp: ev.Timestamp.Format(time.RFC3339),
+			UserName:  ev.UserName,
+			TaskTitle: ev.TaskTitle,
+		}
+		// Display fields thiếu lúc ingest (spring/tasks down) → thử resolve lại lúc đọc.
+		if item.UserName == "" {
+			item.UserName = h.Resolver.UserName(r.Context(), authz, ev.UserID)
+		}
+		if item.TaskTitle == "" {
+			if title, err := h.Tasks.TaskTitle(r.Context(), ev.TaskID); err == nil {
+				item.TaskTitle = title
+			}
+		}
+		items = append(items, item)
+	}
+
+	writeJSON(w, http.StatusOK, feedResponse{Items: items, Total: total})
+}
+
+// clampInt parse query int với min/max + default.
+func clampInt(raw string, min, max, def int) int {
+	n, err := strconv.Atoi(raw)
+	if err != nil {
+		return def
+	}
+	if n < min {
+		return min
+	}
+	if n > max {
+		return max
+	}
+	return n
+}