diff --git a/cmd/grumble/args.go b/cmd/grumble/args.go index 4b2331c..a00a4b4 100644 --- a/cmd/grumble/args.go +++ b/cmd/grumble/args.go @@ -8,6 +8,8 @@ import ( "text/template" ) +// UsageArgs contains usage information that can be +// templated for the final usage display type UsageArgs struct { Version string BuildDate string @@ -67,6 +69,7 @@ func defaultLogPath() string { return filepath.Join(defaultDataDir(), "grumble.log") } +// Usage will print usage information about the command func Usage() { t, err := template.New("usage").Parse(usageTmpl) if err != nil { @@ -85,6 +88,7 @@ func Usage() { } } +// Args contains all the possible arguments to the Grumble command var Args args func init() { diff --git a/cmd/grumble/channel.go b/cmd/grumble/channel.go index 672c439..f9eaabd 100644 --- a/cmd/grumble/channel.go +++ b/cmd/grumble/channel.go @@ -10,7 +10,7 @@ import ( "mumble.info/grumble/pkg/acl" ) -// A Mumble channel +// Channel represents a Mumble channel type Channel struct { Id int Name string @@ -31,6 +31,7 @@ type Channel struct { DescriptionBlob string } +// NewChannel creates a new Mumble channel func NewChannel(id int, name string) (channel *Channel) { channel = new(Channel) channel.Id = id diff --git a/cmd/grumble/client.go b/cmd/grumble/client.go index d6bf9cd..233958b 100644 --- a/cmd/grumble/client.go +++ b/cmd/grumble/client.go @@ -23,7 +23,7 @@ import ( "mumble.info/grumble/pkg/packetdata" ) -// A client connection +// Client contains all information about a client connection type Client struct { // Logging *log.Logger @@ -115,18 +115,22 @@ func (client *Client) IsSuperUser() bool { return client.user.Id == 0 } +// ACLContext returns the access control list context for this client func (client *Client) ACLContext() *acl.Context { return &client.Channel.ACL } +// CertHash returns the certificate hash for this client func (client *Client) CertHash() string { return client.certHash } +// Session returns the session ID for this client func (client *Client) Session() uint32 { return client.session } +// Tokens return all tokens for this client func (client *Client) Tokens() []string { return client.tokens } @@ -159,13 +163,13 @@ func (client *Client) IsVerified() bool { return len(state.VerifiedChains) > 0 } -// Log a panic and disconnect the client. +// Panic will log a panic and disconnect the client. func (client *Client) Panic(v ...interface{}) { client.Print(v...) client.Disconnect() } -// Log a formatted panic and disconnect the client. +// Panicf will log a formatted panic and disconnect the client. func (client *Client) Panicf(format string, v ...interface{}) { client.Printf(format, v...) client.Disconnect() @@ -203,7 +207,7 @@ func (client *Client) Disconnect() { client.disconnect(false) } -// Disconnect a client (kick/ban) +// ForceDisconnect will disconnect a client (kick/ban) func (client *Client) ForceDisconnect() { client.disconnect(true) } @@ -215,7 +219,7 @@ func (client *Client) ClearCaches() { } } -// Reject an authentication attempt +// RejectAuth will reject an authentication attempt func (client *Client) RejectAuth(rejectType mumbleproto.Reject_RejectType, reason string) { var reasonString *string = nil if len(reason) > 0 { @@ -384,7 +388,7 @@ func (client *Client) udpRecvLoop() { } } -// Send buf as a UDP message. If the client does not have +// SendUDP will send buf as a UDP message. If the client does not have // an established UDP connection, the datagram will be tunelled // through the client's control channel (TCP). func (client *Client) SendUDP(buf []byte) error { diff --git a/cmd/grumble/freeze.go b/cmd/grumble/freeze.go index a8dbcfe..4b289dd 100644 --- a/cmd/grumble/freeze.go +++ b/cmd/grumble/freeze.go @@ -22,7 +22,7 @@ import ( "mumble.info/grumble/pkg/serverconf" ) -// Freeze a server to disk and closes the log file. +// FreezeToFile will freeze a server to disk and closes the log file. // This must be called from within the Server's synchronous handler. func (server *Server) FreezeToFile() error { // See freeeze_{windows,unix}.go for real implementations. @@ -116,7 +116,7 @@ func (server *Server) Freeze() (fs *freezer.Server, err error) { return fs, nil } -// Merge the contents of a freezer.BanList into the server's +// UnfreezeBanList will merge the contents of a freezer.BanList into the server's // ban list. func (s *Server) UnfreezeBanList(fblist *freezer.BanList) { s.Bans = nil @@ -147,7 +147,7 @@ func (s *Server) UnfreezeBanList(fblist *freezer.BanList) { } } -// Freeze a ban into a flattened protobuf-based struct +// FreezeBan will freeze a ban into a flattened protobuf-based struct // ready to be persisted to disk. func FreezeBan(ban ban.Ban) (fb *freezer.Ban) { fb = new(freezer.Ban) @@ -307,7 +307,7 @@ func (user *User) Freeze() (fu *freezer.User, err error) { return } -// Merge the contents of a frozen User into an existing user struct. +// Unfreeze will merge the contents of a frozen User into an existing user struct. func (u *User) Unfreeze(fu *freezer.User) { if fu.Name != nil { u.Name = *fu.Name @@ -332,7 +332,7 @@ func (u *User) Unfreeze(fu *freezer.User) { } } -// Freeze a ChannelACL into it a flattened protobuf-based structure +// FreezeACL will freeze a ChannelACL into it a flattened protobuf-based structure // ready to be persisted to disk. func FreezeACL(aclEntry acl.ACL) (*freezer.ACL, error) { frozenAcl := &freezer.ACL{} @@ -348,7 +348,7 @@ func FreezeACL(aclEntry acl.ACL) (*freezer.ACL, error) { return frozenAcl, nil } -// Freeze a Group into a flattened protobuf-based structure +// FreezeGroup will freeze a Group into a flattened protobuf-based structure // ready to be persisted to disk. func FreezeGroup(group acl.Group) (*freezer.Group, error) { frozenGroup := &freezer.Group{} @@ -364,7 +364,7 @@ func FreezeGroup(group acl.Group) (*freezer.Group, error) { return frozenGroup, nil } -// Create a new server from its on-disk representation. +// NewServerFromFrozen will create a new server from its on-disk representation. // // This will read a full serialized server (typically stored in // a file called 'main.fz') from disk. It will also check for @@ -681,7 +681,7 @@ func NewServerFromFrozen(name string) (s *Server, err error) { return s, nil } -// Update the datastore with the user's current state. +// UpdateFrozenUser will update the datastore with the user's current state. func (server *Server) UpdateFrozenUser(client *Client, state *mumbleproto.UserState) { // Full sync If there's no userstate messgae provided, or if there is one, and // it includes a registration operation. @@ -718,7 +718,7 @@ func (server *Server) UpdateFrozenUser(client *Client, state *mumbleproto.UserSt server.numLogOps += 1 } -// Update a user's last active channel +// UpdateFrozenUserLastChannel will update a user's last active channel func (server *Server) UpdateFrozenUserLastChannel(client *Client) { if client.IsRegistered() { user := client.user @@ -737,7 +737,7 @@ func (server *Server) UpdateFrozenUserLastChannel(client *Client) { } } -// Mark a user as deleted in the datstore. +// DeleteFrozenUser will mark a user as deleted in the datstore. func (server *Server) DeleteFrozenUser(user *User) { err := server.freezelog.Put(&freezer.UserRemove{Id: proto.Uint32(user.Id)}) if err != nil { @@ -746,7 +746,7 @@ func (server *Server) DeleteFrozenUser(user *User) { server.numLogOps += 1 } -// Given a target channel and a ChannelState protocol message, create a freezer.Channel that +// UpdateFrozenChannel will, given a target channel and a ChannelState protocol message, create a freezer.Channel that // only includes the values changed by the given ChannelState message. When done, write that // frozen.Channel to the datastore. func (server *Server) UpdateFrozenChannel(channel *Channel, state *mumbleproto.ChannelState) { @@ -814,7 +814,7 @@ func (server *Server) UpdateFrozenChannelACLs(channel *Channel) { server.numLogOps += 1 } -// Mark a channel as deleted in the datastore. +// DeleteFrozenChannel will mark a channel as deleted in the datastore. func (server *Server) DeleteFrozenChannel(channel *Channel) { err := server.freezelog.Put(&freezer.ChannelRemove{Id: proto.Uint32(uint32(channel.Id))}) if err != nil { diff --git a/cmd/grumble/gencert.go b/cmd/grumble/gencert.go index 4c2bb30..904caa8 100644 --- a/cmd/grumble/gencert.go +++ b/cmd/grumble/gencert.go @@ -17,7 +17,7 @@ import ( "time" ) -// Generate a 4096-bit RSA keypair and a Grumble auto-generated X509 +// GenerateSelfSignedCert will generate a 4096-bit RSA keypair and a Grumble auto-generated X509 // certificate. Output PEM-encoded DER representations of the resulting // certificate and private key to certpath and keypath. func GenerateSelfSignedCert(certpath, keypath string) (err error) { diff --git a/cmd/grumble/message.go b/cmd/grumble/message.go index 417faba..b9e9780 100644 --- a/cmd/grumble/message.go +++ b/cmd/grumble/message.go @@ -18,12 +18,14 @@ import ( "mumble.info/grumble/pkg/mumbleproto" ) +// Message contains a specific message for a client type Message struct { buf []byte kind uint16 client *Client } +// VoiceBroadcast contains a voice broadcast for a specific client type VoiceBroadcast struct { // The client who is performing the broadcast client *Client diff --git a/cmd/grumble/murmurdb.go b/cmd/grumble/murmurdb.go index 83cd2c9..55792e2 100644 --- a/cmd/grumble/murmurdb.go +++ b/cmd/grumble/murmurdb.go @@ -23,22 +23,31 @@ import ( ) const ( + // ChannelInfoDescription represents the description of a channel info ChannelInfoDescription int = iota + // ChannelInfoPosition represents the position of a channel info ChannelInfoPosition ) const ( + // UserInfoName points to the name field of user information UserInfoName int = iota + // UserInfoEmail points to the email field of user information UserInfoEmail + // UserInfoComment points to the comment field of user information UserInfoComment + // UserInfoHash points to the hash field of user information UserInfoHash + // UserInfoPassword points to the password field of user information UserInfoPassword + // UserInfoLastActive points to the last active field of user information UserInfoLastActive ) +// SQLiteSupport marks whether SQLite is supported or not const SQLiteSupport = true -// Import the structure of an existing Murmur SQLite database. +// MurmurImport will import the structure of an existing Murmur SQLite database. func MurmurImport(filename string) (err error) { db, err := sql.Open("sqlite", filename) if err != nil { @@ -84,7 +93,7 @@ func MurmurImport(filename string) (err error) { return } -// Create a new Server from a Murmur SQLite database +// NewServerFromSQLite will create a new Server from a Murmur SQLite database func NewServerFromSQLite(id int64, db *sql.DB) (s *Server, err error) { s, err = NewServer(id) if err != nil { diff --git a/cmd/grumble/register.go b/cmd/grumble/register.go index 50015a8..76d318f 100644 --- a/cmd/grumble/register.go +++ b/cmd/grumble/register.go @@ -16,6 +16,7 @@ import ( "net/http" ) +// Register contains the information necessary to register a server type Register struct { XMLName xml.Name `xml:"server"` Version string `xml:"version"` @@ -33,7 +34,7 @@ type Register struct { const registerUrl = "https://mumble.info/register.cgi" -// Determines whether a server is public by checking whether the +// IsPublic Determines whether a server is public by checking whether the // config values required for public registration are set. // // This function is used to determine whether or not to periodically @@ -54,7 +55,7 @@ func (server *Server) IsPublic() bool { return true } -// Perform a public server registration update. +// RegisterPublicServer will perform a public server registration update. // // When a Mumble server connects to the master server // for registration, it connects using its server certificate diff --git a/cmd/grumble/server.go b/cmd/grumble/server.go index 3638616..03ed4ac 100644 --- a/cmd/grumble/server.go +++ b/cmd/grumble/server.go @@ -36,13 +36,23 @@ import ( "mumble.info/grumble/pkg/web" ) -// The default port a Murmur server listens on +// DefaultPort is the default port a Murmur server listens on const DefaultPort = 64738 + +// DefaultWebPort is the default web port a Grumble server listens on const DefaultWebPort = 443 + +// UDPPacketSize is the size of each UDP packet const UDPPacketSize = 1024 +// LogOpsBeforeSync is the amount of logging operations that can be done +// before syncing const LogOpsBeforeSync = 100 + +// CeltCompatBitstream specifies the codec for celt compatibility const CeltCompatBitstream = -2147483637 + +// These constants keep track of the different states the server can be in const ( StateClientConnected = iota StateServerSentVersion @@ -52,13 +62,14 @@ const ( StateClientDead ) +// KeyValuePair contains a key value pair and a reset flag type KeyValuePair struct { Key string Value string Reset bool } -// A Murmur server instance +// Server is a Grumble server instance type Server struct { Id int64 @@ -137,7 +148,7 @@ func (lf clientLogForwarder) Write(incoming []byte) (int, error) { return len(incoming), nil } -// Allocate a new Murmur instance +// NewServer will allocate a new Grumble instance func NewServer(id int64) (s *Server, err error) { s = new(Server) @@ -175,7 +186,7 @@ func (server *Server) RootChannel() *Channel { return root } -// Set password as the new SuperUser password +// SetSuperUserPassword will set password as the new SuperUser password func (server *Server) SetSuperUserPassword(password string) { saltBytes := make([]byte, 24) _, err := rand.Read(saltBytes) @@ -356,13 +367,13 @@ func (server *Server) RemoveChanel(channel *Channel) { delete(server.Channels, channel.Id) } -// Link two channels +// LinkChannels will link two channels func (server *Server) LinkChannels(channel *Channel, other *Channel) { channel.Links[other.Id] = other other.Links[channel.Id] = channel } -// Unlink two channels +// UnlinkChannels will unlink two channels func (server *Server) UnlinkChannels(channel *Channel, other *Channel) { delete(channel.Links, other.Id) delete(other.Links, channel.Id) @@ -877,6 +888,7 @@ func (server *Server) sendClientPermissions(client *Client, channel *Channel) { // }) } +// ClientPredicate takes a client and returns a boolean type ClientPredicate func(client *Client) bool func (server *Server) broadcastProtoMessageWithPredicate(msg interface{}, clientcheck ClientPredicate) error { @@ -940,7 +952,7 @@ func (server *Server) handleIncomingMessage(client *Client, msg *Message) { } } -// Send the content of buf as a UDP packet to addr. +// SendUDP will send the content of buf as a UDP packet to addr. func (s *Server) SendUDP(buf []byte, addr *net.UDPAddr) (err error) { _, err = s.udpconn.WriteTo(buf, addr) return @@ -1085,7 +1097,7 @@ func (server *Server) userEnterChannel(client *Client, channel *Channel, usersta } } -// Register a client on the server. +// RegisterClient will register a client on the server. func (s *Server) RegisterClient(client *Client) (uid uint32, err error) { // Increment nextUserId only if registration succeeded. defer func() { @@ -1257,7 +1269,7 @@ func (server *Server) IsCertHashBanned(hash string) bool { return false } -// Filter incoming text according to the server's current rules. +// FilterText filters incoming text according to the server's current rules. func (server *Server) FilterText(text string) (filtered string, err error) { options := &htmlfilter.Options{ StripHTML: !server.cfg.BoolValue("AllowHTML"), diff --git a/cmd/grumble/signal_unix.go b/cmd/grumble/signal_unix.go index 7127f24..c46cf9e 100644 --- a/cmd/grumble/signal_unix.go +++ b/cmd/grumble/signal_unix.go @@ -15,6 +15,7 @@ import ( "mumble.info/grumble/pkg/logtarget" ) +// SignalHandler manages signals on Unix like systems func SignalHandler() { sigchan := make(chan os.Signal, 10) signal.Notify(sigchan, syscall.SIGUSR2, syscall.SIGTERM, syscall.SIGINT) diff --git a/cmd/grumble/user.go b/cmd/grumble/user.go index 8346514..47ab09b 100644 --- a/cmd/grumble/user.go +++ b/cmd/grumble/user.go @@ -13,6 +13,7 @@ import ( // // Users are registered clients on the server. +// User contains all user information type User struct { Id uint32 Name string @@ -25,7 +26,7 @@ type User struct { LastActive uint64 } -// Create a new User +// NewUser will create a new User func NewUser(id uint32, name string) (user *User, err error) { if id < 0 { return nil, errors.New("Invalid user id") @@ -40,7 +41,7 @@ func NewUser(id uint32, name string) (user *User, err error) { }, nil } -// HasComment Does the channel have comment? +// HasComment checks whether the channel have comment? func (user *User) HasComment() bool { return len(user.CommentBlob) > 0 } diff --git a/cmd/grumble/voicetarget.go b/cmd/grumble/voicetarget.go index 4c8453e..74d3175 100644 --- a/cmd/grumble/voicetarget.go +++ b/cmd/grumble/voicetarget.go @@ -6,7 +6,7 @@ package main import "mumble.info/grumble/pkg/acl" -// A VoiceTarget holds information about a single +// VoiceTarget holds information about a single // VoiceTarget entry of a Client. type VoiceTarget struct { sessions []uint32 @@ -23,7 +23,7 @@ type voiceTargetChannel struct { onlyGroup string } -// Add's a client's session to the VoiceTarget +// AddSession adds a client's session to the VoiceTarget func (vt *VoiceTarget) AddSession(session uint32) { vt.sessions = append(vt.sessions, session) } @@ -53,7 +53,7 @@ func (vt *VoiceTarget) ClearCache() { vt.fromChannelsCache = nil } -// Send the contents of the VoiceBroadcast to all targets specified in the +// SendVoiceBroadcast will send the contents of the VoiceBroadcast to all targets specified in the // VoiceTarget. func (vt *VoiceTarget) SendVoiceBroadcast(vb *VoiceBroadcast) { buf := vb.buf