std/io/socks

NAME

std/io/socks - socket programming helpers for Zuzu.

SYNOPSIS

  from std/io/socks import *;

  let srv := listen_tcp( "127.0.0.1", 0 );
  let cli := connect_tcp( "127.0.0.1", srv.port() );
  let peer := srv.accept();

  cli.say( "hello" );
  let line := peer.next_line();

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is not supported by zuzu-js in the browser.

DESCRIPTION

This module provides a practical API for TCP, UDP, and Unix domain sockets.

When possible, method names mirror other stream APIs: read, write, print, say, next_line, each_line, and close.

EXPORTS

Functions

listen_tcp(String host?, Number port?, Number backlog?)
Parameters: host, port, and backlog are optional bind settings. Returns: TCPServer. Creates a TCP listening socket.
connect_tcp(String host, Number port, Bool raw?)
Parameters: host and port identify the server, and raw controls line decoding. Returns: TCPSocket. Connects to a TCP server.
bind_udp(String host?, Number port?, Bool raw?)
Parameters: host, port, and raw are optional bind settings. Returns: UDPSocket. Binds a UDP socket.
connect_udp(String host, Number port, Bool raw?)
Parameters: host and port identify the peer, and raw controls byte handling. Returns: UDPSocket. Creates a connected UDP socket.
listen_unix(String path, Number backlog?)
Parameters: path is the socket path and backlog is optional. Returns: UnixServer. Creates a Unix domain stream server.
connect_unix(String path, Bool raw?)
Parameters: path is the socket path and raw controls line decoding. Returns: UnixSocket. Connects to a Unix domain stream server.

Classes

Socket methods

socket.read(Number length?)
Parameters: length is an optional byte count. Returns: BinaryString or String. Reads data from the socket.
socket.write(value), socket.print(value), socket.say(value)
Parameters: value is data to send. Returns: null. Writes data to the socket, with say adding a newline.
socket.next_line()
Parameters: none. Returns: String, BinaryString, or null. Reads the next line.
socket.each_line(callback)
Parameters: callback is called for each line. Returns: null. Iterates over incoming lines.
socket.close()
Parameters: none. Returns: null. Closes the socket.
socket.is_open()
Parameters: none. Returns: Boolean. Returns true when the socket is open.

TCPSocket

peer_host() and peer_port() take no parameters and return the remote host String and port Number.

TCPServer

accept() returns TCPSocket, port() returns Number, host() returns String, and close() closes the server and returns null.

UDPSocket

send(value, host?, port?) returns null; recv() returns a received datagram value; port() and host() return the bound port and host; close() closes the socket.

UnixSocket / UnixServer

Unix sockets support stream methods, and UnixServer offers accept() returning UnixSocket, path() returning String, and close() returning null.

COPYRIGHT AND LICENCE

std/io/socks is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.

Module