274 lines
7.1 KiB
Markdown
274 lines
7.1 KiB
Markdown
# Error Handling
|
||
|
||
## Категории ошибок
|
||
|
||
### 1. Configuration Errors
|
||
|
||
Ошибки связанные с отсутствием или невалидностью конфигурации.
|
||
|
||
| Код | Сообщение | Когда возникает | Решение |
|
||
|-----|-----------|-----------------|---------|
|
||
| `ERR_NO_GLOBAL_CONFIG` | `No storage configured. Run 'aevs config' first.` | Любая команда кроме `config` без глобального конфига | `aevs config` |
|
||
| `ERR_NO_PROJECT_CONFIG` | `No aevs.yaml found. Run 'aevs init' first.` | `push`, `status` без локального конфига | `aevs init` |
|
||
| `ERR_CONFIG_EXISTS` | `aevs.yaml already exists. Use --force to overwrite.` | `init` когда конфиг существует | `aevs init --force` |
|
||
| `ERR_INVALID_CONFIG` | `Invalid config: {details}` | Конфиг существует, но невалидный | Проверить синтаксис YAML |
|
||
|
||
### 2. Validation Errors
|
||
|
||
Ошибки валидации входных данных.
|
||
|
||
| Код | Сообщение | Когда возникает |
|
||
|-----|-----------|-----------------|
|
||
| `ERR_INVALID_PROJECT_NAME` | `Invalid project name "{name}". Use only a-z, 0-9, -, _` | Невалидное имя проекта |
|
||
| `ERR_EMPTY_FILES` | `No files specified in aevs.yaml` | Пустой список files |
|
||
| `ERR_INVALID_PATH` | `Invalid file path: {path}` | Путь содержит `..` или абсолютный |
|
||
|
||
### 3. File System Errors
|
||
|
||
Ошибки работы с локальной файловой системой.
|
||
|
||
| Код | Сообщение | Когда возникает |
|
||
|-----|-----------|-----------------|
|
||
| `ERR_FILE_NOT_FOUND` | `File not found: {path}` | Файл из config не существует при push |
|
||
| `ERR_PERMISSION_DENIED` | `Permission denied: {path}` | Нет прав на чтение/запись |
|
||
| `ERR_DIR_CREATE_FAILED` | `Failed to create directory: {path}` | Не удалось создать директорию при pull |
|
||
|
||
### 4. Storage Errors
|
||
|
||
Ошибки работы с S3 storage.
|
||
|
||
| Код | Сообщение | Когда возникает |
|
||
|-----|-----------|-----------------|
|
||
| `ERR_ACCESS_DENIED` | `Access denied. Check your credentials.` | Невалидные credentials |
|
||
| `ERR_BUCKET_NOT_FOUND` | `Bucket "{name}" not found.` | Bucket не существует |
|
||
| `ERR_PROJECT_NOT_FOUND` | `Project "{name}" not found in storage.` | Проект не найден при pull |
|
||
| `ERR_UPLOAD_FAILED` | `Failed to upload: {details}` | Ошибка при загрузке |
|
||
| `ERR_DOWNLOAD_FAILED` | `Failed to download: {details}` | Ошибка при скачивании |
|
||
| `ERR_CONNECTION_FAILED` | `Could not connect to storage: {details}` | Сетевая ошибка |
|
||
|
||
### 5. Archive Errors
|
||
|
||
Ошибки работы с архивами.
|
||
|
||
| Код | Сообщение | Когда возникает |
|
||
|-----|-----------|-----------------|
|
||
| `ERR_ARCHIVE_CREATE` | `Failed to create archive: {details}` | Ошибка создания tar.gz |
|
||
| `ERR_ARCHIVE_EXTRACT` | `Failed to extract archive: {details}` | Ошибка распаковки |
|
||
| `ERR_ARCHIVE_CORRUPT` | `Archive is corrupted` | Повреждённый архив |
|
||
|
||
---
|
||
|
||
## Формат вывода ошибок
|
||
|
||
### Стандартный формат
|
||
|
||
```
|
||
Error: {сообщение}
|
||
|
||
{подсказка как исправить, если есть}
|
||
```
|
||
|
||
### Примеры
|
||
|
||
```
|
||
$ aevs push
|
||
|
||
Error: No aevs.yaml found. Run 'aevs init' first.
|
||
```
|
||
|
||
```
|
||
$ aevs pull my-project
|
||
|
||
Error: Project "my-project" not found in storage.
|
||
|
||
Available projects:
|
||
- my-app
|
||
- another-project
|
||
```
|
||
|
||
```
|
||
$ aevs push
|
||
|
||
Error: File not found: .env.production
|
||
|
||
The file is listed in aevs.yaml but doesn't exist.
|
||
Remove it from the config or create the file.
|
||
```
|
||
|
||
---
|
||
|
||
## Exit Codes
|
||
|
||
| Code | Meaning |
|
||
|------|---------|
|
||
| `0` | Success |
|
||
| `1` | General error |
|
||
| `2` | Configuration error |
|
||
| `3` | File system error |
|
||
| `4` | Storage error |
|
||
| `5` | Network error |
|
||
| `130` | Interrupted (Ctrl+C) |
|
||
|
||
### Использование в скриптах
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
aevs push
|
||
exit_code=$?
|
||
|
||
case $exit_code in
|
||
0)
|
||
echo "Success"
|
||
;;
|
||
2)
|
||
echo "Config error - run 'aevs config' or 'aevs init'"
|
||
;;
|
||
4)
|
||
echo "Storage error - check credentials"
|
||
;;
|
||
5)
|
||
echo "Network error - check connection"
|
||
;;
|
||
*)
|
||
echo "Unknown error: $exit_code"
|
||
;;
|
||
esac
|
||
```
|
||
|
||
---
|
||
|
||
## Логирование
|
||
|
||
### Уровни логирования
|
||
|
||
По умолчанию выводятся только ошибки. Для подробного вывода:
|
||
|
||
```bash
|
||
# Verbose mode
|
||
$ aevs push -v
|
||
$ aevs push --verbose
|
||
|
||
# Debug mode (максимум деталей)
|
||
$ aevs push --debug
|
||
```
|
||
|
||
### Формат verbose вывода
|
||
|
||
```
|
||
$ aevs push -v
|
||
|
||
[INFO] Reading config from ./aevs.yaml
|
||
[INFO] Project: my-app
|
||
[INFO] Files to upload: 3
|
||
[INFO] Creating archive...
|
||
[INFO] Archive size: 479 bytes
|
||
[INFO] Uploading to s3://my-bucket/my-app/envs.tar.gz
|
||
[INFO] Uploading metadata...
|
||
[INFO] Done
|
||
|
||
Pushed 3 files to "my-app"
|
||
```
|
||
|
||
### Формат debug вывода
|
||
|
||
```
|
||
$ aevs push --debug
|
||
|
||
[DEBUG] Config path: /Users/me/project/aevs.yaml
|
||
[DEBUG] Global config: /Users/me/.config/aevs/config.yaml
|
||
[DEBUG] Storage endpoint: https://s3.amazonaws.com
|
||
[DEBUG] Bucket: my-bucket
|
||
[DEBUG] Reading file: .env.development (156 bytes)
|
||
[DEBUG] Reading file: .env.production (234 bytes)
|
||
[DEBUG] Reading file: docker/.env (89 bytes)
|
||
[DEBUG] Creating tar.gz archive
|
||
[DEBUG] S3 PutObject: my-app/envs.tar.gz
|
||
[DEBUG] S3 Response: 200 OK, ETag: "abc123"
|
||
[DEBUG] S3 PutObject: my-app/metadata.json
|
||
[DEBUG] S3 Response: 200 OK
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
## Graceful Degradation
|
||
|
||
### При сетевых ошибках
|
||
|
||
```
|
||
$ aevs push
|
||
|
||
Error: Could not connect to storage.
|
||
|
||
Retrying in 2 seconds... (1/3)
|
||
Retrying in 4 seconds... (2/3)
|
||
Retrying in 8 seconds... (3/3)
|
||
|
||
Error: Connection failed after 3 attempts.
|
||
Check your internet connection and try again.
|
||
```
|
||
|
||
### При прерывании (Ctrl+C)
|
||
|
||
```
|
||
$ aevs push
|
||
Pushing "my-app"...
|
||
✓ .env.development
|
||
^C
|
||
Interrupted. No changes were made to storage.
|
||
```
|
||
|
||
```
|
||
$ aevs pull
|
||
Pulling "my-app"...
|
||
✓ .env.development (created)
|
||
^C
|
||
Interrupted. Partially pulled files:
|
||
- .env.development
|
||
|
||
Run 'aevs pull' again to complete.
|
||
```
|
||
|
||
---
|
||
|
||
## Recovery Scenarios
|
||
|
||
### Corrupted local config
|
||
|
||
```
|
||
$ aevs push
|
||
|
||
Error: Invalid config: yaml: line 3: did not find expected key
|
||
|
||
Fix the syntax error in aevs.yaml or run 'aevs init --force' to recreate.
|
||
```
|
||
|
||
### Missing credentials
|
||
|
||
```
|
||
$ aevs push
|
||
|
||
Error: Access denied. Check your credentials.
|
||
|
||
Your credentials may have expired or been revoked.
|
||
Run 'aevs config' to update them.
|
||
```
|
||
|
||
### Partial push failure
|
||
|
||
```
|
||
$ aevs push
|
||
|
||
Pushing "my-app"...
|
||
✓ .env.development
|
||
✓ .env.production
|
||
✗ docker/.env (failed)
|
||
|
||
Error: Upload interrupted.
|
||
|
||
Some files may have been uploaded. Run 'aevs push' again to retry.
|
||
```
|
||
|
||
При повторном push всё будет загружено заново (идемпотентность).
|