@fastify/send

Send هي مكتبة لبث الملفات من نظام الملفات كاستجابة HTTP، وتدعم الاستجابات الجزئية (Ranges)، والتفاوض الشرطي لطلبات GET (If-Match، وIf-Unmodified-Since، وIf-None-Match، وIf-Modified-Since)، وتغطية اختبارات عالية، وأحداثًا دقيقة يمكن الاستفادة منها لاتخاذ الإجراءات المناسبة في تطبيقك أو إطار عملك.

التثبيت

هذه وحدة Node.js متاحة عبر سجل npm. يتم التثبيت باستخدام أمر npm install:

$ npm install @fastify/send

TypeScript

يجب استخدام @types/mime@3 إذا كنت ترغب في استخدام TypeScript؛ فقد أزالت @types/mime@4 أنواع mime.

$ npm install -D @types/mime@3

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

const send = require('@fastify/send')

send(req, path, [options])

وفّر statusCode وheaders وstream للمسار المحدد لإرساله إلى res. يمثّل req طلب HTTP الخاص بـ Node.js، وpath هو مسار مُرمَّز بعنوان URL للإرسال (مُرمَّز بعنوان URL، وليس مسار نظام الملفات الفعلي).

الخيارات

acceptRanges

تفعيل أو تعطيل قبول الطلبات ذات النطاقات، القيمة الافتراضية هي true. سيؤدي تعطيل هذا إلى عدم إرسال Accept-Ranges وتجاهل محتويات ترويسة الطلب Range.

cacheControl

تفعيل أو تعطيل تعيين ترويسة الاستجابة Cache-Control، القيمة الافتراضية هي true. سيؤدي تعطيل هذا إلى تجاهل خيارَي immutable وmaxAge.

contentType

افتراضيًا، تستخدم هذه المكتبة وحدة mime لتعيين Content-Type في الاستجابة بناءً على امتداد الملف المطلوب.

لتعطيل هذه الوظيفة، عيّن contentType إلى false. سيلزم تعيين ترويسة Content-Type يدويًا في حال التعطيل.

dotfiles

حدّد كيفية التعامل مع "الملفات النقطية" (dotfiles) عند مواجهتها. الملف النقطي هو ملف أو دليل يبدأ بنقطة ("."). لاحظ أن هذا الفحص يتم على المسار نفسه دون التحقق من وجود المسار على القرص. إذا تم تحديد root، فسيتم فحص الملفات النقطية الواقعة فوق الجذر فقط (أي يمكن أن يكون الجذر نفسه داخل ملف نقطي عند تعيينه إلى "deny").

• 'allow' لا معاملة خاصة للملفات النقطية.
• 'deny' إرسال 403 لأي طلب لملف نقطي.
• 'ignore' التظاهر بأن الملف النقطي غير موجود وإرجاع 404.

القيمة الافتراضية مشابهة لـ 'ignore'، باستثناء أن هذه القيمة الافتراضية لن تتجاهل الملفات داخل دليل يبدأ بنقطة، وذلك للتوافق مع الإصدارات السابقة.

end

إزاحة البايت التي ينتهي عندها التدفق، القيمة الافتراضية هي طول الملف ناقص 1. النهاية شاملة في التدفق، بمعنى أن end: 3 سيتضمن البايت الرابع في التدفق.

etag

تفعيل أو تعطيل توليد etag، القيمة الافتراضية هي true.

extensions

إذا لم يكن الملف المحدد موجودًا، فجرّب إلحاق أحد الامتدادات المحددة، بالترتيب المحدد. افتراضيًا، هذا معطّل (مضبوط على false). مثال على قيمة ستخدم ملفات HTML بلا امتداد: ['html', 'htm']. يتم تخطي هذا إذا كان الملف المطلوب يمتلك امتدادًا بالفعل.

immutable

تفعيل أو تعطيل توجيه immutable في ترويسة الاستجابة Cache-Control، القيمة الافتراضية هي false. إذا تم تعيينه إلى true، فينبغي تحديد خيار maxAge أيضًا لتمكين التخزين المؤقت. سيمنع توجيه immutable العملاء المدعومين من إجراء طلبات شرطية خلال مدة خيار maxAge للتحقق مما إذا كان الملف قد تغيّر.

index

