Bedrock Downloader Core Documentation

class bedrock_server_manager.BedrockDownloader(settings_obj: Settings, server_dir: str, target_version: str = 'LATEST', server_zip_path: str | None = None)

Bases: object

Manages the download, extraction, and setup of a Bedrock Server instance.

This class orchestrates the process of obtaining and preparing Minecraft Bedrock server files for a specific server instance. It handles:

• Version Targeting: Allows specifying “LATEST” (stable), “PREVIEW”, or a concrete version number (e.g., “1.20.10.01”, “1.20.10.01-PREVIEW”).

• URL Resolution: Primarily uses the official Minecraft download API to find the correct download URL for the target version and operating system (Linux/Windows).

• Downloading: Downloads the server ZIP archive from the resolved URL, saving it to a version-specific (stable/preview) subdirectory within the configured global downloads path. It skips downloading if the file already exists.

• Extraction: Extracts the contents of the downloaded ZIP archive into the specified server directory. It supports “fresh install” and “update” modes, where the latter preserves user data like worlds, properties, and allowlists.

• Cache Pruning: After a download, it can trigger pruning of older ZIP files within its specific download subdirectory (stable or preview) based on retention settings.

An instance of this class is typically created when a new server needs to be installed or an existing one updated.

settings

The application settings object.

Type:

Settings

server_dir

The absolute path to the target server directory.

Type:

str

input_target_version

The user-provided version string.

Type:

str

os_name

The name of the current operating system (e.g., “Linux”, “Windows”).

Type:

str

base_download_dir

The root directory for all downloads.

Type:

Optional[str]

resolved_download_url

The final URL used for downloading.

Type:

Optional[str]

actual_version

The specific version number resolved (e.g., “1.20.10.01”).

Type:

Optional[str]

zip_file_path

Full path to the downloaded server ZIP file.

Type:

Optional[str]

specific_download_dir

Path to the subdirectory within base_download_dir used for this instance’s downloads (e.g., “…/downloads/stable”).

Type:

Optional[str]

__init__(settings_obj: Settings, server_dir: str, target_version: str = 'LATEST', server_zip_path: str | None = None)

Initializes the BedrockDownloader.

Parameters:

• settings_obj (Settings) – The application’s Settings object, providing access to configuration like download paths.

• server_dir (str) – The target directory where the server files will be installed or updated. This path will be converted to an absolute path.

• target_version (str, optional) – The version identifier for the server to download. Defaults to “LATEST”. Examples: “LATEST”, “PREVIEW”, “CUSTOM”, “1.20.10.01”, “1.20.10.01-PREVIEW”.

• server_zip_path (str, optional) – Absolute path to a custom server ZIP file. Required if target_version is “CUSTOM”.

Raises:

• MissingArgumentError – If settings_obj, server_dir, or target_version are not provided or are empty.

• ConfigurationError – If the paths.downloads setting is missing or empty in the provided settings_obj.

PRESERVED_ITEMS_ON_UPDATE: Set[str] = {'allowlist.json', 'permissions.json', 'server.properties', 'worlds/'}

get_version_for_target_spec() → str

Resolves and returns the actual version string for the instance’s target.

This method orchestrates the lookup of the download URL (via _lookup_bedrock_download_url()) and the extraction of the version number from that URL (via _get_version_from_url()). It populates instance attributes self.actual_version and self.resolved_download_url as side effects.

This method primarily focuses on identifying the version and its download source without actually downloading the server files.

Returns:

The actual, resolved version string (e.g., “1.20.10.01”) corresponding to the initial target specification.

Return type:

str

Raises:

• SystemError – If the OS is unsupported (from _lookup_bedrock_download_url()).

• InternetConnectivityError – If network issues prevent API access (from _lookup_bedrock_download_url()).

• DownloadError – If the API response is invalid, the URL cannot be found or constructed, or if the version cannot be parsed from the URL.

prepare_download_assets() → Tuple[str, str, str]

Orchestrates the download preparation, including potential download.

This comprehensive method coordinates all steps required to make the server ZIP file available locally, prior to extraction. The steps include:

1. Checking for internet connectivity using system_base.check_internet_connectivity().

2. Ensuring the main server directory (self.server_dir) and the base download directory (self.base_download_dir) exist, creating them if necessary.

3. Resolving the actual version and download URL by calling get_version_for_target_spec(). This populates self.actual_version and self.resolved_download_url.

