README
¶
Herein lies the definition of the objects that will be passed around.
Your basic Connect, Subscribe, Publish kid of objects (or types since this is Go).
They will have fields and virtual methods and will have to marshal and un-marshal. There are many fine library's available for marshalling, or serializing, these objects and in the meantime we're serializing everything as a unique character followed by an array of byte arrays.
The players are:
-
Connect is the first packet received. Will contain a credential
-
Disconnect is the last packet received.
-
Subscribe contains a string ([]byte really) with a channel name, or topic, or address, or source address or domain name. Whatever you want to call it.
-
Unsubscribe reverses what Subscribe did.
-
Lookup will return options set during the Subscribe (like an IPv6 address) and also whether anything is subscribed to this channel.
-
Send sends a message or payload (a byte array) to another channel, or topic, or destination address.
The serialization can be read in the code (packets.go)
There is a particular String() format that I like for debugging this. See packets_test.go
eg: A Send looks like this [P,dest,source,some_data] which would be better json if the quote marks weren't missing.
There will be more description of these structs later.
#TODO: finish the code coverage past 93.7% #TODO: formalize/finalize the marshaling.
FromString constructs san AddressType from an incoming string.
String is for display purposes only
ToBytes makes a parsable 'string'
EnsureAddressIsBinary converts all the address formats to binary
Documentation
¶
Overview ¶
Package packets comments. TODO: package comments for these packets.
Index ¶
- Constants
- func ReadArrayOfByteArray(reader io.Reader) ([][]byte, error)
- func ReadVarLenInt(reader io.Reader) (int, error)
- func UniversalToJSON(str *Universal) ([]byte, error)
- func WriteArrayOfByteArray(args [][]byte, writer io.Writer) error
- func WriteVarLenInt(uintvalue uint32, mask uint8, writer io.Writer) error
- type AddressType
- type AddressUnion
- type CommandType
- type Connect
- type Disconnect
- type Interface
- type Lookup
- type MessageCommon
- type PacketCommon
- func (p *PacketCommon) DeleteOption(key string)
- func (p *PacketCommon) GetIPV6Option() []byte
- func (p *PacketCommon) GetOption(key string) ([]byte, bool)
- func (p *PacketCommon) GetOptionKeys() ([]string, [][]byte)
- func (p *PacketCommon) OptionSize() int
- func (p *PacketCommon) SetOption(key string, val []byte)
- type Ping
- type Send
- type Subscribe
- type Universal
- type Unsubscribe
Constants ¶
const ( // BinaryAddress is whan an AddressUnion is 24 bytes of bits BinaryAddress = AddressType(0) // HexAddress is whan an AddressUnion is 48 bytes of hex bytes HexAddress = AddressType('$') // Base64Address is whan an AddressUnion is 32 bytes of base64 bytes Base64Address = AddressType('=') // Utf8Address is whan an AddressUnion is a utf-8 bytes. The default Utf8Address = AddressType(' ') )
const HashTypeLen int = 24
HashTypeLen must be the same as iot.HashTypeLen
Variables ¶
This section is empty.
Functions ¶
func ReadArrayOfByteArray ¶
ReadArrayOfByteArray to read an array of byte arrays
func ReadVarLenInt ¶
ReadVarLenInt see comments above Not meant for integers >= 2^28 big endian
func UniversalToJSON ¶
UniversalToJSON outputs an array of strings. in a bad json like syntax. It's just for debugging. It should be parseable by badjson. some of the strings start with \0 and must be converted
func WriteArrayOfByteArray ¶
WriteArrayOfByteArray write count then lengths and then bytes
func WriteVarLenInt ¶
WriteVarLenInt writes a variable length integer. bigendian I'm sure there's a name for this but I forget. Unsigned integers are written big end first 7 bits at at time. The last byte is >=0 and <=127. The other bytes have the high bit set. Small values use one byte. A version of this without recursion would be better. todo:
Types ¶
type AddressUnion ¶
type AddressUnion struct {
Type AddressType // AddressType
Bytes []byte // ' ' or '$' or '=' or 0
}
AddressUnion is one byte followed by more bytes. is either utf-8 of an address, or it is a coded version of HashTypeLen bytes coding: space followed by utf8 glyphs $ followed by exactly 48 bytes of hex = followed by exactly 32 bytes of base64 \0 followed by exactly 24 bytes of binary
func NewAddressUnion ¶
func NewAddressUnion(str string) AddressUnion
NewAddressUnion is for constructing utf-8 AddressUnion
func (*AddressUnion) EnsureAddressIsBinary ¶
func (address *AddressUnion) EnsureAddressIsBinary()
EnsureAddressIsBinary looks at the type and then changes the address as necessary to be BinaryAddress if the $ and = types are malformed then it all gets hashed as if it were a string in the first place. parsers should screen for bad cases
func (*AddressUnion) FromBytes ¶
func (address *AddressUnion) FromBytes(bytes []byte)
FromBytes will construct an AddressUnion from a string we check the first byte for encoding type else assume it's a string
func (*AddressUnion) FromString ¶
func (address *AddressUnion) FromString(bytes string)
FromString will construct an AddressUnion from a string we check the first byte for encoding type else assume it's a string
func (*AddressUnion) String ¶
func (address *AddressUnion) String() string
ToString is for display purposes. It will need to convert the binary type to base64
func (*AddressUnion) ToBytes ¶
func (address *AddressUnion) ToBytes() []byte
ToBytes simply concates the Type and the Bytes The utf-8 types will NOT end up with a space at the start is it better to just alloc the bytes?
type Connect ¶
type Connect struct {
PacketCommon
}
Connect is the first message Usually the options have a JWT with permissions.
type Disconnect ¶
type Disconnect struct {
PacketCommon
}
Disconnect is the last thing a client will hear. May contain a string in options["error"] A client can also send this to server.
func (*Disconnect) Fill ¶
func (p *Disconnect) Fill(str *Universal) error
Fill implements the 2nd part of an unmarshal.
func (*Disconnect) String ¶
func (p *Disconnect) String() string
type Interface ¶
type Interface interface {
//
Write(writer io.Writer) error // write to Universal and then to writer
Fill(*Universal) error // init myself from a Universal that was just read
//
ToJSON() ([]byte, error) // for debugging and String() etc.
String() string
GetOption(key string) ([]byte, bool)
GetOptionKeys() ([]string, [][]byte)
}
Interface is virtual functions for all packets. Basically odd versions of marshal and unmarshal.
func FillPacket ¶
FillPacket construct a packet from supplied Universal
type Lookup ¶
type Lookup struct {
MessageCommon
// a return address
Source AddressUnion
}
Lookup returns information on the dest to source. can be used to verify existance of an endpoint prior to subscribe. If the topic metadata has one subscriber and an ipv6 address then this is the same as a dns lookup.
type MessageCommon ¶
type MessageCommon struct {
PacketCommon
// aka destination address aka channel aka topic.
Address AddressUnion
}
MessageCommon is
type PacketCommon ¶
type PacketCommon struct {
// contains filtered or unexported fields
}
PacketCommon is stuff the packets all have, like options.
func (*PacketCommon) DeleteOption ¶
func (p *PacketCommon) DeleteOption(key string)
DeleteOption returns the value,true to go with the key or nil,false
func (*PacketCommon) GetIPV6Option ¶
func (p *PacketCommon) GetIPV6Option() []byte
GetIPV6Option is an example of using options
func (*PacketCommon) GetOption ¶
func (p *PacketCommon) GetOption(key string) ([]byte, bool)
GetOption returns the value,true to go with the key or nil,false
func (*PacketCommon) GetOptionKeys ¶
func (p *PacketCommon) GetOptionKeys() ([]string, [][]byte)
GetOptionKeys returns a slice of strings
func (*PacketCommon) OptionSize ¶
func (p *PacketCommon) OptionSize() int
OptionSize returns key count which is same as value count
func (*PacketCommon) SetOption ¶
func (p *PacketCommon) SetOption(key string, val []byte)
SetOption adds the key,value
type Ping ¶
type Ping struct {
PacketCommon
}
Ping is a utility. Aka Heartbeat.
type Send ¶
type Send struct {
MessageCommon // address
// a return address. Required.
Source AddressUnion
Payload []byte
}
Send aka 'publish' aka 'push' sends Payload (and the options) to destination aka Address.
type Subscribe ¶
type Subscribe struct {
MessageCommon
}
Subscribe is to declare that the Thing has an address. Presumably one would Subscribe before a Send.
type Universal ¶
type Universal struct {
Cmd CommandType
Args [][]byte
}
Universal is the wire representation. they can all be represented this way.
func ReadUniversal ¶
ReadUniversal reads a Universal packet.
type Unsubscribe ¶
type Unsubscribe struct {
MessageCommon
}
Unsubscribe might prevent future reception at the indicated destination address.
func (*Unsubscribe) Fill ¶
func (p *Unsubscribe) Fill(str *Universal) error
Fill implements the 2nd part of an unmarshal.
func (*Unsubscribe) String ¶
func (p *Unsubscribe) String() string
func (*Unsubscribe) ToJSON ¶
func (p *Unsubscribe) ToJSON() ([]byte, error)
ToJSON is something that wastes memory.
Source Files