Add doc strings to mtglib events

mtglib/events.go

@@ -10,56 +10,89 @@ type eventBase struct {
 	timestamp time.Time
 }
 
+// StreamID returns a ID of the stream this event belongs to.
 func (e eventBase) StreamID() string {
 	return e.streamID
 }
 
+// Timestamp return a time when this event was generated.
 func (e eventBase) Timestamp() time.Time {
 	return e.timestamp
 }
 
+// EventStart is emitted when mtg proxy starts to process a new
+// connection.
 type EventStart struct {
 	eventBase
 
+	// RemoteIP is an IP address of the client.
 	RemoteIP net.IP
 }
 
+// EventConnectedToDC is emitted when mtg proxy has connected to a
+// Telegram server.
 type EventConnectedToDC struct {
 	eventBase
 
+	// RemoteIP is an IP address of the Telegram server proxy has been
+	// connected to.
 	RemoteIP net.IP
-	DC       int
+
+	// DC is an index of the datacenter proxy has been connected to.
+	DC int
 }
 
+// EventTraffic is emitted when we read/write some bytes on a connection.
 type EventTraffic struct {
 	eventBase
 
+	// Traffic is a count of bytes which were transmitted.
 	Traffic uint
-	IsRead  bool
+
+	// IsRead defines if we _read_ or _write_ to connection. A rule of
+	// thumb is simple: EventTraffic is bound to a remote connection. Not
+	// to a client one, but either to Telegram or front domain one.
+	//
+	// In the case of Telegram, isRead means that we've fetched some bytes
+	// from Telegram to send it to a client.
+	//
+	// In the case of the front domain, it means that we've fetched some
+	// bytes from this domain to send it to a client.
+	IsRead bool
 }
 
+// EventFinish is emitted when we stop to manage a connection.
 type EventFinish struct {
 	eventBase
 }
 
+// EventDomainFronting is emitted when we connect to a front domain
+// instead of Telegram server.
 type EventDomainFronting struct {
 	eventBase
 }
 
+// EventConcurrencyLimited is emitted when connection was declined
+// because of the concurrency limit of the worker pool.
 type EventConcurrencyLimited struct {
 	eventBase
 }
 
+// EventIPBlocklisted is emitted when connection was declined because
+// IP address was found in IP blocklist.
 type EventIPBlocklisted struct {
 	eventBase
 
 	RemoteIP net.IP
 }
 
+// EventReplayAttack is emitted when mtg detects a replay attack on a
+// connection.
 type EventReplayAttack struct {
 	eventBase
 }
 
+// NewEventStart creates a new EventStart event.
 func NewEventStart(streamID string, remoteIP net.IP) EventStart {
 	return EventStart{
 		eventBase: eventBase{
@@ -70,6 +103,7 @@ func NewEventStart(streamID string, remoteIP net.IP) EventStart {
 	}
 }
 
+// NewEventConnectedToDC creates a new EventConnectedToDC event.
 func NewEventConnectedToDC(streamID string, remoteIP net.IP, dc int) EventConnectedToDC {
 	return EventConnectedToDC{
 		eventBase: eventBase{
@@ -81,6 +115,7 @@ func NewEventConnectedToDC(streamID string, remoteIP net.IP, dc int) EventConnec
 	}
 }
 
+// NewEventTraffic creates a new EventTraffic event.
 func NewEventTraffic(streamID string, traffic uint, isRead bool) EventTraffic {
 	return EventTraffic{
 		eventBase: eventBase{
@@ -92,6 +127,7 @@ func NewEventTraffic(streamID string, traffic uint, isRead bool) EventTraffic {
 	}
 }
 
+// NewEventFinish creates a new EventFinish event.
 func NewEventFinish(streamID string) EventFinish {
 	return EventFinish{
 		eventBase: eventBase{
@@ -101,6 +137,7 @@ func NewEventFinish(streamID string) EventFinish {
 	}
 }
 
+// NewEventDomainFronting creates a new EventDomainFronting event.
 func NewEventDomainFronting(streamID string) EventDomainFronting {
 	return EventDomainFronting{
 		eventBase: eventBase{
@@ -110,6 +147,8 @@ func NewEventDomainFronting(streamID string) EventDomainFronting {
 	}
 }
 
+// NewEventConcurrencyLimited creates a new EventConcurrencyLimited
+// event.
 func NewEventConcurrencyLimited() EventConcurrencyLimited {
 	return EventConcurrencyLimited{
 		eventBase: eventBase{
@@ -118,6 +157,7 @@ func NewEventConcurrencyLimited() EventConcurrencyLimited {
 	}
 }
 
+// NewEventIPBlocklisted creates a new EventIPBlocklisted event.
 func NewEventIPBlocklisted(remoteIP net.IP) EventIPBlocklisted {
 	return EventIPBlocklisted{
 		eventBase: eventBase{
@@ -127,6 +167,7 @@ func NewEventIPBlocklisted(remoteIP net.IP) EventIPBlocklisted {
 	}
 }
 
+// NewEventReplayAttack creates a new EventReplayAttack event.
 func NewEventReplayAttack(streamID string) EventReplayAttack {
 	return EventReplayAttack{
 		eventBase: eventBase{