HTTP

[Stable: 2 - Stabile]

Stable: 2 Stabilità: 2 - Stabile

Codice sorgente: lib/http.js

Questo modulo, che contiene 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 grandi, possibilmente codificati a blocchi. L'interfaccia è attenta a non memorizzare mai in buffer intere richieste o risposte, in modo che l'utente sia 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 dello stream e dell'analisi dei messaggi. Analizza un messaggio in intestazioni e corpo, ma non analizza le intestazioni effettive o il corpo.

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

Le intestazioni grezze come sono state ricevute vengono conservate nella proprietà rawHeaders, che è un array di [key, value, key2, value2, ...]. 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 della connessione e del riutilizzo per i client HTTP. Mantiene una coda di richieste in sospeso per un dato host e porta, riutilizzando una singola connessione socket per ciascuna fino a quando la coda non è vuota, a quel punto il socket viene distrutto o inserito in un pool dove viene conservato per essere riutilizzato per le richieste allo stesso host e porta. Se viene distrutto o raggruppato dipende dall'opzione keepAlive opzione.

Le connessioni in pool hanno TCP Keep-Alive abilitato per loro, ma i server possono comunque chiudere le connessioni inattive, nel qual caso verranno rimosse dal pool e verrà effettuata una nuova connessione quando viene effettuata una nuova richiesta HTTP per quell'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. Tutti i socket inutilizzati nel pool verranno dereferenziati in modo da non mantenere il processo Node.js in esecuzione quando non ci sono richieste in sospeso. (vedere socket.unref()).

È buona norma destroy() un'istanza 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 di tempo senza mantenerla nell'agente, è possibile eseguire un'operazione simile alla seguente:

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	Modificato lo scheduling predefinito da 'fifo' a 'lifo'.
v14.5.0, v12.20.0	Aggiunta l'opzione scheduling per specificare la strategia di scheduling dei socket liberi.
v14.5.0, v12.19.0	Aggiunta l'opzione maxTotalSockets al costruttore dell'agente.
v0.3.4	Aggiunto 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 impostate rispettivamente 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 consentiti per host. Se lo stesso host apre più connessioni simultanee, ogni richiesta utilizzerà un nuovo socket fino a raggiungere 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 passeranno allo stato di connessione attiva quando una connessione esistente termina. Ciò garantisce 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 raggiungere 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 scheduling da applicare quando si sceglie il prossimo socket libero da utilizzare. Può essere 'fifo' o 'lifo'. La principale differenza tra le due strategie di scheduling è che 'lifo' seleziona il socket utilizzato più di recente, mentre 'fifo' seleziona il socket utilizzato meno di recente. In caso di basso tasso di richieste al secondo, lo scheduling 'lifo' ridurrà il rischio di scegliere un socket che potrebbe essere stato chiuso dal server a causa dell'inattività. In caso di alto tasso di richieste al secondo, lo scheduling 'fifo' massimizzerà il numero di socket aperti, mentre lo scheduling 'lifo' lo manterrà il più basso possibile. Predefinito: 'lifo'.
  • timeout <number> Timeout del socket in millisecondi. Ciò imposterà il timeout quando il socket viene creato.

Le options in socket.connect() sono supportate anche.

Per configurare una qualsiasi di esse, è 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. Controlla 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 è uguale a net.createConnection(). Tuttavia, gli agenti personalizzati possono sovrascrivere questo metodo nel caso in cui si desideri una maggiore flessibilità.

Un socket/stream può essere fornito in due modi: restituendo il socket/stream da questa funzione oppure 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 staccato da una richiesta e potrebbe essere mantenuto dall' Agent. Il comportamento predefinito è:

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

Questo metodo può essere sovrascritto da una particolare sottoclasse Agent. Se questo metodo restituisce un valore falso, 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 viene collegato a request dopo essere stato mantenuto a causa delle opzioni keep-alive. Il comportamento predefinito è:

socket.ref()

Questo metodo può essere sovrascritto da una particolare sottoclasse 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 arrestare esplicitamente l'agente quando non è più necessario. Altrimenti, i socket potrebbero rimanere aperti per un 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 nell'elenco freeSockets verranno automaticamente distrutti e rimossi dall'array in 'timeout'.

agent.getName([options])

[Cronologia]

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

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

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

• Restituisce: <string>

