Queuing Backend

Spring Boot 4 / Java 21 기반의 실시간 DJing·음악 공유 백엔드다.

루트 구조

• src/main/java/queuing/core
  • global 공통 설정, 예외, 보안, 응답, Redis/JPA 인프라
  • room 방/큐/실시간 재생 도메인
  • user 사용자 조회/인증/프로필 도메인
  • follow 팔로우 관계 도메인
  • friend 상호 팔로우 기반 친구 목록 API
• src/main/resources
  • config 프로필별 설정
  • templates, static, scripts 런타임 리소스
• src/test/java
  • 현재 room 중심 회귀/통합 테스트
• docs
  • frontend-room-websocket-guide.md 프론트 연동 가이드
  • queue-feature-execution-plan.md 큐 저장 구조 정리 문서
  • youtube-queue-integration.md YouTube 메타데이터 연동 메모
• container
  • 로컬 MariaDB/Redis 컨테이너 리소스

핵심 구조 원칙

• room queue의 source of truth는 Redis가 아니라 RDB 다.
• Redis는 참가자 / 세션 / playback / track-end scheduling / delayed room auto-delete reservation 같은 세션성 최신 상태만 담당한다.
• room 도메인은 application / domain / infrastructure / presentation 계층으로 분리한다.

room 관련 Redis key 메모

• 참가자: room:{slug}:participants
• playback: room:{slug}:playback
• 세션 역인덱스: room:{slug}:sessions
• user/session 매핑: room:user_session:{userId}, room:session:{sessionId}
• track-end scheduling: room:track_end:zset, room:{slug}:track_end:member
• auto-delete scheduling: room:auto_delete:zset, room:{slug}:auto_delete:member

track-end cleanup 과 auto-delete cleanup 은 모두 room delete 이후 Redis runtime state 정리 단계에서 멱등하게 실행되도록 설계되어, 이미 사라진 key 를 다시 지워도 실패로 취급하지 않는다.

자주 쓰는 명령

./gradlew test
./gradlew build
./gradlew test --tests '*RoomQueueCommandServicePersistenceTest'
./gradlew test --tests '*RoomSocketServiceTest'

Spring profile configuration

The packaged configuration uses src/main/resources/application.yaml as the common entrypoint. It imports only domain index YAML files under config/core, config/security, and config/external. Domain index files import detail YAML files from the same domain only; detail YAML files must not declare spring.config.import.

Local profile

Run local development with an explicit profile:

SPRING_PROFILES_ACTIVE=local ./gradlew bootRun

Only the local profile carries development defaults such as local MariaDB/Redis endpoints, SQL logging, and ddl-auto=update. OAuth2 and YouTube secrets are not stored in YAML; provide them through environment variables when those features are needed locally.

Dev/prod profiles

dev and prod import optional external files at /config/{profile}/overrides.yaml and /config/{profile}/secrets.yaml. Keep those files outside Git and container images. Required runtime values still fail fast during startup/config validation when they are absent or unsafe.

Required environment variables for shared dev/prod startup:

DATASOURCE_URL
DATASOURCE_USERNAME
DATASOURCE_PASSWORD
REDIS_HOST
REDIS_PORT
GOOGLE_OAUTH2_REDIRECT_BASE_URI
GOOGLE_OAUTH2_CLIENT_ID
GOOGLE_OAUTH2_CLIENT_SECRET
YOUTUBE_API_KEY
CORS_ALLOWED_ORIGINS
REDIRECT_BASE_URL
REDIRECT_ALLOWED_ORIGINS
XSRF_COOKIE_DOMAIN
XSRF_COOKIE_SECURE
SESSION_COOKIE_DOMAIN
SESSION_COOKIE_SECURE
REMEMBER_ME_COOKIE_KEY
ROOM_KICK_IDENTITY_PEPPER

Optional runtime tuning variables with packaged defaults:

YOUTUBE_BASE_URL=https://www.googleapis.com/youtube/v3
YOUTUBE_CONNECT_TIMEOUT=3s
YOUTUBE_READ_TIMEOUT=5s
SESSION_COOKIE_PATH=/
SESSION_COOKIE_HTTP_ONLY=true
REMEMBER_ME_COOKIE_SAME_SITE=LAX
ROOM_DEFAULTS_MAX_PARTICIPANTS=
ROOM_DEFAULTS_TRACK_LIMIT_MINUTES=
ROOM_KICK_BLOCK_TTL=10m
ROOM_AUTO_DELETE_BATCH_SIZE=50
ROOM_TRACK_END_POLL_FIXED_DELAY=500ms
ROOM_TRACK_END_BATCH_SIZE=50
ROOM_CHAT_FLUSH_FIXED_DELAY=500ms
ROOM_CHAT_FLUSH_BATCH_SIZE=100
ROOM_CHAT_PROCESSING_STALE_TIMEOUT=60s
ROOM_SESSION_TTL=3h
ROOM_PRESENCE_EMPTY_ROOM_TTL=1h

For develop and prod deployments, the GitHub Actions environment variable ENV_FILE_PATH points the self-hosted runner to the server-side env file used by nerdctl run --env-file. Keep the file out of Git, do not document actual server paths or values, and restrict access so the deployment runner user owns and reads it without group or other permissions. The workflow verifies that an env-file path is configured; application startup validation then rejects missing or unsafe resolved configuration. SPRING_PROFILES_ACTIVE remains controlled by the GitHub APP_PROFILE variable, and timezone remains set by the workflow.

prod also enforces safer JPA behavior: SQL logging is disabled and schema mutation is not allowed by configuration validation.