Add version property to Instance and AsyncInstance classes (#11)

TL;DR
-----

Lets Applications report their version information alongside instance status

Details
--------

Extends the existing instance telemetry infrastructure with a `set_version()` method that mirrors the established `set_status()` pattern. Version information transmits through the `X-Replicated-VersionLabel` header during instance reporting, ensuring it reaches the vendor's dashboard alongside other telemetry data.

Both synchronous and asynchronous instance classes now support version reporting, and the example scripts demonstrate this capability through a `--version` command-line argument. The change also fixes an important detail in the customer service by setting "Stable" as the default channel instead of None, preventing potential issues with unspecified channels during customer creation.

Warning
-------

Do not merge until replicatedhq/vandoor#8194 lands.

Author: crdant

examples/basic_example.py

@@ -31,6 +31,17 @@ def main():
     )
     parser.add_argument("--channel", help="Channel for the customer (optional)")
     parser.add_argument("--customer-name", help="Customer name (optional)")
+    parser.add_argument(
+        "--status",
+        choices=["missing", "unavailable", "ready", "updating", "degraded"],
+        default="ready",
+        help="Instance status (default: ready)",
+    )
+    parser.add_argument(
+        "--version",
+        default="",
+        help="Application version (optional)",
+    )
 
     args = parser.parse_args()
 
@@ -65,6 +76,15 @@ def main():
         instance = customer.get_or_create_instance()
         print(f"✓ Instance created/retrieved - ID: {instance.instance_id}")
 
+        # Set instance status
+        instance.set_status(args.status)
+        print(f"✓ Instance status set to: {args.status}")
+
+        # Set instance version if provided
+        if args.version:
+            instance.set_version(args.version)
+            print(f"✓ Instance version set to: {args.version}")
+
         print("\n🎉 Basic example completed successfully!")
         print(f"Customer ID: {customer.customer_id}")
         print(f"Instance ID: {instance.instance_id}")

examples/metrics_example.py

@@ -38,6 +38,11 @@ async def main():
         default="ready",
         help="Instance status (default: ready)",
     )
+    parser.add_argument(
+        "--version",
+        default="",
+        help="Application version (optional)",
+    )
 
     args = parser.parse_args()
 
@@ -80,6 +85,11 @@ async def main():
         await instance.set_status(args.status)
         print(f"✓ Instance status set to: {args.status}")
 
+        # Set instance version if provided
+        if args.version:
+            await instance.set_version(args.version)
+            print(f"✓ Instance version set to: {args.version}")
+
         # Send some metrics concurrently
         await asyncio.gather(
             instance.send_metric("cpu_usage", 0.83),

replicated/resources.py

@@ -67,6 +67,7 @@ def __init__(
         self._machine_id = client._machine_id
         self._data = kwargs
         self._status = "ready"
+        self._version = ""
         self._metrics: dict[str, Union[int, float, str]] = {}
 
     def send_metric(self, name: str, value: Union[int, float, str]) -> None:
@@ -100,6 +101,14 @@ def set_status(self, status: str) -> None:
         self._status = status
         self._report_instance()
 
+    def set_version(self, version: str) -> None:
+        """Set the version of this instance for telemetry reporting."""
+        if not self.instance_id:
+            self._ensure_instance()
+
+        self._version = version
+        self._report_instance()
+
     def _ensure_instance(self) -> None:
         """Ensure the instance ID is generated and cached."""
         if self.instance_id:
@@ -154,6 +163,7 @@ def _report_instance(self) -> None:
                 "X-Replicated-InstanceID": self.instance_id,
                 "X-Replicated-ClusterID": self._machine_id,
                 "X-Replicated-AppStatus": self._status,
+                "X-Replicated-VersionLabel": self._version,
                 "X-Replicated-InstanceTagData": instance_tags_b64,
             }
 
@@ -188,6 +198,7 @@ def __init__(
         self._machine_id = client._machine_id
         self._data = kwargs
         self._status = "ready"
+        self._version = ""
         self._metrics: dict[str, Union[int, float, str]] = {}
 
     async def send_metric(self, name: str, value: Union[int, float, str]) -> None:
@@ -221,6 +232,14 @@ async def set_status(self, status: str) -> None:
         self._status = status
         await self._report_instance()
 
+    async def set_version(self, version: str) -> None:
+        """Set the version of this instance for telemetry reporting."""
+        if not self.instance_id:
+            await self._ensure_instance()
+
+        self._version = version
+        await self._report_instance()
+
     async def _ensure_instance(self) -> None:
         """Ensure the instance ID is generated and cached."""
         if self.instance_id:
@@ -275,6 +294,7 @@ async def _report_instance(self) -> None:
                 "X-Replicated-InstanceID": self.instance_id,
                 "X-Replicated-ClusterID": self._machine_id,
                 "X-Replicated-AppStatus": self._status,
+                "X-Replicated-VersionLabel": self._version,
                 "X-Replicated-InstanceTagData": instance_tags_b64,
             }
 

replicated/services.py

@@ -16,7 +16,7 @@ def __init__(self, client: "ReplicatedClient") -> None:
     def get_or_create(
         self,
         email_address: str,
-        channel: Optional[str] = None,
+        channel: str = "Stable",
         name: Optional[str] = None,
     ) -> Customer:
         """Get or create a customer."""
@@ -82,7 +82,7 @@ def __init__(self, client: "AsyncReplicatedClient") -> None:
     async def get_or_create(
         self,
         email_address: str,
-        channel: Optional[str] = None,
+        channel: str = "Stable",
         name: Optional[str] = None,
     ) -> AsyncCustomer:
         """Get or create a customer."""