rconx 0.1.0__py3-none-any.whl

rconx/__init__.py

@@ -0,0 +1,68 @@
+from rconx.client.client import AsyncRconClient, RconClient
+from rconx.client.client_options import RconClientOptions
+from rconx.client.preset import RconPreset
+from rconx.client.raw import AsyncRawRconClient, LocalAddress, RawRconClient
+from rconx.common.connection import AsyncConnection, Connection
+from rconx.common.connection_info import ConnectionAddress, ConnectionInfo
+from rconx.common.connection_options import ConnectionOptions
+from rconx.common.content import RconContent
+from rconx.common.exceptions import (
+	RconAuthenticationError,
+	RconConnectionError,
+	RconError,
+	RconPacketDecodeError,
+	RconProtocolError,
+	RconStateError,
+	RconTimeoutError,
+)
+from rconx.common.protocol import Packet, PacketType
+from rconx.server.raw import AsyncRawRconServer, RawRconServer
+from rconx.server.raw_options import RawRconServerOptions
+from rconx.server.server import AsyncRconServer, RconServer
+from rconx.server.server_options import RconServerOptions
+
+__all__ = [
+	# High-level clients
+	'RconClient',
+	'AsyncRconClient',
+	'RconPreset',
+	'RconClientOptions',
+
+	# Low-level clients
+	'RawRconClient',
+	'AsyncRawRconClient',
+	'LocalAddress',
+
+	# High-level servers
+	'RconServer',
+	'AsyncRconServer',
+	'RconServerOptions',
+
+	# Low-level servers
+	'RawRconServer',
+	'AsyncRawRconServer',
+	'RawRconServerOptions',
+
+	# Low-level connections
+	'Connection',
+	'AsyncConnection',
+	'ConnectionOptions',
+
+	# Shared data
+	'RconContent',
+	'ConnectionInfo',
+	'ConnectionAddress',
+
+	# Protocol
+	'Packet',
+	'PacketType',
+
+	# Exceptions
+	'RconError',
+	'RconConnectionError',
+	'RconTimeoutError',
+	'RconPacketDecodeError',
+	'RconAuthenticationError',
+	'RconStateError',
+	'RconProtocolError',
+]

rconx/__main__.py

@@ -0,0 +1,5 @@
+from rconx.cli.main import main
+
+
+if __name__ == '__main__':
+	main()

rconx/cli/arguments.py

