OxideTerm: Análise de Circuito

Posse de Sessão do Nó OxideTerm

Use esta habilidade sempre que uma alteração puder modificar qual componente cria, compartilha, fecha, reconecta ou observa uma sessão remota ou tarefa em segundo plano.

Invariante central

Um nó SSH conectado é independente de qualquer painel de terminal que o consuma. O tempo de vida da interface do usuário não deve se tornar silenciosamente o tempo de vida do backend.

flowchart TD
    W["Tempo de vida do workspace ou aplicação"] --> R["NodeRouter e registro de conexão"]
    R --> N["Conexão física do nó SSH"]
    N --> T["Consumidor do terminal"]
    N --> S["Consumidor SFTP"]
    N --> F["Consumidor de encaminhamento"]
    R --> H["Tarefas de integridade e reconexão"]

Regras obrigatórias

• A atividade do nó pertence ao registro de conexão, ao NodeRouter ou a uma operação explícita de desconexão do nó.
• Fechar um painel de terminal remove aquele consumidor do terminal. Não deve desconectar um nó compartilhado.
• O SFTP deve adquirir uma sessão SFTP real com suporte do nó. Um comando de shell que imite transferência de arquivos é apenas uma alternativa de compatibilidade documentada.
• O encaminhamento de porta possui suas próprias tarefas de ouvinte e ponte. Essas tarefas devem permanecer ativas sem um painel de terminal aberto e devem parar quando a regra de encaminhamento ou o nó proprietário parar.
• Reconexão, verificações de integridade, períodos de carência e pontes de processo filho precisam de um proprietário explícito e um caminho de cancelamento vinculado ao tempo de vida do nó, workspace ou aplicação.
• Trabalhos de longa duração não devem ser executados em um runtime de uso único que é descartado quando um manipulador de comando retorna.
• Um nó filho conectado através de um host de salto deve manter a conexão pai enquanto o transporte filho precisar dela.
• Os componentes da UI observam o estado do runtime através de eventos do roteador ou do registro. Eles não devem inferir a atividade do nó a partir da existência do terminal.
• Adicione comentários concisos em inglês nas transferências de posse: criação, compartilhamento, invalidação, readquisição, cancelamento e sobrevivência deliberada após a destruição da UI.

Bypass proibidos

• Não abra um segundo transporte SSH não gerenciado porque uma API baseada em nó é inconveniente.
• Não encontre uma conexão selecionando o primeiro painel de terminal associado a um host.
• Não armazene uma tarefa de longa duração apenas em um diálogo temporário, manipulador de comando ou visualização de terminal.
• Não marque um nó como desconectado meramente porque um canal, painel, requisição SFTP ou consumidor de encaminhamento fecha.
• Não deixe processos filhos gerados ou tarefas Tokio destacadas sem um sinal de desligamento e um caminho de conclusão limitado.

Práticas recomendadas

• Expresse cada dependência do backend como um consumidor ou proprietário no registro, em vez de confiar na retenção incidental de Arc.
• Mantenha o estado do transporte físico na entrada da conexão e a topologia lógica no NodeRouter.
• Faça as cascatas de desconexão seguirem identidades de conexão pai-filho registradas, não strings de host correspondentes.
• Mantenha identificadores de tarefa ou transmissores de cancelamento no objeto cujo tempo de vida define o trabalho.
• Prefira atualizações da UI orientadas a eventos em vez de sondar o estado do terminal.

Caminhos de compatibilidade

Alternativas de compatibilidade são permitidas apenas quando são explícitas, limitadas e relatadas com precisão. Não devem ser descritas como uma implementação nativa de SFTP, encaminhamento ou sessão de nó. Registre o proprietário e o caminho de limpeza mesmo para alternativas temporárias.

Exemplos

Incorreto:

// Fechar o painel acidentalmente destrói o único proprietário do nó compartilhado.
struct TerminalPane {
    ssh_transport: SshTransport,
}

Forma correta:

// O painel possui apenas seu registro de consumidor; o registro possui a atividade do transporte.
struct TerminalPane {
    connection_id: String,
    terminal_consumer: ConnectionConsumer,
}

Incorreto:

tokio::runtime::Runtime::new()?.spawn(run_forward_listener());
// O runtime é descartado quando o comando retorna.

Forma correta:

// O proprietário do encaminhamento retém tanto o cancelamento quanto os identificadores de conclusão.
struct ForwardingJob {
    shutdown_tx: Option<oneshot::Sender<()>>,
    worker: JoinHandle<()>,
}

Lista de verificação de revisão

1. Identifique o proprietário da conexão física.
2. Liste todos os consumidores de terminal, SFTP, encaminhamento, reconexão, integridade e nó filho.
3. Verifique que fechar um consumidor não fecha consumidores não relacionados.
4. Verifique que a desconexão explícita do nó para tarefas dependentes e transportes filhos.
5. Inspecione cada tarefa ou processo gerado em busca de um proprietário retido, sinal de cancelamento e caminho de limpeza.
6. Verifique que o estado da UI consome eventos do nó em vez de atividade derivada do terminal.
7. Declare precisamente qualquer alternativa de compatibilidade restante.

Verificação

• Feche o último terminal e prove que o nó permanece utilizável por outro consumidor registrado.
• Abra SFTP sem exigir um painel de terminal.
• Inicie encaminhamento local, remoto e dinâmico e verifique que os ouvintes sobrevivem ao fechamento do painel.
• Desconecte um nó pai e verifique que os nós filhos dependentes e as tarefas transicionam de forma consistente.
• Reconecte dentro do período de carência sem perder estado não relacionado da UI.
• Confirme que a limpeza de tarefa/processo é concluída após desconexão explícita e desligamento da aplicação.