شبكة

[مستقر: 2 - مستقر]

مستقر: 2 الاستقرار: 2 - مستقر

شفرة المصدر: lib/net.js

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

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

ESM

import net from 'node:net';

CJS

const net = require('node:net');

دعم IPC

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

الإصدار	التغييرات
v20.8.0	دعم الربط بمسار مقبس نطاق Unix مجرد مثل \0abstract. يمكننا ربط '\0' لـ Node.js \< v20.4.0.

تدعم الوحدة node:net اتصالات IPC باستخدام الأنابيب المسماة على نظام التشغيل Windows، ومقابس نطاق Unix على أنظمة التشغيل الأخرى.

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

تأخذ الدوال net.connect()، net.createConnection()، server.listen()، و socket.connect() معامِلاً path لتحديد نقاط نهاية IPC.

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

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

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

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

الفئة: net.BlockList

تمت إضافتها في: الإصدار v15.0.0, v14.18.0

يمكن استخدام كائن BlockList مع بعض واجهات برمجة تطبيقات الشبكة لتحديد قواعد لتعطيل الوصول الوارد أو الصادر إلى عناوين IP محددة أو نطاقات IP أو شبكات IP الفرعية.

blockList.addAddress(address[, type])

تمت إضافتها في: الإصدار v15.0.0, v14.18.0

• address <string> | <net.SocketAddress> عنوان IPv4 أو IPv6.
• type <string> إما 'ipv4' أو 'ipv6'. افتراضي: 'ipv4'.

يضيف قاعدة لحظر عنوان IP المحدد.

blockList.addRange(start, end[, type])

تمت إضافتها في: الإصدار v15.0.0, v14.18.0

• start <string> | <net.SocketAddress> عنوان IPv4 أو IPv6 البدائي في النطاق.
• end <string> | <net.SocketAddress> عنوان IPv4 أو IPv6 النهائي في النطاق.
• type <string> إما 'ipv4' أو 'ipv6'. افتراضي: 'ipv4'.

يضيف قاعدة لحظر نطاق من عناوين IP من start (شامل) إلى end (شامل).

blockList.addSubnet(net, prefix[, type])

تمت إضافتها في: الإصدار v15.0.0, v14.18.0

• net <string> | <net.SocketAddress> عنوان شبكة IPv4 أو IPv6.
• prefix <number> عدد بتات بادئة CIDR. بالنسبة لـ IPv4، يجب أن تكون قيمة بين 0 و 32. بالنسبة لـ IPv6، يجب أن تكون بين 0 و 128.
• type <string> إما 'ipv4' أو 'ipv6'. افتراضي: 'ipv4'.

يضيف قاعدة لحظر نطاق من عناوين IP محددة كقناع شبكة فرعية.

blockList.check(address[, type])

تمت الإضافة في: v15.0.0, v14.18.0

• address <string> | <net.SocketAddress> عنوان IP المراد فحصه
• type <string> إما 'ipv4' أو 'ipv6'. افتراضي: 'ipv4'.
• الإرجاع: <boolean>

ترجع true إذا كان عنوان IP المحدد يطابق أيًا من القواعد المضافة إلى BlockList.

const blockList = new net.BlockList();
blockList.addAddress('123.123.123.123');
blockList.addRange('10.0.0.1', '10.0.0.10');
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6');

console.log(blockList.check('123.123.123.123'));  // يطبع: true
console.log(blockList.check('10.0.0.3'));  // يطبع: true
console.log(blockList.check('222.111.111.222'));  // يطبع: false

// تعمل تدوين IPv6 لعناوين IPv4:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // يطبع: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // يطبع: true

blockList.rules

تمت الإضافة في: v15.0.0, v14.18.0

• النوع: <string[]>

قائمة القواعد المضافة إلى القائمة المحظورة.

BlockList.isBlockList(value)

تمت الإضافة في: v23.4.0

• value <any> أي قيمة JS
• ترجع true إذا كانت value عبارة عن net.BlockList.

الفئة: net.SocketAddress

تمت الإضافة في: v15.14.0, v14.18.0

new net.SocketAddress([options])

تمت الإضافة في: v15.14.0, v14.18.0

• options <Object>
  • address <string> عنوان الشبكة كسلسلة IPv4 أو IPv6. افتراضي: '127.0.0.1' إذا كانت family هي 'ipv4'; '::' إذا كانت family هي 'ipv6'.
  • family <string> واحدة من 'ipv4' أو 'ipv6'. افتراضي: 'ipv4'.
  • flowlabel <number> تسمية تدفق IPv6 تستخدم فقط إذا كانت family هي 'ipv6'.
  • port <number> منفذ IP.

socketaddress.address

تمت الإضافة في: v15.14.0, v14.18.0

• النوع <string>

socketaddress.family

تمت الإضافة في: v15.14.0, v14.18.0

• النوع <string> إما 'ipv4' أو 'ipv6'.

socketaddress.flowlabel

تمت الإضافة في: v15.14.0, v14.18.0

• النوع <number>

socketaddress.port

تمت الإضافة في: v15.14.0, v14.18.0

• النوع <number>

SocketAddress.parse(input)

تمت الإضافة في: v23.4.0

