### Install Server API (Bash)

Source: https://context7.com/pyrohost/elytra/llms.txt

Initiates the installation process for a game server. Requires a node token for authorization.

```bash
curl -X POST "http://localhost:8080/api/servers/abc-123-def/install" \
  -H "Authorization: Bearer your-node-token"
```

--------------------------------

### POST /api/servers/{server_uuid}/install

Source: https://context7.com/pyrohost/elytra/llms.txt

Initiates the installation process for a specified server.

```APIDOC
## POST /api/servers/{server_uuid}/install

### Description
Trigger server installation process.

### Method
POST

### Endpoint
/api/servers/{server_uuid}/install

### Parameters
#### Path Parameters
- **server_uuid** (string) - Required - The unique identifier of the server.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X POST "http://localhost:8080/api/servers/abc-123-def/install" \
  -H "Authorization: Bearer your-node-token"
```

### Response
#### Success Response (200)
No specific response body is detailed, typically an empty success response or a status message.

#### Response Example
(No example provided in source)
```

--------------------------------

### Conventional Commit Scopes Example (Bash)

Source: https://github.com/pyrohost/elytra/blob/main/CONTRIBUTING.md

Examples demonstrating the use of scopes within Conventional Commits to provide additional context for the commit.

```bash
feat(backup): add compression options
fix(sftp): resolve permission issues
docs(readme): update installation instructions
```

--------------------------------

### Conventional Commit Example (Bash)

Source: https://github.com/pyrohost/elytra/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification. This format aids in automated versioning and changelog generation.

```bash
# Feature addition (minor bump)
feat: add support for rustic backup encryption

# Bug fix (patch bump)
fix: resolve server startup crash on invalid config

# Breaking change (major bump)
feat!: change default configuration format from TOML to YAML

# Breaking change with body
feat: add new authentication system

BREAKING CHANGE: the old authentication tokens are no longer supported
```

--------------------------------

### Manage Server Lifecycle and Resources in Go

Source: https://context7.com/pyrohost/elytra/llms.txt

Demonstrates how to manage the lifecycle of a game server, including starting, stopping, checking status, and monitoring resource usage. It relies on the 'server', 'remote', and 'config' packages from the Elytra library. Inputs include configuration details and server IDs, with outputs being logs of server actions and resource metrics.

```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/pyrohost/elytra/src/server"
    "github.com/pyrohost/elytra/src/remote"
    "github.com/pyrohost/elytra/src/config"
)

func main() {
    // Load configuration
    cfg, err := config.LoadConfiguration("/etc/elytra/config.yml")
    if err != nil {
        log.Fatal(err)
    }

    // Create Panel API client
    client := remote.NewClient(cfg.Remote, cfg.TokenID, cfg.Token)

    // Create server manager
    ctx := context.Background()
    manager, err := server.NewManager(ctx, client)
    if err != nil {
        log.Fatal(err)
    }

    // Get specific server
    srv, exists := manager.Get("abc-123-def")
    if !exists {
        log.Fatal("server not found")
    }

    // Check server status
    log.Printf("Server state: %s", srv.Environment.State())
    log.Printf("Is running: %v", srv.IsRunning())
    log.Printf("Is suspended: %v", srv.IsSuspended())

    // Start server with 30 second timeout
    if !srv.IsRunning() {
        err = srv.HandlePowerAction(server.PowerActionStart, 30)
        if err != nil {
            log.Printf("Failed to start: %v", err)
        }
    }

    // Wait for server to be running
    for i := 0; i < 30; i++ {
        if srv.IsRunning() {
            break
        }
        time.Sleep(1 * time.Second)
    }

    // Get resource usage
    usage := srv.Proc()
    log.Printf("CPU: %.2f%%", usage.CpuAbsolute)
    log.Printf("Memory: %d MB / %d MB",
        usage.Memory / 1024 / 1024,
        usage.MemoryLimit / 1024 / 1024)

    // Send command
    err = srv.Environment.SendCommand("say Server started via API")
    if err != nil {
        log.Printf("Failed to send command: %v", err)
    }

    // Stop server gracefully
    time.Sleep(5 * time.Second)
    err = srv.HandlePowerAction(server.PowerActionStop, 30)
    if err != nil {
        log.Printf("Failed to stop: %v", err)
    }
}
```

--------------------------------

### Elytra CLI Commands for Management and Configuration

Source: https://context7.com/pyrohost/elytra/llms.txt

Demonstrates various command-line interface commands for interacting with the Elytra daemon. Includes starting the daemon with specific configurations, enabling debug or profiling modes, managing SSL certificates, running the configuration wizard, performing system diagnostics, and checking the version.

```bash
# Start daemon
elytra --config /etc/elytra/config.yml

