coordinator: Serve env file via new GetEnvironment RPC

The lab admin currently has to distribute the env file to every client
out of band - via a shared filesystem, git checkout, scp etc.  This is
awkward duplication for casual clients who just want to talk to a few
boards from a remote machine. It also makes it harder to scale to larger
labs with a lot of clients.

For some labs, particularly smaller ones, the environment is very tied
to the client, with each client having its own special file. For other
labs, such as larger labs where changes are few, the environment is the
same for each client.

Add a new GetEnvironment RPC that returns the env file's text content,
and a coordinator --environment flag pointing at the file to serve. The
file is read fresh on each request, so admins can edit it in place and
clients pick up the new version on their next invocation.

The default (no --environment) is unchanged: GetEnvironment returns an
empty string and clients keep loading env from a local file as before.

Signed-off-by: Simon Glass <sjg@chromium.org>

Author: sjg20

doc/man/coordinator.rst

@@ -25,9 +25,23 @@ OPTIONS
     display command line help
 -l ADDRESS, --listen ADDRESS
     make coordinator listen on host and port
+-e FILE, --environment FILE
+    serve the given YAML env file to clients via the ``GetEnvironment`` RPC.
+    Clients opt in by setting ``LG_ENV=coordinator:`` (see
+    ``labgrid-client``\(1))
 -d, --debug
     enable debug mode
 
+-e / --environment
+~~~~~~~~~~~~~~~~~~
+When this option is set the coordinator reads the file fresh on each
+``GetEnvironment`` request and returns its contents verbatim to the client.
+This means a remote user no longer needs a local copy of the env file - they
+only need network access to the coordinator.
+
+The default (no ``--environment``) is unchanged: ``GetEnvironment`` returns an
+empty string and clients keep loading env from a local file as before.
+
 SEE ALSO
 --------
 

labgrid/remote/coordinator.py

@@ -209,11 +209,12 @@ class ExporterError(Exception):
 
 
 class Coordinator(labgrid_coordinator_pb2_grpc.CoordinatorServicer):
-    def __init__(self) -> None:
+    def __init__(self, environment_file: str | None = None) -> None:
         self.places: dict[str, Place] = {}
         self.reservations = {}
         self.poll_tasks = []
         self.save_scheduled = False
+        self.environment_file = environment_file
 
         self.lock = asyncio.Lock()
         self.exporters: dict[str, ExporterSession] = {}
