@searchos/bot-proxy 0.1.2 → 0.1.3

package/README.md

@@ -4,6 +4,18 @@
 
 ## 워크플로우
 
+### 봇 분류
+
+```
+봇 요청 (UA 기반 감지)
+  │
+  ├── AI 봇 (isAi: true) + aiRender 활성화
+  │     ai 캐시 → desktop 폴백 → origin
+  │
+  └── 일반 봇 (검색엔진, SNS, SEO 등)
+        desktop/mobile 캐시 → origin
+```
+
 ### Next.js + CloudFront (S3)
 
 ```
@@ -14,25 +26,28 @@ Next.js middleware
   │
   ├── nextjsProxy() 호출
   │     │
+  │     ├── 정적 SEO 파일 (robots.txt, sitemap.xml, llms.txt)
+  │     │     → 프리렌더 서버에서 프록시
+  │     │
   │     ├── UA로 봇 감지 (detectBot)
   │     │     봇 아님 → null 반환 → 기존 middleware 실행
   │     │
   │     ├── IP 대역 검증 (verifyBotIp) → 로그에 ip_verified 기록
   │     │
-  │     ├── 캐시 키 계산 (computeCacheKey)
-  │     │     URL path → 정규화 → MD5 → {hash}_{device}
-  │     │
-  │     ├── CloudFront에서 캐시 조회
-  │     │     GET https://{cf도메인}/v2/{사이트도메인}/{hash}_{device}.html
+  │     ├── [AI 봇 + aiRender + aiPath 매칭]
+  │     │     │
+  │     │     ├── ai 캐시 조회: {cf}/v2/{도메인}/{hash}_ai.html
+  │     │     │     히트 → HIT-AI 반환 + ai 워밍
   │     │     │
-  │     │     ├── 히트 → 캐시 HTML 반환
-  │     │     │         + 백그라운드: 봇 로그 전송 + 캐시 워밍 요청
+  │     │     ├── desktop 폴백: {cf}/v2/{도메인}/{hash}_desktop.html
+  │     │     │     히트 → HIT-DESKTOP 반환 + ai 워밍
   │     │     │
-  │     │     └── 미스 → null 반환 → 기존 middleware 실행
-  │     │               + 백그라운드: 봇 로그 전송 + 캐시 워밍 요청
+  │     │     └── 미스 → null (origin) + ai 워밍 + 일반 워밍
   │     │
-  │     └── 정적 SEO 파일 (robots.txt, sitemap.xml, llms.txt)
-  │           → 프리렌더 서버에서 프록시
+  │     └── [일반 봇]
+  │           캐시 조회: {cf}/v2/{도메인}/{hash}_{device}.html
+  │           히트 → HIT 반환 + 워밍
+  │           미스 → null (origin) + 워밍
   │
   ▼
 기존 middleware 로직 (인증, i18n, 리다이렉트 등)
@@ -48,25 +63,31 @@ Cloudflare Worker
   │
   ├── cloudflareProxy() 호출
   │     │
+  │     ├── 정적 SEO 파일 (robots.txt, sitemap.xml, llms.txt)
+  │     │     → 프리렌더 서버에서 프록시
+  │     │
   │     ├── UA로 봇 감지 (detectBot)
   │     │     봇 아님 → null 반환 → origin fetch
   │     │
-  │     ├── IP 대역 검증 (verifyBotIp) → 로그에 ip_verified 기록
+  │     ├── KV 바인딩 확인 (env.V2_CACHE)
+  │     │     없음 → null 반환
   │     │
-  │     ├── 캐시 키 계산 (computeCacheKey)
-  │     │     URL path → 정규화 → MD5 → {hash}_{device}
+  │     ├── IP 대역 검증 (verifyBotIp) → 로그에 ip_verified 기록
   │     │
-  │     ├── KV에서 캐시 조회
-  │     │     env.V2_CACHE.get("{hash}_{device}")
+  │     ├── [AI 봇 + aiRender + aiPath 매칭]
+  │     │     │
+  │     │     ├── ai 캐시 조회: V2_CACHE.get("{hash}_ai")
+  │     │     │     히트 → HIT-AI 반환 + waitUntil(로그 + ai 워밍)
   │     │     │
-  │     │     ├── 히트 → 캐시 HTML 반환
-  │     │     │         + waitUntil: 봇 로그 전송 + 캐시 워밍 요청
+  │     │     ├── desktop 폴백: V2_CACHE.get("{hash}_desktop")
+  │     │     │     히트 → HIT-DESKTOP 반환 + waitUntil(로그 + ai 워밍)
   │     │     │
-  │     │     └── 미스 → null 반환 → origin fetch
-  │     │               + waitUntil: 봇 로그 전송 + 캐시 워밍 요청
+  │     │     └── 미스 → null (origin) + waitUntil(로그 + ai 워밍 + 일반 워밍)
   │     │
-  │     └── 정적 SEO 파일 (robots.txt, sitemap.xml, llms.txt)
-  │           → 프리렌더 서버에서 프록시
+  │     └── [일반 봇]
+  │           캐시 조회: V2_CACHE.get("{hash}_{device}")
+  │           히트 → HIT 반환 + waitUntil(로그 + 워밍)
+  │           미스 → null (origin) + waitUntil(로그 + 워밍)
   │
   ▼
 origin (고객 서버)
@@ -78,6 +99,26 @@ origin (고객 서버)
 npm install @searchos/bot-proxy
 ```
 
