HTTP/2

[السجل]

الإصدار	التغييرات
v15.0.0	يمكن الآن إرسال/استقبال الطلبات مع رأس host (مع أو بدون :authority).
v15.3.0، v14.17.0	من الممكن الآن إلغاء طلب باستخدام AbortSignal.
v10.10.0	أصبح HTTP/2 الآن مستقرًا. كان تجريبيًا سابقًا.
v8.4.0	تمت الإضافة في: v8.4.0

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

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

رمز المصدر: lib/http2.js

يوفر مُعامل node:http2 تطبيقًا لبروتوكول HTTP/2. يمكن الوصول إليه باستخدام:

const http2 = require('node:http2')

تحديد ما إذا كان دعم التشفير غير متوفر

من الممكن إنشاء Node.js دون تضمين دعم لوحدة node:crypto. في مثل هذه الحالات، سيؤدي محاولة import من node:http2 أو استدعاء require('node:http2') إلى إلقاء خطأ.

عند استخدام CommonJS، يمكن التقاط الخطأ المُلقى باستخدام try/catch:

let http2
try {
  http2 = require('node:http2')
} catch (err) {
  console.error('تم تعطيل دعم http2!')
}

عند استخدام الكلمة الأساسية import ESM النحوية، لا يمكن التقاط الخطأ إلا إذا تم تسجيل مُعامل لـ process.on('uncaughtException') قبل أي محاولة لتحميل الوحدة (باستخدام، على سبيل المثال، وحدة تحميل مسبق).

عند استخدام ESM، إذا كانت هناك فرصة لتنفيذ الرمز على إصدار من Node.js حيث لم يتم تمكين دعم التشفير، فكر في استخدام دالة import() بدلاً من الكلمة الأساسية import النحوية:

let http2
try {
  http2 = await import('node:http2')
} catch (err) {
  console.error('تم تعطيل دعم http2!')
}

واجهة برمجة التطبيقات الأساسية

توفر واجهة برمجة التطبيقات الأساسية واجهة منخفضة المستوى مصممة خصيصًا لدعم ميزات بروتوكول HTTP/2. وهي ليست مصممة خصيصًا للتوافق مع واجهة برمجة التطبيقات الموجودة لوحدة HTTP/1. ومع ذلك، فإن واجهة برمجة التطبيقات للتوافق هي كذلك.

واجهة برمجة التطبيقات الأساسية http2 أكثر تناسقًا بين العميل والخادم من واجهة برمجة التطبيقات http. على سبيل المثال، يمكن إصدار معظم الأحداث، مثل 'error' و'connect' و'stream'، إما بواسطة رمز العميل أو رمز الخادم.

مثال من جانب الخادم

يوضح ما يلي خادم HTTP/2 بسيطًا باستخدام واجهة برمجة التطبيقات الأساسية. نظرًا لعدم وجود متصفحات معروفة تدعم HTTP/2 غير مشفر، فإن استخدام http2.createSecureServer() ضروري عند التواصل مع عملاء المتصفح.

ESM

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

const server = createSecureServer({
  key: readFileSync('localhost-privkey.pem'),
  cert: readFileSync('localhost-cert.pem'),
})

server.on('error', err => console.error(err))

server.on('stream', (stream, headers) => {
  // stream is a Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8443)

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const server = http2.createSecureServer({
  key: fs.readFileSync('localhost-privkey.pem'),
  cert: fs.readFileSync('localhost-cert.pem'),
})
server.on('error', err => console.error(err))

server.on('stream', (stream, headers) => {
  // stream is a Duplex
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8443)

لتوليد الشهادة والمفتاح لهذا المثال، قم بتشغيل:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout localhost-privkey.pem -out localhost-cert.pem

مثال من جانب العميل

يوضح ما يلي عميل HTTP/2:

ESM

import { connect } from 'node:http2'
import { readFileSync } from 'node:fs'

const client = connect('https://localhost:8443', {
  ca: readFileSync('localhost-cert.pem'),
})
client.on('error', err => console.error(err))

const req = client.request({ ':path': '/' })

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`)
  }
})

req.setEncoding('utf8')
let data = ''
req.on('data', chunk => {
  data += chunk
})
req.on('end', () => {
  console.log(`\n${data}`)
  client.close()
})
req.end()

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const client = http2.connect('https://localhost:8443', {
  ca: fs.readFileSync('localhost-cert.pem'),
})
client.on('error', err => console.error(err))

const req = client.request({ ':path': '/' })

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`)
  }
})

req.setEncoding('utf8')
let data = ''
req.on('data', chunk => {
  data += chunk
})
req.on('end', () => {
  console.log(`\n${data}`)
  client.close()
})
req.end()

صنف: Http2Session

مضاف في: v8.4.0

• يمتد: <EventEmitter>

تمثل مثيلات صنف http2.Http2Session جلسة اتصال نشطة بين عميل وخادم HTTP/2. لا يُقصد أن يتم إنشاء مثيلات هذا الصنف مباشرةً بواسطة شفرة المستخدم.

ستظهر كل مثيل من Http2Session سلوكًا مختلفًا قليلاً اعتمادًا على ما إذا كان يعمل كخادم أو عميل. يمكن استخدام خاصية http2session.type لتحديد الوضع الذي يعمل فيه Http2Session. على جانب الخادم، يجب أن يكون لدى شفرة المستخدم نادرًا مناسبة للعمل مع كائن Http2Session مباشرةً، حيث يتم اتخاذ معظم الإجراءات عادةً من خلال التفاعلات مع كائنات Http2Server أو Http2Stream.

لن تقوم شفرة المستخدم بإنشاء مثيلات Http2Session مباشرةً. يتم إنشاء مثيلات Http2Session على جانب الخادم بواسطة مثيل Http2Server عندما يتم استقبال اتصال HTTP/2 جديد. يتم إنشاء مثيلات Http2Session على جانب العميل باستخدام طريقة http2.connect().

Http2Session والمقابس

يرتبط كل مثيل من Http2Session بمقبس واحد فقط net.Socket أو tls.TLSSocket عند إنشائه. عند تدمير كل من Socket أو Http2Session، سيتم تدمير كليهما.

بسبب متطلبات التهيئة والمعالجة المحددة التي يفرضها بروتوكول HTTP/2، لا يُنصح لشفرة المستخدم بقراءة البيانات من أو كتابة البيانات إلى مثيل Socket مرتبط بـ Http2Session. يمكن أن يؤدي القيام بذلك إلى وضع جلسة HTTP/2 في حالة غير محددة مما يتسبب في جعل الجلسة والمقبس غير قابل للاستخدام.

بمجرد ربط Socket بـ Http2Session، يجب على شفرة المستخدم الاعتماد فقط على واجهة برمجة التطبيقات الخاصة بـ Http2Session.

حدث: 'close'

مضاف في: v8.4.0

يتم إصدار حدث 'close' بمجرد تدمير Http2Session. لا يتوقع مستمعه أي وسيطات.

حدث: 'connect'

مضاف في: v8.4.0

• session <Http2Session>
• socket <net.Socket>

يتم إصدار حدث 'connect' بمجرد اتصال Http2Session بنجاح بالطرف البعيد ويمكن أن تبدأ عملية الاتصال.

عادةً ما لا تستمع شفرة المستخدم إلى هذا الحدث مباشرةً.

الحدث: 'error'

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

• error <Error>

يتم بث حدث 'error' عندما يحدث خطأ أثناء معالجة Http2Session.

الحدث: 'frameError'

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

• type <integer> نوع الإطار.
• code <integer> رمز الخطأ.
• id <integer> معرف الدفق (أو 0 إذا لم يكن الإطار مرتبطًا بدفق).

يتم بث حدث 'frameError' عندما يحدث خطأ أثناء محاولة إرسال إطار على الجلسة. إذا كان الإطار الذي تعذر إرساله مرتبطًا بـ Http2Stream محدد، فسيتم إجراء محاولة لبث حدث 'frameError' على Http2Stream.

إذا كان حدث 'frameError' مرتبطًا بدفق، فسيتم إغلاق الدفق وتدميره مباشرةً بعد حدث 'frameError'. إذا لم يكن الحدث مرتبطًا بدفق، فسيتم إيقاف تشغيل Http2Session مباشرةً بعد حدث 'frameError'.

الحدث: 'goaway'

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

• errorCode <number> رمز خطأ HTTP/2 المحدد في إطار GOAWAY.
• lastStreamID <number> معرف آخر دفق قام النظير البعيد بمعالجته بنجاح (أو 0 إذا لم يتم تحديد أي معرف).
• opaqueData <Buffer> إذا تم تضمين بيانات معتمة إضافية في إطار GOAWAY، فسيتم تمرير مثيل Buffer يحتوي على تلك البيانات.

يتم بث حدث 'goaway' عند استقبال إطار GOAWAY.

سيتم إيقاف تشغيل مثيل Http2Session تلقائيًا عند بث حدث 'goaway'.

الحدث: 'localSettings'

مضاف في: v8.4.0

• settings <كائن إعدادات HTTP/2> نسخة من إطار SETTINGS المستلم.

يُصدر حدث 'localSettings' عندما يتم استلام إطار SETTINGS للاعتراف.

عند استخدام http2session.settings() لإرسال إعدادات جديدة، لا تسري الإعدادات المُعدلة حتى يتم إصدار حدث 'localSettings'.

session.settings({ enablePush: false })

session.on('localSettings', settings => {
  /* استخدم الإعدادات الجديدة */
})

الحدث: 'ping'

مضاف في: v10.12.0

• payload <مُخزن مؤقت> حمولة إطار PING المكونة من 8 بايت.

يُصدر حدث 'ping' كلما تم استلام إطار PING من النظير المُتصل.

الحدث: 'remoteSettings'

مضاف في: v8.4.0

• settings <كائن إعدادات HTTP/2> نسخة من إطار SETTINGS المستلم.

يُصدر حدث 'remoteSettings' عندما يتم استلام إطار SETTINGS جديد من النظير المُتصل.

session.on('remoteSettings', settings => {
  /* استخدم الإعدادات الجديدة */
})

الحدث: 'stream'

مضاف في: v8.4.0

• stream <Http2Stream> مرجع إلى التدفق
• headers <كائن رؤوس HTTP/2> كائن يصف الرؤوس
• flags <رقم> الأعلام العددية المُرتبطة
• rawHeaders <مصفوفة> مصفوفة تحتوي على أسماء الرؤوس الخام متبوعة بقيمها المُناظرة.

يُصدر حدث 'stream' عندما يتم إنشاء Http2Stream جديد.

session.on('stream', (stream, headers, flags) => {
  const method = headers[':method']
  const path = headers[':path']
  // ...
  stream.respond({
    ':status': 200,
    'content-type': 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

على جانب الخادم، عادةً ما لا يستمع رمز المستخدم لهذا الحدث مباشرةً، وسيقوم بدلاً من ذلك بتسجيل مُعالِج لحدث 'stream' المُصدر من مثيلات net.Server أو tls.Server التي تُرجعها http2.createServer() و http2.createSecureServer() على التوالي، كما في المثال أدناه:

ESM

import { createServer } from 'node:http2'

// إنشاء خادم HTTP/2 غير مُشفر
const server = createServer()

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.on('error', error => console.error(error))
  stream.end('<h1>Hello World</h1>')
})

server.listen(8000)

CJS

const http2 = require('node:http2')

// إنشاء خادم HTTP/2 غير مُشفر
const server = http2.createServer()

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.on('error', error => console.error(error))
  stream.end('<h1>Hello World</h1>')
})

server.listen(8000)

على الرغم من أن تدفقات HTTP/2 ومقابس الشبكة ليست في مُطابقة 1:1، إلا أن خطأ الشبكة سيدمر كل تدفق فردي ويجب التعامل معه على مستوى التدفق، كما هو موضح أعلاه.

الحدث: 'timeout'

مضاف في: v8.4.0

بعد استخدام طريقة http2session.setTimeout() لتعيين فترة مهلة زمنية لهذا Http2Session، يتم إصدار حدث 'timeout' إذا لم يكن هناك نشاط على Http2Session بعد عدد المللي ثواني المُهيّأ. لا يتوقع مُستمعه أي وسيطات.

session.setTimeout(2000)
session.on('timeout', () => {
  /* .. */
})

http2session.alpnProtocol

مضاف في: v9.4.0

• <string> | <undefined>

ستكون القيمة undefined إذا لم يتم توصيل Http2Session بعد بمقبس، أو h2c إذا لم يتم توصيل Http2Session بـ TLSSocket، أو ستُعيد قيمة خاصية alpnProtocol الخاصة بـ TLSSocket المُوصّل.

http2session.close([callback])

مضاف في: v9.4.0

• callback <Function>

يُغلق Http2Session بسلاسة، مما يسمح لأي تدفقات موجودة بالانتهاء بنفسها ويمنع إنشاء مثيلات جديدة من Http2Stream. بعد الإغلاق، قد يتم استدعاء http2session.destroy() إذا لم تكن هناك مثيلات مفتوحة من Http2Stream.

إذا تم تحديده، فسيتم تسجيل دالة callback كمعالج لحدث 'close'.

http2session.closed

مضاف في: v9.4.0

• <boolean>

ستكون true إذا تم إغلاق مثيل Http2Session هذا، وإلا false.

http2session.connecting

مضاف في: v10.0.0

• <boolean>

ستكون true إذا كان مثيل Http2Session هذا لا يزال يتصل، وسيتم تعيينه إلى false قبل إصدار حدث connect و/أو استدعاء مُستدعي http2.connect.

http2session.destroy([error][, code])

مضاف في: v8.4.0

• error <Error> كائن Error إذا كان يتم تدمير Http2Session بسبب خطأ.
• code <number> رمز خطأ HTTP/2 لإرساله في إطار GOAWAY النهائي. إذا لم يتم تحديده، ولم يكن error غير مُعرّف، فإن الافتراضي هو INTERNAL_ERROR، وإلا فإن الافتراضي هو NO_ERROR.

يُنهي Http2Session و net.Socket أو tls.TLSSocket المُرتبطين على الفور.

بعد التدمير، سيُصدر Http2Session حدث 'close'. إذا لم يكن error غير مُعرّف، فسيتم إصدار حدث 'error' قبل حدث 'close' مباشرةً.

إذا كانت هناك أيّ تدفقات Http2Streams مفتوحة متبقية مُرتبطة بـ Http2Session، فسيتم تدميرها أيضًا.

http2session.destroyed

مُضاف في: v8.4.0

• <boolean>

سيكون true إذا تم تدمير مثيل Http2Session هذا ويجب عدم استخدامه بعد الآن، وإلا فسيكون false.

http2session.encrypted

مُضاف في: v9.4.0

• <boolean> | <undefined>

القيمة هي undefined إذا لم يتم توصيل مقبس جلسة Http2Session بعد، true إذا تم توصيل Http2Session باستخدام TLSSocket، و false إذا تم توصيل Http2Session بأي نوع آخر من المقابس أو الدفق.

http2session.goaway([code[, lastStreamID[, opaqueData]]])

مُضاف في: v9.4.0

• code <number> رمز خطأ HTTP/2
• lastStreamID <number> المعرف العددي لـ Http2Stream المُعالَج أخيرًا
• opaqueData <Buffer> | <TypedArray> | <DataView> مثيل TypedArray أو DataView يحتوي على بيانات إضافية ليتم حملها داخل إطار GOAWAY.

ينقل إطار GOAWAY إلى النظير المُتصل بدون إغلاق Http2Session.

http2session.localSettings

مُضاف في: v8.4.0

• <كائن إعدادات HTTP/2>

كائن بدون نموذج أولي يصف إعدادات الموقع الحالية لهذا Http2Session. الإعدادات المحلية خاصة بمثيل Http2Session هذا.

http2session.originSet

مُضاف في: v9.4.0

• <string[]> | <undefined>

إذا تم توصيل Http2Session بـ TLSSocket، فستعيد خاصية originSet مصفوفة من الأصول التي يمكن اعتبار Http2Session موثوقًا بها.

خاصية originSet متاحة فقط عند استخدام اتصال TLS آمن.

http2session.pendingSettingsAck

مُضاف في: v8.4.0

• <boolean>

يشير إلى ما إذا كان Http2Session ينتظر حاليًا إقرار إطار SETTINGS المُرسل. سيكون true بعد استدعاء طريقة http2session.settings(). سيكون false بمجرد إقرار جميع أطر SETTINGS المُرسلة.

http2session.ping([payload, ]callback)

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُدعًى غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.9.3	مُضاف في: v8.9.3

• payload <Buffer> | <TypedArray> | <DataView> حمولة ping اختيارية.
• callback <Function>
• القيمة المُرجعة: <boolean>

يُرسل إطار PING إلى نظير HTTP/2 المُتصل. يجب توفير دالة callback. ستُرجع الطريقة true إذا تم إرسال PING، و false بخلاف ذلك.

يتم تحديد الحد الأقصى لعدد عمليات ping المعلقة (غير المُعترف بها) بواسطة خيار التكوين maxOutstandingPings. الحد الأقصى الافتراضي هو 10.

إذا تم توفيره، يجب أن تكون payload عبارة عن Buffer أو TypedArray أو DataView تحتوي على 8 بايت من البيانات التي سيتم إرسالها مع PING وإرجاعها مع إقرار ping.

سيتم استدعاء دالة callback بثلاث وسيطات: وسيطة خطأ ستكون null إذا تم إقرار PING بنجاح، وسيطة duration التي تُبلغ عن عدد الميلي ثانية التي انقضت منذ إرسال ping واستلام الإقرار، و Buffer تحتوي على حمولة PING التي تبلغ 8 بايت.

session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`تم إقرار Ping في ${duration} ميلي ثانية`)
    console.log(`بحمولة '${payload.toString()}'`)
  }
})

إذا لم يتم تحديد وسيطة payload، فستكون حمولة افتراضية هي طابع زمني 64 بت (أقل بت) يُشير إلى بداية مدة PING.

http2session.ref()

مضاف في: v9.4.0

يطلق ref() على net.Socket الأساسية لمثيل Http2Session هذا.

http2session.remoteSettings

مضاف في: v8.4.0

• <كائن إعدادات HTTP/2>

كائن بدون نموذج أولي يصف إعدادات العميل البعيد الحالية لهذا Http2Session. يتم تعيين الإعدادات البعيدة بواسطة نظير HTTP/2 المتصل.

http2session.setLocalWindowSize(windowSize)

مضاف في: v15.3.0، v14.18.0

• windowSize <رقم>

يحدد حجم نافذة نقطة النهاية المحلية. windowSize هو حجم النافذة الإجمالي المراد تعيينه، وليس دلتا.

ESM

import { createServer } from 'node:http2'

const server = createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // تعيين حجم النافذة المحلية ليكون 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
const expectedWindowSize = 2 ** 20
server.on('session', session => {
  // تعيين حجم النافذة المحلية ليكون 2 ** 20
  session.setLocalWindowSize(expectedWindowSize)
})

