chatr

Chatr - แอปตัวอย่าง Azure Web PubSub

นี่คือแอปพลิเคชันสาธิตและตัวอย่างที่ออกแบบมาให้เป็นระบบแชทบนเว็บที่มีผู้ใช้หลายคนอย่างง่าย
มีการแชทกลุ่มแบบถาวร การแชทส่วนตัวระหว่างผู้ใช้กับผู้ใช้ รายชื่อผู้ใช้ การตรวจจับการไม่ได้ใช้งาน (อยู่ห่างจากแป้นพิมพ์) และคุณสมบัติอื่น ๆ อีกมากมาย

สร้างขึ้นจากเทคโนโลยี Azure หลายอย่าง รวมถึง: Web PubSub, Static Web Apps และ Table Storage

?? บันทึก. สิ่งนี้สร้างขึ้นเป็นโปรเจ็กต์ส่วนตัว สร้างขึ้นเพื่อช่วยในการเรียนรู้ควบคู่ไปกับการสร้างสิ่งที่น่าสนใจ รหัสนี้มาพร้อมกับคำเตือนทั้งหมดที่คุณอาจคาดหวังจากโครงการดังกล่าว

เป้าหมาย:

• เรียนรู้เกี่ยวกับการใช้เว็บซ็อกเก็ต
• เขียนสิ่งที่ 'สนุก'
• ลองใช้บริการ Azure Web PubSub ใหม่
• ใช้คุณสมบัติการรับรองความถูกต้องของ Azure Static Web Apps
• ปรับใช้ทุกอย่างโดยใช้ Azure Bicep

กรณีการใช้งานและคุณสมบัติที่สำคัญ:

• ลงชื่อเข้าใช้ด้วยบัญชี Microsoft, Twitter หรือ GitHub
• สนทนาแบบเรียลไทม์กับผู้ใช้
• แชทกลุ่มที่ใช้ร่วมกัน มีเพียงผู้สร้างเท่านั้นที่สามารถลบแชทได้
• ตรวจจับตำแหน่งที่ผู้ใช้ไม่ได้ใช้งานและอยู่ห่างจากคีย์บอร์ด (ค่าเริ่มต้นคือหนึ่งนาที)
• การแชทส่วนตัวแบบ 'ผู้ใช้ถึงผู้ใช้' พร้อมการแจ้งเตือนและป๊อปอัป

ภาพหน้าจอ

สถาปัตยกรรม

ลูกค้า / ส่วนหน้า

นี่คือส่วนหน้าของเว็บหลักที่ผู้ใช้ปลายทางใช้ผ่านเบราว์เซอร์

พบแหล่งที่มาของสิ่งนี้ใน ไคลเอนต์/ และประกอบด้วยแอปพลิเคชัน ES6 JS ล้วนแบบสแตนด์อโลนแบบคงที่ ไม่จำเป็นต้องรวมกลุ่มหรือ Node.js เขียนโดยใช้ Vue.js เป็นเฟรมเวิร์กสนับสนุน และใช้ Bulma เป็นเฟรมเวิร์ก CSS

หมายเหตุบางประการ:

• ใช้โมดูล ES6 เพื่อให้ไฟล์ JS ต่างๆ สามารถใช้การนำเข้า/ส่งออกได้โดยไม่จำเป็นต้องรวมกลุ่ม
• Vue.js ถูกใช้เป็นไลบรารีฝั่งเบราว์เซอร์ที่โหลดจาก CDN เป็นโมดูล ESM นี่เป็นแนวทางที่หรูหราและมีน้ำหนักเบาซึ่งรองรับโดยเบราว์เซอร์สมัยใหม่ แทนที่จะเป็นแอปสไตล์ vue-cli ทั่วไปที่ต้องใช้ Node และ webpack เป็นต้น
• client/js/app.js แสดงวิธีสร้างแอป Vue.js ด้วยคอมโพเนนต์ลูกโดยใช้วิธีนี้ ตรรกะไคลเอนต์ส่วนใหญ่อยู่ที่นี่
• client/js/components/chat.js เป็นส่วนประกอบ Vue.js ที่ใช้ในการโฮสต์แต่ละแท็บแชทในแอปพลิเคชัน
• จุดสิ้นสุด .auth/ พิเศษที่จัดทำโดย Static Web Apps ใช้เพื่อลงชื่อเข้าใช้ผู้ใช้และดึงรายละเอียดผู้ใช้ เช่น userId

