クリーンアーキテクチャ設計書¶

// Domain Entities
package domain

import "time"

// RouteDefinition represents an API route mapping
type RouteDefinition struct {
    ID              string
    Path            string            // e.g., "/api/friends/*"
    Method          string            // GET, POST, etc.
    UpstreamURL     string            // e.g., "http://friends-svc:8080"
    Middlewares     []string          // auth, ratelimit, logging, etc.
    TimeoutSeconds  int
    RetryPolicy     *RetryPolicy
    CircuitBreaker  *CircuitBreakerConfig
    CreatedAt       time.Time
    UpdatedAt       time.Time
}

// AuthenticatedRequest represents a validated HTTP request
type AuthenticatedRequest struct {
    RequestID       string
    UserID          string
    Path            string
    Method          string
    Headers         map[string]string
    Body            []byte
    TokenClaims     map[string]interface{}
    Timestamp       time.Time
}

// RateLimitWindow tracks requests within a time window
type RateLimitWindow struct {
    UserID         string
    WindowStart    time.Time
    RequestCount   int
    Limit          int
    WindowSizeMs   int64
}

// BlockedToken represents a revoked JWT
type BlockedToken struct {
    TokenID    string
    UserID     string
    RevokedAt  time.Time
    ExpiresAt  time.Time
}

// CircuitBreakerState manages circuit breaker state
type CircuitBreakerState struct {
    UpstreamURL    string
    State          string // CLOSED, OPEN, HALF_OPEN
    FailureCount   int
    SuccessCount   int
    LastFailureAt  time.Time
    LastSuccessAt  time.Time
    Threshold      int
}

// Value Objects
type JWT struct {
    Token  string
    Claims map[string]interface{}
}

type JWKS struct {
    Keys []map[string]interface{}
}

// Application DTOs
package application

import "time"

// ProcessRequestInput ユースケース入力
type ProcessRequestInput struct {
    Method          string
    Path            string
    Headers         map[string]string
    Body            []byte
    RemoteAddr      string
}

// ProcessRequestOutput ユースケース出力
type ProcessRequestOutput struct {
    StatusCode  int
    Headers     map[string]string
    Body        []byte
    RequestID   string
    ProcessedAt time.Time
}

// AuthenticateRequestInput 認証ユースケース入力
type AuthenticateRequestInput struct {
    AuthorizationHeader string
    RequestID           string
}

// AuthenticateRequestOutput 認証ユースケース出力
type AuthenticateRequestOutput struct {
    UserID      string
    TokenClaims map[string]interface{}
    TokenID     string
}

// CheckRateLimitInput レート制限チェック入力
type CheckRateLimitInput struct {
    UserID   string
    Endpoint string
}

// CheckRateLimitOutput レート制限チェック出力
type CheckRateLimitOutput struct {
    Allowed           bool
    RemainingQuota    int
    ResetAt           time.Time
    RetryAfterSeconds int
}

// CheckPermissionInput 権限チェック入力
type CheckPermissionInput struct {
    UserID   string
    Resource string
    Action   string
}

// CheckPermissionOutput 権限チェック出力
type CheckPermissionOutput struct {
    Allowed bool
    Reason  string
}

// RouteRequestInput ルーティング入力
type RouteRequestInput struct {
    AuthenticatedRequest *AuthenticatedRequest
    RouteDefinition      *RouteDefinition
}

// RouteRequestOutput ルーティング出力
type RouteRequestOutput struct {
    StatusCode int
    Headers    map[string]string
    Body       []byte
}

// Application Ports - Repository Interfaces
package ports

import (
    "context"
    "time"
)

// RouteDefinitionRepository route定義の永続化と取得
type RouteDefinitionRepository interface {
    FindByPathAndMethod(ctx context.Context, path, method string) (*RouteDefinition, error)
    FindAll(ctx context.Context) ([]*RouteDefinition, error)
    Save(ctx context.Context, route *RouteDefinition) error
}

// BlockedTokenRepository ブロックリスト管理
type BlockedTokenRepository interface {
    IsBlocked(ctx context.Context, tokenID string) (bool, error)
    Add(ctx context.Context, tokenID string, expiresAt time.Time) error
    RemoveExpired(ctx context.Context) error
}

// RateLimitRepository レート制限ウィンドウ管理
type RateLimitRepository interface {
    GetWindow(ctx context.Context, userID, endpoint string) (*RateLimitWindow, error)
    IncrementAndCheck(ctx context.Context, userID, endpoint string, limit int, windowMs int64) (bool, int, error)
    ResetWindow(ctx context.Context, userID, endpoint string) error
}

// CircuitBreakerRepository サーキットブレーカー状態管理
type CircuitBreakerRepository interface {
    GetState(ctx context.Context, upstreamURL string) (*CircuitBreakerState, error)
    RecordSuccess(ctx context.Context, upstreamURL string) error
    RecordFailure(ctx context.Context, upstreamURL string) error
    Open(ctx context.Context, upstreamURL string) error
    Reset(ctx context.Context, upstreamURL string) error
}

