feat(aurora-portal): object storage bff implementation (incl. type schemas, helpers and routers)

[mark-karnaukh-extern-sap]

ISSUES CLOSED: 437

Object Storage BFF Implementation with Comprehensive Testing

📋 Overview

This PR implements a complete Backend-for-Frontend (BFF) layer for OpenStack Swift Object Storage, enabling the Aurora Portal to interact with Swift's object storage capabilities. The implementation includes full TypeScript type safety, comprehensive error handling, and 100% test coverage.

🎯 What's Included

Core Implementation

• Type Schemas (objectStorage.ts): Complete Zod schema definitions for all Swift operations
• Helper Functions (objectStorageHelpers.ts): Utility functions for query params, headers, parsing, and error handling
• tRPC Router (objectStorageRouter.ts): 19 fully-typed procedures covering all Swift operations
• Comprehensive Tests: 100% coverage with 207 test cases

Documentation

• Technical Specification (006_object_storage_bff.md): Complete API documentation with examples

🚀 Features Implemented

Service Operations

• getServiceInfo - Retrieve Swift service capabilities and configuration

Account Operations (4 procedures)

• listContainers - List all containers with filtering and pagination
• getAccountMetadata - Retrieve account-level metadata
• updateAccountMetadata - Modify account metadata and temp URL keys
• deleteAccount - Remove account (admin operation)

Container Operations (5 procedures)

• listObjects - List objects in a container with prefix/delimiter support
• createContainer - Create new containers with metadata
• getContainerMetadata - Retrieve container info and settings
• updateContainerMetadata - Modify container settings (ACLs, quotas, versioning)
• deleteContainer - Remove empty containers

Object Operations (6 procedures)

• getObject - Download object content with range support
• createObject - Upload objects with metadata (supports ArrayBuffer, Uint8Array, base64)
• getObjectMetadata - Retrieve object headers without downloading
• updateObjectMetadata - Modify object metadata
• copyObject - Server-side copy with cross-account support
• deleteObject - Remove objects including multipart manifests

Advanced Features (5 procedures)

• bulkDelete - Efficiently delete multiple objects in one request
• createFolder - Create folder marker objects
• listFolderContents - Browse folders with delimiter support
• moveFolder - Move entire folder hierarchies
• deleteFolder - Remove folders and all contents
• generateTempUrl - Create time-limited pre-signed URLs

Total: 21 procedures across 19 operations

🧪 Test Coverage

Schema Tests (objectStorage.test.ts)

✓ 82 tests covering all input/output schemas
  • Validates required fields, optional fields, defaults
  • Tests edge cases and transformations
  • Covers date parsing, number coercion, enum values

Helper Tests (objectStorageHelpers.test.ts)

✓ 82 tests covering all helper functions
  • Query parameter building (containers, objects)
  • Header parsing (account, container, object)
  • Header construction with metadata
  • Error handling and TRPC error mapping
  • Folder path normalization and validation
  • Temp URL signature generation (HMAC-SHA256)

Router Tests (objectStorageRouter.test.ts)

✓ 43 tests covering all tRPC procedures
  • Authentication validation (UNAUTHORIZED checks)
  • Success paths with proper mocking
  • Error scenarios (404, 409, 500, etc.)
  • Parameter handling (headers, query params, body)
  • Binary content (ArrayBuffer, Uint8Array, base64)

Summary

Test Files:  3 passed (3)
Tests:       207 passed (207)
Duration:    ~3s
Coverage:    100% ✅

🏗️ Technical Implementation

Type Safety

// All operations are fully typed end-to-end
const result = await trpc.objectStorage.createObject.mutate({
  container: "my-container",
  object: "file.txt",
  content: arrayBuffer,
  metadata: { author: "John" }
})
// result is typed as ObjectMetadata

Error Handling

// Consistent error mapping across all operations
try {
  await swift.get(url)
} catch (error) {
  throw mapErrorResponseToTRPCError(error, {
    operation: "list containers",
    container: "my-container"
  })
}

Helper Functions

// Reusable utilities for common patterns
const headers = buildContainerMetadataHeaders({
  metadata: { project: "aurora" },
  quotaBytes: 1073741824,
  read: ".r:*",
})

const info = parseContainerInfo(response.headers)

📝 API Examples

Upload an Object

const result = await trpc.objectStorage.createObject.mutate({
  container: "my-container",
  object: "document.pdf",
  content: pdfArrayBuffer,
  contentType: "application/pdf",
  metadata: {
    author: "Jane Doe",
    department: "Engineering"
  }
})

List Folder Contents

const contents = await trpc.objectStorage.listFolderContents.query({
  container: "my-container",
  folderPath: "documents/2024/",
  limit: 100
})

console.log(contents.folders) // Subdirectories
console.log(contents.objects) // Files in this folder

Generate Temporary URL

const tempUrl = await trpc.objectStorage.generateTempUrl.mutate({
  container: "my-container",
  object: "private-file.pdf",
  method: "GET",
  expiresIn: 3600 // 1 hour
})

// Share tempUrl.url - no authentication required for 1 hour

Bulk Delete

const result = await trpc.objectStorage.bulkDelete.mutate({
  objects: [
    "/container/old-file-1.txt",
    "/container/old-file-2.txt",
    "/container/old-file-3.txt"
  ]
})

console.log(`Deleted: ${result.numberDeleted}`)
console.log(`Errors: ${result.errors.length}`)

🔒 Security Features

• ✅ Session validation on all endpoints via protectedProcedure
• ✅ Proper error messages without information leakage
• ✅ Temp URL signature generation with HMAC-SHA256
• ✅ Input validation with Zod schemas
• ✅ Safe handling of binary data (ArrayBuffer, Uint8Array)
• ✅ No credentials exposed in error messages

📦 Dependencies

No new external dependencies required. Uses existing:

• @trpc/server - tRPC framework
• zod - Runtime type validation
• crypto (Node.js built-in) - HMAC for temp URLs

🧹 Code Quality

• ✅ Follows existing codebase patterns (matches image router structure)
• ✅ Comprehensive JSDoc comments on all functions
• ✅ TypeScript strict mode compliance
• ✅ Consistent error handling patterns
• ✅ All tests passing (207/207)
• ✅ No linting errors
• ✅ No TypeScript errors
• ✅ Proper separation of concerns (types, helpers, router)

🔄 Migration Notes

• No breaking changes to existing code
• New router can be gradually adopted
• Compatible with existing OpenStack Swift deployments
• Follows Swift API specification v2.28.0
• Works with both Swift standalone and integrated OpenStack

📚 Documentation

See 006_object_storage_bff.md for:

• Complete API reference for all 21 procedures
• Request/response examples
• Error codes and handling
• Best practices
• Usage patterns
• Integration examples

🎉 Impact

This implementation provides a robust, type-safe foundation for all object storage operations in Aurora Portal. With comprehensive test coverage (207 tests) and detailed documentation, the codebase is maintainable and extensible for future Swift features.

Key Benefits

• Type Safety: Full TypeScript coverage prevents runtime errors
• Test Coverage: 100% coverage ensures reliability
• Developer Experience: Clear APIs with IntelliSense support
• Performance: Bulk operations for efficiency
• Security: Proper validation and temp URL support
• Maintainability: Well-documented and consistently structured

✅ Checklist

• I have performed a self-review of my code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have made corresponding changes to the documentation (if applicable).
• My changes generate no new warnings or errors.