+## 옵션
+
+### 공통 옵션
+
+| 옵션 | 타입 | 필수 | 기본값 | 설명 |
+|------|------|------|--------|------|
+| `projectId` | `string` | O | | SearchOS 프로젝트 ID |
+| `siteDomain` | `string` | O | | 사이트 도메인 (`https://` 자동 제거) |
+| `prerenderDomain` | `string` | O | | 프리렌더 서버 URL |
+| `botLogEndpoint` | `string` | O | | 봇 로그 엔드포인트 |
+| `aiRender` | `boolean` | | `true` | AI 봇에게 ai 캐시 우선 서빙 |
+| `ocr` | `boolean` | | `true` | AI 워밍 요청 시 OCR 포함 여부 |
+| `aiPathPrefixes` | `string[]` | | `[]` | AI 렌더 적용 경로 prefix (빈 배열 = 전체 경로) |
+
+### Next.js 전용
+
+| 옵션 | 타입 | 필수 | 설명 |
+|------|------|------|------|
+| `cloudfrontDomain` | `string` | O | CloudFront 배포 도메인 (S3 캐시 조회용) |
+
 ## 사용법
 
 ### Next.js
@@ -88,15 +129,18 @@ import { nextjsProxy } from "@searchos/bot-proxy";
 
 export async function middleware(request) {
   const res = await nextjsProxy(request, {
-    projectId: "...",           // SearchOS 프로젝트 ID
-    siteDomain: "example.com",  // 사이트 도메인
-    cloudfrontDomain: "...",    // CloudFront 배포 도메인
-    prerenderDomain: "...",     // 프리렌더 서버 도메인
-    botLogEndpoint: "...",      // 봇 로그 엔드포인트
+    projectId: "...",
+    siteDomain: "example.com",
+    cloudfrontDomain: "https://d1234.cloudfront.net",
+    prerenderDomain: "https://proxy.searchos.kr",
+    botLogEndpoint: "https://botlog.searchos.kr/bot-ping",
+    // AI 옵션 (모두 선택사항)
+    aiRender: true,              // AI 봇에게 ai 캐시 우선 서빙
+    ocr: true,                   // AI 워밍 시 OCR 포함
+    aiPathPrefixes: ["/blog/"],  // /blog/ 하위만 AI 렌더 적용
   });
   if (res) return res;
 
-  // 기존 middleware 로직
   return NextResponse.next();
 }
 ```
@@ -110,17 +154,28 @@ export default {
   async fetch(request, env, ctx) {
     const res = await cloudflareProxy(request, env, ctx, {
       projectId: "...",
-      siteDomain: "https://example.com",
-      prerenderDomain: "...",
-      botLogEndpoint: "...",
+      siteDomain: "example.com",
+      prerenderDomain: "https://proxy.searchos.kr",
+      botLogEndpoint: "https://botlog.searchos.kr/bot-ping",
+      // AI 옵션 (모두 선택사항)
+      aiRender: true,
+      ocr: true,
+      aiPathPrefixes: [],  // 빈 배열 = 전체 경로에 AI 렌더 적용
     });
     if (res) return res;
 
-    return fetch(request); // origin
+    return fetch(request);
   }
 };
 ```
 
+> **KV 바인딩 필수**: Cloudflare Worker는 `wrangler.toml`에 `V2_CACHE` KV namespace 바인딩이 필요.
+> ```toml
+> [[kv_namespaces]]
+> binding = "V2_CACHE"
+> id = "your-kv-namespace-id"
+> ```
+
 ## 캐시 키 규칙
 
 ```
@@ -178,12 +233,20 @@ UA 기반으로 6개 카테고리의 봇을 감지:
 
 ## 응답 헤더
 
+캐시 히트 시에만 응답에 포함 (미스 시 null 반환, 헤더 없음).
+
 | 헤더 | 값 | 설명 |
 |------|-----|------|
-| X-Cache | HIT / MISS | 캐시 히트 여부 |
+| X-Cache | `HIT-AI` / `HIT-DESKTOP` / `HIT` | 어떤 캐시에서 서빙되었는지 |
 | X-Bot | googlebot, chatgpt-user 등 | 감지된 봇 이름 |
 | X-Bot-Verified | true / false | IP 대역 검증 결과 |
 
+| X-Cache 값 | 의미 |
+|-------------|------|
+| `HIT-AI` | AI 전용 캐시에서 서빙 |
+| `HIT-DESKTOP` | AI 봇이지만 ai 캐시 미스, desktop 폴백으로 서빙 |
+| `HIT` | 일반 봇, desktop/mobile 캐시에서 서빙 |
+
 ## 패키지 구조
 
 ```