Create service to upload assets to DAM

Problem/Motivation

Create the acquia_dam.upload_service in the parent acquia_dam module that handles file uploads to Acquia DAM via its API. This service does not exist today and is a prerequisite for the queue-based migration worker.

Files to Create / Modify

• NEW src/Services/AcquiaDamUploadService.php (parent acquia_dam module)
• NEW src/Services/AcquiaDamUploadServiceInterface.php
• UPDATE acquia_dam.services.yml (parent module)
• NEW tests/src/Unit/Services/AcquiaDamUploadServiceTest.php
• NEW tests/src/Kernel/Services/AcquiaDamUploadServiceTest.php

Interface (AcquiaDamUploadServiceInterface.php)

• uploadFile(string $file_path, array $metadata): ?string — Uploads a local file to DAM, returns asset ID or null on failure
• uploadFromUri(string $uri, array $metadata): ?string — Uploads from a Drupal stream wrapper URI (e.g., public://images/photo.jpg)
• getUploadStatus(string $upload_id): array — Check status of an async upload
• validateFile(string $file_path): bool — Pre-upload validation (file exists, size limits, allowed extensions)

Service Implementation (AcquiaDamUploadService.php)

• Inject acquia_dam.client (existing HTTP client for DAM API) and file_system service
• uploadFile() logic:
  1. Validate file exists and is readable
  2. Determine MIME type via file.mime_type.guesser
  3. Prepare multipart request with file binary + metadata (filename, description, folder, category)
  4. POST to Acquia DAM Upload API endpoint
  5. Parse response → extract and return asset_id
  6. Handle API errors (auth failure, quota exceeded, invalid format) with typed exceptions
• uploadFromUri() — Resolve Drupal URI to real path via file_system->realpath(), delegate to uploadFile()
• validateFile() — Check file size against DAM limits, validate extension against allowed types
• Configurable retry logic (max 3 retries with exponential backoff for transient failures)
• Logging via logger.factory for all upload attempts (success + failure)

Custom Exceptions

• DamUploadException — Base exception
• DamAuthenticationException — API auth/token errors
• DamQuotaExceededException — Storage quota exceeded
• DamFileValidationException — Invalid file type/size

Test Coverage

• Unit tests: Mock DAM client, test upload flow, error handling, retry logic, file validation
• Kernel tests: Test service wiring, Drupal URI resolution, integration with acquia_dam.client

Acceptance Criteria

• Service registered as acquia_dam.upload_service in parent module's services.yml
• Successfully uploads a file and returns a valid DAM asset ID
• Handles all error scenarios with typed exceptions (auth, quota, validation, network)
• Retry logic works for transient API failures (3 retries, exponential backoff)
• File validation rejects oversized files and disallowed extensions before upload attempt
• Service is reusable by any submodule (not coupled to migration logic)