HTTP

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Codice sorgente: lib/http.js

Questo modulo, contenente sia un client che un server, può essere importato tramite require('node:http') (CommonJS) o import * as http from 'node:http' (modulo ES).

Le interfacce HTTP in Node.js sono progettate per supportare molte funzionalità del protocollo che sono state tradizionalmente difficili da usare. In particolare, messaggi di grandi dimensioni, possibilmente codificati in blocchi. L'interfaccia è attenta a non memorizzare mai in buffer intere richieste o risposte, quindi l'utente è in grado di trasmettere dati in streaming.

Le intestazioni dei messaggi HTTP sono rappresentate da un oggetto come questo:

{ "content-length": "123",
  "content-type": "text/plain",
  "connection": "keep-alive",
  "host": "example.com",
  "accept": "*/*" }

Le chiavi sono in minuscolo. I valori non vengono modificati.

Per supportare l'intero spettro di possibili applicazioni HTTP, l'API HTTP di Node.js è di livello molto basso. Si occupa solo della gestione dei flussi e dell'analisi dei messaggi. Analizza un messaggio in intestazioni e corpo, ma non analizza le intestazioni o il corpo effettivi.

Vedi message.headers per i dettagli su come vengono gestite le intestazioni duplicate.

Le intestazioni raw così come sono state ricevute vengono conservate nella proprietà rawHeaders, che è un array di [chiave, valore, chiave2, valore2, ...]. Ad esempio, l'oggetto di intestazione del messaggio precedente potrebbe avere un elenco rawHeaders simile al seguente:

[ 'ConTent-Length', '123456',
  'content-LENGTH', '123',
  'content-type', 'text/plain',
  'CONNECTION', 'keep-alive',
  'Host', 'example.com',
  'accepT', '*/*' ]

Classe: http.Agent

Aggiunto in: v0.3.4

Un Agent è responsabile della gestione della persistenza e del riutilizzo della connessione per i client HTTP. Mantiene una coda di richieste in sospeso per un determinato host e porta, riutilizzando una singola connessione socket per ciascuna fino a quando la coda non è vuota, momento in cui il socket viene distrutto o inserito in un pool in cui viene conservato per essere riutilizzato per le richieste allo stesso host e porta. La sua distruzione o il suo raggruppamento dipende dall'opzione keepAlive.

Le connessioni in pool hanno TCP Keep-Alive abilitato, ma i server possono comunque chiudere le connessioni inattive, nel qual caso verranno rimosse dal pool e verrà creata una nuova connessione quando viene effettuata una nuova richiesta HTTP per tale host e porta. I server possono anche rifiutare di consentire più richieste sulla stessa connessione, nel qual caso la connessione dovrà essere rifatta per ogni richiesta e non potrà essere raggruppata. L'Agent effettuerà comunque le richieste a quel server, ma ognuna avverrà su una nuova connessione.

Quando una connessione viene chiusa dal client o dal server, viene rimossa dal pool. Qualsiasi socket inutilizzato nel pool verrà dereferenziato in modo da non mantenere in esecuzione il processo Node.js quando non ci sono richieste in sospeso. (vedere socket.unref()).

È buona norma destroy() un'istanza di Agent quando non è più in uso, perché i socket inutilizzati consumano risorse del sistema operativo.

I socket vengono rimossi da un agente quando il socket emette un evento 'close' o un evento 'agentRemove'. Quando si intende mantenere aperta una richiesta HTTP per un lungo periodo senza mantenerla nell'agente, si può fare qualcosa del genere:

http.get(options, (res) => {
  // Fai qualcosa
}).on('socket', (socket) => {
  socket.emit('agentRemove');
});

Un agente può essere utilizzato anche per una singola richiesta. Fornendo {agent: false} come opzione alle funzioni http.get() o http.request(), verrà utilizzato un Agent usa e getta con le opzioni predefinite per la connessione client.

agent:false:

http.get({
  hostname: 'localhost',
  port: 80,
  path: '/',
  agent: false,  // Crea un nuovo agente solo per questa richiesta
}, (res) => {
  // Fai qualcosa con la risposta
});

new Agent([options])

[Cronologia]

Versione	Modifiche
v15.6.0, v14.17.0	Cambia la pianificazione predefinita da 'fifo' a 'lifo'.
v14.5.0, v12.20.0	Aggiunta l'opzione scheduling per specificare la strategia di pianificazione dei socket liberi.
v14.5.0, v12.19.0	Aggiunta l'opzione maxTotalSockets al costruttore dell'agente.
v0.3.4	Aggiunta in: v0.3.4

• options <Object> Insieme di opzioni configurabili da impostare sull'agente. Può avere i seguenti campi:
  • keepAlive <boolean> Mantiene i socket attivi anche quando non ci sono richieste in sospeso, in modo che possano essere utilizzati per richieste future senza dover ristabilire una connessione TCP. Da non confondere con il valore keep-alive dell'header Connection. L'header Connection: keep-alive viene sempre inviato quando si utilizza un agente, tranne quando l'header Connection è specificato esplicitamente o quando le opzioni keepAlive e maxSockets sono rispettivamente impostate su false e Infinity, nel qual caso verrà utilizzato Connection: close. Predefinito: false.
  • keepAliveMsecs <number> Quando si utilizza l'opzione keepAlive, specifica il ritardo iniziale per i pacchetti TCP Keep-Alive. Ignorato quando l'opzione keepAlive è false o undefined. Predefinito: 1000.
  • maxSockets <number> Numero massimo di socket da consentire per host. Se lo stesso host apre più connessioni simultanee, ogni richiesta utilizzerà un nuovo socket fino a quando non viene raggiunto il valore maxSockets. Se l'host tenta di aprire più connessioni di maxSockets, le richieste aggiuntive entreranno in una coda di richieste in sospeso e entreranno nello stato di connessione attiva quando una connessione esistente termina. Questo assicura che ci siano al massimo maxSockets connessioni attive in qualsiasi momento, da un determinato host. Predefinito: Infinity.
  • maxTotalSockets <number> Numero massimo di socket consentiti per tutti gli host in totale. Ogni richiesta utilizzerà un nuovo socket fino a quando non viene raggiunto il massimo. Predefinito: Infinity.
  • maxFreeSockets <number> Numero massimo di socket per host da lasciare aperti in uno stato libero. Rilevante solo se keepAlive è impostato su true. Predefinito: 256.
  • scheduling <string> Strategia di pianificazione da applicare quando si sceglie il socket libero successivo da utilizzare. Può essere 'fifo' o 'lifo'. La principale differenza tra le due strategie di pianificazione è che 'lifo' seleziona il socket utilizzato più recentemente, mentre 'fifo' seleziona il socket utilizzato meno recentemente. In caso di una bassa frequenza di richieste al secondo, la pianificazione 'lifo' ridurrà il rischio di scegliere un socket che potrebbe essere stato chiuso dal server a causa dell'inattività. In caso di un'alta frequenza di richieste al secondo, la pianificazione 'fifo' massimizzerà il numero di socket aperti, mentre la pianificazione 'lifo' lo manterrà il più basso possibile. Predefinito: 'lifo'.
  • timeout <number> Timeout del socket in millisecondi. Questo imposterà il timeout quando il socket viene creato.

Sono supportate anche le options in socket.connect().

Per configurarne una qualsiasi, è necessario creare un'istanza personalizzata di http.Agent.

ESM

import { Agent, request } from 'node:http';
const keepAliveAgent = new Agent({ keepAlive: true });
options.agent = keepAliveAgent;
request(options, onResponseCallback);

CJS

const http = require('node:http');
const keepAliveAgent = new http.Agent({ keepAlive: true });
options.agent = keepAliveAgent;
http.request(options, onResponseCallback);

agent.createConnection(options[, callback])

Aggiunto in: v0.11.4

• options <Object> Opzioni contenenti i dettagli della connessione. Controllare net.createConnection() per il formato delle opzioni
• callback <Function> Funzione di callback che riceve il socket creato
• Restituisce: <stream.Duplex>

Produce un socket/stream da utilizzare per le richieste HTTP.

Per impostazione predefinita, questa funzione è la stessa di net.createConnection(). Tuttavia, gli agent personalizzati possono sovrascrivere questo metodo nel caso in cui si desideri una maggiore flessibilità.

Un socket/stream può essere fornito in uno dei due modi: restituendo il socket/stream da questa funzione o passando il socket/stream a callback.

È garantito che questo metodo restituisca un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non specifichi un tipo di socket diverso da <net.Socket>.

callback ha una firma di (err, stream).

agent.keepSocketAlive(socket)

Aggiunto in: v8.1.0

• socket <stream.Duplex>

Chiamato quando socket viene scollegato da una richiesta e potrebbe essere mantenuto attivo dall'Agent. Il comportamento predefinito è:

socket.setKeepAlive(true, this.keepAliveMsecs);
socket.unref();
return true;

Questo metodo può essere sovrascritto da una particolare sottoclasse di Agent. Se questo metodo restituisce un valore falsy, il socket verrà distrutto invece di essere mantenuto per l'uso con la richiesta successiva.

L'argomento socket può essere un'istanza di <net.Socket>, una sottoclasse di <stream.Duplex>.

agent.reuseSocket(socket, request)

Aggiunto in: v8.1.0

• socket <stream.Duplex>
• request <http.ClientRequest>

Chiamato quando socket è collegato a request dopo essere stato mantenuto attivo a causa delle opzioni di keep-alive. Il comportamento predefinito è:

socket.ref();

Questo metodo può essere sovrascritto da una particolare sottoclasse di Agent.

L'argomento socket può essere un'istanza di <net.Socket>, una sottoclasse di <stream.Duplex>.

agent.destroy()

Aggiunto in: v0.11.4

Distrugge tutti i socket attualmente in uso dall'agente.

Di solito non è necessario farlo. Tuttavia, se si utilizza un agente con keepAlive abilitato, è meglio spegnere esplicitamente l'agente quando non è più necessario. Altrimenti, i socket potrebbero rimanere aperti per un periodo di tempo piuttosto lungo prima che il server li termini.

agent.freeSockets

[Cronologia]

Versione	Modifiche
v16.0.0	La proprietà ora ha un prototipo null.
v0.11.4	Aggiunto in: v0.11.4

• <Object>

Un oggetto che contiene array di socket attualmente in attesa di essere utilizzati dall'agente quando keepAlive è abilitato. Non modificare.

I socket nella lista freeSockets verranno automaticamente distrutti e rimossi dall'array in caso di 'timeout'.

agent.getName([options])

[Cronologia]

Versione	Modifiche
v17.7.0, v16.15.0	Il parametro options è ora opzionale.
v0.11.4	Aggiunto in: v0.11.4

• options <Object> Un set di opzioni che forniscono informazioni per la generazione del nome

  • host <string> Un nome di dominio o un indirizzo IP del server a cui inviare la richiesta
  • port <number> Porta del server remoto
  • localAddress <string> Interfaccia locale a cui collegarsi per le connessioni di rete quando si invia la richiesta
  • family <integer> Deve essere 4 o 6 se questo non è uguale a undefined.

• Restituisce: <string>

Ottiene un nome univoco per un set di opzioni di richiesta, per determinare se una connessione può essere riutilizzata. Per un agente HTTP, questo restituisce host:port:localAddress o host:port:localAddress:family. Per un agente HTTPS, il nome include CA, cert, ciphers e altre opzioni specifiche di HTTPS/TLS che determinano la riutilizzabilità del socket.

agent.maxFreeSockets

Aggiunto in: v0.11.7

• <number>

Impostato di default a 256. Per gli agenti con keepAlive abilitato, questo imposta il numero massimo di socket che verranno lasciati aperti nello stato libero.

agent.maxSockets

Aggiunto in: v0.3.6

• <number>

Impostato di default a Infinity. Determina quanti socket concorrenti l'agente può avere aperti per origine. L'origine è il valore restituito da agent.getName().

agent.maxTotalSockets

Aggiunto in: v14.5.0, v12.19.0

• <number>

Impostato di default a Infinity. Determina quanti socket concorrenti l'agente può avere aperti. A differenza di maxSockets, questo parametro si applica a tutte le origini.

agent.requests

[Cronologia]

Versione	Modifiche
v16.0.0	La proprietà ora ha un prototipo null.
v0.5.9	Aggiunto in: v0.5.9

• <Object>

Un oggetto che contiene code di richieste che non sono ancora state assegnate ai socket. Non modificare.

agent.sockets

[Cronologia]

Versione	Modifiche
v16.0.0	La proprietà ora ha un prototipo null.
v0.3.6	Aggiunto in: v0.3.6

• <Object>

Un oggetto che contiene array di socket attualmente in uso dall'agente. Non modificare.

Classe: http.ClientRequest

Aggiunto in: v0.1.17

• Estende: <http.OutgoingMessage>

Questo oggetto viene creato internamente e restituito da http.request(). Rappresenta una richiesta in corso la cui intestazione è già stata accodata. L'intestazione è ancora mutabile usando le API setHeader(name, value), getHeader(name), removeHeader(name). L'intestazione effettiva verrà inviata insieme al primo blocco di dati o quando si chiama request.end().

