Public Access
Let the desktop client replace itself, and give the repository one version
Packaging for Windows, and the updater that only exists once something is
packaged. Velopack, win-x64, fed from the project's own forge — never from the
deployment a client signs in to, which is ADR 0011 rule 2 carried over
unchanged and is why the feed address is a constant in the code rather than a
setting. See docs/adr/0012-desktop-distribution-and-updates.md.
**Nothing is ever installed while somebody is using it.** A newer build is found
on a six-hourly pass, downloaded in the background, and then waits — for a
restart the user presses, or for the next launch they were going to do anyway.
That is a policy rather than caution: this application argues at length that
locking keeps shells running, because a lock that destroyed work would stop
being used, and a restart does not keep them. Having taught that, it owes the
user the choice at the one moment it stops being true, and the sentence saying
so counts the shells it would close.
**The version is now derived from the v* tag**, by MinVer, for everything. There
was no version before this — no property anywhere, so every assembly reported
the SDK's 1.0.0 and the API served that string as its serverVersion to every
client that asked. The tag was already the version of record for the container
image; this makes it the version of record full stop. MinVer's failure mode is
answering plausibly rather than failing, and here a wrong version is a client
that never updates, so it is guarded twice: fetch-depth 0 on every checkout, and
a step that fails a tag build when the tag and the computed version disagree.
**The pack id is DodoSSH.Desktop and not DodoSSH**, which is the one decision
here that would have destroyed data. Velopack installs to %LOCALAPPDATA%\<packId>
and removes that whole directory on uninstall, and %LOCALAPPDATA%\DodoSSH is
where ClientPaths keeps the encrypted cache, the outbox of changes not yet
pushed, and the device key. The obvious id would have had the uninstaller
silently delete work the server has never seen — the thing the application
refuses to do without a counted confirmation. Velopack's own advice to move user
data to roaming %APPDATA% is declined for the reason ClientPaths already gives.
**Releases are cut by a person, and CI gains no job that could.** The tempting
argument is that a forge write token is not a signing key. It does not survive
contact with what the token does: Velopack clients trust their feed and do not
verify a package signature when they apply one, so whoever can write a release
can ship an update every install runs. That is the capability ADR 0011 rule 1
puts on a machine which is not a runner, reached through a different door. The
mechanical objection — vpk needs Windows and the runners are Linux — is the
smaller of the two and is recorded beside it, because somebody will fix one and
believe they are done.
Unsigned for now, deliberately and with the cost stated where a user reads it:
SmartScreen warns once per person, on Setup.exe, because Mark-of-the-Web is
applied by the browser that downloaded it. In-app updates are fetched by the
application and applied from a local file, and never trip it.
The banner is a fourth row of the window rather than an overlay. Anything drawn
in the terminal's rectangle is sliced by the native child window that composites
above it — the defect this window has shipped once — and a sibling row is the
arrangement TitleBar and StatusBar already prove works.
----
Three defects surfaced on the way, none of them in the feature being built.
**A settings key absent from the file came back as the CLR default, not the
declared one.** The JSON source generator builds a record through a synthesised
parameterised constructor and assigns every property from its argument array, so
a property initializer runs and is then overwritten by a default for anything the
file did not contain. A settings.json of {} read back a font size of 0, clamped
up to the 8px floor rather than the 13px the renderer draws at. It could not bite
while there was one setting, because that setting was written on every save and
so was never absent; adding a second would have turned automatic update checks
off for every existing profile, silently, the opposite of the documented default.
Reflection-based deserialisation of the same JSON answers correctly, which is why
every way of checking it by hand agrees except the one that ships. The defaults
now live on the constructor parameters, which is the only place the generator
reads them from.
**Declaring a RuntimeIdentifier on the desktop head broke the server's image
build.** It is the obvious way to let a self-contained publish restore under
locked mode, and it writes a net10.0/win-x64 target into the lock file of every
project the head references transitively — including DodoSSH.Contracts and
DodoSSH.Crypto, which the API builds too. The Dockerfile restores those with no
RID and fails NU1004. Found by running docker build rather than by reading. The
RID stays out of the committed state; the two commands that need one ask for it
unlocked, and the release script puts the lock files back.
**A Docker ARG named VERSION silently sets MSBuild's Version.** An ARG is an
environment variable for the rest of the stage, MSBuild reads environment
variables as properties, and property names are case-insensitive. With the
workflow passing main-<short sha> on a main build the publish died with
NETSDK1018 pointing at DodoSSH.Contracts, a project nobody had touched. The build
stage's argument is ASSEMBLY_VERSION now, empty except on a tag build.
All three are in docs/platform-flags.md, which is where the next person will look.
----
Verified: the whole solution builds and restores locked; 289 shell, 93 layout and
54 session tests pass, including the regression test for the settings defect and
a measurement of the banner at the window's minimum width. vpk pack runs end to
end and reports "Verified VelopackApp.Run()" against Program.Main. The API image
builds correctly both as a main build and as a tag build, carrying 1.0.0 and
0.1.0 respectively.
Not verified, and it needs a published release to be: installing, updating and
uninstalling on a real machine. That is Phase 15 of docs/manual-checks.md, and
the pack id and the WebView2 profile fix are reasoned and commented but only
proved by walking it. Two things to watch at the first upload — the reverse
proxy's body-size limit for a 64 MB asset, and whether vpk upload gitea is happy
with Gitea 1.27.1.
This commit is contained in:
@@ -0,0 +1,246 @@
|
||||
# ADR 0012 — Distributing the desktop client, and letting it replace itself
|
||||
|
||||
- Status: accepted
|
||||
- Date: 2026-08-04
|
||||
- Builds on: [ADR 0001](0001-e2ee-trust-model.md), [ADR 0011](0011-android-distribution.md)
|
||||
- Settles: the desktop half of M4 packaging, which [ADR 0011](0011-android-distribution.md#consequences)
|
||||
left open
|
||||
|
||||
## Context
|
||||
|
||||
[ADR 0011](0011-android-distribution.md) settled the phone and said explicitly what it was not settling:
|
||||
"M4's desktop packaging inherits rule 2 and not the rest." This is that inheritance, plus the thing the
|
||||
phone deliberately does not have.
|
||||
|
||||
The desktop head was not packaged at all. There were no tags, no `Version` property anywhere in the
|
||||
repository, and therefore no version: every assembly reported the SDK's default `1.0.0`, and the API had
|
||||
been serving that string to every client that asked it for `serverVersion`. There was no installer and no
|
||||
way for anybody holding a copy to learn that a newer one existed.
|
||||
|
||||
That is tolerable while nobody has it. It stops being tolerable at the first release, and it stops in a
|
||||
particular direction: this client holds the plaintext of a team's infrastructure credentials, by
|
||||
construction (ADR 0001). For software like that, "the fix shipped and the user never got it" is a security
|
||||
outcome. ADR 0011 named the cost of shipping outside a store — "no discovery, no automatic update" — and
|
||||
accepted it for Android because the platform left no better option. The desktop leaves a better option, and
|
||||
this ADR takes it.
|
||||
|
||||
The new thing an updater introduces is a capability that did not exist before: **something that can replace
|
||||
the binary on a user's machine, without the user choosing each build.** ADR 0001 models the party who wants
|
||||
the secrets as attacking the client rather than the crypto, and ADR 0011 turns that into a question of
|
||||
custody — *which parties can ship one person a build?* An updater is a second answer to that question, so
|
||||
it needs the same treatment as the signing key, and it is easy to get wrong because the dangerous part does
|
||||
not look like a key.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Velopack, per-user, under `%LOCALAPPDATA%`, with no administrator prompt
|
||||
|
||||
`docs/platform-flags.md` had already ruled out the platform-native option, and it is worth restating
|
||||
because it is the kind of decision that gets reopened: **MSIX is not deprioritised, it is impossible
|
||||
here.** A packaged application runs WebView2 in an AppContainer where loopback connections are blocked
|
||||
without a `CheckNetIsolation` exemption, and the terminal data plane *is* a loopback WebSocket. MSIX would
|
||||
not degrade the product, it would remove the terminal.
|
||||
|
||||
Velopack's path was checked against that and reintroduces nothing: `Setup.exe` is an ordinary Win32
|
||||
executable that unpacks a directory and creates shortcuts, there is no package manifest and no package
|
||||
identity, and the process therefore stays an ordinary desktop process. Manual check 15.4 is what would
|
||||
notice if that ever changed, because it connects a real shell from the installed build.
|
||||
|
||||
### 2. The pack id is `DodoSSH.Desktop`, and it is irreversible
|
||||
|
||||
Velopack installs to `%LOCALAPPDATA%\<packId>` and **removes that entire directory on uninstall**.
|
||||
`ClientPaths.DataDirectory` is `%LOCALAPPDATA%\DodoSSH`, and it holds `cache.db` with its `-wal` and `-shm`
|
||||
companions, `settings.json`, and `device.key`.
|
||||
|
||||
So the obvious pack id would have installed the application on top of the user's encrypted cache, and
|
||||
uninstalling would have deleted the device key and the outbox — the changes this machine has made and not
|
||||
yet pushed, which `MainWindowViewModel.SignOutWarning` already describes to users as existing "nowhere else
|
||||
in the world". The application refuses to delete that without a counted confirmation; an uninstaller would
|
||||
have done it silently.
|
||||
|
||||
Velopack's own guidance is to keep persistent files in roaming `%APPDATA%`. **That guidance is declined**,
|
||||
and `ClientPaths` already explains why: two machines writing one SQLite file through a file-sync client
|
||||
corrupts it, and the outbox is per-machine by design. The install moves; the profile does not.
|
||||
|
||||
Like the Android package id, this is a one-way door — it is the identity an installed client matches an
|
||||
update against, so changing it later orphans every existing install: still running, never updated, and
|
||||
invisible to the new one.
|
||||
|
||||
### 3. The release is cut by a person, and the forge token never goes near CI
|
||||
|
||||
This is the paragraph that will be argued with, so it is the one written most carefully.
|
||||
|
||||
The tempting argument is that a Gitea write token is not a signing key, and so — unlike the Android
|
||||
keystore ADR 0011 rule 1 keeps off runners — it could live in a CI secret and let a tag cut a release.
|
||||
|
||||
**It does not survive contact with what the token can do.** Velopack clients fetch from the configured
|
||||
source over TLS and do not verify a package signature when they apply it. So anyone who can write a release
|
||||
on this repository can publish an update that every installed client downloads and runs. That is precisely
|
||||
the capability ADR 0011 rule 1 places on a machine which is not a runner, reached through a different door —
|
||||
and a workflow secret is held by everyone who can change a workflow file, which for a repository with any
|
||||
contributors is a wider set than it looks.
|
||||
|
||||
So: `scripts/release-windows.ps1`, run by a person on a Windows machine, in two phases. Phase one builds and
|
||||
packs and stops. Phase two, a separate invocation, asks for the token and uploads. The split exists so that
|
||||
what reaches users has been installed and started by a human first, and so that the credential is in memory
|
||||
only for the minutes that need it.
|
||||
|
||||
There is a second, smaller reason the release could not be a CI job here anyway: `vpk` stamps and embeds
|
||||
the `Setup.exe` and `Update.exe` stubs with Windows tooling, and every job in `ci.yml` is
|
||||
`runs-on: [linux]`. Both reasons are recorded because somebody will fix one and believe they are done.
|
||||
|
||||
What CI does gain is the same thing the `android` job already does — it proves the artefact still builds.
|
||||
A `win-x64` publish runs on main and on tags, so a restore graph that resolves for `net10.0` and not for
|
||||
`net10.0/win-x64` fails there rather than under a person midway through a release.
|
||||
|
||||
### 4. The update check points at the project's forge, and the address is a constant
|
||||
|
||||
ADR 0011 rule 2 carries over unchanged, and its update clause carries with it: "If an update check is ever
|
||||
added it points at the project's domain." Here that is `git.dodotech.cloud`, and it is a `const` in
|
||||
`VelopackUpdateChannel` rather than a setting.
|
||||
|
||||
**The constant is the mechanism, not a convention.** A configurable feed address is exactly the knob that
|
||||
would let an operator — or an edit to a plaintext `settings.json` — point the update path at the
|
||||
deployment, and an operator who can answer "is there a newer version" can answer "no" forever, pinning a
|
||||
chosen user to a build with a known hole while holding no key at all. Making it unsettable is that rule
|
||||
expressed in a way nobody has to remember.
|
||||
|
||||
`ClientSettings` therefore stores whether to check, and nothing else: no address, no channel, no token. A
|
||||
private release repository is incompatible with this design and that is worth knowing rather than
|
||||
discovering, because the token would have to be readable before the vault is unlocked, and this file is the
|
||||
one place that can be read then — which is the one place a token may not go.
|
||||
|
||||
### 5. `MinClientVersion` stays unread, and if it is ever read it may not fetch
|
||||
|
||||
`MetaResponse.MinClientVersion` has existed since M1, is served, is fetched on every sign-in, and is read
|
||||
by nothing. Hanging the updater off it would have been natural and would have been wrong — and note the
|
||||
shape of the error, because it is not "inherits an existing risk". Today the field controls nothing at all.
|
||||
The moment an update check is conditioned on it, rule 2's sentence applies verbatim and the risk is
|
||||
*created*.
|
||||
|
||||
The split to preserve:
|
||||
|
||||
- A deployment may say **"I will not serve a client this old"** and draw a remediation screen. That is the
|
||||
deployment describing itself, which is legitimate and is what the field's own documentation asks for.
|
||||
That screen may carry a sentence and a link to the project's release page.
|
||||
- It may **not** carry a button that triggers a check or a download. A link is the user going somewhere; a
|
||||
fetch is the operator's answer steering this process.
|
||||
|
||||
Under the design as built, an operator withholding or deflating the value achieves nothing — the check runs
|
||||
on its own timer and never consults the deployment. Inflating it denies service to their own users, which
|
||||
they can already do by turning the server off.
|
||||
|
||||
### 6. Self-contained, and not single-file
|
||||
|
||||
Self-contained because .NET 10 is recent enough that almost no machine has the runtime, and because the
|
||||
usual objection — that runtime security patches then require an application update — is answered by the
|
||||
feature this ADR is about. Velopack's deltas are per-file and the runtime files do not change between our
|
||||
releases, so the runtime costs almost nothing per update; it is paid on first install.
|
||||
|
||||
Not single-file, for four independent reasons: `platform-flags.md` records that libsodium ships native
|
||||
binaries per RID and complicates single-file publishing, and `libe_sqlite3`, `libSkiaSharp` and
|
||||
`libHarfBuzzSharp` do the same; a bundle changes wholly on every build, so deltas stop working; Velopack is
|
||||
a directory-based updater by design; and a self-extracting bundle puts the executable under a temp path
|
||||
deep enough to hit the WebView2 long-path failure that same document records. Not trimmed — EF Core is not
|
||||
trim-safe and `TreatWarningsAsErrors` turns every `IL2xxx` into a build break, so trimming is a project
|
||||
rather than a flag.
|
||||
|
||||
**Native symbol files are excluded and ours are kept**, which is worth recording as a decision because the
|
||||
numbers are so lopsided: `libSkiaSharp.pdb` and `libHarfBuzzSharp.pdb` are 100 MB of debug symbols for
|
||||
third-party native code nobody here will step through, and all fifteen of our own managed PDBs together are
|
||||
0.93 MB. Dropping the two took a publish from 227 MB to 127 MB. Keeping ours means an
|
||||
`Exception.ToString()` carries file names and line numbers, which for a self-hosted product is the whole
|
||||
diagnostic channel — the way a fault gets reported is a user pasting a stack into an issue.
|
||||
|
||||
### 7. One version, derived from the tag
|
||||
|
||||
MinVer, with `MinVerTagPrefix` of `v`, matching the tags CI already triggers on. The tag was already the
|
||||
version of record for the API's container image; this makes it the version of record for everything,
|
||||
including the client's own `AssemblyInformationalVersion`, which is what the preferences screen prints and
|
||||
what Velopack compares.
|
||||
|
||||
MinVer's one sharp edge is that it answers plausibly rather than failing: a shallow clone with no tags
|
||||
yields `0.0.0-alpha.0.N`. Here a wrong version is a client that never updates, so it is guarded twice —
|
||||
`fetch-depth: 0` on every checkout, and a step that fails a tag build when the computed version and the tag
|
||||
disagree.
|
||||
|
||||
The Windows application manifest's `assemblyIdentity` version is **deliberately** left at `1.0.0.0`. It is a
|
||||
side-by-side activation field this application does not use and nothing reads; what a person sees comes from
|
||||
the PE version resource, which MSBuild fills from `FileVersion`.
|
||||
|
||||
### 8. Unsigned for now, with a named trigger
|
||||
|
||||
Every installer will raise SmartScreen's "Windows protected your PC" until reputation accrues. The cost is
|
||||
smaller and more precisely bounded than the reflex suggests, and the bound is worth knowing: Mark-of-the-Web
|
||||
is applied by the *browser* that downloads `Setup.exe`, so the warning lands at first install only. In-app
|
||||
updates are fetched by the application's own HTTP client and applied by `Update.exe` from a local file, and
|
||||
never trip it. **One dialog per user per lifetime, not one per update.**
|
||||
|
||||
The trigger for buying an OV certificate on a hardware token is the first release the README invites a
|
||||
stranger to install. ADR 0011 already describes Authenticode as the easy custody case — the key stays with
|
||||
the developer — and the post-2023 requirement that it live on FIPS 140-2 Level 2 hardware enforces "offline,
|
||||
never in CI" physically rather than by policy. `--signParams` is the single line in the release script that
|
||||
changes.
|
||||
|
||||
**Azure Trusted Signing is not the quiet default and needs its own ADR.** It is cheaper and has no hardware
|
||||
token, and it puts a compellable third party in the signing path — which is ADR 0011 rule 3's shape one
|
||||
layer down, declined there for reasons that do not stop applying because the vendor changed.
|
||||
|
||||
## Consequences
|
||||
|
||||
**The desktop gets what ADR 0011 had to refuse the phone.** Discovery is still manual — somebody has to be
|
||||
told where the release page is — but from the first install onward the client keeps itself current without
|
||||
anybody deciding to go and look. That is the sharpest edge of the Android decision, blunted on the platform
|
||||
where it could be.
|
||||
|
||||
**Nothing is ever installed while the application is running.** A fetched update waits for a restart the
|
||||
user presses, or for the next launch they were going to do anyway. This is not caution for its own sake:
|
||||
this application deliberately keeps shells running across a lock, and argues in `LockAsync` that a lock
|
||||
which destroyed work would simply stop being used. A restart does end every shell, so it is a decision that
|
||||
belongs to the person whose job is running in one — and the interface says so, in the same words the close
|
||||
button already uses.
|
||||
|
||||
**The release is a manual step, and that will feel slow.** It is roughly ten minutes of a person's attention
|
||||
per release, and the convenience being refused is the entire point of CI. Where the two collide the custody
|
||||
argument wins, exactly as it does for the Android keystore.
|
||||
|
||||
**The forge grows by about 125 MB per release, forever.** Measured on the first real pack rather than
|
||||
estimated: a 127 MB publish directory compresses to a 60 MB full `.nupkg` and a 64 MB `Setup.exe`, and both
|
||||
are uploaded. Velopack needs the previous full package present to build a delta against, so pruning old
|
||||
releases has a real cost — a client several versions behind falls back to a full download. A 64 MB asset is
|
||||
also large enough to meet whatever body-size limit fronts `git.dodotech.cloud` (nginx's
|
||||
`client_max_body_size` defaults to 1 MB), which is worth checking before the first upload rather than
|
||||
discovering after ten minutes of transfer.
|
||||
|
||||
**Uninstalling leaves the vault cache behind, on purpose.** `%LOCALAPPDATA%\DodoSSH` survives, so a
|
||||
reinstall finds an enrolled machine and asks for the passphrase — which is what somebody reinstalling wants.
|
||||
The honest cost is that `device.key` is left too, and the account goes on listing a device that is no longer
|
||||
installed. That is a wart rather than a hole: the blob is decryptable only by this machine's TPM, and Sign
|
||||
Out is the button that withdraws the registration. An uninstall is not a sign-out and must not pretend to
|
||||
be one.
|
||||
|
||||
**Contracts and client now share a version number.** `DodoSSH.Contracts` is packable, so a contracts-only
|
||||
change ships as a client version bump. One number is the point; this is the price of it.
|
||||
|
||||
**The Android head's `versionName` now follows the same tag**, while its integer `versionCode` stays
|
||||
hand-bumped, because Android needs a monotonic integer and SemVer does not provide one. Nothing else about
|
||||
ADR 0011 changes.
|
||||
|
||||
## Rejected
|
||||
|
||||
- **MSIX.** Not a preference. It would break the terminal outright; see decision 1.
|
||||
- **A CI job that cuts the release on a tag.** The convenience is the point of CI and the custody is the
|
||||
point of ADR 0011; where they collide the custody wins. See decision 3, and note that a Windows runner
|
||||
answers the mechanical objection while leaving the real one untouched.
|
||||
- **A configurable update feed.** Named here because it is the change somebody will propose in good faith,
|
||||
for a self-hosted product where making things configurable is usually right. It is the one setting that
|
||||
would hand the operator the capability the whole trust model is about.
|
||||
- **The deployment serving the installer.** Refused again, for the third ADR running, because it is
|
||||
genuinely the nicest onboarding available and will be proposed again.
|
||||
- **Conditioning updates on `MinClientVersion`.** See decision 5. It would create the attack rather than
|
||||
inherit it.
|
||||
- **Azure Trusted Signing**, for now, on custody grounds rather than on mechanics. See decision 8.
|
||||
- **A hand-edited version property.** Considered seriously against MinVer, and it loses on the thing that
|
||||
matters here: the tag is already the version of record for the container image, and two places to write
|
||||
one number is a pair that can disagree. MinVer's silent-wrong-answer failure mode is real and is what the
|
||||
two CI guards in decision 7 exist for.
|
||||
@@ -1465,3 +1465,127 @@ delivery survives the failure because it is held against the transfer rather tha
|
||||
**Failure means:** a retry that succeeds but leaves the destination empty is the delivery having been
|
||||
dropped on the failure. An error saying the staged file is missing is the copy having been deleted at the
|
||||
stop, which is what `QueueDeliveredDownload` documents it does not do.
|
||||
|
||||
---
|
||||
|
||||
## Phase 15 — Installing the desktop client, and being updated by it
|
||||
|
||||
Nothing in this phase is reachable by a test, and not for the usual reason. There is no installed
|
||||
application in CI, no `%LOCALAPPDATA%` worth inspecting, and the update path only exists across two builds
|
||||
published minutes apart — so what is being checked is the shape of a release, which only exists once
|
||||
somebody has cut one. What *is* automated is the machinery underneath: `UpdateFlowTests` drives every state
|
||||
of the view model against a fake channel, and pins the one promise that matters
|
||||
(`AReadyUpdate_IsNeverAppliedOnItsOwn`); `UpdateBannerTests` measures the banner at the window's minimum
|
||||
width. Neither can install anything.
|
||||
|
||||
Walk it once per release, and in order — 15.6 onwards needs 15.1 to have happened.
|
||||
|
||||
Run `pwsh -File scripts/release-windows.ps1` first. It stops after packing, on purpose, so that everything
|
||||
below happens before anything reaches a user.
|
||||
|
||||
### 15.1 The installer needs no administrator, and lands beside the vault rather than on it · **the one that would destroy data**
|
||||
|
||||
Run `Releases\DodoSSH.Desktop-win-Setup.exe` from an ordinary account. Then look at `%LOCALAPPDATA%`.
|
||||
|
||||
**Pass:** no UAC prompt; `%LOCALAPPDATA%\DodoSSH.Desktop\current\DodoSSH.exe` exists; a Start-menu entry
|
||||
reading **DodoSSH**; and `%LOCALAPPDATA%\DodoSSH` either absent (a fresh machine) or **untouched**.
|
||||
|
||||
**Failure means:** a UAC prompt is a per-machine install, which is not what was designed. Anything written
|
||||
into `%LOCALAPPDATA%\DodoSSH` is the pack id having drifted back to `DodoSSH`, and that is the serious one —
|
||||
the uninstaller removes its whole install root, so it would take the vault cache and the outbox with it.
|
||||
See [ADR 0012](adr/0012-desktop-distribution-and-updates.md) decision 2.
|
||||
|
||||
### 15.2 The installed path is short, measured rather than assumed
|
||||
|
||||
```powershell
|
||||
"$env:LOCALAPPDATA\DodoSSH.Desktop\current\DodoSSH.exe".Length
|
||||
```
|
||||
|
||||
**Pass:** under 100. It is 64 on an ordinary profile.
|
||||
|
||||
**Failure means:** folder redirection, or a very long profile path. The terminal is about to fail with
|
||||
`CO_E_SERVER_EXEC_FAILURE` and name nothing — see the long-path entry in `platform-flags.md`, which is the
|
||||
reason this check is a number rather than a shrug.
|
||||
|
||||
### 15.3 The window opens and carries its own icon
|
||||
|
||||
**Pass:** the Start-menu shortcut launches it, and the taskbar and Alt-Tab show the dodo mark rather than a
|
||||
generic icon.
|
||||
|
||||
**Failure means:** `--icon` or `ApplicationIcon` did not survive packaging. Cosmetic, and the first thing
|
||||
anybody notices.
|
||||
|
||||
### 15.4 A terminal connects from the installed build · **the one that would catch an AppContainer**
|
||||
|
||||
Sign in, unlock, open a shell against a real host, and type.
|
||||
|
||||
**Pass:** characters reach the remote and output comes back.
|
||||
|
||||
**Failure means:** if it hangs and then reports the WebView2 message after about fifteen seconds, the
|
||||
renderer never attached — check whether packaging has given the process a package identity, which would put
|
||||
WebView2 in an AppContainer where the loopback data plane cannot connect. That is the failure MSIX was ruled
|
||||
out for, and this is the check that would find it in the Velopack path. `RendererTimeout` is where the
|
||||
fifteen seconds comes from.
|
||||
|
||||
### 15.5 The version on screen is the version that was built
|
||||
|
||||
Right-click `DodoSSH.exe` → Properties → Details, and open PREFERENCES → UPDATES.
|
||||
|
||||
**Pass:** File version reads the tag (`0.1.0.0`), product **DodoSSH**, company **DodoTech**, and the
|
||||
preferences screen prints the same number.
|
||||
|
||||
**Failure means:** `0.0.0.0` is MinVer never seeing a tag — a shallow clone, or `fetch-depth` having been
|
||||
dropped from a checkout. `1.0.0.0` is somebody having wired the app manifest's inert `assemblyIdentity`
|
||||
version to the real one. A version on screen that differs from the file properties means the two are being
|
||||
read from different places, which is the thing having one number was for.
|
||||
|
||||
### 15.6 A second release produces a delta, not only a full package
|
||||
|
||||
Tag `v0.1.1` and run the script again.
|
||||
|
||||
**Pass:** `Releases\` holds both a `*-full.nupkg` and a `*-delta.nupkg`, and the delta is a small fraction
|
||||
of the full.
|
||||
|
||||
**Failure means:** no delta at all is `vpk download gitea` having found nothing to build one against — the
|
||||
previous release did not come down, so every user is about to fetch a ~60 MB full package for a one-line
|
||||
change. The
|
||||
script warns rather than failing when that is legitimate, which is the first release only.
|
||||
|
||||
### 15.7 The update arrives, and the restart lands in it · **the whole point of the work**
|
||||
|
||||
With v0.1.0 installed and running, a vault unlocked, a host change made, and **a terminal open**, publish
|
||||
v0.1.1 (`-Upload`). Then press CHECK NOW on PREFERENCES rather than waiting six hours.
|
||||
|
||||
**Pass:** the progress bar moves, the banner appears above the status bar, and — the part to actually watch
|
||||
— the terminal **reflows cleanly rather than being sliced**, with the remote seeing the smaller row count.
|
||||
Press **RESTART NOW**: the application closes and reopens as 0.1.1, still enrolled, with the host change
|
||||
intact.
|
||||
|
||||
**Failure means:** no banner is a channel mismatch between `vpk pack --channel` and
|
||||
`VelopackUpdateChannel.ReleaseChannel`, which fails silently by design — the check succeeds, finds nothing,
|
||||
and reports the client up to date forever. A banner sliced at the terminal's left edge is the occlusion rule
|
||||
having been broken, and the fallback is to move the offer into the titlebar instead. Coming back as 0.1.0 is
|
||||
the swap having been blocked, usually by a process still holding a file under `current\`. Being asked to
|
||||
enrol again means the profile directory did not survive, which is 15.1's failure arriving late.
|
||||
|
||||
### 15.8 The first connect after an update is not a cold start
|
||||
|
||||
Immediately after 15.7, connect to a host.
|
||||
|
||||
**Pass:** the terminal appears about as quickly as it did before the update.
|
||||
|
||||
**Failure means:** the WebView2 user data folder is back inside `current\` and was destroyed by the update —
|
||||
see the entry in `platform-flags.md`. Slow but working, so it gets dismissed as a fluke unless somebody is
|
||||
looking for it, which is why it is a numbered check rather than a note.
|
||||
|
||||
### 15.9 Uninstalling removes the application and leaves the vault · **the data-loss check**
|
||||
|
||||
Settings → Apps → DodoSSH → Uninstall.
|
||||
|
||||
**Pass:** `%LOCALAPPDATA%\DodoSSH.Desktop` is gone, and `%LOCALAPPDATA%\DodoSSH` still holds `cache.db`,
|
||||
`cache.db-wal` and `cache.db-shm` — all three, per the entry that says any routine touching only the first
|
||||
is wrong. Reinstalling then asks for the passphrase rather than for a server.
|
||||
|
||||
**Failure means:** the cache going with the application is the pack-id collision, and whoever ran this has
|
||||
lost their offline unlock and any change that was still in the outbox. That is the failure ADR 0012
|
||||
decision 2 exists to prevent, and it is why 15.1 checks the same thing from the other end.
|
||||
|
||||
+86
-2
@@ -217,8 +217,33 @@ execution failed") and the terminal never appears. Hit while building the harnes
|
||||
that failed from a ~230-character directory ran first time from `%TEMP%\h`. The exact threshold was not
|
||||
established and the mechanism is unconfirmed — the user data folder is created beside the executable by
|
||||
default and the browser process is launched with paths derived from it, so `MAX_PATH` is the obvious
|
||||
suspect. Relevant to packaging: an installer that lands under a deep per-user path would break the
|
||||
terminal with an error that names nothing.
|
||||
suspect.
|
||||
|
||||
*Measured for the packaged layout, so this stops being a worry and becomes a number.* Velopack installs to
|
||||
`%LOCALAPPDATA%\DodoSSH.Desktop\current\`, and `…\AppData\Local\DodoSSH.Desktop\current\DodoSSH.exe` is
|
||||
**64 characters** against the ~230 that reproduced the failure — about 180 characters of headroom, and a
|
||||
40-character corporate username adds 35 of them back. The shipped installer is not at risk. Two things
|
||||
would reopen it and neither is in the plan: a self-extracting single-file publish, whose native libraries
|
||||
land under a hashed temp path, and `%LOCALAPPDATA%` folder-redirected to a deep UNC path in a domain.
|
||||
Manual check 15.2 measures it on the real machine rather than trusting this paragraph.
|
||||
|
||||
**WebView2's user data folder must be kept out of the install directory.** It defaults to a directory
|
||||
beside the host executable, which under Velopack is inside `current\` — and `current\` is *replaced* by
|
||||
every update. Left alone, the browser profile would be destroyed on each one, so the first connect after
|
||||
every update would pay a cold WebView2 start: a fresh user-data directory and a new process tree, which is
|
||||
the slow path `RendererTimeout`'s fifteen seconds was sized for, arriving at the exact moment somebody is
|
||||
most ready to believe the update broke the terminal. `Program.Main` sets `WEBVIEW2_USER_DATA_FOLDER` to
|
||||
`%LOCALAPPDATA%\DodoSSH\WebView2` — under the profile directory, which Velopack never touches. Check 15.8
|
||||
is what would notice it regressing, and it is worth having because the symptom is "slow but working", which
|
||||
gets dismissed as a fluke.
|
||||
|
||||
**The install root and the profile directory must not be the same folder.** Velopack removes
|
||||
`%LOCALAPPDATA%\<packId>` entirely on uninstall, and `ClientPaths` puts `cache.db` (plus `-wal` and `-shm`),
|
||||
`settings.json` and `device.key` in `%LOCALAPPDATA%\DodoSSH`. So a pack id of `DodoSSH` — the obvious
|
||||
choice — would have made the uninstaller delete the vault cache and the outbox of changes not yet pushed,
|
||||
silently, which is the thing the application will not do without a counted confirmation. The pack id is
|
||||
`DodoSSH.Desktop` for that reason and no other; `--packTitle` supplies the name people see, so nothing is
|
||||
lost. Do not "tidy" it. See [ADR 0012](adr/0012-desktop-distribution-and-updates.md) and check 15.9.
|
||||
|
||||
**The Windows app manifest must declare a `supportedOS` list.** Without it the process reports a
|
||||
downlevel Windows version and Avalonia's native control host fails outright — *"Unable to create child
|
||||
@@ -329,6 +354,15 @@ AppContainer where loopback connections are blocked without a `CheckNetIsolation
|
||||
terminal data plane *is* a loopback WebSocket, so MSIX would break the product outright. Velopack
|
||||
for Windows/macOS/AppImage; Flatpak and deb/rpm defer updates to the package manager.
|
||||
|
||||
*Checked rather than assumed, now that Velopack is actually wired up:* its Windows path does not
|
||||
reintroduce the thing MSIX was ruled out for. `Setup.exe` is an ordinary Win32 executable that unpacks a
|
||||
directory under `%LOCALAPPDATA%` and creates shortcuts — there is no `AppxManifest`, no package identity,
|
||||
no `runFullTrust`, no elevation and no execution alias, so the process stays an ordinary desktop process
|
||||
and WebView2 stays out of an AppContainer. That is reasoning, not measurement; manual check 15.4 is the
|
||||
measurement, because if a package identity ever did appear the symptom would be the terminal hanging and
|
||||
then reporting the WebView2 message after fifteen seconds, which reads like a broken runtime rather than
|
||||
like packaging.
|
||||
|
||||
**Linux ships AppImage and Flatpak first**, specifically so the WebKit runtime is bundled rather
|
||||
than assumed present on the user's machine.
|
||||
|
||||
@@ -486,6 +520,56 @@ so it cannot be discovered from Kestrel afterwards. The window for another proce
|
||||
few milliseconds; if the suite ever fails with an address-in-use, this is why, and a retry is the fix
|
||||
rather than a redesign.
|
||||
|
||||
**A RID must never reach the committed lock files, and the obvious fix for a RID-specific publish puts
|
||||
one there.** `dotnet publish -r win-x64` resolves a graph the committed `packages.lock.json` files do not
|
||||
describe — they carry a `net10.0` target and nothing else — so under locked mode it fails NU1004. The
|
||||
obvious answer is `<RuntimeIdentifiers>win-x64</RuntimeIdentifiers>` on the desktop head plus a
|
||||
`--force-evaluate` to regenerate. **That is wrong here, and it was tried and reverted.**
|
||||
|
||||
A RID declared on one project flows to every project it references transitively while restoring, so the
|
||||
regenerated lock files for `DodoSSH.Contracts` and `DodoSSH.Crypto` grew a `net10.0/win-x64` target as
|
||||
well — and those two are built by the *server*. The API's Dockerfile restores them with no RID and
|
||||
`--locked-mode`, so it failed:
|
||||
|
||||
```
|
||||
error NU1004: The project's runtime identifiers have changed from.
|
||||
Project's runtime identifiers: , lock file's runtime identifiers win-x64.
|
||||
```
|
||||
|
||||
Packaging the desktop client had broken the server's image build, and nothing but the `image` job would
|
||||
have caught it. Found by running `docker build` locally rather than by reading the lock files.
|
||||
|
||||
So the RID stays out of the committed state, and the two commands that need one — the release script's
|
||||
publish and the `windows publish still resolves` step in `ci.yml` — pass `-p:RestoreLockedMode=false` for
|
||||
themselves alone. That restore rewrites the lock files as a side effect, which does not matter on a runner
|
||||
whose checkout is discarded and does matter on a developer's machine, so the release script runs
|
||||
`git checkout -- '*packages.lock.json'` afterwards. `-p:RestorePackagesWithLockFile=false` is not an
|
||||
alternative: it fails NU1005 whenever a lock file already exists.
|
||||
|
||||
**A Docker `ARG` named `VERSION` silently sets MSBuild's `Version`.** An `ARG` is an environment variable
|
||||
for the rest of the stage, MSBuild reads environment variables as global properties, and MSBuild property
|
||||
names are case-insensitive — so `ARG VERSION` in a build stage sets `Version` for every project built in
|
||||
it, with no line anywhere saying so. The workflow passes `main-<short sha>` on a main build, which is a
|
||||
fine docker tag and not a version, and the publish died with `NETSDK1018: Invalid NuGet version string`
|
||||
pointing at `DodoSSH.Contracts` — a project nobody had touched. The build stage's argument is therefore
|
||||
`ASSEMBLY_VERSION`, passed empty except on a tag build; the `VERSION` arg in the final stage is only ever
|
||||
an OCI label and never meets MSBuild. Renaming is the entire fix, and the reason it is written down is that
|
||||
the symptom names the wrong project and the cause is invisible.
|
||||
|
||||
**System.Text.Json's source generator does not honour property initializers on a record.** Defaults for a
|
||||
`ClientSettings`-style record must live on the **constructor parameters**, not on property initializers,
|
||||
and getting it wrong fails silently in the worst direction. The generator emits an
|
||||
`ObjectWithParameterizedConstructorCreator` — it treats the init-only properties as constructor arguments
|
||||
and builds `new ClientSettings() { A = (T)args[0], … }`, so the initializer runs and is then overwritten by
|
||||
`args`, which for a member absent from the JSON is the CLR default. Measured: a `settings.json` of `{}`
|
||||
read back `TerminalFontSize` 0 (clamped up to the 8px floor, not the 13px the renderer draws at) and, once
|
||||
it existed, `AutomaticUpdateChecks` false. **Reflection-based deserialisation of the same JSON answers 13
|
||||
and true**, which is what makes it so easy to miss — every way of checking it by hand is right except the
|
||||
one that ships. `JsonSourceGenerationMode.Metadata` does not help; it was tried. It stayed invisible while
|
||||
there was one setting, because that setting was written on every save and so was never absent; it went live
|
||||
the moment a second one was added, since every existing profile lacks the new key.
|
||||
`ASettingAbsentFromTheFile_ComesBackAsItsDeclaredDefault` fails without the fix.
|
||||
|
||||
**`[CallerFilePath]` is rewritten to `/_/...` under `ContinuousIntegrationBuild`.** Any test that
|
||||
locates a fixture by source path passes locally and fails in CI. Copy fixtures to the output
|
||||
directory and read them via `AppContext.BaseDirectory` instead; `GoldenVectorTests` shows the
|
||||
|
||||
Reference in New Issue
Block a user