Update Mechanism

CHANGELOG.md

@@ -7,11 +7,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 The changelog starts with version 1.7.0.
 Changes to prior versions can be found on the [Github release page](https://github.com/cryptomator/integrations-api/releases).
 
-## [Unreleased]
+## [Unreleased](https://github.com/cryptomator/integrations-api/compare/1.7.0...HEAD)
 
-No changes yet.
+### Added
 
-## [1.7.0] - 2025-09-17
+* Experimental [Update API](https://github.com/cryptomator/integrations-api/blob/a052dd06a38f5410f6d9c9c7061c036efee83480/src/main/java/org/cryptomator/integrations/update/UpdateMechanism.java)
+
+## [1.7.0](https://github.com/cryptomator/integrations-api/releases/tag/1.7.0) - 2025-09-17
 
 ### Changed
 

pom.xml

@@ -30,6 +30,7 @@
 		<jdk.version>25</jdk.version>
 
 		<slf4j.version>2.0.17</slf4j.version>
+		<jackson.version>2.20.0</jackson.version>
 		<jetbrains-annotation.version>26.0.2-1</jetbrains-annotation.version>
 
 		<!-- Test dependencies -->
@@ -59,6 +60,11 @@
 			<artifactId>slf4j-api</artifactId>
 			<version>${slf4j.version}</version>
 		</dependency>
+		<dependency>
+			<groupId>com.fasterxml.jackson.core</groupId>
+			<artifactId>jackson-databind</artifactId>
+			<version>${jackson.version}</version>
+		</dependency>
 
 		<dependency>
 			<groupId>org.jetbrains</groupId>

src/main/java/module-info.java

@@ -6,11 +6,14 @@
 import org.cryptomator.integrations.keychain.KeychainAccessProvider;
 import org.cryptomator.integrations.tray.TrayIntegrationProvider;
 import org.cryptomator.integrations.uiappearance.UiAppearanceProvider;
+import org.cryptomator.integrations.update.UpdateMechanism;
 
 
 module org.cryptomator.integrations.api {
 	requires static org.jetbrains.annotations;
 	requires org.slf4j;
+	requires com.fasterxml.jackson.databind;
+	requires java.net.http;
 
 	exports org.cryptomator.integrations.autostart;
 	exports org.cryptomator.integrations.common;
@@ -20,6 +23,7 @@
 	exports org.cryptomator.integrations.tray;
 	exports org.cryptomator.integrations.uiappearance;
 	exports org.cryptomator.integrations.quickaccess;
+	exports org.cryptomator.integrations.update;
 
 	uses AutoStartProvider;
 	uses KeychainAccessProvider;
@@ -29,4 +33,5 @@
 	uses TrayMenuController;
 	uses UiAppearanceProvider;
 	uses QuickAccessService;
+	uses UpdateMechanism;
 }

src/main/java/org/cryptomator/integrations/Localization.java

@@ -0,0 +1,14 @@
+package org.cryptomator.integrations;
+
+import java.util.ResourceBundle;
+
+public enum Localization {
+	INSTANCE;
+
+	private final ResourceBundle resourceBundle = ResourceBundle.getBundle("IntegrationsApi");
+
+	public static ResourceBundle get() {
+		return INSTANCE.resourceBundle;
+	}
+
+}

src/main/java/org/cryptomator/integrations/common/IntegrationsLoader.java

@@ -36,6 +36,19 @@ public static <T> Optional<T> load(Class<T> clazz) {
 		return loadAll(clazz).findFirst();
 	}
 
+	/**
+	 * Loads a specific service provider by its implementation class name.
+	 * @param clazz Service class
+	 * @param implementationClassName fully qualified class name of the implementation
+	 * @return Optional of the service provider if found
+	 * @param <T> Type of the service
+	 */
+	public static <T> Optional<T> loadSpecific(Class<T> clazz, String implementationClassName) {
+		return ServiceLoader.load(clazz, ClassLoaderFactory.forPluginDir()).stream()
+				.filter(provider -> provider.type().getName().equals(implementationClassName))
+				.map(ServiceLoader.Provider::get)
+				.findAny();
+	}
 
 	/**
 	 * Loads all suited service providers ordered by priority in descending order.

src/main/java/org/cryptomator/integrations/update/DownloadUpdateInfo.java

@@ -0,0 +1,8 @@
+package org.cryptomator.integrations.update;
+
+public record DownloadUpdateInfo(
+		DownloadUpdateMechanism updateMechanism,
+		String version,
+		DownloadUpdateMechanism.Asset asset
+) implements UpdateInfo<DownloadUpdateInfo> {
+}

src/main/java/org/cryptomator/integrations/update/DownloadUpdateMechanism.java

@@ -0,0 +1,130 @@
+package org.cryptomator.integrations.update;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.jetbrains.annotations.Blocking;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.HexFormat;
+import java.util.List;
+
+public abstract class DownloadUpdateMechanism implements UpdateMechanism<DownloadUpdateInfo> {
+
+	private static final Logger LOG = LoggerFactory.getLogger(DownloadUpdateMechanism.class);
+	private static final String LATEST_VERSION_API_URL = "https://api.cryptomator.org/connect/apps/desktop/latest-version?format=1";
+	private static final ObjectMapper MAPPER = new ObjectMapper();
+
+	@Override
+	public DownloadUpdateInfo checkForUpdate(String currentVersion, HttpClient httpClient) {
+		try {
+			HttpRequest request = HttpRequest.newBuilder().uri(URI.create(LATEST_VERSION_API_URL)).build();
+			HttpResponse<InputStream> response = httpClient.send(request, HttpResponse.BodyHandlers.ofInputStream());
+			if (response.statusCode() != 200) {
+				LOG.warn("Failed to fetch release: HTTP {}", response.statusCode());
+				return null;
+			}
+			var release = MAPPER.readValue(response.body(), LatestVersionResponse.class);
+			return checkForUpdate(currentVersion, release);
+		} catch (InterruptedException e) {
+			Thread.currentThread().interrupt();
+			LOG.debug("Update check interrupted.");
+			return null;
+		} catch (IOException e) {
+			LOG.warn("Update check failed", e);
+			return null;
+		}
+	}
+
+	/**
+	 * Returns the first step to prepare the update. This downloads the {@link DownloadUpdateInfo#asset() asset} to a temporary location and verifies its checksum.
+	 * @param updateInfo The {@link DownloadUpdateInfo} retrieved from {@link #checkForUpdate(String, HttpClient)}.
+	 * @return a new {@link UpdateStep} that can be used to monitor the download progress.
+	 * @throws UpdateFailedException When failing to prepare a temporary download location.
+	 */
+	@Override
+	public UpdateStep firstStep(DownloadUpdateInfo updateInfo) throws UpdateFailedException {
+		try {
+			Path workDir = Files.createTempDirectory("cryptomator-update");
+			return new FirstStep(workDir, updateInfo);
+		} catch (IOException e) {
+			throw new UpdateFailedException("Failed to create temporary directory for update", e);
+		}
+	}
+
+	/**
+	 * Second step that is executed after the download has completed in the {@link #firstStep(DownloadUpdateInfo) first step}.
+	 * @param workDir A temporary working directory to which the asset has been downloaded.
+	 * @param assetPath The path of the downloaded asset.
+	 * @param updateInfo The {@link DownloadUpdateInfo} representing the update.
+	 * @return The next step of the update process.
+	 * @throws IllegalStateException if preconditions aren't met.
+	 * @throws IOException indicating an error preventing the next step from starting.
+	 * @implSpec The returned {@link UpdateStep} must either be stateless or a new instance must be returned on each call.
+	 */
+	public abstract UpdateStep secondStep(Path workDir, Path assetPath, DownloadUpdateInfo updateInfo) throws IllegalStateException, IOException;
+
+	@Nullable
+	@Blocking
+	protected abstract DownloadUpdateInfo checkForUpdate(String currentVersion, LatestVersionResponse response);
+
+	@JsonIgnoreProperties(ignoreUnknown = true)
+	public record LatestVersionResponse(
+			@JsonProperty("latestVersion") LatestVersion latestVersion,
+			@JsonProperty("assets") List<Asset> assets
+	) {}
+
+	@JsonIgnoreProperties(ignoreUnknown = true)
+	public record LatestVersion(
+			@JsonProperty("mac") String macVersion,
+			@JsonProperty("win") String winVersion,
+			@JsonProperty("linux") String linuxVersion
+	) {}
+
+	@JsonIgnoreProperties(ignoreUnknown = true)
+	public record Asset(
+			@JsonProperty("name") String name,
+			@JsonProperty("digest") String digest,
+			@JsonProperty("size") long size,
+			@JsonProperty("downloadUrl") String downloadUrl
+	) {}
+
+	private class FirstStep extends DownloadUpdateStep {
+		private final Path workDir;
+		private final DownloadUpdateInfo updateInfo;
+
+		public FirstStep(Path workDir, DownloadUpdateInfo updateInfo) {
+			var uri = URI.create(updateInfo.asset().downloadUrl);
+			var destination = workDir.resolve(updateInfo.asset().name);
+			var digest = updateInfo.asset().digest().startsWith("sha256:")
+					? HexFormat.of().withLowerCase().parseHex(updateInfo.asset().digest.substring(7)) // remove "sha256:" prefix
+					: null;
+			var size = updateInfo.asset().size;
+			super(uri, destination, digest, size);
+			this.workDir = workDir;
+			this.updateInfo = updateInfo;
+		}
+
+		@Override
+		public @Nullable UpdateStep nextStep() throws IllegalStateException, IOException {
+			if (!isDone()) {
+				throw new IllegalStateException("Download not yet completed.");
+			} else if (downloadException != null) {
+				throw new UpdateFailedException("Download failed.", downloadException);
+			}
+			return secondStep(workDir, destination, updateInfo);
+		}
+	}
+
+}