Per ottenere la risposta, aggiungi un listener per 'response' all'oggetto request. 'response' verrà emesso dall'oggetto request quando le intestazioni di risposta sono state ricevute. L'evento 'response' viene eseguito con un argomento che è un'istanza di http.IncomingMessage.

Durante l'evento 'response', è possibile aggiungere listener all'oggetto response; in particolare per ascoltare l'evento 'data'.

Se non viene aggiunto alcun gestore 'response', la risposta verrà scartata interamente. Tuttavia, se viene aggiunto un gestore eventi 'response', i dati dall'oggetto response devono essere consumati, chiamando response.read() ogni volta che c'è un evento 'readable', o aggiungendo un gestore 'data', o chiamando il metodo .resume(). Finché i dati non vengono consumati, l'evento 'end' non verrà attivato. Inoltre, finché i dati non vengono letti, consumerà memoria che può alla fine portare a un errore di "processo senza memoria".

Per compatibilità con le versioni precedenti, res emetterà 'error' solo se è registrato un listener 'error'.

Imposta l'intestazione Content-Length per limitare la dimensione del corpo della risposta. Se response.strictContentLength è impostato su true, la mancata corrispondenza del valore dell'intestazione Content-Length comporterà la generazione di un Error, identificato da code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

Il valore di Content-Length deve essere in byte, non in caratteri. Utilizzare Buffer.byteLength() per determinare la lunghezza del corpo in byte.

Event: 'abort'

Aggiunto in: v1.4.1

Deprecato a partire da: v17.0.0, v16.12.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Ascoltare invece l'evento 'close'.

Emesso quando la richiesta è stata interrotta dal client. Questo evento viene emesso solo alla prima chiamata a abort().

Event: 'close'

Aggiunto in: v0.5.4

Indica che la richiesta è stata completata o che la sua connessione sottostante è stata interrotta prematuramente (prima del completamento della risposta).

Event: 'connect'

Aggiunto in: v0.7.0

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

Emesso ogni volta che un server risponde a una richiesta con un metodo CONNECT. Se questo evento non viene ascoltato, le connessioni dei client che ricevono un metodo CONNECT verranno chiuse.

È garantito che a questo evento venga passata un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non specifichi un tipo di socket diverso da <net.Socket>.

Una coppia client e server che dimostra come ascoltare l'evento 'connect':

ESM

import { createServer, request } from 'node:http';
import { connect } from 'node:net';
import { URL } from 'node:url';

// Crea un proxy di tunneling HTTP
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connettiti a un server di origine
  const { port, hostname } = new URL(`http://${req.url}`);
  const serverSocket = connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    serverSocket.write(head);
    serverSocket.pipe(clientSocket);
    clientSocket.pipe(serverSocket);
  });
});

// Ora che il proxy è in esecuzione
proxy.listen(1337, '127.0.0.1', () => {

  // Effettua una richiesta a un proxy di tunneling
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  };

  const req = request(options);
  req.end();

  req.on('connect', (res, socket, head) => {
    console.log('got connected!');

    // Effettua una richiesta tramite un tunnel HTTP
    socket.write('GET / HTTP/1.1\r\n' +
                 'Host: www.google.com:80\r\n' +
                 'Connection: close\r\n' +
                 '\r\n');
    socket.on('data', (chunk) => {
      console.log(chunk.toString());
    });
    socket.on('end', () => {
      proxy.close();
    });
  });
});

CJS

const http = require('node:http');
const net = require('node:net');
const { URL } = require('node:url');

// Crea un proxy di tunneling HTTP
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connettiti a un server di origine
  const { port, hostname } = new URL(`http://${req.url}`);
  const serverSocket = net.connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    serverSocket.write(head);
    serverSocket.pipe(clientSocket);
    clientSocket.pipe(serverSocket);
  });
});

// Ora che il proxy è in esecuzione
proxy.listen(1337, '127.0.0.1', () => {

  // Effettua una richiesta a un proxy di tunneling
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  };

  const req = http.request(options);
  req.end();

  req.on('connect', (res, socket, head) => {
    console.log('got connected!');

    // Effettua una richiesta tramite un tunnel HTTP
    socket.write('GET / HTTP/1.1\r\n' +
                 'Host: www.google.com:80\r\n' +
                 'Connection: close\r\n' +
                 '\r\n');
    socket.on('data', (chunk) => {
      console.log(chunk.toString());
    });
    socket.on('end', () => {
      proxy.close();
    });
  });
});

Evento: 'continue'

Aggiunto in: v0.3.2

Emesso quando il server invia una risposta HTTP '100 Continue', di solito perché la richiesta conteneva 'Expect: 100-continue'. Questa è un'istruzione che indica al client di inviare il corpo della richiesta.

Evento: 'finish'

Aggiunto in: v0.3.6

Emesso quando la richiesta è stata inviata. Più precisamente, questo evento viene emesso quando l'ultimo segmento delle intestazioni e del corpo della risposta sono stati passati al sistema operativo per la trasmissione sulla rete. Non implica che il server abbia ancora ricevuto qualcosa.

Evento: 'information'

Aggiunto in: v10.0.0

• info <Oggetto>
  • httpVersion <stringa>
  • httpVersionMajor <intero>
  • httpVersionMinor <intero>
  • statusCode <intero>
  • statusMessage <stringa>
  • headers <Oggetto>
  • rawHeaders <stringa[]>

Emesso quando il server invia una risposta intermedia 1xx (escluso l'aggiornamento 101). I listener di questo evento riceveranno un oggetto contenente la versione HTTP, il codice di stato, il messaggio di stato, l'oggetto intestazioni chiave-valore e l'array con i nomi delle intestazioni non elaborate seguiti dai rispettivi valori.

ESM

import { request } from 'node:http';

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
};

// Make a request
const req = request(options);
req.end();

req.on('information', (info) => {
  console.log(`Got information prior to main response: ${info.statusCode}`);
});

CJS

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

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
};

// Make a request
const req = http.request(options);
req.end();

req.on('information', (info) => {
  console.log(`Got information prior to main response: ${info.statusCode}`);
});

Gli stati di aggiornamento 101 non attivano questo evento a causa della loro interruzione dalla tradizionale catena di richiesta/risposta HTTP, come i socket web, gli aggiornamenti TLS in loco o HTTP 2.0. Per essere avvisati delle notifiche di aggiornamento 101, ascoltare invece l'evento 'upgrade'.

Evento: 'response'

Aggiunto in: v0.1.0

• response <http.IncomingMessage>

Emesso quando viene ricevuta una risposta a questa richiesta. Questo evento viene emesso solo una volta.

Evento: 'socket'

Aggiunto in: v0.5.3

• socket <stream.Duplex>

È garantito che a questo evento venga passato un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non specifichi un tipo di socket diverso da <net.Socket>.

Evento: 'timeout'

Aggiunto in: v0.7.8

Emesso quando il socket sottostante va in timeout a causa di inattività. Questo notifica solo che il socket è stato inattivo. La richiesta deve essere distrutta manualmente.

Vedi anche: request.setTimeout().

Evento: 'upgrade'

Aggiunto in: v0.1.94

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

Emesso ogni volta che un server risponde a una richiesta con un upgrade. Se questo evento non viene ascoltato e il codice di stato della risposta è 101 Switching Protocols, le connessioni dei client che ricevono un header di upgrade verranno chiuse.

È garantito che a questo evento venga passato un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non specifichi un tipo di socket diverso da <net.Socket>.

Una coppia client-server che dimostra come ascoltare l'evento 'upgrade'.

ESM

import http from 'node:http';
import process from 'node:process';

// Create an HTTP server
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
server.on('upgrade', (req, socket, head) => {
  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

  socket.pipe(socket); // echo back
});

// Now that server is running
server.listen(1337, '127.0.0.1', () => {

  // make a request
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket',
    },
  };

  const req = http.request(options);
  req.end();

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('got upgraded!');
    socket.end();
    process.exit(0);
  });
});

CJS

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

// Create an HTTP server
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
server.on('upgrade', (req, socket, head) => {
  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

  socket.pipe(socket); // echo back
});

// Now that server is running
server.listen(1337, '127.0.0.1', () => {

  // make a request
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket',
    },
  };

  const req = http.request(options);
  req.end();

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('got upgraded!');
    socket.end();
    process.exit(0);
  });
});

request.abort()

Aggiunto in: v0.3.8

Deprecato da: v14.1.0, v13.14.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Utilizzare invece request.destroy().

Marca la richiesta come interrotta. La chiamata a questo metodo farà sì che i dati rimanenti nella risposta vengano scartati e il socket venga distrutto.

request.aborted

[Cronologia]

Versione	Modifiche
v17.0.0, v16.12.0	Deprecato da: v17.0.0, v16.12.0
v11.0.0	La proprietà aborted non è più un numero di timestamp.
v0.11.14	Aggiunto in: v0.11.14

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Controllare invece request.destroyed.

• <boolean>

La proprietà request.aborted sarà true se la richiesta è stata interrotta.

request.connection

Aggiunto in: v0.3.0

Deprecato da: v13.0.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Utilizzare request.socket.

• <stream.Duplex>

Vedere request.socket.

request.cork()

Aggiunto in: v13.2.0, v12.16.0

Vedere writable.cork().

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

[Cronologia]

Versione	Modifiche
v15.0.0	Il parametro data può ora essere un Uint8Array.
v10.0.0	Questo metodo ora restituisce un riferimento a ClientRequest.
v0.1.90	Aggiunto in: v0.1.90

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Restituisce: <this>

Termina l'invio della richiesta. Se delle parti del corpo non sono state inviate, le invierà al flusso. Se la richiesta è chunked, questo invierà il terminatore '0\r\n\r\n'.

Se data è specificato, è equivalente a chiamare request.write(data, encoding) seguito da request.end(callback).

Se callback è specificato, verrà chiamato quando il flusso di richiesta è terminato.

request.destroy([error])

[Cronologia]

Versione	Modifiche
v14.5.0	La funzione restituisce this per coerenza con altri stream Readable.
v0.3.0	Aggiunto in: v0.3.0

• error <Error> Opzionale, un errore da emettere con l'evento 'error'.
• Restituisce: <this>

Distrugge la richiesta. Facoltativamente, emette un evento 'error' ed emette un evento 'close'. La chiamata a questo metodo farà sì che i dati rimanenti nella risposta vengano eliminati e che il socket venga distrutto.

Vedi writable.destroy() per ulteriori dettagli.

request.destroyed

Aggiunto in: v14.1.0, v13.14.0

• <boolean>

È true dopo che request.destroy() è stato chiamato.

Vedi writable.destroyed per ulteriori dettagli.

request.finished

Aggiunto in: v0.0.1

Deprecato dal: v13.4.0, v12.16.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Utilizzare request.writableEnded.

• <boolean>

La proprietà request.finished sarà true se request.end() è stato chiamato. request.end() verrà chiamato automaticamente se la richiesta è stata avviata tramite http.get().

request.flushHeaders()

Aggiunto in: v1.6.0

Scarica gli header della richiesta.

Per motivi di efficienza, Node.js normalmente memorizza nel buffer gli header della richiesta finché non viene chiamato request.end() o non viene scritto il primo blocco di dati della richiesta. Quindi tenta di impacchettare gli header della richiesta e i dati in un singolo pacchetto TCP.

Questo è in genere desiderato (risparmia un round-trip TCP), ma non quando i primi dati non vengono inviati fino a molto tempo dopo. request.flushHeaders() aggira l'ottimizzazione e avvia la richiesta.

request.getHeader(name)

Aggiunto in: v1.6.0

• name <stringa>
• Restituisce: <qualsiasi>

Legge un header sulla richiesta. Il nome non fa distinzione tra maiuscole e minuscole. Il tipo del valore di ritorno dipende dagli argomenti forniti a request.setHeader().

request.setHeader('content-type', 'text/html');
request.setHeader('Content-Length', Buffer.byteLength(body));
request.setHeader('Cookie', ['type=ninja', 'language=javascript']);
const contentType = request.getHeader('Content-Type');
// 'contentType' è 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' è di tipo number
const cookie = request.getHeader('Cookie');
// 'cookie' è di tipo string[]

request.getHeaderNames()

Aggiunto in: v7.7.0

• Restituisce: <stringa[]>

Restituisce un array contenente i nomi univoci degli header in uscita correnti. Tutti i nomi degli header sono in minuscolo.

request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);

const headerNames = request.getHeaderNames();
// headerNames === ['foo', 'cookie']

request.getHeaders()

Aggiunto in: v7.7.0

• Restituisce: <Oggetto>

Restituisce una copia superficiale degli header in uscita correnti. Poiché viene utilizzata una copia superficiale, i valori dell'array possono essere modificati senza ulteriori chiamate a vari metodi del modulo http relativi agli header. Le chiavi dell'oggetto restituito sono i nomi degli header e i valori sono i rispettivi valori degli header. Tutti i nomi degli header sono in minuscolo.

