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 handles:

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(app_context: AppContext, host: str | None = None, port: int | None = None, debug: bool = False, mode: str = 'direct') → 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 process for process management.

Triggers before_web_server_start and after_web_server_start plugin events.

Parameters:

  • host (Optional[str], optional) – The host address to bind the web server to. If None, defaults to the application’s configured setting (typically “127.0.0.1”). 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’.

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, verifies that the process is the correct one using expected executable and arguments, 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 and then inspecting the process itself (using utilities from process) to ensure it is running and is the correct executable. 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), 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 service-related functions: 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]