เซิร์ฟเวอร์

นี่คือแบ็กเอนด์ที่จัดการเหตุการณ์ websocket เข้าและออกจาก Azure Web PubSub และจัดเตรียม REST API สำหรับการดำเนินการบางอย่าง

แหล่งที่มาของสิ่งนี้พบได้ใน api/ และประกอบด้วยแอปฟังก์ชัน Azure ของ Node.js เชื่อมต่อกับ Azure Table Storage เพื่อคงการแชทเป็นกลุ่มและข้อมูลผู้ใช้ (Table Storage ถูกเลือกเนื่องจากง่ายและราคาถูก) สิ่งนี้ไม่ได้โฮสต์ในแอปฟังก์ชัน Azure แบบสแตนด์อโลน แต่ปรับใช้ใน Static Web App แทนซึ่งเป็นส่วนหนึ่งของการสนับสนุน API แบบไร้เซิร์ฟเวอร์

มีฟังก์ชัน HTTP สี่ฟังก์ชันที่ทำงานจากเส้นทาง /api/ เริ่มต้น

• eventHandler - ตัวรับ Webhook สำหรับเหตุการณ์ "อัปสตรีม" ที่ส่งจากบริการ Azure Web PubSub ประกอบด้วยตรรกะแอปพลิเคชันส่วนใหญ่ ลูกค้าไม่ได้เรียกโดยตรง มีเพียง Azure WebPub Sub เท่านั้น
• getToken - ไคลเอ็นต์เรียกเพื่อรับโทเค็นการเข้าถึงและ URL เพื่อเชื่อมต่อผ่าน WebSockets ไปยังบริการ Azure Web PubSub จะต้องเรียกด้วย userId ในการสืบค้น URL เช่น GET /api/getToken?userId={user}
• getUsers - ส่งคืนรายชื่อผู้ใช้ที่ลงชื่อเข้าใช้ โปรดทราบว่าเส้นทางสำหรับฟังก์ชันนี้คือ /api/users
• getChats - ส่งคืนรายการแชทกลุ่มที่ใช้งานอยู่ โปรดทราบว่าเส้นทางสำหรับฟังก์ชันนี้คือ /api/chats

สถานะได้รับการจัดการด้วย state.js ซึ่งเป็นโมดูล ES6 ที่ส่งออกฟังก์ชันที่รองรับ CRUD สถานะสำหรับผู้ใช้และการแชท โมดูลนี้ดำเนินการโต้ตอบทั้งหมดกับ Azure Tables และมีอินเทอร์เฟซที่ค่อนข้างโปร่งใส ดังนั้นจึงสามารถเปลี่ยนแบ็กเอนด์พื้นที่เก็บข้อมูลอื่นได้

กระแสข้อความ WebSocket และ API

มีการรับส่งข้อความสองทางระหว่างไคลเอนต์และเซิร์ฟเวอร์ผ่าน Azure Web PubSub และตัวจัดการเหตุการณ์

มีการใช้โปรโตคอลย่อย json.webpubsub.azure.v1 แทนที่จะเป็น WebSockets พื้นฐาน ซึ่งมีคุณสมบัติหลายประการ: คุณสามารถเพิ่มผู้ใช้ในกลุ่มได้ ไคลเอนต์สามารถส่งเหตุการณ์ที่กำหนดเอง (โดยใช้ type: event ) และยังส่งข้อความโดยตรงไปยังไคลเอนต์อื่น ๆ โดยไม่ต้องผ่านเซิร์ฟเวอร์ (ใช้ type: sendToGroup )

หมายเหตุ:

