@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/observability/sentry.go

@@ -0,0 +1,445 @@
+package observability
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/getsentry/sentry-go"
+	sentrygin "github.com/getsentry/sentry-go/gin"
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/requestprivacy"
+	"{{module}}/internal/core/config"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 配置
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	defaultSentrySampleRate         = 1.0
+	defaultSentryTracesSampleRate   = 0.1
+	defaultSentryProfilesSampleRate = 0.1
+	defaultSentryFlushTimeoutMs     = 2000
+	defaultSentryCloseTimeoutMs     = 5000
+)
+
+// SentryUser Sentry 用户上下文
+type SentryUser struct {
+	ID        string
+	Email     string
+	Username  string
+	IPAddress string
+}
+
+// SentryContext Sentry 额外上下文信息
+type SentryContext map[string]any
+
+// ═══════════════════════════════════════════════════════════════
+// Sentry 服务
+// ═══════════════════════════════════════════════════════════════
+
+// SentryService Sentry 错误追踪服务
+//
+// 提供 Sentry SDK 的封装，用于：
+//   - 异常捕获和上报
+//   - 消息级别事件
+//   - 用户上下文设置
+//   - 面包屑和标签
+//   - Gin 中间件集成
+type SentryService struct {
+	logger      *zap.Logger
+	config      config.SentryConfig
+	initialized bool
+}
+
+// NewSentryService 创建 Sentry 服务
+func NewSentryService(logger *zap.Logger, cfg *config.SentryConfig) *SentryService {
+	return &SentryService{
+		logger: logger.Named("Sentry"),
+		config: *cfg,
+	}
+}
+
+// Initialize 初始化 Sentry SDK
+func (s *SentryService) Initialize() error {
+	if !s.config.Enabled {
+		s.logger.Info("Sentry is disabled")
+		return nil
+	}
+
+	if s.config.DSN == "" {
+		s.logger.Warn("Sentry DSN is not configured")
+		return nil
+	}
+
+	// 设置默认采样率
+	sampleRate := s.config.SampleRate
+	if sampleRate <= 0 {
+		sampleRate = defaultSentrySampleRate
+	}
+	tracesSampleRate := s.config.TracesSampleRate
+	if tracesSampleRate <= 0 {
+		tracesSampleRate = defaultSentryTracesSampleRate
+	}
+	err := sentry.Init(sentry.ClientOptions{
+		Dsn:              s.config.DSN,
+		Environment:      s.config.Environment,
+		Release:          s.config.Release,
+		SampleRate:       sampleRate,
+		TracesSampleRate: tracesSampleRate,
+		Debug:            s.config.Debug,
+		BeforeSend: func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
+			sanitizeSentryRecoveredPanic(event, hint)
+			sanitizeSentryEventRequest(event)
+			// 在开发环境过滤常见的连接拒绝错误
+			if s.config.Environment == "development" && hint != nil {
+				if hint.OriginalException != nil {
+					if strings.Contains(hint.OriginalException.Error(), "ECONNREFUSED") ||
+						strings.Contains(hint.OriginalException.Error(), "connection refused") {
+						return nil
+					}
+				}
+			}
+			return event
+		},
+		BeforeSendTransaction: func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
+			sanitizeSentryEventRequest(event)
+			// 过滤健康检查事务
+			if event.Transaction != "" {
+				txn := event.Transaction
+				if strings.Contains(txn, "/health") ||
+					strings.Contains(txn, "/ready") ||
+					strings.Contains(txn, "/live") ||
+					strings.Contains(txn, "/metrics") {
+					return nil
+				}
+			}
+			return event
+		},
+	})
+	if err != nil {
+		s.logger.Error("failed to initialize Sentry", zap.Error(err))
+		return fmt.Errorf("initialize sentry: %w", err)
+	}
+
+	s.initialized = true
+	s.logger.Info("Sentry initialized successfully")
+	return nil
+}
+
+// IsEnabled 检查 Sentry 是否已启用并初始化
+func (s *SentryService) IsEnabled() bool {
+	return s.initialized && s.config.Enabled
+}
+
+// CaptureException 捕获异常
+func (s *SentryService) CaptureException(err error, ctx ...SentryContext) string {
+	if !s.IsEnabled() || err == nil {
+		return ""
+	}
+
+	if len(ctx) > 0 {
+		sentry.WithScope(func(scope *sentry.Scope) {
+			for k, v := range ctx[0] {
+				scope.SetExtra(k, v)
+			}
+			sentry.CaptureException(err)
+		})
+		return ""
+	}
+
+	eventID := sentry.CaptureException(err)
+	if eventID != nil {
+		return string(*eventID)
+	}
+	return ""
+}
+
+// CaptureMessage 捕获消息
+func (s *SentryService) CaptureMessage(message string, level sentry.Level, ctx ...SentryContext) string {
+	if !s.IsEnabled() {
+		return ""
+	}
+
+	sentry.WithScope(func(scope *sentry.Scope) {
+		scope.SetLevel(level)
+		if len(ctx) > 0 {
+			for k, v := range ctx[0] {
+				scope.SetExtra(k, v)
+			}
+		}
+		sentry.CaptureMessage(message)
+	})
+
+	return ""
+}
+
+// SetUser 设置错误追踪的用户上下文
+func (s *SentryService) SetUser(user *SentryUser) {
+	if !s.IsEnabled() {
+		return
+	}
+
+	if user == nil {
+		sentry.ConfigureScope(func(scope *sentry.Scope) {
+			scope.SetUser(sentry.User{})
+		})
+		return
+	}
+
+	sentry.ConfigureScope(func(scope *sentry.Scope) {
+		scope.SetUser(sentry.User{
+			ID:        user.ID,
+			Email:     user.Email,
+			Username:  user.Username,
+			IPAddress: user.IPAddress,
+		})
+	})
+}
+
+// SetContext 设置额外的上下文信息
+func (s *SentryService) SetContext(name string, ctx SentryContext) {
+	if !s.IsEnabled() {
+		return
+	}
+
+	sentry.ConfigureScope(func(scope *sentry.Scope) {
+		scope.SetContext(name, ctx)
+	})
+}
+
+// SetTags 设置用于错误分类的标签
+func (s *SentryService) SetTags(tags map[string]string) {
+	if !s.IsEnabled() {
+		return
+	}
+
+	sentry.ConfigureScope(func(scope *sentry.Scope) {
+		scope.SetTags(tags)
+	})
+}
+
+// SetTag 设置单个标签
+func (s *SentryService) SetTag(key, value string) {
+	if !s.IsEnabled() {
+		return
+	}
+
+	sentry.ConfigureScope(func(scope *sentry.Scope) {
+		scope.SetTag(key, value)
+	})
+}
+
+// AddBreadcrumb 添加用于调试的面包屑
+func (s *SentryService) AddBreadcrumb(category, message string, level sentry.Level, data map[string]any) {
+	if !s.IsEnabled() {
+		return
+	}
+
+	sentry.AddBreadcrumb(&sentry.Breadcrumb{
+		Category: category,
+		Message:  message,
+		Level:    level,
+		Data:     data,
+	})
+}
+
+// Flush 在关闭前刷新待处理的事件
+func (s *SentryService) Flush(timeout ...time.Duration) bool {
+	if !s.IsEnabled() {
+		return true
+	}
+
+	t := time.Duration(defaultSentryFlushTimeoutMs) * time.Millisecond
+	if len(timeout) > 0 {
+		t = timeout[0]
+	}
+
+	return sentry.Flush(t)
+}
+
+// Close 关闭 Sentry 客户端
+func (s *SentryService) Close(timeout ...time.Duration) bool {
+	if !s.IsEnabled() {
+		return true
+	}
+
+	t := time.Duration(defaultSentryCloseTimeoutMs) * time.Millisecond
+	if len(timeout) > 0 {
+		t = timeout[0]
+	}
+
+	return sentry.Flush(t)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Gin 中间件
+// ═══════════════════════════════════════════════════════════════
+
+// GinMiddleware 返回 Gin 框架的 Sentry 异常自动捕获中间件
+//
+// 该中间件会自动捕获请求处理过程中的 panic 和错误，
+// 并上报给 Sentry，同时附加请求上下文信息。
+func (s *SentryService) GinMiddleware(repanic bool) gin.HandlerFunc {
+	if !s.IsEnabled() {
+		// Sentry 未启用时返回透传中间件
+		return func(c *gin.Context) {
+			c.Next()
+		}
+	}
+
+	// 使用 sentry-go 官方 Gin 集成
+	return sentrygin.New(sentrygin.Options{
+		Repanic:         repanic,
+		WaitForDelivery: false,
+	})
+}
+
+// GinRecoveryMiddleware 返回带 Sentry 上报的 Recovery 中间件
+//
+// 捕获 panic 后自动上报 Sentry 并返回 500 响应。
+func (s *SentryService) GinRecoveryMiddleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		defer func() {
+			if r := recover(); r != nil {
+				err := fmt.Errorf("panic recovered")
+
+				// 上报 Sentry
+				if s.IsEnabled() {
+					sentry.WithScope(func(scope *sentry.Scope) {
+						scope.SetRequest(sanitizedSentryRequest(c))
+						scope.SetTag("panic_type", fmt.Sprintf("%T", r))
+						sentry.CaptureException(err)
+					})
+				}
+
+				c.AbortWithStatus(http.StatusInternalServerError)
+			}
+		}()
+
+		c.Next()
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 请求上下文提取
+// ═══════════════════════════════════════════════════════════════
+
+// ExtractRequestContext 从 Gin 上下文提取请求信息用于 Sentry 上下文
+func (s *SentryService) ExtractRequestContext(c *gin.Context) SentryContext {
+	safeURL := requestprivacy.SanitizeURL(
+		c.Request.URL,
+		requestprivacy.RouteTemplateOrUnmatched(c.FullPath()),
+		requestprivacy.RedactAllQueryValues,
+	)
+	return SentryContext{
+		"method":     c.Request.Method,
+		"url":        safeURL.String(),
+		"path":       safeURL.Path,
+		"query":      safeURL.RawQuery,
+		"headers":    requestprivacy.RedactSensitiveHeaders(c.Request.Header),
+		"ip":         c.ClientIP(),
+		"user_agent": c.Request.UserAgent(),
+	}
+}
+
+func sanitizeSentryEventRequest(event *sentry.Event) {
+	if event == nil {
+		return
+	}
+	routeTemplate := sanitizeSentryTransaction(event)
+	if event.Request == nil {
+		return
+	}
+	request := event.Request
+	request.URL = requestprivacy.SanitizeRawURL(
+		request.URL,
+		routeTemplate,
+		requestprivacy.RemoveQueryValues,
+	)
+	request.QueryString = requestprivacy.SanitizeQuery(request.QueryString, requestprivacy.RedactAllQueryValues)
+	request.Data = ""
+	request.Cookies = ""
+	for key := range request.Headers {
+		if requestprivacy.IsSensitiveHeader(key) {
+			delete(request.Headers, key)
+		}
+	}
+}
+
+func sanitizeSentryRecoveredPanic(event *sentry.Event, hint *sentry.EventHint) {
+	if event == nil || hint == nil || hint.RecoveredException == nil {
+		return
+	}
+	event.Message = "panic recovered"
+	for index := range event.Exception {
+		event.Exception[index].Value = "panic recovered"
+	}
+	delete(event.Extra, "panic_value")
+	if event.Tags == nil {
+		event.Tags = make(map[string]string)
+	}
+	event.Tags["panic_type"] = fmt.Sprintf("%T", hint.RecoveredException)
+}
+
+func sanitizeSentryTransaction(event *sentry.Event) string {
+	method, path := splitSentryHTTPTransaction(event.Transaction)
+	if path == "" {
+		if event.Request != nil {
+			return requestprivacy.UnmatchedRoute
+		}
+		return ""
+	}
+	if event.TransactionInfo != nil && event.TransactionInfo.Source == sentry.SourceRoute {
+		routeTemplate := requestprivacy.SanitizePath("", path)
+		if routeTemplate == "" {
+			event.Transaction = joinSentryHTTPTransaction(method, requestprivacy.UnmatchedRoute)
+			return requestprivacy.UnmatchedRoute
+		}
+		event.Transaction = joinSentryHTTPTransaction(method, routeTemplate)
+		return routeTemplate
+	}
+	event.Transaction = joinSentryHTTPTransaction(method, requestprivacy.UnmatchedRoute)
+	return requestprivacy.UnmatchedRoute
+}
+
+func splitSentryHTTPTransaction(transaction string) (string, string) {
+	trimmed := strings.TrimSpace(transaction)
+	parts := strings.SplitN(trimmed, " ", 2)
+	if len(parts) == 2 && strings.HasPrefix(strings.TrimSpace(parts[1]), "/") {
+		return strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1])
+	}
+	if strings.HasPrefix(trimmed, "/") {
+		return "", trimmed
+	}
+	return "", ""
+}
+
+func joinSentryHTTPTransaction(method, path string) string {
+	if method == "" {
+		return path
+	}
+	return method + " " + path
+}
+
+func sanitizedSentryRequest(c *gin.Context) *http.Request {
+	request := c.Request.Clone(c.Request.Context())
+	safeURL := requestprivacy.SanitizeURL(
+		c.Request.URL,
+		requestprivacy.RouteTemplateOrUnmatched(c.FullPath()),
+		requestprivacy.RemoveQueryValues,
+	)
+	request.URL = &safeURL
+	request.RequestURI = safeURL.RequestURI()
+	request.Header = request.Header.Clone()
+	for key := range request.Header {
+		if requestprivacy.IsSensitiveHeader(key) {
+			request.Header.Del(key)
+		}
+	}
+	return request
+}