L'oggetto restituito dal metodo request.getHeaders() non eredita prototipicamente dall'Oggetto JavaScript. Ciò significa che i tipici metodi Oggetto come obj.toString(), obj.hasOwnProperty() e altri non sono definiti e non funzioneranno.

request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);

const headers = request.getHeaders();
// headers === { foo: 'bar', 'cookie': ['foo=bar', 'bar=baz'] }

request.getRawHeaderNames()

Aggiunto in: v15.13.0, v14.17.0

• Restituisce: <string[]>

Restituisce un array contenente i nomi univoci degli header raw in uscita correnti. I nomi degli header vengono restituiti con il loro casing esatto impostato.

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

const headerNames = request.getRawHeaderNames();
// headerNames === ['Foo', 'Set-Cookie']

request.hasHeader(name)

Aggiunto in: v7.7.0

• name <string>
• Restituisce: <boolean>

Restituisce true se l'header identificato da name è attualmente impostato negli header in uscita. La corrispondenza del nome dell'header non fa distinzione tra maiuscole e minuscole.

const hasContentType = request.hasHeader('content-type');

request.maxHeadersCount

• <number> Predefinito: 2000

Limita il numero massimo di header di risposta. Se impostato su 0, non verrà applicato alcun limite.

request.path

Aggiunto in: v0.4.0

• <string> Il percorso della richiesta.

request.method

Aggiunto in: v0.1.97

• <string> Il metodo della richiesta.

request.host

Aggiunto in: v14.5.0, v12.19.0

• <string> L'host della richiesta.

request.protocol

Aggiunto in: v14.5.0, v12.19.0

• <string> Il protocollo della richiesta.

request.removeHeader(name)

Aggiunto in: v1.6.0

• name <string>

Rimuove un header già definito nell'oggetto headers.

request.removeHeader('Content-Type');

request.reusedSocket

Aggiunto in: v13.0.0, v12.16.0

• <boolean> Indica se la richiesta viene inviata tramite un socket riutilizzato.

Quando si invia una richiesta tramite un agent con keep-alive abilitato, il socket sottostante potrebbe essere riutilizzato. Tuttavia, se il server chiude la connessione in un momento sfortunato, il client potrebbe incorrere in un errore 'ECONNRESET'.

ESM

import http from 'node:http';

// Il server ha un timeout di keep-alive di 5 secondi per impostazione predefinita
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adattamento di un agent keep-alive
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Non fare nulla
    });
  });
}, 5000); // Invio della richiesta a intervalli di 5 secondi, quindi è facile raggiungere il timeout di inattività

CJS

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

// Il server ha un timeout di keep-alive di 5 secondi per impostazione predefinita
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adattamento di un agent keep-alive
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Non fare nulla
    });
  });
}, 5000); // Invio della richiesta a intervalli di 5 secondi, quindi è facile raggiungere il timeout di inattività

Contrassegnando una richiesta che ha riutilizzato o meno il socket, possiamo eseguire un nuovo tentativo automatico in base ad esso.

ESM

import http from 'node:http';
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // Controlla se è necessario un nuovo tentativo
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

CJS

const http = require('node:http');
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // Controlla se è necessario un nuovo tentativo
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

request.setHeader(name, value)

Aggiunto in: v1.6.0

• name <stringa>
• value <qualsiasi>

Imposta un singolo valore di intestazione per l'oggetto headers. Se questa intestazione esiste già nelle intestazioni da inviare, il suo valore verrà sostituito. Utilizzare un array di stringhe qui per inviare più intestazioni con lo stesso nome. I valori non stringa verranno memorizzati senza modifiche. Pertanto, request.getHeader() può restituire valori non stringa. Tuttavia, i valori non stringa verranno convertiti in stringhe per la trasmissione di rete.

request.setHeader('Content-Type', 'application/json');

oppure

request.setHeader('Cookie', ['type=ninja', 'language=javascript']);

Quando il valore è una stringa, verrà generata un'eccezione se contiene caratteri al di fuori della codifica latin1.

Se devi passare caratteri UTF-8 nel valore, codifica il valore utilizzando lo standard RFC 8187.

const filename = 'Rock 🎵.txt';
request.setHeader('Content-Disposition', `attachment; filename*=utf-8''${encodeURIComponent(filename)}`);

request.setNoDelay([noDelay])

Aggiunto in: v0.5.9

• noDelay <boolean>

Una volta che un socket è assegnato a questa richiesta ed è connesso, verrà chiamato socket.setNoDelay().

request.setSocketKeepAlive([enable][, initialDelay])

Aggiunto in: v0.5.9

• enable <boolean>
• initialDelay <number>

Una volta che un socket è assegnato a questa richiesta ed è connesso, verrà chiamato socket.setKeepAlive().

request.setTimeout(timeout[, callback])

[Cronologia]

Versione	Modifiche
v9.0.0	Imposta in modo coerente il timeout del socket solo quando il socket si connette.
v0.5.9	Aggiunto in: v0.5.9

• timeout <number> Millisecondi prima che una richiesta vada in timeout.
• callback <Function> Funzione opzionale da chiamare quando si verifica un timeout. Come il binding all'evento 'timeout'.
• Restituisce: <http.ClientRequest>

Una volta che un socket viene assegnato a questa richiesta ed è connesso, verrà chiamato socket.setTimeout().

request.socket

Aggiunto in: v0.3.0

• <stream.Duplex>

Riferimento al socket sottostante. Di solito gli utenti non vorranno accedere a questa proprietà. In particolare, il socket non emetterà eventi 'readable' a causa del modo in cui il parser del protocollo si collega al socket.

ESM

import http from 'node:http';
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Il tuo indirizzo IP è ${ip} e la tua porta di origine è ${port}.`);
  // Consume response object
});

CJS

const http = require('node:http');
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Il tuo indirizzo IP è ${ip} e la tua porta di origine è ${port}.`);
  // Consume response object
});

Questa proprietà è garantita essere un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non abbia specificato un tipo di socket diverso da <net.Socket>.

request.uncork()

Aggiunto in: v13.2.0, v12.16.0

Vedi writable.uncork().

request.writableEnded

Aggiunto in: v12.9.0

• <boolean>

È true dopo che è stato chiamato request.end(). Questa proprietà non indica se i dati sono stati scaricati, per questo usa invece request.writableFinished.

request.writableFinished

Aggiunto in: v12.7.0

• <boolean>

È true se tutti i dati sono stati scaricati nel sistema sottostante, immediatamente prima che venga emesso l'evento 'finish'.

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

[Cronologia]

Versione	Modifiche
v15.0.0	Il parametro chunk ora può essere un Uint8Array.
v0.1.29	Aggiunto in: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Restituisce: <boolean>

Invia un chunk del body. Questo metodo può essere chiamato più volte. Se non è impostato Content-Length, i dati verranno automaticamente codificati nella codifica di trasferimento HTTP Chunked, in modo che il server sappia quando i dati terminano. L'intestazione Transfer-Encoding: chunked viene aggiunta. Chiamare request.end() è necessario per terminare l'invio della richiesta.

L'argomento encoding è opzionale e si applica solo quando chunk è una stringa. Il valore predefinito è 'utf8'.

L'argomento callback è opzionale e verrà chiamato quando questo chunk di dati viene scaricato, ma solo se il chunk non è vuoto.

Restituisce true se tutti i dati sono stati scaricati con successo nel buffer del kernel. Restituisce false se tutti o parte dei dati sono stati accodati nella memoria utente. 'drain' verrà emesso quando il buffer sarà di nuovo libero.

Quando la funzione write viene chiamata con una stringa o un buffer vuoto, non fa nulla e attende ulteriori input.

Classe: http.Server

Aggiunto in: v0.1.17

• Estende: <net.Server>

Evento: 'checkContinue'

Aggiunto in: v0.3.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Emesso ogni volta che viene ricevuta una richiesta con un Expect: 100-continue HTTP. Se questo evento non viene ascoltato, il server risponderà automaticamente con un 100 Continue come appropriato.

La gestione di questo evento comporta la chiamata a response.writeContinue() se il client deve continuare a inviare il corpo della richiesta, oppure la generazione di una risposta HTTP appropriata (ad es. 400 Bad Request) se il client non deve continuare a inviare il corpo della richiesta.

Quando questo evento viene emesso e gestito, l'evento 'request' non verrà emesso.

Evento: 'checkExpectation'

Aggiunto in: v5.5.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Emesso ogni volta che viene ricevuta una richiesta con un header Expect HTTP, dove il valore non è 100-continue. Se questo evento non viene ascoltato, il server risponderà automaticamente con un 417 Expectation Failed come appropriato.

Quando questo evento viene emesso e gestito, l'evento 'request' non verrà emesso.

Evento: 'clientError'

[Cronologia]

Versione	Modifiche
v12.0.0	Il comportamento predefinito restituirà un 431 Request Header Fields Too Large se si verifica un errore HPE_HEADER_OVERFLOW.
v9.4.0	rawPacket è il buffer corrente appena analizzato. L'aggiunta di questo buffer all'oggetto errore dell'evento 'clientError' consente agli sviluppatori di registrare il pacchetto danneggiato.
v6.0.0	L'azione predefinita di chiamare .destroy() sul socket non avrà più luogo se ci sono listener collegati per 'clientError'.
v0.1.94	Aggiunto in: v0.1.94

• exception <Error>
• socket <stream.Duplex>

Se una connessione client emette un evento 'error', verrà inoltrato qui. Il listener di questo evento è responsabile della chiusura/distruzione del socket sottostante. Ad esempio, si potrebbe desiderare di chiudere più elegantemente il socket con una risposta HTTP personalizzata invece di interrompere bruscamente la connessione. Il socket deve essere chiuso o distrutto prima che il listener termini.

È garantito che questo evento venga passato a un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non specifichi un tipo di socket diverso da <net.Socket>.

Il comportamento predefinito consiste nel provare a chiudere il socket con un HTTP '400 Bad Request' o un HTTP '431 Request Header Fields Too Large' nel caso di un errore HPE_HEADER_OVERFLOW. Se il socket non è scrivibile o le intestazioni dell'attuale http.ServerResponse allegato sono state inviate, viene immediatamente distrutto.

socket è l'oggetto net.Socket da cui ha avuto origine l'errore.

ESM

import http from 'node:http';

const server = http.createServer((req, res) => {
  res.end();
});
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});
server.listen(8000);

CJS

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

const server = http.createServer((req, res) => {
  res.end();
});
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});
server.listen(8000);

Quando si verifica l'evento 'clientError', non ci sono oggetti request o response, quindi qualsiasi risposta HTTP inviata, incluse le intestazioni di risposta e il payload, deve essere scritta direttamente sull'oggetto socket. Bisogna fare attenzione per assicurarsi che la risposta sia un messaggio di risposta HTTP formattato correttamente.

err è un'istanza di Error con due colonne extra:

• bytesParsed: il conteggio dei byte del pacchetto di richiesta che Node.js potrebbe aver analizzato correttamente;
• rawPacket: il pacchetto raw della richiesta corrente.

In alcuni casi, il client ha già ricevuto la risposta e/o il socket è già stato distrutto, come nel caso degli errori ECONNRESET. Prima di provare a inviare dati al socket, è meglio verificare che sia ancora scrivibile.

server.on('clientError', (err, socket) => {
  if (err.code === 'ECONNRESET' || !socket.writable) {
    return;
  }

  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});

Evento: 'close'

Aggiunto in: v0.1.4

Emesso quando il server si chiude.

Evento: 'connect'

Aggiunto in: v0.7.0

• request <http.IncomingMessage> Argomenti per la richiesta HTTP, come nell'evento 'request'
• socket <stream.Duplex> Socket di rete tra il server e il client
• head <Buffer> Il primo pacchetto del flusso di tunneling (può essere vuoto)

Emesso ogni volta che un client richiede un metodo HTTP CONNECT. Se questo evento non viene ascoltato, le connessioni dei client che richiedono un metodo CONNECT verranno chiuse.

È garantito che a questo evento venga passato un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non specifichi un tipo di socket diverso da <net.Socket>.

Dopo che questo evento è stato emesso, il socket della richiesta non avrà un listener di eventi 'data', il che significa che dovrà essere associato per gestire i dati inviati al server su quel socket.

Evento: 'connection'

Aggiunto in: v0.1.0

• socket <stream.Duplex>

Questo evento viene emesso quando viene stabilito un nuovo flusso TCP. socket è in genere un oggetto di tipo net.Socket. Di solito gli utenti non vorranno accedere a questo evento. In particolare, il socket non emetterà eventi 'readable' a causa del modo in cui il parser del protocollo si collega al socket. È possibile accedere al socket anche in request.socket.

Questo evento può anche essere emesso esplicitamente dagli utenti per iniettare connessioni nel server HTTP. In tal caso, può essere passato qualsiasi flusso Duplex.

Se qui viene chiamato socket.setTimeout(), il timeout verrà sostituito con server.keepAliveTimeout quando il socket ha servito una richiesta (se server.keepAliveTimeout è diverso da zero).

