net

Documentation

Overview

Package net provide constants and library for networking.

Index

• Variables
• func IsHostnameValid(hname []byte, isFQDN bool) bool
• func IsIPv4(ip net.IP) bool
• func IsIPv6(ip net.IP) bool
• func IsTypeTCP(t Type) bool
• func IsTypeTransport(t Type) bool
• func IsTypeUDP(t Type) bool
• func ParseIPPort(address string, defPort uint16) (host string, ip net.IP, port uint16)
• func ParseTCPAddr(address string, defPort uint16) (udp *net.TCPAddr, err error)
• func ParseUDPAddr(address string, defPort uint16) (udp *net.UDPAddr, err error)
• func Read(conn net.Conn, bufsize int, timeout time.Duration) (packet []byte, err error)
• func ToDotIPv6(ip net.IP) (out []byte)
• func WaitAlive(network, address string, timeout time.Duration) (err error)
• type Poll
  • func NewPoll() (Poll, error)
• type PollEvent
• type ResolvConf
  • func NewResolvConf(path string) (rc *ResolvConf, err error)
  • func (rc *ResolvConf) Init(src string)
  • func (rc *ResolvConf) PopulateQuery(dname string) (queries []string)
  • func (rc *ResolvConf) WriteTo(w io.Writer) (n int64, err error)
• type Type
  • func ConvertStandard(network string) Type

Examples

• ResolvConf.PopulateQuery
• ResolvConf.WriteTo

Variables

var ErrHostAddress = errors.New("invalid host address")

ErrHostAddress define an error if address of connection is invalid.

var ErrReadTimeout = errors.New(`read timeout`)

ErrReadTimeout define an error when Read operation receive no data after waiting for specific duration.

Functions

func IsHostnameValid

func IsHostnameValid(hname []byte, isFQDN bool) bool

IsHostnameValid will return true if hostname is valid, otherwise it will return false. They must begin with alphanumeric character or "_" and end with an alphanumeric character. Host names may contain only alphanumeric characters, minus signs ("-"), underscore ("_"), and periods (".").

If isFQDN is true, the hostname must at least contains two labels; otherwise it will be invalid.

See rfc952 and rfc1123.

func IsIPv4

func IsIPv4(ip net.IP) bool

IsIPv4 will return true if string representation of IP contains three dots, for example "127.0.0.1".

func IsIPv6

func IsIPv6(ip net.IP) bool

IsIPv6 will return true if string representation of IP contains two or more colons ":", for example, "::1".

func IsTypeTCP

func IsTypeTCP(t Type) bool

IsTypeTCP will return true if t is type of TCP(4,6); otherwise it will return false.

func IsTypeTransport

func IsTypeTransport(t Type) bool

IsTypeTransport will return true if t is type of transport layer, i.e. tcp(4,6) or udp(4,6); otherwise it will return false.

func IsTypeUDP

func IsTypeUDP(t Type) bool

IsTypeUDP will return true if t is type of UDP(4,6); otherwise it will return false.

func ParseIPPort

func ParseIPPort(address string, defPort uint16) (host string, ip net.IP, port uint16)

ParseIPPort parse address into hostname/address, IP and port. If address is not an IP address, it will return the address as hostname (without port number if its exist) and nil on ip. In case of port is empty or invalid, it will set to defPort.

func ParseTCPAddr

func ParseTCPAddr(address string, defPort uint16) (udp *net.TCPAddr, err error)

ParseTCPAddr parse IP address into standard library TCP address. If address is not contains IP address, it will return nil with error. In case of port is empty, it will set to default port value in defPort.

func ParseUDPAddr

func ParseUDPAddr(address string, defPort uint16) (udp *net.UDPAddr, err error)

ParseUDPAddr parse IP address into standard library UDP address. If address is not contains IP address, it will return nil with error. In case of port is empty, it will set to default port value in defPort.

func Read

func Read(conn net.Conn, bufsize int, timeout time.Duration) (packet []byte, err error)

Read packet from network.

