Node.js/net

مؤشر الاستقرار: 2 - مستقر.

توفر الوحدة net واجهة تطبيقات لشبكة اتصال غير متزامن لإنشاء خوادم قائمة على تدفق اتصالات TCP أو IPC أي (net.createServer()‎) والعملاء (net.createConnection()‎).

ويمكن الوصول إليه باستخدام:

const net = require('net');

دعم اتصالات IPC

تدعم وحدة net اتصالات IPC بواسطة الأنابيب المُسماة (named pipes) في ويندوز، أو مقابس مجالات يونكس (UNIX domain sockets) في أنظمة التشغيل الأخرى.

تحديد مسارات اتصالات IPC

تحتاج التوابع net.connect()‎ و net.createConnection()‎ و server.listen()‎ و socket.connect()‎ المعامل path لتحديد نهايات اتصالات IPC.

يُعرف النطاق المحلي في UNIX بنطاق UNIX. ويكون المسار هو اسم مسار نظام الملفات. ويجري اقتصاصها إلى حجم يساوي sizeof(sockaddr_un.sun_path)-1، والذي يختلف من نظام تشغيل إلى آخر بين 91 و 107 بايت. القيم النموذجية هي 107 في نظام لينكس و 103 في نظام macOS. ويخضع المسار لنفس اصطلاحات التسمية وفحص الأذونات بنفس كيفية إنشاء ملف. إذا أُنشئ مقبس مجال UNIX (الذي يكون مرئياً كمسار نظام ملف) واستُخدم بالاقتران مع أحد تجريديات واجهات تطبيقات Node.js مثل net.createServer()‎، سينقطع ارتباطه كجزء من server.close()‎. من ناحية أخرى، إذا أُنشئ واستُخدم خارج هذه التجريديات، سوف يحتاج المستخدم لإزالته يدويًا. وينطبق الشيء نفسه عند إنشاء المسار من قِبَل واجهات تطبيقات Node.js ولكن البرنامج يتعطل فجأة. وباختصار، سيظهر مقبس مجال UNIX في نظام الملفات تم إنشاءه بنجاح، وسوف يستمر حتى يقطع ارتباطه.

في ويندوز، يتحقق النطاق المحلي باستخدام أنبوب مُسمّى. يجب أن يشير المسار إلى مُدخل في ‎\\?\pipe\‎ أو ‎\\.\pipe\‎. مسموح بأي حروف، ولكن قد يجري هذا الأخير بعض المعالجة لأسماء الأنابيب مثل أن يُترجم متواليات .. . على الرغم من كيف يمكن أن تبدو، فإن مجال أسماء الأنابيب مسطحة. لن تستمر الأنابيب. وتُزال عند إغلاق آخر مرجع إليها. على عكس مقابس مجال UNIX، يُغلق ويندوز الأنابيب ويُزيلها عند انتهاء العملية المالكة.

يتطلب الهروب من سلسلة JavaScript مسارات محددة باستخدام شرطة هروب مائلة عكسية \ إضافية مثل:

net.createServer().listen(
  path.join('\\\\?\\pipe', process.cwd(), 'myctl'));

الصنف net.Server

أُضيف مع الإصدار: v0.1.90.

يستخدم هذا الصنف لإنشاء خادم TCP أو IPC.

new net.Server([options][, connectionListener])‎

• options ‏‎<Object>‎: راجع net.createServer([options][, connectionListener])‎.
• connectionListener‏ <Function>: ضبط الدالة تلقائيًا كمستمع للحدث 'connection'.

• القيمة المُعادة: من النوع <net.Server>.

ويُعد net.Server هو EventEmitter مع الأحداث التالية:

الحدث 'close'

أُضيف مع الإصدار: v0.5.0.

يُطلَق عند إغلاق الخادم. لاحظ أنه في حالة وجود اتصالات، لا ينطلق هذا الحدث حتى إنهاء كافة الاتصالات.

الحدث 'connection'

أُضيف مع الإصدار: v0.1.90.

• <net.Socket>: وهو كائن الاتصال.

يُطلَق عند إجراء اتصال جديد. ويكون socket مثيل net.Socket.

الحدث 'error'

أُضيف مع الإصدار: v0.1.90.

• من النوع <Error>.

يُطلَق عند حدوث خطأ ما. على عكس net.Socket لا يصدر الحدث 'close' مباشرة بعد هذا الحدث إلا إذا اُستدعيَ server.close()‎ يدويًا. راجع المثال في شرح server.listen()‎.

الحدث: 'listening'

أُضيف مع الإصدار: v0.1.90.

يُطلَق عند ربط الخادم بعد استدعاء server.listen()‎.

server.address()‎

أُضيف مع الإصدار: v0.1.90.

• القيمة المُعادة: من النوع <Object> أو <string>.

يعيد العنوان address المنضم واسم عائلة العنوان family ومنفذ الخادم port كما يذكره نظام التشغيل إذا كان يستمع إلى مقبس IP (وهو يفيد في العثور على أي منفذ الذي عُيّن عند الحصول على عنوان مُعيَّن من قِبل نظام التشغيل): ‎{ port: 12346, family: 'IPv4', address: '127.0.0.1' }‎.

بالنسبة لخادم يستمع إلى أنابيب أو مقبس نطاق UNIX، يُعاد الاسم كسلسلة نصية.

على سبيل المثال:

