Middleware

The middleware system allows you to intercept, inspect, and modify OCPP messages (calls and results) as they flow through the client and server. It follows an onion-like execution model similar to Koa or Axios interceptors.

Basic Usage

You can add middleware to both OCPPServer and OCPPClient.

client.use(async (ctx, next) => {
  console.log(`Processing ${ctx.method} (${ctx.direction})`);

  // Modify context or just observe
  ctx.params.timestamp = new Date().toISOString();

  // Proceed to next middleware/handler
  await next();

  // Code here runs after the handler returns (on the way out)
  console.log(`Finished ${ctx.method}`);
});

Built-in Middleware

Logging

The logging middleware is enabled by default but can be customized. It logs all incoming and outgoing messages.

import { createLoggingMiddleware } from "ocpp-ws-io/middleware";

// Manually adding (if you disabled default logging)
client.use(createLoggingMiddleware(logger, "Point1"));

Creating Custom Middleware

Middleware functions receive a context and a next function.

Context Object

Property	Type	Description
`type`	`incoming_call` \| `outgoing_call`	Direction and type of message
`method`	`string`	OCPP Action (e.g. `BootNotification`)
`params`	`any`	Payload of the message
`messageId`	`string`	Unique ID of the message
`protocol`	`OCPPProtocol`	negotiated protocol version

import { defineRpcMiddleware } from "ocpp-ws-io/browser"; // Or "ocpp-ws-io" for Server/NodeClient

const validationMiddleware = defineRpcMiddleware(async (ctx, next) => {
  if (ctx.type === "outgoing_call" && !ctx.params) {
    throw new Error("Payload cannot be empty");
  }
  await next();
});

client.use(validationMiddleware);

Connection Middleware (Server Setup)

While clients only utilize RPC middleware (parsing payloads), the OCPPServer and OCPPRouter handle raw HTTP upgrades. To gain type-safety when building connection middlewares (e.g. rate-limiting, authentication), use defineMiddleware and the native ctx controls:

import { defineMiddleware } from "ocpp-ws-io";

const rateLimitConnection = defineMiddleware(async (ctx) => {
  // `ctx` includes full `IncomingMessage`, URL parsed `pathname`, and `headers`
  console.log(`Connection attempt from: ${ctx.handshake.remoteAddress}`);

  if (isRateLimited(ctx.handshake.remoteAddress)) {
    // Instantly aborts the WebSocket connection with an HTTP code
    ctx.reject(429, "Too Many Requests");
  } else {
    // Or proceed down the execution chain. You can optionally pass an object
    // to next(), which will automatically be shallow-merged into `ctx.state`.
    await ctx.next({
      isTrusted: true,
      rateLimitRemaining: 99,
    });
  }
});

server.use(rateLimitConnection);

Authentication Helpers

To secure incoming WebSocket connections on the OCPPServer, you attach an auth() hook. ocpp-ws-io provides two utilities to make authentication chains typed and composable.

`defineAuth`

The defineAuth helper provides immediate IDE type inference for the accept, reject, and handshake parameters, so you don't need to manually type your callback.

import { defineAuth } from "ocpp-ws-io";

const verifyBasicAuth = defineAuth(async (ctx) => {
  const token = ctx.handshake.headers.authorization;
  if (!token) {
    return ctx.reject(401, "Basic auth required");
  }

  // Inject arbitrary session properties that your RPC handlers can access later
  ctx.accept({ session: { identity: ctx.handshake.identity, role: "admin" } });
});

server.auth(verifyBasicAuth);

`combineAuth`

When building modular endpoints with the OCPPRouter, you might need to combine multiple authentication rules (e.g. check a firewall IP, then check a JWT). combineAuth executes defineAuth callbacks sequentially.

import { combineAuth, defineAuth } from "ocpp-ws-io";

const checkFirewall = defineAuth((ctx) => {
  if (ctx.handshake.remoteAddress === "1.2.3.4") ctx.reject(403, "IP Blocked");
  else ctx.accept({}); // Pass immediately to the next auth handler
});

server.auth(combineAuth(checkFirewall, verifyBasicAuth));

// Alternatively, inline:
server.auth(
  combineAuth(
    // Firewall Check
    async (ctx) => {
      if (isBlocked(ctx.handshake.headers["x-forwarded-for"])) {
        return ctx.reject(403, "IP Blocked");
      }
    },
    // Basic Auth
    async (ctx) => {
      if (!ctx.handshake.headers.authorization) {
        return ctx.reject(401, "Missing Auth");
      }
      ctx.accept({ protocol: "ocpp1.6" });
    },
  ),
);

Execution Flow

Response Phase: Middleware runs from last to first (after await next()).

Middleware

On this page