# Start with debug mode
elytra --debug

# Enable profiling
elytra --pprof --pprof-port 6060

# Auto-generate SSL certificate
elytra --auto-tls --tls-hostname node.example.com

# Skip certificate verification (development only)
elytra --ignore-certificate-errors

# Configuration wizard
elytra configure \
  --panel-url https://panel.example.com \
  --token-id your-token-id \
  --token your-token

# System diagnostics
elytra diagnostics

# Version information
elytra version
```

--------------------------------

### Job System Management in Go

Source: https://context7.com/pyrohost/elytra/llms.txt

Illustrates how to manage jobs within the Elytra project using the Go job system. This includes creating a job manager, starting workers, creating and monitoring backup and restore jobs, listing all jobs, canceling jobs, and shutting down the manager gracefully.

```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/pyrohost/elytra/src/jobs"
    "github.com/pyrohost/elytra/src/server"
    "github.com/pyrohost/elytra/src/remote"
)

func jobManagement(client remote.Client, mgr *server.Manager) {
    // Create job manager
    jobManager := jobs.NewManager(client, mgr)

    // Start job workers (4 concurrent workers)
    jobManager.Start(4)

    // Create backup job
    jobData := map[string]interface{}{
        "server_id":    "abc-123-def",
        "backup_uuid":  "backup-uuid-from-panel",
        "adapter_type": "rustic_local",
        "ignore":       ".git\n*.log\ncache/",
        "name":         "scheduled-backup",
    }

    jobID, err := jobManager.CreateJob("backup_create", jobData)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Created job: %s", jobID)

    // Monitor job progress
    ticker := time.NewTicker(1 * time.Second)
    defer ticker.Stop()

    for range ticker.C {
        instance, exists := jobManager.GetJob(jobID)
        if !exists {
            log.Println("Job not found")
            break
        }

        log.Printf("Job status: %s, progress: %d%%, message: %s",
            instance.Status, instance.Progress, instance.Message)

        if instance.Status == jobs.StatusCompleted {
            log.Printf("Job completed! Result: %+v", instance.Result)
            break
        }

        if instance.Status == jobs.StatusFailed {
            log.Printf("Job failed: %s", instance.Error)
            break
        }
    }

    // Create restore job
    restoreData := map[string]interface{}{
        "server_id":          "abc-123-def",
        "backup_uuid":        "backup-uuid",
        "adapter_type":       "rustic_local",
        "truncate_directory": true,
    }

    restoreJobID, err := jobManager.CreateJob("backup_restore", restoreData)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Created restore job: %s", restoreJobID)

    // List all jobs
    allJobs := jobManager.ListJobs()
    log.Printf("Total jobs: %d", len(allJobs))

    // Cancel job
    err = jobManager.CancelJob(jobID)
    if err != nil {
        log.Printf("Failed to cancel: %v", err)
    }

    // Shutdown job manager gracefully
    jobManager.Shutdown(30 * time.Second)
}

```

--------------------------------

### GET /api/system

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieves detailed system information about the node where the Elytra daemon is running.

```APIDOC
## GET /api/system

### Description
Retrieve node system details.

### Method
GET

### Endpoint
`/api/system?v=2`

### Parameters
#### Query Parameters
- **v** (string) - Optional - Version of the system API to use. Defaults to the latest.

### Request Example
```bash
curl -X GET "http://localhost:8080/api/system?v=2" \
  -H "Authorization: Bearer your-node-token"
```

### Response
#### Success Response (200)
- **architecture** (string) - The system's CPU architecture.
- **cpu_count** (integer) - The number of CPU cores available.
- **kernel_version** (string) - The kernel version of the operating system.
- **os** (string) - The name of the operating system.
- **version** (string) - The version of the Elytra daemon.

#### Response Example
```json
{
  "architecture": "x86_64",
  "cpu_count": 8,
  "kernel_version": "5.15.0-91-generic",
  "os": "linux",
  "version": "1.0.0"
}
```
```

--------------------------------

### GET /api/servers

Source: https://context7.com/pyrohost/elytra/llms.txt

Fetches a list of all servers managed by the Elytra daemon on the current node.

```APIDOC
## GET /api/servers

### Description
Get all servers on this node.

### Method
GET

### Endpoint
`/api/servers`

### Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/servers" \
  -H "Authorization: Bearer your-node-token"
