# ipswap

A tray-resident Windows utility for switching a network adapter between saved
static-IP configurations. Built for field and support work, where a laptop hops
between customer subnets — broadcast control networks, media networks,
management VLANs — many times a day.

Switching a preset is two clicks and no browser. Editing fifty presets happens
in a real UI. Those are different problems, so they use different interfaces.

## How it works

**Fast path (native, no browser).** The tray icon holds a menu of presets
grouped into submenus. Clicking one reads the adapter's live configuration,
shows a Win32 message box with a before/after diff, and on Yes runs the netsh
sequence. The tray tooltip then names the preset that is actually applied.

**Slow path (browser).** "Manage presets…" starts a local HTTP server on a
random loopback port and opens your default browser to it. Full CRUD, adapter
picker, import/export, settings, and switching. The server shuts itself down
five minutes after the browser stops sending heartbeats, and on exit.

Switching works from either side. The tray confirms with a native MessageBox;
the browser shows the identical before/after text in a modal. Both read the
adapter live at prompt time and both go through the same code — see
`internal/switcher`, which exists so that path is written once.

## Launching

Opening ipswap — from the desktop shortcut, the Start menu, or by running the
.exe — opens the editor in your browser. If ipswap is not already running that
also starts the tray; if it is, the running copy opens the browser and the
second process exits. You never get two tray icons.

That is done with a loopback control listener owned by the running instance,
whose port and token live in `%APPDATA%\ipswap\session.json` (mode 600). A
second launch reads that file, calls the listener and exits. On Windows a
session-local named mutex settles who is primary when two launches race.

The start-with-Windows entry passes `--background`, which starts the tray
without opening a browser. Nobody wants a browser tab at login.

## Building

Pure Go, no cgo anywhere, so a Linux or macOS host cross-compiles the Windows
binary directly — no Wine, no mingw, no fyne-cross.

```
make build      # -> bin/ipswap.exe
make check      # tests + vet + typecheck for both targets
make dist       # bin/ipswap.exe plus dist/SHA256SUMS
make installer  # -> Output/ipswap-<version>-setup.exe (needs Inno Setup)
```

`make build` regenerates `cmd/ipswap/resource_windows.syso` first. That object
carries the icon, the version resource and the manifest — the manifest is the
part that matters, because it is what asks for `asInvoker` and per-monitor DPI.

`GOOS=windows go vet ./...` is worth running on its own during development: the
Windows-only files (netsh, user32, the registry) are most of the risk and a
plain Linux build never looks at them. `make vet` does both targets.

`go run ./cmd/devserver` starts the editor alone against a throwaway preset
file, so the web UI can be opened on a non-Windows box. It is a development
aid; the shipped binary is `cmd/ipswap` only.

### Installer

`Inno-compile.iss` builds a **per-user** installer: it installs to
`%APPDATA%\ipswap` with `PrivilegesRequired=lowest`, so it never shows a UAC
prompt. That is deliberate and matches the app — ipswap ships an `asInvoker`
manifest, and an installer demanding elevation would undo the point. It also
means the in-app updater can replace the .exe without a privilege prompt,
which a Program Files install would not allow.

It offers a desktop shortcut and an optional start-with-Windows entry, and it
uses the app's own single-instance mutex as `AppMutex` so setup notices a
running copy — a running .exe on Windows cannot be overwritten.

Uninstalling leaves `presets.json`, `config.json` and the log alone. Inno only
removes what it installed, and preset packs represent real work.

Inno Setup is a Windows tool, so this is the one build step that is not
cross-platform; it runs fine under wine if you would rather not use Windows.
The `.exe` itself still cross-compiles natively, so CI never needs wine.

## Layout

