Merge pull request #53 from RTradeLtd/rep-cli-doc

docs for replication cli

doc/REPLICATION_CLI.md

@@ -0,0 +1,101 @@
+# Replication CLI Documentation
+
+## Prepare a Versioned Replication File
+
+Here is an example minimum replication file:
+
+```yml
+topic: test rep
+author: 12D3KooWCTToC93Nsy2kqQroRtktzsJ4q5F1ymgR8XqHqje1RXNN
+version: 1
+redundancy: 2
+cids:
+- bafybeihykld7uyxzogax6vgyvag42y7464eywpf55gxi5qpoisibh3c5wa
+servers:
+- id: QmXtW5fXrrvmHWPhq3FLHdm4zKnC5FZdhTRynSQT57Yrmd
+  grpcport: 9094
+  addresses:
+  - /ip4/127.0.0.1/tcp/12345
+- id: QmRd2F8C6Nk49zjLmNCHKRzPaMUggEicJMw6tHX6DEe8VL
+  grpcport: 9094
+  addresses:
+  - /ip4/127.0.0.2/tcp/12345
+```
+
+The default location of this file is `replication.yml`, you can change it with the `--yml` flag of the `tex-cli rep sign` command.
+
+`topic` and `author` identifies a replication subscription. You can update a published replication by keeping those identifiers the same and increase the version number. The minimum allowed `version` is 1.
+
+`author` is the public key that is used to verify the authenticity of updates.
+
+`redundancy` specifies the number of desired servers to replicate to. It must be 2 or greater.
+
+`cids` is a list of contents the servers should replicate. The files should be already available on the IPFS network.
+
+`servers` is a list of protentional servers to replicate to. The number of servers must be equal or greater than redundancy. The servers are preferred by the order they appear in the list. To publish on a server, the author's public key must be whitelisted.
+
+## Providing the Private Key
+
+The private key is provided by the global config file given to `tex-cli`. You can generate this file by `tex-cli config gen`. By default, it will use the key in `node.private_key` in `config.yml`. Please keep it safe.
+
+## Sign and Publish Replication Changes
+
+Sign and publish is accomplished with the following command:
+
+```bash
+tex-cli rep sign
+```
+
+## Add an Author to a Server's Whitelist
+
+You can export your public key with the following command:
+
+```bash
+tex-cli rep export-public-key
+```
+
+Which will create a file named as your author id, such as `12D3KooWEdRfREmzv2NnVjaPAvCR9WAWnShgEcLTbrk7NLpqH7g3.publickey`.
+
+Copy this file to your server's whitelist folder and restart your server will add it to the white list.
+
+The whitelist folder is defined under `node.replication.white_list_location` of `config.yml`, which is `storage/replication/publishers` by default.
+
+## Check Server state
+
+To check the state of a replication use the following command:
+
+```bash
+tex-cli rep check
+```
+
+Sample Output:
+
+```
+server 0: active true, target 3, current 3
+server 1: active true, target 3, current 2
+```
+
+Where `active` is a server that is actively replicating. The number of active servers should be at `redundancy` or greater.
+
+`target` is the targeted version. This is the highest version the server knows about.
+
+`current` is the highest version the server have replicated. If this number is lower than `target`, then this server is retrieving the listed cids.
+
+
+## Common Error Conditions
+
+> private key does not sign author id, please use author id 12D3KooWCTToC93Nsy2kqQroRtktzsJ4q5F1ymgR8XqHqje1RXNN or using the correct private key
+
+Use the correct private key, or copy the author id to the `author` field of `replication.yml`.
+
+> rpc error: code = FailedPrecondition desc = Author 12D3KooWEdRfREmzv2NnVjaPAvCR9WAWnShgEcLTbrk7NLpqH7g3 not allowed to replicate on this server
+
+This author is not white listed on the server, to add it to the white list,  
+
+> an equal or greater version already exist on the network, you must change your replication version to greater than 1
+
+Increase the `version` field of `replication.yml`, or if no changes was made since last publish, you current version was already published on the network.
+
+> current version is stuck at 0 or other number lower than target
+
+Make sure the cids are availed on IPFS. You can upload the files directly to one of the replicating servers for best performance.

go/rep_addr_info_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 
 	"github.com/ipfs/go-cid"
-	libcryto "github.com/libp2p/go-libp2p-core/crypto"
+	libcrypto "github.com/libp2p/go-libp2p-core/crypto"
 	"github.com/libp2p/go-libp2p-core/peer"
 	"github.com/multiformats/go-multiaddr"
 )
