Практическое подключение клиента
Работа из терминала через 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, описано в разделе Разработка простого клиента.