testflows.machine 0.1.2__tar.gz → 0.1.3__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.
Potentially problematic release.
This version of testflows.machine might be problematic. Click here for more details.
- {testflows_machine-0.1.2/testflows.machine.egg-info → testflows_machine-0.1.3}/PKG-INFO +1 -1
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/__init__.py +3 -1
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_requires.py +11 -1
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_service.py +18 -2
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_version.py +1 -1
- testflows_machine-0.1.3/testflows/machine/v1/_warn.py +38 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/client.py +160 -7
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/errors.py +4 -3
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/sessions.py +128 -4
- {testflows_machine-0.1.2 → testflows_machine-0.1.3/testflows.machine.egg-info}/PKG-INFO +1 -1
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows.machine.egg-info/SOURCES.txt +1 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/LICENSE +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/NOTICE +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/README.md +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/pyproject.toml +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/setup.cfg +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_args.py +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_when.py +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/disks.py +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/login.py +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/ping.py +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/results.py +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/runs.py +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows.machine.egg-info/dependency_links.txt +0 -0
- {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows.machine.egg-info/top_level.txt +0 -0
|
@@ -153,7 +153,7 @@ from .runs import (
|
|
|
153
153
|
Task,
|
|
154
154
|
Vtime,
|
|
155
155
|
)
|
|
156
|
-
from .sessions import Session, Sessions
|
|
156
|
+
from .sessions import Session, SessionClosing, SessionMovedBack, Sessions
|
|
157
157
|
|
|
158
158
|
__all__ = [
|
|
159
159
|
"AlreadyExists",
|
|
@@ -255,6 +255,8 @@ __all__ = [
|
|
|
255
255
|
"Runs",
|
|
256
256
|
"ServiceUnavailable",
|
|
257
257
|
"Session",
|
|
258
|
+
"SessionClosing",
|
|
259
|
+
"SessionMovedBack",
|
|
258
260
|
"Sessions",
|
|
259
261
|
"State",
|
|
260
262
|
"Storage",
|
|
@@ -32,6 +32,9 @@ import testflows.machine
|
|
|
32
32
|
|
|
33
33
|
#: The core interface versions this SDK works with.
|
|
34
34
|
CORE_API_VERSIONS = range(1, 2)
|
|
35
|
+
#: The least revision of that interface this SDK needs. A core from before
|
|
36
|
+
#: revisions has none and counts as 1.
|
|
37
|
+
CORE_API_REVISION = 2
|
|
35
38
|
|
|
36
39
|
#: The name the core is loaded under, and the file it ships as.
|
|
37
40
|
CORE_MODULE = "testflows.machine._core"
|
|
@@ -93,7 +96,8 @@ def _core() -> ModuleType:
|
|
|
93
96
|
)
|
|
94
97
|
|
|
95
98
|
|
|
96
|
-
|
|
99
|
+
_loaded = _core()
|
|
100
|
+
_found = getattr(_loaded, "API_VERSION", None)
|
|
97
101
|
if _found not in CORE_API_VERSIONS:
|
|
98
102
|
raise ImportError(
|
|
99
103
|
f"The TestFlows™ Machine SDK Core has interface version {_found};"
|
|
@@ -101,3 +105,9 @@ if _found not in CORE_API_VERSIONS:
|
|
|
101
105
|
f" {CORE_API_VERSIONS.stop - 1}."
|
|
102
106
|
f" Update it with the TestFlows™ Machine client {_INSTALLER}"
|
|
103
107
|
)
|
|
108
|
+
_revision = getattr(_loaded, "API_REVISION", 1)
|
|
109
|
+
if _revision < CORE_API_REVISION:
|
|
110
|
+
raise ImportError(
|
|
111
|
+
"The TestFlows™ Machine SDK Core is older than this SDK."
|
|
112
|
+
f" Update it with the TestFlows™ Machine client {_INSTALLER}"
|
|
113
|
+
)
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
from __future__ import annotations
|
|
17
17
|
|
|
18
18
|
import contextlib
|
|
19
|
+
import logging
|
|
19
20
|
from pathlib import Path
|
|
20
21
|
from typing import Any, Callable, Generator, Optional
|
|
21
22
|
|
|
@@ -27,6 +28,10 @@ from testflows.machine._core import tunnel
|
|
|
27
28
|
|
|
28
29
|
from .errors import NotFound, ServiceUnavailable, _translated
|
|
29
30
|
|
|
31
|
+
#: Where the SDK says what a call waits on, such as a session moving to
|
|
32
|
+
#: another host. At INFO: the call goes on by itself.
|
|
33
|
+
_log = logging.getLogger("testflows.machine")
|
|
34
|
+
|
|
30
35
|
|
|
31
36
|
class _Service:
|
|
32
37
|
"""One session's service: where its socket is and how disks are named.
|
|
@@ -43,11 +48,15 @@ class _Service:
|
|
|
43
48
|
disks: Optional[Callable[[], list[dict[str, Any]]]],
|
|
44
49
|
label: str,
|
|
45
50
|
renew: Optional[Callable[[], None]] = None,
|
|
51
|
+
follow: Optional[Callable[[], Optional[Path]]] = None,
|
|
46
52
|
) -> None:
|
|
47
53
|
self.socket = socket
|
|
48
54
|
self.disks = disks
|
|
49
55
|
self.label = label
|
|
50
56
|
self.renew = renew
|
|
57
|
+
#: Follows the session when it moved, `sessions migrate`, and gives the
|
|
58
|
+
#: socket of where it went: a call that meets the move goes on there.
|
|
59
|
+
self.follow = follow
|
|
51
60
|
|
|
52
61
|
@contextlib.contextmanager
|
|
53
62
|
def client(self) -> Generator[ipc.Client, None, None]:
|
|
@@ -58,7 +67,9 @@ class _Service:
|
|
|
58
67
|
raise ServiceUnavailable(f"The {self.label} is not running.")
|
|
59
68
|
if self.renew is not None:
|
|
60
69
|
self.renew()
|
|
61
|
-
client = ipc.Client(
|
|
70
|
+
client = ipc.Client(
|
|
71
|
+
socket_path=self.socket, follow=self.follow, notice=_log.info
|
|
72
|
+
)
|
|
62
73
|
try:
|
|
63
74
|
client.connect()
|
|
64
75
|
except OSError as exc:
|
|
@@ -86,7 +97,11 @@ def local() -> _Service:
|
|
|
86
97
|
|
|
87
98
|
|
|
88
99
|
def of_session(
|
|
89
|
-
client: api.client.Client,
|
|
100
|
+
client: api.client.Client,
|
|
101
|
+
creds: dict[str, Any],
|
|
102
|
+
session_id: str,
|
|
103
|
+
name: str,
|
|
104
|
+
follow: Optional[Callable[[], Optional[Path]]] = None,
|
|
90
105
|
) -> _Service:
|
|
91
106
|
"""A cloud session's service, through this machine's tunnel to it.
|
|
92
107
|
|
|
@@ -106,4 +121,5 @@ def of_session(
|
|
|
106
121
|
lambda: api.auth.authed(creds, client.disk_list),
|
|
107
122
|
f"service of session {name}",
|
|
108
123
|
renew,
|
|
124
|
+
follow,
|
|
109
125
|
)
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Copyright 2026 Katteli Inc.
|
|
2
|
+
#
|
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
# you may not use this file except in compliance with the License.
|
|
5
|
+
# You may obtain a copy of the License at
|
|
6
|
+
#
|
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
#
|
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
# See the License for the specific language governing permissions and
|
|
13
|
+
# limitations under the License.
|
|
14
|
+
"""Warnings attributed to the program's own call."""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import contextlib
|
|
19
|
+
import os
|
|
20
|
+
import sys
|
|
21
|
+
import types
|
|
22
|
+
import warnings
|
|
23
|
+
from typing import Optional
|
|
24
|
+
|
|
25
|
+
#: Frames a warning is never attributed to: the SDK's own, and contextlib's,
|
|
26
|
+
#: which a `with` on the SDK's connections passes through.
|
|
27
|
+
_SKIPPED = (os.path.dirname(__file__) + os.sep, contextlib.__file__)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def warn(message: str, category: type[Warning]) -> None:
|
|
31
|
+
"""Warn at the first frame outside the SDK: the program's call, however
|
|
32
|
+
many of the SDK's own calls lie between."""
|
|
33
|
+
level = 1
|
|
34
|
+
frame: Optional[types.FrameType] = sys._getframe(1)
|
|
35
|
+
while frame is not None and frame.f_code.co_filename.startswith(_SKIPPED):
|
|
36
|
+
frame = frame.f_back
|
|
37
|
+
level += 1
|
|
38
|
+
warnings.warn(message, category, stacklevel=level + 1)
|
|
@@ -24,9 +24,11 @@ from __future__ import annotations
|
|
|
24
24
|
import builtins
|
|
25
25
|
import contextlib
|
|
26
26
|
import dataclasses
|
|
27
|
+
from datetime import datetime, timezone
|
|
27
28
|
import time
|
|
28
29
|
import os
|
|
29
|
-
from
|
|
30
|
+
from pathlib import Path
|
|
31
|
+
from typing import Any, Callable, Generator, Literal, Optional, Sequence, overload
|
|
30
32
|
|
|
31
33
|
from testflows.machine._core import api
|
|
32
34
|
from testflows.machine._core import branches as _branches
|
|
@@ -38,19 +40,21 @@ from testflows.machine._core import parsers as _parsers
|
|
|
38
40
|
from testflows.machine._core import ping as _ping
|
|
39
41
|
from testflows.machine._core import storage_ops as _storage_ops
|
|
40
42
|
from testflows.machine._core import run_source as _run_source
|
|
43
|
+
from testflows.machine._core import sessions as _sessions
|
|
41
44
|
from testflows.machine._core import sorting as _sorting
|
|
42
45
|
from testflows.machine._core import wait as _wait
|
|
43
46
|
from testflows.machine._core import wire as _wire
|
|
44
47
|
|
|
45
48
|
from . import _args
|
|
46
49
|
from . import _service
|
|
50
|
+
from . import _warn
|
|
47
51
|
from . import _when
|
|
48
52
|
from . import results
|
|
49
53
|
from .errors import ApiError, InvalidArgument, ServiceUnavailable, _translated
|
|
50
54
|
from .disks import Disk, Disks
|
|
51
55
|
from .ping import Ping, _public
|
|
52
56
|
from .runs import Run
|
|
53
|
-
from .sessions import Session, Sessions
|
|
57
|
+
from .sessions import Session, SessionClosing, Sessions
|
|
54
58
|
|
|
55
59
|
#: Set to 1, a client given no session works with the service on this
|
|
56
60
|
#: machine.
|
|
@@ -62,6 +66,25 @@ _MEM_MODES = ("auto", "map", "lazy")
|
|
|
62
66
|
_CONSOLES = ("serial", "virtio")
|
|
63
67
|
_FRAMEBUFFERS = ("vnc", "gtk", "sdl", "none")
|
|
64
68
|
|
|
69
|
+
#: A notice's deadline as the client keys it, and as `Session.closing_at`
|
|
70
|
+
#: holds it when the service cannot be read: ISO 8601 in UTC.
|
|
71
|
+
_NOTICE_TIME = "%Y-%m-%dT%H:%M:%S"
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _deadline(value: str) -> datetime:
|
|
75
|
+
"""A deadline as the service or the record writes it, in UTC. One with no
|
|
76
|
+
offset is UTC already."""
|
|
77
|
+
at = datetime.fromisoformat(value)
|
|
78
|
+
if at.tzinfo is None:
|
|
79
|
+
return at.replace(tzinfo=timezone.utc)
|
|
80
|
+
return at.astimezone(timezone.utc)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _deadline_key(at: datetime) -> str:
|
|
84
|
+
"""How the client remembers a deadline it told."""
|
|
85
|
+
return at.astimezone(timezone.utc).strftime(_NOTICE_TIME)
|
|
86
|
+
|
|
87
|
+
|
|
65
88
|
#: `runs --parents`: where a run reads its data parents from.
|
|
66
89
|
_PARENTS = ("local", "remote")
|
|
67
90
|
|
|
@@ -104,11 +127,31 @@ class Client:
|
|
|
104
127
|
... run.run(until="/app:exit")
|
|
105
128
|
... run.checkpoint("done")
|
|
106
129
|
|
|
130
|
+
A session can be scheduled to stop for maintenance of its host. The
|
|
131
|
+
client reads the notice at the start of a call into the session, at most
|
|
132
|
+
once every ten minutes from the service, and tells the program once for
|
|
133
|
+
each notice: through `on_session_closing` when it is given, or with a
|
|
134
|
+
`SessionClosing` warning. The session's `closing_at` and
|
|
135
|
+
`closing_reason` say when and why. Use `Session.migrate` before then to
|
|
136
|
+
keep its machines running. A call that is already running when the
|
|
137
|
+
deadline passes is not told.
|
|
138
|
+
|
|
139
|
+
Example:
|
|
140
|
+
>>> def closing(session):
|
|
141
|
+
... session.migrate()
|
|
142
|
+
>>> client = machine.Client(on_session_closing=closing)
|
|
143
|
+
|
|
107
144
|
Args:
|
|
108
145
|
session (str, optional): The current session, by name, id or unique
|
|
109
146
|
id prefix, as `-s` names it.
|
|
110
147
|
api_url (str, optional): The service's URL, as `--api-url` gives it;
|
|
111
148
|
defaults to TESTFLOWS_MACHINE_API_URL, else the public service.
|
|
149
|
+
on_session_closing (callable, optional): Called with the `Session`
|
|
150
|
+
once for each maintenance notice, before the call that found it
|
|
151
|
+
goes on. A call it makes goes on in the session it leaves
|
|
152
|
+
current, so a callback that migrates moves the call with it. An
|
|
153
|
+
exception it raises is raised from that call, and the notice is
|
|
154
|
+
not told again.
|
|
112
155
|
"""
|
|
113
156
|
|
|
114
157
|
def __init__(
|
|
@@ -116,6 +159,7 @@ class Client:
|
|
|
116
159
|
*,
|
|
117
160
|
session: Optional[str] = None,
|
|
118
161
|
api_url: Optional[str] = None,
|
|
162
|
+
on_session_closing: Optional[Callable[[Session], None]] = None,
|
|
119
163
|
) -> None:
|
|
120
164
|
local = os.environ.get(_LOCAL_ENV) == "1"
|
|
121
165
|
if local and session is not None:
|
|
@@ -126,9 +170,17 @@ class Client:
|
|
|
126
170
|
self._local = local
|
|
127
171
|
self._session_ref = session
|
|
128
172
|
self._session: Optional[Session] = None
|
|
173
|
+
#: The session each moved one went to, `sessions migrate`, so every
|
|
174
|
+
#: Session object of a moved session names where it went.
|
|
175
|
+
self._moved_ids: dict[str, str] = {}
|
|
129
176
|
self._api_url = api_url
|
|
130
177
|
self._api: Optional[tuple[api.client.Client, dict[str, Any]]] = None
|
|
131
178
|
self._services: dict[str, _service._Service] = {}
|
|
179
|
+
self._on_session_closing = on_session_closing
|
|
180
|
+
#: The deadlines each session's notice was told for, so a notice is
|
|
181
|
+
#: told once, and again only when it changes. Both the record's and
|
|
182
|
+
#: the session's as read again, which can differ while the record lags.
|
|
183
|
+
self._closing_told: dict[str, set[str]] = {}
|
|
132
184
|
|
|
133
185
|
@classmethod
|
|
134
186
|
def _signed_in(
|
|
@@ -867,6 +919,14 @@ class Client:
|
|
|
867
919
|
self._session_ref = session.id
|
|
868
920
|
self._session = session
|
|
869
921
|
|
|
922
|
+
def _moved(self, old_id: str, session: Session) -> None:
|
|
923
|
+
"""`old_id` moved to `session`: every Session object of `old_id` names it
|
|
924
|
+
now, and the client uses it in its place when it was current."""
|
|
925
|
+
self._moved_ids[old_id] = session.id
|
|
926
|
+
self._services.pop(old_id, None)
|
|
927
|
+
if self._session is not None and self._session.id == session.id:
|
|
928
|
+
self._use(session)
|
|
929
|
+
|
|
870
930
|
def _forget(self, session_id: str) -> None:
|
|
871
931
|
"""Drop `session_id` as current, when it is: it was deleted."""
|
|
872
932
|
self._services.pop(session_id, None)
|
|
@@ -893,16 +953,109 @@ class Client:
|
|
|
893
953
|
)
|
|
894
954
|
if session.id not in self._services:
|
|
895
955
|
client, creds = self._account()
|
|
896
|
-
|
|
897
|
-
|
|
956
|
+
session_id = session.id
|
|
957
|
+
self._services[session_id] = _service.of_session(
|
|
958
|
+
client,
|
|
959
|
+
creds,
|
|
960
|
+
session_id,
|
|
961
|
+
session.name,
|
|
962
|
+
follow=lambda: self._follow_from(session_id),
|
|
898
963
|
)
|
|
899
964
|
return self._services[session.id]
|
|
900
965
|
|
|
901
966
|
@contextlib.contextmanager
|
|
902
967
|
def _connection(self) -> Generator[_ipc.Client, None, None]:
|
|
903
|
-
"""A connection to the current session's service.
|
|
904
|
-
|
|
905
|
-
|
|
968
|
+
"""A connection to the current session's service.
|
|
969
|
+
|
|
970
|
+
A call that fails because the session moved, `sessions migrate`, makes
|
|
971
|
+
the client follow it: the next call goes to where the session went. The
|
|
972
|
+
failed call is raised as it failed, since it may have done its work.
|
|
973
|
+
|
|
974
|
+
A session's maintenance notice is told first, so a callback that
|
|
975
|
+
migrates sends the call to the new session."""
|
|
976
|
+
if not self._local:
|
|
977
|
+
self._tell_closing()
|
|
978
|
+
try:
|
|
979
|
+
with self._service().client() as client:
|
|
980
|
+
yield client
|
|
981
|
+
except Exception as err:
|
|
982
|
+
if not self._local and _sessions.moved_away(err):
|
|
983
|
+
self._follow()
|
|
984
|
+
raise
|
|
985
|
+
|
|
986
|
+
def _tell_closing(self) -> None:
|
|
987
|
+
"""Tell the program of the current session's maintenance notice, once
|
|
988
|
+
for each deadline: `on_session_closing`, or a `SessionClosing`
|
|
989
|
+
warning. Marked told before the callback runs, so the calls it makes
|
|
990
|
+
do not tell it again."""
|
|
991
|
+
session = self.session
|
|
992
|
+
if session is None:
|
|
993
|
+
return
|
|
994
|
+
notice = _sessions.notice(session.id, self._account)
|
|
995
|
+
if notice is None:
|
|
996
|
+
if self._closing_told.pop(session.id, None):
|
|
997
|
+
session._closing(None, None)
|
|
998
|
+
return
|
|
999
|
+
by = _deadline_key(notice.by)
|
|
1000
|
+
told = self._closing_told.setdefault(session.id, set())
|
|
1001
|
+
if by in told:
|
|
1002
|
+
return
|
|
1003
|
+
told.add(by)
|
|
1004
|
+
if not self._closing_still(session, by, notice.reason):
|
|
1005
|
+
return
|
|
1006
|
+
deadline = _deadline(str(session.closing_at))
|
|
1007
|
+
told.add(_deadline_key(deadline))
|
|
1008
|
+
if self._on_session_closing is not None:
|
|
1009
|
+
self._on_session_closing(session)
|
|
1010
|
+
return
|
|
1011
|
+
reason = session.closing_reason or notice.reason
|
|
1012
|
+
_warn.warn(
|
|
1013
|
+
f"Session {session.name} stops at {deadline:%Y-%m-%d %H:%M} UTC"
|
|
1014
|
+
f" because of {reason}. Move it before then with Session.migrate.",
|
|
1015
|
+
SessionClosing,
|
|
1016
|
+
)
|
|
1017
|
+
|
|
1018
|
+
def _closing_still(self, session: Session, by: str, reason: str) -> bool:
|
|
1019
|
+
"""Read `session` again before a notice is told: the notice is read
|
|
1020
|
+
from a record up to ten minutes old, and a session that moved or ended
|
|
1021
|
+
since keeps its notice, which nothing can act on. When the service
|
|
1022
|
+
does not answer, the notice is told as recorded: a notice never fails
|
|
1023
|
+
the call it rides on."""
|
|
1024
|
+
try:
|
|
1025
|
+
session.refresh()
|
|
1026
|
+
except Exception:
|
|
1027
|
+
session._closing(by, reason)
|
|
1028
|
+
return True
|
|
1029
|
+
live = session.state in _sessions.NOTICE_STATES
|
|
1030
|
+
moved = bool(session._row.get("successor_id"))
|
|
1031
|
+
return live and not moved and session.closing_at is not None
|
|
1032
|
+
|
|
1033
|
+
def _follow(self) -> None:
|
|
1034
|
+
"""Use the session the current one moved to, when it moved."""
|
|
1035
|
+
if self._session is not None:
|
|
1036
|
+
self._follow_from(self._session.id)
|
|
1037
|
+
|
|
1038
|
+
def _follow_from(self, old_id: str) -> Optional[Path]:
|
|
1039
|
+
"""Follow session `old_id` to where it moved, and give its socket; None
|
|
1040
|
+
when it did not move. Bound to each session's service, so a session that
|
|
1041
|
+
is not the current one follows its own move, not the current one's."""
|
|
1042
|
+
client, creds = self._account()
|
|
1043
|
+
try:
|
|
1044
|
+
info = _sessions.follow(client, creds, old_id)
|
|
1045
|
+
except Exception: # the error that led here is the one to report
|
|
1046
|
+
return None
|
|
1047
|
+
if info is None:
|
|
1048
|
+
return None
|
|
1049
|
+
moved = Session(self, info)
|
|
1050
|
+
self._moved(old_id, moved)
|
|
1051
|
+
return api.store.session_socket(moved.id)
|
|
1052
|
+
|
|
1053
|
+
def _now_id(self, session_id: str) -> str:
|
|
1054
|
+
"""The id a session has now: the session it moved to, after every move this
|
|
1055
|
+
client followed."""
|
|
1056
|
+
while session_id in self._moved_ids:
|
|
1057
|
+
session_id = self._moved_ids[session_id]
|
|
1058
|
+
return session_id
|
|
906
1059
|
|
|
907
1060
|
@contextlib.contextmanager
|
|
908
1061
|
def _catalog(self) -> Generator[_run_source.RunSource, None, None]:
|
|
@@ -115,9 +115,10 @@ class Conflict(Error):
|
|
|
115
115
|
|
|
116
116
|
|
|
117
117
|
class Diverged(Error):
|
|
118
|
-
"""A
|
|
119
|
-
machine no longer matched the recording
|
|
120
|
-
|
|
118
|
+
"""A machine's state did not match what was recorded. `Run.play` stopped
|
|
119
|
+
where the machine no longer matched the recording, or `Session.migrate`
|
|
120
|
+
started a machine in another state than it stopped in. `Run.replay`
|
|
121
|
+
reports a divergence in its result instead."""
|
|
121
122
|
|
|
122
123
|
|
|
123
124
|
class Timeout(Error, TimeoutError):
|
|
@@ -19,9 +19,11 @@ import builtins
|
|
|
19
19
|
from typing import TYPE_CHECKING, Any, Generator, Literal, Optional, overload
|
|
20
20
|
|
|
21
21
|
from testflows.machine._core import api
|
|
22
|
+
from testflows.machine._core import migration as _migration
|
|
22
23
|
from testflows.machine._core import sessions as _sessions
|
|
23
24
|
|
|
24
25
|
from . import _args
|
|
26
|
+
from . import _warn
|
|
25
27
|
from .errors import ApiError, InvalidArgument, NotFound, _translated
|
|
26
28
|
|
|
27
29
|
if TYPE_CHECKING:
|
|
@@ -49,6 +51,18 @@ FIELDS: tuple[str, ...] = (
|
|
|
49
51
|
)
|
|
50
52
|
|
|
51
53
|
|
|
54
|
+
class SessionClosing(UserWarning):
|
|
55
|
+
"""A session is scheduled to stop for maintenance of its host. The
|
|
56
|
+
client gives it once for each notice, at the program's next call into the
|
|
57
|
+
session, when the program set no `on_session_closing`. Use
|
|
58
|
+
`warnings.simplefilter("error", SessionClosing)` to raise it instead."""
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class SessionMovedBack(UserWarning):
|
|
62
|
+
"""A run that `migrate` started at its last checkpoint, not where it was,
|
|
63
|
+
because the session's host was lost before the move stopped it."""
|
|
64
|
+
|
|
65
|
+
|
|
52
66
|
class Session:
|
|
53
67
|
"""One session: a machine the account rents, with its own CPUs,
|
|
54
68
|
memory and storage, where runs execute.
|
|
@@ -75,8 +89,9 @@ class Session:
|
|
|
75
89
|
|
|
76
90
|
@property
|
|
77
91
|
def id(self) -> str:
|
|
78
|
-
"""str: The session's id
|
|
79
|
-
|
|
92
|
+
"""str: The session's id. A session moved with `migrate` has a new id,
|
|
93
|
+
which this follows, whichever client or object moved it."""
|
|
94
|
+
return self._client._now_id(str(self._row["session_id"]))
|
|
80
95
|
|
|
81
96
|
@property
|
|
82
97
|
def name(self) -> str:
|
|
@@ -142,6 +157,24 @@ class Session:
|
|
|
142
157
|
"""str: When the session stopped, ISO 8601; None while it runs."""
|
|
143
158
|
return _str_or_none(self._row.get("stopped_at"))
|
|
144
159
|
|
|
160
|
+
@property
|
|
161
|
+
def closing_at(self) -> Optional[str]:
|
|
162
|
+
"""str: When the session stops for maintenance of its host, ISO 8601;
|
|
163
|
+
None when none is scheduled. Use `migrate` before then to keep its
|
|
164
|
+
machines running in a new session. Read again with `refresh`."""
|
|
165
|
+
return _str_or_none(self._row.get("closing_at"))
|
|
166
|
+
|
|
167
|
+
@property
|
|
168
|
+
def closing_reason(self) -> Optional[str]:
|
|
169
|
+
"""str: Why the session stops at `closing_at`, such as a kernel
|
|
170
|
+
update; None when none is scheduled."""
|
|
171
|
+
return _str_or_none(self._row.get("closing_reason"))
|
|
172
|
+
|
|
173
|
+
def _closing(self, by: Optional[str], reason: Optional[str]) -> None:
|
|
174
|
+
"""Set the notice the client read, without asking the API again."""
|
|
175
|
+
self._row["closing_at"] = by
|
|
176
|
+
self._row["closing_reason"] = reason
|
|
177
|
+
|
|
145
178
|
def refresh(self) -> "Session":
|
|
146
179
|
"""Read the session again, so its attributes are current.
|
|
147
180
|
|
|
@@ -241,6 +274,60 @@ class Session:
|
|
|
241
274
|
self._row = _sessions.keep(client, creds, self.id, minutes)
|
|
242
275
|
return self
|
|
243
276
|
|
|
277
|
+
def migrate(self) -> "Session":
|
|
278
|
+
"""Move the session to a new session with its runs, as `machine
|
|
279
|
+
sessions migrate` does.
|
|
280
|
+
|
|
281
|
+
A session of the same class and size is created. Each running machine
|
|
282
|
+
is stopped, which checkpoints it, and started in the new session at
|
|
283
|
+
that checkpoint, in the same state. The new session takes the name,
|
|
284
|
+
and the old one is deleted. A command running on a machine ends, as
|
|
285
|
+
`stop` ends it.
|
|
286
|
+
|
|
287
|
+
A move that fails is put back: every machine it stopped starts again
|
|
288
|
+
in the session, and the new session is deleted. When the session ends
|
|
289
|
+
during the move, the move finishes in the new session instead.
|
|
290
|
+
|
|
291
|
+
A machine the move had not stopped when the session's host was lost
|
|
292
|
+
starts at its last checkpoint, not where it was. Each one is reported
|
|
293
|
+
with a `SessionMovedBack` warning that names the run.
|
|
294
|
+
|
|
295
|
+
This object becomes the new session. When it was the client's current
|
|
296
|
+
session, the client uses the new one.
|
|
297
|
+
|
|
298
|
+
Example:
|
|
299
|
+
>>> session = client.sessions.show("ci-1")
|
|
300
|
+
>>> session.migrate().name
|
|
301
|
+
'ci-1'
|
|
302
|
+
|
|
303
|
+
Returns:
|
|
304
|
+
Session: This session, moved.
|
|
305
|
+
|
|
306
|
+
Raises:
|
|
307
|
+
NoCapacity: No other host has room for the session now.
|
|
308
|
+
NotRunning: The session is not running.
|
|
309
|
+
Diverged: A machine started in another state in the new session.
|
|
310
|
+
The sessions are kept as they are, and the message says how
|
|
311
|
+
to go on.
|
|
312
|
+
Conflict: The move was refused, or failed and was put back. The
|
|
313
|
+
message says why.
|
|
314
|
+
ApiError: The service could not carry out the move.
|
|
315
|
+
"""
|
|
316
|
+
client, creds = self._client._account()
|
|
317
|
+
old_id = self.id
|
|
318
|
+
with _translated():
|
|
319
|
+
planned = _migration.plan(client, creds, old_id)
|
|
320
|
+
moved = _migration.migrate(client, creds, planned)
|
|
321
|
+
self._row = moved.session
|
|
322
|
+
self._client._moved(old_id, self)
|
|
323
|
+
for machine in moved.went_back:
|
|
324
|
+
_warn.warn(
|
|
325
|
+
f"{machine.name} ({machine.run_id}) started at its last checkpoint."
|
|
326
|
+
" The session's host was lost before the move stopped it.",
|
|
327
|
+
SessionMovedBack,
|
|
328
|
+
)
|
|
329
|
+
return self
|
|
330
|
+
|
|
244
331
|
def delete(self, *, wait: bool = True, timeout: Optional[float] = None) -> None:
|
|
245
332
|
"""Delete the session, as `machine sessions delete` does.
|
|
246
333
|
|
|
@@ -471,7 +558,9 @@ class Sessions:
|
|
|
471
558
|
tests it and reconnects through a fresh tunnel when it does not
|
|
472
559
|
answer. Otherwise it connects, waiting while the session is still
|
|
473
560
|
provisioning. Only this client changes: the CLI's current session is
|
|
474
|
-
left as it is.
|
|
561
|
+
left as it is. A session that moved, `migrate` here or on another
|
|
562
|
+
computer, is followed: the session it moved to becomes current, and
|
|
563
|
+
every Session object of the one it left names it.
|
|
475
564
|
|
|
476
565
|
Example:
|
|
477
566
|
>>> session = client.sessions.use("ci-1")
|
|
@@ -498,13 +587,48 @@ class Sessions:
|
|
|
498
587
|
failed.
|
|
499
588
|
ServiceUnavailable: The session does not respond.
|
|
500
589
|
"""
|
|
501
|
-
known = self.show(session)
|
|
590
|
+
known = self._moved_to(self.show(session))
|
|
502
591
|
with _translated():
|
|
503
592
|
if api.store.session_connected(known.id) and _sessions.recheck(known.id):
|
|
504
593
|
self._client._use(known)
|
|
505
594
|
return known
|
|
506
595
|
return self.connect(known, wait=wait, timeout=timeout)
|
|
507
596
|
|
|
597
|
+
def _moved_to(self, session: Session) -> Session:
|
|
598
|
+
"""The session `session` moved to, after every move; itself when it did
|
|
599
|
+
not move."""
|
|
600
|
+
if not session._row.get("successor_id"):
|
|
601
|
+
return session
|
|
602
|
+
client, creds = self._client._account()
|
|
603
|
+
with _translated():
|
|
604
|
+
row = _sessions.follow(client, creds, session.id)
|
|
605
|
+
if row is None:
|
|
606
|
+
return session
|
|
607
|
+
moved = Session(self._client, row)
|
|
608
|
+
self._client._moved(session.id, moved)
|
|
609
|
+
return moved
|
|
610
|
+
|
|
611
|
+
def migrate(self, session: "Session | str | None" = None) -> Session:
|
|
612
|
+
"""Move a session to a new session with its runs, as `machine sessions
|
|
613
|
+
migrate` does. See `Session.migrate`.
|
|
614
|
+
|
|
615
|
+
Args:
|
|
616
|
+
session (Session or str, optional): The session; defaults to the
|
|
617
|
+
only one.
|
|
618
|
+
|
|
619
|
+
Returns:
|
|
620
|
+
Session: The session, moved.
|
|
621
|
+
|
|
622
|
+
Raises:
|
|
623
|
+
NotFound: No session matches.
|
|
624
|
+
NoCapacity: No other host has room for the session now.
|
|
625
|
+
NotRunning: The session is not running.
|
|
626
|
+
Diverged: A machine started in another state. See `Session.migrate`.
|
|
627
|
+
Conflict: The move was refused, or failed and was put back.
|
|
628
|
+
"""
|
|
629
|
+
target = session if isinstance(session, Session) else self.show(session)
|
|
630
|
+
return target.migrate()
|
|
631
|
+
|
|
508
632
|
def show(self, session: "Session | str | None" = None) -> Session:
|
|
509
633
|
"""Read a session, as `machine sessions show` does.
|
|
510
634
|
|
|
@@ -11,6 +11,7 @@ testflows/machine/v1/_args.py
|
|
|
11
11
|
testflows/machine/v1/_requires.py
|
|
12
12
|
testflows/machine/v1/_service.py
|
|
13
13
|
testflows/machine/v1/_version.py
|
|
14
|
+
testflows/machine/v1/_warn.py
|
|
14
15
|
testflows/machine/v1/_when.py
|
|
15
16
|
testflows/machine/v1/client.py
|
|
16
17
|
testflows/machine/v1/disks.py
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows.machine.egg-info/dependency_links.txt
RENAMED
|
File without changes
|
{testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows.machine.egg-info/top_level.txt
RENAMED
|
File without changes
|