From f655167761dea2bbaaa59a4e2a6d98dded663087 Mon Sep 17 00:00:00 2001 From: Bruce Marriner Date: Mon, 16 Nov 2015 21:39:39 -0600 Subject: [PATCH] Several updates to make library more idiomatic Go --- channel.go | 10 ++++--- guild.go | 27 +++++++++++-------- restapi.go | 4 +-- session.go | 19 -------------- structs.go | 23 +++++++++++------ users.go | 11 ++++---- util.go | 2 +- wsapi.go | 76 ++++++++++++++++++++++++++++++++++-------------------- 8 files changed, 94 insertions(+), 78 deletions(-) diff --git a/channel.go b/channel.go index 8e187fa..47fc9b1 100644 --- a/channel.go +++ b/channel.go @@ -1,21 +1,23 @@ package discordgo +// A Channel holds all data related to an individual Discord channel. type Channel struct { - Id string `json:"id"` - GuildId string `json:"guild_idomitempty"` + ID string `json:"id"` + GuildID string `json:"guild_idomitempty"` Name string `json:"name"` Topic string `json:"topic"` Position int `json:"position"` Type string `json:"type"` PermissionOverwrites []PermissionOverwrite `json:"permission_overwrites"` IsPrivate bool `json:"is_private"` - LastMessageId string `json:"last_message_id"` + LastMessageID string `json:"last_message_id"` Recipient User `json:"recipient"` Session *Session } +// A PermissionOverwrite holds permission overwrite data for a Channel type PermissionOverwrite struct { - Id string `json:"id"` + ID string `json:"id"` Type string `json:"type"` Deny int `json:"deny"` Allow int `json:"allow"` diff --git a/guild.go b/guild.go index d57bf15..0f32373 100644 --- a/guild.go +++ b/guild.go @@ -1,15 +1,17 @@ package discordgo +// A Guild holds all data related to a specific Discord Guild. Guilds are also +// sometimes referred to as Servers in the Discord client. type Guild struct { - Id string `json:"id"` + ID string `json:"id"` Name string `json:"name"` Icon string `json:"icon"` Region string `json:"region"` AfkTimeout int `json:"afk_timeout"` - AfkChannelId string `json:"afk_channel_id"` - EmbedChannelId string `json:"embed_channel_id"` + AfkChannelID string `json:"afk_channel_id"` + EmbedChannelID string `json:"embed_channel_id"` EmbedEnabled bool `json:"embed_enabled"` - OwnerId string `json:"owner_id"` + OwnerID string `json:"owner_id"` Large bool `json:"large"` // ?? JoinedAt string `json:"joined_at"` // make this a timestamp Roles []Role `json:"roles"` @@ -19,8 +21,9 @@ type Guild struct { VoiceStates []VoiceState `json:"voice_states"` } +// A Role stores information about Discord guild member roles. type Role struct { - Id string `json:"id"` + ID string `json:"id"` Name string `json:"name"` Managed bool `json:"managed"` Color int `json:"color"` @@ -29,26 +32,28 @@ type Role struct { Permissions int `json:"permissions"` } +// A VoiceState stores the voice states of Guilds type VoiceState struct { - UserId string `json:"user_id"` + UserID string `json:"user_id"` Suppress bool `json:"suppress"` - SessionId string `json:"session_id"` + SessionID string `json:"session_id"` SelfMute bool `json:"self_mute"` SelfDeaf bool `json:"self_deaf"` Mute bool `json:"mute"` Deaf bool `json:"deaf"` - ChannelId string `json:"channel_id"` + ChannelID string `json:"channel_id"` } +// A Presence stores the online, offline, or idle and game status of Guild members. type Presence struct { User User `json:"user"` Status string `json:"status"` - GameId int `json:"game_id"` + GameID int `json:"game_id"` } -// TODO: Member vs User? +// A Member stores user information for Guild members. type Member struct { - GuildId string `json:"guild_id"` + GuildID string `json:"guild_id"` JoinedAt string `json:"joined_at"` Deaf bool `json:"deaf"` Mute bool `json:"mute"` diff --git a/restapi.go b/restapi.go index 367b454..7c07673 100644 --- a/restapi.go +++ b/restapi.go @@ -541,8 +541,8 @@ func (s *Session) VoiceRegions() (st []VoiceRegion, err error) { return } -// VoiceIce returns the voice server ICE information -func (s *Session) VoiceIce() (st VoiceIce, err error) { +// VoiceICE returns the voice server ICE information +func (s *Session) VoiceICE() (st VoiceICE, err error) { body, err := s.Request("GET", VOICE_ICE, ``) err = json.Unmarshal(body, &st) diff --git a/session.go b/session.go index 6a4eddd..66cd192 100644 --- a/session.go +++ b/session.go @@ -59,22 +59,3 @@ type Session struct { // lets put all the general session // tracking and infos here.. clearly } - -/****************************************************************************** - * The below functions are "shortcut" methods for functions in restapi.go - * Reference the client.go file for more documentation. - */ -func (s *Session) Self() (user User, err error) { - user, err = s.User("@me") - return -} - -func (s *Session) MyPrivateChannels() (channels []Channel, err error) { - channels, err = s.UserChannels("@me") - return -} - -func (s *Session) MyGuilds() (servers []Guild, err error) { - servers, err = s.UserGuilds("@me") - return -} diff --git a/structs.go b/structs.go index eeadc10..efa4cb6 100644 --- a/structs.go +++ b/structs.go @@ -2,8 +2,9 @@ package discordgo // TODO: Eventually everything here gets moved to a better place. +// A Message stores all data related to a specific Discord message. type Message struct { - Id int `json:"id,string"` + ID int `json:"id,string"` Author User `json:"author"` Content string `json:"content"` Attachments []Attachment `json:"attachments"` @@ -13,33 +14,39 @@ type Message struct { MentionEveryone bool `json:"mention_everyone"` EditedTimestamp string `json:"edited_timestamp"` Mentions []User `json:"mentions"` - ChannelId int `json:"channel_id,string"` + ChannelID int `json:"channel_id,string"` } +// An Attachment stores data for message attachments. type Attachment struct { //TODO figure this out } +// An Embed stores data for message embeds. type Embed struct { // TODO figure this out } +// A VoiceRegion stores data for a specific voice region server. type VoiceRegion struct { - Id string `json:"id"` + ID string `json:"id"` Name string `json:"name"` SampleHostname string `json:"sample_hostname"` SamplePort int `json:"sample_port"` } -type VoiceIce struct { - Ttl int `json:"ttl,string"` - Servers []IceServer `json:"servers"` +// A VoiceICE stores data for voice ICE servers. +type VoiceICE struct { + TTL int `json:"ttl,string"` + Servers []ICEServer `json:"servers"` } -type IceServer struct { - Url string `json:"url"` +// A ICEServer stores data for a specific voice ICE server. +type ICEServer struct { + URL string `json:"url"` Username string `json:"username"` Credential string `json:"credential"` } +// A Invite stores all data related to a specific Discord Guild or Channel invite. type Invite struct { MaxAge int `json:"max_age"` Code string `json:"code"` diff --git a/users.go b/users.go index bcfa48c..e04c161 100644 --- a/users.go +++ b/users.go @@ -1,7 +1,8 @@ package discordgo +// A User stores all data for an individual Discord user. type User struct { - Id string `json:"id"` + ID string `json:"id"` Email string `json:"email"` Username string `json:"username"` Avatar string `json:"Avatar"` @@ -18,13 +19,15 @@ type User struct { // it just doesn't seem able to handle this one // field correctly. Need to research this more. +// A PrivateChannel stores all data for a specific user private channel. type PrivateChannel struct { - Id string `json:"id"` + ID string `json:"id"` IsPrivate bool `json:"is_private"` - LastMessageId string `json:"last_message_id"` + LastMessageID string `json:"last_message_id"` Recipient User `json:"recipient"` } // merge with channel? +// A Settings stores data for a specific users Discord client settings. type Settings struct { RenderEmbeds bool `json:"render_embeds"` InlineEmbedMedia bool `json:"inline_embed_media"` @@ -35,5 +38,3 @@ type Settings struct { Theme string `json:"theme"` MutedChannels []string `json:"muted_channels"` } - -// PM function to PM a user. diff --git a/util.go b/util.go index 6e00040..070d550 100644 --- a/util.go +++ b/util.go @@ -9,7 +9,7 @@ import ( "fmt" ) -// convert to return as string +// printJSON is a helper function to display JSON data in a easy to read format. func printJSON(body []byte) { var prettyJSON bytes.Buffer error := json.Indent(&prettyJSON, body, "", "\t") diff --git a/wsapi.go b/wsapi.go index 412e79d..00775b1 100644 --- a/wsapi.go +++ b/wsapi.go @@ -17,19 +17,16 @@ import ( "github.com/gorilla/websocket" ) -// Basic struct for all Websocket Event messages +// An Event provides a basic initial struct for all websocket event. type Event struct { - Type string `json:"t"` - State int `json:"s"` - Operation int `json:"o"` - Direction int `json:"dir"` - //Direction of command, 0-received, 1-sent -- thanks Xackery/discord - - RawData json.RawMessage `json:"d"` - Session *Session + Type string `json:"t"` + State int `json:"s"` + Operation int `json:"o"` + Direction int `json:"dir"` + RawData json.RawMessage `json:"d"` } -// The Ready Event given after initial connection +// A Ready stores all data for the websocket READY event. type Ready struct { Version int `json:"v"` SessionID string `json:"session_id"` @@ -42,51 +39,61 @@ type Ready struct { // ReadState might need to move? Gives me the read status // of all my channels when first connecting. I think :) + +// A ReadState stores data on the read state of channels. type ReadState struct { MentionCount int - LastMessageId string `json:"last_message_id"` - Id string `json:"id"` + LastMessageID string `json:"last_message_id"` + ID string `json:"id"` } +// A TypingStart stores data for the typing start websocket event. type TypingStart struct { - UserId string `json:"user_id"` - ChannelId string `json:"channel_id"` + UserID string `json:"user_id"` + ChannelID string `json:"channel_id"` Timestamp int `json:"timestamp"` } +// A PresenceUpdate stores data for the pressence update websocket event. type PresenceUpdate struct { User User `json:"user"` Status string `json:"status"` Roles []string `json:"roles"` - GuildId string `json:"guild_id"` - GameId int `json:"game_id"` + GuildID string `json:"guild_id"` + GameID int `json:"game_id"` } +// A MessageAck stores data for the message ack websocket event. type MessageAck struct { - MessageId string `json:"message_id"` - ChannelId string `json:"channel_id"` + MessageID string `json:"message_id"` + ChannelID string `json:"channel_id"` } +// A MessageDelete stores data for the message delete websocket event. type MessageDelete struct { - Id string `json:"id"` - ChannelId string `json:"channel_id"` + ID string `json:"id"` + ChannelID string `json:"channel_id"` } // so much like MessageAck.. +// A GuildIntegrationsUpdate stores data for the guild integrations update +// websocket event. type GuildIntegrationsUpdate struct { - GuildId string `json:"guild_id"` + GuildID string `json:"guild_id"` } +// A GuildRole stores data for guild role websocket events. type GuildRole struct { Role Role `json:"role"` - GuildId string `json:"guild_id"` + GuildID string `json:"guild_id"` } +// A GuildRoleDelete stores data for the guild role delete websocket event. type GuildRoleDelete struct { - RoleId string `json:"role_id"` - GuildId string `json:"guild_id"` + RoleID string `json:"role_id"` + GuildID string `json:"guild_id"` } -// Open a websocket connection to Discord +// Open opens a websocket connection to Discord. func (s *Session) Open() (err error) { // Get the gateway to use for the Websocket connection @@ -101,6 +108,8 @@ func (s *Session) Open() (err error) { // maybe this is SendOrigin? not sure the right name here // also bson.M vs string interface map? Read about // how to send JSON the right way. + +// Handshake sends the client data to Discord during websocket initial connection. func (s *Session) Handshake() (err error) { err = s.wsConn.WriteJSON(map[string]interface{}{ @@ -121,21 +130,23 @@ func (s *Session) Handshake() (err error) { return } -func (s *Session) UpdateStatus(idleSince, gameId string) (err error) { +// UpdateStatus is used to update the authenticated user's status. +func (s *Session) UpdateStatus(idleSince, gameID string) (err error) { err = s.wsConn.WriteJSON(map[string]interface{}{ "op": 2, "d": map[string]interface{}{ "idle_since": idleSince, - "game_id": gameId, + "game_id": gameID, }, }) - return } // TODO: need a channel or something to communicate // to this so I can tell it to stop listening + +// Listen starts listening to the websocket connection for events. func (s *Session) Listen() (err error) { if s.wsConn == nil { @@ -157,12 +168,17 @@ func (s *Session) Listen() (err error) { // Not sure how needed this is and where it would be best to call it. // somewhere. + +// Close closes the connection to the websocket. func (s *Session) Close() { s.wsConn.Close() } // Front line handler for all Websocket Events. Determines the // event type and passes the message along to the next handler. + +// event is the front line handler for all events. This needs to be +// broken up into smaller functions to be more idiomatic Go. func (s *Session) event(messageType int, message []byte) (err error) { if s.Debug { @@ -429,6 +445,10 @@ func (s *Session) event(messageType int, message []byte) (err error) { // This heartbeat is sent to keep the Websocket conenction // to Discord alive. If not sent, Discord will close the // connection. + +// Heartbeat sends regular heartbeats to Discord so it knows the client +// is still connected. If you do not send these heartbeats Discord will +// disconnect the websocket connection after a few seconds. func (s *Session) Heartbeat(i time.Duration) { if s.wsConn == nil {