feat!: query the update server from ValidateAsync

ValidateAsync now takes only the installed version and discovers the
package itself, so callers no longer build an UpdatePackageInfo by hand.

- add UpdateServerOptions and wire it into AndroidUpdateOptions.UpdateServer
- add HttpUpdatePackageClient: POSTs the GeneralUpdate
  /Upgrade/Verification protocol by default, or GETs a single
  UpdatePackageInfo document when UseJsonEndpoint is true; picks the
  newest non-frozen full APK and rejects invalid metadata
- report server, transport and metadata problems through Success=false,
  FailureReason and AddListenerUpdateFailed, return Canceled on user
  cancellation, and succeed with UpdateFound=false when no package exists
- forward updateServer/httpClient/httpOptions through CreateDefault so the
  check shares the download transport (timeout, proxy, TLS, auth)
- remove the ValidateAsync(UpdatePackageInfo, currentVersion, ct) overload

BREAKING CHANGE: ValidateAsync(UpdatePackageInfo packageInfo, string
currentVersion, CancellationToken) is replaced by ValidateAsync(string
currentVersion, CancellationToken); pass UpdateCheckResult.PackageInfo to
DownloadAndVerifyAsync and LaunchInstallerAsync.

Also fixes HttpResumableApkDownloader holding its write stream until the
end of the method: PhysicalFileStorage opens files with FileShare.None, so
MoveFile threw IOException on Windows and every download failed with
FileIoError. The stream is now flushed and closed before the temporary
file is renamed, which also stops .part/.part.json from being left behind.

Tests cover the new package client and the end-to-end flow (validate ->
download -> verify -> installer handoff) using the real downloader, real
file system writes and real SHA-256. The READMEs document the server
protocol and the Android prerequisites.

Author: JusterZhu

README-EN.md

@@ -65,20 +65,23 @@ var cacheDirPath = Android.App.Application.Context.CacheDir?.AbsolutePath
 var options = new AndroidUpdateOptions
 {
     DownloadDirectoryPath = Path.Combine(cacheDirPath, "update"),
-    FileProviderAuthority = "com.example.app.generalupdate.fileprovider"
+    FileProviderAuthority = "com.example.app.generalupdate.fileprovider",
+
+    // ValidateAsync queries this server internally; callers only pass the installed version
+    UpdateServer = new UpdateServerOptions
+    {
+        RequestUrl = "https://example.com/Upgrade/Verification",
+        AppKey = "your-app-key",
+        AppType = 1,
+        Platform = androidPlatformId,
+        ProductId = "your-product-id"
+    }
 };
 
 using var bootstrap = GeneralUpdateBootstrap.CreateDefault(options);
-var packageInfo = new UpdatePackageInfo
-{
-    Version = "2.3.0",
-    DownloadUrl = "https://example.com/app-release.apk",
-    Sha256 = "REPLACE_WITH_ACTUAL_SHA256_HASH",
-    FileName = "app-release.apk"
-};
 
