@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/middleware/idempotent.go

@@ -0,0 +1,273 @@
+package middleware
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/common/utils"
+	"{{module}}/pkg/apierror"
+)
+
+// CachedIdempotentResponse 幂等响应缓存的内部数据结构。
+type CachedIdempotentResponse struct {
+	RequestHash  string          `json:"request_hash"`
+	Data         json.RawMessage `json:"data"`
+	StatusCode   int             `json:"status_code"`
+	CachedAt     int64           `json:"cached_at"`
+	IsError      bool            `json:"is_error"`
+	ErrorMessage string          `json:"error_message,omitempty"`
+	ErrorStatus  int             `json:"error_status,omitempty"`
+}
+
+// IdempotentOptions 幂等中间件选项。
+type IdempotentOptions struct {
+	TTL               int
+	OnMissingKey      string
+	MissingKeyMessage string
+	Logger            *zap.Logger
+}
+
+// Idempotent 使用请求指纹和 Redis 占位锁保护写请求。
+func Idempotent(rdb *redis.Client, opts IdempotentOptions) gin.HandlerFunc {
+	ttl := opts.TTL
+	if ttl <= 0 {
+		ttl = utils.DefaultIdempotencyTTL
+	}
+	onMissingKey := opts.OnMissingKey
+	if onMissingKey == "" {
+		onMissingKey = "throw"
+	}
+	missingKeyMessage := opts.MissingKeyMessage
+	if missingKeyMessage == "" {
+		missingKeyMessage = "Idempotency key is required"
+	}
+	logger := opts.Logger
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+
+	return func(c *gin.Context) {
+		if rdb == nil {
+			abortIdempotencyUnavailable(c)
+			return
+		}
+
+		idempotencyKey := strings.TrimSpace(c.GetHeader(types.HeaderIdempotencyKey))
+		if idempotencyKey == "" {
+			if onMissingKey == "skip" {
+				logger.Debug("idempotency key missing, skipping check")
+				c.Next()
+				return
+			}
+			apiErr := apierror.BadRequest(apierror.CodeValidationFailed, missingKeyMessage)
+			c.AbortWithStatusJSON(apiErr.Status, apiErr.ToResponse())
+			return
+		}
+		if len(idempotencyKey) > 200 {
+			apiErr := apierror.BadRequest(apierror.CodeValidationFailed, "Idempotency key is too long")
+			c.AbortWithStatusJSON(apiErr.Status, apiErr.ToResponse())
+			return
+		}
+
+		method := c.Request.Method
+		path := c.FullPath()
+		if path == "" {
+			path = c.Request.URL.Path
+		}
+		requestHash, err := idempotentRequestHash(c.Request, method, path)
+		if err != nil {
+			apiErr := apierror.BadRequest(apierror.CodeValidationFailed, "Request body could not be read")
+			c.AbortWithStatusJSON(apiErr.Status, apiErr.ToResponse())
+			return
+		}
+
+		cacheKey := fmt.Sprintf("%s:%s:%s:%s", utils.IdempotencyCachePrefix, method, path, idempotencyKey)
+		ctx := c.Request.Context()
+		cached, err := getIdempotentCache(ctx, rdb, cacheKey)
+		if err != nil {
+			logger.Warn("idempotency cache read failed", zap.Error(err))
+			abortIdempotencyUnavailable(c)
+			return
+		}
+		if cached != nil {
+			if apiErr := validateIdempotentRequestHash(cached.RequestHash, requestHash); apiErr != nil {
+				c.AbortWithStatusJSON(apiErr.Status, apiErr.ToResponse())
+				return
+			}
+			writeCachedIdempotentResponse(c, cached)
+			return
+		}
+
+		processingTTL := 2 * time.Minute
+		if configuredTTL := time.Duration(ttl) * time.Second; configuredTTL < processingTTL {
+			processingTTL = configuredTTL
+		}
+		lockKey := cacheKey + ":processing"
+		acquired, err := rdb.SetNX(ctx, lockKey, requestHash, processingTTL).Result()
+		if err != nil {
+			logger.Warn("idempotency processing lock failed", zap.Error(err))
+			abortIdempotencyUnavailable(c)
+			return
+		}
+		if !acquired {
+			processingHash, getErr := rdb.Get(ctx, lockKey).Result()
+			if getErr != nil && !errors.Is(getErr, redis.Nil) {
+				logger.Warn("idempotency processing lock read failed", zap.Error(getErr))
+				abortIdempotencyUnavailable(c)
+				return
+			}
+			apiErr := idempotencyProcessingConflict(processingHash, requestHash)
+			c.AbortWithStatusJSON(apiErr.Status, apiErr.ToResponse())
+			return
+		}
+
+		writer := &idempotentResponseWriter{
+			ResponseWriter: c.Writer,
+			body:           &bytes.Buffer{},
+		}
+		c.Writer = writer
+		c.Next()
+
+		statusCode := writer.Status()
+		bodyBytes := writer.body.Bytes()
+		response := CachedIdempotentResponse{
+			RequestHash: requestHash,
+			Data:        bodyBytes,
+			StatusCode:  statusCode,
+			CachedAt:    time.Now().UnixMilli(),
+			IsError:     statusCode >= http.StatusBadRequest,
+		}
+		if response.IsError {
+			response.ErrorStatus = statusCode
+			response.ErrorMessage = string(bodyBytes)
+		}
+		if err := setIdempotentCache(ctx, rdb, cacheKey, &response, ttl); err != nil {
+			logger.Error("idempotency cache write failed", zap.Error(err))
+			return
+		}
+		logger.Debug("cached idempotent response")
+	}
+}
+
+func idempotentRequestHash(request *http.Request, method, path string) (string, error) {
+	var body []byte
+	if request.Body != nil {
+		var err error
+		body, err = io.ReadAll(request.Body)
+		if err != nil {
+			return "", err
+		}
+		request.Body = io.NopCloser(bytes.NewReader(body))
+	}
+
+	hasher := sha256.New()
+	_, _ = io.WriteString(hasher, method)
+	_, _ = hasher.Write([]byte{0})
+	_, _ = io.WriteString(hasher, path)
+	_, _ = hasher.Write([]byte{0})
+	_, _ = io.WriteString(hasher, request.URL.RawQuery)
+	_, _ = hasher.Write([]byte{0})
+	_, _ = hasher.Write(body)
+	return fmt.Sprintf("%x", hasher.Sum(nil)), nil
+}
+
+func validateIdempotentRequestHash(cachedHash, requestHash string) *apierror.APIError {
+	if cachedHash != "" && cachedHash == requestHash {
+		return nil
+	}
+	return apierror.Conflict(
+		apierror.CodeIdempotencyKeyConflict,
+		"Idempotency key was already used with different request parameters",
+	)
+}
+
+func idempotencyProcessingConflict(processingHash, requestHash string) *apierror.APIError {
+	if processingHash != "" && processingHash == requestHash {
+		return apierror.Conflict(
+			apierror.CodeIdempotencyRequestInProgress,
+			"A request with this idempotency key is still processing",
+		)
+	}
+	return apierror.Conflict(
+		apierror.CodeIdempotencyKeyConflict,
+		"Idempotency key was already used with different request parameters",
+	)
+}
+
+func writeCachedIdempotentResponse(c *gin.Context, cached *CachedIdempotentResponse) {
+	status := cached.StatusCode
+	if cached.IsError {
+		status = cached.ErrorStatus
+	}
+	if status == 0 {
+		status = http.StatusOK
+	}
+	c.Data(status, "application/json; charset=utf-8", cached.Data)
+	c.Abort()
+}
+
+func abortIdempotencyUnavailable(c *gin.Context) {
+	apiErr := apierror.New(
+		http.StatusServiceUnavailable,
+		apierror.TypeAPI,
+		apierror.CodeServiceUnavailable,
+		"Idempotency protection is temporarily unavailable",
+	)
+	c.AbortWithStatusJSON(apiErr.Status, apiErr.ToResponse())
+}
+
+func getIdempotentCache(ctx context.Context, rdb *redis.Client, key string) (*CachedIdempotentResponse, error) {
+	val, err := rdb.Get(ctx, key).Result()
+	if errors.Is(err, redis.Nil) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	var cached CachedIdempotentResponse
+	if err := json.Unmarshal([]byte(val), &cached); err != nil {
+		return nil, fmt.Errorf("unmarshal cached response: %w", err)
+	}
+	return &cached, nil
+}
+
+func setIdempotentCache(ctx context.Context, rdb *redis.Client, key string, response *CachedIdempotentResponse, ttlSeconds int) error {
+	data, err := json.Marshal(response)
+	if err != nil {
+		return fmt.Errorf("marshal cached response: %w", err)
+	}
+	return rdb.Set(ctx, key, data, time.Duration(ttlSeconds)*time.Second).Err()
+}
+
+type idempotentResponseWriter struct {
+	gin.ResponseWriter
+	body *bytes.Buffer
+}
+
+func (w *idempotentResponseWriter) Write(b []byte) (int, error) {
+	w.body.Write(b)
+	return w.ResponseWriter.Write(b)
+}
+
+func (w *idempotentResponseWriter) WriteString(s string) (int, error) {
+	w.body.WriteString(s)
+	return w.ResponseWriter.WriteString(s)
+}
+
+func (w *idempotentResponseWriter) ReadFrom(r io.Reader) (int64, error) {
+	return io.Copy(w, r)
+}