@@ -0,0 +1,128 @@
+import argparse
+import dataclasses
+import os
+import sys
+from typing import List, Optional
+
+from rconx.client.preset import RconPreset
+from rconx.common.connection_info import ConnectionAddress
+from rconx.common.utils import validate_packet_size_limit, validate_timeout
+
+
+def __get_self_version() -> str:
+	try:
+		if sys.version_info >= (3, 8):
+			from importlib.metadata import version
+		else:
+			from importlib_metadata import version
+		return version('rconx')
+	except Exception:
+		return 'unknown'
+
+
+@dataclasses.dataclass(frozen=True)
+class SizeLimit:
+	value: Optional[int]
+
+
+@dataclasses.dataclass(frozen=True)
+class CliOptions:
+	address: ConnectionAddress
+	password: str = dataclasses.field(repr=False)
+	commands: List[str]
+	preset: RconPreset
+	interactive: bool
+	timeout: Optional[float]
+	idle_window: Optional[float]
+	encoding: Optional[str]
+	raw: bool
+	max_send_packet_size: Optional[SizeLimit]
+	max_receive_packet_size: Optional[SizeLimit]
+	max_response_size: Optional[SizeLimit]
+
+
+def compute_address(value: str) -> ConnectionAddress:
+	if value.startswith('['):
+		closing = value.find(']')
+		if closing < 0 or value[closing + 1:closing + 2] != ':':
+			raise ValueError('expected HOST:PORT or [IPv6]:PORT')
+		host = value[1:closing]
+		port_text = value[closing + 2:]
+		if ':' not in host or '[' in host:
+			raise ValueError('expected [IPv6]:PORT')
+	else:
+		host, separator, port_text = value.rpartition(':')
+		if not separator or ':' in host or '[' in host or ']' in host:
+			raise ValueError('expected HOST:PORT or [IPv6]:PORT')
+	if not host:
+		raise ValueError('host must not be empty')
+	if not port_text or any(character < '0' or character > '9' for character in port_text):
+		raise ValueError('port must be a decimal integer from 1 to 65535')
+	port = int(port_text)
+	if not 1 <= port <= 65535:
+		raise ValueError('port must be from 1 to 65535')
+	return ConnectionAddress(host, port)
+
+
+def seconds(value: str) -> float:
+	seconds = float(value)
+	validate_timeout(seconds)
+	return seconds
+
+
+def timeout(value: str) -> Optional[float]:
+	return None if value == 'none' else seconds(value)
+
+
+def size_limit(value: str) -> SizeLimit:
+	size = None if value == 'none' else int(value)
+	validate_packet_size_limit(size, 'size limit')
+	return SizeLimit(size)
+
+
+def parse_args() -> CliOptions:
+	parser = argparse.ArgumentParser(
+		prog='rconx',
+		usage='%(prog)s [OPTIONS] HOST:PORT [COMMAND ...]',
+		description='Put every local option before HOST:PORT; use [IPv6]:PORT for IPv6 addresses.',
+		epilog='Each COMMAND is one complete command string. After HOST:PORT, all arguments are commands, including --help, -i and --. '
+			'Without -i, zero commands check the connection and authentication. With -i, interaction follows the startup commands.',
+	)
+	password_source = parser.add_mutually_exclusive_group(required=True)
+	password_source.add_argument('-p', '--password', metavar='PASSWORD', help='password; an explicitly empty value is allowed')
+	password_source.add_argument('--password-env', metavar='NAME', help='read the password from environment variable NAME')
+	parser.add_argument('-P', '--preset', choices=[preset.name for preset in RconPreset], default='minecraft', help='RCON exchange preset (default: %(default)s)')
+	parser.add_argument('-i', '--interactive', action='store_true', help='read commands interactively after the startup commands')
+	parser.add_argument('-t', '--timeout', type=timeout, default=10.0, metavar='SECONDS|none', help='timeout for each connect, authentication or command operation (default: 10 seconds)')
+	parser.add_argument('--idle-window', type=seconds, metavar='SECONDS', help='response quiet window; required and valid only for the idle_timeout preset')
+	parser.add_argument('--encoding', metavar='NAME', help='password, command and response text encoding (default: core utf8)')
+	parser.add_argument('--raw', action='store_true', help='write response bytes; incompatible with -i')
+	parser.add_argument('--max-send-packet-size', type=size_limit, metavar='BYTES|none', help='send packet size limit; none disables it (default: selected preset)')
+	parser.add_argument('--max-receive-packet-size', type=size_limit, metavar='BYTES|none', help='receive packet size limit; none disables it (default: core limit)')
+	parser.add_argument('--max-response-size', type=size_limit, metavar='BYTES|none', help='accumulated response size limit; none disables it (default: core limit)')
+	parser.add_argument('--version', action='version', version='%(prog)s {}'.format(__get_self_version()))
+	parser.add_argument('items', nargs=argparse.REMAINDER, metavar='HOST:PORT [COMMAND ...]', help='target address followed by zero or more complete command strings')
+	arguments = parser.parse_args()
+
+	if not arguments.items:
+		raise ValueError('HOST:PORT is required')
+	if (arguments.preset == 'idle_timeout') != (arguments.idle_window is not None):
+		raise ValueError('--idle-window is required and valid only for idle_timeout')
+	if arguments.raw and arguments.interactive:
+		raise ValueError('--raw cannot be combined with --interactive')
+	password = os.environ[arguments.password_env] if arguments.password_env is not None else arguments.password
+
+	return CliOptions(
+		address=compute_address(arguments.items[0]),
+		password=password,
+		commands=arguments.items[1:],
+		preset=RconPreset[arguments.preset],
+		interactive=arguments.interactive,
+		timeout=arguments.timeout,
+		idle_window=arguments.idle_window,
+		encoding=arguments.encoding,
+		raw=arguments.raw,
+		max_send_packet_size=arguments.max_send_packet_size,
+		max_receive_packet_size=arguments.max_receive_packet_size,
+		max_response_size=arguments.max_response_size,
+	)

rconx/cli/main.py

