Status: historical design record (Pullwell has since been built from it and is a standalone program; the NetMerge references below describe where the code came from at the time).
Original status: design for review, no code written yet. Written 2026-11-10 against NetMerge main at commit
0bfab33 (3.11.20) and docs/convoy-handover.md from that commit. Target: Windows 10 and 11, 64-bit (x64).
Legend: [PC] = needs a real Windows PC to test. [here] = can be checked in the cloud workspace (Linux, Go
1.24.7 installed): unit tests of the pure-Go parts, and a cross-compile with GOOS=windows that proves the Windows
code compiles, not that it works.
| # | Decision | Why |
|---|---|---|
| D1 | The name lives in one file, appname.go. Everything else is derived from it: the window title, the data folder, the custom header (X-Pullwell), the mutex name, the toast app id, the link scheme (pullwell://) and the window classes. |
A rename changes one constant. |
| D2 | One UI thread owns the window, the tray icon, WebView2 and the toasts, with one Windows message loop. The download engine never touches them; it sends messages to that thread. | WebView2 and Windows COM objects must be used from the thread that created them. One owner avoids a whole class of crashes. |
| D3 | WebView2 without WebView2Loader.dll: own small wrapper, standard library only. It finds the runtime the way the open-source loaders do (registry, then EmbeddedBrowserWebView.dll). No DLL is written to disk. |
It keeps the “no third-party modules” rule. Dropping a DLL and loading it is the kind of thing antivirus products dislike (handover 7.7). Details in 4.1. |
| D4 | Fallback chain for the window: WebView2, then Edge/Chrome app mode (NetMerge’s tested code), then the default browser. The page is told which one it is in. | The program must always open, even if WebView2 is missing or broken. |
| D5 | Single instance per data folder. A second start hands over to the first one with a window message (no network), and the first window comes to the front. | A test copy with its own data folder can still run next to the real one (lesson of NetMerge 3.11.12). |
| D6 | Closing the window hides it; the program stays in the tray. The web view is closed when the window hides and recreated on open, to give back its memory. | A download manager lives in the tray for days. A hidden web view keeps about 100 MB or more in its helper processes (to be measured [PC]). |
| D7 | Toasts are for the installed version only (as agreed). Toast buttons call back through a pullwell:// link that carries a one-time random token. |
It needs no background COM server, it works after the toast has moved to the Action Center, and the token stops web pages from using the link. Details in 6.4. |
| D8 | Notification setting becomes three-way: All, Problems only, Off. Default: All. The old noNotify: true reads as “Problems only”. |
Today noNotify silences only “finished”, while “needs attention”, “checksum does not match” and “downloads finished” ignore it. That’s sensible, but the setting doesn’t say so. Now it does. |
| D9 | No PowerShell anywhere. Shortcuts are made through the Windows shell API, and “Start with Windows” uses the per-user Run key (no scheduled task, no administrator). | Handover 7.7. NetMerge uses PowerShell for its desktop shortcut and to adjust its scheduled task; Pullwell copies neither. |
D3 is the one decision that changes a stated default in a meaningful way, so here is the alternative:
vendoring github.com/wailsapp/go-webview2 (MIT, used by the Wails framework) at a pinned commit. Its default build
already uses a pure-Go loader with no DLL, but it brings golang.org/x/sys as a dependency and about 35,000 lines
of generated code. My choice is the own wrapper, using that library’s code only as the reference for method order
and the runtime lookup (with credit in the source). If the own wrapper cannot be made stable on a real PC within a
reasonable effort, vendoring the library is the fallback plan, and I will tell you before doing it.
// appname.go: the only place the product name is written.
const AppName = "Pullwell"
var (
appID = AppName + ".App" // toast app id (AppUserModelID)
appScheme = strings.ToLower(AppName) // pullwell://
appHeader = "X-" + AppName // required on every POST to the local API
appDataDir = AppName // %LOCALAPPDATA%\Pullwell\data when installed
)
A test ([here]) fails if the string “Pullwell” appears anywhere else in Go code, except in appname.go, the
changelog and the docs. Copied dm/ texts that say “NetMerge” (for example “Open NetMerge to cancel”) are changed to
use AppName.
main goroutine ── starts the local server, the download engine, then the UI thread
UI thread (runtime.LockOSThread, COM single-threaded) ── message loop for:
hidden message window (second-start hand-over, tray callbacks, "post to UI" calls)
main window (WebView2 inside)
tray icon
toasts
engine goroutines ── call ui.Post(func(){ ... }) to ask the UI thread to do something
ui.Post(f) puts f on a queue and posts one message to the hidden window, which runs the queued functions.safeHandler, rule 4.5.7).syscall.NewCallback has a limit of about 2,000 for the whole
process, so callbacks are never created per window, per toast or per event).Local\Pullwell-<hash of the data folder>.PullwellMsg-<hash>), call AllowSetForegroundWindow with the first instance’s process id, send it the
command line with WM_COPYDATA (for example “show”, or a pullwell:// link from a toast), and exit.Why AllowSetForegroundWindow: the second start is the program the person just launched, so Windows lets it hand
its right to take the focus to the first instance. This is the documented way, and it should avoid the
AttachThreadInput workaround NetMerge needed for Explorer (handover 7.4). That workaround stays available for
“Show in folder”, where it was proven to work. [PC]
Tests: the parsing of the hand-over message [here]; two starts, a start while the window is minimised, a start while another program has the focus [PC].
The open-source loaders do this, and I read the MIT-licensed Go port to confirm the steps:
EBWebView under
Software\Microsoft\EdgeUpdate\ClientState\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5} (the stable WebView2 runtime),
first in HKEY_LOCAL_MACHINE, then in HKEY_CURRENT_USER, using the 32-bit registry view. The value is the
runtime’s folder, whose name is its version.<folder>\EBWebView\x64\EmbeddedBrowserWebView.dll and call its export
CreateWebViewEnvironmentWithOptionsInternal.http://127.0.0.1:<port>/.Risk: step 3 calls an entry point Microsoft does not document. Wails and the open-source loaders rely on it, so it’s widely used, but a future runtime could change it. Protection: any failure in steps 1-4 is logged with the reason and the program falls back to Edge/Chrome app mode (D4). It never fails to open.
The web view’s own data (cache, local storage) goes in data\webview. Settings: no developer tools unless started
with --debug, no status bar, default context menu kept for copy and paste.
http://127.0.0.1:<port>/ load inside the window. Any other link (a help page, the GitHub
releases page) opens in the default browser. A request for a new window does the same.Origin, so the local API guard (handover 4.6) works
unchanged.GET /api/app/info which host it runs in (webview2, app-mode or browser) and show a
one-line note in the last two cases.| Action | Result |
|---|---|
| Start normally | Window opens. |
Start with Windows (--tray) |
Tray icon only, no window. |
| Close (X) | Window hides, web view closes, downloads continue. The first time only, a balloon or toast says “Pullwell is still running in the notification area.” |
| Tray click, “Open” in the tray menu, second start | Window shows, web view is recreated if it was closed, window comes to the front. |
| Quit (tray menu) | Engine stops and saves its state (at most 5 seconds), tray icon is removed, web view closes, program exits. No confirmation; unfinished downloads continue at the next start. |
data\window.json. On load they’re checked against the monitors that exist
now. A position on a monitor that has gone becomes centred on the main monitor. Impossible sizes (smaller than
720x480, larger than the screen) are replaced (rule 4.5.5).Measure on the PC [PC]: memory of the hidden program with the web view closed, and the time from tray click to a usable window. If reopening takes more than about a second, keep the web view alive instead and accept the memory.
openWindow code, with its own profile folder in
data\ui-profile, and focus through NetMerge’s focusExistingWindow (matched by window class and the title
“Pullwell”).A port of NetMerge’s sys_tray_windows.go, which is tested on real PCs, including putting the icon back after
Explorer restarts.
.ico), with a second variant shown while something is downloading.Pullwell - 3 downloading, 4.2 MB/s or Pullwell - nothing downloading (Windows allows 127
characters).Tests: the tooltip text for different states [here]; everything else [PC].
Host.Notify(title, text) becomes Host.Notify(n Notice), a change to Pullwell’s copy of dm/ only:
type Notice struct {
Kind string // "finished", "attention", "checksum", "allDone", "shutdown"
Title string // plain words, already written by the engine today
Text string
ItemID string // empty for "allDone" and "shutdown"
}
The engine already has the four places that notify (finished, needs attention, checksum does not match, downloads
finished with the power action). Only their call changes. The engine checks the setting in one place:
“Problems only” lets attention, checksum and shutdown through.
Notices are collected for 3 seconds before anything is shown.
This logic is pure Go, so it’s fully testable [here] with a fake clock.
Pullwell.App) as a shortcut property, through
the Windows shell API (no PowerShell). The program also sets the same id on itself at start, so its taskbar button
and its toasts belong together.ToastNotificationManager for our app id, an XML document, Show). All text from file names and servers is
XML-escaped.Example of the XML for one finished download:
<toast launch="pullwell://show?item=d1762741234-7&t=9f2c41a0d3" activationType="protocol">
<visual><binding template="ToastGeneric">
<text>Download finished</text>
<text>ubuntu-24.04.iso (5.8 GB)</text>
</binding></visual>
<actions>
<action content="Open" activationType="protocol" arguments="pullwell://open?item=d1762741234-7&t=9f2c41a0d3"/>
<action content="Show in folder" activationType="protocol" arguments="pullwell://reveal?item=d1762741234-7&t=9f2c41a0d3"/>
</actions>
</toast>
pullwell:// link (security matters here)The installer registers pullwell:// for the current user, pointing to Pullwell.exe "%1". A click starts a short
second copy, which hands the link to the running program (section 3) and exits. If Pullwell isn’t running, it
starts and handles the link.
Any web page can also try to open a pullwell:// link (the browser asks the person first, but people click
“Allow”). Download ids are predictable (d<time>-<number> in dl_manager.go), and “Open” runs a downloaded file,
which may be a program. So:
.exe, .msi, .bat, .cmd, .ps1,
.vbs, .js, .scr, .lnk and similar). For those it shows the window with the item selected, and the person
opens it from there. Show in folder is always allowed with a valid token.show, open, reveal, list and cancel-shutdown exist. Anything else, or anything over 512
characters, is ignored and logged.The parser and the token checks are pure Go and fully testable [here], including links made by an attacker.
When “shut down after downloads” fires, the toast says “The PC shuts down in one minute” with a Cancel
shutdown button (pullwell://cancel-shutdown, with a token). The window’s existing cancel button stays.
| Installed (per user, no administrator) | Portable zip | |
|---|---|---|
| Data folder | %LOCALAPPDATA%\Pullwell\data |
data beside the exe |
| Window, tray, single instance | yes | yes |
| Toasts with buttons | yes | no, tray balloons |
pullwell:// registered |
yes | no |
| Start with Windows | per-user Run key | per-user Run key, refused from a copy with a custom data folder |
| Registry use | shortcut, link scheme, Run key, uninstall entry | Run key only, and only if switched on |
The installer and the updater get their own design next. This document only fixes what they must provide (the shortcut with the app id, and the link registration).
| File | Content | Tested |
|---|---|---|
appname.go |
D1 | [here] |
notify_group.go |
grouping and storm control (6.2) | [here] |
applink.go |
pullwell:// parsing, tokens, allowed actions (6.4) |
[here] |
wingeom.go |
checking the saved window position (4.3) | [here] |
win_ui.go |
UI thread, message loop, ui.Post |
compile [here], run [PC] |
win_instance.go |
mutex, hand-over, focus (section 3) | compile [here], run [PC] |
win_tray.go |
tray (section 5) | compile [here], run [PC] |
win_webview.go |
WebView2 lookup and wrapper (4.1, 4.2) | compile [here], run [PC] |
win_toast.go |
toasts (6.3) | compile [here], run [PC] |
win_appmode.go |
Edge/Chrome fallback (4.4) | compile [here], run [PC] |
go.mod (module pullwell, Go 1.24), MIT licence, README, CHANGELOG, VERSION 0.1.0,
CI that runs vet, tests and a Windows build. appname.go with its test. [here]dm/ from NetMerge 3.11.20 (commit 0bfab33), unchanged, and run its full test suite. [here]pullwell:// link, which depend on the installer (its own design). [PC] Stronger model.For each [PC] step I’ll write a short checklist for you or Codex, in the format of the existing test plan, and report each line as PASS, FAIL or BLOCKED with the reason. Nothing will be reported as working until someone has seen it work on Windows.
Nothing to report to NetMerge from this part. Two things I looked at and found safe in NetMerge:
pullwell:// link, which 6.4 handles.noNotify; the other notices ignore it. This looks intended (problems should still be
shown), so it’s a wording issue for Pullwell (D8), not a NetMerge bug.Separately, NetMerge’s desktop shortcut and its scheduled-task adjustment use hidden PowerShell. That’s a NetMerge choice, not a bug in the download code; Pullwell simply won’t copy it.