• input <string> سلسلة إدخال تحتوي على عنوان IP ومنفذ اختياري، على سبيل المثال 123.1.2.3:1234 أو [1::1]:1234.
• Returns: <net.SocketAddress> تُرجع SocketAddress إذا نجح التحليل. وإلا فستُرجع undefined.

الصنف: net.Server

تمت الإضافة في: v0.1.90

• يمتد من: <EventEmitter>

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

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

• options <Object> انظر net.createServer([options][, connectionListener]).
• connectionListener <Function> يتم تعيينه تلقائيًا كمستمع لحدث 'connection'.
• Returns: <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().

الحدث: 'drop'

تمت الإضافة في: الإصدار v18.6.0، v16.17.0

عندما يصل عدد الاتصالات إلى حد server.maxConnections، سيقوم الخادم بإسقاط الاتصالات الجديدة وإصدار الحدث 'drop' بدلاً من ذلك. إذا كان خادم TCP، فإن الوسيطة هي كما يلي، وإلا فإن الوسيطة هي undefined.

• data <Object> الوسيطة التي تم تمريرها إلى مستمع الحدث.
  • localAddress <string> العنوان المحلي.
  • localPort <number> المنفذ المحلي.
  • localFamily <string> العائلة المحلية.
  • remoteAddress <string> العنوان البعيد.
  • remotePort <number> المنفذ البعيد.
  • remoteFamily <string> عائلة IP البعيدة. 'IPv4' أو 'IPv6'.

server.address()

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

الإصدار	التغييرات
v18.4.0	تعيد الخاصية family الآن سلسلة بدلاً من رقم.
v18.0.0	تعيد الخاصية family الآن رقمًا بدلاً من سلسلة.
v0.1.90	تمت الإضافة في: v0.1.90

• إرجاع: <Object> | <string> | <null>

يُرجع 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) => {
  // Handle errors here.
  throw err;
});

// Grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
});

يُرجع server.address() قيمة null قبل إصدار الحدث 'listening' أو بعد استدعاء server.close().

server.close([callback])

تمت الإضافة في: v0.1.90

• callback <Function> يتم استدعاؤه عند إغلاق الخادم.
• إرجاع: <net.Server>

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

server[Symbol.asyncDispose]()

أضيف في: الإصدار 20.5.0، الإصدار 18.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 الاستقرار: 1 - تجريبي

يستدعي server.close() ويعيد وعدًا يتحقق عند إغلاق الخادم.

server.getConnections(callback)

أضيف في: الإصدار 0.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. يحدث هذا عندما يستمع خادم آخر بالفعل على المنفذ/المسار/المقبض المطلوب. إحدى طرق التعامل مع هذا هي إعادة المحاولة بعد فترة زمنية معينة:

server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('العنوان قيد الاستخدام، تتم إعادة المحاولة...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

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

أُضيف في: v0.5.10

• handle <Object>
• backlog <number> وسيطة شائعة لوظائف server.listen().
• callback <Function>
• الإرجاع: <net.Server>

يبدأ الخادم في الاستماع للاتصالات على handle معينة تم ربطها بالفعل بمنفذ أو مقبس نطاق Unix أو قناة مسماة في Windows.

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

الاستماع على واصف ملف غير مدعوم على Windows.

server.listen(options[, callback])

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

الإصدار	التغييرات
v23.1.0	خيار reusePort مدعوم.
v15.6.0	تمت إضافة دعم AbortSignal.
v11.4.0	خيار ipv6Only مدعوم.
v0.11.14	أُضيف في: v0.11.14

• options <Object> مطلوب. يدعم الخصائص التالية:

  • backlog <number> وسيطة شائعة لوظائف server.listen().
  • exclusive <boolean> الافتراضي: false
  • host <string>
  • ipv6Only <boolean> لخوادم TCP، سيؤدي تعيين ipv6Only إلى true إلى تعطيل دعم المكدس المزدوج، أي أن الربط بالمضيف :: لن يجعل 0.0.0.0 مرتبطًا. الافتراضي: false.
  • reusePort <boolean> بالنسبة لخوادم TCP، يسمح تعيين reusePort إلى true لعدة مآخذ توصيل على نفس المضيف بالربط بنفس المنفذ. يتم توزيع الاتصالات الواردة بواسطة نظام التشغيل على مآخذ التوصيل المستمعة. هذا الخيار متاح فقط على بعض الأنظمة الأساسية، مثل Linux 3.9+ و DragonFlyBSD 3.6+ و FreeBSD 12.0+ و Solaris 11.4 و AIX 7.2.5+. الافتراضي: false.
  • path <string> سيتم تجاهله إذا تم تحديد port. راجع تحديد المسارات لاتصالات IPC.
  • port <number>
  • readableAll <boolean> بالنسبة لخوادم IPC، تجعل الأنبوب قابلاً للقراءة لجميع المستخدمين. الافتراضي: false.
  • signal <AbortSignal> إشارة إلغاء يمكن استخدامها لإغلاق خادم يستمع.
  • writableAll <boolean> بالنسبة لخوادم IPC، تجعل الأنبوب قابلاً للكتابة لجميع المستخدمين. الافتراضي: false.

• callback <Function> functions.

• الإرجاع: <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,
});

