chatr

Chatr - Aplikasi Contoh Azure Web PubSub

Ini adalah demonstrasi & contoh aplikasi yang dirancang untuk menjadi sistem obrolan berbasis web multi-pengguna yang sederhana.
Ini menyediakan obrolan grup persisten, obrolan pribadi pengguna ke pengguna, daftar pengguna, deteksi idle (jauh dari keyboard) dan beberapa fitur lainnya.

Itu dibangun di beberapa teknologi Azure, termasuk: Web PubSub, Aplikasi Web Statis , dan Penyimpanan Tabel

?‍? Catatan. Ini dibuat sebagai proyek pribadi, dibuat untuk membantu pembelajaran sambil membangun sesuatu yang menarik. Kode ini dilengkapi dengan semua peringatan yang mungkin Anda harapkan dari proyek semacam itu.

Sasaran:

• Pelajari tentang menggunakan soket web
• Tulislah hal yang 'menyenangkan'
• Cobalah layanan Azure Web PubSub yang baru
• Gunakan fitur autentikasi Azure Static Web Apps
• Terapkan semuanya menggunakan Azure Bicep

Kasus penggunaan & fitur utama:

• Masuk dengan akun Microsoft, Twitter, atau GitHub
• Obrolan waktu nyata dengan pengguna
• Obrolan grup bersama, hanya pembuatnya yang dapat menghapus obrolan tersebut
• Mendeteksi saat pengguna menganggur dan jauh dari keyboard (defaultnya adalah satu menit)
• Obrolan pribadi 'pengguna ke pengguna', dengan notifikasi dan popup

Tangkapan layar

Arsitektur

Klien / Frontend

Ini adalah antarmuka web utama yang digunakan oleh pengguna akhir melalui browser.

Sumber untuk ini ditemukan di client/ dan terdiri dari aplikasi ES6 JS murni mandiri yang statis, tidak diperlukan bundling atau Node.js. Itu ditulis menggunakan Vue.js sebagai kerangka pendukung, dan Bulma sebagai kerangka CSS.

Beberapa catatan:

• Modul ES6 digunakan agar berbagai file JS dapat menggunakan impor/ekspor tanpa perlu dibundel.
• Vue.js digunakan sebagai perpustakaan sisi browser yang dimuat dari CDN sebagai modul ESM, ini adalah pendekatan elegan & ringan yang didukung oleh browser modern, daripada aplikasi gaya vue-cli biasa yang memerlukan Node dan webpack dll.
• client/js/app.js menunjukkan cara membuat aplikasi Vue.js dengan komponen turunan menggunakan pendekatan ini. Mayoritas logika klien ada di sini.
• client/js/components/chat.js adalah komponen Vue.js yang digunakan untuk meng-host setiap tab obrolan dalam aplikasi
• Titik akhir .auth/ khusus yang disediakan oleh Static Web Apps digunakan untuk memasukkan pengguna dan mengambil detail pengguna mereka, seperti userId.

pelayan

Ini adalah backend, yang menangani kejadian websocket ke dan dari Azure Web PubSub, dan menyediakan REST API untuk beberapa operasi.

Sumbernya ditemukan di api/ dan terdiri dari Aplikasi Fungsi Azure Node.js. Ini terhubung ke Azure Table Storage untuk mempertahankan obrolan grup dan data pengguna (Table Storage dipilih karena sederhana & murah). Ini tidak dihosting di Aplikasi Fungsi Azure yang berdiri sendiri, melainkan disebarkan ke Aplikasi Web Statis sebagai bagian dari dukungan API tanpa servernya

Ada empat fungsi HTTP yang semuanya dilayani dari jalur /api/ default

• eventHandler - Penerima webhook untuk peristiwa "hulu" yang dikirim dari layanan Azure Web PubSub, berisi sebagian besar logika aplikasi. Tidak dipanggil langsung oleh klien, hanya Sub Azure WebPub.
• getToken - Dipanggil oleh klien untuk mendapatkan token akses dan URL untuk terhubung melalui WebSockets ke layanan Azure Web PubSub. Harus dipanggil dengan userId di kueri URL, misalnya GET /api/getToken?userId={user}
• getUsers - Mengembalikan daftar pengguna yang masuk, perhatikan rute untuk fungsi ini adalah /api/users
• getChats - Mengembalikan daftar obrolan grup yang aktif, perhatikan rute untuk fungsi ini adalah /api/chats

