Capítulo 38 — Implementação do projeto final
Mapa da aula
Aula 38 publicada. Mapa, exemplo, EX112.
flowchart TD
N0["38.1 Construção"]
N1["38.2 Falhar fechado"]
N2["38.3 Testes"]
N3["38.4 Docs"]
N4["38.5 Congelamento"]
N5["38.6 Passagem"]
N6["38.7 Fixtures douradas difíceis"]
N7["38.8 Flag de correspondência fuzzy"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Exemplo resolvido"]
EX --> Q["Exercício EX112"]
Desenho lógico
flowchart LR
N0["38.1 Construção"]
N1["38.2 Falhar fechado"]
N2["38.3 Testes"]
N3["38.4 Docs"]
N4["38.5 Congelamento"]
N5["38.6 Passagem"]
N6["38.7 Fixtures douradas difíceis"]
N7["38.8 Flag de correspondência fuzzy"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX112"]
[38.1 Construção]
|
v
[38.2 Falhar fechado]
|
v
[38.3 Testes]
|
v
[38.4 Docs]
|
v
[38.5 Congelamento]
|
v
[38.6 Passagem]
|
v
[38.7 Fixtures douradas difíceis]
|
v
[38.8 Flag de correspondência fuzzy]
|
v
[Exemplo resolvido] --> [Exercício EX112]
Objetivos de aprendizagem
Você vai (1) implementar o diff de inventário; (2) falhar fechado; (3) entregar testes, docs e passagem.
38.1 Construção
Fazer o diff de dois inventários sintéticos; sinalizar only-in-docs / only-on-network / conflito de tipo. A implementação faz o diff de dois inventários sintéticos e sinaliza hosts só nos documentos, só na rede, ou presentes nos dois com tipos conflitantes. Sam mantém a lógica do diff pequena o bastante para testar. Relatórios vistosos sem classes de conflito falham na avaliação. A ferramenta imprime ids de ativos, não apelidos. Construção aqui significa propriedades, e não um dashboard. Operadores deveriam terminar uma execução sabendo o que investigar a seguir.
38.2 Falhar fechado
YAML corrompido → negar com motivo. YAML corrompido precisa negar com uma string de motivo na qual um humano consiga agir. Devolver uma lista vazia de allow na falha de parse é tratado como um bug crítico. O teste de propriedade de Sam procura esse caminho vazio de propósito. Motivos citam o caminho do arquivo e a classe do erro de parse. Falhar fechado é a primeira demonstração em todo checkpoint. Uma negação educada é melhor engenharia do que um silêncio educado. Os testes de propriedade de Sam invertem bits até a negação disparar em cada mutação, e motivos citam o caminho do arquivo e a classe do erro de parse.
38.3 Testes
Fixtures douradas; sem rede. Os testes usam fixtures douradas e nunca tocam a rede. As fixtures incluem inventários felizes, quase-correspondências, arquivos truncados e encodings errados. Sam nomeia as fixtures corrompidas de forma que os testes de propriedade as encontrem. Testes que precisam de rede falham na CI de propósito. Fixtures douradas tornam as regressões óbvias. Avaliação sem rede mantém o projeto final alinhado com a disciplina do laboratório. Sam nomeia as fixtures corrompidas com o prefixo corrupt- para que a CI as descubra, e testes que precisam de rede falham na CI de propósito.
38.4 Docs
README do operador com exemplos. O README do operador mostra exemplos que se pode copiar e colar para os casos comuns de conflito. Sam escreve o README como se o leitor nunca tivesse visto seus aliases de shell. Exemplos incluem a negação em arquivo corrompido e o caminho de reconhecimento fuzzy. Documentação que só funciona na cabeça de Sam falha no dia do operador. Exemplos são testes para humanos. Um README que um estranho consegue executar é parte da nota. Os exemplos incluem o caminho de negação para que os operadores pratiquem a falha, e um README que um estranho consegue executar é parte da nota.
38.5 Congelamento
Congelamento de recursos antes da semana de avaliação. Congelar a construção também mantém as derivas plantadas e os casos de falhar fechado medindo o mesmo código que o orientador aprovou na nota de pré-registro. Sam estaciona ideias na versão dois. Congelamentos quebrados invalidam as métricas. A semana de avaliação não é para recursos heroicos de última hora. Congelar é como a honestidade da avaliação sobrevive ao entusiasmo. Ideias estacionadas ainda podem ser boas; só não são desta nota. Sam estaciona ideias numa lista da v2 em vez de mesclar cromado, e congelamentos quebrados invalidam as métricas da semana de avaliação.
38.6 Passagem
Acompanhar um operador executando sozinho. Passagem significa acompanhar um operador que executa a ferramenta sozinho numa conta nova. Sam pode responder perguntas, mas não pode digitar. Se o operador precisar do histórico do shell de Sam, o README falhou. A passagem é cronometrada e anotada. Sucesso sem as mãos é o critério. Uma ferramenta que só o autor consegue operar ainda não foi entregue. Se o operador precisar do histórico do shell cheio de aliases de Sam, a documentação falhou, e sucesso sem as mãos é o critério da passagem.
38.7 Fixtures douradas difíceis
As fixtures douradas incluem um escopo deliberadamente corrompido e um inventário de quase-correspondência que não deve ser mesclado por padrão. Mesclas prestativas são como hosts distintos viram um registro confuso. A fixture de quase-correspondência existe para punir a fuzzy padrão. Os testes de Sam falham se os conflitos desaparecerem sem um reconhecimento. Padrões que mesclam em silêncio são bugs de produto. Fixtures que parecem chatas pegam falhas caras. Quase-correspondências são onde inventários mentem com educação. Os testes de Sam falham se os conflitos desaparecerem sem --ack-fuzzy, e escopo corrompido precisa negar em vez de ser "consertado" em silêncio.
38.8 Flag de correspondência fuzzy
Nomes de inventário quase correspondentes exigem --ack-fuzzy para mesclar. O padrão é listá-los como conflitos. A flag força uma escolha intencional antes de os inventários colapsarem. A listagem padrão de conflitos impede que gêmeos de homologação e de produção se mesclem em silêncio. Sam registra os reconhecimentos fuzzy no log de auditoria. Conveniência que esconde risco não é conveniência. O padrão protege operadores cansados de si mesmos. Mesclar continua possível; só deixa de ser o caminho de menor resistência. Sam registra o uso da flag com o nome de usuário para perguntas posteriores de auditoria, e mesclar continua possível sem ser o caminho de menor resistência.
38.9 Nomes das fixtures corrompidas
Fixtures nomeadas corrupt-*.yaml precisam negar. Um teste de propriedade na CI gera corrupção aleatória além das fixtures nomeadas. Convenções de nomenclatura permitem que os testes de propriedade descubram fixtures sem um manifesto frágil. A corrupção aleatória cresce a cada período conforme os parsers endurecem. Sam exige que cada mutação nova tenha nome e intenção. Fixtures sem o padrão de nome são invisíveis para a propriedade. Descoberta por convenção escala melhor do que listas feitas à mão. Parsers endurecem quando a corrupção se recusa a ficar previsível.
38.10 Teste de propriedade com bit-flip
O teste de propriedade de corrupção aleatória inverte bits no YAML até a negação disparar. Sam assiste para o caminho vazio de allow nunca voltar. O caminho vazio de allow teria parecido um escopo vazio limpo na produção. Grosseria nos testes é bem-vinda quando a alternativa é cegueira educada. Sam acrescentou o teste depois de um quase incidente em homologação. Bit-flips encontram classes de bugs que fixtures felizes perdem. Propriedades que caçam o silêncio protegem falhar fechado. Uma suite educada demais deixa passar o pior bug.
38.11 Fixtures de truncamento e encoding
As fixtures corrompidas incluem arquivos truncados e encodings errados. A negação precisa disparar nos dois. Truncamento no meio do documento e encodings surpresa são comuns em exportações reais. A negação não pode depender de um único estilo de corrupção. A mutação nova de cada período é registrada com nome. Sam se recusa a tratar UTF-16 inesperado como um caminho feliz. Robustez significa negar estranheza sem travar. Exportações do mundo real não respeitam os exemplos do tutorial. A mutação nova de cada período é registrada com uma intenção de uma linha para legibilidade na CI, e Sam se recusa a tratar UTF-16 inesperado como caminho feliz.
38.12 Mutações nomeadas
Cada mutação nova no teste de propriedade ganha um nome e uma intenção de uma linha. Nomes como trunc-mid-yaml tornam as falhas legíveis nos logs da CI. Linhas de intenção impedem que estudantes futuros apaguem uma mutação que não entendem. Sam revisa os nomes nos checkpoints. Mutações anônimas viram dívida. Clareza nos testes é parte da clareza do produto. Uma falha que nomeia a mutação ensina o conserto. Sam revisa os nomes quanto à clareza do mesmo jeito que revisa achados, e uma falha que nomeia a mutação ensina o conserto na semana de avaliação.
38.13 Nomes legíveis de mutação
Os nomes das mutações parecem "trunc-mid-yaml", para que as falhas se leiam com clareza na CI. Hashes opacos como ids de mutação desperdiçam minutos na semana de avaliação. O guia de estilo de testes de Sam proíbe nomes engraçados que escondem a intenção. Nomes claros também ajudam os orientadores a auditar a cobertura. Legibilidade é uma propriedade de controle para humanos. Testes que explicam a si mesmos sobrevivem às trocas de turma. Avaliação anda mais rápido quando os logs já contam a história.
38.14 Dia do operador com conta nova
O dia do operador usa uma conta nova, sem aliases de Sam no histórico do shell. Se o operador precisar dos aliases, o README falhou. Shells tribais compartilhados mentem sobre a prontidão. Contas novas retiram o conforto de docs incompletos. Sam observa sem digitar e toma notas para consertos no README. Aliases são dívida disfarçada de velocidade. Passagem que depende da memória muscular do autor não é passagem. O dia do operador é onde a documentação encontra a verdade. Aliases que voltam pelos dotfiles são tratados como falhas da passagem, e contas novas retiram o conforto de documentação incompleta de propósito.
38.15 Reconhecimento digitado da mescla
Reconhecimentos de correspondência fuzzy exigem digitar a frase "I accept merge risk" exatamente. Diálogos de um clique treinam a cegueira; frases digitadas criam uma pausa. Copiar e colar da wiki ainda força os olhos a passar pelas palavras. Os logs de auditoria guardam quem digitou a frase. Sam quer atrito antes de inventários colapsarem. Uma frase que as pessoas precisam digitar é um controle, não um ornamento. Atrito no momento certo evita recalls caros depois. Os logs de auditoria guardam quem digitou a frase e quando, e remover a frase por conveniência é tratado como um defeito de produto.
38.16 Log de auditoria do reconhecimento
A frase de reconhecimento digitada é registrada no log de auditoria com o nome de usuário. Os logs apoiam perguntas posteriores quando uma mescla ruim é descoberta. Os nomes de usuário vêm do contexto autenticado do operador, e não de uma caixa de texto livre. Os runbooks de Sam ensinam a consultar o log antes de culpar a ferramenta. Auditoria sem identidade é teatro. Registros que nomeiam a pessoa tornam o risco aceito real. Mesclas ruins merecem uma trilha, não uma lenda.
Exemplo resolvido (TRB sintético)
A ferramenta de Sam sinaliza only-in-docs, only-on-network e type-conflict, e nega YAML corrompido com motivo.
Caso sintético — Riverstone Transit Bank (TRB). O banco, Sam Ito, TrackScope/FindingsDesk/PulseMap e todos os números são inventados para fins didáticos.
Erros e limites
Este livro não concede nenhuma autoridade para testar bancos ou sistemas de pagamento reais. Os laboratórios usam apenas endereços de faixas de documentação e dados sintéticos; código de exploit nunca é fornecido.
Exercícios
- EX112 — Flags. Quais classes o diff sinaliza? Rubrica: 3 = only-in-docs, only-on-network e type-conflict (e match); 2 = parcial; 1 = uma; 0 = nada.
- EX113 — Falhar fechado. O que acontece com YAML corrompido? Rubrica: 3 = falhar fechado com motivo claro e código de saída diferente de zero; 2 = parcial; 1 = lista vazia de allow; 0 = nada.
- EX114 — Rede. A ferramenta pode exigir rede? Rubrica: 3 = não; precisa rodar offline em arquivos locais; 2 = não, sem justificativa; 1 = sim; 0 = nada.
Síntese
A implementação entrega propriedades de controle, fixtures douradas e uma passagem sem as mãos do autor.
Continue estudando — capítulo 38 de 40
← Capítulo 37 (rascunho) · Índice de capítulos do curso · Capítulo 39 (rascunho) →