package/dist/resources/templates/go-backend/internal/common/middleware/idempotent_test.go

@@ -0,0 +1,83 @@
+package middleware
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"{{module}}/pkg/apierror"
+)
+
+func TestIdempotentRequestHashBindsParametersAndRestoresBody(t *testing.T) {
+	first, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "/test/resources?channel=web", strings.NewReader(`{"value":101}`))
+	if err != nil {
+		t.Fatalf("create first request: %v", err)
+	}
+	firstHash, err := idempotentRequestHash(first, http.MethodPost, "/test/resources")
+	if err != nil {
+		t.Fatalf("hash first request: %v", err)
+	}
+	restored, err := io.ReadAll(first.Body)
+	if err != nil {
+		t.Fatalf("read restored body: %v", err)
+	}
+	if string(restored) != `{"value":101}` {
+		t.Fatalf("restored body = %q", restored)
+	}
+
+	second, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "/test/resources?channel=web", strings.NewReader(`{"value":202}`))
+	if err != nil {
+		t.Fatalf("create second request: %v", err)
+	}
+	secondHash, err := idempotentRequestHash(second, http.MethodPost, "/test/resources")
+	if err != nil {
+		t.Fatalf("hash second request: %v", err)
+	}
+	if firstHash == secondHash {
+		t.Fatal("different request parameters produced the same idempotency fingerprint")
+	}
+}
+
+func TestValidateIdempotentRequestHashRejectsDifferentOrLegacyCache(t *testing.T) {
+	if apiErr := validateIdempotentRequestHash("same", "same"); apiErr != nil {
+		t.Fatalf("equal hashes rejected: %v", apiErr)
+	}
+	for _, cachedHash := range []string{"", "different"} {
+		apiErr := validateIdempotentRequestHash(cachedHash, "current")
+		if apiErr == nil || apiErr.Detail.Code != apierror.CodeIdempotencyKeyConflict {
+			t.Fatalf("cached hash %q error = %+v", cachedHash, apiErr)
+		}
+	}
+}
+
+func TestIdempotencyProcessingConflictDistinguishesRetryFromKeyReuse(t *testing.T) {
+	inProgress := idempotencyProcessingConflict("same", "same")
+	if inProgress.Detail.Code != apierror.CodeIdempotencyRequestInProgress {
+		t.Fatalf("same request code = %q", inProgress.Detail.Code)
+	}
+	conflict := idempotencyProcessingConflict("first", "second")
+	if conflict.Detail.Code != apierror.CodeIdempotencyKeyConflict {
+		t.Fatalf("different request code = %q", conflict.Detail.Code)
+	}
+}
+
+func TestIdempotentFailsClosedWithoutRedis(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.POST("/orders", Idempotent(nil, IdempotentOptions{}), func(c *gin.Context) {
+		c.Status(http.StatusCreated)
+	})
+	request := httptest.NewRequest(http.MethodPost, "/orders", strings.NewReader(`{"price_id":101}`))
+	request.Header.Set("X-Idempotency-Key", "checkout_test")
+	recorder := httptest.NewRecorder()
+
+	router.ServeHTTP(recorder, request)
+
+	if recorder.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status = %d, want %d", recorder.Code, http.StatusServiceUnavailable)
+	}
+}

