پروژهٔ چت سادهٔ وب با Node.js و WebSocket

«گفت‌وگوی کوچک» یک پروژهٔ قابل اجرا برای دیدن ارتباط زندهٔ مرورگر و Node.js است. دو پنجرهٔ مرورگر را باز می‌کنید، در هر کدام نامی ساختگی می‌نویسید و وارد یک اتاق مشترک می‌شوید. پیام پذیرفته‌شده در سرور، بدون تازه‌کردن صفحه به کاربران متصل می‌رسد. این بسته شامل کد واقعی صفحه، سرور، آزمون‌ها و راهنمای فارسی اجرا و دیباگ است؛ تصویر صفحه یا پاسخ‌های از پیش نوشته‌شده جای ارتباط زنده را نگرفته‌اند.

این پروژه چه چیزی به آموزش‌های قبلی اضافه می‌کند؟

در پروژهٔ «سلام، سرور!» هر بار یک درخواست HTTP می‌فرستادیم و یک پاسخ می‌گرفتیم. این بار WebSocket یک اتصال زنده میان مرورگر و سرور نگه می‌دارد تا هر طرف در زمان لازم پیام بفرستد. مرورگر از WebSocket داخلی خودش استفاده می‌کند و Node.js با بستهٔ رسمی و مشخص‌شدهٔ ws ارتباط را مدیریت می‌کند. پروتکل سطح پایین WebSocket را دستی بازنویسی نکرده‌ایم؛ تمرکز تمرین بر قرارداد پیام، وضعیت اتصال، پاک‌سازی منابع و رفتار قابل توضیح هنگام خطاست.

اگر مبانی هنوز دشوار است، ابتدا دورهٔ مقدماتی و متوسط JavaScript و آماده‌سازی Node.js در ویندوز را مرور کنید. دو دورهٔ تکمیلی تازه نیز جدا از هم نوشته شده‌اند: مسیر JavaScript دربارهٔ متن فارسی، URL، زمان، پیمایش، بایت و چرخهٔ عمر کلاینت است؛ مسیر Node.js دربارهٔ EventEmitter، Stream، WebSocket، پخش پیام و آزمون سرور است. پروژه محل کنار هم قرارگرفتن این دو مسیر است، نه تکرار فشردهٔ همهٔ درس‌ها در یک صفحه.

مسیر JavaScript:
https://www.darsavand.com/courses/javascript-data-lifecycle-realtime
مسیر Node.js:
https://www.darsavand.com/courses/nodejs-events-streams-websocket
پروژهٔ قبلی صفحه و API:
https://www.darsavand.com/courses/nodejs-http-server-page-api-tls

پیش از اجرا، مرز اتاق مشترک را بدانید

این نمونه یک اتاق آموزشی عمومی دارد. نامی که وارد می‌کنید فقط نام نمایشی است و هویت شما را تأیید نمی‌کند. هر اتصال پذیرفته‌شده می‌تواند حداکثر ۵۰ پیام آخر همان فرایند را ببیند. تاریخچه در حافظه است و با توقف یا راه‌اندازی دوبارهٔ سرور از بین می‌رود. حساب کاربری، پیام خصوصی، پایگاه داده و ذخیرهٔ دائمی در این نسخه وجود ندارد؛ از نام و محتوای ساختگی استفاده کنید. بازکردن صفحه در دو تب هم برای آزمایش کافی است.

شروع روی ویندوز و اوبونتو

Node.js نسخهٔ ۲۴ یا نسخهٔ پشتیبانی‌شدهٔ جدیدتر، npm و مرورگر جدید لازم است. ZIP را استخراج کنید و پوشهٔ project را باز کنید؛ package.json باید دقیقاً در همان پوشه دیده شود. ابتدا وابستگی قفل‌شده را نصب کنید، سپس آزمون و اجرای برنامه را انجام دهید. npm ci بر اساس package-lock.json نصب می‌کند و به دسترسی به مخزن بسته نیاز دارد؛ فایل‌های node_modules داخل ZIP قرار نگرفته‌اند. فایل را با file:// باز نکنید، چون در آن حالت سرور و اتصال چت اجرا نمی‌شوند.

