Tipos de tyrus:net
tyrus:net exporta valores estructurados de dirección y paquete, errores recuperables estructurados y handles explícitos de TCP y UDP.
Los tipos deben importarse por nombre
IpAddress, SocketAddress, UdpPacket, UdpSocket, TcpStream, TcpListener y NetError deben importarse explícitamente siempre que se usen sus campos o métodos.
IpAddress
IpAddress es devuelto por parseIpAddress(). Representa una dirección IPv4 o IPv6 validada.
| Campo | Tipo | Descripción |
|---|---|---|
address | string | Dirección textual canónica, como "192.0.2.10" o "2001:db8::10". |
family | string | Familia de dirección: "IPv4" o "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 es devuelto por parseSocketAddress(). Combina una dirección IP validada con su puerto.
| Campo | Tipo | Descripción |
|---|---|---|
ip | IpAddress | La dirección IPv4 o IPv6 analizada. |
port | u16 | Número de puerto de 0 a 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 es devuelto por UdpSocket.receiveFrom(). Contiene un datagrama recibido y su dirección de origen.
| Campo | Tipo | Descripción |
|---|---|---|
data | u8[] | Payload del datagrama, truncado al maxBytes solicitado por receiveFrom. |
address | string | Dirección de socket del remitente, 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 es el tipo de error recuperable de las operaciones asíncronas de red.
NetError es un Error: un catch (error) sin anotación lo recibe, y error is NetError estrecha el binding a él, con todos los campos de NetError.
| Campo | Tipo | Descripción |
|---|---|---|
code | string | Código estable legible por máquina, como "ERR_NET_TIMEOUT". |
message | string | Explicación legible del fallo. |
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 es devuelto por udpBind(). Ciérralo después de su operación final; las llamadas posteriores devuelven Err(NetError) con ERR_NET_CLOSED.
| Método | Firma | Descripción |
|---|---|---|
sendTo | (data: u8[], address: string, timeoutMs?: u64) => Promise<Result<u64, NetError>> | Envía un datagrama y devuelve la cantidad de bytes enviados. |
receiveFrom | (maxBytes: u32, timeoutMs?: u64) => Promise<Result<UdpPacket, NetError>> | Recibe un datagrama y su dirección de origen. |
setBroadcast | (enabled: boolean) => Promise<void> | Habilita o deshabilita la transmisión broadcast. |
setTtl | (ttl: u32) => Promise<void> | Establece el TTL IP; los valores válidos son de 1 a 255. |
localAddress | () => string | Devuelve la dirección local vinculada. |
close | () => void | Cierra el socket e interrumpe recepciones pendientes. |
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 es devuelto por tcpConnect() y TcpListener.accept(). Ciérralo después de su operación final.
| Método | Firma | Descripción |
|---|---|---|
read | (maxBytes: u32, timeoutMs?: u64) => Promise<Result<u8[], NetError>> | Lee hasta maxBytes; EOF es un array vacío. |
write | (data: u8[], timeoutMs?: u64) => Promise<Result<u64, NetError>> | Escribe bytes y devuelve la cantidad escrita. |
shutdown | () => Promise<Result<void, NetError>> | Cierra el lado de escritura manteniendo el lado de lectura. |
localAddress | () => string | Devuelve la dirección local del socket. |
peerAddress | () => string | Devuelve la dirección remota del socket. |
stream | () => Promise<Result<DuplexStream<u8[], u8[]>, NetError>> | Entrega la conexión a un duplex de bytes acotado; cerrar su lado de escritura cierra solo la dirección de escritura. Después, read, write y shutdown devuelven Err(NetError) con ERR_NET_STREAMED. |
close | () => void | Cierra el stream e interrumpe I/O pendiente. |
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 es devuelto por tcpListen(). Ciérralo después de dejar de aceptar conexiones.
| Método | Firma | Descripción |
|---|---|---|
accept | (timeoutMs?: u64) => Promise<Result<TcpStream, NetError>> | Acepta la siguiente conexión. |
localAddress | () => string | Devuelve la dirección local en escucha. |
close | () => void | Cierra el listener e interrumpe accepts pendientes. |
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();
}Manejo de errores
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();
}