package/dist/resources/templates/go-backend/internal/common/middleware/internal_route_permission.go

@@ -0,0 +1,45 @@
+package middleware
+
+import (
+	"fmt"
+
+	"github.com/gin-gonic/gin"
+
+	"{{module}}/internal/common/internalapi"
+	"{{module}}/pkg/apierror"
+)
+
+// RequireInternalRouteResourcePermission 按 method + Gin FullPath 执行内部路由资源授权。
+func RequireInternalRouteResourcePermission(authz ResourceAuthorizer, policies internalapi.RoutePermissionPolicySet) gin.HandlerFunc {
+	handlers := make(map[internalapi.RoutePermissionKey]gin.HandlerFunc, len(policies))
+	for key, policy := range policies {
+		normalizedKey, err := internalapi.CanonicalRoutePermissionKey(key.Method, key.RouteName)
+		if err != nil {
+			panic(fmt.Sprintf("invalid internal route permission policy %s %s: %v", key.Method, key.RouteName, err))
+		}
+		opts := make([]ResourcePermissionOption, 0, 1)
+		if policy.DecisionLogRisk != "" {
+			opts = append(opts, WithDecisionLogRisk(policy.DecisionLogRisk))
+		}
+		handlers[normalizedKey] = RequireResourcePermission(authz, policy.Action, policy.Resource, opts...)
+	}
+
+	return func(c *gin.Context) {
+		if authz == nil {
+			abortWithAPIError(c, apierror.Internal("Authorization service is not configured"))
+			return
+		}
+
+		key, err := internalapi.CanonicalRoutePermissionKey(c.Request.Method, c.FullPath())
+		if err != nil {
+			abortWithAPIError(c, apierror.Forbidden("Internal route permission policy is not registered"))
+			return
+		}
+		handler, ok := handlers[key]
+		if !ok {
+			abortWithAPIError(c, apierror.Forbidden("Internal route permission policy is not registered"))
+			return
+		}
+		handler(c)
+	}
+}

