HTTP

[Stable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código fuente: lib/http.js

Este módulo, que contiene tanto un cliente como un servidor, se puede importar a través de require('node:http') (CommonJS) o import * as http from 'node:http' (módulo ES).

Las interfaces HTTP en Node.js están diseñadas para admitir muchas características del protocolo que tradicionalmente han sido difíciles de usar. En particular, mensajes grandes, posiblemente codificados en fragmentos. La interfaz tiene cuidado de no almacenar en búfer solicitudes o respuestas completas, por lo que el usuario puede transmitir datos.

Los encabezados de mensajes HTTP están representados por un objeto como este:

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

Las claves están en minúsculas. Los valores no se modifican.

Para admitir el espectro completo de posibles aplicaciones HTTP, la API HTTP de Node.js es de muy bajo nivel. Solo se ocupa del manejo de flujos y del análisis de mensajes. Analiza un mensaje en encabezados y cuerpo, pero no analiza los encabezados reales ni el cuerpo.

Consulte message.headers para obtener detalles sobre cómo se manejan los encabezados duplicados.

Los encabezados sin procesar tal como se recibieron se conservan en la propiedad rawHeaders, que es una matriz de [clave, valor, clave2, valor2, ...]. Por ejemplo, el objeto de encabezado de mensaje anterior podría tener una lista rawHeaders como la siguiente:

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

Clase: http.Agent

Agregado en: v0.3.4

Un Agent es responsable de administrar la persistencia y la reutilización de conexiones para clientes HTTP. Mantiene una cola de solicitudes pendientes para un host y puerto dados, reutilizando una única conexión de socket para cada una hasta que la cola esté vacía, momento en el cual el socket se destruye o se coloca en un grupo donde se mantiene para ser utilizado nuevamente para solicitudes al mismo host y puerto. Si se destruye o se agrupa depende de la opción keepAlive.

Las conexiones agrupadas tienen TCP Keep-Alive habilitado para ellas, pero los servidores aún pueden cerrar las conexiones inactivas, en cuyo caso se eliminarán del grupo y se realizará una nueva conexión cuando se realice una nueva solicitud HTTP para ese host y puerto. Los servidores también pueden negarse a permitir múltiples solicitudes a través de la misma conexión, en cuyo caso la conexión tendrá que rehacerse para cada solicitud y no se podrá agrupar. El Agent seguirá realizando las solicitudes a ese servidor, pero cada una se realizará a través de una nueva conexión.

Cuando un cliente o el servidor cierra una conexión, se elimina del grupo. Cualquier socket no utilizado en el grupo se dejará de referenciar para no mantener el proceso de Node.js en ejecución cuando no haya solicitudes pendientes. (consulte socket.unref()).

Es una buena práctica, destroy() una instancia Agent cuando ya no está en uso, porque los sockets no utilizados consumen recursos del sistema operativo.

Los sockets se eliminan de un agente cuando el socket emite un evento 'close' o un evento 'agentRemove'. Cuando se pretende mantener una solicitud HTTP abierta durante mucho tiempo sin mantenerla en el agente, se puede hacer algo como lo siguiente:

http
  .get(options, res => {
    // Hacer cosas
  })
  .on('socket', socket => {
    socket.emit('agentRemove')
  })

También se puede usar un agente para una solicitud individual. Al proporcionar {agent: false} como una opción para las funciones http.get() o http.request(), se usará un Agent de un solo uso con opciones predeterminadas para la conexión del cliente.

agent:false:

http.get(
  {
    hostname: 'localhost',
    port: 80,
    path: '/',
    agent: false, // Crea un nuevo agente solo para esta solicitud
  },
  res => {
    // Hacer cosas con la respuesta
  }
)

new Agent([options])

[Historial]

Versión	Cambios
v15.6.0, v14.17.0	Cambia la programación predeterminada de 'fifo' a 'lifo'.
v14.5.0, v12.20.0	Añade la opción scheduling para especificar la estrategia de programación de sockets libres.
v14.5.0, v12.19.0	Añade la opción maxTotalSockets al constructor del agente.
v0.3.4	Añadido en: v0.3.4

• options <Object> Conjunto de opciones configurables para establecer en el agente. Puede tener los siguientes campos:
  • keepAlive <boolean> Mantener los sockets activos incluso cuando no hay solicitudes pendientes, para que puedan utilizarse para futuras solicitudes sin tener que restablecer una conexión TCP. No debe confundirse con el valor keep-alive de la cabecera Connection. La cabecera Connection: keep-alive siempre se envía cuando se utiliza un agente, excepto cuando la cabecera Connection se especifica explícitamente o cuando las opciones keepAlive y maxSockets se establecen respectivamente en false e Infinity, en cuyo caso se utilizará Connection: close. Predeterminado: false.
  • keepAliveMsecs <number> Cuando se utiliza la opción keepAlive, especifica el retraso inicial para los paquetes TCP Keep-Alive. Se ignora cuando la opción keepAlive es false o undefined. Predeterminado: 1000.
  • maxSockets <number> Número máximo de sockets permitidos por host. Si el mismo host abre varias conexiones simultáneas, cada solicitud utilizará un nuevo socket hasta que se alcance el valor maxSockets. Si el host intenta abrir más conexiones que maxSockets, las solicitudes adicionales entrarán en una cola de solicitudes pendientes y entrarán en estado de conexión activa cuando termine una conexión existente. Esto asegura que haya como máximo maxSockets conexiones activas en cualquier momento, desde un host dado. Predeterminado: Infinity.
  • maxTotalSockets <number> Número máximo de sockets permitidos para todos los hosts en total. Cada solicitud utilizará un nuevo socket hasta que se alcance el máximo. Predeterminado: Infinity.
  • maxFreeSockets <number> Número máximo de sockets por host que se dejan abiertos en estado libre. Sólo es relevante si keepAlive se establece en true. Predeterminado: 256.
  • scheduling <string> Estrategia de programación que se aplica al seleccionar el siguiente socket libre para usar. Puede ser 'fifo' o 'lifo'. La principal diferencia entre las dos estrategias de programación es que 'lifo' selecciona el socket utilizado más recientemente, mientras que 'fifo' selecciona el socket utilizado menos recientemente. En el caso de una baja tasa de solicitudes por segundo, la programación 'lifo' reducirá el riesgo de elegir un socket que el servidor pueda haber cerrado debido a la inactividad. En el caso de una alta tasa de solicitudes por segundo, la programación 'fifo' maximizará el número de sockets abiertos, mientras que la programación 'lifo' lo mantendrá lo más bajo posible. Predeterminado: 'lifo'.
  • timeout <number> Tiempo de espera del socket en milisegundos. Esto establecerá el tiempo de espera cuando se cree el socket.

options en socket.connect() también son compatibles.

Para configurar cualquiera de ellos, debe crearse una instancia personalizada de 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])

Agregado en: v0.11.4

• options <Objeto> Opciones que contienen detalles de la conexión. Consulte net.createConnection() para conocer el formato de las opciones.
• callback <Función> Función de callback que recibe el socket creado.
• Devuelve: <stream.Duplex>

Produce un socket/stream para ser utilizado en peticiones HTTP.

Por defecto, esta función es la misma que net.createConnection(). Sin embargo, los agentes personalizados pueden sobreescribir este método en caso de que se desee mayor flexibilidad.

Un socket/stream puede ser proporcionado de dos maneras: retornando el socket/stream desde esta función o pasando el socket/stream a callback.

Este método garantiza que se devuelva una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket distinto de <net.Socket>.

callback tiene una firma de (err, stream).

agent.keepSocketAlive(socket)

Agregado en: v8.1.0

• socket <stream.Duplex>

Se llama cuando socket se separa de una solicitud y podría ser mantenido por el Agent. El comportamiento predeterminado es:

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

Este método puede ser anulado por una subclase Agent particular. Si este método devuelve un valor falso, el socket se destruirá en lugar de persistirlo para su uso con la siguiente solicitud.

El argumento socket puede ser una instancia de <net.Socket>, una subclase de <stream.Duplex>.

agent.reuseSocket(socket, request)

Agregado en: v8.1.0

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

Se llama cuando socket se adjunta a request después de haber sido persistido debido a las opciones de keep-alive. El comportamiento predeterminado es:

socket.ref()

Este método puede ser anulado por una subclase Agent particular.

El argumento socket puede ser una instancia de <net.Socket>, una subclase de <stream.Duplex>.

agent.destroy()

Agregado en: v0.11.4

Destruye cualquier socket que esté actualmente en uso por el agente.

Por lo general, no es necesario hacer esto. Sin embargo, si se usa un agente con keepAlive habilitado, es mejor apagar explícitamente el agente cuando ya no sea necesario. De lo contrario, los sockets podrían permanecer abiertos durante bastante tiempo antes de que el servidor los termine.

agent.freeSockets

[Historial]

Versión	Cambios
v16.0.0	La propiedad ahora tiene un prototipo null.
v0.11.4	Agregado en: v0.11.4

• <Object>

Un objeto que contiene arreglos de sockets que actualmente esperan ser usados por el agente cuando keepAlive está habilitado. No modificar.

Los sockets en la lista freeSockets se destruirán automáticamente y se eliminarán del arreglo en 'timeout'.

agent.getName([options])

[Historial]

Versión	Cambios
v17.7.0, v16.15.0	El parámetro options ahora es opcional.
v0.11.4	Agregado en: v0.11.4

• options <Object> Un conjunto de opciones que proporciona información para la generación de nombres

  • host <string> Un nombre de dominio o dirección IP del servidor al que se debe emitir la solicitud
  • port <number> Puerto del servidor remoto
  • localAddress <string> Interfaz local para enlazar para conexiones de red al emitir la solicitud
  • family <integer> Debe ser 4 o 6 si esto no es igual a undefined.

• Devuelve: <string>

Obtiene un nombre único para un conjunto de opciones de solicitud, para determinar si una conexión se puede reutilizar. Para un agente HTTP, esto devuelve host:port:localAddress o host:port:localAddress:family. Para un agente HTTPS, el nombre incluye el CA, cert, cifrados y otras opciones específicas de HTTPS/TLS que determinan la reutilización del socket.

agent.maxFreeSockets

Agregado en: v0.11.7

• <number>

Por defecto establecido en 256. Para agentes con keepAlive habilitado, esto establece el número máximo de sockets que se dejarán abiertos en estado libre.

agent.maxSockets

Agregado en: v0.3.6

• <number>

Por defecto establecido en Infinity. Determina cuántos sockets concurrentes puede tener abiertos el agente por origen. El origen es el valor devuelto por agent.getName().

agent.maxTotalSockets

Agregado en: v14.5.0, v12.19.0

• <number>

Por defecto establecido en Infinity. Determina cuántos sockets concurrentes puede tener abiertos el agente. A diferencia de maxSockets, este parámetro se aplica a todos los orígenes.

agent.requests

[Historial]

Versión	Cambios
v16.0.0	La propiedad ahora tiene un prototipo null.
v0.5.9	Agregado en: v0.5.9

• <Object>

Un objeto que contiene colas de solicitudes que aún no se han asignado a los sockets. No modificar.

agent.sockets

[Historial]

Versión	Cambios
v16.0.0	La propiedad ahora tiene un prototipo null.
v0.3.6	Añadido en: v0.3.6

• <Objeto>

Un objeto que contiene arrays de sockets actualmente en uso por el agente. No modificar.

Clase: http.ClientRequest

Añadido en: v0.1.17

• Extiende: <http.OutgoingMessage>

Este objeto se crea internamente y se devuelve desde http.request(). Representa una solicitud en curso cuyo encabezado ya se ha puesto en cola. El encabezado aún es mutable usando la API setHeader(name, value), getHeader(name), removeHeader(name). El encabezado real se enviará junto con el primer fragmento de datos o al llamar a request.end().