```

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier for the server.
- **state** (string) - The current operational state of the server (e.g., `"running"`, `"offline"`).
- **suspended** (boolean) - Indicates if the server is currently suspended.

#### Response Example
```json
[
  {
    "uuid": "abc-123-def",
    "state": "running",
    "suspended": false
  },
  {
    "uuid": "ghi-456-jkl",
    "state": "offline",
    "suspended": false
  }
]
```
```

--------------------------------

### Get Server Details API (Bash)

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieves comprehensive server information, including its current state, resource utilization (CPU, memory, disk, network), and configuration parameters. Requires a node token for authorization.

```bash
curl -X GET "http://localhost:8080/api/servers/abc-123-def" \
  -H "Authorization: Bearer your-node-token"
```

--------------------------------

### Get System Information with curl

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieves essential details about the node's system, such as architecture, CPU count, kernel version, and operating system. This HTTP GET request requires an Authorization header with a valid node token. The response is a JSON object containing the system specifications.

```bash
curl -X GET "http://localhost:8080/api/system?v=2" \
  -H "Authorization: Bearer your-node-token"

# Response:
{
  "architecture": "x86_64",
  "cpu_count": 8,
  "kernel_version": "5.15.0-91-generic",
  "os": "linux",
  "version": "1.0.0"
}
```

--------------------------------

### Server Power Control API (Bash)

Source: https://context7.com/pyrohost/elytra/llms.txt

Allows control over server power states (start, stop, restart, kill) with an option to specify a wait time for lock acquisition. Requires a node token for authorization.

```bash
# Start server
curl -X POST "http://localhost:8080/api/servers/abc-123-def/power" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "start",
    "wait_seconds": 30
  }'

# Stop server gracefully
curl -X POST "http://localhost:8080/api/servers/abc-123-def/power" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{"action": "stop"}'

# Restart server
curl -X POST "http://localhost:8080/api/servers/abc-123-def/power" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{"action": "restart"}'

# Force kill server
curl -X POST "http://localhost:8080/api/servers/abc-123-def/power" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{"action": "kill"}'
```

--------------------------------

### GET /api/servers/{server_uuid}/files/list-directory

Source: https://context7.com/pyrohost/elytra/llms.txt

Lists the contents of a specified directory for a given server, with support for pagination.

```APIDOC
## GET /api/servers/{server_uuid}/files/list-directory

### Description
List files and directories with pagination support.

### Method
GET

### Endpoint
/api/servers/{server_uuid}/files/list-directory

### Parameters
#### Path Parameters
- **server_uuid** (string) - Required - The unique identifier of the server.

#### Query Parameters
- **directory** (string) - Required - The absolute path to the directory to list.
- **offset** (integer) - Optional - The number of items to skip for pagination. Defaults to 0.
- **limit** (integer) - Optional - The maximum number of items to return per page. Defaults to 100.

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/servers/abc-123-def/files/list-directory?directory=/&offset=0&limit=100" \
  -H "Authorization: Bearer your-node-token"
```

### Response
#### Success Response (200)
- **files** (array of objects) - A list of file and directory objects.
  - **name** (string) - The name of the file or directory.
  - **size** (integer) - The size of the file in bytes (0 for directories).
  - **mode** (string) - File permissions (e.g., "-rw-r--r--").
  - **type** (string) - "file" or "directory".
  - **mtime** (string) - Last modification time (ISO 8601 format).

#### Response Example
```json
{
  "files": [
    {
      "name": "server.jar",
      "size": 12345678,
      "mode": "-rw-r--r--",
      "type": "file",
      "mtime": "2023-10-27T10:00:00Z"
    },
    {
      "name": "logs",
      "size": 0,
      "mode": "drwxr-xr-x",
      "type": "directory",
      "mtime": "2023-10-27T09:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Get Console Logs API (Bash)

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieves a specified number of recent console output lines from a game server. Supports pagination via the 'size' parameter. Requires a node token for authorization.

```bash
curl -X GET "http://localhost:8080/api/servers/abc-123-def/logs?size=100" \
  -H "Authorization: Bearer your-node-token"
```

--------------------------------

### GET /api/servers/{server_uuid}

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieves detailed information about a specific server, including its current state, resource utilization, and configuration settings.

```APIDOC
## GET /api/servers/{server_uuid}

### Description
Returns complete server information including current state, resource utilization, and configuration.

### Method
GET

### Endpoint
/api/servers/{server_uuid}

### Parameters
#### Path Parameters
- **server_uuid** (string) - Required - The unique identifier of the server.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/servers/abc-123-def" \
  -H "Authorization: Bearer your-node-token"