package/dist/resources/templates/go-backend/internal/common/middleware/internal_route_permission_test.go

@@ -0,0 +1,186 @@
+package middleware
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+
+	"{{module}}/internal/common/iamscope"
+	"{{module}}/internal/common/internalapi"
+	"{{module}}/internal/common/types"
+	iamdomain "{{module}}/internal/integrations/onex/iam"
+)
+
+func TestRequireInternalRouteResourcePermissionFailsClosedForUnknownRoute(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	authorizer := &routePermissionAuthorizer{allowed: true}
+	handled := false
+	engine, group := newInternalPermissionRouter(authorizer, internalapi.RoutePermissionPolicySet{})
+	group.GET("/unregistered", func(c *gin.Context) {
+		handled = true
+		c.Status(http.StatusNoContent)
+	})
+
+	response := performRequest(engine, http.MethodGet, "/internal/v1/unregistered")
+
+	require.Equal(t, http.StatusForbidden, response.Code)
+	require.False(t, handled)
+	require.Empty(t, authorizer.requests)
+}
+
+func TestRequireInternalRouteResourcePermissionAllowsPolicy(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	authorizer := &routePermissionAuthorizer{allowed: true}
+	handled := false
+	engine, group := newInternalPermissionRouter(authorizer, internalapi.RoutePermissionPolicySet{
+		{Method: http.MethodPost, RouteName: "/internal/v1/test"}: {
+			Action:   "order:order:create",
+			Resource: "onex:product:{product_code}:order:order/*",
+		},
+	})
+	group.POST("/test", func(c *gin.Context) {
+		handled = true
+		c.Status(http.StatusNoContent)
+	})
+
+	response := performRequest(engine, http.MethodPost, "/internal/v1/test")
+
+	require.Equal(t, http.StatusNoContent, response.Code)
+	require.True(t, handled)
+	require.Len(t, authorizer.requests, 1)
+	require.Equal(t, "order:order:create", authorizer.requests[0].Action)
+	require.Equal(t, "onex:product:catalog:order:order/*", authorizer.requests[0].Resource)
+	require.Equal(t, "/internal/v1/test", authorizer.requests[0].Context.Request.RouteName)
+	require.Equal(t, "catalog", authorizer.requests[0].Context.Workspace.ProductCode)
+}
+
+func TestRequireInternalRouteResourcePermissionCanonicalizesGinParameters(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	authorizer := &routePermissionAuthorizer{allowed: true}
+	engine, group := newInternalPermissionRouter(authorizer, internalapi.RoutePermissionPolicySet{
+		{Method: http.MethodGet, RouteName: "/internal/v1/orders/{orderNo}"}: {
+			Action:   "order:order:read",
+			Resource: "onex:product:{product_code}:order:order/*",
+		},
+	})
+	group.GET("/orders/:orderNo", func(c *gin.Context) {
+		c.Status(http.StatusNoContent)
+	})
+
+	response := performRequest(engine, http.MethodGet, "/internal/v1/orders/ord_1")
+
+	require.Equal(t, http.StatusNoContent, response.Code)
+	require.Len(t, authorizer.requests, 1)
+	require.Equal(t, "/internal/v1/orders/:orderNo", authorizer.requests[0].Context.Request.RouteName)
+}
+
+func TestRequireInternalRouteResourcePermissionDeniesDecision(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	authorizer := &routePermissionAuthorizer{allowed: false}
+	handled := false
+	engine, group := newInternalPermissionRouter(authorizer, internalapi.RoutePermissionPolicySet{
+		{Method: http.MethodPost, RouteName: "/internal/v1/test"}: {
+			Action:   "order:order:create",
+			Resource: "onex:product:{product_code}:order:order/*",
+		},
+	})
+	group.POST("/test", func(c *gin.Context) {
+		handled = true
+		c.Status(http.StatusNoContent)
+	})
+
+	response := performRequest(engine, http.MethodPost, "/internal/v1/test")
+
+	require.Equal(t, http.StatusForbidden, response.Code)
+	require.False(t, handled)
+	require.Len(t, authorizer.requests, 1)
+}
+
+func newInternalPermissionRouter(
+	authorizer ResourceAuthorizer,
+	policies internalapi.RoutePermissionPolicySet,
+) (*gin.Engine, *gin.RouterGroup) {
+	engine := gin.New()
+	engine.Use(func(c *gin.Context) {
+		c.Set(string(types.ContextKeyProductCode), types.Product("catalog"))
+		SetAuthenticatedIAMPrincipal(c, &AuthenticatedIAMPrincipal{
+			PrincipalID:   42,
+			PrincipalType: string(iamdomain.PrincipalTypeServiceAccount),
+			SourceIP:      "127.0.0.1",
+		})
+		c.Next()
+	})
+	group := engine.Group("/internal/v1", RequireInternalRouteResourcePermission(authorizer, policies))
+	return engine, group
+}
+
+func performRequest(router http.Handler, method string, path string) *httptest.ResponseRecorder {
+	request := httptest.NewRequest(method, path, nil)
+	response := httptest.NewRecorder()
+	router.ServeHTTP(response, request)
+	return response
+}
+
+type routePermissionAuthorizer struct {
+	allowed  bool
+	requests []iamdomain.EvaluateRequest
+}
+
+func (a *routePermissionAuthorizer) ResolvePrincipalByIdentity(context.Context, int64) (*iamdomain.PrincipalRecord, error) {
+	return nil, iamdomain.ErrPrincipalNotFound
+}
+
+func (a *routePermissionAuthorizer) AssembleAdminAccessContext(
+	_ context.Context,
+	principal *iamdomain.PrincipalRecord,
+	input iamdomain.AdminAccessContextInput,
+) (iamdomain.AdminAccessContext, error) {
+	return iamdomain.AdminAccessContext{
+		Principal: iamdomain.PrincipalContext{
+			PrincipalID:   principal.ID,
+			PrincipalType: principal.PrincipalType,
+			SourceIP:      input.Principal.SourceIP,
+		},
+		Workspace: input.Workspace,
+		Request:   input.Request,
+		Resource:  input.Resource,
+	}, nil
+}
+
+func (a *routePermissionAuthorizer) Evaluate(_ context.Context, req iamdomain.EvaluateRequest) (iamdomain.Decision, error) {
+	a.requests = append(a.requests, req)
+	if a.allowed {
+		return iamdomain.NewAllowedDecision(req.Action, req.Resource, nil), nil
+	}
+	return iamdomain.NewDeniedDecision(req.Action, req.Resource, iamdomain.ReasonNoMatchingAllow, nil, "denied"), nil
+}
+
+func (a *routePermissionAuthorizer) EvaluateMany(_ context.Context, reqs []iamdomain.EvaluateRequest) ([]iamdomain.Decision, error) {
+	decisions := make([]iamdomain.Decision, len(reqs))
+	for i := range reqs {
+		if a.allowed {
+			decisions[i] = iamdomain.NewAllowedDecision(reqs[i].Action, reqs[i].Resource, nil)
+			continue
+		}
+		decisions[i] = iamdomain.NewDeniedDecision(reqs[i].Action, reqs[i].Resource, iamdomain.ReasonNoMatchingAllow, nil, "denied")
+	}
+	return decisions, nil
+}
+
+func (a *routePermissionAuthorizer) ResolveScope(context.Context, int64, string, iamdomain.WorkspaceContext) (iamscope.ScopeConstraint, error) {
+	return iamscope.NewUnboundedScope(), nil
+}
+
+func (a *routePermissionAuthorizer) ResolveProductScopes(context.Context, int64, string) ([]string, bool, error) {
+	return nil, true, nil
+}
+
+var _ ResourceAuthorizer = (*routePermissionAuthorizer)(nil)