# Go net #

The following are my notes on the Go net package (https://golang.org/pkg/net/).
Much of these are director quotes from the official docs.

The `net` package provides access to low-level networking primitives.
However, many projects only need the basic `Dial`, `Listen`, and `Accept` functions, and the associated `Conn` and `Listener` interfaces.

The Dial function connects to a server:

	package main
	import ("bufio"; "fmt"; "log"; "net")
	func main() {
		conn, err := net.Dial("tcp", "golang.org:80")
		if err != nil {
			log.Fatal(err)
		}
		fmt.Fprintf(conn, "GET / HTTP/1.0\r\n\r\n")
		status, err := bufio.NewReader(conn).ReadString('\n')
		fmt.Printf(string(status))
	}

The Listen function creates servers:

	package main
	import ("log"; "net")
	func main() {
		ln, err := net.Listen("tcp", ":8080")
		if err != nil {
			log.Fatal(err)
		}
		for {
			conn, err := ln.Accept()
			if err != nil {
				log.Println(err)
			}
			go func(c net.Conn) {
				defer c.Close()
				c.Write([]byte("Hello.\n"))
			}(conn)
		}
	}

(Hit the above like `nc 127.0.0.1 8080`.)

## Conn ##

Conn is an interface for generic stream-oriented network connections.
(Comments abbreviated below. See the docs for full comments.)

	type Conn interface {
		// Read data from the connection.
		Read(b []byte) (n int, err error)
		// Write data to the connection.
		Write(b []byte) (n int, err error)
		// Close the connection, unbocking any blocked r/w operations.
		Close() error
		// LocalAddr returns the local network address.
		LocalAddr() Addr
		// RemoteAddr returns the remote network address.
		RemoteAddr() Addr
		// SetDeadline for reads and writes.
		SetDeadline(t time.Time) error
		// SetReadDeadline sets the deadline for Read calls.
		SetReadDeadline(t time.Time) error
		// SetWriteDeadline sets the deadline for Write calls.
		SetWriteDeadline(t time.Time) error
	}

## Listener ##

A Listener is an interface for generic stream-oriented protocols.

	type Listener interface {
			// Accept waits for and returns the next connection to the listener.
			Accept() (Conn, error)
			// Close closes the listener.
			// Any blocked Accept operations will be unblocked and return errors.
			Close() error
			// Addr returns the listener's network address.
			Addr() Addr
	}

## PacketConn and IPConn ##

Although, Conn and Listener are stream-oriented, the `net` package also offers packet-oriented tools.

PacketConn is a generic packet-oriented network connection.
(Comments abbreviated below. See the docs for full comments.)

	type PacketConn interface {
		// ReadFrom reads a packet from the connection,
		// copying the payload into b. It returns the number of
		// bytes copied into b and the return address on the packet.
		ReadFrom(b []byte) (n int, addr Addr, err error)
		// WriteTo writes a packet with payload b to addr.
		WriteTo(b []byte, addr Addr) (n int, err error)
		// Close closes the connection.
		Close() error
		// LocalAddr returns the local network address.
		LocalAddr() Addr
		// SetDeadline sets read and write deadlines for a connection.
		SetDeadline(t time.Time) error
		// SetReadDeadline sets the deadline for future ReadFrom calls.
		SetReadDeadline(t time.Time) error
		// SetWriteDeadline sets the deadline for future WriteTo calls.
		SetWriteDeadline(t time.Time) error
	}

IPConn implements the Conn and PacketConn interfaces for IP network connections.
IPConn offers `DialIP` and `ListenIP` functions.

The `net` package offers still more specialized tools, like `UDPConn`.

Mon Oct 23 17:11:11 EDT 2017