// JWKSRepository JWKS キャッシュ管理
type JWKSRepository interface {
    Get(ctx context.Context) (*JWKS, error)
    Set(ctx context.Context, jwks *JWKS, ttl time.Duration) error
}

// EventPublisher イベント発行
type EventPublisher interface {
    Publish(ctx context.Context, eventType string, payload map[string]interface{}) error
}

// Application Ports - External Service Interfaces
package ports

import "context"

// CognitoJWKSProvider AWS Cognito JWKS取得
type CognitoJWKSProvider interface {
    GetJWKS(ctx context.Context) (*JWKS, error)
}

// PermissionServiceClient Permission Serviceへの gRPC クライアント
type PermissionServiceClient interface {
    CheckPermission(ctx context.Context, userID, resource, action string) (bool, error)
    CheckUserSuspended(ctx context.Context, userID string) (bool, error)
}

// UpstreamServiceClient バックエンドサービスへのHTTPクライアント
type UpstreamServiceClient interface {
    Do(ctx context.Context, method, url string, headers map[string]string, body []byte) (int, map[string]string, []byte, error)
}

// WebSocketProxyHandler WebSocketプロキシ
type WebSocketProxyHandler interface {
    ProxyWebSocket(ctx context.Context, userID, targetURL string) error
}

// Mappers
package adapters

import "domain"
import "application"

// MapProcessRequestInputToDomain HTTP request → Domain AuthenticatedRequest
func MapProcessRequestInputToDomain(input *ProcessRequestInput, userID string, claims map[string]interface{}) *domain.AuthenticatedRequest {
    return &domain.AuthenticatedRequest{
        RequestID:   generateRequestID(),
        UserID:      userID,
        Path:        input.Path,
        Method:      input.Method,
        Headers:     input.Headers,
        Body:        input.Body,
        TokenClaims: claims,
        Timestamp:   time.Now(),
    }
}

// MapDomainToProcessRequestOutput Domain output → HTTP response
func MapDomainToProcessRequestOutput(output *domain.RouteRequestOutput) *application.ProcessRequestOutput {
    return &application.ProcessRequestOutput{
        StatusCode:  output.StatusCode,
        Headers:     output.Headers,
        Body:        output.Body,
        RequestID:   output.RequestID,
        ProcessedAt: time.Now(),
    }
}

// Infrastructure - Dependency Injection
package infrastructure

import (
    "context"
    "go.uber.org/fx"
    "github.com/redis/go-redis/v9"
    "github.com/gin-gonic/gin"
)

// Module provides all infrastructure dependencies
var Module = fx.Module("infrastructure",
    fx.Provide(
        // Redis
        provideRedisClient,

        // HTTP Client
        provideHTTPClient,

        // AWS SDK (Cognito only — AWS で唯一許可されたサービス)
        provideAWSConfig,
        provideCognitoClient,

        // QueuePort adapter (Beta: Redis+BullMQ, Prod: OCI Queue)
        provideQueueAdapter,

        // gRPC clients
        providePermissionServiceClient,

        // Repositories
        provideBlockedTokenRepository,
        provideRateLimitRepository,
        provideCircuitBreakerRepository,
        provideJWKSRepository,
        provideRouteDefinitionRepository,

        // External Service Adapters
        provideCognitoJWKSAdapter,
        providePermissionServiceAdapter,
        provideUpstreamServiceAdapter,

        // Event Publisher (QueuePort-backed)
        provideQueueEventPublisher,

        // Gin Engine
        provideGinEngine,

        // Controllers
        provideRequestHandler,
        provideWebSocketHandler,

        // Use Cases
        provideProcessRequestUseCase,
        provideAuthenticateRequestUseCase,
        provideCheckRateLimitUseCase,
        provideCheckPermissionUseCase,
        provideRouteRequestUseCase,
        provideBlockTokenUseCase,
        provideReloadRoutesUseCase,
    ),
)

func provideRedisClient() *redis.Client {
    return redis.NewClient(&redis.Options{
        Addr: "redis:6379",
    })
}

func provideGinEngine(
    requestHandler *RequestHandler,
    wsHandler *WebSocketHandler,
) *gin.Engine {
    engine := gin.Default()

    // Mount handlers
    engine.Any("/*path", requestHandler.Handle)
    engine.GET("/ws/*path", wsHandler.Handle)
    engine.GET("/health", healthCheck)
    engine.GET("/metrics", metricsHandler)
    engine.POST("/admin/reload-routes", adminReloadRoutes)

    return engine
}

func main() {
    app := fx.New(
        fx.Module("recerdo-api-gateway",
            infrastructure.Module,
            handlers.Module,
        ),
        fx.Invoke(startServer),
    )
    app.Run()
}