Para obtener la respuesta, añade un listener para 'response' al objeto de solicitud. 'response' se emitirá desde el objeto de solicitud cuando se hayan recibido los encabezados de respuesta. El evento 'response' se ejecuta con un argumento que es una instancia de http.IncomingMessage.

Durante el evento 'response', se pueden agregar listeners al objeto de respuesta; particularmente para escuchar el evento 'data'.

Si no se añade ningún controlador 'response', entonces la respuesta se descartará por completo. Sin embargo, si se añade un controlador de eventos 'response', los datos del objeto de respuesta deben consumirse, ya sea llamando a response.read() siempre que haya un evento 'readable', o agregando un controlador 'data', o llamando al método .resume(). Hasta que se consuman los datos, el evento 'end' no se activará. Además, hasta que se lean los datos, consumirá memoria que eventualmente puede llevar a un error de 'proceso sin memoria'.

Por compatibilidad con versiones anteriores, res solo emitirá 'error' si hay un listener 'error' registrado.

Establece el encabezado Content-Length para limitar el tamaño del cuerpo de la respuesta. Si response.strictContentLength se establece en true, la falta de coincidencia del valor del encabezado Content-Length resultará en que se lance un Error, identificado por code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

El valor de Content-Length debe estar en bytes, no en caracteres. Utiliza Buffer.byteLength() para determinar la longitud del cuerpo en bytes.

Evento: 'abort'

Agregado en: v1.4.1

Obsoleto desde: v17.0.0, v16.12.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Escuche el evento 'close' en su lugar.

Emitido cuando el cliente ha abortado la solicitud. Este evento solo se emite en la primera llamada a abort().

Evento: 'close'

Agregado en: v0.5.4

Indica que la solicitud se completó o que su conexión subyacente se terminó prematuramente (antes de que se completara la respuesta).

Evento: 'connect'

Agregado en: v0.7.0

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

Emitido cada vez que un servidor responde a una solicitud con un método CONNECT. Si no se está escuchando este evento, los clientes que reciban un método CONNECT tendrán sus conexiones cerradas.

Se garantiza que este evento recibirá una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket distinto de <net.Socket>.

Un par cliente y servidor que muestra cómo escuchar el evento 'connect':

ESM

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

// Crea un proxy de túnel HTTP
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('okay')
})
proxy.on('connect', (req, clientSocket, head) => {
  // Conecta a un servidor de origen
  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)
  })
})

// Ahora que el proxy está en ejecución
proxy.listen(1337, '127.0.0.1', () => {
  // Realiza una solicitud a un proxy de túnel
  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('¡conectado!')

    // Realiza una solicitud a través de un túnel 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 de túnel HTTP
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' })
  res.end('okay')
})
proxy.on('connect', (req, clientSocket, head) => {
  // Conecta a un servidor de origen
  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)
  })
})

// Ahora que el proxy está en ejecución
proxy.listen(1337, '127.0.0.1', () => {
  // Realiza una solicitud a un proxy de túnel
  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('¡conectado!')

    // Realiza una solicitud a través de un túnel 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'

Agregado en: v0.3.2

Emitido cuando el servidor envía una respuesta HTTP '100 Continue', usualmente porque la solicitud contenía 'Expect: 100-continue'. Esta es una instrucción para que el cliente envíe el cuerpo de la solicitud.

Evento: 'finish'

Agregado en: v0.3.6

Emitido cuando se ha enviado la solicitud. Más específicamente, este evento se emite cuando el último segmento de los encabezados y el cuerpo de la respuesta se han entregado al sistema operativo para su transmisión a través de la red. No implica que el servidor haya recibido algo todavía.

Evento: 'information'

Agregado en: v10.0.0

• info <Object>
  • httpVersion <string>
  • httpVersionMajor <integer>
  • httpVersionMinor <integer>
  • statusCode <integer>
  • statusMessage <string>
  • headers <Object>
  • rawHeaders <string[]>

Emitido cuando el servidor envía una respuesta intermedia 1xx (excluyendo 101 Upgrade). Los listeners de este evento recibirán un objeto que contiene la versión HTTP, el código de estado, el mensaje de estado, el objeto de encabezados clave-valor y una matriz con los nombres de encabezado sin procesar seguidos de sus respectivos valores.

ESM

import { request } from 'node:http'

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

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

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

CJS

const http = require('node:http')

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

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

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

Los estados 101 Upgrade no disparan este evento debido a su ruptura con la cadena tradicional de solicitud/respuesta HTTP, como los web sockets, las actualizaciones TLS in situ o HTTP 2.0. Para recibir notificaciones de los avisos 101 Upgrade, escuche el evento 'upgrade' en su lugar.

Evento: 'response'

Añadido en: v0.1.0

• response <http.IncomingMessage>

Emitido cuando se recibe una respuesta a esta solicitud. Este evento se emite solo una vez.

Evento: 'socket'

Añadido en: v0.5.3

• socket <stream.Duplex>

Se garantiza que este evento recibirá una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket diferente a <net.Socket>.

Evento: 'timeout'

Añadido en: v0.7.8

Emitido cuando el socket subyacente agota el tiempo de espera por inactividad. Esto solo notifica que el socket ha estado inactivo. La solicitud debe destruirse manualmente.

Ver también: request.setTimeout().

Evento: 'upgrade'

Añadido en: v0.1.94

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

Emitido cada vez que un servidor responde a una solicitud con una actualización. Si no se está escuchando este evento y el código de estado de la respuesta es 101 Switching Protocols, los clientes que reciban un encabezado de actualización tendrán sus conexiones cerradas.

Se garantiza que este evento recibirá una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket diferente a <net.Socket>.

Un par cliente-servidor que muestra cómo escuchar el evento 'upgrade'.

ESM

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

// Crea un servidor 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) // eco de vuelta
})

// Ahora que el servidor está en ejecución
server.listen(1337, '127.0.0.1', () => {
  // hacer una solicitud
  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('¡actualizado!')
    socket.end()
    process.exit(0)
  })
})

CJS

const http = require('node:http')

// Crea un servidor 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) // eco de vuelta
})

// Ahora que el servidor está en ejecución
server.listen(1337, '127.0.0.1', () => {
  // hacer una solicitud
  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('¡actualizado!')
    socket.end()
    process.exit(0)
  })
})

request.abort()

Agregado en: v0.3.8

Obsoleto desde: v14.1.0, v13.14.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Utilice request.destroy() en su lugar.

Marca la solicitud como abortada. Llamar a esto hará que se descarten los datos restantes en la respuesta y que se destruya el socket.

request.aborted

[Historial]

Versión	Cambios
v17.0.0, v16.12.0	Obsoleto desde: v17.0.0, v16.12.0
v11.0.0	La propiedad aborted ya no es un número de marca de tiempo.
v0.11.14	Agregado en: v0.11.14

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Compruebe request.destroyed en su lugar.

• <boolean>

La propiedad request.aborted será true si la solicitud ha sido abortada.

request.connection

Añadido en: v0.3.0

Obsoleto desde: v13.0.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Use request.socket.

• <stream.Duplex>

Ver request.socket.

request.cork()

Añadido en: v13.2.0, v12.16.0

Ver writable.cork().

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

[Historial]

Versión	Cambios
v15.0.0	El parámetro data ahora puede ser un Uint8Array.
v10.0.0	Este método ahora devuelve una referencia a ClientRequest.
v0.1.90	Añadido en: v0.1.90

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

Termina de enviar la solicitud. Si alguna parte del cuerpo no se ha enviado, la enviará al flujo. Si la solicitud se envía en fragmentos, esto enviará el terminador '0\r\n\r\n'.

Si se especifica data, es equivalente a llamar a request.write(data, encoding) seguido de request.end(callback).

Si se especifica callback, se llamará cuando el flujo de la solicitud haya terminado.

request.destroy([error])

[Historial]

Versión	Cambios
v14.5.0	La función devuelve this para mantener la coherencia con otros flujos legibles.
v0.3.0	Añadido en: v0.3.0

• error <Error> Opcional, un error para emitir con el evento 'error'.
• Devuelve: <this>

Destruye la solicitud. Opcionalmente emite un evento 'error' y emite un evento 'close'. Llamar a esto provocará que los datos restantes en la respuesta se descarten y que el socket se destruya.

Consulte writable.destroy() para obtener más detalles.

request.destroyed

Añadido en: v14.1.0, v13.14.0

• <boolean>

Es true después de que se haya llamado a request.destroy().

Consulte writable.destroyed para obtener más detalles.

request.finished

Agregado en: v0.0.1

Obsoleto desde: v13.4.0, v12.16.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Utilice request.writableEnded.

• <boolean>

La propiedad request.finished será true si se ha llamado a request.end(). Se llamará automáticamente a request.end() si la solicitud se inició a través de http.get().

request.flushHeaders()

Agregado en: v1.6.0

Vacía los encabezados de la solicitud.

Por razones de eficiencia, Node.js normalmente almacena en búfer los encabezados de la solicitud hasta que se llama a request.end() o se escribe el primer fragmento de datos de la solicitud. Luego intenta empaquetar los encabezados y los datos de la solicitud en un solo paquete TCP.

Eso suele ser lo deseado (ahorra un viaje de ida y vuelta de TCP), pero no cuando los primeros datos no se envían hasta posiblemente mucho más tarde. request.flushHeaders() evita la optimización e inicia la solicitud.

request.getHeader(name)

Agregado en: v1.6.0

• name <string>
• Devuelve: <any>

Lee un encabezado en la solicitud. El nombre no distingue entre mayúsculas y minúsculas. El tipo del valor de retorno depende de los argumentos proporcionados 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' es 'text/html'
const contentLength = request.getHeader('Content-Length')
// 'contentLength' es de tipo number
const cookie = request.getHeader('Cookie')
// 'cookie' es de tipo string[]

request.getHeaderNames()

Agregado en: v7.7.0

• Devuelve: <string[]>

Devuelve un array que contiene los nombres únicos de los encabezados salientes actuales. Todos los nombres de encabezado están en minúsculas.

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

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

request.getHeaders()

Agregado en: v7.7.0

• Devuelve: <Objeto>

Devuelve una copia superficial de los encabezados salientes actuales. Dado que se utiliza una copia superficial, los valores de la matriz pueden mutarse sin llamadas adicionales a varios métodos del módulo http relacionados con los encabezados. Las claves del objeto devuelto son los nombres de los encabezados y los valores son los respectivos valores de los encabezados. Todos los nombres de los encabezados están en minúsculas.

El objeto devuelto por el método request.getHeaders() no hereda prototípicamente de Object de JavaScript. Esto significa que los métodos típicos de Object como obj.toString(), obj.hasOwnProperty() y otros no están definidos y no funcionarán.

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

Agregado en: v15.13.0, v14.17.0

• Devuelve: <string[]>

Devuelve un array que contiene los nombres únicos de los encabezados sin procesar salientes actuales. Los nombres de los encabezados se devuelven con su capitalización exacta establecida.

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

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

request.hasHeader(name)

Agregado en: v7.7.0

• name <string>
• Devuelve: <boolean>

Devuelve true si el encabezado identificado por name está actualmente establecido en los encabezados salientes. La coincidencia del nombre del encabezado no distingue entre mayúsculas y minúsculas.

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

request.maxHeadersCount

• <number> Predeterminado: 2000

Limita el número máximo de encabezados de respuesta. Si se establece en 0, no se aplicará ningún límite.

request.path

Agregado en: v0.4.0

• <string> La ruta de la solicitud.

request.method

Agregado en: v0.1.97

• <string> El método de la solicitud.

request.host

Agregado en: v14.5.0, v12.19.0

• <string> El host de la solicitud.

request.protocol

Agregado en: v14.5.0, v12.19.0

• <string> El protocolo de la solicitud.

request.removeHeader(name)

Agregado en: v1.6.0

• name <string>

Elimina un encabezado que ya está definido en el objeto headers.

request.removeHeader('Content-Type')

request.reusedSocket