بالنسبة لعملاء http2، الحدث المناسب هو إما 'connect' أو 'remoteSettings'.

http2session.setTimeout(msecs, callback)

[السجل]

الإصدار	التغييرات
v18.0.0	إن تمرير دالة استدعاء غير صالحة إلى وسيطة callback يلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.4.0	مضاف في: v8.4.0

• msecs <رقم>
• callback <دالة>

يستخدم لتعيين دالة استدعاء يتم استدعاؤها عندما لا يكون هناك نشاط على Http2Session بعد msecs ميلي ثانية. يتم تسجيل callback المعطى كمستمع على حدث 'timeout'.

http2session.socket

مُضاف في: v8.4.0

• <net.Socket> | <tls.TLSSocket>

يُعيد كائن Proxy يعمل كـ net.Socket (أو tls.TLSSocket) ولكنه يحدّ من الطرق المتاحة إلى تلك الآمنة للاستخدام مع HTTP/2.

سيرمي destroy, emit, end, pause, read, resume, و write خطأً برمز ERR_HTTP2_NO_SOCKET_MANIPULATION. اطلع على Http2Session and Sockets لمزيد من المعلومات.

ستتمّ مُناداة طريقة setTimeout على هذا Http2Session.

سيتمّ توجيه جميع التفاعلات الأخرى مباشرةً إلى المقبس.

http2session.state

مُضاف في: v8.4.0

يوفر معلومات متنوعة حول الحالة الحالية لـ Http2Session.

• <Object>
  • effectiveLocalWindowSize <number> حجم نافذة التحكم بالتدفق المحلية (استقبال) الحالية لـ Http2Session.
  • effectiveRecvDataLength <number> العدد الحالي للبايتات التي تم استقبالها منذ آخر WINDOW_UPDATE للتحكم بالتدفق.
  • nextStreamID <number> المُعرّف العددي الذي سيتم استخدامه في المرة القادمة التي يتم فيها إنشاء Http2Stream جديد بواسطة هذا Http2Session.
  • localWindowSize <number> عدد البايتات التي يمكن للطرف البعيد إرسالها دون استقبال WINDOW_UPDATE.
  • lastProcStreamID <number> المعرف العددي لـ Http2Stream الذي تم استقبال إطار HEADERS أو DATA له مؤخراً.
  • remoteWindowSize <number> عدد البايتات التي قد يُرسلها هذا Http2Session دون استقبال WINDOW_UPDATE.
  • outboundQueueSize <number> عدد الإطارات الموجودة حاليًا داخل قائمة الانتظار الصادرة لهذا Http2Session.
  • deflateDynamicTableSize <number> الحجم الحالي بالبايتات لجداول حالة ضغط الرأس الصادرة.
  • inflateDynamicTableSize <number> الحجم الحالي بالبايتات لجداول حالة ضغط الرأس الواردة.

كائن يصف الحالة الحالية لهذا Http2Session.

http2session.settings([settings][, callback])

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير مُعاودة اتصال غير صالحة إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.4.0	تمت الإضافة في: v8.4.0

• settings <كائن إعدادات HTTP/2>
• callback <دالة> دالة تُستدعى بمجرد اتصال الجلسة أو على الفور إذا كانت الجلسة متصلة بالفعل.
  • err <خطأ> | <لا شيء>
  • settings <كائن إعدادات HTTP/2> كائن settings المُحدّث.
  • duration <عدد صحيح>

يُحدّث إعداداتك المحلية الحالية لهذه الجلسة Http2Session ويرسل إطار SETTINGS جديدًا إلى نظير HTTP/2 المتصل.

بمجرد استدعاء هذه الدالة، ستكون خاصية http2session.pendingSettingsAck true بينما تنتظر الجلسة من النظير البعيد الموافقة على الإعدادات الجديدة.

لن تصبح الإعدادات الجديدة فعّالة حتى يتم استلام إقرار SETTINGS ويتم إصدار حدث 'localSettings'. من الممكن إرسال العديد من إطارات SETTINGS بينما يكون الإقرار لا يزال قيد الانتظار.

http2session.type

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

• <رقم>

سيكون http2session.type مساويًا لـ http2.constants.NGHTTP2_SESSION_SERVER إذا كانت مثيل Http2Session هذا خادمًا، و http2.constants.NGHTTP2_SESSION_CLIENT إذا كانت المثيل عميلًا.

http2session.unref()

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

تُدعو الدالة unref() على net.Socket الأساسية لمثيل Http2Session هذا.

الصنف: ServerHttp2Session

مضاف في: v8.4.0

• يمتد: <Http2Session>

serverhttp2session.altsvc(alt, originOrStream)

مضاف في: v9.4.0

• alt <string> وصف لتكوين الخدمة البديلة كما هو محدد بواسطة RFC 7838.
• originOrStream <number> | <string> | <URL> | <Object> إما سلسلة URL تحدد الأصل (أو كائن بخاصية origin) أو معرف رقمي لـ Http2Stream نشط كما هو موضح بواسطة خاصية http2stream.id.

يرسل إطار ALTSVC (كما هو محدد بواسطة RFC 7838) إلى العميل المتصل.

ESM

import { createServer } from 'node:http2'

const server = createServer()
server.on('session', session => {
  // تعيين altsvc لمنشأ https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // تعيين altsvc لدفق محدد
  stream.session.altsvc('h2=":8000"', stream.id)
})

CJS

const http2 = require('node:http2')

const server = http2.createServer()
server.on('session', session => {
  // تعيين altsvc لمنشأ https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80')
})

server.on('stream', stream => {
  // تعيين altsvc لدفق محدد
  stream.session.altsvc('h2=":8000"', stream.id)
})

يشير إرسال إطار ALTSVC باستخدام معرف دفق محدد إلى أن الخدمة البديلة مرتبطة بأصل Http2Stream المعطى.

يجب أن تحتوي سلسلة alt وسلسلة الأصل على بايت ASCII فقط ويتم تفسيرها بدقة على أنها تسلسل من بايت ASCII. يمكن تمرير القيمة الخاصة 'clear' لمسح أي خدمة بديلة تم تعيينها مسبقًا لنطاق معين.

عندما يتم تمرير سلسلة كوسيط originOrStream، سيتم تحليلها كـ URL وسيتم اشتقاق الأصل. على سبيل المثال، الأصل لعنوان URL HTTP 'https://example.org/foo/bar' هو سلسلة ASCII 'https://example.org'. سيتم إطلاق خطأ إذا تعذر تحليل السلسلة المعطاة كـ URL أو إذا تعذر اشتقاق أصل صالح.

يمكن تمرير كائن URL، أو أي كائن يحتوي على خاصية origin، كـ originOrStream، وفي هذه الحالة سيتم استخدام قيمة خاصية origin. يجب أن تكون قيمة خاصية origin أصل ASCII مُسلسل بشكل صحيح.

تحديد الخدمات البديلة

يتم تعريف تنسيق معلمة alt بدقة بواسطة RFC 7838 كسلسلة ASCII تحتوي على قائمة بفاصلات فاصلة من البروتوكولات "البديلة" المرتبطة بمضيف ومنفذ محددين.

على سبيل المثال، تشير القيمة 'h2="example.org:81"' إلى أن بروتوكول HTTP/2 متوفر على المضيف 'example.org' على منفذ TCP/IP 81. يجب أن يكون المضيف والمنفذ محصورين ضمن علامات الاقتباس (").

يمكن تحديد بدائل متعددة، على سبيل المثال: 'h2="example.org:81", h2=":82"'.

قد يكون معرف البروتوكول ('h2' في الأمثلة) أي معرف بروتوكول ALPN صالح معرف بروتوكول ALPN.

لا يتم التحقق من صحة بناء جملة هذه القيم بواسطة تنفيذ Node.js ويتم تمريرها كما هو موفر من قبل المستخدم أو مُستقبَل من النظير.

serverhttp2session.origin(...origins)

مضاف في: v10.12.0

• origins <string> | <URL> | <Object> سلسلة أو أكثر من سلاسل URL مُمررة كحجج منفصلة.

يرسل إطار ORIGIN (كما هو مُعرّف بواسطة RFC 8336) إلى العميل المُتصل للإعلان عن مجموعة الأصول التي يستطيع الخادم توفير استجابات مُعتمدة لها.

ESM

import { createSecureServer } from 'node:http2'
const options = getSecureOptionsSomehow()
const server = createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})
server.on('session', session => {
  session.origin('https://example.com', 'https://example.org')
})

CJS

const http2 = require('node:http2')
const options = getSecureOptionsSomehow()
const server = http2.createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})
server.on('session', session => {
  session.origin('https://example.com', 'https://example.org')
})

عندما يتم تمرير سلسلة كـ origin، سيتم تحليلها كـ URL وسيتم اشتقاق الأصل. على سبيل المثال، الأصل لعنوان URL HTTP 'https://example.org/foo/bar' هو سلسلة ASCII 'https://example.org'. سيتم إلقاء خطأ إذا تعذر تحليل السلسلة المعطاة كـ URL أو إذا تعذر اشتقاق أصل صالح.

يمكن تمرير كائن URL، أو أي كائن به خاصية origin، كـ origin، وفي هذه الحالة سيتم استخدام قيمة خاصية origin. يجب أن تكون قيمة خاصية origin أصل ASCII مُسلسل بشكل صحيح.

بدلاً من ذلك، يمكن استخدام خيار origins عند إنشاء خادم HTTP/2 جديد باستخدام طريقة http2.createSecureServer() :

ESM

import { createSecureServer } from 'node:http2'
const options = getSecureOptionsSomehow()
options.origins = ['https://example.com', 'https://example.org']
const server = createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})

CJS

const http2 = require('node:http2')
const options = getSecureOptionsSomehow()
options.origins = ['https://example.com', 'https://example.org']
const server = http2.createSecureServer(options)
server.on('stream', stream => {
  stream.respond()
  stream.end('ok')
})

الصف: ClientHttp2Session

مضاف في: v8.4.0

• يمتد: <Http2Session>

الحدث: 'altsvc'

مضاف في: v9.4.0

• alt <string>
• origin <string>
• streamId <number>

يتم إصدار حدث 'altsvc' كلما استقبل العميل إطار ALTSVC. يتم إصدار الحدث بقيمة ALTSVC، وorigin، وstream ID. إذا لم يتم توفير origin في إطار ALTSVC، فسيكون origin سلسلة فارغة.

ESM

import { connect } from 'node:http2'
const client = connect('https://example.org')

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt)
  console.log(origin)
  console.log(streamId)
})

CJS

const http2 = require('node:http2')
const client = http2.connect('https://example.org')

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt)
  console.log(origin)
  console.log(streamId)
})

الحدث: 'origin'

مضاف في: v10.12.0

• origins <string[]>

يتم إصدار حدث 'origin' كلما استقبل العميل إطار ORIGIN. يتم إصدار الحدث بمصفوفة من سلاسل origin. سيتم تحديث http2session.originSet لتشمل أصول المستلمة.

ESM

import { connect } from 'node:http2'
const client = connect('https://example.org')

client.on('origin', origins => {
  for (let n = 0; n < origins.length; n++) console.log(origins[n])
})

CJS

const http2 = require('node:http2')
const client = http2.connect('https://example.org')

client.on('origin', origins => {
  for (let n = 0; n < origins.length; n++) console.log(origins[n])
})

لا يتم إصدار حدث 'origin' إلا عند استخدام اتصال TLS آمن.

clienthttp2session.request(headers[, options])

مضاف في: v8.4.0

• headers <كائن رؤوس HTTP/2>

• options <كائن>

  • endStream <قيمة منطقية> true إذا كان يجب إغلاق جانب الكتابة من Http2Stream في البداية، كما هو الحال عند إرسال طلب GET الذي لا يتوقع نصًا أساسيًا.
  • exclusive <قيمة منطقية> عندما تكون true و parent تحدد تيارًا رئيسيًا، يصبح التيار المُنشأ التابع المباشر الوحيد للتيار الرئيسي، مع جعل جميع التوابع الأخرى تابعة للتيار المُنشأ حديثًا. الافتراضي: false.
  • parent <رقم> يحدد المُعرّف العددي لتيار يعتمد عليه التيار المُنشأ حديثًا.
  • weight <رقم> يحدد التبعية النسبية لتيار فيما يتعلق بالتيارات الأخرى التي لها نفس parent. القيمة هي رقم بين 1 و 256 (بما في ذلك).
  • waitForTrailers <قيمة منطقية> عندما تكون true، سيصدر Http2Stream حدث 'wantTrailers' بعد إرسال إطار DATA الأخير.
  • signal <إشارة الإلغاء> إشارة إلغاء يمكن استخدامها لإلغاء طلب جارٍ.

• المُخرجات: <ClientHttp2Stream>

لنسخ Http2Session لعميل HTTP/2 فقط، يقوم http2session.request() بإنشاء مثيل Http2Stream وإرجاعه، والذي يمكن استخدامه لإرسال طلب HTTP/2 إلى الخادم المتصل.

عند إنشاء مثيل ClientHttp2Session لأول مرة، قد لا يكون المقبس متصلاً بعد. إذا تم استدعاء clienthttp2session.request() خلال هذا الوقت، فسيتم تأجيل الطلب الفعلي حتى يصبح المقبس جاهزًا للعمل. إذا تم إغلاق session قبل تنفيذ الطلب الفعلي، فسيتم طرح ERR_HTTP2_GOAWAY_SESSION.

تتوفر هذه الطريقة فقط إذا كانت http2session.type تساوي http2.constants.NGHTTP2_SESSION_CLIENT.

ESM

import { connect, constants } from 'node:http2'
const clientSession = connect('https://localhost:1234')
const { HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS } = constants

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' })
req.on('response', headers => {
  console.log(headers[HTTP2_HEADER_STATUS])
  req.on('data', chunk => {
    /* .. */
  })
  req.on('end', () => {
    /* .. */
  })
})

CJS

const http2 = require('node:http2')
const clientSession = http2.connect('https://localhost:1234')
const { HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS } = http2.constants

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' })
req.on('response', headers => {
  console.log(headers[HTTP2_HEADER_STATUS])
  req.on('data', chunk => {
    /* .. */
  })
  req.on('end', () => {
    /* .. */
  })
})

عندما يتم تعيين خيار options.waitForTrailers، يتم إصدار حدث 'wantTrailers' مباشرة بعد وضع آخر جزء من بيانات الحمولة المراد إرسالها في قائمة الانتظار. يمكن بعد ذلك استدعاء طريقة http2stream.sendTrailers() لإرسال رؤوس متتبعة إلى النظير.

عندما يتم تعيين options.waitForTrailers، لن يغلق Http2Stream تلقائيًا عند إرسال إطار DATA الأخير. يجب على رمز المستخدم استدعاء http2stream.sendTrailers() أو http2stream.close() لإغلاق Http2Stream.

عندما يتم تعيين options.signal مع AbortSignal ثم يتم استدعاء abort على AbortController المقابل، سيصدر الطلب حدث 'error' مع خطأ AbortError.

لا يتم تحديد رؤوس :method و :path الوهمية داخل headers، فهي افتراضياً على التوالي:

• :method = 'GET'
• :path = /

صنف: Http2Stream

مضاف في: v8.4.0

• يمتد: <stream.Duplex>

يمثل كل مثيل من صنف Http2Stream دفق اتصالات ثنائي الاتجاه HTTP/2 عبر مثيل Http2Session. قد يكون لأي Http2Session واحد ما يصل إلى 2-1 مثيل من Http2Stream طوال فترة حياته.

لن يقوم كود المستخدم بإنشاء مثيلات Http2Stream مباشرة. بل يتم إنشاؤها وإدارتها وتوفيرها لكود المستخدم من خلال مثيل Http2Session. على الخادم، يتم إنشاء مثيلات Http2Stream إما استجابةً لطلب HTTP وارد (ويتم تسليمه إلى كود المستخدم عبر حدث 'stream')، أو استجابةً لإجراء مكالمة إلى طريقة http2stream.pushStream(). على العميل، يتم إنشاء مثيلات Http2Stream وإعادتها عندما يتم استدعاء طريقة http2session.request()، أو استجابةً لحدث 'push' وارد.

يُعد صنف Http2Stream أساسًا لصنفي ServerHttp2Stream و ClientHttp2Stream، حيث يُستخدم كل منهما على وجه التحديد من قبل جانب الخادم أو العميل، على التوالي.

جميع مثيلات Http2Stream هي دفقات Duplex. يتم استخدام الجانب Writable من Duplex لإرسال البيانات إلى النظير المتصل، بينما يتم استخدام الجانب Readable لاستقبال البيانات التي يرسلها النظير المتصل.

ترميز الأحرف النصية الافتراضي لـ Http2Stream هو UTF-8. عند استخدام Http2Stream لإرسال نص، استخدم رأس 'content-type' لتعيين ترميز الأحرف.

stream.respond({
  'content-type': 'text/html; charset=utf-8',
  ':status': 200,
})

دورة حياة Http2Stream

الإنشاء

على جانب الخادم، يتم إنشاء مثيلات ServerHttp2Stream عندما:

• يتم استلام إطار HTTP/2 HEADERS جديد برقم دفق غير مستخدم سابقًا؛
• يتم استدعاء طريقة http2stream.pushStream().

على جانب العميل، يتم إنشاء مثيلات ClientHttp2Stream عند استدعاء طريقة http2session.request().

على العميل، قد لا يكون مثيل Http2Stream الذي تم إرجاعه بواسطة http2session.request() جاهزًا للاستخدام على الفور إذا لم يتم إنشاء Http2Session الرئيسي بالكامل بعد. في مثل هذه الحالات، سيتم تخزين العمليات التي يتم استدعاؤها على Http2Stream مؤقتًا حتى يتم إصدار حدث 'ready'. يجب أن يتعامل كود المستخدم نادرًا، إن لم يكن أبدًا، مع حدث 'ready' مباشرة. يمكن تحديد حالة جاهزية Http2Stream من خلال التحقق من قيمة http2stream.id. إذا كانت القيمة undefined، فإن الدفق غير جاهز للاستخدام بعد.

الإلغاء

يتم إلغاء جميع مثيلات Http2Stream إما عندما:

• يتم استلام إطار RST_STREAM للتيار من قبل النظير المتصل، و(للتيارات العميل فقط) تم قراءة البيانات المعلقة.
• يتم استدعاء طريقة http2stream.close()، و(للتيارات العميل فقط) تم قراءة البيانات المعلقة.
• يتم استدعاء الطريقتين http2stream.destroy() أو http2session.destroy().

عندما يتم إلغاء مثيل Http2Stream، سيتم إجراء محاولة لإرسال إطار RST_STREAM إلى النظير المتصل.

عندما يتم إلغاء مثيل Http2Stream، سيتم إصدار حدث 'close'. ولأن Http2Stream هو مثيل لـ stream.Duplex، سيتم أيضًا إصدار حدث 'end' إذا كانت بيانات التيار تتدفق حاليًا. قد يتم أيضًا إصدار حدث 'error' إذا تم استدعاء http2stream.destroy() مع تمرير Error كحجة أولى.

