Supervisor Client Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package provides a direct PHP interface to Supervisor’s XML-RPC API, enabling dynamic process management (start/stop/restart, status checks, logs, etc.) from within Laravel applications. This is valuable for:
  • Background job orchestration (e.g., managing Laravel queues, cron jobs, or custom workers).
  • Self-healing systems (e.g., auto-restarting failed processes).
  • Monitoring and observability (e.g., fetching process metrics programmatically).
• Laravel Synergy: Integrates seamlessly with Laravel’s task scheduling (artisan schedule:run), queues (e.g., supervisor:worker), and event-driven workflows (e.g., triggering Supervisor actions via Laravel events).
• Alternative to CLI: Avoids shelling out to supervisorctl commands, reducing security risks (e.g., command injection) and improving maintainability.

Integration Feasibility

• Low Coupling: The package is stateless and protocol-agnostic (supports both Unix socket and TCP connections), making it adaptable to most Supervisor setups.
• Laravel-Specific Considerations:
  • Can be injected as a service into Laravel’s Service Container (via bind() in AppServiceProvider).
  • Supports dependency injection in controllers/commands (e.g., public function __construct(SupervisorClient $supervisor)).
  • Compatible with Laravel’s logging (e.g., log Supervisor RPC responses/errors via Monolog).
• XML-RPC Limitations:
  • Supervisor’s XML-RPC API is not strongly typed (responses are arrays/dictionaries), requiring manual validation in PHP.
  • No async support: RPC calls are blocking; consider offloading to queues if latency is critical.

Technical Risk

Key Questions

1. Why not SupervisorPHP?

   • Does the team need additional features (e.g., async support, HTTP API fallback) not in mondalaci/supervisor-client?
   • What’s the migration effort to switch from this package to SupervisorPHP?

2. Security Requirements

   • Is TLS mandatory for TCP connections? If not, how will authentication be enforced?
   • Are there sensitive processes that require granular access control (e.g., RBAC)?

3. Operational Workflow

   • How will Supervisor actions be triggered (e.g., via Laravel commands, HTTP endpoints, or events)?
   • Are there idempotency requirements for RPC calls (e.g., restarting a process twice)?

4. Observability

   • Should RPC responses/errors be logged centrally (e.g., Laravel’s log channels)?
   • Are there metrics (e.g., RPC latency) to monitor?

5. Fallback Strategy

   • What’s the plan if the Supervisor API is unavailable (e.g., fallback to supervisorctl CLI)?

Integration Approach

Stack Fit

• Laravel Compatibility:

  • Service Container: Register the client as a singleton/bound service:

    $this->app->bind(SupervisorClient::class, function ($app) {
        $supervisor = new SupervisorClient('unix:///var/run/supervisor.sock');
        $supervisor->setAuth(env('SUPERVISOR_USERNAME'), env('SUPERVISOR_PASSWORD'));
        $supervisor->setTimeout(5000); // 5ms
        return $supervisor;
    });
    

  • Artisan Commands: Useful for admin tasks (e.g., php artisan supervisor:restart worker).
  • Queues/Jobs: Integrate with Laravel’s queue workers (e.g., restart a stuck worker on failure).
  • Events: Trigger Supervisor actions via Laravel events (e.g., ProcessFailed event → restart process).

• Supervisor Configuration:

  • Ensure the [unix_http_server] or [inet_http_server] section is enabled and secured in supervisord.conf:

    [unix_http_server]
    file=/var/run/supervisor.sock
    chmod=0700
    chown=www-data:www-data
    username=admin
    password=securepassword
    
    [inet_http_server]
    port=*:9001
    username=admin
    password=securepassword
    

Migration Path

1. Short-Term (Immediate Use)

   • Install the package:

     composer require mondalaci/supervisor-client
     

   • Implement a basic wrapper service to abstract RPC calls (e.g., app/Services/SupervisorService.php).
   • Example:

     public function restartProcess(string $processName): bool {
         try {
             return $this->supervisor->supervisorRestartProcess($processName);
         } catch (Exception $e) {
             Log::error("Failed to restart {$processName}: " . $e->getMessage());
             return false;
         }
     }
     

2. Medium-Term (SupervisorPHP Migration)

   • Feature Parity Check: Verify if SupervisorPHP supports all required RPC methods (e.g., supervisor.getAllProcessInfo).
   • Incremental Replacement: Replace mondalaci/supervisor-client with SupervisorPHP in non-critical paths first.
   • Configuration Sync: Update Laravel’s service binding to use SupervisorPHP’s client.

3. Long-Term (API Abstraction)

   • Create an interface (e.g., SupervisorClientInterface) to decouple Laravel from the underlying client:

     interface SupervisorClientInterface {
         public function restartProcess(string $name): bool;
         public function getProcessStatus(string $name): array;
     }
     

   • Implement adapters for both mondalaci/supervisor-client and SupervisorPHP.

Compatibility

• Supervisor Versions:
  • Test against the target Supervisor version (e.g., 4.2.x). Some RPC methods may vary.
  • Check for deprecated methods in the Supervisor API docs.
• PHP Version:
  • The package requires PHP 5.6+ (Laravel’s minimum is 8.0+), so no conflicts.
• Laravel Ecosystem:
  • Works with Laravel’s process utilities (e.g., symfony/process), but this package is preferred for Supervisor-specific tasks.

Sequencing

1. Phase 1: Core Integration
   • Implement basic CRUD operations (start/stop/restart, status checks).
   • Add logging and error handling.
2. Phase 2: Advanced Features
   • Integrate with Laravel queues (e.g., restart workers on failure).
   • Add health checks (e.g., HTTP endpoint to verify Supervisor connectivity).
3. Phase 3: Observability
   • Expose metrics (e.g., process uptime, RPC latency) via Laravel’s monitoring tools.
   • Implement alerts for critical Supervisor failures.
4. Phase 4: Migration (if needed)
   • Replace mondalaci/supervisor-client with SupervisorPHP in a feature branch.

Operational Impact

Maintenance

• Pros:
  • No external dependencies beyond Supervisor and PHP.
  • Minimal boilerplate for basic use cases.
• Cons:
  • Unmaintained package: Bug fixes/PRs may be slow; SupervisorPHP is the future.
  • XML-RPC quirks: Responses require manual parsing/validation.
• Recommendations:
  • Pin the package version in composer.json to avoid unexpected breaking changes.
  • **Monitor Git