monibuca/doc/arch/plugin.md

# Plugin System

Monibuca adopts a plugin-based architecture design, extending functionality through its plugin mechanism. The plugin system is one of Monibuca's core features, allowing developers to add new functionality in a modular way without modifying the core code.

## Plugin Lifecycle

The plugin system has complete lifecycle management, including the following phases:

### 1. Registration Phase

Plugins are registered using the `InstallPlugin` generic function, during which:

- Plugin metadata (PluginMeta) is created, including:
  - Plugin name: automatically extracted from the plugin struct name (removing "Plugin" suffix)
  - Plugin version: extracted from the caller's file path or package path, defaults to "dev" if not extractable
  - Plugin type: obtained through reflection of the plugin struct type
  
- Optional features are registered:
  - Exit handler (OnExitHandler)
  - Default configuration (DefaultYaml)
  - Puller
  - Pusher
  - Recorder
  - Transformer
  - Publish authentication (AuthPublisher)
  - Subscribe authentication (AuthSubscriber)
  - gRPC service (ServiceDesc)
  - gRPC gateway handler (RegisterGRPCHandler)

- Plugin metadata is added to the global plugin list

The registration phase is the first stage in a plugin's lifecycle, providing the plugin system with basic information and functional definitions, preparing for subsequent initialization and startup.

### 2. Initialization Phase (Init)

Plugins are initialized through the `Plugin.Init` method, including these steps:

1. Instance Verification
   - Check if the plugin implements the IPlugin interface
   - Get plugin instance through reflection

2. Basic Setup
   - Set plugin metadata and server reference
   - Configure plugin logger
   - Set plugin name and version information

3. Environment Check
   - Check if plugin is disabled by environment variables ({PLUGIN_NAME}_ENABLE=false)
   - Check global disable status (DisableAll)
   - Check enable status in user configuration (enable)

4. Configuration Loading
   - Parse common configuration
   - Load default YAML configuration
   - Merge user configuration
   - Apply final configuration and log

5. Database Initialization (if needed)
   - Check database connection configuration (DSN)
   - Establish database connection
   - Auto-migrate database tables (for recording functionality)

6. Status Recording
   - Record plugin version
   - Record user configuration
   - Set log level
   - Record initialization status

If errors occur during initialization:
- Plugin is marked as disabled
- Disable reason is recorded
- Plugin is added to the disabled plugins list

The initialization phase prepares necessary environment and resources for plugin operation, crucial for ensuring normal plugin operation.

### 3. Startup Phase (Start)

Plugins start through the `Plugin.Start` method, executing these operations in sequence:

1. gRPC Service Registration (if configured)
   - Register gRPC service
   - Register gRPC gateway handler
   - Handle gRPC-related errors

2. Plugin Management
   - Add plugin to server's plugin list
   - Set plugin status to running

3. Network Listener Initialization
   - Start HTTP/HTTPS services
   - Start TCP/TLS services (if implementing ITCPPlugin interface)
   - Start UDP services (if implementing IUDPPlugin interface)
   - Start QUIC services (if implementing IQUICPlugin interface)

4. Plugin Initialization Callback
   - Call plugin's OnInit method
   - Handle initialization errors

5. Timer Task Setup
   - Configure server keepalive task (if enabled)
   - Set up other timer tasks

If errors occur during startup:
- Error reason is recorded
- Plugin is marked as disabled
- Subsequent startup steps are stopped

The startup phase is crucial for plugins to begin providing services, with all preparations completed and ready for business logic processing.

### 4. Stop Phase (Stop)

The plugin stop phase is implemented through the `Plugin.OnStop` method and related stop handling logic, including:

1. Service Shutdown
   - Stop all network services (HTTP/HTTPS/TCP/UDP/QUIC)
   - Close all network connections
   - Stop processing new requests

2. Resource Cleanup
   - Stop all timer tasks
   - Close database connections (if any)
   - Clean up temporary files and cache

3. Status Handling
   - Update plugin status to stopped
   - Remove from server's active plugin list
   - Trigger stop event notifications

4. Callback Processing
   - Call plugin's custom OnStop method
   - Execute registered stop callback functions
   - Handle errors during stop process

5. Connection Handling
   - Wait for current request processing to complete
   - Gracefully close existing connections
   - Reject new connection requests

The stop phase aims to ensure plugins can safely and cleanly stop running without affecting other parts of the system.

### 5. Destroy Phase (Destroy)

The plugin destroy phase is implemented through the `Plugin.Dispose` method, the final phase in a plugin's lifecycle, including:

1. Resource Release
   - Call plugin's OnStop method for stop processing
   - Remove from server's plugin list
   - Release all allocated system resources

2. Status Cleanup
   - Clear all plugin status information
   - Reset plugin internal variables
   - Clear plugin configuration information

3. Connection Disconnection
   - Disconnect all connections with other plugins
   - Clean up plugin dependencies
   - Remove event listeners

4. Data Cleanup
   - Clean up temporary data generated by plugin
   - Close and clean up database connections
   - Delete unnecessary files

5. Final Processing
   - Execute registered destroy callback functions
   - Log destruction
   - Ensure all resources are properly released

The destroy phase aims to ensure plugins completely clean up all resources, leaving no residual state, preventing memory and resource leaks.