• รหัสการแชทเป็นเพียง GUID ที่สร้างขึ้นแบบสุ่ม ซึ่งสอดคล้องกับ "กลุ่ม" ในโปรโตคอลย่อย
• การแชทส่วนตัวเป็นกรณีพิเศษ โดยจะไม่คงอยู่ในสถานะ และไม่ทำให้เกิดเหตุการณ์ chatCreated นอกจากนี้ ผู้ใช้ไม่ได้ออกกิจกรรม joinChat เพื่อเข้าร่วม ซึ่งเซิร์ฟเวอร์จะจัดการในลักษณะ "พุช" ไปยังไคลเอนต์
• รหัสผู้ใช้เป็นเพียงสตริงซึ่งถือว่าไม่ซ้ำกัน ซึ่งสามารถปรับปรุงได้ เช่น ใช้คำนำหน้า

การส่งข้อความถึงลูกค้า

กิจกรรมและการแชทจะถูกส่งโดยใช้โปรโตคอลย่อย json.webpubsub.azure.v1

ข้อความแชทที่ส่งจากไคลเอนต์ใช้ sendToGroup และเพย์โหลด JSON แบบกำหนดเองพร้อม message สามฟิลด์ fromUserId & fromUserName ข้อความเหล่านี้จะถูกส่งต่อไคลเอนต์ไปยังไคลเอนต์โดย Azure Web PubSub เซิร์ฟเวอร์จะไม่ได้รับการแจ้งเตือน:

{
  type : 's endToGroup ',
  group : < chatId > ,
  dataType : 'j son ',
  data : {
    message : < message text > ,
    fromUserId : < userId > ,
    fromUserName : < userName > ,
  },
}

กิจกรรมที่กำหนดไว้สำหรับเซิร์ฟเวอร์แบ็กเอนด์จะถูกส่งเป็นข้อความ WebSocket จากไคลเอนต์ผ่านโปรโตคอลย่อยเดียวกันกับประเภท event และประเภทย่อยเฉพาะแอปพลิเคชัน เช่น

{
  type : 'e vent ',
  event : 'j oinChat ',
  dataType : 't ext ',
  data : < chatId > ,
}

ประเภทของเหตุการณ์คือ:

• createChat - ขอเซิร์ฟเวอร์ที่คุณต้องการสร้างการแชทกลุ่ม
• createPrivateChat - ขอเซิร์ฟเวอร์ที่คุณต้องการสร้างการแชทส่วนตัว
• joinChat - หากต้องการเข้าร่วมแชท เซิร์ฟเวอร์จะเพิ่มผู้ใช้ในกลุ่มสำหรับ chatId นั้น
• leaveChat - เพื่อออกจากการแชทเป็นกลุ่ม
• DeleteChat - โทรจากเจ้าของแชทเพื่อลบแชท
• userEnterIdle - แจ้งให้เซิร์ฟเวอร์ทราบว่าขณะนี้ผู้ใช้ไม่ได้ใช้งาน
• userExitIdle - แจ้งให้เซิร์ฟเวอร์ทราบว่าผู้ใช้ไม่ได้ใช้งานอีกต่อไป

ฟังก์ชัน eventHandler ของ API แบ็กเอนด์มีเคสสำหรับเหตุการณ์ผู้ใช้แต่ละเหตุการณ์ พร้อมด้วยตัวจัดการสำหรับเหตุการณ์ระบบการเชื่อมต่อและการตัดการเชื่อมต่อ

การส่งข้อความเซิร์ฟเวอร์

ข้อความที่ส่งจากเซิร์ฟเวอร์จะมีเพย์โหลดเฉพาะของแอป Chatr แบบกำหนดเองดังต่อไปนี้:

{
  chatEvent : < eventType > ,
  data : < JSON object type dependant >
}

โดยที่ eventType เป็นหนึ่งใน:

• chatCreated - แจ้งให้ผู้ใช้ทุกคนทราบว่ามีการสร้างแชทกลุ่มใหม่แล้ว
• chatDeleted - แจ้งให้ผู้ใช้ทุกคนทราบว่าการแชทเป็นกลุ่มถูกลบแล้ว
• userOnline - แจ้งให้ผู้ใช้ทุกคนทราบว่าผู้ใช้ออนไลน์แล้ว
• userOffline - แจ้งให้ผู้ใช้ทุกคนทราบว่ามีผู้ใช้ออกไป
• joinPrivateChat - ส่งถึงทั้งผู้ริเริ่มและผู้รับการแชทส่วนตัว
• userIsIdle - ส่งไปยังผู้ใช้ทั้งหมดเมื่อผู้ใช้เข้าสู่สถานะไม่ได้ใช้งาน
• userNotIdle - ส่งไปยังผู้ใช้ทั้งหมดเมื่อผู้ใช้ออกจากสถานะไม่ได้ใช้งาน