Ottiene un nome univoco per un insieme 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, certificato, cifrari 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 rimarranno 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	Cambiamenti
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	Cambiamenti
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 modificabile utilizzando 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 richiesta. 'response' verrà emesso dall'oggetto richiesta 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 risposta; in particolare per ascoltare l'evento 'data'.

Se non viene aggiunto alcun gestore 'response', la risposta verrà interamente scartata. Tuttavia, se viene aggiunto un gestore di eventi 'response', i dati dall'oggetto risposta devono essere consumati, o chiamando response.read() ogni volta che c'è un evento 'readable', o aggiungendo un gestore 'data', o chiamando il metodo .resume(). Fino a quando i dati non vengono consumati, l'evento 'end' non verrà attivato. Inoltre, fino a quando i dati non vengono letti, consumeranno memoria che alla fine può 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 dovrebbe essere in byte, non in caratteri. Utilizza Buffer.byteLength() per determinare la lunghezza del corpo in byte.

Evento: 'abort'

Aggiunto in: v1.4.1

Deprecato da: v17.0.0, v16.12.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Invece, ascolta l'evento 'close'.

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

Evento: 'close'

Aggiunto in: v0.5.4

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

Evento: '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 mostra 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) => {
  // Connetti 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', () => {
  // Crea 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('connessione stabilita!')

    // Crea una richiesta su 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) => {
  // Connetti 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', () => {
  // Crea 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('connessione stabilita!')

    // Crea una richiesta su 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 il client dovrebbe inviare il corpo della richiesta.

Evento: 'finish'

Aggiunto in: v0.3.6

Emesso quando la richiesta è stata inviata. Più specificamente, questo evento viene emesso quando l'ultimo segmento delle intestazioni e del corpo della risposta sono stati consegnati 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 101 Upgrade). 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 un 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',
}

// Effettua una richiesta
const req = request(options)
req.end()

req.on('information', info => {
  console.log(`Ottenute informazioni prima della risposta principale: ${info.statusCode}`)
})

CJS

const http = require('node:http')

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

// Effettua una richiesta
const req = http.request(options)
req.end()

req.on('information', info => {
  console.log(`Ottenute informazioni prima della risposta principale: ${info.statusCode}`)
})

Gli stati 101 Upgrade non attivano questo evento a causa della loro rottura dalla tradizionale catena richiesta/risposta HTTP, come i web socket, gli upgrade TLS in-place o HTTP 2.0. Per essere notificati degli avvisi 101 Upgrade, ascolta 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 una sola volta.

Evento: 'socket'

Aggiunto in: v0.5.3

• socket <stream.Duplex>

È garantito che questo evento riceva 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 dell'inattività. Questo notifica solo che il socket è rimasto 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, i client che ricevono un header di upgrade vedranno le loro connessioni chiuse.

È garantito che questo evento riceva 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'

// Crea un server HTTP
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) // rimanda indietro
})

// Ora che il server è in esecuzione
server.listen(1337, '127.0.0.1', () => {
  // effettua una richiesta
  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("ottenuto l'upgrade!")
    socket.end()
    process.exit(0)
  })
})

CJS

const http = require('node:http')

// Crea un server HTTP
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) // rimanda indietro
})