package/dist/resources/templates/go-backend/internal/core/observability/sentry_privacy_test.go

@@ -0,0 +1,175 @@
+package observability
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/getsentry/sentry-go"
+	"github.com/gin-gonic/gin"
+)
+
+func TestSanitizeSentryRecoveredPanicRemovesRawValue(t *testing.T) {
+	const secret = "panic-secret-token"
+	event := &sentry.Event{
+		Message: secret,
+		Exception: []sentry.Exception{{
+			Type:  "runtime.errorString",
+			Value: secret,
+		}},
+		Extra: map[string]any{"panic_value": secret, "safe_count": 1},
+	}
+
+	sanitizeSentryRecoveredPanic(event, &sentry.EventHint{RecoveredException: secret})
+
+	encoded, err := json.Marshal(event)
+	if err != nil {
+		t.Fatalf("marshal event: %v", err)
+	}
+	if strings.Contains(string(encoded), secret) {
+		t.Fatalf("event retained recovered panic value: %s", encoded)
+	}
+	if event.Message != "panic recovered" || event.Exception[0].Value != "panic recovered" {
+		t.Fatalf("panic evidence = %#v", event)
+	}
+	if _, exists := event.Extra["panic_value"]; exists {
+		t.Fatalf("panic_value extra = %#v", event.Extra)
+	}
+	if event.Tags["panic_type"] != "string" {
+		t.Fatalf("panic_type = %q", event.Tags["panic_type"])
+	}
+}
+
+func TestSanitizeSentryEventRequestRemovesRequestSecrets(t *testing.T) {
+	event := &sentry.Event{Request: &sentry.Request{
+		URL:         "https://docs.example.com/search?q=refund&locale=en#section",
+		QueryString: "q=refund&locale=en",
+		Data:        `{"query":"refund"}`,
+		Cookies:     "session=secret",
+		Headers: map[string]string{
+			"Authorization":              "Bearer secret",
+			"Idempotency-Key":            "idempotency-secret",
+			"Stripe-Signature":           "stripe-secret",
+			"X-Anonymous-Session-ID":     "anonymous-secret",
+			"X-Checkout-Session-Token":   "checkout-secret",
+			"X-Checkout-Return-State":    "return-secret",
+			"X-CSRF-Token":               "csrf-secret",
+			"X-Onex-Delegated-Authority": "delegated-secret",
+			"X-Onex-Guest-Capability":    "guest-secret",
+			"X-OneX-Signature":           "signature-secret",
+			"X-Session-ID":               "session-secret",
+			"X-Token-JTI":                "jti-secret",
+			"X-Device-ID":                "device-public-value",
+			"User-Agent":                 "test-agent",
+		},
+	}}
+
+	sanitizeSentryEventRequest(event)
+
+	request := event.Request
+	if strings.Contains(request.URL, "refund") || strings.Contains(request.URL, "?") || request.Data != "" || request.Cookies != "" {
+		t.Fatalf("request payload was not scrubbed: %#v", request)
+	}
+	if request.QueryString != "locale=redacted&q=redacted" {
+		t.Fatalf("query = %q", request.QueryString)
+	}
+	if len(request.Headers) != 2 || request.Headers["User-Agent"] != "test-agent" || request.Headers["X-Device-ID"] != "device-public-value" {
+		t.Fatalf("headers = %#v", request.Headers)
+	}
+}
+
+func TestSanitizeSentryEventRequestUsesRouteTemplateForProtectedPath(t *testing.T) {
+	event := &sentry.Event{
+		Transaction:     "GET /iap/google/orders/by-token/:purchaseToken",
+		TransactionInfo: &sentry.TransactionInfo{Source: sentry.SourceRoute},
+		Request: &sentry.Request{
+			URL:         "https://data.product-alpha.example/iap/google/orders/by-token/secret%2Fpurchase-token?token=secret-query",
+			QueryString: "token=secret-query&locale=en",
+		},
+	}
+
+	sanitizeSentryEventRequest(event)
+
+	if event.Request.URL != "https://data.product-alpha.example/iap/google/orders/by-token/:purchaseToken" {
+		t.Fatalf("URL = %q", event.Request.URL)
+	}
+	if event.Request.QueryString != "locale=redacted&token=redacted" {
+		t.Fatalf("query = %q", event.Request.QueryString)
+	}
+	if event.Transaction != "GET /iap/google/orders/by-token/:purchaseToken" {
+		t.Fatalf("transaction = %q", event.Transaction)
+	}
+	if strings.Contains(event.Request.URL, "secret") {
+		t.Fatalf("URL retained protected path value: %q", event.Request.URL)
+	}
+}
+
+func TestSanitizeSentryEventRequestRedactsPaymentResultFallback(t *testing.T) {
+	event := &sentry.Event{
+		Transaction:     "GET /api/v1/payment-results/secret-result-token",
+		TransactionInfo: &sentry.TransactionInfo{Source: sentry.SourceURL},
+		Request: &sentry.Request{
+			URL: "https://api.example.com/api/v1/payment-results/secret-result-token?return_state=secret-state",
+		},
+	}
+
+	sanitizeSentryEventRequest(event)
+
+	if event.Request.URL != "https://api.example.com/unmatched" {
+		t.Fatalf("URL = %q", event.Request.URL)
+	}
+	if event.Transaction != "GET /unmatched" {
+		t.Fatalf("transaction = %q", event.Transaction)
+	}
+}
+
+func TestExtractRequestContextAndRecoveryRequestUseSanitizedRoute(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	service := &SentryService{}
+	engine := gin.New()
+	var extracted SentryContext
+	var recoveryRequest *http.Request
+	engine.GET("/iap/google/orders/by-token/:purchaseToken", func(c *gin.Context) {
+		extracted = service.ExtractRequestContext(c)
+		recoveryRequest = sanitizedSentryRequest(c)
+		c.Status(http.StatusNoContent)
+	})
+
+	request := httptest.NewRequest(http.MethodGet, "/iap/google/orders/by-token/secret-purchase-token?locale=en&token=secret-query", nil)
+	request.URL.RawPath = "/iap/google/orders/by-token/secret%2Dpurchase-token"
+	request.Header.Set("X-Anonymous-Session-ID", "anonymous-secret")
+	request.Header.Set("X-Onex-Delegated-Authority", "delegated-secret")
+	request.Header.Set("X-Device-ID", "device-public-value")
+	response := httptest.NewRecorder()
+	engine.ServeHTTP(response, request)
+
+	if response.Code != http.StatusNoContent {
+		t.Fatalf("status = %d", response.Code)
+	}
+	if extracted["path"] != "/iap/google/orders/by-token/:purchaseToken" {
+		t.Fatalf("path = %#v", extracted["path"])
+	}
+	if extracted["query"] != "locale=redacted&token=redacted" {
+		t.Fatalf("query = %#v", extracted["query"])
+	}
+	for _, secret := range []string{"secret-purchase-token", "secret-query", "anonymous-secret", "delegated-secret"} {
+		if strings.Contains(extracted["url"].(string), secret) || strings.Contains(extracted["path"].(string), secret) {
+			t.Fatalf("request context retained %q: %#v", secret, extracted)
+		}
+	}
+	headers := extracted["headers"].(map[string]string)
+	if headers["X-Anonymous-Session-Id"] != "[REDACTED]" || headers["X-Onex-Delegated-Authority"] != "[REDACTED]" {
+		t.Fatalf("headers = %#v", headers)
+	}
+	if recoveryRequest.URL.RawPath != "" || recoveryRequest.RequestURI != "/iap/google/orders/by-token/:purchaseToken" {
+		t.Fatalf("recovery request URL = %#v, requestURI = %q", recoveryRequest.URL, recoveryRequest.RequestURI)
+	}
+	if recoveryRequest.Header.Get("X-Anonymous-Session-ID") != "" || recoveryRequest.Header.Get("X-Onex-Delegated-Authority") != "" {
+		t.Fatalf("recovery request headers = %#v", recoveryRequest.Header)
+	}
+	if recoveryRequest.Header.Get("X-Device-ID") != "device-public-value" {
+		t.Fatalf("X-Device-ID = %q", recoveryRequest.Header.Get("X-Device-ID"))
+	}
+}