Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotificationSenderNotInitialized 서비스 시작 시 핵심 의존성 객체인 NotificationSender가 올바르게 초기화되지 않았을 때 반환하는 에러입니다. ErrNotificationSenderNotInitialized = apperrors.New(apperrors.Internal, "NotificationSender 객체가 초기화되지 않았습니다") )
Functions ¶
func NewEchoServer ¶
func NewEchoServer(cfg ServerConfig) *echo.Echo
NewEchoServer 설정된 미들웨어를 포함한 Echo 인스턴스를 생성합니다.
미들웨어는 다음 순서로 적용됩니다 (순서가 중요합니다):
HTTPLogger - HTTP 요청/응답 로깅 - 모든 HTTP 요청과 응답 정보를 구조화된 로그로 기록 - 민감 정보(app_key, password 등)는 자동으로 마스킹 - 요청 처리 시간, 상태 코드, IP 주소 등 기록
PanicRecovery - 패닉 복구 및 로깅 - 핸들러에서 발생한 panic을 복구하여 서버 다운 방지 - 스택 트레이스와 함께 에러를 로깅 - 가장 먼저 적용되어야 다른 미들웨어의 panic도 복구 가능
RequestID - 요청 ID 생성 - 각 요청에 고유한 ID를 부여 (X-Request-ID 헤더) - 로깅 및 디버깅 시 요청 추적에 사용 - 로깅 미들웨어보다 먼저 적용되어야 로그에 request_id 포함 가능
Secure - 보안 헤더 설정 - X-XSS-Protection, X-Content-Type-Options 등 보안 헤더 자동 추가 - XSS, 클릭재킹 등의 공격 방어 - 가장 마지막에 적용되어 모든 응답에 보안 헤더 추가
CORS - Cross-Origin Resource Sharing - 허용된 Origin에서의 크로스 도메인 요청 처리 - Preflight 요청(OPTIONS) 자동 응답 - 프로덕션 환경에서는 특정 도메인만 허용 권장
ServerHeader - Server 헤더 제거 - 응답 헤더에서 Server 필드를 삭제하여 기술 스택 노출 방지 - 공격자가 서버 버전을 파악하여 취약점을 악용하는 것을 어렵게 함 - 보안 감화를 위한 조치 (Security through Obscurity)
RateLimit - IP 기반 요청 제한 - IP 주소별로 초당 요청 수 제한 (기본: 20 req/s, 버스트: 40) - Brute Force 공격 방어 및 서버 리소스 보호 - 제한 초과 시 429 Too Many Requests 응답 - 로깅 전에 적용하여 과도한 로그 생성 방지
BodyLimit - 요청 본문 크기 제한 (초과 시 413 응답) - 대용량 요청으로 인한 메모리 고갈 및 DoS 공격 방지
라우트 설정은 포함되지 않으며, 반환된 Echo 인스턴스에 별도로 설정해야 합니다.
Types ¶
type ServerConfig ¶
type ServerConfig struct {
// Debug Echo 프레임워크의 상세 로깅 및 디버그 모드 활성화 여부
// 활성화 시 상세한 에러 메시지와 스택 트레이스가 응답에 포함될 수 있으므로,
// 운영(Production) 환경에서는 보안상 반드시 비활성화(false)해야 합니다.
Debug bool
// EnableHSTS HSTS(HTTP Strict Transport Security) 보안 헤더 활성화 여부
// 이 설정이 활성화되면 브라우저에게 "앞으로 일정 기간 동안은 무조건 HTTPS로만 접속하라"고 지시하여,
// 프로토콜 다운그레이드 공격(SSL Stripping) 및 쿠키 하이재킹과 같은 중간자 공격(MITM)을 원천 차단합니다.
// TLS(HTTPS) 환경에서는 반드시 활성화(true)하는 것이 강력히 권장됩니다.
EnableHSTS bool
// AllowOrigins CORS(Cross-Origin Resource Sharing) 정책에서 허용할 도메인 목록
// - 개발 환경: ["*"] (모든 출처 허용) 또는 ["http://localhost:3000"]
// - 운영 환경: ["https://example.com"]과 같이 신뢰할 수 있는 특정 도메인만 명시해야 합니다.
// 무분별한 허용은 악의적인 웹사이트가 사용자의 브라우저를 통해 API를 호출하는 보안 위협을 초래할 수 있습니다.
AllowOrigins []string
}
ServerConfig HTTP 서버 생성에 필요한 설정을 정의합니다.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service Notify API 서버(Echo 웹 서버)의 생명주기를 관리하는 서비스입니다.
이 서비스는 다음과 같은 역할을 수행합니다:
- Echo 기반 HTTP/HTTPS 서버 시작 및 종료
- 미들웨어 체인 설정 (PanicRecovery, RequestID, RateLimit, HTTPLogger, CORS, Secure)
- 인증 관리 (Authenticator 생성 및 API 엔드포인트 보호)
- API 엔드포인트 라우팅 설정 (Health Check, Version, 알림 메시지 전송 등)
- Swagger UI 제공
- 커스텀 HTTP 에러 핸들러 설정
- 서비스 상태 관리 (시작/중지)
- Graceful Shutdown 지원 (5초 타임아웃)
- 서버 에러 처리 및 알림 전송 (예상치 못한 에러 발생 시)
서비스는 고루틴으로 실행되며, context를 통해 종료 신호를 받습니다. Start() 메서드로 시작하고, context 취소로 종료됩니다.
func NewService ¶
func NewService(appConfig *config.AppConfig, notificationSender contract.NotificationSender, buildInfo version.Info) *Service
NewService API 서비스를 생성합니다.
func (*Service) Start ¶
Start API 서비스를 시작합니다.
서비스는 별도의 고루틴에서 실행되며, 다음 작업을 수행합니다:
- 서비스 상태 검증 (notificationSender nil 체크, 중복 실행 방지)
- Echo 서버 설정 (Authenticator, Handler, 미들웨어, 라우트)
- HTTP/HTTPS 서버 시작 (별도 고루틴)
- Shutdown 신호 대기
- Graceful Shutdown 처리 (5초 타임아웃)
- 서버 에러 처리 및 알림 전송 (예상치 못한 에러 발생 시)
- 서비스 상태 정리 (running 플래그 초기화)
매개변수:
- serviceStopCtx: 서비스 종료 신호를 받기 위한 Context
- serviceStopWG: 서비스 종료 완료를 알리기 위한 WaitGroup
반환값:
- error: notificationSender가 nil이거나 서비스가 이미 실행 중인 경우
Note: 이 함수는 즉시 반환되며, 실제 서버는 고루틴에서 실행됩니다.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
handler
|
|
|
system
Package system 시스템 엔드포인트 핸들러를 제공합니다.
|
Package system 시스템 엔드포인트 핸들러를 제공합니다. |
|
Package middleware Echo 프레임워크를 위한 HTTP 미들웨어를 제공합니다.
|
Package middleware Echo 프레임워크를 위한 HTTP 미들웨어를 제공합니다. |
|
model
|
|
|
domain
Package domain API 서비스의 핵심 도메인 모델을 정의합니다.
|
Package domain API 서비스의 핵심 도메인 모델을 정의합니다. |
|
Package v1 Notify API의 v1 버전 라우트를 정의하고 설정합니다.
|
Package v1 Notify API의 v1 버전 라우트를 정의하고 설정합니다. |
|
handler
Package handler v1 API의 HTTP 요청 핸들러를 제공합니다.
|
Package handler v1 API의 HTTP 요청 핸들러를 제공합니다. |