È garantito che a questo evento venga passato un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non specifichi un tipo di socket diverso da <net.Socket>.

Evento: 'dropRequest'

Aggiunto in: v18.7.0, v16.17.0

• request <http.IncomingMessage> Argomenti per la richiesta HTTP, come nell'evento 'request'
• socket <stream.Duplex> Socket di rete tra il server e il client

Quando il numero di richieste su un socket raggiunge la soglia di server.maxRequestsPerSocket, il server abbandonerà le nuove richieste ed emetterà invece l'evento 'dropRequest', quindi invierà 503 al client.

Evento: 'request'

Aggiunto in: v0.1.0

• request <http.IncomingMessage>
• response <http.ServerResponse>

Emesso ogni volta che c'è una richiesta. Ci possono essere più richieste per connessione (nel caso di connessioni HTTP Keep-Alive).

Evento: 'upgrade'

[Cronologia]

Versione	Modifiche
v10.0.0	Non ascoltare questo evento non causa più la distruzione del socket se un client invia un header Upgrade.
v0.1.94	Aggiunto in: v0.1.94

• request <http.IncomingMessage> Argomenti per la richiesta HTTP, come nell'evento 'request'
• socket <stream.Duplex> Socket di rete tra il server e il client
• head <Buffer> Il primo pacchetto dello stream aggiornato (può essere vuoto)

Emesso ogni volta che un client richiede un upgrade HTTP. L'ascolto di questo evento è opzionale e i client non possono insistere su un cambio di protocollo.

Dopo che questo evento è stato emesso, il socket della richiesta non avrà un listener di eventi 'data', il che significa che dovrà essere collegato per gestire i dati inviati al server su quel socket.

È garantito che a questo evento venga passata un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non specifichi un tipo di socket diverso da <net.Socket>.

server.close([callback])

[Cronologia]

Versione	Modifiche
v19.0.0	Il metodo chiude le connessioni inattive prima di restituire.
v0.1.90	Aggiunto in: v0.1.90

• callback <Function>

Impedisce al server di accettare nuove connessioni e chiude tutte le connessioni connesse a questo server che non stanno inviando una richiesta o aspettando una risposta. Vedere net.Server.close().

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

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
// Chiudi il server dopo 10 secondi
setTimeout(() => {
  server.close(() => {
    console.log('server sulla porta 8000 chiuso correttamente');
  });
}, 10000);

server.closeAllConnections()

Aggiunto in: v18.2.0

Chiude tutte le connessioni HTTP(S) stabilite connesse a questo server, incluse le connessioni attive connesse a questo server che stanno inviando una richiesta o aspettando una risposta. Questo non distrugge i socket aggiornati a un protocollo diverso, come WebSocket o HTTP/2.

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

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
// Chiudi il server dopo 10 secondi
setTimeout(() => {
  server.close(() => {
    console.log('server sulla porta 8000 chiuso correttamente');
  });
  // Chiude tutte le connessioni, assicurandosi che il server si chiuda correttamente
  server.closeAllConnections();
}, 10000);

server.closeIdleConnections()

Aggiunto in: v18.2.0

Chiude tutte le connessioni connesse a questo server che non stanno inviando una richiesta o aspettando una risposta.

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

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
// Chiudi il server dopo 10 secondi
setTimeout(() => {
  server.close(() => {
    console.log('server sulla porta 8000 chiuso correttamente');
  });
  // Chiude le connessioni inattive, come le connessioni keep-alive. Il server si chiuderà
  // una volta terminate le connessioni attive rimanenti
  server.closeIdleConnections();
}, 10000);

server.headersTimeout

[Cronologia]

Versione	Modifiche
v19.4.0, v18.14.0	Il valore predefinito è ora impostato sul minimo tra 60000 (60 secondi) o requestTimeout.
v11.3.0, v10.14.0	Aggiunto in: v11.3.0, v10.14.0

• <number> Predefinito: Il minimo tra server.requestTimeout o 60000.

Limita la quantità di tempo che il parser attenderà per ricevere le intestazioni HTTP complete.

Se il timeout scade, il server risponde con lo stato 408 senza inoltrare la richiesta al listener delle richieste e quindi chiude la connessione.

Deve essere impostato su un valore diverso da zero (ad esempio 120 secondi) per proteggere da potenziali attacchi Denial-of-Service nel caso in cui il server venga distribuito senza un reverse proxy davanti.

server.listen()

Avvia il server HTTP in ascolto di connessioni. Questo metodo è identico a server.listen() da net.Server.

server.listening

Aggiunto in: v5.7.0

• <boolean> Indica se il server è in ascolto di connessioni.

server.maxHeadersCount

Aggiunto in: v0.7.0

• <number> Predefinito: 2000

Limita il numero massimo di intestazioni in entrata. Se impostato su 0, non verrà applicato alcun limite.

server.requestTimeout

[Cronologia]

Versione	Modifiche
v18.0.0	Il timeout di richiesta predefinito è cambiato da nessun timeout a 300s (5 minuti).
v14.11.0	Aggiunto in: v14.11.0

• <number> Predefinito: 300000

Imposta il valore di timeout in millisecondi per la ricezione dell'intera richiesta dal client.

Se il timeout scade, il server risponde con lo stato 408 senza inoltrare la richiesta al listener delle richieste e quindi chiude la connessione.

Deve essere impostato su un valore diverso da zero (ad esempio 120 secondi) per proteggere da potenziali attacchi Denial-of-Service nel caso in cui il server venga distribuito senza un reverse proxy davanti.

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

[Cronologia]

Versione	Modifiche
v13.0.0	Il timeout predefinito è cambiato da 120s a 0 (nessun timeout).
v0.9.12	Aggiunto in: v0.9.12

• msecs <number> Predefinito: 0 (nessun timeout)
• callback <Function>
• Restituisce: <http.Server>

Imposta il valore di timeout per i socket ed emette un evento 'timeout' sull'oggetto Server, passando il socket come argomento, se si verifica un timeout.

Se è presente un listener di eventi 'timeout' sull'oggetto Server, verrà chiamato con il socket scaduto come argomento.

Per impostazione predefinita, il Server non imposta il timeout dei socket. Tuttavia, se viene assegnata una callback all'evento 'timeout' del Server, i timeout devono essere gestiti esplicitamente.

server.maxRequestsPerSocket

Aggiunto in: v16.10.0

• <number> Richieste per socket. Predefinito: 0 (nessun limite)

Il numero massimo di richieste che un socket può gestire prima di chiudere la connessione keep-alive.

Un valore di 0 disabiliterà il limite.

Quando viene raggiunto il limite, imposterà il valore dell'intestazione Connection su close, ma in realtà non chiuderà la connessione, le richieste successive inviate dopo il raggiungimento del limite riceveranno 503 Servizio non disponibile come risposta.

server.timeout

[Cronologia]

Versione	Modifiche
v13.0.0	Il timeout predefinito è cambiato da 120s a 0 (nessun timeout).
v0.9.12	Aggiunto in: v0.9.12

• <number> Timeout in millisecondi. Predefinito: 0 (nessun timeout)

Il numero di millisecondi di inattività prima che si presuma che un socket sia scaduto.

Un valore di 0 disabiliterà il comportamento di timeout sulle connessioni in entrata.

La logica del timeout del socket viene impostata sulla connessione, quindi la modifica di questo valore influisce solo sulle nuove connessioni al server, non su quelle esistenti.

server.keepAliveTimeout

Aggiunto in: v8.0.0

• <number> Timeout in millisecondi. Predefinito: 5000 (5 secondi).

Il numero di millisecondi di inattività che un server deve attendere per ulteriori dati in entrata, dopo aver terminato di scrivere l'ultima risposta, prima che un socket venga distrutto. Se il server riceve nuovi dati prima che il timeout keep-alive sia scaduto, reimposterà il timeout di inattività regolare, ovvero server.timeout.

Un valore di 0 disabiliterà il comportamento del timeout keep-alive sulle connessioni in entrata. Un valore di 0 fa sì che il server http si comporti in modo simile alle versioni di Node.js precedenti alla 8.0.0, che non avevano un timeout keep-alive.

La logica del timeout del socket è impostata sulla connessione, quindi la modifica di questo valore influisce solo sulle nuove connessioni al server, non su quelle esistenti.

server[Symbol.asyncDispose]()

Aggiunto in: v20.4.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Chiama server.close() e restituisce una promise che si realizza quando il server è stato chiuso.

Classe: http.ServerResponse

Aggiunto in: v0.1.17

• Estende: <http.OutgoingMessage>

Questo oggetto viene creato internamente da un server HTTP, non dall'utente. Viene passato come secondo parametro all'evento 'request'.

Evento: 'close'

Aggiunto in: v0.6.7

Indica che la risposta è completata o che la sua connessione sottostante è stata terminata prematuramente (prima del completamento della risposta).

Evento: 'finish'

Aggiunto in: v0.3.6

Emesso quando la risposta è stata inviata. Più precisamente, questo evento viene emesso quando l'ultimo segmento delle intestazioni e del corpo della risposta è stato consegnato al sistema operativo per la trasmissione sulla rete. Ciò non implica che il client abbia già ricevuto qualcosa.

response.addTrailers(headers)

Aggiunta in: v0.3.0

• headers <Object>

Questo metodo aggiunge header finali HTTP (un header ma alla fine del messaggio) alla risposta.

I trailer saranno emessi solo se la codifica a blocchi è utilizzata per la risposta; se non lo è (ad es. se la richiesta era HTTP/1.0), saranno scartati silenziosamente.

HTTP richiede che l'header Trailer sia inviato per emettere i trailer, con una lista dei campi header nel suo valore. Es.,

response.writeHead(200, { 'Content-Type': 'text/plain',
                          'Trailer': 'Content-MD5' });
response.write(fileData);
response.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
response.end();

Tentare di impostare un nome di campo header o un valore che contiene caratteri non validi risulterà in un TypeError che viene lanciato.

response.connection

Aggiunta in: v0.3.0

Deprecata dal: v13.0.0

[Stabile: 0 - Deprecata]

Stabile: 0 Stabilità: 0 - Deprecata. Usa response.socket.

• <stream.Duplex>

Vedi response.socket.

response.cork()

Aggiunta in: v13.2.0, v12.16.0

Vedi writable.cork().

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

[Cronologia]

Versione	Modifiche
v15.0.0	Il parametro data ora può essere un Uint8Array.
v10.0.0	Questo metodo ora restituisce un riferimento a ServerResponse.
v0.1.90	Aggiunta in: v0.1.90

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• Restituisce: <this>

Questo metodo segnala al server che tutti gli header e il corpo della risposta sono stati inviati; quel server dovrebbe considerare questo messaggio completo. Il metodo, response.end(), DEVE essere chiamato su ogni risposta.

Se data è specificato, ha un effetto simile a chiamare response.write(data, encoding) seguito da response.end(callback).

Se callback è specificato, sarà chiamato quando lo stream di risposta è terminato.

response.finished

Aggiunto in: v0.0.2

Deprecato a partire da: v13.4.0, v12.16.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Usa response.writableEnded.

• <boolean>

La proprietà response.finished sarà true se è stato chiamato response.end().

response.flushHeaders()

Aggiunto in: v1.6.0

Scarica gli header della risposta. Vedi anche: request.flushHeaders().

response.getHeader(name)

Aggiunto in: v0.4.0

• name <string>
• Restituisce: <any>

Legge un header che è già stato accodato ma non inviato al client. Il nome non fa distinzione tra maiuscole e minuscole. Il tipo del valore restituito dipende dagli argomenti forniti a response.setHeader().

response.setHeader('Content-Type', 'text/html');
response.setHeader('Content-Length', Buffer.byteLength(body));
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
const contentType = response.getHeader('content-type');
// contentType è 'text/html'
const contentLength = response.getHeader('Content-Length');
// contentLength è di tipo number
const setCookie = response.getHeader('set-cookie');
// setCookie è di tipo string[]

response.getHeaderNames()

Aggiunto in: v7.7.0

• Restituisce: <string[]>

Restituisce un array contenente i nomi univoci degli header in uscita correnti. Tutti i nomi degli header sono in minuscolo.

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

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

response.getHeaders()

Aggiunto in: v7.7.0

• Restituisce: <Object>

Restituisce una copia superficiale delle intestazioni in uscita correnti. Poiché viene utilizzata una copia superficiale, i valori degli array possono essere modificati senza ulteriori chiamate a vari metodi del modulo http relativi all'intestazione. Le chiavi dell'oggetto restituito sono i nomi delle intestazioni e i valori sono i rispettivi valori delle intestazioni. Tutti i nomi delle intestazioni sono in minuscolo.

L'oggetto restituito dal metodo response.getHeaders() non eredita prototipicamente dall'oggetto JavaScript Object. Ciò significa che i tipici metodi Object come obj.toString(), obj.hasOwnProperty() e altri non sono definiti e non funzioneranno.

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)

Aggiunto in: v7.7.0