If the conn parameter is nil it will return net.ErrClosed.

The bufsize parameter set the size of buffer for each read operation, default to 1024 if not set or invalid (less than 0 or greater than 65535).

The timeout parameter set how long to wait for data before considering it as failed. If its not set, less or equal to 0, it will wait forever. If no data received and timeout is set, it will return ErrReadTimeout.

If there is data received and connection closed at the same time, it will return the data first without error. The subsequent Read will return empty packet with [ErrClosed].

func ToDotIPv6

func ToDotIPv6(ip net.IP) (out []byte)

ToDotIPv6 convert the IPv6 address format from "::1" format into "0.0.0.0 ... 0.0.0.1".

This function only useful for expanding SPF macro "i" or when generating query for DNS PTR.

func WaitAlive

func WaitAlive(network, address string, timeout time.Duration) (err error)

WaitAlive try to connect to network at address until timeout reached. If connection cannot established it will return an error.

Unlike net.DialTimeout, this function will retry not returning an error immediately if the address has not ready yet.

Types

type Poll

type Poll interface {
	// Close the poll.
	Close()

	// RegisterRead add the file descriptor to read poll.
	RegisterRead(fd int) (err error)

	// UnregisterRead remove file descriptor from the poll.
	UnregisterRead(fd int) (err error)

	// WaitRead wait and return list of file descriptor (fd) that are
	// ready for reading from the pool.
	// The returned fd is detached from poll to allow concurrent
	// processing of fd at the same time.
	// Once the data has been read from the fd and its still need to be
	// used, one need to put it back to poll using RegisterRead.
	WaitRead() (fds []int, err error)

	// WaitReadEvents wait and return list of PollEvent that contains the
	// file descriptor and the underlying OS specific event state.
	WaitReadEvents() (events []PollEvent, err error)
}

Poll represent an interface to network polling.

func NewPoll

func NewPoll() (Poll, error)

NewPoll create and initialize new poll using epoll for Linux system or kqueue for BSD or Darwin (macOS).

type PollEvent

type PollEvent interface {
	// Descriptor return the file descriptor associated with poll.
	Descriptor() uint64

	// Event return the underlying event structure.
	// It can be cast to actual type, unix.EpollEvent in Linux or
	// unix.Kevent_t on BSD.
	Event() any
}

PollEvent define an interface for poll event, unix.EpollEvent on Linux or unix.Kevent_t on BSD.

type ResolvConf

type ResolvConf struct {
	// OptMisc contains other options with string key and boolean value.
	OptMisc map[string]bool

	// Local domain name.
	// Most queries for names within this domain can use short names
	// relative to the local domain.  If set to '.', the root domain
	// is considered.  If no domain entry is present, the domain is
	// determined from the local hostname returned by gethostname(2);
	// the domain part is taken to be everything after the first '.'.
	// Finally, if the hostname does not contain a domain part, the
	// root domain is assumed.
	Domain string

	// Search list for host-name lookup.
	// The search list is normally determined from the local domain
	// name; by default, it contains only the local domain name.
	// This may be changed by listing the desired domain search path
	// following the search keyword with spaces or tabs separating
	// the names.  Resolver queries having fewer than ndots dots
	// (default is 1) in them will be attempted using each component
	// of the search path in turn until a match is found.  For
	// environments with multiple subdomains please read options
	// ndots:n below to avoid man-in-the-middle attacks and
	// unnecessary traffic for the root-dns-servers.  Note that this
	// process may be slow and will generate a lot of network traffic
	// if the servers for the listed domains are not local, and that
	// queries will time out if no server is available for one of the
	// domains.
	//
	// The search list is currently limited to six domains with a
	// total of 256 characters.
	Search []string

	// Name server IP address
	// Internet address of a name server that the resolver should
	// query, either an IPv4 address (in dot notation), or an IPv6
	// address in colon (and possibly dot) notation as per RFC 2373.
	// Up to 3 name servers may be listed, one per keyword.  If there are
	// multiple servers, the resolver library queries them in the order
	// listed.  If no nameserver entries are present, the default is to
	// use the name server on the local machine.  (The algorithm used is
	// to try a name server, and if the query times out, try the next,
	// until out of name servers, then repeat trying all the name servers
	// until a maximum number of retries are made.)
	NameServers []string

	// Sets a threshold for the number of dots which must appear in a name
	// before an initial absolute query will be made.  The default for n
	// is 1, meaning that if there are any dots in a name, the name will
	// be tried first as an absolute name before any search list elements
	// are appended to it.  The value for this option is silently capped
	// to 15.
	NDots int

	// Sets the amount of time the resolver will wait for a response from
	// a remote name server before retrying the query via a different name
	// server. This may not be the total time taken by any resolver API
	// call and there is no guarantee that a single resolver API call maps
	// to a single timeout.  Measured in seconds, the default is 5 The
	// value for this option is silently capped to 30.
	Timeout int

	// Sets the number of times the resolver will send a query to its name
	// servers before giving up and returning an error to the calling
	// application.  The default is 2. The value for this option is
	// silently capped to 5.
	Attempts int
}

