توقف موقتی کانتینر

کانتینری که در حال اجرا است را به طور موقتی فریز (pause) می‌کند.

---

🧩 دستور کلی

async pauseContainer(containerId, options = {})

---

شرح عملکرد

این متد کانتینر مشخص شده را موقتاً فریز (pause) می‌کند. در این حالت:

• پردازش‌های داخل کانتینر متوقف می‌شوند
• کانتینر کاملاً متوقف (stop) نمی‌شود
• می‌توان بعداً با resumeContainer() ادامه داد

مهم: این دستور فقط روی کانتینرهای در حال اجرا (running) کار می‌کند.

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
containerId	String	بله	شناسه یا نام کانتینر برای توقف موقتی
options	Object	خیر	گزینه‌های اختیاری
options.time	Number	خیر	زمان انتظار قبل از توقف موقتی (به ثانیه)
options.debug	Boolean	خیر	فعال کردن حالت debug برای لاگ‌های تفصیلی

---

خروجی

نوع: String (debug output از crun runtime)

خروجی شامل پیام‌های تفصیلی از فرآیند توقف موقتی:

Pause result: Using debug verbosity

فیلدهای خروجی:

• Using debug verbosity - حالت debug فعال شده

---

استثناها (Errors)

ContainerNotFound (404)

پیام: "No container exists with the specified name or ID prefix."

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

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "containerId": "invalid-id"
}

راهنمای حل:

• شناسه کانتینر را بررسی کنید
• listContainers() استفاده کنید تا تمام کانتینرها را ببینید
• نام یا ID صحیح را وارد کنید

---

ResolveContainerName (500)

پیام: "Database error occurred while resolving container name or ID."

زمان رخ دادن: خطای دیتابیس در تطابق شناسه/نام کانتینر

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "input": "container-id",
  "error": "Database connection lost"
}

راهنمای حل:

• اتصال دیتابیس را بررسی کنید
• لاگ‌های دیتابیس را مطالعه کنید
• دیتابیس را راه‌اندازی کنید

---

FetchContainerState (500)

پیام: "Database error occurred while fetching container state."

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

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Query timeout"
}

راهنمای حل:

• دیتابیس را بررسی کنید
• اتصال را تأیید کنید

---

NotRunning (400)

پیام: "Container is not in a running state. Start the container first."

زمان رخ دادن: کانتینر در وضعیت دیگری باشد (مثلاً stopped، paused، created)

جزئیات:

{
  "type": "INVALID_STATE",
  "statusCode": 400,
  "containerId": "abc123def456",
  "currentState": "stopped"
}

راهنمای حل:

• اگر کانتینر متوقف است، ابتدا با startContainer() شروع کنید
• فقط کانتینرهای در حال اجرا قابل pause هستند

---

BuildPauseDTO (422)

پیام: "Failed to build pause container DTO options."

زمان رخ دادن: هنگام ساخت دستورات pause

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "containerId": "abc123def456",
  "error": "Invalid options structure"
}

راهنمای حل:

• لاگ‌ها را بررسی کنید
• سرویس را دوباره شروع کنید

---

PauseFailure (500)

پیام: "Failed to pause container through ContainerManager."

زمان رخ دادن: خطا در فریز کردن کانتینر

جزئیات:

{
  "type": "CONTAINER_SERVICE_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Runtime error"
}

راهنمای حل:

• سرویس K3 فعال است یا خیر؟
• لاگ‌های سرویس را مطالعه کنید

---

FailedToUpdateStateAfterPause (500)

پیام: "Failed to update container state after pausing."

زمان رخ دادن: خطا در بروزرسانی وضعیت دیتابیس بعد از pause

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Database write failed"
}

راهنمای حل:

• دیتابیس را بررسی کنید
• اتصال را تأیید کنید

---

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

مثال 1: توقف موقتی ساده

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

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.pauseContainer('my-container');
    console.log('کانتینر با موفقیت متوقف شد');
    console.log(result);
  } catch (error) {
    if (error.statusCode === 404) {
      console.log('کانتینر یافت نشد');
    } else if (error.statusCode === 400) {
      console.log(`کانتینر در وضعیت ${error.detail.currentState} است`);
    } else {
      console.error('خطا:', error.message);
    }
  }
})();

مثال 2: توقف موقتی با زمان انتظار

(async () => {
  const k3 = new K3Core();
  
  try {
    // Wait 3 seconds before pausing the container
    const result = await k3.containerCore.pauseContainer('app-container', {
      time: 3
    });
    console.log('کانتینر متوقف شد:', result);
  } catch (error) {
    console.error('خطا:', error.message);
  }
})();

مثال 3: توقف موقتی با debug

(async () => {
  const k3 = new K3Core();
  
  try {
    // Enable debug mode to see detailed logs
    const result = await k3.containerCore.pauseContainer('web-server', {
      debug: true,
      time: 2
    });
    console.log('خروجی Debug:', result);
    // Output:
    // Pause result: Using debug verbosity
  } catch (error) {
    console.error('خطا:', error.message);
  }
})();

مثال 4: مدیریت تمام حالات

