rustfs/crates/targets/AGENTS.md

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
• Full gate before commit: make pre-commit