gerte

README

GERTe Golang API

For more information on GERTe see the GERT Repo

Documentation

Overview

Package gerte provides an api for the GERT system. More info: https://github.com/GlobalEmpire/GERT

Index

• Constants
• func PrettyPrint(data []byte) (string, error)
• type Api
  • func NewApi(ver Version) *Api
  • func (api *Api) Parse() (Command, error)
  • func (api *Api) Register(addr GertAddress, key string) (bool, error)
  • func (api *Api) Shutdown() error
  • func (api *Api) Startup(c net.Conn) error
  • func (api *Api) Transmit(pkt Packet) (bool, error)
• type Command
  • func CommandFromBytes(data []byte) (Command, error)
  • func (cmd Command) PrintCommand() (string, error)
• type GERTc
  • func GertCFromBytes(data []byte) GERTc
  • func (addr GERTc) PrintGERTc() string
  • func (addr GERTc) ToBytes() []byte
• type GertAddress
  • func AddressFromBytes(data []byte) GertAddress
  • func AddressFromString(addr string) (GertAddress, error)
  • func (addr GertAddress) PrintAddress() string
  • func (addr GertAddress) ToBytes() []byte
• type GertCommand
• type GertError
  • func (error GertError) PrintError() (string, error)
• type GertStatus
• type Packet
  • func PacketFromBytes(data []byte) (Packet, error)
  • func (pkt Packet) PrintPacket() string
  • func (pkt Packet) ToBytes() ([]byte, error)
• type Status
  • func StatusFromBytes(data []byte) (Status, error)
  • func (status Status) PrintStatus() (string, error)
• type Version
  • func VersionFromBytes(b []byte) Version
  • func (ver Version) PrintVersion() string
  • func (ver Version) ToBytes() []byte

Constants

const (
	// CommandState is used by relays to indicate result of a command to a gateway and by gateways to request the state.
	CommandState GertCommand = 0
	// CommandRegister claims an address for this gateway using a key.
	CommandRegister GertCommand = 1
	// CommandData transmits data from a GERTi address to a GERTc address.
	CommandData GertCommand = 2
	// CommandClose gracefully closes a connection to a relay.
	CommandClose GertCommand = 3

	// StateFailure is the initial gateway state.
	// Should be changed upon negotiation.
	// Also a response to failed commands with an error
	StateFailure GertStatus = 0
	// StateConnected indicates that the Gateway is connected to a relay, no other action has been taken
	StateConnected GertStatus = 1
	// StateAssigned indicates that the Gateway has successfully claimed an address.
	// Used as a response to the REGISTER command.
	StateAssigned GertStatus = 2
	// StateClosed indicates that the Gateway has closed the connection.
	// Used as a response to the CLOSE command.
	StateClosed GertStatus = 3
	// StateSent indicates that the Data has been successfully sent.
	// Used as a response to the DATA command.
	// This is not a guarantee for data that has to be sent to another peer, although it's unlikely to be incorrect.
	StateSent GertStatus = 4

	// ErrorVersion indicates that an incompatible version was used during negotiation.
	ErrorVersion GertError = 0
	// ErrorBadKey indicates that the Key did not match that used for the requested address.
	// Requested address may not exist
	ErrorBadKey GertError = 1
	// ErrorAlreadyRegistered indicates that Registration has already been performed successfully
	ErrorAlreadyRegistered GertError = 2
	// ErrorNotRegistered indicates that the Gateway hasn't been registered yet.
	// The gateway cannot send data before claiming an address
	ErrorNotRegistered GertError = 3
	// ErrorNoRoute indicates that Data failed to send because the remote gateway couldn't be found
	ErrorNoRoute GertError = 4
	// ErrorAddressTaken indicates that the Address request has already been claimed
	ErrorAddressTaken GertError = 5
)

Functions

func PrettyPrint

func PrettyPrint(data []byte) (string, error)

PrettyPrint prints a GERT Message into a human readable string

Types

type Api

type Api struct {
	Registered bool
	Address    GertAddress
	Version    Version
	// contains filtered or unexported fields
}

Api is used to perform GERTe API Operations

func NewApi

func NewApi(ver Version) *Api

NewApi is the constructor for Api, it assigns the Version

func (*Api) Parse

func (api *Api) Parse() (Command, error)

Parse reads data from the GERTe socket and parses it. It returns the received Command and any errors encountered. The official API only checks the connection for data when requested. This includes connection closures from the relay. If the connection is closed, the API will call the error function instead of returning anything.

func (*Api) Register

func (api *Api) Register(addr GertAddress, key string) (bool, error)