Agregado en: v13.0.0, v12.16.0

• <boolean> Indica si la solicitud se envía a través de un socket reutilizado.

Cuando se envía una solicitud a través de un agente habilitado para keep-alive, el socket subyacente podría reutilizarse. Pero si el servidor cierra la conexión en un momento desafortunado, el cliente puede encontrarse con un error 'ECONNRESET'.

ESM

import http from 'node:http'

// El servidor tiene un tiempo de espera de keep-alive de 5 segundos por defecto
http
  .createServer((req, res) => {
    res.write('hola\n')
    res.end()
  })
  .listen(3000)

setInterval(() => {
  // Adaptando un agente keep-alive
  http.get('http://localhost:3000', { agent }, res => {
    res.on('data', data => {
      // No hacer nada
    })
  })
}, 5000) // Enviando solicitud en un intervalo de 5 segundos para que sea fácil alcanzar el tiempo de espera inactivo

CJS

const http = require('node:http')

// El servidor tiene un tiempo de espera de keep-alive de 5 segundos por defecto
http
  .createServer((req, res) => {
    res.write('hola\n')
    res.end()
  })
  .listen(3000)

setInterval(() => {
  // Adaptando un agente keep-alive
  http.get('http://localhost:3000', { agent }, res => {
    res.on('data', data => {
      // No hacer nada
    })
  })
}, 5000) // Enviando solicitud en un intervalo de 5 segundos para que sea fácil alcanzar el tiempo de espera inactivo

Al marcar una solicitud si reutilizó o no el socket, podemos hacer un reintento automático de errores basándonos en ello.

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 => {
      // Verificar si es necesario reintentar
      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 => {
      // Verificar si es necesario reintentar
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest()
      }
    })
}

retriableRequest()

request.setHeader(name, value)

Agregado en: v1.6.0

• name <string>
• value <any>

Establece un único valor de encabezado para el objeto de encabezados. Si este encabezado ya existe en los encabezados que se enviarán, su valor será reemplazado. Use un array de cadenas aquí para enviar múltiples encabezados con el mismo nombre. Los valores que no sean cadenas se almacenarán sin modificación. Por lo tanto, request.getHeader() puede devolver valores que no sean cadenas. Sin embargo, los valores que no sean cadenas se convertirán a cadenas para la transmisión por la red.

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

o

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

Cuando el valor es una cadena, se lanzará una excepción si contiene caracteres fuera de la codificación latin1.

Si necesita pasar caracteres UTF-8 en el valor, codifique el valor utilizando el estándar RFC 8187.

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

request.setNoDelay([noDelay])

Agregado en: v0.5.9

• noDelay <boolean>

Una vez que un socket se asigna a esta solicitud y se conecta, se llamará a socket.setNoDelay().

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

Agregado en: v0.5.9

• enable <boolean>
• initialDelay <number>

Una vez que un socket se asigna a esta solicitud y se conecta, se llamará a socket.setKeepAlive().

request.setTimeout(timeout[, callback])

[Historial]

Versión	Cambios
v9.0.0	Configura consistentemente el tiempo de espera del socket solo cuando el socket se conecta.
v0.5.9	Agregado en: v0.5.9

• timeout <number> Milisegundos antes de que una solicitud se agote.
• callback <Function> Función opcional que se llamará cuando ocurra un tiempo de espera. Igual que vincularse al evento 'timeout'.
• Devuelve: <http.ClientRequest>

Una vez que un socket se asigna a esta solicitud y se conecta, se llamará a socket.setTimeout().

request.socket

Agregado en: v0.3.0

• <stream.Duplex>

Referencia al socket subyacente. Por lo general, los usuarios no querrán acceder a esta propiedad. En particular, el socket no emitirá eventos 'readable' debido a cómo el analizador de protocolo se adjunta 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(`Tu dirección IP es ${ip} y tu puerto de origen es ${port}.`)
  // Consume el objeto de respuesta
})

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(`Tu dirección IP es ${ip} y tu puerto de origen es ${port}.`)
  // Consume el objeto de respuesta
})

Se garantiza que esta propiedad es una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket diferente a <net.Socket>.

request.uncork()

Agregado en: v13.2.0, v12.16.0

Ver writable.uncork().

request.writableEnded

Agregado en: v12.9.0

• <boolean>

Es true después de que se haya llamado a request.end(). Esta propiedad no indica si los datos se han vaciado, para ello use request.writableFinished en su lugar.

request.writableFinished

Agregado en: v12.7.0

• <boolean>

Es true si todos los datos se han vaciado al sistema subyacente, inmediatamente antes de que se emita el evento 'finish'.

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

[Historial]

Versión	Cambios
v15.0.0	El parámetro chunk ahora puede ser un Uint8Array.
v0.1.29	Agregado en: v0.1.29

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

Envía un fragmento del cuerpo. Este método se puede llamar varias veces. Si no se establece Content-Length, los datos se codificarán automáticamente en la codificación de transferencia HTTP Chunked, para que el servidor sepa cuándo terminan los datos. Se añade el encabezado Transfer-Encoding: chunked. Es necesario llamar a request.end() para finalizar el envío de la solicitud.

El argumento encoding es opcional y solo se aplica cuando chunk es una cadena. El valor predeterminado es 'utf8'.

El argumento callback es opcional y se llamará cuando se vacíe este fragmento de datos, pero solo si el fragmento no está vacío.

Devuelve true si todos los datos se han vaciado correctamente en el búfer del kernel. Devuelve false si todos o parte de los datos se han puesto en cola en la memoria del usuario. Se emitirá 'drain' cuando el búfer vuelva a estar libre.

Cuando la función write se llama con una cadena o un búfer vacíos, no hace nada y espera más entrada.

Clase: http.Server

Añadido en: v0.1.17

• Extiende: <net.Server>

Evento: 'checkContinue'

Añadido en: v0.3.0

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

Se emite cada vez que se recibe una solicitud con un HTTP Expect: 100-continue. Si no se escucha este evento, el servidor responderá automáticamente con un 100 Continue según corresponda.

Manejar este evento implica llamar a response.writeContinue() si el cliente debería continuar enviando el cuerpo de la solicitud, o generar una respuesta HTTP apropiada (por ejemplo, 400 Solicitud Incorrecta) si el cliente no debería continuar enviando el cuerpo de la solicitud.

Cuando se emite y maneja este evento, no se emitirá el evento 'request'.

Evento: 'checkExpectation'

Añadido en: v5.5.0

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

Se emite cada vez que se recibe una solicitud con un encabezado HTTP Expect, donde el valor no es 100-continue. Si no se escucha este evento, el servidor responderá automáticamente con un 417 Expectation Failed según corresponda.

Cuando se emite y maneja este evento, no se emitirá el evento 'request'.

Evento: 'clientError'

[Historial]

Versión	Cambios
v12.0.0	El comportamiento predeterminado devolverá un error 431 Request Header Fields Too Large si ocurre un error HPE_HEADER_OVERFLOW.
v9.4.0	El rawPacket es el búfer actual que acaba de ser analizado. Agregar este búfer al objeto de error del evento 'clientError' es para que los desarrolladores puedan registrar el paquete roto.
v6.0.0	La acción predeterminada de llamar a .destroy() en el socket ya no se llevará a cabo si hay listeners adjuntos para 'clientError'.
v0.1.94	Añadido en: v0.1.94

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

Si una conexión de cliente emite un evento 'error', se reenviará aquí. El listener de este evento es responsable de cerrar/destruir el socket subyacente. Por ejemplo, uno podría desear cerrar el socket de forma más elegante con una respuesta HTTP personalizada en lugar de interrumpir abruptamente la conexión. El socket debe cerrarse o destruirse antes de que finalice el listener.

Se garantiza que este evento recibirá una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket diferente a <net.Socket>.

El comportamiento predeterminado es intentar cerrar el socket con un '400 Bad Request' HTTP, o un '431 Request Header Fields Too Large' HTTP en el caso de un error HPE_HEADER_OVERFLOW. Si el socket no es escribible o se han enviado los encabezados del http.ServerResponse adjunto actual, se destruye inmediatamente.

socket es el objeto net.Socket del que se originó el error.

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)

Cuando ocurre el evento 'clientError', no hay objeto request ni response, por lo que cualquier respuesta HTTP enviada, incluidos los encabezados de respuesta y la carga útil, debe escribirse directamente en el objeto socket. Se debe tener cuidado para asegurar que la respuesta sea un mensaje de respuesta HTTP con el formato adecuado.

err es una instancia de Error con dos columnas adicionales:

• bytesParsed: el recuento de bytes del paquete de solicitud que Node.js puede haber analizado correctamente;
• rawPacket: el paquete sin procesar de la solicitud actual.

En algunos casos, el cliente ya ha recibido la respuesta y/o el socket ya ha sido destruido, como en el caso de errores ECONNRESET. Antes de intentar enviar datos al socket, es mejor verificar que aún se pueda escribir en él.

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'

Agregado en: v0.1.4

Se emite cuando el servidor se cierra.

Evento: 'connect'

Agregado en: v0.7.0

• request <http.IncomingMessage> Argumentos para la solicitud HTTP, tal como está en el evento 'request'
• socket <stream.Duplex> Socket de red entre el servidor y el cliente
• head <Buffer> El primer paquete del flujo de tunneling (puede estar vacío)

Se emite cada vez que un cliente solicita un método HTTP CONNECT. Si no se escucha este evento, las conexiones de los clientes que solicitan un método CONNECT se cerrarán.

Se garantiza que este evento recibirá una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket diferente a <net.Socket>.

Después de que se emita este evento, el socket de la solicitud no tendrá un detector de eventos 'data', lo que significa que deberá estar vinculado para manejar los datos enviados al servidor en ese socket.

Evento: 'connection'

Agregado en: v0.1.0

• socket <stream.Duplex>

Este evento se emite cuando se establece un nuevo flujo TCP. socket es típicamente un objeto de tipo net.Socket. Por lo general, los usuarios no querrán acceder a este evento. En particular, el socket no emitirá eventos 'readable' debido a cómo el analizador de protocolo se adjunta al socket. También se puede acceder al socket en request.socket.

Este evento también puede ser emitido explícitamente por los usuarios para inyectar conexiones en el servidor HTTP. En ese caso, se puede pasar cualquier flujo Duplex.

Si se llama a socket.setTimeout() aquí, el tiempo de espera será reemplazado por server.keepAliveTimeout cuando el socket haya servido una solicitud (si server.keepAliveTimeout no es cero).

Se garantiza que este evento recibirá una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket distinto de <net.Socket>.

Evento: 'dropRequest'

Añadido en: v18.7.0, v16.17.0

• request <http.IncomingMessage> Argumentos para la solicitud HTTP, como en el evento 'request'
• socket <stream.Duplex> Socket de red entre el servidor y el cliente

Cuando el número de solicitudes en un socket alcanza el umbral de server.maxRequestsPerSocket, el servidor descartará nuevas solicitudes y emitirá el evento 'dropRequest' en su lugar, luego enviará 503 al cliente.

Evento: 'request'

Añadido en: v0.1.0

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

Se emite cada vez que hay una solicitud. Puede haber múltiples solicitudes por conexión (en el caso de conexiones HTTP Keep-Alive).

Evento: 'upgrade'

[Historial]

Versión	Cambios
v10.0.0	Dejar de escuchar este evento ya no provoca que el socket se destruya si un cliente envía un encabezado Upgrade.
v0.1.94	Añadido en: v0.1.94

• request <http.IncomingMessage> Argumentos para la solicitud HTTP, como en el evento 'request'
• socket <stream.Duplex> Socket de red entre el servidor y el cliente
• head <Buffer> El primer paquete del flujo actualizado (puede estar vacío)

Se emite cada vez que un cliente solicita una actualización HTTP. Escuchar este evento es opcional y los clientes no pueden insistir en un cambio de protocolo.

