protocol

package
v0.0.0-...-3e13fb5 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2023 License: AGPL-3.0 Imports: 5 Imported by: 0

Documentation

Overview

Byte Order

  • All messages MUST be transmitted in network (big-endian) byte order.

Variable Length Strings

All messages that have string fields accept string values of variable length. The length of a string precedes the string data.

  • String data MUST be a valid sequence of UTF-8 bytes.

Message Types

The first field of each message is a field indicating the message type. The message types are separate for the client and server. Each type is represented as a 32-bit unsigned integer

Message Errors

  • After a client transmits a request that results in an error, the server MUST respond with either an Error or FatalError response.
  • Error and FatalError messages MUST indicate an error code and MAY provide additional information as string data.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidResponseType = errors.New("invalid ResponseType value")
	ErrInvalidErrorType    = errors.New("invalid ErrorType value")
)
View Source 
var ErrInvalidRequestType = errors.New("invalid RequestType value")
View Source 
var ErrInvalidUtf8String = errors.New("invalid UTF-8 string")

Functions

func EncodeClientRequest 

func EncodeClientRequest(w io.Writer, request ClientRequest) error

func EncodeServerResponse 

func EncodeServerResponse(w io.Writer, response ServerResponse) error

Types

type ClientRequest 

type ClientRequest interface {
	RequestType() RequestType
	Accept(RequestVisitor)
	// contains filtered or unexported methods
}

ClientRequest messages originate in the clients before being received by the server and responded to.

func DecodeClientRequest 

func DecodeClientRequest(r io.Reader) (ClientRequest, error)

type ConnectRequest 

type ConnectRequest struct {
	Version uint32 // The version of the protocol that the client is using.
	Name    string // The display name the user wishes to connect with.
}

This ConnectRequest MUST be sent to a server at the beginning of a connection.

  • The server MAY respond with an error message.
  • The server MUST update the user list if the client connected successfully.

func (*ConnectRequest) Accept 

func (c *ConnectRequest) Accept(v RequestVisitor)

func (*ConnectRequest) RequestType 

func (*ConnectRequest) RequestType() RequestType

type CreateRoomRequest 

type CreateRoomRequest struct {
	Room string // Desired name of the new room.
}

A CreateRoomRequest should be sent by the client to create a new room.

  • The server MAY respond with an error message.
  • The server MUST update the room list if the room was created successfully.
  • The server MUST NOT add the user to the newly created room until the client joins with a JoinRoomRequest.

func (*CreateRoomRequest) Accept 

func (cr *CreateRoomRequest) Accept(v RequestVisitor)

func (*CreateRoomRequest) RequestType 

func (*CreateRoomRequest) RequestType() RequestType

type DisconnectRequest 

type DisconnectRequest struct{}

The DisconnectRequest MUST be sent before a client intentionally disconnects from the server.

  • The server MUST remove the user from the active user list, notify other users, and close the TCP connection immediately upon receiving this message.
  • If the server notices that the client closed the TCP connection without sending this message, it MUST also remove the user from the active user list and notify the other users.

func (*DisconnectRequest) Accept 

func (d *DisconnectRequest) Accept(v RequestVisitor)

func (*DisconnectRequest) RequestType 

func (*DisconnectRequest) RequestType() RequestType

type ErrorResponse 

type ErrorResponse struct {
	Error ErrorType // The error code corresponding to the error. See ErrorType.
	Info  string    // Additional information about the cause of the error
}

An ErrorResponse is sent to clients when there is an error performing an operation.

func (*ErrorResponse) Accept 

func (e *ErrorResponse) Accept(v ResponseVisitor)

func (*ErrorResponse) ResponseType 

func (*ErrorResponse) ResponseType() ResponseType

type ErrorType 

type ErrorType uint32
const (
	// The client is attempting to send a request without first sending a ConnectRequest.
	NotConnected ErrorType = 1 + iota

	// The client is already connected and is trying to connect again.
	AlreadyConnected

	// The server had an internal error that prevented it from completing the request.
	InternalError

	// The client sent a request that was not able to be decoded.
	MalformedRequest

	// The client is attempting to connect with a version of the protocol that does not match the server's supported versions.
	//   - This error MUST be sent in a FatalError server message.
	UnsupportedVersion

	// The requested room has not been created on the server or has been removed from the room list.
	MissingRoom

	// The request user has not connected to the server or has already disconnected.
	MissingUser

	// The requested room has already been created. It cannot be created again.
	ExistingRoom

	// The client is attempting to connect with a name that is already in-use on the server.
	//   - This error MUST be sent in a FatalError server message.
	ExistingUser

	// The requested room name does not satisfy the server's room naming requirements.
	//  - The server SHOULD include additional information that explains the room naming requirements.
	InvalidRoom

	// The client is attempting to connect with a name that does not satisfy the server's user naming requirements.
	//   - The server SHOULD include additional information that explains the user naming requirements.
	//   - This error MUST be sent in a FatalError server message.
	InvalidUser

	// The client is attempting to send a chat message with text that does not satisfy the server's text content requirements.
	//   - The server SHOULD include additional information that explains the text content requirements.
	InvalidText
)

