Funções Edge

As funções edge são pequenos manipuladores JavaScript que são executados na rede edge da Kapsule antes de um pedido chegar ao seu projeto, permitindo fazer redireccionamentos, injeção de cabeçalhos, encaminhamento A/B e filtragem de bots sem uma viagem de ida e volta até à sua aplicação. Este guia abrange a escrita de uma, as formas de entrada aceites, correspondência de caminhos, como várias funções interagem, implementação e o que acontece quando uma função lança um erro.

Onde Se Localizam

Abra o seu projeto em Orbit e clique no separador Edge functions. Cada função pertence a um projeto e está listada com a sua etiqueta de estado: LIVE, PAUSED, NOT DEPLOYED ou DEPLOY FAILED.

Criar uma Função

1. Clique em New function.
2. Preencha Name (até 120 caracteres).
3. Preencha Path pattern, o padrão de URL em que esta função deve ser executada.
4. Escolha um Trigger: Request (antes da origem), Response (após a origem), ou Both.
5. Escolha um Environment scope: All environments, Production only, ou Preview only.
6. Escreva o manipulador em Function body.
7. Clique em Save, depois em Deploy to edge.

O objeto request está sempre no âmbito, e a origem é limitada a 64 KB.

Escrever um Manipulador

Devolva um Response para responder ao pedido na edge. Devolva nada, ou undefined, para passar o pedido sem alterações até ao seu projeto.

export default {
  async fetch(request) {
    const url = new URL(request.url)

    // Redirect /old to /new
    if (url.pathname === '/old') {
      return new Response(null, {
        status: 301,
        headers: { Location: '/new' },
      })
    }

    // Returning nothing passes through to the origin
  },
}

A forma de função nomeada também funciona:

export default async function handler(request) {
  // Add a security header to every response
  const response = await fetch(request)
  const headers = new Headers(response.headers)
  headers.set('X-Frame-Options', 'DENY')
  return new Response(response.body, { status: response.status, headers })
}

Formas de Entrada Suportadas

Padrões de Caminho

O Path pattern decide quais os pedidos que executam a função. Tem de começar com / e pode ter até 2048 caracteres. * corresponde a qualquer série de caracteres e ? corresponde a um único carácter. Um padrão sem wildcard corresponde a esse caminho exato e a tudo abaixo dele.

O Objeto request

request é um standard Fetch API Request. Pode ler o URL, método, cabeçalhos e corpo:

export default {
  async fetch(request) {
    const url    = new URL(request.url)
    const cookie = request.headers.get('cookie') ?? ''
    const ua     = request.headers.get('user-agent') ?? ''

    if (ua.includes('BadBot')) {
      return new Response('Forbidden', { status: 403 })
    }
  },
}

Padrões Comuns

Redirecionar URLs Antigas

export default {
  async fetch(request) {
    const url = new URL(request.url)
    const redirects = {
      '/old-about':   '/about',
      '/old-contact': '/contact',
    }
    const dest = redirects[url.pathname]
    if (dest) return Response.redirect(url.origin + dest, 301)
  },
}

Para um punhado de movimentos de caminho para caminho diretos, utilize o motor de redireccionamento incorporado: não precisa de código e é configurado em Settings. Veja Configuring Redirects and Rewrites.

Adicionar Cabeçalhos de Segurança

export default async function handler(request) {
  const response = await fetch(request)
  const headers = new Headers(response.headers)
  headers.set('X-Frame-Options', 'DENY')
  headers.set('X-Content-Type-Options', 'nosniff')
  headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers,
  })
}

Para regras de cabeçalho estáticas também não precisa de código. Settings tem uma secção de cabeçalhos de resposta com predefinições de adição rápida para HSTS, CSP, no-embed, no-sniff, política de referidor e CORS.

Encaminhamento A/B

export default {
  async fetch(request) {
    const url     = new URL(request.url)
    const variant = Math.random() < 0.5 ? 'a' : 'b'
    url.searchParams.set('variant', variant)
    return fetch(url.toString(), request)
  },
}

Âmbito de Ambiente

Como Várias Funções Interagem

Todas as funções ativadas do seu projeto são avaliadas pela ordem em que foram criadas. Para cada pedido, a edge percorre a lista e executa a primeira função cujo padrão de caminho corresponde ao caminho do pedido e cujo âmbito cobre o ambiente.

• Se essa função devolver um Response, é enviado e a avaliação para.
• Se não devolver nada, a avaliação continua para a próxima função correspondente.
• Se nenhuma delas devolver um Response, o pedido vai para o seu projeto normalmente.

Isto significa que uma função /* ampla criada cedo pode sombrear uma mais estreita criada mais tarde, se a ampla devolver um Response. Crie as específicas primeiro, ou faça com que a ampla não devolva nada para caminhos que não deve processar.

Implementar

Clique em Deploy to edge. A implementação regenera um único router combinado para toda a rede edge a partir do estado atual da base de dados, por isso ativar, desativar, editar ou eliminar qualquer função republica tudo. As alterações geralmente têm efeito dentro de alguns segundos.

Cada linha de função mantém um Deploy log mostrando os passos da última implementação, e um crachá DEPLOY FAILED com o erro se não tiver sucesso.

Pause tira uma função do router sem a eliminar, o que é a forma mais rápida de recuar de uma função mal comportada. Resume coloca-a de volta.

Quando uma Função Lança um Erro

Uma excepção dentro de uma função é capturada na edge. O erro é registado e o pedido passa para o seu projeto como se a função não tivesse devolvido nada.

Limites

• Até 20 funções por projeto. A 21ª é rejeitada.
• Até 64 KB de origem por função.
• Até 120 caracteres para o nome, e 2048 caracteres para o padrão de caminho.

Leitura Relacionada

• Configuring Redirects and Rewrites, a opção sem código para regras de caminho
• Deploying Your Project
• Branch Preview Deployments in Orbit para testar uma função antes de chegar à produção