exedev 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: exedev
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Official Python SDK for the exe.dev HTTPS API
5
5
  Project-URL: Homepage, https://exe.dev
6
6
  Project-URL: Documentation, https://exe.dev/docs/https-api
@@ -164,7 +164,9 @@ seconds (60, or 600 for setup), `VMReadyError` is raised.
164
164
 
165
165
  If waiting fails, or is interrupted by an exception, a `KeyboardInterrupt`,
166
166
  or cancellation, `new()` deletes the VM before raising. Pass
167
- `keep_on_failure=True` to keep it for debugging, as `err.vm`.
167
+ `keep_on_failure=True` to keep it for debugging, as `err.vm`. Interrupted
168
+ while the server is still creating the VM, `new()` (and `vm.copy()`) waits
169
+ for it, deletes it, and then raises; a second interrupt gives up on it.
168
170
 
169
171
  A VM from `new()` or `vm.copy()` is a context manager that deletes it at the
170
172
  end of the block (`async with exe.new() as vm:` in async code). Otherwise,
@@ -178,9 +180,9 @@ for vm in exe.vms(): # or exe.vms("web-*")
178
180
 
179
181
  vm = exe.vm("build") # NotFoundError if there is none
180
182
 
181
- copy = vm.copy("build-2", cpu=8) # a new VM with a copy of the disk (syncs it first)
183
+ copy = vm.copy("build-2", cpu=8) # a new VM with a copy of the disk
182
184
  vm.restart() # waits for SSH again, like new()
183
- vm.pause(); vm.resume()
185
+ vm.pause(); vm.resume() # a paused VM can be copied too
184
186
  vm.rename("builder") # vm.name, ssh_dest, and https_url follow
185
187
  vm.tag("ci", "linux"); vm.untag("linux")
186
188
  vm.set_comment("nightly builds")
@@ -196,6 +198,11 @@ A VM's attributes (`status`, `ssh_dest`, `https_url`, `tags`, `comment`,
196
198
  `region`, `created_at`) are a snapshot: the SDK's own operations keep them
197
199
  current, and `refresh()` fetches the rest.
198
200
 
201
+ `copy()`, `pause()`, and `restart()` (and `resize(restart=True)`) first flush
202
+ the VM's recent writes to its disk, so that copies and the restarted VM have
203
+ them. Pass `flush=False` to skip that. It is best effort: it needs a token that
204
+ may run `ssh`.
205
+
199
206
  `vm.delete()` raises `NotFoundError` for a VM that is gone, while
200
207
  `exe.delete()` reports each VM's fate in its result, since some may be
201
208
  deleted and others not.
@@ -147,7 +147,9 @@ seconds (60, or 600 for setup), `VMReadyError` is raised.
147
147
 
148
148
  If waiting fails, or is interrupted by an exception, a `KeyboardInterrupt`,
149
149
  or cancellation, `new()` deletes the VM before raising. Pass
150
- `keep_on_failure=True` to keep it for debugging, as `err.vm`.
150
+ `keep_on_failure=True` to keep it for debugging, as `err.vm`. Interrupted
151
+ while the server is still creating the VM, `new()` (and `vm.copy()`) waits
152
+ for it, deletes it, and then raises; a second interrupt gives up on it.
151
153
 
152
154
  A VM from `new()` or `vm.copy()` is a context manager that deletes it at the
153
155
  end of the block (`async with exe.new() as vm:` in async code). Otherwise,
@@ -161,9 +163,9 @@ for vm in exe.vms(): # or exe.vms("web-*")
161
163
 
162
164
  vm = exe.vm("build") # NotFoundError if there is none
163
165
 
164
- copy = vm.copy("build-2", cpu=8) # a new VM with a copy of the disk (syncs it first)
166
+ copy = vm.copy("build-2", cpu=8) # a new VM with a copy of the disk
165
167
  vm.restart() # waits for SSH again, like new()
166
- vm.pause(); vm.resume()
168
+ vm.pause(); vm.resume() # a paused VM can be copied too
167
169
  vm.rename("builder") # vm.name, ssh_dest, and https_url follow
168
170
  vm.tag("ci", "linux"); vm.untag("linux")
169
171
  vm.set_comment("nightly builds")
@@ -179,6 +181,11 @@ A VM's attributes (`status`, `ssh_dest`, `https_url`, `tags`, `comment`,
179
181
  `region`, `created_at`) are a snapshot: the SDK's own operations keep them
180
182
  current, and `refresh()` fetches the rest.
181
183
 
184
+ `copy()`, `pause()`, and `restart()` (and `resize(restart=True)`) first flush
185
+ the VM's recent writes to its disk, so that copies and the restarted VM have
186
+ them. Pass `flush=False` to skip that. It is best effort: it needs a token that
187
+ may run `ssh`.
188
+
182
189
  `vm.delete()` raises `NotFoundError` for a VM that is gone, while
183
190
  `exe.delete()` reports each VM's fate in its result, since some may be
184
191
  deleted and others not.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "exedev"
3
- version = "0.2.0"
3
+ version = "0.3.0"
4
4
  description = "Official Python SDK for the exe.dev HTTPS API"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -11,6 +11,8 @@
11
11
  AsyncClient is the same API for asyncio.