• name <stringa>
• Restituisce: <boolean>

Restituisce true se l'intestazione identificata da name è attualmente impostata nelle intestazioni in uscita. La corrispondenza del nome dell'intestazione non fa distinzione tra maiuscole e minuscole.

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

response.headersSent

Aggiunto in: v0.9.3

• <boolean>

Booleano (sola lettura). True se le intestazioni sono state inviate, false altrimenti.

response.removeHeader(name)

Aggiunto in: v0.4.0

• name <stringa>

Rimuove un'intestazione che è in coda per l'invio implicito.

response.removeHeader('Content-Encoding');

response.req

Aggiunto in: v15.7.0

• <http.IncomingMessage>

Un riferimento all'oggetto request HTTP originale.

response.sendDate

Aggiunto in: v0.7.5

• <boolean>

Quando è true, l'intestazione Date verrà generata e inviata automaticamente nella risposta se non è già presente nelle intestazioni. Il valore predefinito è true.

Questo dovrebbe essere disabilitato solo per i test; HTTP richiede l'intestazione Date nelle risposte.

response.setHeader(name, value)

Aggiunto in: v0.4.0

• name <string>
• value <any>
• Restituisce: <http.ServerResponse>

Restituisce l'oggetto risposta.

Imposta un singolo valore di intestazione per le intestazioni implicite. Se questa intestazione esiste già nelle intestazioni da inviare, il suo valore verrà sostituito. Usa un array di stringhe qui per inviare più intestazioni con lo stesso nome. I valori non stringa verranno archiviati senza modifiche. Pertanto, response.getHeader() potrebbe restituire valori non stringa. Tuttavia, i valori non stringa verranno convertiti in stringhe per la trasmissione di rete. Lo stesso oggetto risposta viene restituito al chiamante, per consentire l'incatenamento delle chiamate.

response.setHeader('Content-Type', 'text/html');

oppure

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

Tentare di impostare un nome di campo di intestazione o un valore che contenga caratteri non validi comporterà il lancio di un TypeError.

Quando le intestazioni sono state impostate con response.setHeader(), verranno unite a tutte le intestazioni passate a response.writeHead(), con le intestazioni passate a response.writeHead() che hanno la precedenza.

// Restituisce content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
});

Se il metodo response.writeHead() viene chiamato e questo metodo non è stato chiamato, scriverà direttamente i valori dell'intestazione forniti sul canale di rete senza memorizzare nella cache internamente e il response.getHeader() sull'intestazione non produrrà il risultato previsto. Se si desidera il popolamento progressivo delle intestazioni con potenziale recupero e modifica futuri, utilizzare response.setHeader() invece di response.writeHead().

response.setTimeout(msecs[, callback])

Aggiunto in: v0.9.12

• msecs <number>
• callback <Function>
• Restituisce: <http.ServerResponse>

Imposta il valore di timeout del Socket a msecs. Se viene fornito un callback, viene aggiunto come listener all'evento 'timeout' sull'oggetto response.

Se nessun listener 'timeout' viene aggiunto alla request, alla response o al server, i socket vengono distrutti quando scadono. Se un gestore viene assegnato agli eventi 'timeout' della request, della response o del server, i socket scaduti devono essere gestiti esplicitamente.

response.socket

Aggiunto in: v0.3.0

• <stream.Duplex>

Riferimento al socket sottostante. Di solito gli utenti non vorranno accedere a questa proprietà. In particolare, il socket non emetterà eventi 'readable' a causa del modo in cui il parser del protocollo si collega al socket. Dopo response.end(), la proprietà viene impostata su null.

ESM

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

CJS

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

È garantito che questa proprietà sia un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non abbia specificato un tipo di socket diverso da <net.Socket>.

response.statusCode

Aggiunto in: v0.4.0

• <number> Predefinito: 200

Quando si utilizzano intestazioni implicite (senza chiamare esplicitamente response.writeHead()), questa proprietà controlla il codice di stato che verrà inviato al client quando le intestazioni vengono scaricate.

response.statusCode = 404;

Dopo che l'intestazione della risposta è stata inviata al client, questa proprietà indica il codice di stato che è stato inviato.

response.statusMessage

Aggiunto in: v0.11.8

• <stringa>

Quando si utilizzano intestazioni implicite (senza chiamare esplicitamente response.writeHead()), questa proprietà controlla il messaggio di stato che verrà inviato al client quando le intestazioni vengono scaricate. Se questo viene lasciato come undefined, verrà utilizzato il messaggio standard per il codice di stato.

response.statusMessage = 'Non trovato';

Dopo che l'intestazione della risposta è stata inviata al client, questa proprietà indica il messaggio di stato che è stato inviato.

response.strictContentLength

Aggiunto in: v18.10.0, v16.18.0

• <booleano> Predefinito: false

Se impostato su true, Node.js controllerà se il valore dell'intestazione Content-Length e la dimensione del corpo, in byte, sono uguali. La mancata corrispondenza del valore dell'intestazione Content-Length comporterà la generazione di un Error, identificato da code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

response.uncork()

Aggiunto in: v13.2.0, v12.16.0

Vedi writable.uncork().

response.writableEnded

Aggiunto in: v12.9.0

• <booleano>

È true dopo che è stato chiamato response.end(). Questa proprietà non indica se i dati sono stati scaricati, per questo usa invece response.writableFinished.

response.writableFinished

Aggiunto in: v12.7.0

• <booleano>

È true se tutti i dati sono stati scaricati nel sistema sottostante, immediatamente prima che venga emesso l'evento 'finish'.

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

[Cronologia]

Versione	Modifiche
v15.0.0	Il parametro chunk ora può essere un Uint8Array.
v0.1.29	Aggiunto in: v0.1.29

• chunk <stringa> | <Buffer> | <Uint8Array>
• encoding <stringa> Predefinito: 'utf8'
• callback <Funzione>
• Restituisce: <booleano>

Se questo metodo viene chiamato e response.writeHead() non è stato chiamato, passerà alla modalità di intestazione implicita e scaricherà le intestazioni implicite.

Questo invia un blocco del corpo della risposta. Questo metodo può essere chiamato più volte per fornire parti successive del corpo.

Se rejectNonStandardBodyWrites è impostato su true in createServer, la scrittura nel corpo non è consentita quando il metodo di richiesta o lo stato della risposta non supportano il contenuto. Se si tenta di scrivere nel corpo per una richiesta HEAD o come parte di una risposta 204 o 304, viene generato un Error sincrono con il codice ERR_HTTP_BODY_NOT_ALLOWED.

chunk può essere una stringa o un buffer. Se chunk è una stringa, il secondo parametro specifica come codificarla in un flusso di byte. callback verrà chiamato quando questo blocco di dati viene scaricato.

Questo è il corpo HTTP non elaborato e non ha nulla a che fare con le codifiche del corpo multi-parte di livello superiore che possono essere utilizzate.

La prima volta che viene chiamato response.write(), invierà le informazioni sull'intestazione memorizzate nel buffer e il primo blocco del corpo al client. La seconda volta che viene chiamato response.write(), Node.js presume che i dati verranno trasmessi in streaming e invia i nuovi dati separatamente. Cioè, la risposta viene memorizzata nel buffer fino al primo blocco del corpo.

Restituisce true se tutti i dati sono stati scaricati correttamente nel buffer del kernel. Restituisce false se tutti o parte dei dati sono stati accodati nella memoria utente. 'drain' verrà emesso quando il buffer è di nuovo libero.

response.writeContinue()

Aggiunto in: v0.3.0

Invia un messaggio HTTP/1.1 100 Continue al client, indicando che il corpo della richiesta dovrebbe essere inviato. Vedi l'evento 'checkContinue' su Server.

response.writeEarlyHints(hints[, callback])

[Cronologia]

Versione	Modifiche
v18.11.0	Consente di passare gli hints come oggetto.
v18.11.0	Aggiunto in: v18.11.0

• hints <Object>
• callback <Function>

Invia un messaggio HTTP/1.1 103 Early Hints al client con un header Link, indicando che lo user agent può precaricare/preconnettere le risorse collegate. Gli hints sono un oggetto contenente i valori degli header da inviare con il messaggio early hints. L'argomento opzionale callback verrà chiamato quando il messaggio di risposta è stato scritto.

Esempio

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,
  'x-trace-id': 'id for diagnostics',
});

const earlyHintsCallback = () => console.log('early hints message sent');
response.writeEarlyHints({
  'link': earlyHintsLinks,
}, earlyHintsCallback);

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

[Cronologia]

Versione	Modifiche
v14.14.0	Consente di passare gli header come array.
v11.10.0, v10.17.0	Restituisce this da writeHead() per consentire l'incatenamento con end().
v5.11.0, v4.4.5	Viene generato un RangeError se statusCode non è un numero nell'intervallo [100, 999].
v0.1.30	Aggiunto in: v0.1.30

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• Restituisce: <http.ServerResponse>

Invia un header di risposta alla richiesta. Il codice di stato è un codice di stato HTTP a 3 cifre, come 404. L'ultimo argomento, headers, sono gli header di risposta. Facoltativamente, si può fornire un statusMessage leggibile come secondo argomento.

headers può essere un Array dove le chiavi e i valori sono nella stessa lista. Non è una lista di tuple. Quindi, gli offset pari sono i valori delle chiavi, e gli offset dispari sono i valori associati. L'array è nello stesso formato di request.rawHeaders.

Restituisce un riferimento a ServerResponse, in modo che le chiamate possano essere concatenate.

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

Questo metodo deve essere chiamato solo una volta su un messaggio e deve essere chiamato prima che venga chiamato response.end().

Se response.write() o response.end() vengono chiamati prima di chiamare questo, gli header impliciti/modificabili verranno calcolati e chiameranno questa funzione.

Quando gli header sono stati impostati con response.setHeader(), verranno uniti con qualsiasi header passato a response.writeHead(), con gli header passati a response.writeHead() che hanno la precedenza.

Se questo metodo viene chiamato e response.setHeader() non è stato chiamato, scriverà direttamente i valori degli header forniti sul canale di rete senza memorizzare nella cache internamente, e response.getHeader() sull'header non darà il risultato atteso. Se si desidera una popolazione progressiva degli header con potenziale recupero e modifica futura, utilizzare invece response.setHeader().

// Restituisce content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
});

Content-Length viene letto in byte, non in caratteri. Utilizzare Buffer.byteLength() per determinare la lunghezza del corpo in byte. Node.js verificherà se Content-Length e la lunghezza del corpo che è stato trasmesso sono uguali o meno.

Il tentativo di impostare un nome o un valore di campo di header che contenga caratteri non validi comporterà la generazione di un [Error][].

response.writeProcessing()

Aggiunto in: v10.0.0

Invia un messaggio HTTP/1.1 102 Processing al client, indicando che il corpo della richiesta deve essere inviato.

Classe: http.IncomingMessage

[Cronologia]

Versione	Modifiche
v15.5.0	Il valore destroyed restituisce true dopo che i dati in entrata sono stati consumati.
v13.1.0, v12.16.0	Il valore readableHighWaterMark rispecchia quello del socket.
v0.1.17	Aggiunto in: v0.1.17

• Estende: <stream.Readable>

Un oggetto IncomingMessage viene creato da http.Server o http.ClientRequest e passato come primo argomento agli eventi 'request' e 'response' rispettivamente. Può essere utilizzato per accedere allo stato della risposta, alle intestazioni e ai dati.

A differenza del suo valore socket che è una sottoclasse di <stream.Duplex>, IncomingMessage stesso estende <stream.Readable> e viene creato separatamente per analizzare ed emettere le intestazioni e il payload HTTP in entrata, poiché il socket sottostante può essere riutilizzato più volte in caso di keep-alive.

Evento: 'aborted'

Aggiunto in: v0.3.8

Deprecato a partire da: v17.0.0, v16.12.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Ascolta invece l'evento 'close'.

Emesso quando la richiesta è stata interrotta.

Evento: 'close'

[Cronologia]

Versione	Modifiche
v16.0.0	L'evento close viene ora emesso quando la richiesta è stata completata e non quando il socket sottostante è chiuso.
v0.4.2	Aggiunto in: v0.4.2

Emesso quando la richiesta è stata completata.

message.aborted

Aggiunto in: v10.1.0

Deprecato a partire da: v17.0.0, v16.12.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Controlla message.destroyed da <stream.Readable>.

• <boolean>

La proprietà message.aborted sarà true se la richiesta è stata interrotta.

message.complete

Aggiunto in: v0.3.0

• <boolean>

La proprietà message.complete sarà true se un messaggio HTTP completo è stato ricevuto e analizzato con successo.

Questa proprietà è particolarmente utile come mezzo per determinare se un client o un server ha trasmesso completamente un messaggio prima che una connessione venisse terminata:

const req = http.request({
  host: '127.0.0.1',
  port: 8080,
  method: 'POST',
}, (res) => {
  res.resume();
  res.on('end', () => {
    if (!res.complete)
      console.error(
        'La connessione è stata terminata mentre il messaggio era ancora in fase di invio');
  });
});

