Class BunHelpers

java.lang.Object
io.github.m_segreti.BunHelpers
public class BunHelpers extends Object
Utility helpers used by the Bun Gradle plugin for downloading, verifying, extracting, and locating the Bun runtime.

Responsibilities include:

  • Normalizing version strings (including supporting "latest").
  • Building the correct GitHub release asset URL for a platform-specific Bun zip.
  • Downloading files and computing SHA-256 hashes.
  • Discovering an expected SHA-256 from the upstream release metadata page.
  • Unzipping a Bun distribution into a destination directory.
  • Locating the Bun executable under an installation directory.

Note: This is a pure utility class and is not meant to be instantiated.

  • Method Details

    • normalizeVersion

      public static String normalizeVersion(String version)
      Normalizes a Bun version string.

      If the input is null or blank after trimming, "latest" is returned. Otherwise, the trimmed version string is returned.

      Parameters:
      version - the configured version (may be null or blank)
      Returns:
      a non-blank version string, or "latest" when not specified

    • stripZip

      public static String stripZip(String zipName)
      Removes a trailing ".zip" suffix from a zip file name, if present.
      Parameters:
      zipName - the zip file name (e.g., "bun-linux-x64.zip")
      Returns:
      the base name without ".zip" when present; otherwise the original value

    • bunZipUrl

      public static URI bunZipUrl(String version, BunSystem sys)
      Builds the GitHub download URI for the Bun release zip for the given version and system.

      For "latest", this points to the releases/latest/download endpoint. For explicit versions, this points to releases/download/bun-v<version>/....

      Parameters:
      version - the Bun version (use "latest" for newest)
      sys - the target system/platform descriptor used to choose the correct asset name
      Returns:
      the download URI for the Bun zip asset

    • sha256

      public static String sha256(File file) throws NoSuchAlgorithmException, IOException
      Computes the SHA-256 hash of a file and returns it as a lowercase hexadecimal string.
      Parameters:
      file - the file to hash
      Returns:
      SHA-256 digest as a lowercase hex string
      Throws:
      NoSuchAlgorithmException - if SHA-256 is not available in the current JVM
      IOException - if the file cannot be read

    • downloadUrlTo

      public static void downloadUrlTo(URL url, File destination, boolean disableSslVerification) throws IOException
      Downloads the content at url and writes it to destination.

      This method ensures the destination parent directory exists before writing.

      Parameters:
      url - the URL to download
      destination - the destination file to write (will be overwritten if it exists)
      disableSslVerification - whether to disable SSL certificate verification
      Throws:
      IOException - if the download fails or the destination cannot be written

    • fetchExpectedSha256

      public static String fetchExpectedSha256(String version, String assetZipName) throws IOException
      Fetches the expected SHA-256 for a given Bun asset zip from the release metadata page.

      The SHA values are published on the bun-releases-for-updater repository release pages in a sha256: <hex> format. This method scrapes the HTML for the given asset name and extracts the first SHA-256 match.

      Parameters:
      version - the Bun version (use "latest" for newest)
      assetZipName - the exact asset file name to locate (e.g., bun-linux-x64.zip)
      Returns:
      the expected SHA-256 digest as a lowercase hex string
      Throws:
      IOException - if the release page cannot be downloaded
      IllegalStateException - if the SHA-256 cannot be found for the given asset on the page

    • unzip

      public static void unzip(File zip, File destination) throws IOException
      Extracts a zip file into the given destination directory.

      Directory entries are created as directories, file entries are written to disk. Parent directories are created as needed.

      Parameters:
      zip - the zip file to extract
      destination - the destination directory where the zip contents will be written
      Throws:
      IOException - if the zip cannot be read or any entry cannot be written

    • findBunExecutable

      public static Optional<File> findBunExecutable(File root, String executable)
      Recursively searches for a Bun executable file under the provided root directory.

      The search is case-insensitive to better support Windows file systems, and returns the first match found during a depth-first traversal.

      Parameters:
      root - the directory to search
      executable - the executable file name to find (e.g., "bun" or "bun.exe")
      Returns:
      an Optional containing the first matching file, or empty if none is found