m3ua

README

go-m3ua

Simple M3UA protocol implementation in pure Golang.

Quickstart

Installation

This project supports Go Modules. So you don't need to get dependent packages manually if you are using Go 1.11+ and GO111MODULE is set to on.

Otherwise, the following packages should be installed manually.

go get -u github.com/pkg/errors
go get -u github.com/ishidawataru/sctp
go get -u github.com/google/go-cmp/cmp
go get -u github.com/pascaldekloe/goe/verify
go get -u github.com/Amrrx/go-m3ua

*Non-Linux machine is NOT supported, as this package relies much on github.com/ishidawataru/sctp.

Trying Examples

Working examples are available in examples directory. Just executing the following commands, you can see the client and server setting up M3UA connection.

# Run Server first
cd examples/server
go run m3ua-server.go

// Run Client then
cd examples/client
go run m3ua-client.go

For Developers

The API design is kept as similar as possible to other protocols in standard net package. To establish M3UA connection as client/server, you can use Dial() and Listen()/Accept() without caring about the underlying SCTP association, as go-m3ua handles it together with M3UA ASPSM & ASPTM procedures.

Here is an example to develop your own M3UA client using go-m3ua.

First, you need to create *Config used to setup/maintain M3UA connection.

config := m3ua.NewClientConfig(
    &m3ua.HeartbeatInfo{
        Enabled:  true,
        Interval: time.Duration(3 * time.Second),
        Timer:    time.Duration(10 * time.Second),
    },
    0x11111111, // OriginatingPointCode
    0x22222222, // DestinationPointCode
    1,          // AspIdentifier
    params.TrafficModeLoadshare, // TrafficModeType
    0,                     // NetworkAppearance
    0,                     // CorrelationID
    []uint32{1, 2},        // RoutingContexts
    params.ServiceIndSCCP, // ServiceIndicator
    0, // NetworkIndicator
    0, // MessagePriority
    1, // SignalingLinkSelection
)
// set nil on unnecessary paramters.
config.CorrelationID = nil

Then, prepare network addresses and context and try to connect with Dial().

// setup SCTP peer on the specified IPs and Port.
raddr, err := sctp.ResolveSCTPAddr("sctp", SERVER_IPS)
if err != nil {
    log.Fatal(err)
}

ctx := context.Background()
ctx, cancel := context.WithCancel(ctx)
defer cancel()

conn, err := m3ua.Dial(ctx, "m3ua", nil, raddr, config)
if err != nil {
    log.Fatalf("Failed to dial M3UA: %s", err)
}
defer conn.Close()

Now you can Read() / Write() data from/to the remote endpoint.

if _, err := conn.Write(d); err != nil {
    log.Fatalf("Failed to write M3UA data: %s", err)
}
log.Printf("Successfully sent M3UA data: %x", d)

buf := make([]byte, 1500)
n, err := conn.Read(buf)
if err != nil {
    log.Fatal(err)
}

log.Printf("Successfully read M3UA data: %x", buf[:n])

See example/server directory for server example.

Supported Features

Messages

Class	Message	Supported	Notes
Transfer	Payload Data Message (DATA)	Yes	RFC4666#3.3
SSNM	Destination Unavailable (DUNA)	Yes	RFC4666#3.4
	Destination Available (DAVA)	Yes
	Destination State Audit (DAUD)	Yes
	Signalling Congestion (SCON)	Yes
	Destination User Part Unavailable (DUPU)	Yes
	Destination Restricted (DRST)	Yes
ASPSM	ASP Up	Yes	RFC4666#3.5
	ASP Up Acknowledgement (ASP Up Ack)	Yes
	ASP Down	Yes
	ASP Down Acknowledgement (ASP Down Ack)	Yes
	Heartbeat (BEAT)	Yes
	Heartbeat Acknowledgement (BEAT Ack)	Yes
RKM	Registration Request (REG REQ)		RFC4666#3.6
	Registration Response (REG RSP)
	Deregistration Request (DEREG REQ)
	Deregistration Response (DEREG RSP)
ASPTM	ASP Active	Yes	RFC4666#3.7
	ASP Active Acknowledgement (ASP Active Ack)	Yes
	ASP Inactive	Yes
	ASP Inactive Acknowledgement (ASP Inactive Ack)	Yes
MGMT	Error	Yes	RFC4666#3.8
	Notify	Yes

Parameters

Type	Parameters	Supported	Notes
Common	INFO String	Yes
	Routing Context	Yes
	Diagnostic Information	Yes
	Heartbeat Data	Yes
	Traffic Mode Type	Yes
	Error Code	Yes
	Status	Yes
	ASP Identifier	Yes