// Ora che il server è in esecuzione
server.listen(1337, '127.0.0.1', () => {
  // effettua una richiesta
  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("ottenuto l'upgrade!")
    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: Invece, usa request.destroy().

Contrassegna la richiesta come in fase di interruzione. La chiamata a questo metodo farà sì che i dati rimanenti nella risposta vengano eliminati 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 timestamp.
v0.11.14	Aggiunto in: v0.11.14

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato. Controlla 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. Usa request.socket.

• <stream.Duplex>

Vedi request.socket.

request.cork()

Aggiunto in: v13.2.0, v12.16.0

Vedi writable.cork().

request.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 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 qualche parte del corpo non è stata inviata, la invia allo stream. Se la richiesta è suddivisa in chunk, questo invierà il terminatore '0\r\n\r\n'.

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

Se viene specificato callback, verrà chiamata quando lo stream della richiesta è terminato.

request.destroy([error])

[Cronologia]

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

• error <Errore> Facoltativo, 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 causerà la perdita dei dati rimanenti nella risposta e la distruzione del socket.

Vedi writable.destroy() per ulteriori dettagli.

request.destroyed

Aggiunto in: v14.1.0, v13.14.0

• <booleano>

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

Vedi writable.destroyed per ulteriori dettagli.

request.finished

Aggiunto in: v0.0.1

Deprecato da: v13.4.0, v12.16.0

[Stabile: 0 - Deprecato]

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

• <booleano>

La proprietà request.finished sarà true se è stato chiamato request.end(). 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 ragioni di efficienza, Node.js normalmente memorizza nel buffer gli header della richiesta fino a quando non viene chiamato request.end() o viene scritto il primo blocco di dati della richiesta. Quindi cerca di impacchettare gli header della richiesta e i dati in un singolo pacchetto TCP.

Questo è generalmente desiderabile (si risparmia un round-trip TCP), ma non quando i primi dati non vengono inviati fino a un momento possibilmente molto successivo. request.flushHeaders() ignora l'ottimizzazione e avvia la richiesta.

request.getHeader(name)

Aggiunto in: v1.6.0

• name <string>
• Restituisce: <any>

Legge un'intestazione nella richiesta. Il nome non è sensibile alla maiuscola/minuscola. Il tipo del valore restituito 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: <string[]>

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

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: <Object>

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 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 minuscoli.

L'oggetto restituito dal metodo request.getHeaders() non eredita prototipicamente dall'Object JavaScript. Ciò significa che i tipici metodi Object 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 unici delle intestazioni raw in uscita correnti. I nomi delle intestazioni vengono restituiti con la loro esatta capitalizzazione impostata.

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'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 = request.hasHeader('content-type')

request.maxHeadersCount

• <number> Predefinito: 2000

Limita il numero massimo di intestazioni 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'intestazione già definita 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 agente 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 keep-alive di 5 secondi per impostazione predefinita
http
  .createServer((req, res) => {
    res.write('hello\n')
    res.end()
  })
  .listen(3000)

setInterval(() => {
  // Adattamento di un agente 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 keep-alive di 5 secondi per impostazione predefinita
http
  .createServer((req, res) => {
    res.write('hello\n')
    res.end()
  })
  .listen(3000)

setInterval(() => {
  // Adattamento di un agente 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 indica se ha riutilizzato un socket o meno, possiamo eseguire automaticamente il nuovo tentativo di errore in base a ciò.

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 riprovare
      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 riprovare
      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 header per l'oggetto degli header. Se questo header esiste già negli header da inviare, il suo valore verrà sostituito. Utilizzare un array di stringhe qui per inviare più header con lo stesso nome. I valori non stringa verranno memorizzati senza modifiche. Pertanto, request.getHeader() potrebbe 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 è necessario passare caratteri UTF-8 nel valore, codificare 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 <booleano>

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

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

Aggiunto in: v0.5.9

• enable <booleano>
• initialDelay <numero>

Una volta che un socket viene assegnato a questa richiesta e 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. Uguale al binding all'evento 'timeout'.
• Restituisce: <http.ClientRequest>

Una volta che un socket è 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 di come 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}.`)
  // Consuma l'oggetto response
})

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}.`)
  // Consuma l'oggetto response
})

Questa proprietà è garantita per 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	Cambiamenti
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 blocco del corpo. Questo metodo può essere chiamato più volte. Se non è impostato Content-Length, i dati verranno codificati automaticamente nella codifica di trasferimento HTTP Chunked, in modo che il server sappia quando terminano i dati. L'intestazione Transfer-Encoding: chunked viene aggiunta. La chiamata a request.end() è necessaria 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 blocco di dati viene scaricato, ma solo se il blocco 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 è di nuovo libero.

Quando la funzione write viene chiamata con una stringa o un buffer vuoto, non fa nulla e aspetta più 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 di response.writeContinue() se il client deve continuare a inviare il corpo della richiesta, oppure la generazione di una risposta HTTP appropriata (ad esempio, 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 di 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', questo verrà inoltrato qui. Il listener di questo evento è responsabile della chiusura/distruzione del socket sottostante. Ad esempio, si potrebbe desiderare di chiudere il socket in modo più elegante 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 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>.

Il comportamento predefinito è di 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 gli header della corrente http.ServerResponse collegata sono stati inviati, 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, inclusi gli header di risposta e il payload, deve essere scritta direttamente sull'oggetto socket. Bisogna fare attenzione per garantire 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 di 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 dello stream di tunneling (può essere vuoto)

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

È 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>.

Dopo che questo evento è stato emesso, il socket della richiesta non avrà un listener di evento '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 di come il parser del protocollo si collega al socket. È possibile accedere al socket anche tramite request.socket.

Questo evento può anche essere emesso esplicitamente dagli utenti per iniettare connessioni nel server HTTP. In tal caso, è possibile passare 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 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>.

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 rilascerà nuove richieste ed emetterà l'evento 'dropRequest' invece, 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. Potrebbero esserci più richieste per connessione (nel caso di connessioni HTTP Keep-Alive).

Evento: 'upgrade'

[Cronologia]

Versione	Modifiche
v10.0.0	Non ascoltare più questo evento non causa più la distruzione del socket se un client invia un'intestazione 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 (potrebbe essere vuoto)

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

Dopo l'emissione di questo evento, 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.

È garantito che 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>.

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>

Interrompe l'accettazione di nuove connessioni da parte del server e chiude tutte le connessioni collegate a questo server che non stanno inviando una richiesta o in attesa di una risposta. Vedi 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: 'Ciao Mondo!',
    })
  )
})

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

