101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
# Photobooth Control Service API
|
||
|
||
The control service is a lightweight sidecar responsible for provisioning vsftpd accounts. Laravel talks to it via REST whenever an Event Admin enables, rotates, or disables the Photobooth feature.
|
||
|
||
## Authentication
|
||
|
||
- **Scheme:** Bearer token.
|
||
- **Header:** `Authorization: Bearer ${PHOTOBOOTH_CONTROL_TOKEN}`.
|
||
- **Timeout:** Configurable via `PHOTOBOOTH_CONTROL_TIMEOUT` (default 5 s).
|
||
- **Token generation:** `openssl rand -hex 32` (or `php -r "echo bin2hex(random_bytes(32)), "`); store in `.env`/Dokploy secrets as `PHOTOBOOTH_CONTROL_TOKEN`.
|
||
|
||
## Endpoints
|
||
|
||
| Method & Path | Description |
|
||
|---------------|-------------|
|
||
| `POST /users` | Create a new FTP account for an event. |
|
||
| `POST /users/{username}/rotate` | Rotate credentials / extend expiry for an existing user. |
|
||
| `DELETE /users/{username}` | Remove an FTP account (called when an event disables Photobooth or expires). |
|
||
| `POST /config` | Optionally push global config changes (port, rate-limit, expiry grace) to the control service. |
|
||
|
||
### `POST /users`
|
||
|
||
```json
|
||
{
|
||
"username": "pbA12345",
|
||
"password": "F4P9K2QX",
|
||
"path": "tenant-slug/123",
|
||
"rate_limit_per_minute": 20,
|
||
"expires_at": "2025-06-15T22:59:59Z",
|
||
"ftp_port": 2121,
|
||
"allowed_ip_ranges": ["1.2.3.4/32"],
|
||
"metadata": {
|
||
"event_id": 123,
|
||
"tenant_id": 5
|
||
}
|
||
}
|
||
```
|
||
|
||
**Response:** `201 Created` with `{ "ok": true }`. On failure return 4xx/5xx JSON with `error.code` + `message`.
|
||
|
||
Implementation tips:
|
||
|
||
- Ensure the system user or virtual user’s home directory is set to the provided `path` (prefixed with the shared Photobooth root).
|
||
- Apply the rate limit token-bucket before writing to disk (or integrate with HAProxy).
|
||
- Store `expires_at` and automatically disable the account when reached (in addition to Laravel’s scheduled cleanup).
|
||
|
||
Reference implementation (current stack): `photobooth-ftp` builds from `docker/photobooth-control`, starts pure-ftpd and a Node-based control API on port 8080. Healthcheck: `GET /health` on 8080 (wired in docker-compose.dokploy.yml). Rate-limit/expiry enforcement inside the FTP tier is still to be implemented.
|
||
|
||
### `POST /users/{username}/rotate`
|
||
|
||
```json
|
||
{
|
||
"password": "K9M4T6QZ",
|
||
"rate_limit_per_minute": 20,
|
||
"expires_at": "2025-06-16T22:59:59Z"
|
||
}
|
||
```
|
||
|
||
- Rotate the password atomically and respond with `{ "ok": true }`.
|
||
- If username does not exist return `404` with a descriptive message so Laravel can re-provision.
|
||
|
||
### `DELETE /users/{username}`
|
||
|
||
No request body. Delete or disable the FTP account, removing access to the assigned directory.
|
||
|
||
### `POST /config`
|
||
|
||
Optional hook used when SuperAdmins change defaults:
|
||
|
||
```json
|
||
{
|
||
"ftp_port": 2121,
|
||
"rate_limit_per_minute": 20,
|
||
"expiry_grace_days": 1
|
||
}
|
||
```
|
||
|
||
Use this to reload vsftpd or adjust proxy rules without redeploying the control service.
|
||
|
||
## Error Contract
|
||
|
||
Return JSON structured as:
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "user_exists",
|
||
"message": "Username already provisioned",
|
||
"context": { "username": "pbA12345" }
|
||
}
|
||
}
|
||
```
|
||
|
||
Laravel treats any non-2xx as fatal and logs the payload (sans password). Prefer descriptive `code` values: `user_exists`, `user_not_found`, `rate_limit_violation`, `invalid_payload`, etc.
|
||
|
||
## Observability
|
||
|
||
- Emit structured logs for every create/rotate/delete with event + tenant IDs.
|
||
- Expose `/health` so Laravel (or uptime monitors) can verify connectivity.
|
||
- Consider metrics (e.g., Prometheus) for active accounts, rotations, and failures.
|