ادامه اجرای کانتینر

کانتینری که موقتاً متوقف (paused) شده است را دوباره شروع می‌کند.

---

🧩 دستور کلی

async resumeContainer(containerId, options = {})

---

شرح عملکرد

این متد کانتینر مشخص شده را که در وضعیت pause قرار دارد مجدداً راه‌اندازی می‌کند. در این حالت:

• پردازش‌های داخل کانتینر از جایی که متوقف شدند ادامه می‌یابند
• کانتینر به وضعیت running برمی‌گردد
• تمام داده‌های موجود محفوظ است

مهم: این دستور فقط روی کانتینرهای در وضعیت paused کار می‌کند.

---

ورودی‌ها

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

---

خروجی

نوع: String

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

Using debug verbosity

---

استثناها (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"
}

راهنمای حل:

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

---

NotPaused (400)

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

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

جزئیات:

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

راهنمای حل:

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

---

BuildResumeDTO (422)

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

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

جزئیات:

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

راهنمای حل:

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

---

ResumeFailure (500)

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

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

جزئیات:

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

راهنمای حل:

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

---

FailedToUpdateStateAfterResume (500)

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

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

جزئیات:

{
  "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.resumeContainer('my-container');
    console.log('کانتینر با موفقیت از حالت pause خارج شد');
    console.log(result);
  } catch (error) {
    console.log(error.createFullMessage())
  }
})();

مثال 2: ادامه اجرا با زمان انتظار

(async () => {
  const k3 = new K3Core();
  
  try {
    // Wait 5 seconds before resuming the container
    const result = await k3.containerCore.resumeContainer('app-container', {
      time: 5
    });
    console.log('کانتینر دوباره شروع شد:', result);
  } catch (error) {
    console.log(error.createFullMessage())
  }
})();

مثال 3: ادامه اجرا با debug

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

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

(async () => {
  const k3 = new K3Core();
  const containerId = 'my-app';
  
  try {
    const result = await k3.containerCore.resumeContainer(containerId, {
      time: 2,
      debug: true
    });
    console.log('ادامه اجرا موفق');
    console.log(result);
  } catch (error) {
    // Container not found
    console.log(error.createFullMessage())
  }
})();

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

(async () => {
  const k3 = new K3Core();
  const containerId = 'worker-container';
  
  try {
    // Step 1: Start container if not running
    let [container] = await k3.containerCore.listContainers({ 
      containerId: containerId 
    });
    
    if (container.status !== 'running') {
      console.log('Starting container first...');
      await k3.containerCore.startContainer(containerId);
    }
    
    // Step 2: Pause the container
    console.log('Pausing container...');
    await k3.containerCore.pauseContainer(containerId);
    
    // Step 3: Perform some maintenance or other tasks
    console.log('Performing maintenance tasks...');
    await new Promise(resolve => setTimeout(resolve, 3000));
    
    // Step 4: Resume the container
    console.log('Resuming container...');
    const result = await k3.containerCore.resumeContainer(containerId);
    
    // Step 5: Verify container is running
    [container] = await k3.containerCore.listContainers({ 
      containerId: containerId 
    });
    
    if (container.status === 'running') {
      console.log('Container successfully resumed and is running');
    }
    
    console.log('Complete cycle finished');
  } catch (error) {
    console.error('Error in pause/resume cycle:', error.message);
  }
})();

مثال 6: مدیریت resume برای چند کانتینر

(async () => {
  const k3 = new K3Core();
  
  // Resume multiple paused containers
  const resumeMultiple = async (containerIds) => {
    const results = {
      succeeded: [],
      failed: []
    };
    
    for (const id of containerIds) {
      try {
        await k3.containerCore.resumeContainer(id);
        results.succeeded.push(id);
      } catch (error) {
        results.failed.push({
          id,
          error: error.message,
          type: error.type
        });
      }
    }
    
    return results;
  };
  
  // Resume three containers
  const results = await resumeMultiple(['c1', 'c2', 'c3']);
  console.log(`Succeeded: ${results.succeeded.length}`);
  console.log(`Failed: ${results.failed.length}`);
  
  results.failed.forEach(fail => {
    console.log(`Failed to resume ${fail.id}: ${fail.error}`);
  });
})();

---

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

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

خطا: ContainerNotFound (404)

راهنمای حل:

// Get list of all available containers
const allContainers = await k3.containerCore.listContainers({ all: true });
console.log('Available containers:', allContainers.map(c => c.name));

// Find paused containers
const pausedContainers = allContainers.filter(c => c.status === 'paused');
console.log('Paused containers:', pausedContainers.map(c => c.name));

// Find and resume the correct container
const container = pausedContainers.find(c => c.name.includes('my'));
if (container) {
  await k3.containerCore.resumeContainer(container.id);
}

الگو 2: کانتینر در وضعیت pause نیست

خطا: NotPaused (400)

راهنمای حل:

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

if (status.status === 'paused') {
  // Container is paused - can be resumed
  await k3.containerCore.resumeContainer('my-container');
} else if (status.status === 'running') {
  console.log('Container is already running');
} else if (status.status === 'stopped') {
  // Container is stopped - must start first
  console.log('Container is stopped, starting first...');
  await k3.containerCore.startContainer('my-container');
}

الگو3 : بررسی وضعیت قبل از resume

راهنمای حل:

const safeResume = async (containerId) => {
  try {
    // Check current status
    const [container] = await k3.containerCore.listContainers({ 
      containerId: containerId 
    });
    
    // Only resume if paused
    if (container.status === 'paused') {
      console.log('Container is paused - resuming...');
      const result = await k3.containerCore.resumeContainer(containerId);
      console.log('Resume successful');
      return result;
    } else {
      console.log(`Container is ${container.status} - no need to resume`);
      return null;
    }
  } catch (error) {
    console.log(error.createFullMessage())
    throw error;
  }
};

await safeResume('my-container');

---

نکات عملی

1. شرط‌های resume:

   • فقط کانتینرهای paused قابل resume هستند
   • اگر کانتینر در حال اجرا است، نیاز به resume ندارد

2. پارامتر time:

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

3. حالت Debug:

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

4. بعد از resume:

   • وضعیت کانتینر: running
   • پردازش‌ها از جایی که متوقف شدند ادامه می‌یابند
   • تمام داده‌ها محفوظ است

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

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

6. تفاوت resume و start:

   • Resume: ادامه از وضعیت pause، داده‌ها محفوظ
   • Start: شروع از ابتدا برای کانتینرهای created یا stopped

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	کانتینر دوباره شروع شد
یافت نشد	404	ContainerNotFound
وضعیت نامناسب	400	NotPaused
خطای دیتابیس	500	FetchContainerState
خطای resume	500	ResumeFailure
خطای بروزرسانی	500	FailedToUpdateStateAfterResume

---

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