Después de que se emite este evento, el socket de la solicitud no tendrá un escuchador de eventos 'data', lo que significa que deberá estar vinculado para manejar los datos enviados al servidor en ese socket.

Se garantiza que a este evento se le pasará una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket diferente a <net.Socket>.

server.close([callback])

[Historial]

Versión	Cambios
v19.0.0	El método cierra las conexiones inactivas antes de retornar.
v0.1.90	Agregado en: v0.1.90

• callback <Función>

Detiene la aceptación de nuevas conexiones por parte del servidor y cierra todas las conexiones establecidas a este servidor que no están enviando una solicitud o esperando una respuesta. Consulta 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: '¡Hola Mundo!',
    })
  )
})

server.listen(8000)
// Cierra el servidor después de 10 segundos
setTimeout(() => {
  server.close(() => {
    console.log('servidor en el puerto 8000 cerrado correctamente')
  })
}, 10000)

server.closeAllConnections()

Agregado en: v18.2.0

Cierra todas las conexiones HTTP(S) establecidas a este servidor, incluyendo las conexiones activas que están enviando una solicitud o esperando una respuesta. Esto no destruye los sockets actualizados a un protocolo diferente, como 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: '¡Hola Mundo!',
    })
  )
})

server.listen(8000)
// Cierra el servidor después de 10 segundos
setTimeout(() => {
  server.close(() => {
    console.log('servidor en el puerto 8000 cerrado correctamente')
  })
  // Cierra todas las conexiones, asegurando que el servidor se cierre correctamente
  server.closeAllConnections()
}, 10000)

server.closeIdleConnections()

Agregado en: v18.2.0

Cierra todas las conexiones conectadas a este servidor que no están enviando una solicitud ni esperando una respuesta.

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: '¡Hola Mundo!',
    })
  )
})

server.listen(8000)
// Cierra el servidor después de 10 segundos
setTimeout(() => {
  server.close(() => {
    console.log('servidor en el puerto 8000 cerrado correctamente')
  })
  // Cierra las conexiones inactivas, como las conexiones keep-alive. El servidor se cerrará
  // una vez que se terminen las conexiones activas restantes
  server.closeIdleConnections()
}, 10000)

server.headersTimeout

[Historial]

Versión	Cambios
v19.4.0, v18.14.0	El valor predeterminado ahora se establece en el mínimo entre 60000 (60 segundos) o requestTimeout.
v11.3.0, v10.14.0	Agregado en: v11.3.0, v10.14.0

• <number> Predeterminado: El mínimo entre server.requestTimeout o 60000.

Limita la cantidad de tiempo que el analizador esperará para recibir los encabezados HTTP completos.

Si el tiempo de espera expira, el servidor responde con el estado 408 sin reenviar la solicitud al receptor de la solicitud y luego cierra la conexión.

Debe establecerse en un valor distinto de cero (por ejemplo, 120 segundos) para proteger contra posibles ataques de denegación de servicio en caso de que el servidor se implemente sin un proxy inverso delante.

server.listen()

Comienza el servidor HTTP a escuchar conexiones. Este método es idéntico a server.listen() de net.Server.

server.listening

Añadido en: v5.7.0

• <boolean> Indica si el servidor está escuchando o no conexiones.

server.maxHeadersCount

Añadido en: v0.7.0

• <number> Predeterminado: 2000

Limita el número máximo de encabezados entrantes. Si se establece en 0, no se aplicará ningún límite.

server.requestTimeout

[Historial]

Versión	Cambios
v18.0.0	El tiempo de espera predeterminado de la solicitud cambió de sin tiempo de espera a 300 segundos (5 minutos).
v14.11.0	Añadido en: v14.11.0

• <number> Predeterminado: 300000

Establece el valor de tiempo de espera en milisegundos para recibir la solicitud completa del cliente.

Si el tiempo de espera expira, el servidor responde con el estado 408 sin reenviar la solicitud al listener de la solicitud y luego cierra la conexión.

Debe establecerse en un valor distinto de cero (por ejemplo, 120 segundos) para proteger contra posibles ataques de denegación de servicio en caso de que el servidor se implemente sin un proxy inverso delante.

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

[Historial]

Versión	Cambios
v13.0.0	El tiempo de espera predeterminado cambió de 120s a 0 (sin tiempo de espera).
v0.9.12	Añadido en: v0.9.12

• msecs <number> Predeterminado: 0 (sin tiempo de espera)
• callback <Function>
• Devuelve: <http.Server>

Establece el valor de tiempo de espera para los sockets y emite un evento 'timeout' en el objeto Server, pasando el socket como argumento, si ocurre un tiempo de espera.

Si hay un listener de eventos 'timeout' en el objeto Server, entonces será llamado con el socket con tiempo de espera como argumento.

De forma predeterminada, el Server no establece tiempo de espera para los sockets. Sin embargo, si se asigna un callback al evento 'timeout' del Server, los tiempos de espera deben manejarse explícitamente.

server.maxRequestsPerSocket

Añadido en: v16.10.0

• <number> Solicitudes por socket. Predeterminado: 0 (sin límite)

El número máximo de solicitudes que el socket puede manejar antes de cerrar la conexión keep alive.

Un valor de 0 desactivará el límite.

Cuando se alcanza el límite, establecerá el valor del encabezado Connection en close, pero en realidad no cerrará la conexión; las solicitudes posteriores enviadas después de que se alcance el límite obtendrán 503 Servicio no disponible como respuesta.

server.timeout

[Historial]

Versión	Cambios
v13.0.0	El tiempo de espera predeterminado cambió de 120s a 0 (sin tiempo de espera).
v0.9.12	Añadido en: v0.9.12

• <número> Tiempo de espera en milisegundos. Predeterminado: 0 (sin tiempo de espera)

El número de milisegundos de inactividad antes de que se presuma que un socket ha agotado el tiempo de espera.

Un valor de 0 deshabilitará el comportamiento de tiempo de espera en las conexiones entrantes.

La lógica de tiempo de espera del socket se configura en la conexión, por lo que cambiar este valor solo afecta a las nuevas conexiones al servidor, no a las conexiones existentes.

server.keepAliveTimeout

Añadido en: v8.0.0

• <número> Tiempo de espera en milisegundos. Predeterminado: 5000 (5 segundos).

El número de milisegundos de inactividad que un servidor necesita esperar para datos entrantes adicionales, después de que haya terminado de escribir la última respuesta, antes de que se destruya un socket. Si el servidor recibe nuevos datos antes de que se active el tiempo de espera de keep-alive, restablecerá el tiempo de espera de inactividad regular, es decir, server.timeout.

Un valor de 0 deshabilitará el comportamiento de tiempo de espera de keep-alive en las conexiones entrantes. Un valor de 0 hace que el servidor http se comporte de manera similar a las versiones de Node.js anteriores a la 8.0.0, que no tenían un tiempo de espera de keep-alive.

La lógica de tiempo de espera del socket se configura en la conexión, por lo que cambiar este valor solo afecta a las nuevas conexiones al servidor, no a las conexiones existentes.

server[Symbol.asyncDispose]()

Agregado en: v20.4.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Llama a server.close() y devuelve una promesa que se cumple cuando el servidor se ha cerrado.

Clase: http.ServerResponse

Agregado en: v0.1.17

• Extiende: <http.OutgoingMessage>

Este objeto es creado internamente por un servidor HTTP, no por el usuario. Se pasa como el segundo parámetro al evento 'request'.

Evento: 'close'

Agregado en: v0.6.7

Indica que la respuesta se ha completado o que su conexión subyacente se ha terminado prematuramente (antes de que se complete la respuesta).

Evento: 'finish'

Agregado en: v0.3.6

Se emite cuando se ha enviado la respuesta. Más específicamente, este evento se emite cuando el último segmento de los encabezados y el cuerpo de la respuesta se han entregado al sistema operativo para su transmisión a través de la red. No implica que el cliente haya recibido nada todavía.

response.addTrailers(headers)

Agregado en: v0.3.0

• headers <Object>

Este método agrega encabezados HTTP de cola (un encabezado pero al final del mensaje) a la respuesta.

Los trailers solo se emitirán si se utiliza la codificación fragmentada para la respuesta; si no es así (por ejemplo, si la solicitud era HTTP/1.0), se descartarán silenciosamente.

HTTP requiere que se envíe el encabezado Trailer para emitir trailers, con una lista de los campos de encabezado en su valor. Por ejemplo,

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

Intentar establecer un nombre o valor de campo de encabezado que contenga caracteres no válidos resultará en que se lance un TypeError.

response.connection

Agregado en: v0.3.0

Obsoleto desde: v13.0.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Use response.socket.

• <stream.Duplex>

Vea response.socket.

response.cork()

Añadido en: v13.2.0, v12.16.0

Ver writable.cork().

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

[Historial]

Versión	Cambios
v15.0.0	El parámetro data ahora puede ser un Uint8Array.
v10.0.0	Este método ahora retorna una referencia a ServerResponse.
v0.1.90	Añadido en: v0.1.90

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

Este método indica al servidor que todos los encabezados y el cuerpo de la respuesta han sido enviados; que el servidor debe considerar este mensaje como completo. El método, response.end(), DEBE ser llamado en cada respuesta.

Si se especifica data, es similar en efecto a llamar a response.write(data, encoding) seguido de response.end(callback).

Si se especifica callback, se llamará cuando la transmisión de la respuesta haya terminado.

response.finished

Añadido en: v0.0.2

Obsoleto desde: v13.4.0, v12.16.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Utilice response.writableEnded.

• <boolean>

La propiedad response.finished será true si se ha llamado a response.end().

response.flushHeaders()

Añadido en: v1.6.0

Descarga los encabezados de la respuesta. Consulte también: request.flushHeaders().

response.getHeader(name)

Añadido en: v0.4.0

• name <string>
• Devuelve: <any>

Lee un encabezado que ya se ha puesto en cola pero que no se ha enviado al cliente. El nombre no distingue entre mayúsculas y minúsculas. El tipo del valor de retorno depende de los argumentos proporcionados 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 es 'text/html'
const contentLength = response.getHeader('Content-Length')
// contentLength es de tipo number
const setCookie = response.getHeader('set-cookie')
// setCookie es de tipo string[]

response.getHeaderNames()

Agregado en: v7.7.0

• Devuelve: <string[]>

Devuelve un array que contiene los nombres únicos de los encabezados salientes actuales. Todos los nombres de encabezados están en minúsculas.

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

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

response.getHeaders()

Agregado en: v7.7.0

• Devuelve: <Object>

Devuelve una copia superficial de los encabezados salientes actuales. Dado que se utiliza una copia superficial, los valores del array se pueden mutar sin llamadas adicionales a varios métodos del módulo http relacionados con los encabezados. Las claves del objeto devuelto son los nombres de los encabezados y los valores son los valores de los encabezados respectivos. Todos los nombres de los encabezados están en minúsculas.

El objeto devuelto por el método response.getHeaders() no hereda prototípicamente de JavaScript Object. Esto significa que los métodos típicos de Object, como obj.toString(), obj.hasOwnProperty() y otros, no están definidos y no funcionarán.

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)

Agregado en: v7.7.0

• name <string>
• Devuelve: <boolean>

Devuelve true si el encabezado identificado por name está actualmente establecido en los encabezados salientes. La coincidencia del nombre del encabezado no distingue entre mayúsculas y minúsculas.

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

response.headersSent

Agregado en: v0.9.3

• <boolean>

Booleano (solo lectura). True si se enviaron los encabezados, false en caso contrario.

response.removeHeader(name)

Agregado en: v0.4.0

• name <string>

Elimina un encabezado que está en cola para el envío implícito.

response.removeHeader('Content-Encoding')

response.req

Agregado en: v15.7.0

• <http.IncomingMessage>

Una referencia al objeto HTTP request original.

response.sendDate

Agregado en: v0.7.5

• <boolean>

