Migre padrões de handler em Functions

Mova uma função do handler legado Service Worker para o handler ES Modules, com o antes e o depois de fetch e firewall.

Última atualização

Ver como Markdown Configurar agente

Functions suporta dois padrões de handler: ES Modules, que Azion recomenda, e Service Worker, que Azion mantém para compatibilidade com código legado. O código Service Worker existente continua funcionando, então a migração é um trabalho a planejar e não uma quebra a reparar. Código que não segue nenhum dos dois padrões não é suportado.

Padrões de handler suportados

Os dois padrões entregam ao handler a mesma requisição e o mesmo contexto de execução. Eles diferem na forma como o código os recebe.

ES Modules

Uma função ES Modules exporta um objeto padrão. O método fetch desse objeto recebe a requisição, as variáveis de ambiente e bindings e o contexto de execução. Um método firewall recebe os mesmos três argumentos:

JavaScript
01export default {
02 fetch: (request, env, ctx) => {
03 return new Response('Hello World');
04 },
05 firewall: (request, env, ctx) => {
06 // Bloqueia a requisição antes que ela chegue ao handler fetch.
07 ctx.deny();
08 }
09};

Um export padrão cujo método fetch recebe request, env e ctx segue esse padrão, seja ele um objeto literal ou a instância de aplicação que um framework retorna. Uma instância de aplicação construída com um framework atende ao requisito, então um app Hono exportado com export default app é um handler ES Modules. Para uma função escrita dessa forma, consulte Crie uma API RESTful de tarefas com Functions e SQL Database.

Service Worker

Uma função Service Worker registra um listener com addEventListener. O listener lê a requisição a partir de um objeto de evento e responde com event.respondWith:

JavaScript
01addEventListener('fetch', (event) => {
02 event.respondWith(handleRequest(event.request));
03});
04
05addEventListener('firewall', (event) => {
06 // Bloqueia a requisição antes que ela chegue ao listener fetch.
07 event.deny();
08});
09
10async function handleRequest(request) {
11 return new Response('Hello World');
12}

Parâmetros dos handlers

Um handler ES Modules recebe três argumentos. Um listener Service Worker recebe um objeto de evento que carrega os mesmos valores. Para a assinatura como a referência do runtime a descreve, consulte Handlers.

fetch(request, env, ctx) em ES Modules

ParâmetroTipoDescrição
requestRequestO objeto da requisição HTTP recebida
envObjectVariáveis de ambiente e bindings
ctxObjectContexto de execução. Use ctx.waitUntil(promise) para estender o tempo de vida da função para tarefas assíncronas

firewall(request, env, ctx) em ES Modules

ParâmetroTipoDescrição
requestRequestO objeto da requisição HTTP recebida
envObjectVariáveis de ambiente e bindings
ctxObjectContexto de execução. Chame ctx.deny() para bloquear a requisição imediatamente. Se ctx.deny() não for chamado, a requisição continua para o handler fetch

O objeto de evento em Service Worker

PropriedadeDescrição
event.requestAcesso ao objeto Request
event.deny()Bloqueia a requisição imediatamente. Se não for chamado, a requisição continua para o handler fetch

Migre o handler

A lógica permanece a mesma nos dois padrões. O que muda é onde o handler lê a requisição e onde ele retorna a resposta.

Migre o handler fetch

O listener vira um método fetch. A requisição chega como primeiro argumento e não como uma propriedade do evento.

O código Service Worker registra o listener e delega para uma função nomeada:

JavaScript
01addEventListener('fetch', (event) => {
02 event.respondWith(handleRequest(event.request));
03});
04
05async function handleRequest(request) {
06 const url = new URL(request.url);
07
08 if (url.pathname === '/api/hello') {
09 return new Response(JSON.stringify({ message: 'Hello World' }), {
10 headers: { 'Content-Type': 'application/json' }
11 });
12 }
13
14 return new Response('Not Found', { status: 404 });
15}

A versão ES Modules move a mesma lógica para o método fetch e retorna a resposta diretamente:

JavaScript
01export default {
02 fetch: async (request, env, ctx) => {
03 const url = new URL(request.url);
04
05 if (url.pathname === '/api/hello') {
06 return new Response(JSON.stringify({ message: 'Hello World' }), {
07 headers: { 'Content-Type': 'application/json' }
08 });
09 }
10
11 return new Response('Not Found', { status: 404 });
12 }
13};

Migre o handler firewall

Três nomes mudam: o listener vira um método firewall, event.request vira request e event.deny() vira ctx.deny().

O código Service Worker lê os headers a partir do evento e bloqueia com event.deny():