-var check = await bootstrap.ValidateAsync(packageInfo, "2.2.1", CancellationToken.None);
-if (check.UpdateFound)
+var check = await bootstrap.ValidateAsync("2.2.1", CancellationToken.None);
+if (check.Success && check.UpdateFound && check.PackageInfo is { } packageInfo)
 {
     var prepared = await bootstrap.DownloadAndVerifyAsync(packageInfo, CancellationToken.None);
     if (prepared.Success && prepared.FilePath is not null)
@@ -88,6 +91,87 @@ if (check.UpdateFound)
 }
 ```
 
+### Server-Driven Version Validation
+
+`ValidateAsync(currentVersion, cancellationToken)` only needs the version installed on the device: the component queries
+the server configured through `AndroidUpdateOptions.UpdateServer`, picks the newest full APK, compares it with
+`currentVersion`, and exposes the discovered package through `UpdateCheckResult.PackageInfo` for download and installation.
+
+The default protocol is GeneralUpdate's sample server `POST /Upgrade/Verification`: the request body carries
+`version/appKey/appType/platform/productId` and the response is `{"code":200,"body":[...]}`. The client maps
+`version/url/hash/size/name/updateLog/releaseDate/isForcibly/authScheme/authToken` and selects the newest non-frozen full APK
+(`packageType` 2, 0 or omitted; `format` `apk`/`.apk`, or a `.apk` URL path when omitted). ZIP, patch and driver packages are
+never handed to the Android installer; an empty `body` or no matching package means "no update".
+**Verify the deployed URL, response shape and Android platform id — do not assume a fixed id**; when the protocol differs,
+have the server expose the standard JSON endpoint below.
+
+Static JSON server: set `UpdateServer.UseJsonEndpoint = true` and point `RequestUrl` at the JSON address; the component
+then GETs a single `UpdatePackageInfo` (property names are case-insensitive), for example:
+
+```json
+{
+  "version": "2.3.0",
+  "downloadUrl": "https://example.com/app-release.apk",
+  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "description": "Release notes",
+  "isForced": false
+}
+```
+
+- `sha256` must be the APK's real 64-character hexadecimal SHA-256 (never MD5); `fileSize` may be omitted or 0 when unknown.
+- HTTP 204 or a JSON `null` body means "no package"; transport, protocol and metadata errors are reported through
+  `UpdateCheckResult.Success = false`, `FailureReason` and `AddListenerUpdateFailed`, and never invoke the pre-check callback.
+- Cancellation during the request returns `UpdateState.Canceled`; cancelling while waiting on the operation gate throws
+  `OperationCanceledException`.
+- Validation and downloads share the `httpOptions` passed to `CreateDefault` (`RequestTimeout`, proxy, TLS, `AuthProvider`).
+  Without `httpOptions` the supplied `httpClient` is reused and its lifetime stays with the host.
+- Calling `ValidateAsync` without `UpdateServer` fails with `UpdateFailureReason.InvalidMetadata`.
+- Only query trusted servers and use HTTPS in production.
+
+Once a newer version is found, the `AddListenerUpdatePrecheck` callback receives the discovered package metadata and returns
+`true` to skip or `false` to continue (forced updates bypass it), matching `GeneralUpdate.Core`.
+
+## Android Prerequisites
+
+The library ships no UI and does not request permissions on your behalf. A full update only completes when the host app
+configures all four items below:
+
+1. **Install permission (Android 8.0+)** — declare it in `AndroidManifest.xml`:
+
+   ```xml
+   <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
+   ```
+
+   When the user has not granted it, `LaunchInstallerAsync` returns `FailureReason = InstallPermissionDenied`. Send the
+   user to the "install unknown apps" screen and retry afterwards:
+
+   ```csharp
+   var context = Android.App.Application.Context;
+   context.StartActivity(new Android.Content.Intent(
+           Android.Provider.Settings.ActionManageUnknownAppSources,
+           Android.Net.Uri.Parse("package:" + context.PackageName))
+       .AddFlags(Android.Content.ActivityFlags.NewTask));
+   ```
+
+2. **FileProvider** — the `android:authorities` in `AndroidManifest.xml` must match
+   `AndroidUpdateOptions.FileProviderAuthority` exactly, and `generalupdate_file_paths.xml` must cover
+   `DownloadDirectoryPath` (defaults to `<CacheDir>/update`). A mismatch returns `InstallLaunchFailed`.
+
+3. **Current Activity** — `CreateDefault` uses `NullAndroidActivityProvider` by default, in which case the installer is
+   launched through `Application.Context` + `FLAG_ACTIVITY_NEW_TASK`. Passing an `IAndroidActivityProvider` that returns
+   the current `Activity` is more robust:
+
+   ```csharp
+   using var bootstrap = GeneralUpdateBootstrap.CreateDefault(options, activityProvider: myActivityProvider);
+   ```
+
+4. **Server** — `AndroidUpdateOptions.UpdateServer` must be configured (or use the static JSON endpoint through
+   `UseJsonEndpoint`), and `sha256` must be a 64-character hexadecimal SHA-256.
+
+`LaunchInstallerAsync` returning `Success = true` only means the installer intent was launched; it **does not** mean the user
+finished installing. The process is killed on completion, so compare the installed version with the server again on the next
+launch to confirm the update actually took effect.
+
 ## Directory Structure
 
 ```text

