Struct ConnectionBuilder 

pub struct ConnectionBuilder { /* private fields */ }

Строитель для создания и настройки экземпляров Connection.

ConnectionBuilder предоставляет удобный интерфейс для настройки параметров соединения перед установлением соединения с сервером CloudPub.

Пример

use cloudpub_sdk::Connection;
use std::time::Duration;

let conn = Connection::builder()
    .config_path("/custom/config.toml")  // Пользовательский файл конфигурации
    .log_level("debug")                  // Установка уровня логирования
    .verbose(true)                       // Включить вывод в консоль
    .credentials("user@example.com", "password")  // Учетные данные для аутентификации
    .timeout(Duration::from_secs(30))    // Таймаут операций
    .build()
    .await?;

Методы аутентификации

Строитель поддерживает два метода аутентификации:

1. На основе токена: Используйте token() для аутентификации с существующим токеном
2. Учетные данные: Используйте credentials() или email()/password() для аутентификации по имени/паролю

Значения по умолчанию

• Уровень логирования: “info”
• Подробный вывод: false
• Таймаут: 10 секунд
• Путь к конфигурации: Системное расположение по умолчанию (~/.config/cloudpub/client.toml)

Implementations

impl ConnectionBuilder

pub fn new() -> Self

Создает новый builder с настройками по умолчанию.

Пример

use cloudpub_sdk::ConnectionBuilder;

let builder = ConnectionBuilder::new();

pub fn config_path<P: AsRef<Path>>(self, path: P) -> Self

Устанавливает путь к файлу конфигурации.

По умолчанию SDK ищет файл конфигурации в стандартном системном расположении. Используйте этот метод для указания пользовательского расположения.

Аргументы

• path - Путь к файлу конфигурации

Пример

use cloudpub_sdk::Connection;
use std::path::Path;

let conn = Connection::builder()
    .config_path(Path::new("/etc/cloudpub/config.toml"))
    .build()
    .await?;

Examples found in repository

examples/example.rs (line 36)

async fn main() -> Result<()> {
    // ====================================================================
    // ШАГ 1: УСТАНОВЛЕНИЕ СОЕДИНЕНИЯ
    // ====================================================================
    println!("1. Подключение к серверу");

    // Создание соединения с использованием паттерна билдера
    // Билдер позволяет настроить различные параметры соединения
    let mut conn = Connection::builder()
        // Указать путь к пользовательскому файлу конфигурации (опционально)
        // Если не указан, используется системное расположение по умолчанию
        .config_path(Path::new("/tmp/cloudpub.toml"))
        // Установить уровень логирования для отладки
        // Варианты: "trace", "debug", "info", "warn", "error"
        .log_level("info")
        // Включить подробный вывод в stderr для отладки
        // Полезно при разработке, отключите в продакшене
        .verbose(true)
        // Предоставить учетные данные для аутентификации
        // Вы также можете использовать .token() для аутентификации на основе токена
        .credentials("admin@example.com", "test")
        // Установить таймаут для операций (в секундах)
        // Применяется ко всем асинхронным операциям
        .timeout_secs(3)
        // Построить и установить соединение
        // Произойдет аутентификация и ожидание готовности соединения
        .build()
        .await?;

    // ====================================================================
    // ШАГ 2: ПУБЛИКАЦИЯ HTTP СЕРВИСА
    // ====================================================================
    println!("2. Публикация нового HTTP сервиса...");

    // Публикация локального HTTP сервиса для доступа через CloudPub
    let endpoint = conn
        .publish(
            Protocol::Http,                           // Тип протокола
            "localhost:8080".to_string(),             // Локальный адрес для публикации
            Some("Тестовый HTTP сервис".to_string()), // Человекочитаемое имя сервиса
            Some(Auth::None),                         // Метод аутентификации для доступа к сервису
            None,                                     // Без ограничений ACL
            None,                                     // Без пользовательских заголовков
            None,                                     // Без правил фильтрации
        )
        .await?;

    // Endpoint содержит информацию об опубликованном сервисе
    // as_url() возвращает публичный URL, по которому доступен сервис
    println!("  Сервис опубликован: {}", endpoint.as_url());

    // ====================================================================
    // ШАГ 3: ПУБЛИКАЦИЯ TCP СЕРВИСА
    // ====================================================================
    println!("3. Публикация нового TCP сервиса...");

    // TCP сервисы полезны для публикации SSH, баз данных или пользовательских TCP протоколов
    let endpoint = conn
        .publish(
            Protocol::Tcp,                           // TCP протокол
            "localhost:22".to_string(),              // Локальный SSH порт (пример)
            Some("Тестовый TCP сервис".to_string()), // Имя сервиса
            Some(Auth::None),                        // Аутентификация не требуется
            None,                                    // Без ограничений ACL
            None,                                    // Без пользовательских заголовков
            None,                                    // Без правил фильтрации
        )
        .await?;

    println!("  Сервис опубликован: {}", endpoint.as_url());

    // Сохранить GUID для последующих операций
    // GUID уникально идентифицирует этот сервис
    let service_guid = endpoint.guid.clone();

    // ====================================================================
    // ШАГ 4: СПИСОК ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("4. Список сервисов:");

    // Получить все сервисы, зарегистрированные текущим пользователем
    let services = conn.ls().await?;

    // Отобразить каждый сервис с его GUID и URL
    for service in &services {
        println!("  {}: {}", service.guid, service.as_url());

        // Сервисы также содержат дополнительные метаданные:
        // - service.name: Опциональное человекочитаемое имя
        // - service.status: Текущий статус (работает, остановлен и т.д.)
        // - service.protocol: Тип протокола
        // - service.auth: Метод аутентификации
    }

    // ====================================================================
    // ШАГ 5: ЗАПУСК СЕРВИСА
    // ====================================================================
    println!("5. Запуск сервиса {}...", service_guid);

    // Запустить ранее остановленный сервис
    // Примечание: Сервисы обычно запускаются автоматически после публикации
    conn.start(service_guid.clone()).await?;
    println!("   - Сервис запущен");

    // ====================================================================
    // ШАГ 6: ПРОВЕРКА СТАТУСА СЕРВИСА
    // ====================================================================
    println!("6. Проверка статуса сервиса...");

    // Получить список сервисов снова, чтобы увидеть обновленный статус
    let services = conn.ls().await?;

    // Найти наш конкретный сервис и отобразить его статус
    if let Some(service) = services.iter().find(|s| s.guid == service_guid) {
        println!(
            "   - Статус сервиса: {}",
            service.status.as_ref().unwrap_or(&"Неизвестно".to_string())
        );

        // Поле статуса указывает состояние сервиса:
        // - "running": Сервис активен и доступен
        // - "stopped": Сервис зарегистрирован, но не доступен
        // - "error": Сервис столкнулся с ошибкой
    }

    let mut buffer = String::new();
    io::stdin()
        .read_line(&mut buffer)
        .expect("Не удалось прочитать строку");

    // ====================================================================
    // ШАГ 7: ОСТАНОВКА СЕРВИСА
    // ====================================================================
    println!("7. Остановка сервиса {}...", service_guid);

    // Остановка делает сервис временно недоступным,
    // но сохраняет его регистрацию
    conn.stop(service_guid.clone()).await?;
    println!("   - Сервис остановлен");

    // ====================================================================
    // ШАГ 8: ОТМЕНА ПУБЛИКАЦИИ СЕРВИСА
    // ====================================================================
    println!("8. Отмена регистрации сервиса {}...", service_guid);

    // Отмена публикации удаляет регистрацию сервиса
    // Сервис больше не будет доступен через CloudPub
    conn.unpublish(service_guid.clone()).await?;
    println!("   - Регистрация сервиса отменена");

    // ====================================================================
    // ШАГ 9: ПРОВЕРКА УДАЛЕНИЯ
    // ====================================================================
    println!("9. Финальный список сервисов...");

    // Получить список сервисов для подтверждения удаления
    let services = conn.ls().await?;
    println!("   - Осталось {} сервис(ов)", services.len());

    // ====================================================================
    // ШАГ 10: ОЧИСТКА ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("10. Очистка всех сервисов...");

    // Clean удаляет все сервисы, зарегистрированные текущим пользователем
    // Используйте с осторожностью, так как это действие нельзя отменить
    conn.clean().await?;
    println!("   - Все сервисы удалены");

    // Проверить, что все сервисы были удалены
    let services = conn.ls().await?;
    println!("   Финальное количество: {} сервис(ов)", services.len());

    println!("Демонстрация успешно завершена!");

    // ====================================================================
    // ОЧИСТКА СОЕДИНЕНИЯ
    // ====================================================================
    // Соединение будет автоматически закрыто, когда `conn` выйдет из области видимости
    // Реализация Drop обрабатывает:
    // - Отправку сообщения Break для корректной остановки клиента
    // - Отмену фоновых задач
    // - Очистку ресурсов

    Ok(())
}

