بررسی جزئیات شبکه

شبکه مشخص‌شده را بررسی کرده و تمام اطلاعات تفصیلی آن را نمایش می‌دهد.

🧩 دستور کلی

async inspectNetwork(network, options = {})

شرح عملکرد

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

اعتبارسنجی پارامتر شبکه (ID یا نام)
دریافت اطلاعات کامل شبکه از NetworkManager
استخراج پیکربندی IPAM
فهرست‌کردن کانتینرهای متصل
اعتبارسنجی پاسخ
Logging عملیات

نکته: شبکه را می‌توان با ID یا نام مشخص کرد.

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
`network`	String	بله	شناسه یا نام شبکه
`options`	Object	خیر	گزینه‌های بررسی (برای استفاده آتی)

مثال‌های network

// بر اساس نام
"my-bridge"

// بر اساس ID
"a279434eea2bb32a"

// بر اساس ID جزئی (جستجو شروع می‌شود)
"a279434eea"

خروجی

نوع: Object

پاسخ موفق:

{
  id: "bdca227e494b4292",
  name: "kb0",
  driver: "bridge",
  networkIF_name: "kb0",
  options: {},
  IPAM: {
    options: {},
    configs: {
      subnet: "192.168.100.0/24",
      gateway: "192.168.100.254/24"
    }
  },
  containers: {},
  subnet: "192.168.100.0/24",
  gateway: "192.168.100.254/24"
}

نمونه با کانتینرهای متصل

{
  id: "a279434eea2bb32a",
  name: "app-network",
  driver: "bridge",
  networkIF_name: "kb-a279434eea2b",
  options: {},
  IPAM: {
    options: {},
    configs: {
      subnet: "10.0.0.0/24",
      gateway: "10.0.0.1/24"
    }
  },
  containers: {
    "container-1": {
      name: "web-server",
      MacAddress: "02:42:0a:00:00:02",
      IPv4Address: "10.0.0.2/24"
    },
    "container-2": {
      name: "app-server",
      MacAddress: "02:42:0a:00:00:03",
      IPv4Address: "10.0.0.3/24"
    }
  },
  subnet: "10.0.0.0/24",
  gateway: "10.0.0.1/24"
}

نمونه با Host Driver

{
  id: "c49a656ggc4dd54c",
  name: "host-net",
  driver: "host",
  networkIF_name: "host",
  options: {},
  IPAM: {
    options: {},
    configs: {
      subnet: null,
      gateway: null
    }
  },
  containers: {},
  subnet: null,
  gateway: null
}

استثناها (Errors)

InvalidInspectNetworkParameters (422)

پیام: "Invalid inspect network parameters."

زمان رخ دادن: پارامتر شبکه نامعتبر یا خالی

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "network": null,
  "error": "Network parameter is required and must be a string"
}

راهنمای حل:

پارامتر network الزامی است
باید string باشد
نام یا ID شبکه را مشخص کنید

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

try {
  await k3.networkCore.inspectNetwork(null);
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [VALIDATION_ERROR] (422)
  // Type: InvalidInspectNetworkParameters
  // Message: Invalid inspect network parameters.
  // Parameter: network = null
  // Details: Network parameter is required and must be a string
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-param01
}

NetworkNotFound (404)

پیام: "Network not found."

زمان رخ دادن: شبکه با این نام/ID موجود نیست

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "network": "nonexistent-net",
  "error": "Network doesn't exist"
}

راهنمای حل:

نام/ID شبکه را بررسی کنید
listNetworks() استفاده کنید
شبکه را ابتدا ایجاد کنید

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

try {
  await k3.networkCore.inspectNetwork("nonexistent-net");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NOT_FOUND] (404)
  // Type: NetworkNotFound
  // Message: Network not found.
  // Network: nonexistent-net
  // Details: Network doesn't exist in the system
  // Suggestion: Use listNetworks() to find available networks
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-notfound02
}

NetworkInspectionReadFailure (500)

پیام: "Failed to read network inspection data."

زمان رخ دادن: خطا در خواندن فایل‌های شبکه

جزئیات:

{
  "type": "NETWORK_ERROR",
  "statusCode": 500,
  "network": "my-bridge",
  "error": "File read error: ENOENT or EACCES"
}