server.closeAllConnections()

Aggiunto in: v18.2.0

Chiude tutte le connessioni HTTP(S) stabilite collegate a questo server, incluse le connessioni attive collegate a questo server che stanno inviando una richiesta o in attesa di 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: 'Ciao Mondo!',
    })
  )
})

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

server.closeIdleConnections()

Aggiunto in: v18.2.0

Chiude tutte le connessioni collegate a questo server che non stanno inviando una richiesta o in attesa di 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: 'Ciao Mondo!',
    })
  )
})

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

server.headersTimeout

[Cronologia]

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

• <numero> Predefinito: Il valore 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 della richiesta 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 proxy inverso di fronte.

server.listen()

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

server.listening

Aggiunto in: v5.7.0

• <booleano> Indica se il server è in ascolto o meno per le connessioni.

server.maxHeadersCount

Aggiunto in: v0.7.0

• <numero> Predefinito: 2000

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

server.requestTimeout

[Cronologia]

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

• <numero> 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 della richiesta 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 proxy inverso di fronte.

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

[Storia]

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 in timeout 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, il valore dell'intestazione Connection viene impostato su close, ma la connessione non viene effettivamente chiusa, le successive richieste inviate dopo che il limite è stato raggiunto riceveranno 503 Servizio non disponibile come risposta.

server.timeout

[Storia]

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 andato in timeout.

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

La logica di 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 dati in entrata aggiuntivi, dopo che ha finito di scrivere l'ultima risposta, prima che un socket venga distrutto. Se il server riceve nuovi dati prima che il timeout keep-alive scatti, ripristinerà 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 comportare il server http 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 viene impostata alla connessione, quindi la modifica di questo valore influisce solo sulle nuove connessioni al server, non sulle connessioni 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 viene risolta 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ù specificamente, questo evento viene emesso quando l'ultimo segmento delle intestazioni e del corpo della risposta sono stati consegnati al sistema operativo per la trasmissione sulla rete. Ciò non implica che il client abbia ancora ricevuto qualcosa.

response.addTrailers(headers)

Aggiunto in: v0.3.0

• headers <Object>