M3UA-specific	Network Appearance	Yes
	User/Cause	Yes
	Congestion Indications	Yes
	Concerned Destination	Yes
	Routing Key	Yes
	Registration Result	Yes
	Deregistration Result	Yes
	Local Routing Key Identifier	Yes
	Destination Point Code	Yes
	Service Indicators	Yes
	Originating Point Code List	Yes
	Protocol Data	Yes
	Registration Status	Yes
	Deregistration Status	Yes

Disclaimer

This is still experimental project. In some part, the behavior is not fully compliant with RFC, and some of the features are not even implemented yet.

Also note that some exported APIs may be changed without notice before first release.

Author

Yoshiyuki Kurauchi (My Website / Twitter)

LICENSE

MIT

Documentation

Overview

Package m3ua provides easy and painless handling of M3UA protocol in pure Golang.

The API design is kept as similar as possible to other protocols in standard net package. To establish M3UA connection as client/server, you can use Dial() and Listen() / Accept() without caring about the underlying SCTP association, as go-m3ua handles it together with M3UA ASPSM & ASPTM procedures.

This package relies much on github.com/ishidawataru/sctp, as M3UA requires underlying SCTP connection,

Specification: https://tools.ietf.org/html/rfc4666

Index

• Constants
• Variables
• func FormatPC(pc uint32, format PCFormat) string
• func ParsePC(pc string, format PCFormat) uint32
• type Config
  • func NewClientConfig(hbInfo *HeartbeatInfo, opc, dpc, aspID, tmt, nwApr, corrID uint32, ...) *Config
  • func NewConfig(opc, dpc uint32, si, ni, mp, sls uint8) *Config
  • func NewServerConfig(hbInfo *HeartbeatInfo, opc, dpc, aspID, tmt, nwApr, corrID uint32, ...) *Config
  • func (c *Config) EnableHeartbeat(interval, timer time.Duration) *Config
  • func (c *Config) SetAspIdentifier(id uint32) *Config
  • func (c *Config) SetCorrelationID(id uint32) *Config
  • func (c *Config) SetNetworkAppearance(nwApr uint32) *Config
  • func (c *Config) SetRoutingContexts(rtCtxs ...uint32) *Config
  • func (c *Config) SetTrafficModeType(tmType uint32) *Config
• type Conn
  • func Dial(ctx context.Context, net string, laddr, raddr *sctp.SCTPAddr, cfg *Config) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(b []byte) (n int, err error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) State() State
  • func (c *Conn) Write(b []byte) (n int, err error)
  • func (c *Conn) WriteSignal(m3 messages.M3UA) (n int, err error)
• type ErrAspIDRequired
  • func NewErrAspIDRequired() *ErrAspIDRequired
  • func (e *ErrAspIDRequired) Error() string
• type ErrInvalidSCTPStreamID
  • func NewErrInvalidSCTPStreamID(id uint16) *ErrInvalidSCTPStreamID
  • func (e *ErrInvalidSCTPStreamID) Error() string
• type ErrInvalidVersion
  • func NewErrInvalidVersion(ver uint8) *ErrInvalidVersion
  • func (e *ErrInvalidVersion) Error() string
• type ErrUnexpectedMessage
  • func NewErrUnexpectedMessage(msg messages.M3UA) *ErrUnexpectedMessage
  • func (e *ErrUnexpectedMessage) Error() string
• type ErrUnsupportedClass
  • func NewErrUnsupportedClass(msg messages.M3UA) *ErrUnsupportedClass
  • func (e *ErrUnsupportedClass) Error() string
• type ErrUnsupportedMessage
  • func NewErrUnsupportedMessage(msg messages.M3UA) *ErrUnsupportedMessage
  • func (e *ErrUnsupportedMessage) Error() string
• type HeartbeatInfo
  • func NewHeartbeatInfo(interval, timer time.Duration, data []byte) *HeartbeatInfo
