حذف شبکه

شبکه‌های K3 را حذف می‌کند. برخی شبکه‌ها محافظت‌شده هستند و نیاز به force دارند.

---

🧩 دستور کلی

async deleteNetwork(network, options = {})

---

شرح عملکرد

این متد یک شبکه را حذف می‌کند. شامل:

• اعتبارسنجی پارامتر شبکه (ID یا نام)
• بارگذاری اطلاعات شبکه
• بررسی شبکه‌های محافظت‌شده
• بررسی شبکه‌های در حال استفاده
• حذف واسط‌های شبکه
• پاک‌کردن قوانین Firewall
• ثبت تغییرات در دیتابیس
• Logging عملیات

نکته مهم:

• شبکه‌های پیش‌فرض (kb0، none، host) نیاز به force: true دارند
• شبکه‌های در حال استفاده توسط کانتینر نیاز به force: true دارند
• شبکه‌های داخلی macvlan (-bridge-mac) قابل حذف نیستند

---

ورودی‌ها

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

مثال‌های network

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

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

// شبکه پیش‌فرض (نیاز به force)
"kb0"

مثال‌های options

// حذف عادی
{}

// حذف با force (برای شبکه‌های محافظت‌شده)
{ force: true }

---

خروجی

نوع: Object

بازگشت اطلاعات شبکه حذف‌شده (مانند inspectNetwork):

{
  id: "a279434eea2bb32a",
  name: "my-bridge",
  driver: "bridge",
  networkIF_name: "kb-a279434eea2b",
  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"
}

---

استثناها (Errors)

InvalidDeleteNetworkParameters (422)

پیام: "Invalid delete 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.deleteNetwork(null);
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [VALIDATION_ERROR] (422)
  // Type: InvalidDeleteNetworkParameters
  // Message: Invalid delete 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.deleteNetwork("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
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-notfound02
}

---

InspectNetworkFailure (500)

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

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

جزئیات:

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

راهنمای حل:

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

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

try {
  await k3.networkCore.deleteNetwork("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-inspect03
}

---

ProtectedMacvlanBridge (403)

پیام: "Cannot delete protected macvlan internal bridge."

زمان رخ دادن: تلاش برای حذف bridge داخلی macvlan

جزئیات:

{
  "type": "INVALID_STATE_ERROR",
  "statusCode": 403,
  "network": "app-bridge-mac",
  "error": "This is an internal macvlan bridge and cannot be deleted directly"
}

راهنمای حل:

• این شبکه محافظت‌شده است
• درعوض، macvlan parent را حذف کنید
• bridge داخلی خودکار حذف می‌شود

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

try {
  await k3.networkCore.deleteNetwork("app-bridge-mac");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [INVALID_STATE_ERROR] (403)
  // Type: ProtectedMacvlanBridge
  // Message: Cannot delete protected macvlan internal bridge.
  // Network: app-bridge-mac
  // Details: This is an internal macvlan bridge
  // Solution: Delete the parent macvlan network instead
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-protected04
}

---

ProtectedDefaultNetwork (403)

پیام: "Cannot delete protected default network without force option."

زمان رخ دادن: تلاش برای حذف شبکه پیش‌فرض بدون force

جزئیات:

{
  "type": "INVALID_STATE_ERROR",
  "statusCode": 403,
  "network": "kb0",
  "error": "Default network is protected. Use force option."
}

راهنمای حل:

• استفاده کنید: { force: true }
• شبکه‌های پیش‌فرض: kb0، none، host
• فقط اگر خیلی ضروری باشد

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

try {
  await k3.networkCore.deleteNetwork("kb0");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [INVALID_STATE_ERROR] (403)
  // Type: ProtectedDefaultNetwork
  // Message: Cannot delete protected default network without force option.
  // Network: kb0
  // Protected Networks: kb0, none, host
  // Solution: Use force option: { force: true }
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-default05
}

---

NetworkInUse (409)

پیام: "Network is in use by containers. Cannot delete without force option."

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

جزئیات:

{
  "type": "INVALID_STATE_ERROR",
  "statusCode": 409,
  "network": "app-network",
  "containersCount": 2,
  "error": "Network has active containers"
}

راهنمای حل:

• کانتینرها را متصل کنید یا حذف کنید
• یا استفاده کنید: { force: true }
• برای ایمن‌تر: ابتدا کانتینرها را قطع کنید

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

try {
  await k3.networkCore.deleteNetwork("app-network");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [INVALID_STATE_ERROR] (409)
  // Type: NetworkInUse
  // Message: Network is in use by containers. Cannot delete without force option.
  // Network: app-network
  // Containers Connected: 2
  // Solution: Either disconnect containers or use { force: true }
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-inuse06
}

---

DeleteNetworkInterfaceFailure (500)

پیام: "Failed to delete network interface."

زمان رخ دادن: خطا در حذف واسط فیزیکی

جزئیات:

{
  "type": "NETWORK_ERROR",
  "statusCode": 500,
  "network": "my-bridge",
  "error": "ip link delete failed"
}

راهنمای حل:

• اجازه‌های root را بررسی کنید
• واسط استفاده‌شده است؟
• NetworkManager را restart کنید

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

try {
  await k3.networkCore.deleteNetwork("my-bridge");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NETWORK_ERROR] (500)
  // Type: DeleteNetworkInterfaceFailure
  // Message: Failed to delete network interface.
  // Network: my-bridge
  // System Error: Operation not permitted
  // Details: Interface deletion failed (ip link delete)
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-delif07
}