pub fn log_level<S: Into<String>>(self, level: S) -> Self

Устанавливает уровень логирования для SDK.

Аргументы

• level - Уровень логирования: “trace”, “debug”, “info”, “warn”, “error”

Пример

use cloudpub_sdk::Connection;

// Включить отладочное логирование
let conn = Connection::builder()
    .log_level("debug")
    .verbose(true)  // Также выводить в консоль
    .build()
    .await?;

Examples found in repository

examples/example.rs (line 39)

async fn main() -> Result<()> {
    // ====================================================================
    // ШАГ 1: УСТАНОВЛЕНИЕ СОЕДИНЕНИЯ
    // ====================================================================
    println!("1. Подключение к серверу");

    // Создание соединения с использованием паттерна билдера
    // Билдер позволяет настроить различные параметры соединения
    let mut conn = Connection::builder()
        // Указать путь к пользовательскому файлу конфигурации (опционально)
        // Если не указан, используется системное расположение по умолчанию
        .config_path(Path::new("/tmp/cloudpub.toml"))
        // Установить уровень логирования для отладки
        // Варианты: "trace", "debug", "info", "warn", "error"
        .log_level("info")
        // Включить подробный вывод в stderr для отладки
        // Полезно при разработке, отключите в продакшене
        .verbose(true)
        // Предоставить учетные данные для аутентификации
        // Вы также можете использовать .token() для аутентификации на основе токена
        .credentials("admin@example.com", "test")
        // Установить таймаут для операций (в секундах)
        // Применяется ко всем асинхронным операциям
        .timeout_secs(3)
        // Построить и установить соединение
        // Произойдет аутентификация и ожидание готовности соединения
        .build()
        .await?;

    // ====================================================================
    // ШАГ 2: ПУБЛИКАЦИЯ HTTP СЕРВИСА
    // ====================================================================
    println!("2. Публикация нового HTTP сервиса...");

    // Публикация локального HTTP сервиса для доступа через CloudPub
    let endpoint = conn
        .publish(
            Protocol::Http,                           // Тип протокола
            "localhost:8080".to_string(),             // Локальный адрес для публикации
            Some("Тестовый HTTP сервис".to_string()), // Человекочитаемое имя сервиса
            Some(Auth::None),                         // Метод аутентификации для доступа к сервису
            None,                                     // Без ограничений ACL
            None,                                     // Без пользовательских заголовков
            None,                                     // Без правил фильтрации
        )
        .await?;

    // Endpoint содержит информацию об опубликованном сервисе
    // as_url() возвращает публичный URL, по которому доступен сервис
    println!("  Сервис опубликован: {}", endpoint.as_url());

    // ====================================================================
    // ШАГ 3: ПУБЛИКАЦИЯ TCP СЕРВИСА
    // ====================================================================
    println!("3. Публикация нового TCP сервиса...");

    // TCP сервисы полезны для публикации SSH, баз данных или пользовательских TCP протоколов
    let endpoint = conn
        .publish(
            Protocol::Tcp,                           // TCP протокол
            "localhost:22".to_string(),              // Локальный SSH порт (пример)
            Some("Тестовый TCP сервис".to_string()), // Имя сервиса
            Some(Auth::None),                        // Аутентификация не требуется
            None,                                    // Без ограничений ACL
            None,                                    // Без пользовательских заголовков
            None,                                    // Без правил фильтрации
        )
        .await?;

    println!("  Сервис опубликован: {}", endpoint.as_url());

    // Сохранить GUID для последующих операций
    // GUID уникально идентифицирует этот сервис
    let service_guid = endpoint.guid.clone();

    // ====================================================================
    // ШАГ 4: СПИСОК ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("4. Список сервисов:");

    // Получить все сервисы, зарегистрированные текущим пользователем
    let services = conn.ls().await?;

    // Отобразить каждый сервис с его GUID и URL
    for service in &services {
        println!("  {}: {}", service.guid, service.as_url());

        // Сервисы также содержат дополнительные метаданные:
        // - service.name: Опциональное человекочитаемое имя
        // - service.status: Текущий статус (работает, остановлен и т.д.)
        // - service.protocol: Тип протокола
        // - service.auth: Метод аутентификации
    }

    // ====================================================================
    // ШАГ 5: ЗАПУСК СЕРВИСА
    // ====================================================================
    println!("5. Запуск сервиса {}...", service_guid);

    // Запустить ранее остановленный сервис
    // Примечание: Сервисы обычно запускаются автоматически после публикации
    conn.start(service_guid.clone()).await?;
    println!("   - Сервис запущен");

    // ====================================================================
    // ШАГ 6: ПРОВЕРКА СТАТУСА СЕРВИСА
    // ====================================================================
    println!("6. Проверка статуса сервиса...");

    // Получить список сервисов снова, чтобы увидеть обновленный статус
    let services = conn.ls().await?;

    // Найти наш конкретный сервис и отобразить его статус
    if let Some(service) = services.iter().find(|s| s.guid == service_guid) {
        println!(
            "   - Статус сервиса: {}",
            service.status.as_ref().unwrap_or(&"Неизвестно".to_string())
        );

        // Поле статуса указывает состояние сервиса:
        // - "running": Сервис активен и доступен
        // - "stopped": Сервис зарегистрирован, но не доступен
        // - "error": Сервис столкнулся с ошибкой
    }

    let mut buffer = String::new();
    io::stdin()
        .read_line(&mut buffer)
        .expect("Не удалось прочитать строку");

    // ====================================================================
    // ШАГ 7: ОСТАНОВКА СЕРВИСА
    // ====================================================================
    println!("7. Остановка сервиса {}...", service_guid);

    // Остановка делает сервис временно недоступным,
    // но сохраняет его регистрацию
    conn.stop(service_guid.clone()).await?;
    println!("   - Сервис остановлен");

    // ====================================================================
    // ШАГ 8: ОТМЕНА ПУБЛИКАЦИИ СЕРВИСА
    // ====================================================================
    println!("8. Отмена регистрации сервиса {}...", service_guid);

    // Отмена публикации удаляет регистрацию сервиса
    // Сервис больше не будет доступен через CloudPub
    conn.unpublish(service_guid.clone()).await?;
    println!("   - Регистрация сервиса отменена");

    // ====================================================================
    // ШАГ 9: ПРОВЕРКА УДАЛЕНИЯ
    // ====================================================================
    println!("9. Финальный список сервисов...");

    // Получить список сервисов для подтверждения удаления
    let services = conn.ls().await?;
    println!("   - Осталось {} сервис(ов)", services.len());

    // ====================================================================
    // ШАГ 10: ОЧИСТКА ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("10. Очистка всех сервисов...");

    // Clean удаляет все сервисы, зарегистрированные текущим пользователем
    // Используйте с осторожностью, так как это действие нельзя отменить
    conn.clean().await?;
    println!("   - Все сервисы удалены");

    // Проверить, что все сервисы были удалены
    let services = conn.ls().await?;
    println!("   Финальное количество: {} сервис(ов)", services.len());

    println!("Демонстрация успешно завершена!");

    // ====================================================================
    // ОЧИСТКА СОЕДИНЕНИЯ
    // ====================================================================
    // Соединение будет автоматически закрыто, когда `conn` выйдет из области видимости
    // Реализация Drop обрабатывает:
    // - Отправку сообщения Break для корректной остановки клиента
    // - Отмену фоновых задач
    // - Очистку ресурсов

    Ok(())
}

