iDoc.dev

Português

English
简体中文
Español
Français
Deutsch
Italiano
日本語
한국어
Русский
العربية

Português

English
简体中文
Español
Français
Deutsch
Italiano
日本語
한국어
Русский
العربية

Tema

Net ​

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código Fonte: lib/net.js

O módulo node:net fornece uma API de rede assíncrona para criar servidores TCP ou IPC baseados em fluxo (net.createServer()) e clientes (net.createConnection()).

Ele pode ser acessado usando:

js
import net from 'node:net'
js
const net = require('node:net')

Suporte a IPC ​

[Histórico]

VersãoMudanças
v20.8.0Suporte para vinculação a caminho de socket de domínio Unix abstrato como \0abstract. Podemos vincular '\0' para Node.js \< v20.4.0.

O módulo node:net suporta IPC com pipes nomeados no Windows e sockets de domínio Unix em outros sistemas operacionais.

Identificando caminhos para conexões IPC ​

net.connect(), net.createConnection(), server.listen() e socket.connect() recebem um parâmetro path para identificar os endpoints IPC.

No Unix, o domínio local também é conhecido como domínio Unix. O caminho é um nome de caminho do sistema de arquivos. Ele lançará um erro quando o comprimento do nome do caminho for maior que o comprimento de sizeof(sockaddr_un.sun_path). Os valores típicos são 107 bytes no Linux e 103 bytes no macOS. Se uma abstração de API Node.js criar o socket de domínio Unix, ele também desvinculará o socket de domínio Unix. Por exemplo, net.createServer() pode criar um socket de domínio Unix e server.close() o desvinculará. Mas se um usuário criar o socket de domínio Unix fora dessas abstrações, o usuário precisará removê-lo. O mesmo se aplica quando uma API Node.js cria um socket de domínio Unix, mas o programa falha. Em resumo, um socket de domínio Unix ficará visível no sistema de arquivos e persistirá até ser desvinculado. No Linux, você pode usar um socket abstrato Unix adicionando \0 ao início do caminho, como \0abstract. O caminho para o socket abstrato Unix não é visível no sistema de arquivos e desaparecerá automaticamente quando todas as referências abertas ao socket forem fechadas.

No Windows, o domínio local é implementado usando um pipe nomeado. O caminho deve se referir a uma entrada em \\?\pipe\ ou \\.\pipe\. Quaisquer caracteres são permitidos, mas o último pode fazer algum processamento de nomes de pipe, como resolver sequências ... Apesar de como pode parecer, o namespace do pipe é plano. Os pipes não persistirão. Eles são removidos quando a última referência a eles é fechada. Ao contrário dos sockets de domínio Unix, o Windows fechará e removerá o pipe quando o processo proprietário for encerrado.

O escape de string JavaScript requer que os caminhos sejam especificados com escape de barra invertida extra, como:

js
net.createServer().listen(path.join('\\\\?\\pipe', process.cwd(), 'myctl'))

Classe: net.BlockList ​

Adicionado em: v15.0.0, v14.18.0

O objeto BlockList pode ser usado com algumas APIs de rede para especificar regras para desabilitar o acesso de entrada ou saída a endereços IP, intervalos de IP ou sub-redes IP específicas.

blockList.addAddress(address[, type]) ​

Adicionado em: v15.0.0, v14.18.0

Adiciona uma regra para bloquear o endereço IP fornecido.

blockList.addRange(start, end[, type]) ​

Adicionado em: v15.0.0, v14.18.0

Adiciona uma regra para bloquear um intervalo de endereços IP de start (inclusivo) a end (inclusivo).

blockList.addSubnet(net, prefix[, type]) ​

Adicionado em: v15.0.0, v14.18.0

  • net <string> | <net.SocketAddress> O endereço IPv4 ou IPv6 da rede.
  • prefix <number> O número de bits de prefixo CIDR. Para IPv4, este deve ser um valor entre 0 e 32. Para IPv6, este deve ser entre 0 e 128.
  • type <string> Ou 'ipv4' ou 'ipv6'. Padrão: 'ipv4'.

Adiciona uma regra para bloquear um intervalo de endereços IP especificado como uma máscara de sub-rede.

blockList.check(address[, type]) ​

Adicionado em: v15.0.0, v14.18.0

Retorna true se o endereço IP fornecido corresponder a alguma das regras adicionadas ao BlockList.

js
const blockList = new net.BlockList()
blockList.addAddress('123.123.123.123')
blockList.addRange('10.0.0.1', '10.0.0.10')
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6')

console.log(blockList.check('123.123.123.123')) // Imprime: true
console.log(blockList.check('10.0.0.3')) // Imprime: true
console.log(blockList.check('222.111.111.222')) // Imprime: false

// A notação IPv6 para endereços IPv4 funciona:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')) // Imprime: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')) // Imprime: true

blockList.rules ​

Adicionado em: v15.0.0, v14.18.0

A lista de regras adicionadas à lista de bloqueio.

BlockList.isBlockList(value) ​

Adicionado em: v23.4.0

  • value <any> Qualquer valor JS
  • Retorna true se o value for um net.BlockList.

Classe: net.SocketAddress ​

Adicionado em: v15.14.0, v14.18.0

new net.SocketAddress([options]) ​

Adicionado em: v15.14.0, v14.18.0

  • options <Object>
    • address <string> O endereço de rede como uma string IPv4 ou IPv6. Padrão: '127.0.0.1' se family for 'ipv4'; '::' se family for 'ipv6'.
    • family <string> Um de 'ipv4' ou 'ipv6'. Padrão: 'ipv4'.
    • flowlabel <number> Um flow-label IPv6 usado apenas se family for 'ipv6'.
    • port <number> Uma porta IP.

socketaddress.address ​

Adicionado em: v15.14.0, v14.18.0

socketaddress.family ​

Adicionado em: v15.14.0, v14.18.0

socketaddress.flowlabel ​

Adicionado em: v15.14.0, v14.18.0

socketaddress.port ​

Adicionado em: v15.14.0, v14.18.0