รหัสไคลเอนต์ใน client/js/app.js จัดการข้อความเหล่านี้ตามที่ลูกค้าได้รับและตอบสนองตามนั้น

หมายเหตุบางประการเกี่ยวกับการเลือกการออกแบบและการบริการ

แผนของโปรเจ็กต์นี้คือการใช้ Azure Web PubSub และ Azure Static Web Apps และโฮสต์ส่วนประกอบฝั่งเซิร์ฟเวอร์เป็นชุดของฟังก์ชันไร้เซิร์ฟเวอร์ในการรองรับ Static Web Apps API (ซึ่งจริงๆ แล้วคือ ฟังก์ชัน Azure ภายใต้ประทุน) เลือก Azure Static Web Apps เนื่องจากมีการสนับสนุนที่ยอดเยี่ยมสำหรับการลงชื่อเข้าใช้และรับรองความถูกต้องของผู้ใช้โดยไม่ต้องใช้รหัสและไม่ต้องกำหนดค่า ซึ่งฉันต้องการใช้ประโยชน์

ความคิดเห็นบางส่วนเกี่ยวกับแนวทางนี้:

• การสนับสนุน API ใน Static Web Apps ค่อนข้างจำกัด และไม่สามารถรองรับการเชื่อมโยงและทริกเกอร์ใหม่สำหรับ Web PubSub อย่างไรก็ตาม คุณไม่จำเป็นต้องใช้การผูกเหล่านี้ใช่ไหม คุณสามารถสร้างฟังก์ชัน HTTP มาตรฐานเพื่อทำหน้าที่เป็นตัวจัดการเหตุการณ์ webhook แทนการใช้การเชื่อมโยง webPubSubConnection สำหรับการส่งข้อความกลับไปยัง Web PubSub คุณสามารถใช้ SDK เซิร์ฟเวอร์ภายในโค้ดฟังก์ชันได้ แทนที่จะใช้การเชื่อมโยงเอาต์พุต webPubSub
• Table Storage ถูกเลือกสำหรับสถานะคงอยู่เนื่องจากมี JS SDK ที่ดี (ใช้ SDK ใหม่ใน @azure/data-table) ซึ่งมีน้ำหนักเบามากและราคาถูก และดีพอสำหรับโปรเจ็กต์นี้ ดูรายละเอียดด้านล่าง

การออกแบบของรัฐและนิติบุคคล

สถานะใน Azure Tables ประกอบด้วยสองตาราง (คอลเลกชัน) ที่มีชื่อ chats และ users

โต๊ะสนทนา

เนื่องจากแต่ละแชทมีอ็อบเจ็กต์ที่ซ้อนกันอยู่ภายในช่องสมาชิก แต่ละแชทจึงถูกจัดเก็บเป็นสตริง JSON ในช่องที่เรียกว่า data PartitionKey ไม่ได้ใช้และฮาร์ดโค้ดเป็นสตริง "chatr" RowKey และฟิลด์ id ภายในออบเจ็กต์ข้อมูลเหมือนกัน

• PartitionKey : "chatr"
• RowKey : chatId (GUID สุ่มสร้างฝั่งไคลเอ็นต์)
• data : เอนทิตีการแชทแบบสตริง JSON

ตัวอย่างของเอนทิตีข้อมูลการสนทนา

{
  "id" : " eab4b030-1a3d-499a-bd89-191578395910 " ,
  "name" : " This is a group chat " ,
  "members" : {
    "0987654321" : {
      "userId" : " 0987654321 " ,
      "userName" : " Another Guy "
    },
    "1234567890" : {
      "userId" : " 1234567890 " ,
      "userName" : " Ben "
    }
  },
  "owner" : " 1234567890 "
}

ตารางผู้ใช้