README.md

@@ -65,20 +65,23 @@ var cacheDirPath = Android.App.Application.Context.CacheDir?.AbsolutePath
 var options = new AndroidUpdateOptions
 {
     DownloadDirectoryPath = Path.Combine(cacheDirPath, "update"),
-    FileProviderAuthority = "com.example.app.generalupdate.fileprovider"
+    FileProviderAuthority = "com.example.app.generalupdate.fileprovider",
+
+    // ValidateAsync 据此在组件内部请求服务端，调用方只需要提供当前版本
+    UpdateServer = new UpdateServerOptions
+    {
+        RequestUrl = "https://example.com/Upgrade/Verification",
+        AppKey = "your-app-key",
+        AppType = 1,
+        Platform = androidPlatformId,
+        ProductId = "your-product-id"
+    }
 };
 
 using var bootstrap = GeneralUpdateBootstrap.CreateDefault(options);
-var packageInfo = new UpdatePackageInfo
-{
-    Version = "2.3.0",
-    DownloadUrl = "https://example.com/app-release.apk",
-    Sha256 = "REPLACE_WITH_ACTUAL_SHA256_HASH",
-    FileName = "app-release.apk"
-};
 
-var check = await bootstrap.ValidateAsync(packageInfo, "2.2.1", CancellationToken.None);
-if (check.UpdateFound)
+var check = await bootstrap.ValidateAsync("2.2.1", CancellationToken.None);
+if (check.Success && check.UpdateFound && check.PackageInfo is { } packageInfo)
 {
     var prepared = await bootstrap.DownloadAndVerifyAsync(packageInfo, CancellationToken.None);
     if (prepared.Success && prepared.FilePath is not null)
@@ -88,6 +91,83 @@ if (check.UpdateFound)
 }
 ```
 
+### 服务端版本校验
+
+`ValidateAsync(currentVersion, cancellationToken)` 只需要当前应用的版本号：组件按
+`AndroidUpdateOptions.UpdateServer` 的配置请求服务端，选出最新的完整 APK，与 `currentVersion`
+比较，并把发现的包信息放在结果的 `PackageInfo` 中，供下载与安装继续使用。
+
+默认使用 GeneralUpdate 示例服务端的 `POST /Upgrade/Verification` 协议：请求体发送
+`version/appKey/appType/platform/productId`，响应为 `{"code":200,"body":[...]}`；客户端映射
+`version/url/hash/size/name/updateLog/releaseDate/isForcibly/authScheme/authToken`，并按版本选择最新的
+非冻结完整 APK（`packageType` 为 2、0 或省略；`format` 为 `apk`/`.apk`，省略时 URL 路径需以 `.apk` 结尾）。
+ZIP、差分包、驱动包不会交给 Android 安装器；`body` 为空数组或没有符合条件的包时视为“无更新”。
+**请核对实际部署的地址、响应格式与 Android 平台编号，不要假定固定编号**；协议不同时，可让服务端提供下面的标准 JSON 端点。
+
+静态 JSON 服务端：设置 `UpdateServer.UseJsonEndpoint = true` 并把 `RequestUrl` 指向 JSON 地址，
+组件自动 GET 一个 `UpdatePackageInfo`（字段名不区分大小写），例如：
+
+```json
+{
+  "version": "2.3.0",
+  "downloadUrl": "https://example.com/app-release.apk",
+  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "description": "更新说明",
+  "isForced": false
+}
+```
+
+- `sha256` 必须是 APK 实际的 64 位十六进制 SHA-256，不能使用 MD5；`fileSize` 可省略或为 0（表示未知），已知时单位为字节。
+- HTTP 204 或 GET JSON `null` 表示无包；请求、协议与元数据错误通过 `UpdateCheckResult.Success = false`、
+  `FailureReason` 和 `AddListenerUpdateFailed` 上报，并且不会触发 pre-check。
+- 请求期间取消返回 `UpdateState.Canceled`；等待操作锁时取消会抛出 `OperationCanceledException`。
+- 查询与下载共用 `CreateDefault` 的 `httpOptions`（`RequestTimeout`、代理、TLS 与 `AuthProvider`）；
+  未提供 `httpOptions` 时复用传入的 `httpClient`，其生命周期仍由宿主管理。
+- 未配置 `UpdateServer` 时调用 `ValidateAsync` 会以 `UpdateFailureReason.InvalidMetadata` 失败。
+- 仅应查询可信服务器，生产环境请使用 HTTPS。
+
+发现新版本后，`AddListenerUpdatePrecheck` 回调会拿到最新包信息，返回 `true` 跳过、`false` 继续
+（强制更新不调用该回调），语义与 `GeneralUpdate.Core` 一致。
+
+## Android 接入前提
+
+库不提供 UI，也不代替宿主申请权限。要真正走完一次更新，宿主必须配置好下面四项，缺一项就会停在半路：
+
+1. **安装权限（Android 8.0+）**：在 `AndroidManifest.xml` 中声明
+
+   ```xml
+   <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
+   ```
+
+   用户可能仍未授予，此时 `LaunchInstallerAsync` 返回 `FailureReason = InstallPermissionDenied`。
+   用下面的 intent 引导用户开启“允许安装未知应用”，授权后重试即可：
+
+   ```csharp
+   var context = Android.App.Application.Context;
+   context.StartActivity(new Android.Content.Intent(
+           Android.Provider.Settings.ActionManageUnknownAppSources,
+           Android.Net.Uri.Parse("package:" + context.PackageName))
+       .AddFlags(Android.Content.ActivityFlags.NewTask));
+   ```
+
+2. **FileProvider**：`AndroidManifest.xml` 的 `android:authorities` 必须与
+   `AndroidUpdateOptions.FileProviderAuthority` 完全一致，且 `generalupdate_file_paths.xml` 要覆盖
+   `DownloadDirectoryPath`（默认是 `<CacheDir>/update`）。不一致时返回 `InstallLaunchFailed`。
+
+3. **当前 Activity**：`CreateDefault` 默认使用 `NullAndroidActivityProvider`，此时安装器通过
+   `Application.Context` + `FLAG_ACTIVITY_NEW_TASK` 拉起。传入实现 `IAndroidActivityProvider` 的
+   provider（返回当前 `Activity`）更稳妥：
+
+   ```csharp
+   using var bootstrap = GeneralUpdateBootstrap.CreateDefault(options, activityProvider: myActivityProvider);
+   ```
+
+4. **服务端**：必须配置 `AndroidUpdateOptions.UpdateServer`（或改用 `UseJsonEndpoint` 的静态 JSON），
+   且 `sha256` 为 64 位十六进制 SHA-256。
+
+`LaunchInstallerAsync` 返回 `Success = true` 只表示安装器已拉起，**不代表用户已完成安装**：安装完成后进程会被
+系统结束，下次启动时请自行比较本机版本与服务端版本，以确认这次更新是否真正生效。
+
 ## 目录结构
 
 ```text

