The plugin contract defines optional init, onMigrate, onEnable, and onDisable callbacks. These hooks represent different responsibilities and should not be treated as interchangeable.
init: prepare plugin-owned runtime state.onMigrate: perform plugin migration-related work when the host's migration lifecycle invokes it.onEnable: react to activation, optionally receiving context.onDisable: release or stop plugin behavior.
The presence of a callback on the interface does not mean every host integration automatically calls it at a particular time. Verify the installed registry/provider lifecycle and test the behavior in the application composition you use.
Idempotency#
Make lifecycle callbacks safe to retry where possible. Avoid irreversible external side effects during initialization; if a callback sends messages, provisions resources, or changes remote systems, use idempotency keys and explicit failure recovery.
Migrations#
Version schema changes and avoid destructive plugin migrations during request-time activation. If plugins can be disabled, decide whether their data is retained, migrated, or deleted; disabling a plugin should not silently erase customer data.
Cleanup#
Release timers, listeners, subscriptions, and external clients when a plugin is disabled or the application shuts down. Tests should verify that repeated activation does not duplicate event listeners or scheduled jobs.
