Server Install & Config API Documentation

Provides API functions for server installation, updates, and detailed configuration.

This module serves as an interface for managing the setup and fine-grained configuration of Bedrock server instances. It primarily orchestrates calls to the BedrockServer class to handle operations related to:

Functions in this module typically return structured dictionary responses suitable for use by web routes or CLI commands and integrate with the plugin system for extensibility.

bedrock_server_manager.api.server_install_config.add_players_to_allowlist_api(server_name: str, new_players_data: List[Dict[str, Any]], app_context: AppContext) → Dict[str, Any]

Adds new players to the allowlist for a specific server.

This function updates the server’s allowlist.json file by calling add_to_allowlist(). If the server is running, the underlying BedrockServer method typically attempts to reload the allowlist via a server command. Triggers before_allowlist_change and after_allowlist_change plugin events.

Parameters:

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

  • new_players_data (List[Dict[str, Any]]) – A list of player dictionaries to add. Each dictionary must contain a “name” key (str). It can optionally include “xuid” (str) and “ignoresPlayerLimit” (bool, defaults to False if not provided).

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Successfully added <n> new players...", "added_count": <n>} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server_install_config.get_server_allowlist_api(server_name: str, app_context: AppContext) → Dict[str, Any]

Retrieves the allowlist for a specific server.

Calls get_allowlist() to read and parse the server’s allowlist.json file.

Parameters:

server_name (str) – The name of the server.

Returns:

A dictionary with the operation result. On success: {"status": "success", "players": List[Dict[str, Any]]} where players is the list of entries from allowlist.json. Returns an empty list for players if the file doesn’t exist or is empty. On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server_install_config.remove_players_from_allowlist(server_name: str, player_names: List[str], app_context: AppContext) → Dict[str, Any]

Removes one or more players from the server’s allowlist by name.

This function iterates through the provided player_names and calls remove_from_allowlist() for each. Triggers before_allowlist_change and after_allowlist_change plugin events.

Parameters:

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

  • player_names (List[str]) – A list of player gamertags to remove. Case-insensitive matching is performed for removal.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Allowlist update process completed.", "details": {"removed": List[str], "not_found": List[str]}} If player_names is empty: {"status": "success", "message": "No players specified...", "details": {"removed": [], "not_found": []}} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server_install_config.configure_player_permission(server_name: str, xuid: str, player_name: str | None, permission: str, app_context: AppContext) → Dict[str, str]

Sets a player’s permission level in permissions.json.

This function calls set_player_permission() to update the server’s permissions.json file. Valid permission levels are “operator”, “member”, and “visitor”. Triggers before_permission_change and after_permission_change plugin events.

Parameters:

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

  • xuid (str) – The player’s XUID. Cannot be empty.

  • player_name (Optional[str]) – The player’s gamertag. Included in the permissions.json entry for reference if provided.

  • permission (str) – The permission level to set (e.g., ‘member’, ‘operator’, ‘visitor’). Case-insensitive. Cannot be empty.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Permission for XUID '<xuid>' set to '<perm>'."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.server_install_config.get_server_permissions_api(server_name: str, app_context: AppContext) → Dict[str, Any]

Retrieves processed permissions data for a server.

This function reads the server’s permissions.json file via get_formatted_permissions(). To enrich the data, it first fetches a global XUID-to-name mapping using get_all_known_players_api(). It also merges in any global players who are not currently in the permissions file, assigning them a default permission level for display. The resulting list of permissions is sorted by player name.

Parameters:

server_name (str) – The name of the server.

Returns:

A dictionary with the operation result. On success: {"status": "success", "data": {"permissions": List[Dict[str, Any]]}} where each dict in permissions contains “xuid”, “name”, and “permission_level”. On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server_install_config.get_server_properties_api(server_name: str, app_context: AppContext) → Dict[str, Any]

Reads and returns the server.properties file for a server.