ผู้ใช้จะถูกจัดเก็บเป็นเอนทิตีพร้อมกับฟิลด์ (คอลัมน์) ที่อธิบายไว้ด้านล่าง เนื่องจากไม่มีฟิลด์ที่ซ้อนกัน จึงไม่จำเป็นต้องเข้ารหัสเป็นสตริง JSON อีกครั้งที่ PartitionKey ไม่ได้ถูกใช้และฮาร์ดโค้ดเป็นสตริง "chatr"

• PartitionKey : "chatr"
• RowKey : ฟิลด์ userId ที่ส่งคืนจากจุดสิ้นสุดการตรวจสอบสิทธิ์ Web Apps แบบคงที่
• ชื่อผู้ใช้ : ชื่อผู้ใช้ (อาจเป็นที่อยู่อีเมลหรือหมายเลขอ้างอิง) ของผู้ใช้
• userProvider : การรับรองความถูกต้องใดที่ผู้ใช้ลงชื่อเข้าใช้ด้วย twitter , aad หรือ github
• idle : Boolean ระบุว่าผู้ใช้ไม่ได้ใช้งานอยู่หรือไม่

การเรียกใช้และการปรับใช้แอป

ทำงานในพื้นที่

ดูที่ เมคไฟล์

 $ make
help                  This help message
lint                 ? Lint & format, will not fix but sets exit code on error
lint-fix              Lint & format, will try to fix errors and modify code
run                  ? Run server locally using Static Web Apps CLI
clean                ? Clean up project
deploy                Deploy everything to Azure using Bicep
tunnel               ? Start loophole tunnel to expose localhost

กำลังปรับใช้กับ Azure

การปรับใช้มีความซับซ้อนเล็กน้อยเนื่องจากจำนวนส่วนประกอบและการกำหนดค่าระหว่างส่วนประกอบเหล่านั้น deploy เป้าหมาย makefile ควรปรับใช้ทุกอย่างให้คุณในขั้นตอนเดียวโดยใช้เทมเพลต Bicep ที่พบในโฟลเดอร์ ปรับใช้ /

ดู readme ในโฟลเดอร์ปรับใช้สำหรับรายละเอียดและคำแนะนำ

วิ่งในพื้นที่

สิ่งนี้เป็นไปได้แต่ต้องใช้ความพยายามเพียงเล็กน้อย เนื่องจากบริการ Azure Web PubSub จำเป็นต้องสามารถเรียกตำแหน่งข้อมูล HTTP บนเครื่องระบุตำแหน่งของคุณได้ ดังนั้นจึงมีการใช้ทันเนล

เมื่อทำงานภายในเครื่อง จะใช้ Static Web Apps CLI และทำให้มีจุดสิ้นสุดการตรวจสอบสิทธิ์ผู้ใช้ปลอมสำหรับเรา

สรุปขั้นตอนคือ:

• ปรับใช้บัญชี Azure Storage รับชื่อและรหัสการเข้าถึง
• ปรับใช้อินสแตนซ์ Azure Web Pub Sub รับสตริงการเชื่อมต่อจากหน้า 'คีย์'
• คัดลอก api/local.settings.sample.json ไปยัง api/local.settings.json และแก้ไขค่าการตั้งค่าที่จำเป็น
• เริ่มบริการทันเนล localhost เช่น ngrok หรือ loophole อุโมงค์ควรเปิดเผยพอร์ต 7071 ผ่าน HTTP
  ฉันใช้ช่องโหว่เนื่องจากช่วยให้ฉันตั้งค่าโฮสต์และชื่อ DNS ที่กำหนดเองได้ เช่น
  • loophole http 7071 --hostname chatr
• ในการตั้งค่า ย่อย Azure Web Pub
  • เพิ่มฮับชื่อ แชท
  • ในเทมเพลต URL ให้ใส่ https://{{hostname-of-tunnel-service}}/api/eventHandler
  • ในเหตุการณ์ของระบบ ให้ทำเครื่องหมาย ที่เชื่อมต่อ และ ตัดการเชื่อมต่อ
• วิ่ง make run
• เปิด http://localhost:4280/index.html

ปัญหาที่ทราบ

• จะไม่ทำงานใน Firefox เนื่องจากยังไม่รองรับการรอคอยระดับบนสุด