feat(robot-server): Notify clients whenever labware offsets change (#17817)

## Overview

Does the server half of EXEC-1342. Client half forthcoming in a separate
PR.

## Changelog

Publish a notification to a new topic, `/labwareOffsets`, whenever an
offset is added or deleted.

## Test Plan and Hands on Testing

* [x] Try it out with Postman.

## Risk assessment

Low.

Author: SyntaxColoring

robot-server/robot_server/labware_offsets/fastapi_dependencies.py

@@ -13,6 +13,10 @@
 import sqlalchemy
 
 from robot_server.persistence.fastapi_dependencies import get_sql_engine
+from robot_server.service.notifications.publishers.labware_offsets_publisher import (
+    LabwareOffsetsPublisher,
+    get_labware_offsets_publisher,
+)
 from .store import LabwareOffsetStore
 
 
@@ -24,10 +28,13 @@
 async def get_labware_offset_store(
     app_state: Annotated[AppState, Depends(get_app_state)],
     sql_engine: Annotated[sqlalchemy.engine.Engine, Depends(get_sql_engine)],
+    labware_offsets_publisher: Annotated[
+        LabwareOffsetsPublisher, Depends(get_labware_offsets_publisher)
+    ],
 ) -> LabwareOffsetStore:
     """Get the server's singleton LabwareOffsetStore."""
     labware_offset_store = _labware_offset_store_accessor.get_from(app_state)
     if labware_offset_store is None:
-        labware_offset_store = LabwareOffsetStore(sql_engine)
+        labware_offset_store = LabwareOffsetStore(sql_engine, labware_offsets_publisher)
         _labware_offset_store_accessor.set_on(app_state, labware_offset_store)
     return labware_offset_store

robot-server/robot_server/labware_offsets/store.py

@@ -17,6 +17,9 @@
     labware_offset_table,
     labware_offset_location_sequence_components_table,
 )
