summaryrefslogtreecommitdiff
path: root/doc/api/libstd/dns.txt
blob: 86cf5f4d124937566654412699f21fd543e2f44b (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
{
        title: DNS
        description:    libstd: DNS
}

Networking
----------

     pkg std =
            type rectype = union
                    `DnsA	/* host address */
                    `DnsNS	/* authoritative name server */
                    `DnsCNAME	/* canonical name for an alias */
                    `DnsSOA	/* marks the start of a zone of authority */
                    `DnsWKS	/* well known service description */
                    `DnsPTR	/* domain name pointer */
                    `DnsHINFO	/* host information */
                    `DnsMINFO	/* mailbox or mail list information */
                    `DnsMX	/* mail exchange */
                    `DnsTXT	/* text strings */
                    `DnsAAAA	/* ipv6 host address */
            ;;

            type resolveerr = union
                    `Badhost
                    `Badsrv
                    `Badquery
                    `Badresp
            ;;

            type hostinfo = struct
                    fam	: sys.sockfam
                    stype	: sys.socktype
                    ttl	: uint32
                    addr	: netaddr
            ;;

            const resolve	: (host : byte[:]	-> result(hostinfo[:], resolveerr))
            const resolvemx	: (host : byte[:]	-> result(hostinfo[:], resolveerr))
            const resolverec	: (host : byte[:], t : rectype	-> result(hostinfo[:], resolveerr))
    ;;


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

    type rectype = union
            `DnsA	/* host address */
            `DnsNS	/* authoritative name server */
            `DnsCNAME	/* canonical name for an alias */
            `DnsSOA	/* marks the start of a zone of authority */
            `DnsWKS	/* well known service description */
            `DnsPTR	/* domain name pointer */
            `DnsHINFO	/* host information */
            `DnsMINFO	/* mailbox or mail list information */
            `DnsMX	/* mail exchange */
            `DnsTXT	/* text strings */
            `DnsAAAA	/* ipv6 host address */
    ;;

This union contains all of the record types that we claim to know how to
resolve. At the moment, few of them have been tested sufficiently (only A
records can reasonably be said to be exercised).

    type resolveerr = union
            `Badhost
            `Badsrv
            `Badquery
            `Badresp
    ;;

This union contains the errors that we can encounter when trying to resolve a
host.

    type hostinfo = struct
            fam	: sys.sockfam
            stype	: sys.socktype
            ttl	: uint32
            addr	: netaddr
    ;;

DNS Resolution
--------------

    const resolve	: (host : byte[:]	-> result(hostinfo[:], resolveerr))

Resolves the A or AAAA record for the host `host` using DNS. This function
does caching, expiring based on the TTL. Returns all of the host info entries sent
back by DNS or found in the cache on success, or a resolve error on failure.

    const resolvemx	: (host : byte[:]	-> result(hostinfo[:], resolveerr))

Resolves the MX record for the host `host` using DNS. This function does
caching, expiring based on the TTL. Returns all of the host info entries sent
back by DNS or found in the cache on success, or a resolve error on failure.

    const resolverec	: (host : byte[:], t : rectype	-> result(hostinfo[:], resolveerr))

Resolves a record from DNS. This function's interface is slightly broken, as
it will never work for TXT or CNAME records.