From 70faf9685f652e3f74c98d6daf90f24d5293913d Mon Sep 17 00:00:00 2001 From: Lana Begunova <70295997+lana-20@users.noreply.github.com> Date: Mon, 28 Sep 2026 03:20:52 -0700 Subject: [PATCH 1/4] Prebuilt binaries: make dist, and a release workflow for v* tags make dist builds every CROSS target static (CGO off) and without build paths (-trimpath), as mobium___.tar.gz (.zip for Windows) holding the binary, LICENSE, THIRD_PARTY_NOTICES.md and the README, with SHA256SUMS. Built here: six archives of about 4MB, every checksum OK, the darwin/arm64 binary reporting its version and holding no path from this machine. The release workflow runs make test and make dist on a v* tag, checks every archive against SHA256SUMS and the Linux binary's --version, and attaches them to a GitHub Release; on a pull request touching it or the Makefile it does all of that but the release. SETUP.md says how to install one, and that on macOS a download goes by curl, the binaries not being notarized. --- .github/workflows/release.yml | 91 +++++++++++++++++++++++++++++++++++ .gitignore | 1 + Makefile | 24 ++++++++- README.md | 3 +- docs/ROADMAP.md | 14 ++++-- docs/SETUP.md | 27 +++++++++++ 6 files changed, 153 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..da3015fe --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,91 @@ +# Prebuilt binaries, so installing mobium does not need Go. +# +# A tag `v` builds every platform with `make dist`, checks the +# archives against SHA256SUMS and runs the Linux binary to see it reports +# the tag's version, then attaches them to a GitHub Release of that tag. +# A pull request that touches this file or the Makefile does everything but +# the release, so the build is proven before a tag ever needs it. +# +# Nothing here signs or notarizes the macOS binaries: that needs an Apple +# Developer Program membership. docs/SETUP.md says what that means for +# someone who downloads one. + +name: Release + +on: + push: + tags: ['v*'] + pull_request: + paths: + - Makefile + - .github/workflows/release.yml + +permissions: + contents: read + +jobs: + build: + name: Build and verify the release archives + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-go@v7 + with: + go-version-file: go.mod + cache-dependency-path: | + go.sum + clients/go/go.sum + + # The tag names the version, without its leading v; a pull request + # gets one that cannot be mistaken for a release. + - name: Version + run: | + if [ "${GITHUB_REF_TYPE}" = tag ]; then v="${GITHUB_REF_NAME#v}"; else v="0.0.0-pr${{ github.event.number }}"; fi + echo "VERSION=$v" >> "$GITHUB_ENV" + + - name: Test what is being released + run: make test + + - name: make dist + run: make dist VERSION="$VERSION" + + # Read back, not assumed: every archive against its checksum, and the + # binary asked what version it is. + - name: Verify + run: | + cd dist + shasum -a 256 -c SHA256SUMS + tar -xzf "mobium_${VERSION}_linux_amd64.tar.gz" + got=$("./mobium_${VERSION}_linux_amd64/mobium" --version) + echo "$got" + [ "$got" = "mobium version $VERSION" ] || { echo "the binary says '$got', not $VERSION"; exit 1; } + rm -rf "mobium_${VERSION}_linux_amd64" + ls -l + + - uses: actions/upload-artifact@v4 + with: + name: dist + path: dist/ + if-no-files-found: error + + publish: + name: Publish the release + needs: build + if: github.ref_type == 'tag' + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist + + - name: Create the release + env: + GH_TOKEN: ${{ github.token }} + run: | + gh release create "$GITHUB_REF_NAME" dist/* \ + --repo "$GITHUB_REPOSITORY" --verify-tag --title "mobium ${GITHUB_REF_NAME}" \ + --notes "Prebuilt mobium for macOS, Linux and Windows, amd64 and arm64. Check a download against SHA256SUMS. The macOS binaries are not notarized; see docs/SETUP.md." diff --git a/.gitignore b/.gitignore index 52008639..a107b0c8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ bin/ +dist/ # Screenshots land here constantly during device work, so PNGs are ignored by # default and the branding is excepted rather than the rule loosened. *.png diff --git a/Makefile b/Makefile index a7d79ca1..e1798cbc 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ BIN := bin/mobium VERSION := $(shell cat VERSION 2>/dev/null || echo dev) -.PHONY: all build test fmt fmt-check vet lint clients java crosscompile api api-check flags flags-check quickstart license-check docs-check ci clean +.PHONY: all build dist test fmt fmt-check vet lint clients java crosscompile api api-check flags flags-check quickstart license-check docs-check ci clean all: build test @@ -74,6 +74,28 @@ clients: # it, and that has broken before without anyone on a Mac noticing. CROSS := windows/amd64 windows/arm64 linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 +# dist builds the release archives: every CROSS target, static and with no +# build paths in it, as mobium___ — a .tar.gz, or a .zip +# for Windows — holding the binary, the license and its notices, and the +# README, with SHA256SUMS over them all. `make dist VERSION=0.1.0` for a +# release; the release workflow runs it on a tag. +DIST := dist + +dist: + @rm -rf $(DIST) && mkdir -p $(DIST) + @for t in $(CROSS); do \ + os=$${t%/*}; arch=$${t#*/}; ext=""; [ $$os = windows ] && ext=.exe; \ + name=mobium_$(VERSION)_$${os}_$${arch}; dir=$(DIST)/$$name; mkdir -p $$dir; \ + CGO_ENABLED=0 GOOS=$$os GOARCH=$$arch go build -trimpath \ + -ldflags "-s -w -X main.version=$(VERSION)" -o $$dir/mobium$$ext ./cmd/mobium || exit 1; \ + cp LICENSE THIRD_PARTY_NOTICES.md README.md $$dir/; \ + if [ $$os = windows ]; then (cd $(DIST) && zip -qr $$name.zip $$name) || exit 1; \ + else tar -C $(DIST) -czf $(DIST)/$$name.tar.gz $$name || exit 1; fi; \ + rm -rf $$dir; echo " $$name"; \ + done + @cd $(DIST) && shasum -a 256 mobium_* > SHA256SUMS + @echo "wrote $(DIST)/SHA256SUMS" + crosscompile: @for t in $(CROSS); do \ os=$${t%/*}; arch=$${t#*/}; \ diff --git a/README.md b/README.md index f2415e6e..426995e3 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,8 @@ person driving an emulator for it. People get the same commands. Requirements: -- **Go 1.24+**, to install it — there are no prebuilt binaries yet +- **Go 1.24+**, to install it — prebuilt binaries arrive with the first + release ([SETUP.md](docs/SETUP.md#installing-a-release)) - **Android:** platform-tools on `PATH` (or `ANDROID_HOME`, or `MOBIUM_ADB_PATH`), and an emulator or a phone with USB debugging on - **iOS:** full Xcode and a booted simulator — or an iPhone on a cable, with diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d2286723..c9956012 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -22,11 +22,15 @@ this is what is not. verified by a TXT record on `mobium.dev`), a GPG key for Maven Central, and a tag — `v0.1.0`, and `clients/go/v0.1.0` for the Go module. All four names were unclaimed on 2026-09-27. -- **Prebuilt `mobium` binaries.** `go install - github.com/mobiumdev/mobium/cmd/mobium@latest` works, but needs Go; someone - installing a client from PyPI or npm should not have to have it. Releases - with checksummed binaries for macOS and Linux, and possibly a Homebrew tap, - are the missing piece — and the prerequisite for publishing the clients. +- **Prebuilt `mobium` binaries — built, waiting on the first tag.** + `make dist` builds all six platforms, static and without build paths, into + archives with the license, notices and README and a `SHA256SUMS`; the + release workflow runs it on a `v*` tag, checks every archive and the Linux + binary's `--version`, and attaches them to the release, and on a pull + request does all of that but the release. What is left: the tag, which is + a decision, not a step; a Homebrew tap; and notarizing the macOS binaries, + which needs an Apple Developer Program membership — until then + [SETUP.md](SETUP.md#installing-a-release) says to download with `curl`. - **The quick start on Linux, against a device.** Mobium builds and passes its tests on Linux in CI; no emulator has been driven from Linux yet, so the quick start calls Linux expected rather than verified. diff --git a/docs/SETUP.md b/docs/SETUP.md index 165d6ab3..7faf7e6e 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -23,15 +23,42 @@ no Xcode on a machine doing Android work is normal, not a problem. ## Contents +- [Installing a release](#installing-a-release) — no Go needed, from the first release - [Android emulator](#android-emulator) - [Android real device](#android-real-device) - [iOS simulator](#ios-simulator) - [iOS real device](#ios-real-device) — native screens, WebViews and Safari - [Parallel runs](#parallel-runs) — one daemon for each +- [Driving another machine's devices](#driving-another-machines-devices) — `--remote`, and a grid - [What Mobium installs, and removing it](#what-mobium-installs-and-removing-it) --- +## Installing a release + +From the first tagged release on, each one carries mobium prebuilt for +macOS, Linux and Windows, on amd64 and arm64, so installing it needs no Go: +`mobium___.tar.gz` (`.zip` for Windows), each holding the +binary, the license and its notices, and the README, and `SHA256SUMS` over +all of them. The binary is static — nothing else to install with it. + +```sh +v=0.1.0; os=darwin; arch=arm64 # or linux / windows, amd64 +base=https://github.com/mobiumdev/mobium/releases/download/v$v +curl -LO "$base/mobium_${v}_${os}_${arch}.tar.gz" -LO "$base/SHA256SUMS" +shasum -a 256 -c --ignore-missing SHA256SUMS # must say OK +tar -xzf "mobium_${v}_${os}_${arch}.tar.gz" +mv "mobium_${v}_${os}_${arch}/mobium" /usr/local/bin/ # or anywhere on PATH +mobium --version +``` + +**On macOS, download with `curl`, not a browser.** The binaries are not +notarized — that needs an Apple Developer Program membership — and macOS +blocks a quarantined, un-notarized download from a browser at first launch. +`curl` does not quarantine what it saves. For a copy that came through a +browser, `xattr -d com.apple.quarantine mobium` lifts it, after checking its +checksum. + ## Android emulator ```sh From 114ea2aefeaba12bddf13350d97980b75ea86bbf Mon Sep 17 00:00:00 2001 From: Lana Begunova <70295997+lana-20@users.noreply.github.com> Date: Mon, 28 Sep 2026 03:33:24 -0700 Subject: [PATCH 2/4] Grid: route by model and OS, and have the node enforce leases MOBIUM_GRID_MODEL and MOBIUM_GRID_OS narrow routing; the node now reports each device's OS (Android's release, iOS's runtime), and OS matches at the start of a word, so 17 is Android 17 and not 15. Leases move to internal/grid, and every daemon on a node now refuses a device leased to a holder other than its own session. Each grid run gets a daemon of its own on its node, named by its lease, stopped when the run ends. Live: a run holding the Android 17 emulator kept it while a mobium --device run on the node that bypassed the grid was refused, naming the holder, and the free emulator stayed usable. A run that got no device left a daemon of its own on the node: the grid's queries ran in the run's session and started one to list devices. Queries and leases now use the node's default daemon, and only the run's connection has a session of its own. --- cmd/mobium/grid.go | 205 +++++++++++++++-------------------- cmd/mobium/grid_test.go | 60 +++++++--- cmd/mobium/remote.go | 11 +- docs/ROADMAP.md | 10 +- docs/SETUP.md | 10 ++ internal/agent/backend.go | 22 ++++ internal/agent/lease_test.go | 49 +++++++++ internal/grid/lease.go | 130 ++++++++++++++++++++++ 8 files changed, 359 insertions(+), 138 deletions(-) create mode 100644 internal/agent/lease_test.go create mode 100644 internal/grid/lease.go diff --git a/cmd/mobium/grid.go b/cmd/mobium/grid.go index 9cce7317..3f8f9b07 100644 --- a/cmd/mobium/grid.go +++ b/cmd/mobium/grid.go @@ -2,21 +2,21 @@ package main import ( "bytes" + "context" "crypto/rand" "encoding/hex" "encoding/json" "fmt" "os" - "path/filepath" - "regexp" "sort" "strings" "sync" "time" "github.com/mobiumdev/mobium/internal/agent" + "github.com/mobiumdev/mobium/internal/device" + "github.com/mobiumdev/mobium/internal/grid" "github.com/mobiumdev/mobium/internal/mobiumerr" - "github.com/mobiumdev/mobium/internal/paths" "github.com/spf13/cobra" ) @@ -26,10 +26,8 @@ import ( // callers on different machines cannot take the same one. Nothing new listens // anywhere — every step is SSH, and the connection is --remote's (Stage 2). -const ( - leaseTTL = 60 * time.Second // a lease no heartbeat has renewed for this long is free - leaseEvery = 20 * time.Second // how often a holder renews -) +// leaseEvery is how often a holder renews, well inside grid.TTL. +const leaseEvery = 20 * time.Second var ( gridActive bool // this process routes through MOBIUM_GRID @@ -52,14 +50,15 @@ func gridNodes() []string { // nodeStatus is what `mobium grid node --json` prints: the devices here, and // which of them a run holds. type nodeStatus struct { - Devices []agent.DeviceView `json:"devices"` - Leases map[string]string `json:"leases"` // serial -> holder, live leases only + Devices []gridDevice `json:"devices"` + Leases map[string]string `json:"leases"` // serial -> holder, live leases only } -// leaseAnswer is what `mobium grid lease` prints. -type leaseAnswer struct { - OK bool `json:"ok"` - Holder string `json:"holder"` +// gridDevice is a device as a grid routes it: what `devices` reports, and +// the OS it runs, for MOBIUM_GRID_OS. +type gridDevice struct { + agent.DeviceView + OS string `json:"os,omitempty"` } func newGridCmd() *cobra.Command { @@ -77,11 +76,15 @@ func newGridCmd() *cobra.Command { if err != nil { return err } - var st nodeStatus - if err := remarshal(res.StructuredContent, &st); err != nil { + var dv agent.DevicesView + if err := remarshal(res.StructuredContent, &dv); err != nil { return err } - if st.Leases, err = liveLeases(); err != nil { + var st nodeStatus + for _, d := range dv.Devices { + st.Devices = append(st.Devices, gridDevice{DeviceView: d, OS: deviceOS(d)}) + } + if st.Leases, err = grid.Live(); err != nil { return err } return printJSON(st) @@ -91,7 +94,7 @@ func newGridCmd() *cobra.Command { Use: "lease ", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { - got, err := takeLease(args[0], holder) + got, err := grid.Take(args[0], holder) if err != nil { return err } @@ -102,7 +105,7 @@ func newGridCmd() *cobra.Command { Use: "release ", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { - return dropLease(args[0], holder) + return grid.Drop(args[0], holder) }, } for _, c := range []*cobra.Command{lease, release} { @@ -113,92 +116,6 @@ func newGridCmd() *cobra.Command { return cmd } -var unsafeSerial = regexp.MustCompile(`[^A-Za-z0-9._-]`) - -func leaseDir() (string, error) { - dir := filepath.Join(paths.Root(), "leases") - return dir, os.MkdirAll(dir, 0o700) -} - -func leaseFile(serial string) (string, error) { - dir, err := leaseDir() - if err != nil { - return "", err - } - return filepath.Join(dir, unsafeSerial.ReplaceAllString(serial, "_")), nil -} - -// takeLease gives a device to a holder: a new lease if there is none or the -// last one lapsed, a renewal if the holder already has it, and a refusal -// naming the holder otherwise. The file is created exclusively, so two -// callers asking at once cannot both be told yes. -func takeLease(serial, holder string) (leaseAnswer, error) { - f, err := leaseFile(serial) - if err != nil { - return leaseAnswer{}, err - } - for attempt := 0; attempt < 2; attempt++ { - if w, err := os.OpenFile(f, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600); err == nil { - _, err = w.WriteString(holder) - w.Close() - return leaseAnswer{OK: err == nil, Holder: holder}, err - } - held, info, err := readLease(f) - if err != nil { - continue // released between the two looks; try again - } - if held == holder { - now := time.Now() - return leaseAnswer{OK: true, Holder: holder}, os.Chtimes(f, now, now) - } - if time.Since(info.ModTime()) < leaseTTL { - return leaseAnswer{OK: false, Holder: held}, nil - } - // Lapsed: its holder stopped renewing, most likely because it died. - _ = os.Remove(f) - } - return leaseAnswer{}, mobiumerr.New(mobiumerr.DeviceServer, "could not take the lease on %s", serial) -} - -func dropLease(serial, holder string) error { - f, err := leaseFile(serial) - if err != nil { - return err - } - if held, _, err := readLease(f); err == nil && held == holder { - return os.Remove(f) - } - return nil -} - -func readLease(f string) (string, os.FileInfo, error) { - info, err := os.Stat(f) - if err != nil { - return "", nil, err - } - b, err := os.ReadFile(f) - return strings.TrimSpace(string(b)), info, err -} - -func liveLeases() (map[string]string, error) { - dir, err := leaseDir() - if err != nil { - return nil, err - } - entries, err := os.ReadDir(dir) - if err != nil { - return nil, err - } - out := map[string]string{} - for _, e := range entries { - held, info, err := readLease(filepath.Join(dir, e.Name())) - if err == nil && time.Since(info.ModTime()) < leaseTTL { - out[e.Name()] = held - } - } - return out, nil -} - // ---- the caller's side ----------------------------------------------------- // routeGrid chooses the node and device for this run, from what its first @@ -229,6 +146,11 @@ func routeGrid(args map[string]interface{}) error { wait = d } gridHolder = newHolder() + // The run's daemon on the node is named by its lease, so it alone may + // use the device; this process's own socket is named the same. + if err := os.Setenv("MOBIUM_SESSION", gridHolder); err != nil { + return err + } nodes := gridNodes() deadline := time.Now().Add(wait) @@ -241,10 +163,10 @@ func routeGrid(args map[string]interface{}) error { continue } for _, d := range st.Devices { - if !deviceReady(d) || (serial != "" && d.ID != serial) || (platform != "" && d.Platform != platform) { + if !deviceReady(d.DeviceView) || (serial != "" && d.ID != serial) || (platform != "" && d.Platform != platform) || !matches(d) { continue } - if h, held := st.Leases[unsafeSerial.ReplaceAllString(d.ID, "_")]; held { + if h, held := st.Leases[grid.Key(d.ID)]; held { busy = append(busy, fmt.Sprintf("%s on %s (held by %s)", d.ID, node, h)) continue } @@ -271,6 +193,8 @@ func useLease(node, serial string) error { cleanups = append(cleanups, func() { once.Do(func() { close(stop) }) _, _ = askLease(node, "release", serial) + // The run's own daemon on the node goes with it. + _ = sshCommand(node, "daemon stop").Run() }) if err := openRemote(node); err != nil { return err @@ -294,6 +218,49 @@ func useLease(node, serial string) error { return nil } +// deviceOS names the OS a device runs: Android's release, read from the +// device, and iOS's runtime, which the listing already carries. +func deviceOS(d agent.DeviceView) string { + if d.Platform == "ios" { + return d.Runtime + } + if d.Platform != "android" || !deviceReady(d) { + return "" + } + adb, err := device.New(d.ID) + if err != nil { + return "" + } + out, err := adb.Shell(context.Background(), "getprop", "ro.build.version.release") + if err != nil { + return "" + } + return "Android " + strings.TrimSpace(string(out)) +} + +// matches applies MOBIUM_GRID_MODEL — part of the model's name, in any case +// — and MOBIUM_GRID_OS — the start of a word of the OS, so "17" matches +// "Android 17" and "Android 17.1" and not "Android 15". +func matches(d gridDevice) bool { + if m := strings.ToLower(os.Getenv("MOBIUM_GRID_MODEL")); m != "" && !strings.Contains(strings.ToLower(d.Model), m) { + return false + } + want := strings.ToLower(strings.TrimSpace(os.Getenv("MOBIUM_GRID_OS"))) + if want == "" { + return true + } + have := strings.ToLower(d.OS) + if strings.HasPrefix(have, want) { + return true + } + for _, w := range strings.Fields(have) { + if strings.HasPrefix(w, want) { + return true + } + } + return false +} + func deviceReady(d agent.DeviceView) bool { switch strings.ToLower(d.State) { case "device", "booted", "connected": @@ -314,7 +281,7 @@ func askNodes(nodes []string) (map[string]nodeStatus, []string) { go func(n string) { defer wg.Done() var st nodeStatus - err := runJSON(sshCommand(n, "grid node --json"), &st) + err := runJSON(sshSession(n, "", "grid node --json"), &st) mu.Lock() defer mu.Unlock() if err != nil { @@ -329,9 +296,9 @@ func askNodes(nodes []string) (map[string]nodeStatus, []string) { return out, down } -func askLease(node, verb, serial string) (leaseAnswer, error) { - var got leaseAnswer - cmd := sshCommand(node, fmt.Sprintf("grid %s %s --holder %s", verb, shellWord(serial), gridHolder)) +func askLease(node, verb, serial string) (grid.Answer, error) { + var got grid.Answer + cmd := sshSession(node, "", fmt.Sprintf("grid %s %s --holder %s", verb, shellWord(serial), gridHolder)) if verb == "release" { return got, cmd.Run() } @@ -352,16 +319,14 @@ func runJSON(cmd interface { // keeps one that is not from becoming a command. func shellWord(s string) string { return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'" } -// newHolder names this run in a lease: the machine, the process, and a -// random part, since two runs on one machine are two holders. +// newHolder names this run in a lease, and is also the session name of the +// daemon the run gets on its node: every daemon there refuses a device leased +// to a holder other than its own session. Random, since two runs on one +// machine are two holders, and short, since it is part of a socket's path. func newHolder() string { - host, _ := os.Hostname() - if host == "" { - host = "caller" - } b := make([]byte, 4) _, _ = rand.Read(b) - return fmt.Sprintf("%s-%d-%s", unsafeSerial.ReplaceAllString(host, "_"), os.Getpid(), hex.EncodeToString(b)) + return "g" + hex.EncodeToString(b) } func noDevice(serial, platform string, wait time.Duration, busy, down []string) error { @@ -372,6 +337,12 @@ func noDevice(serial, platform string, wait time.Duration, busy, down []string) case platform != "": want = "an " + platform + " device" } + if m := os.Getenv("MOBIUM_GRID_MODEL"); m != "" { + want += ", model " + m + } + if o := os.Getenv("MOBIUM_GRID_OS"); o != "" { + want += ", OS " + o + } msg := fmt.Sprintf("no node in MOBIUM_GRID had %s free within %s", want, wait) if len(busy) > 0 { msg += "; busy: " + strings.Join(busy, ", ") diff --git a/cmd/mobium/grid_test.go b/cmd/mobium/grid_test.go index df2ec877..4c5ce821 100644 --- a/cmd/mobium/grid_test.go +++ b/cmd/mobium/grid_test.go @@ -2,8 +2,12 @@ package main import ( "os" + "path/filepath" + "strings" "testing" "time" + + "github.com/mobiumdev/mobium/internal/grid" ) // A device belongs to one run at a time, and the lease on the node is what @@ -12,44 +16,70 @@ import ( func TestLeases(t *testing.T) { t.Setenv("MOBIUM_HOME", t.TempDir()) - if got, err := takeLease("emulator-5554", "a"); err != nil || !got.OK { + if got, err := grid.Take("emulator-5554", "a"); err != nil || !got.OK { t.Fatalf("a free device was not leased: %+v, %v", got, err) } - if got, _ := takeLease("emulator-5554", "b"); got.OK || got.Holder != "a" { + if got, _ := grid.Take("emulator-5554", "b"); got.OK || got.Holder != "a" { t.Errorf("a second holder was given a leased device: %+v", got) } - if got, _ := takeLease("emulator-5554", "a"); !got.OK { + if got, _ := grid.Take("emulator-5554", "a"); !got.OK { t.Error("the holder could not renew its own lease") } - if live, _ := liveLeases(); live["emulator-5554"] != "a" { + if live, _ := grid.Live(); live["emulator-5554"] != "a" { t.Errorf("live leases %v", live) } // Lapsed: nobody renewed it for longer than the TTL. - f, _ := leaseFile("emulator-5554") - old := time.Now().Add(-2 * leaseTTL) + f := filepath.Join(os.Getenv("MOBIUM_HOME"), "leases", grid.Key("emulator-5554")) + old := time.Now().Add(-2 * grid.TTL) os.Chtimes(f, old, old) - if live, _ := liveLeases(); len(live) != 0 { + if live, _ := grid.Live(); len(live) != 0 { t.Errorf("a lapsed lease is still live: %v", live) } - if got, _ := takeLease("emulator-5554", "b"); !got.OK || got.Holder != "b" { + if got, _ := grid.Take("emulator-5554", "b"); !got.OK || got.Holder != "b" { t.Errorf("a lapsed lease was not taken over: %+v", got) } // Only its holder releases it. - dropLease("emulator-5554", "a") - if live, _ := liveLeases(); live["emulator-5554"] != "b" { + grid.Drop("emulator-5554", "a") + if live, _ := grid.Live(); live["emulator-5554"] != "b" { t.Error("someone else's release freed the device") } - dropLease("emulator-5554", "b") - if live, _ := liveLeases(); len(live) != 0 { + grid.Drop("emulator-5554", "b") + if live, _ := grid.Live(); len(live) != 0 { t.Errorf("the holder's release left %v", live) } // A serial never reaches the filesystem as a path. - if f, _ := leaseFile("../../etc/x"); f == "" || !startsWith(f, os.Getenv("MOBIUM_HOME")) { - t.Errorf("a hostile serial became %q", f) + if k := grid.Key("../../etc/x"); strings.ContainsAny(k, "/\\") { + t.Errorf("a hostile serial became %q", k) } } -func startsWith(s, prefix string) bool { return len(s) >= len(prefix) && s[:len(prefix)] == prefix } +// MOBIUM_GRID_OS matches the start of a word, so a version asks for that +// version and its point releases, not every OS containing its digits. +func TestGridMatchesOSAndModel(t *testing.T) { + d := func(model, os string) gridDevice { + g := gridDevice{OS: os} + g.Model = model + return g + } + for _, c := range []struct { + model, os, wantModel, wantOS string + match bool + }{ + {"sdk_gphone64_arm64", "Android 17", "", "17", true}, + {"sdk_gphone64_arm64", "Android 17.1", "", "17", true}, + {"sdk_gphone64_arm64", "Android 15", "", "17", false}, + {"sdk_gphone64_arm64", "Android 15", "", "android", true}, + {"iPhone 17 Pro", "iOS 26.5", "", "iOS 26", true}, + {"iPhone 17 Pro", "iOS 26.5", "pixel", "", false}, + {"Pixel 8 Pro", "Android 17", "PIXEL", "17", true}, + } { + t.Setenv("MOBIUM_GRID_MODEL", c.wantModel) + t.Setenv("MOBIUM_GRID_OS", c.wantOS) + if got := matches(d(c.model, c.os)); got != c.match { + t.Errorf("model %q os %q against model=%q os=%q: %v, want %v", c.model, c.os, c.wantModel, c.wantOS, got, c.match) + } + } +} diff --git a/cmd/mobium/remote.go b/cmd/mobium/remote.go index 0ce9ee8f..0e145ee6 100644 --- a/cmd/mobium/remote.go +++ b/cmd/mobium/remote.go @@ -166,9 +166,16 @@ func sshExec(args ...string) *exec.Cmd { // sshCommand runs `mobium ` on a node, in the session this process // uses, as MOBIUM_REMOTE_BIN says the node's shell runs mobium. func sshCommand(node, sub string) *exec.Cmd { + return sshSession(node, paths.SessionName(), sub) +} + +// sshSession is sshCommand in a named session on the node: "" is the node's +// default daemon, which a grid's queries and leases use, so asking which +// devices are free never starts a daemon of a run's own. +func sshSession(node, session, sub string) *exec.Cmd { remote := remoteBin() + " " + sub - if s := paths.SessionName(); s != "" { - remote = "MOBIUM_SESSION=" + s + " " + remote + if session != "" { + remote = "MOBIUM_SESSION=" + session + " " + remote } return sshExec("-T", node, remote) } diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index c9956012..97c46e0d 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -132,10 +132,12 @@ this is what is not. device up to `MOBIUM_GRID_WAIT`; a node that does not answer is left out. A `kill -9` left an SSH forward running for good until the forward read a pipe its parent holds ([SETUP.md](SETUP.md#a-grid)). - 4. **Still to do.** Routing by model and OS version, not only platform and - serial. Leases are honored by mobium, not enforced by the node's - daemon, so a run that ignores the grid can still take a leased device. - And one device per run holds on a node's daemon as anywhere — nothing + 4. **Model, OS and enforcement — done, 2026-09-28.** `MOBIUM_GRID_MODEL` + and `MOBIUM_GRID_OS` route by model and OS version, the node reporting + each device's. Each run gets a daemon of its own on its node, named by + its lease, and every daemon there refuses a device leased to another — + a run on the node that bypassed the grid was refused, naming the + holder. Still to do: one device per run holds as anywhere, and nothing yet shares one session between two runs. 5. **A grid UI** (written down 2026-09-28): a page showing each node, its devices, who holds each lease and for how long, and what is queued — diff --git a/docs/SETUP.md b/docs/SETUP.md index 7faf7e6e..cd039f1e 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -586,6 +586,16 @@ that matches, a run waits, asking again every two seconds, up to nodes did not answer. A node that does not answer within five seconds is left out, and routing goes on without it. +`MOBIUM_GRID_MODEL` narrows it to a model — part of its name, in any case — +and `MOBIUM_GRID_OS` to an OS version, matched at the start of a word, so +`17` means Android 17 and its point releases and `iOS 26` an iOS 26 runtime. + +**The node enforces a lease; mobium does not merely respect it.** Each run +gets a daemon of its own on its node, named by its lease, and every daemon +on the node refuses a device leased to another: a `mobium --device` run on +the node that goes around the grid is told the device belongs to a grid run +until that run ends. The run's daemon stops with it. + A lease is renewed every 20 seconds while its run lives, released when it ends, and free again 60 seconds after a run that died without releasing it. A run killed outright takes its SSH forward with it, and the next run clears diff --git a/internal/agent/backend.go b/internal/agent/backend.go index 43d49ac4..3232d125 100644 --- a/internal/agent/backend.go +++ b/internal/agent/backend.go @@ -3,7 +3,9 @@ package agent import ( "context" "fmt" + "github.com/mobiumdev/mobium/internal/grid" "github.com/mobiumdev/mobium/internal/mobiumerr" + "github.com/mobiumdev/mobium/internal/paths" "strings" "time" @@ -204,6 +206,26 @@ func (s *session) healthy(ctx context.Context) bool { // sessionFor returns the cached session for a device, creating it if needed. func (h *Handlers) sessionFor(ctx context.Context, args map[string]interface{}) (*session, error) { + s, err := h.resolveSession(ctx, args) + if err != nil || s == nil || s.dev == nil { + return s, err + } + // A device a grid has leased to one run is refused to every other, on + // every call: each grid run has a daemon of its own on the node, named + // by its lease, and any other daemon here — a run that bypassed the + // grid included — would otherwise take the device from under it. + if holder, leased := grid.Holder(s.dev.Serial); leased && holder != paths.SessionName() { + return nil, mobiumerr.New(mobiumerr.DeviceNotReady, "%s is leased to a grid run (%s) and belongs to it until "+ + "that run ends", s.dev.Serial, holder). + WithRemedy("wait for the run to finish, or reach a free device through MOBIUM_GRID"). + WithDetail("holder", holder) + } + return s, nil +} + +// resolveSession finds or opens the session a call is for, before any lease +// is consulted. +func (h *Handlers) resolveSession(ctx context.Context, args map[string]interface{}) (*session, error) { serial := stringArg(args, "device") if serial == "" { serial = h.defaultDevice diff --git a/internal/agent/lease_test.go b/internal/agent/lease_test.go new file mode 100644 index 00000000..76496d4f --- /dev/null +++ b/internal/agent/lease_test.go @@ -0,0 +1,49 @@ +package agent + +import ( + "context" + "os" + "testing" + + "github.com/mobiumdev/mobium/internal/grid" + "github.com/mobiumdev/mobium/internal/mobiumerr" +) + +// A device a grid leased to one run is refused to every other daemon on the +// node — the one a run that bypassed the grid would use included — and +// allowed to the run's own, whose session name is the lease's holder. +func TestALeasedDeviceBelongsToItsRun(t *testing.T) { + home, err := os.MkdirTemp("/tmp", "mbl-") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { os.RemoveAll(home) }) + t.Setenv("MOBIUM_HOME", home) + t.Setenv("MOBIUM_SESSION", "") + + h, _, _ := withFake(t, screen(t, "OK")) + ctx := context.Background() + args := map[string]interface{}{"device": "fake"} + + if _, err := h.sessionFor(ctx, args); err != nil { + t.Fatalf("an unleased device was refused: %v", err) + } + if got, _ := grid.Take("fake", "g1234abcd"); !got.OK { + t.Fatal("could not lease the device") + } + _, err = h.sessionFor(ctx, args) + if mobiumerr.CodeOf(err) != mobiumerr.DeviceNotReady { + t.Fatalf("another daemon reached a leased device: %v", err) + } + + t.Setenv("MOBIUM_SESSION", "g1234abcd") + if _, err := h.sessionFor(ctx, args); err != nil { + t.Errorf("the run holding the lease was refused its own device: %v", err) + } + + t.Setenv("MOBIUM_SESSION", "") + grid.Drop("fake", "g1234abcd") + if _, err := h.sessionFor(ctx, args); err != nil { + t.Errorf("a released device is still refused: %v", err) + } +} diff --git a/internal/grid/lease.go b/internal/grid/lease.go new file mode 100644 index 00000000..dd3e566a --- /dev/null +++ b/internal/grid/lease.go @@ -0,0 +1,130 @@ +// Package grid holds a mobium grid's leases: the record, on a node, of which +// run a device belongs to. The caller's mobium takes and renews them over +// SSH, and every daemon on the node reads them, so a device leased to one run +// is refused to every other — a run started through the grid, or not. +package grid + +import ( + "os" + "path/filepath" + "regexp" + "strings" + "time" + + "github.com/mobiumdev/mobium/internal/mobiumerr" + "github.com/mobiumdev/mobium/internal/paths" +) + +// TTL is how long a lease lasts unrenewed; a holder renews well inside it, +// so a lease past it belongs to a run that stopped, most likely by dying. +const TTL = 60 * time.Second + +// Answer is what taking a lease says: whether it was given, and to whom. +type Answer struct { + OK bool `json:"ok"` + Holder string `json:"holder"` +} + +var unsafe = regexp.MustCompile(`[^A-Za-z0-9._-]`) + +// Key is a serial as a lease file names it: nothing in it reaches the +// filesystem as a path. +func Key(serial string) string { return unsafe.ReplaceAllString(serial, "_") } + +func dir() (string, error) { + d := filepath.Join(paths.Root(), "leases") + return d, os.MkdirAll(d, 0o700) +} + +func file(serial string) (string, error) { + d, err := dir() + if err != nil { + return "", err + } + return filepath.Join(d, Key(serial)), nil +} + +// Take gives a device to a holder: a new lease if there is none or the last +// one lapsed, a renewal if the holder already has it, and a refusal naming +// the holder otherwise. The file is created exclusively, so two callers +// asking at once cannot both be told yes. +func Take(serial, holder string) (Answer, error) { + f, err := file(serial) + if err != nil { + return Answer{}, err + } + for attempt := 0; attempt < 2; attempt++ { + if w, err := os.OpenFile(f, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600); err == nil { + _, err = w.WriteString(holder) + w.Close() + return Answer{OK: err == nil, Holder: holder}, err + } + held, info, err := read(f) + if err != nil { + continue // released between the two looks; try again + } + if held == holder { + now := time.Now() + return Answer{OK: true, Holder: holder}, os.Chtimes(f, now, now) + } + if time.Since(info.ModTime()) < TTL { + return Answer{OK: false, Holder: held}, nil + } + _ = os.Remove(f) // lapsed + } + return Answer{}, mobiumerr.New(mobiumerr.DeviceServer, "could not take the lease on %s", serial) +} + +// Drop releases a device, if the holder is the one that has it. +func Drop(serial, holder string) error { + f, err := file(serial) + if err != nil { + return err + } + if held, _, err := read(f); err == nil && held == holder { + return os.Remove(f) + } + return nil +} + +// Holder names the run a device is leased to, if a live lease says so. +func Holder(serial string) (string, bool) { + f, err := file(serial) + if err != nil { + return "", false + } + held, info, err := read(f) + if err != nil || time.Since(info.ModTime()) >= TTL { + return "", false + } + return held, true +} + +// Live maps each leased device's key to its holder, live leases only. +func Live() (map[string]string, error) { + d, err := dir() + if err != nil { + return nil, err + } + entries, err := os.ReadDir(d) + if err != nil { + return nil, err + } + out := map[string]string{} + for _, e := range entries { + held, info, err := read(filepath.Join(d, e.Name())) + if err == nil && time.Since(info.ModTime()) < TTL { + out[e.Name()] = held + } + } + return out, nil +} + +func read(f string) (string, os.FileInfo, error) { + info, err := os.Stat(f) + if err != nil { + return "", nil, err + } + b, err := os.ReadFile(f) + return strings.TrimSpace(string(b)), info, err +} From 5a1d7017efc11558a80d3f57e2cd5e0d431cec9e Mon Sep 17 00:00:00 2001 From: Lana Begunova <70295997+lana-20@users.noreply.github.com> Date: Mon, 28 Sep 2026 03:50:06 -0700 Subject: [PATCH 3/4] Grid UI: mobium grid status and grid ui, and phones lent only by choice mobium grid status prints each node's devices -- platform, OS, model, state -- who holds each and for how long, the nodes down, and the runs waiting; mobium grid ui serves the same as a page on 127.0.0.1, one embedded file, refreshed every three seconds. Both read the grid node answer routing reads. For the view, a lease now records when it started (a renewal moves only the file's time), and a queued run leaves a note on each node it asked, touched every two seconds and lapsing after 15. Building it showed the grid listing a real iPhone as free to route to. A node now lends every emulator and simulator, and a physical phone only when its own environment sets MOBIUM_GRID_PHONES=1; a run asking for one by serial is told the node does not offer it. Live: two runs holding both emulators and a third queued showed as held, held and waiting in status, status.json and the page, with a dead node not answering; the port listened on 127.0.0.1 alone. --- cmd/mobium/grid.go | 74 +++++++++-- cmd/mobium/grid_ui.html | 99 ++++++++++++++ cmd/mobium/grid_view.go | 195 ++++++++++++++++++++++++++++ docs/API.md | 8 +- docs/FLAGS.md | 4 +- docs/ROADMAP.md | 13 +- docs/SETUP.md | 23 ++++ docs/api/flags.json | 12 +- docs/api/surface.json | 7 +- internal/apisurface/surface_test.go | 1 + internal/grid/grid_test.go | 63 +++++++++ internal/grid/lease.go | 47 ++++++- internal/grid/wait.go | 91 +++++++++++++ 13 files changed, 610 insertions(+), 27 deletions(-) create mode 100644 cmd/mobium/grid_ui.html create mode 100644 cmd/mobium/grid_view.go create mode 100644 internal/grid/grid_test.go create mode 100644 internal/grid/wait.go diff --git a/cmd/mobium/grid.go b/cmd/mobium/grid.go index 3f8f9b07..97ebc5b0 100644 --- a/cmd/mobium/grid.go +++ b/cmd/mobium/grid.go @@ -50,8 +50,10 @@ func gridNodes() []string { // nodeStatus is what `mobium grid node --json` prints: the devices here, and // which of them a run holds. type nodeStatus struct { - Devices []gridDevice `json:"devices"` - Leases map[string]string `json:"leases"` // serial -> holder, live leases only + Devices []gridDevice `json:"devices"` + Leases map[string]string `json:"leases"` // serial -> holder, live leases only + Held map[string]grid.Lease `json:"held"` // serial -> the lease in full, for a grid's view + Waiting []grid.Waiting `json:"waiting"` } // gridDevice is a device as a grid routes it: what `devices` reports, and @@ -59,13 +61,21 @@ type nodeStatus struct { type gridDevice struct { agent.DeviceView OS string `json:"os,omitempty"` + // Offered says the node lends this device to the grid: every emulator + // and simulator, and a physical phone only when the node's own + // environment says MOBIUM_GRID_PHONES=1. A phone plugged into a node is + // usually somebody's, and a grid run that took it would install, tap and + // change settings on it — so it is the node's choice, never the caller's. + Offered bool `json:"offered"` } func newGridCmd() *cobra.Command { cmd := &cobra.Command{ - Use: "grid", - Short: "The node's half of a mobium grid, run over SSH by the caller's mobium", - Hidden: true, + Use: "grid", + Short: "Look at the grid MOBIUM_GRID names: its nodes, devices, leases and queue", + Long: "`mobium grid status` prints it, and `mobium grid ui` serves it as a page on this\n" + + "machine. The other subcommands are the node's half of the grid, which the\n" + + "caller's mobium runs over SSH.", } var holder string node := &cobra.Command{ @@ -82,11 +92,18 @@ func newGridCmd() *cobra.Command { } var st nodeStatus for _, d := range dv.Devices { - st.Devices = append(st.Devices, gridDevice{DeviceView: d, OS: deviceOS(d)}) + st.Devices = append(st.Devices, gridDevice{DeviceView: d, OS: deviceOS(d), + Offered: d.Emulator || os.Getenv("MOBIUM_GRID_PHONES") == "1"}) } if st.Leases, err = grid.Live(); err != nil { return err } + if st.Held, err = grid.LiveLeases(); err != nil { + return err + } + if st.Waiting, err = grid.Queue(); err != nil { + return err + } return printJSON(st) }, } @@ -112,7 +129,22 @@ func newGridCmd() *cobra.Command { c.Flags().StringVar(&holder, "holder", "", "who holds the lease") _ = c.MarkFlagRequired("holder") } - cmd.AddCommand(node, lease, release) + var want string + wait := &cobra.Command{ + Use: "wait ", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { return grid.Wait(args[0], want) }, + } + wait.Flags().StringVar(&want, "want", "", "what the run is waiting for") + unwait := &cobra.Command{ + Use: "unwait ", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { return grid.Unwait(args[0]) }, + } + for _, c := range []*cobra.Command{node, lease, release, wait, unwait} { + c.Hidden = true + } + cmd.AddCommand(node, lease, release, wait, unwait, newGridStatusCmd(), newGridUICmd()) return cmd } @@ -153,6 +185,15 @@ func routeGrid(args map[string]interface{}) error { } nodes := gridNodes() deadline := time.Now().Add(wait) + want := describeWant(serial, platform) + // A queued run leaves a note on each node it can reach, so a grid's view + // shows the queue; it lapses by itself if this run dies. + var noted []string + defer func() { + for _, n := range noted { + _ = sshSession(n, "", "grid unwait "+gridHolder).Run() + } + }() for { statuses, down := askNodes(nodes) @@ -166,6 +207,10 @@ func routeGrid(args map[string]interface{}) error { if !deviceReady(d.DeviceView) || (serial != "" && d.ID != serial) || (platform != "" && d.Platform != platform) || !matches(d) { continue } + if !d.Offered { + busy = append(busy, fmt.Sprintf("%s on %s (a phone the node does not offer; MOBIUM_GRID_PHONES=1 there lends it)", d.ID, node)) + continue + } if h, held := st.Leases[grid.Key(d.ID)]; held { busy = append(busy, fmt.Sprintf("%s on %s (held by %s)", d.ID, node, h)) continue @@ -181,6 +226,12 @@ func routeGrid(args map[string]interface{}) error { if time.Now().After(deadline) { return noDevice(serial, platform, wait, busy, down) } + noted = noted[:0] + for n := range statuses { + if sshSession(n, "", "grid wait "+gridHolder+" --want "+shellWord(want)).Run() == nil { + noted = append(noted, n) + } + } time.Sleep(2 * time.Second) } } @@ -329,7 +380,9 @@ func newHolder() string { return "g" + hex.EncodeToString(b) } -func noDevice(serial, platform string, wait time.Duration, busy, down []string) error { +// describeWant says what a run asks the grid for, as its error and the +// queue both show it. +func describeWant(serial, platform string) string { want := "a device" switch { case serial != "": @@ -343,6 +396,11 @@ func noDevice(serial, platform string, wait time.Duration, busy, down []string) if o := os.Getenv("MOBIUM_GRID_OS"); o != "" { want += ", OS " + o } + return want +} + +func noDevice(serial, platform string, wait time.Duration, busy, down []string) error { + want := describeWant(serial, platform) msg := fmt.Sprintf("no node in MOBIUM_GRID had %s free within %s", want, wait) if len(busy) > 0 { msg += "; busy: " + strings.Join(busy, ", ") diff --git a/cmd/mobium/grid_ui.html b/cmd/mobium/grid_ui.html new file mode 100644 index 00000000..82478fa9 --- /dev/null +++ b/cmd/mobium/grid_ui.html @@ -0,0 +1,99 @@ + + + + + +Mobium Grid + + + +
+
+

