connection

Documentation

Index

• Variables
• func AddMessageHeader(message Message)
• func DiscardToSync(conn net.Conn) error
• func InitializeDefaultMessage(message Message)
• func ReceiveBruteForceMatches(conn net.Conn) ([][]Message, error)
• func ReceiveInto[T Message](conn net.Conn, message T) (out T, err error)
• func Send(conn net.Conn, message Message) error
• type Field
  • func (f *Field) Copy() *Field
• type FieldFlags
• type FieldGroup
• type FieldType
• type Message
  • func Receive(conn net.Conn) (Message, error)
  • func ReceiveIntoAny(conn net.Conn, messages ...Message) ([]Message, error)
• type MessageFormat
  • func (m MessageFormat) Copy() MessageFormat
  • func (m MessageFormat) Field(name string) MessageWriter
  • func (m MessageFormat) MatchesStructure(otherMessage MessageFormat) error
  • func (m MessageFormat) String() string
• type MessageWriter
  • func (mw MessageWriter) Child(name string, position int) MessageWriter
  • func (mw MessageWriter) Get() (any, error)
  • func (mw MessageWriter) MustGet() any
  • func (mw MessageWriter) MustWrite(value any)
  • func (mw MessageWriter) Write(value any) error

Variables

var BufferSize = 2048

Functions

func AddMessageHeader

func AddMessageHeader(message Message)

AddMessageHeader adds the given Message's header. This also ensures that each header is unique. This should be called in an init() function.

func DiscardToSync

func DiscardToSync(conn net.Conn) error

DiscardToSync discards all messages in the buffer until a Sync has been reached. If a Sync was never sent, then this may cause the connection to lock until the client send a Sync, as their request structure was malformed.

func InitializeDefaultMessage

func InitializeDefaultMessage(message Message)

InitializeDefaultMessage creates the internal structure of the default message, while ensuring that the structure of the message is correct. This should be called in an init() function.

func ReceiveBruteForceMatches

func ReceiveBruteForceMatches(conn net.Conn) ([][]Message, error)

ReceiveBruteForceMatches checks with every message to find matches. This is highly inefficient, and is intended to assist with debugging, due to code paths where we may not know which message to expect. The order of returned messages are not deterministic. Each []Message represents all matches that follow the first match. Only returns an error on connection errors.

func ReceiveInto

func ReceiveInto[T Message](conn net.Conn, message T) (out T, err error)

ReceiveInto reads the given Message from the connection. This should only be used when a specific message is expected, and that message did not call AddMessageHeader in its init() function. In addition, if the client sends multiple messages at once, then this will only read the first message. If multiple messages are expected, use ReceiveIntoAny.

func Send

func Send(conn net.Conn, message Message) error

Send sends the given message over the connection.

Types

type Field

type Field struct {
	Name     string
	Type     FieldType
	Flags    FieldFlags
	Data     any // Data may ONLY be one of the following: int32, string, []byte. Nil is not allowed.
	Children []FieldGroup
}

Field is a field within the PostgreSQL message.

func (*Field) Copy

func (f *Field) Copy() *Field

Copy returns a copy of this field, which is free to modify.

type FieldFlags

type FieldFlags int32

FieldFlags are special attributes that may be assigned to fields.

const (
	Header                 FieldFlags = 1 << iota // Header is the header of the message.
	MessageLengthInclusive                        // MessageLengthInclusive is the length of the message, including the count's size.
	MessageLengthExclusive                        // MessageLengthExclusive is the length of the message, excluding the count's size.
	ExcludeTerminator                             // ExcludeTerminator excludes the terminator for String types.
	ByteCount                                     // ByteCount signals that the following ByteN non-child field uses this field for its count.
	RepeatedTerminator                            // RepeatedTerminator states that the Repeated type always ends with a NULL terminator.
	StaticData                                    // StaticData states that the data that has been set as the default cannot be changed.
)

type FieldGroup

type FieldGroup []*Field

FieldGroup is a slice of fields. Mainly used for organization, as []FieldGroup looks better than []FieldGroup.

type FieldType

type FieldType byte

