import { KosParentAware } from '../../../../core';
// ---------------  StorageDevice ---------------

/**
 * Configuration options for StorageDevice model instances.
 *
 * This interface defines the complete configuration structure for individual storage devices,
 * including hardware identification, mount information, and runtime metrics. These options
 * are typically populated from storage device discovery services and WebSocket updates.
 *
 * @example Basic Usage
 * ```typescript
 * const device = StorageDevice.instance('usb-backup')
 *   .options({
 *     mountDir: '/media/usb-drive',
 *     vendor: 'SanDisk',
 *     model: 'Ultra USB 3.0',
 *     label: 'BACKUP_DRIVE',
 *     nodeId: 'primary',
 *     local: true,
 *     removed: false,
 *     runTimeMs: 1800000,
 *     syspath: '/sys/devices/usb1'
 *   })
 *   .build();
 * ```
 *
 * @kosService core.storage
 * @category Model Configuration
 * @category Device Management
 */
export interface StorageDeviceOptions extends KosParentAware {
  /**
   * File system mount directory path where the device is accessible.
   * Empty string indicates the device is not currently mounted.
   *
   * @example "/media/usb-drive"
   * @example "/mnt/backup-storage"
   * @example "" // Not mounted
   */
  mountDir: string;

  /**
   * Indicates whether the storage device has been physically removed.
   * When true, the device is no longer accessible and mount operations will fail.
   *
   * @default false
   */
  removed: boolean;

  /**
   * Hardware vendor/manufacturer name of the storage device.
   * Used for device identification and display purposes.
   *
   * @example "SanDisk"
   * @example "Western Digital"
   * @example "Samsung"
   */
  vendor: string;

  /**
   * Total runtime in milliseconds since the device was first connected.
   * Tracks cumulative usage time for analytics and maintenance scheduling.
   *
   * @example 1800000 // 30 minutes
   * @example 3600000 // 1 hour
   */
  runTimeMs: number;

  /**
   * Hardware model name/number of the storage device.
   * Combined with vendor for complete device identification.
   *
   * @example "Ultra USB 3.0"
   * @example "My Passport"
   * @example "EVO Select 64GB"
   */
  model: string;

  /**
   * KOS node identifier where this storage device is physically connected.
   * Used in multi-node systems to track device distribution.
   *
   * @example "primary"
   * @example "secondary"
   * @example "embedded-node-1"
   */
  nodeId: string;

  /**
   * Indicates if the device is connected to the local node (true) or remote node (false).
   * Determines accessibility and operation capabilities from current context.
   *
   * @default true
   */
  local: boolean;

  /**
   * File system label/name assigned to the storage device.
   * Used for user-friendly identification and mount point organization.
   *
   * @example "BACKUP_DRIVE"
   * @example "CONFIG_STORAGE"
   * @example "DATA_ARCHIVE"
   */
  label: string;

  /**
   * System device path in the Linux device tree.
   * Low-level hardware identifier for device tracking and diagnostics.
   *
   * @example "/sys/devices/pci0000:00/usb1/1-2"
   * @example "/sys/devices/mmc0/mmc0:0001"
   * @example "/sys/devices/platform/sdhci"
   */
  syspath: string;
}

// ---------------  StorageDeviceContainer ---------------

/**
 * Configuration options for StorageDeviceContainer model instances.
 *
 * The container model manages collections of storage devices and handles real-time
 * updates via WebSocket topics. Currently uses an empty configuration object as
 * the container's behavior is primarily driven by discovered storage devices.
 *
 * @kosService core.storage
 * @category Model Configuration
 * @category Device Management
 */
export type StorageDeviceContainerOptions = object;
