Node.js Agent

Overview

The NetFUNNEL Node agent is a dedicated client that communicates with the NetFUNNEL server.

Minimum Requirements

• Node.js 18 or later

Agent Installation

Add Library

Add Dependencies

Copy the code below and add the dependency to your package.json. The exact URL can be found in the Console agent tab.

package.json

{
  "dependencies": {
    "netfunnel-node-agent": "{{AGENT_URL}}"
  }
}

Install Packages

From the project root, run the following command to install packages.

npm install

Applying Middleware

Add the following code to the middleware that receives requests first.

Nuxt

In Nuxt 3, register the NetFUNNEL agent via defineEventHandler. After calling Netfunnel.run(), if allowed is false the user is redirected to the redirect URL after the waiting room; otherwise routing continues. Unlike Express, you do not need to call next().

// server/middleware/netfunnelAgent.ts

import { sendRedirect } from 'h3';
import { Netfunnel } from 'netfunnel-node-agent';

export default defineEventHandler(async event => {
	Netfunnel.initialize({
        clientId : '{{CLIENT_ID}}',
        secretKey: '{{SECRET_KEY}}'
	});

	console.log('[APP] NetFUNNEL Version:', Netfunnel.getVersion());
	const allowed = await Netfunnel.run(event.node.req, event.node.res);

	if (!allowed) {
		const redirectUrl = (event.node.req as any)._nfRedirect || '/';
		console.log(`Redirecting now to: ${redirectUrl}`);
		return sendRedirect(event, redirectUrl);
	}
});

Express

In Express, apply NetFUNNEL as global middleware. If Netfunnel.run() returns false, the user is redirected after the waiting room; otherwise call next() to continue. Initialize once at server startup in app.ts.

// middleware/netfunnel-middleware.ts

import { Netfunnel } from 'netfunnel-node-agent';

export function netfunnelMiddleware(req, res, next) {
	Netfunnel.run(req, res).then(allowed => {
		if (!allowed) {
			return res.redirect(302, req._nfRedirect || '/');
		}
		next();
	});
}

// app.ts

import express from 'express';
import { router } from './routes.js';
import { netfunnelMiddleware } from './middleware/netfunnel-middleware.js';
import { Netfunnel } from 'netfunnel-node-agent';

const app  = express();
const PORT = 3000;

/* NetFUNNEL global initialization */
Netfunnel.initialize({
  clientId : '{{CLIENT_ID}}',
  secretKey: '{{SECRET_KEY}}'
});

app.use(netfunnelMiddleware);

app.use('/', router);

app.listen(PORT, () => {
  console.log(`[APP] listening on ${PORT} (NetFUNNEL ${Netfunnel.getVersion()})`);
});

Registering the NetFUNNEL middleware globally applies queue control to all requests.

// routes.ts

import { Router } from 'express';
export const router = Router();

router.get('/', (_req, res) => res.send('Home'));
router.get('/page1', (_req, res) => res.send('Page 1'));
router.get('/page2', (_req, res) => res.send('Page 2'));
router.get('/page3', (_req, res) => res.send('Page 3'));

Initialize Settings

Field	Type	Default	Required	Description	Agent version
clientId	string	N/A	O	Enter the client ID issued from the console.	4.0.1 or later
secretKey	string	N/A	O	Enter the secret key issued from the console.	4.0.1 or later
serverUrl	string	N/A	X	URL of the NetFUNNEL server. Use when accessing via a custom URL or when not using CNAME. <br/>(Backward compatibility.)	4.0.1 or later
settingUrl	string	N/A	X	URL of the NetFUNNEL environment config file. Use when loading via a custom URL or when not using CNAME. <br/>(Backward compatibility.)	4.0.1 or later
vwrPageUrl	string	N/A	X	URL of the NetFUNNEL VWR page. Use when redirecting to the waiting room via a custom URL.	4.0.1 or later
returnKey	boolean	true	X	When the user passes the queue and enters, the next user can enter immediately.<br/>If disabled, the next user waits. <br/>(Timeout: Console > Segment settings > Advanced.)	4.0.1 or later
printLog	boolean	false	X	Enable or disable debug log output.	4.0.1 or later
goodBots	array	N/A	X	Exclude good bots from NetFUNNEL entry. Pass an array of strings.<br/>Example: ["Googlebot", "Bingbot"]	4.0.1 or later
userId	string	N/A	X	When set, this ID is used for whitelist and permanent block. Set in Console > Repeated request block > User settings > Visitor management.	4.0.1 or later
vwrPageDomain	string	N/A	X	Use when building the VWR page URL with only the CNAME domain.<br/>Example: https://vwr.example.com	4.0.1 or later
cookieDomain	string	N/A	X	Set the domain of the NetFUNNEL cookie explicitly.	4.0.1 or later

Agent Application

Queue control points can be configured via segment trigger rules in the NetFUNNEL console. The queue is applied when the URL of the page the user accesses matches the trigger rules.

Configuration Options

• Logical Operator: When creating two or more trigger rules, defines their relationship with and or or.
• Validator: Defines the top-level scope for the trigger rule (e.g. URL only).
• Component: Within the scope defined by the Validator, specifies the target in more detail (e.g. full URL or path).
• Negate: Use to apply the opposite of the configured condition.
• Match: Defines the type of condition (e.g. Equals, Exists) for when the rule applies.
• Value: The value to compare against when the rule is evaluated; used together with Match.
• Aa: Whether to match Value case-sensitively.

Match Options

• Exists: Checks whether the Component exists in the URL. (Only when Component is Path.)
• Equals: Checks whether the Component value exactly matches Value.
• Contains: Checks whether the Component value contains Value.
• StartsWith: Checks whether the Component value starts with Value.
• EndsWith: Checks whether the Component value ends with Value.

Testing Trigger Rules

You can test in advance whether the URLs where you want to apply the queue match the trigger rules.