@@ -55,8 +55,8 @@ func fatalOnError(t *testing.T, err error, msg ...interface{}) {
 }
 
 type keyPair struct {
-	priv libcryto.PrivKey
-	pub  libcryto.PubKey
+	priv libcrypto.PrivKey
+	pub  libcrypto.PubKey
 }
 
 var mockHostMap map[mockHostInfo]keyPair
@@ -72,7 +72,7 @@ func getMockHostKey(m mockHostInfo) keyPair {
 
 	k, ok := mockHostMap[m]
 	if !ok {
-		priv, pub, err := libcryto.GenerateECDSAKeyPair(rand.New(rand.NewSource(int64(m)))) //generate keys determinately for testing.
+		priv, pub, err := libcrypto.GenerateECDSAKeyPair(rand.New(rand.NewSource(int64(m)))) //generate keys deterministically for testing.
 		if err != nil {
 			panic(err)
 		}

go/rep_client.go

@@ -116,7 +116,7 @@ func (s *SimpleGRPCConnectionProvider) ConnectionToServer(a *AddrInfo) (*grpc.Cl
 			address = tcp.String()
 		} else {
 			//TODO: use libp2p port for grpc
-			return nil, errors.New("libp2p grpc transport not yet implemented")
+			return nil, errors.New("libp2p grpc transport not yet implemented, a dedicated grpc port is required.")
 		}
 		tlsConfig := s.tlsConfig.ReusableConfigForPeer(id)
 		opts := append(s.opts, grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)))
@@ -135,5 +135,5 @@ func (s *SimpleGRPCConnectionProvider) ConnectionToServer(a *AddrInfo) (*grpc.Cl
 		}
 		return cc, nil
 	}
-	return nil, fmt.Errorf("can not connect to: %v", a)
+	return nil, fmt.Errorf("can not connect to server after trying all addresses")
 }

go/rep_subscription.go

@@ -7,14 +7,14 @@ import (
 	"fmt"
 	"io"
 
-	libcryto "github.com/libp2p/go-libp2p-core/crypto"
+	libcrypto "github.com/libp2p/go-libp2p-core/crypto"
 	"github.com/libp2p/go-libp2p-core/peer"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 )
 
 //NewSignedSubscription creates a fully signed SignedSubscription with the given private key
-func NewSignedSubscription(topic string, version int64, r *Replication, key libcryto.PrivKey) (*SignedSubscription, error) {
+func NewSignedSubscription(topic string, version int64, r *Replication, key libcrypto.PrivKey) (*SignedSubscription, error) {
 	ss := &SignedSubscription{}
 	ss.SetTopic(topic)
 	ss.SetVersion(version)
@@ -131,7 +131,7 @@ func (ss *SignedSubscription) RemoveSignature() {
 }
 
 //Sign signs with the given private key
-func (ss *SignedSubscription) Sign(key libcryto.PrivKey) error {
+func (ss *SignedSubscription) Sign(key libcrypto.PrivKey) error {
 	if key == nil {
 		return errors.New("can not sign a subscription with a nil key")
 	}
@@ -187,7 +187,7 @@ func (ss *SignedSubscription) verificationData(buf []byte) []byte {
 }
 
 //Verify verifies the SignedSubscription against the provided public key.
-func (ss *SignedSubscription) Verify(pubkey libcryto.PubKey, strict bool) error {
+func (ss *SignedSubscription) Verify(pubkey libcrypto.PubKey, strict bool) error {
 	if haveUnrecognized(ss) {
 		return errors.New("SignedSubscription contains unrecognized data")
 	}

go/rep_subscription_test.go

@@ -4,7 +4,7 @@ import (
 	"reflect"
 	"testing"
 
-	libcryto "github.com/libp2p/go-libp2p-core/crypto"
+	libcrypto "github.com/libp2p/go-libp2p-core/crypto"
 )
 
 func TestNewSignedSubscription(t *testing.T) {
@@ -14,7 +14,7 @@ func TestNewSignedSubscription(t *testing.T) {
 		topic   string
 		version int64
 		r       *Replication
-		key     libcryto.PrivKey
+		key     libcrypto.PrivKey
 	}
 	tests := []struct {
 		name    string
@@ -50,7 +50,7 @@ func TestSignedSubscription_Verify(t *testing.T) {
 	tests := []struct {
 		name      string
 		editer    func(ss *SignedSubscription)
-		verifyKey libcryto.PubKey
+		verifyKey libcrypto.PubKey
 		wantErr   bool
 		strictErr bool
 	}{