SocketAddress.parse(input) ​

Adicionado em: v23.4.0

  • input <string> Uma string de entrada contendo um endereço IP e uma porta opcional, ex. 123.1.2.3:1234 ou [1::1]:1234.
  • Retorna: <net.SocketAddress> Retorna um SocketAddress se a análise for bem-sucedida. Caso contrário, retorna undefined.

Classe: net.Server ​

Adicionado em: v0.1.90

Essa classe é usada para criar um servidor TCP ou IPC.

new net.Server([options][, connectionListener]) ​

net.Server é um EventEmitter com os seguintes eventos:

Evento: 'close' ​

Adicionado em: v0.5.0

Emitido quando o servidor fecha. Se existirem conexões, este evento não é emitido até que todas as conexões sejam encerradas.

Evento: 'connection' ​

Adicionado em: v0.1.90

Emitido quando uma nova conexão é feita. socket é uma instância de net.Socket.

Evento: 'error' ​

Adicionado em: v0.1.90

Emitido quando ocorre um erro. Ao contrário de net.Socket, o evento 'close' não será emitido diretamente após este evento, a menos que server.close() seja chamado manualmente. Veja o exemplo na discussão de server.listen().

Evento: 'listening' ​

Adicionado em: v0.1.90

Emitido quando o servidor foi vinculado após chamar server.listen().

Evento: 'drop' ​

Adicionado em: v18.6.0, v16.17.0

Quando o número de conexões atinge o limite de server.maxConnections, o servidor irá descartar novas conexões e emitir o evento 'drop' em vez disso. Se for um servidor TCP, o argumento é o seguinte, caso contrário, o argumento é undefined.

  • data <Object> O argumento passado para o ouvinte de evento.
    • localAddress <string> Endereço local.
    • localPort <number> Porta local.
    • localFamily <string> Família local.
    • remoteAddress <string> Endereço remoto.
    • remotePort <number> Porta remota.
    • remoteFamily <string> Família de IP remoto. 'IPv4' ou 'IPv6'.

server.address() ​

[Histórico]

VersãoMudanças
v18.4.0A propriedade family agora retorna uma string em vez de um número.
v18.0.0A propriedade family agora retorna um número em vez de uma string.
v0.1.90Adicionado em: v0.1.90

Retorna o endereço vinculado, o nome da família do endereço e a porta do servidor, conforme relatado pelo sistema operacional, se estiver escutando em um socket IP (útil para descobrir qual porta foi atribuída ao obter um endereço atribuído pelo SO): { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

Para um servidor escutando em um pipe ou socket de domínio Unix, o nome é retornado como uma string.

js
const server = net
  .createServer(socket => {
    socket.end('adeus\n')
  })
  .on('error', err => {
    // Lidar com erros aqui.
    throw err
  })

// Pegar uma porta não utilizada arbitrária.
server.listen(() => {
  console.log('servidor aberto em', server.address())
})

server.address() retorna null antes que o evento 'listening' tenha sido emitido ou após chamar server.close().

server.close([callback]) ​

Adicionado em: v0.1.90

Impede que o servidor aceite novas conexões e mantém as conexões existentes. Esta função é assíncrona, o servidor é finalmente fechado quando todas as conexões são encerradas e o servidor emite um evento 'close'. O callback opcional será chamado quando o evento 'close' ocorrer. Diferente desse evento, ele será chamado com um Error como seu único argumento se o servidor não estiver aberto quando foi fechado.

server[Symbol.asyncDispose]() ​

Adicionado em: v20.5.0, v18.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Chama server.close() e retorna uma promessa que é cumprida quando o servidor é fechado.

server.getConnections(callback) ​

Adicionado em: v0.9.7

Obtém assincronamente o número de conexões simultâneas no servidor. Funciona quando os sockets foram enviados para forks.

O callback deve receber dois argumentos, err e count.

server.listen() ​

Inicia um servidor ouvindo conexões. Um net.Server pode ser um servidor TCP ou IPC dependendo do que ele ouve.

Possíveis assinaturas:

Essa função é assíncrona. Quando o servidor começa a ouvir, o evento 'listening' será emitido. O último parâmetro callback será adicionado como um ouvinte para o evento 'listening'.

Todos os métodos listen() podem receber um parâmetro backlog para especificar o comprimento máximo da fila de conexões pendentes. O comprimento real será determinado pelo sistema operacional por meio de configurações sysctl como tcp_max_syn_backlog e somaxconn no Linux. O valor padrão desse parâmetro é 511 (não 512).

Todos os net.Socket são definidos como SO_REUSEADDR (consulte socket(7) para obter detalhes).

O método server.listen() pode ser chamado novamente se e somente se houve um erro durante a primeira chamada de server.listen() ou se server.close() foi chamado. Caso contrário, um erro ERR_SERVER_ALREADY_LISTEN será lançado.

Um dos erros mais comuns levantados ao ouvir é EADDRINUSE. Isso acontece quando outro servidor já está ouvindo no port/path/handle solicitado. Uma maneira de lidar com isso seria tentar novamente após um certo período de tempo:

js
server.on('error', e => {
  if (e.code === 'EADDRINUSE') {
    console.error('Endereço em uso, tentando novamente...')
    setTimeout(() => {
      server.close()
      server.listen(PORT, HOST)
    }, 1000)
  }
})

server.listen(handle[, backlog][, callback]) ​

Adicionado em: v0.5.10

Inicia um servidor que escuta conexões em um dado handle que já foi vinculado a uma porta, um socket de domínio Unix ou um pipe nomeado do Windows.

O objeto handle pode ser um servidor, um socket (qualquer coisa com um membro _handle subjacente) ou um objeto com um membro fd que é um descritor de arquivo válido.

A escuta em um descritor de arquivo não é suportada no Windows.

server.listen(options[, callback]) ​

[Histórico]

VersãoMudanças
v23.1.0A opção reusePort é suportada.
v15.6.0Foi adicionado suporte para AbortSignal.
v11.4.0A opção ipv6Only é suportada.
v0.11.14Adicionado em: v0.11.14
  • options <Object> Obrigatório. Suporta as seguintes propriedades:
    • backlog <number> Parâmetro comum das funções server.listen().
    • exclusive <boolean> Padrão: false
    • host <string>
    • ipv6Only <boolean> Para servidores TCP, definir ipv6Only como true irá desabilitar o suporte a pilha dupla, ou seja, vincular ao host :: não fará com que 0.0.0.0 seja vinculado. Padrão: false.
    • reusePort <boolean> Para servidores TCP, definir reusePort como true permite que vários sockets no mesmo host se liguem à mesma porta. As conexões de entrada são distribuídas pelo sistema operacional para os sockets de escuta. Esta opção está disponível apenas em algumas plataformas, como Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4 e AIX 7.2.5+. Padrão: false.
    • path <string> Será ignorado se port for especificado. Veja Identificação de caminhos para conexões IPC.
    • port <number>
    • readableAll <boolean> Para servidores IPC, torna o pipe legível para todos os usuários. Padrão: false.
    • signal <AbortSignal> Um AbortSignal que pode ser usado para fechar um servidor de escuta.
    • writableAll <boolean> Para servidores IPC, torna o pipe gravável para todos os usuários. Padrão: false.
  • callback <Function> functions.
  • Retorna: <net.Server>

Se port for especificado, ele se comporta da mesma forma que server.listen([port[, host[, backlog]]][, callback]). Caso contrário, se path for especificado, ele se comporta da mesma forma que server.listen(path[, backlog][, callback]). Se nenhum deles for especificado, um erro será lançado.

Se exclusive for false (padrão), então os workers do cluster usarão o mesmo handle subjacente, permitindo que as tarefas de tratamento de conexão sejam compartilhadas. Quando exclusive for true, o handle não é compartilhado e a tentativa de compartilhamento de porta resulta em um erro. Um exemplo que escuta em uma porta exclusiva é mostrado abaixo.

js
server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true,
})

Quando exclusive é true e o handle subjacente é compartilhado, é possível que vários workers consultem um handle com backlogs diferentes. Nesse caso, o primeiro backlog passado para o processo mestre será usado.

Iniciar um servidor IPC como root pode fazer com que o caminho do servidor fique inacessível para usuários sem privilégios. Usar readableAll e writableAll tornará o servidor acessível para todos os usuários.

Se a opção signal estiver habilitada, chamar .abort() no AbortController correspondente é semelhante a chamar .close() no servidor:

js
const controller = new AbortController()
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
})
// Mais tarde, quando você quiser fechar o servidor.
controller.abort()

server.listen(path[, backlog][, callback]) ​

Adicionado em: v0.1.90

Inicia um servidor IPC escutando por conexões no path fornecido.

server.listen([port[, host[, backlog]]][, callback]) ​

Adicionado em: v0.1.90

Inicia um servidor TCP escutando por conexões na port e host fornecidos.

Se port for omitido ou for 0, o sistema operacional atribuirá uma porta não utilizada arbitrária, que pode ser recuperada usando server.address().port após o evento 'listening' ter sido emitido.

Se host for omitido, o servidor aceitará conexões no endereço IPv6 não especificado (::) quando o IPv6 estiver disponível, ou no endereço IPv4 não especificado (0.0.0.0) caso contrário.

Na maioria dos sistemas operacionais, escutar no endereço IPv6 não especificado (::) pode fazer com que o net.Server também escute no endereço IPv4 não especificado (0.0.0.0).

server.listening ​

Adicionado em: v5.7.0

  • <boolean> Indica se o servidor está ou não ouvindo conexões.

server.maxConnections ​

[Histórico]

VersãoMudanças
v21.0.0Definir maxConnections para 0 descarta todas as conexões de entrada. Anteriormente, era interpretado como Infinity.
v0.2.0Adicionado em: v0.2.0

Quando o número de conexões atinge o limite server.maxConnections:

Não é recomendado usar esta opção depois que um socket é enviado para um filho com child_process.fork().

server.dropMaxConnection ​

Adicionado em: v23.1.0

Defina esta propriedade como true para começar a fechar as conexões quando o número de conexões atingir o limite [server.maxConnections][]. Essa configuração só é eficaz no modo de cluster.

server.ref() ​

Adicionado em: v0.9.1

O oposto de unref(), chamar ref() em um servidor que foi anteriormente unref não permitirá que o programa seja encerrado se for o único servidor restante (o comportamento padrão). Se o servidor estiver refed, chamar ref() novamente não terá efeito.

server.unref() ​

Adicionado em: v0.9.1

Chamar unref() em um servidor permitirá que o programa seja encerrado se este for o único servidor ativo no sistema de eventos. Se o servidor já estiver unrefed, chamar unref() novamente não terá efeito.

Classe: net.Socket ​

Adicionado em: v0.3.4

Esta classe é uma abstração de um socket TCP ou um endpoint de streaming IPC (usa pipes nomeados no Windows e sockets de domínio Unix caso contrário). É também um EventEmitter.

Um net.Socket pode ser criado pelo usuário e usado diretamente para interagir com um servidor. Por exemplo, é retornado por net.createConnection(), para que o usuário possa usá-lo para se comunicar com o servidor.

Também pode ser criado pelo Node.js e passado para o usuário quando uma conexão é recebida. Por exemplo, é passado para os listeners de um evento 'connection' emitido em um net.Server, para que o usuário possa usá-lo para interagir com o cliente.

new net.Socket([options]) ​

[Histórico]

