pingu

README

PINGU

This is a simple and tiny heartbeat library with UDP.
Heartbeat is a message that checks if you are healthy or if other connected peers are healthy. The core feature is to periodically request a heartbeat and send an 'alive' message when a heartbeat request is received. Also need to surface a method that allows the user to check the health status.
It could make it your building easier when you need build a server with heartbeat.
If you need heartbeat communication with an external network among peers, register the public IP obtained through a process such as hole punching(This library does not support communication across NAT).

Install

$ go get -u github.com/protocol-diver/pingu

Usage

Create your Pingu

myPingu, err := pingu.NewPingu("127.0.0.1:4874", nil)

// You could preconfig like below,
pingu.Config{
  RecvBufferSize: 512, // default value : 256
  Verbose: true // It's notify that what's going on, default value : false
}

Embed into your Server

type Server struct {
  conn  *net.TCPConn
  pingu *pingu.Pingu
}

Register other Pingus

if err := myPingu.RegisterWithRawAddr("127.0.0.1:4875"); err != nil {
  return err
}
if err := myPingu.RegisterWithRawAddr("127.0.0.1:4876"); err != nil {
  return err
}

Let work Pingu

myPingu.Start()

ticker := time.Ticker(5 * time.Second)
// Second param is time limit of send ping -> recv pong.
cancel, err := myPingu.BroadcastPingWithTicker(*ticker, 3*time.Second)
if err != nil {
  return err
}

Watch Pingu Working

// It's returns map[string]bool.
// Mapping string ip:port to health status.
fmt.Println(myPingu.PingTable())

table := myPingu.PingTable()
// true: target's Pingu is healthy
// false: target's Pingu is unhealthy
fmt.Println(table["127.0.0.1:8552"])

Controll the Pingu

myPingu.Stop()

// Continue previous BroadcastPingWithTicker if exist.
myPingu.Start()

// If you want stop the BroadcastPingWithTicker, close the 'cancel'.
cancel, _ := myPingu.BroadcastPingWithTicker(*ticker, 3*time.Second)
close(cancel)

Documentation

Index

• Constants
• func DefaultAddress() string
• func SuitablePack(b []byte, packet Packet) error
• func SuitableUnpack(packet Packet) ([]byte, error)
• type Config
  • func (c *Config) Default()
• type Packet
  • func ParsePacket(d []byte, sender *net.UDPAddr) (Packet, error)
• type PingPacket
  • func (p *PingPacket) Kind() byte
  • func (p *PingPacket) Sender() *net.UDPAddr
  • func (p *PingPacket) SetSender(s *net.UDPAddr)
• type Pingu
  • func NewPingu(rawAddr string, cfg *Config) (*Pingu, error)
  • func (p *Pingu) BroadcastPingWithTicker(ticker time.Ticker, timeout time.Duration) chan struct{}
  • func (p *Pingu) Close(cancels ...chan struct{}) error
  • func (p *Pingu) IsAlive(raw string) bool
  • func (p *Pingu) LocalAddr() net.Addr
  • func (p *Pingu) PingPong(addr *net.UDPAddr, timeout time.Duration) error
  • func (p *Pingu) PingPongWithRawAddr(raw string, timeout time.Duration) error
  • func (p *Pingu) PingTable() map[string]bool
  • func (p *Pingu) Pingus() []string
  • func (p *Pingu) Register(addr *net.UDPAddr)
  • func (p *Pingu) RegisterWithRawAddr(raw string) error
  • func (p *Pingu) RemoteAddr() net.Addr
  • func (p *Pingu) Start()
  • func (p *Pingu) Stop()
  • func (p *Pingu) Unregister(addr *net.UDPAddr)
  • func (p *Pingu) UnregisterWithRawAddr(raw string) error
• type PongPacket
  • func (p *PongPacket) Kind() byte
  • func (p *PongPacket) Sender() *net.UDPAddr
  • func (p *PongPacket) SetSender(s *net.UDPAddr)

