cloud-path

CloudPath é uma plataforma de controle de IoT auto-hospedada que pode ser executada localmente ou implantada na rede pública. O objetivo é criar um plano de controle genérico para "conectar dispositivos, visualizar status e controle remoto", em vez de ser um software dedicado a uma placa de desenvolvimento específica. O projeto é open source sob a licença MIT e consiste principalmente em três partes: o serviço central de binário único cloudpath-server, o gateway cloudpath-edge que roda em cada computador ou site, e a ferramenta de linha de comando cloudpath responsável pelo plano de controle do Registry de plugins. Tecnicamente, o backend utiliza Go, o frontend é React, os artefatos de construção da WebUI são embutidos no servidor e o banco de dados utiliza o modo WAL do SQLite, permitindo a compilação cruzada para Linux ou arm64 sem a necessidade de CGO. Divisão de Autoridade O serviço central é a única autoridade para o estado desejado, inquilinos e auditoria, sendo responsável por RBAC, tokens, limitação de taxa (rate limiting), períodos de retenção, o estado desejado do diretório de plugins e instâncias em execução, bem como o envio de operações e a liquidação de recibos. O gateway é a única autoridade para o estado de observação, salvando o snapshot do último estado aplicado com sucesso, sendo responsável pela supervisão de dispositivos, reinicialização com backoff e buffer de eventos offline; ele continua operando após a perda de conexão e, ao reconectar, aplica apenas o snapshot final, sem reproduzir efeitos colaterais intermediários. A identidade do dispositivo é determinada pela tríade inquilino, gateway e dispositivo, e a chave de transmissão online é a combinação de edge_id e device_id. Em sessões de conta, o link em tempo real do gateway para o servidor e depois para o navegador utiliza WebSocket, enquanto o REST assume as consultas históricas e operações de gerenciamento. Sistema de Plugins O projeto distingue três tipos de plugins: Driver, que roda por padrão no lado do gateway, responsável pela descoberta de dispositivos, conexão, análise de protocolo, mapeamento de capacidades e ações do dispositivo; Application, que roda no lado do serviço central, responsável por objetos de negócio, vinculações, regras, tarefas e APIs de domínio; e Connector, planejado para rodar no gateway ou serviço central para notificações e saída de dados como MQTT e Webhook, estando atualmente em estado de objetivo. O núcleo não escreve código para nenhum hardware específico; um novo dispositivo equivale a um plugin Driver. Drivers de referência como stcb e diversos plugins de aplicação são publicados em repositórios independentes, fornecendo modelos de plugins Go, aplicações de exemplo e scaffolds de testes E2E do binário ao host. Antes da instalação de um plugin, o Manifest, o escopo de compatibilidade, os ativos de Release e o resumo (checksum) são validados, e a versão, o digest e a origem são registrados em um arquivo de lock. Início Rápido Após instalar Go, Node, pnpm e opcionalmente task, utiliza-se task setup para baixar dependências e task build para gerar os dois binários. O server inicia ouvindo por padrão em 127.0.0.1:8080 e fornece /healthz para verificação de saúde. Sem hardware, é possível usar o adaptador demo integrado para validar a conexão de dispositivos, execução de operações e reconexão; para dispositivos seriais reais, instala-se e ativa-se o plugin Driver correspondente, habilitando o plugin_host no edge.yaml local e preenchendo a porta serial e o adaptador. Após a instalação da conta de administrador, o serviço entra imediatamente no modo de conta, exigindo credenciais para tudo, exceto verificação de saúde, recursos estáticos e interfaces de autenticação. Console de Gerenciamento Após o login, é possível acessar a visão geral, lista e detalhes de dispositivos, registros de execução (eventos), aplicações e plugins com detalhes de instâncias, lista e detalhes de gateways, e configurações; administradores possuem páginas adicionais de membros, permissões e tokens de acesso. O painel de operações na página de detalhes do dispositivo gera botões com base na whitelist declarada pelo adaptador; também é possível enviar comandos via API e consultar o fluxo de eventos e o status online do gateway. Os status de operação são pending, sent, ok, failed e timeout; operações sem recibo por longo tempo são marcadas como timeout por uma tarefa de limpeza em segundo plano, e eventos e operações finais são retidos por 30 dias por padrão. Design de Segurança O README divide a superfície de exposição em três níveis: L0 (máquina única), L1 (rede interna ou proxy reverso) e L2 (rede pública), alertando para não colocar configurações L0 diretamente na rede pública. Existem dois modos de credenciais: tokens de serviço compartilhados para caminhos de compatibilidade, e o modo de conta que oferece login via cookie de sessão, três níveis de funções (admin, operator e viewer), e tokens de inquilino com prefixo cp_, cujos escopos são subconjuntos de read, write, admin e edge. O texto simples é retornado apenas uma vez na resposta de criação; no banco de dados, são armazenados apenas o SHA-256 e um prefixo curto. Secrets aparecem nas configurações do servidor e auditorias na forma de handles secret://name, sendo resolvidos em texto simples apenas localmente no gateway de destino por um provider; plugins devem declarar permissões explicitamente no manifest, e o servidor não armazena nem encaminha texto simples. Além disso, há whitelists de operações, limites de comprimento e caracteres de parâmetros, limites de corpo de requisição, limites de leitura de WebSocket, proteção contra path traversal de SPA, limitação de taxa para operações e login, e um conjunto de cabeçalhos de resposta de segurança. Implantação e Acesso Multi-Gateway O guia oficial fornece passos de implantação pública sem dependência de containers: primeiro, faz-se a asserção de arquitetura dos artefatos (a matriz de publicação inclui Linux arm64), depois utiliza-se unidades systemd para rodar o serviço com uma conta não-root dedicada, segredos em arquivos de ambiente com permissão 0600 e, finalmente, nginx como proxy reverso para HTTPS e WSS, configurando cabeçalhos de upgrade e timeouts de leitura longos para WebSocket; a autenticação é responsabilidade do produto, mantendo a camada de proxy aberta. Formatos de container e Compose também são utilizáveis, desde que a arquitetura do host coincida com a da imagem. Conectar vários computadores a um único servidor é o uso comum: o administrador cria tokens de inquilino com escopo edge para cada computador, fornecendo o endpoint WSS, o token e o edge_id acordado; o usuário baixa o binário da plataforma correspondente, valida via checksums, preenche a configuração local e executa. O gateway possui reconexão com backoff exponencial, e eventos offline entram em um buffer limitado e são reproduzidos após a reconexão. Dispositivos, eventos, operações e instâncias de diferentes inquilinos são invisíveis entre si, e a queda de um gateway não afeta outro. Testes e Publicação Os testes abrangem testes unitários Go, detecção de race conditions, congelamento de instalação e verificação de tipos no frontend, fluxo de modelos de plugins e comandos de gate agregados; a publicação é disparada por tags de versão, realizando a construção em matriz de seis plataformas e gerando um arquivo de checksums unificado. O repositório também fornece scripts de gate para auditoria de fronteira pública, verificação de links Markdown e verificação de estrutura de workflow. Fronteiras Atuais O README distingue claramente o estado atual do estado objetivo: Connector e runtime de notificações, acesso MQTT e Modbus, OTA remoto, agregação de séries temporais, gerenciamento central de chaves, cotas distribuídas e multi-Server ainda não foram implementados; sessões de tokens de inquilino existem apenas para REST, sem canal em tempo real no navegador; a operação de um único driver externo controlando múltiplas placas reais, cobrindo hot-plug e recibos de operação em campo (E2E), também não foi concluída, portanto, links de múltiplas placas não são considerados validados até que a evidência de protocolo e hardware seja completada. O princípio do projeto é: "capacidades não implementadas não são escritas como estado atual".