Migrate handler patterns in Functions

Move a function from the legacy Service Worker handler to the ES Modules handler, with the before and after for fetch and firewall.

Last updated

View as Markdown Agent setup

Functions supports two handler patterns: ES Modules, which Azion recommends, and Service Worker, which Azion maintains for backward compatibility. Existing Service Worker code keeps running, so the migration is work to schedule rather than a break to repair. Code that follows neither pattern is not supported.

Supported handler patterns

Both patterns give the handler the same request and the same execution context. They differ in how the code receives them.

ES Modules

An ES Modules function exports a default object. Its fetch method receives the request, the environment variables and bindings, and the execution context. A firewall method receives the same three arguments:

JavaScript
01export default {
02 fetch: (request, env, ctx) => {
03 return new Response('Hello World');
04 },
05 firewall: (request, env, ctx) => {
06 // Blocks the request before it reaches the fetch handler.
07 ctx.deny();
08 }
09};

A default export whose fetch method takes request, env, and ctx follows this pattern, whether it is an object literal or the application instance a framework returns. An application instance built with a framework qualifies, so a Hono app exported with export default app is an ES Modules handler. For a function written that way, refer to Build a RESTful tasks API with Functions and SQL Database.

Service Worker

A Service Worker function registers a listener with addEventListener. The listener reads the request from an event object, and it answers with event.respondWith:

JavaScript
01addEventListener('fetch', (event) => {
02 event.respondWith(handleRequest(event.request));
03});
04
05addEventListener('firewall', (event) => {
06 // Blocks the request before it reaches the fetch listener.
07 event.deny();
08});
09
10async function handleRequest(request) {
11 return new Response('Hello World');
12}

Handler parameters

An ES Modules handler receives three arguments. A Service Worker listener receives one event object that carries the same values. For the signature as the runtime reference states it, refer to Handlers.

fetch(request, env, ctx) in ES Modules

ParameterTypeDescription
requestRequestThe incoming HTTP request object
envObjectEnvironment variables and bindings
ctxObjectExecution context. Use ctx.waitUntil(promise) to extend the lifetime of the function for async tasks

firewall(request, env, ctx) in ES Modules

ParameterTypeDescription
requestRequestThe incoming HTTP request object
envObjectEnvironment variables and bindings
ctxObjectExecution context. Call ctx.deny() to block the request immediately. If ctx.deny() is not called, the request continues to the fetch handler

The event object in Service Worker

PropertyDescription
event.requestAccess to the Request object
event.deny()Blocks the request immediately. If not called, the request continues to the fetch handler

Migrate the handler

The logic stays the same in both patterns. What changes is where the handler reads the request and where it returns the response.

Migrate the fetch handler

The listener becomes a fetch method. The request arrives as the first argument, not as a property of the event.

Service Worker code registers the listener and delegates to a named function:

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}

The ES Modules replacement moves the same logic into the fetch method and returns the response directly:

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

Migrate the firewall handler

Three names change: the listener becomes a firewall method, event.request becomes request, and event.deny() becomes ctx.deny().

Service Worker code reads the headers from the event and blocks with 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 // Blocks bot requests.
10 if (userAgent && userAgent.includes('bot')) {
11 event.deny();
12 return;
13 }
14
15 // Blocks one specific address.
16 if (clientIP === '192.0.2.100') {
17 event.deny();
18 return;
19 }
20
21 // Without a deny call, the request continues to the fetch listener.
22});
23
24async function handleRequest(request) {
25 return new Response('Hello World');
26}

The ES Modules replacement reads the headers from request and blocks with ctx.deny():

JavaScript
01export default {
02 fetch: async (request, env, ctx) => {
03 return new Response('Access granted');
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 // Blocks bot requests.
11 if (userAgent && userAgent.includes('bot')) {
12 ctx.deny();
13 return;
14 }
15
16 // Blocks one specific address.
17 if (clientIP === '192.0.2.100') {
18 ctx.deny();
19 return;
20 }
21
22 // Without a deny call, the request continues to the fetch handler.
23 return;
24 }
25};

Use the execution context

The ctx argument carries the two calls an ES Modules handler makes on the invocation itself.

Move async work off the response path

ctx.waitUntil(promise) extends the lifetime of the function past the response. Pass it the work whose result the response does not need:

JavaScript
01export default {
02 fetch: async (request, env, ctx) => {
03 // The response returns without waiting for the log call.
04 ctx.waitUntil(logRequest(request));
05
06 return new Response('Hello World');
07 }
08};
09
10async function logRequest(request) {
11 console.log(`Request to: ${request.url}`);
12}

Block requests by path

The firewall method receives the whole request. The handler can read the URL and apply one rule per path. This handler blocks bots everywhere and restricts /admin to a single address range:

JavaScript
01export default {
02 fetch: async (request, env, ctx) => {
03 return new Response('Access granted');
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 // Blocks bot requests.
12 if (userAgent && userAgent.includes('bot')) {
13 ctx.deny();
14 return;
15 }
16
17 // Restricts the admin paths to one address range.
18 if (url.pathname.startsWith('/admin')) {
19 if (!clientIP || !clientIP.startsWith('192.0.2.')) {
20 ctx.deny();
21 return;
22 }
23 }
24
25 // Without a deny call, the request continues to the fetch handler.
26 return;
27 }
28};

Unsupported patterns

Azion Runtime reports Unsupported handler pattern detected when the code matches neither supported pattern. Three shapes produce it:

JavaScript
01// A function as the default export, with no fetch method.
02export default function (request) {
03 return new Response('Hello');
04}
05
06// A named export instead of the default export.
07export function fetch(request) {
08 return new Response('Hello');
09}
10
11// A handler the file declares and never exports.
12function handleRequest(request) {
13 return new Response('Hello');
14}

All three fail the same requirement: the default export must be an object that carries a fetch method. Rewrite the code in the ES Modules pattern to clear the error. The Service Worker pattern also clears it, and Azion recommends ES Modules for new code.

For failures that the handler shape does not explain, refer to Troubleshoot function execution and logs.

Next steps

Functions best practicesWhy ES Modules is the pattern for new code, and the ceilings one invocation runs inside.Run a function on an applicationAdd the Rules Engine rule that runs the instance, from Azion Console or the Azion API.Run a function on a firewallPut a firewall handler behind a firewall rule and block a request with ctx.deny().JavaScript examplesHandler code to adapt, still written in the Service Worker pattern.Write and test a functionWrite the handler in Azion Console and read its response before it serves traffic.FunctionsThe product reference, with the scope, the limits, and the invocation path.Azion RuntimeThe Web APIs a handler can call, including Network, Web Streams, and V8 primitives.Troubleshoot function execution and logsWhat to do when a function never runs, stops before it responds, or produces no log output.