Jobs & Async Operations

Fugoku uses an asynchronous job system for all resource provisioning and lifecycle operations. Jobs track the progress of long-running tasks and provide visibility into what's happening behind the scenes.

Why Jobs Exist

Infrastructure operations like creating a server or instance can take minutes to complete. Rather than blocking the API request, Fugoku enqueues these operations as background jobs and returns immediately with a job ID. You can then poll the job status to track progress.

Job Lifecycle

Jobs progress through the following states:

pending → processing → completed
                    ↘ failed

Job Types

Job Retry Logic

Jobs are retried automatically on failure:

• Max attempts: 3
• Backoff: Exponential (1s, 2s, 4s)
• After max attempts: Job transitions to failed

Viewing Job History

List Jobs

curl https://api.fugoku.com/v1/jobs \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Filter by Status

curl "https://api.fugoku.com/v1/jobs?status=failed" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Filter by Instance

curl "https://api.fugoku.com/v1/jobs?instanceId=inst-abc123" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Get Job Details

curl https://api.fugoku.com/v1/jobs/job-abc123 \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Response:

{
  "data": {
    "id": "job-abc123",
    "type": "jobs",
    "attributes": {
      "type": "instance.create",
      "status": "completed",
      "attempts": 1,
      "maxAttempts": 3,
      "error": null,
      "createdAt": "2024-02-25T10:30:00Z",
      "updatedAt": "2024-02-25T10:31:00Z",
      "startedAt": "2024-02-25T10:30:01Z",
      "completedAt": "2024-02-25T10:31:00Z"
    }
  }
}

List Failed Jobs

curl https://api.fugoku.com/v1/jobs/failed \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Manual Retry

When a job fails, you can retry it manually:

curl -X POST https://api.fugoku.com/v1/jobs/job-abc123/retry \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "data": {
    "jobId": "job-abc123",
    "status": "retrying"
  }
}

Understanding Job Payloads

Each job contains a payload that describes what operation is being performed:

• Server create: Plan, OS, region, hostname, SSH keys, role
• Server action: Action type (start, stop, reboot, etc.)
• Backup create: Server ID, backup name

The payload is stored in the job record and can be inspected for debugging.

Jobs and Servers

You can view all jobs associated with a specific server:

curl "https://api.fugoku.com/v1/servers/srv-abc123/jobs" \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN"

Best Practices

1. Poll job status — Don't assume an operation is complete immediately after the API returns
2. Check job status — Before taking further action, verify the job completed successfully
3. Handle failures — Check the error field on failed jobs for diagnostic information
4. Use manual retry — For transient failures, retry the job instead of creating a new one
5. Monitor job history — Review job history for patterns in failures