Adicione módulos a um servidor Go sem enfraquecer a segurança

## Mantenha padrões seguros e decida onde cada nova funcionalidade deve ficar Trate os padrões seguros como o principal requisito de produto para uma plataforma de servidor voltada para a Internet. Projete as funcionalidades como módulos combináveis, em vez de acoplá-las fortemente ao núcleo. Prefira extensões gerais que atendam a uma classe de casos de uso, em vez de correções para uma única implantação. Identifique se uma alteração pertence a um aplicativo de nível superior, a um módulo reutilizável, à adaptação de configuração ou ao ponto de entrada da linha de comando. Mantenha os identificadores de módulos em espaços de nomes para que componentes desenvolvidos de forma independente não colidam. Preserve um modelo nativo de configuração estruturada mesmo quando houver adaptadores fáceis de usar. Revise com atenção especial o tratamento de solicitações, a segurança de transporte, a identidade, o gerenciamento de certificados e os limites de confiança. Rastreie comportamentos sensíveis à segurança entre repositórios ou pacotes relacionados quando a responsabilidade estiver distribuída. Não considere uma alteração crítica para a segurança pronta para mesclagem até compreender os limites de confiança e os modos de falha afetados. Mantenha explícito o registro de módulos padrão para que os componentes distribuídos possam ser descobertos e auditados. Garanta que os binários de comando importem o conjunto de módulos pretendido, em vez de depender de um registro acidental. Documente a localização arquitetural quando uma nova funcionalidade puder residir razoavelmente em mais de uma camada. Rejeite projetos que enfraqueçam os padrões seguros apenas para reduzir o esforço de implementação. Considere a compatibilidade entre todos os sistemas operacionais compatíveis desde a primeira decisão de projeto. ## Siga o estilo comum de Go em erros, nomes e comentários Use retornos antecipados para erros e mantenha o caminho de sucesso no menor nível de recuo. Evite ramificações else depois de uma ramificação que já retorna. Escreva siglas comuns na forma convencional em maiúsculas, incluindo URL, HTTP e ID. Escolha nomes curtos de receptores que reflitam de forma consistente o tipo do receptor. Comece as mensagens de erro com texto em minúsculas e omita a pontuação final. Escreva a documentação exportada como frases completas que comecem pelo nome declarado. Use uma fatia nil quando uma fatia vazia alocada não tiver valor semântico. Retorne erros para falhas esperadas, em vez de acionar panic. Mantenha o tratamento de erros próximo da operação que pode falhar. Encapsule erros somente quando o contexto adicional ajudar a localizar a operação que falhou. Preserve os erros em um formato que os chamadores possam inspecionar quando houver tratamento programático. Evite fluxos de controle engenhosos que ocultem a responsabilidade ou a limpeza dos recursos. Execute a formatação e a análise estática antes da revisão. Aplique as convenções estabelecidas do repositório mesmo quando houver outro estilo de Go válido. Use asserções de interface em tempo de compilação para tipos que devam satisfazer interfaces do framework. Mantenha estáveis os nomes de receptores, pacotes e itens exportados, a menos que uma alteração deliberada de compatibilidade seja aprovada. ## Construa cada módulo em ordem, da criação à limpeza Registre cada módulo pelo mecanismo de registro padrão do framework. Retorne metadados que contenham um ID de módulo com espaço de nomes e um construtor para uma nova instância. Mantenha os construtores livres de efeitos colaterais específicos do ambiente. Trate o ciclo de vida como fases ordenadas: 1. Construa um novo valor. 2. Decodifique a configuração nele. 3. Provisione as dependências de tempo de execução. 4. Valide a configuração completa. 5. Sirva ou execute a função do módulo. 6. Limpe os recursos que ele possui. Não execute a validação final antes que os dados de configuração e provisionamento estejam disponíveis. Torne a limpeza segura após um provisionamento parcial e sinais de desligamento repetidos quando o framework puder chamá-la dessa forma. Use proteções em tempo de compilação para provisionamento, validação, análise de configuração e outras interfaces opcionais. Mantenha separadas as responsabilidades do ciclo de vida para que os erros de configuração possam ser diferenciados das falhas de tempo de execução. Retorne erros que permitam agir durante o provisionamento e a validação. Não oculte uma inicialização com falha atrás de um módulo parcialmente utilizável. Use interfaces de aplicativo de nível superior apenas para componentes que realmente sejam responsáveis pelo comportamento de início e parada. Mantenha os IDs dos módulos estáveis, pois a configuração, os adaptadores e as integrações externas podem depender deles. ## Leia os arquivos de configuração com rigor e proteja os endpoints administrativos Analise a configuração voltada para pessoas pelo dispensador de tokens do framework ou por um iterador estruturado equivalente. Consuma o nome da diretiva antes de ler os argumentos na mesma linha. Trate os argumentos na mesma linha separadamente dos blocos aninhados. Capture o nível atual de aninhamento e pare quando o analisador sair desse bloco. Reconheça explicitamente as subdiretivas compatíveis. Valide imediatamente os argumentos obrigatórios e retorne o erro de argumento padrão do analisador. Rejeite subdiretivas desconhecidas com um erro que inclua o valor inesperado. Documente a sintaxe aceita ao lado do analisador como um contrato mantido. Mantenha a saída do adaptador alinhada ao modelo nativo de configuração estruturada. Obtenha registradores e outros módulos pelo contexto do framework durante o provisionamento. Use um registrador estruturado com escopo de módulo e anexe campos, em vez de construir mensagens não estruturadas. Não armazene contextos de solicitação ou provisionamento em estruturas de longa duração. Implemente a interface de roteamento do framework ao adicionar endpoints administrativos. Aplique as regras de autenticação, autorização e exposição esperadas pela superfície administrativa. Valide a configuração antes que o módulo comece a tratar o tráfego. ## Evite novas dependências e mantenha claros os limites entre pacotes Evite novas dependências, a menos que seu valor supere claramente os custos de manutenção, segurança e cadeia de suprimentos. Incorpore diretamente funcionalidades pequenas e estáveis quando uma dependência mínima acrescentaria um risco desproporcional. Não exponha tipos de pacotes externos pela API pública do projeto. Encapsule comportamentos de terceiros atrás de interfaces e tipos pertencentes ao projeto. Use as ferramentas de módulos da linguagem para manter consistentes as declarações e as somas de verificação das dependências. Execute o comando de organização das dependências e revise seu diff, em vez de aceitar alterações não relacionadas. Mantenha os adaptadores de configuração separados dos módulos de tempo de execução. Mantenha os utilitários de teste separados dos pontos de entrada de produção. Coloque os módulos padrão no registro usado pelo comando distribuído. Não importe módulos opcionais para o binário padrão sem uma decisão explícita de produto. Preserve os limites dos pacotes em torno do tratamento de protocolos, da segurança de transporte e das operações com certificados. Escolha abstrações generalizadas somente depois de identificar o comportamento repetido ao qual elas atendem. Rejeite abstrações especulativas que ocultem uma implementação simples. Ao refatorar, preserve o comportamento observável ou documente e teste cada alteração intencional. Revise pacotes críticos para a segurança e alterações de dependências com mais profundidade do que o código interno rotineiro. ## Passe em todos os testes, no lint e na compilação antes da mesclagem Trate cada portão de qualidade obrigatório como bloqueador, não como recomendação. Execute a suíte completa no modo short com a detecção de condições de corrida habilitada. Execute o linter configurado com tempo suficiente para todo o repositório. Compile todos os pacotes para detectar interfaces ausentes, restrições de plataforma e erros de registro. Para alterações de desempenho, execute benchmarks com medições de memória. Compare os resultados dos benchmarks com uma referência adequada e considere a variação. Execute testes de integração focados no comportamento afetado do servidor. Garanta que os testes passem no Linux, macOS e Windows quando essas plataformas forem compatíveis com a integração contínua. Examine os avisos nos arquivos alterados mesmo que haja avisos não relacionados em outros locais. Não marque uma pull request como pronta para mesclagem enquanto faltar um portão obrigatório de teste, lint, compilação ou benchmark. Registre os comandos e os resultados relevantes para que os revisores possam reproduzir as evidências. Distinga uma falha de teste de uma falha de ambiente antes de alterar o código de produção. Mantenha a verificação proporcional à alteração, sem deixar de cobrir cada portão diretamente afetado. Execute novamente os portões afetados após qualquer alteração de código feita em resposta à revisão. Trate relatórios de condições de corrida e falhas intermitentes de concorrência como defeitos que exigem investigação. ## Escreva testes unitários orientados por tabelas e testes de servidor com portas próprias Prefira testes orientados por tabelas quando várias entradas compartilharem o mesmo comportamento. Forneça a cada caso uma entrada explícita, uma saída esperada e um estado de erro esperado. Verifique tanto a ausência dos erros esperados quanto os erros inesperados retornados. Compare os valores retornados somente depois de tratar adequadamente a condição de erro. Inclua casos válidos, inválidos, de limite e de regressão. Dê nomes aos casos quando apenas os índices dificultarem o diagnóstico das falhas. Mantenha os fixtures mínimos e determinísticos. Use a estrutura de testes de servidor do projeto para o comportamento de configuração de ponta a ponta. Inicialize os servidores de teste com configuração isolada e formatos explícitos. Use portas não padrão para evitar conflitos com serviços em execução local. Reserve portas separadas para administração, tráfego não criptografado e tráfego criptografado quando necessário. Verifique o status, o corpo e outros comportamentos observáveis externamente. Limpe servidores, listeners, arquivos e goroutines criados pelo teste. Não dependa da ordem dos testes nem de um estado global mutável compartilhado. Teste erros de análise de configuração, bem como a inicialização bem-sucedida do servidor. Adicione casos específicos da plataforma quando os caminhos, sockets, sinais ou comportamentos dos processos forem diferentes. Mantenha os testes de integração suficientemente focados para que uma falha identifique o contrato violado. ## Deixe pull requests, relatórios de segurança e contratos para uma pessoa Trate discussões de issues, pull requests, contratos de licença e relatórios de segurança como ações externas governadas por pessoas. Um assistente de IA não deve se passar por um colaborador humano nem aceitar um acordo legal em nome de uma pessoa. Não crie nem envie issues externas, pull requests ou relatórios de segurança, a menos que a política governante autorize explicitamente essa ação do agente. Mantenha a assistência à revisão dentro da função permitida e identifique a participação da IA quando necessário. Não oculte o envolvimento da IA quando a divulgação fizer parte da política de contribuição. Exija que o operador humano entenda e consiga explicar cada linha enviada. Teste o código assistido por IA com verificações automatizadas quando viável e, caso contrário, com verificações manuais completas. Revise o código gerado em busca de material copiado, licenças incompatíveis e alegações não verificadas. Não invente detalhes de vulnerabilidades nem envie um relatório de segurança não verificado. A assistência de tradução ou edição deve preservar os fatos de segurança verificados pelo autor humano. Deixe assinaturas, atestados e contratos de colaboradores exclusivos de pessoas a cargo do responsável. Quando uma ação solicitada entrar em conflito com a política de contribuição, interrompa essa ação e explique o limite governante. Não adicione arquivos, comentários ou commits enganosos como substitutos de uma ação externa proibida. Mantenha a utilidade técnica da correção sem contornar o processo da comunidade. Antes da aprovação, verifique divulgação, compreensão, testes e licenciamento como portões separados. A responsabilidade humana continua obrigatória mesmo quando um agente tiver produzido a maior parte da implementação.