forwarder

forwarder는 Playwright 기반 세션 유지형 포워드 프록시 모듈입니다. requestKey로 허용된 대상만 호출하며, 사용자별 브라우저 컨텍스트와 SQLite 세션 저장소를 사용해 쿠키, localStorage, IndexedDB 상태를 유지합니다.

책임 범위

ForwardUrls에 등록된 requestKey를 실제 target URL로 변환합니다.
BearerToken과 클라이언트 IP 허용 목록을 확인한 뒤 프록시 요청을 실행합니다.
브라우저형 요청과 프로그램형 요청을 구분해 세션 유지 전략을 적용합니다.
HTML 응답에는 <base> 태그를 주입해 상대 경로 리소스가 원본 사이트 기준으로 동작하게 합니다.
상위 프록시, HTTPS 인증서 예외, 타임아웃, redirect 제한을 설정으로 제어합니다.

주요 API

메서드	경로	용도
`GET`	`/forwarder/api/proxy/get-client-ip`	호출자의 IP 확인용 API입니다.
`ALL`	`/forwarder/api/proxy/pipe?requestKey=...`	등록된 target으로 요청을 포워딩합니다.
`GET`	`/forwarder/api/forward-proxy-lab/*`	개발/검증용 lab 대상 페이지와 응답입니다.
`POST`	`/forwarder/api/forward-proxy-lab/proxy-execute`	lab 화면에서 프로그램형 프록시 호출을 시험합니다.

핵심 구현

Areas/forwarder/Controllers/ProxyController.cs: 실제 프록시 API입니다.
Areas/forwarder/Controllers/ForwardProxyLabController.cs: 개발 검증용 target과 lab UI를 제공합니다.
Services/ForwardProxyService.cs: Playwright 실행, 브라우저 컨텍스트 재사용, 응답 변환을 담당합니다.
Services/SQLiteForwardProxySessionStore.cs: 사용자별 세션 파일을 관리합니다.
Extensions/ForwarderAuthorizationExtensions.cs: IP 허용과 BearerToken 검증을 담당합니다.

주요 설정

설정	설명
`ForwardUrls`	`requestKey -> targetUrl` 화이트리스트입니다. 등록되지 않은 key는 프록시할 수 없습니다.
`AllowClientIP`	접근 가능한 클라이언트 IP 목록입니다.
`UseProxy`, `ProxyServer`, `ProxyUsername`, `ProxyPassword`, `ProxyBypass`	상위 프록시 체인 설정입니다.
`IgnoreHTTPSErrors`	테스트 환경의 TLS 오류를 무시할지 결정합니다.
`RequestTimeoutMS`	기본 요청 제한 시간입니다.
`MaxRedirects`	redirect 최대 횟수입니다.
`SessionStorageBasePath`	사용자별 SQLite 세션 파일 저장 위치입니다.
`BrowserIdleTimeoutSecond`	미사용 브라우저 컨텍스트 정리 기준입니다.

ForwardUrls 예시는 다음과 같습니다.

{
  "ForwardUrls": [
    { "sample-api": "https://example.com" },
    { "lab-json": "http://localhost:8421/forwarder/api/forward-proxy-lab/target/json" }
  ]
}

Playwright Chromium

forwarder는 실행 환경에 Playwright Chromium이 설치되어 있어야 합니다. 자동 설치가 실패하는 서버에서는 실제 호스트가 로드하는 modules/forwarder 경로에서 다음 명령으로 설치합니다.

pwsh .\playwright.ps1 install chromium

설치 상태는 다음 명령으로 확인합니다.

pwsh .\playwright.ps1 install --list

운영 주의사항

ForwardUrls는 외부 호출 allowlist이므로 운영 배포 전에 불필요한 lab key를 제거합니다.
SessionStorageBasePath에는 사용자별 세션 상태가 저장되므로 접근 권한, 보관 기간, 디스크 정리 정책을 둡니다.
IgnoreHTTPSErrors=true는 개발/검증 환경에만 사용합니다.
BrowserIdleTimeoutSecond를 길게 두면 로그인 재사용성은 좋아지지만 메모리 점유가 증가합니다.

책임 범위​

주요 API​

핵심 구현​

주요 설정​

Playwright Chromium​

운영 주의사항​