pub fn verbose(self, verbose: bool) -> Self

Включает или отключает подробное логирование в консоль.

При включении сообщения логов выводятся в stderr в дополнение к файлу логов. Это полезно для отладки и разработки.

Аргументы

• verbose - true для включения вывода в консоль, false для отключения

Пример

use cloudpub_sdk::Connection;

let conn = Connection::builder()
    .verbose(true)  // Включить вывод в консоль
    .build()
    .await?;

Examples found in repository

examples/example.rs (line 42)

async fn main() -> Result<()> {
    // ====================================================================
    // ШАГ 1: УСТАНОВЛЕНИЕ СОЕДИНЕНИЯ
    // ====================================================================
    println!("1. Подключение к серверу");

    // Создание соединения с использованием паттерна билдера
    // Билдер позволяет настроить различные параметры соединения
    let mut conn = Connection::builder()
        // Указать путь к пользовательскому файлу конфигурации (опционально)
        // Если не указан, используется системное расположение по умолчанию
        .config_path(Path::new("/tmp/cloudpub.toml"))
        // Установить уровень логирования для отладки
        // Варианты: "trace", "debug", "info", "warn", "error"
        .log_level("info")
        // Включить подробный вывод в stderr для отладки
        // Полезно при разработке, отключите в продакшене
        .verbose(true)
        // Предоставить учетные данные для аутентификации
        // Вы также можете использовать .token() для аутентификации на основе токена
        .credentials("admin@example.com", "test")
        // Установить таймаут для операций (в секундах)
        // Применяется ко всем асинхронным операциям
        .timeout_secs(3)
        // Построить и установить соединение
        // Произойдет аутентификация и ожидание готовности соединения
        .build()
        .await?;

    // ====================================================================
    // ШАГ 2: ПУБЛИКАЦИЯ HTTP СЕРВИСА
    // ====================================================================
    println!("2. Публикация нового HTTP сервиса...");

    // Публикация локального HTTP сервиса для доступа через CloudPub
    let endpoint = conn
        .publish(
            Protocol::Http,                           // Тип протокола
            "localhost:8080".to_string(),             // Локальный адрес для публикации
            Some("Тестовый HTTP сервис".to_string()), // Человекочитаемое имя сервиса
            Some(Auth::None),                         // Метод аутентификации для доступа к сервису
            None,                                     // Без ограничений ACL
            None,                                     // Без пользовательских заголовков
            None,                                     // Без правил фильтрации
        )
        .await?;

    // Endpoint содержит информацию об опубликованном сервисе
    // as_url() возвращает публичный URL, по которому доступен сервис
    println!("  Сервис опубликован: {}", endpoint.as_url());

    // ====================================================================
    // ШАГ 3: ПУБЛИКАЦИЯ TCP СЕРВИСА
    // ====================================================================
    println!("3. Публикация нового TCP сервиса...");

    // TCP сервисы полезны для публикации SSH, баз данных или пользовательских TCP протоколов
    let endpoint = conn
        .publish(
            Protocol::Tcp,                           // TCP протокол
            "localhost:22".to_string(),              // Локальный SSH порт (пример)
            Some("Тестовый TCP сервис".to_string()), // Имя сервиса
            Some(Auth::None),                        // Аутентификация не требуется
            None,                                    // Без ограничений ACL
            None,                                    // Без пользовательских заголовков
            None,                                    // Без правил фильтрации
        )
        .await?;

    println!("  Сервис опубликован: {}", endpoint.as_url());

    // Сохранить GUID для последующих операций
    // GUID уникально идентифицирует этот сервис
    let service_guid = endpoint.guid.clone();

    // ====================================================================
    // ШАГ 4: СПИСОК ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("4. Список сервисов:");

    // Получить все сервисы, зарегистрированные текущим пользователем
    let services = conn.ls().await?;

    // Отобразить каждый сервис с его GUID и URL
    for service in &services {
        println!("  {}: {}", service.guid, service.as_url());

        // Сервисы также содержат дополнительные метаданные:
        // - service.name: Опциональное человекочитаемое имя
        // - service.status: Текущий статус (работает, остановлен и т.д.)
        // - service.protocol: Тип протокола
        // - service.auth: Метод аутентификации
    }

    // ====================================================================
    // ШАГ 5: ЗАПУСК СЕРВИСА
    // ====================================================================
    println!("5. Запуск сервиса {}...", service_guid);

    // Запустить ранее остановленный сервис
    // Примечание: Сервисы обычно запускаются автоматически после публикации
    conn.start(service_guid.clone()).await?;
    println!("   - Сервис запущен");

    // ====================================================================
    // ШАГ 6: ПРОВЕРКА СТАТУСА СЕРВИСА
    // ====================================================================
    println!("6. Проверка статуса сервиса...");

    // Получить список сервисов снова, чтобы увидеть обновленный статус
    let services = conn.ls().await?;

    // Найти наш конкретный сервис и отобразить его статус
    if let Some(service) = services.iter().find(|s| s.guid == service_guid) {
        println!(
            "   - Статус сервиса: {}",
            service.status.as_ref().unwrap_or(&"Неизвестно".to_string())
        );

        // Поле статуса указывает состояние сервиса:
        // - "running": Сервис активен и доступен
        // - "stopped": Сервис зарегистрирован, но не доступен
        // - "error": Сервис столкнулся с ошибкой
    }

    let mut buffer = String::new();
    io::stdin()
        .read_line(&mut buffer)
        .expect("Не удалось прочитать строку");

    // ====================================================================
    // ШАГ 7: ОСТАНОВКА СЕРВИСА
    // ====================================================================
    println!("7. Остановка сервиса {}...", service_guid);

    // Остановка делает сервис временно недоступным,
    // но сохраняет его регистрацию
    conn.stop(service_guid.clone()).await?;
    println!("   - Сервис остановлен");

    // ====================================================================
    // ШАГ 8: ОТМЕНА ПУБЛИКАЦИИ СЕРВИСА
    // ====================================================================
    println!("8. Отмена регистрации сервиса {}...", service_guid);

    // Отмена публикации удаляет регистрацию сервиса
    // Сервис больше не будет доступен через CloudPub
    conn.unpublish(service_guid.clone()).await?;
    println!("   - Регистрация сервиса отменена");

    // ====================================================================
    // ШАГ 9: ПРОВЕРКА УДАЛЕНИЯ
    // ====================================================================
    println!("9. Финальный список сервисов...");

    // Получить список сервисов для подтверждения удаления
    let services = conn.ls().await?;
    println!("   - Осталось {} сервис(ов)", services.len());

    // ====================================================================
    // ШАГ 10: ОЧИСТКА ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("10. Очистка всех сервисов...");

    // Clean удаляет все сервисы, зарегистрированные текущим пользователем
    // Используйте с осторожностью, так как это действие нельзя отменить
    conn.clean().await?;
    println!("   - Все сервисы удалены");

    // Проверить, что все сервисы были удалены
    let services = conn.ls().await?;
    println!("   Финальное количество: {} сервис(ов)", services.len());

    println!("Демонстрация успешно завершена!");

    // ====================================================================
    // ОЧИСТКА СОЕДИНЕНИЯ
    // ====================================================================
    // Соединение будет автоматически закрыто, когда `conn` выйдет из области видимости
    // Реализация Drop обрабатывает:
    // - Отправку сообщения Break для корректной остановки клиента
    // - Отмену фоновых задач
    // - Очистку ресурсов

    Ok(())
}

