add proxy_state_updated events (#908)

docs/webhook_events.md

@@ -37,6 +37,7 @@ Each event will be submitted via HTTP POST to the user provided URL.
 * [proxy_created](#proxy_created)
 * [proxy_deleted](#proxy_deleted)
 * [proxy_failed](#proxy_failed)
+* [proxy_state_updated](#proxy_state_updated)
 * [regression_reported](#regression_reported)
 * [scaleset_created](#scaleset_created)
 * [scaleset_deleted](#scaleset_deleted)
@@ -1411,6 +1412,61 @@ Each event will be submitted via HTTP POST to the user provided URL.
 }
 ```
 
+### proxy_state_updated
+
+#### Example
+
+```json
+{
+    "proxy_id": "00000000-0000-0000-0000-000000000000",
+    "region": "eastus",
+    "state": "init"
+}
+```
+
+#### Schema
+
+```json
+{
+    "definitions": {
+        "VmState": {
+            "description": "An enumeration.",
+            "enum": [
+                "init",
+                "extensions_launch",
+                "extensions_failed",
+                "vm_allocation_failed",
+                "running",
+                "stopping",
+                "stopped"
+            ],
+            "title": "VmState"
+        }
+    },
+    "properties": {
+        "proxy_id": {
+            "format": "uuid",
+            "title": "Proxy Id",
+            "type": "string"
+        },
+        "region": {
+            "title": "Region",
+            "type": "string"
+        },
+        "state": {
+            "$ref": "#/definitions/VmState"
+        }
+    },
+    "required": [
+        "region",
+        "proxy_id",
+        "state"
+    ],
+    "title": "EventProxyStateUpdated",
+    "type": "object"
+}
+```
+
 ### regression_reported
 
 #### Example
@@ -4963,6 +5019,29 @@ Each event will be submitted via HTTP POST to the user provided URL.
             "title": "EventProxyFailed",
             "type": "object"
         },
+        "EventProxyStateUpdated": {
+            "properties": {
+                "proxy_id": {
+                    "format": "uuid",
+                    "title": "Proxy Id",
+                    "type": "string"
+                },
+                "region": {
+                    "title": "Region",
+                    "type": "string"
+                },
+                "state": {
+                    "$ref": "#/definitions/VmState"
+                }
+            },
+            "required": [
+                "region",
+                "proxy_id",
+                "state"
+            ],
+            "title": "EventProxyStateUpdated",
+            "type": "object"
+        },
         "EventRegressionReported": {
             "properties": {
                 "container": {
@@ -5248,6 +5327,7 @@ Each event will be submitted via HTTP POST to the user provided URL.
                 "proxy_created",
                 "proxy_deleted",
                 "proxy_failed",
+                "proxy_state_updated",
                 "scaleset_created",
                 "scaleset_deleted",
                 "scaleset_failed",
@@ -5858,6 +5938,19 @@ Each event will be submitted via HTTP POST to the user provided URL.
             },
             "title": "UserInfo",
             "type": "object"
+        },
+        "VmState": {
+            "description": "An enumeration.",
+            "enum": [
+                "init",
+                "extensions_launch",
+                "extensions_failed",
+                "vm_allocation_failed",
+                "running",
+                "stopping",
+                "stopped"
+            ],
+            "title": "VmState"
         }
     },
     "properties": {
@@ -5899,6 +5992,9 @@ Each event will be submitted via HTTP POST to the user provided URL.
                 {
                     "$ref": "#/definitions/EventProxyDeleted"
                 },
+                {
+                    "$ref": "#/definitions/EventProxyStateUpdated"
+                },
                 {
                     "$ref": "#/definitions/EventScalesetFailed"
                 },

src/api-service/__app__/onefuzzlib/proxy.py

@@ -11,7 +11,12 @@ from uuid import UUID, uuid4
 
 from azure.mgmt.compute.models import VirtualMachine
 from onefuzztypes.enums import ErrorCode, VmState
-from onefuzztypes.events import EventProxyCreated, EventProxyDeleted, EventProxyFailed
+from onefuzztypes.events import (
+    EventProxyCreated,
+    EventProxyDeleted,
+    EventProxyFailed,
+    EventProxyStateUpdated,
+)
 from onefuzztypes.models import (
     Authentication,
     Error,
@@ -81,7 +86,7 @@ class Proxy(ORMMixin):
                 return
             else:
                 self.save_proxy_config()
-                self.state = VmState.extensions_launch
+                self.set_state(VmState.extensions_launch)
         else:
             result = vm.create()
             if isinstance(result, Error):
@@ -115,8 +120,7 @@ class Proxy(ORMMixin):
             EventProxyFailed(region=self.region, proxy_id=self.proxy_id, error=error)
         )
         self.error = error
-        self.state = VmState.stopping
-        self.save()
+        self.set_state(VmState.stopping)
 
     def extensions_launch(self) -> None:
         vm = self.get_vm()
@@ -146,7 +150,7 @@ class Proxy(ORMMixin):
             self.set_failed(result)
             return
         elif result:
-            self.state = VmState.running
+            self.set_state(VmState.running)
 
         self.save()
 
@@ -298,3 +302,16 @@ class Proxy(ORMMixin):
     def delete(self) -> None:
         super().delete()
         send_event(EventProxyDeleted(region=self.region, proxy_id=self.proxy_id))
+
+    def set_state(self, state: VmState) -> None:
+        if self.state == state:
+            return
+
+        self.state = state
+        self.save()
+
+        send_event(
+            EventProxyStateUpdated(
+                region=self.region, proxy_id=self.proxy_id, state=self.state
+            )
+        )

src/api-service/__app__/timer_daily/__init__.py

@@ -41,8 +41,7 @@ def main(mytimer: func.TimerRequest, dashboard: func.Out[str]) -> None:  # noqa:
                 )
             if not proxy.is_used():
                 logging.info("stopping one proxy in %s.", proxy.region)
-                proxy.state = VmState.stopping
-                proxy.save()
+                proxy.set_state(VmState.stopping)
 
     scalesets = Scaleset.search()
     for scaleset in scalesets:

src/api-service/__app__/timer_proxy/__init__.py

@@ -21,7 +21,7 @@ def main(mytimer: func.TimerRequest, dashboard: func.Out[str]) -> None:  # noqa:
             logging.error(
                 PROXY_LOG_PREFIX + "alive check failed, stopping: %s", proxy.region
             )
-            proxy.state = VmState.stopping
+            proxy.set_state(VmState.stopping)
             proxy.save()
         else:
             proxy.save_proxy_config()

src/pytypes/extra/generate-docs.py

@@ -16,6 +16,7 @@ from onefuzztypes.enums import (
     ScalesetState,
     TaskState,
     TaskType,
+    VmState,
 )
 from onefuzztypes.events import (
     Event,
@@ -33,6 +34,7 @@ from onefuzztypes.events import (
     EventProxyCreated,
     EventProxyDeleted,
     EventProxyFailed,
+    EventProxyStateUpdated,
     EventRegressionReported,
     EventScalesetCreated,
     EventScalesetDeleted,
@@ -163,6 +165,11 @@ def main() -> None:
             proxy_id=UUID(int=0),
             error=Error(code=ErrorCode.PROXY_FAILED, errors=["example error message"]),
         ),
+        EventProxyStateUpdated(
+            region=Region("eastus"),
+            proxy_id=UUID(int=0),
+            state=VmState.init,
+        ),
         EventPoolCreated(
             pool_name=PoolName("example"),
             os=OS.linux,

src/pytypes/onefuzztypes/events.py

@@ -10,7 +10,15 @@ from uuid import UUID, uuid4
 
 from pydantic import BaseModel, Field
 
-from .enums import OS, Architecture, NodeState, ScalesetState, TaskState, TaskType
+from .enums import (
+    OS,
+    Architecture,
+    NodeState,
+    ScalesetState,
+    TaskState,
+    TaskType,
+    VmState,
+)
 from .models import (
     AutoScaleConfig,
     Error,
@@ -135,6 +143,12 @@ class EventProxyFailed(BaseEvent):
     error: Error
 
 
+class EventProxyStateUpdated(BaseEvent):
+    region: Region
+    proxy_id: UUID
+    state: VmState
+
+
 class EventNodeCreated(BaseEvent):
     machine_id: UUID
     scaleset_id: Optional[UUID]
@@ -198,6 +212,7 @@ Event = Union[
     EventProxyFailed,
     EventProxyCreated,
     EventProxyDeleted,
+    EventProxyStateUpdated,
     EventScalesetFailed,
     EventScalesetCreated,
     EventScalesetDeleted,
@@ -225,6 +240,7 @@ class EventType(Enum):
     proxy_created = "proxy_created"
     proxy_deleted = "proxy_deleted"
     proxy_failed = "proxy_failed"
+    proxy_state_updated = "proxy_state_updated"
     scaleset_created = "scaleset_created"
     scaleset_deleted = "scaleset_deleted"
     scaleset_failed = "scaleset_failed"
@@ -253,6 +269,7 @@ EventTypeMap = {
     EventType.proxy_created: EventProxyCreated,
     EventType.proxy_deleted: EventProxyDeleted,
     EventType.proxy_failed: EventProxyFailed,
+    EventType.proxy_state_updated: EventProxyStateUpdated,
     EventType.scaleset_created: EventScalesetCreated,
     EventType.scaleset_deleted: EventScalesetDeleted,
     EventType.scaleset_failed: EventScalesetFailed,