modulo-distribuido.php library

Path in the Gestor bibliotecas/modulo-distribuido.php

It lets a module have two halves:

• central ("scope": "central-module" in <module>.json): runs on the central installation (the vendor's), where the code, users and permissions live;

• distributed ("scope": "distributed-module"): runs on the client's site and keeps the data in the client's database.

The central module code keeps using banco_select(), banco_insert()… as usual; inside the distributed channel, banco_query() packs the SQL and runs it on the client installation. The client sees the module as an embedded screen (iframe) of the central, unlocked only after the central confirms login and permission.

Configuration

In the .env (global variables): MODULO_DISTRIBUIDO_SECRET (shared HMAC secret), MODULO_DISTRIBUIDO_CENTRAL_URL (on the distributed side: the central URL) and MODULO_DISTRIBUIDO_ENDPOINT (on the central side: the distributed API URL). Per module, $_CONFIG['modulo-distribuido']['secrets'][<slug>] and ['endpoints'][<slug>] override the general values (modulo_distribuido_config_get('modulo-distribuido.secrets.<slug>')).

modulo_distribuido_scope($manifest), modulo_distribuido_scope_central(), modulo_distribuido_scope_distribuido() and modulo_distribuido_resolver_manifesto() read the scope from the manifest (constants C2F_SCOPE_CENTRAL and C2F_SCOPE_DISTRIBUIDO).

The data channel

// In the central module, wrapping only the client's data operations:
// the central module manifest declares "distributed": {"target-slug": "my-module"}
$config = modulo_distribuido_canal_central($_GESTOR['modulo#'.$_GESTOR['modulo-id']]);
$orders = modulo_distribuido_com_canal(function () {
    return banco_select(['tabela' => 'pedidos', 'campos' => ['id', 'total']]);
}, $config);
// or by hand: banco_distribuido_iniciar($config); … banco_distribuido_finalizar();

1. banco_distribuido_ativo() makes banco_query() divert to banco_distribuido_query().

2. modulo_distribuido_montar_payload() packs the SQL (operacao, modulo, linguagem, timestamp, nonce), and modulo_distribuido_enviar() sends it through modulo_distribuido_http_post() to <endpoint>/modulo-distribuido/<slug>/db, with X-C2F-Signature = HMAC-SHA256 of the body (modulo_distribuido_assinar()).

3. On the distributed side, the API checks the signature (modulo_distribuido_verificar_assinatura(), constant time) and modulo_distribuido_executar_local() runs the SQL through PDO: a SELECT returns columns and rows; a write returns affected_rows and insert_id.

4. modulo_distribuido_resposta_para_resultado() turns the response into a BancoResultadoRemoto, which mimics mysqli_result for the banco.php functions.

Authentication, variables and the rest of the request stay in the central's local database: only what is inside the channel goes to the client. modulo_distribuido_canal_central($manifest, $overrides) builds the central-side configuration from the manifest's distributed.target-slug (and, optionally, endpoint-config/secret-config, key paths in $_CONFIG); modulo_distribuido_canal_distribuido() does the same on the distributed side, to talk to the central; modulo_distribuido_detectar_operacao() and modulo_distribuido_operacao_leitura() classify the SQL; modulo_distribuido_parse_rota() reads {slug}/{action} from the URL.

Login, permission and screen

The distributed side does not decide access: it asks the central.

• Sign-in is the central's perfil-usuario: without a token, the distributed host sends the browser to the central's /signin/ with a signed context; after the complete sign-in (second factor included) the login.distribuido hook returns a single-use code, exchanged server to server for the tokens (exchange action). modulo_distribuido_token_sessao() and modulo_distribuido_persistir_token() keep and renew the tokens in the session. There is no username and password sign-in on this channel.

• modulo_distribuido_guardiao() (distributed side) asks the central, where modulo_distribuido_middleware_central() validates the token and the user's permission on the module and answers nao-autenticado, sem-permissao or authorized. Any failure resolves to the most restrictive state.

• modulo_distribuido_estado_renderizacao() translates that into login, sem-permissao or iframe; modulo_distribuido_montar_url_iframe() builds the URL of the central screen.

• modulo_distribuido_app() does it all in one call: token, guardian and the state screen, replacing #modulo-distribuido-app# on the page with the modulo-distribuido-app component (modulo_distribuido_render_estado(), modulo_distribuido_render_componente(), modulo_distribuido_textos()).

The variants modulo_distribuido_estado_por_token_ativo(), modulo_distribuido_estado_por_permissao_central() and modulo_distribuido_middleware_permissao() are the pure (testable) pieces of this flow.

Functions

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

Installation registry at the central

The central recognizes each distributed installation by its app_id. The reader is modulo_distribuido_instalacao($app, $slug), which returns url, secret, modules and tables, or false.

• By default the registry is the MODULO_DISTRIBUIDO_INSTALLATIONS variable of the .env (JSON keyed by app_id).

• A project may keep the registry outside the .env and declare the reader in $_CONFIG['modulo-distribuido']['installations-provider']: callable(string $app): array|false|null. array is the installation; false says it exists and is disabled (the .env is not consulted); null says the provider does not know it, and the .env answers. A provider failure refuses the installation.

Cost per query

Each query of the original module that reaches a table of the installation becomes a signed HTTP call. The connection is reused within the request (modulo_distribuido_http_post() keeps the cURL handle), and the sweep of expired nonces in the client's database is sampled, so each query costs one write there, not two.