O que é um vssh-app

Ao terminar esta página você sabe dizer onde cada peça de um vssh-app roda, o que o ambiente faz por ela sem que o app peça, e o que o SDK expõe ao seu código. É o mapa que as outras páginas detalham.

Três lugares

Um vssh-app é um pacote: um vssh-app.json na raiz, um frontend em HTML e um backend em Python, Node ou binário. O pacote é desenvolvido fora do sistema, num repositório próprio, e instalado num servidor Linux que o VSSH já provisionou. Depois de instalado, o app aparece no menu iniciar e no launchpad de cada pessoa que usa aquele servidor, e abre como uma janela.

As peças rodam em três lugares:

O backend escuta num socket unix em $VSSH_APP_SOCKET, que é ~/.vssh-apps/<id>/app.sock. O endereço é derivado de (HOME, id), e os dois lados o calculam sozinhos: o portal não aloca porta, não guarda cache de endereço e não tem o que reconciliar. O diretório é 0700 do dono, então o socket de um app não é alcançável por outra conta Linux da máquina.

A janela é HTML desenhado pelo navegador. Um vssh-app não depende do motor X11 e se comporta igual num servidor sem ele.

O que o ambiente faz sem o app pedir

Antes de escrever uma linha de API, vale saber o que já acontece por conta do sistema:

• o proxy encaminha HTTP e WebSocket ao backend, e injeta em cada requisição o header X-Vssh-App-Token, gerado por instância. O socket já é do dono; o header é a segunda barreira, para o app que serve algo sensível recusar o que não veio pelo proxy;
• o ciclo de vida sobe o backend quando alguém abre a janela, sonda o healthcheckPath até 15 vezes com 1 s de intervalo, e mantém o processo de pé enquanto o estado desejado for "rodando" (ciclo de vida);
• o processo sobe contido por um escopo do systemd, com teto de memória e de tarefas, e sem enxergar a GPU a menos que o manifesto a peça (o manifesto);
• o document.title do frontend vira o título da janela; um <a target="_blank"> ou um window.open de uma biblioteca abre no navegador do ambiente, e o clique direito mostra só o que o app montou (a janela);
• o volume do app obedece ao mixer da barra, e o app aparece nele por carregar o shim;
• a janela sobrevive a uma queda do portal (o que o sistema garante).

O que o SDK expõe

O sistema é o fonte privado; o autor de app programa contra um SDK público gerado a partir dele. A tabela de exportação da ponte entre app e shell é dado: cada verbo tem um nome público, em português, e um nome que viaja no fio por postMessage. O fio é interno ao sistema e fica parado quando o nome público muda, e é isso que mantém um app instalado funcionando enquanto o SDK evolui.

Os espaços, e o que cada um abstrai:

O padrão que atravessa todos os espaços: só dado cruza a ponte. O app manda rótulos, ids e caminhos, nunca uma função nem HTML, e o shell desenha o diálogo, o menu, o seletor e a notificação com a aparência do ambiente.

A primeira pergunta de um app é vssh.app.capacidades(). A resposta traz o nome do host, o que ele sabe fazer (nativeApps, x11Interop, clipboardServer e os demais), a versão do shell e a lista de verbos e eventos da tabela. Com a lista o app decide sozinho se o shell em que caiu tem o que ele precisa, e degrada onde não tem. shellVersion: null é resposta válida: um shell que não se declara.

Fora do ambiente

O frontend roda fora do desktop sem if nenhum: cada verbo degrada para o equivalente do navegador (um diálogo vira window.confirm, um seletor devolve null, um controle de janela não faz nada). O backend precisa só de três variáveis (VSSH_APP_SOCKET, VSSH_APP_ID, VSSH_APP_DATA_DIR) e sobe na sua máquina, sem servidor VSSH. O que não funciona fora do ambiente é o que precisa do shell do outro lado: o consentimento de arquivos, a bandeja, o cofre.

O que o ambiente não entrega

Uma lista curta que decide se um port é viável antes de começar:

Tudo que o app precisa de sistema (um processo filho, um binário nativo, um índice) mora no backend dele, que existe para isso.