(async () => {
  const k3 = new K3Core();
  const containerId = 'my-app';
  
  try {
    const result = await k3.containerCore.pauseContainer(containerId, {
      time: 2,
      debug: true
    });
    console.log('توقف موقتی موفق');
    console.log(result);
  } catch (error) {
    // Container not found
    if (error.type === 'NOT_FOUND') {
      console.log('کانتینر وجود ندارد');
    }
    // Container state is invalid
    else if (error.type === 'INVALID_STATE') {
      console.log(`کانتینر در وضعیت "${error.detail.currentState}" است`);
      console.log('ابتدا کانتینر را شروع کنید');
    }
    // Database error
    else if (error.type === 'DB_ERROR') {
      console.log('مشکل دیتابیس');
    }
    // Other errors
    else {
      console.log('خطا:', error.message);
    }
  }
})();

مثال 5: چرخه pause/resume

(async () => {
  const k3 = new K3Core();
  const containerId = 'worker-container';
  
  try {
    // Check if container is running
    const [container] = await k3.containerCore.listContainers({ 
      containerId: containerId 
    });
    
    if (container.status !== 'running') {
      console.log('کانتینر در حال اجرا نیست');
      return;
    }
    
    // Pause the container
    console.log('توقف موقتی کانتینر...');
    await k3.containerCore.pauseContainer(containerId);
    
    // Do some other work while container is paused
    console.log('انجام کارهای دیگر...');
    await new Promise(resolve => setTimeout(resolve, 5000));
    
    // Resume the container
    console.log('ادامه کانتینر...');
    await k3.containerCore.resumeContainer(containerId);
    
    console.log('چرخه کامل شد');
  } catch (error) {
    console.error('خطا:', error.message);
  }
})();

---

الگوهای خطا و راهنمای حل

الگو 1: کانتینر یافت نشد

خطا: ContainerNotFound (404)

راهنمای حل:

// Get list of all available containers
const allContainers = await k3.containerCore.listContainers({ all: true });
console.log('کانتینرهای در دسترس:', allContainers.map(c => c.name));

// Find the correct container and use its ID
const container = allContainers.find(c => c.name.includes('my'));
if (container) {
  await k3.containerCore.pauseContainer(container.id);
}

الگو 2: کانتینر در حال اجرا نیست

خطا: NotRunning (400)

راهنمای حل:

// Check current container status
const [status] = await k3.containerCore.listContainers({ 
  containerId: 'my-container' 
});

if (status.status === 'running') {
  // Container is running - can be paused
  await k3.containerCore.pauseContainer('my-container');
} else if (status.status === 'stopped') {
  // Container is stopped - must start first
  console.log('کانتینر متوقف است، ابتدا شروع کنید');
  await k3.containerCore.startContainer('my-container');
  await k3.containerCore.pauseContainer('my-container');
} else if (status.status === 'paused') {
  console.log('کانتینر از قبل متوقف است');
}

الگو 3: مدیریت pause برای چند کانتینر

راهنمای حل:

const pauseMultiple = async (containerIds) => {
  const results = {
    succeeded: [],
    failed: []
  };
  
  for (const id of containerIds) {
    try {
      await k3.containerCore.pauseContainer(id);
      results.succeeded.push(id);
    } catch (error) {
      results.failed.push({
        id,
        error: error.message,
        type: error.type
      });
    }
  }
  
  return results;
};

// Pause multiple containers and get results
const results = await pauseMultiple(['c1', 'c2', 'c3']);
console.log(`Succeeded: ${results.succeeded.length}`);
console.log(`Failed: ${results.failed.length}`);

---

نکات عملی

1. شرط‌های pause:

   • فقط کانتینرهای running قابل pause هستند
   • اگر کانتینر paused باشد، نمی‌توانید دوباره pause کنید

2. پارامتر time:

   • مفید برای تأخیر موقتی قبل از pause
   • پیش‌فرض: ۰ ثانیه
   • می‌توانید از آن برای sync کردن با سایر عملیات استفاده کنید

3. حالت Debug:

   • خروجی تفصیلی از فرآیند pause
   • برای troubleshooting مفید است

4. بعد از pause:

   • وضعیت کانتینر: paused
   • برای ادامه: استفاده از resumeContainer()
   • منابع هنوز تخصیص یافته‌اند

5. کاربردهای اصلی:

   • دیباگ پردازش‌ها
   • مدیریت منابع سیستم
   • زمان‌بندی اجرای پردازش‌ها
   • آزمایش بدون حذف داده‌ها

6. تفاوت pause و stop:

   • Pause: موقتی، حالت محفوظ
   • Stop: دایمی تا startContainer دوباره فراخوانی شود

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	کانتینر موقتاً متوقف شد
یافت نشد	404	ContainerNotFound
وضعیت نامناسب	400	NotRunning
خطای دیتابیس	500	FetchContainerState
خطای pause	500	PauseFailure
خطای بروزرسانی	500	FailedToUpdateStateAfterPause

---

نسخه: 1.3 تاریخ آپدیت: ۹ آذر ۱۴۰۴