عندما تكون exclusive هي true ويتم مشاركة المعالج الأساسي، فمن المحتمل أن يستعلم العديد من العمال عن معالج بمسافات متراكمة مختلفة. في هذه الحالة، سيتم استخدام backlog الأول الذي تم تمريره إلى العملية الرئيسية.

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

إذا تم تمكين الخيار signal، فإن استدعاء .abort() على AbortController المقابل يشبه استدعاء .close() على الخادم:

const controller = new AbortController();
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
});
// Later, when you want to close the server.
controller.abort();

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

تمت إضافتها في: v0.1.90

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

ابدأ خادم IPC يستمع للاتصالات على path المحدد.

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

تمت إضافتها في: v0.1.90

• port <number>
• host <string>
• backlog <number>: معامل شائع لوظائف server.listen().
• callback <Function>.
• الإرجاع: <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

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

الإصدار	التغييرات
v21.0.0	يؤدي تعيين maxConnections إلى 0 إلى إسقاط جميع الاتصالات الواردة. في السابق، كان يتم تفسيره على أنه Infinity.
v0.2.0	تمت الإضافة في: v0.2.0

• <integer>

عندما يصل عدد الاتصالات إلى حد server.maxConnections:

لا يُنصح باستخدام هذا الخيار بمجرد إرسال مقبس إلى عملية فرعية باستخدام child_process.fork().

server.dropMaxConnection

تمت الإضافة في: v23.1.0

• <boolean>

قم بتعيين هذه الخاصية إلى true لبدء إغلاق الاتصالات بمجرد وصول عدد الاتصالات إلى حد [server.maxConnections][]. هذا الإعداد فعال فقط في وضع المجموعة.

server.ref()

تمت الإضافة في: v0.9.1

• Returns: <net.Server>

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

server.unref()

تمت الإضافة في: v0.9.1

• Returns: <net.Server>

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

Class: net.Socket

تمت الإضافة في: v0.3.4

• Extends: <stream.Duplex>

هذه الفئة هي تجريد لمقبس TCP أو نقطة نهاية IPC دفقية (تستخدم أنابيب مسماة على Windows ومقابس نطاق Unix بخلاف ذلك). وهي أيضًا EventEmitter.

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

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

new net.Socket([options])

[التاريخ]

الإصدار	التغييرات
v15.14.0	تمت إضافة دعم AbortSignal.
v12.10.0	تمت إضافة خيار onread.
v0.3.4	تمت الإضافة في: v0.3.4

• options <Object> الخيارات المتاحة هي:

  • allowHalfOpen <boolean> إذا تم تعيينها على false، فستقوم المقبس تلقائيًا بإنهاء الجانب القابل للكتابة عندما ينتهي الجانب القابل للقراءة. انظر net.createServer() وحدث 'end' للحصول على التفاصيل. الافتراضي: false.

  • fd <number> إذا تم تحديده، فقم بالتفاف حول مقبس موجود باستخدام واصف الملف المحدد، وإلا فسيتم إنشاء مقبس جديد.

  • onread <Object> إذا تم تحديده، فسيتم تخزين البيانات الواردة في buffer واحد ويتم تمريرها إلى callback المقدمة عند وصول البيانات إلى المقبس. سيؤدي هذا إلى عدم توفير وظيفة التدفق لأي بيانات. سيصدر المقبس أحداثًا مثل 'error' و 'end' و 'close' كالمعتاد. ستتصرف طرق مثل pause() و resume() كما هو متوقع أيضًا.

  • buffer <Buffer> | <Uint8Array> | <Function> إما جزء قابل لإعادة الاستخدام من الذاكرة لاستخدامه لتخزين البيانات الواردة أو دالة تُرجع مثل هذا الجزء.

  • callback <Function> يتم استدعاء هذه الدالة لكل جزء من البيانات الواردة. يتم تمرير وسيطتين إليها: عدد البايتات المكتوبة في buffer ومرجع إلى buffer. أرجع false من هذه الدالة لـ pause() المقبس ضمنيًا. سيتم تنفيذ هذه الدالة في السياق العام.

  • readable <boolean> السماح بالقراءات على المقبس عند تمرير fd، وإلا يتم تجاهله. الافتراضي: false.

  • signal <AbortSignal> إشارة إجهاض يمكن استخدامها لتدمير المقبس.

  • writable <boolean> السماح بالكتابات على المقبس عند تمرير fd، وإلا يتم تجاهله. الافتراضي: false.

• Returns: <net.Socket>

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

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

الحدث: 'close'

أُضيف في: v0.1.90

• hadError <boolean> ‏true إذا كان المقبس يحتوي على خطأ في الإرسال.

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

الحدث: 'connect'

أُضيف في: v0.1.90

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

الحدث: 'connectionAttempt'

أُضيف في: v21.6.0، v20.12.0

• ip <string> عنوان IP الذي يحاول المقبس الاتصال به.
• port <number> المنفذ الذي يحاول المقبس الاتصال به.
• family <number> عائلة IP. يمكن أن تكون 6 لـ IPv6 أو 4 لـ IPv4.

يُطلق عند بدء محاولة اتصال جديدة. قد يُطلق هذا الحدث عدة مرات إذا تم تمكين خوارزمية الاختيار التلقائي للعائلة في socket.connect(options).

الحدث: 'connectionAttemptFailed'

أُضيف في: v21.6.0، v20.12.0