بعد إلغاء Http2Stream، ستكون خاصية http2stream.destroyed هي true وستحدد خاصية http2stream.rstCode رمز خطأ RST_STREAM. لم يعد من الممكن استخدام مثيل Http2Stream مرة أخرى بمجرد إلغائه.

الحدث: 'aborted'

مضاف في: v8.4.0

يتم إصدار حدث 'aborted' كلما تم إلغاء مثيل Http2Stream بشكل غير طبيعي في منتصف الاتصال. لا يتوقع مستمعه أي حجج.

سيتم إصدار حدث 'aborted' فقط إذا لم يتم إنهاء الجانب القابل للكتابة من Http2Stream.

الحدث: 'close'

مضاف في: v8.4.0

يتم إصدار حدث 'close' عند إلغاء Http2Stream. بمجرد إصدار هذا الحدث، لم يعد من الممكن استخدام مثيل Http2Stream.

يمكن استرداد رمز خطأ HTTP/2 المستخدم عند إغلاق التيار باستخدام خاصية http2stream.rstCode. إذا كانت الكود أي قيمة بخلاف NGHTTP2_NO_ERROR (0)، فسيكون حدث 'error' قد تم إصداره أيضًا.

الحدث: 'error'

مضاف في: v8.4.0

• error <Error>

يتم إصدار حدث 'error' عندما يحدث خطأ أثناء معالجة Http2Stream.

حدث: 'frameError'

مضاف في: v8.4.0

• type <عدد صحيح> نوع الإطار.
• code <عدد صحيح> رمز الخطأ.
• id <عدد صحيح> معرف الدفق (أو 0 إذا لم يكن الإطار مرتبطًا بدفق).

يتم إصدار حدث 'frameError' عندما يحدث خطأ أثناء محاولة إرسال إطار. عند استدعائه، ستتلقى دالة المُعالِج وسيطة عدد صحيح تحدد نوع الإطار، ووسيط عدد صحيح يحدد رمز الخطأ. سيتم تدمير مثيل Http2Stream مباشرة بعد إصدار حدث 'frameError'.

حدث: 'ready'

مضاف في: v8.4.0

يتم إصدار حدث 'ready' عندما يتم فتح Http2Stream، ويتم تعيين معرف له، ويمكن استخدامه. لا يتوقع المُستمع أي وسيطات.

حدث: 'timeout'

مضاف في: v8.4.0

يتم إصدار حدث 'timeout' بعد عدم استلام أي نشاط لهذا Http2Stream خلال عدد ميلي ثانية تم تعيينها باستخدام http2stream.setTimeout(). لا يتوقع مُستمعه أي وسيطات.

حدث: 'trailers'

مضاف في: v8.4.0

• headers <كائن عناوين HTTP/2> كائن يصف العناوين
• flags <رقم> الأعلام الرقمية المرتبطة

يتم إصدار حدث 'trailers' عند استلام كتلة من العناوين المرتبطة بحقول العناوين النهائية. يتم تمرير مُستمع المُنعكس كائن عناوين HTTP/2 والأعلام المرتبطة بالعناوين.

قد لا يتم إصدار هذا الحدث إذا تم استدعاء http2stream.end() قبل استلام العناوين النهائية ولم يتم قراءة البيانات الواردة أو الاستماع إليها.

stream.on('trailers', (headers, flags) => {
  console.log(headers)
})

الحدث: 'wantTrailers'

مضاف في: v10.0.0

يتم إصدار حدث 'wantTrailers' عندما يكون Http2Stream قد قام بوضع إطار DATA النهائي في قائمة الانتظار لإرساله على إطار ويكون Http2Stream جاهزًا لإرسال رؤوس مُتَراجِعة. عند بدء طلب أو استجابة، يجب تعيين خيار waitForTrailers ليتم إصدار هذا الحدث.

http2stream.aborted

مضاف في: v8.4.0

• <boolean>

يتم تعيينه إلى true إذا تم إلغاء مثيل Http2Stream بشكل غير طبيعي. عند تعيينه، سيتم إصدار حدث 'aborted'.

http2stream.bufferSize

مضاف في: v11.2.0، v10.16.0

• <number>

تُظهر هذه الخاصية عدد الأحرف المُخزّنة مؤقتًا حاليًا ليتم كتابتها. راجع net.Socket.bufferSize للحصول على التفاصيل.

http2stream.close(code[, callback])

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير مُستدعى غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.4.0	مضاف في: v8.4.0

• code <number> عدد صحيح بدون إشارة 32 بت يُحدد رمز الخطأ. الافتراضي: http2.constants.NGHTTP2_NO_ERROR (0x00).
• callback <Function> دالة اختيارية مسجلة للاستماع إلى حدث 'close'.

يُغلق مثيل Http2Stream عن طريق إرسال إطار RST_STREAM إلى نظير HTTP/2 المُتصل.

http2stream.closed

مضاف في: v9.4.0

• <boolean>

يتم تعيينه إلى true إذا تم إغلاق مثيل Http2Stream.

http2stream.destroyed

مضاف في: v8.4.0

• <boolean>

يتم تعيينه إلى true إذا تم تدمير مثيل Http2Stream ولم يعد صالحًا للاستخدام.

http2stream.endAfterHeaders

مضاف في: v10.11.0

• <boolean>

تعيين على true إذا تم تعيين علم END_STREAM في إطار طلب أو استجابة HEADERS المستلم، مما يشير إلى أنه لا ينبغي استلام أي بيانات إضافية وسيتم إغلاق الجانب القابل للقراءة من Http2Stream.

http2stream.id

مضاف في: v8.4.0

• <number> | <undefined>

معرف الدفق العددي لمثيل Http2Stream هذا. معين على undefined إذا لم يتم تعيين معرف الدفق بعد.

http2stream.pending

مضاف في: v9.4.0

• <boolean>

معين على true إذا لم يتم تعيين معرف دفق رقمي بعد لمثيل Http2Stream.

http2stream.priority(options)

مضاف في: v8.4.0

• options <Object>
  • exclusive <boolean> عندما يكون true و parent يحدد دفقًا رئيسيًا، يصبح هذا الدفق هو التبعية المباشرة الوحيدة للوالد، مع جعل جميع التبعيات الأخرى الموجودة تابعة لهذا الدفق. افتراضيًا: false.
  • parent <number> يحدد المعرف العددي لدفق يعتمد عليه هذا الدفق.
  • weight <number> يحدد التبعية النسبية لدفق فيما يتعلق بالدفقات الأخرى التي لها نفس parent. القيمة هي رقم بين 1 و 256 (ضمنيًا).
  • silent <boolean> عندما يكون true، يغيّر الأولوية محليًا دون إرسال إطار PRIORITY إلى النظير المتصل.

يحدث الأولوية لمثيل Http2Stream هذا.

http2stream.rstCode

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

• <number>

تم تعيينه إلى رمز الخطأ RST_STREAM رمز الخطأ المُبلغ عنه عند تدمير Http2Stream بعد تلقي إطار RST_STREAM من النظير المُتصل، أو استدعاء http2stream.close()، أو http2stream.destroy(). سيكون undefined إذا لم يتم إغلاق Http2Stream.

http2stream.sentHeaders

تم الإضافة في: v9.5.0

• <HTTP/2 Headers Object>

كائن يحتوي على رؤوس الخرج المُرسلة لهذا Http2Stream.

http2stream.sentInfoHeaders

تم الإضافة في: v9.5.0

• <HTTP/2 Headers Object[]>

مصفوفة من الكائنات التي تحتوي على رؤوس المعلومات (الإضافية) المُرسلة لهذا Http2Stream.

http2stream.sentTrailers

تم الإضافة في: v9.5.0

• <HTTP/2 Headers Object>

كائن يحتوي على المُقطورات الصادرة المُرسلة لهذا HttpStream.

http2stream.session

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

• <Http2Session>

مرجع إلى مثيل Http2Session الذي يمتلك هذا Http2Stream. ستكون القيمة undefined بعد تدمير مثيل Http2Stream.

http2stream.setTimeout(msecs, callback)

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُنعطف غير صالح إلى وسيطة callback الآن إلى إلقاء ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.4.0	تم الإضافة في: v8.4.0

• msecs <number>
• callback <Function>

ESM

import { connect, constants } from 'node:http2'
const client = connect('http://example.org:8000')
const { NGHTTP2_CANCEL } = constants
const req = client.request({ ':path': '/' })

// إلغاء الدفق إذا لم يكن هناك نشاط بعد 5 ثوانٍ
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

CJS

const http2 = require('node:http2')
const client = http2.connect('http://example.org:8000')
const { NGHTTP2_CANCEL } = http2.constants
const req = client.request({ ':path': '/' })

// إلغاء الدفق إذا لم يكن هناك نشاط بعد 5 ثوانٍ
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL))

http2stream.state

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

يوفر معلومات متنوعة حول الحالة الحالية لـ Http2Stream.

• <Object>
  • localWindowSize <number> عدد البايتات التي يمكن للنظير المتصل إرسالها لهذا Http2Stream دون استقبال WINDOW_UPDATE.
  • state <number> علم يشير إلى الحالة الحالية منخفضة المستوى لـ Http2Stream كما هو محدد بواسطة nghttp2.
  • localClose <number> 1 إذا تم إغلاق هذا Http2Stream محليًا.
  • remoteClose <number> 1 إذا تم إغلاق هذا Http2Stream عن بُعد.
  • sumDependencyWeight <number> مجموع وزن جميع مثيلات Http2Stream التي تعتمد على هذا Http2Stream كما هو محدد باستخدام إطارات PRIORITY.
  • weight <number> وزن أولوية هذا Http2Stream.

حالة حالية لهذا Http2Stream.

http2stream.sendTrailers(headers)

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

• headers <HTTP/2 Headers Object>

يرسل إطار HEADERS متتالي إلى النظير HTTP/2 المتصل. ستؤدي هذه الطريقة إلى إغلاق Http2Stream على الفور ويجب استدعاءها فقط بعد إصدار حدث 'wantTrailers'. عند إرسال طلب أو إرسال استجابة، يجب تعيين خيار options.waitForTrailers من أجل إبقاء Http2Stream مفتوحًا بعد الإطار DATA الأخير بحيث يمكن إرسال بيانات الإضافات.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respond(undefined, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' })
  })
  stream.end('Hello World')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respond(undefined, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' })
  })
  stream.end('Hello World')
})

يمنع مواصفة HTTP/1 بيانات الإضافات من احتواء حقول رأس HTTP/2 الوهمية (مثل ':method', ':path', إلخ).

الصنف: ClientHttp2Stream

مضاف في: v8.4.0

• يمتد من <Http2Stream>

يُعدُّ صنف ClientHttp2Stream امتدادًا لـ Http2Stream ويُستخدم حصريًا على عملاء HTTP/2. توفر مثيلات Http2Stream على العميل أحداثًا مثل 'response' و 'push' ذات صلة بالعميل فقط.

الحدث: 'continue'

مضاف في: v8.5.0

يُصدر عندما يرسل الخادم حالة 100 Continue، وعادةً ما يكون ذلك لأن الطلب احتوى على Expect: 100-continue. هذه تعليمات بأن على العميل إرسال جسم الطلب.

الحدث: 'headers'

مضاف في: v8.4.0

• headers <كائن رؤوس HTTP/2>
• flags <عدد>

يُصدر الحدث 'headers' عندما يتم استقبال كتلة إضافية من الرؤوس لدفق، مثل عندما يتم استقبال كتلة من رؤوس المعلومات 1xx. يتم تمرير مُستدعي دالة المُنصِت إلى كائن رؤوس HTTP/2 وعلامات مرتبطة بالرؤوس.

stream.on('headers', (headers, flags) => {
  console.log(headers)
})

الحدث: 'push'

مضاف في: v8.4.0

• headers <كائن رؤوس HTTP/2>
• flags <عدد>

يُصدر الحدث 'push' عندما يتم استقبال رؤوس الاستجابة لدفق دفع الخادم. يتم تمرير مُستدعي دالة المُنصِت إلى كائن رؤوس HTTP/2 وعلامات مرتبطة بالرؤوس.

stream.on('push', (headers, flags) => {
  console.log(headers)
})

الحدث: 'response'

مضاف في: v8.4.0

• headers <كائن رؤوس HTTP/2>
• flags <عدد>

يُصدر الحدث 'response' عندما يتم استقبال إطار HEADERS للاستجابة لهذا الدفق من خادم HTTP/2 المُتصل. يتم استدعاء المُنصِت مع وسيطين: كائن يحتوي على كائن رؤوس HTTP/2 المُستقبَل، وعلامات مرتبطة بالرؤوس.

ESM

import { connect } from 'node:http2'
const client = connect('https://localhost')
const req = client.request({ ':path': '/' })
req.on('response', (headers, flags) => {
  console.log(headers[':status'])
})

CJS

const http2 = require('node:http2')
const client = http2.connect('https://localhost')
const req = client.request({ ':path': '/' })
req.on('response', (headers, flags) => {
  console.log(headers[':status'])
})

صنف: ServerHttp2Stream

مضاف في: v8.4.0

• يمتد: <Http2Stream>

صنف ServerHttp2Stream هو امتداد لـ Http2Stream ويستخدم حصريًا على خوادم HTTP/2. توفر مثيلات Http2Stream على الخادم طرقًا إضافية مثل http2stream.pushStream() و http2stream.respond() ذات صلة فقط بالخادم.

http2stream.additionalHeaders(headers)

مضاف في: v8.4.0

• headers <كائن رؤوس HTTP/2>

يرسل إطار HEADERS إعلاميًا إضافيًا إلى نظير HTTP/2 المتصل.

http2stream.headersSent

مضاف في: v8.4.0

• <boolean>

true إذا تم إرسال الرؤوس، false بخلاف ذلك (قراءة فقط).

http2stream.pushAllowed

مضاف في: v8.4.0

• <boolean>

خاصية للقراءة فقط مرتبطة بعلم SETTINGS_ENABLE_PUSH لإطار SETTINGS الأخير للعميل البعيد. ستكون true إذا قبل النظير البعيد تدفقات الدفع، false بخلاف ذلك. الإعدادات هي نفسها لكل Http2Stream في نفس Http2Session.

http2stream.pushStream(headers[, options], callback)

[السجل]

الإصدار	التغييرات
v18.0.0	تمرير دالة استدعاء غير صالحة إلى وسيطة callback يطرح الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.4.0	مضاف في: v8.4.0

• headers <كائن رؤوس HTTP/2>

• options <Object>

  • exclusive <boolean> عندما تكون true و parent تحدد تدفقًا رئيسيًا، يصبح التدفق المُنشأ التبعية المباشرة الوحيدة للوالد، مع جعل جميع التبعيات الأخرى الموجودة تابعة للتدفق المُنشأ حديثًا. الافتراضي: false.
  • parent <number> يحدد المُعرّف العددي للتدفق الذي يعتمد عليه التدفق المُنشأ حديثًا.

• callback <Function> دالة الاستدعاء التي يتم استدعاؤها بمجرد بدء تدفق الدفع.

  • err <Error>
  • pushStream <ServerHttp2Stream> كائن pushStream المُرجع.
  • headers <كائن رؤوس HTTP/2> كائن الرؤوس الذي تم بدء pushStream به.

يبدأ تدفق دفع. يتم استدعاء دالة الاستدعاء مع مثيل Http2Stream الجديد المُنشأ لتدفق الدفع المُمرر كوسيط ثانٍ، أو خطأ مُمرر كوسيط أول.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 })
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err
    pushStream.respond({ ':status': 200 })
    pushStream.end('some pushed data')
  })
  stream.end('some data')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 })
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err
    pushStream.respond({ ':status': 200 })
    pushStream.end('some pushed data')
  })
  stream.end('some data')
})

لا يُسمح بتعيين وزن تدفق الدفع في إطار HEADERS. مرّر قيمة weight إلى http2stream.priority مع تعيين خيار silent إلى true لتمكين موازنة عرض النطاق الترددي من جانب الخادم بين التدفقات المتزامنة.

لا يُسمح باستدعاء http2stream.pushStream() من داخل تدفق مدفوع وسوف يطرح خطأ.

http2stream.respond([headers[, options]])

[History]

الإصدار	التغييرات
v14.5.0, v12.19.0	السماح بتعيين رؤوس التاريخ صراحةً.
v8.4.0	تمت الإضافة في: v8.4.0

• headers <كائن رؤوس HTTP/2>
• options <كائن>
  • endStream <قيمة منطقية> عيّن على true للإشارة إلى أن الاستجابة لن تتضمن بيانات حمولة.
  • waitForTrailers <قيمة منطقية> عندما تكون true، سيصدر Http2Stream حدث 'wantTrailers' بعد إرسال إطار DATA الأخير.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 })
  stream.end('some data')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 })
  stream.end('some data')
})

يبدأ استجابة. عندما يتم تعيين خيار options.waitForTrailers، سيتم إصدار حدث 'wantTrailers' مباشرة بعد وضع آخر جزء من بيانات الحمولة المراد إرسالها في قائمة الانتظار. يمكن بعد ذلك استخدام طريقة http2stream.sendTrailers() لإرسال حقول الرؤوس المتتبعة إلى النظير.

عندما يتم تعيين options.waitForTrailers، لن يغلق Http2Stream تلقائيًا عند نقل إطار DATA النهائي. يجب أن يستدعي رمز المستخدم إما http2stream.sendTrailers() أو http2stream.close() لإغلاق Http2Stream.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })
  stream.end('some data')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })
  stream.end('some data')
})

http2stream.respondWithFD(fd[, headers[, options]])

[History]

الإصدار	التغييرات
v14.5.0, v12.19.0	السماح بتعيين عناوين التاريخ صراحةً.
v12.12.0	أصبح خيار fd الآن يمكن أن يكون FileHandle.
v10.0.0	أي مُوصِّف ملف قابل للقراءة، ليس بالضرورة لملف عادي، مدعوم الآن.
v8.4.0	تمت الإضافة في: v8.4.0

• fd <number> | <FileHandle> مُوصِّف ملف قابل للقراءة.
• headers <HTTP/2 Headers Object>
• options <Object>
  • statCheck <Function>
  • waitForTrailers <boolean> عندما تكون true، سيُصدر Http2Stream حدث 'wantTrailers' بعد إرسال الإطار الأخير DATA.
  • offset <number> موضع الإزاحة الذي يبدأ عنده القراءة.
  • length <number> مقدار البيانات من fd المراد إرسالها.

يبدأ استجابة تُقرأ بياناتها من مُوصِّف الملف المُعطى. لا يتم إجراء أي تحقق من صحة مُوصِّف الملف المُعطى. إذا حدث خطأ أثناء محاولة قراءة البيانات باستخدام مُوصِّف الملف، فسيتم إغلاق Http2Stream باستخدام إطار RST_STREAM باستخدام رمز INTERNAL_ERROR القياسي.

