Document copying of type instances

[cthulhu-rider]

Context

Struct type instances can be copied in two ways - Go assignment/passing to func or chan and dedicated methods (if provided). There are also two kinds of copying - shallow and deep. By default, shallow copying through assignment is expected by user if no particular methods or docs were provided.

Overview

It's unsafe to do shallow copy some of SDK message types through assignment (e.g. session.Token which was encountered in #193: direct copying was not prevented by docs, and no Copy method was provided, so mutability bug has been risen). We must protect the user from data corruption due to the mutability of copies.

Proposal

Explore copying safety of all SDK types, and prevent direct copying by adding corresponding type docs and methods:

// T ...
//
// T MUST NOT be copied by value: make a copy using `CopyTo` method.
//
// ...
type T struct { ... }

// CopyTo writes deep copy of the T to dst.
func (x T) CopyTo(dst *T) { ... }

[cthulhu-rider]

need only deep copy only, shallow copy can be done via :=