VersãoMudanças
v15.14.0Suporte ao AbortSignal foi adicionado.
v12.10.0Opção onread adicionada.
v0.3.4Adicionado em: v0.3.4

  • options <Objeto> As opções disponíveis são:

    • allowHalfOpen <booleano> Se definido como false, o socket terminará automaticamente o lado gravável quando o lado legível terminar. Consulte net.createServer() e o evento 'end' para obter detalhes. Padrão: false.

    • fd <número> Se especificado, envolva um socket existente com o descritor de arquivo fornecido, caso contrário, um novo socket será criado.

    • onread <Objeto> Se especificado, os dados recebidos são armazenados em um único buffer e passados para o callback fornecido quando os dados chegam no socket. Isso fará com que a funcionalidade de streaming não forneça nenhum dado. O socket emitirá eventos como 'error', 'end' e 'close' como de costume. Métodos como pause() e resume() também se comportarão como esperado.

    • buffer <Buffer> | <Uint8Array> | <Função> Um pedaço de memória reutilizável para usar para armazenar dados recebidos ou uma função que retorna tal.

    • callback <Função> Essa função é chamada para cada pedaço de dados recebidos. Dois argumentos são passados para ela: o número de bytes gravados em buffer e uma referência a buffer. Retorne false desta função para implicitamente pause() o socket. Esta função será executada no contexto global.

    • readable <booleano> Permite leituras no socket quando um fd é passado, caso contrário, é ignorado. Padrão: false.

    • signal <AbortSignal> Um sinal de Abort que pode ser usado para destruir o socket.

    • writable <booleano> Permite gravações no socket quando um fd é passado, caso contrário, é ignorado. Padrão: false.

  • Retorna: <net.Socket>

Cria um novo objeto socket.

O socket recém-criado pode ser um socket TCP ou um endpoint IPC de streaming, dependendo do que ele connect() para.

Event: 'close' ​

Adicionado em: v0.1.90

  • hadError <boolean> true se o socket teve um erro de transmissão.

Emitido quando o socket está totalmente fechado. O argumento hadError é um booleano que diz se o socket foi fechado devido a um erro de transmissão.

Event: 'connect' ​

Adicionado em: v0.1.90

Emitido quando uma conexão de socket é estabelecida com sucesso. Veja net.createConnection().

Event: 'connectionAttempt' ​

Adicionado em: v21.6.0, v20.12.0

  • ip <string> O IP ao qual o socket está tentando se conectar.
  • port <number> A porta à qual o socket está tentando se conectar.
  • family <number> A família do IP. Pode ser 6 para IPv6 ou 4 para IPv4.

Emitido quando uma nova tentativa de conexão é iniciada. Isso pode ser emitido várias vezes se o algoritmo de seleção automática de família estiver habilitado em socket.connect(options).

Event: 'connectionAttemptFailed' ​

Adicionado em: v21.6.0, v20.12.0

  • ip <string> O IP ao qual o socket tentou se conectar.
  • port <number> A porta à qual o socket tentou se conectar.
  • family <number> A família do IP. Pode ser 6 para IPv6 ou 4 para IPv4.
  • error <Error> O erro associado à falha.

Emitido quando uma tentativa de conexão falhou. Isso pode ser emitido várias vezes se o algoritmo de seleção automática de família estiver habilitado em socket.connect(options).

Event: 'connectionAttemptTimeout' ​

Adicionado em: v21.6.0, v20.12.0

  • ip <string> O IP ao qual o socket tentou se conectar.
  • port <number> A porta à qual o socket tentou se conectar.
  • family <number> A família do IP. Pode ser 6 para IPv6 ou 4 para IPv4.

Emitido quando uma tentativa de conexão atinge o tempo limite. Isso é emitido (e pode ser emitido várias vezes) apenas se o algoritmo de seleção automática de família estiver habilitado em socket.connect(options).

Event: 'data' ​

Adicionado em: v0.1.90

Emitido quando dados são recebidos. O argumento data será um Buffer ou String. A codificação dos dados é definida por socket.setEncoding().

Os dados serão perdidos se não houver um listener quando um Socket emitir um evento 'data'.

Event: 'drain' ​

Adicionado em: v0.1.90

Emitido quando o buffer de escrita fica vazio. Pode ser usado para controlar uploads.

Veja também: os valores de retorno de socket.write().

Event: 'end' ​

Adicionado em: v0.1.90

Emitido quando a outra extremidade do socket sinaliza o fim da transmissão, encerrando assim o lado legível do socket.

Por padrão (allowHalfOpen é false), o socket enviará um pacote de fim de transmissão de volta e destruirá seu descritor de arquivo assim que tiver gravado sua fila de escrita pendente. No entanto, se allowHalfOpen estiver definido como true, o socket não irá automaticamente end() seu lado gravável, permitindo que o usuário grave quantidades arbitrárias de dados. O usuário deve chamar end() explicitamente para fechar a conexão (ou seja, enviar um pacote FIN de volta).

Evento: 'error' ​

Adicionado em: v0.1.90

Emitido quando ocorre um erro. O evento 'close' será chamado diretamente após este evento.

Evento: 'lookup' ​

[Histórico]

VersãoMudanças
v5.10.0O parâmetro host agora é suportado.
v0.11.3Adicionado em: v0.11.3

Emitido após resolver o nome do host, mas antes de conectar. Não aplicável a sockets Unix.

Evento: 'ready' ​

Adicionado em: v9.11.0

Emitido quando um socket está pronto para ser usado.

Disparado imediatamente após 'connect'.

Evento: 'timeout' ​

Adicionado em: v0.1.90

Emitido se o socket atingir o tempo limite por inatividade. Isso é apenas para notificar que o socket está ocioso. O usuário deve fechar manualmente a conexão.

Veja também: socket.setTimeout().

socket.address() ​

[Histórico]

VersãoMudanças
v18.4.0A propriedade family agora retorna uma string em vez de um número.
v18.0.0A propriedade family agora retorna um número em vez de uma string.
v0.1.90Adicionado em: v0.1.90