Mobium Grid

+
reading the nodes…
+
+
+
+
+ + + diff --git a/cmd/mobium/grid_view.go b/cmd/mobium/grid_view.go new file mode 100644 index 00000000..8936a8df --- /dev/null +++ b/cmd/mobium/grid_view.go @@ -0,0 +1,195 @@ +package main + +import ( + _ "embed" + "encoding/json" + "fmt" + "net" + "net/http" + "os" + "os/signal" + "sort" + "strings" + "sync" + "text/tabwriter" + "time" + + "github.com/mobiumdev/mobium/internal/grid" + "github.com/mobiumdev/mobium/internal/mobiumerr" + "github.com/spf13/cobra" +) + +// gridView is the grid as its nodes report it now — what `grid status` +// prints and `grid ui` shows. It is built from the same `grid node` answers +// the router reads, so the view cannot disagree with where runs are routed. +type gridView struct { + At time.Time `json:"at"` + Nodes []nodeView `json:"nodes"` +} + +type nodeView struct { + Name string `json:"name"` + Up bool `json:"up"` + Error string `json:"error,omitempty"` + Devices []deviceView `json:"devices"` + Waiting []grid.Waiting `json:"waiting"` +} + +type deviceView struct { + gridDevice + Lease *grid.Lease `json:"lease,omitempty"` +} + +// readGrid asks every node at once, as routing does. +func readGrid() (gridView, error) { + nodes := gridNodes() + if len(nodes) == 0 { + return gridView{}, mobiumerr.New(mobiumerr.InvalidArgument, "MOBIUM_GRID names no nodes"). + WithRemedy("set MOBIUM_GRID=node1,node2 — the machines whose devices the grid spreads runs over") + } + view := gridView{At: time.Now(), Nodes: make([]nodeView, len(nodes))} + var wg sync.WaitGroup + for i, n := range nodes { + wg.Add(1) + go func(i int, n string) { + defer wg.Done() + nv := nodeView{Name: n} + var st nodeStatus + if err := runJSON(sshSession(n, "", "grid node --json"), &st); err != nil { + nv.Error = err.Error() + } else { + nv.Up, nv.Waiting = true, st.Waiting + for _, d := range st.Devices { + dv := deviceView{gridDevice: d} + if l, ok := st.Held[grid.Key(d.ID)]; ok { + l := l + dv.Lease = &l + } + nv.Devices = append(nv.Devices, dv) + } + } + view.Nodes[i] = nv + }(i, n) + } + wg.Wait() + return view, nil +} + +func newGridStatusCmd() *cobra.Command { + return &cobra.Command{ + Use: "status", + Short: "Print each node's devices, who holds them, and who is waiting", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, args []string) error { + view, err := readGrid() + if err != nil { + return err + } + if jsonOutput { + return printJSON(view) + } + w := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0) + fmt.Fprintln(w, "NODE\tDEVICE\tPLATFORM\tOS\tMODEL\tSTATE\tHELD BY") + for _, n := range view.Nodes { + if !n.Up { + fmt.Fprintf(w, "%s\t(not answering: %s)\t\t\t\t\t\n", n.Name, firstLine(n.Error)) + continue + } + if len(n.Devices) == 0 { + fmt.Fprintf(w, "%s\t(no devices)\t\t\t\t\t\n", n.Name) + } + for _, d := range n.Devices { + held := "free" + if !d.Offered { + held = "not offered (a phone; MOBIUM_GRID_PHONES=1 on the node lends it)" + } + if d.Lease != nil { + held = fmt.Sprintf("%s for %s", d.Lease.Holder, time.Since(d.Lease.Since).Round(time.Second)) + } + fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n", n.Name, d.ID, d.Platform, d.OS, d.Model, d.State, held) + } + } + if err := w.Flush(); err != nil { + return err + } + var queued []string + for _, n := range view.Nodes { + for _, q := range n.Waiting { + queued = append(queued, fmt.Sprintf(" %s wants %s, waiting %s (seen by %s)", + q.Holder, q.Want, time.Since(q.Since).Round(time.Second), n.Name)) + } + } + if len(queued) > 0 { + sort.Strings(queued) + fmt.Println("\nwaiting:") + fmt.Println(strings.Join(queued, "\n")) + } + return nil + }, + } +} + +//go:embed grid_ui.html +var gridPage []byte + +func newGridUICmd() *cobra.Command { + var port int + cmd := &cobra.Command{ + Use: "ui", + Short: "Serve the grid's status as a page on this machine", + Long: "Serves a page showing each node, its devices, who holds each and for how\\n" + + "long, and who is waiting — refreshed every few seconds from the nodes. It\\n" + + "listens on 127.0.0.1 only: nothing off this machine can reach it.", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, args []string) error { + if len(gridNodes()) == 0 { + _, err := readGrid() + return err + } + // One reading at a time, and reused for two seconds, so a page left + // open in several tabs does not multiply the SSH calls. + var mu sync.Mutex + var last gridView + var lastAt time.Time + mux := http.NewServeMux() + mux.HandleFunc("/status.json", func(w http.ResponseWriter, r *http.Request) { + mu.Lock() + if time.Since(lastAt) > 2*time.Second { + if v, err := readGrid(); err == nil { + last, lastAt = v, time.Now() + } + } + v := last + mu.Unlock() + w.Header().Set("Content-Type", "application/json") + w.Header().Set("Cache-Control", "no-store") + _ = json.NewEncoder(w).Encode(v) + }) + mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/" { + http.NotFound(w, r) + return + } + w.Header().Set("Content-Type", "text/html; charset=utf-8") + _, _ = w.Write(gridPage) + }) + ln, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", port)) + if err != nil { + return err + } + fmt.Printf("grid ui on http://%s — Ctrl-C to stop\n", ln.Addr()) + srv := &http.Server{Handler: mux, ReadHeaderTimeout: 10 * time.Second} + stop := make(chan os.Signal, 1) + signal.Notify(stop, os.Interrupt) + go func() { <-stop; _ = srv.Close() }() + if err := srv.Serve(ln); err != http.ErrServerClosed { + return err + } + return nil + }, + } + cmd.Flags().IntVar(&port, "port", 0, "port on 127.0.0.1 (default: any free one)") + return cmd +} + +func firstLine(s string) string { return strings.TrimSpace(strings.SplitN(s, "\n", 2)[0]) } diff --git a/docs/API.md b/docs/API.md index dbe93ed4..785563ee 100644 --- a/docs/API.md +++ b/docs/API.md @@ -20,9 +20,9 @@ differently. | --- | --- | | Tools | **56** | | CLI commands registered | 62 | -| …visible in `mobium --help` | 60 | -| …hidden | 2 (grid, pipe) | -| Command constructors in source | 66 (includes `daemon start`, `stop`, `status`) | +| …visible in `mobium --help` | 61 | +| …hidden | 1 (pipe) | +| Command constructors in source | 68 (includes `daemon start`, `stop`, `status`) | | Client libraries | 5 | Those three command counts differ on purpose, and the arithmetic is asserted @@ -109,7 +109,9 @@ been wrong twice. - `pipe` - `start` - `status` +- `status` - `stop` +- `ui` - `up` diff --git a/docs/FLAGS.md b/docs/FLAGS.md index f548b864..01670532 100644 --- a/docs/FLAGS.md +++ b/docs/FLAGS.md @@ -294,7 +294,7 @@ arguments and the two global flags. | `fill` | app_fill | — | target, text | | `find` | app_find | — | locator | | `grant` | app_grant | — | app, permissions | -| `grid` | — | --holder | — | +| `grid` | — | --holder --want | — | | `install` | app_install | — | path | | `keyboard` | app_keyboard | --hide --key --text | hide, key, text | | `launch` | app_launch | — | app | @@ -323,6 +323,7 @@ arguments and the two global flags. | `sms` | app_sms | --from | from, text | | `source` | app_source | — | — | | `start` | — | --idle-timeout | — | +| `status` | — | — | — | | `status` | — | — | running | | `stop` | — | — | status | | `storage` | app_storage, app_storage, app_storage | --output | action, state | @@ -332,6 +333,7 @@ arguments and the two global flags. | `text` | app_text | — | target | | `timezone` | app_timezone | — | timezone | | `type` | app_type | — | target, text | +| `ui` | — | --port | — | | `uncheck` | app_check | — | checked, target | | `uninstall` | app_uninstall | — | app | | `up` | — | — | — | diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 97c46e0d..386db92c 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -139,11 +139,14 @@ this is what is not. a run on the node that bypassed the grid was refused, naming the holder. Still to do: one device per run holds as anywhere, and nothing yet shares one session between two runs. - 5. **A grid UI** (written down 2026-09-28): a page showing each node, its - devices, who holds each lease and for how long, and what is queued — - the view Selenium Grid's console gives. Built from the same - `mobium grid node` answer the router reads, so it can never disagree - with what routing does. + 5. **A grid UI — done, 2026-09-28.** `mobium grid status` and `mobium grid + ui`, a page on `127.0.0.1` refreshed every few seconds: each node, its + devices, who holds each lease and for how long, the nodes down, and the + runs waiting — each queued run leaves a note on the nodes it asked, + which lapses by itself. Both read the answer routing reads. Building it + showed the grid listing a real iPhone as free: a node now lends a + physical phone only with `MOBIUM_GRID_PHONES=1` in its own + environment. 6. **Docker for remote** (written down 2026-09-28): a node in a container — an Android emulator with mobium and an SSH server beside it — so a grid can be stood up without a spare machine, and torn down with it. Android diff --git a/docs/SETUP.md b/docs/SETUP.md index cd039f1e..99781b32 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -596,6 +596,29 @@ on the node refuses a device leased to another: a `mobium --device` run on the node that goes around the grid is told the device belongs to a grid run until that run ends. The run's daemon stops with it. +**A node lends its emulators and simulators, and a phone only when it says +so.** A phone plugged into a node is usually somebody's, and a grid run on it +would install, tap and change settings; so a physical device is routed to +only when the node's own environment sets `MOBIUM_GRID_PHONES=1` — the +node's choice, never the caller's. Until then it is listed as not offered, +and a run that asks for it by serial is told so. + +**`mobium grid status`** prints each node's devices — platform, OS, model, +state — who holds each and for how long, the nodes not answering, and the +runs waiting. **`mobium grid ui`** serves the same as a page, refreshed every +few seconds, on `127.0.0.1` only. Both read the nodes' own answers, the ones +routing reads, so neither can disagree with where runs go. + +``` +$ mobium grid status +NODE DEVICE PLATFORM OS MODEL STATE HELD BY +lab-mac emulator-5554 android Android 15 sdk_gphone64_arm64 device g5c1e9a07 for 42s +lab-mac emulator-5556 android Android 17 sdk_gphone64_arm64 device free + +waiting: + g0d4f2b11 wants an android device, OS 15, waiting 9s (seen by lab-mac) +``` + A lease is renewed every 20 seconds while its run lives, released when it ends, and free again 60 seconds after a run that died without releasing it. A run killed outright takes its SSH forward with it, and the next run clears diff --git a/docs/api/flags.json b/docs/api/flags.json index 383e688e..24a86df8 100644 --- a/docs/api/flags.json +++ b/docs/api/flags.json @@ -2270,7 +2270,8 @@ { "command": "grid", "flags": [ - "--holder" + "--holder", + "--want" ] }, { @@ -2604,6 +2605,9 @@ "--idle-timeout" ] }, + { + "command": "status" + }, { "command": "status", "sends": [ @@ -2701,6 +2705,12 @@ "text" ] }, + { + "command": "ui", + "flags": [ + "--port" + ] + }, { "command": "uncheck", "tools": [ diff --git a/docs/api/surface.json b/docs/api/surface.json index 6e775cc1..43e5c316 100644 --- a/docs/api/surface.json +++ b/docs/api/surface.json @@ -703,12 +703,11 @@ "counts": { "tools": 56, "cliRegistered": 62, - "cliVisible": 60, + "cliVisible": 61, "cliHidden": [ - "grid", "pipe" ], - "cliConstructors": 66, + "cliConstructors": 68, "clients": 5 }, "cliWithoutTool": [ @@ -718,7 +717,9 @@ "pipe", "start", "status", + "status", "stop", + "ui", "up" ] } diff --git a/internal/apisurface/surface_test.go b/internal/apisurface/surface_test.go index f34c8d71..3df74a34 100644 --- a/internal/apisurface/surface_test.go +++ b/internal/apisurface/surface_test.go @@ -63,6 +63,7 @@ func TestCLICommandsWithoutAToolAreTheProcessOnes(t *testing.T) { expected := map[string]bool{ "daemon": true, "start": true, "status": true, "stop": true, "up": true, "grid": true, "node": true, "lease": true, "release": true, + "wait": true, "unwait": true, "ui": true, "mcp": true, "pipe": true, } for _, cmd := range sweep(t).Extra { diff --git a/internal/grid/grid_test.go b/internal/grid/grid_test.go new file mode 100644 index 00000000..3277de58 --- /dev/null +++ b/internal/grid/grid_test.go @@ -0,0 +1,63 @@ +package grid + +import ( + "os" + "path/filepath" + "testing" + "time" +) + +// A lease says how long it has been held, and a renewal does not reset that: +// it moves only the file's time. +func TestALeaseKnowsWhenItStarted(t *testing.T) { + t.Setenv("MOBIUM_HOME", t.TempDir()) + if a, _ := Take("emulator-5554", "g1"); !a.OK { + t.Fatal("not leased") + } + f := filepath.Join(os.Getenv("MOBIUM_HOME"), "leases", Key("emulator-5554")) + started := time.Now().Add(-30 * time.Second) + os.WriteFile(f, []byte("g1\n"+started.UTC().Format(time.RFC3339)), 0o600) + Take("emulator-5554", "g1") // a renewal + l := mustLease(t, "emulator-5554") + if l.Holder != "g1" || time.Since(l.Since) < 29*time.Second { + t.Errorf("after a renewal the lease reads %+v, started ~30s ago", l) + } + if h, ok := Holder("emulator-5554"); !ok || h != "g1" { + t.Errorf("Holder read %q, %v from a file with a start time in it", h, ok) + } +} + +func mustLease(t *testing.T, serial string) Lease { + t.Helper() + all, err := LiveLeases() + if err != nil { + t.Fatal(err) + } + l, ok := all[Key(serial)] + if !ok { + t.Fatalf("no live lease on %s", serial) + } + return l +} + +// The queue is the runs that touched their note lately, oldest first; a +// note left by a run that stopped lapses by itself. +func TestTheQueue(t *testing.T) { + t.Setenv("MOBIUM_HOME", t.TempDir()) + Wait("g1", "an android device") + time.Sleep(1100 * time.Millisecond) + Wait("g2", "an ios device") + q, _ := Queue() + if len(q) != 2 || q[0].Holder != "g1" || q[0].Want != "an android device" { + t.Fatalf("queue %+v", q) + } + old := time.Now().Add(-2 * WaitTTL) + os.Chtimes(filepath.Join(os.Getenv("MOBIUM_HOME"), "waiting", "g1"), old, old) + if q, _ := Queue(); len(q) != 1 || q[0].Holder != "g2" { + t.Errorf("a lapsed note is still queued: %+v", q) + } + Unwait("g2") + if q, _ := Queue(); len(q) != 0 { + t.Errorf("an unwaited run is still queued: %+v", q) + } +} diff --git a/internal/grid/lease.go b/internal/grid/lease.go index dd3e566a..09fb3dd1 100644 --- a/internal/grid/lease.go +++ b/internal/grid/lease.go @@ -19,6 +19,14 @@ import ( // so a lease past it belongs to a run that stopped, most likely by dying. const TTL = 60 * time.Second +// Lease is a live lease as a node reports it: its holder, when it was taken, +// and when its holder last renewed it. +type Lease struct { + Holder string `json:"holder"` + Since time.Time `json:"since"` + Renewed time.Time `json:"renewed"` +} + // Answer is what taking a lease says: whether it was given, and to whom. type Answer struct { OK bool `json:"ok"` @@ -55,7 +63,9 @@ func Take(serial, holder string) (Answer, error) { } for attempt := 0; attempt < 2; attempt++ { if w, err := os.OpenFile(f, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600); err == nil { - _, err = w.WriteString(holder) + // The holder, then when it took the device; a renewal moves only + // the file's time, so the start survives it. + _, err = w.WriteString(holder + "\n" + time.Now().UTC().Format(time.RFC3339)) w.Close() return Answer{OK: err == nil, Holder: holder}, err } @@ -102,6 +112,19 @@ func Holder(serial string) (string, bool) { // Live maps each leased device's key to its holder, live leases only. func Live() (map[string]string, error) { + leases, err := LiveLeases() + if err != nil { + return nil, err + } + out := map[string]string{} + for k, l := range leases { + out[k] = l.Holder + } + return out, nil +} + +// LiveLeases maps each leased device's key to its lease, live ones only. +func LiveLeases() (map[string]Lease, error) { d, err := dir() if err != nil { return nil, err @@ -110,21 +133,33 @@ func Live() (map[string]string, error) { if err != nil { return nil, err } - out := map[string]string{} + out := map[string]Lease{} for _, e := range entries { - held, info, err := read(filepath.Join(d, e.Name())) - if err == nil && time.Since(info.ModTime()) < TTL { - out[e.Name()] = held + f := filepath.Join(d, e.Name()) + held, info, err := read(f) + if err != nil || time.Since(info.ModTime()) >= TTL { + continue + } + l := Lease{Holder: held, Since: info.ModTime(), Renewed: info.ModTime()} + if b, err := os.ReadFile(f); err == nil { + if parts := strings.SplitN(strings.TrimSpace(string(b)), "\n", 2); len(parts) == 2 { + if t, err := time.Parse(time.RFC3339, parts[1]); err == nil { + l.Since = t + } + } } + out[e.Name()] = l } return out, nil } +// read returns a lease file's holder — its first line — and the file's info. func read(f string) (string, os.FileInfo, error) { info, err := os.Stat(f) if err != nil { return "", nil, err } b, err := os.ReadFile(f) - return strings.TrimSpace(string(b)), info, err + holder := strings.TrimSpace(strings.SplitN(string(b), "\n", 2)[0]) + return holder, info, err } diff --git a/internal/grid/wait.go b/internal/grid/wait.go new file mode 100644 index 00000000..dcef2372 --- /dev/null +++ b/internal/grid/wait.go @@ -0,0 +1,91 @@ +package grid + +import ( + "os" + "path/filepath" + "strings" + "time" + + "github.com/mobiumdev/mobium/internal/paths" +) + +// WaitTTL is how long a waiting note lasts untouched. A queued run touches +// its note every two seconds, so one older than this belongs to a run that +// stopped waiting — got a device elsewhere, gave up, or died. +const WaitTTL = 15 * time.Second + +// Waiting is a run queued for a device, as a node heard it: who, what it +// asked for, and since when. +type Waiting struct { + Holder string `json:"holder"` + Want string `json:"want"` + Since time.Time `json:"since"` +} + +func waitDir() (string, error) { + d := filepath.Join(paths.Root(), "waiting") + return d, os.MkdirAll(d, 0o700) +} + +// Wait records, or refreshes, a run waiting for a device. Nothing routes by +// it: it is there so a grid's view can show the queue, which otherwise lives +// only in each waiting run's own process. +func Wait(holder, want string) error { + d, err := waitDir() + if err != nil { + return err + } + f := filepath.Join(d, Key(holder)) + if _, err := os.Stat(f); err == nil { + now := time.Now() + return os.Chtimes(f, now, now) + } + return os.WriteFile(f, []byte(want+"\n"+time.Now().UTC().Format(time.RFC3339)), 0o600) +} + +// Unwait removes a run's waiting note. +func Unwait(holder string) error { + d, err := waitDir() + if err != nil { + return err + } + if err := os.Remove(filepath.Join(d, Key(holder))); err != nil && !os.IsNotExist(err) { + return err + } + return nil +} + +// Queue lists the runs waiting now, oldest first. +func Queue() ([]Waiting, error) { + d, err := waitDir() + if err != nil { + return nil, err + } + entries, err := os.ReadDir(d) + if err != nil { + return nil, err + } + var out []Waiting + for _, e := range entries { + f := filepath.Join(d, e.Name()) + info, err := os.Stat(f) + if err != nil || time.Since(info.ModTime()) >= WaitTTL { + continue + } + b, _ := os.ReadFile(f) + parts := strings.SplitN(strings.TrimSpace(string(b)), "\n", 2) + w := Waiting{Holder: e.Name(), Want: parts[0], Since: info.ModTime()} + if len(parts) == 2 { + if t, err := time.Parse(time.RFC3339, parts[1]); err == nil { + w.Since = t + } + } + out = append(out, w) + } + for i := 1; i < len(out); i++ { + for j := i; j > 0 && out[j].Since.Before(out[j-1].Since); j-- { + out[j], out[j-1] = out[j-1], out[j] + } + } + return out, nil +} From e1d28331cc6c0fd58bcf644d45ae39e2e5faa682 Mon Sep 17 00:00:00 2001 From: Lana Begunova <70295997+lana-20@users.noreply.github.com> Date: Mon, 28 Sep 2026 04:00:06 -0700 Subject: [PATCH 4/4] Break ties between same-named commands in the flags table, and give the lease test a portable temp dir daemon status and grid status share a name, and sorting by name alone reordered their rows from run to run, so flags-check failed at random. The lease test made its home under /tmp, which Windows does not have. --- docs/FLAGS.md | 2 +- docs/api/flags.json | 6 +++--- internal/agent/lease_test.go | 10 ++-------- internal/apisurface/flags.go | 13 +++++++++++-- 4 files changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/FLAGS.md b/docs/FLAGS.md index 01670532..a06b469a 100644 --- a/docs/FLAGS.md +++ b/docs/FLAGS.md @@ -323,8 +323,8 @@ arguments and the two global flags. | `sms` | app_sms | --from | from, text | | `source` | app_source | — | — | | `start` | — | --idle-timeout | — | -| `status` | — | — | — | | `status` | — | — | running | +| `status` | — | — | — | | `stop` | — | — | status | | `storage` | app_storage, app_storage, app_storage | --output | action, state | | `swipe` | app_swipe | --duration | direction, duration_ms, x1, x2, y1, y2 | diff --git a/docs/api/flags.json b/docs/api/flags.json index 24a86df8..01d4f576 100644 --- a/docs/api/flags.json +++ b/docs/api/flags.json @@ -2605,15 +2605,15 @@ "--idle-timeout" ] }, - { - "command": "status" - }, { "command": "status", "sends": [ "running" ] }, + { + "command": "status" + }, { "command": "stop", "sends": [ diff --git a/internal/agent/lease_test.go b/internal/agent/lease_test.go index 76496d4f..cc5abd62 100644 --- a/internal/agent/lease_test.go +++ b/internal/agent/lease_test.go @@ -2,7 +2,6 @@ package agent import ( "context" - "os" "testing" "github.com/mobiumdev/mobium/internal/grid" @@ -13,12 +12,7 @@ import ( // node — the one a run that bypassed the grid would use included — and // allowed to the run's own, whose session name is the lease's holder. func TestALeasedDeviceBelongsToItsRun(t *testing.T) { - home, err := os.MkdirTemp("/tmp", "mbl-") - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { os.RemoveAll(home) }) - t.Setenv("MOBIUM_HOME", home) + t.Setenv("MOBIUM_HOME", t.TempDir()) t.Setenv("MOBIUM_SESSION", "") h, _, _ := withFake(t, screen(t, "OK")) @@ -31,7 +25,7 @@ func TestALeasedDeviceBelongsToItsRun(t *testing.T) { if got, _ := grid.Take("fake", "g1234abcd"); !got.OK { t.Fatal("could not lease the device") } - _, err = h.sessionFor(ctx, args) + _, err := h.sessionFor(ctx, args) if mobiumerr.CodeOf(err) != mobiumerr.DeviceNotReady { t.Fatalf("another daemon reached a leased device: %v", err) } diff --git a/internal/apisurface/flags.go b/internal/apisurface/flags.go index 30cfed9b..2ea90195 100644 --- a/internal/apisurface/flags.go +++ b/internal/apisurface/flags.go @@ -53,6 +53,10 @@ type CommandFlags struct { // Unknown are keys it sends that no tool it dispatches declares. These // are the defects this sweep exists to catch. Unknown []string `json:"unknown,omitempty"` + // fn is the constructor, which breaks ties between commands that share a + // name under different parents — `daemon status` and `grid status` — so + // the generated table does not reorder between runs. + fn string } // globalArgs are attached by daemonCall from persistent flags rather than by @@ -134,7 +138,12 @@ func CollectFlags(root string) ([]ArgEntry, []CommandFlags, error) { } return args[i].Name < args[j].Name }) - sort.Slice(cmds, func(i, j int) bool { return cmds[i].Command < cmds[j].Command }) + sort.Slice(cmds, func(i, j int) bool { + if cmds[i].Command != cmds[j].Command { + return cmds[i].Command < cmds[j].Command + } + return cmds[i].fn < cmds[j].fn + }) return args, cmds, nil } @@ -185,7 +194,7 @@ func collectCommandFlags(dir string) ([]CommandFlags, error) { if use == "" { continue } - c := CommandFlags{Command: use, Tools: tools} + c := CommandFlags{Command: use, Tools: tools, fn: fn.Name.Name} c.Flags, c.Sends = inspectFlagsAndKeys(fn, local, map[string]bool{}) out = append(out, c) }