Core Services and Configuration

Core Services and Configuration

The src/pclink/core/ directory contains the essential, non-web-facing components that form the foundation of the PCLink server. These modules handle the application's lifecycle, configuration, state, and platform-specific integrations.

server_controller.py - The Lifecycle Manager

The ServerController class manages the high-level lifecycle of the PCLink server. It coordinates the startup and shutdown of the API server and integrates with the system tray to provide user-facing controls.

• Server Orchestration: It is responsible for initializing the FastAPI application and launching the Uvicorn ASGI server in a background thread.
• State Coordination: It ensures that the server transitions correctly between different states (e.g., starting, running, stopping).
• Tray Integration: It provides the logic for the system tray's context menu, allowing users to restart the server or exit the application.

startup.py - Boot Persistence

The StartupManager handles the complexities of ensuring PCLink starts automatically when the operating system boots.

• Cross-Platform Persistence: It implements platform-specific logic to register PCLink for auto-start (e.g., using the Windows Registry/Task Scheduler or systemd user services on Linux).
• Environment Setup: It ensures that necessary environment variables and paths are correctly configured before the main application logic begins.

config.py - Configuration Management

The ConfigManager provides a persistent way to manage user-configurable settings via a config.json file.

• Storage: Settings are stored in the user's platform-specific application data directory.
• Global Service Toggles: A critical feature is the services configuration block, which allows administrators to globally enable or disable core features (e.g., Terminal, File Browser). These act as "kill-switches" that override individual device permissions.
• Key Settings: Manages configurations such as the server_port, auto_start preferences, and security flags.

device_manager.py - Device Persistence & Security

The DeviceManager handles all aspects of paired mobile devices and their authorization.

• Database: Uses an SQLite database (devices.db) to store device metadata, API keys, and assigned permissions.
• Device Lifecycle:
  1. Registration: New devices are registered with a unique ID and name.
  2. Approval: Devices are marked as approved after the user confirms the pairing request in the Web UI.
  3. Authentication: Assigns a unique, secure API key to each approved device.
  4. Banning: Implements hardware-level blacklisting using unique Hardware IDs to permanently block specific devices from re-pairing.

share_manager.py - Secure File Sharing

The ShareManager implements the secure, token-based file sharing system introduced in v4.3.0.

• Token Generation: Creates unique, cryptographically secure tokens for specific file paths.
• Expiration Logic: Supports both permanent links and temporary links with configurable expiration timers.
• Persistence: Tracks active share tokens and their associated devices in a dedicated database to ensure links remain valid across server restarts.

extension_manager.py - Dynamic Extensibility

The ExtensionManager is the core of PCLink's modular architecture, allowing new features to be added without modifying the core engine.

• Dynamic Loading: Scans the extensions directory and loads modules based on their extension.yaml manifest.
• Lifecycle Management: Handles the initialization, execution, and cleanup of extensions.
• Hot-Loading: Supports on-demand loading of extensions when a request is made to their specific API endpoint.

Other Important Core Modules

• state.py: Holds global, in-memory application state, such as the list of currently connected devices.
• system_tray.py: Implements the cross-platform system tray icon and its context menu.
• singleton.py: Prevents multiple instances of PCLink from running simultaneously using system-wide locks.
• web_auth.py: Manages the security model for the Web UI, including password hashing and session validation.
• update_checker.py: Monitors for new server versions and notifies the user.
• wayland_utils.py: Provides utilities for interacting with Wayland-based display servers on Linux.
• linux_notifier.py & windows_notifier.py: Implement native OS notifications for the server.
• logging.py: Centralized logging configuration, including the fatal.log hook for crash traces.
• utils.py & validators.py: General utility functions and input sanitization logic.
• version.py: Stores application version and metadata.