Network List API

The Azion Runtime Network List API checks whether an IP address is in one of the network lists of your account. Functions that run on an Application or on a Firewall can call it. Pass it the client address of the request to allow, deny, or route that request by where it comes from.

Under azion dev, every call to Azion.networkList.contains() throws TypeError: Cannot read properties of undefined (reading 'find'). Test network list checks on a deployed function.

Access

The API is the Azion.networkList.contains() function, available to every function without an import. The client address of a request is the remote_addr value of the request metadata. With the export default { fetch } handler, read it from request.metadata:

const ip = request.metadata["remote_addr"];

With addEventListener("fetch", ...), read it from event.request.metadata:

let ip = event.request.metadata["remote_addr"];

For every metadata value a function can read, refer to Metadata API.

Syntax

Azion.networkList.contains() takes the network list ID and the address to check:

Azion.networkList.contains(networkListId, ipAddress)

Parameters

Both parameters are strings.

Parameter	Type	Description
`networkListId`	string	ID of the network list, as a string of digits. A number is not accepted: convert it with `String()` first.
`ipAddress`	string	IP address to check. It matches an address item of the list, or any address inside a CIDR item, for example `198.51.100.42` inside `198.51.100.0/24`.

Return value

Azion.networkList.contains() returns a boolean: true when the address is in the network list, and false when it is not. When the call cannot run the check, it throws a NetworkListError, listed in Errors.

Example

This function checks the client address of each request against a network list and returns the result as JSON. Replace <network-list-id> with the ID of one of your network lists:

JavaScript

01const NETWORK_LIST_ID = "<network-list-id>";

03export default {

04 async fetch(request, env, ctx) {

05 const ip = request.metadata["remote_addr"];

06 const ipFound = Azion.networkList.contains(NETWORK_LIST_ID, ip);

07 return new Response(JSON.stringify({ ipFound }, null, 1), {

08 headers: { "content-type": "application/json" },

09 });

10 },

11};

A request from an address that is in the list returns:

JSON

01{

02 "ipFound": true

03}

Errors

Every error Azion.networkList.contains() throws has the name NetworkListError. Catch it with try...catch and match on err.name to decide what the function does when the check cannot run.

Error message	Cause	Fix
`Network List Not Found`	The ID names no network list of the account, or the ID was passed as a number.	Pass the ID of an existing network list as a string of digits.
`Invalid Network List Id: Only numeric values are acceptable`	The ID string holds characters other than digits.	Pass the numeric ID of the network list as a string.
`Invalid value: not-an-ip`	The address is not an IP address. The message ends with the value passed, here `not-an-ip`.	Pass an IP address, such as the `remote_addr` metadata value of the request.

Network Lists

The list types, the format of their items, and the interfaces that create and edit a list.

Metadata API

Read the remote_addr of a request and the other values the runtime gives a function.

Functions for Firewall

End a firewall function with event.continue(), event.deny(), or event.drop() after a check.

Handlers

The export default { fetch } and addEventListener handler forms, and the request each one receives.