xnet

Documentation

Overview

Package xnet extends the Go standard library package net by providing additional primitives and structures for network I/O.

Index

• Constants
• func Dial(network, address string, options ...DialOption) (net.Conn, error)
• func DialContext(ctx context.Context, network, address string, options ...DialOption) (net.Conn, error)
• func FreePort(ctx context.Context, network string, options ...ListenConfigOption) (int, error)
• func ParsePort(port string, allowZero bool) (int, error)
• type DialOption
  • func DialConnectDeadline(deadline time.Time) DialOption
  • func DialConnectTimeout(timeout time.Duration) DialOption
  • func DialKeepAlive(keepAlive time.Duration) DialOption
  • func DialReadTimeout(timeout time.Duration) DialOption
  • func DialWriteTimeout(timeout time.Duration) DialOption
• type Dialer
  • func (d *Dialer) Dial(network, address string) (net.Conn, error)
  • func (d *Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)
• type ListenConfigOption
  • func ListenConfigControl(fn func(network, address string, c syscall.RawConn) error) ListenConfigOption
  • func ListenConfigKeepAlive(keepAlive time.Duration) ListenConfigOption

Examples

• Dial
• DialContext
• Dialer.Dial
• Dialer.DialContext
• FreePort
• ParsePort

Constants

const (
	NetworkIP         = "ip"
	NetworkIP4        = "ip4"
	NetworkIP6        = "ip6"
	NetworkTCP        = "tcp"
	NetworkTCP4       = "tcp4"
	NetworkTCP6       = "tcp6"
	NetworkUDP        = "udp"
	NetworkUDP4       = "udp4"
	NetworkUDP6       = "udp6"
	NetworkUnix       = "unix"
	NetworkUnixgram   = "unixgram"
	NetworkUnixpacket = "unixpacket"
)

Enumaration of networks.

Functions

func Dial

func Dial(network, address string, options ...DialOption) (net.Conn, error)

Dial acts like net.Dial but uses a Dialer that supports read and write timeouts at the connection level. Optional DialOption parameters may be passed in to configure the Dialer.

Read and write timeouts are respectively applied to each Read and Write call on the net.Conn (a zero value means no timeout).

See net.Dial for more information.

Example

package main

import (
	"log"
	"time"

	"github.com/jlourenc/xgo/xnet"
)

func main() {
	dialOptions := []xnet.DialOption{
		xnet.DialReadTimeout(time.Second),
		xnet.DialWriteTimeout(time.Second),
	}

	conn, err := xnet.Dial(xnet.NetworkTCP, "localhost:12345", dialOptions...)
	if err != nil {
		log.Fatalf("Failed to dial: %v", err)
	}
	defer conn.Close()

	log.Print("Connection established")
}

func DialContext

func DialContext(ctx context.Context, network, address string, options ...DialOption) (net.Conn, error)

DialContext acts like Dial but takes a context.Context.

See net.Dialer.DialContext for more information.

Example

package main

import (
	"context"
	"log"
	"time"

	"github.com/jlourenc/xgo/xnet"
)

func main() {
	dialOptions := []xnet.DialOption{
		xnet.DialReadTimeout(time.Second),
		xnet.DialWriteTimeout(time.Second),
	}

	conn, err := xnet.DialContext(context.Background(), xnet.NetworkTCP, "localhost:12345", dialOptions...)
	if err != nil {
		log.Fatalf("Failed to dial: %v", err)
	}
	defer conn.Close()

	log.Print("Connection established")
}

func FreePort

func FreePort(ctx context.Context, network string, options ...ListenConfigOption) (int, error)

FreePort asks the kernel for a free open port, that is ready to use, on the specified Network. Only TCP or UDP networks are supported.

Example

package main

import (
	"context"
	"log"

	"github.com/jlourenc/xgo/xnet"
)

func main() {
	port, err := xnet.FreePort(context.Background(), xnet.NetworkTCP)
	if err != nil {
		log.Fatalf("Failed to get free port: %v", err)
	}

	log.Printf("port: %d", port)
}

func ParsePort

func ParsePort(port string, allowZero bool) (int, error)

ParsePort parses a string representing a port. If the string is not a valid port number, an error is returned.

Example

package main

import (
	"fmt"
	"log"

	"github.com/jlourenc/xgo/xnet"
)

