بررسی جزئیات Volume

جزئیات و پیکربندی یک volume مشخص را نمایش می‌دهد.

---

🧩 دستور کلی

async inspectVolume(volumeName)

---

شرح عملکرد

این متد اطلاعات تفصیلی یک volume را دریافت می‌کند. شامل:

• اعتبارسنجی نام volume
• دریافت اطلاعات کامل volume از VolumeManager
• استخراج metadata و configuration
• بررسی وجود volume
• Logging عملیات

نکته: volume را باید بر اساس نام مشخص کنید.

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
volumeName	String	بله	نام volume برای بررسی

مثال‌های volumeName

// نام ساده
"vlo1"

// نام معنادار
"app-data"
"postgres-data"
"cache-vol"

// نام با prefix
"prod-db-volume"

---

خروجی

نوع: Object

پاسخ موفق:

{
  Name: "vlo1",
  Size: "100MB",
  Type: "custom",
  CreatedAt: "2025-12-02T06:43:16.035Z",
  MountDirectory: "/var/lib/k3/volume/mount_cb6c19ef1a9dac77"
}

شرح فیلدهای خروجی

فیلد	توضیح
Name	نام volume
Size	اندازه volume
Type	نوع volume (tmpfs، persistent، custom)
CreatedAt	زمان ایجاد (ISO format)
MountDirectory	مسیر mount واقعی در سیستم

مثال‌های خروجی دیگر

// persistent volume
{
  Name: "app-data",
  Size: "10GB",
  Type: "persistent",
  CreatedAt: "2025-12-01T10:30:00.000Z",
  MountDirectory: "/var/lib/k3/volume/mount_a1b2c3d4e5f6"
}

// tmpfs volume
{
  Name: "cache-vol",
  Size: "512MB",
  Type: "tmpfs",
  CreatedAt: "2025-12-02T08:15:22.123Z",
  MountDirectory: "/var/lib/k3/volume/mount_x9y0z1a2b3c4"
}

// database volume
{
  Name: "postgres-data",
  Size: "50GB",
  Type: "persistent",
  CreatedAt: "2025-11-30T15:45:10.456Z",
  MountDirectory: "/var/lib/k3/volume/mount_i9j0k1l2m3n4"
}

---

استثناها (Errors)

NoVolumesFound (404)

پیام: "Volume not found."

زمان رخ دادن: volume با نام مشخص‌شده وجود ندارد

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "volumeName": "nonexistent-vol",
  "error": "VolumeDon'tExist"
}

راهنمای حل:

• نام volume را بررسی کنید
• listVolume() استفاده کنید تا نام صحیح را پیدا کنید
• volume ابتدا باید ایجاد شده باشد (createVolume())

مثال خطا در کنسول:

try {
  await k3.volumeCore.inspectVolume("nonexistent-vol");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NOT_FOUND] (404)
  // Type: NoVolumesFound
  // Message: Volume not found.
  // Volume Name: nonexistent-vol
  // Details: Volume doesn't exist in the system
  // Suggestion: Use listVolume() to find available volumes
  // Timestamp: 2025-12-02T10:30:45Z
  // Request ID: req-notfound01
}

---

InspectVolumeFailure (500)

پیام: "Failed to inspect volume."

زمان رخ دادن: خطا در دریافت اطلاعات volume

جزئیات:

{
  "type": "VOLUME_SERVICE_ERROR",
  "statusCode": 500,
  "volumeName": "app-data",
  "error": "VolumeManager communication failed"
}

راهنمای حل:

• VolumeManager را بررسی کنید
• سرویس را restart کنید
• لاگ‌های سیستم را بررسی کنید
• اتصال سیستم پرونده را تأیید کنید

مثال خطا در کنسول:

try {
  await k3.volumeCore.inspectVolume("app-data");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [VOLUME_SERVICE_ERROR] (500)
  // Type: InspectVolumeFailure
  // Message: Failed to inspect volume.
  // Volume Name: app-data
  // Details: VolumeManager service unavailable
  // Timestamp: 2025-12-02T10:30:45Z
  // Request ID: req-inspect02
}

---

GenericFailure (500)

پیام: "Generic failure during volume inspection."

زمان رخ دادن: خطای عمومی نامشخص

جزئیات:

{
  "type": "GENERIC_ERROR",
  "statusCode": 500,
  "error": "Unknown error occurred"
}

