لیست شبکه‌ها

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

---

🧩 دستور کلی

async listNetworks(options = {})

---

شرح عملکرد

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

• دریافت لیست تمام شبکه‌ها از NetworkManager
• اعتبارسنجی پاسخ
• اعمال فیلترها (id، name، driver، dangling)
• انتخاب فرمت خروجی (عادی، verbose، onlyIFs)
• Logging عملیات

نکته: فیلترها اختیاری هستند و می‌توان آن‌ها را ترکیب کرد.

---

ورودی‌ها

پارامتر	نوع	پیش‌فرض	توضیح
options	Object		فیلترها و گزینه‌های نمایش
options.id	String	-	فیلتر بر اساس شناسه شبکه
options.name	String	-	فیلتر بر اساس نام شبکه
options.driver	String	-	فیلتر بر اساس نوع درایور (bridge, macvlan, host, none)
options.dangling	String	"all"	فیلتر بر اساس اتصال کانتینر (true, false, all)
options.verbose	Boolean	false	نمایش اطلاعات تفصیلی شبکه
options.onlyIFs	Boolean	false	نمایش فقط نام‌های واسط‌های شبکه
options.quiet	Boolean	false	نمایش خلاصه‌شده

مثال‌های filters

// فیلتر بر اساس نام
{ name: "my-bridge" }

// فیلتر بر اساس درایور
{ driver: "bridge" }

// فیلتر بر اساس وضعیت dangling
{ dangling: "true" }  // شبکه‌های بدون کانتینر

// ترکیب فیلترها
{ driver: "bridge", dangling: "false", verbose: true }

// فقط واسط‌ها
{ onlyIFs: true }

// خلاصه
{ quiet: true }

---

خروجی

خروجی بر اساس گزینه‌های انتخاب‌شده متفاوت است:

خروجی 1: عادی (پیش‌فرض)

[
  {
    id: "a279434eea2bb32a",
    name: "my-bridge",
    driver: "bridge"
  },
  {
    id: "b389545ffb3cc43b",
    name: "app-net",
    driver: "bridge"
  },
  {
    id: "c49a656ggc4dd54c",
    name: "vlan-net",
    driver: "macvlan"
  }
]

خروجی 2: Verbose (اطلاعات تفصیلی)

[
  {
    id: "a279434eea2bb32a",
    name: "my-bridge",
    driver: "bridge",
    networkIF_name: "kb-a279434eea2b",
    options: {},
    IPAM: {
      options: {},
      configs: {
        subnet: "192.168.0.0/24",
        gateway: "192.168.0.1"
      }
    },
    containers: {
      "container-1": "192.168.0.2",
      "container-2": "192.168.0.3"
    }
  },
  {
    id: "b389545ffb3cc43b",
    name: "app-net",
    driver: "bridge",
    networkIF_name: "kb-b389545ffb3",
    IPAM: {
      configs: {
        subnet: "10.0.0.0/24",
        gateway: "10.0.0.1"
      }
    },
    containers: {}
  }
]

خروجی 3: OnlyIFs (فقط واسط‌ها) - Bridge

[
  {
    name: "my-bridge",
    interfaces: ["kb-a279434eea2b"]
  },
  {
    name: "app-net",
    interfaces: ["kb-b389545ffb3"]
  }
]

خروجی 4: OnlyIFs (فقط واسط‌ها) - Macvlan

[
  {
    name: "vlan-net",
    interfaces: ["kb-vlan-vlanIF", "kb-vlan-bridgeIF"]
  }
]

خروجی 5: Quiet (خلاصه)

[
  {
    name: "my-bridge",
    driver: "bridge"
  },
  {
    name: "app-net",
    driver: "bridge"
  }
]

---

استثناها (Errors)

ListNetworksFailure (500)

پیام: "Failed to list networks from NetworkManager."

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

جزئیات:

{
  "type": "NETWORK_ERROR",
  "statusCode": 500,
  "error": "NetworkManager communication failed"
}

راهنمای حل:

• NetworkManager را بررسی کنید
• سرویس را restart کنید
• اتصال سیستم را تأیید کنید

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

try {
  const networks = await k3.networkCore.listNetworks();
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NETWORK_ERROR] (500)
  // Type: ListNetworksFailure
  // Message: Failed to list networks from NetworkManager.
  // Details: NetworkManager service unavailable
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-list01
}