• type Listener
  • func Listen(net string, laddr *sctp.SCTPAddr, cfg *Config) (*Listener, error)
  • func (l *Listener) Accept(ctx context.Context) (*Conn, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
• type PCFormat
• type State

Constants

const (
	PCFormat3_2_3 = "3-2-3"
)

PointCode Format definitions.

NOT IMPLEMENTED YET!

Variables

var (
	ErrSCTPNotAlive        = errors.New("SCTP is no longer alive")
	ErrInvalidState        = errors.New("invalid state")
	ErrNotEstablished      = errors.New("M3UA Conn not established")
	ErrFailedToEstablish   = errors.New("failed to establish M3UA Conn")
	ErrTimeout             = errors.New("timed out")
	ErrHeartbeatExpired    = errors.New("heartbeat timer expired")
	ErrFailedToPeelOff     = errors.New("failed to peel off Protocol Data")
	ErrFailedToWriteSignal = errors.New("failed to write signal")
)

Error definitions.

Functions

func FormatPC

func FormatPC(pc uint32, format PCFormat) string

FormatPC formats decimal(uint32) PointCode as given format.

NOT IMPLEMENTED YET!

func ParsePC

func ParsePC(pc string, format PCFormat) uint32

ParsePC parses formatted PointCode as uint32.

NOT IMPLEMENTED YET!

Types

type Config

type Config struct {
	*HeartbeatInfo
	AspIdentifier          *params.Param
	TrafficModeType        *params.Param
	NetworkAppearance      *params.Param
	RoutingContexts        *params.Param
	CorrelationID          *params.Param
	OriginatingPointCode   uint32
	DestinationPointCode   uint32
	ServiceIndicator       uint8
	NetworkIndicator       uint8
	MessagePriority        uint8
	SignalingLinkSelection uint8
}

Config is a configration that defines a M3UA server.

func NewClientConfig

func NewClientConfig(hbInfo *HeartbeatInfo, opc, dpc, aspID, tmt, nwApr, corrID uint32, rtCtxs []uint32, si, ni, mp, sls uint8) *Config

NewClientConfig creates a new Config for Client.

The optional parameters that is not required (like CorrelationID) can be omitted by setting it to nil after created *Config.

func NewConfig

func NewConfig(opc, dpc uint32, si, ni, mp, sls uint8) *Config

NewConfig creates a new Config.

To set additional parameters, use constructors in param package or setters defined in this package. Note that the params left nil won't appear in the packets but the initialized params will, with zero values.

func NewServerConfig

func NewServerConfig(hbInfo *HeartbeatInfo, opc, dpc, aspID, tmt, nwApr, corrID uint32, rtCtxs []uint32, si, ni, mp, sls uint8) *Config

NewServerConfig creates a new Config for Server.

The optional parameters that is not required (like CorrelationID) can be omitted by setting it to nil after created *Config.

func (*Config) EnableHeartbeat

func (c *Config) EnableHeartbeat(interval, timer time.Duration) *Config

EnableHeartbeat enables M3UA BEAT with interval and expiration timer given.

The data is hard-coded by default. Manipulate the exported field Config.HeartbeatInfo.Data to customize it such as including current time to identify the BEAT and BEAT ACK pair.

func (*Config) SetAspIdentifier

func (c *Config) SetAspIdentifier(id uint32) *Config

SetAspIdentifier sets AspIdentifier in Config.

func (*Config) SetCorrelationID

func (c *Config) SetCorrelationID(id uint32) *Config

SetCorrelationID sets CorrelationID in Config.

func (*Config) SetNetworkAppearance

func (c *Config) SetNetworkAppearance(nwApr uint32) *Config

SetNetworkAppearance sets NetworkAppearance in Config.

func (*Config) SetRoutingContexts

func (c *Config) SetRoutingContexts(rtCtxs ...uint32) *Config

SetRoutingContexts sets RoutingContexts in Config.

func (*Config) SetTrafficModeType

func (c *Config) SetTrafficModeType(tmType uint32) *Config

SetTrafficModeType sets TrafficModeType in Config.

type Conn

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

Conn represents a M3UA connection, which satisfies standard net.Conn interface.

func Dial

func Dial(ctx context.Context, net string, laddr, raddr *sctp.SCTPAddr, cfg *Config) (*Conn, error)

Dial establishes a M3UA connection as a client.

After successfully established the connection with peer, state-changing signals and heartbeats are automatically handled background in another goroutine.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*Conn) Read

func (c *Conn) Read(b []byte) (n int, err error)

Read reads data from the connection.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls.

func (*Conn) State

func (c *Conn) State() State

State returns current state of Conn.

func (*Conn) Write

func (c *Conn) Write(b []byte) (n int, err error)

Write writes data to the connection.

func (*Conn) WriteSignal

func (c *Conn) WriteSignal(m3 messages.M3UA) (n int, err error)

WriteSignal writes any type of M3UA signals on top of SCTP Connection.

type ErrAspIDRequired

type ErrAspIDRequired struct{}