pub fn token<S: Into<String>>(self, token: S) -> Self

Устанавливает токен аутентификации.

Используйте этот метод для аутентификации на основе токена. Это взаимоисключающе с аутентификацией на основе учетных данных.

Аргументы

• token - Токен аутентификации, полученный при предыдущем входе

Пример

use cloudpub_sdk::Connection;

let conn = Connection::builder()
    .token("your-auth-token-here")
    .build()
    .await?;

pub fn credentials<S: Into<String>>(self, email: S, password: S) -> Self

Устанавливает email и пароль для аутентификации.

Используйте этот метод для аутентификации на основе учетных данных. Это взаимоисключающе с аутентификацией на основе токена.

Аргументы

• email - Email адрес пользователя
• password - Пароль пользователя

Пример

use cloudpub_sdk::Connection;

let conn = Connection::builder()
    .credentials("user@example.com", "secure-password")
    .build()
    .await?;

Examples found in repository

examples/example.rs (line 45)

async fn main() -> Result<()> {
    // ====================================================================
    // ШАГ 1: УСТАНОВЛЕНИЕ СОЕДИНЕНИЯ
    // ====================================================================
    println!("1. Подключение к серверу");

    // Создание соединения с использованием паттерна билдера
    // Билдер позволяет настроить различные параметры соединения
    let mut conn = Connection::builder()
        // Указать путь к пользовательскому файлу конфигурации (опционально)
        // Если не указан, используется системное расположение по умолчанию
        .config_path(Path::new("/tmp/cloudpub.toml"))
        // Установить уровень логирования для отладки
        // Варианты: "trace", "debug", "info", "warn", "error"
        .log_level("info")
        // Включить подробный вывод в stderr для отладки
        // Полезно при разработке, отключите в продакшене
        .verbose(true)
        // Предоставить учетные данные для аутентификации
        // Вы также можете использовать .token() для аутентификации на основе токена
        .credentials("admin@example.com", "test")
        // Установить таймаут для операций (в секундах)
        // Применяется ко всем асинхронным операциям
        .timeout_secs(3)
        // Построить и установить соединение
        // Произойдет аутентификация и ожидание готовности соединения
        .build()
        .await?;

    // ====================================================================
    // ШАГ 2: ПУБЛИКАЦИЯ HTTP СЕРВИСА
    // ====================================================================
    println!("2. Публикация нового HTTP сервиса...");

    // Публикация локального HTTP сервиса для доступа через CloudPub
    let endpoint = conn
        .publish(
            Protocol::Http,                           // Тип протокола
            "localhost:8080".to_string(),             // Локальный адрес для публикации
            Some("Тестовый HTTP сервис".to_string()), // Человекочитаемое имя сервиса
            Some(Auth::None),                         // Метод аутентификации для доступа к сервису
            None,                                     // Без ограничений ACL
            None,                                     // Без пользовательских заголовков
            None,                                     // Без правил фильтрации
        )
        .await?;

    // Endpoint содержит информацию об опубликованном сервисе
    // as_url() возвращает публичный URL, по которому доступен сервис
    println!("  Сервис опубликован: {}", endpoint.as_url());

    // ====================================================================
    // ШАГ 3: ПУБЛИКАЦИЯ TCP СЕРВИСА
    // ====================================================================
    println!("3. Публикация нового TCP сервиса...");

    // TCP сервисы полезны для публикации SSH, баз данных или пользовательских TCP протоколов
    let endpoint = conn
        .publish(
            Protocol::Tcp,                           // TCP протокол
            "localhost:22".to_string(),              // Локальный SSH порт (пример)
            Some("Тестовый TCP сервис".to_string()), // Имя сервиса
            Some(Auth::None),                        // Аутентификация не требуется
            None,                                    // Без ограничений ACL
            None,                                    // Без пользовательских заголовков
            None,                                    // Без правил фильтрации
        )
        .await?;

    println!("  Сервис опубликован: {}", endpoint.as_url());

    // Сохранить GUID для последующих операций
    // GUID уникально идентифицирует этот сервис
    let service_guid = endpoint.guid.clone();

    // ====================================================================
    // ШАГ 4: СПИСОК ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("4. Список сервисов:");

    // Получить все сервисы, зарегистрированные текущим пользователем
    let services = conn.ls().await?;

    // Отобразить каждый сервис с его GUID и URL
    for service in &services {
        println!("  {}: {}", service.guid, service.as_url());

        // Сервисы также содержат дополнительные метаданные:
        // - service.name: Опциональное человекочитаемое имя
        // - service.status: Текущий статус (работает, остановлен и т.д.)
        // - service.protocol: Тип протокола
        // - service.auth: Метод аутентификации
    }

    // ====================================================================
    // ШАГ 5: ЗАПУСК СЕРВИСА
    // ====================================================================
    println!("5. Запуск сервиса {}...", service_guid);

    // Запустить ранее остановленный сервис
    // Примечание: Сервисы обычно запускаются автоматически после публикации
    conn.start(service_guid.clone()).await?;
    println!("   - Сервис запущен");

    // ====================================================================
    // ШАГ 6: ПРОВЕРКА СТАТУСА СЕРВИСА
    // ====================================================================
    println!("6. Проверка статуса сервиса...");

    // Получить список сервисов снова, чтобы увидеть обновленный статус
    let services = conn.ls().await?;

    // Найти наш конкретный сервис и отобразить его статус
    if let Some(service) = services.iter().find(|s| s.guid == service_guid) {
        println!(
            "   - Статус сервиса: {}",
            service.status.as_ref().unwrap_or(&"Неизвестно".to_string())
        );

        // Поле статуса указывает состояние сервиса:
        // - "running": Сервис активен и доступен
        // - "stopped": Сервис зарегистрирован, но не доступен
        // - "error": Сервис столкнулся с ошибкой
    }

    let mut buffer = String::new();
    io::stdin()
        .read_line(&mut buffer)
        .expect("Не удалось прочитать строку");

    // ====================================================================
    // ШАГ 7: ОСТАНОВКА СЕРВИСА
    // ====================================================================
    println!("7. Остановка сервиса {}...", service_guid);

    // Остановка делает сервис временно недоступным,
    // но сохраняет его регистрацию
    conn.stop(service_guid.clone()).await?;
    println!("   - Сервис остановлен");

    // ====================================================================
    // ШАГ 8: ОТМЕНА ПУБЛИКАЦИИ СЕРВИСА
    // ====================================================================
    println!("8. Отмена регистрации сервиса {}...", service_guid);

    // Отмена публикации удаляет регистрацию сервиса
    // Сервис больше не будет доступен через CloudPub
    conn.unpublish(service_guid.clone()).await?;
    println!("   - Регистрация сервиса отменена");

    // ====================================================================
    // ШАГ 9: ПРОВЕРКА УДАЛЕНИЯ
    // ====================================================================
    println!("9. Финальный список сервисов...");

    // Получить список сервисов для подтверждения удаления
    let services = conn.ls().await?;
    println!("   - Осталось {} сервис(ов)", services.len());

    // ====================================================================
    // ШАГ 10: ОЧИСТКА ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("10. Очистка всех сервисов...");

    // Clean удаляет все сервисы, зарегистрированные текущим пользователем
    // Используйте с осторожностью, так как это действие нельзя отменить
    conn.clean().await?;
    println!("   - Все сервисы удалены");

    // Проверить, что все сервисы были удалены
    let services = conn.ls().await?;
    println!("   Финальное количество: {} сервис(ов)", services.len());

    println!("Демонстрация успешно завершена!");

    // ====================================================================
    // ОЧИСТКА СОЕДИНЕНИЯ
    // ====================================================================
    // Соединение будет автоматически закрыто, когда `conn` выйдет из области видимости
    // Реализация Drop обрабатывает:
    // - Отправку сообщения Break для корректной остановки клиента
    // - Отмену фоновых задач
    // - Очистку ресурсов

    Ok(())
}