const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // معالجة الأخطاء هنا
  throw err;
});

// انتزاع منفذ غير مستخدم عشوائيًا.
server.listen(() => {
  console.log('opened server on', server.address());
});

لا يجب استدعاء server.address()‎ حتى ينطلق الحدث 'listening'.

server.close([callback])‎

أُضيف مع الإصدار: v0.1.90.

• callback‏ <Function>: الدالة التي ستستدعى عند إغلاق الاتصال مع الخادم.

• القيمة المُعادة: من النوع <net.Server>.

يمنع الخادم من قبول اتصالات جديدة ويحافظ على الاتصالات الموجودة. وهو دالة غير متزامنة، ويُغلَق الخادم أخيراً عند إنهاء كافة الاتصالات ويُطلِق الخادم حدث 'close'. وتُستدعى دالة رد الاتصال callback الاختيارية بمجرد حدوث الحدث 'close'. على عكس هذا الحدث ستستدعى مع Error كوسيط وحيد إذا كان الخادم غير مفتوح عند إغلاقه.

server.connections (مُهمَل)

أُضيف مع الإصدار: v0.2.0، وأُهمِل مع الإصدار: v0.9.7.

مؤشر الاستقرار: 0 - مُهمل: يُستخدم server.getConnections()‎ بدلاً منه.

عدد الاتصالات المتزامنة مع الخادم.

ويصبح null عند إرسال مقبس لأحد الأبناء بواسطة التابع child_process.fork()‎. لاستطلاع التفرعات والحصول على العدد الحالي من الاتصالات النشطة يستخدم التابع server.getConnections()‎ غير المتزامن بدلاً من ذلك.

server.getConnections(callback)‎

أُضيف مع الإصدار: v0.9.7.

• callback‏ <Function>.

• القيمة المُعادة: من النوع <net.Server>.

يعيد بشكل غير متزامن عدد الاتصالات المتزامنة مع الخادم. يعمل عند إرسال مقبس التوصيل إلى التفريعات.

يجب تمرير وسيطين لدالة رد الاتصال err و count.

server.listen()‎

بدء تشغيل خادم يستمع للاتصالات. يمكن أن يكون net.Server خادم TCP أو IPC اعتمادًا على ما يستمع إليه.

الأشكال الممكنة:

• server.listen(handle[, backlog][, callback])‎
• server.listen(options[, callback])‎
• server.listen(path[, backlog][, callback])‎ لخوادم IPC.
• server.listen([port[, host[, backlog]]][, callback])‎ لخوادم TCP.

هذه الدالة غير متزامنة. عند بدء الخادم في الاستماع، يُطلق حدث 'listening'. وسيضاف المعامل الأخير callback كمستمع للحدث 'listening'.

يمكن أن تأخذ جميع توابع listen()‎‎ معامل تراكم backlog لتعيين الحد الأقصى لطول قائمة الانتظار للاتصالات المعلقة. وستُحدد المدة الفعلية من قِبل نظام التشغيل من خلال إعدادات sysctl مثل tcp_max_syn_backlog و somaxconn في Linux. وتكون القيمة الافتراضية لهذا المعامل 511 (وليس 512).

وتُضبط جميع net.Socket على SO_REUSEADDR (انظر socket(7)‎ لمزيد من التفاصيل).

يمكن استدعاء التابع server.listen()‎ مرة أخرى إذا وفقط إذا كان هناك خطأ أثناء استدعاء server.listen()‎ الأول أو استدعاء server.close()‎. خلاف ذلك، سيُطلق خطأ ERR_SERVER_ALREADY_LISTEN.

أحد الأخطاء الأكثر شيوعاً التي أثيرت عند الاستماع هو EADDRINUSE. ويحدث هذا عند استماع خادم آخر على port/path/handle المطلوبين. أحد طرق التعامل مع ذلك يكون بإعادة المحاولة بعد فترة معينة من الزمن:

server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.log('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

server.listen(handle[, backlog][, callback])‎

أُضيف مع الإصدار: v0.5.10.

• handle من النوع <Object>.
• backlog من النوع <number>: وهو معامل شائع لدوال server.listen()‎.
• callback من النوع <Function>: وهو معامل شائع لدوال server.listen()‎.

• القيمة المُعادة: من النوع <net.Server>.

بدء تشغيل خادم للاستماع للاتصالات على handle سبق ربطه مع منفذ، أو مقبس نطاق UNIX، أو أنبوب ويندوز المسمى.

يمكن أن يكون الكائن handle أما خادم أو مقبس (أي شيء مع عضو ‎_handle أساسي) أو كائن مع عضو fd يكون واصف ملف صالح.

ولا يدعم ويندوز الاستماع إلى واصف ملف.

server.listen(options[, callback])‎

أُضيفت مع الإصدار: 0.11.14.

• options من النوع <Object>: ويجب إدخاله. وهو يدعم الخصائص التالية:
  • port من النوع <number>.
  • host من النوع <string>.
  • path من النوع <string>: سيُتجاهل إذا حُدِد port. راجع تحديد مسارات اتصالات IPC.
  • backlog من النوع <number>: وهو معامل شائع لدوال server.listen()‎.
  • exclusive من النوع <boolean>. وتكون القيمة الافتراضية: false.
  • readableAll من النوع <boolean>: وهو يجعل الأنابيب مقروءة لجميع المستخدمين في خوادم IPC. وتكون القيمة الافتراضية: false.
  • writableAll من النوع <boolean>: وهو يجعل الأنابيب قابلة للكتابة لجميع المستخدمين في خوادم IPC. وتكون القيمة الافتراضية: false.
• callback من النوع <Function> وهو معامل شائع لدوال server.listen()‎.
• القيمة المُعادة: من النوع <net.Server>.

إذا حُدد port، فإنه يتصرف بنفس أسلوب server.listen([port[, host[, backlog]]][, callback])‎. وبخلاف ذلك، إذا حُدد path، فإنه يتصرف بنفس أسلوب server.listen(path[, backlog][, callback])‎. وإذا لم يحدد أي منهما، سيُطلَق خطأ.

إذا كانت قيمة exclusive هي false (افتراضيًا)، ستستخدم مشغلات العنقود نفس المعالج الأساسي، سامحًا بمشاركة مهام معالجة الاتصال. أما إذا كانت قيمة exclusive هي true، فلا تُشارَك المُعالج، وتؤدي محاولة مشاركة المنفذ إلى خطأ. فيما يلي مثال على الاستماع إلى منفذ حصري:

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true
});

