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.
| Campo | Tipo | Descrição |
|---|---|---|
address | string | Endereço textual canônico, como "192.0.2.10" ou "2001:db8::10". |
family | string | Família do endereço: "IPv4" ou "IPv6". |
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.
| Campo | Tipo | Descrição |
|---|---|---|
ip | IpAddress | O endereço IPv4 ou IPv6 analisado. |
port | u16 | Número da porta de 0 até 65535. |
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.
| Campo | Tipo | Descrição |
|---|---|---|
data | u8[] | Payload do datagrama, truncado para o maxBytes solicitado por receiveFrom. |
address | string | Endereço de socket do remetente, como "127.0.0.1:50000". |
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.
| Campo | Tipo | Descrição |
|---|---|---|
code | string | Código estável legível por máquina, como "ERR_NET_TIMEOUT". |
message | string | Explicação legível da falha. |
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étodo | Assinatura | Descriçã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 | () => string | Retorna o endereço local associado. |
close | () => void | Fecha o socket e interrompe recebimentos pendentes. |
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étodo | Assinatura | Descriçã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 | () => string | Retorna o endereço local do socket. |
peerAddress | () => string | Retorna 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 | () => void | Fecha o stream e interrompe I/O pendente. |
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étodo | Assinatura | Descrição |
|---|---|---|
accept | (timeoutMs?: u64) => Promise<Result<TcpStream, NetError>> | Aceita a próxima conexão. |
localAddress | () => string | Retorna o endereço local em escuta. |
close | () => void | Fecha o listener e interrompe accepts pendentes. |
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
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();
}