pub fn email<S: Into<String>>(self, email: S) -> Self

Устанавливает только email адрес.

Должен использоваться в сочетании с password(). Это полезно, когда учетные данные получаются отдельно.

Аргументы

• email - Email адрес пользователя

Пример

use cloudpub_sdk::Connection;

let conn = Connection::builder()
    .email("user@example.com")
    .password("secure-password")
    .build()
    .await?;

pub fn password<S: Into<String>>(self, password: S) -> Self

Устанавливает только пароль.

Должен использоваться в сочетании с email(). Это полезно, когда учетные данные получаются отдельно.

Аргументы

• password - Пароль пользователя

Пример

use cloudpub_sdk::Connection;

let email = std::env::var("CLOUDPUB_EMAIL")?;
let password = std::env::var("CLOUDPUB_PASSWORD")?;

let conn = Connection::builder()
    .email(email)
    .password(password)
    .build()
    .await?;

pub fn timeout(self, timeout: Duration) -> Self

Устанавливает таймаут для операций.

Этот таймаут применяется ко всем асинхронным операциям, таким как register, publish, ls и т.д. По умолчанию 10 секунд.

Аргументы

• timeout - Продолжительность таймаута операции

Пример

use cloudpub_sdk::Connection;
use std::time::Duration;

let conn = Connection::builder()
    .timeout(Duration::from_secs(60))  // Таймаут 1 минута
    .build()
    .await?;

pub fn timeout_secs(self, secs: u64) -> Self

Устанавливает таймаут в секундах.

Удобный метод для установки таймаута в секундах вместо Duration.

Аргументы

• secs - Таймаут в секундах

Пример

use cloudpub_sdk::Connection;

let conn = Connection::builder()
    .timeout_secs(30)  // Таймаут 30 секунд
    .build()
    .await?;

Examples found in repository

examples/example.rs (line 48)

async fn main() -> Result<()> {
    // ====================================================================
    // ШАГ 1: УСТАНОВЛЕНИЕ СОЕДИНЕНИЯ
    // ====================================================================
    println!("1. Подключение к серверу");

    // Создание соединения с использованием паттерна билдера
    // Билдер позволяет настроить различные параметры соединения
    let mut conn = Connection::builder()
        // Указать путь к пользовательскому файлу конфигурации (опционально)
        // Если не указан, используется системное расположение по умолчанию
        .config_path(Path::new("/tmp/cloudpub.toml"))
        // Установить уровень логирования для отладки
        // Варианты: "trace", "debug", "info", "warn", "error"
        .log_level("info")
        // Включить подробный вывод в stderr для отладки
        // Полезно при разработке, отключите в продакшене
        .verbose(true)
        // Предоставить учетные данные для аутентификации
        // Вы также можете использовать .token() для аутентификации на основе токена
        .credentials("admin@example.com", "test")
        // Установить таймаут для операций (в секундах)
        // Применяется ко всем асинхронным операциям
        .timeout_secs(3)
        // Построить и установить соединение
        // Произойдет аутентификация и ожидание готовности соединения
        .build()
        .await?;

    // ====================================================================
    // ШАГ 2: ПУБЛИКАЦИЯ HTTP СЕРВИСА
    // ====================================================================
    println!("2. Публикация нового HTTP сервиса...");

    // Публикация локального HTTP сервиса для доступа через CloudPub
    let endpoint = conn
        .publish(
            Protocol::Http,                           // Тип протокола
            "localhost:8080".to_string(),             // Локальный адрес для публикации
            Some("Тестовый HTTP сервис".to_string()), // Человекочитаемое имя сервиса
            Some(Auth::None),                         // Метод аутентификации для доступа к сервису
            None,                                     // Без ограничений ACL
            None,                                     // Без пользовательских заголовков
            None,                                     // Без правил фильтрации
        )
        .await?;

    // Endpoint содержит информацию об опубликованном сервисе
    // as_url() возвращает публичный URL, по которому доступен сервис
    println!("  Сервис опубликован: {}", endpoint.as_url());

    // ====================================================================
    // ШАГ 3: ПУБЛИКАЦИЯ TCP СЕРВИСА
    // ====================================================================
    println!("3. Публикация нового TCP сервиса...");

    // TCP сервисы полезны для публикации SSH, баз данных или пользовательских TCP протоколов
    let endpoint = conn
        .publish(
            Protocol::Tcp,                           // TCP протокол
            "localhost:22".to_string(),              // Локальный SSH порт (пример)
            Some("Тестовый TCP сервис".to_string()), // Имя сервиса
            Some(Auth::None),                        // Аутентификация не требуется
            None,                                    // Без ограничений ACL
            None,                                    // Без пользовательских заголовков
            None,                                    // Без правил фильтрации
        )
        .await?;

    println!("  Сервис опубликован: {}", endpoint.as_url());

    // Сохранить GUID для последующих операций
    // GUID уникально идентифицирует этот сервис
    let service_guid = endpoint.guid.clone();

    // ====================================================================
    // ШАГ 4: СПИСОК ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("4. Список сервисов:");

    // Получить все сервисы, зарегистрированные текущим пользователем
    let services = conn.ls().await?;

    // Отобразить каждый сервис с его GUID и URL
    for service in &services {
        println!("  {}: {}", service.guid, service.as_url());

        // Сервисы также содержат дополнительные метаданные:
        // - service.name: Опциональное человекочитаемое имя
        // - service.status: Текущий статус (работает, остановлен и т.д.)
        // - service.protocol: Тип протокола
        // - service.auth: Метод аутентификации
    }

    // ====================================================================
    // ШАГ 5: ЗАПУСК СЕРВИСА
    // ====================================================================
    println!("5. Запуск сервиса {}...", service_guid);

    // Запустить ранее остановленный сервис
    // Примечание: Сервисы обычно запускаются автоматически после публикации
    conn.start(service_guid.clone()).await?;
    println!("   - Сервис запущен");

    // ====================================================================
    // ШАГ 6: ПРОВЕРКА СТАТУСА СЕРВИСА
    // ====================================================================
    println!("6. Проверка статуса сервиса...");

    // Получить список сервисов снова, чтобы увидеть обновленный статус
    let services = conn.ls().await?;

    // Найти наш конкретный сервис и отобразить его статус
    if let Some(service) = services.iter().find(|s| s.guid == service_guid) {
        println!(
            "   - Статус сервиса: {}",
            service.status.as_ref().unwrap_or(&"Неизвестно".to_string())
        );

        // Поле статуса указывает состояние сервиса:
        // - "running": Сервис активен и доступен
        // - "stopped": Сервис зарегистрирован, но не доступен
        // - "error": Сервис столкнулся с ошибкой
    }

    let mut buffer = String::new();
    io::stdin()
        .read_line(&mut buffer)
        .expect("Не удалось прочитать строку");

    // ====================================================================
    // ШАГ 7: ОСТАНОВКА СЕРВИСА
    // ====================================================================
    println!("7. Остановка сервиса {}...", service_guid);

    // Остановка делает сервис временно недоступным,
    // но сохраняет его регистрацию
    conn.stop(service_guid.clone()).await?;
    println!("   - Сервис остановлен");

    // ====================================================================
    // ШАГ 8: ОТМЕНА ПУБЛИКАЦИИ СЕРВИСА
    // ====================================================================
    println!("8. Отмена регистрации сервиса {}...", service_guid);

    // Отмена публикации удаляет регистрацию сервиса
    // Сервис больше не будет доступен через CloudPub
    conn.unpublish(service_guid.clone()).await?;
    println!("   - Регистрация сервиса отменена");

    // ====================================================================
    // ШАГ 9: ПРОВЕРКА УДАЛЕНИЯ
    // ====================================================================
    println!("9. Финальный список сервисов...");

    // Получить список сервисов для подтверждения удаления
    let services = conn.ls().await?;
    println!("   - Осталось {} сервис(ов)", services.len());

    // ====================================================================
    // ШАГ 10: ОЧИСТКА ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("10. Очистка всех сервисов...");

    // Clean удаляет все сервисы, зарегистрированные текущим пользователем
    // Используйте с осторожностью, так как это действие нельзя отменить
    conn.clean().await?;
    println!("   - Все сервисы удалены");

    // Проверить, что все сервисы были удалены
    let services = conn.ls().await?;
    println!("   Финальное количество: {} сервис(ов)", services.len());

    println!("Демонстрация успешно завершена!");

    // ====================================================================
    // ОЧИСТКА СОЕДИНЕНИЯ
    // ====================================================================
    // Соединение будет автоматически закрыто, когда `conn` выйдет из области видимости
    // Реализация Drop обрабатывает:
    // - Отправку сообщения Break для корректной остановки клиента
    // - Отмену фоновых задач
    // - Очистку ресурсов

    Ok(())
}