JavaScript
01addEventListener('fetch', (event) => {
02 event.respondWith(handleRequest(event.request));
03});
04
05addEventListener('firewall', (event) => {
06 const clientIP = event.request.headers.get('X-Forwarded-For');
07 const userAgent = event.request.headers.get('User-Agent');
08
09 // Bloqueia requisições de bots.
10 if (userAgent && userAgent.includes('bot')) {
11 event.deny();
12 return;
13 }
14
15 // Bloqueia um endereço específico.
16 if (clientIP === '192.0.2.100') {
17 event.deny();
18 return;
19 }
20
21 // Sem uma chamada de deny, a requisição continua para o listener fetch.
22});
23
24async function handleRequest(request) {
25 return new Response('Hello World');
26}

A versão ES Modules lê os headers a partir de request e bloqueia com ctx.deny():

JavaScript
01export default {
02 fetch: async (request, env, ctx) => {
03 return new Response('Acesso concedido');
04 },
05
06 firewall: async (request, env, ctx) => {
07 const clientIP = request.headers.get('X-Forwarded-For');
08 const userAgent = request.headers.get('User-Agent');
09
10 // Bloqueia requisições de bots.
11 if (userAgent && userAgent.includes('bot')) {
12 ctx.deny();
13 return;
14 }
15
16 // Bloqueia um endereço específico.
17 if (clientIP === '192.0.2.100') {
18 ctx.deny();
19 return;
20 }
21
22 // Sem uma chamada de deny, a requisição continua para o handler fetch.
23 return;
24 }
25};

Use o contexto de execução

O argumento ctx carrega as duas chamadas que um handler ES Modules faz sobre a própria invocação.

Tire o trabalho assíncrono do caminho da resposta

ctx.waitUntil(promise) estende o tempo de vida da função para além da resposta. Passe para ele o trabalho cujo resultado a resposta não precisa:

JavaScript
01export default {
02 fetch: async (request, env, ctx) => {
03 // A resposta retorna sem esperar pela chamada de log.
04 ctx.waitUntil(logRequest(request));
05
06 return new Response('Hello World');
07 }
08};
09
10async function logRequest(request) {
11 console.log(`Requisição para: ${request.url}`);
12}

Bloqueie requisições por path

O método firewall recebe a requisição inteira. O handler pode ler a URL e aplicar uma regra por path. Este handler bloqueia bots em todos os paths e restringe /admin a uma única faixa de endereços:

JavaScript
01export default {
02 fetch: async (request, env, ctx) => {
03 return new Response('Acesso concedido');
04 },
05
06 firewall: async (request, env, ctx) => {
07 const url = new URL(request.url);
08 const userAgent = request.headers.get('User-Agent');
09 const clientIP = request.headers.get('X-Forwarded-For');
10
11 // Bloqueia requisições de bots.
12 if (userAgent && userAgent.includes('bot')) {
13 ctx.deny();
14 return;
15 }
16
17 // Restringe os paths de admin a uma faixa de endereços.
18 if (url.pathname.startsWith('/admin')) {
19 if (!clientIP || !clientIP.startsWith('192.0.2.')) {
20 ctx.deny();
21 return;
22 }
23 }
24
25 // Sem uma chamada de deny, a requisição continua para o handler fetch.
26 return;
27 }
28};

Padrões não suportados

Azion Runtime reporta Unsupported handler pattern detected quando o código não corresponde a nenhum dos padrões suportados. Três formatos produzem esse erro:

JavaScript
01// Uma função como export padrão, sem método fetch.
02export default function (request) {
03 return new Response('Hello');
04}
05
06// Um export nomeado no lugar do export padrão.
07export function fetch(request) {
08 return new Response('Hello');
09}
10
11// Um handler que o arquivo declara e nunca exporta.
12function handleRequest(request) {
13 return new Response('Hello');
14}

Os três falham no mesmo requisito: o export padrão precisa ser um objeto que carregue um método fetch. Reescreva o código no padrão ES Modules para resolver o erro. O padrão Service Worker também o resolve e Azion recomenda ES Modules para código novo.

Para falhas que o formato do handler não explica, consulte Solução de problemas de execução e logs de funções.

Próximos passos

Boas práticas de FunctionsPor que ES Modules é o padrão para código novo e os limites dentro dos quais uma invocação executa.Execute uma função em uma aplicaçãoAdicione a regra do Rules Engine que executa a instância, em Azion Console ou na Azion API.Execute uma função em um firewallColoque um handler firewall atrás de uma regra de firewall e bloqueie uma requisição com ctx.deny().Exemplos em JavaScriptCódigo de handler para adaptar, ainda escrito no padrão Service Worker.Escreva e teste uma funçãoEscreva o handler em Azion Console e leia a resposta dele antes que a função atenda tráfego.FunctionsA referência do produto, com o escopo, os limites e o caminho de invocação.Azion RuntimeAs Web APIs que um handler pode chamar, incluindo Network, Web Streams e primitivas do V8.Solução de problemas de execução e logs de funçõesO que fazer quando uma função não executa, para antes de responder ou não produz saída de log.