mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 07:16:38 +03:00
309 lines
16 KiB
Python
309 lines
16 KiB
Python
"""Argument parsing and output for the standard-library Control API client."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import json
|
|
import sys
|
|
from dataclasses import asdict
|
|
from pathlib import Path
|
|
|
|
if __package__:
|
|
from .telemt_api import TelemtAPI, TelemtAPIError, USER_FIELDS, _positive_seconds
|
|
else:
|
|
from telemt_api import TelemtAPI, TelemtAPIError, USER_FIELDS, _positive_seconds
|
|
|
|
|
|
READ_COMMANDS = {
|
|
"health": "health", "ready": "health_ready", "capabilities": "capabilities",
|
|
"access-policy": "access_policy", "schema": "config_schema", "config": "get_config", "info": "system_info",
|
|
"status": "runtime_gates", "init": "runtime_initialization", "limits": "limits_effective",
|
|
"posture": "security_posture", "whitelist": "security_whitelist", "summary": "stats_summary",
|
|
"zero": "stats_zero_all", "upstreams": "stats_upstreams", "minimal": "stats_minimal_all",
|
|
"me-writers": "stats_me_writers", "dcs": "stats_dcs", "me-pool": "runtime_me_pool_state",
|
|
"me-quality": "runtime_me_quality", "upstream-quality": "runtime_upstream_quality",
|
|
"nat-stun": "runtime_nat_stun", "me-selftest": "runtime_me_selftest",
|
|
"connections": "runtime_connections_summary", "users": "list_users",
|
|
"quota": "users_quota", "active-ips": "users_active_ips", "web-status": "web_status",
|
|
}
|
|
USER_OPTIONS = {
|
|
"--secret": ("secret", str), "--ad-tag": ("user_ad_tag", str),
|
|
"--max-conns": ("max_tcp_conns", int), "--expires": ("expiration_rfc3339", str),
|
|
"--quota": ("data_quota_bytes", int), "--max-ips": ("max_unique_ips", int),
|
|
"--quota-period": ("quota_period", str), "--rate-up": ("rate_limit_up_bps", int),
|
|
"--rate-down": ("rate_limit_down_bps", int),
|
|
}
|
|
|
|
|
|
def _seconds(value):
|
|
try:
|
|
return _positive_seconds(float(value), "timeout/interval")
|
|
except ValueError as error:
|
|
raise argparse.ArgumentTypeError(str(error)) from error
|
|
|
|
|
|
def _poll_args(parser, optional=False):
|
|
if optional:
|
|
parser.add_argument("--wait", action="store_true", help="Poll this accepted operation to a terminal state")
|
|
parser.add_argument("--wait-timeout", type=_seconds, default=60, help="Polling budget in seconds (default: 60)")
|
|
parser.add_argument("--poll-interval", type=_seconds, default=0.25)
|
|
|
|
|
|
def _reload_args(parser, submission=False):
|
|
parser.add_argument("--mode" if submission else "--reload", choices=("instant", "drain"),
|
|
default="instant" if submission else None)
|
|
parser.add_argument("--timeout-secs", type=int, help="Server drain deadline, 1..3600; forbidden for instant")
|
|
parser.add_argument("--failure-policy", choices=("keep_new", "rollback"))
|
|
|
|
|
|
def build_parser():
|
|
# SUPPRESS lets common options appear before or after a command without a
|
|
# subparser default overwriting a value already supplied to the root parser.
|
|
common = argparse.ArgumentParser(add_help=False, argument_default=argparse.SUPPRESS)
|
|
common.add_argument("-u", "--url", help="API base URL (default: http://127.0.0.1:9091)")
|
|
common.add_argument("-a", "--auth", help="Exact Authorization header value")
|
|
common.add_argument("-t", "--timeout", type=_seconds, help="Socket timeout in seconds (default: 10)")
|
|
common.add_argument("--if-match", help="Optional source revision for mutations/preflight")
|
|
common.add_argument("--json-output", action="store_true", help="Print one JSON envelope including http_status")
|
|
parser = argparse.ArgumentParser(prog="telemt_api.py", parents=[common],
|
|
description="Telemt Control API CLI. JSON input uses a file or '-' for stdin.",
|
|
epilog="Config/user outputs may contain credentials. See docs/Architecture/API/PYTHON_CLIENT.md.")
|
|
commands = parser.add_subparsers(dest="command")
|
|
def command(name, **options):
|
|
return commands.add_parser(name, parents=[common], **options)
|
|
command("help", help="Show available commands")
|
|
command("gen-secret", help="Generate a new 32-hex secret locally")
|
|
for name, method in READ_COMMANDS.items():
|
|
command(name, help=method.replace("_", " "))
|
|
for name in ("events", "tls-fingerprints"):
|
|
command(name).add_argument("--limit", type=int)
|
|
command("config-state").add_argument("--sections", help="Comma-separated section names; omission selects all")
|
|
for name in ("config-patch", "validate"):
|
|
sub = command(name)
|
|
sub.add_argument("--json", required=True, metavar="FILE", help="Sparse config object; '-' reads stdin")
|
|
sub.add_argument("--if-runtime-match", help="Publication token from state or preflight")
|
|
_reload_args(sub)
|
|
if name == "config-patch":
|
|
_poll_args(sub, optional=True)
|
|
sub = command("access-policy-patch")
|
|
sub.add_argument("--json", required=True, metavar="FILE")
|
|
sub.add_argument("--if-runtime-match")
|
|
sub = command("reload")
|
|
_reload_args(sub, submission=True)
|
|
_poll_args(sub, optional=True)
|
|
for name in ("reload-status", "reload-wait"):
|
|
sub = command(name)
|
|
sub.add_argument("reload_id", type=int)
|
|
if name == "reload-wait":
|
|
_poll_args(sub)
|
|
sub.add_argument("--expected-revision", help="Accepted operation's config_revision")
|
|
for name in ("user", "create", "patch", "delete", "secret", "enable", "disable", "reset-quota"):
|
|
sub = command(name)
|
|
sub.add_argument("username")
|
|
if name in ("create", "patch"):
|
|
for option, (field, kind) in USER_OPTIONS.items():
|
|
sub.add_argument(option, dest=field, type=kind, default=argparse.SUPPRESS,
|
|
**({"choices": ("daily", "weekly", "monthly")} if field == "quota_period" else {}))
|
|
deny = sub.add_mutually_exclusive_group()
|
|
deny.add_argument("--source-deny", action="append", default=argparse.SUPPRESS, metavar="CIDR",
|
|
help="Replace the source deny list (repeat for multiple CIDRs); generation reload required")
|
|
if name == "create":
|
|
deny.add_argument("--clear-source-deny", dest="source_deny", action="store_const", const=None,
|
|
default=argparse.SUPPRESS, help="Remove a retained rule when recreating this username")
|
|
enabled = sub.add_mutually_exclusive_group()
|
|
enabled.add_argument("--enabled", dest="enabled", action="store_const", const=True, default=argparse.SUPPRESS)
|
|
enabled.add_argument("--disabled", dest="enabled", action="store_const", const=False, default=argparse.SUPPRESS)
|
|
if name == "patch":
|
|
sub.add_argument("--json", metavar="FILE", help="Exact sparse object; cannot be combined with field options")
|
|
sub.add_argument("--clear", action="append", choices=sorted(USER_FIELDS - {"secret"}), default=[],
|
|
help="Send JSON null for one field (repeatable)")
|
|
if name == "secret":
|
|
sub.add_argument("--secret", help="32 hex characters; omission asks the server to generate a secret")
|
|
sub = command("web-sessions")
|
|
sub.add_argument("--limit", type=int)
|
|
for name in ("cursor", "session-ref", "ip", "host", "user", "user-agent-id", "key-id", "carrier", "state"):
|
|
sub.add_argument("--" + name)
|
|
command("web-session").add_argument("session_ref")
|
|
for name in ("web-operation", "web-wait", "web-drain-wait"):
|
|
sub = command(name)
|
|
sub.add_argument("operation_id")
|
|
if name != "web-operation":
|
|
_poll_args(sub)
|
|
if name == "web-drain-wait":
|
|
sub.add_argument("--runtime-instance", required=True)
|
|
for name in ("web-close", "web-debug-clear", "web-learning-reset", "web-pause", "web-drain", "web-resume"):
|
|
sub = command(name)
|
|
sub.add_argument("--runtime-instance", required=True, help="Exact process reference copied from WEB status")
|
|
if name == "web-close":
|
|
sub.add_argument("--selector", required=True, metavar="FILE", help="refs/filter/all selector JSON, or '-' for stdin")
|
|
_poll_args(sub, optional=True)
|
|
if name == "web-drain":
|
|
sub.add_argument("--timeout-secs", required=True, type=int)
|
|
_poll_args(sub, optional=True)
|
|
return parser
|
|
|
|
|
|
def _json_file(path):
|
|
data = json.loads(sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8"))
|
|
if not isinstance(data, dict):
|
|
raise ValueError("JSON input must be an object")
|
|
return data
|
|
|
|
|
|
def _response_field(response, *keys):
|
|
value = response.data
|
|
for key in keys:
|
|
if not isinstance(value, dict) or key not in value:
|
|
raise TelemtAPIError("Missing operation metadata", code="invalid_response", last_response=response)
|
|
value = value[key]
|
|
return value
|
|
|
|
|
|
def _wait_reload(api, response, accepted, options):
|
|
if not isinstance(accepted, dict) or not isinstance(accepted.get("config_revision"), str) or isinstance(accepted.get("reload_id"), bool) or not isinstance(accepted.get("reload_id"), int):
|
|
raise TelemtAPIError("Invalid accepted reload metadata", code="invalid_response", last_response=response)
|
|
return api.wait_reload(accepted["reload_id"], expected_revision=accepted["config_revision"], **options)
|
|
|
|
|
|
def _dispatch(api, args):
|
|
command = args.command
|
|
revision = getattr(args, "if_match", None)
|
|
wait_options = {"timeout": getattr(args, "wait_timeout", 60), "poll_interval": getattr(args, "poll_interval", 0.25)}
|
|
if command in READ_COMMANDS:
|
|
return getattr(api, READ_COMMANDS[command])()
|
|
if command in ("events", "tls-fingerprints"):
|
|
method = api.runtime_events_recent if command == "events" else api.runtime_tls_fingerprints
|
|
return method(args.limit)
|
|
if command == "config-state":
|
|
return api.config_state(args.sections.split(",") if args.sections is not None else None)
|
|
if command in ("config-patch", "validate"):
|
|
method = api.patch_config if command == "config-patch" else api.validate_config
|
|
response = method(_json_file(args.json), if_match=revision, if_runtime_match=args.if_runtime_match,
|
|
reload=args.reload, timeout_secs=args.timeout_secs, failure_policy=args.failure_policy)
|
|
accepted = response.data.get("reload") if isinstance(response.data, dict) else None
|
|
if getattr(args, "wait", False) and accepted:
|
|
return _wait_reload(api, response, accepted, wait_options)
|
|
if getattr(args, "wait", False) and response.http_status == 202:
|
|
raise TelemtAPIError("Accepted config patch lacks reload metadata", code="invalid_response", last_response=response)
|
|
return response
|
|
if command == "access-policy-patch":
|
|
return api.patch_access_policy(_json_file(args.json), if_match=revision,
|
|
if_runtime_match=args.if_runtime_match)
|
|
if command == "reload":
|
|
response = api.reload(args.mode, timeout_secs=args.timeout_secs, failure_policy=args.failure_policy, if_match=revision)
|
|
if args.wait:
|
|
return _wait_reload(api, response, response.data, wait_options)
|
|
return response
|
|
if command == "reload-status":
|
|
return api.reload_status(args.reload_id)
|
|
if command == "reload-wait":
|
|
return api.wait_reload(args.reload_id, expected_revision=args.expected_revision, **wait_options)
|
|
if command == "user":
|
|
return api.get_user(args.username)
|
|
if command in ("create", "patch"):
|
|
fields = {key: value for key, value in vars(args).items() if key in USER_FIELDS}
|
|
if command == "create":
|
|
return api.create_user(args.username, if_match=revision, **fields)
|
|
if args.json:
|
|
if fields or args.clear:
|
|
raise ValueError("--json cannot be combined with user field options or --clear")
|
|
fields = _json_file(args.json)
|
|
else:
|
|
for name in args.clear:
|
|
if name in fields:
|
|
raise ValueError("A field cannot be set and cleared together or cleared twice")
|
|
fields[name] = None
|
|
return api.patch_user_fields(args.username, fields, if_match=revision)
|
|
if command in ("delete", "enable", "disable", "reset-quota", "secret"):
|
|
method = {"delete": api.delete_user, "enable": api.enable_user, "disable": api.disable_user,
|
|
"reset-quota": api.reset_user_quota, "secret": api.rotate_secret}[command]
|
|
return method(args.username, if_match=revision, **({"secret": args.secret} if command == "secret" else {}))
|
|
if command == "web-sessions":
|
|
return api.web_sessions(**{key: getattr(args, key) for key in
|
|
("limit", "cursor", "session_ref", "ip", "host", "user", "user_agent_id", "key_id", "carrier", "state")})
|
|
if command == "web-session":
|
|
return api.web_session(args.session_ref)
|
|
if command == "web-operation":
|
|
return api.web_operation(args.operation_id)
|
|
if command == "web-wait":
|
|
return api.wait_web_operation(args.operation_id, **wait_options)
|
|
if command == "web-drain-wait":
|
|
return api.wait_web_drain(args.runtime_instance, args.operation_id, **wait_options)
|
|
if command == "web-close":
|
|
response = api.web_close_sessions(args.runtime_instance, _json_file(args.selector))
|
|
return api.wait_web_operation(_response_field(response, "operation_id"), **wait_options) if args.wait else response
|
|
if command == "web-drain":
|
|
response = api.web_drain(args.runtime_instance, args.timeout_secs)
|
|
return api.wait_web_drain(args.runtime_instance, _response_field(response, "drain", "operation_id"), **wait_options) if args.wait else response
|
|
method = {"web-debug-clear": api.web_debug_clear, "web-learning-reset": api.web_learning_reset,
|
|
"web-pause": api.web_pause, "web-resume": api.web_resume}[command]
|
|
return method(args.runtime_instance)
|
|
|
|
|
|
def _display(response, args):
|
|
if getattr(args, "json_output", False):
|
|
print(json.dumps(asdict(response), indent=2))
|
|
return
|
|
data = response.data
|
|
if args.command == "users":
|
|
if not data:
|
|
print("No users configured.")
|
|
else:
|
|
fmt = "{:<24} {:>7} {:>14} {}"
|
|
print(fmt.format("USERNAME", "CONNS", "OCTETS", "LINKS"))
|
|
print("-" * 72)
|
|
for user in data:
|
|
links = user.get("links") or {}
|
|
all_links = sum((links.get(kind) or [] for kind in ("classic", "secure", "tls")), [])
|
|
print(fmt.format(user["username"], user.get("current_connections", 0), user.get("total_octets", 0), all_links[0] if all_links else "-"))
|
|
elif args.command == "create":
|
|
print(f"Created: {data.get('user', {}).get('username')}")
|
|
print(f"Secret: {data.get('secret')}")
|
|
for kind, links in ((data.get("user") or {}).get("links") or {}).items():
|
|
for link in links or []:
|
|
print(f"Link ({kind}): {link}")
|
|
elif args.command == "delete":
|
|
print(f"Deleted: {data}")
|
|
else:
|
|
print(json.dumps(data, indent=2))
|
|
if response.revision is not None:
|
|
print(f"# revision: {response.revision}")
|
|
if response.http_status != 200:
|
|
print(f"# HTTP: {response.http_status}")
|
|
|
|
|
|
def main(argv=None):
|
|
parser = build_parser()
|
|
args = parser.parse_args(argv)
|
|
if args.command in (None, "help"):
|
|
parser.print_help()
|
|
return 0
|
|
if args.command == "gen-secret":
|
|
print(TelemtAPI.generate_secret())
|
|
return 0
|
|
try:
|
|
api = TelemtAPI(getattr(args, "url", "http://127.0.0.1:9091"),
|
|
auth_header=getattr(args, "auth", None), timeout=getattr(args, "timeout", 10))
|
|
response = _dispatch(api, args)
|
|
_display(response, args)
|
|
if args.command == "ready":
|
|
return 0 if response.http_status == 200 and _response_field(response, "ready") is True else 1
|
|
data = response.data if isinstance(response.data, dict) else {}
|
|
if data.get("state") in ("failed", "rolled_back", "cancelled"):
|
|
return 1
|
|
if args.command in ("web-drain", "web-drain-wait") and getattr(args, "wait", args.command == "web-drain-wait"):
|
|
drain = (data.get("operator_lifecycle") or {}).get("drain") or {}
|
|
return 1 if drain.get("state") == "cancelled" else 0
|
|
return 0
|
|
except TelemtAPIError as error:
|
|
request = f" (request_id={error.request_id})" if error.request_id is not None else ""
|
|
print(f"API error [{error.http_status}] {error.code}: {error}{request}", file=sys.stderr)
|
|
if error.details:
|
|
print(json.dumps(error.details), file=sys.stderr)
|
|
return 1
|
|
except (ValueError, OSError) as error:
|
|
print(f"Input error: {error}", file=sys.stderr)
|
|
return 2
|
|
except KeyboardInterrupt:
|
|
return 130
|