use std::error::Error;
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
use std::path::PathBuf;
use std::time::Duration;
use better_mimalloc_rs::MiMalloc;
use clap::{Args, Parser, Subcommand, ValueEnum};
use pb_mapper_auth::{
AuthConfig, KeyPage, LegacyProtocolPolicy, MAX_TEMP_KEY_CAPACITY, MAX_TEMP_KEY_TTL,
MIN_TEMP_KEY_TTL, acquire_state_dir_lock, discard_staged_admin_key, generate_admin_key,
initialize_admin_key, stage_admin_key_candidate, write_admin_key_file,
};
use pb_mapper_client::client::handle_status_cli_scoped;
use pb_mapper_client::sdk::{
Client, ConnectOptions, ConnectRequest, PathPolicy, RegisterOptions, RegisterRequest,
TunnelDiagnostics, TunnelStatus,
};
use pb_mapper_core::checksum::set_process_msg_header_key;
use pb_mapper_core::checksum::{MACHINE_MSG_HEADER_KEY_PATH, setup_machine_msg_header_key};
use pb_mapper_core::config::{
StatusOp, init_tracing, keep_alive_from_env, pb_mapper_server_addr,
resolve_pb_mapper_server_async,
};
use pb_mapper_protocol::command::{
AdminConnectionPage, AdminRequest, AdminResponse, AdminServicePage,
};
use pb_mapper_server::run_server_with_shutdown;
use tokio_util::sync::CancellationToken;
#[global_allocator]
static GLOBAL_MIMALLOC: MiMalloc = MiMalloc;
#[derive(Debug, Parser)]
#[command(
author = "L_B__",
version,
about = "Expose and consume keyed TCP/UDP services through a pb-mapper relay",
subcommand_required = true,
arg_required_else_help = true
)]
struct Cli {
#[command(subcommand)]
command: Command,
}
#[derive(Debug, Subcommand)]
enum Command {
Server(ServerArgs),
Register(RegisterArgs),
Connect(ConnectArgs),
Status(StatusArgs),
Admin(AdminArgs),
}
#[derive(Debug, Args)]
struct ServerArgs {
#[arg(short, long, visible_alias = "pb-mapper-port", default_value_t = 7666)]
port: u16,
#[arg(long, requires_all = ["direct_listen", "direct_advertise"])]
enable_direct: bool,
#[arg(long, requires = "enable_direct")]
direct_listen: Option<SocketAddr>,
#[arg(long, requires = "enable_direct")]
direct_advertise: Option<SocketAddr>,
#[arg(long, visible_alias = "use-ipv6", default_value_t = false)]
ipv6: bool,
#[arg(long, default_value_t = false)]
keep_alive: bool,
#[arg(long, default_value_t = false)]
use_machine_msg_header_key: bool,
#[arg(long)]
auth_state_dir: Option<PathBuf>,
#[arg(
long,
conflicts_with = "use_machine_msg_header_key",
default_value_t = false
)]
init_admin_key: bool,
#[arg(long, requires = "init_admin_key", default_value_t = false)]
force_init_admin_key: bool,
#[arg(long)]
max_temporary_keys: Option<usize>,
#[arg(long, value_parser = parse_duration)]
max_temporary_key_ttl: Option<Duration>,
#[arg(long, value_enum)]
legacy_protocol: Option<LegacyProtocolArg>,
}
#[path = "pb-mapper/admin.rs"]
mod admin;
use admin::AdminArgs;
#[derive(Debug, Args)]
struct RegisterArgs {
#[arg(long)]
allow_direct: bool,
#[arg(value_enum)]
transport: Transport,
#[arg(short, long)]
key: String,
#[arg(short, long, visible_alias = "local")]
addr: String,
#[command(flatten)]
relay: RelayArgs,
#[arg(short, long, default_value_t = false)]
codec: bool,
#[arg(long)]
namespace: Option<u64>,
#[arg(long, requires = "namespace", default_value_t = false)]
force: bool,
}
#[derive(Debug, Args)]
struct ConnectArgs {
#[arg(long, value_enum, default_value_t = PathArg::RelayOnly)]
path: PathArg,
#[arg(value_enum)]
transport: Transport,
#[arg(short, long)]
key: String,
#[arg(short, long, visible_alias = "local")]
addr: String,
#[command(flatten)]
relay: RelayArgs,
#[arg(long)]
namespace: Option<u64>,
}
#[derive(Debug, Args)]
struct StatusArgs {
#[arg(value_enum)]
op: StatusOp,
#[arg(short, long, visible_alias = "pb-mapper-server", value_name = "ADDR")]
server: Option<String>,
#[arg(long)]
namespace: Option<u64>,
}
#[derive(Debug, Args)]
struct RelayArgs {
#[arg(short, long, visible_alias = "pb-mapper-server", value_name = "ADDR")]
server: Option<String>,
#[arg(long, default_value_t = false)]
keep_alive: bool,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum PathArg {
RelayOnly,
Auto,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum Transport {
Tcp,
Udp,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum LegacyProtocolArg {
Allow,
Deny,
}
impl From<LegacyProtocolArg> for LegacyProtocolPolicy {
fn from(value: LegacyProtocolArg) -> Self {
match value {
LegacyProtocolArg::Allow => Self::Allow,
LegacyProtocolArg::Deny => Self::Deny,
}
}
}
#[tokio::main]
async fn main() {
MiMalloc::init();
let cli = Cli::parse();
init_tracing();
if let Err(error) = run(cli).await {
tracing::error!(%error, "pb-mapper command failed");
std::process::exit(1);
}
}
async fn run(cli: Cli) -> Result<(), Box<dyn Error>> {
match cli.command {
Command::Server(args) => run_server(args).await?,
Command::Register(args) => run_register(args).await?,
Command::Connect(args) => run_connect(args).await?,
Command::Status(args) => run_status(args).await?,
Command::Admin(args) => admin::run_admin(args).await?,
}
Ok(())
}
fn apply_server_auth_overrides(args: &ServerArgs) -> Result<(), Box<dyn Error>> {
if let Some(auth_state_dir) = &args.auth_state_dir {
unsafe { std::env::set_var("PB_MAPPER_AUTH_STATE_DIR", auth_state_dir) };
}
if let Some(max_temporary_keys) = args.max_temporary_keys {
if !(1..=MAX_TEMP_KEY_CAPACITY).contains(&max_temporary_keys) {
return Err(format!(
"`--max-temporary-keys` must be between 1 and {MAX_TEMP_KEY_CAPACITY}"
)
.into());
}
unsafe {
std::env::set_var(
"PB_MAPPER_AUTH_MAX_TEMP_KEYS",
max_temporary_keys.to_string(),
)
};
}
if let Some(max_temporary_key_ttl) = args.max_temporary_key_ttl {
if max_temporary_key_ttl < MIN_TEMP_KEY_TTL || max_temporary_key_ttl > MAX_TEMP_KEY_TTL {
return Err(format!(
"`--max-temporary-key-ttl` must be between {}s and {}d",
MIN_TEMP_KEY_TTL.as_secs(),
MAX_TEMP_KEY_TTL.as_secs() / 86_400
)
.into());
}
unsafe {
std::env::set_var(
"PB_MAPPER_AUTH_MAX_TEMP_TTL_SECS",
max_temporary_key_ttl.as_secs().to_string(),
)
};
}
Ok(())
}
async fn run_server(args: ServerArgs) -> Result<(), Box<dyn Error>> {
apply_server_auth_overrides(&args)?;
if let Some(legacy_protocol) = args.legacy_protocol {
unsafe {
std::env::set_var(
"PB_MAPPER_LEGACY_PROTOCOL",
match legacy_protocol {
LegacyProtocolArg::Allow => "allow",
LegacyProtocolArg::Deny => "deny",
},
)
};
}
let auth_config = AuthConfig::default();
if args.init_admin_key {
std::fs::create_dir_all(&auth_config.state_dir)?;
let _lock = acquire_state_dir_lock(&auth_config.state_dir)?;
let key_path = auth_config.state_dir.join("admin.key");
let key = initialize_admin_key(&key_path, args.force_init_admin_key)?;
drop(_lock);
set_process_msg_header_key(Some(&key))?;
eprintln!("administrator key initialized at {}", key_path.display());
} else if args.use_machine_msg_header_key {
let admin_key_path = auth_config.state_dir.join("admin.key");
if admin_key_path.exists() {
return Err(format!(
"--use-machine-msg-header-key cannot replace `{}`; use `pb-mapper admin root-key rotate` to change the root key",
admin_key_path.display()
)
.into());
}
tracing::warn!(
"--use-machine-msg-header-key is a legacy compatibility option; prefer a random administrator key"
);
setup_machine_msg_header_key()?;
tracing::info!(
path = MACHINE_MSG_HEADER_KEY_PATH,
"derived and persisted machine MSG_HEADER_KEY"
);
}
let ip_addr = if args.ipv6 {
IpAddr::V6(Ipv6Addr::UNSPECIFIED)
} else {
IpAddr::V4(Ipv4Addr::UNSPECIFIED)
};
let shutdown = CancellationToken::new();
let keep_alive = args.keep_alive || keep_alive_from_env();
if args.enable_direct {
let config = pb_mapper_server::DirectServerConfig {
listen: args.direct_listen.ok_or("--direct-listen is required")?,
advertise: args
.direct_advertise
.ok_or("--direct-advertise is required")?,
};
let auth = pb_mapper_auth::AuthRuntime::from_process(auth_config).await?;
let listener = tokio::net::TcpListener::bind((ip_addr, args.port)).await?;
pb_mapper_server::run_server_on_listener_with_direct(
listener,
shutdown,
None,
keep_alive,
auth,
Some(config),
)
.await?;
} else {
run_server_with_shutdown((ip_addr, args.port), shutdown, None, keep_alive).await?;
}
Ok(())
}
fn tunnel_client(relay: &RelayArgs, namespace: Option<u64>) -> Result<Client, Box<dyn Error>> {
let credential = pb_mapper_core::checksum::get_process_credential().map_err(|error| {
std::io::Error::other(format!("tunnel credential is required: {error}"))
})?;
Ok(Client::from_credential(
pb_mapper_server_addr(relay.server.as_deref())?,
credential,
relay.keep_alive || keep_alive_from_env(),
namespace,
))
}
fn sdk_transport(transport: Transport) -> pb_mapper_client::sdk::Transport {
match transport {
Transport::Tcp => pb_mapper_client::sdk::Transport::Tcp,
Transport::Udp => pb_mapper_client::sdk::Transport::Udp,
}
}
async fn run_register(args: RegisterArgs) -> Result<(), Box<dyn Error>> {
let client = tunnel_client(&args.relay, args.namespace)?;
let registration = client
.register_with_options(
RegisterRequest {
key: args.key,
local_addr: args.addr,
transport: sdk_transport(args.transport),
codec: args.codec,
force_namespace: args.force,
},
RegisterOptions {
allow_direct: args.allow_direct,
..Default::default()
},
)
.await?;
monitor_tunnel(registration.subscribe(), || registration.diagnostics()).await?;
registration.stop().await?;
Ok(())
}
async fn run_connect(args: ConnectArgs) -> Result<(), Box<dyn Error>> {
let client = tunnel_client(&args.relay, args.namespace)?;
let connection = client
.connect_with_options(
ConnectRequest {
key: args.key,
local_addr: args.addr,
transport: sdk_transport(args.transport),
},
ConnectOptions {
path: match args.path {
PathArg::RelayOnly => PathPolicy::RelayOnly,
PathArg::Auto => PathPolicy::Auto,
},
},
)
.await?;
monitor_tunnel(connection.subscribe(), || connection.diagnostics()).await?;
connection.stop().await?;
Ok(())
}
async fn monitor_tunnel(
mut status: tokio::sync::watch::Receiver<TunnelStatus>,
diagnostics: impl Fn() -> TunnelDiagnostics,
) -> Result<(), Box<dyn Error>> {
let mut interval = tokio::time::interval(Duration::from_secs(30));
interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
loop {
let state = status.borrow_and_update().clone();
match state {
TunnelStatus::Failed(reason) => return Err(std::io::Error::other(reason).into()),
TunnelStatus::Stopped => return Ok(()),
_ => {}
}
tokio::select! {
result = tokio::signal::ctrl_c() => { result?; return Ok(()); },
result = status.changed() => { if result.is_err() { return Ok(()); } },
_ = interval.tick() => {
let snapshot = diagnostics();
tracing::info!(event = "tunnel_diagnostics", status = ?state, diagnostics = %serde_json::to_string(&snapshot)?, "tunnel recovery snapshot");
},
}
}
}
async fn run_status(args: StatusArgs) -> Result<(), Box<dyn Error>> {
let remote_addr = resolve_pb_mapper_server_async(args.server.as_deref()).await?;
handle_status_cli_scoped(args.op, remote_addr.as_slice(), args.namespace).await
}
fn parse_duration(raw: &str) -> Result<Duration, String> {
let raw = raw.trim();
if raw.is_empty() {
return Err("duration must not be empty".to_string());
}
let split = raw
.find(|character: char| !character.is_ascii_digit())
.unwrap_or(raw.len());
let (number, unit) = raw.split_at(split);
let value = number
.parse::<u64>()
.map_err(|_| format!("invalid duration `{raw}`"))?;
let multiplier = match unit {
"" | "s" => 1,
"m" => 60,
"h" => 60 * 60,
"d" => 24 * 60 * 60,
_ => {
return Err(format!(
"unsupported duration unit `{unit}`; use s, m, h, or d"
));
}
};
value
.checked_mul(multiplier)
.map(Duration::from_secs)
.ok_or_else(|| "duration is too large".to_string())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_each_runtime_role() {
let cases = [
vec!["pb-mapper", "server", "--port", "7666", "--ipv6"],
vec![
"pb-mapper",
"register",
"tcp",
"--key",
"web",
"--addr",
"127.0.0.1:8080",
"--server",
"relay:7666",
"--codec",
],
vec![
"pb-mapper",
"connect",
"udp",
"--key",
"game",
"--addr",
"127.0.0.1:8211",
"--server",
"relay:7666",
],
vec!["pb-mapper", "status", "keys", "--server", "relay:7666"],
vec![
"pb-mapper",
"admin",
"--server",
"relay:7666",
"key",
"issue",
"--ttl",
"30d",
"--label",
"build-agent",
],
vec![
"pb-mapper",
"admin",
"--output",
"ndjson",
"connection",
"list",
"--page-size",
"1000",
"--all",
],
vec![
"pb-mapper",
"admin",
"root-key",
"rotate",
"--key-file",
"/tmp/pb-mapper-admin.key",
],
];
for args in cases {
Cli::try_parse_from(args).expect("unified command should parse");
}
}
#[test]
fn accepts_documented_option_aliases() {
Cli::try_parse_from([
"pb-mapper",
"server",
"--pb-mapper-port",
"7666",
"--use-ipv6",
])
.expect("server aliases should parse");
Cli::try_parse_from([
"pb-mapper",
"register",
"tcp",
"--key",
"web",
"--local",
"127.0.0.1:8080",
"--pb-mapper-server",
"relay:7666",
])
.expect("relay and local aliases should parse");
Cli::try_parse_from([
"pb-mapper",
"register",
"tcp",
"--key",
"web",
"--addr",
"127.0.0.1:8080",
"--namespace",
"4294967296",
"--force",
])
.expect("administrator namespace registration flags should parse");
}
#[test]
fn rejects_invalid_admin_paging_and_duration() {
assert!(
Cli::try_parse_from(["pb-mapper", "admin", "key", "list", "--page-size", "1001",])
.is_err()
);
assert!(
Cli::try_parse_from(["pb-mapper", "admin", "key", "issue", "--ttl", "1fortnight",])
.is_err()
);
assert!(
Cli::try_parse_from([
"pb-mapper",
"server",
"--init-admin-key",
"--use-machine-msg-header-key",
])
.is_err()
);
}
#[test]
fn server_auth_options_only_override_environment_when_explicit() {
let cli =
Cli::try_parse_from(["pb-mapper", "server"]).expect("server defaults should parse");
let Command::Server(defaults) = cli.command else {
panic!("expected server command");
};
assert_eq!(defaults.auth_state_dir, None);
assert_eq!(defaults.max_temporary_keys, None);
assert_eq!(defaults.max_temporary_key_ttl, None);
assert_eq!(defaults.legacy_protocol, None);
let cli = Cli::try_parse_from([
"pb-mapper",
"server",
"--auth-state-dir",
"/tmp/pb-mapper-auth",
"--max-temporary-keys",
"1024",
"--max-temporary-key-ttl",
"2h",
"--legacy-protocol",
"deny",
])
.expect("explicit server authentication options should parse");
let Command::Server(explicit) = cli.command else {
panic!("expected server command");
};
assert_eq!(
explicit.auth_state_dir,
Some(PathBuf::from("/tmp/pb-mapper-auth"))
);
assert_eq!(explicit.max_temporary_keys, Some(1024));
assert_eq!(
explicit.max_temporary_key_ttl,
Some(Duration::from_secs(2 * 60 * 60))
);
assert_eq!(explicit.legacy_protocol, Some(LegacyProtocolArg::Deny));
}
#[test]
fn explicit_out_of_range_server_auth_flags_are_rejected() {
let cli = Cli::try_parse_from(["pb-mapper", "server", "--max-temporary-keys", "0"])
.expect("clap should accept the token before bounds checking");
let Command::Server(args) = cli.command else {
panic!("expected server command");
};
let error = apply_server_auth_overrides(&args).unwrap_err();
assert!(error.to_string().contains("--max-temporary-keys"));
let cli = Cli::try_parse_from(["pb-mapper", "server", "--max-temporary-key-ttl", "5s"])
.expect("clap should accept the token before bounds checking");
let Command::Server(args) = cli.command else {
panic!("expected server command");
};
let error = apply_server_auth_overrides(&args).unwrap_err();
assert!(error.to_string().contains("--max-temporary-key-ttl"));
}
}