# PowerShell ویندوز؛ در پوشهٔ project دارای package.json
node --version
npm.cmd ci
npm.cmd test
npm.cmd start

# ترمینال اوبونتو؛ در پوشهٔ project دارای package.json
node --version
npm ci
npm test
npm start

در مرورگر دقیقاً http://127.0.0.1:3001 را باز کنید و همین نشانی را در تب دوم نیز وارد کنید. در تنظیم پیش‌فرض، localhost و 127.0.0.1 دو مبدأ متنی متفاوت‌اند؛ اگر یکی را به جای دیگری باز کنید، بررسی Origin می‌تواند اتصال چت را رد کند. تا وقتی سرور در ترمینال پاسخ می‌دهد، برنگشتن خط فرمان طبیعی است. برای توقف فقط در ترمینال همان پروژه Ctrl+C بزنید. اگر پورت اشغال است، راهنمای RUNBOOK را بخوانید و تنظیم PORT و PUBLIC_ORIGIN را هماهنگ تغییر دهید؛ همهٔ برنامه‌های Node دستگاه را متوقف نکنید.

اولین آزمایش با دو کاربر ساختگی

در تب اول «سارا» و در تب دوم «آوند» را وارد کنید. پیش از رسیدن تاریخچهٔ اولیه، کادر ارسال باید آماده نباشد. پس از آماده‌شدن اتصال، یک پیام کوتاه بفرستید و رسیدن همان پیام به هر دو تب را ببینید. تازه‌کردن تب باید تاریخچهٔ محدود را از سرور دوباره بخواند. شمارندهٔ آنلاین، تعداد اتصال‌های واردشده است و تعداد افراد یکتا را ثابت نمی‌کند؛ یک نفر با دو تب می‌تواند دو اتصال داشته باشد.

در این پروژه #json قرارداد پیام را قابل مشاهده می‌کند؛ معتبر‌بودن JSON به‌تنهایی کافی نیست و نوع و فیلدهای هر پیام نیز بررسی می‌شوند. برای متن از نام ساختگی و پیام فارسی استفاده کنید. طول متن هم بر اساس کدپوینت و هم بایت UTF-8 محدود است؛ بنابراین طول رشته و حجم شبکه یک مفهوم واحد نیستند. درس دادهٔ باینری این تفاوت را با TextEncoder نشان می‌دهد.

ارسال موفق، ردشده و نامعلوم چه فرقی دارند؟

سرور برای پیام پذیرفته‌شده شناسه، ترتیب و زمان می‌سازد و یک پاسخ تأیید می‌فرستد. زمان نمایشی در مرورگر فارسی می‌شود، ولی ترتیب معتبر پیام‌ها از شمارندهٔ سرور همان فرایند می‌آید. اگر اتصال هنگام انتظار پاسخ قطع شود، کلاینت نمی‌تواند با قطعیت بگوید سرور پیام را پذیرفته است یا نه؛ وضعیت «نامعلوم» را نشان می‌دهد. پیام نامعلوم خودکار دوباره ارسال نمی‌شود، چون ممکن است تکراری شود. در رابط، تصمیم ارسال دوباره با کاربر است و این احتمال توضیح داده می‌شود.

شناسهٔ درخواست در همان اتصال و در پنجرهٔ محدود نگهداری‌شده به مهار ارسال تکراری کمک می‌کند، اما تضمین «دقیقاً یک بار» در همهٔ قطع و وصل‌ها ایجاد نمی‌کند. اتصال تازه، راه‌اندازی دوبارهٔ سرور و حذف شناسه از حافظهٔ محدود، مرز این رفتارند. برای فهم مدل وضعیت، به #event-listener و #timers رجوع کنید: شنونده، تایمر و اتصال باید صاحب و نقطهٔ پایان مشخص داشته باشند تا چند اتصال پنهان یا چند ارسال ناخواسته ایجاد نشود.