pub fn check_signal_fn(self, check_fn: CheckSignalFn) -> Self

Устанавливает функцию для проверки сигналов прерывания.

Это в основном используется языковыми обертками (например, Python) для проверки сигналов, таких как Ctrl+C, во время долговременных операций.

Аргументы

• check_fn - Функция, которая возвращает ошибку, если операция должна быть прервана

Пример

use cloudpub_sdk::{Connection, CheckSignalFn};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};

let interrupted = Arc::new(AtomicBool::new(false));
let interrupted_clone = interrupted.clone();

let check_signal: CheckSignalFn = Arc::new(move || {
    if interrupted_clone.load(Ordering::Relaxed) {
        anyhow::bail!("Operation interrupted")
    }
    Ok(())
});

let conn = Connection::builder()
    .check_signal_fn(check_signal)
    .build()
    .await?;

pub async fn build(self) -> Result<Connection>

Создает и устанавливает соединение с сервером CloudPub.

Этот метод:

1. Проверяет конфигурацию
2. Инициализирует логирование
3. Загружает или создает файл конфигурации
4. Аутентифицируется на сервере (если предоставлены учетные данные)
5. Устанавливает соединение
6. Ожидает готовности соединения

Возвращает

Возвращает экземпляр Connection при успехе, или ошибку, если:

• Неверная конфигурация (например, email без пароля)
• Неудачная аутентификация
• Не удается установить соединение
• Происходит таймаут

Пример

use cloudpub_sdk::Connection;

// Создание с настройками по умолчанию
let conn = Connection::builder().build().await?;

// Создание с пользовательской конфигурацией
let conn = Connection::builder()
    .credentials("user@example.com", "password")
    .log_level("debug")
    .verbose(true)
    .timeout_secs(30)
    .build()
    .await?;

Ошибки

Этот метод вернет ошибку, если:

• Email предоставлен без пароля или наоборот
• Не удалось инициализировать логирование
• Не удалось загрузить или создать файл конфигурации
• Неудачная аутентификация
• Неудачное соединение с сервером
• Таймаут ожидания соединения

Examples found in repository

examples/example.rs (line 51)

