API Conventions¶

// apps/api/internal/middleware/error_mapper.go
func errorToHTTP(err error) (int, string, string) {
    switch {
    case errors.Is(err, domain.ErrNotFound):
        return 404, "NOT_FOUND", "리소스를 찾을 수 없습니다"
    case errors.Is(err, domain.ErrPermissionDenied):
        return 403, "PERMISSION_DENIED", "권한이 없습니다"
    case errors.Is(err, billing.ErrPlanLimitExceeded):
        return 409, "PLAN_LIMIT_EXCEEDED", "플랜 한도를 초과했습니다"
    case errors.Is(err, restore.ErrAlreadyInProgress):
        return 409, "RESTORE_ALREADY_IN_PROGRESS", "이미 진행 중인 복구가 있습니다"
    ...
    default:
        return 500, "INTERNAL", "서버 오류"
    }
}

// apps/api/internal/handler/subscription.go
type SubscriptionHandler struct {
    billingSvc  billing.Service
    logger      *slog.Logger
}

// StartSubscription godoc
// @Summary Start a new subscription
// @Description Start a Pro subscription for a guild
// @Tags subscriptions
// @Accept json
// @Produce json
// @Param request body StartSubscriptionRequest true "Subscription details"
// @Success 201 {object} SubscriptionResponse
// @Failure 400 {object} ErrorResponse
// @Failure 401 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 409 {object} ErrorResponse
// @Router /subscriptions [post]
// @Security CookieAuth
func (h *SubscriptionHandler) StartSubscription(c echo.Context) error {
    ctx := c.Request().Context()

    // 1. Bind & validate
    var req StartSubscriptionRequest
    if err := c.Bind(&req); err != nil {
        return NewValidationError(err)
    }
    if err := req.Validate(); err != nil {
        return NewValidationError(err)
    }

    // 2. Auth
    userID := getAuthenticatedUserID(ctx)
    if userID == uuid.Nil { return domain.ErrUnauthenticated }

    // 3. Domain call
    sub, err := h.billingSvc.StartSubscription(ctx, billing.StartInput{
        PayerUserID:   userID,
        GuildID:       req.GuildID,
        PlanCode:      req.PlanCode,
        AuthKey:       req.AuthKey,
        CustomerKey:   req.CustomerKey,
    })
    if err != nil { return err }  // middleware 가 HTTP 변환

    // 4. Response
    return c.JSON(201, toSubscriptionResponse(sub))
}

type SubscriptionResponse struct {
    ID                string    `json:"id"`
    Status            string    `json:"status"`
    PlanCode          string    `json:"plan_code"`
    CurrentPeriodEnd  time.Time `json:"current_period_end"`
    NextBillingAt     time.Time `json:"next_billing_at"`
    CancelAtPeriodEnd bool      `json:"cancel_at_period_end"`
}

func toSubscriptionResponse(sub *domain.Subscription, planCode string) SubscriptionResponse {
    return SubscriptionResponse{
        ID:               sub.ID.String(),
        Status:           string(sub.Status),
        PlanCode:         planCode,
        CurrentPeriodEnd: *sub.CurrentPeriodEnd,
        NextBillingAt:    *sub.NextBillingAt,
        CancelAtPeriodEnd: sub.CancelAtPeriodEnd,
    }
}

type StartSubscriptionRequest struct {
    GuildID     uuid.UUID `json:"guild_id" validate:"required"`
    PlanCode    string    `json:"plan_code" validate:"required,oneof=PRO ENTERPRISE"`
    AuthKey     string    `json:"auth_key" validate:"required"`
    CustomerKey string    `json:"customer_key" validate:"required"`
}

func (r *StartSubscriptionRequest) Validate() error {
    return validate.Struct(r)
}

