Add structured remote-control errors

Introduce structured error responses with codes for remote-control endpoints.
Document the error codes in the README.

Author: espentj

das-producer/src/main/java/com/equinor/fiberoptics/das/remotecontrol/ErrorResponse.java

@@ -0,0 +1,31 @@
+/*-
+ * ========================LICENSE_START=================================
+ * fiberoptics-das-producer
+ * %%
+ * Copyright (C) 2020 Equinor ASA
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * =========================LICENSE_END==================================
+ */
+
+package com.equinor.fiberoptics.das.remotecontrol;
+
+/**
+ * Structured error payload for remote-control endpoints.
+ */
+public record ErrorResponse(String errorCode, String message, String path) {
+
+  public static ErrorResponse of(String errorCode, String message, String path) {
+    return new ErrorResponse(errorCode, message, path);
+  }
+}

das-producer/src/main/java/com/equinor/fiberoptics/das/remotecontrol/RemoteControlController.java

@@ -85,9 +85,10 @@ public ResponseEntity<?> stop(
     RemoteControlService.StopResult result = _remoteControlService.stop(
         Optional.ofNullable(acquisitionJson)
     );
-    return result == RemoteControlService.StopResult.NOT_FOUND
-      ? ResponseEntity.notFound().build()
-      : ResponseEntity.ok().build();
+    if (result == RemoteControlService.StopResult.NOT_FOUND) {
+      throw new RemoteControlService.NotFoundException("Acquisition not found.");
+    }
+    return ResponseEntity.ok().build();
   }
 
   private void verifyApiKey(String apiKey) {

das-producer/src/main/java/com/equinor/fiberoptics/das/remotecontrol/RemoteControlExceptionHandler.java

@@ -0,0 +1,72 @@
+/*-
+ * ========================LICENSE_START=================================
+ * fiberoptics-das-producer
+ * %%
+ * Copyright (C) 2020 Equinor ASA
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * =========================LICENSE_END==================================
+ */
+
+package com.equinor.fiberoptics.das.remotecontrol;
+
+import jakarta.servlet.http.HttpServletRequest;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+/**
+ * Maps remote-control errors to structured responses.
+ */
+@RestControllerAdvice(basePackages = "com.equinor.fiberoptics.das.remotecontrol")
+public class RemoteControlExceptionHandler {
+
+  @ExceptionHandler(RemoteControlService.BadRequestException.class)
+  public ResponseEntity<ErrorResponse> handleBadRequest(
+      RemoteControlService.BadRequestException ex,
+      HttpServletRequest request) {
+    return build(HttpStatus.BAD_REQUEST, "RC-400", ex.getMessage(), request);
+  }
+
+  @ExceptionHandler(RemoteControlService.UnauthorizedException.class)
+  public ResponseEntity<ErrorResponse> handleUnauthorized(
+      RemoteControlService.UnauthorizedException ex,
+      HttpServletRequest request) {
+    return build(HttpStatus.UNAUTHORIZED, "RC-401", "Unauthorized", request);
+  }
+
+  @ExceptionHandler(RemoteControlService.NotFoundException.class)
+  public ResponseEntity<ErrorResponse> handleNotFound(
+      RemoteControlService.NotFoundException ex,
+      HttpServletRequest request) {
+    return build(HttpStatus.NOT_FOUND, "RC-404", ex.getMessage(), request);
+  }
+
+  @ExceptionHandler(IllegalStateException.class)
+  public ResponseEntity<ErrorResponse> handleIllegalState(
+      IllegalStateException ex,
+      HttpServletRequest request) {
+    return build(HttpStatus.INTERNAL_SERVER_ERROR, "RC-500", ex.getMessage(), request);
+  }
+
+  private ResponseEntity<ErrorResponse> build(
+      HttpStatus status,
+      String code,
+      String message,
+      HttpServletRequest request) {
+    String path = request == null ? null : request.getRequestURI();
+    String safeMessage = message == null || message.isBlank() ? status.getReasonPhrase() : message;
+    return ResponseEntity.status(status).body(ErrorResponse.of(code, safeMessage, path));
+  }
+}

das-producer/src/main/java/com/equinor/fiberoptics/das/remotecontrol/RemoteControlService.java

@@ -444,4 +444,14 @@ public BadRequestException(String message) {
   @ResponseStatus(HttpStatus.UNAUTHORIZED)
   public static class UnauthorizedException extends RuntimeException {
   }
+
+  /**
+   * Thrown when a requested acquisition does not exist.
+   */
+  @ResponseStatus(HttpStatus.NOT_FOUND)
+  public static class NotFoundException extends RuntimeException {
+    public NotFoundException(String message) {
+      super(message);
+    }
+  }
 }

readme.adoc

@@ -193,6 +193,20 @@ Note: You can also send the full profile JSON in the APPLY request body (for con
 as long as Custom.das-simulator-profile is present; the simulator will still load the profile
 from disk and ignore other fields in the request.
 
+=== Remote-control error responses
+
+Remote-control endpoints return structured error responses when requests are invalid or unauthorized.
+
+.Error codes
+|===
+|Error code |HTTP status |When it happens
+
+|RC-400|400|Invalid request payload (missing/invalid JSON or required fields).
+|RC-401|401|Missing or invalid X-Api-Key.
+|RC-404|404|Requested acquisition id not found when stopping.
+|RC-500|500|Unexpected internal error during remote-control handling.
+|===
+
 Details for ProdML can be found here: http://w3.energistics.org/energyML/data/prodml/v2.0/doc/prodml_schema_overview.html
 
 == Building and running