Status ditangani dengan state.js yang merupakan fungsi pengekspor modul ES6 yang mendukung CRUD status untuk pengguna dan obrolan. Modul ini menjalankan semua interaksi dengan Azure Tables, dan menyediakan antarmuka yang relatif transparan, sehingga backend penyimpanan yang berbeda dapat ditukar.

Alur Pesan WebSocket & API

Ada aliran pesan dua arah antara klien dan server melalui Azure Web PubSub dan pengendali peristiwa

Subprotokol json.webpubsub.azure.v1 digunakan daripada WebSockets dasar, subprotokol ini menyediakan sejumlah fitur: pengguna dapat ditambahkan ke grup, klien dapat mengirim peristiwa khusus (menggunakan type: event ), dan juga mengirim pesan langsung ke klien lain tanpa melalui server (menggunakan type: sendToGroup )

Catatan:

• ID Obrolan hanyalah GUID yang dibuat secara acak, ini sesuai dengan "grup" di subprotokol.
• Obrolan pribadi adalah kasus khusus, tidak dipertahankan dalam status, dan tidak memicu peristiwa chatCreated . Pengguna juga tidak mengeluarkan acara joinChat untuk bergabung dengan mereka, yang ditangani oleh server sebagai semacam "push" ke klien.
• ID Pengguna hanyalah string yang dianggap unik, hal ini dapat ditingkatkan, misalnya dengan awalan.

Pesan Klien

Acara & obrolan dikirim menggunakan subprotokol json.webpubsub.azure.v1

Pesan obrolan yang dikirim dari klien menggunakan sendToGroup dan muatan JSON khusus dengan tiga bidang message , fromUserId & fromUserName , pesan-pesan ini diteruskan dari klien ke klien oleh Azure Web PubSub, server tidak pernah diberi tahu tentangnya:

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

Peristiwa yang ditujukan untuk server backend dikirim sebagai pesan WebSocket dari klien melalui subprotokol yang sama dengan jenis event , dan subjenis aplikasi tertentu, misalnya

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

Jenis acaranya adalah:

• createChat - Minta server tempat Anda ingin membuat obrolan grup
• createPrivateChat - Minta server tempat Anda ingin membuat obrolan pribadi
• joinChat - Untuk bergabung dalam obrolan, server akan menambahkan pengguna ke grup untuk chatId tersebut
• tinggalkan Obrolan - Untuk keluar dari obrolan grup
• deleteChat - Dipanggil dari pemilik obrolan untuk menghapus obrolan
• userEnterIdle - Memberi tahu server bahwa pengguna sedang menganggur
• userExitIdle - Memberi tahu server bahwa pengguna tidak lagi menganggur

Fungsi eventHandler API backend memiliki kasus untuk setiap peristiwa pengguna ini, bersama dengan penangan untuk peristiwa sistem koneksi & pemutusan.

Pesan Server

Pesan yang dikirim dari server memiliki muatan khusus aplikasi Chatr khusus sebagai berikut:

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

Dimana eventType adalah salah satu dari:

• chatCreated - Memberi tahu semua pengguna bahwa obrolan grup baru telah dibuat
• chatDeleted - Memberi tahu semua pengguna bahwa obrolan grup telah dihapus
• userOnline - Memberi tahu semua pengguna bahwa pengguna telah online
• userOffline - Memberi tahu semua pengguna bahwa ada pengguna yang keluar
• joinPrivateChat - Dikirim ke pemrakarsa dan penerima obrolan pribadi
• userIsIdle - Dikirim ke semua pengguna saat pengguna memasuki kondisi idle
• userNotIdle - Dikirim ke semua pengguna saat pengguna keluar dari status idle

Kode klien di client/js/app.js menangani pesan-pesan ini saat diterima oleh klien, dan bereaksi sesuai dengan itu.

Beberapa Catatan tentang Desain dan Pilihan Layanan

Rencana proyek ini adalah menggunakan Azure Web PubSub dan Azure Static Web Apps , dan menghosting komponen sisi server sebagai serangkaian fungsi tanpa server dalam dukungan API Static Web Apps (yang sebenarnya merupakan Azure Functions ). Azure Static Web Apps dipilih karena memiliki dukungan luar biasa untuk login dan autentikasi pengguna tanpa kode dan tanpa konfigurasi, yang ingin saya manfaatkan.