---

InvalidNetworksListResponse (422)

پیام: "Invalid networks list response format."

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

جزئیات:

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

راهنمای حل:

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

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

try {
  const networks = await k3.networkCore.listNetworks();
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [VALIDATION_ERROR] (422)
  // Type: InvalidNetworksListResponse
  // Message: Invalid networks list response format.
  // Details: Response is not an array
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-validation02
}

---

InvalidNetworkListFilters (422)

پیام: "Invalid filter options for network listing."

زمان رخ دادن: گزینه‌های فیلتر نامعتبر

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "filters": {
    "invalid_filter": "value"
  },
  "error": "Invalid filter: invalid_filter"
}

راهنمای حل:

• فیلترهای معتبر: id, name, driver, dangling, verbose, onlyIFs, quiet
• نام فیلتر را بررسی کنید
• درایورهای معتبر: bridge, macvlan, host, none

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

try {
  const networks = await k3.networkCore.listNetworks({
    invalid_option: true
  });
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [VALIDATION_ERROR] (422)
  // Type: InvalidNetworkListFilters
  // Message: Invalid filter options for network listing.
  // Invalid Filter: invalid_option
  // Valid Filters: id, name, driver, dangling, verbose, onlyIFs, quiet
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-filter03
}

---

FilterNetworksFailure (500)

پیام: "Failed to apply filters to networks list."

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

جزئیات:

{
  "type": "NETWORK_ERROR",
  "statusCode": 500,
  "filters": {
    "driver": "invalid-driver"
  },
  "error": "Invalid driver filter value"
}

راهنمای حل:

• درایور معتبر انتخاب کنید
• فیلتر dangling: true, false یا all
• مقادیر فیلتر را بررسی کنید

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

try {
  const networks = await k3.networkCore.listNetworks({
    driver: "invalid-driver"
  });
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NETWORK_ERROR] (500)
  // Type: FilterNetworksFailure
  // Message: Failed to apply filters to networks list.
  // Filter: driver = invalid-driver
  // Valid Values: bridge, macvlan, host, none
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-filterrun04
}

---

GenericFailure (500)

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

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

جزئیات:

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

راهنمای حل:

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

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

try {
  const networks = await k3.networkCore.listNetworks();
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [GENERIC_ERROR] (500)
  // Type: GenericFailure
  // Message: Generic failure during network listing.
  // Action: listNetworks
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-generic05
}