عند استخدامه، سيتم إغلاق واجهة Duplex الخاصة بكائن Http2Stream تلقائيًا.

ESM

import { createServer } from 'node:http2'
import { openSync, fstatSync, closeSync } from 'node:fs'

const server = createServer()
server.on('stream', stream => {
  const fd = openSync('/some/file', 'r')

  const stat = fstatSync(fd)
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  }
  stream.respondWithFD(fd, headers)
  stream.on('close', () => closeSync(fd))
})

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const server = http2.createServer()
server.on('stream', stream => {
  const fd = fs.openSync('/some/file', 'r')

  const stat = fs.fstatSync(fd)
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  }
  stream.respondWithFD(fd, headers)
  stream.on('close', () => fs.closeSync(fd))
})

يمكن تحديد دالة options.statCheck الاختيارية لمنح رمز المستخدم فرصة لتعيين عناوين محتوى إضافية بناءً على تفاصيل fs.Stat الخاصة بـ fd المُعطى. إذا تم توفير دالة statCheck، فستقوم طريقة http2stream.respondWithFD() بإجراء مكالمة fs.fstat() لجمع التفاصيل حول مُوصِّف الملف المُقدّم.

يمكن استخدام خياري offset و length للحد من الاستجابة إلى مجموعة فرعية محددة من النطاق. يمكن استخدام هذا، على سبيل المثال، لدعم طلبات نطاق HTTP.

لا يتم إغلاق مُوصِّف الملف أو FileHandle عند إغلاق الدفق، لذلك يجب إغلاقه يدويًا بمجرد عدم الحاجة إليه. لا يُدعم استخدام مُوصِّف الملف نفسه بالتزامن لعدة دفقات وقد يؤدي ذلك إلى فقدان البيانات. يُدعم إعادة استخدام مُوصِّف ملف بعد انتهاء الدفق.

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

عندما يتم تعيين options.waitForTrailers، لن يغلق Http2Stream تلقائيًا عند إرسال إطار DATA الأخير. يجب على رمز المستخدم اتصال إما http2stream.sendTrailers() أو http2stream.close() لإغلاق Http2Stream.

ESM

import { createServer } from 'node:http2'
import { openSync, fstatSync, closeSync } from 'node:fs'

const server = createServer()
server.on('stream', stream => {
  const fd = openSync('/some/file', 'r')

  const stat = fstatSync(fd)
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  }
  stream.respondWithFD(fd, headers, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })

  stream.on('close', () => closeSync(fd))
})

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const server = http2.createServer()
server.on('stream', stream => {
  const fd = fs.openSync('/some/file', 'r')

  const stat = fs.fstatSync(fd)
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  }
  stream.respondWithFD(fd, headers, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })

  stream.on('close', () => fs.closeSync(fd))
})

http2stream.respondWithFile(path[, headers[, options]])

[History]

الإصدار	التغييرات
v14.5.0, v12.19.0	السماح بتعيين رؤوس التاريخ صراحةً.
v10.0.0	الآن، يتم دعم أي ملف قابل للقراءة، وليس بالضرورة ملفًا عاديًا.
v8.4.0	تمت الإضافة في: v8.4.0

• path <string> | <Buffer> | <URL>
• headers <HTTP/2 Headers Object>
• options <Object>
  • statCheck <Function>
  • onError <Function> دالة الاستدعاء التي يتم استدعاؤها في حالة حدوث خطأ قبل الإرسال.
  • waitForTrailers <boolean> عندما تكون true، سيصدر Http2Stream حدث 'wantTrailers' بعد إرسال الإطار النهائي DATA.
  • offset <number> موضع الإزاحة الذي يبدأ منه القراءة.
  • length <number> كمية البيانات من fd المراد إرسالها.

إرسال ملف عادي كاستجابة. يجب أن يحدد path ملفًا عاديًا، وإلا سيتم إصدار حدث 'error' على كائن Http2Stream.

عند الاستخدام، سيتم إغلاق واجهة Duplex لكائن Http2Stream تلقائيًا.

يمكن تحديد دالة options.statCheck الاختيارية لمنح رمز المستخدم فرصة لتعيين رؤوس محتوى إضافية بناءً على تفاصيل fs.Stat للملف المعطى:

إذا حدث خطأ أثناء محاولة قراءة بيانات الملف، فسيتم إغلاق Http2Stream باستخدام إطار RST_STREAM باستخدام رمز INTERNAL_ERROR القياسي. إذا تم تعريف دالة الاستدعاء onError، فسيتم استدعاؤها. وإلا، سيتم تدمير التدفق.

مثال باستخدام مسار ملف:

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString()
  }

  function onError(err) {
    // يمكن أن يطرح stream.respond() استثناءً إذا تم تدمير التدفق بواسطة
    // الجانب الآخر.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // إجراء معالجة الخطأ الفعلية.
      console.error(err)
    }
    stream.end()
  }

  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck, onError })
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString()
  }

  function onError(err) {
    // يمكن أن يطرح stream.respond() استثناءً إذا تم تدمير التدفق بواسطة
    // الجانب الآخر.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 })
      } else {
        stream.respond({ ':status': 500 })
      }
    } catch (err) {
      // إجراء معالجة الخطأ الفعلية.
      console.error(err)
    }
    stream.end()
  }

  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck, onError })
})

يمكن أيضًا استخدام دالة options.statCheck لإلغاء عملية الإرسال عن طريق إرجاع false. على سبيل المثال، قد يتحقق طلب مشروط من نتائج stat لتحديد ما إذا تم تعديل الملف لإرجاع استجابة 304 مناسبة:

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    // التحقق من stat هنا...
    stream.respond({ ':status': 304 })
    return false // إلغاء عملية الإرسال
  }
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck })
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  function statCheck(stat, headers) {
    // التحقق من stat هنا...
    stream.respond({ ':status': 304 })
    return false // إلغاء عملية الإرسال
  }
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { statCheck })
})

سيتم تعيين حقل الرأس content-length تلقائيًا.

يمكن استخدام خيارات offset و length للحد من الاستجابة إلى مجموعة فرعية محددة من النطاق. يمكن استخدام هذا، على سبيل المثال، لدعم طلبات نطاق HTTP.

يمكن أيضًا استخدام دالة options.onError لمعالجة جميع الأخطاء التي قد تحدث قبل بدء تسليم الملف. السلوك الافتراضي هو تدمير التدفق.

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

عندما يتم تعيين options.waitForTrailers، لن يغلق Http2Stream تلقائيًا عند إرسال الإطار النهائي DATA. يجب أن يستدعي رمز المستخدم إما http2stream.sendTrailers() أو http2stream.close() لإغلاق Http2Stream.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', stream => {
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', stream => {
  stream.respondWithFile('/some/file', { 'content-type': 'text/plain; charset=utf-8' }, { waitForTrailers: true })
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' })
  })
})

الصنف: Http2Server

مضاف في: v8.4.0

• يمتد: <net.Server>

يتم إنشاء مثيلات Http2Server باستخدام دالة http2.createServer(). لا يتم تصدير فئة Http2Server مباشرةً بواسطة وحدة node:http2.

الحدث: 'checkContinue'

مضاف في: v8.5.0

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

إذا تم تسجيل مُستمع 'request' أو تم تزويد http2.createServer() بدالة استدعاء، يتم إصدار حدث 'checkContinue' في كل مرة يتم فيها استقبال طلب يحتوي على HTTP Expect: 100-continue. إذا لم يتم الاستماع لهذا الحدث، فسوف يستجيب الخادم تلقائيًا بوضع 100 Continue كما ينبغي.

يتضمن التعامل مع هذا الحدث الاتصال بـ response.writeContinue() إذا كان يجب على العميل متابعة إرسال جسم الطلب، أو توليد استجابة HTTP مناسبة (مثل 400 Bad Request) إذا كان يجب على العميل عدم متابعة إرسال جسم الطلب.

عندما يتم إصدار هذا الحدث ومعالجته، فلن يتم إصدار حدث 'request'.

الحدث: 'connection'

مضاف في: v8.4.0

• socket <stream.Duplex>

يتم إصدار هذا الحدث عندما يتم إنشاء دفق TCP جديد. عادةً ما يكون socket كائنًا من نوع net.Socket. وعادةً ما لا يرغب المستخدمون في الوصول إلى هذا الحدث.

يمكن أيضًا إصدار هذا الحدث صراحةً بواسطة المستخدمين لحقن اتصالات في خادم HTTP. في هذه الحالة، يمكن تمرير أي دفق Duplex.

الحدث: 'request'

مضاف في: v8.4.0

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

يتم إصداره في كل مرة يكون هناك طلب. قد يكون هناك طلبات متعددة لكل جلسة. راجع واجهة برمجة التطبيقات المتوافقة.

حدث: 'session'

مضاف في: v8.4.0

• session <ServerHttp2Session>

يتم بث حدث 'session' عند إنشاء مُثيل جديد من Http2Session بواسطة Http2Server.

حدث: 'sessionError'

مضاف في: v8.4.0

• error <Error>
• session <ServerHttp2Session>

يتم بث حدث 'sessionError' عندما يتم بث حدث 'error' بواسطة كائن Http2Session المرتبط بـ Http2Server.

حدث: 'stream'

مضاف في: v8.4.0

• stream <Http2Stream> مرجع للتيار
• headers <كائن عناوين HTTP/2> كائن يصف العناوين
• flags <عدد> الأعلام العددية المرتبطة
• rawHeaders <مصفوفة> مصفوفة تحتوي على أسماء العناوين الخام متبوعة بقيمها الخاصة.

يتم بث حدث 'stream' عندما يتم بث حدث 'stream' بواسطة كائن Http2Session مرتبط بالخادم.

راجع أيضًا حدث Http2Session's 'stream'.

ESM

import { createServer, constants } from 'node:http2'
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = constants

const server = createServer()
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD]
  const path = headers[HTTP2_HEADER_PATH]
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

CJS

const http2 = require('node:http2')
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = http2.constants

const server = http2.createServer()
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD]
  const path = headers[HTTP2_HEADER_PATH]
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

الحدث: 'timeout'

[السجل]

الإصدار	التغييرات
v13.0.0	تغير وقت الانتظار الافتراضي من 120 ثانية إلى 0 (بدون وقت انتظار).
v8.4.0	تمت الإضافة في: v8.4.0

يتم إصدار حدث 'timeout' عندما لا يكون هناك نشاط على الخادم لعدد معين من الميلي ثانية تم تعيينها باستخدام http2server.setTimeout(). الافتراضي: 0 (بدون وقت انتظار)

server.close([callback])

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

• callback <Function>

يوقف الخادم من إنشاء جلسات جديدة. هذا لا يمنع إنشاء تدفقات طلبات جديدة بسبب الطبيعة المستمرة لجلسات HTTP/2. لإغلاق الخادم بشكل صحيح، اتصل بـ http2session.close() على جميع الجلسات النشطة.

إذا تم توفير callback، فلن يتم استدعائه حتى يتم إغلاق جميع الجلسات النشطة، على الرغم من أن الخادم قد توقف بالفعل عن السماح بجلسات جديدة. راجع net.Server.close() لمزيد من التفاصيل.

server[Symbol.asyncDispose]()

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

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

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

يدعو server.close() ويعيد وعدًا يتم الوفاء به عندما يتم إغلاق الخادم.

server.setTimeout([msecs][, callback])

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير دالة استدعاء غير صالحة إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v13.0.0	تغير وقت الانتظار الافتراضي من 120 ثانية إلى 0 (بدون وقت انتظار).
v8.4.0	تمت الإضافة في: v8.4.0

• msecs <number> الافتراضي: 0 (بدون وقت انتظار)
• callback <Function>
• الإرجاع: <Http2Server>

يستخدم لتعيين قيمة وقت الانتظار لطلبات خادم http2، ويحدد دالة استدعاء يتم استدعاؤها عندما لا يكون هناك نشاط على Http2Server بعد msecs ميلي ثانية.

يتم تسجيل دالة الاستدعاء المعطاة كمستمع على حدث 'timeout'.

في حالة عدم كون callback دالة، سيتم إرسال خطأ ERR_INVALID_ARG_TYPE جديد.

server.timeout

[السجل]

الإصدار	التغييرات
v13.0.0	تم تغيير مهلة الوقت الافتراضية من 120 ثانية إلى 0 (بدون مهلة).
v8.4.0	تمت الإضافة في: v8.4.0

• <رقم> مهلة بالميلي ثانية. الافتراضي: 0 (بدون مهلة)

عدد ميلي ثواني الخمول قبل افتراض انتهاء مهلة المقبس.

ستؤدي قيمة 0 إلى تعطيل سلوك مهلة الوقت على الاتصالات الواردة.

يتم إعداد منطق مهلة المقبس عند الاتصال، لذا فإن تغيير هذه القيمة يؤثر فقط على الاتصالات الجديدة بالخادم، وليس أي اتصالات موجودة.

server.updateSettings([settings])

تمت الإضافة في: v15.1.0، v14.17.0

• settings <كائن إعدادات HTTP/2>

يستخدم لتحديث الخادم باستخدام الإعدادات المقدمة.

يطرح ERR_HTTP2_INVALID_SETTING_VALUE لقيم settings غير صالحة.

يطرح ERR_INVALID_ARG_TYPE للحجة settings غير صالحة.

الصف: Http2SecureServer

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

• يمتد: <tls.Server>

يتم إنشاء مثيلات Http2SecureServer باستخدام دالة http2.createSecureServer(). لا يتم تصدير فئة Http2SecureServer مباشرة بواسطة وحدة node:http2.

الحدث: 'checkContinue'

تمت الإضافة في: v8.5.0

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

إذا تم تسجيل مُستمع 'request' أو تم تزويد http2.createSecureServer() بدالة استدعاء، فسيتم إصدار حدث 'checkContinue' في كل مرة يتم فيها استقبال طلب يحتوي على HTTP Expect: 100-continue. إذا لم يتم الاستماع إلى هذا الحدث، فسيتجاوب الخادم تلقائيًا بحالة 100 Continue حسب الاقتضاء.

يتضمن التعامل مع هذا الحدث الاتصال بـ response.writeContinue() إذا كان يجب على العميل المتابعة في إرسال جسم الطلب، أو إنشاء استجابة HTTP مناسبة (مثل 400 طلب خاطئ) إذا كان يجب على العميل عدم المتابعة في إرسال جسم الطلب.

عندما يتم إصدار هذا الحدث والتعامل معه، فلن يتم إصدار حدث 'request'.

الحدث: 'connection'

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

• socket <stream.Duplex>

يتم إصدار هذا الحدث عند إنشاء دفق TCP جديد، قبل بدء عملية مصافحة TLS. عادةً ما يكون socket كائنًا من نوع net.Socket. عادةً لا يرغب المستخدمون في الوصول إلى هذا الحدث.

يمكن أيضًا إصدار هذا الحدث صراحةً من قبل المستخدمين لحقن اتصالات في خادم HTTP. في هذه الحالة، يمكن تمرير أي دفق Duplex.

الحدث: 'request'

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

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

يتم إصداره في كل مرة يكون هناك طلب. قد يكون هناك طلبات متعددة لكل جلسة. راجع واجهة برمجة التطبيقات المتوافقة.

الحدث: 'session'

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

• session <ServerHttp2Session>

يتم إصدار حدث 'session' عند إنشاء Http2Session جديد بواسطة Http2SecureServer.

الحدث: 'sessionError'

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

• error <Error>
• session <ServerHttp2Session>

يتم إصدار حدث 'sessionError' عند إصدار حدث 'error' بواسطة كائن Http2Session المرتبط بـ Http2SecureServer.

الحدث: 'stream'

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

• stream <Http2Stream> مرجع للدفق
• headers <كائن رؤوس HTTP/2> كائن يصف الرؤوس
• flags <رقم> الأعلام العددية المرتبطة
• rawHeaders <مصفوفة> مصفوفة تحتوي على أسماء الرؤوس الخام متبوعة بقيمها الخاصة.

يتم إصدار حدث 'stream' عندما يتم إصدار حدث 'stream' بواسطة Http2Session المرتبط بالخادم.

راجع أيضًا حدث 'stream' لـ Http2Session.

ESM

import { createSecureServer, constants } from 'node:http2'
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = constants

const options = getOptionsSomehow()

const server = createSecureServer(options)
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD]
  const path = headers[HTTP2_HEADER_PATH]
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

CJS

const http2 = require('node:http2')
const { HTTP2_HEADER_METHOD, HTTP2_HEADER_PATH, HTTP2_HEADER_STATUS, HTTP2_HEADER_CONTENT_TYPE } = http2.constants

const options = getOptionsSomehow()

const server = http2.createSecureServer(options)
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD]
  const path = headers[HTTP2_HEADER_PATH]
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  })
  stream.write('hello ')
  stream.end('world')
})

حدث: 'timeout'

مضاف في: v8.4.0

يُصدر حدث 'timeout' عندما لا يكون هناك نشاط على الخادم لعدد معين من الميلي ثانية يتم تعيينه باستخدام http2secureServer.setTimeout(). الافتراضي: دقيقتان.

حدث: 'unknownProtocol'

[السجل]

الإصدار	التغييرات
v19.0.0	سيتم إصدار هذا الحدث فقط إذا لم ينقل العميل امتداد ALPN أثناء عملية مصافحة TLS.
v8.4.0	مضاف في: v8.4.0

• socket <stream.Duplex>

يُصدر حدث 'unknownProtocol' عندما يفشل العميل المُتصل في التفاوض على بروتوكول مسموح به (أي HTTP/2 أو HTTP/1.1). يتلقى مُعالِج الحدث المقبس للمعالجة. إذا لم يتم تسجيل أي مستمع لهذا الحدث، فسيتم إنهاء الاتصال. يمكن تحديد مهلة زمنية باستخدام خيار 'unknownProtocolTimeout' المُمرر إلى http2.createSecureServer().

في الإصدارات السابقة من Node.js، سيتم إصدار هذا الحدث إذا كانت قيمة allowHTTP1 هي false، وأثناء عملية مصافحة TLS، إما أن لا يرسل العميل امتداد ALPN أو يرسل امتداد ALPN لا يتضمن HTTP/2 (h2). تقوم الإصدارات الأحدث من Node.js بإصدار هذا الحدث فقط إذا كانت قيمة allowHTTP1 هي false ولم يرسل العميل امتداد ALPN. إذا أرسل العميل امتداد ALPN لا يتضمن HTTP/2 (أو HTTP/1.1 إذا كانت قيمة allowHTTP1 هي true)، فستفشل عملية مصافحة TLS ولن يتم إنشاء اتصال آمن.

راجع واجهة برمجة التطبيقات الخاصة بالتوافق.

server.close([callback])

مضاف في: v8.4.0

• callback <Function>