قد يتسبب بدء تشغيل خادم IPC كجذر في أن يكون مسار الخادم غير قابل للوصول للمستخدمين غير المتمتعين بامتيازات. سيؤدي استخدام readableAll و writableAll إلى أن يكون الخادم في متناول جميع المستخدمين.

server.listen(path[, backlog][, callback])‎

أُضيف مع الإصدار: v0.1.90.

• path من النوع <string>: وهو المسار الذي يجب على الخادم الاستماع إليه. راجع تحديد مسارات اتصالات IPC.
• backlog من النوع <number>: وهو معامل شائع لدوال server.listen()‎.
• callback من النوع <Function>: وهو معامل شائع لدوال server.listen()‎.
• القيمة المُعادة: من النوع <net.Server>.

بدء تشغيل خادم IPC للاستماع للاتصالات على path معين.

server.listen([port[, host[, backlog]]][, callback])‎

أُضيف مع الإصدار: v0.1.90.

• port من النوع <number>.
• host من النوع <string>.
• backlog من النوع <number> وهو معامل شائع لدوال server.listen()‎.
• callback من النوع <Function>: وهو معامل شائع لدوال server.listen()‎.
• القيمة المُعادة: من النوع <net.Server>.

بدء تشغيل خادم TCP للاستماع للاتصالات على port و host معينين.

إذا حُذف المنفذ port أو كان 0، سيُعين نظام التشغيل منفذ عشوائي غير مستخدم، والذي يمكن استعادته باستخدام server.address()‎‎.port بعد إطلاق الحدث 'listening'.

إذا حُذف المضيف host، سيقبل الخادم الاتصالات على عنوان IPv6 غير محدد (::) عندما يتوفر IPv6، أو عنوان IPv4 غير محدد (0.0.0.0) خلاف ذلك.

في معظم أنظمة التشغيل قد يتسبب الاستماع إلى عنوان IPv6 غير محدد (::) في استماع net.Server أيضا إلى عنوان IPv4 غير محدد (0.0.0.0).

server.listening

أُضيفت مع الإصدار: v5.7.0.

• من النوع <boolean>: وهو يشير إلى ما إذا كان الخادم يستمع للاتصالات أم لا.

server.maxConnections

أضيفت مع الإصدار: v0.2.0.

تُضبط هذه الخاصية لرفض الاتصالات عندما يكون عدد الاتصالات بالخادم كبيرًا.

من غير المستحسن استخدام هذا الخيار عند إرسال مقبس إلى أحد الأبناء خلال child_process.fork()‎.

server.ref()‎

أُضيف مع الإصدار: v0.9.1.

• القيمة المُعادة: من النوع <net.Server>.

على عكس unref()‎، استدعاء ref()‎ على خادم سبق إجراء unref عليه لن يسمح للبرنامج بالانتهاء إذا كان هو الخادم الوحيد المتبقي (السلوك الافتراضي). أما استدعاء ref()‎ مرة أخرى على خادم سبق إجراء ref عليه فلن يكون له أي تأثير.

server.unref()‎

أُضيف مع الإصدار: v0.9.1.

• القيمة المُعادة: من النوع <net.Server>.

يسمح استدعاء unref()‎ على خادم للبرنامج بالإنهاء إذا كان هو الخادم النشط الوحيد في نظام الأحداث. أما  استدعاء unref()‎ مرة أخرى على خادم سبق إجراء unref عليه فلن يكون له أي تأثير.

الصنف net.Socket

أُضيف مع الإصدار: v0.3.4.

يعد هذا الصنف تجريد لمقبس TCP أو لنقطة نهاية دفق IPC (يستخدم الأنابيب المسماة في ويندوز، ومقابس مجال UNIX خلاف ذلك). وتعد net.Socket أيضا تيارًا مزدوجًا (duplex stream)، حيث يمكن أن تكون قابلة للقراءة والكتابة على حد سواء، وهي أيضا EventEmitter.

ويمكن للمستخدم إنشاء net.Socket واستخدامها مباشرة في التفاعل مع الخادم. على سبيل المثال، تُعاد من قِبل net.createConnection()‎، بحيث يمكن للمستخدم استخدامها للتحدث إلى الخادم.