@@ -0,0 +1,78 @@
+import sys
+from typing import Optional
+
+from rconx.cli.arguments import CliOptions, parse_args
+from rconx.client.client import RconClient
+from rconx.client.client_options import RconClientOptions
+from rconx.common.content import RconContent
+
+
+def main():
+	options = parse_args()
+	with __create_client(options) as client:
+		__run(client, options)
+
+
+def __create_client(options: CliOptions) -> RconClient:
+	client_options: RconClientOptions = {}
+	if options.encoding is not None:
+		client_options['default_encoding'] = options.encoding
+	if options.max_send_packet_size is not None:
+		client_options['max_send_packet_size'] = options.max_send_packet_size.value
+	if options.max_receive_packet_size is not None:
+		client_options['max_receive_packet_size'] = options.max_receive_packet_size.value
+	if options.max_response_size is not None:
+		client_options['max_response_size'] = options.max_response_size.value
+	return RconClient.create(
+		options.address.host, options.address.port, options.preset,
+		first_byte_timeout=options.idle_window,
+		**client_options,
+	)
+
+
+def __run(client: RconClient, options: CliOptions):
+	client.connect(timeout=options.timeout)
+	client.authenticate(options.password, timeout=options.timeout)
+
+	for option_command in options.commands:
+		__execute_command(client, option_command, options)
+	if not options.interactive:
+		return
+
+	while True:
+		user_command = __read_command()
+		if user_command is None:
+			return
+		if user_command:
+			__execute_command(client, user_command, options)
+
+
+def __execute_command(client: RconClient, command: str, options: CliOptions):
+	response = client.execute(command, timeout=options.timeout)
+	__write_result(response, options)
+
+
+def __read_command() -> Optional[str]:
+	sys.stderr.write('rconx> ')
+	sys.stderr.flush()
+	try:
+		line = sys.stdin.readline()
+		if not line:
+			return None
+		if line.endswith('\n'):
+			line = line[:-1]
+		if line.endswith('\r'):
+			line = line[:-1]
+	except (KeyboardInterrupt, EOFError):
+		sys.exit(0)
+	return line
+
+
+def __write_result(response: RconContent, options: CliOptions):
+	if options.raw:
+		sys.stdout.buffer.write(response.content)
+		sys.stdout.buffer.flush()
+	else:
+		sys.stdout.write(response.text)
+		sys.stdout.write('\n')
+		sys.stdout.flush()

rconx/client/auth/__init__.py

@@ -0,0 +1 @@
+

rconx/client/auth/base.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+from rconx.client.operation import AsyncRconOperationContext, RconOperationContext
+
+
+class AuthenticationHandler(ABC):
+	@abstractmethod
+	def authenticate(self, context: RconOperationContext, password: bytes):
+		raise NotImplementedError
+
+	@abstractmethod
+	async def authenticate_async(self, context: AsyncRconOperationContext, password: bytes):
+		raise NotImplementedError

rconx/client/auth/source_handler.py

@@ -0,0 +1,69 @@
+from rconx.client.auth.base import AuthenticationHandler
+from rconx.client.operation import AsyncRconOperationContext, RconOperationContext
+from rconx.common.exceptions import RconAuthenticationError, RconProtocolError
+from rconx.common.protocol import Packet, PacketType
+
+
+class _AuthenticationResponseProcessor:
+	def __init__(self, request_id: int):
+		self.__request_id = request_id
+		self.__received_empty_response = False
+		self.__is_complete = False
+
+	@property
+	def is_complete(self) -> bool:
+		return self.__is_complete
+
+	def accept(self, packet: Packet) -> None:
+		if packet.payload:
+			raise RconProtocolError('authentication response payload length is {}, expected 0 (request id {})'.format(len(packet.payload), packet.request_id))
+
+		if packet.packet_type == PacketType.auth_response:
+			if packet.request_id == -1:
+				raise RconAuthenticationError('server rejected authentication for request id {}'.format(self.__request_id))
+			if packet.request_id != self.__request_id:
+				raise RconProtocolError('unexpected authentication result request id {}, expected {}'.format(packet.request_id, self.__request_id))
+
+			self.__is_complete = True
+			return
+
+		# Allow at most one empty response-value packet before the authentication result.
+		if packet.packet_type != PacketType.response_value:
+			raise RconProtocolError(
+				'unexpected authentication response type {}, expected {} (response value) or {} (authentication result)'.format(
+					packet.packet_type, PacketType.response_value, PacketType.auth_response,
+				)
+			)
+		if packet.request_id != self.__request_id:
+			raise RconProtocolError('unexpected empty authentication response request id {}, expected {}'.format(packet.request_id, self.__request_id))
+
+		if self.__received_empty_response:
+			raise RconProtocolError('received a second empty response-value packet before the authentication result (request id {})'.format(packet.request_id))
+
+		self.__received_empty_response = True
+
+
+class SourceAuthenticationHandler(AuthenticationHandler):
+	"""
+	**Not public API**
+
+	Source RCON authentication for SRCDS, Minecraft and Cuberite.
+	Accepts an authentication result directly or after one empty response-value packet.
+	"""
+	def authenticate(self, context: RconOperationContext, password: bytes):
+		request = context.prepare_request(PacketType.auth, password)
+		response_processor = _AuthenticationResponseProcessor(request.request_id)
+
+		context.send_packet(request)
+
+		while not response_processor.is_complete:
+			response_processor.accept(context.receive_packet())
+
+	async def authenticate_async(self, context: AsyncRconOperationContext, password: bytes):
+		request = context.prepare_request(PacketType.auth, password)
+		response_processor = _AuthenticationResponseProcessor(request.request_id)
+
+		await context.send_packet(request)
+
+		while not response_processor.is_complete:
+			response_processor.accept(await context.receive_packet())