---

DeleteNetworkStateFailure (500)

پیام: "Failed to update network state during deletion."

زمان رخ دادن: خطا در پاک‌کردن قوانین یا state

جزئیات:

{
  "type": "NETWORK_ERROR",
  "statusCode": 500,
  "network": "my-bridge",
  "error": "NFTable rules removal failed"
}

راهنمای حل:

• قوانین firewall را بررسی کنید
• NFTable را بررسی کنید
• لاگ‌های سیستم را بررسی کنید

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

try {
  await k3.networkCore.deleteNetwork("my-bridge");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NETWORK_ERROR] (500)
  // Type: DeleteNetworkStateFailure
  // Message: Failed to update network state during deletion.
  // Network: my-bridge
  // Details: NFTable rules removal failed
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-state08
}

---

DeleteNetworkFailure (500)

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

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

جزئیات:

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

راهنمای حل:

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

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

try {
  await k3.networkCore.deleteNetwork("my-bridge");
} catch (error) {
  console.log(error.createFullMessage());
  // Output:
  //  ERROR [NETWORK_ERROR] (500)
  // Type: DeleteNetworkFailure
  // Message: Failed to delete network.
  // Network: my-bridge
  // Details: Unexpected error during deletion
  // Timestamp: 2025-12-01T13:45:30Z
  // Request ID: req-del09
}

---

GenericFailure (500)

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

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

جزئیات:

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

راهنمای حل:

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

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

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

---

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