```

### Response
#### Success Response (200)
- **state** (string) - The current power state of the server (e.g., "running", "stopped").
- **is_suspended** (boolean) - Indicates if the server is currently suspended.
- **utilization** (object) - An object containing current resource utilization metrics.
  - **memory_bytes** (integer) - Current memory usage in bytes.
  - **memory_limit_bytes** (integer) - The memory limit allocated to the server in bytes.
  - **cpu_absolute** (number) - Current CPU usage as an absolute value.
  - **disk_bytes** (integer) - Current disk usage in bytes.
  - **network_rx_bytes** (integer) - Total network received bytes.
  - **network_tx_bytes** (integer) - Total network transmitted bytes.
  - **uptime** (integer) - Server uptime in milliseconds.
- **configuration** (object) - The server's configuration details.
  - **uuid** (string) - The server's unique identifier.
  - **suspended** (boolean) - Whether the server is suspended.
  - **environment** (object) - Environment variables for the server.
  - **invocation** (string) - The command used to start the server.
  - **allocations** (object) - Network port allocations for the server.
  - **build** (object) - Build configuration for the server.
    - **memory_limit** (integer) - Memory limit in MB.
    - **swap** (integer) - Swap limit in MB.
    - **cpu_limit** (integer) - CPU limit as a percentage.
    - **disk_space** (integer) - Disk space limit in MB.

#### Response Example
```json
{
  "state": "running",
  "is_suspended": false,
  "utilization": {
    "memory_bytes": 1073741824,
    "memory_limit_bytes": 2147483648,
    "cpu_absolute": 50.5,
    "disk_bytes": 536870912,
    "network_rx_bytes": 1024000,
    "network_tx_bytes": 2048000,
    "uptime": 3600000
  },
  "configuration": {
    "uuid": "abc-123-def",
    "suspended": false,
    "environment": {
      "SERVER_PORT": "25565",
      "MINECRAFT_VERSION": "1.20.1"
    },
    "invocation": "java -Xms128M -Xmx2048M -jar server.jar",
    "allocations": {
      "default": {
        "ip": "0.0.0.0",
        "port": 25565
      }
    },
    "build": {
      "memory_limit": 2147483648,
      "swap": 0,
      "cpu_limit": 200,
      "disk_space": 10240
    }
  }
}
```
```

--------------------------------

### GET /api/servers/{serverID}/files/contents

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieve file contents or download files. Supports reading file content and downloading files directly.

```APIDOC
## GET /api/servers/{serverID}/files/contents

### Description
Retrieve file contents or download files. Use the `download=1` query parameter to trigger a file download.

### Method
GET

### Endpoint
`/api/servers/{serverID}/files/contents`

#### Query Parameters
- **file** (string) - Required - The path to the file.
- **download** (integer) - Optional - Set to `1` to download the file.

### Request Example
```bash
# Read file
curl -X GET "http://localhost:8080/api/servers/abc-123-def/files/contents?file=/server.properties" \
  -H "Authorization: Bearer your-node-token"

# Download file
curl -X GET "http://localhost:8080/api/servers/abc-123-def/files/contents?file=/world.zip&download=1" \
  -H "Authorization: Bearer your-node-token" \
  -o world.zip
```

### Response
#### Success Response (200)
- **content** (string) - The content of the file if reading, or file data if downloading.

#### Response Example
```json
{
  "content": "server-port=25565\nmax-players=20\ngamemode=survival\ndifficulty=normal"
}
```
```

--------------------------------

### List All Servers with curl

Source: https://context7.com/pyrohost/elytra/llms.txt

Fetches a list of all servers managed by the node, including their unique identifiers (UUID), current state (e.g., running, offline), and suspension status. This HTTP GET request is authenticated using a bearer token. The output is a JSON array of server objects.

```bash
curl -X GET "http://localhost:8080/api/servers" \
  -H "Authorization: Bearer your-node-token"

# Response:
[
  {
    "uuid": "abc-123-def",
    "state": "running",
    "suspended": false
  },
  {
    "uuid": "ghi-456-jkl",
    "state": "offline",
    "suspended": false
  }
]
```

--------------------------------

### Create Backup via API

Source: https://context7.com/pyrohost/elytra/llms.txt

Initiates a backup creation process for a specified server using various adapters like 'rustic_local', 's3', 'elytra', or 'rustic_s3'. This operation is asynchronous and returns a job ID for status tracking. Input includes adapter type, backup UUID, optional ignore patterns, and a name for the backup.

