# Usage and Examples

Running locally (development)

1. Build the agent (from repository root):

   ```sh
   cargo build -p agent
   ```

2. Run the agent with defaults (socket in current directory):

   ```sh
   ./target/debug/yanpm-agent
   ```

3. Run with explicit socket and nginx config directory:

   ```sh
   ./target/debug/yanpm-agent --sock /run/yanpm/yanpm-agent.sock --nginx-config-dir /etc/nginx/conf.d
   ```

HTTP over unix-socket examples (using `socat` / `curl` helper)

If you want to call the API from the shell, you can use `socat` to convert the unix socket to an HTTP stream, or use tools that support unix sockets directly (e.g. `curl --unix-socket`). Examples below use `curl --unix-socket`.

Validate a fragment by name and timestamp:

```sh
curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/validate \
  -H 'Content-Type: application/json' \
  -d '{"config_name":"example","timestamp":1234567890}'
```

Validate and reload (returns `rc` and `ro`):

```sh
curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/validate_and_reload \
  -H 'Content-Type: application/json' \
  -d '{"config_name":"example","timestamp":1234567890}'
```

Write a fragment (create or update):

```sh
curl --unix-socket ./yanpm-agent.sock -X POST http://localhost/write_config \
  -H 'Content-Type: application/json' \
  -d '{"config_name":"example","timestamp":1234567890,"content":"server { listen 80; server_name example.local; }"}'
```

Status endpoint (health)

```sh
curl --unix-socket ./yanpm-agent.sock http://localhost/status
```

Notes

- Use the `config_name` and `timestamp` fields consistently: `timestamp` is typically a monotonic update ID from the caller ensuring unique file names.
- When running in containers, mount the host nginx config dir if you want the agent to write directly to host nginx configuration.
- The repository includes a runtime Docker image built by `apps/agent/Dockerfile` which bundles `nginx` and the `yanpm-agent` binary (via s6-overlay). Use that image when you want nginx and the agent colocated (the agent is intended as a runtime companion to `apps/api`).