Purpose and progress
Several callers can use one PC at the same time: the developer, agents in sandboxes and test scripts. A purpose says what a fleet or machine is being used for. Progress is the caller's own count of how far that work has got. With both, the developer can tell a run that is nearly done from one that has just begun, and a slow run from a stuck one, as long as the caller keeps its count up to date. East India stores both and shows them. It does not run or understand the work, and it never estimates progress: a bar moves only when a caller reports a count.
Recording what a run is for
Give the fleet its purpose when you launch it. The title is one line; the notes are an optional Markdown file, such as what the run covers, whom to ask and what not to touch:
endia compose -p "$run" up --wait --purpose "Regression run 412" --purpose-file notes.md
Write the title for the person watching the PC. The desktop app shows it on Home, on one line, beside each running fleet, so say in plain words what the run is doing and why, in about 60 characters or fewer: Checkout smoke tests before the 2.4 release, not smoke-2/test_checkout.py_test_pay_with_card_as_admin. File names, folders, test IDs and timestamps belong in the notes file, where the app shows them in full. A longer title is cut off with an ellipsis.
Change it at any time with endia update, which names a fleet or a machine:
endia update "$run" --purpose "Regression run 412, retrying the login tests"
endia update "$run-client-1" --purpose "Debugging the login timeout"
endia update "$run-client-1" --purpose ""
- A machine inherits its fleet's purpose. A purpose set on one machine overrides the fleet's for that machine only.
--purpose ""clears it, and the machine shows the fleet's purpose again. --purposereplaces the whole purpose, so give--purpose-fileagain to keep the notes.--purpose-file -reads the notes from standard input.- The limits. A title is 1 to 200 characters without a line break, and the notes are at most 65536 bytes of UTF-8.
- Who set it. The service records the caller with each purpose: the client certificate's name over HTTPS, such as
sandbox-1.
endia purpose show <fleet or machine> prints the purpose in effect, who set it and when, then the notes as plain text. With --history it also lists each change. When a name belongs to both a fleet and a machine, endia update and endia purpose show ask you to choose with --fleet or --machine. endia compose down writes the fleet's history to its operation log before it removes the fleet, so the record outlives the run.
Reporting progress
A caller reports progress as counts of whatever it counts, such as files, tests or images:
| Option | Set on | Meaning |
|---|---|---|
--progress |
a machine | The progress: how much of the work the machine has done, a whole number from 0. |
--workload |
a fleet or a machine | The workload: the total amount of work, a whole number from 0. |
--stage |
a fleet | The stage: what the work is doing now, in your own words, 1 to 200 characters without a line break. |
A fleet's done figure is always the sum of its machines' progress, so a fleet takes no --progress count of its own. East India shows a stage exactly as given and reads nothing from it, so a step number such as Run tests 2/2 is part of the text.
- The total is held in one place: on the fleet or on its machines, never on both, because two totals for one piece of work could disagree. Whichever arrives first stays until it is removed.
- A machine sends its workload with its progress, in the same command. Progress alone is fine; a workload alone is refused.
- A support machine sends 0 of 0. A machine that only serves the others, such as a cache, sends
--progress 0 --workload 0and is left out of the fleet's sums. - Progress above the workload is accepted and shows as 100 per cent.
- Stopped and exited machines keep their counts in the fleet's sums, because work done stays done.
- Setting a stage starts a new one. It removes the machines' counts and workloads and the fleet's workload, and adds the stage that ended, with its final figures, to the history.
--stage ""ends the stage without starting another. A count is not added to the history, so send one as often as you like.
When the machines hold the workloads but a running machine has none, the fleet is open-ended: the bar shows how far the measured work has got, and that more work is still running.
A nightly run
The fleet nightly has three runners and a cache, nightly-shop-1. The first stage counts images on the fleet; the second counts tests on each runner:
endia update nightly --purpose "Nightly build and test" --stage "Build images 1/2" --workload 3
endia update nightly-runner-1 --progress 1
endia update nightly --stage "Run tests 2/2"
endia update nightly-runner-1 --progress 30 --workload 120
endia update nightly-runner-2 --progress 20 --workload 80
endia update nightly-runner-3 --progress 10 --workload 100
endia update nightly-shop-1 --progress 0 --workload 0
endia update nightly --progress -1
- After the second line, Home shows
Build images 1/2with the bar at 33 per cent, 1 of 3. - The new stage removes the counts and the fleet's workload, and adds
Build images 1/2with 1 of 3 to the history. Home showsRun tests 2/2with the infinity bar until the runners report. - Once the runners have reported, Home shows 20 per cent, 60 of 300.
nightly-shop-1is left out of the sums. - The last line removes the fleet's progress, and Home shows the infinity bar again while the fleet runs.
endia update prints the name of the fleet or machine it changed. endia purpose show nightly prints Stage: Run tests 2/2 and Progress: 60 of 300 (20%); a support machine shows Progress: 0 of 0 (support). endia ps --format '{{.Progress.Progress}}' prints each machine's count.
Removing a value
As with Docker's docker update --memory-swap -1, -1 removes a number and "" removes text:
| Option | Sent to | Values removed |
|---|---|---|
--progress -1 |
a machine | The machine's progress and its workload. |
--workload -1 |
a machine | The machine's workload only. |
--workload -1 |
a fleet | The fleet's workload, after which its machines may send their own. |
--progress -1 |
a fleet | All the fleet's progress: its stage, its workload and every machine's counts. The stage that ends goes into the history. |
--stage "" |
a fleet | The stage, with the counts, as a new stage would. |
--purpose "" |
a fleet or a machine | The purpose, and with it the progress of the same fleet or machine. |
For example, endia update nightly-runner-2 --workload -1 removes that runner's workload and keeps its progress.
In the desktop app
Home shows each running fleet's bar under its purpose. The fleet's purpose card, the machine's page, and the Progress columns of the fleet list and the machines table show bars too.
- The progress ship bar, for work with a total: the bar fills to the percentage, with a ship sailing along it, its bow at the end of the filled part. Beside it are the percentage, the stage, the counts and when they last changed:
Run tests 2/2, 60 of 300, updated 1 minute ago. - The infinity bar, for running work with no total: a band of diagonal stripes moving left to right, with no ship and no percentage. Beside it are the stage and the done count when there is one, such as
Convert photos, 6,200. - The ship with the infinity bar ahead, for an open-ended fleet: the ship bar, with the stripes moving in the part not yet filled. It becomes the plain ship bar when the open-ended machines stop, and the infinity bar when the measured ones finish first.
- No report. A running fleet or machine that reports nothing shows the infinity bar. So does a support machine, with no words beside it. A stopped or exited fleet or machine draws no bar, and keeps its counts.
The stripes stand still when Windows is set to show fewer animations. A screen reader reads the bar as its figure, such as 20 per cent, 60 of 300, or as Running, no total given. East India's own operations, such as a build, keep their plain progress bar, so the ship always means a caller's count.
Errors
| Error | When |
|---|---|
PROGRESS_CONFLICT |
A machine sends a workload while its fleet holds one, or a fleet sets a workload while any of its machines holds one. The message says which holds the total: nightly holds the workload; send the machine's progress only, or machines of nightly hold workloads; remove them first. |
INVALID_REQUEST |
A machine sends a workload without its progress, or a machine sends a stage, which belongs to its fleet. |
| exit 125 | endia update without an option, a count that is not a whole number from -1, a title with a line break, notes over 65536 bytes, or --purpose-file without --purpose. Nothing was sent. |
None of these changes is an operation: each command answers at once.