```bash
curl -X POST "http://localhost:8080/api/servers/abc-123-def/backup" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{
    "adapter": "rustic_local",
    "uuid": "backup-uuid-from-panel",
    "ignore": ".git\n*.log\n*.tmp\ncache/",
    "name": "manual-backup-2025-12-16"
  }'
```

--------------------------------

### POST /api/servers/{serverID}/files/create-directory

Source: https://context7.com/pyrohost/elytra/llms.txt

Create a new directory. Specify the name and path for the new directory.

```APIDOC
## POST /api/servers/{serverID}/files/create-directory

### Description
Create a new directory. The directory will be created at the specified path with the given name.

### Method
POST

### Endpoint
`/api/servers/{serverID}/files/create-directory`

#### Request Body
- **name** (string) - Required - The name of the directory to create.
- **path** (string) - Required - The path where the directory should be created.

### Request Example
```bash
curl -X POST "http://localhost:8080/api/servers/abc-123-def/files/create-directory" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "plugins",
    "path": "/"
  }'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### GET /api/servers/{server_uuid}/logs

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieves recent console output lines from a server's log.

```APIDOC
## GET /api/servers/{server_uuid}/logs

### Description
Retrieve recent console output lines.

### Method
GET

### Endpoint
/api/servers/{server_uuid}/logs

### Parameters
#### Path Parameters
- **server_uuid** (string) - Required - The unique identifier of the server.

#### Query Parameters
- **size** (integer) - Optional - The maximum number of log lines to retrieve. Defaults to a reasonable value if not specified.

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/servers/abc-123-def/logs?size=100" \
  -H "Authorization: Bearer your-node-token"
```

### Response
#### Success Response (200)
- **lines** (array of strings) - A list of strings, where each string is a line from the server's console log.

#### Response Example
```json
{
  "lines": [
    "[12:34:56] [Server thread/INFO]: Starting minecraft server version 1.20.1",
    "[12:34:57] [Server thread/INFO]: Loading properties",
    "[12:34:58] [Server thread/INFO]: Done! For help, type \"help\""
  ]
}
```
```

--------------------------------

### GET /api/servers/{server_id}/jobs/{job_id}

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieves the status and details of an asynchronous job, such as backup creation or restoration.

```APIDOC
## Get Job Status

### Description
Monitor async job progress and results.

### Method
GET

### Endpoint
`/api/servers/{server_id}/jobs/{job_id}`

### Parameters
#### Path Parameters
- **server_id** (string) - Required - The ID of the server associated with the job.
- **job_id** (string) - Required - The ID of the job to retrieve status for.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/servers/abc-123-def/jobs/job-abc-123" \
  -H "Authorization: Bearer your-node-token"
```

### Response
#### Success Response (200)
- **job_id** (string) - The ID of the job.
- **type** (string) - The type of job (e.g., "backup_create").
- **status** (string) - The current status of the job (e.g., "running", "completed", "failed").
- **progress** (integer) - The completion percentage of the job.
- **message** (string) - A human-readable message about the job's status or progress.
- **error** (string) - Error message if the job failed, otherwise null.
- **result** (object) - The result of the job if completed, otherwise null.
- **created_at** (string) - Timestamp when the job was created.
- **updated_at** (string) - Timestamp when the job was last updated.

#### Response Example (in progress)
```json
{
  "job_id": "job-abc-123",
  "type": "backup_create",
  "status": "running",
  "progress": 45,
  "message": "Backing up files... (2.3 GB / 5.1 GB)",
  "error": null,
  "result": null,
  "created_at": "2025-12-16T10:00:00Z",
  "updated_at": "2025-12-16T10:02:30Z"
}
```

#### Response Example (completed)
```json
{
  "job_id": "job-abc-123",
  "type": "backup_create",
  "status": "completed",
  "progress": 100,
  "message": "Backup completed successfully",
  "error": null,
  "result": {
    "checksum": "a1b2c3d4e5f6...",
    "checksum_type": "sha1",
    "size": 5368709120,
    "snapshot_id": "abc123def456"
  },
  "created_at": "2025-12-16T10:00:00Z",
  "updated_at": "2025-12-16T10:05:45Z"
}
```

#### Response Example (failed)
```json
{
  "job_id": "job-abc-123",
  "type": "backup_create",
  "status": "failed",
  "progress": 67,
  "message": "Backup failed",
  "error": "insufficient disk space: 50 GB required, 30 GB available",
  "result": null,
  "created_at": "2025-12-16T10:00:00Z",
  "updated_at": "2025-12-16T10:03:15Z"
}
```
```