// Unit Tests
package application

import (
    "context"
    "testing"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/mock"
)

// Test Case 1: ProcessRequest - Successful authentication and routing
func TestProcessRequest_Success(t *testing.T) {
    // Arrange
    mockBlockedTokenRepo := new(MockBlockedTokenRepository)
    mockRateLimitRepo := new(MockRateLimitRepository)
    mockPermissionClient := new(MockPermissionServiceClient)
    mockRouteRepo := new(MockRouteDefinitionRepository)
    mockUpstreamClient := new(MockUpstreamServiceClient)

    mockBlockedTokenRepo.On("IsBlocked", mock.Anything, "token-123").Return(false, nil)
    mockRateLimitRepo.On("IncrementAndCheck", mock.Anything, "user-456", "/api/friends", 1000, 60000).Return(true, 999, nil)
    mockPermissionClient.On("CheckPermission", mock.Anything, "user-456", "/api/friends", "GET").Return(true, nil)
    mockRouteRepo.On("FindByPathAndMethod", mock.Anything, "/api/friends", "GET").Return(&domain.RouteDefinition{
        UpstreamURL: "http://friends-svc:8080",
    }, nil)
    mockUpstreamClient.On("Do", mock.Anything, "GET", mock.Anything, mock.Anything, mock.Anything).Return(200, map[string]string{}, []byte(`{"friends": []}`), nil)

    useCase := NewProcessRequestUseCase(
        mockBlockedTokenRepo,
        mockRateLimitRepo,
        mockPermissionClient,
        mockRouteRepo,
        mockUpstreamClient,
    )

    input := &ProcessRequestInput{
        Method:  "GET",
        Path:    "/api/friends",
        Headers: map[string]string{"Authorization": "Bearer token-123"},
    }

    // Act
    output, err := useCase.Execute(context.Background(), input)

    // Assert
    assert.NoError(t, err)
    assert.Equal(t, 200, output.StatusCode)
    assert.Equal(t, `{"friends": []}`, string(output.Body))
    mockBlockedTokenRepo.AssertCalled(t, "IsBlocked", mock.Anything, "token-123")
}

// Test Case 2: ProcessRequest - Token in blocked list
func TestProcessRequest_TokenBlocked(t *testing.T) {
    mockBlockedTokenRepo := new(MockBlockedTokenRepository)
    mockBlockedTokenRepo.On("IsBlocked", mock.Anything, "token-blocked").Return(true, nil)

    useCase := NewProcessRequestUseCase(mockBlockedTokenRepo, nil, nil, nil, nil)

    input := &ProcessRequestInput{
        Method:  "GET",
        Path:    "/api/friends",
        Headers: map[string]string{"Authorization": "Bearer token-blocked"},
    }

    // Act
    output, err := useCase.Execute(context.Background(), input)

    // Assert
    assert.Error(t, err)
    assert.Equal(t, 401, output.StatusCode)
    assert.Contains(t, string(output.Body), "token revoked")
}

// Test Case 3: CheckRateLimit - Quota exceeded
func TestCheckRateLimit_QuotaExceeded(t *testing.T) {
    mockRateLimitRepo := new(MockRateLimitRepository)
    mockRateLimitRepo.On("IncrementAndCheck", mock.Anything, "user-999", "/api/friends", 100, 60000).Return(false, 0, nil)

    useCase := NewCheckRateLimitUseCase(mockRateLimitRepo)

    input := &CheckRateLimitInput{
        UserID:   "user-999",
        Endpoint: "/api/friends",
    }

    // Act
    output, err := useCase.Execute(context.Background(), input)

    // Assert
    assert.NoError(t, err)
    assert.False(t, output.Allowed)
    assert.Equal(t, 0, output.RemainingQuota)
}

// Integration Test: Redis RateLimitRepository
func TestRedisRateLimitRepository_Integration(t *testing.T) {
    // Use testcontainers for Redis
    ctx := context.Background()
    container, err := createRedisContainer(ctx)
    assert.NoError(t, err)
    defer container.Terminate(ctx)

    client := redis.NewClient(&redis.Options{
        Addr: "localhost:6379",
    })
    repo := NewRedisRateLimitRepository(client)

    // Act: First request
    allowed1, remaining1, err := repo.IncrementAndCheck(ctx, "user-123", "api", 5, 60000)
    assert.NoError(t, err)
    assert.True(t, allowed1)
    assert.Equal(t, 4, remaining1)

    // Act: Fill up quota
    for i := 0; i < 4; i++ {
        allowed, _, _ := repo.IncrementAndCheck(ctx, "user-123", "api", 5, 60000)
        assert.True(t, allowed)
    }

    // Act: Exceed quota
    allowed6, _, err := repo.IncrementAndCheck(ctx, "user-123", "api", 5, 60000)
    assert.NoError(t, err)
    assert.False(t, allowed6)
}