Cuando es true, la cabecera Date se generará y enviará automáticamente en la respuesta si no está presente en las cabeceras. El valor predeterminado es true.

Esto solo debe desactivarse para pruebas; HTTP requiere la cabecera Date en las respuestas.

response.setHeader(name, value)

Agregado en: v0.4.0

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

Devuelve el objeto de respuesta.

Establece un único valor de cabecera para cabeceras implícitas. Si esta cabecera ya existe en las cabeceras a enviar, su valor será reemplazado. Use un array de cadenas aquí para enviar múltiples cabeceras con el mismo nombre. Los valores que no sean cadenas se almacenarán sin modificación. Por lo tanto, response.getHeader() puede devolver valores que no son cadenas. Sin embargo, los valores que no son cadenas se convertirán a cadenas para la transmisión de red. Se devuelve el mismo objeto de respuesta al llamador, para habilitar el encadenamiento de llamadas.

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

o

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

Intentar establecer un nombre o valor de campo de cabecera que contenga caracteres no válidos resultará en un TypeError que se lanza.

Cuando las cabeceras se han establecido con response.setHeader(), se fusionarán con cualquier cabecera pasada a response.writeHead(), con las cabeceras pasadas a response.writeHead() que tienen prioridad.

// Devuelve 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')
})

Si se llama al método response.writeHead() y este método no se ha llamado, escribirá directamente los valores de cabecera suministrados en el canal de red sin almacenamiento en caché interno, y response.getHeader() en la cabecera no producirá el resultado esperado. Si se desea una población progresiva de cabeceras con una posible recuperación y modificación futuras, utilice response.setHeader() en lugar de response.writeHead().

response.setTimeout(msecs[, callback])

Añadido en: v0.9.12

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

Establece el valor de tiempo de espera del Socket en msecs. Si se proporciona una función de devolución de llamada, se agrega como un detector en el evento 'timeout' en el objeto de respuesta.

Si no se agrega ningún detector 'timeout' a la solicitud, la respuesta o el servidor, los sockets se destruyen cuando se agota el tiempo de espera. Si se asigna un controlador a los eventos 'timeout' de la solicitud, la respuesta o el servidor, los sockets con tiempo de espera agotado deben manejarse explícitamente.

response.socket

Añadido en: v0.3.0

• <stream.Duplex>

Referencia al socket subyacente. Por lo general, los usuarios no querrán acceder a esta propiedad. En particular, el socket no emitirá eventos 'readable' debido a cómo el analizador de protocolo se adjunta al socket. Después de response.end(), la propiedad se establece en nulo.

ESM