مثال 1: حذف شبکه عادی

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.networkCore.deleteNetwork('my-bridge');
    
    console.log('✓ Network deleted successfully');
    console.log(`  Name: ${result.name}`);
    console.log(`  Driver: ${result.driver}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

خروجی:

✓ Network deleted successfully
  Name: my-bridge
  Driver: bridge

---

مثال 2: حذف شبکه پیش‌فرض با force

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log('  Deleting default network with force...');
    
    const result = await k3.networkCore.deleteNetwork('kb0', {
      force: true
    });
    
    console.log('✓ Default network deleted');
    console.log(`  Name: ${result.name}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 3: حذف شبکه در حال استفاده با force

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log('  Deleting network in use with force...');
    
    const result = await k3.networkCore.deleteNetwork('app-network', {
      force: true
    });
    
    console.log('✓ Network deleted (containers will be disconnected)');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 4: جستجو و حذف

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log(' Searching for network...');
    
    const networks = await k3.networkCore.listNetworks({
      name: 'test-net'
    });
    
    if (networks.length === 0) {
      console.log(' Network not found');
      return;
    }
    
    console.log('🗑️  Deleting network...');
    const result = await k3.networkCore.deleteNetwork(networks[0].name);
    
    console.log(`✓ ${result.name} deleted`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 5: حذف با بررسی کانتینرها

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log(' Inspecting network...');
    
    const network = await k3.networkCore.inspectNetwork('app-network');
    const containerCount = Object.keys(network.containers).length;
    
    if (containerCount > 0) {
      console.log(`  Network has ${containerCount} containers`);
      console.log('  Deleting with force...');
      
      await k3.networkCore.deleteNetwork('app-network', {
        force: true
      });
      
      console.log('✓ Network deleted (containers disconnected)');
    } else {
      console.log('✓ Network is empty');
      
      const result = await k3.networkCore.deleteNetwork('app-network');
      console.log(`✓ ${result.name} deleted`);
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 6: حذف چند شبکه

(async () => {
  const k3 = new K3Core();
  
  try {
    const networksToDelete = ['test-1', 'test-2', 'test-3'];
    const results = [];
    
    for (const name of networksToDelete) {
      try {
        const result = await k3.networkCore.deleteNetwork(name);
        results.push({
          name: name,
          status: 'deleted',
          id: result.id
        });
        console.log(`✓ ${name} deleted`);
      } catch (error) {
        results.push({
          name: name,
          status: 'failed',
          error: error.message
        });
        console.log(` Failed to delete ${name}`);
      }
    }
    
    console.log('\n=== Deletion Summary ===');
    console.table(results);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 7: حذف و تمیزکاری

(async () => {
  const k3 = new K3Core();
  
  try {
    console.log(' Cleanup: Finding dangling networks...');
    
    const networks = await k3.networkCore.listNetworks({
      dangling: 'true',
      verbose: true
    });
    
    console.log(`Found ${networks.length} dangling networks`);
    
    for (const net of networks) {
      try {
        await k3.networkCore.deleteNetwork(net.name);
        console.log(`✓ Deleted: ${net.name}`);
      } catch (error) {
        console.log(` Failed: ${net.name}`);
      }
    }
    
    console.log('✓ Cleanup complete');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 8: حذف ایمن با تایید

(async () => {
  const k3 = new K3Core();
  const readline = require('readline');
  
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
  });
  
  try {
    const network = await k3.networkCore.inspectNetwork('app-network');
    
    console.log(' Network Details:');
    console.log(`  Name: ${network.name}`);
    console.log(`  Driver: ${network.driver}`);
    console.log(`  Subnet: ${network.subnet}`);
    console.log(`  Containers: ${Object.keys(network.containers).length}`);
    
    rl.question('\n  Delete this network? (yes/no): ', async (answer) => {
      if (answer.toLowerCase() === 'yes') {
        try {
          const result = await k3.networkCore.deleteNetwork(network.name, {
            force: Object.keys(network.containers).length > 0
          });
          console.log('✓ Network deleted');
        } catch (error) {
          console.log(error.createFullMessage());
        }
      } else {
        console.log('✗ Deletion cancelled');
      }
      rl.close();
    });
  } catch (error) {
    console.log(error.createFullMessage());
    rl.close();
  }
})();

---

مثال 9: حذف با Backup

(async () => {
  const k3 = new K3Core();
  const fs = require('fs');
  
  try {
    const networkName = 'app-network';
    
    console.log(' Backing up network info...');
    
    const network = await k3.networkCore.inspectNetwork(networkName);
    
    // Save backup
    const backup = {
      network: network,
      deletedAt: new Date().toISOString()
    };
    
    fs.writeFileSync(
      `backup-${networkName}.json`,
      JSON.stringify(backup, null, 2)
    );
    
    console.log(`✓ Backup saved to backup-${networkName}.json`);
    
    // Delete
    console.log('  Deleting network...');
    await k3.networkCore.deleteNetwork(networkName, { force: true });
    
    console.log('✓ Network deleted');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

مثال 10: حذف و تأیید

(async () => {
  const k3 = new K3Core();
  
  try {
    const networkName = 'test-network';
    
    console.log('  Deleting network...');
    const deleted = await k3.networkCore.deleteNetwork(networkName);
    
    console.log('✓ Network deleted');
    console.log(`  Name: ${deleted.name}`);
    
    // Verify deletion
    console.log('\n🔍 Verifying deletion...');
    
    try {
      await k3.networkCore.inspectNetwork(networkName);
      console.log('❌ Network still exists!');
    } catch (error) {
      if (error.statusCode === 404) {
        console.log('✓ Network successfully deleted');
      } else {
        console.log(error.createFullMessage());
      }
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

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

الگو 1: حذف ایمن

const safeDelete = async (networkName) => {
  try {
    // Check if network exists
    const networks = await k3.networkCore.listNetworks({ name: networkName });
    if (networks.length === 0) {
      console.log(`❌ Network ${networkName} not found`);
      return false;
    }
    
    // Check containers
    const network = await k3.networkCore.inspectNetwork(networkName);
    const hasContainers = Object.keys(network.containers).length > 0;
    
    // Delete with appropriate options
    await k3.networkCore.deleteNetwork(networkName, {
      force: hasContainers
    });
    
    console.log(`✓ ${networkName} deleted successfully`);
    return true;
  } catch (error) {
    console.log(error.createFullMessage());
    return false;
  }
};

---

الگو 2: حذف دسته‌ای

class NetworkCleaner {
  constructor(k3) {
    this.k3 = k3;
  }
  
  async deleteByPattern(pattern) {
    const networks = await this.k3.networkCore.listNetworks();
    const matches = networks.filter(n => n.name.includes(pattern));
    
    const results = {
      succeeded: [],
      failed: []
    };
    
    for (const net of matches) {
      try {
        await this.k3.networkCore.deleteNetwork(net.name, { force: true });
        results.succeeded.push(net.name);
      } catch (error) {
        results.failed.push({ name: net.name, error: error.message });
      }
    }
    
    return results;
  }
}

const cleaner = new NetworkCleaner(k3);
const results = await cleaner.deleteByPattern('test-');

---

الگو 3: حذف با Rollback

const deleteWithRollback = async (networkName) => {
  const k3 = require('k3-core');
  const fs = require('fs');
  
  try {
    // Backup
    const network = await k3.networkCore.inspectNetwork(networkName);
    const backup = { network, timestamp: Date.now() };
    
    fs.writeFileSync(`rollback-${networkName}.json`, JSON.stringify(backup));
    
    // Delete
    await k3.networkCore.deleteNetwork(networkName);
    
    console.log('✓ Network deleted (rollback available)');
  } catch (error) {
    console.log(error.createFullMessage());
    console.log('⚠️  Rollback file available if needed');
  }
};

---

نکات عملی

1. شبکه‌های محافظت‌شده:

   • kb0، none، host نیاز به force دارند
   • پیش‌فرض سیستم هستند
   • فقط اگر خیلی ضروری باشد

2. شبکه‌های در حال استفاده:

   • کانتینرهای متصل نیاز به force دارند
   • یا کانتینرها را ابتدا disconnect کنید
   • safer approach: ابتدا کانتینرها را حذف کنید

3. شبکه‌های Macvlan:

   • (-bridge-mac) قابل حذف نیست
   • parent را حذف کنید
   • bridge داخلی خودکار حذف می‌شود

4. بررسی قبل حذف:

   • همیشه inspectNetwork استفاده کنید
   • اطمینان حاصل کنید کانتینری متصل نیست
   • backup تهیه کنید

5. Best Practices:

   • از force فقط وقتی ضروری است استفاده کنید
   • همیشه try-catch استفاده کنید
   • log کلیه تغییرات

---

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

1. اعتبارسنجی پارامتر
2. بارگذاری اطلاعات شبکه
3. بررسی محافظت‌ها (-bridge-mac)
4. بررسی شبکه‌های پیش‌فرض
5. بررسی کانتینرهای متصل
6. حذف واسط فیزیکی
7. حذف قوانین Firewall
8. حذف state از دیتابیس
9. Logging عملیات
10. بازگشت اطلاعات شبکه

---

مرجع سریع

شبکه	محافظت	تلاش اول	با Force
معمولی	❌ خیر	✓ ممکن	✓ ممکن
kb0	بله	✗ نه	✓ ممکن
none	بله	✗ نه	✓ ممکن
host	بله	✗ نه	✓ ممکن
در حال استفاده	⚠️ شرطی	✗ نه	✓ ممکن
-bridge-mac	بله	✗ نه	✗ نه

---

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

حذف ساده

await k3.networkCore.deleteNetwork('my-bridge');

حذف پیش‌فرض

await k3.networkCore.deleteNetwork('kb0', { force: true });

حذف در حال استفاده

await k3.networkCore.deleteNetwork('app-net', { force: true });

حذف جستجو‌شده

const nets = await k3.networkCore.listNetworks({ name: 'test' });
if (nets.length > 0) {
  await k3.networkCore.deleteNetwork(nets[0].name);
}

---

---

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