دیباگ را از لایهٔ خطا شروع کنید

اگر صفحه اصلاً باز نمی‌شود، نخست ترمینال و پورت را بررسی کنید. اگر صفحه باز است ولی چت وصل نمی‌شود، در ابزار توسعهٔ مرورگر، Network و اتصال WebSocket مسیر /chat را ببینید؛ پاسخ ۱۰۱ یعنی ارتقای ارتباط انجام شده است، ولی آماده‌شدن برنامه هنوز به دریافت تاریخچه نیاز دارد. خطای ۴۰۳ معمولاً شما را به تطابق دقیق PUBLIC_ORIGIN و نشانی صفحه هدایت می‌کند. خطای ۵۰۲ در اجرای Nginx نیز نیازمند بررسی سرویس Node و پراکسی است، نه تغییر کد متن پیام.

اگر پیام رد می‌شود، توضیح رابط و بستهٔ خطای سرور را با قرارداد مقایسه کنید. متن خالی، پیام باینری، فیلد اضافه و عبور از محدودیت‌ها رفتار یکسان ندارند. برای دیدن ورودی در دیباگر از دادهٔ ساختگی استفاده کنید. راهنمای RUNBOOK شامل روش یافتن پورت اشغال، مشکل نصب وابستگی، تفاوت محیط اجرا، دیباگ با Node inspector، قطع ارتباط، خطای Origin و تنظیم WSS است. هر نشانه همراه یک اقدام و نتیجهٔ مورد انتظار توضیح داده شده است.

اجرای اوبونتو و WSS

پوشهٔ deploy نمونهٔ مستقل systemd و Nginx همین پروژه را دارد. برنامه به‌صورت پیش‌فرض روی لوپ‌بک اجرا می‌شود و Nginx در انتشار عمومی، HTTPS و ارتقای WebSocket را مدیریت می‌کند. WSS شکل رمزگذاری‌شدهٔ اتصال WebSocket است. اگر صفحه HTTPS است، نشانی WebSocket هم از همان مبدأ به wss تبدیل می‌شود؛ نشانی سرور دلخواه در فرم از کاربر گرفته نمی‌شود. Origin تنظیم‌شده همچنان نشانی https صفحه است، نه wss.

صدور و تمدید Let’s Encrypt و نصب دستی گواهی در دورهٔ قبلی TLS با جزئیات آمده است. در این بسته، گواهی یا کلید خصوصی آماده قرار ندارد و نباید دامنهٔ نمونه را بدون جایگزینی اجرا کنید. مسیر استقرار چت، کاربر سرویس و پورت از پروژه‌های قبلی جدا هستند تا دستورهای آموزشی، کد پروژهٔ قبلی را بازنویسی نکنند. پیش از انتشار اینترنتی، محدودیت‌های نمونهٔ بدون هویت و تاریخچهٔ مشترک را بشناسید.

فایل‌ها و معیار تحویل

کد سرور و مدل پیام، کلاینت HTML/CSS/JavaScript، package.json و lockfile، آزمون‌ها، README فارسی، RUNBOOK رفع مشکل و نمونهٔ تنظیم اوبونتو در بسته موجودند. برای تحویل تمرین، نتیجهٔ دو کاربر، نمایش متن فارسی، ورودی نامعتبر، قطع و اتصال دوباره، ازبین‌رفتن تاریخچه پس از restart و آزمون‌های خودکار را ثبت کنید. اجرای موفق تنها با یک کاربر، پخش پیام میان اتصال‌های مستقل را ثابت نمی‌کند.

متن و کد اختصاصی تحریریه درس‌آوند است. منابع رسمی انگلیسی برای فهم و بررسی رفتار در دو دورهٔ همراه ذکر شده‌اند؛ مثال‌ها برای همین پروژه طراحی شده‌اند. این پروژه آموزشی است و ادعای آماده‌بودن یک پیام‌رسان عمومی با احراز هویت، مدیریت محتوا، حریم خصوصی و ذخیره‌سازی پایدار ندارد.