import http from 'node:http'
const server = http
  .createServer((req, res) => {
    const ip = res.socket.remoteAddress
    const port = res.socket.remotePort
    res.end(`Tu dirección IP es ${ip} y tu puerto de origen es ${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(`Tu dirección IP es ${ip} y tu puerto de origen es ${port}.`)
  })
  .listen(3000)

Se garantiza que esta propiedad es una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket diferente a <net.Socket>.

response.statusCode

Agregado en: v0.4.0

• <number> Predeterminado: 200

Cuando se utilizan encabezados implícitos (no se llama a response.writeHead() explícitamente), esta propiedad controla el código de estado que se enviará al cliente cuando se vacíen los encabezados.

response.statusCode = 404

Después de que el encabezado de respuesta se envió al cliente, esta propiedad indica el código de estado que se envió.

response.statusMessage

Agregado en: v0.11.8

• <string>

Cuando se utilizan encabezados implícitos (no se llama a response.writeHead() explícitamente), esta propiedad controla el mensaje de estado que se enviará al cliente cuando se vacíen los encabezados. Si se deja como undefined, se utilizará el mensaje estándar para el código de estado.

response.statusMessage = 'No encontrado'

Después de que el encabezado de respuesta se envió al cliente, esta propiedad indica el mensaje de estado que se envió.

response.strictContentLength

Agregado en: v18.10.0, v16.18.0

• <boolean> Predeterminado: false

Si se establece en true, Node.js verificará si el valor del encabezado Content-Length y el tamaño del cuerpo, en bytes, son iguales. Una discrepancia en el valor del encabezado Content-Length resultará en que se lance un Error, identificado por code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

response.uncork()

Agregado en: v13.2.0, v12.16.0

Ver writable.uncork().

response.writableEnded

Agregado en: v12.9.0

• <boolean>

Es true después de que se haya llamado a response.end(). Esta propiedad no indica si los datos se han vaciado, para ello use response.writableFinished en su lugar.

response.writableFinished

Añadido en: v12.7.0

• <boolean>

Es true si todos los datos se han volcado al sistema subyacente, inmediatamente antes de que se emita el evento 'finish'.

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

[Historial]

Versión	Cambios
v15.0.0	El parámetro chunk ahora puede ser un Uint8Array.
v0.1.29	Añadido en: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Predeterminado: 'utf8'
• callback <Function>
• Devuelve: <boolean>

Si se llama a este método y no se ha llamado a response.writeHead(), cambiará al modo de encabezado implícito y vaciará los encabezados implícitos.

Esto envía un fragmento del cuerpo de la respuesta. Este método se puede llamar varias veces para proporcionar partes sucesivas del cuerpo.

Si rejectNonStandardBodyWrites se establece en true en createServer, entonces no se permite escribir en el cuerpo cuando el método de solicitud o el estado de la respuesta no admiten contenido. Si se intenta escribir en el cuerpo para una solicitud HEAD o como parte de una respuesta 204 o 304, se lanza un Error síncrono con el código ERR_HTTP_BODY_NOT_ALLOWED.

chunk puede ser una cadena o un búfer. Si chunk es una cadena, el segundo parámetro especifica cómo codificarla en un flujo de bytes. Se llamará a callback cuando se vacíe este fragmento de datos.

Este es el cuerpo HTTP sin procesar y no tiene nada que ver con las codificaciones de cuerpo de varias partes de nivel superior que se puedan usar.

La primera vez que se llama a response.write(), enviará la información del encabezado almacenada en el búfer y el primer fragmento del cuerpo al cliente. La segunda vez que se llama a response.write(), Node.js asume que los datos se transmitirán y envía los nuevos datos por separado. Es decir, la respuesta se almacena en el búfer hasta el primer fragmento del cuerpo.

Devuelve true si todos los datos se volcaron correctamente al búfer del kernel. Devuelve false si todos o parte de los datos se pusieron en cola en la memoria del usuario. Se emitirá 'drain' cuando el búfer esté libre de nuevo.

response.writeContinue()

Añadido en: v0.3.0

Envía un mensaje HTTP/1.1 100 Continue al cliente, indicando que el cuerpo de la solicitud debe ser enviado. Vea el evento 'checkContinue' en Server.

response.writeEarlyHints(hints[, callback])

[Historial]

Versión	Cambios
v18.11.0	Permite pasar pistas como un objeto.
v18.11.0	Añadido en: v18.11.0

• hints <Objeto>
• callback <Función>

Envía un mensaje HTTP/1.1 103 Early Hints al cliente con una cabecera Link, indicando que el agente de usuario puede precargar/preconectar los recursos enlazados. hints es un objeto que contiene los valores de las cabeceras que se enviarán con el mensaje de pistas tempranas. El argumento opcional callback se llamará cuando se haya escrito el mensaje de respuesta.

Ejemplo

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('mensaje de pistas tempranas enviado')
response.writeEarlyHints(
  {
    link: earlyHintsLinks,
  },
  earlyHintsCallback
)

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

[Historial]

Versión	Cambios
v14.14.0	Permite pasar encabezados como un array.
v11.10.0, v10.17.0	Devuelve this desde writeHead() para permitir encadenar con end().
v5.11.0, v4.4.5	Se lanza un RangeError si statusCode no es un número en el rango [100, 999].
v0.1.30	Añadido en: v0.1.30

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

Envía un encabezado de respuesta a la petición. El código de estado es un código de estado HTTP de 3 dígitos, como 404. El último argumento, headers, son los encabezados de la respuesta. Opcionalmente se puede dar un statusMessage legible por humanos como segundo argumento.

headers puede ser un Array donde las claves y los valores están en la misma lista. No es una lista de tuplas. Así, los desplazamientos de número par son valores clave, y los desplazamientos de número impar son los valores asociados. El array está en el mismo formato que request.rawHeaders.

Devuelve una referencia a ServerResponse, de modo que las llamadas puedan ser encadenadas.

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

Este método debe ser llamado una sola vez en un mensaje y debe ser llamado antes de que se llame a response.end().

Si se llama a response.write() o response.end() antes de llamar a esto, se calcularán los encabezados implícitos/mutables y se llamará a esta función.

Cuando los encabezados se han establecido con response.setHeader(), se fusionarán con cualquier encabezado pasado a response.writeHead(), con los encabezados pasados a response.writeHead() teniendo prioridad.

Si se llama a este método y no se ha llamado a response.setHeader(), escribirá directamente los valores del encabezado suministrados en el canal de red sin almacenamiento en caché interno, y el response.getHeader() en el encabezado no producirá el resultado esperado. Si se desea una población progresiva de los encabezados con potencial recuperación y modificación futura, use response.setHeader() en su lugar.

// Devuelve 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 se lee en bytes, no en caracteres. Use Buffer.byteLength() para determinar la longitud del cuerpo en bytes. Node.js comprobará si Content-Length y la longitud del cuerpo que se ha transmitido son iguales o no.

Intentar establecer un nombre de campo de encabezado o un valor que contenga caracteres no válidos resultará en un [Error][] siendo lanzado.

response.writeProcessing()

Añadido en: v10.0.0

Envía un mensaje HTTP/1.1 102 Processing al cliente, indicando que el cuerpo de la solicitud debe ser enviado.

Clase: http.IncomingMessage

[Historial]

Versión	Cambios
v15.5.0	El valor destroyed devuelve true después de que se consume la información entrante.
v13.1.0, v12.16.0	El valor readableHighWaterMark refleja el del socket.
v0.1.17	Añadido en: v0.1.17

• Extiende: <stream.Readable>

Un objeto IncomingMessage es creado por http.Server o http.ClientRequest y pasado como primer argumento a los eventos 'request' y 'response' respectivamente. Se puede usar para acceder al estado, encabezados y datos de la respuesta.

A diferencia de su valor socket que es una subclase de <stream.Duplex>, el propio IncomingMessage extiende <stream.Readable> y se crea por separado para analizar y emitir los encabezados HTTP entrantes y la carga útil, ya que el socket subyacente puede reutilizarse varias veces en caso de keep-alive.

Evento: 'aborted'

Agregado en: v0.3.8

Obsoleto desde: v17.0.0, v16.12.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Escuche el evento 'close' en su lugar.

Emitido cuando la solicitud ha sido abortada.

Evento: 'close'

[Historial]

Versión	Cambios
v16.0.0	El evento close ahora se emite cuando la solicitud se ha completado y no cuando se cierra el socket subyacente.
v0.4.2	Agregado en: v0.4.2

Emitido cuando la solicitud se ha completado.

message.aborted

Agregado en: v10.1.0

Obsoleto desde: v17.0.0, v16.12.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Verifique message.destroyed desde <stream.Readable>.

• <boolean>

La propiedad message.aborted será true si la solicitud ha sido abortada.

message.complete

Agregado en: v0.3.0

• <boolean>

La propiedad message.complete será true si se ha recibido un mensaje HTTP completo y se ha analizado correctamente.

Esta propiedad es particularmente útil como medio para determinar si un cliente o servidor transmitió completamente un mensaje antes de que se terminara una conexión:

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 conexión se terminó mientras el mensaje aún se estaba enviando')
    })
  }
)

message.connection

Agregado en: v0.1.90

Obsoleto desde: v16.0.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto. Use message.socket.

Alias para message.socket.

message.destroy([error])

[Historial]

Versión	Cambios
v14.5.0, v12.19.0	La función devuelve this para mantener la coherencia con otros flujos legibles.
v0.3.0	Añadido en: v0.3.0

• error <Error>
• Devuelve: <this>

Llama a destroy() en el socket que recibió el IncomingMessage. Si se proporciona error, se emite un evento 'error' en el socket y error se pasa como argumento a cualquier receptor en el evento.

message.headers

[Historial]

Versión	Cambios
v19.5.0, v18.14.0	La opción joinDuplicateHeaders en las funciones http.request() y http.createServer() asegura que los encabezados duplicados no se descarten, sino que se combinen usando un separador de coma, de acuerdo con la Sección 5.3 de RFC 9110.
v15.1.0	message.headers ahora se calcula de forma perezosa usando una propiedad de acceso en el prototipo y ya no es enumerable.
v0.1.5	Añadido en: v0.1.5

• <Object>

El objeto de encabezados de solicitud/respuesta.

Pares clave-valor de nombres y valores de encabezado. Los nombres de los encabezados están en minúsculas.

// Imprime algo como:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers)

Los duplicados en los encabezados sin procesar se manejan de las siguientes maneras, según el nombre del encabezado:

• Los duplicados de 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 se descartan. Para permitir que se unan valores duplicados de los encabezados enumerados anteriormente, use la opción joinDuplicateHeaders en http.request() y http.createServer(). Consulte la Sección 5.3 de RFC 9110 para obtener más información.
• set-cookie es siempre una matriz. Los duplicados se agregan a la matriz.
• Para los encabezados cookie duplicados, los valores se unen con ; .
• Para todos los demás encabezados, los valores se unen con , .

message.headersDistinct

Agregado en: v18.3.0, v16.17.0

• <Object>

Similar a message.headers, pero no hay lógica de unión y los valores son siempre arreglos de cadenas, incluso para las cabeceras recibidas una sola vez.

// Imprime algo como:
//
// { 'user-agent': ['curl/7.22.0'],
//   host: ['127.0.0.1:8000'],
//   accept: ['*/*'] }
console.log(request.headersDistinct)

message.httpVersion

Agregado en: v0.1.1

• <string>

En caso de una solicitud del servidor, la versión HTTP enviada por el cliente. En el caso de una respuesta del cliente, la versión HTTP del servidor al que se conectó. Probablemente sea '1.1' o '1.0'.

También message.httpVersionMajor es el primer entero y message.httpVersionMinor es el segundo.

message.method

Agregado en: v0.1.1

• <string>

Solo válido para solicitudes obtenidas de http.Server.

El método de solicitud como una cadena. Solo lectura. Ejemplos: 'GET', 'DELETE'.

message.rawHeaders

Agregado en: v0.11.6

• <string[]>

La lista de encabezados sin procesar de la solicitud/respuesta tal como se recibieron.

Las claves y los valores están en la misma lista. No es una lista de tuplas. Por lo tanto, los desplazamientos con números pares son valores clave y los desplazamientos con números impares son los valores asociados.

Los nombres de los encabezados no se convierten a minúsculas y los duplicados no se fusionan.

// Imprime algo como:
//
// [ 'user-agent',
//   'esto es inválido porque solo puede haber uno',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders)

message.rawTrailers

Agregado en: v0.11.6

• <string[]>

Las claves y valores de los trailers sin procesar de la solicitud/respuesta tal como se recibieron. Solo se completa en el evento 'end'.

message.setTimeout(msecs[, callback])

Agregado en: v0.5.9

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

Llama a message.socket.setTimeout(msecs, callback).

message.socket

Agregado en: v0.3.0

• <stream.Duplex>

El objeto net.Socket asociado con la conexión.

Con soporte HTTPS, utilice request.socket.getPeerCertificate() para obtener los detalles de autenticación del cliente.

Se garantiza que esta propiedad sea una instancia de la clase <net.Socket>, una subclase de <stream.Duplex>, a menos que el usuario especifique un tipo de socket diferente a <net.Socket> o se anule internamente.

message.statusCode

Agregado en: v0.1.1

• <number>

Solo válido para la respuesta obtenida de http.ClientRequest.

El código de estado de respuesta HTTP de 3 dígitos. Por ejemplo, 404.

message.statusMessage

Agregado en: v0.11.10

• <string>

Solo válido para la respuesta obtenida de http.ClientRequest.

El mensaje de estado de la respuesta HTTP (frase de razón). Por ejemplo, OK o Internal Server Error.

message.trailers

Añadido en: v0.3.0

• <Objeto>

El objeto de tráileres de solicitud/respuesta. Solo se completa en el evento 'end'.

message.trailersDistinct

Añadido en: v18.3.0, v16.17.0

• <Objeto>

Similar a message.trailers, pero no hay lógica de unión y los valores son siempre arrays de cadenas, incluso para encabezados recibidos una sola vez. Solo se completa en el evento 'end'.

message.url

Añadido en: v0.1.90

• <cadena>

Solo válido para solicitudes obtenidas de http.Server.

Cadena de URL de la solicitud. Esto contiene solo la URL que está presente en la solicitud HTTP real. Tome la siguiente solicitud:

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

Para analizar la URL en sus partes:

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

Cuando request.url es '/status?name=ryan' y process.env.HOST no está definido:

$ 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: ''
}

Asegúrese de establecer process.env.HOST en el nombre de host del servidor, o considere reemplazar esta parte por completo. Si usa req.headers.host, asegúrese de utilizar la validación adecuada, ya que los clientes pueden especificar un encabezado Host personalizado.

Clase: http.OutgoingMessage

Añadido en: v0.1.17

• Extiende: <Stream>

Esta clase sirve como clase padre de http.ClientRequest y http.ServerResponse. Es un mensaje saliente abstracto desde la perspectiva de los participantes de una transacción HTTP.

Evento: 'drain'

Añadido en: v0.3.6

Se emite cuando el búfer del mensaje vuelve a estar libre.

Evento: 'finish'

Añadido en: v0.1.17

Se emite cuando la transmisión finaliza correctamente.

Evento: 'prefinish'

Añadido en: v0.11.6

Se emite después de llamar a outgoingMessage.end(). Cuando se emite el evento, todos los datos se han procesado, pero no necesariamente se han vaciado por completo.

outgoingMessage.addTrailers(headers)

Añadido en: v0.3.0

• headers <Object>

Agrega tráilers HTTP (cabeceras pero al final del mensaje) al mensaje.

Los tráilers solo se emitirán si el mensaje está codificado en fragmentos. Si no, los tráilers se descartarán silenciosamente.

HTTP requiere que la cabecera Trailer se envíe para emitir tráilers, con una lista de nombres de campos de cabecera en su valor, por ejemplo:

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

Intentar establecer un nombre o valor de campo de cabecera que contenga caracteres no válidos resultará en un TypeError.

outgoingMessage.appendHeader(name, value)

Agregado en: v18.3.0, v16.17.0

• name <string> Nombre del encabezado
• value <string> | <string[]> Valor del encabezado
• Devuelve: <this>

Agrega un solo valor de encabezado al objeto de encabezado.

Si el valor es un arreglo, esto es equivalente a llamar a este método varias veces.

Si no había valores previos para el encabezado, esto es equivalente a llamar a outgoingMessage.setHeader(name, value).

Dependiendo del valor de options.uniqueHeaders cuando se creó la solicitud del cliente o el servidor, esto terminará con el encabezado enviado varias veces o una sola vez con los valores unidos usando ; .

outgoingMessage.connection

Agregado en: v0.3.0

Obsoleto desde: v15.12.0, v14.17.1

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use outgoingMessage.socket en su lugar.

Alias de outgoingMessage.socket.

outgoingMessage.cork()

Agregado en: v13.2.0, v12.16.0

Ver writable.cork().

outgoingMessage.destroy([error])

Agregado en: v0.3.0

• error <Error> Opcional, un error para emitir con el evento error
• Devuelve: <this>

Destruye el mensaje. Una vez que un socket está asociado con el mensaje y está conectado, ese socket también se destruirá.

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

[Historial]

Versión	Cambios
v15.0.0	El parámetro chunk ahora puede ser un Uint8Array.
v0.11.6	Agrega el argumento callback.
v0.1.90	Agregado en: v0.1.90

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Opcional, Predeterminado: utf8
• callback <Function> Opcional
• Devuelve: <this>

Finaliza el mensaje saliente. Si alguna parte del cuerpo no se ha enviado, la enviará al sistema subyacente. Si el mensaje está fragmentado, enviará el fragmento de terminación 0\r\n\r\n y enviará los trailers (si los hay).

Si se especifica chunk, es equivalente a llamar a outgoingMessage.write(chunk, encoding), seguido de outgoingMessage.end(callback).

Si se proporciona callback, se llamará cuando el mensaje haya finalizado (equivalente a un listener del evento 'finish').

outgoingMessage.flushHeaders()

Agregado en: v1.6.0

Descarga los encabezados del mensaje.

Por razones de eficiencia, Node.js normalmente almacena en búfer los encabezados del mensaje hasta que se llama a outgoingMessage.end() o se escribe el primer fragmento de datos del mensaje. Luego intenta empaquetar los encabezados y los datos en un solo paquete TCP.

Por lo general, es deseable (ahorra un viaje de ida y vuelta TCP), pero no cuando los primeros datos no se envían hasta posiblemente mucho más tarde. outgoingMessage.flushHeaders() omite la optimización e inicia el mensaje.

outgoingMessage.getHeader(name)

Agregado en: v0.4.0

• name <string> Nombre del encabezado
• Devuelve: <string> | <undefined>

Obtiene el valor del encabezado HTTP con el nombre dado. Si ese encabezado no está establecido, el valor devuelto será undefined.

outgoingMessage.getHeaderNames()

Agregado en: v7.7.0

• Devuelve: <string[]>

Devuelve un array que contiene los nombres únicos de los encabezados salientes actuales. Todos los nombres están en minúsculas.

outgoingMessage.getHeaders()

Agregado en: v7.7.0

• Devuelve: <Object>

Devuelve una copia superficial de los encabezados salientes actuales. Dado que se utiliza una copia superficial, los valores del array pueden mutarse sin llamadas adicionales a varios métodos del módulo HTTP relacionados con el encabezado. Las claves del objeto devuelto son los nombres de los encabezados y los valores son los valores de los encabezados respectivos. Todos los nombres de los encabezados están en minúsculas.

El objeto devuelto por el método outgoingMessage.getHeaders() no hereda prototípicamente de Object de JavaScript. Esto significa que los métodos típicos de Object como obj.toString(), obj.hasOwnProperty() y otros no están definidos y no funcionarán.

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)

Agregado en: v7.7.0

• name <string>
• Devuelve: <boolean>

Devuelve true si el encabezado identificado por name está establecido actualmente en los encabezados salientes. El nombre del encabezado no distingue entre mayúsculas y minúsculas.

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

outgoingMessage.headersSent

Agregado en: v0.9.3

• <boolean>

De solo lectura. true si se enviaron los encabezados, de lo contrario false.

outgoingMessage.pipe()

Agregado en: v9.0.0

Anula el método stream.pipe() heredado de la clase Stream heredada, que es la clase principal de http.OutgoingMessage.

Llamar a este método lanzará un Error porque outgoingMessage es una secuencia de solo escritura.

outgoingMessage.removeHeader(name)

Agregado en: v0.4.0

• name <string> Nombre del encabezado

Elimina un encabezado que está en cola para su envío implícito.

outgoingMessage.removeHeader('Content-Encoding')

outgoingMessage.setHeader(name, value)

Agregado en: v0.4.0

• name <string> Nombre del encabezado
• value <any> Valor del encabezado
• Devuelve: <this>

Establece un único valor de encabezado. Si el encabezado ya existe en los encabezados que se van a enviar, su valor se reemplazará. Use un arreglo de cadenas para enviar múltiples encabezados con el mismo nombre.

outgoingMessage.setHeaders(headers)

Agregado en: v19.6.0, v18.15.0

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

Establece múltiples valores de encabezado para encabezados implícitos. headers debe ser una instancia de Headers o Map, si un encabezado ya existe en los encabezados que se van a enviar, su valor se reemplazará.

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

o

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

Cuando los encabezados se han establecido con outgoingMessage.setHeaders(), se fusionarán con cualquier encabezado pasado a response.writeHead(), con los encabezados pasados a response.writeHead() que tienen prioridad.

// Devuelve 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])

Agregado en: v0.9.12

• msesc <number>
• callback <Function> Función opcional para ser llamada cuando ocurre un tiempo de espera. Es lo mismo que enlazar al evento timeout.
• Devuelve: <this>

Una vez que un socket está asociado con el mensaje y está conectado, se llamará a socket.setTimeout() con msecs como primer parámetro.

outgoingMessage.socket

Agregado en: v0.3.0

• <stream.Duplex>

Referencia al socket subyacente. Normalmente, los usuarios no querrán acceder a esta propiedad.

Después de llamar a outgoingMessage.end(), esta propiedad se establecerá en nulo.

outgoingMessage.uncork()

Agregado en: v13.2.0, v12.16.0

Ver writable.uncork()

outgoingMessage.writableCorked

Agregado en: v13.2.0, v12.16.0

• <number>

El número de veces que se ha llamado a outgoingMessage.cork().

outgoingMessage.writableEnded

Agregado en: v12.9.0

• <boolean>

Es true si se ha llamado a outgoingMessage.end(). Esta propiedad no indica si los datos se han vaciado. Para ese propósito, use message.writableFinished en su lugar.

outgoingMessage.writableFinished

Agregado en: v12.7.0

• <boolean>

Es true si todos los datos se han vaciado al sistema subyacente.

outgoingMessage.writableHighWaterMark

Agregado en: v12.9.0

• <number>

El highWaterMark del socket subyacente si se asigna. De lo contrario, el nivel de búfer predeterminado cuando writable.write() comienza a devolver false (16384).

outgoingMessage.writableLength

Agregado en: v12.9.0

• <number>

El número de bytes en búfer.

outgoingMessage.writableObjectMode

Agregado en: v12.9.0

• <boolean>

Siempre false.

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

[Historial]

Versión	Cambios
v15.0.0	El parámetro chunk ahora puede ser un Uint8Array.
v0.11.6	Se agregó el argumento callback.
v0.1.29	Agregado en: v0.1.29

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> Predeterminado: utf8
• callback <Function>
• Devuelve: <boolean>

Envía un fragmento del cuerpo. Este método se puede llamar varias veces.

El argumento encoding solo es relevante cuando chunk es una cadena. El valor predeterminado es 'utf8'.

El argumento callback es opcional y se llamará cuando se vacíe este fragmento de datos.

Devuelve true si todos los datos se vaciaron correctamente en el búfer del kernel. Devuelve false si todos o parte de los datos se pusieron en cola en la memoria del usuario. El evento 'drain' se emitirá cuando el búfer esté libre nuevamente.

http.METHODS

Añadido en: v0.11.8

• <string[]>

Una lista de los métodos HTTP que son soportados por el analizador.

http.STATUS_CODES

Añadido en: v0.1.22

• <Object>

Una colección de todos los códigos de estado de respuesta HTTP estándar y la descripción corta de cada uno. Por ejemplo, http.STATUS_CODES[404] === 'Not Found'.

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

[Historial]

Versión	Cambios
v20.1.0, v18.17.0	La opción highWaterMark ahora es soportada.
v18.0.0	Las opciones requestTimeout, headersTimeout, keepAliveTimeout y connectionsCheckingInterval ahora son soportadas.
v18.0.0	La opción noDelay ahora tiene como valor predeterminado true.
v17.7.0, v16.15.0	Las opciones noDelay, keepAlive y keepAliveInitialDelay ahora son soportadas.
v13.3.0	La opción maxHeaderSize ahora es soportada.
v13.8.0, v12.15.0, v10.19.0	La opción insecureHTTPParser ahora es soportada.
v9.6.0, v8.12.0	El argumento options ahora es soportado.
v0.1.13	Añadido en: v0.1.13

• options <Object>

  • connectionsCheckingInterval: Establece el valor del intervalo en milisegundos para comprobar el tiempo de espera de la solicitud y los encabezados en solicitudes incompletas. Predeterminado: 30000.
  • headersTimeout: Establece el valor de tiempo de espera en milisegundos para recibir los encabezados HTTP completos del cliente. Consulta server.headersTimeout para más información. Predeterminado: 60000.
  • highWaterMark <number> Opcionalmente, anula todos los readableHighWaterMark y writableHighWaterMark de los sockets. Esto afecta a la propiedad highWaterMark tanto de IncomingMessage como de ServerResponse. Predeterminado: Consulta stream.getDefaultHighWaterMark().
  • insecureHTTPParser <boolean> Si se establece en true, utilizará un analizador HTTP con las banderas de indulgencia habilitadas. Se debe evitar el uso del analizador inseguro. Consulta --insecure-http-parser para más información. Predeterminado: false.
  • IncomingMessage <http.IncomingMessage> Especifica la clase IncomingMessage que se utilizará. Útil para extender el IncomingMessage original. Predeterminado: IncomingMessage.
  • joinDuplicateHeaders <boolean> Si se establece en true, esta opción permite unir los valores de la línea de campo de varios encabezados en una solicitud con una coma (, ) en lugar de descartar los duplicados. Para obtener más información, consulta message.headers. Predeterminado: false.
  • keepAlive <boolean> Si se establece en true, habilita la funcionalidad keep-alive en el socket inmediatamente después de recibir una nueva conexión entrante, de forma similar a lo que se hace en [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)]. Predeterminado: false.
  • keepAliveInitialDelay <number> Si se establece en un número positivo, establece el retraso inicial antes de que se envíe la primera sonda keepalive en un socket inactivo. Predeterminado: 0.
  • keepAliveTimeout: El número de milisegundos de inactividad que un servidor necesita esperar para obtener datos entrantes adicionales, después de que haya terminado de escribir la última respuesta, antes de que se destruya un socket. Consulta server.keepAliveTimeout para más información. Predeterminado: 5000.
  • maxHeaderSize <number> Opcionalmente, anula el valor de --max-http-header-size para las solicitudes recibidas por este servidor, es decir, la longitud máxima de los encabezados de solicitud en bytes. Predeterminado: 16384 (16 KiB).
  • noDelay <boolean> Si se establece en true, deshabilita el uso del algoritmo de Nagle inmediatamente después de recibir una nueva conexión entrante. Predeterminado: true.
  • requestTimeout: Establece el valor de tiempo de espera en milisegundos para recibir la solicitud completa del cliente. Consulta server.requestTimeout para más información. Predeterminado: 300000.
  • requireHostHeader <boolean> Si se establece en true, obliga al servidor a responder con un código de estado 400 (Bad Request) a cualquier mensaje de solicitud HTTP/1.1 que carezca de un encabezado Host (como lo exige la especificación). Predeterminado: true.
  • ServerResponse <http.ServerResponse> Especifica la clase ServerResponse que se utilizará. Útil para extender el ServerResponse original. Predeterminado: ServerResponse.
  • uniqueHeaders <Array> Una lista de encabezados de respuesta que deben enviarse solo una vez. Si el valor del encabezado es un array, los elementos se unirán utilizando ; .
  • rejectNonStandardBodyWrites <boolean> Si se establece en true, se produce un error al escribir en una respuesta HTTP que no tiene cuerpo. Predeterminado: false.

• requestListener <Function>

• Devuelve: <http.Server>

Devuelve una nueva instancia de http.Server.

El requestListener es una función que se añade automáticamente al evento 'request'.

ESM

import http from 'node:http'

// Crear un servidor local para recibir datos de
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: '¡Hola Mundo!',
    })
  )
})

server.listen(8000)

CJS

const http = require('node:http')

// Crear un servidor local para recibir datos de
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: '¡Hola Mundo!',
    })
  )
})

server.listen(8000)

ESM

import http from 'node:http'

// Crear un servidor local para recibir datos de
const server = http.createServer()

// Escuchar el evento request
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: '¡Hola Mundo!',
    })
  )
})

server.listen(8000)

CJS

const http = require('node:http')

// Crear un servidor local para recibir datos de
const server = http.createServer()

// Escuchar el evento request
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: '¡Hola Mundo!',
    })
  )
})

server.listen(8000)

http.get(options[, callback])

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

[Historial]

Versión	Cambios
v10.9.0	El parámetro url ahora se puede pasar junto con un objeto options separado.
v7.5.0	El parámetro options puede ser un objeto WHATWG URL.
v0.3.6	Añadido en: v0.3.6

• url <string> | <URL>
• options <Object> Acepta las mismas options que http.request(), con el método establecido en GET por defecto.
• callback <Function>
• Devuelve: <http.ClientRequest>

Dado que la mayoría de las peticiones son peticiones GET sin cuerpo, Node.js proporciona este método de conveniencia. La única diferencia entre este método y http.request() es que establece el método en GET por defecto y llama a req.end() automáticamente. La función de retorno debe encargarse de consumir los datos de la respuesta por las razones indicadas en la sección http.ClientRequest.

La callback se invoca con un único argumento que es una instancia de http.IncomingMessage.

Ejemplo de obtención de JSON:

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

    let error
    // Cualquier código de estado 2xx señala una respuesta exitosa, pero
    // aquí solo estamos comprobando el 200.
    if (statusCode !== 200) {
      error = new Error('Solicitud fallida.\n' + `Código de estado: ${statusCode}`)
    } else if (!/^application\/json/.test(contentType)) {
      error = new Error(
        'Tipo de contenido no válido.\n' + `Se esperaba application/json pero se recibió ${contentType}`
      )
    }
    if (error) {
      console.error(error.message)
      // Consumir los datos de la respuesta para liberar 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(`Se produjo un error: ${e.message}`)
  })

// Crear un servidor local para recibir datos de
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(
    JSON.stringify({
      data: '¡Hola Mundo!',
    })
  )
})

server.listen(8000)

http.globalAgent

[Historial]

Versión	Cambios
v19.0.0	El agente ahora usa HTTP Keep-Alive y un tiempo de espera de 5 segundos por defecto.
v0.5.9	Añadido en: v0.5.9

• <http.Agent>

Instancia global de Agent que se usa como predeterminada para todas las solicitudes de cliente HTTP. Difiere de una configuración predeterminada de Agent al tener keepAlive habilitado y un timeout de 5 segundos.

http.maxHeaderSize

Añadido en: v11.6.0, v10.15.0

• <number>

Propiedad de solo lectura que especifica el tamaño máximo permitido de los encabezados HTTP en bytes. El valor predeterminado es 16 KiB. Configurable utilizando la opción CLI --max-http-header-size.

Esto se puede anular para servidores y solicitudes de cliente pasando la opción maxHeaderSize.

http.request(options[, callback])

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

[Historial]

Versión	Cambios
v16.7.0, v14.18.0	Al usar un objeto URL, el nombre de usuario y la contraseña analizados ahora se decodificarán correctamente como URI.
v15.3.0, v14.17.0	Es posible abortar una solicitud con un AbortSignal.
v13.3.0	Ahora se admite la opción maxHeaderSize.
v13.8.0, v12.15.0, v10.19.0	Ahora se admite la opción insecureHTTPParser.
v10.9.0	El parámetro url ahora se puede pasar junto con un objeto options separado.
v7.5.0	El parámetro options puede ser un objeto WHATWG URL.
v0.3.6	Añadido en: v0.3.6

• url <string> | <URL>

• options <Object>

  • agent <http.Agent> | <boolean> Controla el comportamiento de Agent. Valores posibles:

  • undefined (predeterminado): usa http.globalAgent para este host y puerto.

  • Objeto Agent: usa explícitamente el Agent pasado.

  • false: hace que se use un nuevo Agent con valores predeterminados.

  • auth <string> Autenticación básica ('usuario:contraseña') para calcular un encabezado de Autorización.

  • createConnection <Function> Una función que produce un socket/stream para usar en la solicitud cuando no se usa la opción agent. Esto se puede usar para evitar crear una clase Agent personalizada solo para anular la función createConnection predeterminada. Consulta agent.createConnection() para obtener más detalles. Cualquier stream Duplex es un valor de retorno válido.

  • defaultPort <number> Puerto predeterminado para el protocolo. Predeterminado: agent.defaultPort si se usa un Agent, si no, undefined.

  • family <number> Familia de direcciones IP para usar al resolver host o hostname. Los valores válidos son 4 o 6. Cuando no se especifica, se usarán tanto IPv4 como IPv6.

  • headers <Object> Un objeto que contiene encabezados de solicitud.

  • hints <number> Pistas opcionales de dns.lookup().

  • host <string> Un nombre de dominio o dirección IP del servidor al que se emitirá la solicitud. Predeterminado: 'localhost'.

  • hostname <string> Alias para host. Para admitir url.parse(), se usará hostname si se especifican tanto host como hostname.

  • insecureHTTPParser <boolean> Si se establece en true, usará un analizador HTTP con flags de indulgencia habilitados. Se debe evitar usar el analizador inseguro. Consulta --insecure-http-parser para obtener más información. Predeterminado: false

  • joinDuplicateHeaders <boolean> Une los valores de línea de campo de múltiples encabezados en una solicitud con , en lugar de descartar los duplicados. Consulta message.headers para obtener más información. Predeterminado: false.

  • localAddress <string> Interfaz local para enlazar para conexiones de red.

  • localPort <number> Puerto local desde el que conectar.

  • lookup <Function> Función de búsqueda personalizada. Predeterminado: dns.lookup().

  • maxHeaderSize <number> Anula opcionalmente el valor de --max-http-header-size (la longitud máxima de los encabezados de respuesta en bytes) para las respuestas recibidas del servidor. Predeterminado: 16384 (16 KiB).

  • method <string> Una string que especifica el método de solicitud HTTP. Predeterminado: 'GET'.

  • path <string> Ruta de la solicitud. Debe incluir la cadena de consulta si la hay. P. Ej. '/index.html?page=12'. Se lanza una excepción cuando la ruta de solicitud contiene caracteres ilegales. Actualmente, solo se rechazan los espacios, pero eso puede cambiar en el futuro. Predeterminado: '/'.

  • port <number> Puerto del servidor remoto. Predeterminado: defaultPort si está establecido, si no, 80.

  • protocol <string> Protocolo a utilizar. Predeterminado: 'http:'.

  • setDefaultHeaders <boolean>: Especifica si se deben o no agregar automáticamente los encabezados predeterminados como Connection, Content-Length, Transfer-Encoding y Host. Si se establece en false, entonces todos los encabezados necesarios deben agregarse manualmente. El valor predeterminado es true.

  • setHost <boolean>: Especifica si se debe o no agregar automáticamente el encabezado Host. Si se proporciona, esto anula setDefaultHeaders. El valor predeterminado es true.

  • signal <AbortSignal>: Un AbortSignal que se puede usar para abortar una solicitud en curso.

  • socketPath <string> Socket de dominio Unix. No se puede usar si se especifica uno de host o port, ya que esos especifican un socket TCP.

  • timeout <number>: Un número que especifica el tiempo de espera del socket en milisegundos. Esto establecerá el tiempo de espera antes de que se conecte el socket.

  • uniqueHeaders <Array> Una lista de encabezados de solicitud que deben enviarse solo una vez. Si el valor del encabezado es un array, los elementos se unirán usando ; .

• callback <Function>

• Devuelve: <http.ClientRequest>

También se admiten options en socket.connect().

Node.js mantiene varias conexiones por servidor para realizar solicitudes HTTP. Esta función permite emitir solicitudes de forma transparente.

url puede ser una string o un objeto URL. Si url es una string, se analiza automáticamente con new URL(). Si es un objeto URL, se convertirá automáticamente en un objeto options ordinario.

Si se especifican tanto url como options, los objetos se fusionan, y las propiedades de options tienen prioridad.

El parámetro callback opcional se agregará como un listener único para el evento 'response'.

http.request() devuelve una instancia de la clase http.ClientRequest. La instancia de ClientRequest es un stream de escritura. Si uno necesita subir un archivo con una solicitud POST, entonces escribe en el objeto ClientRequest.

ESM

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

const postData = JSON.stringify({
  msg: '¡Hola Mundo!',
})

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 hay más datos en la respuesta.')
  })
})

req.on('error', e => {
  console.error(`problema con la solicitud: ${e.message}`)
})

// Escribir datos en el cuerpo de la solicitud
req.write(postData)
req.end()

CJS

const http = require('node:http')

const postData = JSON.stringify({
  msg: '¡Hola Mundo!',
})

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 hay más datos en la respuesta.')
  })
})

req.on('error', e => {
  console.error(`problema con la solicitud: ${e.message}`)
})

// Escribir datos en el cuerpo de la solicitud
req.write(postData)
req.end()

En el ejemplo, se llamó a req.end(). Con http.request(), siempre se debe llamar a req.end() para indicar el final de la solicitud, incluso si no se están escribiendo datos en el cuerpo de la solicitud.

Si se encuentra algún error durante la solicitud (ya sea con la resolución DNS, errores de nivel TCP o errores de análisis HTTP reales), se emite un evento 'error' en el objeto de solicitud devuelto. Al igual que con todos los eventos 'error', si no se registran listeners, se lanzará el error.

Hay algunos encabezados especiales que se deben tener en cuenta.

• Enviar un 'Connection: keep-alive' notificará a Node.js que la conexión al servidor debe mantenerse hasta la próxima solicitud.
• Enviar un encabezado 'Content-Length' deshabilitará la codificación fragmentada predeterminada.
• Enviar un encabezado 'Expect' enviará inmediatamente los encabezados de la solicitud. Por lo general, al enviar 'Expect: 100-continue', se debe establecer tanto un tiempo de espera como un listener para el evento 'continue'. Consulta la sección 8.2.3 de RFC 2616 para obtener más información.
• Enviar un encabezado de Autorización anulará el uso de la opción auth para calcular la autenticación básica.

Ejemplo usando una URL como options:

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

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

En una solicitud exitosa, los siguientes eventos se emitirán en el siguiente orden:

• 'socket'
• 'response'
  • 'data' cualquier número de veces, en el objeto res ('data' no se emitirá en absoluto si el cuerpo de la respuesta está vacío, por ejemplo, en la mayoría de las redirecciones)
  • 'end' en el objeto res
• 'close'

En el caso de un error de conexión, se emitirán los siguientes eventos:

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

En el caso de un cierre de conexión prematuro antes de recibir la respuesta, se emitirán los siguientes eventos en el siguiente orden:

• 'socket'
• 'error' con un error con el mensaje 'Error: socket hang up' y el código 'ECONNRESET'
• 'close'

En el caso de un cierre de conexión prematuro después de recibir la respuesta, se emitirán los siguientes eventos en el siguiente orden:

• 'socket'
• 'response'
  • 'data' cualquier número de veces, en el objeto res
• (conexión cerrada aquí)
• 'aborted' en el objeto res
• 'close'
• 'error' en el objeto res con un error con el mensaje 'Error: aborted' y el código 'ECONNRESET'
• 'close' en el objeto res

Si se llama a req.destroy() antes de que se asigne un socket, se emitirán los siguientes eventos en el siguiente orden:

• (Se llama a req.destroy() aquí)
• 'error' con un error con el mensaje 'Error: socket hang up' y el código 'ECONNRESET', o el error con el que se llamó a req.destroy()
• 'close'

Si se llama a req.destroy() antes de que la conexión tenga éxito, se emitirán los siguientes eventos en el siguiente orden:

• 'socket'
• (Se llama a req.destroy() aquí)
• 'error' con un error con el mensaje 'Error: socket hang up' y el código 'ECONNRESET', o el error con el que se llamó a req.destroy()
• 'close'

Si se llama a req.destroy() después de que se recibe la respuesta, se emitirán los siguientes eventos en el siguiente orden:

• 'socket'
• 'response'
  • 'data' cualquier número de veces, en el objeto res
• (Se llama a req.destroy() aquí)
• 'aborted' en el objeto res
• 'close'
• 'error' en el objeto res con un error con el mensaje 'Error: aborted' y el código 'ECONNRESET', o el error con el que se llamó a req.destroy()
• 'close' en el objeto res

Si se llama a req.abort() antes de que se asigne un socket, se emitirán los siguientes eventos en el siguiente orden:

• (Se llama a req.abort() aquí)
• 'abort'
• 'close'

Si se llama a req.abort() antes de que la conexión tenga éxito, se emitirán los siguientes eventos en el siguiente orden:

• 'socket'
• (Se llama a req.abort() aquí)
• 'abort'
• 'error' con un error con el mensaje 'Error: socket hang up' y el código 'ECONNRESET'
• 'close'

Si se llama a req.abort() después de que se recibe la respuesta, se emitirán los siguientes eventos en el siguiente orden:

• 'socket'
• 'response'
  • 'data' cualquier número de veces, en el objeto res
• (Se llama a req.abort() aquí)
• 'abort'
• 'aborted' en el objeto res
• 'error' en el objeto res con un error con el mensaje 'Error: aborted' y el código 'ECONNRESET'.
• 'close'
• 'close' en el objeto res

Establecer la opción timeout o usar la función setTimeout() no abortará la solicitud ni hará nada más que agregar un evento 'timeout'.

Pasar un AbortSignal y luego llamar a abort() en el AbortController correspondiente se comportará de la misma manera que llamar a .destroy() en la solicitud. Específicamente, se emitirá el evento 'error' con un error con el mensaje 'AbortError: The operation was aborted', el código 'ABORT_ERR' y la cause, si se proporcionó una.

http.validateHeaderName(name[, label])

[Historial]

Versión	Cambios
v19.5.0, v18.14.0	Se agrega el parámetro label.
v14.3.0	Agregado en: v14.3.0

• name <string>
• label <string> Etiqueta para el mensaje de error. Predeterminado: 'Nombre de encabezado'.

Realiza las validaciones de bajo nivel en el name proporcionado que se realizan cuando se llama a res.setHeader(name, value).

Pasar un valor ilegal como name resultará en un TypeError que se lanzará, identificado por code: 'ERR_INVALID_HTTP_TOKEN'.

No es necesario utilizar este método antes de pasar los encabezados a una solicitud o respuesta HTTP. El módulo HTTP validará automáticamente dichos encabezados.

Ejemplo:

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) // --> 'El nombre del encabezado debe ser un token HTTP válido [""]'
}

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) // --> 'El nombre del encabezado debe ser un token HTTP válido [""]'
}

http.validateHeaderValue(name, value)

Agregado en: v14.3.0

• name <string>
• value <any>

Realiza las validaciones de bajo nivel en el value proporcionado que se realizan cuando se llama a res.setHeader(name, value).

Pasar un valor ilegal como value resultará en que se arroje un TypeError.

• El error de valor indefinido se identifica con code: 'ERR_HTTP_INVALID_HEADER_VALUE'.
• El error de carácter de valor no válido se identifica con code: 'ERR_INVALID_CHAR'.

No es necesario usar este método antes de pasar encabezados a una solicitud o respuesta HTTP. El módulo HTTP validará automáticamente dichos encabezados.

Ejemplos:

ESM

import { validateHeaderValue } from 'node:http'

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

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

CJS

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

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

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

http.setMaxIdleHTTPParsers(max)

Agregado en: v18.8.0, v16.18.0

• max <number> Predeterminado: 1000.

Establece el número máximo de analizadores HTTP inactivos.

WebSocket

Agregado en: v22.5.0

Una implementación compatible con el navegador de WebSocket.