Delegates to get_server_properties() to parse the file into a dictionary.

Parameters:

server_name (str) – The name of the server.

Returns:

A dictionary with the operation result. On success: {"status": "success", "properties": Dict[str, str]} On error (e.g., file not found): {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server_install_config.validate_server_property_value(property_name: str, value: str) → Dict[str, str]

Validates a single server property value based on known rules.

This is a stateless helper function used before modifying properties. It checks specific rules for properties like server-name (MOTD length, no semicolons), level-name (character set, length), network ports (numeric range), and certain numeric game settings (max-players, view-distance, tick-distance).

Properties not explicitly checked by this function are considered valid by default by this validator (though the server itself might have further constraints).

Parameters:

  • property_name (str) – The name of the server property (e.g., ‘level-name’, ‘server-port’).

  • value (str) – The string value of the property to validate.

Returns:

A dictionary with validation result. If valid: {"status": "success"} If invalid: {"status": "error", "message": "<validation_error_detail>"}

Return type:

Dict[str, str]

bedrock_server_manager.api.server_install_config.modify_server_properties(server_name: str, properties_to_update: Dict[str, str], app_context: AppContext, restart_after_modify: bool = False) → Dict[str, str]

Modifies one or more properties in server.properties.

This function first validates all provided properties using validate_server_property_value(). If all validations pass, it then uses the server_lifecycle_manager() to manage the server’s state (stopping it if restart_after_modify is True). Within the managed context, it applies each change by calling set_server_property(). If restart_after_modify is True, the server is restarted only if all properties are successfully set and the lifecycle manager completes without error. Triggers before_properties_change and after_properties_change plugin events.

Parameters:

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

  • properties_to_update (Dict[str, str]) – A dictionary of property keys and their new string values.

  • restart_after_modify (bool, optional) – If True, the server will be stopped before applying changes and restarted afterwards if successful. Defaults to True.

Returns:

A dictionary with the operation result. On success: {"status": "success", "message": "Server properties updated successfully."} On error (validation, file op, etc.): {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.server_install_config.install_new_server(server_name: str, app_context: AppContext, target_version: str = 'LATEST', server_zip_path: str | None = None) → Dict[str, Any]

Installs a new Bedrock server.

This involves validating the server name, ensuring the target directory doesn’t already exist, then creating the server directory, downloading the specified version of the server software (via install_or_update()), extracting files, setting permissions, and setting up initial configuration. Triggers before_server_install and after_server_install plugin events.

Parameters:

  • server_name (str) – The name for the new server. Must be unique and follow valid naming conventions (checked by validate_server_name_format()).

  • target_version (str, optional) – The server version to install (e.g., ‘1.20.10.01’, ‘LATEST’, ‘PREVIEW’). Defaults to ‘LATEST’.

Returns:

A dictionary with the operation result. On success: {"status": "success", "version": "<installed_version>", "message": "Server '<name>' installed..."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server_install_config.update_server(server_name: str, app_context: AppContext, send_message: bool = True) → Dict[str, Any]

Updates an existing server to its configured target version.

The process is as follows:

  1. Retrieves the server’s target version using get_target_version().

  2. Checks if an update is necessary via is_update_needed().

  3. If an update is needed:

    • Uses server_lifecycle_manager() to stop the server (if running and send_message is True, a notification may be sent before stopping).

    • Backs up all server data using backup_all_data().

    • Performs the update using install_or_update().

    • The lifecycle manager attempts to restart the server.

Triggers before_server_update and after_server_update plugin events.

Parameters:

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

  • send_message (bool, optional) – If True and the server is running, attempts to send a notification message to the server console before it’s stopped for the update. Defaults to True.

Returns:

A dictionary with the operation result.

If no update needed: {"status": "success", "updated": False, "message": "Server is already up-to-date."} On successful update: {"status": "success", "updated": True, "new_version": "<version>", "message": "Server '<name>' updated..."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises: