sber-tunnel 2.4.0
CLI для передачи файлов между директориями через Confluence API
License: MIT
Requires Python: >=3.8

# sber-tunnel

CLI-сервис для создания тунеля между директориями на разных устройствах с использованием Confluence API.

## Описание

Sber-tunnel - это инструмент командной строки на Python, который позволяет загружать и скачивать целые директории через Confluence, используя систему манифестов для отслеживания файлов. Сервис автоматически разбивает большие файлы (>100 МБ) на чанки и обеспечивает целостность данных с помощью контрольных сумм SHA256.

## Основные возможности

- 🔐 Безопасная авторизация через API token и опциональные p12 сертификаты
- 📦 Автоматическое чанкование файлов больше 100 МБ
- 🔍 Проверка целостности данных через SHA256
- 📋 Манифест для отслеживания структуры директорий
- 🚫 Автоматическое исключение скрытых и временных файлов
- 📂 Сохранение полной структуры каталогов

## Установка

### Через pip

```bash
pip install sber-tunnel
```

### Из исходников

```bash
git clone <repository-url>
cd sber-tunnel
pip install -e .
```

## Использование

### 1. Инициализация

Перед первым использованием необходимо инициализировать конфигурацию:

```bash
sber-tunnel init
```

Команда запросит:
- Confluence base URL
- Имя пользователя
- Пароль (API token)
- Опционально: путь к p12 сертификату и пароль

Конфигурация сохраняется в `.sber-tunnel/config.json` в текущей директории.

### 2. Просмотр манифеста

Для просмотра списка загруженных директорий на странице Confluence:

```bash
sber-tunnel scan -p <page_id>
```

Где `<page_id>` - ID страницы Confluence.

**Пример:**
```bash
sber-tunnel scan -p 123456789
```

### 3. Загрузка директории

Для загрузки директории со всем содержимым в Confluence:

```bash
sber-tunnel upload -p <page_id> <путь/к/директории>
```

**Пример:**
```bash
sber-tunnel upload -p 123456789 ./my-project
```

Команда:
- Проверяет права доступа к странице
- Рекурсивно собирает все файлы из директории
- Исключает скрытые файлы и директории (начинающиеся с точки)
- Разбивает большие файлы на чанки по 100 МБ
- Загружает все файлы с контрольными суммами
- Обновляет манифест на странице

### 4. Скачивание директории

Для скачивания директории из Confluence:

```bash
sber-tunnel download -p <page_id> -d <имя-директории> <путь/для/сохранения>
```

**Пример:**
```bash
sber-tunnel download -p 123456789 -d my-project ./downloads/
```

Команда:
- Скачивает манифест
- Находит все файлы для указанной директории
- Скачивает и собирает чанки файлов
- Проверяет контрольные суммы
- Восстанавливает структуру каталогов
- Устанавливает время модификации файлов

### 5. Удаление директории

Для удаления директории со всеми вложениями из Confluence:

```bash
sber-tunnel delete -p <page_id> -d <имя-директории>
```

**Пример:**
```bash
sber-tunnel delete -p 123456789 -d my-project
```

Команда:
- Загружает манифест и показывает информацию о директории
- Запрашивает подтверждение удаления (можно пропустить с флагом `-y`)
- Удаляет все чанки (attachments) для каждого файла
- Обновляет манифест (или удаляет его, если он стал пустым)

**Пример с пропуском подтверждения:**
```bash
sber-tunnel delete -p 123456789 -d my-project -y
```

### 6. Режим отладки

Все команды поддерживают флаг `--debug` для отображения детальной информации:

```bash
sber-tunnel download --debug -p 123456789 -d my-project ./downloads/
sber-tunnel upload --debug -p 123456789 ./my-project
sber-tunnel delete --debug -p 123456789 -d my-project
```

В режиме отладки отображается:
- Пагинация при получении attachments
- Количество найденных файлов и чанков
- Контрольные суммы
- Подробные трейсбеки ошибок

## Структура манифеста

Сервис использует файл `st-manifest.json`, который хранится как attachment на странице Confluence. Структура манифеста:

```json
[
  {
    "id": "unique-file-id",
    "path": "relative/path/to/file.txt",
    "parent": "directory-name",
    "size": 1024,
    "mtime": 1699999999.0,
    "sha256": "file-hash",
    "version": 1,
    "chunks": [
      {
        "order": 0,
        "checksum": "chunk-hash"
      }
    ]
  }
]
```

## Ограничения

- Максимальный размер чанка: 100 МБ
- Исключаются: скрытые файлы/директории (начинающиеся с точки), временные файлы
- Требуются права на добавление attachments к указанной странице Confluence

## Требования

- Python >= 3.8
- Доступ к Confluence с правами на добавление attachments
- API token для аутентификации

## Зависимости

- click >= 8.1.0
- atlassian-python-api >= 3.41.0
- requests >= 2.31.0
- cryptography >= 41.0.0

## Безопасность

- Пароли и API токены хранятся локально в конфигурационном файле
- Поддержка p12 сертификатов для дополнительной безопасности
- Все данные передаются через HTTPS (при использовании сертификатов)
- Контрольные суммы SHA256 для проверки целостности файлов

## Лицензия

MIT

## Автор

apaem (emila1998@yandex.ru)