139 lines
2.6 KiB
Markdown
139 lines
2.6 KiB
Markdown
# Plugin Specification
|
|
|
|
## Goal
|
|
|
|
The plugin system should allow additional rack components to be imported without changing application code.
|
|
|
|
Plugins should be data packages, not executable extensions.
|
|
|
|
## Principles
|
|
|
|
- no arbitrary code execution
|
|
- manifest-based validation
|
|
- stable schema versioning
|
|
- internal conversion of optional CAD-derived assets
|
|
|
|
## Package structure
|
|
|
|
Example:
|
|
|
|
```text
|
|
vendor-pack-1/
|
|
manifest.json
|
|
components/
|
|
switch-24p.json
|
|
patchpanel-24p.json
|
|
assets/
|
|
front/
|
|
switch-24p.svg
|
|
patchpanel-24p.svg
|
|
preview3d/
|
|
switch-24p.gltf
|
|
```
|
|
|
|
## Manifest example
|
|
|
|
```json
|
|
{
|
|
"manifestVersion": 1,
|
|
"name": "Example Network Pack",
|
|
"vendor": "Example Vendor",
|
|
"version": "1.0.0",
|
|
"components": [
|
|
"components/switch-24p.json",
|
|
"components/patchpanel-24p.json"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Component definition example
|
|
|
|
```json
|
|
{
|
|
"name": "24-Port Patch Panel",
|
|
"manufacturer": "Example Vendor",
|
|
"partNumber": "PP-24-1U",
|
|
"category": "patch_panel",
|
|
"rackStandard": "19_inch",
|
|
"heightU": 1,
|
|
"depthMm": 95,
|
|
"weightKg": 1.2,
|
|
"priceNet": 79.0,
|
|
"currency": "EUR",
|
|
"assets": {
|
|
"frontSvg": "assets/front/patchpanel-24p.svg"
|
|
},
|
|
"ports": [
|
|
{
|
|
"name": "Port 1",
|
|
"side": "front",
|
|
"offsetXmm": 18,
|
|
"offsetYmm": 10,
|
|
"offsetZmm": 0,
|
|
"portType": "rj45"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Supported file formats
|
|
|
|
### V1 mandatory
|
|
|
|
- `JSON` for manifest and component metadata
|
|
- `SVG` for 2D visuals
|
|
|
|
### V1 optional
|
|
|
|
- `glTF` for future 3D preview assets
|
|
|
|
### Later import formats
|
|
|
|
These should be handled through an import pipeline, not as runtime-native editor formats:
|
|
|
|
- `DXF`
|
|
- `STEP`
|
|
- `OBJ`
|
|
|
|
## Validation rules
|
|
|
|
- schema version must be supported
|
|
- required metadata fields must exist
|
|
- asset references must resolve inside the package
|
|
- all dimensions must be plausible and positive
|
|
- category values must match allowed enums
|
|
- unsupported formats are rejected or ignored
|
|
|
|
## Security model
|
|
|
|
Plugins must never contain executable JavaScript for the editor.
|
|
|
|
Allowed plugin content:
|
|
|
|
- metadata
|
|
- images
|
|
- vector graphics
|
|
- optional validated model assets
|
|
|
|
Rejected:
|
|
|
|
- scripts
|
|
- external network callbacks
|
|
- embedded active content
|
|
|
|
## Import workflow
|
|
|
|
1. upload package
|
|
2. unpack in isolated temporary storage
|
|
3. validate manifest
|
|
4. validate component schema
|
|
5. validate assets
|
|
6. register catalog entries
|
|
7. make components available to selected users or globally
|
|
|
|
## Versioning strategy
|
|
|
|
- application schema versioning is independent from plugin pack version
|
|
- manifest schema must be explicitly versioned
|
|
- deprecated fields should have a migration path where possible
|