src/GeneralUpdate.Avalonia.Android/Abstractions/IAndroidBootstrap.cs

@@ -32,8 +32,32 @@ public interface IAndroidBootstrap : IDisposable
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="func"/> is null.</exception>
     IAndroidBootstrap AddListenerUpdatePrecheck(Func<UpdateInfoEventArgs, bool> func);
 
+    /// <summary>
+    /// Queries the configured update server for the newest package, compares it with
+    /// <paramref name="currentVersion"/> and runs the pre-check callback.
+    /// <para>
+    /// Package metadata is discovered internally from <see cref="AndroidUpdateOptions.UpdateServer"/>, so callers
+    /// only supply the version currently installed on the device. When an update is found, the returned
+    /// <see cref="UpdateCheckResult.PackageInfo"/> can be passed to <see cref="DownloadAndVerifyAsync"/> and
+    /// <see cref="LaunchInstallerAsync"/>.
+    /// </para>
+    /// <para>
+    /// Like <c>GeneralUpdate.Core</c>, the pre-check callback registered with
+    /// <see cref="AddListenerUpdatePrecheck"/> decides whether to continue: returning <c>true</c> skips the update
+    /// (the result carries <see cref="UpdateCheckResult.UpdateFound"/> set to <c>false</c> and state
+    /// <see cref="UpdateState.Completed"/>), returning <c>false</c> keeps it. Forced updates bypass the callback.
+    /// </para>
+    /// <para>
+    /// Server, protocol, metadata and HTTP failures are reported through
+    /// <see cref="UpdateCheckResult.Success"/>, <see cref="UpdateOperationResult.FailureReason"/> and
+    /// <see cref="AddListenerUpdateFailed"/>; when the server reports no package the call succeeds with
+    /// <see cref="UpdateCheckResult.UpdateFound"/> set to <c>false</c>.
+    /// </para>
+    /// </summary>
+    /// <param name="currentVersion">The application version currently installed on the device.</param>
+    /// <param name="cancellationToken">Cancels the server request and the validation.</param>
+    /// <returns>The validation outcome, including the discovered package metadata when an update is available.</returns>
     Task<UpdateCheckResult> ValidateAsync(
-        UpdatePackageInfo packageInfo,
         string currentVersion,
         CancellationToken cancellationToken = default);
 

