@stackonward/cli 1.7.0 → 1.8.0

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/client.go

@@ -0,0 +1,453 @@
+package v1
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"mime"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"{{module}}/internal/common/internalservice"
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/core/httpclient"
+)
+
+const (
+	maximumConfirmedObjectEncodedBytes = ((1 << 20) + 2) / 3 * 4
+	maximumResponseEnvelopeBytes       = 4 << 10
+	defaultMaxResponseBytes            = maximumConfirmedObjectEncodedBytes + maximumResponseEnvelopeBytes
+	maximumRequestIDBytes              = 128
+)
+
+var productCodePattern = regexp.MustCompile(`^[a-z][a-z0-9_-]{1,63}$`)
+
+// Config 定义 OneX internal v1 HTTP 边界的不可变运行参数。
+type Config struct {
+	BaseURL          string
+	ProductCode      string
+	Timeout          time.Duration
+	MaxResponseBytes int
+	SafeReadRetry    SafeReadRetryConfig
+	OperationRetries map[string]int
+	RetryWaiter      RetryWaiter
+	Dependency       DependencyExecutor
+}
+
+// Call 描述一次带独立 deadline 的 OneX wire 请求。
+type Call struct {
+	Method                  string
+	Path                    string
+	Query                   url.Values
+	UserID                  int64
+	RequestID               string
+	IdempotencyKey          string
+	Body                    any
+	ExpectedStatuses        []int
+	RequiredResponseHeaders map[string]string
+	Timeout                 time.Duration
+	Dependency              string
+	Operation               string
+}
+
+// Client 统一执行 OneX internal v1 认证、可信头和严格响应解码。
+type Client struct {
+	httpClient       *httpclient.Client
+	signer           internalservice.Signer
+	baseURL          string
+	productCode      string
+	maxResponseBytes int
+	defaultTimeout   time.Duration
+	safeReadRetry    SafeReadRetryConfig
+	operationRetries map[string]int
+	retryWaiter      RetryWaiter
+	dependency       DependencyExecutor
+}
+
+// NewClient 构造不跟随重定向、仅按显式策略重试安全读取的 OneX v1 专用客户端。
+func NewClient(client *httpclient.Client, signer internalservice.Signer, config Config) (*Client, error) {
+	if client == nil || signer == nil {
+		return nil, fmt.Errorf("onex v1 http client and signer are required")
+	}
+	baseURL, err := validateBaseURL(config.BaseURL)
+	if err != nil {
+		return nil, err
+	}
+	productCode := strings.TrimSpace(config.ProductCode)
+	if productCode == "" || productCode != config.ProductCode || !productCodePattern.MatchString(productCode) {
+		return nil, fmt.Errorf("onex v1 product code is invalid")
+	}
+	if config.Timeout < 0 {
+		return nil, fmt.Errorf("onex v1 timeout is invalid")
+	}
+	operationRetries := make(map[string]int, len(config.OperationRetries))
+	maximumRetries := config.SafeReadRetry.MaxRetries
+	for key, retries := range config.OperationRetries {
+		parts := strings.Split(key, ".")
+		if len(parts) != 2 {
+			return nil, fmt.Errorf("onex v1 operation retry key is invalid")
+		}
+		canonical, keyErr := dependencyOperationKey(parts[0], parts[1])
+		if keyErr != nil || canonical != key || retries < 0 || retries > maximumSafeReadRetries {
+			return nil, fmt.Errorf("onex v1 operation retry policy is invalid")
+		}
+		operationRetries[key] = retries
+		if retries > maximumRetries {
+			maximumRetries = retries
+		}
+	}
+	retryPolicy := config.SafeReadRetry
+	retryPolicy.MaxRetries = maximumRetries
+	if err := validateSafeReadRetryConfig(retryPolicy); err != nil {
+		return nil, err
+	}
+	if maximumRetries > 0 && config.Timeout <= 0 {
+		return nil, fmt.Errorf("onex v1 safe read retry requires a bounded timeout")
+	}
+	maxResponseBytes := config.MaxResponseBytes
+	if maxResponseBytes == 0 {
+		maxResponseBytes = defaultMaxResponseBytes
+	}
+	if maxResponseBytes < 1024 {
+		return nil, fmt.Errorf("onex v1 response limit is invalid")
+	}
+	derived := client.WithOptions(httpclient.Options{
+		Timeout:         config.Timeout,
+		RedirectPolicy:  httpclient.PreserveRedirectResponsePolicy(),
+		EnableLogging:   false,
+		URLLogSanitizer: func(string) string { return "onex://internal/v1" },
+	})
+	derived.Resty().SetResponseBodyLimit(maxResponseBytes)
+	retryWaiter := config.RetryWaiter
+	if retryWaiter == nil {
+		retryWaiter = timerRetryWaiter{}
+	}
+	return &Client{
+		httpClient:       derived,
+		signer:           signer,
+		baseURL:          baseURL,
+		productCode:      productCode,
+		maxResponseBytes: maxResponseBytes,
+		defaultTimeout:   config.Timeout,
+		safeReadRetry:    config.SafeReadRetry,
+		operationRetries: operationRetries,
+		retryWaiter:      retryWaiter,
+		dependency:       config.Dependency,
+	}, nil
+}
+
+// Do 执行一次请求，并将成功响应严格解码到 out。
+func (c *Client) Do(ctx context.Context, call Call, out any) error {
+	if c == nil {
+		return NewValidationError("onex_client_unavailable")
+	}
+	call.Query = cloneQueryValues(call.Query)
+	if err := validateCall(call, out); err != nil {
+		return err
+	}
+	requestCtx, cancel := operationContext(ctx, call.Timeout, c.defaultTimeout)
+	defer cancel()
+	if call.RequestID != "" && !validRequestID(call.RequestID) {
+		return NewValidationError("onex_request_id_invalid")
+	}
+	headers, err := c.signer.AuthHeaders(requestCtx)
+	if err != nil {
+		return mapAuthenticationError(requestCtx, err)
+	}
+	requestHeaders, err := canonicalServiceHeaders(headers)
+	if err != nil {
+		return err
+	}
+	requestHeaders["Content-Type"] = "application/json"
+	requestHeaders["Accept"] = "application/json"
+	requestHeaders[types.HeaderOneXProductCode] = c.productCode
+	if call.UserID > 0 {
+		requestHeaders[types.HeaderInternalUserID] = strconv.FormatInt(call.UserID, 10)
+	}
+	if call.RequestID != "" {
+		requestHeaders[types.HeaderRequestID] = call.RequestID
+	}
+	if call.IdempotencyKey != "" {
+		requestHeaders[types.HeaderIdempotencyKey] = call.IdempotencyKey
+	}
+	var body []byte
+	if call.Body != nil {
+		body, err = json.Marshal(call.Body)
+		if err != nil {
+			return &Error{Kind: ErrorKindValidation, Code: "onex_request_encoding_failed", cause: err}
+		}
+	}
+	requestURL, err := url.Parse(c.baseURL + call.Path)
+	if err != nil {
+		return &Error{Kind: ErrorKindContract, Code: "onex_request_url_invalid", cause: err}
+	}
+	requestURL.RawQuery = call.Query.Encode()
+	operation := func(executionCtx context.Context) error {
+		response, executionErr := c.execute(executionCtx, call, requestURL.String(), body, requestHeaders)
+		if executionErr != nil {
+			return mapTransportError(executionCtx, call.Method, executionErr)
+		}
+		if len(response.Body) > c.maxResponseBytes {
+			return &Error{Kind: ErrorKindContract, Code: "onex_response_too_large", HTTPStatus: response.StatusCode}
+		}
+		if !containsStatus(call.ExpectedStatuses, response.StatusCode) {
+			return decodeHTTPError(response)
+		}
+		if headerErr := requireResponseHeaders(response.Headers, call.RequiredResponseHeaders); headerErr != nil {
+			return &Error{Kind: ErrorKindContract, Code: "onex_response_headers_invalid", HTTPStatus: response.StatusCode, cause: headerErr}
+		}
+		if response.StatusCode == http.StatusNoContent {
+			if len(response.Body) != 0 {
+				return &Error{Kind: ErrorKindContract, Code: "onex_response_contract_invalid", HTTPStatus: response.StatusCode}
+			}
+			return nil
+		}
+		if contentTypeErr := requireJSONContentType(response.Headers); contentTypeErr != nil {
+			return &Error{Kind: ErrorKindContract, Code: "onex_response_content_type_invalid", HTTPStatus: response.StatusCode, cause: contentTypeErr}
+		}
+		if decodeErr := DecodeStrict(response.Body, out); decodeErr != nil {
+			return &Error{Kind: ErrorKindContract, Code: "onex_response_contract_invalid", HTTPStatus: response.StatusCode, cause: decodeErr}
+		}
+		return nil
+	}
+	if c.dependency == nil {
+		return operation(requestCtx)
+	}
+	key, err := dependencyOperationKey(call.Dependency, call.Operation)
+	if err != nil {
+		return NewContractError("onex_dependency_operation_invalid", err)
+	}
+	attempted, err := c.dependency.Execute(requestCtx, key, operation)
+	if err == nil {
+		return nil
+	}
+	if attempted {
+		return err
+	}
+	return &Error{Kind: ErrorKindUnavailable, Code: "onex_dependency_unavailable", Retryable: true, cause: err}
+}
+
+func (c *Client) execute(ctx context.Context, call Call, requestURL string, body []byte, headers map[string]string) (*httpclient.Response, error) {
+	retryLimit := c.safeReadRetry.MaxRetries
+	if key, err := dependencyOperationKey(call.Dependency, call.Operation); err == nil {
+		if configured, exists := c.operationRetries[key]; exists {
+			retryLimit = configured
+		}
+	}
+	for retryNumber := 0; ; retryNumber++ {
+		response, err := c.httpClient.DoOnceWithHeaders(ctx, call.Method, requestURL, body, nil, headers)
+		if call.Method != http.MethodGet || retryNumber >= retryLimit || !retryableSafeReadResult(ctx, response, err) {
+			return response, err
+		}
+		retryAfter := ""
+		if response != nil {
+			retryAfter = response.Headers.Get(types.HeaderRetryAfter)
+		}
+		delay := safeReadRetryDelay(c.safeReadRetry, retryNumber+1, retryAfter, time.Now().UTC())
+		if deadline, ok := ctx.Deadline(); ok && delay >= time.Until(deadline) {
+			return response, err
+		}
+		if waitErr := c.retryWaiter.Wait(ctx, delay); waitErr != nil {
+			return nil, waitErr
+		}
+	}
+}
+
+func retryableSafeReadResult(ctx context.Context, response *httpclient.Response, err error) bool {
+	if ctx.Err() != nil {
+		return false
+	}
+	if err != nil {
+		return true
+	}
+	return response != nil && shouldRetrySafeReadStatus(response.StatusCode)
+}
+
+func operationContext(ctx context.Context, operationTimeout, defaultTimeout time.Duration) (context.Context, context.CancelFunc) {
+	timeout := operationTimeout
+	if timeout == 0 {
+		timeout = defaultTimeout
+	}
+	if timeout <= 0 {
+		return context.WithCancel(ctx)
+	}
+	return context.WithTimeout(ctx, timeout)
+}
+
+func canonicalServiceHeaders(headers map[string]string) (map[string]string, error) {
+	if len(headers) != 1 {
+		return nil, NewContractError("onex_authentication_contract_invalid", nil)
+	}
+	authorization := ""
+	for name, value := range headers {
+		if !strings.EqualFold(name, "Authorization") {
+			return nil, NewContractError("onex_authentication_contract_invalid", nil)
+		}
+		authorization = value
+	}
+	const prefix = "Bearer "
+	if !strings.HasPrefix(authorization, prefix) || !validHeaderCredential(strings.TrimPrefix(authorization, prefix)) {
+		return nil, NewContractError("onex_authentication_contract_invalid", nil)
+	}
+	return map[string]string{"Authorization": authorization}, nil
+}
+
+func validHeaderCredential(value string) bool {
+	if value == "" || len(value) > 8192 {
+		return false
+	}
+	for index := range len(value) {
+		if value[index] < 0x21 || value[index] > 0x7e {
+			return false
+		}
+	}
+	return true
+}
+
+func validRequestID(value string) bool {
+	if value == "" || len(value) > maximumRequestIDBytes || value != strings.TrimSpace(value) {
+		return false
+	}
+	for index := range len(value) {
+		if value[index] < 0x21 || value[index] > 0x7e {
+			return false
+		}
+	}
+	return true
+}
+
+func mapAuthenticationError(ctx context.Context, err error) error {
+	if errors.Is(ctx.Err(), context.Canceled) || errors.Is(err, context.Canceled) {
+		return &Error{Kind: ErrorKindCanceled, Code: "onex_request_canceled", cause: err}
+	}
+	return &Error{Kind: ErrorKindUnavailable, Code: "onex_authentication_unavailable", Retryable: true, cause: err}
+}
+
+func mapTransportError(ctx context.Context, method string, err error) error {
+	if errors.Is(ctx.Err(), context.Canceled) || errors.Is(err, context.Canceled) {
+		return &Error{Kind: ErrorKindCanceled, Code: "onex_request_canceled", cause: err}
+	}
+	if method != http.MethodGet {
+		return &Error{Kind: ErrorKindResultUnknown, Code: "onex_result_unknown", Retryable: true, cause: err}
+	}
+	return &Error{Kind: ErrorKindUnavailable, Code: "onex_request_unavailable", Retryable: true, cause: err}
+}
+
+func validateBaseURL(raw string) (string, error) {
+	value := strings.TrimRight(strings.TrimSpace(raw), "/")
+	parsed, err := url.Parse(value)
+	if err != nil || parsed.Host == "" || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.User != nil || parsed.RawQuery != "" || parsed.Fragment != "" {
+		return "", fmt.Errorf("onex v1 base URL is invalid")
+	}
+	if parsed.EscapedPath() != "/internal/v1" {
+		return "", fmt.Errorf("onex v1 base URL must end at /internal/v1")
+	}
+	return value, nil
+}
+
+func validateCall(call Call, out any) error {
+	if call.Method != http.MethodGet && call.Method != http.MethodPost && call.Method != http.MethodPut {
+		return NewValidationError("onex_method_invalid")
+	}
+	if !strings.HasPrefix(call.Path, "/") || strings.ContainsAny(call.Path, "?#") || strings.Contains(call.Path, "//") {
+		return NewValidationError("onex_path_invalid")
+	}
+	if err := validateQueryValues(call.Query); err != nil {
+		return NewValidationError("onex_query_invalid")
+	}
+	if call.UserID < 0 || strings.TrimSpace(call.RequestID) != call.RequestID || strings.TrimSpace(call.IdempotencyKey) != call.IdempotencyKey {
+		return NewValidationError("onex_trusted_context_invalid")
+	}
+	noContent := len(call.ExpectedStatuses) == 1 && call.ExpectedStatuses[0] == http.StatusNoContent
+	if len(call.ExpectedStatuses) == 0 || noContent && out != nil || !noContent && (out == nil || containsStatus(call.ExpectedStatuses, http.StatusNoContent)) {
+		return NewValidationError("onex_response_contract_required")
+	}
+	if call.Timeout < 0 || (call.Method == http.MethodGet && (call.Body != nil || call.IdempotencyKey != "")) {
+		return NewValidationError("onex_operation_policy_invalid")
+	}
+	if (call.Dependency == "") != (call.Operation == "") {
+		return NewValidationError("onex_dependency_operation_invalid")
+	}
+	if call.Dependency != "" {
+		if _, err := dependencyOperationKey(call.Dependency, call.Operation); err != nil {
+			return NewValidationError("onex_dependency_operation_invalid")
+		}
+	}
+	return nil
+}
+
+func cloneQueryValues(values url.Values) url.Values {
+	if len(values) == 0 {
+		return nil
+	}
+	cloned := make(url.Values, len(values))
+	for key, items := range values {
+		cloned[key] = append([]string(nil), items...)
+	}
+	return cloned
+}
+
+func validateQueryValues(values url.Values) error {
+	if len(values) > 16 {
+		return fmt.Errorf("query contains too many keys")
+	}
+	totalValues := 0
+	for key, items := range values {
+		if key == "" || len(key) > 128 || key != strings.TrimSpace(key) || !validQueryText(key) {
+			return fmt.Errorf("query key is invalid")
+		}
+		totalValues += len(items)
+		if len(items) == 0 || totalValues > 64 {
+			return fmt.Errorf("query values are invalid")
+		}
+		for _, value := range items {
+			if len(value) > 1024 || !validQueryText(value) {
+				return fmt.Errorf("query value is invalid")
+			}
+		}
+	}
+	if len(values.Encode()) > 8192 {
+		return fmt.Errorf("encoded query is too large")
+	}
+	return nil
+}
+
+func validQueryText(value string) bool {
+	for _, character := range value {
+		if character < 0x20 || character == 0x7f {
+			return false
+		}
+	}
+	return true
+}
+
+func containsStatus(statuses []int, status int) bool {
+	for _, candidate := range statuses {
+		if candidate == status {
+			return true
+		}
+	}
+	return false
+}
+
+func requireJSONContentType(headers http.Header) error {
+	mediaType, _, err := mime.ParseMediaType(headers.Get("Content-Type"))
+	if err != nil || mediaType != "application/json" {
+		return fmt.Errorf("response media type is not application/json")
+	}
+	return nil
+}
+
+func requireResponseHeaders(headers http.Header, required map[string]string) error {
+	for name, expected := range required {
+		if strings.TrimSpace(name) == "" || expected == "" || headers.Get(name) != expected {
+			return fmt.Errorf("required response header is missing or invalid")
+		}
+	}
+	return nil
+}