chatr

Chatr - نموذج تطبيق Azure Web PubSub

هذا تطبيق توضيحي وعينة تم تصميمه ليكون نظامًا بسيطًا للدردشة عبر الويب متعدد المستخدمين.
فهو يوفر محادثات جماعية مستمرة، ومحادثات خاصة من مستخدم إلى مستخدم، وقائمة مستخدمين، واكتشاف الخمول (بعيدًا عن لوحة المفاتيح) والعديد من الميزات الأخرى.

إنه مبني على العديد من تقنيات Azure، بما في ذلك: Web PubSub، وتطبيقات الويب الثابتة ، وتخزين الجدول

?‍? ملحوظة. تم إنشاء هذا كمشروع شخصي، تم إنشاؤه للمساعدة في التعلم أثناء بناء شيء مثير للاهتمام. يأتي الكود مع جميع التحذيرات التي قد تتوقعها من مثل هذا المشروع.

الأهداف:

• تعرف على كيفية استخدام websockets
• اكتب شيئًا "ممتعًا".
• جرب خدمة 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 لتسجيل دخول المستخدمين وجلب تفاصيل المستخدم الخاصة بهم، مثل معرف المستخدم.

الخادم

هذه هي الواجهة الخلفية، التي تتعامل مع أحداث websocket من وإلى Azure Web PubSub، وتوفر REST API لبعض العمليات.

تم العثور على مصدر ذلك في api/ ويتكون من تطبيق Node.js Azure Function. إنه يتصل بـ Azure Table Storage للحفاظ على الدردشة الجماعية وبيانات المستخدم (تم اختيار Table Storage لأنه بسيط ورخيص). لا تتم استضافته في تطبيق Azure Function المستقل، ولكن يتم نشره بدلاً من ذلك في تطبيق الويب الثابت كجزء من دعم واجهة برمجة التطبيقات (API) بدون خادم.

هناك أربع وظائف HTTP يتم تقديمها جميعًا من المسار الافتراضي /api/

• eventHandler - جهاز استقبال Webhook للأحداث "المنبعية" المرسلة من خدمة Azure Web PubSub، يحتوي على غالبية منطق التطبيق. لا يتم استدعاؤه مباشرة من قبل العميل، فقط Azure WebPub Sub.
• getToken - يتم استدعاؤه بواسطة العميل للحصول على رمز وصول وعنوان URL للاتصال عبر WebSockets بخدمة Azure Web PubSub. يجب استدعاؤه باستخدام معرف المستخدم في استعلام عنوان URL، على سبيل المثال GET /api/getToken?userId={user}
• getUsers - يعرض قائمة بالمستخدمين الذين سجلوا دخولهم، لاحظ أن مسار هذه الوظيفة هو /api/users
• getChats - يعرض قائمة بالمحادثات الجماعية النشطة، لاحظ أن مسار هذه الوظيفة هو /api/chats

يتم التعامل مع الحالة باستخدام state.js وهي وحدة ES6 التي تصدر وظائف تدعم الحالة CRUD للمستخدمين والمحادثات. تنفذ هذه الوحدة كل التفاعلات مع جداول Azure، وتوفر واجهة شفافة نسبيًا، بحيث يمكن تبديل واجهة تخزين خلفية مختلفة.

تدفقات رسائل WebSocket وAPI

يوجد تدفق للرسائل في اتجاهين بين العملاء والخادم عبر Azure Web PubSub ومعالجات الأحداث

يتم استخدام البروتوكول الفرعي json.webpubsub.azure.v1 بدلاً من WebSockets الأساسي، وهذا يوفر عددًا من الميزات: يمكن إضافة المستخدمين إلى المجموعات، ويمكن للعملاء إرسال أحداث مخصصة (باستخدام type: event )، وكذلك إرسال رسائل مباشرة إلى عملاء آخرين دون المرور عبر الخادم (باستخدام type: sendToGroup )

ملحوظات:

• معرفات الدردشة هي ببساطة معرفات GUID يتم إنشاؤها عشوائيًا، وهي تتوافق مع "المجموعات" في البروتوكول الفرعي.
• تعد الدردشات الخاصة حالة خاصة، فهي لا تستمر في الحالة، ولا تؤدي إلى تشغيل أحداث الدردشة التي تم إنشاؤها . كما أن المستخدم لا يصدر حدث 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 - للانضمام إلى دردشة، سيضيف الخادم مستخدمًا إلى المجموعة لمعرف الدردشة هذا
• leaveChat - لترك محادثة جماعية
• حذف الدردشة - يتم الاتصال به من مالك الدردشة لحذف الدردشة
• userEnterIdle - دع الخادم يعرف أن المستخدم خامل الآن
• userExitIdle - دع الخادم يعرف أن المستخدم لم يعد خاملاً

