story(machine): implement PUT /api/v1/machines/{id} endpoint

[Zaba505]

Description

Implement HTTP REST API endpoint for updating a machine's hardware profile. This allows administrators to update machine specifications when hardware is upgraded or reconfigured.

Acceptance Criteria

• Endpoint created in services/machine/endpoint/put_machine.go
• Route: PUT /api/v1/machines/{id}
• Implements OpenAPI-first handler pattern (z5labs/humus):
  • RequestBody() method defining OpenAPI request schema
  • Responses() method defining OpenAPI response schemas
  • ServeHTTP() method implementing HTTP handler logic
• Path parameter validation:
  • Extract machine ID from path
  • Validate UUIDv7 format
  • Return HTTP 400 Bad Request with RFC 7807 Problem Details for invalid format
• Request body validation:
  • Accept full machine profile JSON (same as POST)
  • Validate at least one NIC is provided
  • Validate MAC address format
  • Return HTTP 400 Bad Request with RFC 7807 Problem Details for validation errors
• Machine existence check:
  • Query Firestore to verify machine exists
  • Return HTTP 404 Not Found with RFC 7807 Problem Details if not found
• MAC address uniqueness check (if MAC changed):
  • Query Firestore for duplicate MAC addresses
  • Exclude current machine from uniqueness check
  • Return HTTP 409 Conflict if MAC already exists on different machine
• Firestore integration:
  • Update machine profile in machines/{id} collection
  • Use protobuf message format
  • Handle Firestore errors gracefully
• Response:
  • HTTP 200 OK on success
  • Return full updated machine profile
  • Include machine ID in response
• Error responses use RFC 7807 Problem Details format:
  • Content-Type: application/problem+json
  • Include type, title, status, detail, instance fields
  • Validation errors include invalid_fields array
  • 404 response includes machine_id field
• OpenTelemetry instrumentation:
  • Log machine updates with machine_id, changed fields
  • Metrics: update count, success/failure rate
  • Trace context propagation
• Unit tests:
  • Test successful machine update
  • Test machine not found (404)
  • Test validation errors (missing NICs, invalid MAC)
  • Test duplicate MAC address conflict (409)
  • Test invalid machine ID format (400)
  • Mock Firestore client
  • Test protobuf message serialization

Related Issues

Part of Machine Service implementation
Related to API documentation in docs/content/r&d/services/machine-mgmt/put-machine.md