feat(instances): add pause and resume functionality

docs/FEATURES.md

@@ -31,10 +31,13 @@ This document provides a comprehensive overview of every feature currently imple
   - **Networking**: Integrated with Open vSwitch (OVS) for true SDN.
 
 - **Backend Selection**: Set via `COMPUTE_BACKEND` environment variable (`docker` or `libvirt`).
-- **Lifecycle**: The `InstanceService` manages the backend API to Create, Start, Stop, Resize, and Remove instances.
+- **Lifecycle**: The `InstanceService` manages the backend API to Create, Start, Stop, Pause, Resume, Resize, and Remove instances.
+- **Instance States**: Instances transition through states: `INITIALIZING` → `RUNNING` → `STOPPED` / `PAUSED` → `DELETED`. The `PAUSED` state freezes CPU while retaining memory and network connections.
+- **Pause/Resume**: RUNNING instances can be paused (via `DomainSuspend` for Libvirt, `ContainerPause` for Docker) and later resumed. State transitions are validated to ensure proper ordering.
 - **Instance Metadata & Labels**: Support for arbitrary key-value pairs assigned to instances for organization and filtering.
 - **Cloud-Init (Docker Simulation)**: Simulates Cloud-Init configuration injection in containers (SSH keys, script execution).
 - **Self-Healing**: Automated background worker that detects instances in `ERROR` state and attempts recovery via restart.
+- **Resilient Compute**: Backend operations are wrapped with circuit breaker and bulkhead patterns for fault tolerance.
 
 ### 2. Networking (VPC & Elastic IPs)
 **What it is**: Isolated virtual networks and static public IP addresses.

docs/api-reference.md

@@ -263,6 +263,40 @@ Get the VNC console URL for the instance.
 }
 ```
 
+### POST /instances/:id/pause
+Pause a running instance (freezes CPU, retains memory/network).
+
+**Prerequisites:** Instance must be in `RUNNING` state.
+
+**Response:**
+```json
+{
+  "message": "instance paused"
+}
+```
+
+**Error Responses:**
+- `400` — Instance not in RUNNING state (returned as `CONFLICT`)
+- `404` — Instance not found
+- `403` — Insufficient permissions
+
+### POST /instances/:id/resume
+Resume a paused instance back to running state.
+
+**Prerequisites:** Instance must be in `PAUSED` state.
+
+**Response:**
+```json
+{
+  "message": "instance resumed"
+}
+```
+
+**Error Responses:**
+- `400` — Instance not in PAUSED state (returned as `CONFLICT`)
+- `404` — Instance not found
+- `403` — Insufficient permissions
+
 ---
 
 ## Images

docs/guides/libvirt-backend.md

@@ -442,6 +442,7 @@ Always use virtio for best I/O performance:
 | **Networking** | Bridge/overlay | NAT/bridge/macvtap |
 | **Storage** | Overlay2/volumes | QCOW2/raw images |
 | **Volume Attach/Detach** | Stop→recreate→start cycle | True hot-plug via DomainAttachDevice |
+| **Pause/Resume** | ContainerPause/Unpause | DomainSuspend/DomainResume |
 | **Use Cases** | Microservices, CI/CD | Legacy apps, multi-OS, security |
 
 ## Best Practices

docs/swagger/docs.go

@@ -3974,6 +3974,76 @@ const docTemplate = `{
                 }
             }
         },
+        "/instances/{id}/pause": {
+            "post": {
+                "security": [
+                    {
+                        "APIKeyAuth": []
+                    }
+                ],
+                "description": "Freezes a running instance (CPU halted, memory/network retained)",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "instances"
+                ],
+                "summary": "Pause an instance",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Instance ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "409": {
+                        "description": "Instance not in RUNNING state",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    }
+                }
+            }
+        },
         "/instances/{id}/resize": {
             "post": {
                 "security": [
@@ -4044,6 +4114,76 @@ const docTemplate = `{
                 }
             }
         },
+        "/instances/{id}/resume": {
+            "post": {
+                "security": [
+                    {
+                        "APIKeyAuth": []
+                    }
+                ],
+                "description": "Resumes a paused instance back to running state",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "instances"
+                ],
+                "summary": "Resume an instance",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Instance ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "409": {
+                        "description": "Instance not in PAUSED state",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/httputil.Response"
+                        }
+                    }
+                }
+            }
+        },
         "/instances/{id}/stats": {
             "get": {
                 "security": [
@@ -8934,13 +9074,15 @@ const docTemplate = `{
                 "RUNNING",
                 "STOPPED",
                 "ERROR",
+                "PAUSED",
                 "DELETED"
             ],
             "x-enum-varnames": [
                 "StatusStarting",
                 "StatusRunning",
                 "StatusStopped",
                 "StatusError",
+                "StatusPaused",
                 "StatusDeleted"
             ]
         },