Funzioni Edge

Le edge functions sono piccoli handler JavaScript che vengono eseguiti sulla rete edge di Kapsule prima che una richiesta raggiunga il tuo progetto, quindi puoi fare redirect, iniezione di header, A/B routing e bot filtering senza un round trip verso la tua app. Questa guida copre la scrittura di una, le forme di entry-point accettate, la corrispondenza dei percorsi, come interagiscono più funzioni, la distribuzione e cosa succede quando una funzione genera un'eccezione.

Dove Vivono

Apri il tuo progetto in Orbit e fai clic sulla scheda Edge functions. Ogni funzione appartiene a un progetto ed è elencata con il suo badge di stato: LIVE, PAUSED, NOT DEPLOYED o DEPLOY FAILED.

Creazione di una Funzione

1. Fai clic su New function.
2. Riempi il campo Name (fino a 120 caratteri).
3. Riempi il campo Path pattern, il pattern URL su cui questa funzione deve essere eseguita.
4. Scegli un Trigger: Request (prima dell'origine), Response (dopo l'origine) o Both.
5. Scegli un Environment scope: All environments, Production only o Preview only.
6. Scrivi l'handler in Function body.
7. Fai clic su Save, poi su Deploy to edge.

L'oggetto request è sempre in scope e il sorgente è limitato a 64 KB.

Scrittura di un Handler

Restituisci Response per rispondere alla richiesta al bordo della rete. Restituisci niente, o undefined, per passare la richiesta al tuo progetto senza modifiche.

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
  },
}

La forma named-function funziona anche:

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 })
}

Forme di Entry-Point Supportate

Path Patterns

Il Path pattern decide quali richieste eseguono la funzione. Deve iniziare con / e può contenere fino a 2048 caratteri. * corrisponde a qualsiasi sequenza di caratteri e ? corrisponde a un singolo carattere. Un pattern senza wildcard corrisponde esattamente a quel percorso e a tutto ciò che si trova sotto.

L'Oggetto request

request è un Fetch API Request standard. Puoi leggere l'URL, il metodo, gli header e il body:

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 })
    }
  },
}

Pattern Comuni

Reindirizzare URL Vecchi

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)
  },
}

Per un numero limitato di spostamenti da percorso a percorso semplici, usa invece il motore di reindirizzamento integrato: non richiede codice ed è configurato in Settings. Vedi Configuring Redirects and Rewrites.

Aggiungere Security Headers

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,
  })
}

Per le regole di header statico non hai bisogno di codice nemmeno. Settings ha una sezione response headers con quick-add preset per HSTS, CSP, no-embed, no-sniff, referrer policy e CORS.

A/B Routing

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)
  },
}

Environment Scope

Come Interagiscono Più Funzioni

Tutte le funzioni abilitate del tuo progetto vengono valutate nell'ordine in cui sono state create. Per ogni richiesta, il bordo della rete percorre l'elenco ed esegue la prima funzione il cui path pattern corrisponde al percorso della richiesta e il cui scope copre l'ambiente.

• Se quella funzione restituisce Response, viene inviato e la valutazione si interrompe.
• Se non restituisce nulla, la valutazione continua alla funzione corrispondente successiva.
• Se nessuno di loro restituisce Response, la richiesta va al tuo progetto come al solito.

Ciò significa che una funzione ampia /* creata in anticipo può oscurare una più stretta creata in seguito, se quella ampia restituisce Response. Crea prima quelle specifiche, o fai in modo che quella ampia non restituisca nulla per i percorsi che non dovrebbe gestire.

Distribuzione

Fai clic su Deploy to edge. La distribuzione rigenera un singolo router combinato per l'intera rete edge dallo stato attuale del database, quindi abilitare, disabilitare, modificare o eliminare qualsiasi funzione ripubblica tutto. Le modifiche di solito hanno effetto entro pochi secondi.

Ogni riga di funzione mantiene un Deploy log che mostra i passaggi dell'ultima distribuzione e un badge DEPLOY FAILED con l'errore se non è riuscito.

Pause rimuove una funzione dal router senza eliminarla, che è il modo più veloce per annullare una funzione che si comporta male. Resume la rimette.

Quando una Funzione Genera un'Eccezione

Un'eccezione all'interno di una funzione viene catturata al bordo della rete. L'errore viene registrato e la richiesta passa al tuo progetto come se la funzione non avesse restituito nulla.

Limiti

• Fino a 20 funzioni per progetto. La 21ª viene rifiutata.
• Fino a 64 KB di sorgente per funzione.
• Fino a 120 caratteri per il nome e 2048 caratteri per il path pattern.

Letture Correlate

• Configuring Redirects and Rewrites, l'opzione senza codice per le regole di percorso
• Deploying Your Project
• Branch Preview Deployments in Orbit per testare una funzione prima che raggiunga la produzione