12
12
  """
13
13
 
14
+ from importlib.metadata import PackageNotFoundError, version
15
+
14
16
  from ._async import AsyncClient, AsyncProcess, AsyncVM
15
17
  from ._errors import (
16
18
  APIError,
@@ -33,6 +35,12 @@ from ._errors import (
33
35
  from ._sync import VM, Client, Process
34
36
  from ._wire import CommandResult, Logs
35
37
 
38
+ try:
39
+ __version__ = version("exedev")
40
+ except PackageNotFoundError: # Not installed, as in a source checkout.
41
+ __version__ = "0+unknown"
42
+ del PackageNotFoundError, version
43
+
36
44
  __all__ = [
37
45
  "APIError",
38
46
  "AsyncClient",
@@ -48,6 +48,7 @@ from ._errors import (
48
48
  from ._wire import (
49
49
  DEFAULT_BASE_URL,
50
50
  DOWNLOAD_SCRIPT,
51
+ FLUSH_SCRIPT,
51
52
  HEADERS,
52
53
  IS_DIRECTORY,
53
54
  KILL_SCRIPT,
@@ -146,6 +147,23 @@ class _AsyncTransport:
146
147
  await asyncio.sleep(retry_delay(response, attempt))
147
148
  attempt += 1
148
149
 
150
+ async def create(self, path: Literal["new", "cp"], args: Sequence[Arg], flags: Sequence[Flag]) -> VMInfo:
151
+ """Run new or cp: the VM it created. Interrupted (by cancellation, or
152
+ KeyboardInterrupt) before the response, it waits for the response
153
+ anyway, deletes the VM, and re-raises: no one else would know of it.
154
+ Interrupted again, it gives up."""
155
+ request = asyncio.ensure_future(self.call(path, args, flags, json=True))
156
+ try:
157
+ result = await asyncio.shield(request)
158
+ except Exception:
159
+ raise
160
+ except BaseException:
161
+ with contextlib.suppress(Exception):
162
+ info = vm_info(await request, path)
163
+ await self.documents("rm", [info.name])
164
+ raise
165
+ return vm_info(result, path)
166
+
149
167
  async def documents(
150
168
  self, path: str, args: Sequence[Arg] = (), flags: Sequence[Flag] = ()
151
169
  ) -> tuple[int, str, list[Any] | None]:
@@ -303,7 +321,7 @@ class AsyncVM:
303
321
 
304
322
  @property
305
323
  def created_at(self) -> datetime | None:
306
- """When the VM was created; None until listed (see refresh())."""
324
+ """When the VM was created; None if the server did not say (see refresh())."""
307
325
  return self._info.created_at
308
326
 
309
327
  @property
@@ -678,7 +696,7 @@ class AsyncVM:
678
696
  async def _flush(self) -> None:
679
697
  """Flush the VM's recent writes to its disk, if it is running. Best effort."""
680
698
  with contextlib.suppress(ExeError):
681
- await self._t.ssh(self.name, "sync", capture=False, timeout=60)
699
+ await self._t.ssh(self.name, sh(FLUSH_SCRIPT), capture=False, timeout=60)
682
700
 
683
701
  async def delete(self) -> None:
684
702
  """Delete the VM. A VM that does not exist raises NotFoundError.
@@ -692,7 +710,13 @@ class AsyncVM:
692
710
  if summary["failed"] or len(summary["deleted"]) != 1:
693
711
  raise api_error("rm", 404 if summary.get("not_found") else 422, body)
694
712
 
695
- async def restart(self, *, wait_until: WaitUntil = "ssh", timeout: float | None = None) -> t.RestartResponse:
713
+ async def restart(
714
+ self,
715
+ *,
716
+ flush: bool = True,
717
+ wait_until: WaitUntil = "ssh",
718
+ timeout: float | None = None,
719
+ ) -> t.RestartResponse:
696
720
  """Restart a VM.
697
721
 
698
722
  CLI: ``restart <vmname>``
@@ -700,6 +724,9 @@ class AsyncVM:
700
724
  Tag-scoped API keys may run this command.
701
725
 
702
726
  Args:
727
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
728
+ ssh permission, and a running VM), so that it still has them after the
729
+ restart.
703
730
  wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
704
731
  also waits for its setup script to finish, and succeed; "created"
705
732
  returns at once. Waiting needs ssh permission, and raises VMReadyError
@@ -707,17 +734,26 @@ class AsyncVM:
707
734
  timeout: seconds to wait for readiness; by default 60, or 600 for "setup".
708
735
  """
709
736
  check_ready(wait_until, timeout)
737
+ if flush:
738
+ await self._flush()
710
739
  result: t.RestartResponse = await self._t.call("restart", [self.name], json=True)
711
740
  await self._ready(wait_until, timeout)
712
741
  return result
713
742
 
714
- async def pause(self) -> t.PauseResponse:
743
+ async def pause(self, *, flush: bool = True) -> t.PauseResponse:
715
744
  """Pause a VM (snapshot RAM to disk, free its CPU and memory).
716
745
 
717
746
  CLI: ``pause <vmname>``
718
747
 
719
748
  Tag-scoped API keys may run this command.
749
+
750
+ Args:
751
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
752
+ ssh permission, and a running VM), so that copies of the paused VM have
753
+ them.
720
754
  """
755
+ if flush:
756
+ await self._flush()
721
757
  result: t.PauseResponse = await self._t.call("pause", [self.name], json=True)
722
758
  self._absorb(result)
723
759
  return result
@@ -812,8 +848,8 @@ class AsyncVM:
812
848
  pool: create the copy in one of your team's pools (see ``exe.pool.list()``)
813
849
  standalone: create the copy as a standalone VM with its own reserved
814
850
  capacity (requires a plan with standalone VMs and team approval)
815
- flush: first flush the VM's recent writes to its disk, so that the copy has
816
- them. Best effort: it needs ssh permission, and a running VM.
851
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
852
+ ssh permission, and a running VM), so that the copy has them.
817
853
  wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
818
854
  also waits for its setup script to finish, and succeed; "created"
819
855
  returns at once. Waiting needs ssh permission, and raises VMReadyError
@@ -826,7 +862,7 @@ class AsyncVM:
826
862
  check_ready(wait_until, timeout)
827
863
  if flush:
828
864
  await self._flush()
829
- result = await self._t.call(
865
+ result = await self._t.create(
830
866
  "cp",
831
867
  [self.name, name],
832
868
  [
@@ -837,9 +873,8 @@ class AsyncVM:
837
873
  ("pool", "string", pool),
838
874
  ("standalone", "bool", standalone or None),
839
875
  ],
840
- json=True,
841
876
  )
842
- vm = AsyncVM(self._t, vm_info(result, "cp"), owned=True)
877
+ vm = AsyncVM(self._t, result, owned=True)
843
878
  return await vm._created(wait_until, timeout, keep_on_failure)
844
879
 
845
880
  async def resize(
@@ -940,7 +975,8 @@ class AsyncProcess:
940
975
 
941
976
  @property
942
977
  def pid(self) -> int:
943
- """Its process ID on the VM, which is also its process group's."""
978
+ """Its process ID on the VM, which is also its process group's; 0 if
979
+ that is unknown, as it can be for a lost process."""
944
980
  return self._state.pid
