instalacao-manifesto.php library

Path in the Gestor bibliotecas/instalacao-manifesto.php

Per-layer installation manifest (req-198). The core can be "cannibalized": a project or plugin may override any core file and still receive updates. Every delivery records what it delivered in installation/manifests/<layer>.json (path and sha256). Precedence is projeto > plugin:<id> > core.

instalacao_planejar() compares the package with the manifests and the disk and splits:

instalacao_aplicar() runs the plan. In copiar mode (API) it writes the files itself. In preparar mode (system update) it only removes the preserved files from the package, and the updater moves the staging. The first delivery of a layer writes everything and records the baseline.

Clashes. Clashes are stored as pending JSON in installation/choques/. instalacao_choques_gravar_pendentes() moves pending clashes into the atualizacoes_choques table after the database stage.

Snapshot and rollback (BATCH-203). instalacao_snapshot_criar() keeps only what the plan will change, and instalacao_snapshot_restaurar() brings files and manifests back.

The library is pure (no Gestor): it runs in the updater, also from staging, and in the API.

Usage

Manifests

• instalacao_manifesto_arquivo($base, $camada) gives the path of the layer manifest.

• instalacao_manifesto_ler() reads one manifest; instalacao_manifestos() reads all of them.

• instalacao_manifesto_gravar() writes atomically.

• instalacao_nivel($camada) gives the precedence: projeto 2, plugin:* 1, core 0.

File maps

• instalacao_recuperacao_caminho_valido($rel) rejects hidden, private, absolute, or traversing paths before inventory and extraction.

• instalacao_recuperacao_arquivo_seguro($base, $rel, $hash) checks containment, real destination, and hash before including a file in the ZIP.

• instalacao_recuperacao_inventario($base, $camadas, $caminhos, $estados) assigns each difference to its owning layer and filters the result; it skips symbolic links and private folders.

• instalacao_mapa($raiz, $ignorar) builds the path → sha256 map of a tree.

• instalacao_fora($rel) tells whether a path stays out of the manifest (protected folders and installation/).

• instalacao_rel() converts to a relative path with /.

• instalacao_caminho_base() normalizes the root.

• instalacao_hash_disco() gives the hash of the file on disk.

Plan and apply

• instalacao_planejar() and instalacao_aplicar(), described above.

• instalacao_diff($antes, $depois) builds the text diff kept with the clash; a binary or oversized file gets only a notice.

Clashes

• instalacao_choques_registrar() writes the pending JSON.

• instalacao_choques_gravar_pendentes($base, $inserir) inserts each clash through the given function and marks the file as recorded.

• instalacao_choque_pendente_filtro($linha, $escapar) builds the SQL filter of an identical clash still pending; the writer skips the row when it exists.

Snapshot

• instalacao_snapshot_criar() and instalacao_snapshot_restaurar(), described above.

• instalacao_snapshot_anotar() adds data to snapshot.json, for example the database dump.

• instalacao_snapshot_podar($raiz, $manter) keeps only the most recent ones.

Database and check (BATCH-204), shared by the system update and the API deploy:

• instalacao_snapshot_dir($base, $id) gives the snapshot folder (a numeric id becomes exec-<id>; characters outside [A-Za-z0-9_-] are dropped);

• instalacao_banco_dump($dir, $banco) and instalacao_banco_restaurar($dump, $banco) dump and restore with mysqldump/mysql; instalacao_banco_processo() runs the pipe with the password in MYSQL_PWD, and instalacao_shell_pipefail() uses bash with pipefail when available (Debian's /bin/sh is dash);

• instalacao_saude_log_offset($base) marks the log position before the delivery; instalacao_saude_verificar() looks for a new fatal and makes the HTTP request (DNS, then 127.0.0.1, no connection is a warning, waits for OPcache); instalacao_saude_http() makes one request.

Clash resolution (req-199 / BATCH-205). One engine for up and down, project and core:

• instalacao_choque_acoes($choque) gives the decisions valid for the reason: editado → overwrite, keep, merge; sobreposto → keep, merge (undoing the override belongs in the owner layer repository); retirado-editado → overwrite (accepts the removal) or keep;

• instalacao_choque_versoes($base, $choque) reads the live version and the new one (copy in backups/overrides/);

• instalacao_choque_resolver($base, $choque, $acao, $mesclado, $gravarRegras) applies it on disk. manter records a rule in installation/regras.json (instalacao_regras_ler() / instalacao_regras_gravar()): the next delivery with the disk as it was at the decision is born resolved (manter-regra). Overwrite and merge remove the rule. During recovery, copia_externa points at the downloaded copy and gravarRegras=false avoids recording deploy rules in the local repository;

• the planner creates no clash when the layer delivers the same content as the previous delivery: there is nothing new to decide.

Functions

instalacao_caminho_base(string $base): string

instalacao_manifesto_arquivo(string $base, string $camada): string

instalacao_nivel(string $camada): int

instalacao_manifesto_ler(string $base, string $camada): ?array

instalacao_manifestos(string $base): array

instalacao_manifesto_gravar(string $base, string $camada, array $arquivos, string $versao): bool

instalacao_rel(string $raiz, string $caminho): string

instalacao_fora(string $rel): bool

instalacao_recuperacao_caminho_valido(string $rel): bool

instalacao_recuperacao_arquivo_seguro(string $base, string $rel, string $hash): ?string

instalacao_recuperacao_inventario(string $base, array $camadas = [], array $caminhos = [], array $estados = []): array

instalacao_mapa(string $raiz, array $ignorar = []): array

instalacao_hash_disco(string $base, string $rel): ?string

instalacao_planejar(string $base, string $camada, array $pacote, bool $completo, ?array $manifestos = null, ?array $listaCompleta = null): array

instalacao_aplicar(string $base, string $pacoteRaiz, string $camada, array $plano, string $versao, string $modo = 'copiar'): array

instalacao_diff(string $antes, string $depois, string $rotulo = ''): ?string

instalacao_choques_registrar(string $base, string $origem, string $camada, string $versao, ?string $execucao, array $choques): ?string

instalacao_choque_pendente_filtro(array $linha, callable $escapar): string

instalacao_choques_gravar_pendentes(string $base, callable $inserir): int

instalacao_snapshot_criar(string $base, array $plano, string $dir, array $meta = []): array

instalacao_snapshot_anotar(string $dir, array $dados): void

instalacao_snapshot_restaurar(string $base, string $dir): array

instalacao_snapshot_podar(string $raiz, int $manter = 5): int

instalacao_snapshot_dir(string $base, string $id): ?string

instalacao_shell_pipefail(string $cmd): array

instalacao_banco_processo(string $cmd, array $banco): array

instalacao_banco_dump(string $dir, array $banco): array

instalacao_banco_restaurar(string $dump, array $banco): array

instalacao_saude_log_offset(string $base): int

instalacao_saude_verificar(string $base, int $offsetLog, string $dominio, array $opcoes = []): array

instalacao_saude_http(string $url, ?string $ip): int

instalacao_regras_ler(string $base): array

instalacao_regras_gravar(string $base, array $regras): bool

instalacao_choque_acoes(array $choque): array

instalacao_choque_versoes(string $base, array $choque): array

instalacao_choque_resolver(string $base, array $choque, string $acao, ?string $mesclado = null, bool $gravarRegras = true): array