ResolvConf contains value of resolver configuration file.

Reference: "man resolv.conf" in Linux.

func NewResolvConf

func NewResolvConf(path string) (rc *ResolvConf, err error)

NewResolvConf open resolv.conf file in path and return the parsed records.

func (*ResolvConf) Init

func (rc *ResolvConf) Init(src string)

Init parse resolv.conf from string.

func (*ResolvConf) PopulateQuery

func (rc *ResolvConf) PopulateQuery(dname string) (queries []string)

PopulateQuery given a domain name to be resolved, generate list of names to be queried based on registered Search in the resolv.conf. The dname itself will be on top of the list. If the number of dots in dname less than NDots then each Search domain will be appended as suffix and added to the list.

Example

package main

import (
	"fmt"

	libnet "git.sr.ht/~shulhan/pakakeh.go/lib/net"
)

func main() {
	var (
		resconf = &libnet.ResolvConf{
			Domain: `internal`,
			Search: []string{`my.internal`},
			NDots:  1,
		}
		queries []string
	)

	queries = resconf.PopulateQuery(`vpn`)
	fmt.Println(queries)
	queries = resconf.PopulateQuery(`a.machine`)
	fmt.Println(queries)

}

Output:

[vpn vpn.my.internal]
[a.machine]

func (*ResolvConf) WriteTo

func (rc *ResolvConf) WriteTo(w io.Writer) (n int64, err error)

WriteTo write the ResolvConf into w.

Example

package main

import (
	"bytes"
	"fmt"
	"log"

	libnet "git.sr.ht/~shulhan/pakakeh.go/lib/net"
)

func main() {
	var (
		rc = &libnet.ResolvConf{
			Domain:      `internal`,
			Search:      []string{`a.internal`, `b.internal`},
			NameServers: []string{`127.0.0.1`, `192.168.1.1`},
			NDots:       1,
			Timeout:     5,
			Attempts:    3,
			OptMisc: map[string]bool{
				`rotate`: true,
				`debug`:  true,
			},
		}

		bb  bytes.Buffer
		err error
	)

	_, err = rc.WriteTo(&bb)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(bb.String())
}

Output:

domain internal
search a.internal b.internal
nameserver 127.0.0.1
nameserver 192.168.1.1
options ndots:1
options timeout:5
options attempts:3
options debug
options rotate

type Type

type Type uint16

Type of network.

const (
	TypeInvalid Type = 0
	TypeTCP     Type = 1 << iota
	TypeTCP4
	TypeTCP6
	TypeUDP
	TypeUDP4
	TypeUDP6
	TypeIP
	TypeIP4
	TypeIP6
	TypeUnix
	TypeUnixGram
	TypeUnixPacket
)

List of possible network type.

func ConvertStandard

func ConvertStandard(network string) Type

ConvertStandard library network value from string to Type. It will return TypeInvalid (0) if network is unknown.