ويمكن أيضا إنشاؤها بواسطة Node.js وتمريرها إلى المستخدم عند تلقي اتصال. على سبيل المثال، تُمرر إلى مستمعي الحدث 'connection' المُصدر على net.Server بحيث يمكن للمستخدم استخدامها للتفاعل مع العميل.

new net.Socket([options])‎

أُضيف مع الإصدار: v0.3.4.

إنشاء كائن مقبس جديد.

• options من النوع <Object>: .الخيارات المتاحة هي:
  • fd من النوع <number>: وهو يغلف حول مقبس موجود مع واصف ملف معين، خلاف ذلك سيُنشَأ مقبس جديد.
  • allowHalfOpen من النوع <boolean>: وهو يشير إلى ما إذا كان مسموح باتصالات TCP مفتوحة نصفيا. راجع net.createServer()‎‎ والحدث 'end' لمزيد من التفاصيل. القيمة الافتراضية: false.
  • readable من النوع <boolean>: وهو يسمح بالقراءة على المقبس عند تمرير fd، ويُتجاهل بخلاف ذلك. القيمة الافتراضية: false.
  • writable من النوع <boolean>: ويسمح بالكتابة على المقبس عند تمرير fd، ويُتجاهل بخلاف ذلك. القيمة الافتراضية: false.
• القيمة المُعادة: من النوع <net.Socket>.

يمكن أن يكون مأخذ التوصيل المُنشأ حديثا أما مقبس توصيل TCP أو نقطة نهاية IPC، اعتماداً على ما تتصل به من خلال connect()‎‎.

الحدث 'close'

أُضيف مع الإصدار: v0.1.90.

• hadError من النوع <boolean>: وتكون قيمتها true إذا حدث للمقبس خطأ في النقل.

يُطلٓق حالما يغلق المقبس بالكامل. ويشير الوسيط hadError وهو قيمة منطقية إذا كان المقبس مغلقا بسبب خطأ في النقل.

الحدث 'connect'

أُضيف مع الإصدار: v0.1.90.

يطلق عند إتمام اتصال المقبس بنجاح. راجع net.createConnection()‎.

الحدث 'data'

أُضيف مع الإصدار: v0.1.90.

• من النوع ‎‎<Buffer>|<string>‎

يُطلق عند استلام البيانات. وسيكون الوسيط data من النوع Buffer أو String. ويُضبط ترميز البيانات بواسطة socket.setEncoding()‎.

علما بأن data ستُفقَد إذا لم يكن هناك أي مستمع عندما يُطلِق Socket الحدث 'data'.

الحدث 'drain'

أُضيف مع الإصدار: v0.1.90.

يُطلق عندما يصبح مخزن الكتابة المؤقت فارغا. يمكن أن يستخدم لخنق التحميلات.

انظر أيضًا: القيم المعادة من socket.write()‎.

الحدث 'end'

أُضيف مع الإصدار: v0.1.90.

يطلق عندما يرسل الطرف الآخر من المقبس حزمة FIN، منهيًا بذلك الجانب المقروء من المقبس.

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

الحدث 'error'

أُضيف مع الإصدار: v0.1.90.

• من النوع <Error>.

يُطلَق عند حدوث خطأ ما. سيُستدعى الحدث 'close' مباشرة بعد هذا الحدث.

الحدث 'lookup'

سجل التغييرات

الإصدار	التغييرات
v5.10.0	أصبح المعامل host مدعومًا الآن.
v0.11.3	أضيف مع الإصدار: v0.11.3.

يُطلَق بعد حل اسم المضيف ولكن قبل الاتصال. لا ينطبق على مقابس UNIX.

• err من النوع ‎<Error> | <null>‎ وهو كائن الخطأ. انظر dns.lookup()‎.
• address من النوع <string>: وهو عنوان IP.
• family من النوع ‎<string> | <null>‎ وهو نوع العنوان. انظر dns.lookup()‎‎.
• host من النوع <string>: اسم المضيف.

الحدث 'ready'

أُضيف مع الإصدار: v9.11.0.

يُطلَق عندما يكون مقبس ما على استعداد لاستخدامه.

ويُطلَق فورًا بعد الحدث 'connect'.

الحدث 'timeout'

أُضيف مع الإصدار: v0.1.90.

يُطلَق إذا انتهت مهلة المقبس نتيجة الخمول. و الغرض منه أن يخطر فقط أن المقبس خامل. يجب على المستخدم إغلاق الاتصال يدويًا.

انظر أيضًا: socket.setTimeout()‎.

socket.address()‎

أُضيف مع الإصدار: v0.1.90.

• القيمة المُعادة: من النوع <Object>.

