scraper

type HTMLScraper interface {
	// FetchHTML 지정된 URL로 HTTP 요청을 보내 HTML 문서를 가져오고, 파싱된 goquery.Document를 반환합니다.
	//
	// 매개변수:
	//   - ctx: 요청의 생명주기를 제어하는 컨텍스트 (취소, 타임아웃 등)
	//   - method: HTTP 메서드 (예: "GET", "POST")
	//   - rawURL: 요청할 URL
	//   - body: 요청 본문 데이터 (nil 가능, GET 요청 시 일반적으로 nil)
	//   - header: 추가 HTTP 헤더 (nil 가능, 예: User-Agent, Cookie 등)
	//
	// 반환값:
	//   - *goquery.Document: 파싱된 HTML 문서 객체
	//   - error: 네트워크 오류, 파싱 오류, 또는 응답 크기 초과 시 에러 반환
	FetchHTML(ctx context.Context, method, rawURL string, body io.Reader, header http.Header) (*goquery.Document, error)

	// FetchHTMLDocument 지정된 URL로 GET 요청을 보내 HTML 문서를 가져오는 헬퍼 함수입니다.
	//
	// 이 함수는 FetchHTML을 내부적으로 호출하며, HTTP 메서드를 "GET"으로 고정하고 요청 본문(Body)을 nil로 설정합니다.
	// 단순히 웹 페이지를 읽어오는 가장 일반적인 사용 사례를 위한 간편한 인터페이스를 제공합니다.
	//
	// 매개변수:
	//   - ctx: 요청의 생명주기를 제어하는 컨텍스트 (취소, 타임아웃 등)
	//   - rawURL: 요청할 URL
	//   - header: 추가 HTTP 헤더 (nil 가능, 예: User-Agent, Cookie 등)
	//
	// 반환값:
	//   - *goquery.Document: 파싱된 HTML 문서 객체
	//   - error: 네트워크 오류, 파싱 오류, 또는 응답 크기 초과 시 에러 반환
	FetchHTMLDocument(ctx context.Context, rawURL string, header http.Header) (*goquery.Document, error)

	// ParseHTML io.Reader로부터 HTML 문서를 파싱하여 goquery.Document를 반환합니다.
	//
	// 이 함수는 이미 메모리에 로드된 HTML 데이터(문자열, 파일 등)를 처리할 때 사용됩니다.
	// FetchHTML과 달리 HTTP 요청을 수행하지 않으며, 제공된 Reader에서 직접 데이터를 읽어 파싱합니다.
	//
	// 매개변수:
	//   - ctx: 컨텍스트 (로깅 연동 및 취소 신호 감지)
	//   - r: HTML 데이터를 읽을 io.Reader (nil 불가)
	//   - rawURL: 문서의 기준 URL (상대 경로 링크를 절대 경로로 변환할 때 사용, 빈 문자열 가능)
	//   - contentType: HTTP 응답의 Content-Type 헤더 (인코딩 감지를 위한 힌트로 사용됨, 빈 문자열 가능)
	//
	// 반환값:
	//   - *goquery.Document: 파싱된 HTML 문서 객체
	//   - error: 입출력 오류, 컨텍스트 취소 또는 파싱 실패 시 에러 반환
	//
	// 보안 고려사항:
	//   - maxResponseBodySize를 초과하는 입력은 에러를 반환합니다. (DoS 방지 및 데이터 무결성 보장)
	//   - 컨텍스트 취소 시 즉시 중단됩니다.
	ParseHTML(ctx context.Context, r io.Reader, rawURL string, contentType string) (*goquery.Document, error)
}

type JSONScraper interface {
	// FetchJSON 지정된 URL로 HTTP 요청을 보내 JSON 응답을 가져오고, 지정된 구조체로 디코딩합니다.
	//
	// 이 함수는 RESTful API 호출에 최적화되어 있으며, 다음과 같은 주요 기능을 제공합니다:
	//   - 요청 본문 자동 처리: 구조체를 전달하면 자동으로 JSON 마샬링하여 전송
	//   - 응답 검증: Content-Type 확인 및 HTML 응답 감지
	//   - 메모리 무결성: maxResponseBodySize 초과 시 에러를 반환하여 불완전한 파싱 방지
	//   - 자동 재시도 지원: 네트워크 오류 시 Fetcher가 요청을 재시도할 수 있도록 본문을 메모리 버퍼링
	//
	// 매개변수:
	//   - ctx: 요청의 생명주기를 제어하는 컨텍스트 (취소, 타임아웃 등)
	//   - method: HTTP 메서드 (예: "GET", "POST")
	//   - rawURL: 요청할 URL
	//   - body: 요청 본문 데이터 (nil 가능, GET 요청 시 일반적으로 nil)
	//   - header: 추가 HTTP 헤더 (nil 가능, 예: User-Agent, Cookie 등)
	//   - v: JSON 응답을 디코딩할 대상 구조체의 포인터 (반드시 nil이 아닌 포인터여야 함)
	//
	// 반환값:
	//   - error: 네트워크 오류, JSON 파싱 오류, 또는 응답 크기 초과 시 에러 반환
	FetchJSON(ctx context.Context, method, rawURL string, body any, header http.Header, v any) error
}

type Option func(*scraper)

type Scraper interface {
	HTMLScraper
	JSONScraper
}