SHttp for Unity

프로젝트 개요

• Unity 내부에서 HTTP/1.1 콘텐츠 전송을 직접 처리하기 위한 로컬 TCP 서버 및 캐싱 컴포넌트 묶음
• 로컬 서버가 원격 자원을 프록시하며 UnityWebRequest, VideoPlayer 등이 요청할 수 있는 형태로 변환
• 범위 요청(HTTP Range)과 디스크 캐시를 통해 대용량 미디어를 부분 스트리밍

주요 기능

• SHttp.Core/Package/Scripts/Server의 SHttpServer가 비동기 소켓으로 수신 대기하고 SHttpContext가 GET 요청과 헤더를 파싱
• 요청 헤더의 Range를 SHttpRequestRange로 해석하고, 응답은 200/206/416 코드 및 Content-Range/Content-Length 헤더를 설정
• SHttp.ContentDelivery/Packages/Scripts/ContentDeliveryService가 요청을 받아 캐시 버킷을 조회하거나 SFramework.WebRequest를 이용해 원본에서 누락된 구간만 다운로드
• BucketManager가 Application.temporaryCachePath/saveFolderName 아래에 SHA-256 경로로 캐시를 보존하고, maxCacheDiskMB 한도를 넘으면 LRU 기준으로 정리
• BucketBufferPool과 DownloadChecker가 스트리밍 버퍼 재사용 및 부분 다운로드 상태를 추적
• 전용 Logger가 전처리기 플래그(SHTTP_LOG_TRACE, SHTTP_LOG_DEBUG, SHTTP_LOG_INFO)에 따라 단계별 로그를 출력

동작 흐름

1. ContentDeliveryServiceBehaviour.StartServer()가 SHttpServer를 시작하고 버킷 관리자, 콘텐츠 서비스, 버킷 정리 스레드를 초기화
2. Unity 측 요청(http://127.0.0.1:{port}/...)이 들어오면 SHttpContext가 헤더를 구성하고 ContentDeliveryService.Work에 전달
3. 해당 URL의 캐시 버킷이 존재하면 필요한 범위를 파일에서 읽어 응답 스트림에 기록
4. 캐시가 비어 있거나 구간이 누락된 경우 SWebRequest로 원본에서 필요한 바이트 범위를 스트리밍 다운로드하면서 즉시 응답에 전송하고, 디스크에도 저장
5. 주기적으로 BucketManager.Update()가 사용하지 않는 버킷을 삭제하고 메타 데이터를 디스크에 저장

디렉터리 구성

• SHttp.Core: 서버, 요청/응답 템플릿, 비동기 네트워크 스트림, 로거 등 핵심 네트워크 계층
• SHttp.ContentDelivery: 버킷 캐시, 콘텐츠 다운로드 파이프라인, Unity MonoBehaviour 진입점
• SHttp.Test: 콘솔 진입점으로 콘텐츠 전송 서비스를 기동하여 동작을 확인
• logo.png, INTRODUCE.md: 프로젝트 소개 자료

의존성 및 빌드

• 타깃 프레임워크: .NET 6 (SHttp.Core.csproj, SHttp.ContentDelivery.csproj)
• Nullability 및 ImplicitUsings 활성화
• 외부 프로젝트: SFramework.SharedLibrary, SFramework.ThreadPool, SFramework.WebRequest, Cysharp.UniTask
• Unity 2021.3 이상 환경에서 ContentDeliveryServiceBehaviour를 MonoBehaviour로 사용할 수 있도록 설계
• 빌드 예시: dotnet build SHttp.sln

사용 방법

• Unity 씬에 ContentDeliveryServiceBehaviour를 배치하거나 런타임에서 ContentDeliveryServiceBehaviour.main.StartServer() 호출
• 필요 시 host, port, saveFolderName, maxCacheDiskMB, autoStart 값을 인스펙터에서 조정
• 클라이언트 코드에서 ContentDeliveryServiceBehaviour.ConvertUrl(originalPath)를 호출해 Unity가 접근할 로컬 URL을 생성
• 모든 자원은 GET으로 요청해야 하며, Range 헤더가 필요한 경우 Unity 쪽 컴포넌트에서 자동으로 전송된 값을 그대로 처리
• 정리 시 ContentDeliveryServiceBehaviour.RemoveAllBuckets() 또는 BucketManager.RemoveAllBucket() 호출로 디스크 캐시 삭제

개발 팁

• SHTTP_LOG_* 전처리기를 정의하면 단계별 로그를 콘솔 또는 Unity 로그로 확인 가능 (Logger.cs)
• BucketManager.Update()는 10초 주기로 동작하므로 캐시 상태 변경 후 Monitor.Pulse 호출로 즉시 작업을 유도
• ContentDeliveryServiceBehaviour는 OnApplicationPause에서 일시 정지 시 서버를 내려두었다가 복귀 시 자동 재기동
• ContentDeliveryService.Work는 예외 발생 시 Keep-Alive를 비활성화하고 소켓을 종료하므로, 확장 시 예외 처리를 동일 패턴으로 맞춰야 함