--------------------------------

### Sync Server Configuration API (Bash)

Source: https://context7.com/pyrohost/elytra/llms.txt

Triggers a synchronization of the server's configuration with the control panel. Requires a node token for authorization.

```bash
curl -X POST "http://localhost:8080/api/servers/abc-123-def/sync" \
  -H "Authorization: Bearer your-node-token"
```

--------------------------------

### Run All Tests (Go)

Source: https://github.com/pyrohost/elytra/blob/main/CONTRIBUTING.md

Execute all tests in the project using the Go testing framework. This is a crucial step before submitting changes.

```go
go test ./...
```

--------------------------------

### Event Handling in Go

Source: https://context7.com/pyrohost/elytra/llms.txt

Demonstrates how to subscribe to various server events (console output, status changes, resource stats, backup completion) and publish custom events using the Elytra server's event system. It utilizes Go channels for asynchronous event processing.

```go
package main

import (
    "context"
    "log"

    "github.com/pyrohost/elytra/src/server"
    "github.com/pyrohost/elytra/src/events"
)

func eventHandling(srv *server.Server) {
    // Subscribe to console output
    consoleChan := make(chan events.Event)
    srv.Events().Subscribe(server.ConsoleOutputEvent, consoleChan)

    go func() {
        for event := range consoleChan {
            line := event.Data.(string)
            log.Printf("[CONSOLE] %s", line)
        }
    }()

    // Subscribe to state changes
    statusChan := make(chan events.Event)
    srv.Events().Subscribe(server.StatusEvent, statusChan)

    go func() {
        for event := range statusChan {
            state := event.Data.(string)
            log.Printf("[STATE] Server is now: %s", state)

            if state == "running" {
                log.Println("Server has started successfully!")
            }
        }
    }()

    // Subscribe to resource stats
    statsChan := make(chan events.Event)
    srv.Events().Subscribe(server.StatsEvent, statsChan)

    go func() {
        for event := range statsChan {
            stats := event.Data.(server.ResourceUsage)
            log.Printf("[STATS] CPU: %.1f%%, Memory: %d MB",
                stats.CpuAbsolute,
                stats.Memory / 1024 / 1024)
        }
    }()

    // Publish custom event
    srv.Events().Publish(server.DaemonMessageEvent,
        "Custom notification from daemon")

    // Subscribe to backup completion
    backupChan := make(chan events.Event)
    srv.Events().Subscribe(server.BackupCompletedEvent, backupChan)

    go func() {
        for event := range backupChan {
            backup := event.Data.(map[string]interface{})
            log.Printf("[BACKUP] Completed: %s (%.2f MB)",
                backup["name"],
                float64(backup["size"].(int64)) / 1024 / 1024)
        }
    }()
}

```

--------------------------------

### Remote File Download API

Source: https://context7.com/pyrohost/elytra/llms.txt

Manage remote file downloads. This API allows starting, listing, and canceling downloads from remote URLs.

```APIDOC
## Remote File Download API

### POST /api/servers/{serverID}/files/pull

#### Description
Start a remote file download. Specify the URL, destination path, and other options for the download.

### Method
POST

### Endpoint
`/api/servers/{serverID}/files/pull`

#### Request Body
- **root** (string) - Required - The destination directory on the server.
- **url** (string) - Required - The URL of the file to download.
- **file_name** (string) - Optional - The desired name for the downloaded file. If not provided, the name from the URL will be used.
- **use_header** (boolean) - Optional - Whether to use response headers to determine the file name. Defaults to `false`.
- **foreground** (boolean) - Optional - Whether to run the download in the foreground. Defaults to `false`.

### Request Example
```bash
curl -X POST "http://localhost:8080/api/servers/abc-123-def/files/pull" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{
    "root": "/plugins",
    "url": "https://github.com/plugin/releases/download/v1.0.0/plugin.jar",
    "file_name": "CustomPlugin.jar",
    "use_header": false,
    "foreground": false
  }'
```

### Response
#### Success Response (200)
- **download_id** (string) - The unique ID of the initiated download.

#### Response Example
```json
{
  "download_id": "dl-uuid-123"
}
```

### GET /api/servers/{serverID}/files/pull

#### Description
List active remote downloads.

### Method
GET

### Endpoint
`/api/servers/{serverID}/files/pull`

### Response
#### Success Response (200)
- **downloads** (array) - A list of active download objects.

### DELETE /api/servers/{serverID}/files/pull/{downloadID}

#### Description
Cancel an active remote download.

### Method
DELETE

### Endpoint
`/api/servers/{serverID}/files/pull/{downloadID}`

### Request Example
```bash
curl -X DELETE "http://localhost:8080/api/servers/abc-123-def/files/pull/dl-uuid-123" \
  -H "Authorization: Bearer your-node-token"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the cancellation was successful.