message.connection

Aggiunto in: v0.1.90

Deprecato da: v16.0.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Utilizzare message.socket.

Alias per message.socket.

message.destroy([error])

[Cronologia]

Versione	Modifiche
v14.5.0, v12.19.0	La funzione restituisce this per coerenza con altri stream Readable.
v0.3.0	Aggiunto in: v0.3.0

• error <Error>
• Restituisce: <this>

Chiama destroy() sul socket che ha ricevuto l'IncomingMessage. Se viene fornito error, viene emesso un evento 'error' sul socket e error viene passato come argomento a qualsiasi listener sull'evento.

message.headers

[Cronologia]

Versione	Modifiche
v19.5.0, v18.14.0	L'opzione joinDuplicateHeaders nelle funzioni http.request() e http.createServer() garantisce che le intestazioni duplicate non vengano scartate, ma piuttosto combinate utilizzando un separatore di virgole, in conformità con RFC 9110 Sezione 5.3.
v15.1.0	message.headers ora viene calcolato pigramente utilizzando una proprietà di accesso sul prototipo e non è più enumerabile.
v0.1.5	Aggiunto in: v0.1.5

• <Object>

L'oggetto delle intestazioni di richiesta/risposta.

Coppie chiave-valore dei nomi e dei valori delle intestazioni. I nomi delle intestazioni sono in minuscolo.

// Stampa qualcosa come:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers);

I duplicati nelle intestazioni non elaborate vengono gestiti nei seguenti modi, a seconda del nome dell'intestazione:

• I duplicati di age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server o user-agent vengono scartati. Per consentire l'unione di valori duplicati delle intestazioni sopra elencate, utilizzare l'opzione joinDuplicateHeaders in http.request() e http.createServer(). Vedere RFC 9110 Sezione 5.3 per ulteriori informazioni.
• set-cookie è sempre un array. I duplicati vengono aggiunti all'array.
• Per le intestazioni cookie duplicate, i valori vengono uniti con ; .
• Per tutte le altre intestazioni, i valori vengono uniti con , .

message.headersDistinct

Aggiunto in: v18.3.0, v16.17.0

• <Object>

Simile a message.headers, ma non c'è logica di unione e i valori sono sempre array di stringhe, anche per le intestazioni ricevute una sola volta.

// Stampa qualcosa del tipo:
//
// { 'user-agent': ['curl/7.22.0'],
//   host: ['127.0.0.1:8000'],
//   accept: ['*/*'] }
console.log(request.headersDistinct);

message.httpVersion

Aggiunto in: v0.1.1

• <string>

Nel caso di richiesta del server, la versione HTTP inviata dal client. Nel caso di risposta del client, la versione HTTP del server a cui è connesso. Probabilmente sia '1.1' che '1.0'.

Inoltre message.httpVersionMajor è il primo numero intero e message.httpVersionMinor è il secondo.

message.method

Aggiunto in: v0.1.1

• <string>

Valido solo per la richiesta ottenuta da http.Server.

Il metodo di richiesta come una stringa. Sola lettura. Esempi: 'GET', 'DELETE'.

message.rawHeaders

Aggiunto in: v0.11.6

• <string[]>

L'elenco delle intestazioni raw di richiesta/risposta esattamente come sono state ricevute.

Le chiavi e i valori sono nella stessa lista. Non è una lista di tuple. Quindi, gli offset con numero pari sono valori chiave e gli offset con numero dispari sono i valori associati.

I nomi delle intestazioni non sono in minuscolo e i duplicati non vengono uniti.

// Stampa qualcosa del tipo:
//
// [ '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);

message.rawTrailers

Aggiunto in: v0.11.6

• <string[]>

Le chiavi e i valori del trailer raw di richiesta/risposta esattamente come sono state ricevute. Popolato solo all'evento 'end'.

message.setTimeout(msecs[, callback])

Aggiunto in: v0.5.9

• msecs <number>
• callback <Function>
• Restituisce: <http.IncomingMessage>

Chiama message.socket.setTimeout(msecs, callback).

message.socket

Aggiunto in: v0.3.0

• <stream.Duplex>

L'oggetto net.Socket associato alla connessione.

Con il supporto HTTPS, utilizzare request.socket.getPeerCertificate() per ottenere i dettagli di autenticazione del client.

È garantito che questa proprietà sia un'istanza della classe <net.Socket>, una sottoclasse di <stream.Duplex>, a meno che l'utente non abbia specificato un tipo di socket diverso da <net.Socket> o internamente impostato su null.

message.statusCode

Aggiunto in: v0.1.1

• <number>

Valido solo per la risposta ottenuta da http.ClientRequest.

Il codice di stato della risposta HTTP a 3 cifre. ES. 404.

message.statusMessage

Aggiunto in: v0.11.10

• <string>

Valido solo per la risposta ottenuta da http.ClientRequest.

Il messaggio di stato della risposta HTTP (frase motivazionale). ES. OK o Internal Server Error.

message.trailers

Aggiunto in: v0.3.0

• <Object>

L'oggetto dei trailer di richiesta/risposta. Popolato solo all'evento 'end'.

message.trailersDistinct

Aggiunto in: v18.3.0, v16.17.0

• <Object>

Simile a message.trailers, ma non c'è logica di join e i valori sono sempre array di stringhe, anche per le intestazioni ricevute una sola volta. Popolato solo all'evento 'end'.

message.url

Aggiunto in: v0.1.90

• <stringa>

Valido solo per le richieste ottenute da http.Server.

Stringa URL della richiesta. Contiene solo l'URL presente nella richiesta HTTP effettiva. Considera la seguente richiesta:

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

Per analizzare l'URL nelle sue parti:

```js [ESM]
new URL(`http://${process.env.HOST ?? 'localhost'}${request.url}`);

Quando request.url è '/status?name=ryan' e process.env.HOST non è definito:

$ node
> new URL(`http://${process.env.HOST ?? 'localhost'}${request.url}`);
URL {
  href: 'http://localhost/status?name=ryan',
  origin: 'http://localhost',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'localhost',
  hostname: 'localhost',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
}

Assicurati di impostare process.env.HOST sul nome host del server oppure valuta la possibilità di sostituire completamente questa parte. Se utilizzi req.headers.host, assicurati che venga utilizzata una convalida appropriata, poiché i client potrebbero specificare un header Host personalizzato.

Classe: http.OutgoingMessage

Aggiunto in: v0.1.17

• Estende: <Stream>

Questa classe funge da classe padre di http.ClientRequest e http.ServerResponse. È un messaggio astratto in uscita dal punto di vista dei partecipanti a una transazione HTTP.

Evento: 'drain'

Aggiunto in: v0.3.6

Emesso quando il buffer del messaggio è di nuovo libero.

Evento: 'finish'

Aggiunto in: v0.1.17

Emesso quando la trasmissione è terminata correttamente.

Evento: 'prefinish'

Aggiunto in: v0.11.6

Emesso dopo che è stato chiamato outgoingMessage.end(). Quando viene emesso l'evento, tutti i dati sono stati elaborati ma non necessariamente completamente scaricati.

outgoingMessage.addTrailers(headers)

Aggiunto in: v0.3.0

• headers <Object>

Aggiunge i trailer HTTP (intestazioni, ma alla fine del messaggio) al messaggio.

I trailer saranno emessi solo se il messaggio è codificato a blocchi. In caso contrario, i trailer verranno scartati silenziosamente.

HTTP richiede che l'intestazione Trailer venga inviata per emettere i trailer, con un elenco di nomi di campi di intestazione nel suo valore, ad esempio:

message.writeHead(200, { 'Content-Type': 'text/plain',
                         'Trailer': 'Content-MD5' });
message.write(fileData);
message.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
message.end();

Il tentativo di impostare un nome o un valore di campo di intestazione che contenga caratteri non validi comporterà la generazione di un TypeError.

outgoingMessage.appendHeader(name, value)

Aggiunto in: v18.3.0, v16.17.0

• name <string> Nome dell'intestazione
• value <string> | <string[]> Valore dell'intestazione
• Restituisce: <this>

Aggiunge un singolo valore di intestazione all'oggetto intestazione.

Se il valore è un array, questo equivale a chiamare questo metodo più volte.

Se non ci fossero valori precedenti per l'intestazione, questo equivale a chiamare outgoingMessage.setHeader(name, value).

A seconda del valore di options.uniqueHeaders quando la richiesta del client o il server sono stati creati, ciò si tradurrà nell'intestazione inviata più volte o una sola volta con i valori uniti usando ; .

outgoingMessage.connection

Aggiunto in: v0.3.0

Deprecato a partire da: v15.12.0, v14.17.1

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Utilizzare invece outgoingMessage.socket.

Alias di outgoingMessage.socket.

outgoingMessage.cork()

Aggiunto in: v13.2.0, v12.16.0

Vedi writable.cork().

outgoingMessage.destroy([error])

Aggiunto in: v0.3.0

• error <Error> Opzionale, un errore da emettere con l'evento error
• Restituisce: <this>

Distrugge il messaggio. Una volta che un socket è associato al messaggio ed è connesso, anche quel socket verrà distrutto.

outgoingMessage.end(chunk[, encoding][, callback])

[Cronologia]

Versione	Modifiche
v15.0.0	Il parametro chunk ora può essere un Uint8Array.
v0.11.6	aggiungi l'argomento callback.
v0.1.90	Aggiunto in: v0.1.90

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Opzionale, Predefinito: utf8
• callback <Function> Opzionale
• Restituisce: <this>

Termina il messaggio in uscita. Se delle parti del body non sono state inviate, le invierà al sistema sottostante. Se il messaggio è suddiviso in chunk, invierà il chunk di terminazione 0\r\n\r\n e invierà i trailer (se presenti).

Se chunk è specificato, è equivalente a chiamare outgoingMessage.write(chunk, encoding), seguito da outgoingMessage.end(callback).