راهنمای حل:

• لاگ‌های سیستم و سرویس را بررسی کنید
• تمام سرویس‌ها را restart کنید
• دوباره تلاش کنید

مثال خطا در کنسول:

try {
  await k3.volumeCore.inspectVolume("app-data");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [GENERIC_ERROR] (500)
  // Type: GenericFailure
  // Message: Generic failure during volume inspection.
  // Action: inspectVolume
  // Details: Unexpected error in VolumeManager
  // Timestamp: 2025-12-02T10:30:45Z
  // Request ID: req-generic03
}

---

مثال‌های استفاده

مثال 1: بررسی Volume ساده

const K3Core = require('k3-core');

(async () => {
  const k3 = new K3Core();
  
  try {
    const volume = await k3.volumeCore.inspectVolume('vlo1');
    
    console.log('✓ Volume Details:');
    console.log(`  Name: ${volume.Name}`);
    console.log(`  Size: ${volume.Size}`);
    console.log(`  Type: ${volume.Type}`);
    console.log(`  Created: ${new Date(volume.CreatedAt).toLocaleString()}`);
    console.log(`  Mount: ${volume.MountDirectory}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

خروجی:

✓ Volume Details:
  Name: vlo1
  Size: 100MB
  Type: custom
  Created: 2025-12-02 10:13:16 AM
  Mount: /var/lib/k3/volume/mount_cb6c19ef1a9dac77

---

مثال 2: جستجو و بررسی

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log(' Searching for volume...');
    
    const volumes = await k3.volumeCore.listVolume();
    const found = volumes.find(v => v.Name === 'app-data');
    
    if (!found) {
      console.log(' Volume not found');
      return;
    }
    
    console.log(' Inspecting volume...');
    const details = await k3.volumeCore.inspectVolume(found.Name);
    
    console.log(`\n✓ ${details.Name}`);
    console.log(`  Size: ${details.Size}`);
    console.log(`  Type: ${details.Type}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 3: بررسی تمام Volume‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log(' Inspecting all volumes...\n');
    
    const volumes = await k3.volumeCore.listVolume();
    
    for (const vol of volumes) {
      try {
        const details = await k3.volumeCore.inspectVolume(vol.Name);
        
        console.log(` ${details.Name}`);
        console.log(`  Size: ${details.Size}`);
        console.log(`  Type: ${details.Type}`);
        console.log(`  Path: ${details.MountDirectory}\n`);
      } catch (error) {
        console.log(` Failed to inspect ${vol.Name}\n`);
      }
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 4: مقایسه Volume‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    const vol1 = await k3.volumeCore.inspectVolume('app-data');
    const vol2 = await k3.volumeCore.inspectVolume('db-storage');
    
    console.log(' Volume Comparison:\n');
    
    console.log('Volume 1:');
    console.log(`  Name: ${vol1.Name}`);
    console.log(`  Size: ${vol1.Size}`);
    console.log(`  Type: ${vol1.Type}`);
    
    console.log('\nVolume 2:');
    console.log(`  Name: ${vol2.Name}`);
    console.log(`  Size: ${vol2.Size}`);
    console.log(`  Type: ${vol2.Type}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 5: بررسی با Export

(async () => {
  const k3 = new K3Core();
  const fs = require('fs');
  
  try {
    const volume = await k3.volumeCore.inspectVolume('app-data');
    
    console.log(' Volume Information:');
    console.log(JSON.stringify(volume, null, 2));
    
    // Export to file
    fs.writeFileSync(
      `volume-${volume.Name}.json`,
      JSON.stringify(volume, null, 2)
    );
    
    console.log(`\n✓ Exported to volume-${volume.Name}.json`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 6: بررسی و Validation

(async () => {
  const k3 = new K3Core();
  
  try {
    const volume = await k3.volumeCore.inspectVolume('app-data');
    
    // Validate
    const isValid = {
      hasName: !!volume.Name,
      hasSize: !!volume.Size,
      hasType: !!volume.Type,
      hasCreatedAt: !!volume.CreatedAt,
      hasMountDirectory: !!volume.MountDirectory
    };
    
    console.log('✓ Volume Validation:');
    Object.entries(isValid).forEach(([key, value]) => {
      console.log(`  ${key}: ${value ? '✓' : '✗'}`);
    });
    
    const allValid = Object.values(isValid).every(v => v);
    console.log(`\nStatus: ${allValid ? '✓ Valid' : '✗ Invalid'}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 7: بررسی سایز Volume

(async () => {
  const k3 = new K3Core();
  
  try {
    const volume = await k3.volumeCore.inspectVolume('app-data');
    
    // تابع تبدیل size به bytes
    const toBytes = (sizeStr) => {
      const units = { KB: 1024, MB: 1024**2, GB: 1024**3, TB: 1024**4 };
      const match = sizeStr.match(/^([\d.]+)\s*([A-Z]+)$/i);
      
      if (!match) return 0;
      const [, num, unit] = match;
      return parseFloat(num) * (units[unit.toUpperCase()] || 1);
    };
    
    const bytes = toBytes(volume.Size);
    const kb = (bytes / 1024).toFixed(2);
    const mb = (bytes / (1024**2)).toFixed(2);
    const gb = (bytes / (1024**3)).toFixed(2);
    
    console.log(` Size Analysis (${volume.Name}):`);
    console.log(`  Original: ${volume.Size}`);
    console.log(`  Bytes: ${bytes}`);
    console.log(`  KB: ${kb}`);
    console.log(`  MB: ${mb}`);
    console.log(`  GB: ${gb}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 8: بررسی و اطلاعات تفصیلی

(async () => {
  const k3 = new K3Core();
  
  try {
    const volume = await k3.volumeCore.inspectVolume('postgres-data');
    
    console.log(' Complete Volume Information:\n');
    
    console.log(' Basic Info:');
    console.log(`  Name: ${volume.Name}`);
    console.log(`  Type: ${volume.Type}`);
    
    console.log('\n Storage:');
    console.log(`  Size: ${volume.Size}`);
    
    console.log('\n Timeline:');
    const createdDate = new Date(volume.CreatedAt);
    const now = new Date();
    const ageMs = now - createdDate;
    const ageDay = Math.floor(ageMs / (24 * 60 * 60 * 1000));
    
    console.log(`  Created: ${createdDate.toLocaleString()}`);
    console.log(`  Age: ${ageDay} days`);
    
    console.log('\n Mount:');
    console.log(`  Path: ${volume.MountDirectory}`);
    console.log(`  Accessible: true`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 9: بررسی با Monitoring

(async () => {
  const k3 = new K3Core();
  
  try {
    const volume = await k3.volumeCore.inspectVolume('app-data');
    
    const status = {
      name: volume.Name,
      size: volume.Size,
      type: volume.Type,
      status: 'active',
      mounted: true,
      timestamp: new Date().toISOString(),
      health: 'good'
    };
    
    console.log(' Volume Status:');
    console.log(JSON.stringify(status, null, 2));
    
    // Log to file
    const fs = require('fs');
    fs.appendFileSync(
      'volume-monitor.log',
      JSON.stringify(status) + '\n'
    );
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 10: بررسی و Comparison

(async () => {
  const k3 = new K3Core();
  
  try {
    // Get list
    const volumes = await k3.volumeCore.listVolume();
    
    // Inspect each
    const details = await Promise.all(
      volumes.map(v => k3.volumeCore.inspectVolume(v.Name))
    );
    
    // Compare
    console.log(' Volume Comparison:\n');
    
    // Find largest
    const largest = details.reduce((max, v) => {
      const maxSize = parseInt(max.Size);
      const vSize = parseInt(v.Size);
      return vSize > maxSize ? v : max;
    });
    
    // Find smallest
    const smallest = details.reduce((min, v) => {
      const minSize = parseInt(min.Size);
      const vSize = parseInt(v.Size);
      return vSize < minSize ? v : min;
    });
    
    // Find newest
    const newest = details.reduce((max, v) => {
      const maxDate = new Date(max.CreatedAt);
      const vDate = new Date(v.CreatedAt);
      return vDate > maxDate ? v : max;
    });
    
    console.log(`Largest: ${largest.Name} (${largest.Size})`);
    console.log(`Smallest: ${smallest.Name} (${smallest.Size})`);
    console.log(`Newest: ${newest.Name}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

الگوهای استفاده

الگو 1: بررسی ایمن

const safeInspectVolume = async (volumeName) => {
  try {
    return await k3.volumeCore.inspectVolume(volumeName);
  } catch (error) {
    if (error.statusCode === 404) {
      console.log(`Volume ${volumeName} not found`);
      
      // List available
      const available = await k3.volumeCore.listVolume();
      console.log('Available volumes:', available.map(v => v.Name));
      
      return null;
    }
    console.log(error.createFullMessage());
    return null;
  }
};

const vol = await safeInspectVolume('app-data');

---

الگو 2: بررسی و Cache

class VolumeInspector {
  constructor(k3) {
    this.k3 = k3;
    this.cache = {};
  }
  
  async inspect(volumeName) {
    if (this.cache[volumeName]) {
      console.log(`(cached) ${volumeName}`);
      return this.cache[volumeName];
    }
    
    const volume = await this.k3.volumeCore.inspectVolume(volumeName);
    this.cache[volumeName] = volume;
    
    return volume;
  }
  
  clearCache() {
    this.cache = {};
  }
}

const inspector = new VolumeInspector(k3);
const vol = await inspector.inspect('app-data');

---

الگو 3: بررسی با تحلیل

class VolumeAnalyzer {
  constructor(k3) {
    this.k3 = k3;
  }
  
  async analyze(volumeName) {
    try {
      const volume = await this.k3.volumeCore.inspectVolume(volumeName);
      
      return {
        name: volume.Name,
        sizeBytes: this.parseSize(volume.Size),
        type: volume.Type,
        age: this.calculateAge(volume.CreatedAt),
        metadata: volume
      };
    } catch (error) {
      console.log(error.createFullMessage());
      return null;
    }
  }
  
  parseSize(sizeStr) {
    const units = { KB: 1024, MB: 1024**2, GB: 1024**3 };
    const match = sizeStr.match(/^([\d.]+)\s*([A-Z]+)$/i);
    if (!match) return 0;
    return parseFloat(match[1]) * (units[match[2].toUpperCase()] || 1);
  }
  
  calculateAge(createdAt) {
    const ms = new Date() - new Date(createdAt);
    return Math.floor(ms / (24 * 60 * 60 * 1000));
  }
}

const analyzer = new VolumeAnalyzer(k3);
const analysis = await analyzer.analyze('app-data');

---

نکات عملی

1. نام Volume:

   • باید دقیق و صحیح باشد
   • case-sensitive است
   • از listVolume() برای پیدا کردن استفاده کنید

2. اطلاعات موجود:

   • Name: نام منحصربه‌فرد
   • Size: اندازه تخصیص‌شده
   • Type: نوع ذخیره‌سازی
   • CreatedAt: تاریخ ایجاد
   • MountDirectory: مسیر mount

3. Error Handling:

   • 404: volume وجود ندارد
   • 500: خطای سرویس
   • همیشه try-catch استفاده کنید

4. Performance:

   • بررسی سریع است
   • می‌توانید여러 volume را بررسی کنید
   • cache برای بهبود سرعت

5. Best Practices:

   • ابتدا listVolume استفاده کنید
   • نام صحیح را تأیید کنید
   • Error handling کامل

---

دنباله عملیات

1. اعتبارسنجی volumeName
2. تماس با VolumeManager
3. دریافت اطلاعات volume
4. بررسی وجود volume
5. Logging عملیات
6. بازگشت اطلاعات کامل

---

مرجع سریع

فیلد	توضیح
Name	نام volume
Size	اندازه (مثل 100MB، 10GB)
Type	نوع (tmpfs، persistent، custom)
CreatedAt	زمان ایجاد ISO format
MountDirectory	مسیر mount سیستم

---

موارد استفاده

بررسی ساده

const vol = await k3.volumeCore.inspectVolume('app-data');

جستجو و بررسی

const list = await k3.volumeCore.listVolume();
const vol = await k3.volumeCore.inspectVolume(list[0].Name);

بررسی تمام Volume‌ها

const list = await k3.volumeCore.listVolume();
for (const v of list) {
  const details = await k3.volumeCore.inspectVolume(v.Name);
}

Export اطلاعات

const vol = await k3.volumeCore.inspectVolume('app-data');
fs.writeFileSync('volume.json', JSON.stringify(vol));

---

نسخه: 1.3
تاریخ آپدیت: 11 آذر 1404
تیم توسعه: K3 Development Team