Constants

const (
	Ping = iota
	Pong
)

const (
	PingType = 1 + iota

	MaxPacketSize = 4
)

const DefultRecvBufferSize = 256

Functions

func DefaultAddress

func DefaultAddress() string

func SuitablePack

func SuitablePack(b []byte, packet Packet) error

SuitablePack is the logic for parse the UDP Payload.

func SuitableUnpack

func SuitableUnpack(packet Packet) ([]byte, error)

SuitableUnpack is change Packet to suitable protocol message. If send message, you must use this method.

Types

type Config

type Config struct {
	RecvBufferSize int
	Verbose        bool
}

func (*Config) Default

func (c *Config) Default()

type Packet

type Packet interface {
	SetSender(s *net.UDPAddr)
	Sender() *net.UDPAddr
	Kind() byte
}

func ParsePacket

func ParsePacket(d []byte, sender *net.UDPAddr) (Packet, error)

ParsePacket parses packets received by other pingus.

type PingPacket

type PingPacket struct {
	// contains filtered or unexported fields
}

func (*PingPacket) Kind

func (p *PingPacket) Kind() byte

func (*PingPacket) Sender

func (p *PingPacket) Sender() *net.UDPAddr

func (*PingPacket) SetSender

func (p *PingPacket) SetSender(s *net.UDPAddr)

type Pingu

type Pingu struct {
	// contains filtered or unexported fields
}

func NewPingu

func NewPingu(rawAddr string, cfg *Config) (*Pingu, error)

Pingu is not accept double use to net.UDPConn. It's should only be used once. Generate net.UDPConn in NewPingu to avoid confusion.

func (*Pingu) BroadcastPingWithTicker

func (p *Pingu) BroadcastPingWithTicker(ticker time.Ticker, timeout time.Duration) chan struct{}

Send broadcast with ticker.

func (*Pingu) Close

func (p *Pingu) Close(cancels ...chan struct{}) error

Close is close the UDP connection and close cancel channels.

func (*Pingu) IsAlive

func (p *Pingu) IsAlive(raw string) bool

func (*Pingu) LocalAddr

func (p *Pingu) LocalAddr() net.Addr

func (*Pingu) PingPong

func (p *Pingu) PingPong(addr *net.UDPAddr, timeout time.Duration) error

PingPong sends a 'ping' and waits for a 'pong' to be received.

func (*Pingu) PingPongWithRawAddr

func (p *Pingu) PingPongWithRawAddr(raw string, timeout time.Duration) error

func (*Pingu) PingTable

func (p *Pingu) PingTable() map[string]bool

PingTable returns recently peer status map.

func (*Pingu) Pingus

func (p *Pingu) Pingus() []string

Pingus returns registered pingus's raw addresses.

func (*Pingu) Register

func (p *Pingu) Register(addr *net.UDPAddr)

Register is register to broadcast list that input address.

func (*Pingu) RegisterWithRawAddr

func (p *Pingu) RegisterWithRawAddr(raw string) error

func (*Pingu) RemoteAddr

func (p *Pingu) RemoteAddr() net.Addr

func (*Pingu) Start

func (p *Pingu) Start()

Start starts loop for controll the packets.

func (*Pingu) Stop

func (p *Pingu) Stop()

Stop stops the packet controll loop. If you stop the Pingu, it will clears the peer state map.

func (*Pingu) Unregister

func (p *Pingu) Unregister(addr *net.UDPAddr)

Unregister is remove input address from broadcast list.

func (*Pingu) UnregisterWithRawAddr

func (p *Pingu) UnregisterWithRawAddr(raw string) error

type PongPacket

type PongPacket struct {
	// contains filtered or unexported fields
}

func (*PongPacket) Kind

func (p *PongPacket) Kind() byte

func (*PongPacket) Sender

func (p *PongPacket) Sender() *net.UDPAddr

func (*PongPacket) SetSender

func (p *PongPacket) SetSender(s *net.UDPAddr)