Skip to content
Snippets Groups Projects
Commit b144a821 authored by Jono Wenger's avatar Jono Wenger
Browse files

Merge branch 'XX-4125/TrackServicesCallbackImproveDocs' into 'release' 

XX-4125 / Fix Ambiguous documentation for TrackServicesCallback

See merge request !362
parents 57b7e3b8 60099808
No related branches found
No related tags found
3 merge requests!510Release,!362XX-4125 / Fix Ambiguous documentation for TrackServicesCallback,!354Channels impl
Hide whitespace changes
Inline Side-by-side
bindings/follow.go
+ 52
− 49
View file @ b144a821
......@@ -27,29 +27,28 @@ import (
// they are stopped if there is no internet access.
//
// Threads Started:
// - Network Follower (/network/follow.go)
// tracks the network events and hands them off to workers for handling.
// - Historical Round Retrieval (/network/rounds/historical.go)
// retrieves data about rounds that are too old to be stored by the client.
// - Message Retrieval Worker Group (/network/rounds/retrieve.go)
// requests all messages in a given round from the gateway of the last
// nodes.
// - Message Handling Worker Group (/network/message/handle.go)
// decrypts and partitions messages when signals via the Switchboard.
// - Health Tracker (/network/health),
// via the network instance, tracks the state of the network.
// - Garbled Messages (/network/message/garbled.go)
// can be signaled to check all recent messages that could be decoded. It
// uses a message store on disk for persistence.
// - Critical Messages (/network/message/critical.go)
// ensures all protocol layer mandatory messages are sent. It uses a message
// store on disk for persistence.
// - KeyExchange Trigger (/keyExchange/trigger.go)
// responds to sent rekeys and executes them.
// - KeyExchange Confirm (/keyExchange/confirm.go)
// responds to confirmations of successful rekey operations.
// - Auth Callback (/auth/callback.go)
// handles both auth confirm and requests.
// - Network Follower (/network/follow.go)
// tracks the network events and hands them off to workers for handling.
// - Historical Round Retrieval (/network/rounds/historical.go)
// retrieves data about rounds that are too old to be stored by the client.
// - Message Retrieval Worker Group (/network/rounds/retrieve.go)
// requests all messages in a given round from the gateway of the last nodes.
// - Message Handling Worker Group (/network/message/handle.go)
// decrypts and partitions messages when signals via the Switchboard.
// - Health Tracker (/network/health),
// via the network instance, tracks the state of the network.
// - Garbled Messages (/network/message/garbled.go)
// can be signaled to check all recent messages that could be decoded. It
// uses a message store on disk for persistence.
// - Critical Messages (/network/message/critical.go)
// ensures all protocol layer mandatory messages are sent. It uses a message
// store on disk for persistence.
// - KeyExchange Trigger (/keyExchange/trigger.go)
// responds to sent rekeys and executes them.
// - KeyExchange Confirm (/keyExchange/confirm.go)
// responds to confirmations of successful rekey operations.
// - Auth Callback (/auth/callback.go)
// handles both auth confirm and requests.
func (c *Cmix) StartNetworkFollower(timeoutMS int) error {
timeout := time.Duration(timeoutMS) * time.Millisecond
return c.api.StartNetworkFollower(timeout)
......@@ -170,35 +169,39 @@ func (c *Cmix) RegisterClientErrorCallback(clientError ClientError) {
}()
}
// TrackServicesCallback is the callback for Cmix.TrackServices.
// TrackServicesCallback is the callback for [Cmix.TrackServices].
// This will pass to the user a JSON-marshalled list of backend services.
// If there was an error retrieving or marshalling the service list,
// there is an error for the second parameter which will be non-null.
//
// Example JSON:
// Parameters:
// - marshalData - JSON marshalled bytes of [message.ServiceList], which is an
// array of [id.ID] and [message.Service].
// - err - JSON unmarshalling error
//
// [
// {
// "Id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD",
// "Services": [
// {
// "Identifier": null,
// "Tag": "test",
// "Metadata": null
// }
// ]
// },
// {
// "Id": "AAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD",
// "Services": [
// {
// "Identifier": null,
// "Tag": "test",
// "Metadata": null
// }
// ]
// },
//]
// Example JSON:
// [
// {
// "Id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD", // bytes of id.ID encoded as base64 string
// "Services": [
// {
// "Identifier": "AQID", // bytes encoded as base64 string
// "Tag": "TestTag 1", // string
// "Metadata": "BAUG" // bytes encoded as base64 string
// }
// ]
// },
// {
// "Id": "AAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD",
// "Services": [
// {
// "Identifier": "AQID",
// "Tag": "TestTag 2",
// "Metadata": "BAUG"
// }
// ]
// },
// ]
type TrackServicesCallback interface {
Callback(marshalData []byte, err error)
}
......@@ -209,8 +212,8 @@ type TrackServicesCallback interface {
// may need context on the available services for this client.
//
// Parameters:
// - cb - A TrackServicesCallback, which will be passed the marshalled
// message.ServiceList.
// - cb - A TrackServicesCallback, which will be passed the marshalled
// message.ServiceList.
func (c *Cmix) TrackServices(cb TrackServicesCallback) {
c.api.GetCmix().TrackServices(func(list message.ServiceList) {
cb.Callback(json.Marshal(list))
......
bindings/notifications.go
+ 38
− 38
View file @ b144a821
......@@ -13,58 +13,58 @@ import (
"gitlab.com/elixxir/primitives/notifications"
)
// NotificationReports is a list of NotificationReport's. This will be returned
// NotificationReports is a list of [NotificationReport]s. This will be returned
// via GetNotificationsReport as a JSON marshalled byte data.
//
// Example JSON:
//
// [
// {
// "ForMe": true,
// "Type": "e2e",
// "Source": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
// },
// {
// "ForMe": true,
// "Type": "e2e",
// "Source": "AAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
// },
// {
// "ForMe": true,
// "Type": "e2e",
// "Source": "AAAAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
// }
//]
// [
// {
// "ForMe": true, // boolean
// "Type": "e2e", // string
// "Source": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD" // bytes of id.ID encoded as base64 string
// },
// {
// "ForMe": true,
// "Type": "e2e",
// "Source": "AAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
// },
// {
// "ForMe": true,
// "Type": "e2e",
// "Source": "AAAAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD"
// }
// ]
type NotificationReports []NotificationReport
// TODO: The table in the docstring below needs to be checked for completeness
// and/or accuracy to ensure descriptions/sources are still accurate (they are
// from the old implementation).
// NotificationReport is the bindings' representation for notifications for
// this user.
//
// Example NotificationReport JSON:
//
// {
// "ForMe": true,
// "Type": "e2e",
// "Source": "dGVzdGVyMTIzAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
//}
// {
// "ForMe": true,
// "Type": "e2e",
// "Source": "dGVzdGVyMTIzAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
// }
//
// Given the Type, the Source value will have specific contextual meanings.
// Below is a table that will define the contextual meaning of the Source field
// given all possible Type fields.
//
// TYPE | SOURCE | DESCRIPTION
// ________________________________________________________________________________________
// "default" | recipient user ID | A message with no association.
// "request" | sender user ID | A channel request has been received, from Source.
// "reset" | sender user ID | A channel reset has been received.
// "confirm" | sender user ID | A channel request has been accepted.
// "silent" | sender user ID | A message where the user should not be notified.
// "e2e" | sender user ID | A reception of an E2E message.
// "group" | group ID | A reception of a group chat message.
// "endFT" | sender user ID | The last message sent confirming end of file transfer.
// "groupRQ" | sender user ID | A request from Source to join a group chat.
// todo iterate over this docstring, ensure descriptions/sources are
// still accurate (they are from the old implementation
// TYPE | SOURCE | DESCRIPTION
// ----------+--------------------+--------------------------------------------------------
// "default" | recipient user ID | A message with no association.
// "request" | sender user ID | A channel request has been received, from Source.
// "reset" | sender user ID | A channel reset has been received.
// "confirm" | sender user ID | A channel request has been accepted.
// "silent" | sender user ID | A message where the user should not be notified.
// "e2e" | sender user ID | A reception of an E2E message.
// "group" | group ID | A reception of a group chat message.
// "endFT" | sender user ID | The last message sent confirming end of file transfer.
// "groupRQ" | sender user ID | A request from Source to join a group chat.
type NotificationReport struct {
// ForMe determines whether this value is for the user. If it is
// false, this report may be ignored.
......
xxdk/cmix.go
+ 22
− 23
View file @ b144a821
......@@ -340,29 +340,28 @@ func (c *Cmix) GetErrorsChannel() <-chan interfaces.ClientError {
// they are stopped if there is no internet access.
//
// Threads Started:
// - Network Follower (/network/follow.go)
// tracks the network events and hands them off to workers for handling.
// - Historical Round Retrieval (/network/rounds/historical.go)
// retrieves data about rounds that are too old to be stored by the client.
// - Message Retrieval Worker Group (/network/rounds/retrieve.go)
// requests all messages in a given round from the gateway of the last
// nodes.
// - Message Handling Worker Group (/network/message/handle.go)
// decrypts and partitions messages when signals via the Switchboard.
// - Health Tracker (/network/health),
// via the network instance, tracks the state of the network.
// - Garbled Messages (/network/message/garbled.go)
// can be signaled to check all recent messages that could be decoded. It
// uses a message store on disk for persistence.
// - Critical Messages (/network/message/critical.go)
// ensures all protocol layer mandatory messages are sent. It uses a
// message store on disk for persistence.
// - KeyExchange Trigger (/keyExchange/trigger.go)
// responds to sent rekeys and executes them.
// - KeyExchange Confirm (/keyExchange/confirm.go)
// responds to confirmations of successful rekey operations.
// - Auth Callback (/auth/callback.go)
// handles both auth confirm and requests.
// - Network Follower (/network/follow.go)
// tracks the network events and hands them off to workers for handling.
// - Historical Round Retrieval (/network/rounds/historical.go)
// retrieves data about rounds that are too old to be stored by the client.
// - Message Retrieval Worker Group (/network/rounds/retrieve.go)
// requests all messages in a given round from the gateway of the last nodes.
// - Message Handling Worker Group (/network/message/handle.go)
// decrypts and partitions messages when signals via the Switchboard.
// - Health Tracker (/network/health),
// via the network instance, tracks the state of the network.
// - Garbled Messages (/network/message/garbled.go)
// can be signaled to check all recent messages that could be decoded. It
// uses a message store on disk for persistence.
// - Critical Messages (/network/message/critical.go)
// ensures all protocol layer mandatory messages are sent. It uses a message
// store on disk for persistence.
// - KeyExchange Trigger (/keyExchange/trigger.go)
// responds to sent rekeys and executes them.
// - KeyExchange Confirm (/keyExchange/confirm.go)
// responds to confirmations of successful rekey operations.
// - Auth Callback (/auth/callback.go)
// handles both auth confirm and requests.
func (c *Cmix) StartNetworkFollower(timeout time.Duration) error {
jww.INFO.Printf(
"StartNetworkFollower() \n\tTransmissionID: %s \n\tReceptionID: %s",
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment