Utils API Documentation

Provides utility functions and a context manager for the API layer.

This module offers a collection of helper functions that support other API modules or perform general application-wide tasks. Key functionalities include:

These utilities are designed to be used by other API modules or higher-level application logic to encapsulate common or complex operations.

bedrock_server_manager.api.utils.validate_server_exist(server_name: str, app_context: AppContext | None = None) → Dict[str, Any]

Validates if a server is correctly installed.

This function checks for the existence of the server’s directory and its executable by instantiating a BedrockServer object for the given server_name and then calling its is_installed() method.

Parameters:

server_name (str) – The name of the server to validate.

Returns:

A dictionary with the operation status. If valid: {"status": "success", "message": "Server '<server_name>' exists and is valid."} If not installed/invalid: {"status": "error", "message": "Server '<server_name>' is not installed..."} If config error: {"status": "error", "message": "Configuration error: <details>"}

Return type:

Dict[str, Any]

Raises:

BSMError – Can be raised by BedrockServer during instantiation if core application settings are misconfigured.

bedrock_server_manager.api.utils.validate_server_name_format(server_name: str) → Dict[str, str]

Validates the format of a potential server name.

This is a stateless check (does not verify if the server actually exists) that delegates to core_validate_server_name_format(). It ensures new server names conform to allowed character sets (alphanumeric, hyphens, underscores) and are not empty.

Parameters:

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

Returns:

A dictionary with the operation status. If format is valid: {"status": "success", "message": "Server name format is valid."} If format is invalid: {"status": "error", "message": "<validation_error_detail>"}

Return type:

Dict[str, str]

bedrock_server_manager.api.utils.update_server_statuses(settings=None, app_context: AppContext | None = None) → Dict[str, Any]

Reconciles the status in config files with the runtime state for all servers.

This function calls get_servers_data(). During that call, for each discovered server, its get_status() method is invoked. This method determines the actual running state of the server process and updates the status field in the server’s JSON configuration file (e.g., <server_name>_config.json) if there’s a discrepancy between the stored status and the live status.

Returns:

A dictionary summarizing the operation. On success (even with individual server errors during discovery): {"status": "success", "message": "Status check completed for <n> servers."} or {"status": "error", "message": "Completed with errors: <details>", "updated_servers_count": <n>} (The “error” status here primarily reflects issues during the overall scan, like directory access problems, rather than individual server status update failures, which are logged and included in the message if discovery_errors occur.)

Return type:

Dict[str, Any]

bedrock_server_manager.api.utils.get_system_and_app_info(settings=None, app_context: AppContext | None = None) → Dict[str, Any]

Retrieves basic system and application information.

Uses BedrockServerManager to get OS type and app version.

Returns:

On success: {"status": "success", "data": {"os_type": "...", "app_version": "..."}}. On error: {"status": "error", "message": "An unexpected error occurred."}

Return type:

Dict[str, Any]

bedrock_server_manager.api.utils.stop_all_servers(app_context: AppContext)

Stops all running servers.

bedrock_server_manager.api.utils.server_lifecycle_manager(server_name: str, stop_before: bool, start_after: bool = True, restart_on_success_only: bool = False, app_context: AppContext | None = None)

A context manager to safely stop and restart a server for an operation.

This manager, when stop_before=True, will attempt to stop a server using api_stop_server() if it is running. It then yields control to the wrapped code block. In its finally clause, it handles restarting the server (if start_after=True and it was originally running) using api_start_server() with mode="detached". This ensures an attempt to return the server to its original state even if the operation within the with block fails.

Parameters:

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

  • stop_before (bool) – If True, the server will be stopped if it’s running before the with block is entered. If stopping fails, the context manager may not yield control.

  • start_after (bool, optional) – If True, the server will be restarted after the with block if it was running initially. Defaults to True.

  • restart_on_success_only (bool, optional) – If True, the server will only be restarted if the with block completes without raising an exception. Defaults to False.

Yields:

None.

Raises:

  • ServerStopError – If stop_before=True and the initial attempt to stop the server fails critically (though the current implementation returns a dict).

  • ServerStartError – If start_after=True and the server fails to restart after the operation. This is raised if the original operation in the with block succeeded but the subsequent restart failed.

  • Exception – Re-raises any exception that occurs within the with block itself.

  • BSMError – For other application-specific errors during server interactions.