• ip <string> عنوان IP الذي حاول المقبس الاتصال به.
• port <number> المنفذ الذي حاول المقبس الاتصال به.
• family <number> عائلة IP. يمكن أن تكون 6 لـ IPv6 أو 4 لـ IPv4.
• error <Error> الخطأ المرتبط بالفشل.

يُطلق عند فشل محاولة اتصال. قد يُطلق هذا الحدث عدة مرات إذا تم تمكين خوارزمية الاختيار التلقائي للعائلة في socket.connect(options).

الحدث: 'connectionAttemptTimeout'

أضيف في: v21.6.0, v20.12.0

• ip <string> عنوان IP الذي حاولت المقبس الاتصال به.
• port <number> المنفذ الذي حاولت المقبس الاتصال به.
• family <number> عائلة IP. يمكن أن تكون 6 لـ IPv6 أو 4 لـ IPv4.

يصدر هذا الحدث عندما تنتهي مهلة محاولة الاتصال. يتم إصداره فقط (وقد يتم إصداره عدة مرات) إذا تم تمكين خوارزمية الاختيار التلقائي للعائلة في socket.connect(options).

الحدث: 'data'

أضيف في: v0.1.90

• <Buffer> | <string>

يصدر هذا الحدث عند استلام البيانات. ستكون الوسيطة data إما Buffer أو String. يتم تعيين ترميز البيانات بواسطة socket.setEncoding().

سيتم فقد البيانات إذا لم يكن هناك مستمع عندما يصدر Socket الحدث 'data'.

الحدث: 'drain'

أضيف في: v0.1.90

يصدر هذا الحدث عندما تصبح مخزن الكتابة المؤقتة فارغًا. يمكن استخدامه لتنظيم عمليات التحميل.

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

الحدث: 'end'

أضيف في: v0.1.90

يصدر هذا الحدث عندما يشير الطرف الآخر من المقبس إلى نهاية الإرسال، وبالتالي إنهاء الجانب القابل للقراءة من المقبس.

افتراضيًا (allowHalfOpen هو false) سيرسل المقبس حزمة نهاية الإرسال مرة أخرى ويتلف واصف الملف الخاص به بمجرد كتابة قائمة انتظار الكتابة المعلقة الخاصة به. ومع ذلك، إذا تم تعيين 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 <number> | <null> نوع العنوان. راجع dns.lookup().
• host <string> اسم المضيف.

الحدث: 'ready'

تمت إضافته في: v9.11.0

يتم إطلاقه عندما يكون المقبس جاهزًا للاستخدام.

يتم تشغيله مباشرة بعد 'connect'.

الحدث: 'timeout'

تمت إضافته في: v0.1.90

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

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

socket.address()

[السجل]

الإصدار	التغييرات
v18.4.0	تُرجع الخاصية family الآن سلسلة بدلاً من رقم.
v18.0.0	تُرجع الخاصية family الآن رقمًا بدلاً من سلسلة.
v0.1.90	تمت إضافته في: v0.1.90

• الإرجاع: <Object>

