Gerenciamento de Dependências

O Wippy resolve dependências de módulos a partir das declarações no código-fonte e registra versões exatas em wippy.lock. Os módulos publicados são baixados do Hub para o diretório de módulos do projeto.

Os nomes de módulos acme/*, versões, hashes e caminhos locais abaixo são ilustrativos. Substitua-os por módulos e digests verificados do seu projeto ou do Hub.

Arquivos do Projeto

wippy.lock

O arquivo de lock rastreia a estrutura de diretorios do seu projeto e dependencias fixadas:

directories:
  modules: .wippy
  src: ./src
modules:
  - name: acme/http
    version: v1.2.0
    hash: 4ea816fe84ca58a1f0869e5ca6afa93d6ddd72fa09e1162d9e600a7fbf39f0a2
  - name: acme/sql
    version: v2.0.1
    hash: b3f9c8e12a456d7890abcdef1234567890abcdef1234567890abcdef12345678

wippy.yaml

Metadados do modulo para publicacao. Necessario apenas quando voce publica seu proprio modulo:

organization: acme
module: http
version: 1.2.0
description: HTTP utilities for Wippy
license: MIT
repository: https://github.com/acme/wippy-http
keywords:
  - http
  - web

Declarando Dependencias

Adicione entradas ns.dependency no seu _index.yaml:

version: "1.0"
namespace: app
entries:
  - name: dependency.http
    kind: ns.dependency
    component: acme/http
    version: "^1.0.0"

  - name: dependency.sql
    kind: ns.dependency
    component: acme/sql
    version: ">=2.0.0"

Restricoes de Versao

Regras de Resolucao

• Cada modulo resolve contra a intersecao de todas as faixas declaradas no grafo de dependencias. Faixas incompativeis (conflitos de diamante) falham a resolucao com um erro explicito em vez de escolher silenciosamente um dos lados.
• Um wippy update completo resolve cada modulo a partir de suas faixas declaradas; uma atualizacao direcionada e o reparo no boot mantem uma versao fixada que ainda satisfaz todas as faixas vigentes.
• Parametros raiz vencem os transitivos: quando sua aplicacao e uma dependencia vinculam o mesmo requirement, os parametros do seu ns.dependency tem precedencia. Faixas de versao nunca sao sobrescritas; toda declaracao entra na intersecao.
• Um componente declarado por varias entradas ns.dependency raiz e controlado por uma delas — declaracoes estabelecidas antes das novas, portadoras de parametros antes das simples, empates pelo menor ID de entrada — e as demais viram referencias a ela. Uma duplicata cujos parametros divergem da declaracao controladora e rejeitada com um erro de conflito; atualize a dependencia existente em vez disso.

Duas falhas de resolucao sao reportadas de forma distinta. Uma expressao de restricao que nunca podera ser satisfeita por nenhum release — a intersecao das faixas vigentes e vazia — e um conflito, e o erro nomeia o modulo e todo solicitante que contribuiu com uma faixa. Um conjunto de faixas valido para o qual o hub atualmente nao publica nenhuma versao correspondente e, em vez disso, uma falha de disponibilidade: um release posterior pode torna-lo resolvivel sem nenhuma mudanca nas declaracoes.

O runtime persiste cada grafo resolvido no historico do seu registro e o reproduz no boot em vez de resolver de novo, entao uma aplicacao implantada inicia exatamente com as versoes que foram resolvidas quando a mudanca de dependencia foi aplicada. O wippy.lock continua sendo o snapshot portavel para projetos de codigo-fonte.

Proveniencia de entradas

A proveniencia pertence ao registry, nao aos metadados da entrada. Quando as entradas sao carregadas, o registry marca cada uma com a fonte de deployment que a forneceu:

Autores de entradas nunca escrevem esses campos; eles sao atribuidos durante o carregamento e nao podem ser forjados a partir de um _index.yaml. Inspecione-os com wippy registry list --registry-meta --json.

Fluxo de Trabalho

Iniciando um Novo Projeto

wippy init

Cria um wippy.lock com diretorios padrao.

Adicionando Dependencias

wippy add acme/http               # Latest version
wippy add acme/http@1.2.3         # Exact version
wippy add acme/http@latest         # Latest label

Isso atualiza o arquivo de lock. Em seguida, instale:

wippy install

Resolvendo a Partir do Codigo-Fonte

Se seu codigo-fonte ja declara entradas ns.dependency:

wippy update

Isso escaneia seu diretorio de codigo-fonte, resolve todas as restricoes de dependencias, atualiza o arquivo de lock e instala os modulos.

Atualizando Dependencias

wippy update                       # Re-resolve all dependencies
wippy update acme/http             # Update only acme/http
wippy update acme/http acme/sql    # Update specific modules

Ao atualizar modulos especificos, os demais modulos permanecem fixados em suas versoes atuais. Se a atualizacao exigir alteracao de modulos que nao sao alvo, uma confirmacao e solicitada.

Instalando a Partir do Arquivo de Lock

wippy install                      # Install all from lock
wippy install --refresh            # Re-fetch every module (--force and --repair are aliases)

Armazenamento de Modulos

Os modulos baixados sao armazenados no diretorio .wippy/vendor/:

project/
  wippy.lock
  src/
    _index.yaml
  .wippy/
    vendor/
      acme/
        http-v1.2.0.wapp
        sql-v2.0.1.wapp

Por padrao, os modulos sao mantidos como arquivos .wapp. Para extrai-los em diretorios:

# wippy.lock
options:
  unpack_modules: true

Com a extracao habilitada:

.wippy/
  vendor/
    acme/
      http-v1.2.0.wapp
      http/
        wippy.yaml
        src/
          _index.yaml
          ...

A extracao nunca descarta o pack. O .wapp canonico verificado permanece ao lado do diretorio extraido porque e a unica evidencia enderecada por conteudo do modulo, e a materializacao de artefatos e o reparo leem recursos de volta a partir dele. O .wapp e o que a instalacao verifica: um diretorio cujo pack esta ausente conta como nao instalado, e o modulo e baixado novamente. Cada instalacao extrai o diretorio de novo a partir do arquivo verificado, entao edicoes manuais em um diretorio vendorizado nao sobrevivem.

Modulos resolvidos a partir de uma substituicao de workspace nunca sao baixados nem vendorizados; eles carregam a partir do caminho local.

Desenvolvimento Local com Substituicoes

Substitua modulos do hub por diretorios locais para desenvolvimento. Substituicoes sao declaradas na secao workspace de um arquivo de configuracao do runtime — tipicamente um arquivo privado, ignorado pelo git, composto sobre .wippy.yaml:

# .wippy.workspace.yaml
version: "1.0"
workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: ../local-sql

wippy run --config .wippy.yaml --config .wippy.workspace.yaml

As chaves sao org/module, os valores sao diretorios (caminhos relativos resolvem contra o diretorio do primeiro arquivo --config). Definir uma substituicao como null desativa uma herdada de uma camada de configuracao ou profile anterior. Substituicoes tambem podem viver dentro de um profile para ativarem apenas com --profile workspace.

O caminho e obrigado a existir, e a ser um diretorio, apenas para um modulo que o grafo do lock realmente seleciona. Uma substituicao declarada para um modulo do qual nada depende e uma entrada de resolucao, nao uma entrada de boot: ela pode apontar para um diretorio que nao esta presente nesta maquina sem falhar a validacao.

Uma substituicao muda de onde vem o codigo-fonte de um modulo, nao qual release foi escolhido. O caminho de carga mantem a versao que o lock selecionou para aquele modulo e e marcado como uma substituicao; entradas carregadas dele sombreiam as vendorizadas com o mesmo ID. A reconciliacao captura a arvore local atual e registra seu digest e tamanho como identidade da substituicao. Quando uma substituicao e declarada para um modulo para o qual o lock nao fixa uma versao, a resolucao pede ao hub uma versao de release, e ate que uma evidencia mais forte selecione uma, ela mantem uma versao zero apenas local.

Substituicoes de workspace afetam o grafo de carga no boot e nunca sao gravadas no wippy.lock. Mudancas no codigo-fonte local sao reconciliadas diretamente, sem contatar o hub. Os globs exclude: do wippy.yaml do modulo aplicam-se tambem a diretorios de substituicao, tanto ao carregar entradas quanto ao calcular o hash do conteudo.

Uma secao replacements: no wippy.lock esta obsoleta: ela ainda carrega, mas imprime um aviso. Mova essas entradas para workspace.replacements em um arquivo de configuracao.

Ordem de Carregamento

Na inicializacao, o Wippy carrega entradas dos diretorios nesta ordem:

1. Diretorio de codigo-fonte (src)
2. Diretorios de substituicao
3. Diretorios de modulos vendorizados

Modulos com substituicoes ativas ignoram seu caminho de vendor.

Verificacao de Integridade

Todo modulo no arquivo de lock carrega um digest de artefato. O boot se recusa a carregar um modulo cuja entrada no lock nao tem nenhum; wippy install aceita tal entrada e registra o digest que o hub serve com o download.

No boot, os downloads sao preparados em etapas: o pack e escrito em um arquivo temporario ao lado de seu local final, verificado contra o digest fixado no wippy.lock e contra o digest que o hub serviu com a URL de download (mais o tamanho servido), e so entao renomeado para o lugar. Um arquivo preparado que falha na verificacao e apagado. wippy install renomeia o download para seu caminho de vendor antes de verifica-lo, confere-o apenas contra o digest e o tamanho servidos, apaga-o em caso de falha, e substitui um digest do lock que difere do servido em vez de impo-lo.

Uma divergencia de digest e uma falha dura e nao retentavel. No boot ela e PermissionDenied, "module integrity verification failed", levantada para um download novo e para um pack ja vendorizado, que e reverificado contra o digest do lock antes de as entradas serem carregadas. wippy install a reporta como Internal: "failed to store module" envolvendo "verify cached WAPP: digest mismatch" para um pack ja presente no diretorio de vendor, e "failed to download module" envolvendo "verify downloaded WAPP: digest mismatch" para um download novo. Nada tenta de novo, rebaixa por cima da divergencia, nem recorre ao conteudo servido.

A mesma verificacao protege a resolucao. Quando o hub serve um manifesto cujo digest difere daquele fixado no lock, o cache de manifestos e atualizado uma vez e recomparado; se ainda divergir, a resolucao falha nomeando ambos os digests.

Diretorios extraidos carregam seu proprio digest, tamanho e digest de arvore registrados, e sao reverificados contra os valores registrados, entao uma arvore vendorizada modificada e detectada em vez de carregada.

Cada tentativa de reconciliacao captura a arvore local e verifica o mesmo digest e tamanho antes de carrega-la. Uma mudanca concorrente faz a validacao falhar em vez de misturar geracoes da fonte. Em reinicializacoes, artefatos historicos imutaveis sao pre-buscados separadamente e substituicoes locais historicas sao reconciliadas com as declaracoes finais; uma substituicao removida nao precisa manter o diretorio antigo, mas uma ainda selecionada deve existir e ser valida.

Artefatos de Build

Um modulo pode entregar um recurso de sistema de arquivos marcado com meta.artifact.format que os consumidores materializam em disco em vez de ler em tempo de execucao. wippy install e wippy update completos e direcionados, o cold boot e as operacoes de dependencia em tempo de execucao reconciliam essas saidas como parte da mesma transacao que altera o grafo de modulos; artifact.materialization_root define a raiz de saida. Veja Artefatos de build.

Veja Tambem

• Artefatos de build - Declarando, materializando e reconciliando recursos de artefato
• Construindo Componentes - O lado do autor: ns.requirement e fornecimento de valores via parameters
• CLI - Referencia de comandos
• Publicacao - Publicando modulos no hub
• Estrutura do Projeto - Layout do projeto