DevContainer User
51 lines
1.9 KiB
Markdown
51 lines
1.9 KiB
Markdown
# ADR 002: extractJsonData() Pattern for KubeObject Unwrapping
|
|
|
|
**Status**: Accepted
|
|
|
|
**Date**: 2026-03-05
|
|
|
|
**Deciders**: Development Team
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
Headlamp's `useList()` hooks return arrays of `KubeObject` class instances that wrap raw JSON under `.jsonData`. The plugin's type system defines plain TypeScript interfaces (e.g., `CephCluster`, `StorageClass`) matching the raw Kubernetes JSON structure.
|
|
|
|
To use these typed interfaces, the `KubeObject` wrapper must be unwrapped. This pattern appears in every plugin that uses `useList()` hooks.
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
Implement an `extractJsonData()` utility function that takes a `KubeObject` instance and returns the unwrapped `.jsonData` property.
|
|
|
|
- Apply this consistently to all `useList()` results before storing in context state.
|
|
- All type guards (e.g., `isRookCephProvisioner()`, `isRookCephStorageClass()`) operate on the unwrapped plain objects, not on `KubeObject` wrappers.
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
- ✅ Clean separation between Headlamp's class instances and the plugin's typed interfaces
|
|
- ✅ Type guards work on plain objects, which are easier to test
|
|
- ✅ Consistent unwrapping pattern across all resources
|
|
- ⚠️ Extra mapping step on every `useList()` result
|
|
- ⚠️ Runtime cost of mapping arrays (negligible for typical cluster sizes of tens to hundreds of resources)
|
|
|
|
---
|
|
|
|
## Alternatives Considered
|
|
|
|
1. **Use `KubeObject` instances directly** — Rejected. Type guards and filters become harder to write and test with class wrappers.
|
|
|
|
2. **Type assertion (`as CephCluster`)** — Rejected. Unsafe with no runtime validation; silently masks shape mismatches.
|
|
|
|
3. **Custom hook wrapping `useList()` with auto-extraction** — Considered but `extractJsonData()` is simpler and more explicit. A wrapper hook would hide the unwrapping step, making the data flow less obvious.
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
- 2026-03-05: Initial decision accepted
|