מי שכותב היום קוד צד שרת ב-Node.js משתמש כמעט בוודאות ב-fetch המובנה. הוא זמין גלובלית, זהה ל-API של הדפדפן ולא דורש שום תלות. אבל ההתנהגות שלו בפרודקשן שונה ממה שרוב המפתחים מניחים: אין Node.js fetch timeout כולל כברירת מחדל, וגוף תגובה שלא נקרא, בעיקר בתגובות שגיאה, עלול להשאיר חיבור תפוס ולגרום לצמיחת זיכרון.
שתי הבעיות האלה כמעט לא נראות בפיתוח מקומי. הן מתגלות כשספק חיצוני מתחיל להאט, כששרת מקבל חיבור ואז שותק, או כש-Gateway מחזיר דף 502 ב-HTML במקום JSON. התוצאה: בקשות שנתקעות דקות ארוכות, פונקציות Serverless שנחתכות על מגבלת זמן, ושירות שנחנק בלי שגיאה ברורה בלוגים.
המדריך מפרק את שתי המלכודות על בסיס התיעוד הרשמי של undici ודיונים בפרויקטים של Node.js, ובונה צעד אחר צעד wrapper מוקשח ב-TypeScript: דדליין כולל עם AbortSignal.timeout, שילוב ביטול מצד הקורא עם AbortSignal.any, ניקוז בטוח של גופי שגיאה, וכוונון Agent של undici לניהול חיבורים. בסוף יש סקריפטים לבדיקה, צ'קליסט ושאלות נפוצות.
מלכודת ראשונה: אין Node.js fetch timeout כולל
ה-fetch של Node.js מבוסס על undici ועוקב אחרי מפרט Fetch של הדפדפן. במפרט הזה אין אפשרות timeout בכלל: האובייקט RequestInit מקבל signal, אבל אין בו שדה timeout. לכן שרת שמקבל את החיבור ואז נעלם משאיר את ה-Promise במצב pending, כפי שמתואר בניתוח של bytefork.
באותו ניתוח מופיעה גם הדגמה: קריאת fetch לשרת שלא עונה, שהורצה על Node v26.2.0, עדיין הייתה ב-pending אחרי 12,020 מילישניות. זו לא תקלה של גרסה ישנה, אלא התנהגות שנגזרת מהמפרט.
headersTimeout ו-bodyTimeout: רשת הביטחון של undici
ב-Node, רשת הביטחון היחידה היא שני timeouts ברמת התעבורה של undici: headersTimeout ו-bodyTimeout. שניהם מוגדרים כברירת מחדל ל-300 שניות, כלומר חמש דקות שלמות.
חשוב להבין מה כל אחד מהם מודד:
- headersTimeout – כמה זמן מחכים לקבלת כותרות התגובה מהשרת.
- bodyTimeout – הפער בין שני chunks עוקבים של גוף התגובה, ולא הזמן הכולל. תגובה שמטפטפת בייט כל כמה שניות לעולם לא תפעיל אותו, וערך 0 מבטל אותו לגמרי (מקור).
אף אחד מהשניים אינו דדליין כולל לבקשה. גם אם מקצרים אותם, שרת שמזרים נתונים לאט מאוד עדיין יכול להחזיק את הבקשה פתוחה כמעט ללא הגבלה.
היסטוריה קצרה: מ-30 שניות ל-300
ב-2022 ערכי ברירת המחדל היו נמוכים בהרבה. Issue #1373 בפרויקט undici, מאפריל 2022, דיווח על timeout ברירת מחדל של 30 שניות. המתחזק mcollina הסכים להעלות אותו לפחות ל-120 שניות כדי להתאים להתנהגות Node.js, ופותח ה-issue ציין ש-Chrome משתמש ב-300 שניות. בהמשך הערכים הועלו ל-300.
בדיון #1989 ממרץ 2023 נאמר ש-PR שמוזג לענף 18.x העלה את שני ה-timeouts ל-300 שניות כדי להתאים ל-Chrome, ובכל זאת השואל עדיין ראה timeouts של 30 שניות. הסיבה מעולם לא הוכרעה.
המסקנה המעשית פשוטה: אין להסתמך על ברירות מחדל שמשתנות בין גרסאות ושאפילו המתחזקים לא תמיד יכולים להסביר. הגבול צריך להיות מוגדר במפורש בקוד, בכל קריאה.
AbortSignal.timeout: דדליין כולל אמיתי
הכלי הנכון לדדליין כולל הוא AbortSignal.timeout(ms). לפי bytefork, הוא מכסה את כל חיי הבקשה, מתחילתה ועד סיום קריאת הגוף. כשהזמן נגמר נזרקת DOMException בשם TimeoutError. הוא opt-in בלבד, ואין לו ערך ברירת מחדל.
AbortSignal.timeout נוסף ב-Node v17.3.0 וב-v16.14.0, כך שבכל גרסה נתמכת של Node הוא זמין.
const res = await fetch('https://api.example.com/orders', {
signal: AbortSignal.timeout(5_000),
});
const data = await res.json(); // still covered by the same 5s deadlineלמה לא פשוט setTimeout עם Promise.race? כי Promise.race מפסיק לחכות, אבל לא עוצר את העבודה. הבקשה ממשיכה להוריד נתונים ברקע, מחזיקה סוקט וממלאת באפר. AbortSignal לעומת זאת מבטל את הבקשה עצמה ומשחרר את המשאבים.
השוואה בין מנגנוני ה-timeout
מנגנון | מה הוא מודד | ברירת מחדל | יתרון מרכזי | חיסרון מרכזי |
|---|---|---|---|---|
AbortSignal.timeout(ms) | דדליין כולל, כולל קריאת הגוף | אין (opt-in) | מבטל את הבקשה בפועל, שורה אחת, שגיאה מזוהה | לא ניתן לבטל אותו מוקדם, דורש Node 17.3 ומעלה |
headersTimeout | זמן עד קבלת הכותרות | 300 שניות | תופס חיבורים תקועים ברמת התעבורה | לא חלק ממפרט fetch, דורש dispatcher מותאם |
bodyTimeout | פער בין chunks של הגוף | 300 שניות | ניתן לכוונון לכל dispatcher | מתאפס עם כל chunk, לא תופס טפטוף איטי |
AbortController עם setTimeout | מה שמוגדר ידנית | אין | עובד בסביבות ישנות, גמישות בסיבת הביטול | קל לשכוח clearTimeout, יותר קוד |
ההשוואה מבוססת על הניתוחים ב-bytefork, בדיון #1989 של undici וב-מאמר על AbortSignal ב-DEV. נקודה נוספת מ-bytefork: AbortSignal.timeout רץ על שעון נפרד מה-timeouts של התעבורה ב-undici, ולכן מה שמסתיים ראשון הוא שקובע איזו שגיאה תתקבל.
איך נראית כל שגיאה
נקודה שמבלבלת בטיפול בשגיאות fetch ב-TypeScript היא שלכל מנגנון צורת שגיאה אחרת (מקור):
- AbortSignal.timeout – DOMException שה-name שלה הוא TimeoutError.
- headersTimeout – TypeError עם ההודעה fetch failed, ו-cause.code שווה UND_ERR_HEADERS_TIMEOUT.
- bodyTimeout – TypeError עם ההודעה terminated, וקוד ייעודי שמתחיל ב-UND_ERR_BODY.
המשמעות: קוד שבודק רק name שווה AbortError יפספס timeouts, וקוד שבודק רק את ההודעה fetch failed לא יבדיל בין timeout לבין כשל DNS או חיבור שנדחה. ה-wrapper שבהמשך מנרמל את כל המקרים האלה למחלקות שגיאה ברורות.
מלכודת שנייה: גופים שלא נקראו ודליפת סוקטים ב-Node.js
הבעיה השנייה שקטה עוד יותר. התיעוד הרשמי של undici קובע שיש תמיד לצרוך או לבטל את גוף התגובה. הסיבה: ה-Garbage Collector של Node אינו אגרסיבי מספיק כדי לשחרר חיבורים בזמן, ולכן גופים שלא נקראו עלולים לגרום לדליפות חיבורים ולבקשות שנתקעות.
במילים אחרות, Response שיצא מהסקופ אינו משחרר מיד את החיבור שמאחוריו. כל עוד הזרם לא נקרא עד הסוף או בוטל, החיבור נשאר תפוס עד שה-GC יגיע אליו, ובעומס זה עלול לקחת זמן רב.
מה הראה Issue #51162
ב-Issue #51162 בפרויקט Node.js, שנפתח ב-15 בדצמבר 2023 על Node v21.4.0, הודגם שה-RSS של התהליך גדל לאורך 1,000 קריאות fetch שהגוף שלהן לא נקרא. ברגע שהגוף נצרך, למשל עם then(r => r.text()), הגדילה נעצרה.
המתחזק ronag הגדיר את ההתנהגות כצפויה, סגר את ה-issue והפנה לתיעוד ה-GC של undici. זו לא תקלה שתתוקן בגרסה הבאה, אלא חוזה שימוש: האחריות לצרוך את הגוף היא על הקוד שקורא ל-fetch.
הדפוס המסוכן: throw על !response.ok
הדפוס הנפוץ ביותר שמפעיל את הבעיה נראה תמים לגמרי:
// Anti-pattern: the error body is never read
const res = await fetch(url);
if (!res.ok) {
throw new Error(`Upstream failed: ${res.status}`);
}
return res.json();בנתיב ההצלחה הגוף נקרא דרך res.json(). אבל בנתיב השגיאה, למשל כש-Gateway מחזיר דף HTML של 502, הגוף נשאר ללא ניקוז. מאמר ב-DEV מתאר זאת כמלכודת השנייה של fetch בפרודקשן.
האירוניה היא שהדפוס הזה מזיק דווקא ברגע הגרוע ביותר: כשספק חיצוני נמצא בתקלה ומחזיר שגיאות בקצב גבוה, גופי השגיאה שלא נקראו מצטברים מהר, והשירות שלכם מתחיל להיחנק בנוסף לספק.
למה FinalizationRegistry אינו פתרון
פותח Issue #51162 הציע כעקיפה FinalizationRegistry שקורא ל-response.arrayBuffer() על גופים שלא נוצלו ברגע שאובייקט ה-Response נאסף (מקור). זה פלסטר ולא פתרון מומלץ: הוא תלוי בדיוק באותו GC שאינו מהיר מספיק, ומוסיף התנהגות קשה לחיזוי.
הדרך הנכונה היא לצרוך או לבטל את הגוף במפורש, בכל נתיב קוד, כולל נתיבי שגיאה וחריגות.
בניית fetch wrapper מוקשח ב-TypeScript
כשמבינים את שתי המלכודות, הדרישות מה-wrapper ברורות:
- כל בקשה מקבלת דדליין כולל עם AbortSignal.timeout, עם ערך ברירת מחדל סביר.
- אם הקורא מעביר signal משלו, הוא משולב עם ה-timeout ולא מחליף אותו.
- בכל תגובת שגיאה הגוף נקרא עד גבול גודל קבוע, ואז הזרם נסגר.
- כל השגיאות מנורמלות למחלקות ברורות: timeout, שגיאת HTTP ושגיאת תעבורה.
- קיימת פונקציית עזר שקוראת JSON בתוך אותו דדליין, כך שהקורא לא שוכח לצרוך את הגוף.
שילוב signals עם AbortSignal.any
ב-Route Handler או בשירות שמבוטל מבחוץ, לרוב כבר קיים signal של הקורא. AbortSignal.any משלב כמה תנאי ביטול, למשל timeout יחד עם ביטול של המשתמש, ל-signal אחד. הוא זמין ב-Node v20.3.0 וב-v18.17.0, ובדפדפנים נתמך מ-Chrome 116 ומ-Firefox 124.
const signal = AbortSignal.any([callerSignal, AbortSignal.timeout(5_000)]);התנאי שמתממש ראשון מבטל את הבקשה. ה-signal המשולב נושא את סיבת הביטול של ה-signal שהופעל, ולכן אפשר עדיין להבדיל בין TimeoutError לבין AbortError של ביטול יזום.
ניקוז או ביטול גוף שגיאה
בנתיב השגיאה יש שתי אפשרויות שהתיעוד של undici מכשיר: לצרוך את הגוף או לבטל אותו. בפועל כדאי לשלב בין השתיים: לקרוא מספר קטן של בייטים, שימושיים ללוגים (הודעת השגיאה של ה-API או תחילת דף ה-HTML), ואז לבטל את שאר הזרם.
כך לא טוענים לזיכרון דף שגיאה של מגה-בייטים, ובאותו זמן לא משאירים זרם פתוח שתלוי ב-GC.
הקוד המלא
// lib/hardened-fetch.ts
const DEFAULT_TIMEOUT_MS = 10_000;
const DEFAULT_MAX_ERROR_BODY_BYTES = 2_048;
export class FetchTimeoutError extends Error {
readonly url: string;
readonly timeoutMs: number;
constructor(url: string, timeoutMs: number, options?: { cause?: unknown }) {
super(`Request to ${url} timed out after ${timeoutMs}ms`, options);
this.name = 'FetchTimeoutError';
this.url = url;
this.timeoutMs = timeoutMs;
}
}
export class HttpError extends Error {
readonly status: number;
readonly url: string;
readonly bodySnippet: string;
constructor(status: number, url: string, bodySnippet: string) {
super(`HTTP ${status} from ${url}`);
this.name = 'HttpError';
this.status = status;
this.url = url;
this.bodySnippet = bodySnippet;
}
}
export class TransportError extends Error {
readonly url: string;
readonly code: string | undefined;
constructor(url: string, code: string | undefined, options?: { cause?: unknown }) {
super(`Transport failure for ${url}${code ? ` (${code})` : ''}`, options);
this.name = 'TransportError';
this.url = url;
this.code = code;
}
}
export interface HardenedFetchOptions extends Omit<RequestInit, 'signal'> {
timeoutMs?: number;
signal?: AbortSignal;
maxErrorBodyBytes?: number;
}
function buildSignal(timeoutMs: number, callerSignal?: AbortSignal): AbortSignal {
const timeoutSignal = AbortSignal.timeout(timeoutMs);
return callerSignal ? AbortSignal.any([callerSignal, timeoutSignal]) : timeoutSignal;
}
function hasName(err: unknown, name: string): boolean {
return typeof err === 'object' && err !== null && (err as { name?: unknown }).name === name;
}
export function normalizeError(err: unknown, url: string, timeoutMs: number): unknown {
if (hasName(err, 'TimeoutError')) {
return new FetchTimeoutError(url, timeoutMs, { cause: err });
}
if (hasName(err, 'AbortError')) {
return err; // cancelled by the caller, keep as is
}
if (err instanceof TypeError) {
const code = (err.cause as { code?: string } | undefined)?.code;
return new TransportError(url, code, { cause: err });
}
return err;
}
async function drainErrorBody(response: Response, limit: number): Promise<string> {
if (!response.body) return '';
const reader = response.body.getReader();
const chunks: Uint8Array[] = [];
let received = 0;
try {
while (received < limit) {
const { done, value } = await reader.read();
if (done) break;
chunks.push(value);
received += value.byteLength;
}
} catch {
// body failed mid-read; nothing useful to keep
} finally {
await reader.cancel().catch(() => undefined);
}
const bytes = Buffer.concat(chunks).subarray(0, limit);
return new TextDecoder().decode(bytes);
}
export async function hardenedFetch(
input: string | URL,
options: HardenedFetchOptions = {},
): Promise<Response> {
const {
timeoutMs = DEFAULT_TIMEOUT_MS,
signal: callerSignal,
maxErrorBodyBytes = DEFAULT_MAX_ERROR_BODY_BYTES,
...init
} = options;
const url = String(input);
const signal = buildSignal(timeoutMs, callerSignal);
let response: Response;
try {
response = await fetch(input, { ...init, signal });
} catch (err) {
throw normalizeError(err, url, timeoutMs);
}
if (!response.ok) {
const snippet = await drainErrorBody(response, maxErrorBodyBytes);
throw new HttpError(response.status, url, snippet);
}
return response;
}
export async function fetchJson<T>(
input: string | URL,
options: HardenedFetchOptions = {},
): Promise<T> {
const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
const response = await hardenedFetch(input, options);
try {
return (await response.json()) as T;
} catch (err) {
throw normalizeError(err, String(input), timeoutMs);
}
}כמה הערות על הקוד:
- המחלקות כתובות עם שדות מפורשים ולא עם parameter properties, כדי שהקובץ ירוץ גם עם type stripping המובנה של Node, שאינו מבצע טרנספורמציות קוד. type stripping פעיל כברירת מחדל מ-v23.6.0 ומ-v22.18.0, ונחשב יציב מ-v25.2.0 ומ-v24.12.0.
- זיהוי השגיאות נעשה לפי name ולא לפי instanceof DOMException, כדי לא להיות תלויים במימוש המחלקה בסביבת הריצה.
- ב-drainErrorBody הקריאה ל-reader.cancel() מתבצעת תמיד ב-finally, גם כשהקריאה הסתיימה וגם כשנכשלה באמצע.
- TransportError שומר את cause.code, כך שבלוגים אפשר להבדיל בין UND_ERR_HEADERS_TIMEOUT, קוד שמתחיל ב-UND_ERR_BODY, או כשלי רשת אחרים.
- hardenedFetch מחזיר Response גולמי בנתיב ההצלחה. האחריות לצרוך את הגוף עוברת לקורא, ולכן עדיף לעבוד דרך fetchJson או פונקציית עזר דומה לטקסט.
קריאת הגוף בתוך הדדליין
מכיוון ש-AbortSignal.timeout מכסה גם את קריאת הגוף, TimeoutError יכולה להיזרק מתוך response.json() ולא רק מתוך fetch. לכן fetchJson עוטף גם את שלב הקריאה ומנרמל את השגיאה. אם ה-JSON עצמו פגום, ה-SyntaxError עובר כמו שהוא, והגוף כבר נקרא במלואו.
אחרי הקריאה כדאי לאמת את מבנה הנתונים ולא לסמוך על as T בלבד. השוואה בין האפשרויות מופיעה ב-מדריך ספריות הוולידציה ל-TypeScript, ובאינטגרציות שמחזירות מזהים מספריים ארוכים כדאי להכיר גם את בעיית איבוד הדיוק ב-JSON.parse.
כשבאמת לא צריך את הגוף, למשל בבדיקת health שמסתפקת בקוד הסטטוס, יש לבטל אותו במפורש:
const res = await hardenedFetch(healthUrl, { timeoutMs: 2_000 });
await res.body?.cancel();כוונון undici Agent: חיבורים, keep-alive ו-timeouts
לפי התיעוד של undici, כברירת מחדל הפונקציות fetch, request, stream ו-pipeline של undici יוצרות חיבור חדש לכל קריאה. ה-dispatcher המומלץ לשימוש כללי הוא Agent: הוא מנהל pool של חיבורים לכל origin, וניתן להגדיר אותו גלובלית עם setGlobalDispatcher.
מעבר לניהול חיבורים, ה-Agent הוא גם המקום לשנות את headersTimeout ו-bodyTimeout. המתחזק metcoder95 הבהיר שמפרט fetch לא תומך בהגדרת timeout, והדרך לשנות את ה-timeouts של undici יחד עם fetch היא להעביר dispatcher מותאם, כלומר Agent עם הערכים הרצויים.
Agent גלובלי
// lib/http-agent.ts
import { Agent, setGlobalDispatcher } from 'undici';
export const defaultAgent = new Agent({
keepAliveTimeout: 30_000,
keepAliveMaxTimeout: 600_000,
headersTimeout: 15_000, // illustrative value
bodyTimeout: 15_000, // illustrative value
});
setGlobalDispatcher(defaultAgent);הערכים של keepAliveTimeout (30,000 מילישניות) ו-keepAliveMaxTimeout (600,000 מילישניות) לקוחים מהדוגמה בתיעוד הרשמי של undici. ערכי headersTimeout ו-bodyTimeout בקוד הם להמחשה בלבד: המקורות אינם מספקים ערכים מומלצים, וגם לא מספרים מומלצים לגודל ה-pool. את אלה יש לגזור מהתנהגות נמדדת של הספקים שאליהם פונים.
Agent לבקשה בודדת
אפשר גם להעביר dispatcher לבקשה ספציפית בתבנית fetch(url, { dispatcher: agent }) (מקור). זה שימושי כשיש ספק אחד איטי במיוחד, למשל שירות ייצוא דוחות, שזקוק ל-timeouts ארוכים יותר בלי לשנות את ההגדרה הגלובלית:
import { Agent, fetch } from 'undici';
const reportsAgent = new Agent({
keepAliveTimeout: 30_000,
keepAliveMaxTimeout: 600_000,
headersTimeout: 60_000,
bodyTimeout: 60_000,
});
const res = await fetch('https://reports.example.com/export', {
dispatcher: reportsAgent,
signal: AbortSignal.timeout(90_000),
});
if (!res.ok) {
await res.body?.cancel();
throw new Error(`Export failed: ${res.status}`);
}
const csv = await res.text();איך שני השעונים עובדים יחד
ה-Agent ו-AbortSignal.timeout לא מחליפים זה את זה, וכאמור הם רצים על שעונים נפרדים. חלוקת התפקידים המעשית:
- AbortSignal.timeout הוא הדדליין העסקי: כמה זמן הקורא מוכן לחכות בסך הכול, כולל קריאת הגוף.
- headersTimeout ו-bodyTimeout הם רשת ביטחון ברמת התעבורה, לחיבורים שנתקעים מתחת לרדאר, כולל קוד שמישהו שכח לעטוף.
- יחס בין הערכים: כשהדדליין הכולל קצר מה-timeouts של התעבורה, השגיאה שתתקבל ברוב המקרים תהיה TimeoutError מזוהה ולא TypeError כללי, וזה מקל מאוד על ניטור.
הסתייגות: undici מ-npm מול fetch המובנה
Agent ו-setGlobalDispatcher מגיעים מחבילת undici ב-npm, בעוד ה-fetch הגלובלי מגיע עם הגרסה של undici שמובנית ב-Node עצמו. שילוב בין השניים עלול להיתקל בבעיות תאימות גרסאות, נושא שהמקורות שעליהם מבוסס המדריך אינם מכסים.
לכן כדאי לבדוק את השילוב בדיוק בגרסת Node שרצה בפרודקשן. אפשרות נוספת, כמו בדוגמה למעלה, היא לייבא גם את fetch מאותה חבילת undici שממנה מגיע ה-Agent, כך ששני הצדדים יהיו מאותה גרסה. בכל מקרה, עדכון שוטף של Node חשוב גם מסיבות אבטחה, כפי שהודגם ב-חולשת http2shell ב-Node.js.
fetch ב-Next.js בפרודקשן ובאינטגרציות API
ב-Next.js הבעיות האלה מקבלות משנה תוקף, כי Route Handlers ו-Server Actions הם בדיוק המקום שבו פונים לספקים חיצוניים. חשוב לציין שהמקורות אינם כוללים הנחיות ספציפיות ל-Next.js, כמו התנהגות ה-caching, ההבדל בין Edge runtime ל-Node runtime, או האם dispatcher גלובלי משותף בין בקשות. את הנקודות האלה יש לאמת מול התיעוד של גרסת Next.js שבשימוש.
Route Handler עם דדליין וביטול מצד הלקוח
// app/api/shipping-quote/route.ts
import { fetchJson, FetchTimeoutError, HttpError, TransportError } from '@/lib/hardened-fetch';
type Quote = { price: number; currency: string };
export async function GET(request: Request) {
try {
const quote = await fetchJson<Quote>('https://shipping.example.com/v1/quote', {
timeoutMs: 5_000,
signal: request.signal,
headers: { accept: 'application/json' },
});
return Response.json(quote);
} catch (err) {
if (err instanceof FetchTimeoutError) {
return Response.json({ error: 'upstream_timeout' }, { status: 504 });
}
if (err instanceof HttpError) {
console.error('upstream error', err.status, err.bodySnippet);
return Response.json({ error: 'upstream_error' }, { status: 502 });
}
if (err instanceof TransportError) {
console.error('transport error', err.code);
return Response.json({ error: 'upstream_unreachable' }, { status: 502 });
}
throw err;
}
}ה-signal של הבקשה הנכנסת מועבר ל-wrapper ומשולב עם ה-timeout. אם סביבת הריצה מעבירה ניתוק של הלקוח דרך request.signal, הקריאה ל-upstream תבוטל יחד איתו. ואם ה-upstream איטי, הלקוח מקבל 504 מסודר תוך חמש שניות במקום לחכות ללא הגבלה.
Serverless: להחזיר תשובה במקום לחכות
בפלטפורמות Serverless יש מגבלת זמן ריצה לכל פונקציה. מאמר ב-DEV מתאר מקרה ב-Vercel שבו API איטי ב-upstream גרם לשגיאה The Serverless Function has timed out. ההמלצה שם: להחזיר תשובה ללקוח במקום לחכות ל-upstream לנצח.
מכאן נגזר כלל פשוט: הדדליין של fetch צריך להיות קצר בבירור ממגבלת הפונקציה, עם מרווח לטיפול בשגיאה, לכתיבת לוג ולהחזרת תשובה. אם בפונקציה יש כמה קריאות רצופות, צריך לחשב תקציב זמן כולל ולא רק timeout לכל קריאה.
אינטגרציות טיפוסיות בצוותים ישראליים
צוותים בישראל שבונים backend על Next.js מתממשקים לעתים קרובות לספקי סליקה, חברות משלוחים, מערכות הפקת חשבוניות וממשקים ממשלתיים או בנקאיים. שירותים כאלה עלולים להיות איטיים בשעות עומס, ולפעמים מחזירים דפי שגיאה ב-HTML במקום JSON. זה בדיוק התרחיש שבו שתי המלכודות מתממשות יחד.
כמה המלצות מעשיות:
- להגדיר timeoutMs לכל ספק לפי ההתנהגות הנמדדת שלו, ולא ערך אחד גורף לכל המערכת.
- לשמור ב-HttpError קטע קצר מגוף השגיאה. דפי שגיאה בעברית מגיעים לרוב ב-UTF-8, ו-TextDecoder מפענח אותם כראוי כל עוד החיתוך לא נופל באמצע תו; במקרה כזה יופיע תו חלופי בודד בסוף, וזה מקובל ללוג.
- לשמור מזהים, קודי שגיאה ושמות שדות באנגלית בלוגים ובדשבורדים, כדי שהטקסט לא יתהפך בתצוגת RTL.
- לשלב timeouts עם מדיניות retry זהירה. ניסיון חוזר מיידי על ספק שכבר תקוע רק מעמיק את העומס, כפי שמוסבר ב-מדריך על retry storm, backoff ו-circuit breaker. כל ניסיון צריך לקבל AbortSignal.timeout משלו, בתוך תקציב זמן כולל.
בדיקות וצ'קליסט לפרודקשן
את ההתנהגות הזאת קל לבדוק מקומית עם שרת HTTP קטן. אם גרסת Node תומכת ב-type stripping, אפשר להריץ את קבצי הבדיקה ישירות עם node test/hang.ts, בלי שלב build.
בדיקה 1: שרת שמקבל חיבור ולא עונה
// test/hang.ts
import http from 'node:http';
import type { AddressInfo } from 'node:net';
import { hardenedFetch } from '../lib/hardened-fetch.ts';
const server = http.createServer(() => {
// accept the connection and never answer
});
server.listen(0, async () => {
const { port } = server.address() as AddressInfo;
const started = Date.now();
try {
await hardenedFetch(`http://127.0.0.1:${port}/`, { timeoutMs: 1_000 });
} catch (err) {
console.log((err as Error).name, Date.now() - started, 'ms');
} finally {
server.closeAllConnections();
server.close();
}
});התוצאה הצפויה היא FetchTimeoutError אחרי כשנייה. עם fetch רגיל, אותה קריאה הייתה נשארת pending עד שאחד ה-timeouts של התעבורה היה מופעל, בדומה להדגמה של bytefork.
בדיקה 2: שרת שמטפטף נתונים
// test/trickle.ts
import http from 'node:http';
import type { AddressInfo } from 'node:net';
import { hardenedFetch } from '../lib/hardened-fetch.ts';
const server = http.createServer((_req, res) => {
res.writeHead(200, { 'content-type': 'text/plain' });
const timer = setInterval(() => res.write('.'), 1_000);
res.on('close', () => clearInterval(timer));
});
server.listen(0, async () => {
const { port } = server.address() as AddressInfo;
const started = Date.now();
try {
const res = await hardenedFetch(`http://127.0.0.1:${port}/`, { timeoutMs: 3_000 });
await res.text();
} catch (err) {
console.log((err as Error).name, Date.now() - started, 'ms');
} finally {
server.closeAllConnections();
server.close();
}
});כאן הכותרות מגיעות מיד, ונקודה אחת נשלחת בכל שנייה. bodyTimeout לא יופעל לעולם, כי כל chunk מאפס אותו. רק הדדליין הכולל של AbortSignal.timeout עוצר את הקריאה אחרי שלוש שניות, והשגיאה תהיה TimeoutError.
בדיקה 3: שגיאות 502 בלולאה
// test/error-bodies.ts
import http from 'node:http';
import type { AddressInfo } from 'node:net';
import { hardenedFetch } from '../lib/hardened-fetch.ts';
const page = '<html><body>' + 'x'.repeat(50_000) + '</body></html>';
const server = http.createServer((_req, res) => {
res.writeHead(502, { 'content-type': 'text/html' });
res.end(page);
});
server.listen(0, async () => {
const { port } = server.address() as AddressInfo;
const url = `http://127.0.0.1:${port}/`;
const mb = () => Math.round(process.memoryUsage().rss / 1024 / 1024);
console.log('rss before', mb(), 'MB');
for (let i = 0; i < 1_000; i++) {
try {
await hardenedFetch(url, { timeoutMs: 2_000 });
} catch {
// HttpError expected
}
}
console.log('rss after', mb(), 'MB');
server.closeAllConnections();
server.close();
});כדי לראות את ההבדל, כדאי להריץ גרסה שנייה של הלולאה עם fetch רגיל שבודק !res.ok וממשיך בלי לקרוא את הגוף, ולהשוות את ה-RSS. זה אותו מבנה ניסוי כמו ב-Issue #51162. המספרים המדויקים תלויים בגרסת Node ובמכונה, ולכן חשוב להסתכל על המגמה ולא על ערך בודד.
צ'קליסט הקשחה
- כל קריאת fetch בקוד צד שרת עוברת דרך wrapper אחד, ולא נקראת ישירות.
- לכל קריאה יש AbortSignal.timeout מפורש, עם ערך שמתאים לספק ולמגבלות הפלטפורמה.
- signal של הקורא, למשל של בקשה נכנסת, משולב באמצעות AbortSignal.any ולא דורס את ה-timeout.
- בכל נתיב שגיאה הגוף נקרא עד גבול קבוע ואז מבוטל.
- בנתיב הצלחה שבו הגוף לא נדרש, נקרא res.body?.cancel() במפורש.
- השגיאות מנורמלות: timeout, שגיאת HTTP ושגיאת תעבורה, עם cause.code נשמר ללוג.
- קיים Agent עם keep-alive ו-timeouts תעבורה מוגדרים, ותאימות הגרסאות שלו נבדקה בגרסת Node של הפרודקשן.
- יש בדיקות אוטומטיות לשרת תקוע, לשרת מטפטף ולשגיאות 5xx חוזרות.
מלכודות נפוצות
- Promise.race במקום AbortSignal – מפסיק לחכות אבל משאיר את הבקשה רצה ומחזיקה סוקט.
- AbortController עם setTimeout בלי clearTimeout – טיימרים שמצטברים ונשארים פעילים.
- הסתמכות על bodyTimeout כדדליין – הוא מתאפס עם כל chunk ולא יתפוס טפטוף.
- בדיקה רק של AbortError – timeout של AbortSignal.timeout מגיע כ-TimeoutError.
- throw על !res.ok בלי לקרוא את הגוף – בדיוק הדפוס שמדליף חיבורים בזמן תקלה אצל הספק.
- הנחה שברירות המחדל קבועות – הערכים השתנו מ-30 ל-300 שניות, ודיווחים על התנהגות לא עקבית לא הוכרעו.
שאלות נפוצות
מה ה-timeout ברירת המחדל של fetch ב-Node.js?
אין timeout כולל לבקשה. undici מפעיל headersTimeout ו-bodyTimeout של 300 שניות כל אחד, כרשת ביטחון ברמת התעבורה, ו-bodyTimeout מתאפס עם כל chunk של הגוף (מקור).
איך מוסיפים timeout ל-fetch?
מעבירים signal: AbortSignal.timeout(ms) ותופסים את השגיאה ששמה TimeoutError. כדי לכבד גם ביטול מצד הקורא, משלבים את שני ה-signals עם AbortSignal.any (מקור).
האם חייבים לקרוא את הגוף של תגובות שגיאה?
כן. התיעוד של undici קובע שיש תמיד לצרוך או לבטל את הגוף, כי ה-GC לא משחרר חיבורים בזמן, וגופים שלא נקראו עלולים להדליף חיבורים ולתקוע בקשות (מקור).
אפשר לשנות את headersTimeout ב-fetch המובנה של Node?
לא דרך אפשרויות fetch, כי למפרט אין הגדרה כזו. מתחזק undici ממליץ להעביר dispatcher מותאם, כלומר Agent שהוגדרו בו ה-timeouts הרצויים (מקור).
האם צמיחת הזיכרון מגופים שלא נקראו היא באג ב-Node?
המתחזקים התייחסו אליה כהתנהגות צפויה, סגרו את Issue #51162 והפנו לתיעוד ה-GC של undici. צריכה או ביטול של הגוף הם דרך השימוש המיועדת (מקור).
איך משתמשים מחדש בחיבורים עם fetch ב-Node?
יוצרים Agent של undici, שמנהל pool לכל origin, ואז קוראים ל-setGlobalDispatcher(agent) או מעבירים dispatcher לכל בקשה. בלי זה, כל קריאה של undici יוצרת חיבור חדש (מקור).
סיכום
ה-fetch המובנה של Node.js נוח, אבל ברירות המחדל שלו לא מתאימות לפרודקשן. אין Node.js fetch timeout כולל, ה-timeouts של undici עומדים על חמש דקות ואינם דדליין אמיתי, וגוף תגובה שלא נקרא, בעיקר בתגובות שגיאה, מחזיק חיבורים וזיכרון עד שה-GC מגיע אליו.
הפתרון מורכב משלושה רכיבים פשוטים: AbortSignal.timeout בכל קריאה, משולב עם signal של הקורא דרך AbortSignal.any; צריכה או ביטול של הגוף בכל נתיב, כולל שגיאות; ו-Agent של undici עם keep-alive ו-timeouts תעבורה כרשת ביטחון. עטיפה של כל אלה ב-wrapper אחד ב-TypeScript, עם מחלקות שגיאה מנורמלות ובדיקות לשרתים תקועים, הופכת את ההתנהגות לצפויה.
באפליקציות Next.js ובאינטגרציות מול ספקים חיצוניים, ההבדל מורגש בדיוק ברגע הקריטי: כשהספק בתקלה, השירות מחזיר שגיאה מסודרת תוך שניות, במקום להיחנק יחד איתו.
מקורות
- fetch() never times out — and Node hides a five-minute one (bytefork)
- Getting Started | Node.js Undici
- Memory leak when using fetch and not consuming the response body · nodejs/node #51162
- How can I increase the headersTimeout with Node.js's fetch? · nodejs/undici Discussion #1989
- Default fetch timeout too short · nodejs/undici #1373
- Stop Using Default Node.js fetch() in Production Without These Two Fixes (DEV)
- AbortSignal.timeout() and AbortSignal.any(): Cancel Any Async Call in TypeScript (DEV)
- Everything about the AbortSignals (Code Driven Development)
- Adding timeout and multiple abort signals to fetch() (DEV)