يوقف الخادم من إنشاء جلسات جديدة. هذا لا يمنع إنشاء تيارات طلبات جديدة نظرًا لطبيعة جلسات HTTP/2 الدائمة. لإغلاق الخادم بشكل صحيح، اتصل بـ http2session.close() على جميع الجلسات النشطة.

إذا تم توفير callback، فلن يتم استدعائه إلا بعد إغلاق جميع الجلسات النشطة، على الرغم من أن الخادم قد توقف بالفعل عن السماح بجلسات جديدة. راجع tls.Server.close() لمزيد من التفاصيل.

server.setTimeout([msecs][, callback])

[History]

الإصدار	التغييرات
v18.0.0	تمرير مُعامل استدعاء غير صالح إلى وسيطة callback يُلقي الآن خطأ ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.4.0	تمت الإضافة في: v8.4.0

• msecs <number> الافتراضي: 120000 (دقيقتان)
• callback <Function>
• القيمة المُرجعة: <Http2SecureServer>

تُستخدم لتعيين قيمة مهلة طلبات الخادم الآمن http2، وتعيين دالة مُعامل استدعاء يتم استدعاؤها عندما لا يكون هناك نشاط على Http2SecureServer بعد msecs ميلي ثانية.

يتم تسجيل مُعامل الاستدعاء المُعطى كمُستمع على حدث 'timeout'.

في حالة عدم كون callback دالة، فسيتم طرح خطأ ERR_INVALID_ARG_TYPE جديد.

server.timeout

[History]

الإصدار	التغييرات
v13.0.0	تغيرت مهلة الافتراضية من 120 ثانية إلى 0 (بدون مهلة).
v8.4.0	تمت الإضافة في: v8.4.0

• <number> مهلة بالميلي ثانية. الافتراضي: 0 (بدون مهلة)

عدد ميلي ثواني الخمول قبل افتراض أن المقبس قد انتهت مهلته.

ستؤدي قيمة 0 إلى تعطيل سلوك المهلة على الاتصالات الواردة.

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

server.updateSettings([settings])

تمت الإضافة في: v15.1.0، v14.17.0

• settings <HTTP/2 Settings Object>

تُستخدم لتحديث الخادم باستخدام الإعدادات المُقدمة.

يُلقي خطأ ERR_HTTP2_INVALID_SETTING_VALUE لقيم settings غير صالحة.

يُلقي خطأ ERR_INVALID_ARG_TYPE لوسيط settings غير صالح.

http2.createServer([options][, onRequestHandler])

[History]

الإصدار	التغييرات
v23.0.0	تمت إضافة streamResetBurst و streamResetRate.
v13.0.0	أصبح PADDING_STRATEGY_CALLBACK مكافئًا لتوفير PADDING_STRATEGY_ALIGNED وتم إزالة selectPadding.
v13.3.0، v12.16.0	تمت إضافة خيار maxSessionRejectedStreams مع افتراضية 100.
v13.3.0، v12.16.0	تمت إضافة خيار maxSessionInvalidFrames مع افتراضية 1000.
v12.4.0	يدعم مُعامل options الآن خيارات net.createServer().
v15.10.0، v14.16.0، v12.21.0، v10.24.0	تمت إضافة خيار unknownProtocolTimeout مع افتراضية 10000.
v14.4.0، v12.18.0، v10.21.0	تمت إضافة خيار maxSettings مع افتراضية 32.
v9.6.0	تمت إضافة خيار Http1IncomingMessage و Http1ServerResponse.
v8.9.3	تمت إضافة خيار maxOutstandingPings مع حد افتراضي 10.
v8.9.3	تمت إضافة خيار maxHeaderListPairs مع حد افتراضي 128 زوجًا من العناوين.
v8.4.0	تمت الإضافة في: v8.4.0

• options <Object>

  • maxDeflateDynamicTableSize <number> يُعيّن الحد الأقصى لحجم الجدول الديناميكي لضغط حقول الرأس. الافتراضي: 4Kib.

  • maxSettings <number> يُعيّن الحد الأقصى لعدد إدخالات الإعدادات لكل إطار SETTINGS. الحد الأدنى للقيمة المسموح بها هو 1. الافتراضي: 32.

  • maxSessionMemory<number> يُعيّن الحد الأقصى للذاكرة التي يُسمح لـ Http2Session باستخدامها. تُعبّر القيمة بمصطلحات عدد ميغابايت، على سبيل المثال، 1 يساوي 1 ميغابايت. الحد الأدنى للقيمة المسموح بها هو 1. هذا حد قائم على الرصيد، قد تتسبب Http2Streams الموجودة في تجاوز هذا الحد، لكن سيتم رفض مثيلات Http2Stream الجديدة بينما يتم تجاوز هذا الحد. يُحسب عدد جلسات Http2Stream الحالية، واستخدام الذاكرة الحالي لجدول ضغط الرأس، والبيانات الحالية المُصفّفة للإرسال، وإطارات PING و SETTINGS غير المُعترف بها كلها ضمن الحد الحالي. الافتراضي: 10.

  • maxHeaderListPairs <number> يُعيّن الحد الأقصى لعدد إدخالات الرأس. هذا مشابه لـ server.maxHeadersCount أو request.maxHeadersCount في وحدة node:http. الحد الأدنى للقيمة هو 4. الافتراضي: 128.

  • maxOutstandingPings <number> يُعيّن الحد الأقصى لعدد عمليات ping المعلقة غير المُعترف بها. الافتراضي: 10.

  • maxSendHeaderBlockLength <number> يُعيّن الحد الأقصى للحجم المسموح به لكتلة مُسلسلة مضغوطة من العناوين. ستؤدي محاولات إرسال عناوين تتجاوز هذا الحد إلى إصدار حدث 'frameError' وإغلاق تيار وإتلافه. في حين أن هذا يُعيّن الحد الأقصى للحجم المسموح به لكتلة العناوين بأكملها، فإن nghttp2 (مكتبة http2 الداخلية) لديها حد قدره 65536 لكل زوج قيمة/مفتاح مُفكك الضغط.

  • paddingStrategy <number> الإستراتيجية المُستخدمة لتحديد مقدار التعبئة المُراد استخدامها لإطارات HEADERS و DATA. الافتراضي: http2.constants.PADDING_STRATEGY_NONE. قد تكون القيمة إحدى القيم التالية:

  • http2.constants.PADDING_STRATEGY_NONE: لا يتم تطبيق أي تعبئة.

  • http2.constants.PADDING_STRATEGY_MAX: يتم تطبيق الحد الأقصى للتعبئة، الذي يحدده التنفيذ الداخلي.

  • http2.constants.PADDING_STRATEGY_ALIGNED: يحاول تطبيق ما يكفي من التعبئة لضمان أن يكون إجمالي طول الإطار، بما في ذلك رأس 9 بايت، مضاعفًا لـ 8. لكل إطار، هناك حد أقصى مسموح به لعدد بايت التعبئة والذي يحدده حالة التحكم في التدفق والإعدادات الحالية. إذا كان هذا الحد الأقصى أقل من الكمية المُحسوبة اللازمة لضمان المحاذاة، فسيتم استخدام الحد الأقصى ولن يكون إجمالي طول الإطار محاذيًا بالضرورة عند 8 بايت.

  • peerMaxConcurrentStreams <number> يُعيّن الحد الأقصى لعدد التيارات المتزامنة للنظير البعيد كما لو كان قد تم استلام إطار SETTINGS. سيتم تجاوز ذلك إذا عيّن النظير البعيد قيمته الخاصة لـ maxConcurrentStreams. الافتراضي: 100.

  • maxSessionInvalidFrames <integer> يُعيّن الحد الأقصى لعدد الإطارات غير الصالحة التي سيتم التسامح معها قبل إغلاق الجلسة. الافتراضي: 1000.

  • maxSessionRejectedStreams <integer> يُعيّن الحد الأقصى لعدد التيارات المُرفوضة عند إنشائها والتي سيتم التسامح معها قبل إغلاق الجلسة. يرتبط كل رفض بخطأ NGHTTP2_ENHANCE_YOUR_CALM الذي يجب أن يخبر النظير بعدم فتح المزيد من التيارات، وبالتالي يُعتبر الاستمرار في فتح التيارات علامة على سوء تصرف النظير. الافتراضي: 100.

  • settings <HTTP/2 Settings Object> الإعدادات الأولية لإرسالها إلى النظير البعيد عند الاتصال.

  • streamResetBurst <number> و streamResetRate <number> يُعيّن حدّ معدل إعادة تعيين التيار الوارد (إطار RST_STREAM). يجب تعيين كلا الإعدادين ليكون لهما أي تأثير، وافتراضهما 1000 و 33 على التوالي.

  • remoteCustomSettings <Array> يحدد مصفوفة قيم عدد صحيح أنواع الإعدادات، والتي يتم تضمينها في خاصية CustomSettings لـ remoteSettings المُستلمة. يُرجى مراجعة خاصية CustomSettings لكائن Http2Settings لمزيد من المعلومات حول أنواع الإعدادات المسموح بها.

  • Http1IncomingMessage <http.IncomingMessage> يُحدد فئة IncomingMessage المُستخدمة لنسخة HTTP/1 الاحتياطية. مفيد لمد فئة http.IncomingMessage الأصلية. الافتراضي: http.IncomingMessage.

  • Http1ServerResponse <http.ServerResponse> يُحدد فئة ServerResponse المُستخدمة لنسخة HTTP/1 الاحتياطية. مفيد لمد فئة http.ServerResponse الأصلية. الافتراضي: http.ServerResponse.

  • Http2ServerRequest <http2.Http2ServerRequest> يُحدد فئة Http2ServerRequest المُراد استخدامها. مفيد لمد فئة Http2ServerRequest الأصلية. الافتراضي: Http2ServerRequest.

  • Http2ServerResponse <http2.Http2ServerResponse> يُحدد فئة Http2ServerResponse المُراد استخدامها. مفيد لمد فئة Http2ServerResponse الأصلية. الافتراضي: Http2ServerResponse.

  • unknownProtocolTimeout <number> يُحدد مهلة بالميلي ثانية يجب أن ينتظرها الخادم عند إصدار 'unknownProtocol'. إذا لم يتم تدمير المقبس بحلول ذلك الوقت، فسيدمره الخادم. الافتراضي: 10000.

  • ...: يمكن توفير أي خيار net.createServer().

• onRequestHandler <Function> انظر واجهة برمجة التطبيقات للتوافق

• القيمة المُرجعة: <Http2Server>

يُعيد مثيلًا من net.Server يُنشئ ويدير مثيلات Http2Session.

بما أنه لا توجد متصفحات معروفة تدعم HTTP/2 غير مشفر، فإن استخدام http2.createSecureServer() ضروري عند التواصل مع عملاء المتصفح.

ESM

import { createServer } from 'node:http2'

// إنشاء خادم HTTP/2 غير مشفر.
// بما أنه لا توجد متصفحات معروفة تدعم
// HTTP/2 غير مشفر، فإن استخدام `createSecureServer()`
// ضروري عند التواصل مع عملاء المتصفح.
const server = createServer()

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8000)

CJS

const http2 = require('node:http2')

// إنشاء خادم HTTP/2 غير مشفر.
// بما أنه لا توجد متصفحات معروفة تدعم
// HTTP/2 غير مشفر، فإن استخدام `http2.createSecureServer()`
// ضروري عند التواصل مع عملاء المتصفح.
const server = http2.createServer()

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8000)

http2.createSecureServer(options[, onRequestHandler])

[السجل]

الإصدار	التغييرات
v13.0.0	أصبح PADDING_STRATEGY_CALLBACK مكافئًا لتوفير PADDING_STRATEGY_ALIGNED وتم إزالة selectPadding.
v13.3.0, v12.16.0	تمت إضافة خيار maxSessionRejectedStreams مع قيمة افتراضية 100.
v13.3.0, v12.16.0	تمت إضافة خيار maxSessionInvalidFrames مع قيمة افتراضية 1000.
v15.10.0, v14.16.0, v12.21.0, v10.24.0	تمت إضافة خيار unknownProtocolTimeout مع قيمة افتراضية 10000.
v14.4.0, v12.18.0, v10.21.0	تمت إضافة خيار maxSettings مع قيمة افتراضية 32.
v10.12.0	تمت إضافة خيار origins لإرسال إطار ORIGIN تلقائيًا عند بدء تشغيل Http2Session.
v8.9.3	تمت إضافة خيار maxOutstandingPings مع حد افتراضي 10.
v8.9.3	تمت إضافة خيار maxHeaderListPairs مع حد افتراضي 128 زوجًا من الرؤوس.
v8.4.0	تمت الإضافة في: v8.4.0

• options <Object>

  • allowHTTP1 <boolean> سيتم ترقية اتصالات العميل الواردة التي لا تدعم HTTP/2 إلى HTTP/1.x عند تعيينها على true. راجع حدث 'unknownProtocol'. راجع مفاوضات ALPN. الافتراضي: false.

  • maxDeflateDynamicTableSize <number> يحدد الحد الأقصى لحجم الجدول الديناميكي لضغط حقول الرأس. الافتراضي: 4Kib.

  • maxSettings <number> يحدد الحد الأقصى لعدد إدخالات الإعدادات لكل إطار SETTINGS. الحد الأدنى للقيمة المسموح بها هو 1. الافتراضي: 32.

  • maxSessionMemory<number> يحدد الحد الأقصى للذاكرة التي يُسمح لـ Http2Session باستخدامها. تُعبّر القيمة بوحدات ميغابايت، على سبيل المثال، 1 تساوي 1 ميغابايت. الحد الأدنى للقيمة المسموح بها هو 1. هذا حد قائم على الائتمان، قد تتسبب جلسات Http2Stream الموجودة في تجاوز هذا الحد، لكن سيتم رفض مثيلات Http2Stream الجديدة بينما يتجاوز هذا الحد. يتم احتساب عدد جلسات Http2Stream الحالية، واستخدام الذاكرة الحالي لجدول ضغط الرأس، والبيانات الحالية المُضافة للإرسال، وإطارات PING و SETTINGS غير المُعترف بها جميعها نحو الحد الحالي. الافتراضي: 10.

  • maxHeaderListPairs <number> يحدد الحد الأقصى لعدد إدخالات الرأس. يشبه هذا server.maxHeadersCount أو request.maxHeadersCount في وحدة node:http. الحد الأدنى للقيمة هو 4. الافتراضي: 128.

  • maxOutstandingPings <number> يحدد الحد الأقصى لعدد عمليات ping المعلقة غير المُعترف بها. الافتراضي: 10.

  • maxSendHeaderBlockLength <number> يحدد الحد الأقصى للحجم المسموح به لكتلة رؤوس مُسلسلة مضغوطة. ستؤدي محاولات إرسال رؤوس تتجاوز هذا الحد إلى إصدار حدث 'frameError' وإغلاق الدفق وتدميره.

  • paddingStrategy <number> الإستراتيجية المستخدمة لتحديد مقدار الحشو الذي يجب استخدامه لإطارات HEADERS و DATA. الافتراضي: http2.constants.PADDING_STRATEGY_NONE. قد تكون القيمة أحد ما يلي:

  • http2.constants.PADDING_STRATEGY_NONE: لا يتم تطبيق أي حشو.

  • http2.constants.PADDING_STRATEGY_MAX: يتم تطبيق الحد الأقصى لمقدار الحشو، الذي يحدده التنفيذ الداخلي.

  • http2.constants.PADDING_STRATEGY_ALIGNED: يحاول تطبيق ما يكفي من الحشو لضمان أن يكون إجمالي طول الإطار، بما في ذلك رأس 9 بايت، مضاعفًا لـ 8. لكل إطار، يوجد حد أقصى مسموح به لعدد بايت الحشو الذي يحدده حالة التحكم في التدفق والإعدادات الحالية. إذا كان هذا الحد الأقصى أقل من الكمية المحسوبة اللازمة لضمان المحاذاة، فسيتم استخدام الحد الأقصى ولا يكون إجمالي طول الإطار محاذيًا بالضرورة عند 8 بايت.

  • peerMaxConcurrentStreams <number> يحدد الحد الأقصى لعدد الدفقات المتزامنة للنظير البعيد كما لو تم استقبال إطار SETTINGS. سيتم تجاوزها إذا قام النظير البعيد بتعيين قيمته الخاصة لـ maxConcurrentStreams. الافتراضي: 100.

  • maxSessionInvalidFrames <integer> يحدد الحد الأقصى لعدد الإطارات غير الصالحة التي سيتم التسامح معها قبل إغلاق الجلسة. الافتراضي: 1000.

  • maxSessionRejectedStreams <integer> يحدد الحد الأقصى لعدد الدفقات المرفوضة عند الإنشاء والتي سيتم التسامح معها قبل إغلاق الجلسة. يرتبط كل رفض بخطأ NGHTTP2_ENHANCE_YOUR_CALM الذي يجب أن يخبر النظير بعدم فتح المزيد من الدفقات، وبالتالي يُعتبر الاستمرار في فتح الدفقات علامة على سوء تصرف النظير. الافتراضي: 100.

  • settings <كائن إعدادات HTTP/2> الإعدادات الأولية لإرسالها إلى النظير البعيد عند الاتصال.

  • remoteCustomSettings <Array> يحدد مُصفوفة قيم الأعداد الصحيحة أنواع الإعدادات، والتي يتم تضمينها في خاصية customSettings لـ remoteSettings المستلمة. يرجى مراجعة خاصية customSettings لكائن Http2Settings لمزيد من المعلومات حول أنواع الإعدادات المسموح بها.

  • ...: يمكن توفير أي خيارات tls.createServer(). بالنسبة للخوادم، غالبًا ما تكون خيارات الهوية (pfx أو key/cert) مطلوبة.

  • origins <string[]> مصفوفة من سلاسل الأصل لإرسالها داخل إطار ORIGIN مباشرة بعد إنشاء خادم Http2Session جديد.

  • unknownProtocolTimeout <number> يحدد مهلة بالميلي ثانية يجب أن ينتظرها الخادم عند إصدار حدث 'unknownProtocol'. إذا لم يتم تدمير المقبس بحلول ذلك الوقت، فسيدمره الخادم. الافتراضي: 10000.

• onRequestHandler <Function> راجع واجهة برمجة التطبيقات للتوافق

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

يرجع مثيلًا لـ tls.Server ينشئ ويدير مثيلات Http2Session.

ESM

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),
}

// إنشاء خادم HTTP/2 آمن
const server = createSecureServer(options)

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8443)

CJS

const http2 = require('node:http2')
const fs = require('node:fs')

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
}

// إنشاء خادم HTTP/2 آمن
const server = http2.createSecureServer(options)

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  })
  stream.end('<h1>Hello World</h1>')
})

server.listen(8443)

http2.connect(authority[, options][, listener])

[History]