+from robot_server.service.notifications.publishers.labware_offsets_publisher import (
+    LabwareOffsetsPublisher,
+)
 from .models import (
     ANY_LOCATION,
     AnyLocation,
@@ -49,14 +52,19 @@ class IncomingStoredLabwareOffset:
 class LabwareOffsetStore:
     """A persistent store for labware offsets, to support the `/labwareOffsets` endpoints."""
 
-    def __init__(self, sql_engine: sqlalchemy.engine.Engine) -> None:
+    def __init__(
+        self,
+        sql_engine: sqlalchemy.engine.Engine,
+        labware_offsets_publisher: LabwareOffsetsPublisher | None,
+    ) -> None:
         """Initialize the store.
 
         Params:
             sql_engine: The SQL database to use as backing storage. Assumed to already
                 have all the proper tables set up.
         """
         self._sql_engine = sql_engine
+        self._labware_offsets_publisher = labware_offsets_publisher
 
     def add(
         self,
@@ -79,6 +87,7 @@ def add(
                     ),
                     location_components_to_insert,
                 )
+        self._publish_change_notification()
 
     def get_all(self) -> list[StoredLabwareOffset]:
         """Return all offsets from oldest to newest.
@@ -123,7 +132,7 @@ def delete(self, offset_id: str) -> StoredLabwareOffset:
                 .where(labware_offset_table.c.offset_id == offset_id)
                 .values(active=False)
             )
-
+        self._publish_change_notification()
         return next(_collate_sql_to_pydantic(offset_rows))
 
     def delete_all(self) -> None:
@@ -132,6 +141,11 @@ def delete_all(self) -> None:
             transaction.execute(
                 sqlalchemy.update(labware_offset_table).values(active=False)
             )
+        self._publish_change_notification()
+
+    def _publish_change_notification(self) -> None:
+        if self._labware_offsets_publisher:
+            self._labware_offsets_publisher.publish_labware_offsets()
 
 
 class LabwareOffsetNotFoundError(KeyError):

robot-server/robot_server/service/notifications/publishers/labware_offsets_publisher.py

@@ -0,0 +1,27 @@
+from typing import Annotated
+import fastapi
+from robot_server.service.notifications import topics
+from robot_server.service.notifications.notification_client import (
+    NotificationClient,
+    get_notification_client,
+)
+
+
+class LabwareOffsetsPublisher:
+    """Publishes clientData topics."""
+
+    def __init__(self, client: NotificationClient) -> None:
+        self._client = client
+
+    def publish_labware_offsets(self) -> None:
+        """Publish the equivalent of `GET /labwareOffsets` or `POST /labwareOffsets/searches`."""
+        self._client.publish_advise_refetch(topics.LABWARE_OFFSETS)
+
+
+async def get_labware_offsets_publisher(
+    notification_client: Annotated[
+        NotificationClient, fastapi.Depends(get_notification_client)
+    ],
+) -> LabwareOffsetsPublisher:
+    """Return a ClientDataPublisher for use by FastAPI endpoints."""
+    return LabwareOffsetsPublisher(notification_client)

robot-server/robot_server/service/notifications/topics.py

@@ -30,6 +30,7 @@ def _is_valid_topic_name_level(level: str) -> bool:
 RUNS = TopicName(f"{_TOPIC_BASE}/runs")
 DECK_CONFIGURATION = TopicName(f"{_TOPIC_BASE}/deck_configuration")
 RUNS_PRE_SERIALIZED_COMMANDS = TopicName(f"{_TOPIC_BASE}/runs/pre_serialized_commands")
+LABWARE_OFFSETS = TopicName(f"{_TOPIC_BASE}/labwareOffsets")
 
 
 def client_data(key: str) -> TopicName:

robot-server/tests/labware_offsets/test_store.py

@@ -3,6 +3,7 @@
 from datetime import datetime, timezone
 from typing import Sequence
 
+from decoy import Decoy
 import pytest
 import sqlalchemy
 
@@ -32,12 +33,24 @@
     StoredLabwareOffsetLocationSequenceComponents,
     UnknownLabwareOffsetLocationSequenceComponent,
 )
+from robot_server.service.notifications.publishers.labware_offsets_publisher import (
+    LabwareOffsetsPublisher,
+)
+
+
+@pytest.fixture
+def mock_labware_offsets_publisher(decoy: Decoy) -> LabwareOffsetsPublisher:
+    """Return a mock in the shape of a LabwareOffsetsPublisher."""
+    return decoy.mock(cls=LabwareOffsetsPublisher)
 
 
 @pytest.fixture
-def subject(sql_engine: sqlalchemy.engine.Engine) -> LabwareOffsetStore:
+def subject(
+    sql_engine: sqlalchemy.engine.Engine,
+    mock_labware_offsets_publisher: LabwareOffsetsPublisher,
+) -> LabwareOffsetStore:
     """Return a test subject."""
-    return LabwareOffsetStore(sql_engine)
+    return LabwareOffsetStore(sql_engine, mock_labware_offsets_publisher)
 
 
 def test_empty_search(subject: LabwareOffsetStore) -> None:
@@ -260,7 +273,7 @@ def test_filter_fields(
             )
         ]
     )
-    assert sorted(results, key=lambda o: o.id,) == sorted(
+    assert sorted(results, key=lambda o: o.id) == sorted(
         [
             StoredLabwareOffset(
                 id=offsets[id_].id,
@@ -473,3 +486,26 @@ def test_handle_unknown(
             )
         )
     assert subject.search([SearchFilter(id="id-a")]) == [outgoing_offset]
+
+
+def test_notifications(
+    subject: LabwareOffsetStore,
+    decoy: Decoy,
+    mock_labware_offsets_publisher: LabwareOffsetsPublisher,
+) -> None:
+    """It should publish notifications any time the set of labware offsets changes."""
+    decoy.verify(mock_labware_offsets_publisher.publish_labware_offsets(), times=0)
+    subject.add(
+        IncomingStoredLabwareOffset(
+            id="id",
+            createdAt=datetime.now(timezone.utc),
+            definitionUri="definitionUri",
+            locationSequence=ANY_LOCATION,
+            vector=LabwareOffsetVector(x=1, y=2, z=3),
+        )
+    )
+    decoy.verify(mock_labware_offsets_publisher.publish_labware_offsets(), times=1)
+    subject.delete("id")
+    decoy.verify(mock_labware_offsets_publisher.publish_labware_offsets(), times=2)
+    subject.delete_all()
+    decoy.verify(mock_labware_offsets_publisher.publish_labware_offsets(), times=3)

robot-server/tests/labware_offsets/test_store_hypothesis.py

@@ -121,7 +121,7 @@ def test_round_trip(
     )
 
     with TemporaryDirectory() as tmp_dir, make_sql_engine(Path(tmp_dir)) as sql_engine:
-        subject = LabwareOffsetStore(sql_engine)
+        subject = LabwareOffsetStore(sql_engine, labware_offsets_publisher=None)
         subject.add(offset_to_add)
         [offset_retrieved_by_get_all] = subject.get_all()
         [offset_retrieved_by_search] = subject.search([SearchFilter(id=id)])
@@ -228,7 +228,7 @@ def __init__(self) -> None:
         self._exit_stack = ExitStack()
         temp_dir = Path(self._exit_stack.enter_context(TemporaryDirectory()))
         sql_engine = self._exit_stack.enter_context(make_sql_engine(temp_dir))
-        self._subject = LabwareOffsetStore(sql_engine)
+        self._subject = LabwareOffsetStore(sql_engine, labware_offsets_publisher=None)
         self._simulated_model = SimulatedStore()
         self._added_ids = set[str]()