Utils Core Documentation

Provides low-level core utility functions for server management.

This module contains a collection of helper functions that perform specific, atomic tasks related to server management. These utilities are designed to be used by higher-level components like the BedrockServer or API endpoints.

Key functions include:

Warning

The functions check_server_status() and update_server_status_in_config() are currently unused in the application. They represent a legacy method of determining server status by parsing log files, which has been superseded by more reliable process-based checks (e.g., using psutil). They are retained for potential future reference or alternative implementations but should not be relied upon in their current state.

bedrock_server_manager.core.utils.check_server_status(server_name: str, base_dir: str, max_attempts: int = 10, chunk_size_bytes: int = 8192, max_scan_bytes: int = 1048576) → str

Determines a server’s status by reading the end of its log file.

Warning

This function is currently unused and represents a legacy approach. Modern status checks rely on process monitoring, which is more reliable than log parsing.

This method efficiently reads the server’s log file (server_output.txt) backwards in chunks to find the most recent status indicator, such as “Server started.” or “Quit correctly.”. It includes a brief wait period to allow the log file to be created if it doesn’t exist.

Parameters:

  • server_name (str) – The name of the server.

  • base_dir (str) – The base directory containing all server installations.

  • max_attempts (int) – The maximum number of attempts to wait for the log file to appear, with a 0.5-second sleep between attempts.

  • chunk_size_bytes (int) – The size of each chunk to read from the end of the file.

  • max_scan_bytes (int) – The maximum total bytes to scan backwards from the end of the file before giving up.

Returns:

The determined server status. Possible values are “RUNNING”, “STARTING”, “RESTARTING”, “STOPPING”, “STOPPED”, or “UNKNOWN”.

Return type:

str

Raises:

  • MissingArgumentError – If server_name or base_dir is empty.

  • FileOperationError – If reading the log file fails due to an OS-level error (e.g., permissions).

bedrock_server_manager.core.utils.core_validate_server_name_format(server_name: str) → None

Validates the format of a server name against a specific pattern.

The function checks that the server name is not empty and contains only alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (_). This helps prevent issues with file paths and system commands.

Parameters:

server_name (str) – The server name string to validate.

Raises:

InvalidServerNameError – If the server name is empty or contains invalid characters.

bedrock_server_manager.core.utils.update_server_status_in_config(server_name: str, base_dir: str, config_dir: str | None = None) → None

Updates a server’s status in its config file based on a log check.

Warning

This function is currently unused and not functional in its current state, as it depends on check_server_status() and a dummy core_server_utils import.

This function calls check_server_status() to get the current status and compares it to the last known status in the server’s configuration. If the status has changed and is informative (i.e., not “UNKNOWN”), it writes the new status to the configuration file.

Parameters:

  • server_name (str) – The name of the server.

  • base_dir (str) – The base directory containing the server’s folder, used to locate the log file.

  • config_dir (Optional[str]) – The base directory containing server config folders. If None, the application’s default config directory would be used.

Raises:

  • MissingArgumentError – If server_name or base_dir is empty.

  • InvalidServerNameError – If server_name has an invalid format.

  • FileOperationError – If reading the log or reading/writing the config file fails.