From 82a29bf6e5bf3f0d616b3214db02eb063d7a15b4 Mon Sep 17 00:00:00 2001
From: Alex Auvolat <alex@adnab.me>
Date: Tue, 16 Jan 2024 14:04:11 +0100
Subject: [PATCH] help, comments: make clear that full-length node ID = public
 key

Generally, avoid using the "public key" terminology
---
 src/garage/cli/init.rs    | 2 +-
 src/garage/cli/structs.rs | 8 +++++---
 src/garage/main.rs        | 7 +++----
 src/rpc/consul.rs         | 2 +-
 src/rpc/system.rs         | 2 +-
 5 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/src/garage/cli/init.rs b/src/garage/cli/init.rs
index 20813f1c..43ca5c09 100644
--- a/src/garage/cli/init.rs
+++ b/src/garage/cli/init.rs
@@ -43,7 +43,7 @@ pub fn node_id_command(config_file: PathBuf, quiet: bool) -> Result<(), Error> {
 			idstr
 		);
 		eprintln!(
-			"where <remote_node> is their own node identifier in the format: <pubkey>@<ip>:<port>"
+			"where <remote_node> is their own node identifier in the format: <full-node-id>@<ip>:<port>"
 		);
 		eprintln!();
 		eprintln!("This node identifier can also be added as a bootstrap node in other node's garage.toml files:");
diff --git a/src/garage/cli/structs.rs b/src/garage/cli/structs.rs
index aba57551..be4d5bd6 100644
--- a/src/garage/cli/structs.rs
+++ b/src/garage/cli/structs.rs
@@ -64,7 +64,8 @@ pub enum Command {
 
 #[derive(StructOpt, Debug)]
 pub enum NodeOperation {
-	/// Print identifier (public key) of this Garage node
+	/// Print the full node ID (public key) of this Garage node, and its publicly reachable IP
+	/// address and port if they are specified in config file under `rpc_public_addr`
 	#[structopt(name = "id", version = garage_version())]
 	NodeId(NodeIdOpt),
 
@@ -82,8 +83,9 @@ pub struct NodeIdOpt {
 
 #[derive(StructOpt, Debug)]
 pub struct ConnectNodeOpt {
-	/// Node public key and address, in the format:
-	/// `<public key hexadecimal>@<ip or hostname>:<port>`
+	/// Full node ID (public key) and IP address and port, in the format:
+	/// `<full node ID>@<ip or hostname>:<port>`.
+	/// You can retrieve this information on the target node using `garage node id`.
 	pub(crate) node: String,
 }
 
diff --git a/src/garage/main.rs b/src/garage/main.rs
index 9f9eefed..5c92dae4 100644
--- a/src/garage/main.rs
+++ b/src/garage/main.rs
@@ -46,8 +46,7 @@ use secrets::Secrets;
 	about = "S3-compatible object store for self-hosted geo-distributed deployments"
 )]
 struct Opt {
-	/// Host to connect to for admin operations, in the format:
-	/// <public-key>@<ip>:<port>
+	/// Host to connect to for admin operations, in the format: <full-node-id>@<ip>:<port>
 	#[structopt(short = "h", long = "rpc-host", env = "GARAGE_RPC_HOST")]
 	pub rpc_host: Option<String>,
 
@@ -201,7 +200,7 @@ async fn cli_command(opt: Opt) -> Result<(), Error> {
 
 	// Find and parse the address of the target host
 	let (id, addr, is_default_addr) = if let Some(h) = opt.rpc_host {
-		let (id, addrs) = parse_and_resolve_peer_addr(&h).ok_or_else(|| format!("Invalid RPC remote node identifier: {}. Expected format is <pubkey>@<IP or hostname>:<port>.", h))?;
+		let (id, addrs) = parse_and_resolve_peer_addr(&h).ok_or_else(|| format!("Invalid RPC remote node identifier: {}. Expected format is <full node id>@<IP or hostname>:<port>.", h))?;
 		(id, addrs[0], false)
 	} else {
 		let node_id = garage_rpc::system::read_node_id(&config.as_ref().unwrap().metadata_dir)
@@ -231,7 +230,7 @@ async fn cli_command(opt: Opt) -> Result<(), Error> {
 				addr
 			);
 		}
-		Err(e).err_context("Unable to connect to destination RPC host. Check that you are using the same value of rpc_secret as them, and that you have their correct public key.")?;
+		Err(e).err_context("Unable to connect to destination RPC host. Check that you are using the same value of rpc_secret as them, and that you have their correct full-length node ID (public key).")?;
 	}
 
 	let system_rpc_endpoint = netapp.endpoint::<SystemRpc, ()>(SYSTEM_RPC_PATH.into());
diff --git a/src/rpc/consul.rs b/src/rpc/consul.rs
index ab8d1112..71fd71b0 100644
--- a/src/rpc/consul.rs
+++ b/src/rpc/consul.rs
@@ -148,7 +148,7 @@ impl ConsulDiscovery {
 				ret.push((pubkey, SocketAddr::new(ip, ent.service_port)));
 			} else {
 				warn!(
-					"Could not process node spec from Consul: {:?} (invalid IP or public key)",
+					"Could not process node spec from Consul: {:?} (invalid IP address or node ID/pubkey)",
 					ent
 				);
 			}
diff --git a/src/rpc/system.rs b/src/rpc/system.rs
index 4b40bec4..4cec369b 100644
--- a/src/rpc/system.rs
+++ b/src/rpc/system.rs
@@ -57,7 +57,7 @@ pub const SYSTEM_RPC_PATH: &str = "garage_rpc/membership.rs/SystemRpc";
 pub enum SystemRpc {
 	/// Response to successfull advertisements
 	Ok,
-	/// Request to connect to a specific node (in <pubkey>@<host>:<port> format)
+	/// Request to connect to a specific node (in <pubkey>@<host>:<port> format, pubkey = full-length node ID)
 	Connect(String),
 	/// Ask other node its cluster layout. Answered with AdvertiseClusterLayout
 	PullClusterLayout,