الإصدار	التغييرات
v13.0.0	أصبح PADDING_STRATEGY_CALLBACK مكافئًا لتوفير PADDING_STRATEGY_ALIGNED وتم إزالة selectPadding.
v15.10.0، v14.16.0، v12.21.0، v10.24.0	تمت إضافة خيار unknownProtocolTimeout مع قيمة افتراضية تبلغ 10000.
v14.4.0، v12.18.0، v10.21.0	تمت إضافة خيار maxSettings مع قيمة افتراضية تبلغ 32.
v8.9.3	تمت إضافة خيار maxOutstandingPings مع حد افتراضي يبلغ 10.
v8.9.3	تمت إضافة خيار maxHeaderListPairs مع حد افتراضي يبلغ 128 زوجًا من العناوين.
v8.4.0	تمت الإضافة في: v8.4.0

• authority <string> | <URL> خادم HTTP/2 البعيد للاتصال به. يجب أن يكون هذا في شكل عنوان URL صالح بسيط مع بادئة http:// أو https:// واسم المضيف ومنفذ IP (إذا تم استخدام منفذ غير افتراضي). سيتم تجاهل تفاصيل معلومات المستخدم (معرف المستخدم وكلمة المرور) والمسار وسلسلة الاستعلام وقطعة الكود في عنوان URL.

• options <Object>

  • maxDeflateDynamicTableSize <number> يحدد الحد الأقصى لحجم الجدول الديناميكي لضغط حقول الرأس. الافتراضي: 4Kib.

  • maxSettings <number> يحدد الحد الأقصى لعدد إدخالات الإعدادات لكل إطار SETTINGS. الحد الأدنى للقيمة المسموح بها هو 1. الافتراضي: 32.

  • maxSessionMemory<number> يحدد الحد الأقصى للذاكرة المسموح باستخدامها بواسطة Http2Session. يتم التعبير عن القيمة من حيث عدد ميجابايت، على سبيل المثال، 1 يساوي 1 ميجابايت. الحد الأدنى للقيمة المسموح بها هو 1. هذا حد قائم على الرصيد، قد تتسبب عمليات Http2Stream الموجودة في تجاوز هذا الحد، ولكن سيتم رفض مثيلات Http2Stream الجديدة بينما يتم تجاوز هذا الحد. يتم احتساب عدد جلسات Http2Stream الحالية، واستخدام الذاكرة الحالي لجدول ضغط الرأس، والبيانات الحالية المُنتظرة للإرسال، وإطارات PING وSETTINGS غير المُعترف بها جميعها نحو الحد الحالي. الافتراضي: 10.

  • maxHeaderListPairs <number> يحدد الحد الأقصى لعدد إدخالات الرأس. هذا مشابه لـ server.maxHeadersCount أو request.maxHeadersCount في وحدة node:http. الحد الأدنى للقيمة هو 1. الافتراضي: 128.

  • maxOutstandingPings <number> يحدد الحد الأقصى لعدد عمليات ping المعلقة غير المُعترف بها. الافتراضي: 10.

  • maxReservedRemoteStreams <number> يحدد الحد الأقصى لعدد تدفقات الدفع المحجوزة التي سيقبلها العميل في أي وقت معين. بمجرد أن يتجاوز العدد الحالي لتدفقات الدفع المحجوزة حاليًا هذا الحد، سيتم رفض تدفقات الدفع الجديدة التي يرسلها الخادم تلقائيًا. الحد الأدنى للقيمة المسموح بها هو 0. الحد الأقصى للقيمة المسموح بها هو 2-1. تقوم قيمة سالبة بتعيين هذا الخيار على الحد الأقصى للقيمة المسموح بها. الافتراضي: 200.

  • maxSendHeaderBlockLength <number> يحدد الحد الأقصى للحجم المسموح به لكتلة مُسلسلة مضغوطة من العناوين. ستؤدي محاولات إرسال عناوين تتجاوز هذا الحد إلى إصدار حدث 'frameError' وإغلاق الدفق وتدميره.

  • paddingStrategy <number> الاستراتيجية المستخدمة لتحديد مقدار التعبئة التي يجب استخدامها لإطارات HEADERS وDATA. الافتراضي: http2.constants.PADDING_STRATEGY_NONE. قد تكون القيمة إحدى القيم التالية:

  • http2.constants.PADDING_STRATEGY_NONE: لا يتم تطبيق أي حشو.

  • http2.constants.PADDING_STRATEGY_MAX: يتم تطبيق الحد الأقصى لمقدار الحشو، والذي يحدده التنفيذ الداخلي.

  • http2.constants.PADDING_STRATEGY_ALIGNED: يحاول تطبيق ما يكفي من الحشو لضمان أن يكون إجمالي طول الإطار، بما في ذلك رأس 9 بايت، مضاعفًا لـ 8. لكل إطار، يوجد حد أقصى مسموح به لعدد بايت الحشو والذي يحدده حالة التحكم في التدفق والإعدادات الحالية. إذا كان هذا الحد الأقصى أقل من المقدار المحسوب اللازم لضمان المحاذاة، فسيتم استخدام الحد الأقصى ولا يكون إجمالي طول الإطار محاذيًا بالضرورة عند 8 بايت.

  • peerMaxConcurrentStreams <number> يحدد الحد الأقصى لعدد التدفقات المتزامنة للنظير البعيد كما لو تم استلام إطار SETTINGS. سيتم تجاوز ذلك إذا قام النظير البعيد بتعيين قيمته الخاصة لـ maxConcurrentStreams. الافتراضي: 100.

  • protocol <string> البروتوكول للاتصال به، إذا لم يتم تعيينه في authority. قد تكون القيمة إما 'http:' أو 'https:'. الافتراضي: 'https:'

  • settings <HTTP/2 Settings Object> الإعدادات الأولية لإرسالها إلى النظير البعيد عند الاتصال.

  • remoteCustomSettings <Array> يحدد مُصفوفة قيم الأعداد الصحيحة أنواع الإعدادات، والتي يتم تضمينها في خاصية CustomSettings من remoteSettings المستلمة. يرجى الاطلاع على خاصية CustomSettings من كائن Http2Settings لمزيد من المعلومات حول أنواع الإعدادات المسموح بها.

  • createConnection <Function> استدعاء اختياري يستقبل مثيل URL المُمرر إلى connect وكائن options، ويرجع أي دفق Duplex يُستخدم كاتصال لهذه الجلسة.

  • ...: يمكن توفير أي خيارات net.connect() أو tls.connect().

  • unknownProtocolTimeout <number> يحدد مهلة بالميلي ثانية يجب على الخادم الانتظار فيها عند إصدار حدث 'unknownProtocol'. إذا لم يتم تدمير المقبس بحلول ذلك الوقت، فسيقوم الخادم بتدميره. الافتراضي: 10000.

• listener <Function> سيتم تسجيله كسامع لمرة واحدة لحدث 'connect'.

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

يرجع مثيلًا ClientHttp2Session.

ESM

import { connect } from 'node:http2'
const client = connect('https://localhost:1234')

/* استخدام العميل */

client.close()

CJS

const http2 = require('node:http2')
const client = http2.connect('https://localhost:1234')

/* استخدام العميل */

client.close()

http2.constants

مضاف في: v8.4.0

رموز الخطأ لـ RST_STREAM و GOAWAY

القيمة	الاسم	الثابت
0x00	لا يوجد خطأ	http2.constants.NGHTTP2_NO_ERROR
0x01	خطأ في البروتوكول	http2.constants.NGHTTP2_PROTOCOL_ERROR
0x02	خطأ داخلي	http2.constants.NGHTTP2_INTERNAL_ERROR
0x03	خطأ في التحكم في التدفق	http2.constants.NGHTTP2_FLOW_CONTROL_ERROR
0x04	مهلة الإعدادات	http2.constants.NGHTTP2_SETTINGS_TIMEOUT
0x05	إغلاق الدفق	http2.constants.NGHTTP2_STREAM_CLOSED
0x06	خطأ في حجم الإطار	http2.constants.NGHTTP2_FRAME_SIZE_ERROR
0x07	دفق مرفوض	http2.constants.NGHTTP2_REFUSED_STREAM
0x08	إلغاء	http2.constants.NGHTTP2_CANCEL
0x09	خطأ في الضغط	http2.constants.NGHTTP2_COMPRESSION_ERROR
0x0a	خطأ في الاتصال	http2.constants.NGHTTP2_CONNECT_ERROR
0x0b	تحسين هدوئك	http2.constants.NGHTTP2_ENHANCE_YOUR_CALM
0x0c	أمان غير كافٍ	http2.constants.NGHTTP2_INADEQUATE_SECURITY
0x0d	مطلوب HTTP/1.1	http2.constants.NGHTTP2_HTTP_1_1_REQUIRED

يُصدر حدث 'timeout' عندما لا يكون هناك نشاط على الخادم لفترة معينة من الميلي ثانية تم تعيينها باستخدام http2server.setTimeout().

http2.getDefaultSettings()

مضاف في: v8.4.0

• الإرجاع: <كائن إعدادات HTTP/2>

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

http2.getPackedSettings([settings])

مضاف في: v8.4.0

• settings <كائن إعدادات HTTP/2>
• الإرجاع: <Buffer>

يرجع مثيلًا Buffer يحتوي على تمثيل مُسلسل لإعدادات HTTP/2 المُعطاة كما هو محدد في مواصفات HTTP/2. وهذا مخصص للاستخدام مع حقل رأس HTTP2-Settings.

ESM

import { getPackedSettings } from 'node:http2'

const packed = getPackedSettings({ enablePush: false })

console.log(packed.toString('base64'))
// يطبع: AAIAAAAA

CJS

const http2 = require('node:http2')

const packed = http2.getPackedSettings({ enablePush: false })

console.log(packed.toString('base64'))
// يطبع: AAIAAAAA

http2.getUnpackedSettings(buf)

مضاف في: v8.4.0

• buf <Buffer> | <TypedArray> إعدادات مُعبأة.
• قيمة مُرجعة: <HTTP/2 Settings Object>

يُرجع كائن إعدادات HTTP/2 يحتوي على الإعدادات المُفككة من المُعطى Buffer كما تم إنشاؤه بواسطة http2.getPackedSettings().

http2.performServerHandshake(socket[, options])

مضاف في: v21.7.0، v20.12.0

• socket <stream.Duplex>

• options <Object>

  • ...: يمكن توفير أي خيار http2.createServer().

• قيمة مُرجعة: <ServerHttp2Session>

إنشاء جلسة خادم HTTP/2 من مقبس موجود.

http2.sensitiveHeaders

مضاف في: v15.0.0، v14.18.0

• <symbol>

يمكن تعيين هذا الرمز كخاصية على كائن عناوين HTTP/2 بقيمة مُصفوفة لتوفير قائمة بالرؤوس التي تعتبر حساسة. انظر الرؤوس الحساسة لمزيد من التفاصيل.

كائن الرؤوس

تُمثَّل الرؤوس كخصائص خاصة في كائنات JavaScript. سيتم تسلسل مفاتيح الخصائص إلى الأحرف الصغيرة. يجب أن تكون قيم الخصائص سلاسل (إذا لم تكن كذلك، فسيتم تحويلها إلى سلاسل) أو مصفوفة من السلاسل (لإرسال أكثر من قيمة لكل حقل رأس).

const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  ABC: ['has', 'more', 'than', 'one', 'value'],
}

stream.respond(headers)

ستحتوي كائنات الرؤوس المُمررة إلى دوال المُعالجة على نموذج أولي null. هذا يعني أن طرق كائن JavaScript العادية مثل Object.prototype.toString() و Object.prototype.hasOwnProperty() لن تعمل.

بالنسبة للرؤوس الواردة:

• يتم تحويل رأس :status إلى number.
• يتم تجاهل المُكررات من :status, :method, :authority, :scheme, :path, :protocol, age, authorization, access-control-allow-credentials, access-control-max-age, access-control-request-method, content-encoding, content-language, content-length, content-location, content-md5, content-range, content-type, date, dnt, etag, expires, from, host, if-match, if-modified-since, if-none-match, if-range, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, range, referer,retry-after, tk, upgrade-insecure-requests, user-agent أو x-content-type-options.
• set-cookie هو دائمًا مصفوفة. يتم إضافة المُكررات إلى المصفوفة.
• بالنسبة للرؤوس المُكررة cookie، يتم ضم القيم معًا باستخدام '; '.
• بالنسبة لجميع الرؤوس الأخرى، يتم ضم القيم معًا باستخدام ', '.

ESM

import { createServer } from 'node:http2'
const server = createServer()
server.on('stream', (stream, headers) => {
  console.log(headers[':path'])
  console.log(headers.ABC)
})

CJS

const http2 = require('node:http2')
const server = http2.createServer()
server.on('stream', (stream, headers) => {
  console.log(headers[':path'])
  console.log(headers.ABC)
})

العناوين الحساسة

يمكن تمييز عناوين HTTP2 على أنها حساسة، مما يعني أن خوارزمية ضغط رأس HTTP/2 لن تقوم بفهرستها أبدًا. قد يكون هذا منطقيًا لقيم الرؤوس ذات الإنتروبيا المنخفضة والتي قد تعتبر قيّمة لمهاجم، على سبيل المثال Cookie أو Authorization. لتحقيق ذلك، أضف اسم الرأس إلى خاصية [http2.sensitiveHeaders] كمصفوفة:

const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  cookie: 'some-cookie',
  'other-sensitive-header': 'very secret data',
  [http2.sensitiveHeaders]: ['cookie', 'other-sensitive-header'],
}

stream.respond(headers)

بالنسبة لبعض العناوين، مثل Authorization وعناوين Cookie القصيرة، يتم تعيين هذه العلامة تلقائيًا.

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

كائن الإعدادات

[History]

الإصدار	التغييرات
v12.12.0	إعداد maxConcurrentStreams أكثر صرامة.
v8.9.3	يتم الآن تطبيق إعداد maxHeaderListSize بشكل صارم.
v8.4.0	تمت الإضافة في: v8.4.0

واجهات برمجة التطبيقات http2.getDefaultSettings()، و http2.getPackedSettings()، و http2.createServer()، و http2.createSecureServer()، و http2session.settings()، و http2session.localSettings، و http2session.remoteSettings إما تُرجع أو تستقبل كمدخل كائنًا يُعرّف إعدادات التكوين لكائن Http2Session. هذه الكائنات هي كائنات JavaScript عادية تحتوي على الخصائص التالية.

• headerTableSize <number> يحدد الحد الأقصى لعدد البايت المستخدمة لضغط الرأس. الحد الأدنى للقيمة المسموح بها هو 0. الحد الأقصى للقيمة المسموح بها هو 2-1. الافتراضي: 4096.
• enablePush <boolean> يحدد true إذا كان يُسمح بتدفقات دفع HTTP/2 على مثيلات Http2Session. الافتراضي: true.
• initialWindowSize <number> يحدد حجم النافذة الأولية للمرسل بالبايت للتحكم في تدفق مستوى التدفق. الحد الأدنى للقيمة المسموح بها هو 0. الحد الأقصى للقيمة المسموح بها هو 2-1. الافتراضي: 65535.
• maxFrameSize <number> يحدد حجم حمولة الإطار الأكبر بالبايت. الحد الأدنى للقيمة المسموح بها هو 16384. الحد الأقصى للقيمة المسموح بها هو 2-1. الافتراضي: 16384.
• maxConcurrentStreams <number> يحدد الحد الأقصى لعدد التدفقات المتزامنة المسموح بها على Http2Session. لا توجد قيمة افتراضية وهذا يعني، على الأقل نظريًا، أنه قد يكون هناك 2-1 تدفق مفتوحًا بشكل متزامن في أي وقت معين في Http2Session. الحد الأدنى للقيمة هو 0. الحد الأقصى للقيمة المسموح بها هو 2-1. الافتراضي: 4294967295.
• maxHeaderListSize <number> يحدد الحد الأقصى لحجم (البايت غير المضغوط) لقائمة الرؤوس التي سيتم قبولها. الحد الأدنى للقيمة المسموح بها هو 0. الحد الأقصى للقيمة المسموح بها هو 2-1. الافتراضي: 65535.
• maxHeaderSize <number> اسم آخر لـ maxHeaderListSize.
• enableConnectProtocol<boolean> يحدد true إذا كان "بروتوكول الاتصال الموسع" المعرّف بواسطة RFC 8441 سيتم تمكينه. هذا الإعداد ذو مغزى فقط إذا تم إرساله من قبل الخادم. بمجرد تمكين إعداد enableConnectProtocol لـ Http2Session معين، لا يمكن تعطيله. الافتراضي: false.
• customSettings <Object> يحدد إعدادات إضافية، لم يتم تنفيذها بعد في node والمكتبات الأساسية. يحدد مفتاح الكائن القيمة العددية لنوع الإعداد (كما هو محدد في سجل "إعدادات HTTP/2" التي أنشأها [RFC 7540]) والقيم القيمة العددية الفعلية للإعدادات. يجب أن يكون نوع الإعداد عددًا صحيحًا في النطاق من 1 إلى 2^16-1. يجب ألا يكون نوع إعداد تمت معالجته بالفعل بواسطة node، أي أنه يجب أن يكون أكبر من 6 حاليًا، على الرغم من أنه ليس خطأ. يجب أن تكون القيم أعدادًا صحيحة غير موقعة في النطاق من 0 إلى 2^32-1. حاليًا، يتم دعم حد أقصى يصل إلى 10 إعدادات مخصصة. يتم دعمه فقط لإرسال إعدادات، أو لاستقبال قيم إعدادات محددة في خيارات remoteCustomSettings لكائن الخادم أو العميل. لا تخلط آلية customSettings لمعرف إعداد مع واجهات لإعدادات المعالجة محليًا، في حالة دعم إعداد محليًا في إصدار node في المستقبل.

يتم تجاهل جميع الخصائص الإضافية في كائن الإعدادات.

معالجة الأخطاء

هناك عدة أنواع من حالات الخطأ التي قد تنشأ عند استخدام وحدة node:http2:

تحدث أخطاء التحقق من الصحة عندما يتم تمرير وسيطة أو خيار أو قيمة إعداد غير صحيحة. سيتم دائمًا الإبلاغ عن هذه الأخطاء من خلال throw متزامن.

تحدث أخطاء الحالة عندما يتم محاولة إجراء في وقت غير صحيح (على سبيل المثال، محاولة إرسال بيانات على دفق بعد إغلاقه). سيتم الإبلاغ عن هذه الأخطاء إما باستخدام throw متزامن أو عبر حدث 'error' على كائنات Http2Stream أو Http2Session أو خادم HTTP/2، اعتمادًا على مكان ووقت حدوث الخطأ.

تحدث الأخطاء الداخلية عندما تفشل جلسة HTTP/2 بشكل غير متوقع. سيتم الإبلاغ عن هذه الأخطاء عبر حدث 'error' على كائنات Http2Session أو خادم HTTP/2.

تحدث أخطاء البروتوكول عندما يتم انتهاك قيود بروتوكول HTTP/2 المختلفة. سيتم الإبلاغ عن هذه الأخطاء إما باستخدام throw متزامن أو عبر حدث 'error' على كائنات Http2Stream أو Http2Session أو خادم HTTP/2، اعتمادًا على مكان ووقت حدوث الخطأ.