func (ErrorType) GoString 

func (e ErrorType) GoString() string

func (ErrorType) String 

func (e ErrorType) String() string

type FatalErrorResponse 

type FatalErrorResponse struct {
	Error ErrorType // The error code corresponding to the error. See ErrorType.
	Info  string    // Additional information about the cause of the error.
}

A FatalErrorResponse is sent to clients when there is an error performing an operation.

  • Clients MUST disconnect from the server following this message.

func (*FatalErrorResponse) Accept 

func (fe *FatalErrorResponse) Accept(v ResponseVisitor)

func (*FatalErrorResponse) ResponseType 

func (*FatalErrorResponse) ResponseType() ResponseType

type JoinRoomRequest 

type JoinRoomRequest struct {
	Room string // Desired name of the room to join.
}

A CreateRoomRequest should be sent by the client to join a room.

  • The server MAY respond with an error message.
  • The server MUST update the room's list of users if the room was joined successfully.

func (*JoinRoomRequest) Accept 

func (jr *JoinRoomRequest) Accept(v RequestVisitor)

func (*JoinRoomRequest) RequestType 

func (*JoinRoomRequest) RequestType() RequestType

type KeepaliveRequest 

type KeepaliveRequest struct{}

KeepaliveRequest messages MUST be sent to the server at least every 30 seconds to prevent the TCP connection from closing.

func (*KeepaliveRequest) Accept 

func (k *KeepaliveRequest) Accept(v RequestVisitor)

func (*KeepaliveRequest) RequestType 

func (*KeepaliveRequest) RequestType() RequestType

type LeaveRoomRequest 

type LeaveRoomRequest struct {
	Room string // Desired name of the room to leave.
}

A LeaveRoomRequest should be sent by the client to leave a room.

  • The server MAY respond with an error message.
  • The server MUST update the room's list of users if the room was left successfully.
  • The server MUST remove a room from the room list if there are no users remaining.

func (*LeaveRoomRequest) Accept 

func (lr *LeaveRoomRequest) Accept(v RequestVisitor)

func (*LeaveRoomRequest) RequestType 

func (*LeaveRoomRequest) RequestType() RequestType

type ListRoomsRequest 

type ListRoomsRequest struct {
	//  The name of the user to get a list of joined rooms for.
	//  - If the user name is empty, the server MUST respond with a list of rooms for the entire server.
	User string
}

A ListRoomsRequest should be sent by the client to obtain a list of rooms.

  • The server MUST respond with an error message or a RoomListResponse.

func (*ListRoomsRequest) Accept 

func (lr *ListRoomsRequest) Accept(v RequestVisitor)

func (*ListRoomsRequest) RequestType 

func (*ListRoomsRequest) RequestType() RequestType

type ListUsersRequest 

type ListUsersRequest struct {
	// The name of the room to get a list of users for.
	//   - If the room name is empty, the server MUST respond with a list of users for the entire server.
	Room string
}

A ListUsersRequest should be sent by the client to obtain a list of users in room or the entire server.

  • The server must respond with an error message or a RoomListResponse.

func (*ListUsersRequest) Accept 

func (lu *ListUsersRequest) Accept(v RequestVisitor)

func (*ListUsersRequest) RequestType 

func (*ListUsersRequest) RequestType() RequestType

type MessageRoomRequest 

type MessageRoomRequest struct {
	Room string // The name of the room to send the chat message to.
	Text string // The text content of the chat message.
}

A MessageRoomRequest should be sent by the client to send a chat message to a room.

  • The server MAY respond with an error message.
  • The server MUST forward the message to other users in the room if sending the chat message was successful.

func (*MessageRoomRequest) Accept 

func (mr *MessageRoomRequest) Accept(v RequestVisitor)

