Deployment service and application packages

Overview · Architecture · Build and release · Olympus integration

This is the client contract implemented by UpdateClient, ServiceManifest, the two JSON contexts in Models.cs, and the semantic checks in DeploymentManifest.Validate. The configuration service is maintained separately. Publishing metadata or packages is not part of Build-Installer.ps1.

Current production request

The base endpoint is Options.Endpoint in Olympus.Deployment.Core/Storage.cs:

https://epsservices-configuration-bhajarhuc3b9e8gk.southcentralus-01.azurewebsites.net/GetOlympusDeploymentInformation

The client appends query parameters:

GET /GetOlympusDeploymentInformation?Channel=0&Architecture=0
X-Olympus-Agent-Version: 1.0.0
If-None-Match: "example-etag"
Selection Current value
Channel Always 0; no user-selectable channel is implemented.
Architecture 0 for x64 Windows, 1 for ARM64 Windows, based on OS architecture.
X-Olympus-Agent-Version Actual running agent assembly version for agent requests. Foreground launcher requests currently send the fallback 1.0.0; they do not inspect the installed agent.
If-None-Match Added only when a cached ETag belongs to the exact same manifest source URL.

The current client does not send an X-Olympus-Architecture header. Select the representation using the query parameter. A preview/alpha application version does not change the channel request. Any future channel selection must also scope cached state and installed policy deliberately.

An HTTP 200 body must contain the nested manifest itself. The HTTP deserializer accepts case-insensitive field names, including the configuration service's PascalCase DataContract representation, and ignores unmodeled base-response members. It does not unwrap an arbitrary outer Data/Result envelope. Required fields and semantic validation still apply.

An HTTP 304 reuses the cached manifest; 304 without a valid cached manifest is an error. Return a representation-specific ETag. A 304 means the release metadata is unchanged, not that downloading, staging, or startup is already complete. The client still enforces bootstrap minimums and retries unfinished work.

The source URL includes channel/architecture, preventing conditional request reuse against a different selected representation. Manifest responses are capped at 1 MiB. Redirects are disabled by the default HTTP handler. Normal OS TLS certificate validation is used; no endpoint user-token acquisition or signed-manifest verification is implemented.

Manifest example

This camelCase example is suitable as a template for strict local manifests. The service may send the equivalent PascalCase names. The URL and all-zero hash below are placeholders, not a downloadable release.

{
  "schemaVersion": 1,
  "application": "Olympus",
  "version": "2026.10.5",
  "minimumVersion": "2026.10.1",
  "dataCompatibilityId": "1",
  "minimumLauncherVersion": "1.0.0",
  "minimumAgentVersion": "1.0.0",
  "package": {
    "url": "https://storage.example.com/olympus/2026.10.5-win-arm64.zip",
    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
    "architecture": "arm64",
    "executable": "Olympus.exe"
  },
  "update": {
    "policy": "required",
    "reminderMinutes": 10,
    "restartDeadlineMinutes": 60
  },
  "prerequisites": []
}
Field Validation and meaning
schemaVersion Supported value 1, default 1.
application Required, exactly Olympus.
version Required immutable application release. See version rules below.
minimumVersion Required lowest permitted application version; must not exceed target. An accepted floor cannot decrease.
dataCompatibilityId Required nonblank epoch, at most 128 characters; automatic activation/rollback cannot cross epochs.
minimumLauncherVersion Optional bootstrap minimum, default 1.0.0; the running launcher enforces it before accepting/starting an incompatible release.
minimumAgentVersion Optional bootstrap minimum, default 1.0.0; the running agent enforces it before staging.
package Required non-null object.
package.url Required absolute HTTPS ZIP URL without URI user-info/credentials; file URLs only in explicit local test mode.
package.sha256 Required 64 hexadecimal characters for the complete final ZIP.
package.architecture Required x64 or arm64, matching the Windows OS.
package.executable Safe relative .exe path with slash separators; defaults to Olympus.exe. It is not a command line.
update Required non-null object.
update.policy normal, required, or critical; default normal.
update.reminderMinutes Integer 1–10,080, default 10; used for repeated critical reminders.
update.restartDeadlineMinutes Null or integer 1–525,600, counted from the first local acceptance of that release.
prerequisites Optional array, default empty; null is rejected. Each item requires type, minimumVersion, and architecture.

Keep service metadata separate from on-disk deployment.json and receipts. Those use the internal flat metadata representation. Do not generate a service response by copying persisted state, or send its resolved restartDeadlineUtc as a service field. The service sends relative minutes; IPC later sends resolved deadlineUtc.