راهنمای حل:

اجازه‌های فایل سیستم را بررسی کنید
دایرکتوری شبکه موجود است؟
سیستم فایل را بررسی کنید

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

try {
  await k3.networkCore.inspectNetwork("my-bridge");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NETWORK_ERROR] (500)
  // Type: NetworkInspectionReadFailure
  // Message: Failed to read network inspection data.
  // Network: my-bridge
  // System Error: Permission denied (EACCES)
  // Details: Cannot read network configuration file
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-readfail03
}

InspectNetworkFailure (500)

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

زمان رخ دادن: خطای عمومی در بررسی شبکه

جزئیات:

{
  "type": "NETWORK_ERROR",
  "statusCode": 500,
  "network": "my-bridge",
  "error": "Network inspection failed"
}

راهنمای حل:

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

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

try {
  await k3.networkCore.inspectNetwork("my-bridge");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NETWORK_ERROR] (500)
  // Type: InspectNetworkFailure
  // Message: Failed to inspect network.
  // Network: my-bridge
  // Details: NetworkManager communication failed
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-inspectfail04
}

InvalidNetworkInspectResponse (422)

پیام: "Invalid network inspect response format."

زمان رخ دادن: پاسخ NetworkManager معتبر نیست

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "error": "Response is not an object"
}

راهنمای حل:

NetworkManager را بررسی کنید
پاسخ سرویس معتبر است؟
لاگ‌های سیستم را بررسی کنید

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

try {
  await k3.networkCore.inspectNetwork("my-bridge");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [VALIDATION_ERROR] (422)
  // Type: InvalidNetworkInspectResponse
  // Message: Invalid network inspect response format.
  // Details: Response is not a valid object
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-response05
}

GenericFailure (500)

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

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

جزئیات:

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

راهنمای حل:

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

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

try {
  await k3.networkCore.inspectNetwork("my-bridge");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [GENERIC_ERROR] (500)
  // Type: GenericFailure
  // Message: Generic failure during network inspection.
  // Action: inspectNetwork
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-generic06
}

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

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

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const network = await k3.networkCore.inspectNetwork('my-bridge');
    
    console.log('✓ Network Details:');
    console.log(`  Name: ${network.name}`);
    console.log(`  ID: ${network.id}`);
    console.log(`  Driver: ${network.driver}`);
    console.log(`  Subnet: ${network.subnet}`);
    console.log(`  Gateway: ${network.gateway}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

خروجی:

✓ Network Details:
  Name: my-bridge
  ID: bdca227e494b4292
  Driver: bridge
  Subnet: 192.168.100.0/24
  Gateway: 192.168.100.254/24

مثال 2: بررسی با ID

(async () => {
  const k3 = new K3Core();
  
  try {
    const network = await k3.networkCore.inspectNetwork('a279434eea2bb32a');
    
    console.log('✓ Network found by ID:');
    console.log(`  Name: ${network.name}`);
    console.log(`  Interface: ${network.networkIF_name}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: کانتینرهای متصل

(async () => {
  const k3 = new K3Core();
  
  try {
    const network = await k3.networkCore.inspectNetwork('app-network');
    
    console.log(`✓ Network: ${network.name}`);
    console.log(`  Subnet: ${network.subnet}`);
    
    const containerCount = Object.keys(network.containers).length;
    console.log(`  Connected Containers: ${containerCount}`);
    
    if (containerCount > 0) {
      console.log('\n  Containers:');
      Object.entries(network.containers).forEach(([id, container]) => {
        console.log(`    - ${container.name}`);
        console.log(`      IP: ${container.IPv4Address}`);
        console.log(`      MAC: ${container.MacAddress}`);
      });
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

خروجی:

✓ Network: app-network
  Subnet: 10.0.0.0/24
  Connected Containers: 2

  Containers:
    - web-server
      IP: 10.0.0.2/24
      MAC: 02:42:0a:00:00:02
    - app-server
      IP: 10.0.0.3/24
      MAC: 02:42:0a:00:00:03

مثال 4: بررسی Host Network

(async () => {
  const k3 = new K3Core();
  
  try {
    const network = await k3.networkCore.inspectNetwork('host-net');
    
    console.log('✓ Network Details:');
    console.log(`  Name: ${network.name}`);
    console.log(`  Driver: ${network.driver}`);
    
    if (network.driver === 'host') {
      console.log('  ℹ️  Host network (no subnet/gateway)');
      console.log(`  Subnet: ${network.subnet}`);
      console.log(`  Gateway: ${network.gateway}`);
    } else {
      console.log(`  Subnet: ${network.subnet}`);
      console.log(`  Gateway: ${network.gateway}`);
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

خروجی:

✓ Network Details:
  Name: host-net
  Driver: host
  ℹ️  Host network (no subnet/gateway)
  Subnet: null
  Gateway: null

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

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log('🔍 Searching for network...');
    
    // Search
    const networks = await k3.networkCore.listNetworks({
      name: 'my-bridge'
    });
    
    if (networks.length === 0) {
      console.log('❌ Network not found');
      return;
    }
    
    // Inspect
    console.log('📊 Getting details...');
    const network = await k3.networkCore.inspectNetwork(networks[0].name);
    
    console.log(`\n✓ Network Details:`);
    console.log(`  Name: ${network.name}`);
    console.log(`  Driver: ${network.driver}`);
    console.log(`  Subnet: ${network.subnet}`);
    console.log(`  Gateway: ${network.gateway}`);
    console.log(`  Interface: ${network.networkIF_name}`);
    console.log(`  Containers: ${Object.keys(network.containers).length}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: معلومات کامل شبکه

(async () => {
  const k3 = new K3Core();
  
  try {
    const network = await k3.networkCore.inspectNetwork('app-network');
    
    console.log('📋 Complete Network Information:');
    console.log(`\n👤 Metadata:`);
    console.log(`  ID: ${network.id}`);
    console.log(`  Name: ${network.name}`);
    console.log(`  Driver: ${network.driver}`);
    console.log(`  Interface: ${network.networkIF_name}`);
    
    console.log(`\n🌐 Network Configuration:`);
    console.log(`  Subnet: ${network.subnet}`);
    console.log(`  Gateway: ${network.gateway}`);
    console.log(`  IPAM Options: ${JSON.stringify(network.IPAM.options)}`);
    
    console.log(`\n📦 Connected Containers:`);
    const containers = network.containers;
    const count = Object.keys(containers).length;
    console.log(`  Total: ${count}`);
    
    if (count > 0) {
      Object.entries(containers).forEach(([id, container]) => {
        console.log(`\n  Container: ${container.name}`);
        console.log(`    IPv4: ${container.IPv4Address}`);
        console.log(`    MAC: ${container.MacAddress}`);
      });
    } else {
      console.log('  (No containers connected)');
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 7: مقایسه شبکه‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    const net1 = await k3.networkCore.inspectNetwork('network-1');
    const net2 = await k3.networkCore.inspectNetwork('network-2');
    
    console.log('📊 Network Comparison:\n');
    
    console.log('Network 1:');
    console.log(`  Name: ${net1.name}`);
    console.log(`  Driver: ${net1.driver}`);
    console.log(`  Subnet: ${net1.subnet}`);
    console.log(`  Containers: ${Object.keys(net1.containers).length}`);
    
    console.log('\nNetwork 2:');
    console.log(`  Name: ${net2.name}`);
    console.log(`  Driver: ${net2.driver}`);
    console.log(`  Subnet: ${net2.subnet}`);
    console.log(`  Containers: ${Object.keys(net2.containers).length}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 8: Export اطلاعات شبکه

(async () => {
  const k3 = new K3Core();
  const fs = require('fs');
  
  try {
    const network = await k3.networkCore.inspectNetwork('my-bridge');
    
    // Prepare export data
    const exportData = {
      network: {
        id: network.id,
        name: network.name,
        driver: network.driver,
        networkIF_name: network.networkIF_name
      },
      ipam: {
        subnet: network.subnet,
        gateway: network.gateway
      },
      containers: network.containers,
      exportedAt: new Date().toISOString()
    };
    
    // Save to file
    fs.writeFileSync(
      `network-${network.name}.json`,
      JSON.stringify(exportData, null, 2)
    );
    
    console.log(`✓ Network exported to network-${network.name}.json`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 9: بررسی تمام شبکه‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log('📋 Inspecting all networks...\n');
    
    const networks = await k3.networkCore.listNetworks();
    
    for (const net of networks) {
      try {
        const details = await k3.networkCore.inspectNetwork(net.name);
        console.log(`✓ ${details.name}`);
        console.log(`  Driver: ${details.driver}`);
        console.log(`  Subnet: ${details.subnet}`);
        console.log(`  Containers: ${Object.keys(details.containers).length}\n`);
      } catch (error) {
        console.log(`❌ Failed to inspect ${net.name}\n`);
      }
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 10: تحلیل شبکه

(async () => {
  const k3 = new K3Core();
  
  try {
    const network = await k3.networkCore.inspectNetwork('app-network');
    
    // Analyze
    const analysis = {
      name: network.name,
      driver: network.driver,
      subnet: network.subnet,
      totalIPs: parseInt(network.subnet?.split('/')[1] || 0),
      usedIPs: Object.keys(network.containers).length + 2, // +2 for gateway and network
      availableIPs: (2 ** (32 - parseInt(network.subnet?.split('/')[1] || 0))) - 2,
      utilization: ((Object.keys(network.containers).length + 2) / 
                    (2 ** (32 - parseInt(network.subnet?.split('/')[1] || 0)))) * 100
    };
    
    console.log('📊 Network Analysis:');
    console.log(`  Name: ${analysis.name}`);
    console.log(`  Driver: ${analysis.driver}`);
    console.log(`  Subnet: ${analysis.subnet}`);
    console.log(`  Used IPs: ${analysis.usedIPs}`);
    console.log(`  Available IPs: ${analysis.availableIPs}`);
    console.log(`  Utilization: ${analysis.utilization.toFixed(2)}%`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

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

الگو 1: جستجو و بررسی

const inspectByName = async (networkName) => {
  try {
    console.log(`🔍 Searching for ${networkName}...`);
    const networks = await k3.networkCore.listNetworks({ name: networkName });
    
    if (networks.length === 0) {
      console.log(`❌ Network ${networkName} not found`);
      return null;
    }
    
    console.log(`📊 Inspecting ${networkName}...`);
    return await k3.networkCore.inspectNetwork(networks[0].name);
  } catch (error) {
    console.log(error.createFullMessage());
    return null;
  }
};

const details = await inspectByName('my-bridge');

الگو 2: مراقبت شبکه

class NetworkMonitor {
  constructor(k3) {
    this.k3 = k3;
  }
  
  async checkNetwork(networkName) {
    try {
      const network = await this.k3.networkCore.inspectNetwork(networkName);
      
      return {
        healthy: true,
        name: network.name,
        containers: Object.keys(network.containers).length,
        driver: network.driver,
        subnet: network.subnet
      };
    } catch (error) {
      return {
        healthy: false,
        name: networkName,
        error: error.message
      };
    }
  }
  
  async checkAll() {
    const networks = await this.k3.networkCore.listNetworks();
    const results = [];
    
    for (const net of networks) {
      results.push(await this.checkNetwork(net.name));
    }
    
    return results;
  }
}

const monitor = new NetworkMonitor(k3);
const health = await monitor.checkAll();

الگو 3: تحلیل کانتینرها

const analyzeContainers = async (networkName) => {
  try {
    const network = await k3.networkCore.inspectNetwork(networkName);
    
    const analysis = {
      total: Object.keys(network.containers).length,
      containers: []
    };
    
    Object.entries(network.containers).forEach(([id, container]) => {
      analysis.containers.push({
        id: id,
        name: container.name,
        ip: container.IPv4Address,
        mac: container.MacAddress
      });
    });
    
    return analysis;
  } catch (error) {
    console.log(error.createFullMessage());
    return null;
  }
};

const analysis = await analyzeContainers('app-network');

نکات عملی

شناسه شبکه:
- نام شبکه اولویت دارد
- ID یا جزء ID قابل قبول
- برای دقت بیشتر: نام استفاده کنید
اطلاعات IPAM:
- برای host/none: subnet و gateway null هستند
- برای bridge: معمولاً معتبر‌اند
- فرمت: IPv4/netmask
کانتینرهای متصل:
- شامل IP و MAC آدرس
- فقط کانتینرهای فعال نمایش داده می‌شوند
- خالی اگر کانتینری متصل نباشد
Performance:
- بررسی تک شبکه سریع است
- برای همه شبکه‌ها: loop کنید
Best Practices:
- همیشه try-catch استفاده کنید
- پیش از اتصال کانتینر: بررسی کنید
- برای debugging: تمام اطلاعات نمایش دهید

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

اعتبارسنجی پارامترها
جستجوی شبکه
دریافت اطلاعات از NetworkManager
استخراج IPAM
فهرست‌کردن کانتینرها
اعتبارسنجی پاسخ
Logging عملیات
بازگشت نتیجه

مرجع سریع

فیلد	نوع	توضیح
id	String	شناسه یکتا SHA-256
name	String	نام شبکه
driver	String	bridge, macvlan, host, none
networkIF_name	String	نام واسط سیستم
subnet	String	IPv4/netmask یا null
gateway	String	IPv4/netmask یا null
containers	Object	کانتینرهای متصل

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

بررسی ساده

const network = await k3.networkCore.inspectNetwork('my-bridge');

جستجو و بررسی

const networks = await k3.networkCore.listNetworks({ name: 'my' });
if (networks.length > 0) {
  const details = await k3.networkCore.inspectNetwork(networks[0].name);
}

اطلاعات کانتینرها

const network = await k3.networkCore.inspectNetwork('app-net');
Object.entries(network.containers).forEach(([id, c]) => {
  console.log(`${c.name}: ${c.IPv4Address}`);
});

بررسی تمام شبکه‌ها

const networks = await k3.networkCore.listNetworks();
for (const net of networks) {
  const details = await k3.networkCore.inspectNetwork(net.name);
}

نسخه: 1.0
تاریخ آپدیت: 1 دسامبر 2025
تیم توسعه: K3 Development Team

🧩 دستور کلی​

شرح عملکرد​

ورودی‌ها​

مثال‌های network​

خروجی​

نمونه با کانتینرهای متصل​

نمونه با Host Driver​

استثناها (Errors)​

InvalidInspectNetworkParameters (422)​

NetworkNotFound (404)​

NetworkInspectionReadFailure (500)​

InspectNetworkFailure (500)​

InvalidNetworkInspectResponse (422)​

GenericFailure (500)​

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

مثال 1: بررسی شبکه ساده​

مثال 2: بررسی با ID​

مثال 3: کانتینرهای متصل​

مثال 4: بررسی Host Network​

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

مثال 6: معلومات کامل شبکه​

مثال 7: مقایسه شبکه‌ها​

مثال 8: Export اطلاعات شبکه​

مثال 9: بررسی تمام شبکه‌ها​

مثال 10: تحلیل شبکه​

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

الگو 1: جستجو و بررسی​

الگو 2: مراقبت شبکه​

الگو 3: تحلیل کانتینرها​

نکات عملی​

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

مرجع سریع​

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

بررسی ساده​

جستجو و بررسی​

اطلاعات کانتینرها​

بررسی تمام شبکه‌ها​

🧩 دستور کلی

شرح عملکرد

ورودی‌ها

مثال‌های network

خروجی

نمونه با کانتینرهای متصل

نمونه با Host Driver

استثناها (Errors)

InvalidInspectNetworkParameters (422)

NetworkNotFound (404)

NetworkInspectionReadFailure (500)

InspectNetworkFailure (500)

InvalidNetworkInspectResponse (422)

GenericFailure (500)

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

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

مثال 2: بررسی با ID

مثال 3: کانتینرهای متصل

مثال 4: بررسی Host Network

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

مثال 6: معلومات کامل شبکه

مثال 7: مقایسه شبکه‌ها

مثال 8: Export اطلاعات شبکه

مثال 9: بررسی تمام شبکه‌ها

مثال 10: تحلیل شبکه

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

الگو 1: جستجو و بررسی

الگو 2: مراقبت شبکه

الگو 3: تحلیل کانتینرها

نکات عملی

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

مرجع سریع

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

بررسی ساده

جستجو و بررسی

اطلاعات کانتینرها

بررسی تمام شبکه‌ها