@@ -1105,8 +1106,17 @@ async def GetReservations(self, request: labgrid_coordinator_pb2.GetReservations
         reservations = [x.as_pb2() for x in self.reservations.values()]
         return labgrid_coordinator_pb2.GetReservationsResponse(reservations=reservations)
 
+    async def GetEnvironment(self, request: labgrid_coordinator_pb2.GetEnvironmentRequest, context):
+        if not self.environment_file:
+            return labgrid_coordinator_pb2.GetEnvironmentResponse(config="")
+        try:
+            with open(self.environment_file, encoding="utf-8") as f:
+                return labgrid_coordinator_pb2.GetEnvironmentResponse(config=f.read())
+        except OSError as e:
+            await context.abort(grpc.StatusCode.FAILED_PRECONDITION, f"cannot read environment file: {e}")
+
 
-async def serve(listen, cleanup) -> None:
+async def serve(listen, cleanup, environment_file=None) -> None:
     asyncio.current_task().set_name("coordinator-serve")
     # It seems since https://github.com/grpc/grpc/pull/34647, the
     # ping_timeout_ms default of 60 seconds overrides keepalive_timeout_ms,
@@ -1124,7 +1134,7 @@ async def serve(listen, cleanup) -> None:
     server = grpc.aio.server(
         options=channel_options,
     )
-    coordinator = Coordinator()
+    coordinator = Coordinator(environment_file=environment_file)
     labgrid_coordinator_pb2_grpc.add_CoordinatorServicer_to_server(coordinator, server)
     # enable reflection for use with grpcurl
     reflection.enable_server_reflection(
@@ -1172,6 +1182,15 @@ def main():
         default="[::]:20408",
         help="coordinator listening host and port",
     )
+    parser.add_argument(
+        "-e",
+        "--environment",
+        metavar="FILE",
+        type=str,
+        default=None,
+        help="path to a YAML environment file to serve to clients via "
+        "GetEnvironment (LG_ENV=coordinator: on the client side)",
+    )
     parser.add_argument("-d", "--debug", action="store_true", default=False, help="enable debug mode")
     parser.add_argument("--pystuck", action="store_true", help="enable pystuck")
     parser.add_argument(
@@ -1201,7 +1220,7 @@ def main():
     cleanup = []
     loop.set_debug(True)
     try:
-        loop.run_until_complete(serve(args.listen, cleanup))
+        loop.run_until_complete(serve(args.listen, cleanup, environment_file=args.environment))
     finally:
         if cleanup:
             loop.run_until_complete(*cleanup)

labgrid/remote/generated/labgrid_coordinator_pb2.py

@@ -446,3 +446,13 @@ class GetReservationsResponse(_message.Message):
 class GetReservationsRequest(_message.Message):
     __slots__ = ()
     def __init__(self) -> None: ...
+
+class GetEnvironmentRequest(_message.Message):
+    __slots__ = ()
+    def __init__(self) -> None: ...
+
+class GetEnvironmentResponse(_message.Message):
+    __slots__ = ("config",)
+    CONFIG_FIELD_NUMBER: _ClassVar[int]
+    config: str
+    def __init__(self, config: _Optional[str] = ...) -> None: ...

labgrid/remote/generated/labgrid_coordinator_pb2.pyi

@@ -104,6 +104,11 @@ def __init__(self, channel):
                 request_serializer=labgrid__coordinator__pb2.GetReservationsRequest.SerializeToString,
                 response_deserializer=labgrid__coordinator__pb2.GetReservationsResponse.FromString,
                 )
+        self.GetEnvironment = channel.unary_unary(
+                '/labgrid.Coordinator/GetEnvironment',
+                request_serializer=labgrid__coordinator__pb2.GetEnvironmentRequest.SerializeToString,
+                response_deserializer=labgrid__coordinator__pb2.GetEnvironmentResponse.FromString,
+                )
 
 
 class CoordinatorServicer(object):
@@ -217,6 +222,12 @@ def GetReservations(self, request, context):
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
+    def GetEnvironment(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
 
 def add_CoordinatorServicer_to_server(servicer, server):
     rpc_method_handlers = {
@@ -310,6 +321,11 @@ def add_CoordinatorServicer_to_server(servicer, server):
                     request_deserializer=labgrid__coordinator__pb2.GetReservationsRequest.FromString,
                     response_serializer=labgrid__coordinator__pb2.GetReservationsResponse.SerializeToString,
             ),
+            'GetEnvironment': grpc.unary_unary_rpc_method_handler(
+                    servicer.GetEnvironment,
+                    request_deserializer=labgrid__coordinator__pb2.GetEnvironmentRequest.FromString,
+                    response_serializer=labgrid__coordinator__pb2.GetEnvironmentResponse.SerializeToString,
+            ),
     }
     generic_handler = grpc.method_handlers_generic_handler(
             'labgrid.Coordinator', rpc_method_handlers)
@@ -625,3 +641,20 @@ def GetReservations(request,
             labgrid__coordinator__pb2.GetReservationsResponse.FromString,
             options, channel_credentials,
             insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def GetEnvironment(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/labgrid.Coordinator/GetEnvironment',
+            labgrid__coordinator__pb2.GetEnvironmentRequest.SerializeToString,
+            labgrid__coordinator__pb2.GetEnvironmentResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

labgrid/remote/generated/labgrid_coordinator_pb2_grpc.py

@@ -38,6 +38,8 @@ service Coordinator {
   rpc PollReservation(PollReservationRequest) returns (PollReservationResponse) {}
 
   rpc GetReservations(GetReservationsRequest) returns (GetReservationsResponse) {}
+
+  rpc GetEnvironment(GetEnvironmentRequest) returns (GetEnvironmentResponse) {}
 }
 
 message ClientInMessage {
@@ -295,3 +297,13 @@ message GetReservationsResponse {
 
 message GetReservationsRequest {
 };
+
+message GetEnvironmentRequest {
+};
+
+message GetEnvironmentResponse {
+  // Raw text of the lab environment file (typically YAML) curated by
+  // the lab admin and served to clients.  Empty if the coordinator was
+  // started without a configured environment file.
+  string config = 1;
+};

labgrid/remote/proto/labgrid-coordinator.proto

@@ -51,9 +51,23 @@ display command line help
 .BI \-l \ ADDRESS\fR,\fB \ \-\-listen \ ADDRESS
 make coordinator listen on host and port
 .TP
+.BI \-e \ FILE\fR,\fB \ \-\-environment \ FILE
+serve the given YAML env file to clients via the \fBGetEnvironment\fP RPC.
+Clients opt in by setting \fBLG_ENV=coordinator:\fP (see
+\fBlabgrid\-client\fP(1))
+.TP
 .B  \-d\fP,\fB  \-\-debug
 enable debug mode
 .UNINDENT
+.SS \-e / \-\-environment
+.sp
+When this option is set the coordinator reads the file fresh on each
+\fBGetEnvironment\fP request and returns its contents verbatim to the client.
+This means a remote user no longer needs a local copy of the env file \- they
+only need network access to the coordinator.
+.sp
+The default (no \fB\-\-environment\fP) is unchanged: \fBGetEnvironment\fP returns an
+empty string and clients keep loading env from a local file as before.
 .SS SEE ALSO
 .sp
 \fBlabgrid\-client\fP(1), \fBlabgrid\-exporter\fP(1)