# Nomad API Integration

This document explains how the Nomad API integration works in this application, the recent improvements made, and how to test the functionality.

## Overview

This application uses Hashicorp Nomad for job orchestration, interacting with Nomad through its HTTP API. The integration allows starting, stopping, and monitoring jobs in Nomad.

## Recent Improvements

The following improvements have been made to the Nomad service integration:

1. **Simplified Namespace Handling**:
   - Clear priority order for determining which namespace to use:
     1. Explicitly specified in job spec (highest priority)
     2. Service instance namespace (default: "development")
   - Consistent namespace handling across all API operations
   - Better logging of namespace resolution

2. **Standardized Job Specification Formatting**:
   - Consistent normalization of job specifications to ensure proper structure
   - Always ensures job specs are wrapped in a "Job" key as required by Nomad
   - Maintains any existing structure while normalizing as needed

3. **Enhanced Error Handling**:
   - Improved error messages with more context
   - Added logging of API responses for better troubleshooting
   - Returns namespace information in responses

4. **Automated Testing**:
   - Added pytest tests to verify job start/stop functionality
   - Tests cover different job specification formats
   - Auto-cleanup of test jobs

## How to Run Tests

### Prerequisites

1. Set up the environment variables:
   - `NOMAD_ADDR`: URL of your Nomad server (e.g., `http://pjmldk01.ds.meisheng.group:4646`)
   - `NOMAD_TOKEN`: Authentication token (if your Nomad cluster uses ACLs)
   - `NOMAD_NAMESPACE`: Default namespace to use (defaults to "development")

2. Install test dependencies:
   ```
   pip install pytest pytest-cov
   ```

### Running the Tests

From the project root directory:

```bash
python -m pytest tests/test_nomad_service.py -v
```

Add coverage reporting:

```bash
python -m pytest tests/test_nomad_service.py --cov=app.services.nomad_client -v
```

## Manual API Testing

You can use PowerShell to test Nomad API operations directly:

### List Jobs

```powershell
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/jobs?namespace=development" -Method GET
```

### Get Job Details

```powershell
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/job/example-job?namespace=development" -Method GET
```

### Start a Job

```powershell
$jobSpec = @{ 
  "Job" = @{
    "ID" = "example-job"
    "Name" = "example-job"
    "Namespace" = "development"
    # Other job properties
  }
} | ConvertTo-Json -Depth 20

Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/jobs" -Method POST -Body $jobSpec -ContentType "application/json"
```

### Stop a Job

```powershell
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/job/example-job?namespace=development" -Method DELETE
```

## API Documentation

For more comprehensive documentation on the Nomad API integration, refer to the `nomad_job_api_docs.md` file.

## Troubleshooting

### Common Issues

1. **Job Not Found**: Ensure you're specifying the correct namespace
2. **Failed to Start Job**: Check job specification format and resource requirements
3. **Permission Denied**: Verify ACL token has appropriate permissions

### Debugging Tips

1. Check the application logs for detailed error messages
2. Use the `-v` flag with pytest to see more verbose output
3. Try direct API requests to isolate application vs. Nomad API issues