Beberapa komentar mengenai pendekatan ini:

• Dukungan API di Aplikasi Web Statis sangat terbatas dan tidak dapat mendukung pengikatan dan pemicu baru untuk Web PubSub. NAMUN Anda tidak perlu menggunakan binding ini?. Anda dapat membuat fungsi HTTP standar untuk bertindak sebagai pengendali peristiwa webhook alih-alih menggunakan pengikatan webPubSubConnection . Untuk mengirim pesan kembali ke Web PubSub, SDK server cukup digunakan dalam kode fungsi daripada menggunakan pengikatan keluaran webPubSub .
• Penyimpanan Tabel dipilih karena statusnya bertahan karena memiliki JS SDK yang bagus (SDK baru di @azure/data-table digunakan), sangat ringan dan murah serta cukup baik untuk proyek ini, lihat detailnya di bawah

Desain Negara & Entitas

Status di Tabel Azure terdiri dari dua tabel (koleksi) bernama chats dan users

Tabel Obrolan

Karena setiap obrolan berisi objek bersarang di dalam bidang member, setiap obrolan disimpan sebagai string JSON dalam bidang yang disebut data . PartitionKey tidak digunakan dan di-hardcode ke string "chatr". RowKey dan kolom id di dalam objek data adalah sama.

• PartitionKey : "obrolan"
• RowKey : ChatId (GUID acak dibuat di sisi klien)
• data : entitas obrolan string JSON

Contoh entitas data obrolan

{
  "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 "
}

Tabel Pengguna

Pengguna disimpan sebagai entitas dengan bidang (kolom) yang dijelaskan di bawah. Karena tidak ada bidang bersarang, maka tidak perlu melakukan enkode sebagai string JSON. Sekali lagi PartitionKey tidak digunakan dan di-hardcode ke string "chatr".

• PartitionKey : "obrolan"
• RowKey : Bidang userId dikembalikan dari titik akhir autentikasi Static Web Apps
• userName : Nama pengguna (bisa berupa alamat email atau nama pengguna) pengguna
• userProvider : Otentikasi mana yang menyediakan pengguna masuk dengan twitter , aad atau github
• idle : Boolean, menunjukkan jika pengguna sedang menganggur

Menjalankan dan Menerapkan Aplikasi

Bekerja Secara Lokal

Lihat makefile

 $ 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

Menyebarkan ke Azure

Penerapannya sedikit rumit karena jumlah komponen dan konfigurasi di antara komponen tersebut. deploy target makefile harus menyebarkan semuanya untuk Anda dalam satu langkah menggunakan templat Bicep yang ada di folder deploy/

Lihat readme di folder penerapan untuk detail dan instruksi

Berjalan Secara Lokal

Hal ini mungkin dilakukan tetapi memerlukan sedikit usaha karena layanan Azure Web PubSub harus dapat memanggil titik akhir HTTP di mesin lokasi Anda, sehingga terowongan telah digunakan.

Saat dijalankan secara lokal, CLI Aplikasi Web Statis digunakan dan ini menyediakan titik akhir otentikasi pengguna palsu untuk kami.

Ringkasan langkah-langkahnya adalah:

• Terapkan akun Azure Storage , dapatkan nama dan kunci akses.
• Sebarkan instans Azure Web Pub Sub , dapatkan string koneksi dari halaman 'Kunci'.
• Salin api/local.settings.sample.json ke api/local.settings.json dan edit nilai pengaturan yang diperlukan.
• Mulai layanan terowongan localhost seperti ngrok atau loophole . Terowongan harus mengekspos port 7071 melalui HTTP.
  Saya menggunakan celah karena memungkinkan saya untuk mengatur host khusus & nama DNS, misalnya
  • loophole http 7071 --hostname chatr
• Dalam pengaturan Sub Azure Web Pub .
  • Tambahkan hub bernama obrolan
  • Di templat URL, masukkan https://{{hostname-of-tunnel-service}}/api/eventHandler
  • Dalam peristiwa sistem, centang terhubung dan terputus
• Lari, make run
• Buka http://localhost:4280/index.html

Masalah yang Diketahui

• Tidak akan berjalan di Firefox karena menunggu tingkat atas belum didukung