func main() {
	port, err := xnet.ParsePort("12001", false)
	if err != nil {
		log.Fatalf("Failed to parse port number: %v", err)
	}

	fmt.Printf("%d\n", port)
}

Output:

12001

Types

type DialOption

type DialOption interface {
	// contains filtered or unexported methods
}

DialOption configures how connections are made.

func DialConnectDeadline

func DialConnectDeadline(deadline time.Time) DialOption

DialConnectDeadline returns a DialOption that configures a deadline for a connect to complete by.

func DialConnectTimeout

func DialConnectTimeout(timeout time.Duration) DialOption

DialConnectTimeout returns a DialOption that configures a timeout for a connect to complete.

func DialKeepAlive

func DialKeepAlive(keepAlive time.Duration) DialOption

WithKeepAlive returns a DialOption that configures the interval between keep-alive probes for an active network TCP connection.

func DialReadTimeout

func DialReadTimeout(timeout time.Duration) DialOption

DialReadTimeout returns a DialOption that configures a timeout for a Conn Read to complete.

func DialWriteTimeout

func DialWriteTimeout(timeout time.Duration) DialOption

DialWriteTimeout returns a DialOption that configures a timeout for a Conn Write to complete.

type Dialer

type Dialer struct {
	net.Dialer
	// ReadTimeout is the maximum amount of time after which each Conn Read operation
	// fails instead of blocking. In this case, an error that wraps os.ErrDeadlineExceeded
	// is returned. This can be tested using errors.Is(err, os.ErrDeadlineExceeded).
	//
	// The error's Timeout method will return true, but note that there are other possible
	// errors for which the Timeout method will return true even if the Read has timed out.
	//
	// The default is no timeout. (zero value)
	ReadTimeout time.Duration
	// WriteTimeout is the maximum amount of time after which each Conn Write operation
	// fails instead of blocking. In this case, an error that wraps os.ErrDeadlineExceeded
	// is returned. This can be tested using errors.Is(err, os.ErrDeadlineExceeded).
	//
	// The error's Timeout method will return true, but note that there are other possible
	// errors for which the Timeout method will return true even if the Write has timed out.
	//
	// The default is no timeout. (zero value)
	WriteTimeout time.Duration
}

Dialer is a wrapper around net.Dialer that provides additional options for connecting to an address.

See net.Dialer for more information.

func (*Dialer) Dial

func (d *Dialer) Dial(network, address string) (net.Conn, error)

Dial acts like net.Dialer.Dial but uses a Dialer that supports read and write timeouts at the connection level.

See Dial for more information.

Example

package main

import (
	"log"
	"time"

	"github.com/jlourenc/xgo/xnet"
)

func main() {
	d := xnet.Dialer{
		ReadTimeout:  time.Second,
		WriteTimeout: time.Second,
	}

	conn, err := d.Dial(xnet.NetworkTCP, "localhost:12345")
	if err != nil {
		log.Fatalf("Failed to dial: %v", err)
	}
	defer conn.Close()

	log.Print("Connection established")
}

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext acts like Dialer.Dial but takes a context.Context.

See net.Dialer.DialContext for more information.

Example

package main

import (
	"context"
	"log"
	"time"

	"github.com/jlourenc/xgo/xnet"
)

func main() {
	d := xnet.Dialer{
		ReadTimeout:  time.Second,
		WriteTimeout: time.Second,
	}

	conn, err := d.DialContext(context.Background(), xnet.NetworkTCP, "localhost:12345")
	if err != nil {
		log.Fatalf("Failed to dial: %v", err)
	}
	defer conn.Close()

	log.Print("Connection established")
}

type ListenConfigOption

type ListenConfigOption interface {
	// contains filtered or unexported methods
}

ListenConfigOption is an option to configure anet.ListenConfig.

func ListenConfigControl

func ListenConfigControl(fn func(network, address string, c syscall.RawConn) error) ListenConfigOption

ListenConfigControl returns a ListenConfigOption that configures a control of a net.ListenConfig.

func ListenConfigKeepAlive

func ListenConfigKeepAlive(keepAlive time.Duration) ListenConfigOption

ListenConfigKeepAlive returns a ListenConfigOption that configures a keep alive for a net.ListenConfig.