ITEP-92735: Mapping service should communicate with outside world over proxy (#1469)

This PR updates SceneScape’s mapping service exposure so external clients access it through the manager’s Apache reverse proxy (instead of directly via :8444), aligning service-to-outside-world communication with the existing proxy pattern used for autocalibration.

Author: saratpoluri

.github/copilot-instructions.md

@@ -129,33 +129,15 @@ make rebuild-core                  # Clean + build (useful after code changes)
 
 ## Testing Framework
 
-**For comprehensive test creation guidance, see `.github/skills/testing/SKILL.md`** - detailed instructions on creating unit, functional, integration, UI, and smoke tests with both positive and negative cases.
+Testing guidance is intentionally centralized in skills to avoid duplication.
 
-**Test infrastructure** is fully pytest-based. Docker Compose lifecycle is managed by session-scoped fixtures in `tests/conftest.py`. Tests declare their service requirements via a module-level `SCENESCAPE_SPEC` using `FuncTestSpec` + `ServiceProfile`.
+- Canonical test authoring and categorization guidance: `.github/skills/testing/SKILL.md`
+- Canonical runtime verification and completion rules: `.github/skills/test-verification-gate/SKILL.md`
 
-**Running Tests** (from repo root):
+At this level, only rely on high-level routing:
 
-```bash
-make setup-tests                                            # Build test images, secrets, venv
-make run_basic_acceptance_tests                             # Smoke tests (functional + ui + unit + stability)
-make run_standard_tests                                     # Functional + UI + security + stability
-make run_functional_tests                                   # Functional tests only
-make run_ui_tests                                           # UI/Selenium tests only
-make run_unit_tests                                         # Unit tests only (sscape_tests)
-make run_metric_tests                                       # Tracker quality metrics
-make run_performance_tests                                  # Inference performance + geometry
-make run_stability_tests HOURS=24                           # Long-running stability
-```
-
-**Running tests directly with pytest** (from repo root, with tests/.venv activated):
-
-```bash
-pytest tests/sscape_tests                                   # Unit tests
-pytest tests/functional                                     # All functional tests
-pytest tests/functional/test_roi_mqtt.py                    # Single functional test
-pytest tests/ -m basic_acceptance                           # Smoke suite only
-pytest tests/ --junitxml=results.xml 2>&1 | tee output.log  # Save results to file
-```
+- Test infrastructure is pytest-based with Docker Compose lifecycle managed in `tests/conftest.py`.
+- Prefer root `Makefile` test targets for execution unless a narrower, explicit pytest invocation is required.
 
 ### Completion Gate For Test Tasks (Critical)
 

Makefile

@@ -736,7 +736,13 @@ init-secrets: $(SECRETSDIR) certificates auth-secrets
 
 $(SECRETSDIR):
 	mkdir -p $@
-	chmod go-rwx $(SECRETSDIR)
+	@if ! chmod go-rwx $(SECRETSDIR); then \
+		if [ "$${CI}" = "true" ] || [ "$${CI}" = "1" ]; then \
+			echo "Warning: could not set restrictive permissions on $(SECRETSDIR) in CI; secrets may be more exposed on this filesystem. Ensure runner isolation controls are in place."; \
+		else \
+			exit 1; \
+		fi; \
+	fi
 
 .PHONY: $(SECRETSDIR) certificates
 certificates:

autocalibration/src/auto_camera_calibration_api.py

@@ -130,7 +130,7 @@ def __init__(self, calibrationContext=None):
     self.app.config['MAX_CONTENT_LENGTH'] = self.MAX_REQUEST_SIZE
     self.calibrationContext = calibrationContext
 
-    self.socketio = SocketIO(self.app, cors_allowed_origins=["*"])
+    self.socketio = SocketIO(self.app, path="/v1/socket.io/", cors_allowed_origins=["*"])
     if self.calibrationContext is not None:
       self.calibrationContext.socketio = self.socketio
     self.socket_client = {}

autocalibration/src/autocalibration_client.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+from scene_common.rest_client import RESTClient
+
+
+class AutoCalibrationClient(RESTClient):
+  """Client for auto-calibration REST endpoints."""
+
+  def getStatus(self):
+    """Gets auto-calibration service status."""
+    return self._get("status", None)
+
+  def registerScene(self, sceneId, data):
+    """Register a scene for auto-calibration."""
+    return self._create(f"scenes/{sceneId}/registration", data)
+
+  def getSceneRegistrationStatus(self, sceneId):
+    """Gets scene registration status."""
+    return self._get(f"scenes/{sceneId}/registration", None)
+
+  def updateSceneRegistration(self, sceneId, data):
+    """Updates scene registration."""
+    return self._update(f"scenes/{sceneId}/registration", data)
+
+  def calibrateCamera(self, cameraId, data):
+    """Calibrate a camera."""
+    return self._create(f"cameras/{cameraId}/calibration", data)
+
+  def getCameraCalibrationStatus(self, cameraId):
+    """Gets camera calibration status."""
+    return self._get(f"cameras/{cameraId}/calibration", None)

common.mk

@@ -31,6 +31,7 @@ build-image: $(BUILD_DIR) Dockerfile
 	@{ \
 		set -xe; \
 		set -o pipefail; \
+		EXTRA_BUILD_ARGS="$(EXTRA_BUILD_ARGS)"; \
 		if [ "$(GHCR_CACHE)" = "true" ]; then \
 		  EXTRA_BUILD_ARGS+=" --cache-from type=registry,ref=ghcr.io/${CACHE_REGISTRY}/$(IMAGE):main"; \
 			if [ "$(WRITE_CACHE)" = "true" ]; then \

docs/user-guide/microservices/auto-calibration/_assets/autocalibration-api.yaml

@@ -17,6 +17,9 @@ info:
 
 servers:
   - url: "https://localhost:8443/v1"
+    description: Direct standalone access
+  - url: "https://localhost/api/v1/autocalibration"
+    description: Access via Apache reverse proxy when web service is running
 
 components:
   schemas:

docs/user-guide/microservices/mapping-service/api-docs/mapping-api.yaml

@@ -7,6 +7,10 @@ info:
   description: |
     REST API service for 3D reconstruction with build-time model selection.
 
+    Authentication/Authorization status:
+    - This service currently does not implement endpoint-level AuthN/AuthZ.
+    - Protect access using trusted network boundaries, reverse proxy controls, and TLS.
+
     This service provides endpoints for performing 3D reconstruction from multiple input images. The model is selected at build time:
     - **MapAnything**: Universal Feed-Forward Metric 3D Reconstruction
     - **VGGT**: Visual Geometry Grounded Transformer for sparse view reconstruction
@@ -18,10 +22,10 @@ info:
     url: https://www.apache.org/licenses/LICENSE-2.0.html
 
 servers:
-  - url: https://localhost:8444
-    description: Local development server
-  - url: https://0.0.0.0:8444
-    description: Docker container server
+  - url: https://localhost:8444/v1
+    description: Direct standalone access
+  - url: https://localhost/api/v1/mapping
+    description: Access via Apache reverse proxy when web service is running
 
 tags:
   - name: reconstruction

docs/user-guide/microservices/mapping-service/build-from-source.md

@@ -111,7 +111,7 @@ The response will include which model was used:
 ### Health Check
 
 ```bash
-curl https://localhost:8444/health
+curl https://localhost:8444/v1/health
 ```
 
 Response includes model information:
@@ -128,7 +128,7 @@ Response includes model information:
 ### Model Information
 
 ```bash
-curl https://localhost:8444/models
+curl https://localhost:8444/v1/models
 ```
 
 Response shows single model details:

docs/user-guide/microservices/mapping-service/mapping-service.md

@@ -43,6 +43,10 @@ sequenceDiagram
 
 ## API Endpoints
 
+> **Security note:** Mapping service endpoints currently do not enforce endpoint-level
+> authentication or authorization. Deploy behind trusted network boundaries and reverse
+> proxy controls, and use TLS for transport protection.
+
 ### Health Check
 
 ```bash
@@ -130,34 +134,40 @@ the service from source and running it.
 ```python
 import base64
 import requests
-
-# Encode images to base64
-def encode_image(image_path):
-    with open(image_path, "rb") as f:
-        return base64.b64encode(f.read()).decode('utf-8')
-
-# Prepare request
-payload = {
-    "images": [
-        {"data": encode_image("image1.jpg"), "filename": "image1.jpg"},
-        {"data": encode_image("image2.jpg"), "filename": "image2.jpg"}
-    ],
-    "output_format": "glb"
+from pathlib import Path
+
+# Prepare multipart request
+files = []
+handles = []
+for image_path in ["image1.jpg", "image2.jpg"]:
+  path = Path(image_path)
+  handle = path.open("rb")
+  handles.append(handle)
+  files.append(("images", (path.name, handle, "image/jpeg")))
+
+data = {
+  "output_format": "glb",
+  "mesh_type": "mesh",
 }
 
-# Send request
-response = requests.post("https://localhost:8444/reconstruction", json=payload)
-result = response.json()
+try:
+try:
+  # Send request through the Apache reverse proxy used in the full stack deployment
+  response = requests.post("https://localhost/api/v1/mapping/reconstruction", data=data, files=files, verify=False)
+  result = response.json()
 
-if result["success"]:
+  if result["success"]:
     # Save GLB file
     glb_data = base64.b64decode(result["glb_data"])
     with open("output.glb", "wb") as f:
-        f.write(glb_data)
+      f.write(glb_data)
 
     print(f"Model used: {result['model']}")
     print(f"Processing time: {result['processing_time']:.2f}s")
     print(f"Camera poses: {len(result['camera_poses'])}")
+finally:
+  for handle in handles:
+    handle.close()
 ```
 
 ### Using the Included Client
@@ -175,29 +185,29 @@ python client_example.py --images image1.jpg image2.jpg --mesh-type pointcloud -
 
 ```bash
 # Health check
-curl https://localhost:8444/health --insecure
+curl https://localhost:8444/v1/health --insecure
 
 # List models
-curl https://localhost:8444/models --insecure
+curl https://localhost:8444/v1/models --insecure
 
 # Reconstruction with images (using multipart/form-data - recommended)
-curl -X POST "https://localhost:8444/reconstruction" \
+curl -X POST "https://localhost:8444/v1/reconstruction" \
   -F "images=@image1.jpg" \
   -F "images=@image2.jpg" \
   -F "output_format=glb" \
   -F "mesh_type=mesh" \
   --insecure
 
 # Reconstruction with video
-curl -X POST "https://localhost:8444/reconstruction" \
+curl -X POST "https://localhost:8444/v1/reconstruction" \
   -F "video=@video.mp4" \
   -F "output_format=glb" \
   -F "mesh_type=mesh" \
   -F "use_keyframes=true" \
   --insecure
 
 # Reconstruction with both images and video
-curl -X POST "https://localhost:8444/reconstruction" \
+curl -X POST "https://localhost:8444/v1/reconstruction" \
   -F "images=@image1.jpg" \
   -F "images=@image2.jpg" \
   -F "video=@video.mp4" \
@@ -206,7 +216,7 @@ curl -X POST "https://localhost:8444/reconstruction" \
   --insecure
 
 # Save GLB output to file (requires jq for JSON parsing)
-curl -X POST "https://localhost:8444/reconstruction" \
+curl -X POST "https://localhost:8444/v1/reconstruction" \
   -F "images=@image1.jpg" \
   -F "images=@image2.jpg" \
   -F "output_format=glb" \

kubernetes/scenescape-chart/templates/mapping/deployment.yaml

@@ -42,7 +42,7 @@ spec:
               command:
               - sh
               - -c
-              - curl -k -s https://localhost:8444/health
+              - curl -k -s https://localhost:8444/v1/health
             periodSeconds: 10
             timeoutSeconds: 60
             failureThreshold: 5