945
981
 
946
982
  @property
@@ -1185,7 +1221,7 @@ class AsyncClient:
1185
1221
  is interrupted.
1186
1222
  """
1187
1223
  check_ready(wait_until, timeout)
1188
- result = await self._t.call(
1224
+ result = await self._t.create(
1189
1225
  "new",
1190
1226
  [],
1191
1227
  [
@@ -1206,9 +1242,8 @@ class AsyncClient:
1206
1242
  ("tag", "repeated", tags),
1207
1243
  ("no-email", "bool", None if email else True),
1208
1244
  ],
1209
- json=True,
1210
1245
  )
1211
- vm = AsyncVM(self._t, vm_info(result, "new"), owned=True)
1246
+ vm = AsyncVM(self._t, result, owned=True)
1212
1247
  return await vm._created(wait_until, timeout, keep_on_failure)
1213
1248
 
1214
1249
  async def whoami(self) -> t.WhoamiResponse:
@@ -16,7 +16,7 @@ import signal
16
16
  import stat
17
17
  import time
18
18
  from collections.abc import Callable, Mapping, Sequence
19
- from concurrent.futures import ThreadPoolExecutor
19
+ from concurrent.futures import Future, ThreadPoolExecutor
20
20
  from datetime import datetime
21
21
  from pathlib import Path, PurePosixPath
22
22
  from time import monotonic
@@ -49,6 +49,7 @@ from ._errors import (
49
49
  from ._wire import (
50
50
  DEFAULT_BASE_URL,
51
51
  DOWNLOAD_SCRIPT,
52
+ FLUSH_SCRIPT,
52
53
  HEADERS,
53
54
  IS_DIRECTORY,
54
55
  KILL_SCRIPT,
@@ -95,6 +96,7 @@ from ._wire import (
95
96
  remote_path,
96
97
  required,
97
98
  retry_delay,
99
+ in_thread,
98
100
  rm_result,
99
101
  setup_state,
100
102
  sh,
@@ -146,6 +148,26 @@ class _Transport:
146
148
  time.sleep(retry_delay(response, attempt))
147
149
  attempt += 1
148
150
 
151
+ def create(self, path: Literal["new", "cp"], args: Sequence[Arg], flags: Sequence[Flag]) -> VMInfo:
152
+ """Run new or cp: the VM it created. Interrupted (by cancellation, or
153
+ KeyboardInterrupt) before the response, it waits for the response
154
+ anyway, deletes the VM, and re-raises: no one else would know of it.
155
+ Interrupted again, it gives up."""
156
+ request: Future[Any] = Future()
157
+ try:
158
+ in_thread(request, lambda: self.call(path, args, flags, json=True))
159
+ result = request.result()
160
+ except Exception:
161
+ raise
162
+ except BaseException:
163
+ if request.cancel(): # It never started.
164
+ raise
165
+ with contextlib.suppress(Exception):
166
+ info = vm_info(request.result(), path)
167
+ self.documents("rm", [info.name])
168
+ raise
169
+ return vm_info(result, path)
170
+
149
171
  def documents(
150
172
  self, path: str, args: Sequence[Arg] = (), flags: Sequence[Flag] = ()
151
173
  ) -> tuple[int, str, list[Any] | None]:
@@ -303,7 +325,7 @@ class VM:
303
325
 
304
326
  @property
305
327
  def created_at(self) -> datetime | None:
306
- """When the VM was created; None until listed (see refresh())."""
328
+ """When the VM was created; None if the server did not say (see refresh())."""
307
329
  return self._info.created_at
308
330
 
309
331
  @property
@@ -674,7 +696,7 @@ class VM:
674
696
  def _flush(self) -> None:
675
697
  """Flush the VM's recent writes to its disk, if it is running. Best effort."""
676
698
  with contextlib.suppress(ExeError):
677
- self._t.ssh(self.name, "sync", capture=False, timeout=60)
699
+ self._t.ssh(self.name, sh(FLUSH_SCRIPT), capture=False, timeout=60)
678
700
 
679
701
  def delete(self) -> None:
680
702
  """Delete the VM. A VM that does not exist raises NotFoundError.
@@ -688,7 +710,13 @@ class VM:
688
710
  if summary["failed"] or len(summary["deleted"]) != 1:
689
711
  raise api_error("rm", 404 if summary.get("not_found") else 422, body)
690
712
 
691
- def restart(self, *, wait_until: WaitUntil = "ssh", timeout: float | None = None) -> t.RestartResponse:
713
+ def restart(
714
+ self,
715
+ *,
716
+ flush: bool = True,
717
+ wait_until: WaitUntil = "ssh",
718
+ timeout: float | None = None,
719
+ ) -> t.RestartResponse:
692
720
  """Restart a VM.
693
721
 
694
722
  CLI: ``restart <vmname>``
@@ -696,6 +724,9 @@ class VM:
696
724
  Tag-scoped API keys may run this command.
697
725
 
698
726
  Args:
727
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
728
+ ssh permission, and a running VM), so that it still has them after the
729
+ restart.
699
730
  wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
700
731
  also waits for its setup script to finish, and succeed; "created"
701
732
  returns at once. Waiting needs ssh permission, and raises VMReadyError
@@ -703,17 +734,26 @@ class VM:
703
734
  timeout: seconds to wait for readiness; by default 60, or 600 for "setup".
704
735
  """
705
736
  check_ready(wait_until, timeout)
737
+ if flush:
738
+ self._flush()
706
739
  result: t.RestartResponse = self._t.call("restart", [self.name], json=True)
707
740
  self._ready(wait_until, timeout)
708
741
  return result
709
742
 
710
- def pause(self) -> t.PauseResponse:
743
+ def pause(self, *, flush: bool = True) -> t.PauseResponse:
711
744
  """Pause a VM (snapshot RAM to disk, free its CPU and memory).
712
745
 
713
746
  CLI: ``pause <vmname>``
714
747
 
715
748
  Tag-scoped API keys may run this command.
749
+
750
+ Args:
751
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
752
+ ssh permission, and a running VM), so that copies of the paused VM have
753
+ them.
716
754
  """
755
+ if flush:
756
+ self._flush()
717
757
  result: t.PauseResponse = self._t.call("pause", [self.name], json=True)
718
758
  self._absorb(result)
719
759
  return result
@@ -807,8 +847,8 @@ class VM:
807
847
  pool: create the copy in one of your team's pools (see ``exe.pool.list()``)
808
848
  standalone: create the copy as a standalone VM with its own reserved
809
849
  capacity (requires a plan with standalone VMs and team approval)
810
- flush: first flush the VM's recent writes to its disk, so that the copy has
811
- them. Best effort: it needs ssh permission, and a running VM.
850
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
851
+ ssh permission, and a running VM), so that the copy has them.
812
852
  wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
813
853
  also waits for its setup script to finish, and succeed; "created"
814
854
  returns at once. Waiting needs ssh permission, and raises VMReadyError
@@ -821,7 +861,7 @@ class VM:
821
861
  check_ready(wait_until, timeout)
822
862
  if flush:
823
863
  self._flush()
824
- result = self._t.call(
864
+ result = self._t.create(
825
865
  "cp",
826
866
  [self.name, name],
827
867
  [
@@ -832,9 +872,8 @@ class VM:
832
872
  ("pool", "string", pool),
833
873
  ("standalone", "bool", standalone or None),
834
874
  ],
835
- json=True,
836
875
  )
837
- vm = VM(self._t, vm_info(result, "cp"), owned=True)
876
+ vm = VM(self._t, result, owned=True)
838
877
  return vm._created(wait_until, timeout, keep_on_failure)
839
878
 
840
879
  def resize(
@@ -935,7 +974,8 @@ class Process:
935
974
 
936
975
  @property
937
976
  def pid(self) -> int:
938
- """Its process ID on the VM, which is also its process group's."""
977
+ """Its process ID on the VM, which is also its process group's; 0 if
978
+ that is unknown, as it can be for a lost process."""
939
979
  return self._state.pid
940
980
 
941
981
  @property
@@ -1179,7 +1219,7 @@ class Client:
1179
1219
  is interrupted.
1180
1220
  """
1181
1221
  check_ready(wait_until, timeout)
1182
- result = self._t.call(
1222
+ result = self._t.create(
1183
1223
  "new",
1184
1224
  [],
1185
1225
  [
@@ -1200,9 +1240,8 @@ class Client:
1200
1240
  ("tag", "repeated", tags),
1201
1241
  ("no-email", "bool", None if email else True),
1202
1242
  ],
1203
- json=True,
1204
1243
  )
1205
- vm = VM(self._t, vm_info(result, "new"), owned=True)
1244
+ vm = VM(self._t, result, owned=True)
1206
1245
  return vm._created(wait_until, timeout, keep_on_failure)
1207
1246
 
1208
1247
  def whoami(self) -> t.WhoamiResponse:
@@ -20,7 +20,9 @@ import shlex
20
20
  import signal
21
21
  import sys
22
22
  import tarfile
23
+ import threading
23
24
  from collections.abc import Awaitable, Callable, Coroutine, Generator, Iterable, Mapping, Sequence
25
+ from concurrent.futures import Future
24
26
  from contextlib import AbstractAsyncContextManager
25
27
  from dataclasses import dataclass
26
28
  from datetime import datetime
@@ -429,7 +431,8 @@ def _string_map(v: object) -> bool:
429
431
  RETRYABLE = re.compile(r"failed to (?:connect|dial|create session|run command on VM)", re.IGNORECASE)
430
432
 
431
433
  # Report exe-setup.service's state, whether a setup script is in place, and
432
- # on failure the end of its journal. exe-init puts /exe.dev/setup in place
434
+ # on failure the end of the script's output (its unit's journal also holds
435
+ # systemd's messages, and sudo's). exe-init puts /exe.dev/setup in place
433
436
  # before exessh answers, and the unit removes it once it has run. exessh can
434
437
  # answer before exe-init hands PID 1 to systemd, and then before systemd's
435
438
  # bus is up ("Failed to connect to bus"): both are "booting".
@@ -446,7 +449,7 @@ echo "$props"
446
449
  echo "SystemState=$(systemctl is-system-running 2>/dev/null)"
447
450
  if [ "$(systemctl show exe-setup.service -p ActiveState --value)" = failed ]; then
448
451
  echo ---
449
- journalctl -b -u exe-setup.service -o cat --no-pager -n 50 2>&1
452
+ journalctl -b _SYSTEMD_UNIT=exe-setup.service _TRANSPORT=stdout -o cat --no-pager -n 50 2>&1
450
453
  fi"""
451
454
 
452
455
 