func SessionMiddleware(sessions SessionStore) echo.MiddlewareFunc {
    return func(next echo.HandlerFunc) echo.HandlerFunc {
        return func(c echo.Context) error {
            sessID, err := c.Cookie("umbra_session")
            if err != nil { return next(c) }

            sess, err := sessions.Get(c.Request().Context(), sessID.Value)
            if err != nil || sess == nil { return next(c) }

            // Inject user into context
            ctx := ctxpkg.WithUser(c.Request().Context(), sess.User)
            c.SetRequest(c.Request().WithContext(ctx))
            return next(c)
        }
    }
}

// Inline example
func (h *Handler) CreateSnapshot(c echo.Context) error {
    ctx := c.Request().Context()
    userID := getAuthenticatedUserID(ctx)
    guildID := parseUUID(c.Param("guild_id"))

    // Discord permission 체크 (caching 포함)
    if !h.permission.HasManageGuild(ctx, userID, guildID) {
        return domain.ErrPermissionDenied
    }

    // ... domain call
}

// CreateSnapshot godoc
// @Summary Create a snapshot
// @Description Create a manual snapshot for a guild
// @Tags snapshots
// @Accept json
// @Produce json
// @Param guild_id path string true "Guild ID"
// @Param request body CreateSnapshotRequest false "Snapshot details"
// @Success 201 {object} SnapshotResponse
// @Failure 400 {object} ErrorResponse
// @Failure 403 {object} ErrorResponse
// @Failure 409 {object} ErrorResponse
// @Router /guilds/{guild_id}/snapshots [post]
// @Security CookieAuth

e.Use(middleware.RequestID())
e.Use(middleware.Recover())
e.Use(middleware.CORS())
e.Use(middleware.Gzip())
e.Use(LoggerMiddleware(logger))
e.Use(TelemetryMiddleware())       // OpenTelemetry
e.Use(SessionMiddleware(sessions)) // Cookie → User
e.Use(RateLimitMiddleware(redis))  // Optional per route

// Routes
registerRoutes(e, handlers)

// Error handler (맨 마지막)
e.HTTPErrorHandler = ErrorHandler

func ErrorHandler(err error, c echo.Context) {
    status, code, msg := errorToHTTP(err)
    requestID := c.Response().Header().Get(echo.HeaderXRequestID)

    c.JSON(status, ErrorResponse{
        Error: ErrorDetail{
            Code:      code,
            Message:   msg,
            RequestID: requestID,
        },
    })

    // Log server errors
    if status >= 500 {
        logger.Error("handler error",
            "error", err,
            "request_id", requestID,
            "path", c.Request().URL.Path,
        )
    }
}

func RateLimitMiddleware(redis *redis.Client) echo.MiddlewareFunc {
    limiter := redislimiter.NewSlidingWindow(...)
    return func(next echo.HandlerFunc) echo.HandlerFunc {
        return func(c echo.Context) error {
            key := "rl:" + c.RealIP() + ":" + c.Path()
            allowed, err := limiter.Allow(c.Request().Context(), key)
            if err != nil { return next(c) }  // fail open
            if !allowed { return echo.NewHTTPError(429, "rate limited") }
            return next(c)
        }
    }
}

func TestSubscriptionHandler_Start(t *testing.T) {
    mockSvc := &mockBillingService{startResult: &billing.StartResult{...}}
    h := &SubscriptionHandler{billingSvc: mockSvc, logger: testLogger}

    e := echo.New()
    body := `{"guild_id":"018f...","plan_code":"PRO","auth_key":"x","customer_key":"y"}`
    req := httptest.NewRequest(http.MethodPost, "/subscriptions", strings.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    rec := httptest.NewRecorder()
    ctx := e.NewContext(req, rec)

    err := h.StartSubscription(ctx)
    assert.NoError(t, err)
    assert.Equal(t, 201, rec.Code)

    var resp SubscriptionResponse
    json.Unmarshal(rec.Body.Bytes(), &resp)
    assert.Equal(t, "active", resp.Status)
}