Skip to content

Tipos de tyrus:net ​

tyrus:net exporta valores estruturados de endereço e pacote, erros recuperáveis estruturados e handles explícitos de TCP e UDP.

Os tipos devem ser importados por nome

IpAddress, SocketAddress, UdpPacket, UdpSocket, TcpStream, TcpListener e NetError devem ser importados explicitamente sempre que seus campos ou métodos forem usados.

IpAddress ​

IpAddress é retornado por parseIpAddress(). Ele representa um endereço IPv4 ou IPv6 validado.

CampoTipoDescrição
addressstringEndereço textual canônico, como "192.0.2.10" ou "2001:db8::10".
familystringFamília do endereço: "IPv4" ou "IPv6".
tyrus
import { IpAddress, parseIpAddress } from "tyrus:net";

const address: IpAddress? = parseIpAddress("192.0.2.10");
if (address) {
    print(address.address, address.family); // "192.0.2.10", "IPv4"
}

SocketAddress ​

SocketAddress é retornado por parseSocketAddress(). Ele combina um endereço IP validado com sua porta.

CampoTipoDescrição
ipIpAddressO endereço IPv4 ou IPv6 analisado.
portu16Número da porta de 0 até 65535.
tyrus
import { SocketAddress, parseSocketAddress } from "tyrus:net";

const endpoint: SocketAddress? = parseSocketAddress("[2001:db8::10]:443");
if (endpoint) {
    print(endpoint.ip.address, endpoint.ip.family, endpoint.port); // "2001:db8::10", "IPv6", 443
}

UdpPacket ​

UdpPacket é retornado por UdpSocket.receiveFrom(). Ele contém um datagrama recebido e seu endereço de origem.

CampoTipoDescrição
datau8[]Payload do datagrama, truncado para o maxBytes solicitado por receiveFrom.
addressstringEndereço de socket do remetente, como "127.0.0.1:50000".
tyrus
import { NetError, UdpPacket, UdpSocket, udpBind } from "tyrus:net";

async function receive(): Promise<void> {
    const bindResult: Result<UdpSocket, NetError> = await udpBind("127.0.0.1:0");
    match (bindResult) {
        Ok(socket) => {
            const result: Result<UdpPacket, NetError> = await socket.receiveFrom(1024, 1000);
            match (result) {
                Ok(packet) => { print(packet.data.length, packet.address); // 5, "127.0.0.1:50000"
                }
                Err(error) => { printError(error.code); }
            }
            socket.close();
        }
        Err(error) => { printError(error.code); }
    }
}

NetError ​

NetError é o tipo de erro recuperável das operações assíncronas de rede.

NetError é um Error: um catch (error) sem anotação o recebe, e error is NetError estreita o binding para ele, com todos os campos de NetError.

CampoTipoDescrição
codestringCódigo estável legível por máquina, como "ERR_NET_TIMEOUT".
messagestringExplicação legível da falha.
tyrus
import { NetError, TcpStream, tcpConnect } from "tyrus:net";

async function connect(): Promise<void> {
    const result: Result<TcpStream, NetError> = await tcpConnect("127.0.0.1:1", 100);
    match (result) {
        Ok(stream) => { stream.close(); }
        Err(error) => { print(error.code, error.message); // "ERR_NET_CONNECTION_REFUSED", "the TCP connection was refused"
        }
    }
}

Métodos de UdpSocket ​

UdpSocket é retornado por udpBind(). Feche-o após sua operação final; chamadas posteriores retornam Err(NetError) com ERR_NET_CLOSED.

MétodoAssinaturaDescrição
sendTo(data: u8[], address: string, timeoutMs?: u64) => Promise<Result<u64, NetError>>Envia um datagrama e retorna a quantidade de bytes enviados.
receiveFrom(maxBytes: u32, timeoutMs?: u64) => Promise<Result<UdpPacket, NetError>>Recebe um datagrama e seu endereço de origem.
setBroadcast(enabled: boolean) => Promise<void>Habilita ou desabilita transmissão por broadcast.
setTtl(ttl: u32) => Promise<void>Define o TTL IP; valores válidos são de 1 a 255.
localAddress() => stringRetorna o endereço local associado.
close() => voidFecha o socket e interrompe recebimentos pendentes.
tyrus
import { NetError, UdpSocket, udpBind } from "tyrus:net";