Retorna o address vinculado, o nome da family do endereço e a port do socket, conforme relatado pelo sistema operacional: { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.autoSelectFamilyAttemptedAddresses ​

Adicionado em: v19.4.0, v18.18.0

Esta propriedade só está presente se o algoritmo de seleção automática de família estiver ativado em socket.connect(options) e é um array dos endereços que foram tentados.

Cada endereço é uma string no formato $IP:$PORT. Se a conexão foi bem-sucedida, o último endereço é aquele ao qual o socket está atualmente conectado.

socket.bufferSize ​

Adicionado em: v0.3.8

Obsoleto desde: v14.6.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use writable.writableLength em vez disso.

Esta propriedade mostra o número de caracteres em buffer para gravação. O buffer pode conter strings cujo comprimento após a codificação ainda não é conhecido. Portanto, este número é apenas uma aproximação do número de bytes no buffer.

net.Socket tem a propriedade de que socket.write() sempre funciona. Isso é para ajudar os usuários a começar a usar rapidamente. O computador nem sempre consegue acompanhar a quantidade de dados gravados em um socket. A conexão de rede simplesmente pode ser muito lenta. O Node.js enfileirará internamente os dados gravados em um socket e os enviará pela rede quando for possível.

A consequência desse buffer interno é que a memória pode crescer. Os usuários que experimentam um bufferSize grande ou crescente devem tentar "restringir" os fluxos de dados em seu programa com socket.pause() e socket.resume().

socket.bytesRead ​

Adicionado em: v0.5.3

A quantidade de bytes recebidos.

socket.bytesWritten ​

Adicionado em: v0.5.3

A quantidade de bytes enviados.

socket.connect() ​

Inicia uma conexão em um socket fornecido.

Possíveis assinaturas:

Essa função é assíncrona. Quando a conexão é estabelecida, o evento 'connect' será emitido. Se houver um problema ao conectar, em vez de um evento 'connect', um evento 'error' será emitido com o erro passado para o listener 'error'. O último parâmetro connectListener, se fornecido, será adicionado como um listener para o evento 'connect' uma vez.

Essa função só deve ser usada para reconectar um socket depois que 'close' for emitido ou, caso contrário, pode levar a um comportamento indefinido.

socket.connect(options[, connectListener]) ​

[Histórico]

VersãoMudanças
v19.4.0O valor padrão para a opção autoSelectFamily pode ser alterado em tempo de execução usando setDefaultAutoSelectFamily ou por meio da opção de linha de comando --enable-network-family-autoselection.
v20.0.0, v18.18.0O valor padrão para a opção autoSelectFamily agora é verdadeiro. O sinalizador CLI --enable-network-family-autoselection foi renomeado para --network-family-autoselection. O nome antigo agora é um alias, mas é desencorajado.
v19.3.0, v18.13.0Adicionada a opção autoSelectFamily.
v17.7.0, v16.15.0As opções noDelay, keepAlive e keepAliveInitialDelay agora são suportadas.
v6.0.0A opção hints agora tem como padrão 0 em todos os casos. Anteriormente, na ausência da opção family, o padrão era `dns.ADDRCONFIG
v5.11.0A opção hints agora é suportada.
v0.1.90Adicionado em: v0.1.90

Inicia uma conexão em um socket fornecido. Normalmente, esse método não é necessário, o socket deve ser criado e aberto com net.createConnection(). Use isso somente ao implementar um Socket personalizado.

Para conexões TCP, as options disponíveis são:

  • autoSelectFamily <boolean>: Se definido como true, ele ativa um algoritmo de detecção automática de família que implementa livremente a seção 5 do RFC 8305. A opção all passada para lookup é definida como true e o socket tenta se conectar a todos os endereços IPv6 e IPv4 obtidos, em sequência, até que uma conexão seja estabelecida. O primeiro endereço AAAA retornado é tentado primeiro, depois o primeiro endereço A retornado, depois o segundo endereço AAAA retornado e assim por diante. Cada tentativa de conexão (exceto a última) recebe o tempo especificado pela opção autoSelectFamilyAttemptTimeout antes de expirar e tentar o próximo endereço. Ignorado se a opção family não for 0 ou se localAddress estiver definida. Os erros de conexão não são emitidos se pelo menos uma conexão for bem-sucedida. Se todas as tentativas de conexão falharem, um único AggregateError com todas as tentativas falhas será emitido. Padrão: net.getDefaultAutoSelectFamily().
  • autoSelectFamilyAttemptTimeout <number>: A quantidade de tempo em milissegundos para aguardar que uma tentativa de conexão seja concluída antes de tentar o próximo endereço ao usar a opção autoSelectFamily. Se definido como um inteiro positivo menor que 10, o valor 10 será usado em vez disso. Padrão: net.getDefaultAutoSelectFamilyAttemptTimeout().
  • family <number>: Versão da pilha IP. Deve ser 4, 6 ou 0. O valor 0 indica que os endereços IPv4 e IPv6 são permitidos. Padrão: 0.
  • hints <number> dns.lookup() dicas opcionais.
  • host <string> Host ao qual o socket deve se conectar. Padrão: 'localhost'.
  • keepAlive <boolean> Se definido como true, ele ativa a funcionalidade keep-alive no socket imediatamente após a conexão ser estabelecida, de forma semelhante ao que é feito em socket.setKeepAlive(). Padrão: false.
  • keepAliveInitialDelay <number> Se definido como um número positivo, ele define o atraso inicial antes que a primeira sonda keepalive seja enviada em um socket ocioso. Padrão: 0.
  • localAddress <string> Endereço local de onde o socket deve se conectar.
  • localPort <number> Porta local de onde o socket deve se conectar.
  • lookup <Function> Função de pesquisa personalizada. Padrão: dns.lookup().
  • noDelay <boolean> Se definido como true, ele desativa o uso do algoritmo de Nagle imediatamente após o socket ser estabelecido. Padrão: false.
  • port <number> Obrigatório. Porta à qual o socket deve se conectar.
  • blockList <net.BlockList> blockList pode ser usado para desabilitar o acesso de saída a endereços IP, intervalos de IP ou sub-redes IP específicos.

Para conexões IPC, as options disponíveis são:

socket.connect(path[, connectListener]) ​

Inicia uma conexão IPC no socket fornecido.

Alias para socket.connect(options[, connectListener]) chamado com { path: path } como options.

socket.connect(port[, host][, connectListener]) ​

Adicionado em: v0.1.90

Inicia uma conexão TCP no socket fornecido.

Alias para socket.connect(options[, connectListener]) chamado com {port: port, host: host} como options.

socket.connecting ​

Adicionado em: v6.1.0

Se true, socket.connect(options[, connectListener]) foi chamado e ainda não foi concluído. Ele permanecerá true até que o socket seja conectado, então será definido como false e o evento 'connect' será emitido. Observe que o callback socket.connect(options[, connectListener]) é um listener para o evento 'connect'.

socket.destroy([error]) ​

Adicionado em: v0.1.90

Garante que nenhuma outra atividade de E/S ocorra neste socket. Destrói o stream e fecha a conexão.

Consulte writable.destroy() para mais detalhes.

socket.destroyed ​

  • <boolean> Indica se a conexão está destruída ou não. Uma vez que uma conexão é destruída, nenhum dado adicional pode ser transferido usando-a.

Consulte writable.destroyed para mais detalhes.

socket.destroySoon() ​

Adicionado em: v0.3.4

Destrói o socket após todos os dados serem escritos. Se o evento 'finish' já foi emitido, o socket é destruído imediatamente. Se o socket ainda for gravável, ele implicitamente chama socket.end().

socket.end([data[, encoding]][, callback]) ​

Adicionado em: v0.1.90

Fecha o socket pela metade. Ou seja, envia um pacote FIN. É possível que o servidor ainda envie alguns dados.

Consulte writable.end() para mais detalhes.

socket.localAddress ​

Adicionado em: v0.9.6

A representação em string do endereço IP local no qual o cliente remoto está se conectando. Por exemplo, em um servidor ouvindo em '0.0.0.0', se um cliente se conectar em '192.168.1.1', o valor de socket.localAddress seria '192.168.1.1'.

socket.localPort ​

Adicionado em: v0.9.6

A representação numérica da porta local. Por exemplo, 80 ou 21.

socket.localFamily ​

Adicionado em: v18.8.0, v16.18.0

A representação em string da família de IP local. 'IPv4' ou 'IPv6'.

socket.pause() ​

Pausa a leitura de dados. Ou seja, eventos 'data' não serão emitidos. Útil para controlar um upload.

socket.pending ​

Adicionado em: v11.2.0, v10.16.0

Isso é true se o socket ainda não estiver conectado, seja porque .connect() ainda não foi chamado ou porque ainda está em processo de conexão (veja socket.connecting).

socket.ref() ​

Adicionado em: v0.9.1

O oposto de unref(), chamar ref() em um socket previamente unref não permitirá que o programa saia se for o único socket restante (o comportamento padrão). Se o socket for ref, chamar ref novamente não terá efeito.

socket.remoteAddress ​

Adicionado em: v0.5.10

A representação em string do endereço IP remoto. Por exemplo, '74.125.127.100' ou '2001:4860:a005::68'. O valor pode ser undefined se o socket for destruído (por exemplo, se o cliente se desconectou).

socket.remoteFamily ​

Adicionado em: v0.11.14

A representação em string da família de IP remota. 'IPv4' ou 'IPv6'. O valor pode ser undefined se o socket for destruído (por exemplo, se o cliente se desconectou).

socket.remotePort ​

Adicionado em: v0.5.10

A representação numérica da porta remota. Por exemplo, 80 ou 21. O valor pode ser undefined se o socket for destruído (por exemplo, se o cliente se desconectar).

socket.resetAndDestroy() ​

Adicionado em: v18.3.0, v16.17.0

Fecha a conexão TCP enviando um pacote RST e destrói o stream. Se este socket TCP estiver no status de conexão, ele enviará um pacote RST e destruirá este socket TCP assim que estiver conectado. Caso contrário, ele chamará socket.destroy com um Erro ERR_SOCKET_CLOSED. Se este não for um socket TCP (por exemplo, um pipe), chamar este método lançará imediatamente um erro ERR_INVALID_HANDLE_TYPE.

socket.resume() ​

Retoma a leitura após uma chamada para socket.pause().

socket.setEncoding([encoding]) ​

Adicionado em: v0.1.90

Define a codificação para o socket como um Readable Stream. Consulte readable.setEncoding() para obter mais informações.

socket.setKeepAlive([enable][, initialDelay]) ​

[Histórico]

VersãoAlterações
v13.12.0, v12.17.0Novos padrões para as opções de socket TCP_KEEPCNT e TCP_KEEPINTVL foram adicionados.
v0.1.92Adicionado em: v0.1.92

Ativa/desativa a funcionalidade keep-alive e, opcionalmente, define o atraso inicial antes que a primeira sonda keepalive seja enviada em um socket ocioso.

Defina initialDelay (em milissegundos) para definir o atraso entre o último pacote de dados recebido e a primeira sonda keepalive. Definir 0 para initialDelay deixará o valor inalterado do padrão (ou configuração anterior).

Habilitar a funcionalidade keep-alive definirá as seguintes opções de socket:

  • SO_KEEPALIVE=1
  • TCP_KEEPIDLE=initialDelay
  • TCP_KEEPCNT=10
  • TCP_KEEPINTVL=1

socket.setNoDelay([noDelay]) ​

Adicionado em: v0.1.90

Ativa/desativa o uso do algoritmo de Nagle.

Quando uma conexão TCP é criada, ela terá o algoritmo de Nagle ativado.

O algoritmo de Nagle atrasa os dados antes de serem enviados pela rede. Ele tenta otimizar a taxa de transferência em detrimento da latência.

Passar true para noDelay ou não passar um argumento desativará o algoritmo de Nagle para o socket. Passar false para noDelay ativará o algoritmo de Nagle.

socket.setTimeout(timeout[, callback]) ​

[Histórico]

VersãoMudanças
v18.0.0Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v0.1.90Adicionado em: v0.1.90

Define o socket para expirar após timeout milissegundos de inatividade no socket. Por padrão, net.Socket não têm um tempo limite.

Quando um tempo limite ocioso é acionado, o socket receberá um evento 'timeout', mas a conexão não será interrompida. O usuário deve chamar manualmente socket.end() ou socket.destroy() para finalizar a conexão.

js
socket.setTimeout(3000)
socket.on('timeout', () => {
  console.log('socket timeout')
  socket.end()
})

Se timeout for 0, o tempo limite ocioso existente será desativado.

O parâmetro opcional callback será adicionado como um ouvinte único para o evento 'timeout'.

socket.timeout ​

Adicionado em: v10.7.0

O tempo limite do socket em milissegundos, conforme definido por socket.setTimeout(). É undefined se um tempo limite não foi definido.

socket.unref() ​

Adicionado em: v0.9.1

Chamar unref() em um socket permitirá que o programa seja encerrado se este for o único socket ativo no sistema de eventos. Se o socket já estiver unref chamado unref() novamente não terá efeito.

socket.write(data[, encoding][, callback]) ​

Adicionado em: v0.1.90

Envia dados no socket. O segundo parâmetro especifica a codificação no caso de uma string. O padrão é a codificação UTF8.

Retorna true se todos os dados foram enviados com sucesso para o buffer do kernel. Retorna false se todos ou parte dos dados foram enfileirados na memória do usuário. 'drain' será emitido quando o buffer estiver livre novamente.

O parâmetro opcional callback será executado quando os dados forem finalmente gravados, o que pode não ser imediatamente.

Consulte o método write() do fluxo Writable para obter mais informações.

socket.readyState ​

Adicionado em: v0.5.0

Esta propriedade representa o estado da conexão como uma string.

  • Se o stream estiver conectando, socket.readyState é opening.
  • Se o stream for legível e gravável, é open.
  • Se o stream for legível e não gravável, é readOnly.
  • Se o stream não for legível e gravável, é writeOnly.

net.connect() ​

Alias para net.createConnection().

Assinaturas possíveis:

net.connect(options[, connectListener]) ​

Adicionado em: v0.7.0

Alias para net.createConnection(options[, connectListener]).

net.connect(path[, connectListener]) ​

Adicionado em: v0.1.90

Alias para net.createConnection(path[, connectListener]).

net.connect(port[, host][, connectListener]) ​

Adicionado em: v0.1.90

Alias para net.createConnection(port[, host][, connectListener]).

net.createConnection() ​

Uma função de fábrica, que cria um novo net.Socket, inicia imediatamente a conexão com socket.connect() e, em seguida, retorna o net.Socket que inicia a conexão.

Quando a conexão é estabelecida, um evento 'connect' será emitido no socket retornado. O último parâmetro connectListener, se fornecido, será adicionado como um listener para o evento 'connect' uma vez.

Possíveis assinaturas:

A função net.connect() é um alias para esta função.

net.createConnection(options[, connectListener]) ​

Adicionado em: v0.1.90

Para opções disponíveis, consulte new net.Socket([options]) e socket.connect(options[, connectListener]).

Opções adicionais:

A seguir, um exemplo de um cliente do servidor echo descrito na seção net.createServer():

js
import net from 'node:net'
const client = net.createConnection({ port: 8124 }, () => {
  // Listener 'connect'.
  console.log('conectado ao servidor!')
  client.write('mundo!\r\n')
})
client.on('data', data => {
  console.log(data.toString())
  client.end()
})
client.on('end', () => {
  console.log('desconectado do servidor')
})
js
const net = require('node:net')
const client = net.createConnection({ port: 8124 }, () => {
  // Listener 'connect'.
  console.log('conectado ao servidor!')
  client.write('mundo!\r\n')
})
client.on('data', data => {
  console.log(data.toString())
  client.end()
})
client.on('end', () => {
  console.log('desconectado do servidor')
})

Para conectar no socket /tmp/echo.sock:

js
const client = net.createConnection({ path: '/tmp/echo.sock' })

A seguir, um exemplo de um cliente usando a opção port e onread. Nesse caso, a opção onread será usada apenas para chamar new net.Socket([options]) e a opção port será usada para chamar socket.connect(options[, connectListener]).

js
import net from 'node:net'
import { Buffer } from 'node:buffer'
net.createConnection({
  port: 8124,
  onread: {
    // Reutiliza um Buffer de 4KiB para cada leitura do socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function (nread, buf) {
      // Os dados recebidos estão disponíveis em `buf` de 0 até `nread`.
      console.log(buf.toString('utf8', 0, nread))
    },
  },
})
js
const net = require('node:net')
net.createConnection({
  port: 8124,
  onread: {
    // Reutiliza um Buffer de 4KiB para cada leitura do socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function (nread, buf) {
      // Os dados recebidos estão disponíveis em `buf` de 0 até `nread`.
      console.log(buf.toString('utf8', 0, nread))
    },
  },
})

net.createConnection(path[, connectListener]) ​

Adicionado em: v0.1.90

Inicia uma conexão IPC.

Esta função cria um novo net.Socket com todas as opções definidas como padrão, inicia imediatamente a conexão com socket.connect(path[, connectListener]) e, em seguida, retorna o net.Socket que inicia a conexão.

net.createConnection(port[, host][, connectListener]) ​

Adicionado em: v0.1.90

Inicia uma conexão TCP.

Esta função cria um novo net.Socket com todas as opções definidas como padrão, inicia imediatamente a conexão com socket.connect(port[, host][, connectListener]) e, em seguida, retorna o net.Socket que inicia a conexão.

net.createServer([options][, connectionListener]) ​

[Histórico]

VersãoMudanças
v20.1.0, v18.17.0A opção highWaterMark agora é suportada.
v17.7.0, v16.15.0As opções noDelay, keepAlive e keepAliveInitialDelay agora são suportadas.
v0.5.0Adicionado em: v0.5.0

  • options <Objeto>

    • allowHalfOpen <boolean> Se definido como false, então o socket encerrará automaticamente o lado gravável quando o lado legível terminar. Padrão: false.
    • highWaterMark <number> Opcionalmente, substitui readableHighWaterMark e writableHighWaterMark de todos os net.Sockets. Padrão: Consulte stream.getDefaultHighWaterMark().
    • keepAlive <boolean> Se definido como true, ele ativa a funcionalidade keep-alive no socket imediatamente após o recebimento de uma nova conexão de entrada, de forma semelhante ao que é feito em socket.setKeepAlive(). Padrão: false.
    • keepAliveInitialDelay <number> Se definido como um número positivo, ele define o atraso inicial antes que a primeira sonda keepalive seja enviada em um socket ocioso. Padrão: 0.
    • noDelay <boolean> Se definido como true, ele desativa o uso do algoritmo de Nagle imediatamente após o recebimento de uma nova conexão de entrada. Padrão: false.
    • pauseOnConnect <boolean> Indica se o socket deve ser pausado em conexões de entrada. Padrão: false.
    • blockList <net.BlockList> blockList pode ser usado para desabilitar o acesso de entrada a endereços IP, intervalos de IP ou sub-redes IP específicos. Isso não funciona se o servidor estiver atrás de um proxy reverso, NAT, etc., porque o endereço verificado em relação à lista de bloqueio é o endereço do proxy ou aquele especificado pelo NAT.

  • connectionListener <Função> Definido automaticamente como um listener para o evento 'connection'.

  • Retorna: <net.Server>

Cria um novo servidor TCP ou IPC.

Se allowHalfOpen for definido como true, quando a outra extremidade do socket sinalizar o final da transmissão, o servidor só enviará o final da transmissão quando socket.end() for chamado explicitamente. Por exemplo, no contexto de TCP, quando um pacote FIN é recebido, um pacote FIN é enviado de volta somente quando socket.end() é chamado explicitamente. Até então, a conexão é semiaberta (não legível, mas ainda gravável). Consulte o evento 'end' e o RFC 1122 (seção 4.2.2.13) para mais informações.

Se pauseOnConnect for definido como true, o socket associado a cada conexão de entrada será pausado e nenhum dado será lido de seu manipulador. Isso permite que as conexões sejam passadas entre processos sem que nenhum dado seja lido pelo processo original. Para começar a ler dados de um socket pausado, chame socket.resume().

O servidor pode ser um servidor TCP ou um servidor IPC, dependendo do que ele listen() para.

Aqui está um exemplo de um servidor de eco TCP que escuta conexões na porta 8124:

js
import net from 'node:net'
const server = net.createServer(c => {
  // Listener 'connection'.
  console.log('cliente conectado')
  c.on('end', () => {
    console.log('cliente desconectado')
  })
  c.write('olá\r\n')
  c.pipe(c)
})
server.on('error', err => {
  throw err
})
server.listen(8124, () => {
  console.log('servidor vinculado')
})
js
const net = require('node:net')
const server = net.createServer(c => {
  // Listener 'connection'.
  console.log('cliente conectado')
  c.on('end', () => {
    console.log('cliente desconectado')
  })
  c.write('olá\r\n')
  c.pipe(c)
})
server.on('error', err => {
  throw err
})
server.listen(8124, () => {
  console.log('servidor vinculado')
})

Teste isso usando telnet:

bash
telnet localhost 8124

Para escutar no socket /tmp/echo.sock:

js
server.listen('/tmp/echo.sock', () => {
  console.log('servidor vinculado')
})

Use nc para conectar a um servidor de socket de domínio Unix:

bash
nc -U /tmp/echo.sock

net.getDefaultAutoSelectFamily() ​

Adicionado em: v19.4.0

Obtém o valor padrão atual da opção autoSelectFamily de socket.connect(options). O valor padrão inicial é true, a menos que a opção de linha de comando --no-network-family-autoselection seja fornecida.

  • Retorna: <boolean> O valor padrão atual da opção autoSelectFamily.

net.setDefaultAutoSelectFamily(value) ​

Adicionado em: v19.4.0

Define o valor padrão da opção autoSelectFamily de socket.connect(options).

  • value <boolean> O novo valor padrão. O valor padrão inicial é true, a menos que a opção de linha de comando --no-network-family-autoselection seja fornecida.

net.getDefaultAutoSelectFamilyAttemptTimeout() ​

Adicionado em: v19.8.0, v18.18.0

Obtém o valor padrão atual da opção autoSelectFamilyAttemptTimeout de socket.connect(options). O valor padrão inicial é 250 ou o valor especificado através da opção de linha de comando --network-family-autoselection-attempt-timeout.

  • Retorna: <number> O valor padrão atual da opção autoSelectFamilyAttemptTimeout.

net.setDefaultAutoSelectFamilyAttemptTimeout(value) ​

Adicionado em: v19.8.0, v18.18.0

Define o valor padrão da opção autoSelectFamilyAttemptTimeout de socket.connect(options).

  • value <number> O novo valor padrão, que deve ser um número positivo. Se o número for menor que 10, o valor 10 será usado. O valor padrão inicial é 250 ou o valor especificado através da opção de linha de comando --network-family-autoselection-attempt-timeout.

net.isIP(input) ​

Adicionado em: v0.3.0

Retorna 6 se input for um endereço IPv6. Retorna 4 se input for um endereço IPv4 em notação decimal com pontos sem zeros à esquerda. Caso contrário, retorna 0.

js
net.isIP('::1') // retorna 6
net.isIP('127.0.0.1') // retorna 4
net.isIP('127.000.000.001') // retorna 0
net.isIP('127.0.0.1/24') // retorna 0
net.isIP('fhqwhgads') // retorna 0

net.isIPv4(input) ​

Adicionado em: v0.3.0

Retorna true se input for um endereço IPv4 em notação decimal com pontos sem zeros à esquerda. Caso contrário, retorna false.

js
net.isIPv4('127.0.0.1') // retorna true
net.isIPv4('127.000.000.001') // retorna false
net.isIPv4('127.0.0.1/24') // retorna false
net.isIPv4('fhqwhgads') // retorna false

net.isIPv6(input) ​

Adicionado em: v0.3.0

Retorna true se input for um endereço IPv6. Caso contrário, retorna false.

js
net.isIPv6('::1') // retorna true
net.isIPv6('fhqwhgads') // retorna false