```
cmd/ipswap/          entrypoint, manifest, version resource
cmd/devserver/       runs the editor alone for development
internal/preset/     data model, store, prefix parsing, import/export
internal/netcfg/     adapter reads (Win32) and the netsh command plan
internal/switcher/   the one place a preset is applied; both front ends use it
internal/instance/   single-instance lock and the launch control channel
internal/tray/       tray menu, confirm-then-apply, icon
internal/server/     the local editor server and its embedded web app
internal/updater/    Gitea release check, download, verify, swap
internal/dialog/     Win32 MessageBoxW wrappers
internal/elevate/    token elevation check, relaunch via ShellExecuteW runas
internal/desktop/    open-in-browser, HKCU Run key
internal/config/     paths and settings
internal/applog/     rotating log
```

`internal/server/web/apointless.css` is vendored verbatim from
[bsncubed/css](https://gitea.apointless.space/bsncubed/css) — re-pull it to
update, do not edit it here. `ipswap.css` beside it adds only what the design
system does not ship (page chrome, tables, modals, stat tiles) and is built
strictly on its tokens, so a refreshed apointless.css restyles the app too.

Two rules shape the split. Anything portable lives in portable code and is
tested on any host — most usefully `netcfg.Plan`, which builds the exact netsh
sequence and is covered without a Windows box. Anything Windows-specific has a
`_windows.go` and an `_other.go`, so the whole tree stays buildable and
vettable during development on Linux.

## Elevation

The manifest asks for `asInvoker`, not `requireAdministrator`. On a machine
with UAC relaxed, or when the parent process is already elevated, that means
zero prompts — including at login, if start-with-Windows is on.

Membership of the Administrators group is not the same as holding an elevated
token: with UAC on, a member's process gets a filtered token and `netsh
interface ipv4 set address` fails with "The requested operation requires
elevation." So ipswap checks the token at startup, and if it is not elevated it
adds a "Relaunch as administrator" item to the tray. A failed apply offers the
same thing. Nothing blocks startup either way.

## Data

```
%APPDATA%\ipswap\presets.json    presets
%APPDATA%\ipswap\config.json     settings
%APPDATA%\ipswap\ipswap.log      rotating, 5 × 1 MB
```

`presets.json` is the export format too, so a preset pack is just this file and
stays hand-editable. See `examples/preset-pack.json`.

Masks are stored as an integer prefix. Both `/24` and `255.255.255.0` are
accepted on input, in the editor and in a hand-written file; the display style
is a single global setting.

## Why applies are destructive

After an apply, the adapter has exactly the addresses in the preset and nothing
else.

`netsh interface ipv4 set address … static` replaces the primary address but
leaves previously-added secondary addresses attached. A naive implementation
therefore leaks addresses across switches — after visiting three presets the
adapter is still carrying secondaries from the first two. So every apply
enumerates the live addresses, deletes each one, then sets the primary and adds
the preset's secondaries. `internal/netcfg/plan_test.go` pins that ordering.

Reads use `GetAdaptersAddresses`, not `netsh show config`: netsh's output is
localised and parsing it breaks on a non-English Windows.

## Updates

ipswap checks `https://gitea.apointless.space/bsncubed/ipswap` by default. The
check runs at startup in a goroutine, behind a short timeout, and fails
silently to the log — a laptop on a customer site usually cannot reach the
host, and that is not an error worth showing.

Point it elsewhere, or clear it to switch the check off entirely, in Settings
(`update_repo` in `config.json`). Forks should change it: otherwise they will
offer their users an upstream binary.

A newer tag adds "Update available — vX.Y.Z" to the top of the tray menu.
Clicking it downloads the `.exe`, verifies its SHA256 against the release, and
hands off to a small batch helper that waits for ipswap to exit, swaps the
binary and relaunches. **A release that publishes no checksum is refused** — an
unverified binary that is about to be run is not worth the convenience. It
never installs on its own.

## Not in v1

Revert / restore-previous / timed auto-revert; post-apply connectivity checks
(the confirmation diff is the check); global hotkeys; IPv6; adapter matching by
MAC address; per-preset scripts.