คำสั่งต่างๆ (Client Commands)

หลังจากเชื่อมต่อ WebSocket สำเร็จ Client สามารถส่ง Control Commands ในรูปแบบ JSON ไปยัง Gateway เพื่อควบคุม State และดำเนินการต่างๆ ได้

ทุกคำสั่งจำเป็นต้องมีแอตทริบิวต์ cmd เสมอ เพื่อเป็นตัวบ่งชี้ประเภทของการทำงาน (Operation Type)

---

🔐 1. Command: auth

คำสั่งแรกสุดและสำคัญที่สุดของระบบ Authentication! หากเปิด Connection สำเร็จแล้ว แต่ไม่ส่ง auth command มาภายใน 10 วินาที Connection จะถูกตัดทันที (Timeout)

• การใช้งาน: ใช้สำหรับยืนยันตัวตน Client ด้วยระบบ Cryptographic Token (HMAC) เพื่อรับรองความถูกต้องของเซสชัน

ws.send(JSON.stringify({
  // คำสั่งที่ 1
  "cmd": "auth",
  
  // นำค่า 7 ส่วนนี้มาจาก Backend ของคุณ
  "token": {
    "v": "v1",
    "purpose": "ws-auth",
    "sub": "usr_123456",
    "aud": "websocket",
    "iat": 1718000000000,
    "exp": 1718000600000,
    "jti": "random_uuid"
  },
  "signature": "8a329be8f9a..."
}));

(ผลลัพธ์ที่ตอบกลับจากระบบ): ถ้าผ่าน คุณจะได้รับ Reply ตอบกลับพร้อม status: "ok" และ data: { session_id, user_id } ทันที

---

📡 2. Command: subscribe

เมื่อผ่านการ auth แล้ว Client จำเป็นต้อง Subscribe เข้า Channel ก่อนจึงจะสามารถรับ Events ทราฟฟิกข้อมูลได้

• ความสามารถ: รองรับการ Subscribe พร้อมกันหลาย Channel ภายใน 1 Connection ช่วยให้ระบบการรับส่งแบบ Multiplexing ทำงานได้อย่างมีประสิทธิภาพ (ตัวอย่างเช่น ข้อมูล updates:feed_1, ticker:btc_usd ถูกจัดการผ่าน Single Connection)

ws.send(JSON.stringify({
  "cmd": "subscribe",
  
  // ชื่อ Channel ที่ต้องการ subscribe
  "channel": "updates:feed_1",
  
  // (เฉพาะห้อง Private) ลายเซ็น HMAC สำหรับห้องนี้
  // "auth": { "sig": "signature_from_your_backend" },

  // reference ID (กำหนดเอง) เพื่อจับคู่กับ reply ที่จะตอบกลับมา
  "ref": "sub-01" 
}));

(ผลลัพธ์ที่ตอบกลับจากระบบ): ระบบจะตอบ type: reply กลับมาโดยมี ref: "sub-01" แจ้งโชว์สถานะ status: ok (หรือ error หากลายเซ็นช่อง Private ไม่ถูกต้อง)

---

🚫 3. Command: unsubscribe

เมื่อต้องการหยุดรับข้อมูลจาก Channel ใด ๆ สามารถส่งคำสั่งเพื่อยกเลิก Subscription ได้ ช่วยเพิ่มประสิทธิภาพในการจัดการหน่วยความจำและ Bandwidth

ws.send(JSON.stringify({
  "cmd": "unsubscribe",
  "channel": "updates:feed_1",
  "ref": "unsub-01" 
}));

---

✉️ 4. Command: publish

นอกจาก Backend Service จะสามารถส่งข้อมูลผ่าน REST API แล้ว ฝั่ง Client ยังสามารถ Broadcast Event ตรงผ่าน WebSocket สู่ Subscribers ท่านอื่นใน Channel เดียวกันได้ (Client-to-Client Broadcasting) ซึ่งเหมาะสำหรับระบบที่มี Low-Latency Requirements (เช่น Cursor Tracking หรือ Typing Status)

ws.send(JSON.stringify({
  "cmd": "publish",
  
  // ส่งข้อความไปยัง Channel นี้
  "channel": "collaboration:doc_1",
  
  // ภายใต้ชื่อ Event ว่าอะไร?
  "event": "cursor.move",
  
  // ข้อมูล Data Payload (JSON รูปแบบอิสระ)
  "data": {
     "user_id": "user_444",
     "name": "Tom",
     "x": 100,
     "y": 250
  },
  "ref": "pub-01"
}));

⚠️ กฎเหล็กเรื่องสิทธิ์ (Permissions)

คุณต้อง Subscribe ห้อง (Channel) นั้นก่อนเสมอ ถึงจะ Publish ส่งข้อมูลเข้าไปได้ — หากพยายาม Publish ไปยัง Channel ที่ยังไม่ได้ Subscribe จะได้ Error CHANNEL_DENIED กลับมาทันที

สำหรับข้อมูลที่มีความปลอดภัยสูง (เช่น กระบวนการสั่งซื้อ, Data Mutation หรือ Broadcast จาก Admin) แนะนำให้ Backend Service ของคุณ ดำเนินการผ่าน REST API (POST /api/v1/publish) เท่านั้น เพื่อป้องกันการปลอมแปลง Event (Spoofing) จาก Client-Side

---

💓 5. Command: ping

ระบบ Heartbeat สำหรับตรวจสอบสถานะการเชื่อมต่อ

ในบางกรณี Client อาจยังคง connect อยู่แต่ Network ขาดหายไปแล้ว ระบบ RawPush จะส่ง ping มาเป็นระยะ หรือคุณสามารถส่ง ping ไปที่ RawPush เมื่อไหร่ก็ได้เพื่อตรวจสอบว่า connection ยังทำงานอยู่หรือไม่

ws.send(JSON.stringify({
  "cmd": "ping",
  "ref": "my-ping"
}));

(ผลลัพธ์ที่ตอบกลับจากระบบ): Gateway จะตอบกลับในระดับมิลลิวินาทีด้วย Reply สถานะ status: ok พร้อมด้วย ref: "my-ping" หากไม่ได้รับการตอบสนองเกิน 5 วินาที Application ควรจัดการ Connection Failure ด้วยการเรียก ws.close() และเข้าสู่กระบวนการ Reconnect ทันที