معالجة الأحرف غير الصالحة في أسماء وقيم الرؤوس

يطبق تنفيذ HTTP/2 معالجة أكثر صرامة للأحرف غير الصالحة في أسماء وقيم رؤوس HTTP من تنفيذ HTTP/1.

أسماء حقول الرأس غير حساسة لحالة الأحرف ويتم إرسالها عبر السلك كسلاسل أحرف صغيرة فقط. تسمح واجهة برمجة التطبيقات التي يوفرها Node.js بتعيين أسماء الرؤوس كسلاسل أحرف مختلطة الحالات (مثل Content-Type) ولكنها ستقوم بتحويلها إلى أحرف صغيرة (مثل content-type) عند الإرسال.

يجب أن تحتوي أسماء حقول الرأس فقط على حرف واحد أو أكثر من أحرف ASCII التالية: a-z، A-Z، 0-9، !، #، $، %، &، '، *، +، -، .، ^، _، ```(علامة اقتباس عكسية)،|، و ~.

سيؤدي استخدام أحرف غير صالحة داخل اسم حقل رأس HTTP إلى إغلاق الدفق مع الإبلاغ عن خطأ بروتوكول.

يتم التعامل مع قيم حقول الرأس بمزيد من المرونة ولكن يجب ألا تحتوي على أحرف جديدة أو أحرف عودة عربات ويجب أن تقتصر على أحرف US-ASCII، وفقًا لمتطلبات مواصفات HTTP.

تدفقات الدفع على العميل

لاستقبال تدفقات الدفع على العميل، قم بتعيين مستمع لحدث 'stream' على ClientHttp2Session:

ESM

import { connect } from 'node:http2'

const client = connect('http://localhost')

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', responseHeaders => {
    // معالجة رؤوس الاستجابة
  })
  pushedStream.on('data', chunk => {
    /* معالجة البيانات المدفوعة */
  })
})

const req = client.request({ ':path': '/' })

CJS

const http2 = require('node:http2')

const client = http2.connect('http://localhost')

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', responseHeaders => {
    // معالجة رؤوس الاستجابة
  })
  pushedStream.on('data', chunk => {
    /* معالجة البيانات المدفوعة */
  })
})

const req = client.request({ ':path': '/' })

دعم طريقة CONNECT

تُستخدم طريقة CONNECT للسماح باستخدام خادم HTTP/2 كوكيل لاتصالات TCP/IP.

خادم TCP بسيط:

ESM

import { createServer } from 'node:net'

const server = createServer(socket => {
  let name = ''
  socket.setEncoding('utf8')
  socket.on('data', chunk => (name += chunk))
  socket.on('end', () => socket.end(`hello ${name}`))
})

server.listen(8000)

CJS

const net = require('node:net')

const server = net.createServer(socket => {
  let name = ''
  socket.setEncoding('utf8')
  socket.on('data', chunk => (name += chunk))
  socket.on('end', () => socket.end(`hello ${name}`))
})

server.listen(8000)

وكيل HTTP/2 CONNECT:

ESM

import { createServer, constants } from 'node:http2'
const { NGHTTP2_REFUSED_STREAM, NGHTTP2_CONNECT_ERROR } = constants
import { connect } from 'node:net'

const proxy = createServer()
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // قبول طلبات CONNECT فقط
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // من الجيد جدًا التحقق من أن اسم المضيف والمنفذ هما
  // الأشياء التي يجب أن يتصل بها هذا الوكيل.
  const socket = connect(auth.port, auth.hostname, () => {
    stream.respond()
    socket.pipe(stream)
    stream.pipe(socket)
  })
  socket.on('error', error => {
    stream.close(NGHTTP2_CONNECT_ERROR)
  })
})

proxy.listen(8001)

CJS

const http2 = require('node:http2')
const { NGHTTP2_REFUSED_STREAM } = http2.constants
const net = require('node:net')

const proxy = http2.createServer()
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // قبول طلبات CONNECT فقط
    stream.close(NGHTTP2_REFUSED_STREAM)
    return
  }
  const auth = new URL(`tcp://${headers[':authority']}`)
  // من الجيد جدًا التحقق من أن اسم المضيف والمنفذ هما
  // الأشياء التي يجب أن يتصل بها هذا الوكيل.
  const socket = net.connect(auth.port, auth.hostname, () => {
    stream.respond()
    socket.pipe(stream)
    stream.pipe(socket)
  })
  socket.on('error', error => {
    stream.close(http2.constants.NGHTTP2_CONNECT_ERROR)
  })
})

proxy.listen(8001)

عميل HTTP/2 CONNECT:

ESM

import { connect, constants } from 'node:http2'

const client = connect('http://localhost:8001')

// يجب عدم تحديد رؤوس ':path' و ':scheme'
// لطلبات CONNECT أو سيتم إلقاء خطأ.
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
})

req.on('response', headers => {
  console.log(headers[constants.HTTP2_HEADER_STATUS])
})
let data = ''
req.setEncoding('utf8')
req.on('data', chunk => (data += chunk))
req.on('end', () => {
  console.log(`يقول الخادم: ${data}`)
  client.close()
})
req.end('Jane')

CJS

const http2 = require('node:http2')

const client = http2.connect('http://localhost:8001')

// يجب عدم تحديد رؤوس ':path' و ':scheme'
// لطلبات CONNECT أو سيتم إلقاء خطأ.
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
})

req.on('response', headers => {
  console.log(headers[http2.constants.HTTP2_HEADER_STATUS])
})
let data = ''
req.setEncoding('utf8')
req.on('data', chunk => (data += chunk))
req.on('end', () => {
  console.log(`يقول الخادم: ${data}`)
  client.close()
})
req.end('Jane')

بروتوكول CONNECT الموسّع

يُعرّف RFC 8441 امتداد "بروتوكول CONNECT الموسّع" لـ HTTP/2، والذي يمكن استخدامه لبدء تشغيل استخدام Http2Stream باستخدام طريقة CONNECT كنافذة لنقل بروتوكولات الاتصال الأخرى (مثل WebSockets).

يتم تمكين استخدام بروتوكول CONNECT الموسّع بواسطة خوادم HTTP/2 باستخدام إعداد enableConnectProtocol:

ESM

import { createServer } from 'node:http2'
const settings = { enableConnectProtocol: true }
const server = createServer({ settings })

CJS

const http2 = require('node:http2')
const settings = { enableConnectProtocol: true }
const server = http2.createServer({ settings })

بمجرد أن يستقبل العميل إطار SETTINGS من الخادم الذي يشير إلى إمكانية استخدام CONNECT الموسّع، يمكنه إرسال طلبات CONNECT التي تستخدم رأس HTTP/2 الوهمي ':protocol':

ESM

import { connect } from 'node:http2'
const client = connect('http://localhost:8080')
client.on('remoteSettings', settings => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' })
    // ...
  }
})

CJS

const http2 = require('node:http2')
const client = http2.connect('http://localhost:8080')
client.on('remoteSettings', settings => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' })
    // ...
  }
})

واجهة برمجة التطبيقات المتوافقة

يهدف واجهة برمجة التطبيقات المتوافقة إلى توفير تجربة مطوّر مماثلة لـ HTTP/1 عند استخدام HTTP/2، مما يجعل من الممكن تطوير تطبيقات تدعم كل من HTTP/1 و HTTP/2. تستهدف هذه الواجهة البرمجية واجهة برمجة التطبيقات العامة لـ HTTP/1 فقط. ومع ذلك، تستخدم العديد من الوحدات طرقًا أو حالات داخلية، وهذه غير مدعومة لأنها تنفيذ مختلف تمامًا.

يوضّح المثال التالي إنشاء خادم HTTP/2 باستخدام واجهة برمجة التطبيقات المتوافقة:

ESM

import { createServer } from 'node:http2'
const server = createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
  res.end('ok')
})

CJS

const http2 = require('node:http2')
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
  res.end('ok')
})

لإنشاء خادم مختلط HTTPS و HTTP/2، يُرجى الرجوع إلى قسم مفاوضات ALPN. ترقية خوادم HTTP/1 غير TLS غير مدعومة.

تتكوّن واجهة برمجة تطبيقات HTTP/2 المتوافقة من Http2ServerRequest و Http2ServerResponse. تهدف إلى توافق واجهة برمجة التطبيقات مع HTTP/1، لكنها لا تخفي الاختلافات بين البروتوكولات. على سبيل المثال، يتم تجاهل رسالة الحالة لأكواد HTTP.

مفاوضات ALPN

تتيح مفاوضات ALPN دعم كل من HTTPS و HTTP/2 عبر نفس المقبس. يمكن أن يكون كائنا req و res إما HTTP/1 أو HTTP/2، ويجب على التطبيق الالتزام بواجهة برمجة التطبيقات العامة لـ HTTP/1، والكشف عما إذا كان من الممكن استخدام ميزات HTTP/2 الأكثر تقدمًا.

يوضح المثال التالي إنشاء خادم يدعم كلا البروتوكولين:

ESM

import { createSecureServer } from 'node:http2'
import { readFileSync } from 'node:fs'

const cert = readFileSync('./cert.pem')
const key = readFileSync('./key.pem')

const server = createSecureServer({ cert, key, allowHTTP1: true }, onRequest).listen(8000)

function onRequest(req, res) {
  // الكشف عما إذا كان طلب HTTPS أو HTTP/2
  const {
    socket: { alpnProtocol },
  } = req.httpVersion === '2.0' ? req.stream.session : req
  res.writeHead(200, { 'content-type': 'application/json' })
  res.end(
    JSON.stringify({
      alpnProtocol,
      httpVersion: req.httpVersion,
    })
  )
}

CJS

const { createSecureServer } = require('node:http2')
const { readFileSync } = require('node:fs')

const cert = readFileSync('./cert.pem')
const key = readFileSync('./key.pem')

const server = createSecureServer({ cert, key, allowHTTP1: true }, onRequest).listen(4443)

function onRequest(req, res) {
  // الكشف عما إذا كان طلب HTTPS أو HTTP/2
  const {
    socket: { alpnProtocol },
  } = req.httpVersion === '2.0' ? req.stream.session : req
  res.writeHead(200, { 'content-type': 'application/json' })
  res.end(
    JSON.stringify({
      alpnProtocol,
      httpVersion: req.httpVersion,
    })
  )
}

يعمل حدث 'request' بشكل مطابق على كل من HTTPS و HTTP/2.

Class: http2.Http2ServerRequest

مضاف في: v8.4.0

• يمتد: <stream.Readable>

يتم إنشاء كائن Http2ServerRequest بواسطة http2.Server أو http2.SecureServer ويتم تمريره كأول وسيطة إلى حدث 'request'. يمكن استخدامه للوصول إلى حالة الطلب، والرؤوس، والبيانات.

الحدث: 'aborted'

مضاف في: v8.4.0

يتم إرسال حدث 'aborted' كلما تم إلغاء مثيل Http2ServerRequest بشكل غير طبيعي في منتصف الاتصال.

لن يتم إرسال حدث 'aborted' إلا إذا لم يتم إنهاء الجانب القابل للكتابة من Http2ServerRequest.

الحدث: 'close'

مضاف في: v8.4.0

يشير إلى أن Http2Stream الأساسي قد تم إغلاقه. مثل 'end', يحدث هذا الحدث مرة واحدة فقط لكل استجابة.

request.aborted

مضاف في: v10.1.0

• <boolean>

ستكون خاصية request.aborted قيمة true إذا تم إلغاء الطلب.

request.authority

مضاف في: v8.4.0

• <string>

حقل رأس السلطة الوهمي للطلب. نظرًا لأن HTTP/2 يسمح للطلبات بتعيين :authority أو host, يتم اشتقاق هذه القيمة من req.headers[':authority'] إذا وجدت. خلاف ذلك، يتم اشتقاقها من req.headers['host'].

request.complete

مضاف في: v12.10.0

• <boolean>

ستكون خاصية request.complete قيمة true إذا تم إكمال الطلب أو إلغاؤه أو تدميره.

request.connection

مضاف في: v8.4.0

تم إهماله منذ: v13.0.0

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

مستقر: 0 الثبات: 0 - تم إهماله. استخدم request.socket.

• <net.Socket> | <tls.TLSSocket>

انظر request.socket.

request.destroy([error])

مضاف في: v8.4.0

• error <Error>

يطلق destroy() على Http2Stream الذي استلم Http2ServerRequest. إذا تم توفير error، فسيتم إرسال حدث 'error' ويتم تمرير error كوسيط لأي مستمعين على الحدث.

لا يفعل شيئًا إذا تم تدمير التدفق بالفعل.

request.headers

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

• <Object>

كائن عناوين الطلب/الاستجابة.

أزواج مفتاح-قيمة لأسماء العناوين وقيمها. أسماء العناوين صغيرة الحروف.

// يطبع شيئًا مثل:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers)

انظر كائن عناوين HTTP/2.

في HTTP/2، يتم تمثيل مسار الطلب، واسم المضيف، والبروتوكول، والطريقة كعناوين خاصة بادئة بعلامة : (مثل ':path'). سيتم تضمين هذه العناوين الخاصة في كائن request.headers. يجب توخي الحذر لعدم تعديل هذه العناوين الخاصة عن غير قصد، وإلا فقد تحدث أخطاء. على سبيل المثال، سيؤدي إزالة جميع العناوين من الطلب إلى حدوث أخطاء:

removeAllHeaders(request.headers)
assert(request.url) // يفشل لأن عنوان :path قد تم إزالته

request.httpVersion

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

• <string>

في حالة طلب الخادم، إصدار HTTP الذي أرسله العميل. في حالة استجابة العميل، إصدار HTTP للخادم المتصل به. يُرجع '2.0'.

أيضًا، message.httpVersionMajor هو الرقم الصحيح الأول وmessage.httpVersionMinor هو الثاني.

request.method

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

• <string>

طريقة الطلب كسلسلة. للقراءة فقط. أمثلة: 'GET', 'DELETE'.

request.rawHeaders

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

• <string[]>

قائمة عناوين الطلب/الاستجابة الخام كما تم استلامها بالضبط.

المفاتيح والقيم في نفس القائمة. إنها ليست قائمة من التuples. لذلك، فإن الإزاحات ذات الأرقام الزوجية هي قيم المفاتيح، والإزاحات ذات الأرقام الفردية هي القيم المرتبطة.

أسماء العناوين ليست صغيرة الحروف، ولم يتم دمج المكررات.

// يطبع شيئًا مثل:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders)

request.rawTrailers

أضيف في: v8.4.0

• <string[]>

مفاتيح وقيم مُلحق الطلب/الاستجابة الخام كما تم استلامها بالضبط. يتم تعبئتها فقط في حدث 'end' .

request.scheme

أضيف في: v8.4.0

• <string>

حقل رأس الطلب الوهمي الذي يشير إلى جزء المخطط من عنوان URL الهدف.

request.setTimeout(msecs, callback)

أضيف في: v8.4.0

• msecs <number>
• callback <Function>
• الإرجاع: <http2.Http2ServerRequest>

يُعيّن قيمة مهلة Http2Stream إلى msecs. إذا تم توفير دالة مُراجعة، فسيتم إضافتها كمُستمع لحدث 'timeout' على كائن الاستجابة.

إذا لم يتم إضافة مُستمع 'timeout' إلى الطلب، أو الاستجابة، أو الخادم، فسيتم تدمير Http2Stream عند انتهاء وقتها. إذا تم تعيين مُعالِج لأحداث 'timeout' للطلب، أو الاستجابة، أو الخادم، فيجب التعامل بشكل صريح مع المقابس التي انتهى وقتها.

request.socket

أضيف في: v8.4.0

• <net.Socket> | <tls.TLSSocket>

يُرجع كائن Proxy يعمل كـ net.Socket (أو tls.TLSSocket) ولكنه يُطبق مُحصلات، و مُعيّنات، و طرق بناءً على منطق HTTP/2.

سيتم استرداد خصائص destroyed, readable, و writable من request.stream و تعيينها عليها.

سيتم استدعاء طرق destroy, emit, end, on و once على request.stream.

سيتم استدعاء طريقة setTimeout على request.stream.session.

ستُلقي طرق pause, read, resume, و write خطأً برمز ERR_HTTP2_NO_SOCKET_MANIPULATION. راجع Http2Session and Sockets لمزيد من المعلومات.

سيتم توجيه جميع التفاعلات الأخرى مباشرةً إلى المقبس. مع دعم TLS، استخدم request.socket.getPeerCertificate() للحصول على تفاصيل مصادقة العميل.

request.stream

مضاف في: v8.4.0

• <Http2Stream>

كائن Http2Stream الذي يدعم الطلب.

request.trailers

مضاف في: v8.4.0

• <Object>

كائن بيانات نهاية الطلب/الاستجابة. يتم تعبئته فقط عند حدث 'end' .

request.url

مضاف في: v8.4.0

• <string>

سلسلة URL للطلب. هذه تحتوي فقط على عنوان URL الموجود في طلب HTTP الفعلي. إذا كان الطلب هو:

GET /status?name=ryan HTTP/1.1 Accept: text/plain

فإن request.url ستكون:

'/status?name=ryan'

لتحليل عنوان url إلى أجزائه، يمكن استخدام new URL() :