Questo metodo aggiunge intestazioni di coda HTTP (un'intestazione ma alla fine del messaggio) alla risposta.

I trailer verranno emessi solo se per la risposta viene utilizzata la codifica a blocchi; in caso contrario (ad es. se la richiesta era HTTP/1.0), verranno eliminati silenziosamente.

HTTP richiede che l'intestazione Trailer venga inviata per emettere i trailer, con un elenco dei campi di intestazione nel suo valore. Ad esempio,

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

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

response.connection

Aggiunto in: v0.3.0

Deprecato dal: v13.0.0

[Stabile: 0 - Deprecato]

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

• <stream.Duplex>

Vedere response.socket.

response.cork()

Aggiunto in: v13.2.0, v12.16.0

Vedere 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	Aggiunto in: v0.1.90

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

Questo metodo segnala al server che tutte le intestazioni di risposta e il corpo sono stati inviati; che il server deve considerare completo questo messaggio. Il metodo response.end() DEVE essere chiamato su ogni risposta.

Se data viene specificato, ha un effetto simile alla chiamata di response.write(data, encoding) seguita da response.end(callback).

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

response.finished

Aggiunto in: v0.0.2

Deprecato da: v13.4.0, v12.16.0

[Stabile: 0 - Deprecato]

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

• <boolean>

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

response.flushHeaders()

Aggiunto in: v1.6.0

Scarica gli header di risposta. Vedere 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 di ritorno 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 unici 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 dell'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'Object JavaScript. 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 <string>
• 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 <string>

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 HTTP request originale.

response.sendDate

Aggiunto in: v0.7.5

• <boolean>

Quando è true, l'header Date sarà generato automaticamente e inviato nella risposta se non è già presente negli header. Il valore predefinito è true.

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

response.setHeader(name, value)

Aggiunto in: v0.4.0

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

Restituisce l'oggetto response.

Imposta un singolo valore di header per gli header impliciti. Se questo header esiste già negli header da inviare, il suo valore verrà sostituito. Utilizzare un array di stringhe qui per inviare più header con lo stesso nome. I valori non stringa saranno memorizzati 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 response viene restituito al chiamante, per abilitare l'incatenamento delle chiamate.

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

oppure

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

Il tentativo di impostare un nome o un valore di campo di header che contiene caratteri non validi comporterà il lancio di un TypeError.

Quando gli header sono stati impostati con response.setHeader(), saranno uniti con tutti gli header passati a response.writeHead(), con gli header passati 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 di header forniti sul canale di rete senza memorizzare internamente nella cache, e response.getHeader() sull'header non produrrà il risultato previsto. Se si desidera un popolamento progressivo degli header con potenziali recuperi e modifiche future, 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 su msecs. Se viene fornito un callback, questo viene aggiunto come listener sull'evento 'timeout' sull'oggetto response.

Se nessun listener 'timeout' viene aggiunto alla richiesta, alla risposta o al server, i socket vengono distrutti quando si verifica un timeout. Se viene assegnato un gestore agli eventi 'timeout' della richiesta, della risposta o del server, i socket in timeout 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 a 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(`Il tuo indirizzo IP è ${ip} e la tua porta di origine è ${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(`Il tuo indirizzo IP è ${ip} e la tua porta di origine è ${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 questa proprietà viene lasciata 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 response.end() è stato chiamato. 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.

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 della 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 codificarlo in un flusso di byte. callback verrà chiamata quando questo blocco di dati viene scaricato.

Questo è il corpo HTTP raw e non ha nulla a che fare con codifiche di corpo multipart di livello superiore che possono essere utilizzate.

La prima volta che viene chiamato response.write(), invierà le informazioni dell'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 messi in coda nella memoria utente. 'drain' verrà emesso quando il buffer sarà 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 deve essere inviato. Vedi l'evento 'checkContinue' su Server.

response.writeEarlyHints(hints[, callback])

[Cronologia]

Versione	Modifiche
v18.11.0	Consente di passare gli hint come un 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. hints è un oggetto contenente i valori degli header da inviare con il messaggio early hints. L'argomento callback opzionale 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 un array.
v11.10.0, v10.17.0	Restituisce this da writeHead() per consentire il concatenamento 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 dall'utente 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 valori di chiave 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 una sola volta su un messaggio e deve essere chiamato prima di response.end().

Se response.write() o response.end() vengono chiamati prima di chiamare questo, gli header impliciti/mutabili verranno calcolati e verrà chiamata 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() a cui viene data 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 memorizzarli internamente nella cache, e il response.getHeader() sull'header non produrrà il risultato previsto. Se si desidera la popolazione progressiva degli header con un potenziale recupero e modifica futuri, utilizzare response.setHeader() invece.

// 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 trasmesso sono uguali o meno.

Il tentativo di impostare un nome o un valore di campo header che contenga caratteri non validi causerà 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 dovrebbe essere inviato.

Classe: http.IncomingMessage

[Cronologia]

Versione	Cambiamenti
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.

Diverso dal suo valore socket che è una sottoclasse di <stream.Duplex>, lo stesso IncomingMessage estende <stream.Readable> e viene creato separatamente per analizzare ed emettere le intestazioni HTTP in entrata e il payload, 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. Ascoltare invece l'evento 'close'.

Emesso quando la richiesta è stata interrotta.

Evento: 'close'

[Cronologia]

Versione	Cambiamenti
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. Controllare 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 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 a partire 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() assicura che le intestazioni duplicate non vengano scartate, ma piuttosto combinate usando un separatore di virgola, in conformità con la RFC 9110 Sezione 5.3.
v15.1.0	message.headers viene ora calcolato in modo pigro usando 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 valori delle intestazioni. I nomi delle intestazioni sono in minuscolo.

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

I duplicati nelle intestazioni raw 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 di unire i valori duplicati delle intestazioni sopra elencate, usare l'opzione joinDuplicateHeaders in http.request() e http.createServer(). Vedere la 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 insieme con ; .
• Per tutte le altre intestazioni, i valori vengono uniti insieme con , .

message.headersDistinct

Aggiunto in: v18.3.0, v16.17.0

• <Object>

Simile a message.headers, ma non c'è una logica di join e i valori sono sempre array di stringhe, anche per gli header ricevuti 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>

In caso di richiesta del server, la versione HTTP inviata dal client. Nel caso di risposta del client, la versione HTTP del server a cui ci si è connessi. Probabilmente '1.1' o '1.0'.

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

message.method

Aggiunto in: v0.1.1

• <string>

Valido solo per le richieste ottenute da http.Server.

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

message.rawHeaders

Aggiunto in: v0.11.6

• <string[]>

L'elenco degli header grezzi di richiesta/risposta esattamente come sono stati ricevuti.

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

I nomi degli header non sono in minuscolo e i duplicati non vengono uniti.

// Stampa qualcosa del tipo:
//
// [ 'user-agent',
//   'questo non è valido perché ce ne può essere solo uno',
//   '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 dei trailer di richiesta/risposta grezzi esattamente come sono stati ricevuti. 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, usa request.socket.getPeerCertificate() per ottenere i dettagli di autenticazione del client.

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> o internamente nullo.

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 di motivazione). Es: OK o Internal Server Error.

message.trailers

Aggiunto in: v0.3.0

• <Object>

L'oggetto dei trailer della 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 gli header ricevuti una sola volta. Popolato solo all'evento 'end'.

message.url

Aggiunto in: v0.1.90

• <string>

Valido solo per le richieste ottenute da http.Server.

Stringa dell'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:

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 sull'hostname del server o considera di sostituire completamente questa parte. Se si utilizza req.headers.host, assicurati che venga utilizzata una validazione adeguata, poiché i client possono 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 in uscita astratto dal punto di vista dei partecipanti di 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 con successo.

Evento: 'prefinish'

Aggiunto in: v0.11.6

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

outgoingMessage.addTrailers(headers)

Aggiunto in: v0.3.0

• headers <Oggetto>

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

I trailer verranno 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 es.

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 <stringa> Nome dell'intestazione
• value <stringa> | <stringa[]> Valore dell'intestazione
• Restituisce: <this>

Aggiunge un singolo valore di intestazione all'oggetto intestazione.

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

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

A seconda del valore di options.uniqueHeaders quando viene creata la richiesta del client o il server, questo farà sì che l'intestazione venga 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])

[Storia]

Versione	Modifiche
v15.0.0	Il parametro chunk ora può essere un Uint8Array.
v0.11.6	Aggiunto 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 qualche parte del corpo non è stata inviata, questa verrà inviata 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 fornita callback, questa verrà chiamata quando il messaggio è terminato (equivalente a un listener dell'evento 'finish').

outgoingMessage.flushHeaders()

Aggiunto in: v1.6.0

Scarica le intestazioni del messaggio.

Per motivi di efficienza, Node.js normalmente memorizza le intestazioni del messaggio nel buffer fino a quando non viene chiamato outgoingMessage.end() o viene scritto il primo chunk di dati del messaggio. Quindi cerca di impacchettare le intestazioni e i dati in un unico pacchetto TCP.

Solitamente è auspicabile (si risparmia un round-trip TCP), ma non quando i primi dati non vengono inviati fino a molto tempo dopo. outgoingMessage.flushHeaders() aggira 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 specificato. 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 degli 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 da Object di JavaScript. Ciò significa che i tipici metodi Object 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.

La chiamata di 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)

o

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

Quando le intestazioni sono state impostate con outgoingMessage.setHeaders(), verranno unite con 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) => {
  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. Equivalente al binding 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. Solitamente, gli utenti non dovrebbero accedere a questa proprietà.

Dopo aver chiamato outgoingMessage.end(), questa proprietà verrà impostata a 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. Per questo scopo, usa 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 memorizzati nel buffer.

outgoingMessage.writableObjectMode

Aggiunto in: v12.9.0

• <boolean>

Sempre false.

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

[Cronologia]

Versione	Cambiamenti
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 blocco del corpo. 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 blocco di dati verrà scaricato.

Restituisce true se l'intero dato è stato scaricato con successo nel buffer del kernel. Restituisce false se tutto o parte del dato è stato accodato 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 della 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 <Oggetto>

  • connectionsCheckingInterval: Imposta il valore dell'intervallo in millisecondi per verificare il timeout di richiesta e intestazioni nelle richieste incomplete. Predefinito: 30000.
  • headersTimeout: Imposta il valore di timeout in millisecondi per la ricezione delle intestazioni HTTP complete dal client. Vedi server.headersTimeout per maggiori informazioni. Predefinito: 60000.
  • highWaterMark <numero> Facoltativamente sovrascrive tutti i socket readableHighWaterMark e writableHighWaterMark. 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 flag di tolleranza abilitati. L'uso 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'originale IncomingMessage. Predefinito: IncomingMessage.
  • joinDuplicateHeaders <boolean> Se impostato su true, questa opzione consente di unire i valori della riga di campo di più intestazioni in una richiesta con una virgola (, ) invece di scartare i duplicati. Per maggiori informazioni, fare 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 ingresso, in modo simile a quanto viene fatto in [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)]. Predefinito: false.
  • keepAliveInitialDelay <numero> 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 arrivo, dopo aver terminato di scrivere l'ultima risposta, prima che un socket venga distrutto. Vedi server.keepAliveTimeout per maggiori informazioni. Predefinito: 5000.
  • maxHeaderSize <numero> Facoltativamente sovrascrive il valore di --max-http-header-size per le richieste ricevute da questo server, ovvero la lunghezza massima delle intestazioni della richiesta 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 ingresso. Predefinito: true.
  • requestTimeout: Imposta il valore di 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 non valida) a qualsiasi messaggio di richiesta HTTP/1.1 che non ha un'intestazione Host (come previsto dalla specifica). Predefinito: true.
  • ServerResponse <http.ServerResponse> Specifica la classe ServerResponse da utilizzare. Utile per estendere l'originale ServerResponse. 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 <Funzione>

