System Base Core Documentation

Provides base system utilities and foundational cross-platform functionalities.

This module contains a collection of essential system-level utilities that are generally platform-agnostic or provide a common interface for operations that might have platform-specific nuances handled elsewhere. It serves as a core part of the system interaction layer.

Key functionalities include:

Constants:

  • PSUTIL_AVAILABLE: Boolean indicating if psutil was imported, critical for ResourceMonitor.

Internal Helpers:

  • _handle_remove_readonly_onerror(): An error handler for shutil.rmtree.

bedrock_server_manager.core.system.base.check_internet_connectivity(host: str = '8.8.8.8', port: int = 53, timeout: int = 3) → None

Checks for basic internet connectivity by attempting a TCP socket connection.

This function tries to establish a TCP connection to a specified host and port with a given timeout. Success indicates likely internet access. Failure (timeout or other OSError) raises an InternetConnectivityError.

Parameters:

  • host (str, optional) – The hostname or IP address to connect to. Defaults to “8.8.8.8” (Google Public DNS).

  • port (int, optional) – The port number to connect to. Defaults to 53 (DNS port).

  • timeout (int, optional) – The connection timeout in seconds. Defaults to 3.

Raises:

InternetConnectivityError – If the socket connection fails due to a timeout, OSError (e.g., network unreachable, host not found), or any other unexpected exception during the check.

bedrock_server_manager.core.system.base.delete_path_robustly(path_to_delete: str, item_description: str) → bool

Deletes a file or directory robustly, attempting to handle read-only attributes.

This function attempts to delete the specified path_to_delete.

  • If it’s a directory, it uses shutil.rmtree with a custom error handler (_handle_remove_readonly_onerror()) that tries to make read-only files writable before retrying deletion.

  • If it’s a file, it first checks if it’s writable. If not, it attempts to make it writable (stat.S_IWRITE | stat.S_IWUSR) before calling os.remove.

  • If the path does not exist, it logs this and returns True.

  • If the path is neither a file nor a directory, it logs a warning and returns False.

Deletion failures are logged, and the function returns False in such cases.

Parameters:

  • path_to_delete (str) – The absolute path to the file or directory to delete.

  • item_description (str) – A human-readable description of the item being deleted, used for logging messages (e.g., “temporary file”, “old backup directory”).

Returns:

True if the deletion was successful or if the path did not exist initially. False if an error occurred during deletion or if the path was neither a file nor a directory.

Return type:

bool

Raises:

MissingArgumentError – If path_to_delete or item_description are empty or not strings.

bedrock_server_manager.core.system.base.is_server_running(server_name: str, server_dir: str, config_dir: str) → bool

Checks if a specific Bedrock server process is running and verified.

This function acts as a high-level convenience wrapper around get_verified_bedrock_process(). It determines if a Bedrock server, identified by server_name, is active by checking its PID file and verifying the running process’s identity (e.g., executable path and CWD).

Parameters:

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

  • server_dir (str) – The server’s installation directory, used for process verification.

  • config_dir (str) – The main application configuration directory where the server’s PID file is expected to be located.

Returns:

True if a matching and verified Bedrock server process is found to be running, False otherwise (e.g., if psutil is unavailable, PID file is missing, process is not running, or verification fails).

Return type:

bool

Raises:

MissingArgumentError – If server_name, server_dir, or config_dir are empty or not strings.

bedrock_server_manager.core.system.base.set_server_folder_permissions(server_dir: str) → None

Sets appropriate permissions for a Bedrock server installation directory.

This function adjusts permissions recursively for the specified server_dir based on the operating system:

  • On Linux:

    • Ownership of all files and directories is set to the current effective user (UID) and group (GID) using os.chown.

    • Directories are set to 0o775 (rwxrwxr-x).

    • The main server executable (assumed to be named “bedrock_server”) is set to 0o775 (rwxrwxr-x).

    • Other files are set to 0o664 (rw-rw-r–).

  • On Windows:

    • Ensures that the “write” permission (stat.S_IWRITE or stat.S_IWUSR) is set for all files and directories. It preserves other existing permissions by ORing with the current mode.

  • Other OS:

    • Logs a warning that permission setting is not implemented.

Parameters:

server_dir (str) – The absolute path to the server’s installation directory.

Raises:

  • MissingArgumentError – If server_dir is empty or not a string.

  • AppFileNotFoundError – If server_dir does not exist or is not a directory.

  • PermissionsError – If any OSError occurs during os.chown or os.chmod operations (e.g., due to insufficient privileges to change ownership or permissions), or for other unexpected errors.