Quest 131 - Worker API Builder

Quest 131: Worker API Builder

hard 35 minutes

---

🎯 Learning Objectives

• ✅ เข้าใจ path-based routing สำหรับ different storage backends (KV vs D1)
• ✅ รู้วิธี config error handling ที่แตกต่างกันสำหรับ preview vs production environments
• ✅ สร้าง Worker routes ที่เชื่อมต่อ storage ได้ถูกต้อง
• ✅ จัดการ edge cases ของ D1 ใน preview environments

---

📖 Concept: Worker API Routing with Storage

Cloudflare Workers ไม่ได้เป็นแค่ “run code on edge” — มันคือ full API platform ที่เชื่อมต่อ storage backends หลายชนิดได้ ใน quest นี้คุณจะเรียนรู้ pattern ที่ route API requests ไปหา storage ที่ถูกต้องตาม URL path

KV (Key-Value) เหมือน dictionary — เก็บ key-value pairs ที่เข้าถึงเร็วมาก เหมาะสำหรับ caching, sessions, และ config data

D1 (Database) เหมือน SQL database — เῄาะสำหรับ relational data ที่ต้อง query ด้วย SQL

Think ของ pattern นี้เหมือน “มัลติแพลตฟอร์ม dispatch” — URL path เป็น “address” ที่บอกว่า request ต้องไปหา storage ไหน

---

⚙️ How It Works

Routing Logic

1. รับ request (method, path, env)
         ↓
2. ตรวจสอบ path prefix (/kv/, /d1/, etc.)
         ↓
3. Route ไปหา storage backend ที่ถูกต้อง
         ↓
4. เพิ่ม error handling ตาม storage type
         ↓
5. ตรวจสอบ env.isPreview → เพิ่ม preview-specific handling
         ↓
6. Return { handler, storage, errorHandling, status }

Path-Based Storage Detection

Path Pattern	Storage	Handler Example
/kv/*	KV	kv-get, kv-post
/d1/*	D1	d1-get, d1-post
Other	None	api-get, api-post

Error Handling by Environment

Production:

• D1 query errors
• Database connection timeout

Preview:

• Database not ready in preview environment
• D1 binding not configured
• Friendly error for preview DB errors

---

💡 Example: Building Worker Routes

ขั้นตอนที่ 1: กำหนด path-based routing

function buildWorkerRoute(method, path, env) {
  let storage = 'none';
  let handler = '';
  const errorHandling = [];

ขั้นตอนที่ 2: Route by path prefix

  if (path.startsWith('/kv/')) {
    storage = 'kv';
    handler = `kv-${method.toLowerCase()}`;
    errorHandling.push('Handle KV namespace not found');
    errorHandling.push('Handle key not found (404)');
  } else if (path.startsWith('/d1/')) {
    storage = 'd1';
    handler = `d1-${method.toLowerCase()}`;
    // ... more handling below
  } else {
    handler = `api-${method.toLowerCase()}`;
    errorHandling.push('Handle method not allowed');
  }

ขั้นตอนที่ 3: D1 environment-specific handling

    // D1 requires special error handling in preview environments
    if (env.isPreview) {
      errorHandling.push('Handle database not ready in preview environment');
      errorHandling.push('Handle D1 binding not configured');
      errorHandling.push('Return friendly error for preview DB errors');
    } else {
      errorHandling.push('Handle D1 query errors');
      errorHandling.push('Handle database connection timeout');
    }

    // D1 specific method handling
    if (method === 'POST' || method === 'PUT') {
      errorHandling.push('Validate request body before D1 insert');
      errorHandling.push('Handle unique constraint violations');
    }

ขั้นตอนที่ 4: Return structured result

  return { handler, storage, errorHandling, status: 200 };
}

---

⚠️ Common Mistakes

Mistake 1: ไม่ distinguish preview vs production

“env.isPreview ไม่สำคัญ” → D1 ใน preview environment อาจไม่ ready — ต้อง handle error ต่างกัน

Mistake 2: ลืม validate request body สำหรับ D1

POST/PUT requests ต้อง validate body ก่อน insert เสมอ → D1 จะ throw error ถ้า data ไม่ตรง schema

Mistake 3: ไม่ handle KV namespace not found

KV namespace อาจไม่ถูก config ใน environment บางตัว → ต้อง check และ return user-friendly error

Mistake 4: ใช้ method name ตรงๆ แทน lowercase

"GET" แทน "get" ทำให้ handler name ผิด format → เสมอใช้ .toLowerCase() กับ method name

---

📝 Knowledge Check

📝 Knowledge Check

Q1:Path prefix ใดที่ใช้สำหรับ routing ไปหา KV storage ใน Worker API?

/storage/kv//kv//key-value//cache/

Q2:ทำไม D1 ใน preview environment ต้องมี error handling ต่างจาก production?

D1 ช้ากว่าใน previewDatabase อาจไม่ ready หรือ binding ไม่ถูก config ใน previewD1 รองรับ SQL น้อยกว่าใน previewPreview ไม่รองรับ D1 เลย

Q3:method name GET ต้องทำอย่างไรก่อนสร้าง handler name?

ใช้ตรงๆ ได้เลยแปลงเป็น uppercaseใช้ .toLowerCase() เพื่อเปลี่ยนเป็น 'get'ใส่เครื่องหมาย _ หน้าชื่อ

---

🏋️ Quest: Worker API Builder

ถึงเวลาสร้าง Worker API router ที่เชื่อมต่อ storage backends ได้แล้ว!

1. Download ไฟล์เริ่มต้นของ quest:

   npx bluebeltdojo download quest-131-worker-api
   cd quest-131-worker-api

2. เปิด problem.js ใน editor ของคุณพร้อมความช่วยเหลือของ AI

3. Implement ฟังก์ชัน buildWorkerRoute(method, path, env) ที่:

   • Route requests ตาม path prefix (/kv/, /d1/)
   • เพิ่ม error handling ที่ถูกต้องสำหรับแต่ละ storage
   • จัดการ preview vs production environments ต่างกัน
   • Handle POST/PUT validation สำหรับ D1

4. ตรวจสอบ solution ของคุณ:

   node test.js

5. อ่าน test output อย่างละเอียด — ดูว่า test ไหน fail และทำไม

6. แก้ไขจนกว่า tests ทั้งหมดจะผ่าน

7. เมื่อ tests ผ่านทั้งหมด ส่งคำตอบ:

   npx bluebeltdojo submit

💡 Tip: ลองนึกถึง flow ของ request — path เป็น “address” ที่บอกว่า request ต้องไปหา storage ไหน

---

คำใบ้

• Path prefixes ที่ต้อง handle: /kv/ สำหรับ KV และ /d1/ สำหรับ D1
• ใช้ .toLowerCase() กับ method name เพื่อสร้าง handler name
• ตรวจสอบ env.isPreview เพื่อเพิ่ม preview-specific error handling
• POST และ PUT requests สำหรับ D1 ต้อง validate request body