```

--------------------------------

### Perform File System Operations in Go

Source: https://context7.com/pyrohost/elytra/llms.txt

Illustrates various file system operations including listing, reading, writing, creating directories, copying, renaming, deleting, checking disk space, compressing, and decompressing files. This function requires a server object and utilizes the 'server' package. It operates on file paths and content, with outputs being logged messages about the operations performed or file details.

```go
package main

import (
    "io"
    "log"
    "os"
    "bytes"

    "github.com/pyrohost/elytra/src/server"
)

func fileOperations(srv *server.Server) {
    fs := srv.Filesystem()

    // List directory with pagination
    files, total, err := fs.ListDirectoryPaged(ctx, "/", 0, 50)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Found %d files (showing 50)", total)

    for _, f := range files {
        log.Printf("  %s - %d bytes - %s",
            f.Name(), f.Size(), f.Mode())
    }

    // Read file
    file, stat, err := fs.File("/server.properties")
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close()

    content, err := io.ReadAll(file)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("File size: %d bytes", stat.Size())
    log.Printf("Content:\n%s", string(content))

    // Write file
    newContent := []byte("server-port=25565\nmax-players=20\n")
    err = fs.Write("/server.properties", bytes.NewReader(newContent),
        int64(len(newContent)), 0644)
    if err != nil {
        log.Fatal(err)
    }

    // Create directory
    err = fs.CreateDirectory("plugins", "/")
    if err != nil {
        log.Fatal(err)
    }

    // Copy file
    err = fs.Copy("/config.yml")
    if err != nil {
        log.Fatal(err)
    }
    // Creates: /config copy.yml

    // Rename file
    err = fs.Rename("/config copy.yml", "/config-backup.yml")
    if err != nil {
        log.Fatal(err)
    }

    // Delete file
    err = fs.Delete("/old-file.txt")
    if err != nil {
        log.Fatal(err)
    }

    // Check disk space
    if !fs.HasSpaceAvailable(false) {
        log.Println("Warning: disk space low!")
    }

    // Compress files
    archive, err := fs.CompressFiles("/", []string{"world/", "config.yml"})
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Created archive: %s (%d bytes)",
        archive.Name(), archive.Size())

    // Decompress archive
    err = fs.DecompressFile(ctx, "/", "backup.tar.gz")
    if err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### POST /api/servers/{server_uuid}/power

Source: https://context7.com/pyrohost/elytra/llms.txt

Controls the power state of a server (start, stop, restart, kill) with an optional wait time for graceful operations.

```APIDOC
## POST /api/servers/{server_uuid}/power

### Description
Control server power states with configurable wait times for lock acquisition.

### Method
POST

### Endpoint
/api/servers/{server_uuid}/power

### Parameters
#### Path Parameters
- **server_uuid** (string) - Required - The unique identifier of the server.

#### Query Parameters
None

#### Request Body
- **action** (string) - Required - The power action to perform. Must be one of: "start", "stop", "restart", "kill".
- **wait_seconds** (integer) - Optional - The number of seconds to wait for a graceful shutdown before forcing termination (applicable for "stop" and "restart").

### Request Example
```bash
# Start server
curl -X POST "http://localhost:8080/api/servers/abc-123-def/power" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{ 
    "action": "start",
    "wait_seconds": 30
  }'

# Stop server gracefully
curl -X POST "http://localhost:8080/api/servers/abc-123-def/power" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{"action": "stop"}'

# Restart server
curl -X POST "http://localhost:8080/api/servers/abc-123-def/power" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{"action": "restart"}'

# Force kill server
curl -X POST "http://localhost:8080/api/servers/abc-123-def/power" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{"action": "kill"}'
```

### Response
#### Success Response (200)
No specific response body is detailed, typically an empty success response or a status message.

#### Response Example
(No example provided in source)
```

--------------------------------

### POST /api/servers/{serverID}/files/compress

Source: https://context7.com/pyrohost/elytra/llms.txt

Create a tar.gz archive from specified files and directories. The archive is created in the root directory.