إرجاع address المرتبط واسم family العنوان و port للمقبس كما هو مُبلغ عنه بواسطة نظام التشغيل: { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.autoSelectFamilyAttemptedAddresses

تمت إضافته في: v19.4.0، v18.18.0

• <string[]>

تكون هذه الخاصية موجودة فقط إذا تم تمكين خوارزمية الاختيار التلقائي للعائلة في socket.connect(options) وهي عبارة عن مصفوفة من العناوين التي تمت محاولتها.

كل عنوان هو سلسلة نصية في شكل $IP:$PORT. إذا كان الاتصال ناجحًا، فإن العنوان الأخير هو العنوان الذي يتصل به المقبس حاليًا.

socket.bufferSize

تمت إضافته في: v0.3.8

تم الإيقاف منذ: v14.6.0

[مستقر: 0 - مهمل]

مستقر: 0 الاستقرار: 0 - مهمل: استخدم writable.writableLength بدلاً من ذلك.

• <integer>

تعرض هذه الخاصية عدد الأحرف المخزنة مؤقتًا للكتابة. قد تحتوي المخزن المؤقت على سلاسل نصية لا يُعرف طولها بعد الترميز. لذلك هذا الرقم هو مجرد تقدير لعدد البايتات في المخزن المؤقت.

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

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

socket.bytesRead

تمت إضافته في: v0.5.3

• <integer>

كمية البايتات المستلمة.

socket.bytesWritten

أُضيف في: v0.5.3

• <integer>

مقدار البايتات المرسلة.

socket.connect()

يبدأ اتصالًا على مقبس معين.

التوقيعات الممكنة:

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

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

يجب استخدام هذه الدالة فقط لإعادة توصيل مقبس بعد إطلاق 'close' أو قد يؤدي ذلك إلى سلوك غير محدد.

socket.connect(options[, connectListener])

[السجل]

الإصدار	التغييرات
v19.4.0	يمكن تغيير القيمة الافتراضية لخيار autoSelectFamily في وقت التشغيل باستخدام setDefaultAutoSelectFamily أو عبر خيار سطر الأوامر --enable-network-family-autoselection.
v20.0.0, v18.18.0	القيمة الافتراضية لخيار autoSelectFamily هي الآن true. تمت إعادة تسمية علامة CLI --enable-network-family-autoselection إلى --network-family-autoselection. الاسم القديم هو الآن اسم مستعار ولكن لا يُشجع عليه.
v19.3.0, v18.13.0	تمت إضافة خيار autoSelectFamily.
v17.7.0, v16.15.0	خيارات noDelay و keepAlive و keepAliveInitialDelay مدعومة الآن.
v6.0.0	خيار hints افتراضيًا هو 0 في جميع الحالات الآن. سابقًا، في غياب خيار family، كان سيصبح افتراضيًا `dns.ADDRCONFIG
v5.11.0	خيار hints مدعوم الآن.
v0.1.90	أُضيف في: v0.1.90

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

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

بالنسبة لاتصالات TCP، الخيارات المتاحة هي:

• autoSelectFamily <boolean>: إذا تم تعيينه على true، فإنه يمكّن خوارزمية الكشف التلقائي عن العائلة التي تنفذ بشكل فضفاض القسم 5 من RFC 8305. يتم تعيين خيار all الذي تم تمريره إلى البحث على true وتحاول المقابس الاتصال بجميع عناوين IPv6 و IPv4 التي تم الحصول عليها، بالتسلسل، حتى يتم إنشاء اتصال. تتم تجربة عنوان AAAA الأول الذي تم إرجاعه أولاً، ثم عنوان A الأول الذي تم إرجاعه، ثم عنوان AAAA الثاني الذي تم إرجاعه وهكذا. يتم إعطاء كل محاولة اتصال (ولكن المحاولة الأخيرة) مقدار الوقت المحدد بواسطة خيار autoSelectFamilyAttemptTimeout قبل انتهاء المهلة وتجربة العنوان التالي. يتم تجاهله إذا لم يكن خيار family هو 0 أو إذا تم تعيين localAddress. لا يتم إطلاق أخطاء الاتصال إذا نجح اتصال واحد على الأقل. إذا فشلت جميع محاولات الاتصال، فسيتم إطلاق AggregateError واحد مع جميع المحاولات الفاشلة. افتراضي: net.getDefaultAutoSelectFamily().
• autoSelectFamilyAttemptTimeout <number>: مقدار الوقت بالمللي ثانية للانتظار حتى تنتهي محاولة الاتصال قبل تجربة العنوان التالي عند استخدام خيار autoSelectFamily. إذا تم تعيينه على عدد صحيح موجب أقل من 10، فسيتم استخدام القيمة 10 بدلاً من ذلك. افتراضي: net.getDefaultAutoSelectFamilyAttemptTimeout().
• family <number>: إصدار حزمة بروتوكولات الإنترنت. يجب أن يكون 4 أو 6 أو 0. تشير القيمة 0 إلى أنه يُسمح بكل من عناوين IPv4 و IPv6. افتراضي: 0.
• hints <number> اختياري dns.lookup() تلميحات.
• host <string> المضيف الذي يجب أن يتصل به المقبس. افتراضي: 'localhost'.
• keepAlive <boolean> إذا تم تعيينه على true، فإنه يمكّن وظيفة keep-alive على المقبس مباشرة بعد إنشاء الاتصال، وبالمثل ما يتم القيام به في socket.setKeepAlive(). افتراضي: false.
• keepAliveInitialDelay <number> إذا تم تعيينه على رقم موجب، فإنه يحدد التأخير الأولي قبل إرسال أول مسبار keepalive على مقبس خامل. افتراضي: 0.
• localAddress <string> العنوان المحلي الذي يجب أن يتصل منه المقبس.
• localPort <number> المنفذ المحلي الذي يجب أن يتصل منه المقبس.
• lookup <Function> دالة بحث مخصصة. افتراضي: dns.lookup().
• noDelay <boolean> إذا تم تعيينه على true، فإنه يعطل استخدام خوارزمية Nagle مباشرة بعد إنشاء المقبس. افتراضي: false.
• port <number> مطلوب. المنفذ الذي يجب أن يتصل به المقبس.
• blockList <net.BlockList> يمكن استخدام blockList لتعطيل الوصول الصادر إلى عناوين IP معينة أو نطاقات IP أو شبكات IP الفرعية.

بالنسبة لاتصالات IPC، الخيارات المتاحة هي:

• path <string> مطلوب. المسار الذي يجب أن يتصل به العميل. انظر تحديد المسارات لاتصالات IPC. إذا تم توفيره، فسيتم تجاهل خيارات TCP المحددة أعلاه.

socket.connect(path[, connectListener])

• path <string> المسار الذي يجب أن يتصل به العميل. انظر تحديد المسارات لاتصالات IPC.
• connectListener <Function> معلمة شائعة لطرق socket.connect(). ستتم إضافتها كمستمع لحدث 'connect' مرة واحدة.
• الإرجاع: <net.Socket> المقبس نفسه.

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

اسم مستعار لـ socket.connect(options[, connectListener]) تم استدعاؤه مع { path: path } كـ options.

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

تمت الإضافة في: v0.1.90

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

بدء اتصال TCP على المقبس المحدد.

اسم مستعار لـ socket.connect(options[, connectListener]) تم استدعاؤه مع {port: port, host: host} كـ options.

socket.connecting

تمت الإضافة في: v6.1.0

• <boolean>

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

socket.destroy([error])

تمت الإضافة في: v0.1.90

• error <Object>
• الإرجاع: <net.Socket>

يضمن عدم حدوث المزيد من نشاط الإدخال/الإخراج على هذا المقبس. يدمر الدفق ويغلق الاتصال.

انظر writable.destroy() لمزيد من التفاصيل.

socket.destroyed

• <boolean> يشير إلى ما إذا كان الاتصال مدمرًا أم لا. بمجرد تدمير الاتصال، لا يمكن نقل أي بيانات أخرى باستخدامه.

انظر writable.destroyed لمزيد من التفاصيل.

socket.destroySoon()

تمت الإضافة في: v0.3.4

يدمر المقبس بعد كتابة جميع البيانات. إذا تم بالفعل إصدار الحدث 'finish'، فسيتم تدمير المقبس على الفور. إذا كان المقبس لا يزال قابلاً للكتابة، فإنه يستدعي ضمنيًا socket.end().

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

تمت الإضافة في: v0.1.90

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> يُستخدم فقط عندما تكون البيانات string. الافتراضي: 'utf8'.
• callback <Function> رد اتصال اختياري عند انتهاء المقبس.
• الإرجاع: <net.Socket> المقبس نفسه.

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

انظر writable.end() لمزيد من التفاصيل.

socket.localAddress

تمت الإضافة في: v0.9.6

• <string>

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

socket.localPort

أضيف في: الإصدار 0.9.6

• <integer>

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

socket.localFamily

أضيف في: الإصدار 18.8.0، 16.18.0

• <string>

التمثيل النصي لعائلة IP المحلية. 'IPv4' أو 'IPv6'.

socket.pause()

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

يقوم بإيقاف قراءة البيانات مؤقتًا. أي أن أحداث 'data' لن تُصدر. مفيد لتقليل سرعة التحميل.

socket.pending

أضيف في: الإصدار 11.2.0، 10.16.0

• <boolean>

هذا true إذا لم يكن المقبس متصلاً بعد، إما لأن .connect() لم يتم استدعاؤه بعد أو لأنه لا يزال في طور الاتصال (انظر socket.connecting).

socket.ref()

أضيف في: الإصدار 0.9.1

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

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

socket.remoteAddress

أضيف في: الإصدار 0.5.10

• <string>

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

socket.remoteFamily

أضيف في: الإصدار 0.11.14

• <string>

التمثيل النصي لعائلة IP البعيدة. 'IPv4' أو 'IPv6'. قد تكون القيمة undefined إذا تم تدمير المقبس (على سبيل المثال، إذا قام العميل بقطع الاتصال).

socket.remotePort

تمت الإضافة في: الإصدار v0.5.10

• <عدد صحيح>

التمثيل الرقمي للمنفذ البعيد. على سبيل المثال، 80 أو 21. قد تكون القيمة undefined إذا تم تدمير المقبس (على سبيل المثال، إذا تم فصل العميل).

socket.resetAndDestroy()

تمت الإضافة في: الإصدار v18.3.0, v16.17.0

• الإرجاع: <net.Socket>

إغلاق اتصال TCP عن طريق إرسال حزمة RST وتدمير التدفق. إذا كان مقبس TCP هذا في حالة اتصال، فسوف يرسل حزمة RST ويدمر مقبس TCP هذا بمجرد توصيله. خلاف ذلك، سيتم استدعاء socket.destroy مع خطأ ERR_SOCKET_CLOSED. إذا لم يكن هذا مقبس TCP (على سبيل المثال، أنبوب)، فإن استدعاء هذه الطريقة سيؤدي على الفور إلى طرح خطأ ERR_INVALID_HANDLE_TYPE.

socket.resume()

• الإرجاع: <net.Socket> المقبس نفسه.

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

socket.setEncoding([encoding])

تمت الإضافة في: الإصدار v0.1.90

• encoding <سلسلة نصية>
• الإرجاع: <net.Socket> المقبس نفسه.

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

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

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

الإصدار	التغييرات
v13.12.0, v12.17.0	تمت إضافة إعدادات افتراضية جديدة لخيارات المقبس TCP_KEEPCNT و TCP_KEEPINTVL.
v0.1.92	تمت الإضافة في: الإصدار v0.1.92

• enable <بولياني> افتراضي: false
• initialDelay <رقم> افتراضي: 0
• الإرجاع: <net.Socket> المقبس نفسه.

تمكين/تعطيل وظيفة الإبقاء على قيد الحياة، واختياريًا تعيين التأخير الأولي قبل إرسال أول مسبار إبقاء على قيد الحياة على مقبس غير نشط.

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

سيؤدي تمكين وظيفة الإبقاء على قيد الحياة إلى تعيين خيارات المقبس التالية:

• SO_KEEPALIVE=1
• TCP_KEEPIDLE=initialDelay
• TCP_KEEPCNT=10
• TCP_KEEPINTVL=1

socket.setNoDelay([noDelay])

تمت إضافتها في: v0.1.90

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

تمكين/تعطيل استخدام خوارزمية ناجل.

عند إنشاء اتصال TCP، سيتم تمكين خوارزمية ناجل.

تؤخر خوارزمية ناجل البيانات قبل إرسالها عبر الشبكة. إنها تحاول تحسين الإنتاجية على حساب الكمون.

سيؤدي تمرير true لـ noDelay أو عدم تمرير وسيطة إلى تعطيل خوارزمية ناجل للمقبس. سيؤدي تمرير false لـ noDelay إلى تمكين خوارزمية ناجل.

socket.setTimeout(timeout[, callback])

[التاريخ]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير رد اتصال غير صالح إلى وسيطة callback الآن إلى إطلاق ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v0.1.90	تمت إضافتها في: v0.1.90

• timeout <number>
• callback <Function>
• الإرجاع: <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.timeout

تمت الإضافة في: v10.7.0

• <number> | <undefined>

مهلة المقبس بالمللي ثانية كما تم تعيينها بواسطة socket.setTimeout(). تكون undefined إذا لم يتم تعيين مهلة.

socket.unref()

تمت الإضافة في: v0.9.1

• الإرجاع: <net.Socket> المقبس نفسه.

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

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

تمت الإضافة في: v0.1.90

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

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

إرجاع true إذا تم مسح البيانات بأكملها بنجاح إلى مخزن kernel المؤقت. إرجاع false إذا تم وضع كل أو جزء من البيانات في قائمة الانتظار في ذاكرة المستخدم. سيتم إصدار 'drain' عندما يكون المخزن المؤقت مجانيًا مرة أخرى.

سيتم تنفيذ المعلمة callback الاختيارية عند كتابة البيانات أخيرًا، وهو ما قد لا يكون فوريًا.

راجع دفق Writable طريقة write() لمزيد من المعلومات.

socket.readyState

أُضيف في: v0.5.0

• <string>

تمثل هذه الخاصية حالة الاتصال كسلسلة نصية.

• إذا كان التيار قيد الاتصال، فإن socket.readyState تكون opening.
• إذا كان التيار قابلاً للقراءة والكتابة، فإنه يكون open.
• إذا كان التيار قابلاً للقراءة وغير قابل للكتابة، فإنه يكون readOnly.
• إذا كان التيار غير قابل للقراءة وقابل للكتابة، فإنه يكون writeOnly.

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

• options <Object>
• connectListener <Function>
• الإرجاع: <net.Socket>

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

net.connect(path[, connectListener])

أُضيف في: v0.1.90

• path <string>
• connectListener <Function>
• الإرجاع: <net.Socket>

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

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

أُضيف في: v0.1.90

• port <number>
• host <string>
• connectListener <Function>
• الإرجاع: <net.Socket>

اسم مستعار لـ 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) بعد إنشاء المقبس، ولكن قبل أن يبدأ الاتصال.

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

ESM

import net from 'node:net';
const client = net.createConnection({ port: 8124 }, () => {
  // 'connect' listener.
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
});

CJS

const net = require('node:net');
const client = net.createConnection({ port: 8124 }, () => {
  // 'connect' listener.
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
});

للاتصال بالمقبس /tmp/echo.sock:

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

فيما يلي مثال لعميل يستخدم خياري port و onread. في هذه الحالة، سيتم استخدام خيار onread فقط لاستدعاء new net.Socket([options]) وسيتم استخدام خيار port لاستدعاء socket.connect(options[, connectListener]).

ESM

import net from 'node:net';
import { Buffer } from 'node:buffer';
net.createConnection({
  port: 8124,
  onread: {
    // Reuses a 4KiB Buffer for every read from the socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // Received data is available in `buf` from 0 to `nread`.
      console.log(buf.toString('utf8', 0, nread));
    },
  },
});

CJS

const net = require('node:net');
net.createConnection({
  port: 8124,
  onread: {
    // Reuses a 4KiB Buffer for every read from the socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // Received data is available in `buf` from 0 to `nread`.
      console.log(buf.toString('utf8', 0, nread));
    },
  },
});

net.createConnection(path[, connectListener])

تمت الإضافة في: v0.1.90

• path <string> المسار الذي يجب أن يتصل به المقبس. سيتم تمريره إلى socket.connect(path[, connectListener]). انظر تحديد المسارات لاتصالات IPC.
• connectListener <Function> معلمة شائعة لوظائف net.createConnection()، مستمع "مرة واحدة" لحدث 'connect' على المقبس الذي يبدأ الاتصال. سيتم تمريره إلى socket.connect(path[, connectListener]).
• Returns: <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(port[, host][, connectListener]).
• Returns: <net.Socket> المقبس الذي تم إنشاؤه حديثًا والذي يُستخدم لبدء الاتصال.

يبدأ اتصال TCP.

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

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

[التاريخ]

الإصدار	التغييرات
v20.1.0, v18.17.0	خيار highWaterMark مدعوم الآن.
v17.7.0, v16.15.0	خيارات noDelay و keepAlive و keepAliveInitialDelay مدعومة الآن.
v0.5.0	تمت إضافته في: v0.5.0

• options <Object>

  • allowHalfOpen <boolean> إذا تم تعيينه على false، فستنهي المقبس تلقائيًا الجانب القابل للكتابة عند انتهاء الجانب القابل للقراءة. افتراضي: false.
  • highWaterMark <number> يتجاوز اختياريًا جميع readableHighWaterMark و writableHighWaterMark الخاصة بـ net.Socket. افتراضي: راجع stream.getDefaultHighWaterMark().
  • keepAlive <boolean> إذا تم تعيينه على true، فإنه يمكّن وظيفة keep-alive على المقبس فور استلام اتصال وارد جديد، بشكل مشابه لما يتم القيام به في socket.setKeepAlive(). افتراضي: false.
  • keepAliveInitialDelay <number> إذا تم تعيينه على رقم موجب، فإنه يحدد التأخير الأولي قبل إرسال أول مسبار keepalive على مقبس خامد. افتراضي: 0.
  • noDelay <boolean> إذا تم تعيينه على true، فإنه يعطل استخدام خوارزمية Nagle فور استلام اتصال وارد جديد. افتراضي: false.
  • pauseOnConnect <boolean> يشير إلى ما إذا كان يجب إيقاف المقبس مؤقتًا على الاتصالات الواردة. افتراضي: false.
  • blockList <net.BlockList> يمكن استخدام blockList لتعطيل الوصول الوارد إلى عناوين IP محددة أو نطاقات IP أو شبكات IP الفرعية. هذا لا يعمل إذا كان الخادم خلف وكيل عكسي أو NAT أو ما إلى ذلك، لأن العنوان الذي يتم فحصه مقابل القائمة المحظورة هو عنوان الوكيل أو العنوان المحدد بواسطة NAT.

• connectionListener <Function> يتم تعيينه تلقائيًا كمستمع لحدث 'connection'.

• الإرجاع: <net.Server>

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

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

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

يمكن أن يكون الخادم خادم TCP أو خادم IPC، اعتمادًا على ما listen() إليه.

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

ESM

import net from 'node:net';
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
});

CJS

const net = require('node:net');
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
});

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

telnet localhost 8124

للاستماع على المقبس /tmp/echo.sock:

server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
});

استخدم nc للاتصال بخادم مقبس نطاق Unix:

nc -U /tmp/echo.sock

net.getDefaultAutoSelectFamily()

تمت الإضافة في: الإصدار v19.4.0

يحصل على القيمة الافتراضية الحالية للخيار autoSelectFamily في socket.connect(options). القيمة الافتراضية الأولية هي true، إلا إذا تم توفير خيار سطر الأوامر --no-network-family-autoselection.

• الإرجاع: <boolean> القيمة الافتراضية الحالية للخيار autoSelectFamily.

net.setDefaultAutoSelectFamily(value)

تمت الإضافة في: الإصدار v19.4.0

يضبط القيمة الافتراضية للخيار autoSelectFamily في socket.connect(options).

• value <boolean> القيمة الافتراضية الجديدة. القيمة الافتراضية الأولية هي true، إلا إذا تم توفير خيار سطر الأوامر --no-network-family-autoselection.

net.getDefaultAutoSelectFamilyAttemptTimeout()

تمت الإضافة في: الإصدار v19.8.0, v18.18.0

يحصل على القيمة الافتراضية الحالية للخيار autoSelectFamilyAttemptTimeout في socket.connect(options). القيمة الافتراضية الأولية هي 250 أو القيمة المحددة عبر خيار سطر الأوامر --network-family-autoselection-attempt-timeout.

• الإرجاع: <number> القيمة الافتراضية الحالية للخيار autoSelectFamilyAttemptTimeout.

net.setDefaultAutoSelectFamilyAttemptTimeout(value)

تمت الإضافة في: الإصدار v19.8.0, v18.18.0

يضبط القيمة الافتراضية للخيار autoSelectFamilyAttemptTimeout في socket.connect(options).

• value <number> القيمة الافتراضية الجديدة، والتي يجب أن تكون رقمًا موجبًا. إذا كان الرقم أقل من 10، فسيتم استخدام القيمة 10 بدلاً من ذلك. القيمة الافتراضية الأولية هي 250 أو القيمة المحددة عبر خيار سطر الأوامر --network-family-autoselection-attempt-timeout.

net.isIP(input)

تمت الإضافة في: v0.3.0

• input <string>
• إرجاع: <integer>

يُرجع 6 إذا كان input عنوان IPv6. يُرجع 4 إذا كان input عنوان IPv4 في تدوين عشري نقطي بدون أصفار بادئة. بخلاف ذلك، يُرجع 0.

net.isIP('::1'); // يُرجع 6
net.isIP('127.0.0.1'); // يُرجع 4
net.isIP('127.000.000.001'); // يُرجع 0
net.isIP('127.0.0.1/24'); // يُرجع 0
net.isIP('fhqwhgads'); // يُرجع 0

net.isIPv4(input)

تمت الإضافة في: v0.3.0

• input <string>
• إرجاع: <boolean>

يُرجع true إذا كان input عنوان IPv4 في تدوين عشري نقطي بدون أصفار بادئة. بخلاف ذلك، يُرجع false.

net.isIPv4('127.0.0.1'); // يُرجع true
net.isIPv4('127.000.000.001'); // يُرجع false
net.isIPv4('127.0.0.1/24'); // يُرجع false
net.isIPv4('fhqwhgads'); // يُرجع false

net.isIPv6(input)

تمت الإضافة في: v0.3.0

• input <string>
• إرجاع: <boolean>

يُرجع true إذا كان input عنوان IPv6. بخلاف ذلك، يُرجع false.

net.isIPv6('::1'); // يُرجع true
net.isIPv6('fhqwhgads'); // يُرجع false