• Restituisce: <http.Server>

Restituisce una nuova istanza di http.Server.

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

ESM

import http from 'node:http'

// Crea un server locale per ricevere i dati da
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')

// Crea un server locale per ricevere i dati da
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'

// Crea un server locale per ricevere i dati da
const server = http.createServer()

// Ascolta l'evento di richiesta
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')

// Crea un server locale per ricevere i dati da
const server = http.createServer()

// Ascolta l'evento di richiesta
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	Cambiamenti
v10.9.0	Il parametro url 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 <Oggetto> Accetta le stesse options di http.request(), con il metodo impostato su GET per impostazione predefinita.
• callback <Funzione>
• Restituisce: <http.ClientRequest>

Poiché la maggior parte delle richieste sono richieste GET senza corpi, Node.js fornisce questo comodo metodo. 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 occuparsi di consumare i dati di risposta per i motivi indicati nella sezione http.ClientRequest.

La callback viene invocata 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 riuscita ma
    // qui stiamo solo controllando 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 della 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 ottenuto: ${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'agente 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 utilizzata come predefinita per tutte le richieste client HTTP. Si differenzia da una configurazione predefinita di Agent per avere 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 delle intestazioni HTTP in byte. Il valore predefinito è 16 KiB. Configurato 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, lo username e la password analizzati verranno ora decodificati correttamente tramite 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 URL WHATWG.
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 i valori predefiniti.

  • auth <string> Autenticazione di base ('user:password') per calcolare un'intestazione 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 predefinita createConnection. Vedere agent.createConnection() per maggiori dettagli. Qualsiasi flusso 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 durante la risoluzione di 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 le intestazioni di richiesta.

  • hints <number> Suggerimenti opzionali per dns.lookup().

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

  • hostname <string> Alias per host. Per supportare url.parse(), hostname verrà utilizzato se vengono 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 non sicuro dovrebbe essere evitato. Vedere --insecure-http-parser per maggiori informazioni. Predefinito: false

  • joinDuplicateHeaders <boolean> Unisce i valori della riga di campo di più intestazioni in una richiesta con , invece di scartare i duplicati. Vedere 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 ricerca personalizzata. Predefinito: dns.lookup().

  • maxHeaderSize <number> Sovrascrive facoltativamente il valore di --max-http-header-size (la lunghezza massima delle intestazioni 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 le intestazioni predefinite come Connection, Content-Length, Transfer-Encoding e Host. Se impostato su false, tutte le intestazioni necessarie devono essere aggiunte manualmente. Il valore predefinito è true.

  • setHost <boolean>: Specifica se aggiungere o meno automaticamente l'intestazione 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 viene specificato uno tra 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 venga connesso.

  • uniqueHeaders <Array> Un elenco di intestazioni di richiesta che dovrebbero essere inviate una sola volta. Se il valore dell'intestazione è un array, gli elementi verranno uniti utilizzando ; .

• callback <Function>

• Restituisce: <http.ClientRequest>

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

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 analizzato automaticamente con new URL(). Se è un oggetto URL, verrà automaticamente convertito in un normale oggetto options.

Se vengono 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 è un flusso scrivibile. Se è necessario caricare un file con una richiesta POST, scrivere nell'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() è necessario chiamare sempre req.end() per indicare la fine della richiesta, anche se non vengono scritti dati nel corpo della richiesta.

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

Ci sono alcune intestazioni speciali che devono essere notate.

• L'invio di un'intestazione 'Connection: keep-alive' notificherà a Node.js che la connessione al server deve essere mantenuta fino alla richiesta successiva.
• L'invio di un'intestazione 'Content-Length' disabiliterà la codifica a blocchi predefinita.
• L'invio di un'intestazione 'Expect' invierà immediatamente le intestazioni di richiesta. Di solito, quando si invia 'Expect: 100-continue', è necessario impostare sia un timeout che un listener per l'evento 'continue'. Vedere la sezione 8.2.3 della RFC 2616 per maggiori informazioni.
• L'invio di un'intestazione 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 riuscita, i seguenti eventi verranno emessi nel seguente ordine:

• 'socket'

• 'response'

  • 'data' un numero qualsiasi di volte, sull'oggetto res (l'evento '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 il messaggio 'Error: socket hang up' e il codice 'ECONNRESET'
• 'close'

In caso di chiusura prematura della connessione 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

• (connessione chiusa qui)

• 'aborted' sull'oggetto res

• 'close'

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

• 'close' sull'oggetto res

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

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

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

• 'socket'
• (req.destroy() chiamato qui)
• 'error' con un errore con il messaggio 'Error: socket hang up' e il codice 'ECONNRESET', oppure 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 il messaggio 'Error: aborted' e il codice 'ECONNRESET', oppure l'errore con cui è stato chiamato req.destroy()

• 'close' sull'oggetto res

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

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

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

• 'socket'
• (req.abort() chiamato qui)
• 'abort'
• 'error' con un errore con il messaggio 'Error: socket hang up' e il 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 il messaggio 'Error: aborted' e il 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'.

Il passaggio di un AbortSignal e quindi la chiamata di abort() sul corrispondente AbortController si comporteranno allo stesso modo della chiamata di .destroy() sulla richiesta. In particolare, l'evento 'error' verrà emesso con un errore con il messaggio 'AbortError: The operation was aborted', il codice 'ABORT_ERR' e la causa, 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).

Il passaggio di un valore non valido 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) // --> 'Il nome dell'intestazione deve essere un token HTTP valido [""]'
}

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) // --> 'Il nome dell'intestazione deve essere un token HTTP valido [""]'
}

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).

Il passaggio di un valore non valido come value comporterà la generazione di un TypeError.

• L'errore di valore indefinito è 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) // --> 'Valore non valido "undefined" per l'intestazione "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) // --> 'Carattere non valido nel contenuto dell'intestazione ["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) // --> 'Valore non valido "undefined" per l'intestazione "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) // --> 'Carattere non valido nel contenuto dell'intestazione ["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.