async function useUdp(): Promise<Result<void, NetError>> {
    const socket: UdpSocket = (await udpBind("127.0.0.1:0"))?;
    (await socket.setBroadcast(false))?;
    (await socket.setTtl(64))?;
    const sent: u64 = (await socket.sendTo([104, 101, 108, 108, 111], "127.0.0.1:9000", 1000))?;
    print(socket.localAddress(), sent); // "127.0.0.1:random-port", 5
    socket.close();
    return Ok();
}

Métodos de TcpStream ​

TcpStream é retornado por tcpConnect() e TcpListener.accept(). Feche-o após sua operação final.

MétodoAssinaturaDescrição
read(maxBytes: u32, timeoutMs?: u64) => Promise<Result<u8[], NetError>>Lê até maxBytes; EOF é um array vazio.
write(data: u8[], timeoutMs?: u64) => Promise<Result<u64, NetError>>Escreve bytes e retorna a quantidade escrita.
shutdown() => Promise<Result<void, NetError>>Fecha o lado de escrita mantendo o lado de leitura.
localAddress() => stringRetorna o endereço local do socket.
peerAddress() => stringRetorna o endereço remoto do socket.
stream() => Promise<Result<DuplexStream<u8[], u8[]>, NetError>>Entrega a conexão a um duplex de bytes limitado; fechar o lado de escrita encerra só a direção de escrita. Depois disso, read, write e shutdown retornam Err(NetError) com ERR_NET_STREAMED.
close() => voidFecha o stream e interrompe I/O pendente.
tyrus
import { NetError, TcpStream, tcpConnect } from "tyrus:net";

async function useTcp(): Promise<Result<void, NetError>> {
    const stream: TcpStream = (await tcpConnect("127.0.0.1:8080", 1000))?;
    const written: u64 = (await stream.write([104, 105], 1000))?;
    const data: u8[] = (await stream.read(1024, 1000))?;
    (await stream.shutdown())?;
    print(stream.localAddress(), stream.peerAddress(), written, data.length); // "127.0.0.1:random-port", "127.0.0.1:8080", 2, 2
    stream.close();
    return Ok();
}

Métodos de TcpListener ​

TcpListener é retornado por tcpListen(). Feche-o depois que parar de aceitar conexões.

MétodoAssinaturaDescrição
accept(timeoutMs?: u64) => Promise<Result<TcpStream, NetError>>Aceita a próxima conexão.
localAddress() => stringRetorna o endereço local em escuta.
close() => voidFecha o listener e interrompe accepts pendentes.
tyrus
import { NetError, TcpListener, TcpStream, tcpListen } from "tyrus:net";

async function acceptOne(): Promise<Result<void, NetError>> {
    const listener: TcpListener = (await tcpListen("127.0.0.1:0", 1000))?;
    print(listener.localAddress()); // "127.0.0.1:random-port"
    const stream: TcpStream = (await listener.accept(1000))?;
    print(stream.peerAddress()); // "127.0.0.1:random-port"
    stream.close();
    listener.close();
    return Ok();
}

Tratamento de erro ​

error

tyrus
import { NetError, UdpSocket, udpBind } from "tyrus:net";

async function useClosedSocket(): Promise<Result<void, NetError>> {
    const socket: UdpSocket = (await udpBind("127.0.0.1:0"))?;
    socket.close();
    const result: Result<UdpPacket, NetError> = await socket.receiveFrom(32, 1000);
    match (result) {
        Ok(_) => {}
        Err(error) => { print(error.code); // "ERR_NET_CLOSED"
        }
    }
    return Ok();
}