4. Determining the specific download subdirectory (e.g., .../downloads/stable or .../downloads/preview) and ensuring it exists. This sets self.specific_download_dir.

5. Constructing the full path to the target ZIP file (self.zip_file_path).

6. If the ZIP file does not already exist at self.zip_file_path, it downloads the file using _download_server_zip_file().

7. Finally, it triggers cache pruning for the specific download directory using _execute_instance_pruning().

Returns:

A tuple containing:

• actual_version (str): The resolved version string (e.g., “1.20.10.01”).

• zip_file_path (str): The absolute path to the downloaded (or pre-existing) server ZIP file.

• specific_download_dir (str): The absolute path to the specific download subdirectory used (e.g., “…/downloads/stable”).

Return type:

Tuple[str, str, str]

Raises:

• InternetConnectivityError – If internet is unavailable or if download fails.

• FileOperationError – If directory creation or file writing fails.

• DownloadError – If version/URL resolution fails, or if critical attributes are not set post-preparation.

• SystemError – Propagated from version resolution if OS is unsupported.

extract_server_files(is_update: bool)

Extracts server files from the downloaded ZIP to the target server directory.

This method assumes that prepare_download_assets() has been successfully called, so that self.zip_file_path points to a valid local ZIP file and self.server_dir is the target extraction directory.

The behavior changes based on the is_update flag:

• If is_update is True, extraction preserves specific files and directories listed in PRESERVED_ITEMS_ON_UPDATE (e.g., worlds, server.properties, allowlist.json, permissions.json). Other files from the ZIP archive will overwrite existing files.

• If is_update is False (fresh install), all files from the ZIP archive are extracted, potentially overwriting anything in the self.server_dir.

Parameters:

is_update (bool) – If True, performs an update extraction, preserving key server files and data. If False, performs a fresh extraction of all files.

Raises:

• MissingArgumentError – If self.zip_file_path is not set (i.e., prepare_download_assets() was likely not called).

• AppFileNotFoundError – If the ZIP file at self.zip_file_path does not exist.

• FileOperationError – If creating the self.server_dir fails or if there are other filesystem errors during extraction (e.g., permissions).

• ExtractError – If the ZIP file is invalid, corrupted, or if an unexpected error occurs during the extraction process.

full_server_setup(is_update: bool) → str

Performs the complete server setup: download and extraction.

This is a high-level convenience method that orchestrates the entire process of obtaining and setting up the Bedrock server files. It calls prepare_download_assets() to handle the download (or use a cached version) and then calls extract_server_files() to extract the archive into the target server directory.

Parameters:

is_update (bool) – True if this is an update to an existing server (preserving data), False for a fresh installation. This flag is passed down to extract_server_files().

Returns:

The actual version string of the server that was successfully set up (e.g., “1.20.10.01”).

Return type:

str

Raises:

• InternetConnectivityError – If internet is unavailable or download fails.

• FileOperationError – If directory/file operations fail during download or extraction.

• DownloadError – If version/URL resolution or download preparation fails.

• ExtractError – If the server archive extraction fails.

• SystemError – If the OS is unsupported.

• MissingArgumentError – If prerequisites for extraction are not met.

• AppFileNotFoundError – If the ZIP file is missing before extraction.

get_actual_version() → str | None

Returns the resolved actual version string of the server.

This value is populated after get_version_for_target_spec() or prepare_download_assets() has been successfully called.

Returns:

The actual version string (e.g., “1.20.10.01”), or None if the version has not been resolved yet.

Return type:

Optional[str]

get_zip_file_path() → str | None

Returns the absolute path to the downloaded (or identified) server ZIP file.

This value is populated after prepare_download_assets() has successfully identified or downloaded the ZIP file.

Returns:

The full path to the server ZIP file, or None if not yet determined.

Return type:

Optional[str]

get_specific_download_dir() → str | None

Returns the specific download directory used for this instance’s downloads.

This is typically a subdirectory like ‘stable’ or ‘preview’ within the main download directory. It’s populated by prepare_download_assets().

Returns:

The absolute path to the instance’s specific download directory (e.g., /path/to/downloads/stable), or None if not yet determined.

Return type:

Optional[str]

get_resolved_download_url() → str | None

Returns the fully resolved download URL for the server archive.

This value is populated after get_version_for_target_spec() or prepare_download_assets() (which calls the former) has successfully resolved the URL.

Returns:

The complete download URL, or None if not yet resolved.

Return type:

Optional[str]