@@ -579,6 +582,24 @@ def creates(method: Callable[_P, Coroutine[Any, Any, _CM]]) -> Callable[_P, Crea
579
582
  # reading the command: a retry cannot run anything twice.
580
583
 
581
584
 
585
+ _T = TypeVar("_T")
586
+
587
+
588
+ def in_thread(future: Future[_T], fn: Callable[[], _T]) -> None:
589
+ """Call fn in a thread of its own, which a KeyboardInterrupt does not
590
+ stop, and resolve future with it; unless future is cancelled first."""
591
+
592
+ def run() -> None:
593
+ if not future.set_running_or_notify_cancel():
594
+ return
595
+ try:
596
+ future.set_result(fn())
597
+ except BaseException as err: # noqa: BLE001 -- the caller gets it
598
+ future.set_exception(err)
599
+
600
+ threading.Thread(target=run, daemon=True).start()
601
+
602
+
582
603
  def retry_delay(response: httpx.Response, attempt: int) -> float:
583
604
  """Seconds to wait before retrying a 429: Retry-After, or exponential backoff with jitter."""
584
605
  try:
@@ -614,21 +635,26 @@ def fits(vm: str, command: str) -> bool:
614
635
  #
615
636
  # The VM kills the process it started for the session: this script, or a
616
637
  # login shell that runs it. The watchdog notices either, as this script
617
- # ending or its parent changing.
638
+ # ending or its parent changing. It checks four times a second, with shell
639
+ # builtins, so that its one process per check is sleep.
618
640
  RUN_SCRIPT = """\
619
641
  s=${SHELL:-/bin/sh}
620
642
  command -v setsid >/dev/null 2>&1 || exec "$s" -lc "$1"
621
643
  setsid "$s" -lc "$1" &
622
644
  p=$!
623
- parent() { st=$(cat /proc/$$/stat 2>/dev/null) && st=${st##*) } && set -- $st && echo $2; }
624
- pp=$(parent)
625
- (while [ "$(parent)" = "$pp" ]; do sleep 1; done; kill -KILL -$p) >/dev/null 2>&1 &
645
+ parent() { read -r st </proc/$$/stat && st=${st##*) } && set -- $st && pp=$2; }
646
+ parent 2>/dev/null; p0=$pp
647
+ (while parent && [ "$pp" = "$p0" ]; do sleep 0.25 || sleep 1; done; kill -KILL -$p) >/dev/null 2>&1 &
626
648
  w=$!
627
649
  wait $p
628
650
  c=$?
629
651
  kill $w 2>/dev/null
630
652
  exit $c"""
631
653
 
654
+ # Flushes the VM's recent writes to its disk. Only its disk: a plain sync
655
+ # also waits on network and FUSE mounts, which can hang.
656
+ FLUSH_SCRIPT = "sync -f / 2>/dev/null || sync"
657
+
632
658
  # A command line too long for one request is uploaded first, then run as
633
659
  # this: the script reads and deletes the file, then runs what it read.
634
660
  UPLOADED_COMMAND = 'c=$(cat {path}) && rm -f {path} && eval "$c"'
@@ -762,20 +788,28 @@ def process_name(name: object) -> str:
762
788
 
763
789
  _PROCESSES = """\
764
790
  base=${XDG_STATE_HOME:-$HOME/.local/state}/exedev/processes
791
+ # Sets n to the number in file $1, or to "" if it is missing, empty, or
792
+ # garbled, as a VM that stopped before writing it out can leave it.
793
+ num() { { n=$(cat "$1"); } 2>/dev/null; case $n in ''|*[!0-9]*) n=;; esac; }
765
794
  # Prints the process in directory $1 as "PID running", "PID exited STATUS",
766
- # or "PID lost"; fails if there is none.
795
+ # or "PID lost", where PID is 0 if unknown; fails if there is none, or it is
796
+ # still starting.
767
797
  state() {
768
- p=$(cat "$1/pid" 2>/dev/null) || return
769
- if [ -f "$1/exit" ]; then echo "$p exited $(cat "$1/exit")"; return; fi
770
- if [ "$(cat "$1/boot" 2>/dev/null)" = "$(cat /proc/sys/kernel/random/boot_id 2>/dev/null)" ] &&
771
- kill -0 "$(cat "$1/monitor" 2>/dev/null)" 2>/dev/null; then echo "$p running"; return; fi
772
- if [ -f "$1/exit" ]; then echo "$p exited $(cat "$1/exit")"; return; fi
798
+ [ -d "$1" ] || return
799
+ num "$1/pid"; p=${n:-0}
800
+ num "$1/exit"; if [ -n "$n" ]; then echo "$p exited $n"; return; fi
801
+ if [ "$(cat "$1/boot" 2>/dev/null)" = "$(cat /proc/sys/kernel/random/boot_id 2>/dev/null)" ]; then
802
+ [ "$p" != 0 ] || return
803
+ if kill -0 "$(cat "$1/monitor" 2>/dev/null)" 2>/dev/null; then echo "$p running"; return; fi
804
+ num "$1/exit"; if [ -n "$n" ]; then echo "$p exited $n"; return; fi
805
+ fi
773
806
  echo "$p lost"
774
807
  }
775
808
  """
776
809
 
777
810
  # $1 name, $2 command line. Prints the pid; exits 3 if the name is taken
778
- # by a running process.
811
+ # by a running process. Records are synced to disk as they are completed,
812
+ # so that a VM that stops without flushing its disk still has them.
779
813
  SPAWN_SCRIPT = (
780
814
  _PROCESSES
781
815
  + """\
@@ -788,9 +822,10 @@ setsid sh -c 'echo $$ > "$1/monitor"
788
822
  setsid "${SHELL:-/bin/sh}" -lc "$2" < /dev/null > "$1/stdout" 2> "$1/stderr" &
789
823
  echo $! > "$1/pid.new" && mv "$1/pid.new" "$1/pid"
790
824
  wait $!
791
- echo $? > "$1/exit.new" && mv "$1/exit.new" "$1/exit"' sh "$d" "$2" < /dev/null > /dev/null 2>&1 &
825
+ echo $? > "$1/exit.new" && mv "$1/exit.new" "$1/exit" && sync "$1/exit" "$1"' sh "$d" "$2" < /dev/null > /dev/null 2>&1 &
792
826
  i=0
793
827
  while [ ! -f "$d/pid" ] && [ $i -lt 100 ]; do sleep 0.05; i=$((i+1)); done
828
+ sync "$d/pid" "$d/boot" "$d/command" "$d/monitor" "$d" 2>/dev/null
794
829
  cat "$d/pid\""""
795
830
  )
796
831
 
@@ -145,6 +145,8 @@ class NewResponse(TypedDict):
145
145
  xterm_url: NotRequired[str]
146
146
  comment: NotRequired[str]
147
147
  """The ``comment`` the VM was created with; absent when there is none."""
148
+ created_at: str
149
+ """When the VM was created, as in `ls`."""
148
150
  pool_id: NotRequired[str]
149
151
  standalone: NotRequired[bool]
150
152
  error: NotRequired[str]
@@ -167,6 +169,10 @@ class CpResponse(TypedDict):
167
169
  https_url: str
168
170
  tags: list[str]
169
171
  """The copy's tags: the source's, unless ``copy_tags=False``."""
172
+ comment: NotRequired[str]
173
+ """The copy's comment, which is the source's; absent when there is none."""
174
+ created_at: NotRequired[str]
175
+ """When the copy was created, as in `ls`; absent if that is unknown."""
170
176
  elapsed: float
171
177
  """How long the copy took, in seconds."""
172
178
  pool_id: NotRequired[str]
@@ -110,7 +110,7 @@ def describe(command: str) -> str:
110
110
  prefix = shlex.join(["sh", "-c", script, "sh"])
111
111
  if inner == prefix or inner.startswith(prefix + " "):
112
112
  rest = inner[len(prefix) + 1 :]
113
- args = rest.split(" ") if re.fullmatch(r"[\w@%+=:,./ -]*", rest) else shlex.split(rest)
113
+ args = rest.split(" ") if re.fullmatch(r"[\w@%+=:,./ -]+", rest) else shlex.split(rest)
114
114
  return shlex.join(["ssh", match[1], name, *args])
115
115
  return command
116
116
 
@@ -3,6 +3,8 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import asyncio
6
+ import tomllib
7
+ from pathlib import Path
6
8
 
7
9
  import httpx
8
10
  import pytest
@@ -328,3 +330,8 @@ def test_async_client_closes_its_http_client():
328
330
  return exe._t._http
329
331
 
330
332
  assert asyncio.run(main()).is_closed
333
+
334
+
335
+ def test_version():
336
+ pyproject = tomllib.loads((Path(__file__).parent.parent / "pyproject.toml").read_text())
337
+ assert exedev.__version__ == pyproject["project"]["version"]
@@ -13,9 +13,12 @@ import asyncio
13
13
  import json
14
14
  import os
15
15
  import random
16
+ import signal
17
+ import threading
16
18
  import time
17
19
  from pathlib import Path
18
20
 
21
+ import httpx
19
22
  import pytest
20
23
 
21
24
  import exedev
@@ -41,7 +44,14 @@ def token() -> str | None:
41
44
 
42
45
 
43
46
  NAME = f"sdk-py-{int(time.time() * 1000):x}"
44
- NAMES = {"vm": NAME, "renamed": f"{NAME}-r", "copy": f"{NAME}-c", "setup": f"{NAME}-s", "missing": f"{NAME}-x"}
47
+ NAMES = {
48
+ "vm": NAME,
49
+ "renamed": f"{NAME}-r",
50
+ "copy": f"{NAME}-c",
51
+ "setup": f"{NAME}-s",
52
+ "missing": f"{NAME}-x",
53
+ "interrupted": f"{NAME}-i",
54
+ }
45
55
 
46
56
 
47
57
  @pytest.fixture(scope="module")
@@ -76,6 +86,7 @@ def test_new(vm):
76
86
  assert vm.name == NAME
77
87
  assert TAG in vm.tags
78
88
  assert vm.https_url and vm.https_url.startswith("https://")
89
+ assert vm.created_at is not None
79
90
 
80
91
 
81
92
  @skip_ssh
@@ -219,13 +230,25 @@ def test_vms_and_refresh(exe, vm):
219
230
 
220
231
 
221
232
  def test_copy(vm):
222
- with vm.copy(NAMES["copy"], **READY) as copy:
223
- assert copy.name == NAMES["copy"]
224
- assert TAG in copy.tags
225
- if SSH:
226
- assert copy.run("hostname", check=True).stdout.strip() == NAMES["copy"]
227
- with pytest.raises(exedev.NotFoundError):
228
- copy.refresh()
233
+ # A copy of a paused VM has its recent writes: pause() flushes them.
234
+ if SSH:
235
+ vm.write_file("recent.txt", "before pause\n")
236
+ vm.pause()
237
+ try:
238
+ with vm.copy(NAMES["copy"], **READY) as copy:
239
+ assert copy.name == NAMES["copy"]
240
+ assert TAG in copy.tags
241
+ assert copy.comment == "sdk integration test"
242
+ assert copy.created_at is not None
243
+ if SSH:
244
+ assert copy.run("hostname; cat recent.txt", check=True).stdout.split("\n")[:2] == [
245
+ NAMES["copy"],
246
+ "before pause",
247
+ ]
248
+ with pytest.raises(exedev.NotFoundError):
249
+ copy.refresh()
250
+ finally:
251
+ vm.resume(**READY)
229
252
 
230
253
 
231
254
  def test_stats_and_share(vm):
@@ -241,9 +264,14 @@ def test_account(exe):
241
264
 
242
265
 
243
266
  def test_restart(vm):
267
+ if SSH:
268
+ vm.write_file("recent.txt", "before restart\n")
269
+ sleeper = vm.spawn("sleep 600", name="sleeper")
244
270
  vm.restart(**READY)
245
271
  if SSH:
246
- assert vm.run("true").ok
272
+ assert vm.read_file("recent.txt") == b"before restart\n"
273
+ with pytest.raises(exedev.ProcessLostError):
274
+ sleeper.wait(timeout=30)
247
275
 
248
276
 
249
277
  def test_rename(exe, vm):
@@ -260,18 +288,34 @@ def test_rename(exe, vm):
260
288
 
261
289
  @skip_ssh
262
290
  def test_setup_failure(exe):
263
- script = "#!/bin/sh\necho setup-output-marker\necho 'back\\slash'\nexit 3"
291
+ script = "#!/bin/sh\nsudo true\necho setup-output-marker\necho 'back\\slash' >&2\nexit 3"
264
292
  with pytest.raises(exedev.VMSetupError) as info:
265
293
  exe.new(name=NAMES["setup"], setup_script=script, wait_until="setup")
266
294
  assert info.value.vm.name == NAMES["setup"]
267
295
  assert info.value.exit_code == 3
268
- assert "setup-output-marker" in info.value.output
269
- assert "back\\slash" in info.value.output
296
+ # The script's output, and only its output: not systemd's or sudo's.
297
+ assert info.value.output.splitlines() == ["setup-output-marker", "back\\slash"]
270
298
  # new() deleted the VM it could not hand over.
271
299
  with pytest.raises(exedev.NotFoundError):
272
300
  exe.vm(NAMES["setup"])
273
301
 
274
302
 
303
+ def test_interrupted_new(exe):
304
+ """Interrupted while the server creates it, new() still deletes the VM."""
305
+ main = threading.main_thread().ident
306
+ assert main is not None
307
+
308
+ def interrupt(request: httpx.Request) -> None:
309
+ if request.content.startswith(b"new "):
310
+ threading.Timer(0.3, signal.pthread_kill, (main, signal.SIGINT)).start()
311
+
312
+ http = httpx.Client(timeout=300, event_hooks={"request": [interrupt]})
313
+ with exedev.Client(token(), base_url=BASE_URL, http_client=http) as client, pytest.raises(KeyboardInterrupt):
314
+ client.new(name=NAMES["interrupted"], **READY)
315
+ with pytest.raises(exedev.NotFoundError):
316
+ exe.vm(NAMES["interrupted"])
317
+
318
+
275
319
  def test_delete(exe, vm):
276
320
  vm.delete()
277
321
  assert vm.name not in [v.name for v in exe.vms()]
@@ -104,3 +104,57 @@ def test_lost_processes(api, local):
104
104
  with pytest.raises(exedev.ProcessLostError):
105
105
  api(process.wait())
106
106
  os.killpg(process.pid, signal.SIGKILL)
107
+
108
+
109
+ @pytest.mark.parametrize(
110
+ "damage",
111
+ [
112
+ {},
113
+ {"pid": ""},
114
+ {"pid": None},
115
+ {"pid": "\x00\x00\x00\x00"},
116
+ {"boot": None, "pid": ""},
117
+ {"exit": ""},
118
+ {"exit": "\x00\x00"},
119
+ ],
120
+ )
121
+ def test_records_damaged_by_a_crash_are_lost(api, local, damage):
122
+ # A VM that stopped before writing a record out leaves files missing or
123
+ # empty. Such a process is lost, whatever its record lacks.
124
+ vm, machine, _ = local
125
+ api(api(vm.spawn("true", name="crashed")).wait())
126
+ record = machine.home / ".local/state/exedev/processes/crashed"
127
+ (record / "boot").write_text("another boot\n")
128
+ (record / "exit").unlink()
129
+ for name, content in damage.items():
130
+ if content is None:
131
+ (record / name).unlink()
132
+ else:
133
+ (record / name).write_text(content)
134
+ process = api(vm.process("crashed"))
135
+ assert process.exit_code is None
136
+ assert "lost" in repr(process)
137
+ with pytest.raises(exedev.ProcessLostError):
138
+ api(process.poll())
139
+ with pytest.raises(exedev.ProcessLostError):
140
+ api(process.wait())
141
+ assert [p.name for p in api(vm.processes())] == ["crashed"]
142
+
143
+
144
+ def test_an_exit_status_outlives_a_damaged_pid(api, local):
145
+ vm, machine, _ = local
146
+ api(api(vm.spawn("exit 4", name="crashed")).wait())
147
+ record = machine.home / ".local/state/exedev/processes/crashed"
148
+ (record / "boot").write_text("another boot\n")
149
+ (record / "pid").write_text("")
150
+ process = api(vm.process("crashed"))
151
+ assert (process.pid, process.exit_code) == (0, 4)
152
+ assert api(process.wait()).exit_code == 4
153
+
154
+
155
+ def test_spawn_writes_its_records_out(api, local):
156
+ # So that they survive the VM stopping without flushing its disk.
157
+ vm, _, server = local
158
+ api(vm.spawn("true", name="durable"))
159
+ script = next(r for r in server.raw if "durable" in r)
160
+ assert 'sync "$d/pid"' in script
@@ -52,7 +52,8 @@ def test_run_script_stops_everything_when_the_session_ends(tmp_path, login_shell
52
52
  assert not gone(pgid, 0.2)
53
53
  session.kill()
54
54
  session.wait()
55
- assert gone(pgid)
55
+ # Promptly: a run() timeout should not run on for long.
56
+ assert gone(pgid, 0.7)
56
57
  finally:
57
58
  try:
58
59
  os.killpg(pgid, signal.SIGKILL)
@@ -4,6 +4,9 @@ from __future__ import annotations
4
4
 
5
5
  import asyncio
6
6
  import shlex
7
+ import signal
8
+ import threading
9
+ import time
7
10
 
8
11
  import httpx
9
12
  import pytest
@@ -174,6 +177,74 @@ def test_new_deletes_the_vm_when_cancelled():
174
177
  assert commands == ["new --no-email", "ssh worker true", "rm worker"]
175
178
 
176
179
 
180
+ def interrupting(first: str, interrupts: int = 1):
181
+ """A handler for which a Ctrl-C arrives while the server runs first,
182
+ which creates the VM: it is done, but the response is yet to come."""
183
+ commands = []
184
+ main = threading.main_thread().ident
185
+ assert main is not None
186
+
187
+ def handle(request):
188
+ commands.append(request.content.decode())
189
+ if commands[-1] == first:
190
+ for _ in range(interrupts):
191
+ signal.pthread_kill(main, signal.SIGINT)
192
+ time.sleep(0.05)
193
+ if commands[-1].startswith("rm "):
194
+ return httpx.Response(200, json={"deleted": [commands[-1][3:]], "failed": []})
195
+ return httpx.Response(200, json=CP if first.startswith("cp ") else NEW)
196
+
197
+ return commands, handle
198
+
199
+
200
+ def test_new_deletes_the_vm_when_interrupted_during_creation():
201
+ commands, handle = interrupting("new --no-email")
202
+ exe = exedev.Client("tok", http_client=httpx.Client(transport=httpx.MockTransport(handle)))
203
+ with pytest.raises(KeyboardInterrupt):
204
+ exe.new()
205
+ assert commands == ["new --no-email", "rm worker"]
206
+
207
+
208
+ def test_copy_deletes_the_vm_when_interrupted_during_creation():
209
+ commands, handle = interrupting("cp worker")
210
+ exe = exedev.Client("tok", http_client=httpx.Client(transport=httpx.MockTransport(handle)))
211
+ vm = exedev.VM(exe._t, exedev._wire.vm_info(NEW, "new"))
212
+ with pytest.raises(KeyboardInterrupt):
213
+ vm.copy(flush=False)
214
+ assert commands == ["cp worker", "rm copy"]
215
+
216
+
217
+ def test_a_second_interrupt_abandons_the_vm():
218
+ commands, handle = interrupting("new --no-email", interrupts=2)
219
+ exe = exedev.Client("tok", http_client=httpx.Client(transport=httpx.MockTransport(handle)))
220
+ with pytest.raises(KeyboardInterrupt):
221
+ exe.new()
222
+ time.sleep(0.2)
223
+ assert commands == ["new --no-email"]
224
+
225
+
226
+ def test_new_deletes_the_vm_when_cancelled_during_creation():
227
+ commands = []
228
+
229
+ async def handle(request):
230
+ commands.append(request.content.decode())
231
+ if commands[-1] == "new --no-email":
232
+ await asyncio.sleep(0.05)
233
+ return httpx.Response(200, json=RM if commands[-1] == "rm worker" else NEW)
234
+
235
+ async def main():
236
+ exe = exedev.AsyncClient("tok", http_client=httpx.AsyncClient(transport=httpx.MockTransport(handle)))
237
+ task = asyncio.create_task(exe.new())
238
+ while not commands:
239
+ await asyncio.sleep(0.001)
240
+ task.cancel()
241
+ with pytest.raises(asyncio.CancelledError):
242
+ await task
243
+
244
+ asyncio.run(main())
245
+ assert commands == ["new --no-email", "rm worker"]
246
+
247
+
177
248
  def test_readiness_without_ssh_permission_fails_fast(api, clock):
178
249
  exe, server = api.client({"new --no-email": NEW, "ssh worker true": error(403, "forbidden"), "rm worker": RM})
179
250
  with pytest.raises(exedev.VMReadyError, match='use wait_until="created"'):
@@ -311,10 +382,10 @@ def test_only_new_vms_are_context_managers(api):
311
382
 
312
383
 
313
384
  def test_copy(api, clock):
314
- _, vm, server = api.vm({"ssh worker sync": ran(), "cp --cpu=4 worker copy": CP, "ssh copy true": ran()})
385
+ _, vm, server = api.vm({"ssh worker flush": ran(), "cp --cpu=4 worker copy": CP, "ssh copy true": ran()})
315
386
  copy = api(vm.copy("copy", cpu=4))
316
387
  # It flushes the VM's writes to disk first, so that the copy has them.
317
- assert server.commands == ["ssh worker sync", "cp --cpu=4 worker copy", "ssh copy true"]
388
+ assert server.commands == ["ssh worker flush", "cp --cpu=4 worker copy", "ssh copy true"]
318
389
  assert (copy.name, copy.ssh_dest, copy.https_url, copy.status, copy.tags) == (
319
390
  "copy",
320
391
  "copy.exe.xyz",
@@ -331,9 +402,9 @@ def test_copy_without_tags(api):
331
402
 
332
403
 
333
404
  def test_copy_flush_is_best_effort(api, clock):
334
- _, vm, server = api.vm({"ssh worker sync": error(403, "no ssh"), "cp worker": CP})
405
+ _, vm, server = api.vm({"ssh worker flush": error(403, "no ssh"), "cp worker": CP})
335
406
  api(vm.copy(wait_until="created"))
336
- assert server.commands == ["ssh worker sync", "cp worker"]
407
+ assert server.commands == ["ssh worker flush", "cp worker"]
337
408
 
338
409
 
339
410
  def test_delete(api):
@@ -392,6 +463,7 @@ def test_lifecycle(api, clock):
392
463
  "resume worker": {"vm_name": "worker", "status": "running", "cold_booted": "false"},
393
464
  "restart worker": {"status": "restarted", "vm_name": "worker"},
394
465
  "ssh worker true": [NOT_READY, ran()],
466
+ "ssh worker flush": ran(),
395
467
  }
396
468
  )
397
469
  api(vm.pause())
@@ -399,18 +471,32 @@ def test_lifecycle(api, clock):
399
471
  assert api(vm.resume())["cold_booted"] == "false"
400
472
  assert vm.status == "running"
401
473
  api(vm.restart(wait_until="created"))
402
- api(vm.restart())
474
+ api(vm.restart(flush=False))
475
+ api(vm.pause(flush=False))
403
476
  assert server.commands == [
477
+ # Recent writes reach the disk before a pause, so copies of the
478
+ # paused VM have them, and before a restart, which loses the rest.
479
+ "ssh worker flush",
404
480
  "pause worker",
405
481
  "resume worker",
406
482
  "ssh worker true",
407
483
  "ssh worker true",
484
+ "ssh worker flush",
408
485
  "restart worker",
409
486
  "restart worker",
410
487
  "ssh worker true",
488
+ "pause worker",
411
489
  ]
412
490
 
413
491
 
492
+ def test_flushing_is_best_effort(api):
493
+ _, vm, server = api.vm(
494
+ {"ssh worker flush": error(403, "no ssh"), "pause worker": {"vm_name": "worker", "status": "paused"}}
495
+ )
496
+ api(vm.pause())
497
+ assert server.commands == ["ssh worker flush", "pause worker"]
498
+
499
+
414
500
  def test_tags_and_comment(api):
415
501
  exe, _server = api.client(
416
502
  {
@@ -457,7 +543,8 @@ def test_resize_and_restart(api, clock):
457
543
  "resize --memory=8G worker": {"vm_name": "worker", "memory": "8G"},
458
544
  "restart worker": {"status": "restarted", "vm_name": "worker"},
459
545
  "ssh worker true": ran(),
546
+ "ssh worker flush": ran(),
460
547
  }
461
548
  )
462
549
  api(vm.resize(memory="8G", restart=True))
463
- assert server.commands == ["resize --memory=8G worker", "restart worker", "ssh worker true"]
550
+ assert server.commands == ["resize --memory=8G worker", "ssh worker flush", "restart worker", "ssh worker true"]
@@ -103,7 +103,7 @@ wheels = [
103
103
 
104
104
  [[package]]
105
105
  name = "exedev"
106
- version = "0.2.0"
106
+ version = "0.3.0"
107
107
  source = { editable = "." }
108
108
  dependencies = [
109
109
  { name = "httpx" },
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes