microvm-ctl 0.3.0__tar.gz → 0.3.1__tar.gz

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microvm-ctl
-Version: 0.3.0
+Version: 0.3.1
 Summary: Control and execution plane for AWS Lambda MicroVMs: build images, launch Firecracker microVMs, scale fleets inside your quotas, call into them securely, and watch it all live.
 Author: Vivek Raja P S
 License: Apache-2.0

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/microvm/__init__.py

@@ -12,7 +12,7 @@ from microvm.images import ImageBuilder, ImageBuildError
 from microvm.lease import FanoutLimit, Lease, LeasePlan, LeasePlanRejected, LeasePolicy, plan_fanout
 from microvm.monitor import CostModel, FleetMonitor
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "microvm_client",

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/microvm/cli.py

@@ -531,11 +531,11 @@ def cmd_lease_run(args):
         task = json.loads(args.task) if args.task else {}
     except ValueError as e:
         sys.exit(f"mvm lease run: --task is not valid JSON: {e}")
+    policy = _lease_policy(args)
     lease = Lease(kind=args.kind, token=args.token or "", region=cfg.region, target=args.target,
-                  heartbeat_s=args.heartbeat_every, id=args.id)
+                  heartbeat_s=policy.heartbeat_every(args.heartbeat_every), id=args.id)
     fm = FleetManager(cfg)
-    vm = fm.lease(args.image, lease, task, _lease_policy(args), version=args.version,
-                  execution_role=args.execution_role)
+    vm = fm.lease(args.image, lease, task, policy, version=args.version, execution_role=args.execution_role)
     console.print(
         f"[bold green]✓[/] {vm.microvm_id}  {_state(vm.state)}  "
         f"[link=https://{vm.endpoint}]{vm.endpoint}[/link]  lease {lease.kind}"
@@ -562,14 +562,14 @@ def cmd_lease_run_many(args, cfg):
         sys.exit(f"mvm lease run: --task-template is not valid JSON: {e}")
     if not isinstance(template, dict):
         sys.exit("mvm lease run: --task-template must be a JSON object")
+    policy = _lease_policy(args)
     leases, tasks = [], []
     for i in range(args.shards):
         token = args.token_template.replace("{i}", str(i)) if args.token_template else ""
         lease_id = args.id.replace("{i}", str(i)) if args.id else None
         leases.append(Lease(kind=kind, token=token, region=cfg.region, target=args.target,
-                            heartbeat_s=args.heartbeat_every, id=lease_id))
+                            heartbeat_s=policy.heartbeat_every(args.heartbeat_every), id=lease_id))
         tasks.append(_fill_template(template, i))
-    policy = _lease_policy(args)
     fm = FleetManager(cfg)
     baseline = _baseline_mib(args, cfg)
     plan = fm.plan(args.shards, baseline, policy)

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/microvm/hooks/server.py

@@ -514,7 +514,11 @@ class HookApp:
             self._deliver(ctx, completer, "failure", ctx.completion(error=err))
 
     def _heartbeat_loop(self, ctx: LeaseContext, completer, interval: float) -> None:
-        while not ctx._stop.wait(interval):
+        # The first heartbeat goes out at once: the orchestrator's heartbeat clock started before
+        # RunMicrovm returned, so waiting a full interval first can lose a tight lease.
+        first = True
+        while first or not ctx._stop.wait(interval):
+            first = False
             try:
                 with ctx._lock:  # serialized with _deliver: no heartbeat lands after the completion
                     if ctx.done:

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/microvm/integrations/durable.py

@@ -187,7 +187,7 @@ def lease_microvm(
         ),
     )
     lease = Lease(kind="durable", token=callback.callback_id, region=region,
-                  heartbeat_s=heartbeat_s, id=execution_name(context))
+                  heartbeat_s=policy.heartbeat_every(heartbeat_s), id=execution_name(context))
     policy_dict = {"budget_s": policy.budget_s, "heartbeat_timeout_s": policy.heartbeat_timeout_s,
                    "slack_s": policy.slack_s}
     launch_once = StepConfig(step_semantics=StepSemantics.AT_MOST_ONCE_PER_RETRY,

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/microvm/integrations/stepfunctions.py

@@ -103,8 +103,10 @@ def _lease_states(
     task_expr: str, heartbeat_s: int, lease_id_expr: str, client_token_expr: str,
     done_name: str = "Done",
 ) -> dict:
-    """The states of one lease: `name` -> Terminate -> Done, failures -> Reap ->
-    TerminateStale -> Failed. Used as the whole machine and as a Map item processor."""
+    """The states of one lease: `name` -> Terminate -> Done; a typed failure ->
+    OnLeaseError -> TerminateFailed (the VM the cause names) -> Reap -> TerminateStale ->
+    Failed; a timeout -> OnLeaseError -> Reap -> TerminateStale -> Failed. Used as the whole
+    machine and as a Map item processor."""
     max_duration = policy.max_duration()
     stale_ms = max_duration * 1000
     items_expr = (
@@ -118,7 +120,8 @@ def _lease_states(
             "Arguments": {
                 "ImageIdentifier": image_arn,
                 "ExecutionRoleArn": execution_role_arn,
-                "RunHookPayload": run_hook_payload_expr(region, heartbeat_s, task_expr, lease_id_expr),
+                "RunHookPayload": run_hook_payload_expr(
+                    region, policy.heartbeat_every(heartbeat_s), task_expr, lease_id_expr),
                 "IdlePolicy": _idle_policy_args(policy),
                 "MaximumDurationInSeconds": max_duration,
                 "ClientToken": _jsonata(f"$substring({client_token_expr}, 0, 128)"),
@@ -129,11 +132,30 @@ def _lease_states(
             "Catch": [{
                 "ErrorEquals": ["States.Timeout", "States.HeartbeatTimeout", "States.TaskFailed"],
                 "Assign": {"lease_error": _jsonata("$states.errorOutput")},
-                "Next": "Reap",
+                "Next": "OnLeaseError",
             }],
             "Assign": {"vm": _jsonata("$states.result.microvm_id")},
             "Next": "Terminate",
         },
+        # A typed failure's cause is the VM's own payload and names it: terminate that VM at
+        # once. A timeout carries no id; that VM is bounded by MaximumDurationInSeconds
+        # (budget + slack) and Reap terminates anything older than that.
+        "OnLeaseError": {
+            "Type": "Choice",
+            "Choices": [{
+                "Condition": _jsonata("$contains($string($lease_error.Cause), '\"microvm_id\"')"),
+                "Next": "TerminateFailed",
+            }],
+            "Default": "Reap",
+        },
+        "TerminateFailed": {
+            "Type": "Task",
+            "Resource": TERMINATE,
+            "Arguments": {"MicrovmIdentifier": _jsonata("$parse($lease_error.Cause).microvm_id")},
+            "Retry": _retry_throttling(),
+            "Catch": [{"ErrorEquals": ["States.ALL"], "Next": "Reap"}],
+            "Next": "Reap",
+        },
         "Terminate": {
             "Type": "Task",
             "Resource": TERMINATE,

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/microvm/lease.py

@@ -119,6 +119,15 @@ class LeasePolicy:
     def to_dict(self) -> dict:
         return asdict(self)
 
+    def heartbeat_every(self, requested: int | float | None = None) -> int:
+        """The interval the VM should heartbeat at: the requested seconds (default 30), never
+        more than a third of `heartbeat_timeout_s` and never under 5 s. A heartbeat interval at
+        or above the timeout loses the lease before the first heartbeat lands, because the
+        orchestrator's clock starts before RunMicrovm returns."""
+        want = 30 if requested is None else float(requested)
+        ceiling = max(5.0, self.heartbeat_timeout_s / 3.0)
+        return int(max(5.0, min(want, ceiling)))
+
     def idle_policy(self):
         """No auto-resume: a leased VM that goes idle is finished, not dormant."""
         from microvm.fleet import IdlePolicy

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/microvm_ctl.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microvm-ctl
-Version: 0.3.0
+Version: 0.3.1
 Summary: Control and execution plane for AWS Lambda MicroVMs: build images, launch Firecracker microVMs, scale fleets inside your quotas, call into them securely, and watch it all live.
 Author: Vivek Raja P S
 License: Apache-2.0

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "microvm-ctl"
-version = "0.3.0"
+version = "0.3.1"
 description = "Control and execution plane for AWS Lambda MicroVMs: build images, launch Firecracker microVMs, scale fleets inside your quotas, call into them securely, and watch it all live."
 readme = "README.md"
 requires-python = ">=3.9"

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/tests/test_integrations.py

@@ -23,7 +23,8 @@ def test_asl_is_jsonata_and_json_serialisable():
     json.dumps(asl)  # no sets, no dataclasses
     assert asl["QueryLanguage"] == "JSONata"
     assert asl["StartAt"] == "Lease"
-    assert set(asl["States"]) == {"Lease", "Terminate", "Reap", "TerminateStale", "Failed", "Done"}
+    assert set(asl["States"]) == {"Lease", "Terminate", "OnLeaseError", "TerminateFailed", "Reap",
+                                  "TerminateStale", "Failed", "Done"}
     assert asl["States"]["Done"] == {"Type": "Succeed"}
     assert asl["States"]["Failed"]["Type"] == "Fail"
     assert asl["States"]["Failed"]["Error"] == "LeaseFailed"
@@ -51,7 +52,16 @@ def test_lease_state_resources_and_arguments():
     assert lease["Retry"][0]["BackoffRate"] == 2
     catch = lease["Catch"][0]
     assert catch["ErrorEquals"] == ["States.Timeout", "States.HeartbeatTimeout", "States.TaskFailed"]
-    assert catch["Next"] == "Reap"
+    assert catch["Next"] == "OnLeaseError"
+    asl = _asl()
+    choice = asl["States"]["OnLeaseError"]
+    assert choice["Type"] == "Choice" and choice["Default"] == "Reap"
+    assert choice["Choices"][0]["Next"] == "TerminateFailed"
+    assert "microvm_id" in choice["Choices"][0]["Condition"]
+    tf = asl["States"]["TerminateFailed"]
+    assert tf["Resource"] == asl["States"]["Terminate"]["Resource"]
+    assert "$parse($lease_error.Cause).microvm_id" in tf["Arguments"]["MicrovmIdentifier"]
+    assert tf["Next"] == "Reap" and tf["Catch"][0]["Next"] == "Reap"
     assert catch["Assign"] == {"lease_error": "{% $states.errorOutput %}"}
 
 

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/tests/test_integrations_durable.py

@@ -91,7 +91,7 @@ def test_success_carries_the_lease_and_terminates_once(fm):
         launch = fm.leases[0]
         lease = launch["lease"]
         assert lease.kind == "durable" and lease.token == cb and lease.region == "us-east-1"
-        assert lease.heartbeat_s == 30 and lease.id
+        assert lease.heartbeat_s == 5 and lease.id  # clamped: timeout 2 s -> floor of 5 s
         assert launch["image"] == "handoff-agent" and launch["task"] == TASK
         assert launch["policy"].budget_s == 4 and launch["policy"].max_duration() == 124
         assert launch["version"] == "3" and launch["execution_role"] == "arn:aws:iam::1:role/agent"

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/tests/test_integrations_scale.py

@@ -11,7 +11,8 @@ from microvm.lease import LeasePolicy
 IMAGE = "arn:aws:lambda:us-east-1:123456789012:microvm-image:handoff-agent"
 ROLE = "arn:aws:iam::123456789012:role/agent"
 TOPIC = "arn:aws:sns:us-east-1:1:t"
-LEASE_STATES = {"Lease", "Terminate", "Reap", "TerminateStale", "Failed", "Done"}
+LEASE_STATES = {"Lease", "Terminate", "OnLeaseError", "TerminateFailed", "Reap", "TerminateStale", "Failed",
+                "Done"}
 
 def _indexed(expr: str) -> str:
     return "{% $map(" + expr + ", function($v, $i) { {'index': $i, 'task': $v} }) %}"

{microvm_ctl-0.3.0 → microvm_ctl-0.3.1}/tests/test_scale.py

@@ -329,3 +329,24 @@ def test_package_exports():
 
     assert microvm.LeasePlan is LeasePlan and microvm.LeasePlanRejected is LeasePlanRejected
     assert microvm.FanoutLimit is FanoutLimit and microvm.plan_fanout is plan_fanout
+
+
+def test_heartbeat_every_clamps_to_a_third_of_the_timeout():
+    from microvm.lease import LeasePolicy
+
+    assert LeasePolicy().heartbeat_every() == 30            # 120 s timeout: the default 30 s stands
+    assert LeasePolicy(heartbeat_timeout_s=30).heartbeat_every() == 10
+    assert LeasePolicy(heartbeat_timeout_s=30).heartbeat_every(30) == 10
+    assert LeasePolicy(heartbeat_timeout_s=30).heartbeat_every(4) == 5
+    assert LeasePolicy(heartbeat_timeout_s=9).heartbeat_every() == 5
+    assert LeasePolicy(heartbeat_timeout_s=600).heartbeat_every(45) == 45
+
+
+def test_state_machine_and_durable_lease_use_the_clamped_interval():
+    from microvm.integrations.stepfunctions import lease_state_machine
+    from microvm.lease import LeasePolicy
+
+    asl = lease_state_machine(image_arn="arn:aws:lambda:us-east-1:1:microvm-image:x",
+                              execution_role_arn="arn:aws:iam::1:role/r",
+                              policy=LeasePolicy(heartbeat_timeout_s=30), region="us-east-1", heartbeat_s=30)
+    assert "'heartbeat_s': 10" in asl["States"]["Lease"]["Arguments"]["RunHookPayload"]