m3ua

package module
v0.0.0-...-1c86a79 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2022 License: MIT Imports: 11 Imported by: 2

README

go-m3ua

Simple M3UA protocol implementation in pure Golang.

CircleCI GolangCI GoDoc GitHub

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

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

PointCode Format definitions.

NOT IMPLEMENTED YET!

Variables

View Source
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.

Directories

Path Synopsis
examples
client
Command m3ua-client works as M3UA client.
Command m3ua-client works as M3UA client.
server
Command m3ua-server works as M3UA server.
Command m3ua-server works as M3UA server.
Package messages provides protocol definitions and encoding/decoding feature of M3UA messages.
Package messages provides protocol definitions and encoding/decoding feature of M3UA messages.
params
Package params provides the protocol definition and encoding/decoding feature of M3UA Common Paratemeters and M3UA-specific parameters.
Package params provides the protocol definition and encoding/decoding feature of M3UA Common Paratemeters and M3UA-specific parameters.
Package pc provides Point Code converting from some variants and translation to IP.
Package pc provides Point Code converting from some variants and translation to IP.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL