Biblioteca modulo-distribuido.php

Caminho no Gestor bibliotecas/modulo-distribuido.php

Permite que um módulo tenha duas metades:

• central ("scope": "central-module" no <modulo>.json): roda na instalação central (a do fornecedor), onde ficam o código, os usuários e as permissões;

• distribuído ("scope": "distributed-module"): roda no site do cliente e guarda os dados no banco do cliente.

O código do módulo central continua usando banco_select(), banco_insert()… normalmente; dentro do canal distribuído, banco_query() empacota a SQL e a executa na instalação do cliente. O cliente vê o módulo como uma tela embutida (iframe) do central, liberada só depois de o central confirmar login e permissão.

Configuração

No .env (variáveis globais): MODULO_DISTRIBUIDO_SECRET (segredo HMAC compartilhado), MODULO_DISTRIBUIDO_CENTRAL_URL (no distribuído: a URL do central) e MODULO_DISTRIBUIDO_ENDPOINT (no central: a URL da API do distribuído). Por módulo, $_CONFIG['modulo-distribuido']['secrets'][<slug>] e ['endpoints'][<slug>] sobrepõem os valores gerais (modulo_distribuido_config_get('modulo-distribuido.secrets.<slug>')).

modulo_distribuido_scope($manifesto), modulo_distribuido_scope_central(), modulo_distribuido_scope_distribuido() e modulo_distribuido_resolver_manifesto() leem o escopo do manifesto (constantes C2F_SCOPE_CENTRAL e C2F_SCOPE_DISTRIBUIDO).

O canal de dados

// No módulo central, envolvendo só as operações de dados do cliente:
// o manifesto do módulo central declara "distributed": {"target-slug": "meu-modulo"}
$config = modulo_distribuido_canal_central($_GESTOR['modulo#'.$_GESTOR['modulo-id']]);
$pedidos = modulo_distribuido_com_canal(function () {
    return banco_select(['tabela' => 'pedidos', 'campos' => ['id', 'total']]);
}, $config);
// ou, à mão: banco_distribuido_iniciar($config); … banco_distribuido_finalizar();

1. banco_distribuido_ativo() faz banco_query() desviar para banco_distribuido_query().

2. modulo_distribuido_montar_payload() empacota a SQL (operacao, modulo, linguagem, timestamp, nonce), e modulo_distribuido_enviar() a manda por modulo_distribuido_http_post() para <endpoint>/modulo-distribuido/<slug>/db, com X-C2F-Signature = HMAC-SHA256 do corpo (modulo_distribuido_assinar()).

3. No distribuído, a API confere a assinatura (modulo_distribuido_verificar_assinatura(), tempo constante) e modulo_distribuido_executar_local() roda a SQL via PDO: SELECT devolve colunas e linhas; escrita devolve affected_rows e insert_id.

4. modulo_distribuido_resposta_para_resultado() converte a resposta num BancoResultadoRemoto, que imita o mysqli_result para as funções da banco.php.

Autenticação, variáveis e o resto da requisição continuam no banco local do central: só o que estiver dentro do canal vai para o cliente. modulo_distribuido_canal_central($manifesto, $overrides) monta a configuração do lado central a partir de distributed.target-slug (e, opcionalmente, endpoint-config/secret-config, caminhos de chaves em $_CONFIG) do manifesto; modulo_distribuido_canal_distribuido() faz o mesmo no distribuído, para falar com o central; modulo_distribuido_detectar_operacao() e modulo_distribuido_operacao_leitura() classificam a SQL; modulo_distribuido_parse_rota() lê {slug}/{acao} da URL.

Login, permissão e tela

O distribuído não decide acesso: pergunta ao central.

• O login é o do perfil-usuario do central: sem token, o host distribuído manda o navegador para /signin/ do central com um contexto assinado; depois do login completo (inclusive segundo fator) o gancho login.distribuido devolve um código de uso único, trocado entre servidores pelos tokens (ação exchange). modulo_distribuido_token_sessao() e modulo_distribuido_persistir_token() guardam e renovam os tokens na sessão. Não existe login por usuário e senha neste canal.

• modulo_distribuido_guardiao() (no distribuído) consulta o central, onde modulo_distribuido_middleware_central() valida o token e a permissão do usuário no módulo e responde nao-autenticado, sem-permissao ou autorizado. Qualquer falha resolve para o estado mais restritivo.

• modulo_distribuido_estado_renderizacao() traduz isso em login, sem-permissao ou iframe; modulo_distribuido_montar_url_iframe() monta a URL da tela do central.

• modulo_distribuido_app() faz tudo numa chamada: token, guardião e a tela do estado, trocando #modulo-distribuido-app# na página pelo componente modulo-distribuido-app (modulo_distribuido_render_estado(), modulo_distribuido_render_componente(), modulo_distribuido_textos()).

As variantes modulo_distribuido_estado_por_token_ativo(), modulo_distribuido_estado_por_permissao_central() e modulo_distribuido_middleware_permissao() são as peças puras (testáveis) desse fluxo.

Funções

modulo_distribuido_scope(array|string $modulo, string|null $slug = null): string|null

modulo_distribuido_scope_central($scope): bool

modulo_distribuido_scope_distribuido($scope): bool

modulo_distribuido_resolver_manifesto(array|string $modulo, string|null $slug = null): array|null

modulo_distribuido_assinar(string $corpo, string $secret, string $algo = 'sha256'): string

modulo_distribuido_verificar_assinatura(string $corpo, string $assinatura, string $secret, string $algo = 'sha256'): bool

modulo_distribuido_detectar_operacao(string $sql): string

modulo_distribuido_operacao_leitura($operacao): bool

modulo_distribuido_montar_payload(string $sql, array $opcoes = []): array

modulo_distribuido_enviar(array $payload, array $config): array

modulo_distribuido_http_post($url, $corpo, array $headers, $timeout = 15): string|false

modulo_distribuido_resposta_para_resultado(array $resposta): BancoResultadoRemoto|bool

modulo_distribuido_executar_local(array $payload, PDO $pdo): array

modulo_distribuido_sql_segura(string $sql): bool

modulo_distribuido_parse_rota(array $caminho): array|null

modulo_distribuido_estado_por_token_ativo(bool $token_ativo): string

modulo_distribuido_estado_renderizacao(bool $token_ativo, bool $tem_permissao): string

modulo_distribuido_estado_por_permissao_central(string $estado_central): string

modulo_distribuido_middleware_permissao(array $config, string $token, string|null $slug = null): array

modulo_distribuido_guardiao(array $config, array $opcoes = []): array

modulo_distribuido_middleware_central(string $token, string $slug, array $opcoes = []): array

modulo_distribuido_montar_url_iframe(string $endpoint_central, string $slug, array $opcoes = []): string

banco_distribuido_iniciar(array $config): void

banco_distribuido_finalizar(): void

banco_distribuido_ativo(): bool

banco_distribuido_query(string $sql): BancoResultadoRemoto|bool

modulo_distribuido_config_get(string $path, mixed $default = null): mixed

modulo_distribuido_canal_central(array $modulo_config, array $overrides = []): array

modulo_distribuido_canal_distribuido(array $modulo_config, array $overrides = []): array

modulo_distribuido_com_canal(callable $operacao, array $config): mixed

modulo_distribuido_token_sessao(string $chave, $slug = null): string

modulo_distribuido_persistir_token(string $chave, array $tokens, callable|null $persistir = null): void

modulo_distribuido_textos(string|null $lang = null, array $overrides = [], $resolver = null): array

modulo_distribuido_render_componente(string $html, string $estado, string|null $iframe_url = null, array $textos = []): string

modulo_distribuido_render_estado(string $estado, string|null $iframe_url = null): string

modulo_distribuido_app(array $config, array $opcoes = []): array

Cadastro de instalações no central

O central reconhece cada instalação distribuída pelo app_id. A leitura é de modulo_distribuido_instalacao($app, $slug), que devolve url, secret, modules e tables, ou false.

• Sem mais nada, o cadastro é a variável MODULO_DISTRIBUIDO_INSTALLATIONS do .env (JSON por app_id).

• Um projeto pode manter o cadastro fora do .env e declarar o leitor em $_CONFIG['modulo-distribuido']['installations-provider']: callable(string $app): array|false|null. array é a instalação; false diz que ela existe e está desativada (o .env não é consultado); null diz que o provedor não a conhece, e o .env responde. Falha do provedor recusa a instalação.

Custo por consulta

Cada consulta do módulo original que alcança uma tabela da instalação vira uma chamada HTTP assinada. A conexão é reaproveitada dentro da requisição (modulo_distribuido_http_post() mantém o handle do cURL), e a faxina dos nonces vencidos no banco do cliente é amostrada, de modo que cada consulta custa uma gravação lá, não duas.