---

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

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

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const networks = await k3.networkCore.listNetworks();
    
    console.log('✓ Networks found:', networks.length);
    networks.forEach(net => {
      console.log(`  - ${net.name} (${net.driver}) [${net.id}]`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

خروجی:

✓ Networks found: 3
  - my-bridge (bridge) [a279434eea2bb32a]
  - app-net (bridge) [b389545ffb3cc43b]
  - vlan-net (macvlan) [c49a656ggc4dd54c]

---

مثال 2: فیلتر بر اساس نام

(async () => {
  const k3 = new K3Core();
  
  try {
    const networks = await k3.networkCore.listNetworks({
      name: "my-bridge"
    });
    
    if (networks.length > 0) {
      const net = networks[0];
      console.log('✓ Network found:');
      console.log(`  Name: ${net.name}`);
      console.log(`  ID: ${net.id}`);
      console.log(`  Driver: ${net.driver}`);
    } else {
      console.log('❌ Network not found');
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 3: فیلتر بر اساس درایور

(async () => {
  const k3 = new K3Core();
  
  try {
    const bridgeNetworks = await k3.networkCore.listNetworks({
      driver: "bridge"
    });
    
    console.log(`✓ Bridge networks: ${bridgeNetworks.length}`);
    bridgeNetworks.forEach(net => {
      console.log(`  - ${net.name}`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 4: نمایش تفصیلی (Verbose)

(async () => {
  const k3 = new K3Core();
  
  try {
    const networks = await k3.networkCore.listNetworks({
      verbose: true
    });
    
    networks.forEach(net => {
      console.log(`\n📊 Network: ${net.name}`);
      console.log(`   ID: ${net.id}`);
      console.log(`   Driver: ${net.driver}`);
      console.log(`   Interface: ${net.networkIF_name}`);
      console.log(`   Subnet: ${net.IPAM.configs.subnet}`);
      console.log(`   Gateway: ${net.IPAM.configs.gateway}`);
      console.log(`   Containers: ${Object.keys(net.containers).length}`);
      
      if (Object.keys(net.containers).length > 0) {
        console.log('   Connected Containers:');
        Object.entries(net.containers).forEach(([name, ip]) => {
          console.log(`     - ${name}: ${ip}`);
        });
      }
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

خروجی:

📊 Network: my-bridge
   ID: a279434eea2bb32a
   Driver: bridge
   Interface: kb-a279434eea2b
   Subnet: 192.168.0.0/24
   Gateway: 192.168.0.1
   Containers: 2
   Connected Containers:
     - container-1: 192.168.0.2
     - container-2: 192.168.0.3

📊 Network: app-net
   ID: b389545ffb3cc43b
   Driver: bridge
   Interface: kb-b389545ffb3
   Subnet: 10.0.0.0/24
   Gateway: 10.0.0.1
   Containers: 0

---

مثال 5: نمایش فقط واسط‌ها (OnlyIFs)

(async () => {
  const k3 = new K3Core();
  
  try {
    const interfaces = await k3.networkCore.listNetworks({
      onlyIFs: true
    });
    
    console.log('✓ Network Interfaces:');
    interfaces.forEach(net => {
      console.log(`\n  Network: ${net.name}`);
      net.interfaces.forEach(iface => {
        console.log(`    - ${iface}`);
      });
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

خروجی:

✓ Network Interfaces:

  Network: my-bridge
    - kb-a279434eea2b

  Network: app-net
    - kb-b389545ffb3

  Network: vlan-net
    - kb-vlan-vlanIF
    - kb-vlan-bridgeIF

---

مثال 6: فیلتر شبکه‌های بدون کانتینر (Dangling)

(async () => {
  const k3 = new K3Core();
  
  try {
    const danglingNets = await k3.networkCore.listNetworks({
      dangling: "true",
      verbose: true
    });
    
    console.log(`✓ Dangling networks: ${danglingNets.length}`);
    danglingNets.forEach(net => {
      console.log(`  - ${net.name} (${net.driver})`);
      console.log(`    Subnet: ${net.IPAM.configs.subnet}`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 7: ترکیب فیلترها

(async () => {
  const k3 = new K3Core();
  
  try {
    const networks = await k3.networkCore.listNetworks({
      driver: "bridge",
      dangling: "false",
      verbose: true
    });
    
    console.log(`✓ Bridge networks with containers: ${networks.length}`);
    networks.forEach(net => {
      console.log(`  ${net.name}:`);
      console.log(`    Containers: ${Object.keys(net.containers).length}`);
      console.log(`    Subnet: ${net.IPAM.configs.subnet}`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 8: خلاصه (Quiet)

(async () => {
  const k3 = new K3Core();
  
  try {
    const options = {};
    
    if (process.env.VERBOSE) options.verbose = true;
    if (process.env.ONLY_IFS) options.onlyIFs = true;
    if (process.env.QUIET) options.quiet = true;
    
    const networks = await k3.networkCore.listNetworks(options);
    
    console.log('✓ Networks:');
    networks.forEach(net => {
      console.log(`  ${net.name} (${net.driver})`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 9: جستجو و تفصیل

(async () => {
  const k3 = new K3Core();
  
  try {
    // Search
    console.log('🔍 Searching for network...');
    const results = await k3.networkCore.listNetworks({
      driver: "bridge"
    });
    
    if (results.length === 0) {
      console.log('❌ No bridge networks found');
      return;
    }
    
    // Get details
    console.log('📊 Getting details...');
    const detailed = await k3.networkCore.listNetworks({
      name: results[0].name,
      verbose: true
    });
    
    if (detailed.length > 0) {
      const net = detailed[0];
      console.log(`\n✓ Network Details:`);
      console.log(`  ID: ${net.id}`);
      console.log(`  Name: ${net.name}`);
      console.log(`  Driver: ${net.driver}`);
      console.log(`  Subnet: ${net.IPAM.configs.subnet}`);
      console.log(`  Containers: ${Object.keys(net.containers).length}`);
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 10: Export لیست شبکه‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    const networks = await k3.networkCore.listNetworks({
      verbose: true
    });
    
    const report = networks.map(net => ({
      name: net.name,
      id: net.id,
      driver: net.driver,
      subnet: net.IPAM.configs.subnet,
      gateway: net.IPAM.configs.gateway,
      containers: Object.keys(net.containers).length,
      interface: net.networkIF_name
    }));
    
    console.log('✓ Network Report:');
    console.table(report);
    
    // Save to file
    const fs = require('fs');
    fs.writeFileSync('networks-report.json', JSON.stringify(report, null, 2));
    console.log('✓ Report saved to networks-report.json');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

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

الگو 1: لیست و فیلتر

const listByDriver = async (driver) => {
  try {
    const networks = await k3.networkCore.listNetworks({
      driver: driver
    });
    
    console.log(`✓ ${driver} networks: ${networks.length}`);
    return networks;
  } catch (error) {
    console.log(error.createFullMessage());
    return [];
  }
};

// Usage
const bridges = await listByDriver('bridge');
const macvlans = await listByDriver('macvlan');

---

الگو 2: لیست با صفحه‌بندی

class NetworkLister {
  constructor(k3) {
    this.k3 = k3;
    this.pageSize = 10;
  }
  
  async listAll(options = {}) {
    try {
      const networks = await this.k3.networkCore.listNetworks(options);
      return this.paginate(networks);
    } catch (error) {
      console.log(error.createFullMessage());
      return [];
    }
  }
  
  paginate(networks) {
    const pages = [];
    for (let i = 0; i < networks.length; i += this.pageSize) {
      pages.push(networks.slice(i, i + this.pageSize));
    }
    return pages;
  }
}

const lister = new NetworkLister(k3);
const pages = await lister.listAll();

---

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

class NetworkMonitor {
  constructor(k3) {
    this.k3 = k3;
  }
  
  async checkHealth() {
    try {
      const networks = await this.k3.networkCore.listNetworks({
        verbose: true
      });
      
      const report = {
        total: networks.length,
        healthy: 0,
        warnings: []
      };
      
      networks.forEach(net => {
        if (Object.keys(net.containers).length > 0) {
          report.healthy++;
        } else {
          report.warnings.push(`⚠️  Dangling network: ${net.name}`);
        }
      });
      
      return report;
    } catch (error) {
      console.log(error.createFullMessage());
      return null;
    }
  }
}

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

---

نکات عملی

1. فیلترهای معتبر:

   • id: شناسه یکتا
   • name: نام شبکه
   • driver: bridge, macvlan, host, none
   • dangling: true, false, all

2. گزینه‌های نمایش:

   • verbose: تمام اطلاعات
   • onlyIFs: فقط واسط‌ها
   • quiet: اطلاعات خلاصه

3. ترکیب فیلترها:

   • می‌توان چند فیلتر را ترکیب کرد
   • ترتیب فیلترها اهمیتی ندارد

4. Performance:

   • verbose بار زیادی دارد
   • برای لیست بزرگ timeout احتمالی
   • onlyIFs سریعترین است

5. Best Practices:

   • برای بررسی وجود: name فیلتر کنید
   • برای تفصیلات: verbose استفاده کنید
   • برای واسط‌ها: onlyIFs استفاده کنید

---

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

1. دریافت لیست از NetworkManager
2. اعتبارسنجی پاسخ
3. اعمال فیلترها
4. فرمت‌کردن خروجی
5. Logging عملیات
6. بازگشت نتیجه

---

مرجع سریع

فیلتر	نوع	مثال
id	String	{ id: "a279434eea2bb32a" }
name	String	{ name: "my-bridge" }
driver	String	{ driver: "bridge" }
dangling	String	{ dangling: "true" }
verbose	Boolean	{ verbose: true }
onlyIFs	Boolean	{ onlyIFs: true }
quiet	Boolean	{ quiet: true }

---

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

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

const all = await k3.networkCore.listNetworks();

جستجو بر اساس نام

const found = await k3.networkCore.listNetworks({ name: "my-net" });

فیلتر بر اساس درایور

const bridges = await k3.networkCore.listNetworks({ driver: "bridge" });

شبکه‌های بدون کانتینر

const dangling = await k3.networkCore.listNetworks({ dangling: "true" });

اطلاعات تفصیلی

const details = await k3.networkCore.listNetworks({ verbose: true });

---

---

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