# Targets Crate Instructions
Applies to `crates/targets/`.
`rustfs-targets` is the shared target-plugin foundation for `audit` and
`notify`. It owns plugin metadata, builtin target descriptors, runtime
orchestration primitives, and plugin control-plane state modeling.
## Current Module Boundaries
- `manifest.rs`: declarative plugin metadata and marketplace-facing shape.
Keep this layer declarative only; do not add runtime execution logic here.
- `catalog/`: centralized builtin descriptor registration and example external
plugin assembly. Keep admin-facing plugin source data here instead of
spreading it into handlers.
- `plugin.rs`: `TargetPluginDescriptor`, `TargetPluginRegistry`,
`BuiltinTargetDescriptor`, and admin descriptor metadata.
- `runtime/`: shared runtime lifecycle and replay orchestration:
`TargetRuntimeManager`, `ReplayWorkerManager`, `PluginRuntimeAdapter`,
`BuiltinPluginRuntimeAdapter`, and sidecar protocol/runtime MVP types.
- `control_plane.rs`: install/enable/runtime state models and install policy
validation helpers. Keep install/governance state logic centralized here.
- `config/`, `target/`, `store/`, `check/`: target config normalization,
target implementations, queue/store, and endpoint connectivity checks.
## Change Style and Ownership Rules
- Preserve the layering above. Do not move install/runtime/governance logic
into admin handlers or manifest structs.
- Prefer extending shared abstractions (`TargetPluginRegistry`,
`PluginRuntimeAdapter`, `TargetRuntimeManager`) over duplicating per-domain
orchestration logic.
- Keep external sidecar behavior scoped to current MVP boundaries unless the
task explicitly includes real installer/transport integration.
- Reuse existing constants/keys from `rustfs_config`; avoid introducing
duplicate literals for target field names and subsystem keys.
## Library Design
- Treat crate code as reusable library code by default.
- Return structured `TargetError`/`StoreError` results; avoid panic-driven
control flow outside tests.
- Keep serialization contracts stable for types re-exported by `lib.rs`.
## Testing
- Keep unit tests close to the module they test.
- Keep integration tests under `crates/targets/tests/`.
- Add regression tests for behavior changes in:
- plugin manifest/catalog/control-plane contracts
- runtime adapter lifecycle behavior
- target config normalization and validation
- sidecar handshake/policy validation paths
## Async and Performance
- Keep async paths non-blocking.
- Avoid hot-path allocations and repeated config normalization when a cached
snapshot can be reused.
- Use bounded concurrency and timeout guards for runtime and health checks.
## Integration Tests
Integration tests under `tests/` are `#[ignore]` by default so CI never runs
them. See module-level doc comments in each test file for prerequisites and
run commands.
- `tests/mysql_integration.rs` — MySQL 8.0+ / TiDB 8.5+
- `tests/postgres_integration.rs` — PostgreSQL
## Suggested Validation
- `cargo test -p rustfs-targets`
- If runtime/plugin contracts changed, run focused tests under:
- `cargo test -p rustfs-targets plugin`
- `cargo test -p rustfs-targets runtime`
- `cargo test -p rustfs-targets control_plane`