Практическое подключение клиента

Работа из терминала через altera-cli

Предполагается, что основная служба Altera уже запущена и соответствующие модули установлены.

Один модуль:

altera-cli /backend3/sysinfo

Внутри CLI:

altera> {"action":"read"}

Несколько модулей:

altera-cli

Внутри CLI:

altera> {"/backend3/sysinfo":{"action":"read"}}
altera> {"/backend4/python-example":{"action":{"read":{"name":"eth0"}}}}
altera> {"/backend4/python-example":"exit"}

После отправки запросов stdin можно закрыть: CLI дождётся ответов и завершения обмена. Для длительной сессии или ответов на вопросы Polkit stdin нужно сохранять открытым.

Из браузера

Следующий пример предназначен для UI, обслуживаемого тем же веб-origin, что и API Altera. Он демонстрирует вход и маршрутизацию событий, но не реализует формы диалога Polkit.

Запрос входа:

POST /auth/login
Content-Type: application/json

{"username":"alice","password":"example-password"}

При успешном входе сервер возвращает 200 OK и JSON (Login Response):

{
    "token": "<session-token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": "alice",
    "auth_level": "user"
}

expires_in — срок действия сессии в секундах, заданный настройкой сервера; 3600 — значение по умолчанию (для systemd-сервиса значение по умолчанию увеличено до 86400 секунд). auth_level равен root для имени пользователя root и user для остальных. Это поле не заменяет проверку прав на операции модулей через Polkit. Токен — непрозрачный идентификатор серверной сессии; разбирать его как JWT не нужно.

async function connectAltera(username, password) {
    const response = await fetch("/auth/login", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ username, password })
    });

    const login = await response.json();
    if (!response.ok) {
        throw new Error(login.message ?? `Login failed: HTTP ${response.status}`);
    }

    const url = new URL("/ws", location.href);
    url.protocol = location.protocol === "https:" ? "wss:" : "ws:";

    const socket = new WebSocket(url, ["altera", `bearer.${login.token}`]);

    socket.addEventListener("message", (event) => {
        // Веб-мост данной версии отправляет stdout CLI текстовыми кадрами.
        const message = JSON.parse(event.data);

        // Общая ошибка, когда маршрут не удалось определить.
        if (typeof message.type === "string" &&
            message.type.endsWith("-error") && typeof message.code === "string") {
            console.error(message.type, message.code, message.message);
            return;
        }

        for (const [path, payload] of Object.entries(message)) {
            if (typeof payload?.type === "string" &&
                payload.type.endsWith("-error") && typeof payload.code === "string") {
                console.error("Ошибка запроса:", path, payload.type, payload.code, payload.message);
            } else if (payload?.altera === "write_state") {
                console.log("Состояние записи:", path, payload.busy);
            } else if (payload?.auth_needed === true) {
                console.log("Нужно подтверждение:", path, payload.query);
                // UI предлагает пользователю начать диалог.
            } else if (typeof payload?.type === "string" &&
                       payload.type.startsWith("auth_")) {
                console.log("Событие Polkit:", path, payload);
                // UI показывает выбор identity / вопрос / информацию.
            } else {
                console.log("Ответ модуля:", path, payload);
            }
        }
    });

    await new Promise((resolve, reject) => {
        socket.addEventListener("open", resolve, { once: true });
        socket.addEventListener(
            "error",
            () => reject(new Error("WebSocket connection failed")),
            { once: true }
        );
    });

    socket.send(JSON.stringify({
        "/backend3/sysinfo": { action: "read" }
    }));

    // Сохраняем все поля Login Response для состояния интерфейса.
    return { socket, ...login };
}

async function logoutAltera(token) {
    const response = await fetch("/auth/logout", {
        method: "POST",
        headers: { Authorization: `Bearer ${token}` }
    });
    if (response.status !== 204) {
        throw new Error(`Logout failed: HTTP ${response.status}`);
    }
    // После успешного ответа удалите токен из состояния приложения.
    // Все WebSocket этого токена сервер закроет самостоятельно.
}

username и password передаются из формы входа; пример не предлагает хранить пароль. После успешного подключения токен не нужно вкладывать в каждый backend-запрос: он проверяется при handshake. logoutAltera(token) отзывает Bearer-сессию; обработчик close должен учитывать код 1008 при выходе или истечении TTL. Формат подпротоколов и сообщений соответствует текущей реализации.

Для начала интерактивной авторизации в /ws:

socket.send(JSON.stringify({
    "/backend3/services": {
        authenticate: true,
        query: originalQuery
    }
}));

После этого интерфейс обрабатывает auth_identities, auth_prompt и отвечает в том же пути.

Примечание: Сокет не следует автоматически переподключать и повторять write при ошибке: результат предыдущей записи может быть неизвестен.

Собственный Unix-клиент

Клиент подключается к /run/altera/.socket и обменивается JSON Lines. В сборке с legacy-unix-peer перед JSON-обменом выполняется дополнительная идентификация, реализованная в src/unix_peer/legacy.rs. Клиент продолжает читать ответы и служебные события во время диалога авторизации.

Подробнее о том, как разработать собственный клиент для Altera, описано в разделе Разработка простого клиента.

Источники