تحتوي وظيفة eventHandler الخاصة بواجهة برمجة التطبيقات الخلفية على حالات لكل حدث من أحداث المستخدم هذه، بالإضافة إلى معالجات لأحداث نظام الاتصال وقطع الاتصال.

رسائل الخادم

تحتوي الرسائل المرسلة من الخادم على حمولة مخصصة لتطبيق Chatr كما يلي:

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

حيث يكون eventType واحدًا مما يلي:

• تم إنشاء الدردشة - دع جميع المستخدمين يعرفون أنه تم إنشاء دردشة جماعية جديدة
• تم حذف الدردشة - دع جميع المستخدمين يعرفون أنه تمت إزالة الدردشة الجماعية
• 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) في تطبيقات الويب الثابتة محدودًا للغاية ولا يمكنه دعم الارتباطات والمشغلات الجديدة لـ Web PubSub. ومع ذلك، لا تحتاج إلى استخدام هذه الارتباطات؟ يمكنك إنشاء وظيفة HTTP قياسية لتكون بمثابة معالج حدث webhook بدلاً من استخدام ربط webPubSubConnection . لإرسال الرسائل مرة أخرى إلى Web PubSub، يمكن ببساطة استخدام SDK للخادم ضمن رمز الوظيفة بدلاً من استخدام ربط إخراج webPubSub .
• تم اختيار Table Storage للحالة المستمرة نظرًا لأنه يحتوي على JS SDK جيد (تم استخدام SDK الجديد في @azure/data-table)، فهو خفيف الوزن للغاية ورخيص الثمن وكان جيدًا بما يكفي لهذا المشروع، راجع التفاصيل أدناه

تصميم الدولة والكيان

تتكون الحالة في جداول Azure من جدولين (مجموعات) تسمى chats users

جدول الدردشات

نظرًا لأن كل دردشة تحتوي على كائنات متداخلة داخل حقل الأعضاء، يتم تخزين كل دردشة كسلسلة JSON في حقل يسمى data . لا يتم استخدام PartitionKey وترميزه ضمن سلسلة "chatr". مفتاح الصف وحقل المعرف داخل كائن البيانات متماثلان.

• مفتاح التقسيم : "الدردشة"
• RowKey : معرف الدردشة (معرف GUID عشوائي تم إنشاؤه من جانب العميل)
• البيانات : كيان دردشة 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".

• مفتاح التقسيم : "الدردشة"
• RowKey : تم إرجاع حقل userId من نقطة نهاية مصادقة تطبيقات الويب الثابتة
• userName : اسم المستخدم (يمكن أن يكون عنوان بريد إلكتروني أو عنوان بريد إلكتروني) للمستخدم
• userProvider : ما هي المصادقة التي قدمت للمستخدم تسجيل الدخول باستخدام twitter أو aad أو github
• خامل : منطقي، يشير إلى ما إذا كان المستخدم خاملاً حاليًا

تشغيل ونشر التطبيق

العمل محليا

انظر ملف التعريف

 $ 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 الموجودة في مجلد النشر/

راجع الملف التمهيدي في مجلد النشر للحصول على التفاصيل والتعليمات

تشغيل محليا

هذا ممكن ولكنه يتطلب القليل من الجهد حيث تحتاج خدمة Azure Web PubSub إلى أن تكون قادرة على الاتصال بنقطة نهاية HTTP على جهاز الموقع الخاص بك، لذلك تم استخدام النفق.

عند التشغيل محليًا، يتم استخدام واجهة سطر أوامر Static Web Apps وهذا يوفر لنا نقطة نهاية وهمية لمصادقة المستخدم.

ملخص الخطوات هو:

• انشر حساب Azure Storage ، واحصل على الاسم ومفتاح الوصول.
• انشر مثيل Azure Web Pub Sub ، واحصل على سلسلة الاتصال من صفحة "المفاتيح".
• انسخ api/local.settings.sample.json إلى api/local.settings.json وقم بتحرير قيم الإعدادات المطلوبة.
• ابدأ خدمة نفق مضيف محلي مثل ngrok أو ثغرة . يجب أن يعرض النفق المنفذ 7071 عبر HTTP.
  أستخدم الثغرة لأنها تسمح لي بتعيين مضيف مخصص واسم DNS، على سبيل المثال
  • loophole http 7071 --hostname chatr
• في إعدادات Azure Web Pub Sub .
  • أضف مركزًا باسم الدردشة
  • في قالب URL، ضع https://{{hostname-of-tunnel-service}}/api/eventHandler
  • في أحداث النظام، ضع علامة على متصل ومنفصل
• تشغيل make run
• افتح http://localhost:4280/index.html

القضايا المعروفة

• لن يتم تشغيله في Firefox لأن انتظار المستوى الأعلى غير مدعوم بعد