```APIDOC
## POST /api/servers/{serverID}/files/compress

### Description
Create a tar.gz archive from a list of files and directories. The archive is named automatically based on the current date and time.

### Method
POST

### Endpoint
`/api/servers/{serverID}/files/compress`

#### Request Body
- **root** (string) - Required - The root directory containing the files to compress.
- **files** (array) - Required - An array of strings, where each string is the name of a file or directory to include in the archive.

### Request Example
```bash
curl -X POST "http://localhost:8080/api/servers/abc-123-def/files/compress" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{
    "root": "/",
    "files": [
      "world/",
      "config.yml",
      "plugins/"
    ]
  }'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **archive_name** (string) - The name of the created archive file.

#### Response Example
```json
{
  "success": true,
  "archive_name": "archive-2025-12-17-103000.tar.gz"
}
```
```

--------------------------------

### POST /api/servers/{server_id}/backup

Source: https://context7.com/pyrohost/elytra/llms.txt

Creates a backup for a specified server using a given adapter. This operation is processed asynchronously.

```APIDOC
## Create Backup

### Description
Create a backup using specified adapter with async job processing.

### Method
POST

### Endpoint
`/api/servers/{server_id}/backup`

### Parameters
#### Path Parameters
- **server_id** (string) - Required - The ID of the server to create a backup for.

#### Query Parameters
None

#### Request Body
- **adapter** (string) - Required - The backup adapter to use (e.g., "rustic_local", "s3").
- **uuid** (string) - Required - A unique identifier for the backup.
- **ignore** (string) - Optional - Files or directories to ignore during backup, separated by newlines.
- **name** (string) - Optional - A custom name for the backup.

### Request Example
```json
{
  "adapter": "rustic_local",
  "uuid": "backup-uuid-from-panel",
  "ignore": ".git\n*.log\n*.tmp\ncache/",
  "name": "manual-backup-2025-12-16"
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The ID of the asynchronous job created.
- **status** (string) - The status of the job request (e.g., "accepted").
- **message** (string) - A message indicating the job has been queued.

#### Response Example
```json
{
  "job_id": "job-abc-123",
  "status": "accepted",
  "message": "Backup job has been queued for processing"
}
```

### Available Adapters
- "elytra": Traditional tar.gz backup
- "s3": Upload to S3 storage
- "rustic_local": Deduplicated local backup
- "rustic_s3": Deduplicated S3 backup
```

--------------------------------

### Read and Download Files (Bash)

Source: https://context7.com/pyrohost/elytra/llms.txt

Reads the content of a file or initiates a file download. Requires specifying the server and file path. Download operations append '&download=1' to the URL and use '-o' to specify the output file.

```bash
# Read file
curl -X GET "http://localhost:8080/api/servers/abc-123-def/files/contents?file=/server.properties" \
  -H "Authorization: Bearer your-node-token"

# Download file
curl -X GET "http://localhost:8080/api/servers/abc-123-def/files/contents?file=/world.zip&download=1" \
  -H "Authorization: Bearer your-node-token" \
  -o world.zip
```

--------------------------------

### Create Directory (Bash)

Source: https://context7.com/pyrohost/elytra/llms.txt

Creates a new directory at a specified path. The request includes the desired name for the new directory and its parent path.

```bash
curl -X POST "http://localhost:8080/api/servers/abc-123-def/files/create-directory" \
  -H "Authorization: Bearer your-node-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "plugins",
    "path": "/"
  }'
```

--------------------------------

### Clone Elytra Repository

Source: https://github.com/pyrohost/elytra/blob/main/CONTRIBUTING.md

Clone the Elytra repository to your local machine. This is the first step in setting up your development environment.

```bash
git clone https://github.com/yourusername/elytra.git
```

--------------------------------

### Get Job Status via API

Source: https://context7.com/pyrohost/elytra/llms.txt

Retrieves the status, progress, and results of an asynchronous job. This endpoint is crucial for monitoring backup, restore, or deletion operations. It returns detailed information including timestamps, status messages, and potential errors.

```bash
curl -X GET "http://localhost:8080/api/servers/abc-123-def/jobs/job-abc-123" \
  -H "Authorization: Bearer your-node-token"
```

--------------------------------

### Build Project (Make)

Source: https://github.com/pyrohost/elytra/blob/main/CONTRIBUTING.md

Build the Elytra project using the Make build tool. This command compiles the source code into an executable.

```makefile
make build
```

--------------------------------

### Run Tests with Race Detection (Go)

Source: https://github.com/pyrohost/elytra/blob/main/CONTRIBUTING.md

Run Go tests with the race detector enabled to identify potential data races in concurrent code. This helps uncover subtle bugs.

```go
go test -race ./...
```