$ node
> new URL('/status?name=ryan', 'http://example.com')
URL {
  href: 'http://example.com/status?name=ryan',
  origin: 'http://example.com',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'example.com',
  hostname: 'example.com',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

Class: http2.Http2ServerResponse

مضاف في: v8.4.0

• يمتد: <Stream>

يتم إنشاء هذا الكائن داخليًا بواسطة خادم HTTP، وليس بواسطة المستخدم. يتم تمريره كمعامل ثاني لحدث 'request' .

Event: 'close'

مضاف في: v8.4.0

يشير إلى أن Http2Stream الأساسي قد تم إنهاؤه قبل استدعاء response.end() أو قبل تمكنه من التصريف.

Event: 'finish'

مضاف في: v8.4.0

يتم إصداره عندما يتم إرسال الاستجابة. على وجه التحديد، يتم إصدار هذا الحدث عندما يتم تسليم آخر جزء من رؤوس الاستجابة والجسم إلى الإرسال المتعدد HTTP/2 لنقله عبر الشبكة. لا يعني ذلك أن العميل قد استلم أي شيء بعد.

بعد هذا الحدث، لن يتم إصدار أي أحداث أخرى على كائن الاستجابة.

response.addTrailers(headers)

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

• headers <Object>

تضيف هذه الطريقة عناوين HTTP المتتالية (عنوان ولكن في نهاية الرسالة) إلى الاستجابة.

إن محاولة تعيين اسم حقل عنوان أو قيمة تحتوي على أحرف غير صالحة سيؤدي إلى طرح خطأ TypeError.

response.appendHeader(name, value)

تم الإضافة في: v21.7.0، v20.12.0

• name <string>
• value <string> | <string[]>

إضافة قيمة عنوان واحدة إلى كائن العنوان.

إذا كانت القيمة عبارة عن مصفوفة، فهذا ما يعادل استدعاء هذه الطريقة عدة مرات.

إذا لم تكن هناك قيم سابقة للعنوان، فهذا ما يعادل استدعاء response.setHeader().

إن محاولة تعيين اسم حقل عنوان أو قيمة تحتوي على أحرف غير صالحة سيؤدي إلى طرح خطأ TypeError.

// تُرجع العناوين بما في ذلك "set-cookie: a" و "set-cookie: b"
const server = http2.createServer((req, res) => {
  res.setHeader('set-cookie', 'a')
  res.appendHeader('set-cookie', 'b')
  res.writeHead(200)
  res.end('ok')
})

response.connection

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

تم إهماله منذ: v13.0.0

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

مستقر: 0 الثبات: 0 - مهمل. استخدم response.socket.

• <net.Socket> | <tls.TLSSocket>

انظر response.socket.

response.createPushResponse(headers, callback)

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُدعمة غير صالحة إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v8.4.0	تم الإضافة في: v8.4.0

• headers <كائن عناوين HTTP/2> كائن يصف العناوين
• callback <Function> يتم استدعائه مرة واحدة عند الانتهاء من http2stream.pushStream()، أو إما عندما تفشل محاولة إنشاء Http2Stream المُدفوع أو يتم رفضها، أو يتم إغلاق حالة Http2ServerRequest قبل استدعاء طريقة http2stream.pushStream()
  • err <Error>
  • res <http2.Http2ServerResponse> كائن Http2ServerResponse المُنشأ حديثًا

استدعاء http2stream.pushStream() باستخدام العناوين المعطاة، ولفّ Http2Stream المعطى على Http2ServerResponse المُنشأ حديثًا كمعلمة المُدعمة إذا نجحت العملية. عند إغلاق Http2ServerRequest، يتم استدعاء المُدعمة بخطأ ERR_HTTP2_INVALID_STREAM.

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

[السجل]

الإصدار	التغييرات
v10.0.0	هذه الطريقة تُعيد الآن مرجعًا إلى ServerResponse.
v8.4.0	تمت الإضافة في: v8.4.0

• data <سلسلة> | <عازل> | <Uint8Array>
• encoding <سلسلة>
• callback <دالة>
• القيمة المُرجعة: <هذا>

تشير هذه الطريقة إلى الخادم بأن جميع رؤوس الاستجابة والهيكل قد تم إرسالها؛ يجب على الخادم اعتبار هذه الرسالة كاملة. يجب استدعاء الطريقة، response.end()، على كل استجابة.

إذا تم تحديد data، فسيكون ذلك مكافئًا لاستدعاء response.write(data, encoding) متبوعًا بـ response.end(callback).

إذا تم تحديد callback، فسيتم استدعاؤه عند الانتهاء من دفق الاستجابة.

response.finished

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

تم إهماله منذ: v13.4.0، v12.16.0

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

مستقر: 0 الثبات: 0 - مُهمل. استخدم response.writableEnded.

• <قيمة منطقية>

قيمة منطقية تشير إلى ما إذا كانت الاستجابة قد اكتملت. تبدأ بقيمة false. بعد تنفيذ response.end()، ستكون القيمة true.

response.getHeader(name)

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

• name <سلسلة>
• القيمة المُرجعة: <سلسلة>

يقرأ رأسًا تم وضعه بالفعل في قائمة الانتظار ولكن لم يتم إرساله إلى العميل. اسم الرأس غير حساس لحالة الأحرف.

const contentType = response.getHeader('content-type')

response.getHeaderNames()

مضاف في: v8.4.0

• قيمة الإرجاع: <string[]>

يرجع مصفوفة تحتوي على أسماء فريدة للرؤوس الصادرة الحالية. جميع أسماء الرؤوس صغيرة الحروف.

response.setHeader('Foo', 'bar')
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headerNames = response.getHeaderNames()
// headerNames === ['foo', 'set-cookie']

response.getHeaders()

مضاف في: v8.4.0

• قيمة الإرجاع: <Object>

يرجع نسخة سطحية من الرؤوس الصادرة الحالية. بما أن نسخة سطحية تُستخدم، يمكن تغيير قيم المصفوفة دون مكالمات إضافية لطرق وحدة http المتعلقة بالرؤوس المختلفة. مفاتيح الكائن المُرجع هي أسماء الرؤوس والقيم هي قيم الرؤوس الخاصة بها. جميع أسماء الرؤوس صغيرة الحروف.

الكائن الذي تُرجعه طريقة response.getHeaders() لا يرث نموذجياً من كائن JavaScript Object. وهذا يعني أن طرق Object النموذجية مثل obj.toString(), obj.hasOwnProperty(), وغيرها غير مُعرّفة ولن تعمل.

response.setHeader('Foo', 'bar')
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz'])

const headers = response.getHeaders()
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }

response.hasHeader(name)

مضاف في: v8.4.0

• name <string>
• قيمة الإرجاع: <boolean>

يرجع true إذا كان الرأس المحدد بواسطة name مُعيّن حاليًا في الرؤوس الصادرة. مطابقة اسم الرأس غير حساسة لحالة الأحرف.

const hasContentType = response.hasHeader('content-type')

response.headersSent

مضاف في: v8.4.0

• <boolean>

صحيح إذا تم إرسال الرؤوس، خطأ خلاف ذلك (قراءة فقط).

response.removeHeader(name)

مضاف في: v8.4.0

• name <string>

يزيل رأسًا تم وضعه في قائمة الانتظار للإرسال الضمني.

response.removeHeader('Content-Encoding')

response.req

مضاف في: v15.7.0

• <http2.Http2ServerRequest>

مرجع إلى كائن request الأصلي لـ HTTP2.

response.sendDate

مضاف في: v8.4.0

• <boolean>

عندما تكون قيمتها true، سيتم إنشاء رأس Date وإرساله تلقائيًا في الاستجابة إذا لم يكن موجودًا بالفعل في الرؤوس. القيمة الافتراضية هي true.

يجب تعطيل هذا فقط لأغراض الاختبار؛ يتطلب HTTP رأس Date في الاستجابات.

response.setHeader(name, value)

مضاف في: v8.4.0

• name <string>
• value <string> | <string[]>

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

response.setHeader('Content-Type', 'text/html; charset=utf-8')

أو

response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript'])

إن محاولة تعيين اسم حقل رأس أو قيمة تحتوي على أحرف غير صالحة سيؤدي إلى طرح استثناء TypeError.

عندما يتم تعيين الرؤوس باستخدام response.setHeader()، سيتم دمجها مع أي رؤوس تم تمريرها إلى response.writeHead()، مع إعطاء الأولوية للرؤوس الممررة إلى response.writeHead().

// تُرجع content-type = text/plain
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html; charset=utf-8')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
  res.end('ok')
})

response.setTimeout(msecs[, callback])

مضاف في: v8.4.0

• msecs <number>
• callback <Function>
• قيمة الإرجاع: <http2.Http2ServerResponse>

يُعيّن قيمة مهلة Http2Stream إلى msecs. إذا تم توفير دالة مُعالجة (callback)، فسيتم إضافتها كمُستمع لحدث 'timeout' على كائن الاستجابة.

إذا لم يتم إضافة أي مُستمع لحدث 'timeout' إلى الطلب، أو الاستجابة، أو الخادم، فسيتم تدمير Http2Stream عند انتهاء وقتها. إذا تم تعيين مُعالِج لأحداث 'timeout' الخاصة بالطلب، أو الاستجابة، أو الخادم، فيجب التعامل مع المقابس التي انتهى وقتها صراحةً.

response.socket

مضاف في: v8.4.0

• <net.Socket> | <tls.TLSSocket>

يُعيد كائن Proxy يعمل كـ net.Socket (أو tls.TLSSocket) ولكنه يطبق مُجَمِّعات، و مُعِدِّلات، و طرق بناءً على منطق HTTP/2.

سيتم استرداد خصائص destroyed, readable, و writable من response.stream و تعيينها عليها.

سيتم استدعاء طرق destroy, emit, end, on و once على response.stream.

سيتم استدعاء طريقة setTimeout على response.stream.session.

ستُلقي طرق pause, read, resume, و write خطأً برمز ERR_HTTP2_NO_SOCKET_MANIPULATION. راجع Http2Session and Sockets لمزيد من المعلومات.

سيتم توجيه جميع التفاعلات الأخرى مباشرةً إلى المقبس.

ESM

import { createServer } from 'node:http2'
const server = createServer((req, res) => {
  const ip = req.socket.remoteAddress
  const port = req.socket.remotePort
  res.end(`Your IP address is ${ip} and your source port is ${port}.`)
}).listen(3000)

CJS

const http2 = require('node:http2')
const server = http2
  .createServer((req, res) => {
    const ip = req.socket.remoteAddress
    const port = req.socket.remotePort
    res.end(`Your IP address is ${ip} and your source port is ${port}.`)
  })
  .listen(3000)

response.statusCode

مُضاف في: v8.4.0

• <number>

عند استخدام الرؤوس الضمنية (دون استدعاء response.writeHead() صراحةً)، تتحكم هذه الخاصية في رمز الحالة الذي سيتم إرساله إلى العميل عند إفراغ الرؤوس.

response.statusCode = 404

بعد إرسال رأس الاستجابة إلى العميل، تشير هذه الخاصية إلى رمز الحالة الذي تم إرساله.

response.statusMessage

مُضاف في: v8.4.0

• <string>

لا يدعم بروتوكول HTTP/2 رسالة الحالة (RFC 7540 8.1.2.4). يعيد سلسلة فارغة.

response.stream

مُضاف في: v8.4.0

• <Http2Stream>

كائن Http2Stream الذي يدعم الاستجابة.

response.writableEnded

مُضاف في: v12.9.0

• <boolean>

تكون true بعد استدعاء response.end(). لا تشير هذه الخاصية إلى ما إذا تم إفراغ البيانات، استخدم writable.writableFinished لهذا الغرض بدلاً من ذلك.

response.write(chunk[, encoding][, callback])

مُضاف في: v8.4.0

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• مُخرجات: <boolean>

إذا تم استدعاء هذه الطريقة ولم يتم استدعاء response.writeHead()، فسيتحول إلى وضع الرؤوس الضمنية ويفرغ الرؤوس الضمنية.

هذا يرسل جزءًا من جسم الاستجابة. يمكن استدعاء هذه الطريقة عدة مرات لتوفير أجزاء متعاقبة من الجسم.

في وحدة node:http، يتم حذف جسم الاستجابة عندما يكون الطلب طلبًا HEAD. وبالمثل، يجب ألا تتضمن استجابات 204 و 304 جسم رسالة.

يمكن أن يكون chunk سلسلة أو مخزن مؤقت. إذا كان chunk سلسلة، فإن المعلمة الثانية تحدد كيفية ترميزها إلى دفق بايت. افتراضيًا، يكون encoding هو 'utf8'. سيتم استدعاء callback عندما يتم إفراغ هذا الجزء من البيانات.

هذا هو جسم HTTP الخام وليس له علاقة بتشفير أجسام متعددة الأجزاء عالية المستوى التي قد يتم استخدامها.

في المرة الأولى التي يتم فيها استدعاء response.write()، سيرسل معلومات الرأس المخزنة مؤقتًا والجزء الأول من الجسم إلى العميل. في المرة الثانية التي يتم فيها استدعاء response.write()، يفترض Node.js أن البيانات ستتم دفقها، ويرسل البيانات الجديدة بشكل منفصل. وهذا هو، يتم تخزين الاستجابة مؤقتًا حتى الجزء الأول من الجسم.

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

response.writeContinue()

أضيف في: v8.4.0

يرسل حالة 100 Continue إلى العميل، مما يشير إلى أنه يجب إرسال جسم الطلب. راجع حدث 'checkContinue' على Http2Server و Http2SecureServer.

response.writeEarlyHints(hints)

أضيف في: v18.11.0

• hints <Object>

يرسل حالة 103 Early Hints إلى العميل مع رأس رابط، مما يشير إلى أن وكيل المستخدم يمكنه تحميل/الاتصال المسبق بالموارد المرتبطة. hints هو كائن يحتوي على قيم الرؤوس المراد إرسالها مع رسالة التلميحات المبكرة.

مثال

const earlyHintsLink = '</styles.css>; rel=preload; as=style'
response.writeEarlyHints({
  link: earlyHintsLink,
})

const earlyHintsLinks = ['</styles.css>; rel=preload; as=style', '</scripts.js>; rel=preload; as=script']
response.writeEarlyHints({
  link: earlyHintsLinks,
})

response.writeHead(statusCode[, statusMessage][, headers])

[السجل]

الإصدار	التغييرات
v11.10.0, v10.17.0	إرجاع this من writeHead() للسماح بالتسلسل مع end().
v8.4.0	أضيف في: v8.4.0

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• الإرجاع: <http2.Http2ServerResponse>

يرسل رأس استجابة إلى الطلب. رمز الحالة هو رمز حالة HTTP من 3 أرقام، مثل 404. الوسيطة الأخيرة، headers، هي رؤوس الاستجابة.

يرجع مرجعًا إلى Http2ServerResponse، بحيث يمكن سلسلة المكالمات.

للتوافق مع HTTP/1، يمكن تمرير statusMessage قابل للقراءة من قبل الإنسان كوسيطة ثانية. ومع ذلك، نظرًا لأن statusMessage ليس له معنى داخل HTTP/2، فلن يكون للوسيطة أي تأثير وسيتم إصدار تحذير عملية.

const body = 'hello world'
response.writeHead(200, {
  'Content-Length': Buffer.byteLength(body),
  'Content-Type': 'text/plain; charset=utf-8',
})

يتم إعطاء Content-Length بالبايت وليس الأحرف. يمكن استخدام واجهة برمجة التطبيقات Buffer.byteLength() لتحديد عدد البايتات في ترميز معين. في الرسائل الصادرة، لا يقوم Node.js بالتحقق مما إذا كان Content-Length وطول الجسم الذي يتم إرساله متساويين أم لا. ومع ذلك، عند استقبال الرسائل، سيرفض Node.js الرسائل تلقائيًا عندما لا يتطابق Content-Length مع حجم الحمولة الفعلي.

يمكن استدعاء هذه الطريقة مرة واحدة على الأكثر في رسالة قبل استدعاء response.end().

إذا تم استدعاء response.write() أو response.end() قبل استدعاء هذا، فسيتم حساب الرؤوس الضمنية/القابلة للتغيير واستدعاء هذه الدالة.

عندما يتم تعيين الرؤوس باستخدام response.setHeader()، سيتم دمجها مع أي رؤوس تم تمريرها إلى response.writeHead()، مع إعطاء الأولوية للرؤوس التي تم تمريرها إلى response.writeHead().

// يعيد content-type = text/plain
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html; charset=utf-8')
  res.setHeader('X-Foo', 'bar')
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
  res.end('ok')
})

ستؤدي محاولة تعيين اسم حقل رأس أو قيمة تحتوي على أحرف غير صالحة إلى إلقاء TypeError.

جمع بيانات قياس أداء HTTP/2

يمكن استخدام واجهة برمجة التطبيقات Performance Observer لجمع بيانات قياس أداء أساسية لكل مثيل من Http2Session و Http2Stream.

ESM

import { PerformanceObserver } from 'node:perf_hooks'

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // يطبع 'http2'
  if (entry.name === 'Http2Session') {
    // الإدخال يحتوي على إحصائيات حول Http2Session
  } else if (entry.name === 'Http2Stream') {
    // الإدخال يحتوي على إحصائيات حول Http2Stream
  }
})
obs.observe({ entryTypes: ['http2'] })

CJS

const { PerformanceObserver } = require('node:perf_hooks')

const obs = new PerformanceObserver(items => {
  const entry = items.getEntries()[0]
  console.log(entry.entryType) // يطبع 'http2'
  if (entry.name === 'Http2Session') {
    // الإدخال يحتوي على إحصائيات حول Http2Session
  } else if (entry.name === 'Http2Stream') {
    // الإدخال يحتوي على إحصائيات حول Http2Stream
  }
})
obs.observe({ entryTypes: ['http2'] })

ستكون خاصية entryType لـ PerformanceEntry مساوية لـ 'http2'.

ستكون خاصية name لـ PerformanceEntry مساوية إما لـ 'Http2Stream' أو 'Http2Session'.

إذا كانت name مساوية لـ Http2Stream، فستحتوي PerformanceEntry على الخصائص الإضافية التالية:

• bytesRead <number> عدد بايتات إطار DATA المستلمة لهذا Http2Stream.
• bytesWritten <number> عدد بايتات إطار DATA المرسلة لهذا Http2Stream.
• id <number> معرف Http2Stream المرتبط.
• timeToFirstByte <number> عدد ميلي ثانية المنقضية بين startTime لـ PerformanceEntry واستلام أول إطار DATA.
• timeToFirstByteSent <number> عدد ميلي ثانية المنقضية بين startTime لـ PerformanceEntry وإرسال أول إطار DATA.
• timeToFirstHeader <number> عدد ميلي ثانية المنقضية بين startTime لـ PerformanceEntry واستلام أول رأس.

إذا كانت name مساوية لـ Http2Session، فستحتوي PerformanceEntry على الخصائص الإضافية التالية:

• bytesRead <number> عدد البايتات المستلمة لهذا Http2Session.
• bytesWritten <number> عدد البايتات المرسلة لهذا Http2Session.
• framesReceived <number> عدد أطر HTTP/2 المستلمة بواسطة Http2Session.
• framesSent <number> عدد أطر HTTP/2 المرسلة بواسطة Http2Session.
• maxConcurrentStreams <number> الحد الأقصى لعدد التدفقات المفتوحة بالتزامن خلال عمر Http2Session.
• pingRTT <number> عدد ميلي ثانية المنقضية منذ إرسال إطار PING واستلام إقراره. يتوفر فقط إذا تم إرسال إطار PING على Http2Session.
• streamAverageDuration <number> متوسط المدة (بميلي ثانية) لجميع مثيلات Http2Stream.
• streamCount <number> عدد مثيلات Http2Stream التي تم معالجتها بواسطة Http2Session.
• type <string> إما 'server' أو 'client' لتحديد نوع Http2Session.

ملاحظة حول :authority و host

يتطلب HTTP/2 أن تحتوي الطلبات على رأس :authority الكاذب أو رأس host. يُفضّل استخدام :authority عند إنشاء طلب HTTP/2 مباشرةً، و host عند التحويل من HTTP/1 (في الخوادم الوكيلية، على سبيل المثال).

يُعيد واجهة برمجة التطبيقات المتوافقة استخدام host إذا لم يكن :authority موجودًا. راجع request.authority لمزيد من المعلومات. ومع ذلك، إذا لم تستخدم واجهة برمجة التطبيقات المتوافقة (أو استخدمت req.headers مباشرةً)، فأنت بحاجة إلى تنفيذ أي سلوك بديل بنفسك.