Local manifests differ from HTTP parsing

--manifest <path> deliberately enables trusted local-file testing. Local JSON uses the camelCase nested contract and rejects unknown members through DeploymentJsonContext. The HTTP ServiceResponseJsonContext is case-insensitive and skips unknown members for compatibility with base-response fields. Neither path substitutes the old flat service schema for required nested objects.

samples/manifest.json and samples/deployment-manifest.schema.json describe the local template/schema. Check the sample schema and New-TestDeployment.ps1 when introducing prerelease feeds: the dummy-generation script currently accepts only numeric three/four-part versions. The runtime release parser is more capable; the source implementation remains authoritative if an example/schema has not yet been brought forward.

Version ordering and immutability

The runtime OlympusVersion parser accepts three/four numeric components with an optional -alphaN or -previewN stage. For the same numeric version, alpha sorts below preview, which sorts below a stable release; stage numbers sort numerically. Numeric components take precedence over stage. Bootstrap MSI versions remain strictly three-part numeric values.

Examples:

6.0.0-alpha1 < 6.0.0-alpha2 < 6.0.0-preview1 < 6.0.0
6.0.0 < 6.0.1-alpha1
6.0.0 and 6.0.0.0 compare equally

Choose one canonical spelling per published release. Do not publish equivalent aliases as separate version directories. Never reuse a published version with a different ZIP hash. To roll back code intentionally, publish that code under a new, higher version with compatible data and an appropriate minimum floor. Do not make the service move backwards or lower a previously accepted minimum.

Package requirements

The ZIP's contents begin at the application root. Include every required assembly, native dependency, read-only resource, and self-contained runtime file where applicable. The entry point must exist at package.executable. A structurally compatible x86 PE is permitted for legacy .NET Framework/AnyCPU; that does not establish that its runtime/dependencies are available.

Limits and protections:

The shared update cycle has a 15-minute cancellation budget, with the launcher's foreground manifest request independently limited to five seconds. First installation still requires a usable feed and package. Subsequent offline operation is allowed only for a verified installed release that meets accepted policy and compatibility constraints.

Prerequisites

Supported lowercase type values are netframework, desktopruntime, webview2, and office. Dependency versions accept two to four numeric components, such as 4.8 or 120.0; dependency architectures can be x86, x64, or arm64 independently of the package OS architecture.

Detectors are allowlisted. Framework detection uses release keys (the current probe supports requirements through 4.8.0), desktop runtime detection uses architecture-specific shared-framework registration, and Office checks Click-to-Run version/platform rather than MSI Office. These checks do not prove executable health or install prerequisites, and the protocol cannot supply arbitrary commands.

Current WebView2 exception: Prerequisites.HasWebView checks a hardcoded HKLM WOW6432Node EdgeUpdate client key twice. It does not currently compare the requested minimum version or implement separate user/machine/CPU-aware probes. When absent, it attempts to open Microsoft's runtime-download URL with Process.Start before logging manual installation instructions; URL-launch failure can therefore surface as an exception. This is not automatic runtime installation. Correct and validate this implementation before relying on WebView2 minimum/architecture declarations in production. The class comments and older README's broader registry-detector description do not establish those guarantees.

Validate vendor installations and emulation/registry-view behavior on actual supported machines.

Update policy and deadlines

The agent stages packages while Olympus is running and sends updateReady messages. Normal updates may be passive; required/critical updates need Olympus-owned save/restart UI. Critical notifications repeat at reminderMinutes; other accepted notifications are not repeated continuously for the same pending release.

The client persists the first acceptance timestamp and resolved deadline before package download. Repeated HTTP 200/304 results, retries, and restarts cannot restart the countdown. A deadline can be shortened for the same release, but not extended or removed once established. Expiry is logged and communicated; it never grants permission to kill unsaved work. The agent does not automatically restart Olympus.

If minimumLauncherVersion or minimumAgentVersion is too high, the relevant process reports that the latest installer is needed. This is a manual bootstrap-upgrade requirement. The agent can stage an application needing a newer launcher, but that launcher must still enforce its own minimum before starting it. Foreground checks do not verify the installed agent binary's version.

Service release validation

Verify both query representations, real ZIP hashes/content, ETag behavior, a cold first install, a warm 304 response, interrupted package retry, and offline startup after policy acceptance. Include invalid JSON/required fields, wrong CPU, bad hash, missing prerequisites, older bootstrap versions, blocked application releases, and floor/data-epoch restrictions. Unit HTTP-handler tests do not demonstrate a working deployed service or authorization policy.

Previous
Next