Se viene fornito callback, verrà chiamato al termine del messaggio (equivalente a un listener dell'evento 'finish').

outgoingMessage.flushHeaders()

Aggiunto in: v1.6.0

Invia gli header del messaggio.

Per motivi di efficienza, Node.js normalmente memorizza nel buffer gli header del messaggio finché non viene chiamato outgoingMessage.end() o viene scritto il primo chunk di dati del messaggio. Quindi cerca di inserire gli header e i dati in un singolo pacchetto TCP.

Di solito è auspicabile (risparmia un round-trip TCP), ma non quando i primi dati non vengono inviati fino a molto tempo dopo. outgoingMessage.flushHeaders() bypassa l'ottimizzazione e avvia il messaggio.

outgoingMessage.getHeader(name)

Aggiunto in: v0.4.0

• name <stringa> Nome dell'intestazione
• Restituisce: <stringa> | <undefined>

Ottiene il valore dell'intestazione HTTP con il nome fornito. Se tale intestazione non è impostata, il valore restituito sarà undefined.

outgoingMessage.getHeaderNames()

Aggiunto in: v7.7.0

• Restituisce: <stringa[]>

Restituisce un array contenente i nomi univoci delle intestazioni in uscita correnti. Tutti i nomi sono in minuscolo.

outgoingMessage.getHeaders()

Aggiunto in: v7.7.0

• Restituisce: <Oggetto>

Restituisce una copia superficiale delle intestazioni in uscita correnti. Poiché viene utilizzata una copia superficiale, i valori dell'array possono essere modificati senza ulteriori chiamate ai vari metodi del modulo HTTP relativi all'intestazione. Le chiavi dell'oggetto restituito sono i nomi delle intestazioni e i valori sono i rispettivi valori delle intestazioni. Tutti i nomi delle intestazioni sono in minuscolo.

L'oggetto restituito dal metodo outgoingMessage.getHeaders() non eredita prototipicamente dall'Oggetto JavaScript. Ciò significa che i metodi Oggetto tipici come obj.toString(), obj.hasOwnProperty() e altri non sono definiti e non funzioneranno.

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

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

outgoingMessage.hasHeader(name)

Aggiunto in: v7.7.0

• name <stringa>
• Restituisce: <booleano>

Restituisce true se l'intestazione identificata da name è attualmente impostata nelle intestazioni in uscita. Il nome dell'intestazione non fa distinzione tra maiuscole e minuscole.

const hasContentType = outgoingMessage.hasHeader('content-type');

outgoingMessage.headersSent

Aggiunto in: v0.9.3

• <boolean>

Sola lettura. true se le intestazioni sono state inviate, altrimenti false.

outgoingMessage.pipe()

Aggiunto in: v9.0.0

Sovrascrive il metodo stream.pipe() ereditato dalla classe Stream legacy che è la classe padre di http.OutgoingMessage.

Chiamare questo metodo genererà un Error perché outgoingMessage è uno stream di sola scrittura.

outgoingMessage.removeHeader(name)

Aggiunto in: v0.4.0

• name <string> Nome dell'intestazione

Rimuove un'intestazione che è in coda per l'invio implicito.

outgoingMessage.removeHeader('Content-Encoding');

outgoingMessage.setHeader(name, value)

Aggiunto in: v0.4.0

• name <string> Nome dell'intestazione
• value <any> Valore dell'intestazione
• Restituisce: <this>

Imposta un singolo valore di intestazione. Se l'intestazione esiste già nelle intestazioni da inviare, il suo valore verrà sostituito. Utilizza un array di stringhe per inviare più intestazioni con lo stesso nome.

outgoingMessage.setHeaders(headers)

Aggiunto in: v19.6.0, v18.15.0

• headers <Headers> | <Map>
• Restituisce: <this>

Imposta più valori di intestazione per le intestazioni implicite. headers deve essere un'istanza di Headers o Map, se un'intestazione esiste già nelle intestazioni da inviare, il suo valore verrà sostituito.

const headers = new Headers({ foo: 'bar' });
outgoingMessage.setHeaders(headers);

oppure

const headers = new Map([['foo', 'bar']]);
outgoingMessage.setHeaders(headers);

Quando le intestazioni sono state impostate con outgoingMessage.setHeaders(), verranno unite con qualsiasi intestazione passata a response.writeHead(), con le intestazioni passate a response.writeHead() che hanno la precedenza.

// Restituisce content-type = text/plain
const server = http.createServer((req, res) => {
  const headers = new Headers({ 'Content-Type': 'text/html' });
  res.setHeaders(headers);
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
});

outgoingMessage.setTimeout(msesc[, callback])

Aggiunto in: v0.9.12

• msesc <number>
• callback <Function> Funzione opzionale da chiamare quando si verifica un timeout. Come l'associazione all'evento timeout.
• Restituisce: <this>

Una volta che un socket è associato al messaggio ed è connesso, socket.setTimeout() verrà chiamato con msecs come primo parametro.

outgoingMessage.socket

Aggiunto in: v0.3.0

• <stream.Duplex>

Riferimento al socket sottostante. Di solito, gli utenti non vorranno accedere a questa proprietà.

Dopo aver chiamato outgoingMessage.end(), questa proprietà sarà impostata su null.

outgoingMessage.uncork()

Aggiunto in: v13.2.0, v12.16.0

Vedi writable.uncork()

outgoingMessage.writableCorked

Aggiunto in: v13.2.0, v12.16.0

• <number>

Il numero di volte in cui è stato chiamato outgoingMessage.cork().

outgoingMessage.writableEnded

Aggiunto in: v12.9.0

• <boolean>

È true se è stato chiamato outgoingMessage.end(). Questa proprietà non indica se i dati sono stati scaricati. A tale scopo, utilizzare invece message.writableFinished.

outgoingMessage.writableFinished

Aggiunto in: v12.7.0

• <boolean>

È true se tutti i dati sono stati scaricati nel sistema sottostante.

outgoingMessage.writableHighWaterMark

Aggiunto in: v12.9.0

• <number>

Il highWaterMark del socket sottostante se assegnato. Altrimenti, il livello di buffer predefinito quando writable.write() inizia a restituire false (16384).

outgoingMessage.writableLength

Aggiunto in: v12.9.0

• <number>

Il numero di byte in buffer.

outgoingMessage.writableObjectMode

Aggiunto in: v12.9.0

• <boolean>

Sempre false.

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

[Cronologia]

Versione	Modifiche
v15.0.0	Il parametro chunk ora può essere un Uint8Array.
v0.11.6	L'argomento callback è stato aggiunto.
v0.1.29	Aggiunto in: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Predefinito: utf8
• callback <Function>
• Restituisce: <boolean>

Invia un chunk del body. Questo metodo può essere chiamato più volte.

L'argomento encoding è rilevante solo quando chunk è una stringa. Il valore predefinito è 'utf8'.

L'argomento callback è opzionale e verrà chiamato quando questo chunk di dati viene scaricato.

Restituisce true se tutti i dati sono stati scaricati correttamente nel buffer del kernel. Restituisce false se tutti o parte dei dati sono stati accodati nella memoria utente. L'evento 'drain' verrà emesso quando il buffer sarà di nuovo libero.

http.METHODS

Aggiunto in: v0.11.8

• <string[]>

Un elenco dei metodi HTTP supportati dal parser.

http.STATUS_CODES

Aggiunto in: v0.1.22

• <Object>

Una raccolta di tutti i codici di stato di risposta HTTP standard e la breve descrizione di ciascuno. Ad esempio, http.STATUS_CODES[404] === 'Not Found'.

http.createServer([options][, requestListener])

[Cronologia]

Versione	Modifiche
v20.1.0, v18.17.0	L'opzione highWaterMark è ora supportata.
v18.0.0	Le opzioni requestTimeout, headersTimeout, keepAliveTimeout e connectionsCheckingInterval sono ora supportate.
v18.0.0	L'opzione noDelay ora ha come valore predefinito true.
v17.7.0, v16.15.0	Le opzioni noDelay, keepAlive e keepAliveInitialDelay sono ora supportate.
v13.3.0	L'opzione maxHeaderSize è ora supportata.
v13.8.0, v12.15.0, v10.19.0	L'opzione insecureHTTPParser è ora supportata.
v9.6.0, v8.12.0	L'argomento options è ora supportato.
v0.1.13	Aggiunto in: v0.1.13

• options <Object>

  • connectionsCheckingInterval: Imposta il valore dell'intervallo in millisecondi per verificare il timeout di richieste e intestazioni nelle richieste incomplete. Predefinito: 30000.
  • headersTimeout: Imposta il valore del timeout in millisecondi per la ricezione delle intestazioni HTTP complete dal client. Vedi server.headersTimeout per maggiori informazioni. Predefinito: 60000.
  • highWaterMark <number> Sovrascrive facoltativamente tutti i valori readableHighWaterMark e writableHighWaterMark dei socket. Ciò influisce sulla proprietà highWaterMark sia di IncomingMessage che di ServerResponse. Predefinito: Vedi stream.getDefaultHighWaterMark().
  • insecureHTTPParser <boolean> Se impostato su true, utilizzerà un parser HTTP con i flag di tolleranza abilitati. L'utilizzo del parser non sicuro dovrebbe essere evitato. Vedi --insecure-http-parser per maggiori informazioni. Predefinito: false.
  • IncomingMessage <http.IncomingMessage> Specifica la classe IncomingMessage da utilizzare. Utile per estendere l'IncomingMessage originale. Predefinito: IncomingMessage.
  • joinDuplicateHeaders <boolean> Se impostato su true, questa opzione consente di unire i valori delle righe di campo di più intestazioni in una richiesta con una virgola (, ) invece di scartare i duplicati. Per maggiori informazioni, fai riferimento a message.headers. Predefinito: false.
  • keepAlive <boolean> Se impostato su true, abilita la funzionalità keep-alive sul socket immediatamente dopo aver ricevuto una nuova connessione in entrata, in modo simile a quanto fatto in [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)]. Predefinito: false.
  • keepAliveInitialDelay <number> Se impostato su un numero positivo, imposta il ritardo iniziale prima che la prima sonda keepalive venga inviata su un socket inattivo. Predefinito: 0.
  • keepAliveTimeout: Il numero di millisecondi di inattività che un server deve attendere per ulteriori dati in entrata, dopo aver terminato di scrivere l'ultima risposta, prima che un socket venga distrutto. Vedi server.keepAliveTimeout per maggiori informazioni. Predefinito: 5000.
  • maxHeaderSize <number> Sovrascrive facoltativamente il valore di --max-http-header-size per le richieste ricevute da questo server, ovvero la lunghezza massima delle intestazioni delle richieste in byte. Predefinito: 16384 (16 KiB).
  • noDelay <boolean> Se impostato su true, disabilita l'uso dell'algoritmo di Nagle immediatamente dopo aver ricevuto una nuova connessione in entrata. Predefinito: true.
  • requestTimeout: Imposta il valore del timeout in millisecondi per la ricezione dell'intera richiesta dal client. Vedi server.requestTimeout per maggiori informazioni. Predefinito: 300000.
  • requireHostHeader <boolean> Se impostato su true, forza il server a rispondere con un codice di stato 400 (Richiesta errata) a qualsiasi messaggio di richiesta HTTP/1.1 che non ha un'intestazione Host (come richiesto dalla specifica). Predefinito: true.
  • ServerResponse <http.ServerResponse> Specifica la classe ServerResponse da utilizzare. Utile per estendere la ServerResponse originale. Predefinito: ServerResponse.
  • uniqueHeaders <Array> Un elenco di intestazioni di risposta che dovrebbero essere inviate una sola volta. Se il valore dell'intestazione è un array, gli elementi verranno uniti usando ; .
  • rejectNonStandardBodyWrites <boolean> Se impostato su true, viene generato un errore quando si scrive in una risposta HTTP che non ha un corpo. Predefinito: false.

• requestListener <Function>

• Restituisce: <http.Server>

Restituisce una nuova istanza di http.Server.

Il requestListener è una funzione che viene automaticamente aggiunta all'evento 'request'.

ESM

import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);

CJS

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

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);

ESM

import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);

CJS

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

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);

http.get(options[, callback])

http.get(url[, options][, callback])

[Cronologia]

Versione	Modifiche
v10.9.0	Il parametro url ora può essere passato insieme a un oggetto options separato.
v7.5.0	Il parametro options può essere un oggetto URL WHATWG.
v0.3.6	Aggiunto in: v0.3.6

• url <string> | <URL>
• options <Object> Accetta le stesse options di http.request(), con il metodo impostato su GET per impostazione predefinita.
• callback <Function>
• Restituisce: <http.ClientRequest>

Poiché la maggior parte delle richieste sono richieste GET senza corpi, Node.js fornisce questo metodo di convenienza. L'unica differenza tra questo metodo e http.request() è che imposta il metodo su GET per impostazione predefinita e chiama req.end() automaticamente. La callback deve preoccuparsi di consumare i dati di risposta per i motivi indicati nella sezione http.ClientRequest.

La callback viene richiamata con un singolo argomento che è un'istanza di http.IncomingMessage.

Esempio di recupero JSON:

http.get('http://localhost:8000/', (res) => {
  const { statusCode } = res;
  const contentType = res.headers['content-type'];

  let error;
  // Qualsiasi codice di stato 2xx segnala una risposta corretta ma
  // qui stiamo controllando solo il 200.
  if (statusCode !== 200) {
    error = new Error('Richiesta fallita.\n' +
                      `Codice di stato: ${statusCode}`);
  } else if (!/^application\/json/.test(contentType)) {
    error = new Error('Tipo di contenuto non valido.\n' +
                      `Previsto application/json ma ricevuto ${contentType}`);
  }
  if (error) {
    console.error(error.message);
    // Consuma i dati di risposta per liberare memoria
    res.resume();
    return;
  }

  res.setEncoding('utf8');
  let rawData = '';
  res.on('data', (chunk) => { rawData += chunk; });
  res.on('end', () => {
    try {
      const parsedData = JSON.parse(rawData);
      console.log(parsedData);
    } catch (e) {
      console.error(e.message);
    }
  });
}).on('error', (e) => {
  console.error(`Errore: ${e.message}`);
});

// Crea un server locale per ricevere dati da
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Ciao Mondo!',
  }));
});

server.listen(8000);

http.globalAgent

[Cronologia]

Versione	Modifiche
v19.0.0	L'agent ora utilizza HTTP Keep-Alive e un timeout di 5 secondi per impostazione predefinita.
v0.5.9	Aggiunto in: v0.5.9

• <http.Agent>

Istanza globale di Agent che viene utilizzata come predefinita per tutte le richieste client HTTP. Diverge da una configurazione Agent predefinita avendo keepAlive abilitato e un timeout di 5 secondi.

http.maxHeaderSize

Aggiunto in: v11.6.0, v10.15.0

• <number>

Proprietà di sola lettura che specifica la dimensione massima consentita degli header HTTP in byte. Il valore predefinito è 16 KiB. Configurable utilizzando l'opzione CLI --max-http-header-size.

Questo può essere sovrascritto per server e richieste client passando l'opzione maxHeaderSize.

http.request(options[, callback])

http.request(url[, options][, callback])

[Cronologia]

Versione	Modifiche
v16.7.0, v14.18.0	Quando si utilizza un oggetto URL analizzato, username e password verranno ora decodificati correttamente come URI.
v15.3.0, v14.17.0	È possibile interrompere una richiesta con un AbortSignal.
v13.3.0	L'opzione maxHeaderSize è ora supportata.
v13.8.0, v12.15.0, v10.19.0	L'opzione insecureHTTPParser è ora supportata.
v10.9.0	Il parametro url può ora essere passato insieme a un oggetto options separato.
v7.5.0	Il parametro options può essere un oggetto WHATWG URL.
v0.3.6	Aggiunto in: v0.3.6

• url <string> | <URL>