افتراضيًا يدعم send ملفات "index.html"، لتعطيل هذا عيّن false أو لتوفير فهرس جديد مرّر سلسلة أو مصفوفة بالترتيب المفضّل.

lastModified

تفعيل أو تعطيل ترويسة Last-Modified، القيمة الافتراضية هي true. يستخدم قيمة آخر تعديل الخاصة بنظام الملفات.

maxAge

وفّر max-age بالمللي ثانية للتخزين المؤقت عبر HTTP، القيمة الافتراضية هي 0. يمكن أن يكون هذا أيضًا سلسلة مقبولة من وحدة ms.

maxContentRangeChunkSize

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

onFile

يُستدعى بالمسار المطلق للملف المحدد نهائيًا وإحصاءات نظام الملفات بعد حلّ الملف، ولكن قبل معالجة الاستجابة وإنشاء تدفق الملف. يمكن أن تكون دالة الاستدعاء متزامنة أو تُرجع وعدًا (promise). إذا أرجعت وعدًا، فإن send ينتظر حتى يُحسم. إذا رمت دالة الاستدعاء استثناءً أو رُفض الوعد الذي أرجعته، فسيتم إلغاء العملية ويرفض send().

root

خدمة الملفات نسبةً إلى path.

start

إزاحة البايت التي يبدأ عندها التدفق، القيمة الافتراضية هي 0. البداية شاملة، بمعنى أن start: 2 سيتضمن البايت الثالث في التدفق.

highWaterMark

عند توفيره، يضبط هذا الخيار الحد الأقصى لعدد البايتات التي سيحتفظ بها المخزن المؤقت الداخلي قبل إيقاف القراءات من المورد الأساسي. إذا حذفت هذا الخيار (أو مرّرت undefined)، فسيعود Node.js إلى قيمته الافتراضية المدمجة للتدفقات الثنائية القابلة للقراءة.

.mime

تصدير mime هو النسخة العامة من وحدة mime على npm.

يُستخدم هذا لتهيئة أنواع MIME المرتبطة بامتدادات الملفات بالإضافة إلى خيارات أخرى لكيفية تحديد نوع MIME للملف (مثل النوع الافتراضي المستخدم لامتداد ملف غير معروف).

التخزين المؤقت

لا يقوم بـ إجراء تخزين مؤقت داخلي، يجب عليك استخدام ذاكرة تخزين مؤقت عكسية للوكيل مثل Varnish لهذا الغرض، أو تلك الأشياء الفاخرة المسماة CDNs. إذا كانت تطبيقك صغيرًا بما يكفي ليستفيد من التخزين المؤقت في ذاكرة عقدة واحدة، فهو صغير بما يكفي لعدم حاجته إلى التخزين المؤقت على الإطلاق ;).

تصحيح الأخطاء

لتمكين مخرجات أدوات التتبع debug() صدّر NODE_DEBUG:

$ NODE_DEBUG=send node app

تشغيل الاختبارات

$ npm install
$ npm test

أمثلة

تقديم ملف محدد

هذا المثال البسيط سيرسل ملفًا محددًا إلى جميع الطلبات.

const http = require('node:http')
const send = require('send')

const server = http.createServer(async function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, '/path/to/index.html')
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)

تقديم جميع الملفات من دليل

هذا المثال البسيط سيقوم فقط بتقديم جميع الملفات في دليل معين كمستوى أعلى. على سبيل المثال، طلب GET /foo.txt سيعيد إرسال /www/public/foo.txt.

const http = require('node:http')
const parseUrl = require('parseurl')
const send = require('@fastify/send')

const server = http.createServer(async function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)

أنواع الملفات المخصصة

const http = require('node:http')
const parseUrl = require('parseurl')
const send = require('@fastify/send')

// Default unknown types to text/plain
send.mime.default_type = 'text/plain'

// Add a custom type
send.mime.define({
  'application/x-my-type': ['x-mt', 'x-mtt']
})

const server = http.createServer(function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)

عرض فهرس دليل مخصص

هذا مثال على تقديم بنية من الأدلة باستخدام دالة مخصصة لعرض قائمة محتويات دليل ما.

const http = require('node:http')
const fs = require('node:fs')
const parseUrl = require('parseurl')
const send = require('@fastify/send')