FieldType is the type of the field as defined by PostgreSQL.

const (
	Byte1    FieldType = iota // Byte1 is a single unsigned byte.
	ByteN                     // ByteN is a variable number of bytes. Allowed on the last field, or when a ByteCount-tagged field precedes it.
	Int8                      // Int8 is a single signed byte.
	Int16                     // Int16 are two bytes.
	Int32                     // Int32 are four bytes.
	String                    // String is a variable-length type, generally punctuated by a NULL terminator.
	Repeated                  // Repeated is a parent type that states its children will be repeated until the end of the message.

	Byte4 = Int32 //TODO: verify that this is correct, only used on one type
)

type Message

type Message interface {
	// Encode returns a new MessageFormat containing any modified data contained within the object. This should NOT be
	// the default message.
	Encode() (MessageFormat, error)
	// Decode returns a new Message that represents the given MessageFormat. You should never return the default
	// message, even if the message never varies from the default. Always make a copy, and then modify that copy.
	Decode(s MessageFormat) (Message, error)
	// DefaultMessage returns the default, unmodified message for this type.
	DefaultMessage() *MessageFormat
}

Message is a type that represents a PostgreSQL message.

func Receive

func Receive(conn net.Conn) (Message, error)

Receive returns all messages that were sent from the given connection. This checks with all messages that have a Header, and have called AddMessageHeader within their init() function. Returns a nil slice if no messages were matched. This is the recommended way to check for messages when a specific message is not expected. Use ReceiveInto or ReceiveIntoAny when expecting specific messages, where it would be an error to receive messages different from the expectation.

func ReceiveIntoAny

func ReceiveIntoAny(conn net.Conn, messages ...Message) ([]Message, error)

ReceiveIntoAny returns all messages that were sent from the given connection. This should only be used when one of several specific messages are expected, and those messages did not call AddMessageHeader in their init() functions. Messages given first have a higher matching priority. Returns a nil slice if no messages matched. Only returns an error on connection errors. This will not error if the connection sends extra data or unspecified messages.

type MessageFormat

type MessageFormat struct {
	Name   string
	Fields FieldGroup
	// contains filtered or unexported fields
}

MessageFormat is the format of a message as defined by PostgreSQL. Contains the description and values. https://www.postgresql.org/docs/15/protocol-message-formats.html

func (MessageFormat) Copy

func (m MessageFormat) Copy() MessageFormat

Copy returns a copy of the MessageFormat, which is free to modify.

func (MessageFormat) Field

func (m MessageFormat) Field(name string) MessageWriter

Field returns a MessageWriter for the calling MessageFormat, which makes it easier (and safer) to update the field whose name was given.

func (MessageFormat) MatchesStructure

func (m MessageFormat) MatchesStructure(otherMessage MessageFormat) error

MatchesStructure returns an error if the given MessageFormat has a different structure than the calling MessageFormat.

func (MessageFormat) String

func (m MessageFormat) String() string

String returns a printable version of the MessageFormat.

type MessageWriter

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

MessageWriter is used to easily (and safely) interact with the contents of a MessageFormat.

func (MessageWriter) Child

func (mw MessageWriter) Child(name string, position int) MessageWriter

Child returns a new MessageWriter pointing to the child of the field chain provided so far. As there may be multiple children, the position determines which child will be referenced. If a child position is given that does not exist, then a child at that position will be created. If the position is more than an increment, then this will also create all children up to the position, by giving them their default values.

func (MessageWriter) Get

func (mw MessageWriter) Get() (any, error)

Get returns the value of the field pointed to by the field chain provided.

func (MessageWriter) MustGet

func (mw MessageWriter) MustGet() any

MustGet is the same as Get, except that this panics on errors rather than returning them.

func (MessageWriter) MustWrite

func (mw MessageWriter) MustWrite(value any)

MustWrite is the same as Write, except that this panics on errors rather than returning them.

func (MessageWriter) Write

func (mw MessageWriter) Write(value any) error

Write writes the given value to the field pointed to by the field chain provided. Only accepts values with the following types: int/8/16/32/64, uint/8/16/32/64, string, []byte (use an empty slice instead of nil).