• options <Object>

  • agent <http.Agent> | <boolean> Controlla il comportamento di Agent. Valori possibili:

  • undefined (predefinito): utilizza http.globalAgent per questo host e porta.

  • oggetto Agent: utilizza esplicitamente l'Agent passato.

  • false: fa sì che venga utilizzato un nuovo Agent con valori predefiniti.

  • auth <string> Autenticazione di base ('user:password') per calcolare un header Authorization.

  • createConnection <Function> Una funzione che produce un socket/stream da utilizzare per la richiesta quando l'opzione agent non viene utilizzata. Questo può essere utilizzato per evitare di creare una classe Agent personalizzata solo per sovrascrivere la funzione createConnection predefinita. Vedi agent.createConnection() per maggiori dettagli. Qualsiasi stream Duplex è un valore di ritorno valido.

  • defaultPort <number> Porta predefinita per il protocollo. Predefinito: agent.defaultPort se viene utilizzato un Agent, altrimenti undefined.

  • family <number> Famiglia di indirizzi IP da utilizzare quando si risolve host o hostname. I valori validi sono 4 o 6. Quando non specificato, verranno utilizzati sia IP v4 che v6.

  • headers <Object> Un oggetto contenente header di richiesta.

  • hints <number> dns.lookup() hint opzionali.

  • host <string> Un nome di dominio o un indirizzo IP del server a cui inviare la richiesta. Predefinito: 'localhost'.

  • hostname <string> Alias per host. Per supportare url.parse(), hostname verrà utilizzato se sono specificati sia host che hostname.

  • insecureHTTPParser <boolean> Se impostato su true, utilizzerà un parser HTTP con i flag di tolleranza abilitati. L'utilizzo del parser insicuro dovrebbe essere evitato. Vedi --insecure-http-parser per maggiori informazioni. Predefinito: false

  • joinDuplicateHeaders <boolean> Unisce i valori della riga di campo di più header in una richiesta con , invece di scartare i duplicati. Vedi message.headers per maggiori informazioni. Predefinito: false.

  • localAddress <string> Interfaccia locale a cui collegarsi per le connessioni di rete.

  • localPort <number> Porta locale da cui connettersi.

  • lookup <Function> Funzione di lookup personalizzata. Predefinito: dns.lookup().

  • maxHeaderSize <number> Sovrascrive facoltativamente il valore di --max-http-header-size (la lunghezza massima degli header di risposta in byte) per le risposte ricevute dal server. Predefinito: 16384 (16 KiB).

  • method <string> Una stringa che specifica il metodo di richiesta HTTP. Predefinito: 'GET'.

  • path <string> Percorso della richiesta. Dovrebbe includere la stringa di query, se presente. ES. '/index.html?page=12'. Viene generata un'eccezione quando il percorso della richiesta contiene caratteri non validi. Attualmente, vengono rifiutati solo gli spazi, ma ciò potrebbe cambiare in futuro. Predefinito: '/'.

  • port <number> Porta del server remoto. Predefinito: defaultPort se impostato, altrimenti 80.

  • protocol <string> Protocollo da utilizzare. Predefinito: 'http:'.

  • setDefaultHeaders <boolean>: Specifica se aggiungere o meno automaticamente header predefiniti come Connection, Content-Length, Transfer-Encoding e Host. Se impostato su false, tutti gli header necessari devono essere aggiunti manualmente. Il valore predefinito è true.

  • setHost <boolean>: Specifica se aggiungere o meno automaticamente l'header Host. Se fornito, questo sovrascrive setDefaultHeaders. Il valore predefinito è true.

  • signal <AbortSignal>: Un AbortSignal che può essere utilizzato per interrompere una richiesta in corso.

  • socketPath <string> Socket di dominio Unix. Non può essere utilizzato se sono specificati host o port, poiché questi specificano un Socket TCP.

  • timeout <number>: Un numero che specifica il timeout del socket in millisecondi. Questo imposterà il timeout prima che il socket sia connesso.

  • uniqueHeaders <Array> Un elenco di header di richiesta che devono essere inviati solo una volta. Se il valore dell'header è un array, gli elementi verranno uniti usando ; .

• callback <Function>

• Restituisce: <http.ClientRequest>

Anche le options in socket.connect() sono supportate.

Node.js mantiene diverse connessioni per server per effettuare richieste HTTP. Questa funzione consente di effettuare richieste in modo trasparente.

url può essere una stringa o un oggetto URL. Se url è una stringa, viene automaticamente analizzata con new URL(). Se è un oggetto URL, verrà automaticamente convertito in un normale oggetto options.

Se sono specificati sia url che options, gli oggetti vengono uniti, con le proprietà options che hanno la precedenza.

Il parametro callback opzionale verrà aggiunto come listener una tantum per l'evento 'response'.

http.request() restituisce un'istanza della classe http.ClientRequest. L'istanza ClientRequest è uno stream scrivibile. Se è necessario caricare un file con una richiesta POST, scrivi sull'oggetto ClientRequest.

ESM

import http from 'node:http';
import { Buffer } from 'node:buffer';

const postData = JSON.stringify({
  'msg': 'Hello World!',
});

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
};

const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

// Write data to request body
req.write(postData);
req.end();

CJS

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

const postData = JSON.stringify({
  'msg': 'Hello World!',
});

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
};

const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

// Write data to request body
req.write(postData);
req.end();

Nell'esempio è stato chiamato req.end(). Con http.request() si deve sempre chiamare req.end() per indicare la fine della richiesta, anche se non ci sono dati scritti nel corpo della richiesta.

Se si verifica un errore durante la richiesta (che si tratti di risoluzione DNS, errori a livello TCP o errori di analisi HTTP effettivi), viene emesso un evento 'error' sull'oggetto richiesta restituito. Come per tutti gli eventi 'error', se non sono registrati listener, l'errore verrà generato.

Ci sono alcuni header speciali che dovrebbero essere notati.

• L'invio di 'Connection: keep-alive' notificherà a Node.js che la connessione al server deve essere mantenuta fino alla prossima richiesta.
• L'invio di un header 'Content-Length' disabiliterà la codifica a blocchi predefinita.
• L'invio di un header 'Expect' invierà immediatamente gli header della richiesta. Solitamente, quando si invia 'Expect: 100-continue', dovrebbero essere impostati sia un timeout che un listener per l'evento 'continue'. Vedi RFC 2616 Section 8.2.3 per maggiori informazioni.
• L'invio di un header Authorization sovrascriverà l'utilizzo dell'opzione auth per calcolare l'autenticazione di base.

Esempio di utilizzo di un URL come options:

const options = new URL('http://abc:');

const req = http.request(options, (res) => {
  // ...
});

In una richiesta di successo, i seguenti eventi verranno emessi nel seguente ordine:

• 'socket'

• 'response'

  • 'data' un numero qualsiasi di volte, sull'oggetto res ('data' non verrà emesso affatto se il corpo della risposta è vuoto, ad esempio, nella maggior parte dei reindirizzamenti)
  • 'end' sull'oggetto res

• 'close'

In caso di errore di connessione, verranno emessi i seguenti eventi:

• 'socket'
• 'error'
• 'close'

In caso di chiusura prematura della connessione prima che venga ricevuta la risposta, verranno emessi i seguenti eventi nel seguente ordine:

• 'socket'
• 'error' con un errore con messaggio 'Error: socket hang up' e codice 'ECONNRESET'
• 'close'

In caso di chiusura prematura della connessione dopo che la risposta è stata ricevuta, verranno emessi i seguenti eventi nel seguente ordine:

• 'socket'

• 'response'

  • 'data' un numero qualsiasi di volte, sull'oggetto res

• (connessione chiusa qui)

• 'aborted' sull'oggetto res

• 'close'

• 'error' sull'oggetto res con un errore con messaggio 'Error: aborted' e codice 'ECONNRESET'

• 'close' sull'oggetto res

Se req.destroy() viene chiamato prima che venga assegnato un socket, verranno emessi i seguenti eventi nel seguente ordine:

• (req.destroy() chiamato qui)
• 'error' con un errore con messaggio 'Error: socket hang up' e codice 'ECONNRESET', o l'errore con cui è stato chiamato req.destroy()
• 'close'

Se req.destroy() viene chiamato prima che la connessione abbia successo, verranno emessi i seguenti eventi nel seguente ordine:

• 'socket'
• (req.destroy() chiamato qui)
• 'error' con un errore con messaggio 'Error: socket hang up' e codice 'ECONNRESET', o l'errore con cui è stato chiamato req.destroy()
• 'close'

Se req.destroy() viene chiamato dopo che è stata ricevuta la risposta, verranno emessi i seguenti eventi nel seguente ordine:

• 'socket'

• 'response'

  • 'data' un numero qualsiasi di volte, sull'oggetto res

• (req.destroy() chiamato qui)

• 'aborted' sull'oggetto res

• 'close'

• 'error' sull'oggetto res con un errore con messaggio 'Error: aborted' e codice 'ECONNRESET', o l'errore con cui è stato chiamato req.destroy()

• 'close' sull'oggetto res

Se req.abort() viene chiamato prima che venga assegnato un socket, verranno emessi i seguenti eventi nel seguente ordine:

• (req.abort() chiamato qui)
• 'abort'
• 'close'

Se req.abort() viene chiamato prima che la connessione abbia successo, verranno emessi i seguenti eventi nel seguente ordine:

• 'socket'
• (req.abort() chiamato qui)
• 'abort'
• 'error' con un errore con messaggio 'Error: socket hang up' e codice 'ECONNRESET'
• 'close'

Se req.abort() viene chiamato dopo che è stata ricevuta la risposta, verranno emessi i seguenti eventi nel seguente ordine:

• 'socket'

• 'response'

  • 'data' un numero qualsiasi di volte, sull'oggetto res

• (req.abort() chiamato qui)

• 'abort'

• 'aborted' sull'oggetto res

• 'error' sull'oggetto res con un errore con messaggio 'Error: aborted' e codice 'ECONNRESET'.

• 'close'

• 'close' sull'oggetto res

L'impostazione dell'opzione timeout o l'utilizzo della funzione setTimeout() non interromperà la richiesta né farà altro che aggiungere un evento 'timeout'.

Passare un AbortSignal e quindi chiamare abort() sul AbortController corrispondente si comporterà allo stesso modo della chiamata .destroy() sulla richiesta. Nello specifico, l'evento 'error' verrà emesso con un errore con il messaggio 'AbortError: The operation was aborted', il codice 'ABORT_ERR' e la cause, se ne è stata fornita una.

http.validateHeaderName(name[, label])

[Cronologia]

Versione	Modifiche
v19.5.0, v18.14.0	Aggiunto il parametro label.
v14.3.0	Aggiunto in: v14.3.0

• name <stringa>
• label <stringa> Etichetta per il messaggio di errore. Predefinito: 'Nome dell'intestazione'.

Esegue le validazioni di basso livello sul name fornito che vengono eseguite quando viene chiamato res.setHeader(name, value).

Passare un valore illegale come name comporterà la generazione di un TypeError, identificato da code: 'ERR_INVALID_HTTP_TOKEN'.

Non è necessario utilizzare questo metodo prima di passare le intestazioni a una richiesta o risposta HTTP. Il modulo HTTP convaliderà automaticamente tali intestazioni.

Esempio:

ESM

import { validateHeaderName } from 'node:http';

try {
  validateHeaderName('');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message); // --> 'Header name must be a valid HTTP token [""]'
}

CJS

const { validateHeaderName } = require('node:http');

try {
  validateHeaderName('');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message); // --> 'Header name must be a valid HTTP token [""]'
}

http.validateHeaderValue(name, value)

Aggiunto in: v14.3.0

• name <stringa>
• value <qualsiasi>

Esegue le validazioni di basso livello sul value fornito che vengono eseguite quando viene chiamato res.setHeader(name, value).

Passare un valore illegale come value comporterà la generazione di un TypeError.

• L'errore di valore non definito è identificato da code: 'ERR_HTTP_INVALID_HEADER_VALUE'.
• L'errore di carattere di valore non valido è identificato da code: 'ERR_INVALID_CHAR'.

Non è necessario utilizzare questo metodo prima di passare le intestazioni a una richiesta o risposta HTTP. Il modulo HTTP convaliderà automaticamente tali intestazioni.

Esempi:

ESM

import { validateHeaderValue } from 'node:http';

try {
  validateHeaderValue('x-my-header', undefined);
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'); // --> true
  console.error(err.message); // --> 'Invalid value "undefined" for header "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_INVALID_CHAR'); // --> true
  console.error(err.message); // --> 'Invalid character in header content ["x-my-header"]'
}

CJS

const { validateHeaderValue } = require('node:http');

try {
  validateHeaderValue('x-my-header', undefined);
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'); // --> true
  console.error(err.message); // --> 'Invalid value "undefined" for header "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_INVALID_CHAR'); // --> true
  console.error(err.message); // --> 'Invalid character in header content ["x-my-header"]'
}

http.setMaxIdleHTTPParsers(max)

Aggiunto in: v18.8.0, v16.18.0

• max <number> Predefinito: 1000.

Imposta il numero massimo di parser HTTP inattivi.

WebSocket

Aggiunto in: v22.5.0

Un'implementazione compatibile con il browser di WebSocket.