Skip to main content

Plugin Lifecycle

+-----------+     +------------+     +----------+     +-----------+
|  Install  | --> |  Discover  | --> |  Loaded  | --> |  Unload   |
+-----------+     +------------+     +----------+     +-----------+

Install​

  • arcan plugin install postgres downloads .arcanpkg from registry.
  • Package is verified: checksum match, signature valid.
  • Extracted to ~/.arcan/plugins/postgres/.

Discover​

  • On startup, core scans ~/.arcan/plugins/ for extracted packages.
  • Core reads each package's manifest.json (descriptor).
  • Validates SDK version compatibility.
  • Plugin is registered in the engine registry.

Loaded​

  • On first request to that engine type, core loads the plugin code into the sandboxed runtime.
  • Subsequent requests reuse the loaded runtime instance.
  • Since plugins are sandboxed code (not separate processes), there is no process management, no health checking for liveness, and no crash recovery needed. If the sandboxed code throws an error, it is caught and returned as an engine error.

Unload​

  • arcan plugin remove postgres calls Shutdown() on the loaded engine and removes the package.

Upgrade Flow​

  • arcan plugin update postgres downloads new package, verifies signature.
  • Old plugin is unloaded, new plugin loaded on next request.

Health Check​

  • Core calls Ping() on loaded engines periodically (every 30s) to verify external system connectivity (not plugin liveness -- the plugin IS the core).
  • Three consecutive Ping failures mark the engine as degraded and log a warning.
  • Degraded engines still accept requests (they might recover).