func (*MessageRoomRequest) RequestType 

func (*MessageRoomRequest) RequestType() RequestType

type MessageUserRequest 

type MessageUserRequest struct {
	User string
	Text string
}

A MessageUserRequest should be sent by the client to send a chat message to another user.

  • The server MAY respond with an error message.
  • The server MUST forward the message to the other user if sending the chat message was successful.

func (*MessageUserRequest) Accept 

func (mu *MessageUserRequest) Accept(v RequestVisitor)

func (*MessageUserRequest) RequestType 

func (*MessageUserRequest) RequestType() RequestType

type RequestType 

type RequestType uint32
const (
	Keepalive RequestType = iota
	Connect
	Disconnect
	ListRooms
	ListUsers
	MessageRoom
	MessageUser
	CreateRoom
	JoinRoom
	LeaveRoom
)

func (RequestType) GoString 

func (r RequestType) GoString() string

func (RequestType) String 

func (r RequestType) String() string

type RequestVisitor 

type RequestVisitor interface {
	Keepalive(*KeepaliveRequest)
	Connect(*ConnectRequest)
	Disconnect(*DisconnectRequest)
	ListRooms(*ListRoomsRequest)
	ListUsers(*ListUsersRequest)
	MessageRoom(*MessageRoomRequest)
	MessageUser(*MessageUserRequest)
	CreateRoom(*CreateRoomRequest)
	JoinRoom(*JoinRoomRequest)
	LeaveRoom(*LeaveRoomRequest)
}

type ResponseType 

type ResponseType uint32
const (
	Error ResponseType = 1 + iota
	FatalError
	RoomList
	UserList
	RoomMessage
	UserMessage
)

func (ResponseType) GoString 

func (r ResponseType) GoString() string

func (ResponseType) String 

func (r ResponseType) String() string

type ResponseVisitor 

type ResponseVisitor interface {
	Error(*ErrorResponse)
	FatalError(*FatalErrorResponse)
	RoomList(*RoomListResponse)
	UserList(*UserListResponse)
	RoomMessage(*RoomMessageResponse)
	UserMessage(*UserMessageResponse)
}

type RoomListResponse 

type RoomListResponse struct {
	User  string   // The user who has joined the rooms. Empty if the response is for the list of rooms in the entire server.
	Count uint32   // The number of rooms in the response.
	Rooms []string // The array of room names.
}

A RoomListResponse is sent as a response to clients that ask for the list of rooms.

func (*RoomListResponse) Accept 

func (rl *RoomListResponse) Accept(v ResponseVisitor)

func (*RoomListResponse) ResponseType 

func (*RoomListResponse) ResponseType() ResponseType

type RoomMessageResponse 

type RoomMessageResponse struct {
	Room   string // The name of the room the chat message was sent from.
	Sender string // The name of the user that sent the direct message.
	Text   string // The text content of the chat message.
}

A RoomMessageResponse is sent when another user has sent a message in a room that the client user has joined.

func (*RoomMessageResponse) Accept 

func (rm *RoomMessageResponse) Accept(v ResponseVisitor)

func (*RoomMessageResponse) ResponseType 

func (*RoomMessageResponse) ResponseType() ResponseType

type ServerResponse 

type ServerResponse interface {
	ResponseType() ResponseType
	Accept(ResponseVisitor)
	// contains filtered or unexported methods
}

ServerResponse messages originate in the server before being received by relevant clients.

func DecodeServerResponse 

func DecodeServerResponse(r io.Reader) (ServerResponse, error)

type UserListResponse 

type UserListResponse struct {
	Room  string   // The room the users are located in. Empty if the response is for the list of users in the entire server.
	Count uint32   // The number of users in the room/server.
	Users []string // The array of user names.
}

A UserListResponse is sent as a response to clients that ask for a list of users.

func (*UserListResponse) Accept 

func (ul *UserListResponse) Accept(v ResponseVisitor)

func (*UserListResponse) ResponseType 

func (*UserListResponse) ResponseType() ResponseType

type UserMessageResponse 

type UserMessageResponse struct {
	Sender string // The name of the user that sent the direct message.
	Text   string // The text content of the chat message.
}

A UserMessageResponse is sent when another user has sent a direct message to the client user.

func (*UserMessageResponse) Accept 

func (um *UserMessageResponse) Accept(v ResponseVisitor)

func (*UserMessageResponse) ResponseType 

func (*UserMessageResponse) ResponseType() ResponseType

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.