Asset Entry Metadata Normalization Contract
This commit is contained in:
+33
@@ -0,0 +1,33 @@
|
||||
# LSN-0023: Typed Helpers for Asset Metadata
|
||||
|
||||
Status: Published
|
||||
Decisions: [[DEC-0004]]
|
||||
Tags: [asset, runtime, rust, pattern]
|
||||
|
||||
## Contexto
|
||||
|
||||
A decisão [[DEC-0004]] estabeleceu um contrato de metadados segmentados para assets, mantendo campos críticos na raiz do JSON e detalhes técnicos em subárvores (`codec`, `pipeline`). No entanto, o `AssetEntry.metadata` no runtime é um `serde_json::Value` dinâmico.
|
||||
|
||||
## Lição
|
||||
|
||||
O uso de `serde_json::Value` diretamente nos loaders do runtime introduz riscos de runtime (erros de tipo, campos ausentes) e polui o código com chamadas repetitivas de `.get()`, `.as_u64()`, etc.
|
||||
|
||||
### Abordagem Adotada
|
||||
|
||||
Para mitigar isso, implementamos o padrão de **Typed Metadata Helpers**:
|
||||
|
||||
1. **Structs Dedicadas**: Criamos structs Rust (ex: `TilesMetadata`, `SoundsMetadata`) que representam o contrato exato de cada banco.
|
||||
2. **Conversion Methods**: Adicionamos métodos ao `AssetEntry` (ex: `metadata_as_tiles()`) que utilizam `serde_json::from_value` para realizar o "cast" do JSON dinâmico para a struct tipada.
|
||||
3. **Fail-Fast**: A falha no parsing dos metadados deve ser tratada como erro de carregamento do asset, garantindo que o motor não opere com metadados corrompidos ou incompletos.
|
||||
|
||||
### Benefícios
|
||||
|
||||
- **Segurança de Tipo**: Erros de estrutura de metadados são detectados no momento do carregamento.
|
||||
- **Ergonomia**: O código dos drivers passa a usar `meta.tile_size` em vez de parsing manual.
|
||||
- **Desacoplamento**: A complexidade do JSON fica encapsulada nos helpers de conversão.
|
||||
|
||||
## Referências
|
||||
|
||||
- DEC-0004: Asset Entry Metadata Normalization Contract
|
||||
- `prometeu-hal/src/asset.rs`
|
||||
- `prometeu-drivers/src/asset.rs`
|
||||
Reference in New Issue
Block a user