summaryrefslogtreecommitdiff
path: root/doc/api/libstd/networking.txt
blob: 0229573a33a37941364e250a1d655472f1a1ecc2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
{
        title: Networking
        description:    libstd: Networking
}
Networking
----------

    pkg std =
            type netaddr = union
                    `Ipv4	byte[4]
                    `Ipv6	byte[16]
            ;;


            /* network connections */
            const dial	: (dialstr : byte[:] -> result(fd, byte[:]))
            const announce	: (ds : byte[:] -> result(fd, byte[:]))
            const listen	: (sock : fd -> result(fd, byte[:]))
            const accept	: (lfd : fd -> result(fd, byte[:]))

            /* ip parsing */
            const ipparse	: (ip : byte[:]	-> option(netaddr))
            const ip4parse	: (ip : byte[:] -> option(netaddr))
            const ip6parse	: (ip : byte[:] -> option(netaddr))

            generic hosttonet	: (v : @a -> @a)
            generic nettohost	: (v : @a -> @a)
    ;;

Summary
-------

This group of functions contains the basic, portable networking functionality
provided by libstd. There are other packages shipped which provide access
to the underlying functionality used to implement this code, and which may
provide more control.

The bulk of the functionality is fairly low level. Most of the client side
networking should be done using nothing more than `dial` and `announce`

Dial describes the endpoint to connect to in the form `proto!host!service`.
`proto` can be any supported protocol.  The host specified can be an IP
address, hostname, or path to a local socket. The service ismay be either a
named service, or a protocol specific port. If the port is not a component of
the address (eg, Unix domain sockets) then it should be ommitted.

On plan 9, the full dial(2) dial string syntax is suported.

Data Types
----------

This contains the infomation that we extract by resolving a host.

    type ipaddr = union
            `Ipv4	byte[4]
            `Ipv6	byte[16]
    ;;

This contains an IP address. Either V4 or V6 is supported.

Connections
----------

    const dial	: (dialstr : byte[:] -> result(fd, byte[:]))

Dial connects to a dial string as described in the summary, returning either a
file descriptor on success, or an error description on failure. The FD
returned is a connection to the server.

    const announce	: (ds : byte[:] -> result(fd, byte[:]))

Announce sets up a file descriptor which is ready to listen for connections,
and binds it to an address. Wildcards can be specified with '*' within the
dial string.

    const listen	: (sock : fd -> result(fd, byte[:]))

Listen specifies that the socket created with `announce` is willing to accept
connections.

    const accept	: (lfd : fd -> result(fd, byte[:]))

Accept takes the returned file descriptor from listen, and returns a file
descriptor that is prepared for reading and writing.

IP Parsing
----------

    const ipparse	: (ip : byte[:]	-> option(netaddr))

Ipparse will parse an IP address. This will recognize either V4 or V6
addresses, and `\`Some \`Ipv4 bits or `\`Some \`Ipv6 bits` as appropriate, or
`\`None` if the address can't be parsed.

    const ip4parse	: (ip : byte[:] -> option(netaddr))

Parses an Ipv4 address from the string `ip`. The syntax expected is dotted
quad notation. Returns `\` Some \`Ipv4 bits` if the address parses successfully, or
`\`None` if parsing fails.

    const ip6parse	: (ip : byte[:] -> option(netaddr))

Parses an Ipv6 address from the string `ip`. Returns `\` Some \`Ipv4 bits` if
the address parses successfully, or `\`None` if parsing fails. Zones are
currently not supported. This is a bug.


Endian flipping
--------------

    generic hosttonet	: (v : @a -> @a)
    generic nettohost	: (v : @a -> @a)


Flips the bits in an integer to match the expected. These functions should be
avoided in favor of explicit packing functions.

Examples
--------

Some simple examples of how to use the Myrddin networking API

#### Echo Server

	use std

	const Dialstr = "tcp!*!1234"
	const main = {
		var lfd, afd
		var buf : byte[1024]

		match std.announce(Dialstr)
		| `std.Ok f:    lfd = f
		| `std.Fail e:  std.fatal("unable to announce on {}: {}\n", Dialstr, e)
		;;

		match std.listen(lfd)
		| `std.Ok f:    afd = f
		| `std.Fail e:  std.fatal("unable to listen on {}: {}\n", Dialstr, e)
		;;

		while true
			match std.accept(afd)
			| `std.Ok fd:
				match std.read(fd, buf[:])
				| `std.Ok n:
					std.writeall(fd, buf[:n])
				| `std.Fail e:
					std.put("lost conection while reading: {}\n", e)
				;;
				std.close(fd)
			| `std.Fail e:
				std.fatal("unable to accept connection on {}: {}\n", Dialstr, e)
			;;
		;;
	}
		

#### Echo Client

	use std

	const Dialstr = "tcp!localhost!1234"
	const main = {args : byte[:][:]
		var req, resp

		match std.dial(Dialstr)
		| `std.Ok fd:
			req = std.strjoin(args[1:], " ")
			std.writeall(fd, req)
			resp = std.try(std.fslurp(fd))
			std.put("{}\n", resp)
		| `std.Fail e:
			std.fatal("unable to dial {}: {}\n", Dialstr, e)
		;;
	}

Bugs
----
The errors returned are strings, when they should be unions with default
formatting functions.