feat(storage,logging,docs): 테이블명 설정·상세 로깅·OpenAPI 한글화

[ppzxc]

Summary

• DB 테이블명을 config로 변경 가능하게 (storage.tableName, 기본값 messages)
• INPUT 수신/OUTPUT 송신 상세 로깅 추가 (INFO=요약, DEBUG=전체 body/header)
• OpenAPI 문서 한글화 및 요청/응답 예제·curl 코드 샘플 추가

Motivation

• 동일 DB에 여러 relaybox 인스턴스를 운영할 때 테이블명 충돌 방지
• 운영 환경에서 메시지 흐름 추적을 위한 상세 로깅 필요
• ReDoc에서 예제 없이는 API 사용 방법을 파악하기 어려움

Changes

storage: 테이블명 설정

• StorageConfig.TableName 필드 추가 (정규식 검증: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$)
• SQLite/MariaDB repository에서 sqlc Queries 의존 제거, SQL 직접 관리로 전환 (Tidy First)
• New(dsn, tableName string) / Config.TableName 으로 테이블명 전파
• config 예시 파일에 tableName: messages 주석 추가

logging: 상세 로깅

• handler.go: slog.Info("message received") + slog.Debug (headers, body)
• webhook/sender.go: slog.Info("webhook sent", statusCode, elapsed) + slog.Debug (request/response body, headers)
• relay_worker.go: processing/delivered/failed Info 로그, delivering Debug 로그

docs: OpenAPI 한글화 + 예제

• 모든 summary/description 한글화
• 각 엔드포인트에 요청/응답 JSON example 추가
• 모든 엔드포인트에 x-codeSamples curl 예제 추가
• 에러 응답 example 추가

Test plan

• 빌드 확인 (go build -o relaybox ./cmd/server/)
• 전체 테스트 통과 (go test -race ./... -timeout 60s)
• 정적 분석 통과 (go vet ./...)

[ppzxc]

코드 리뷰 코멘트

전반적으로 견고한 구현입니다. 아래 2개의 non-blocking 이슈와 1개 보안 주의사항을 남깁니다.

---

이슈 1: buildSchemaSQL 내 no-op 라인 — SQLite & MariaDB

mariadb/repository.go buildSchemaSQL:

s := strings.ReplaceAll(schemaTemplate, "messages", tableName)
// 아래 두 줄은 no-op: 이미 첫 번째 ReplaceAll이 처리함
s = strings.ReplaceAll(s, "idx_"+tableName+"_input", "idx_"+tableName+"_input")
s = strings.ReplaceAll(s, "idx_"+tableName+"_created_at", "idx_"+tableName+"_created_at")

sqlite/repository.go buildSchemaSQL도 동일한 no-op 라인 포함. 삭제 권장.

---

이슈 2: captureHandler 테스트 헬퍼 중복

handler_test.go, sender_test.go, relay_worker_test.go 세 파일에 거의 동일한 slog 캡처 핸들러가 각각 정의되어 있습니다. internal/testutil/ 공유 패키지로 통합 권장.

---

보안 주의 3: DEBUG 레벨에서 Authorization 헤더 노출 (by design)

handler.go:

slog.Debug("request received",
    "headers", r.Header,  // Authorization: Bearer <token> 포함
)

DEBUG는 기본 비활성이므로 production에서는 문제 없으나, log.level: DEBUG 사용 시 시크릿이 로그에 기록됩니다. config.example.yaml 주석에 명시 권장.

[ppzxc]

코드 리뷰 — 이전 코멘트 반영 확인

이전 리뷰 코멘트가 모두 깔끔하게 반영되었습니다.

✅ 반영 확인

1. buildSchemaSQL no-op 제거
SQLite, MariaDB 모두 단일 strings.ReplaceAll 한 줄로 정리됨.

2. testutil.CaptureHandler 공유 헬퍼 도입
internal/testutil/slog.go 신설, sync.Mutex 기반 thread-safe 구현.
handler_test.go, sender_test.go, relay_worker_test.go 3곳 중복 정의 제거 완료.

3. config.example.yaml DEBUG 주의 주석
Authorization 헤더 노출 경고 및 운영 환경 권장 레벨 안내 추가.

참고

mariadb/repository.go의 scanMessage / scanMessageRow 두 함수 로직이 동일해 보이나, MariaDB(int32) vs SQLite(int64) 타입 차이로 분리가 불가피 — 허용 가능.