src/GeneralUpdate.Avalonia.Android/GeneralUpdateBootstrap.cs

@@ -63,6 +63,9 @@ public static IAndroidBootstrap CreateDefault(
             installer,
             usedStorage,
             eventDispatcher,
-            usedLogger);
+            usedLogger,
+            options.UpdateServer,
+            httpClient,
+            httpOptions);
     }
 }

src/GeneralUpdate.Avalonia.Android/Models/AndroidUpdateOptions.cs

@@ -2,6 +2,13 @@ namespace GeneralUpdate.Avalonia.Android.Models;
 
 public sealed record AndroidUpdateOptions
 {
+    /// <summary>
+    /// Update server queried by <see cref="Abstractions.IAndroidBootstrap.ValidateAsync"/>.
+    /// When null, <see cref="Abstractions.IAndroidBootstrap.ValidateAsync"/> reports
+    /// <see cref="Enums.UpdateFailureReason.InvalidMetadata"/> because no package can be discovered.
+    /// </summary>
+    public UpdateServerOptions? UpdateServer { get; init; }
+
     public string DownloadDirectoryPath { get; init; } = string.Empty;
     public string TemporaryFileExtension { get; init; } = ".part";
     public string SidecarExtension { get; init; } = ".json";

src/GeneralUpdate.Avalonia.Android/Models/HttpDownloadOptions.cs

@@ -4,7 +4,7 @@
 namespace GeneralUpdate.Avalonia.Android.Models;
 
 /// <summary>
-/// Configures HTTP transport behavior for update downloads:
+/// Configures HTTP transport behavior for update verification and downloads:
 /// SSL/TLS certificate validation, timeouts, proxy, retry, and authentication.
 /// <para>
 /// When provided to <see cref="GeneralUpdateBootstrap.CreateDefault"/>,
@@ -23,7 +23,7 @@ public sealed record HttpDownloadOptions
     public ISslValidationPolicy? SslValidationPolicy { get; init; }
 
     /// <summary>
-    /// Timeout for individual HTTP requests (HEAD probes, etc.).
+    /// Timeout for update server verification requests and download HEAD probes.
     /// Default is 30 seconds.
     /// </summary>
     public TimeSpan RequestTimeout { get; init; } = TimeSpan.FromSeconds(30);
@@ -61,8 +61,8 @@ public sealed record HttpDownloadOptions
     public TimeSpan RetryBaseDelay { get; init; } = TimeSpan.FromSeconds(1);
 
     /// <summary>
-    /// Global authentication provider applied to all download requests.
-    /// Per-package authentication on <see cref="UpdatePackageInfo"/> takes precedence.
+    /// Global authentication provider applied to update server verification and download requests.
+    /// Per-package authentication on <see cref="UpdatePackageInfo"/> takes precedence for downloads.
     /// </summary>
     public IHttpAuthProvider? AuthProvider { get; init; }
 

src/GeneralUpdate.Avalonia.Android/Models/UpdatePackageRequest.cs

@@ -0,0 +1,14 @@
+namespace GeneralUpdate.Avalonia.Android.Models;
+
+/// <summary>
+/// Request body for the GeneralUpdate <c>/Upgrade/Verification</c> reference protocol.
+/// <see cref="Platform"/> must match the identifier configured by the server.
+/// </summary>
+internal sealed record UpdatePackageRequest
+{
+    public required string Version { get; init; }
+    public required string AppKey { get; init; }
+    public int AppType { get; init; } = 1;
+    public required int Platform { get; init; }
+    public required string ProductId { get; init; }
+}

src/GeneralUpdate.Avalonia.Android/Models/UpdateServerOptions.cs

@@ -0,0 +1,54 @@
+namespace GeneralUpdate.Avalonia.Android.Models;
+
+/// <summary>
+/// Configures the update server that <see cref="Abstractions.IAndroidBootstrap.ValidateAsync"/> queries
+/// internally, so callers only pass the version currently installed.
+/// <para>
+/// By default the client POSTs the GeneralUpdate verification request
+/// (<c>version</c>, <c>appKey</c>, <c>appType</c>, <c>platform</c>, <c>productId</c>) to
+/// <see cref="RequestUrl"/> and picks the newest non-frozen full APK from the
+/// <c>{"code":200,"body":[...]}</c> response.
+/// </para>
+/// <para>
+/// Set <see cref="UseJsonEndpoint"/> to <c>true</c> when <see cref="RequestUrl"/> instead returns a
+/// single <see cref="UpdatePackageInfo"/> JSON document over GET.
+/// </para>
+/// </summary>
+public sealed record UpdateServerOptions
+{
+    /// <summary>
+    /// Absolute HTTP(S) URL queried by <see cref="Abstractions.IAndroidBootstrap.ValidateAsync"/>.
+    /// For the GeneralUpdate reference protocol this is the verification endpoint
+    /// (for example <c>https://example.com/Upgrade/Verification</c>).
+    /// </summary>
+    public required string RequestUrl { get; init; }
+
+    /// <summary>
+    /// Application key sent in the verification request body.
+    /// This is a request field only; it does not enable HMAC signing
+    /// (configure <see cref="HttpDownloadOptions.AuthProvider"/> for that).
+    /// </summary>
+    public string AppKey { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Application type sent in the verification request body. Default is 1.
+    /// </summary>
+    public int AppType { get; init; } = 1;
+
+    /// <summary>
+    /// Platform identifier expected by the server for Android.
+    /// Must match the identifier configured by the deployment; no fixed value is assumed.
+    /// </summary>
+    public int Platform { get; init; }
+
+    /// <summary>
+    /// Product identifier sent in the verification request body.
+    /// </summary>
+    public string ProductId { get; init; } = string.Empty;
+
+    /// <summary>
+    /// GET a JSON <see cref="UpdatePackageInfo"/> from <see cref="RequestUrl"/> instead of POSTing
+    /// the GeneralUpdate verification protocol. HTTP 204 or a JSON <c>null</c> body means no update.
+    /// </summary>
+    public bool UseJsonEndpoint { get; init; }
+}