يعيد العنوان address المنضم واسم عائلة العنوان family ومنفذ الخادم port كما يذكره نظام التشغيل. { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.bufferSize

أُضيفت مع الإصدار: v0.3.8.

من خواص net.Socket أن التابع socket.write()‎ دائما ما يعمل. وهذا لمساعدة المستخدمين للبدء والانطلاق بسرعة. لا يمكن لجهاز الكمبيوتر مواكبة كمية البيانات المكتوبة على المقبس دائماً، فقد يؤدي ببساطة إلى بطء شديد بشبكة الاتصال. وستصُف Node.js البيانات المكتوبة إلى المقبس داخليًا وترسلها عبر الأسلاك عندما يكون ذلك ممكناً. (فهي تختار واصف ملف المقبس داخليا لكونه قابل للكتابة).

وقد تتزايد الذاكرة نتيجة لهذا التخزين الداخلي المؤقت. وتبين هذه الخاصية عدد الأحرف المخزنة حاليا بغرض كتابتها. (عدد الأحرف مساو تقريبا للعدد البايتات المراد كتابتها، ولكن قد يحتوي المخزن المؤقت على سلاسل، والتي ترمَّز ببطء، لذلك لا يمكن معرفة عدد البايتات بالضبط).

يجب أن يحاول المستخدمون الذين يعانون من كِبر أو تزايد bufferSize "خنق" تدفق البيانات في برامجهم باستخدام socket.pause()‎ و socket.resume()‎.

socket.bytesRead

أضيفت مع الإصدار: v0.5.3.

مقدار وحدات البايت المُتلقاة.

socket.bytesWritten

أضيفت مع الإصدار: v0.5.3.

مقدار وحدات البايت المُرسَلة.

socket.connect()‎

بدء اتصال مقبس معين.

الأشكال الممكنة:

• socket.connect(options[, connectListener])‎
• socket.connect(path[, connectListener])‎ لاتصالات IPC.
• socket.connect(port[, host][, connectListener])‎ لاتصالات TCP.
• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

هذه الدالة غير متزامنة. سيطلق الحدث 'connect' عند تأسيس الاتصال. إذا كان هناك مشكلة في الاتصال سيُطلق الحدث 'error' بدلا من الحدث 'connect' ويُمرر مع الخطأ إلى مستمع 'error'. سيضاف المعامل الأخير connectListener، إذا توفَّر، كمستمع للحدث 'connect' مرة واحدة.

socket.connect(options[, connectListener])‎

سجل التغييرات

الإصدار	التغييرات
v6.0.0	أصبحت قيمة الخيار hints الافتراضية 0 في كافة الحالات الآن. في السابق، كانت قيمته الافتراضية DNS.ADDRCONFIG | dns.V4MAPPED. في حالة عدم وجود خيار family.
v5.11.0	أصبح الخيار  hints  مدعومًا الآن.
v0.1.90	أضيف مع الإصدار : v0.1.90.

• options من النوع  <Object>.
• connectListener من النوع <Function>: وهو معامل شائع لتوابع socket.connect()‎. سيضاف كمستمع للحدث 'connect' مرة واحدة.
• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

بدء الاتصال على مقبس معين. لا يستخدم هذا التابع عادةً، وينبغي إنشاء المقبس و فتحه باستخدام net.createConnection()‎. وينصح باستخدامه فقط عند تنفيذ مقبس مخصص.

الخيارات المتاحة لاتصالات TCP هي:

• port من النوع <number>: وهو قيمة يجب إدخالها. وهو المنفذ الذي يجب على المقبس الاتصال به.
• host من النوع <string>: وهو المضيف الذي يجب على المقبس الاتصال به. القيمة الافتراضية: 'localhost'.
• localAddress من النوع <string>: وهو العنوان المحلي الذي يجب على المقبس الاتصال منه.
• localPort من النوع <number>: وهو المنفذ محلي الذي يجب على المقبس الاتصال منه.
• family من النوع<number>: نسخة من مُكدِّس IP، ويمكن أن تكون إما 4 أو 6. القيمة الافتراضية: 4.
• hints من النوع <number>: وهي تلميحات اختيارية حول dns.lookup()‎.
• lookup من النوع <Function> وهي دالة البحث المخصص. القيمة الافتراضية: dns.lookup()‎.

الخيارات المتاحة لاتصالات IPC هي:

• path من النوع <string>: وهي قيمة يجب إدخالها. وهو المسار الذي يجب على العميل الاتصال به. راجع تحديد مسارات اتصالات IPC. وإذا توفرت، تُتَجاهَل خيارات TCP الخاصة المذكورة أعلاه.

socket.connect(path[, connectListener])‎

path من النوع <string>: وهو المسار الذي يجب على العميل الاتصال به. راجع تحديد مسارات اتصالات IPC.

connectListener من النوع <Function>: وهو معامل شائع لتوابع socket.connect()‎. سيضاف كمستمع للحدث 'connect' مرة واحدة.

• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

بدء اتصال IPC على المقبس المعطى.

اسم مستعار يشير إلى socket.connect(options[, connectListener])‎ ويستدعى مع الخيار options بالقيمة { path: path }.

socket.connect(port[, host][, connectListener])‎

أُضيف مع الإصدار: v0.1.90.

• port من النوع <string>: وهو المنفذ الذي يجب على العميل الاتصال به.
• host من النوع <string>:  وهو المضيف الذي يجب على العميل الاتصال به.
• connectListener من النوع <Function> وهو معامل شائع لتوابع socket.connect()‎. سيضاف كمستمع للحدث 'connect' مرة واحدة.
• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

الشروع في اتصال TCP على المقبس المُعطى.

اسم مستعار يشير إلى socket.connect(options[, connectListener])‎ ويستدعى مع الخيار options بالقيمة {port: port, host: host}.

socket.connecting

أضيفت في: v6.1.0

إذا كان قيمتها true فهذا يعني استدعاء socket.connect(options[, connectListener])‎ وأنه لم ينته بعد. وتصبح قيمتها false قبل انبعاث الحدث 'connect' و/أو استدعاء دالة رد الاتصال socket.connect(options[, connectListener])‎.

socket.destroy([exception])‎

أُضيف مع الإصدار: v0.1.90.

• exception من النوع <Object>.
• القيمة المُعادة: من النوع <net.Socket>.

وهو يضمن عدم حدوث أي نشاط إدخال/إخراج على هذا المقبس. ويُعد ضروريا فقط في حالة الأخطاء (خطأ تحليل أو نحو ذلك).

إذا حُدِّد استثناءً exception، سيُطلق حدث 'error' وسيتلقى أي مستمع لهذا الحدث exception كوسيط.

socket.destroyed

من النوع <boolean>: ويشير إلى ما إذا كان الاتصال قد هُدِم أم لا. بمجرد هدم اتصال لا تُنقل أي بيانات باستخدامه.

socket.end([data][, encoding])‎

أُضيف مع الإصدار: v0.1.90.

• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

تغلق المُقبس نصفيًا. أي أنه يرسل حزمة FIN. ومن الممكن أن يستمر الخادم في إرسال بعض البيانات.

إذا كانت data مُحددة، فإن ذلك يكافئ استدعاء socket.write(data, encoding)‎ يتبعه socket.end()‎.

socket.localAddress

أضيفت مع الإصدار: v0.9.6.

وهو التمثيل النصي لعنوان IP المحلي الذي يتصل به العميل البعيد. على سبيل المثال، في خادم الاستماع إلى '0.0.0.0'، إذا اتصل عميل على '192.168.1.1'، ستتخذ socket.localAddress القيمة '192.168.1.1'.

socket.localPort

أضيفت مع الإصدار: v0.9.6.

التمثيل الرقمي للمنفذ المحلي. على سبيل المثال، 80 أو 21.

socket.pause()‎

• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

إيقاف مؤقت لقراءة البيانات. بمعنى عدم إطلاق الأحداث 'data'. وهو يفيد في خنق التحميل.

socket.ref()‎

أُضيف مع الإصدار: v0.9.1.

القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

على عكس unref()‎، استدعاء ref()‎ على خادم سبق إجراء unref عليه لن يسمح للبرنامج بالانتهاء إذا كان هو الخادم الوحيد المتبقي (السلوك الافتراضي). استدعاء ref()‎ مرة أخرى على مقبس سبق إجراء ref عليه لن يكون له أي تأثير.

socket.remoteAddress

أُضيف مع الإصدار: v0.5.10.

التمثيل النصي لعنوان IP البعيد. على سبيل المثال، '74.125.127.100' أو ‎'2001:4860:a005::68'‎. قد تكون القيمة غير معرفة undefined إذا هُدِم المقبس (على سبيل المثال، إذا قُطع اتصال العميل).

socket.remoteFamily

أُضيفت مع الإصدار: v0.11.14.

التمثيل النصي لعائلة IP البعيد. وتكون إما 'IPv4' أو 'IPv6'.

socket.remotePort

أُضيف مع الإصدار: v0.5.10.

التمثيل الرقمي للمنفذ البعيد. على سبيل المثال، 80 أو 21.

socket.resume()‎

• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

استئناف القراءة بعد استدعاء socket.pause()‎.

socket.setEncoding([encoding])‎

أُضيف مع الإصدار: v0.1.90.

• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

تعيين ترميز المقبس كدفق مقروء Readable Stream. راجع readable.setEncoding()‎ لمزيد من المعلومات.

socket.setKeepAlive([enable][, initialDelay])‎

أضيف مع الإصدار: v0.1.92.

• enable من النوع <boolean>. القيمة الافتراضية: false.
• initialDelay من النوع <number>. القيمة الافتراضية: 0.
• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

تمكين أو تعطيل وظيفة المحافظة على الحياة، وتعيين التأخير المبدئي قبل إرسال أول تحقق من المحافظة على الحياة (keepalive probe) على مقبس خامل.

ضبط initialDelay (بالمللي ثانية) لتعيين التأخير بين آخر حزمة بيانات واردة وأول تحقق من المحافظة على الحياة. وسيؤدي ضبط initialDelay بالقيمة 0 إلى ترك القيمة دون تغيير عن القيمة الافتراضية (أو القيمة السابقة).

socket.setNoDelay([noDelay])‎

أُضيف مع الإصدار: v0.1.90.

• noDelay من النوع <boolean>. القيمة الافتراضية: true.
• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

تعطيل خوارزمية Nagle التي تستخدمها اتصالات TCP بشكل افتراضي، فتخزن البيانات مؤقتًا قبل إرسالها. ضبط noDelay بالقيمة true يُطلق البيانات فور استدعاء socket.write()‎.

socket.setTimeout(timeout[, callback])‎

أُضيف مع الإصدار: v0.1.90.

• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

ضبط المقبس للانقضاء بعد مهلة timeout من الخمول على المقبس محسوبًا بالمللي ثانية. بشكل افتراضي لا تملك net.Socket مهلة للانقضاء.

عند إطلاق مهلة خمول، يتلقى المقبس حدث 'timeout' ولكن لن ينقطع الاتصال. يجب على المستخدم استدعاء socket.end()‎ أو socket.destroy()‎ يدوياً لإنهاء الاتصال.

socket.setTimeout(3000);
socket.on('timeout', () => {
  console.log('socket timeout');
  socket.end();
});

إذا كانت timeout تساوي 0، تتعطل مهلة الخمول الحالية.

يضاف المعامل callback الاختياري كمستمع لمرة واحدة لحدث 'timeout'.

socket.unref()‎

أُضيف مع الإصدار: v0.9.1.

• القيمة المُعادة: <net.Socket> وهو المقبس نفسه.

يسمح استدعاء unref()‎ على مقبسٍ ما للبرنامج بالإنهاء إذا كان هو المقبس النشط الوحيد في نظام الأحداث. استدعاء unref()‎ مرة أخرى على مقبس سبق إجراء unref عليه لن يكون له أي تأثير.

socket.write(data[, encoding][, callback])‎

أُضيف مع الإصدار: v0.1.90.

• data من النوع ‎<string> | <Buffer> | <Uint8Array>‎.
• encoding من النوع <string>: وتستخدم فقط عندما تكون data من النوع string. القيمة الافتراضية: utf8.
• callback من النوع <Function>.
• القيمة المُعادة: من النوع <boolean>.

إرسال البيانات على مقبس. ويحدد المعامل الثاني الترميز في حالة أن تكون البيانات سلسلة — ويكون الترميز UTF8 في الوضع الافتراضي.

ويعيد true إذا انتقلت البيانات بالكامل بنجاح إلى مخزن النواة المؤقت (kernel buffer). ويعيد false إذا كان كل أو جزء من البيانات في قائمة الانتظار في ذاكرة المستخدم. ويُطلق الحدث 'drain' عندما يكون المحزن المؤقت متاحًا مرة أخرى.

وسينفذ معامل رد الاتصال callback الاختياري عند الانتهاء من كتابة البيانات خارجًا--وقد لا حدث هذا فورًا.

راجع التابع write()‎ وهو تابع التيار القابل للكتابة Writable Stream‎ للحصول على مزيد من المعلومات.

net.connect()‎

الأسماء المستعارة للتابع net.createConnection()‎.

الأشكال الممكنة:

• net.connect(options[, connectListener])‎
• net.connect(path[, connectListener])‎ لاتصالات IPC.
• net.connect(port[, host][, connectListener])‎ لاتصالات TCP.

net.connect(options[, connectListener])‎

أُضيف مع الإصدار: v0.7.0.

الاسم المستعار للتابع net.createConnection(options[, connectListener])‎.

net.connect(path[, connectListener])‎

أُضيف مع الإصدار: v0.1.90.

الاسم المستعار للتابع net.createConnection(path[, connectListener])‎.

net.connect(port[, host][, connectListener])‎

أُضيف مع الإصدار: v0.1.90.

الاسم المستعار للتابع net.createConnection(port[, host][, connectListener])‎.

net.createConnection()‎

وهي دالة تصنيع، تنشئ net.Socket جديدة، وهي تهيئ اتصال مع socket.connect()‎، ثم تعيد net.Socket الذي يبدأ الاتصال.

عند تأسيس الاتصال، سيُطلق الحدث 'connect' على المقبس المُعاد. وسيضاف المعامل الأخير connectListener، إذا توفَّر، كمستمع للحدث 'connect' مرة واحدة.

الأشكال الممكنة:

• net.createConnection(options[, connectListener])‎
• net.createConnection(path[, connectListener])‎ لاتصالات IPC.
• net.createConnection(port[, host][, connectListener])‎ لاتصالات TCP.

الدالة net.connect()‎ هي اسم مستعار لهذه الدالة.

net.createConnection(options[, connectListener])‎

أُضيف مع الإصدار: v0.1.90.

• options من النوع <Object>: ويجب إدخالها. ستمرر إلى كل من استدعاء new net.Socket([options])‎ والتابع socket.connect(options[, connectListener])‎.
• connectListener من النوع <Function>: وهو معامل شائع للدالة net.createConnection()‎. إذا توفَّرت، ستضاف كمستمع للحدث 'connect' على المقبس المُعاد مرة واحدة.
• القيمة المُعادة: <net.Socket> وهو المقبس المُنشأ حديثا والمستخدم لبدء الاتصال.

للخيارات المتاحة، انظر new net.Socket([options])‎ و socket.connect(options[, connectListener]).

خيارات إضافية:

• timeout من النوع <number>: إذا ضُبِط، سيستخدم لاستدعاء socket.setTimeout(timeout)‎ بعد إنشاء مقبس، ولكن قبل أن يبدأ الاتصال.

فيما يلي مثال لعميل خادم صدى (echo server) الموصوف في قسم ()‎‎net.createServer:

const net = require('net');
const client = net.createConnection({ port: 8124 }, () => {
  // 'connect' مستمع
  console.log('التوصيل مع الخادم!');
  client.write('أيها العالم!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('قطع الإتصال مع الخادم');
});

للاتصال على المقبس ‎/tmp/echo.sock يجب تغيير السطر الثاني فقط إلى:

const client = net.createConnection({ path: '/tmp/echo.sock' });

net.createConnection(path[, connectListener])‎

أُضيف مع الإصدار: v0.1.90.

• path من النوع <string>: وهو المسار الذي يجب على المقبس الاتصال به. سيُمرر إلى socket.connect(path[, connectListener])‎. راجع تحديد مسارات اتصالات IPC.
• connectListener من النوع <Function>: وهو معامل شائع لدوال net.createConnection()‎ وهو مستمع "لمرة واحدة" للحدث 'connect' المقبس البادئ. سيُمرر إلى socket.connect(path[, connectListener])‎.
• القيمة المُعادة: <net.Socket> وهو المقبس المُنشأ حديثا والمستخدم لبدء الاتصال.

يبدأ إجراء اتصال IPC.

تُنشئ هذه الدالة net.Socket مع جميع الخيارات مضبوطة بالقيم الافتراضية، وتبدأ الاتصال مع socket.connect(path[, connectListener])‎ على الفور، ثم تعيد net.Socket والذي يبدأ الاتصال.

net.createConnection(port[, host][, connectListener])‎

أُضيف مع الإصدار: v0.1.90.

• port من النوع <number>: وهو المنفذ الذي يجب على المقبس الاتصال به. سيُمرر إلى socket.connect(port[, host][, connectListener])‎.
• host من النوع <string>: وهو المضيف الذي الذي يجب على المقبس الاتصال به. سيُمرر إلى socket.connect(port[, host][, connectListener])‎. القيمة الافتراضية: 'localhost'.
• connectListener من النوع <Function>: وهو معامل شائع لدوال net.createConnection()‎ وهو مستمع "لمرة واحدة" للحدث 'connect' المقبس البادئ. سيُمرر إلى socket.connect(path[, connectListener])‎.
• القيمة المُعادة: <net.Socket> وهو المقبس المُنشأ حديثا والمستخدم لبدء الاتصال.

يبدأ اتصال TCP.

تُنشئ هذه الدالة net.Socket مع جميع الخيارات مضبوطة بالقيم الافتراضية، وتبدأ الاتصال مع socket.connect(port[, host][, connectListener])‎ على الفور، ثم تعيد net.Socket والذي يبدأ الاتصال.

net.createServer([options][, connectionListener])‎

أُضيف مع الإصدار: v0.5.0.

إنشاء خادم TCP أو IPC جديد.

• options من النوع  <Object>.
• allowHalfOpen من النوع <boolean>: وهو يشير إلى ما إذا كان مسموح باتصالات TCP مفتوحة نصفيا. القيمة الافتراضية: false.
• pauseOnConnect من النوع <boolean>: وهو يحدد ما إذا كان يجب إيقاف المقبس مؤقتا عن الاتصالات الواردة .القيمة الافتراضية: false.
• connectionListener من النوع <Function>: وهو يضبط مستمع للحدث 'connection' تلقائيا.
• القيمة المُعادة: من النوع <net.Server>.

إذا ضُبط allowHalfOpen بالقيمة true عندما يرسل الطرف الآخر من المقبس حزمة FIN، يرسل الخادم حزمة FIN فقط عند استدعاء socket.end()‎ صراحة وحتى هذا الحين يكون الاتصال مغلقًا نصفيًا (غير مقروء ولكن لا يزال قابل للكتابة). انظر الحدث 'end' و RFC 1122 (القسم 4.2.2.13) لمزيد من المعلومات.

إذا ضُبط pauseOnConnect بالقيمة true، سيتوقف المقبس المرتبط مع كل اتصال وارد مؤقتا، ولن تُقرأ أي بيانات من معالجها. ويسمح هذا للاتصالات بالمرور بين العمليات دون قراءة أي بيانات من قِبَل العملية الأصلية. للبدء في قراءة البيانات من مقبس متوقف مؤقتاً، يجب استدعاء socket.resume()‎.

يمكن أن يكون الخادم TCP أو IPC اعتماداً على ما يستمع إليه بواسطة listen()‎.

إليك مثال على صدى خادم TCP والذي يستمع للاتصالات على المنفذ 8124:

const net = require('net');
const server = net.createServer((c) => {
  // 'connection' مستمع
  console.log('إتصال العميل');
  c.on('end', () => {
    console.log('قطع إتصال العميل');
  });
  c.write('مرحبًا\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('الخادم مرتبط');
});

اختبر هذا باستخدام telnet:

$ telnet localhost 8124

للاستماع على المقبس ‎/tmp/echo.sock يجب تغيير السطر الثالث من النهاية فقط إلى:

server.listen('/tmp/echo.sock', () => {
  console.log('الخادم مرتبط');
});

ويستخدم nc للاتصال بخادم مقبس مجال UNIX:

$ nc -U /tmp/echo.sock

net.isIP(input)‎

أُضيف مع الإصدار: v0.3.0.

• القيمة المُعادة: من النوع <integer>.

تُعيد الاختبارات إذا كان المُدخَل عنوان IP القيمة 0 للسلاسل النصية غير الصالحة، و 4 لعناوين IP من الإصدار 4 و 6 لعناوين IP من الإصدار 6.

net.isIPv4(input)‎

أُضيف مع الإصدار: v0.3.0.

• القيمة المُعادة: من النوع <boolean>

تُعيد true في حالة إدخال عنوان IP من الإصدار 4، وإلا سيُعيد false.

net.isIPv6(input)‎

أُضيف مع الإصدار: v0.3.0.

• القيمة المُعادة: من النوع <boolean>.

تُعيد true في حالة إدخال عنوان IP من الإصدار 6، وإلا سيُعيد false.

مصادر

• صفحة الوحدة Net في توثيق Node.js الرسمي.