async fn main() -> Result<()> {
    // ====================================================================
    // ШАГ 1: УСТАНОВЛЕНИЕ СОЕДИНЕНИЯ
    // ====================================================================
    println!("1. Подключение к серверу");

    // Создание соединения с использованием паттерна билдера
    // Билдер позволяет настроить различные параметры соединения
    let mut conn = Connection::builder()
        // Указать путь к пользовательскому файлу конфигурации (опционально)
        // Если не указан, используется системное расположение по умолчанию
        .config_path(Path::new("/tmp/cloudpub.toml"))
        // Установить уровень логирования для отладки
        // Варианты: "trace", "debug", "info", "warn", "error"
        .log_level("info")
        // Включить подробный вывод в stderr для отладки
        // Полезно при разработке, отключите в продакшене
        .verbose(true)
        // Предоставить учетные данные для аутентификации
        // Вы также можете использовать .token() для аутентификации на основе токена
        .credentials("admin@example.com", "test")
        // Установить таймаут для операций (в секундах)
        // Применяется ко всем асинхронным операциям
        .timeout_secs(3)
        // Построить и установить соединение
        // Произойдет аутентификация и ожидание готовности соединения
        .build()
        .await?;

    // ====================================================================
    // ШАГ 2: ПУБЛИКАЦИЯ HTTP СЕРВИСА
    // ====================================================================
    println!("2. Публикация нового HTTP сервиса...");

    // Публикация локального HTTP сервиса для доступа через CloudPub
    let endpoint = conn
        .publish(
            Protocol::Http,                           // Тип протокола
            "localhost:8080".to_string(),             // Локальный адрес для публикации
            Some("Тестовый HTTP сервис".to_string()), // Человекочитаемое имя сервиса
            Some(Auth::None),                         // Метод аутентификации для доступа к сервису
            None,                                     // Без ограничений ACL
            None,                                     // Без пользовательских заголовков
            None,                                     // Без правил фильтрации
        )
        .await?;

    // Endpoint содержит информацию об опубликованном сервисе
    // as_url() возвращает публичный URL, по которому доступен сервис
    println!("  Сервис опубликован: {}", endpoint.as_url());

    // ====================================================================
    // ШАГ 3: ПУБЛИКАЦИЯ TCP СЕРВИСА
    // ====================================================================
    println!("3. Публикация нового TCP сервиса...");

    // TCP сервисы полезны для публикации SSH, баз данных или пользовательских TCP протоколов
    let endpoint = conn
        .publish(
            Protocol::Tcp,                           // TCP протокол
            "localhost:22".to_string(),              // Локальный SSH порт (пример)
            Some("Тестовый TCP сервис".to_string()), // Имя сервиса
            Some(Auth::None),                        // Аутентификация не требуется
            None,                                    // Без ограничений ACL
            None,                                    // Без пользовательских заголовков
            None,                                    // Без правил фильтрации
        )
        .await?;

    println!("  Сервис опубликован: {}", endpoint.as_url());

    // Сохранить GUID для последующих операций
    // GUID уникально идентифицирует этот сервис
    let service_guid = endpoint.guid.clone();

    // ====================================================================
    // ШАГ 4: СПИСОК ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("4. Список сервисов:");

    // Получить все сервисы, зарегистрированные текущим пользователем
    let services = conn.ls().await?;

    // Отобразить каждый сервис с его GUID и URL
    for service in &services {
        println!("  {}: {}", service.guid, service.as_url());

        // Сервисы также содержат дополнительные метаданные:
        // - service.name: Опциональное человекочитаемое имя
        // - service.status: Текущий статус (работает, остановлен и т.д.)
        // - service.protocol: Тип протокола
        // - service.auth: Метод аутентификации
    }

    // ====================================================================
    // ШАГ 5: ЗАПУСК СЕРВИСА
    // ====================================================================
    println!("5. Запуск сервиса {}...", service_guid);

    // Запустить ранее остановленный сервис
    // Примечание: Сервисы обычно запускаются автоматически после публикации
    conn.start(service_guid.clone()).await?;
    println!("   - Сервис запущен");

    // ====================================================================
    // ШАГ 6: ПРОВЕРКА СТАТУСА СЕРВИСА
    // ====================================================================
    println!("6. Проверка статуса сервиса...");

    // Получить список сервисов снова, чтобы увидеть обновленный статус
    let services = conn.ls().await?;

    // Найти наш конкретный сервис и отобразить его статус
    if let Some(service) = services.iter().find(|s| s.guid == service_guid) {
        println!(
            "   - Статус сервиса: {}",
            service.status.as_ref().unwrap_or(&"Неизвестно".to_string())
        );

        // Поле статуса указывает состояние сервиса:
        // - "running": Сервис активен и доступен
        // - "stopped": Сервис зарегистрирован, но не доступен
        // - "error": Сервис столкнулся с ошибкой
    }

    let mut buffer = String::new();
    io::stdin()
        .read_line(&mut buffer)
        .expect("Не удалось прочитать строку");

    // ====================================================================
    // ШАГ 7: ОСТАНОВКА СЕРВИСА
    // ====================================================================
    println!("7. Остановка сервиса {}...", service_guid);

    // Остановка делает сервис временно недоступным,
    // но сохраняет его регистрацию
    conn.stop(service_guid.clone()).await?;
    println!("   - Сервис остановлен");

    // ====================================================================
    // ШАГ 8: ОТМЕНА ПУБЛИКАЦИИ СЕРВИСА
    // ====================================================================
    println!("8. Отмена регистрации сервиса {}...", service_guid);

    // Отмена публикации удаляет регистрацию сервиса
    // Сервис больше не будет доступен через CloudPub
    conn.unpublish(service_guid.clone()).await?;
    println!("   - Регистрация сервиса отменена");

    // ====================================================================
    // ШАГ 9: ПРОВЕРКА УДАЛЕНИЯ
    // ====================================================================
    println!("9. Финальный список сервисов...");

    // Получить список сервисов для подтверждения удаления
    let services = conn.ls().await?;
    println!("   - Осталось {} сервис(ов)", services.len());

    // ====================================================================
    // ШАГ 10: ОЧИСТКА ВСЕХ СЕРВИСОВ
    // ====================================================================
    println!("10. Очистка всех сервисов...");

    // Clean удаляет все сервисы, зарегистрированные текущим пользователем
    // Используйте с осторожностью, так как это действие нельзя отменить
    conn.clean().await?;
    println!("   - Все сервисы удалены");

    // Проверить, что все сервисы были удалены
    let services = conn.ls().await?;
    println!("   Финальное количество: {} сервис(ов)", services.len());

    println!("Демонстрация успешно завершена!");

    // ====================================================================
    // ОЧИСТКА СОЕДИНЕНИЯ
    // ====================================================================
    // Соединение будет автоматически закрыто, когда `conn` выйдет из области видимости
    // Реализация Drop обрабатывает:
    // - Отправку сообщения Break для корректной остановки клиента
    // - Отмену фоновых задач
    // - Очистку ресурсов

    Ok(())
}

Trait Implementations

impl Default for ConnectionBuilder

fn default() -> Self

Returns the “default value” for a type.