ErrAspIDRequired is used by an SGP in response to an ASP Up message that does not contain an ASP Identifier parameter when the SGP requires one..

func NewErrAspIDRequired

func NewErrAspIDRequired() *ErrAspIDRequired

NewErrAspIDRequired creates ErrAspIDRequired

func (*ErrAspIDRequired) Error

func (e *ErrAspIDRequired) Error() string

Error returns error string.

type ErrInvalidSCTPStreamID

type ErrInvalidSCTPStreamID struct {
	ID uint16
}

ErrInvalidSCTPStreamID is used if a message is received on an unexpected SCTP stream.

func NewErrInvalidSCTPStreamID

func NewErrInvalidSCTPStreamID(id uint16) *ErrInvalidSCTPStreamID

NewErrInvalidSCTPStreamID creates ErrInvalidSCTPStreamID

func (*ErrInvalidSCTPStreamID) Error

func (e *ErrInvalidSCTPStreamID) Error() string

Error returns error string with violating stream ID.

type ErrInvalidVersion

type ErrInvalidVersion struct {
	Ver uint8
}

ErrInvalidVersion is used if a message with an unsupported version is received.

func NewErrInvalidVersion

func NewErrInvalidVersion(ver uint8) *ErrInvalidVersion

NewErrInvalidVersion creates ErrInvalidVersion.

func (*ErrInvalidVersion) Error

func (e *ErrInvalidVersion) Error() string

Error returns error string with violating version.

type ErrUnexpectedMessage

type ErrUnexpectedMessage struct {
	Msg messages.M3UA
}

ErrUnexpectedMessage is used if a defined and recognized message is received that is not expected in the current state (in some cases, the ASP may optionally silently discard the message and not send an Error message).

func NewErrUnexpectedMessage

func NewErrUnexpectedMessage(msg messages.M3UA) *ErrUnexpectedMessage

NewErrUnexpectedMessage creates ErrUnexpectedMessage

func (*ErrUnexpectedMessage) Error

func (e *ErrUnexpectedMessage) Error() string

Error returns error string with message class and type.

type ErrUnsupportedClass

type ErrUnsupportedClass struct {
	Msg messages.M3UA
}

ErrUnsupportedClass is used if a message with an unexpected or unsupported Message Class is received.

func NewErrUnsupportedClass

func NewErrUnsupportedClass(msg messages.M3UA) *ErrUnsupportedClass

NewErrUnsupportedClass creates ErrUnsupportedClass

func (*ErrUnsupportedClass) Error

func (e *ErrUnsupportedClass) Error() string

Error returns error string with message class.

type ErrUnsupportedMessage

type ErrUnsupportedMessage struct {
	Msg messages.M3UA
}

ErrUnsupportedMessage is used if a message with an unexpected or unsupported Message Type is received.

func NewErrUnsupportedMessage

func NewErrUnsupportedMessage(msg messages.M3UA) *ErrUnsupportedMessage

NewErrUnsupportedMessage creates ErrUnsupportedMessage

func (*ErrUnsupportedMessage) Error

func (e *ErrUnsupportedMessage) Error() string

Error returns error string with message class and type.

type HeartbeatInfo

type HeartbeatInfo struct {
	Enabled  bool
	Interval time.Duration
	Timer    time.Duration
	Data     []byte
}

HeartbeatInfo is a set of information for M3UA BEAT.

func NewHeartbeatInfo

func NewHeartbeatInfo(interval, timer time.Duration, data []byte) *HeartbeatInfo

NewHeartbeatInfo creates a new HeartbeatInfo.

type Listener

type Listener struct {
	*Config
	// contains filtered or unexported fields
}

Listener is a M3UA listener.

func Listen

func Listen(net string, laddr *sctp.SCTPAddr, cfg *Config) (*Listener, error)

Listen returns a M3UA listener.

func (*Listener) Accept

func (l *Listener) Accept(ctx context.Context) (*Conn, error)

Accept waits for and returns the next connection to the listener. After successfully established the association with peer, Payload can be read with Read() func. Other signals are automatically handled background in another goroutine.

func (*Listener) Addr

func (l *Listener) Addr() net.Addr

Addr returns the listener's network address.

func (*Listener) Close

func (l *Listener) Close() error

Close closes the listener.

type PCFormat

type PCFormat string

PCFormat represents the format of PointCode.

NOT IMPLEMENTED YET!

type State

type State uint8

State represents ASP State.

const (
	StateAspDown State = iota
	StateAspInactive
	StateAspActive
	StateSCTPCDI
	StateSCTPRI
)

M3UA status definitions.