Register registers the GERTe client on the GERTe address with the associated 20 byte key. It returns a bool whether the registration was successful and any encountered errors. All gateways must register themselves with a valid GERTe address and key before sending data. The API does not track if it is registered nor what address it has registered, it instead relies on the relay it is connected to.

func (*Api) Shutdown

func (api *Api) Shutdown() error

Shutdown Gracefully closes the GERTe Socket. It returns any errors encountered. The official API prefers using a safe shutdown procedure, although the GEDS servers should be more than stable enough to survive any number of unclean shutdowns.

func (*Api) Startup

func (api *Api) Startup(c net.Conn) error

Startup initializes the API. It returns any encountered errors. Initializing the API is incredibly simple. The API should be initialized for every program when it decides to use it (although it is potentially already initialized, the API will ensure it's safe to initialize.)

func (*Api) Transmit

func (api *Api) Transmit(pkt Packet) (bool, error)

Transmit sends data to the target Address. It returns a bool whether the operation was successful and any encountered errors. The official API only allows transmissions from GERTi to GERTi via GERTe. his means that a GERTi address must be provided for each endpoint in a message.

type Command

type Command struct {
	Command GertCommand
	Packet  Packet
	Status  Status
}

Command is the Parsed Data returned from Api.Parse

func CommandFromBytes

func CommandFromBytes(data []byte) (Command, error)

CommandFromBytes parses bytes to a GERT Command

func (Command) PrintCommand

func (cmd Command) PrintCommand() (string, error)

PrintCommand prints a GERT Command to a Human-readable string

type GERTc

type GERTc struct {
	GERTe GertAddress
	GERTi GertAddress
}

GERTc is a 6 byte GERTc Address

func GertCFromBytes

func GertCFromBytes(data []byte) GERTc

GertCFromBytes parses bytes to a GERTc Address

func (GERTc) PrintGERTc

func (addr GERTc) PrintGERTc() string

PrintGERTc prints a GERTc Address as a string

func (GERTc) ToBytes

func (addr GERTc) ToBytes() []byte

ToBytes converts a GERTc to bytes for sending

type GertAddress

type GertAddress struct {
	Upper int
	Lower int
}

GertAddress is a 3 byte address used as a GERTe/i Address

func AddressFromBytes

func AddressFromBytes(data []byte) GertAddress

AddressFromBytes parses bytes to a GERT Address

func AddressFromString

func AddressFromString(addr string) (GertAddress, error)

AddressFromString converts a string with an address in the format "XXXX.YYYY" into the corresponding GertAddress. It returns the GertAddress and any encountered errors.

func (GertAddress) PrintAddress

func (addr GertAddress) PrintAddress() string

PrintAddress prints a GertAddress as a string

func (GertAddress) ToBytes

func (addr GertAddress) ToBytes() []byte

ToBytes converts a GERT Address to bytes for sending

type GertCommand

type GertCommand byte

GertCommand indicates the Command of a Request

type GertError

type GertError byte

GertError is the Error Code in a "Failed" Status

func (GertError) PrintError

func (error GertError) PrintError() (string, error)

PrintError prints a GERT Error to a Human-readable string

type GertStatus

type GertStatus byte

GertStatus indicates the Status from a Status Command

type Packet

type Packet struct {
	Source GERTc
	Target GERTc
	Data   []byte
}

Packet is the Parsed Data returned from Api.Parse for a Data Command

func PacketFromBytes

func PacketFromBytes(data []byte) (Packet, error)

PacketFromBytes parses bytes to a GERT Packet

func (Packet) PrintPacket

func (pkt Packet) PrintPacket() string

PrintPacket prints a GERT Packet to a Human-readable string

func (Packet) ToBytes

func (pkt Packet) ToBytes() ([]byte, error)

ToBytes converts a Packet to bytes for sending

type Status

type Status struct {
	Status  GertStatus
	Size    byte
	Error   GertError
	Version Version
}

Status is the Parsed Status returned from Api.Parse for a Status Command

func StatusFromBytes

func StatusFromBytes(data []byte) (Status, error)

StatusFromBytes parses bytes to a GERT Status

func (Status) PrintStatus

func (status Status) PrintStatus() (string, error)

PrintStatus prints a GERT Status to a Human-readable string

type Version

type Version struct {
	Major byte
	Minor byte
	Patch byte
}

Version is the Version used by the Connected Status

func VersionFromBytes

func VersionFromBytes(b []byte) Version

VersionFromBytes parses bytes to a GERT Version

func (Version) PrintVersion

func (ver Version) PrintVersion() string

PrintVersion prints a GERT Version to a Human-readable string

func (Version) ToBytes

func (ver Version) ToBytes() []byte

ToBytes converts a GERT Version to bytes for sending