Web API Documentation

Provides API functions for managing the application’s own web user interface.

This module contains the logic for controlling the lifecycle and querying the status of the built-in web UI, which is powered by FastAPI. It interfaces with the BedrockServerManager to handle:

These functions are intended for programmatic control of the application’s web server, often used by CLI commands or service management scripts.

bedrock_server_manager.api.web.start_web_server_api(host: str | List[str] | None = None, debug: bool = False, mode: str = 'direct', threads: int | None = None, app_context: AppContext | None = None) → Dict[str, Any]

Starts the application’s web server.

This function can start the web server in two modes:

  • ‘direct’: A blocking call that runs the server in the current process Useful for development or when managed by an external process manager.

  • ‘detached’: Launches the server as a new background process and creates a PID file to track it. Requires the psutil library. Uses various methods from BedrockServerManager and process for process management.

Triggers before_web_server_start and after_web_server_start plugin events.

Parameters:

  • host (Optional[Union[str, List[str]]], optional) – The host address(es) to bind the web server to. Can be a single string or a list of strings. If None, defaults to the application’s configured setting (typically “0.0.0.0”). Defaults to None.

  • debug (bool, optional) – If True, starts the web server (Uvicorn) in debug mode (e.g., with auto-reload). Defaults to False.

  • mode (str, optional) – The start mode, either ‘direct’ or ‘detached’. Defaults to ‘direct’.

  • threads (Optional[int]) –

    Specifies the number of worker processes for Uvicorn

    Only used for Windows Service

Returns:

A dictionary with the operation result. If ‘direct’ mode: {"status": "success", "message": "Web server (direct mode) shut down."} If ‘detached’ mode (success): {"status": "success", "pid": <pid>, "message": "Web server started (PID: <pid>)."} On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

Raises:

  • UserInputError – If the provided mode is invalid.

  • SystemError – If detached mode is used but psutil is not installed.

  • ServerProcessError – If the web server is already running in detached mode.

  • BSMError – For other application-specific errors during startup.

bedrock_server_manager.api.web.stop_web_server_api(app_context: AppContext) → Dict[str, str]

Stops the detached web server process.

This function reads the PID from the web server’s PID file (path obtained via get_web_ui_pid_path()), verifies that the process is the correct one using expected executable and arguments (from BedrockServerManager), and then terminates it. Uses utilities from process. Requires the psutil library. Triggers before_web_server_stop and after_web_server_stop plugin events.

Returns:

A dictionary with the operation result. If successfully stopped: {"status": "success", "message": "Web server (PID: <pid>) stopped."} If not running (no PID file or stale PID): {"status": "success", "message": "Web server not running..."} On error (e.g., PID file error, process mismatch, termination error): {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.web.get_web_server_status_api(app_context: AppContext) → Dict[str, Any]

Checks the status of the web server process.

This function verifies the web server’s status by checking for a valid PID file (path obtained via get_web_ui_pid_path()) and then inspecting the process itself (using utilities from process) to ensure it is running and is the correct executable (details from BedrockServerManager). Requires the psutil library.

Returns:

A dictionary with the web server’s status. The "status" field can be one of “RUNNING”, “STOPPED”, “MISMATCHED_PROCESS”, or “ERROR”. If running, "pid" (int) will be present. A "message" (str) field provides details. Example: {"status": "RUNNING", "pid": 1234, "message": "Web server running..."}

Return type:

Dict[str, Any]

Raises:

BSMError – Can be raised by underlying operations if critical errors occur (e.g., ConfigurationError if web UI paths are not set up in BedrockServerManager), though many operational errors are returned in the status dictionary.

bedrock_server_manager.api.web.create_web_ui_service(app_context: AppContext, autostart: bool = False, system: bool = False, username: str | None = None, password: str | None = None) → Dict[str, str]

Creates (or updates) a system service for the Web UI.

On Linux, this creates a systemd user service. On Windows, this creates a Windows Service (typically requires Administrator privileges). This function calls create_web_service_file(), and then either enable_web_service() or disable_web_service() based on the autostart flag. Triggers before_web_service_change and after_web_service_change plugin events.

Parameters:

  • autostart (bool, optional) – If True, the service will be enabled to start automatically on system boot/login. If False, it will be created but left disabled. Defaults to False.

  • system (bool, optional) – If True, creates a system-wide service on Linux. This option is ignored on other operating systems. Defaults to False.

  • username (Optional[str], optional) – The username to run the service as on Windows. This option is ignored on other operating systems. Defaults to None.

  • password (Optional[str], optional) – The password for the user on Windows. This option is ignored on other operating systems. Defaults to None.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Web UI system service created and <enabled/disabled> successfully."} On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:

BSMError – Propagates errors from the underlying service management calls, such as SystemError, PermissionsError, CommandNotFoundError, or FileOperationError.

bedrock_server_manager.api.web.enable_web_ui_service(app_context: AppContext, system: bool = False) → Dict[str, str]

Enables the Web UI system service for autostart.

On Linux, this enables the systemd user service. On Windows, this sets the Windows Service start type to ‘Automatic’ (typically requires Administrator privileges). It calls enable_web_service(). Triggers before_web_service_change and after_web_service_change plugin events.

Parameters:

system (bool, optional) – If True, enables a system-wide service on Linux. This option is ignored on other operating systems. Defaults to False.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Web UI service enabled successfully."} If service management tools are unavailable: {"status": "error", "message": "System service management tool ... not found."} On other error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:

BSMError – Propagates errors from the underlying enable_web_service() call (e.g., SystemError, PermissionsError).

bedrock_server_manager.api.web.disable_web_ui_service(app_context: AppContext, system: bool = False) → Dict[str, str]

Disables the Web UI system service from autostarting.

On Linux, this disables the systemd user service. On Windows, this sets the Windows Service start type to ‘Disabled’ or ‘Manual’ (typically requires Administrator privileges). It calls disable_web_service(). Triggers before_web_service_change and after_web_service_change plugin events.

Parameters:

system (bool, optional) – If True, disables a system-wide service on Linux. This option is ignored on other operating systems. Defaults to False.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Web UI service disabled successfully."} If service management tools are unavailable: {"status": "error", "message": "System service management tool ... not found."} On other error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:

BSMError – Propagates errors from the underlying disable_web_service() call (e.g., SystemError, PermissionsError).

bedrock_server_manager.api.web.remove_web_ui_service(app_context: AppContext, system: bool = False) → Dict[str, str]

Removes the Web UI system service.

The service should ideally be stopped and disabled before removal. This function calls remove_web_service_file().

Warning

This is a DESTRUCTIVE operation that removes the service definition from the system.

Triggers before_web_service_change and after_web_service_change plugin events.

Parameters:

system (bool, optional) – If True, removes a system-wide service on Linux. This option is ignored on other operating systems. Defaults to False.

Returns:

A dictionary with the operation result. On success (service removed or was not found): {"status": "success", "message": "Web UI service removed successfully."} If service management tools are unavailable: {"status": "error", "message": "System service management tool ... not found."} On other error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:

BSMError – Propagates errors from the underlying remove_web_service_file() call (e.g., SystemError, PermissionsError, FileOperationError).

bedrock_server_manager.api.web.get_web_ui_service_status(app_context: AppContext, system: bool = False) → Dict[str, Any]

Gets the current status of the Web UI system service.

This function calls several methods on the BedrockServerManager instance: check_web_service_exists(), is_web_service_active(), and is_web_service_enabled().

Parameters:

system (bool, optional) – If True, checks a system-wide service on Linux. This option is ignored on other operating systems. Defaults to False.

Returns:

A dictionary with the operation result. On success: {"status": "success", "service_exists": bool, "is_active": bool, "is_enabled": bool, "message": Optional[str]}. - service_exists: True if the service definition is found on the system. - is_active: True if the service is currently running. - is_enabled: True if the service is set to start automatically. A “message” field may be present if service management tools are unavailable. On error during checks: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]