internos plugins

Internos: Plugins 🚧

Home > Guia de contribuição > Internos: Plugins

Para quem mexe no código: o host de plugins, autenticação, segurança, CORS, conteúdo, concorrência e certificado automático. Aqui fica o porquê de cada parte ser como é, e o que não pode mudar sem quebrar algo. O código traz só a descrição curta de cada coisa.

Conteúdo da versão 2.0, ainda em desenvolvimento (branch 2.0).

O que a página de uso já diz (fases, Priority, como escrever um) está em Criar um plugin.

Os dois laços do servidor

• Plugins primeiro, módulos depois. ProcessCommands roda os plugins por Priority e depois os módulos, que acham a rota e a executam. Servidor sem plugin ainda responde. Tudo o que não é roteamento é plugin (limite, compressão, cifra, listas, força bruta, flood, CORS, cada autenticação, corpo JSON como params), como um middleware, mas a ordem vem da prioridade e não da ordem em que a aplicação liga; empate mantém a ordem em que foram adicionados.
• Uma lista por fase. O plugin declara as suas (Phases) e o host guarda uma lista para cada uma: fase que ninguém usa não custa nada.
• ppValidate roda antes de o corpo ser decodificado: pedido recusado nunca é descomprimido nem decifrado. ppProcess é o laço dos plugins (quem responde marca AHandled). ppResolveRoute, ppAuthenticate e ppAuthResult não são laços do servidor: são chamadas entre plugins (rota própria, autenticadores decidindo, e quem quer saber o veredito; a força bruta conta as falhas ali, antes de qualquer módulo).
• A rota é procurada uma vez (FindRoute) e guardada no pedido. A autenticação precisa dela (o método pula autenticação?), o CORS precisa dos métodos dela, e os módulos respondem sem procurar de novo.
• RALPriorityConcurrency (50) fica depois de todo plugin do RAL que recusa em ppValidate: um pedido que a lista negra, o flood ou o limite de tamanho recusam nunca espera uma vaga na fila.

Ciclo de vida

• ServerActivating/ServerDeactivating têm o contrato dos módulos. "Ativando" quer dizer pedido, não porta aberta: os motores chamam antes de abrir a porta, então o plugin ainda muda como ela abre (o TRALSelfSignedPlugin entrega o certificado ali). Uma exceção mantém o servidor parado. Plugin adicionado a servidor rodando ouve ServerActivating na hora.
• PluginRemoved é o único aviso garantido. O plugin se tira do host antes de as notificações de Free saírem. Descendente que guarda referência a um plugin (o Authentication do servidor) limpa ali; só com Notification a referência ficaria solta.

Leitura sem lock

Qualquer mudança (adicionar, remover, Priority, Enabled) monta um snapshot novo (TRALPluginSnapshot) sob o lock. O velho fica vivo até o host ser destruído, porque um pedido pode estar percorrendo-o. Cada pedido lê o snapshot uma vez e anda nele.

Força bruta: quem conta é o autenticador

O que vale como tentativa é o autenticador que diz (AttemptOf, que devolve TRALAuthAttempt): segredo errado conta contra o endereço, certo zera a contagem, e nenhum dos dois quando não veio credencial (não é tentativa) ou o token venceu (ninguém adivinha token).

Plugins que olham a resposta pronta (operação)

Não há fase depois do módulo. Log, métricas, rastreio e cache registram, na passagem de antes do módulo, um aviso no pedido (TRALRequest.AddFinishHandler) ou na resposta (TRALResponse.AddWireHandler, que roda uma vez no início de TakeWireStream/ TakeWireString, antes de o corpo sair). O pedido guarda o que o fim precisa: StartTick (posto em ValidateRequest), ResponseStatus e BytesSent (postos ao entregar a resposta ao motor; -1 numa resposta em fluxo) e TraceId.

Três restrições moldaram o código:

• Os parâmetros do pedido somem antes do fim. ProcessCommands limpa ARequest.Params ao terminar. Cabeçalhos, agente, usuário e corpo que o log quer, e a chave, o TTL e o If-None-Match que o cache quer, são copiados na passagem de antes (o log num retrato por pedido; o cache num objeto por pedido cujo aviso de resposta faz o trabalho e cujo aviso de fim o libera).
• O aviso não pode ser método do plugin. Um formulário libera os componentes em qualquer ordem, e um pedido pode terminar depois de o plugin ter ido embora. O aviso é método de um objeto com contagem de referência (TRALLogSink, TRALMetricsRegistry, TRALTraceCollector): o plugin e cada pedido em curso seguram uma referência, e o destrutor do plugin só desliga o objeto (não escreve mais) e solta a sua.
• Uma resposta abaixo de 400 em ppValidate não encerra o pedido. Só >= 400 encerra ali; por isso o redirecionamento para HTTPS responde em ppProcess com AHandled := True, e o cache também é ppProcess.

O corpo de texto de uma resposta não é um parâmetro ral_body: quem lê a resposta pronta usa AResponse.Params.SingleBody.