From 3bc3c823b5bbf54ba1c1b82a331b2c776c42b702 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Mon, 10 Nov 2025 17:23:17 +0100 Subject: [PATCH] refactor: cleanup payload validation code MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérôme Benoit --- .../ocpp/1.6/OCPP16IncomingRequestService.ts | 57 +++++++++++++++++- .../ocpp/1.6/OCPP16RequestService.ts | 9 +-- .../ocpp/1.6/OCPP16ResponseService.ts | 41 +++++++++++++ .../ocpp/1.6/OCPP16ServiceUtils.ts | 28 ++++----- .../ocpp/2.0/OCPP20IncomingRequestService.ts | 60 ++++++++++++++++++- .../ocpp/2.0/OCPP20ResponseService.ts | 49 +++++++++++++++ .../ocpp/2.0/OCPP20ServiceUtils.ts | 28 ++++----- .../ocpp/OCPPIncomingRequestService.ts | 7 +++ .../ocpp/OCPPRequestService.ts | 9 ++- .../ocpp/OCPPResponseService.ts | 7 +++ src/charging-station/ocpp/OCPPServiceUtils.ts | 34 +++++++++++ 11 files changed, 290 insertions(+), 39 deletions(-) diff --git a/src/charging-station/ocpp/1.6/OCPP16IncomingRequestService.ts b/src/charging-station/ocpp/1.6/OCPP16IncomingRequestService.ts index 2ace4b87..f924231e 100644 --- a/src/charging-station/ocpp/1.6/OCPP16IncomingRequestService.ts +++ b/src/charging-station/ocpp/1.6/OCPP16IncomingRequestService.ts @@ -117,6 +117,40 @@ import { OCPP16ServiceUtils } from './OCPP16ServiceUtils.js' const moduleName = 'OCPP16IncomingRequestService' +/** + * OCPP 1.6 Incoming Request Service - handles and processes all incoming requests + * from the Central System (CS) to the Charging Station (CP) using OCPP 1.6 protocol. + * + * This service class is responsible for: + * - **Request Reception**: Receiving and routing OCPP 1.6 incoming requests from Central System + * - **Payload Validation**: Validating incoming request payloads against OCPP 1.6 JSON schemas + * - **Request Processing**: Executing business logic for each OCPP 1.6 request type + * - **Response Generation**: Creating and sending appropriate responses back to Central System + * - **Error Handling**: Managing protocol-level and application-level errors + * + * Supported OCPP 1.6 Incoming Request Types: + * - **Configuration Management**: ChangeConfiguration, GetConfiguration, GetLocalListVersion + * - **Remote Operations**: RemoteStartTransaction, RemoteStopTransaction, UnlockConnector + * - **Firmware Management**: GetDiagnostics, UpdateFirmware, Reset + * - **Reservation Management**: ReserveNow, CancelReservation + * - **Charging Profiles**: SetChargingProfile, ClearChargingProfile, GetCompositeSchedule + * - **Monitoring**: GetLocalListVersion, TriggerMessage + * + * Architecture Pattern: + * This class extends OCPPIncomingRequestService and implements OCPP 1.6-specific + * request handling logic. It uses a handler mapping pattern where each request type + * is mapped to a specific handler method, providing clean separation of concerns. + * + * Validation Workflow: + * 1. Incoming request received and parsed + * 2. Payload validated against OCPP 1.6 JSON schema + * 3. Request routed to appropriate handler method + * 4. Business logic executed with charging station state management + * 5. Response payload validated and sent back to Central System + * @see {@link validatePayload} Request payload validation method + * @see {@link handleRequestRemoteStartTransaction} Example request handler + */ + export class OCPP16IncomingRequestService extends OCPPIncomingRequestService { protected payloadValidatorFunctions: Map> @@ -202,7 +236,7 @@ export class OCPP16IncomingRequestService extends OCPPIncomingRequestService { ]) this.payloadValidatorFunctions = OCPP16ServiceUtils.createPayloadValidatorMap( OCPP16ServiceUtils.createIncomingRequestPayloadConfigs(), - OCPP16ServiceUtils.createIncomingRequestFactoryOptions(moduleName, 'constructor'), + OCPP16ServiceUtils.createIncomingRequestPayloadOptions(moduleName, 'constructor'), this.ajv ) // Handle incoming request events @@ -1033,6 +1067,13 @@ export class OCPP16IncomingRequestService extends OCPPIncomingRequestService { } } + /** + * Handles OCPP 1.6 RemoteStartTransaction request from central system + * Initiates charging transaction on specified or available connector + * @param chargingStation - The charging station instance processing the request + * @param commandPayload - RemoteStartTransaction request payload with connector and ID tag + * @returns Promise resolving to GenericResponse indicating operation success or failure + */ private async handleRequestRemoteStartTransaction ( chargingStation: ChargingStation, commandPayload: RemoteStartTransactionRequest @@ -1213,7 +1254,12 @@ export class OCPP16IncomingRequestService extends OCPPIncomingRequestService { } } - // Simulate charging station restart + /** + * Handles incoming Reset request and initiates station reset + * @param chargingStation - The charging station instance processing the request + * @param commandPayload - Reset request payload containing reset type + * @returns OCPP response indicating acceptance of the reset request + */ private handleRequestReset ( chargingStation: ChargingStation, commandPayload: ResetRequest @@ -1605,6 +1651,13 @@ export class OCPP16IncomingRequestService extends OCPPIncomingRequestService { } } + /** + * Validates incoming OCPP 1.6 request payload against JSON schema + * @param chargingStation - The charging station instance processing the request + * @param commandName - OCPP 1.6 command name to validate against + * @param commandPayload - JSON payload to validate + * @returns True if payload validation succeeds, false otherwise + */ private validatePayload ( chargingStation: ChargingStation, commandName: OCPP16IncomingRequestCommand, diff --git a/src/charging-station/ocpp/1.6/OCPP16RequestService.ts b/src/charging-station/ocpp/1.6/OCPP16RequestService.ts index e07e9791..e2a0417e 100644 --- a/src/charging-station/ocpp/1.6/OCPP16RequestService.ts +++ b/src/charging-station/ocpp/1.6/OCPP16RequestService.ts @@ -11,7 +11,6 @@ import { type JsonObject, type JsonType, OCPP16ChargePointStatus, - type OCPP16MeterValue, OCPP16RequestCommand, type OCPP16StartTransactionRequest, OCPPVersion, @@ -125,9 +124,6 @@ export class OCPP16RequestService extends OCPPRequestService { case OCPP16RequestCommand.DIAGNOSTICS_STATUS_NOTIFICATION: return commandParams as unknown as Request case OCPP16RequestCommand.FIRMWARE_STATUS_NOTIFICATION: - logger.debug( - `${chargingStation.logPrefix()} ${moduleName}.buildRequestPayload: Building ${OCPP16RequestCommand.FIRMWARE_STATUS_NOTIFICATION} payload` - ) return commandParams as unknown as Request case OCPP16RequestCommand.HEARTBEAT: return OCPP16Constants.OCPP_REQUEST_EMPTY as unknown as Request @@ -174,14 +170,13 @@ export class OCPP16RequestService extends OCPPRequestService { ...(chargingStation.stationInfo?.transactionDataMeterValues === true && { transactionData: OCPP16ServiceUtils.buildTransactionDataMeterValues( // eslint-disable-next-line @typescript-eslint/no-non-null-assertion - chargingStation.getConnectorStatus(connectorId!)! - .transactionBeginMeterValue! as OCPP16MeterValue, + chargingStation.getConnectorStatus(connectorId!)!.transactionBeginMeterValue!, OCPP16ServiceUtils.buildTransactionEndMeterValue( chargingStation, // eslint-disable-next-line @typescript-eslint/no-non-null-assertion connectorId!, energyActiveImportRegister - ) as OCPP16MeterValue + ) ), }), ...commandParams, diff --git a/src/charging-station/ocpp/1.6/OCPP16ResponseService.ts b/src/charging-station/ocpp/1.6/OCPP16ResponseService.ts index 06b7be4a..78bd2e2c 100644 --- a/src/charging-station/ocpp/1.6/OCPP16ResponseService.ts +++ b/src/charging-station/ocpp/1.6/OCPP16ResponseService.ts @@ -42,6 +42,40 @@ import { OCPP16ServiceUtils } from './OCPP16ServiceUtils.js' const moduleName = 'OCPP16ResponseService' +/** + * OCPP 1.6 Response Service - handles and processes all outgoing request responses + * from the Charging Station (CP) to the Central System (CS) using OCPP 1.6 protocol. + * + * This service class is responsible for: + * - **Response Reception**: Receiving responses to requests sent from the Charging Station + * - **Payload Validation**: Validating response payloads against OCPP 1.6 JSON schemas + * - **Response Processing**: Processing Central System responses and updating station state + * - **Error Handling**: Managing response errors and protocol-level exceptions + * - **State Synchronization**: Ensuring charging station state reflects Central System responses + * + * Supported OCPP 1.6 Response Types: + * - **Authentication**: Authorize responses with authorization status updates + * - **Transaction Management**: StartTransaction, StopTransaction response handling + * - **Status Updates**: BootNotification, StatusNotification, MeterValues responses + * - **Configuration**: Responses to configuration queries and updates + * - **Heartbeat**: Heartbeat response processing for connection maintenance + * - **Data Transfer**: Custom data transfer response handling + * + * Architecture Pattern: + * This class extends OCPPResponseService and implements OCPP 1.6-specific response + * processing logic. It follows a handler mapping pattern where each response type + * is processed by dedicated handler methods that manage charging station state updates. + * + * Response Validation Workflow: + * 1. Response received from Central System for previously sent request + * 2. Response payload validated against OCPP 1.6 JSON schema + * 3. Response routed to appropriate handler based on original request type + * 4. Charging station state updated based on response content + * 5. Any follow-up actions triggered (transactions, status changes, etc.) + * @see {@link validatePayload} Response payload validation method + * @see {@link handleResponse} Response processing methods + */ + export class OCPP16ResponseService extends OCPPResponseService { public incomingRequestResponsePayloadValidateFunctions: Map< OCPP16IncomingRequestCommand, @@ -574,6 +608,13 @@ export class OCPP16ResponseService extends OCPPResponseService { await OCPP16ServiceUtils.restoreConnectorStatus(chargingStation, connectorId, connectorStatus) } + /** + * Validates incoming OCPP 1.6 response payload against JSON schema + * @param chargingStation - The charging station instance receiving the response + * @param commandName - OCPP 1.6 command name to validate against + * @param payload - JSON response payload to validate + * @returns True if payload validation succeeds, false otherwise + */ private validatePayload ( chargingStation: ChargingStation, commandName: OCPP16RequestCommand, diff --git a/src/charging-station/ocpp/1.6/OCPP16ServiceUtils.ts b/src/charging-station/ocpp/1.6/OCPP16ServiceUtils.ts index 0d3c9937..a97598d8 100644 --- a/src/charging-station/ocpp/1.6/OCPP16ServiceUtils.ts +++ b/src/charging-station/ocpp/1.6/OCPP16ServiceUtils.ts @@ -378,20 +378,6 @@ export class OCPP16ServiceUtils extends OCPPServiceUtils { } } - /** - * Factory options for OCPP 1.6 Incoming Request Service - * @param moduleName - Name of the OCPP module - * @param methodName - Name of the method/command - * @returns Factory options object for OCPP 1.6 incoming request validators - */ - public static createIncomingRequestFactoryOptions = (moduleName: string, methodName: string) => - OCPP16ServiceUtils.PayloadValidatorOptions( - OCPPVersion.VERSION_16, - 'assets/json-schemas/ocpp/1.6', - moduleName, - methodName - ) - /** * OCPP 1.6 Incoming Request Service validator configurations * @returns Array of validator configuration tuples @@ -467,6 +453,20 @@ export class OCPP16ServiceUtils extends OCPPServiceUtils { ], ] + /** + * Factory options for OCPP 1.6 Incoming Request Service + * @param moduleName - Name of the OCPP module + * @param methodName - Name of the method/command + * @returns Factory options object for OCPP 1.6 incoming request validators + */ + public static createIncomingRequestPayloadOptions = (moduleName: string, methodName: string) => + OCPP16ServiceUtils.PayloadValidatorOptions( + OCPPVersion.VERSION_16, + 'assets/json-schemas/ocpp/1.6', + moduleName, + methodName + ) + /** * Factory options for OCPP 1.6 Incoming Request Response Service * @param moduleName - Name of the OCPP module diff --git a/src/charging-station/ocpp/2.0/OCPP20IncomingRequestService.ts b/src/charging-station/ocpp/2.0/OCPP20IncomingRequestService.ts index f6f68bfc..4c4051e8 100644 --- a/src/charging-station/ocpp/2.0/OCPP20IncomingRequestService.ts +++ b/src/charging-station/ocpp/2.0/OCPP20IncomingRequestService.ts @@ -68,6 +68,50 @@ import { getVariableMetadata, VARIABLE_REGISTRY } from './OCPP20VariableRegistry const moduleName = 'OCPP20IncomingRequestService' +/** + * OCPP 2.0+ Incoming Request Service - handles and processes all incoming requests + * from the Central System (CSMS) to the Charging Station using OCPP 2.0+ protocol. + * + * This service class is responsible for: + * - **Request Reception**: Receiving and routing OCPP 2.0+ incoming requests from CSMS + * - **Payload Validation**: Validating incoming request payloads against OCPP 2.0+ JSON schemas + * - **Request Processing**: Executing business logic for each OCPP 2.0+ request type + * - **Response Generation**: Creating and sending appropriate responses back to CSMS + * - **Enhanced Features**: Supporting advanced OCPP 2.0+ features like variable management + * + * Supported OCPP 2.0+ Incoming Request Types: + * - **Transaction Management**: RequestStartTransaction, RequestStopTransaction + * - **Configuration Management**: SetVariables, GetVariables, GetBaseReport + * - **Security Operations**: CertificatesSigned, SecurityEventNotification + * - **Charging Management**: SetChargingProfile, ClearChargingProfile, GetChargingProfiles + * - **Diagnostics**: TriggerMessage, GetLog, UpdateFirmware + * - **Display Management**: SetDisplayMessage, ClearDisplayMessage + * - **Customer Management**: ClearCache, SendLocalList + * + * Key OCPP 2.0+ Enhancements: + * - **Variable Model**: Advanced configuration through standardized variable system + * - **Enhanced Security**: Improved authentication and authorization mechanisms + * - **Rich Messaging**: Support for display messages and customer information + * - **Advanced Monitoring**: Comprehensive logging and diagnostic capabilities + * - **Flexible Charging**: Enhanced charging profile management and scheduling + * + * Architecture Pattern: + * This class extends OCPPIncomingRequestService and implements OCPP 2.0+-specific + * request handling logic. It integrates with the OCPP20VariableManager for advanced + * configuration management and maintains backward compatibility concepts while + * providing next-generation OCPP features. + * + * Validation Workflow: + * 1. Incoming request received and parsed + * 2. Payload validated against OCPP 2.0+ JSON schema + * 3. Request routed to appropriate handler method + * 4. Business logic executed with variable model integration + * 5. Response payload validated and sent back to CSMS + * @see {@link validatePayload} Request payload validation method + * @see {@link handleRequestRequestStartTransaction} Example OCPP 2.0+ request handler + * @see {@link OCPP20VariableManager} Variable management integration + */ + export class OCPP20IncomingRequestService extends OCPPIncomingRequestService { protected payloadValidatorFunctions: Map> @@ -116,7 +160,7 @@ export class OCPP20IncomingRequestService extends OCPPIncomingRequestService { ]) this.payloadValidatorFunctions = OCPP20ServiceUtils.createPayloadValidatorMap( OCPP20ServiceUtils.createIncomingRequestPayloadConfigs(), - OCPP20ServiceUtils.createIncomingRequestFactoryOptions(moduleName, 'constructor'), + OCPP20ServiceUtils.createIncomingRequestPayloadOptions(moduleName, 'constructor'), this.ajv ) // Handle incoming request events @@ -830,6 +874,13 @@ export class OCPP20IncomingRequestService extends OCPPIncomingRequestService { } } + /** + * Handles OCPP 2.0 RequestStartTransaction request from central system + * Initiates charging transaction on specified EVSE with enhanced authorization + * @param chargingStation - The charging station instance processing the request + * @param commandPayload - RequestStartTransaction request payload with EVSE, ID token and profiles + * @returns Promise resolving to RequestStartTransactionResponse with status and transaction details + */ private async handleRequestRequestStartTransaction ( chargingStation: ChargingStation, commandPayload: OCPP20RequestStartTransactionRequest @@ -1489,6 +1540,13 @@ export class OCPP20IncomingRequestService extends OCPPIncomingRequestService { return true } + /** + * Validates incoming OCPP 2.0 request payload against JSON schema + * @param chargingStation - The charging station instance processing the request + * @param commandName - OCPP 2.0 command name to validate against + * @param commandPayload - JSON payload to validate + * @returns True if payload validation succeeds, false otherwise + */ private validatePayload ( chargingStation: ChargingStation, commandName: OCPP20IncomingRequestCommand, diff --git a/src/charging-station/ocpp/2.0/OCPP20ResponseService.ts b/src/charging-station/ocpp/2.0/OCPP20ResponseService.ts index e529c4a1..b2bb8434 100644 --- a/src/charging-station/ocpp/2.0/OCPP20ResponseService.ts +++ b/src/charging-station/ocpp/2.0/OCPP20ResponseService.ts @@ -25,6 +25,48 @@ import { OCPP20ServiceUtils } from './OCPP20ServiceUtils.js' const moduleName = 'OCPP20ResponseService' +/** + * OCPP 2.0+ Response Service - handles and processes all outgoing request responses + * from the Charging Station to the Central System Management System (CSMS) using OCPP 2.0+ protocol. + * + * This service class is responsible for: + * - **Response Reception**: Receiving responses to requests sent from the Charging Station + * - **Payload Validation**: Validating response payloads against OCPP 2.0+ JSON schemas + * - **Response Processing**: Processing CSMS responses and updating station state + * - **Variable Management**: Handling variable-based configuration responses + * - **Enhanced State Management**: Managing OCPP 2.0+ advanced state and feature coordination + * + * Supported OCPP 2.0+ Response Types: + * - **Authentication**: Authorize responses with enhanced authorization mechanisms + * - **Transaction Management**: TransactionEvent responses for flexible transaction handling + * - **Status Updates**: BootNotification, StatusNotification, NotifyReport responses + * - **Variable Operations**: Responses to GetVariables, SetVariables operations + * - **Security**: Responses to security-related operations and certificate management + * - **Heartbeat**: Enhanced heartbeat response processing with additional metadata + * + * Key OCPP 2.0+ Features: + * - **Variable Model Integration**: Seamless integration with OCPP 2.0+ variable system + * - **Enhanced Transaction Model**: Support for flexible transaction event handling + * - **Security Framework**: Advanced security response processing and validation + * - **Rich Data Model**: Support for complex data structures and enhanced messaging + * - **Backward Compatibility**: Maintains compatibility concepts while extending functionality + * + * Architecture Pattern: + * This class extends OCPPResponseService and implements OCPP 2.0+-specific response + * processing logic. It works closely with OCPP20VariableManager and other OCPP 2.0+ + * components to provide comprehensive protocol support with enhanced features. + * + * Response Validation Workflow: + * 1. Response received from CSMS for previously sent request + * 2. Response payload validated against OCPP 2.0+ JSON schema + * 3. Response routed to appropriate handler based on original request type + * 4. Charging station state and variable model updated based on response content + * 5. Enhanced follow-up actions triggered based on OCPP 2.0+ capabilities + * @see {@link validatePayload} Response payload validation method + * @see {@link handleResponse} Response processing methods + * @see {@link OCPP20VariableManager} Variable management integration + */ + export class OCPP20ResponseService extends OCPPResponseService { public incomingRequestResponsePayloadValidateFunctions: Map< OCPP20IncomingRequestCommand, @@ -218,6 +260,13 @@ export class OCPP20ResponseService extends OCPPResponseService { ) } + /** + * Validates incoming OCPP 2.0 response payload against JSON schema + * @param chargingStation - The charging station instance receiving the response + * @param commandName - OCPP 2.0 command name to validate against + * @param payload - JSON response payload to validate + * @returns True if payload validation succeeds, false otherwise + */ private validatePayload ( chargingStation: ChargingStation, commandName: OCPP20RequestCommand, diff --git a/src/charging-station/ocpp/2.0/OCPP20ServiceUtils.ts b/src/charging-station/ocpp/2.0/OCPP20ServiceUtils.ts index 2ea07cdf..884983ec 100644 --- a/src/charging-station/ocpp/2.0/OCPP20ServiceUtils.ts +++ b/src/charging-station/ocpp/2.0/OCPP20ServiceUtils.ts @@ -21,20 +21,6 @@ import { OCPPServiceUtils, sendAndSetConnectorStatus } from '../OCPPServiceUtils import { OCPP20Constants } from './OCPP20Constants.js' export class OCPP20ServiceUtils extends OCPPServiceUtils { - /** - * Factory options for OCPP 2.0 Incoming Request Service - * @param moduleName - Name of the OCPP module - * @param methodName - Name of the method/command - * @returns Factory options object for OCPP 2.0 incoming request validators - */ - public static createIncomingRequestFactoryOptions = (moduleName: string, methodName: string) => - OCPP20ServiceUtils.PayloadValidatorOptions( - OCPPVersion.VERSION_201, - 'assets/json-schemas/ocpp/2.0', - moduleName, - methodName - ) - /** * OCPP 2.0 Incoming Request Service validator configurations * @returns Array of validator configuration tuples @@ -73,6 +59,20 @@ export class OCPP20ServiceUtils extends OCPPServiceUtils { ], ] + /** + * Factory options for OCPP 2.0 Incoming Request Service + * @param moduleName - Name of the OCPP module + * @param methodName - Name of the method/command + * @returns Factory options object for OCPP 2.0 incoming request validators + */ + public static createIncomingRequestPayloadOptions = (moduleName: string, methodName: string) => + OCPP20ServiceUtils.PayloadValidatorOptions( + OCPPVersion.VERSION_201, + 'assets/json-schemas/ocpp/2.0', + moduleName, + methodName + ) + /** * Factory options for OCPP 2.0 Incoming Request Response Service * @param moduleName - Name of the OCPP module diff --git a/src/charging-station/ocpp/OCPPIncomingRequestService.ts b/src/charging-station/ocpp/OCPPIncomingRequestService.ts index b5880026..5b6819c0 100644 --- a/src/charging-station/ocpp/OCPPIncomingRequestService.ts +++ b/src/charging-station/ocpp/OCPPIncomingRequestService.ts @@ -67,6 +67,13 @@ export abstract class OCPPIncomingRequestService extends EventEmitter { return OCPPConstants.OCPP_RESPONSE_REJECTED } + /** + * Validates incoming request payload against JSON schema + * @param chargingStation - The charging station instance processing the request + * @param commandName - OCPP command name to validate against + * @param payload - JSON payload to validate + * @returns True if payload validation succeeds, false otherwise + */ // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters protected validateIncomingRequestPayload( chargingStation: ChargingStation, diff --git a/src/charging-station/ocpp/OCPPRequestService.ts b/src/charging-station/ocpp/OCPPRequestService.ts index 0d6d56b5..ed3a56d5 100644 --- a/src/charging-station/ocpp/OCPPRequestService.ts +++ b/src/charging-station/ocpp/OCPPRequestService.ts @@ -479,6 +479,13 @@ export abstract class OCPPRequestService { ) } + /** + * Validates outgoing request payload against JSON schema + * @param chargingStation - The charging station instance sending the request + * @param commandName - OCPP command name to validate against + * @param payload - JSON payload to validate + * @returns True if payload validation succeeds, false otherwise + */ // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters private validateRequestPayload( chargingStation: ChargingStation, @@ -490,7 +497,7 @@ export abstract class OCPPRequestService { } if (!this.payloadValidatorFunctions.has(commandName as RequestCommand)) { logger.warn( - `${chargingStation.logPrefix()} ${moduleName}.validateRequestPayload: No JSON schema found for command '${commandName}' PDU validation` + `${chargingStation.logPrefix()} ${moduleName}.validateRequestPayload: No JSON schema validation function found for command '${commandName}' PDU validation` ) return true } diff --git a/src/charging-station/ocpp/OCPPResponseService.ts b/src/charging-station/ocpp/OCPPResponseService.ts index d94bb33e..3c01181c 100644 --- a/src/charging-station/ocpp/OCPPResponseService.ts +++ b/src/charging-station/ocpp/OCPPResponseService.ts @@ -62,6 +62,13 @@ export abstract class OCPPResponseService { requestPayload: ReqType ): Promise + /** + * Validates incoming response payload against JSON schema + * @param chargingStation - The charging station instance receiving the response + * @param commandName - OCPP command name to validate against + * @param payload - JSON response payload to validate + * @returns True if payload validation succeeds, false otherwise + */ // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters protected validateResponsePayload( chargingStation: ChargingStation, diff --git a/src/charging-station/ocpp/OCPPServiceUtils.ts b/src/charging-station/ocpp/OCPPServiceUtils.ts index ec16a6b5..c83377c3 100644 --- a/src/charging-station/ocpp/OCPPServiceUtils.ts +++ b/src/charging-station/ocpp/OCPPServiceUtils.ts @@ -1766,6 +1766,31 @@ const getMeasurandDefaultUnit = ( } } +/** + * Utility class providing core OCPP (Open Charge Point Protocol) service functionality + * and common operations across all OCPP versions and protocol implementations. + * + * This class serves as the foundation for OCPP protocol handling, providing: + * - JSON schema-based payload validation using AJV (Another JSON Schema Validator) + * - Common OCPP operations like connector status management and transaction handling + * - Utility functions for meter value processing and ID tag authorization + * - Shared functionality between OCPP 1.6 and OCPP 2.0+ implementations + * + * Key Features: + * - **Schema Validation**: Centralized JSON schema loading and validation functions + * - **Protocol Agnostic**: Provides utilities that work across OCPP versions + * - **Transaction Management**: Utilities for transaction lifecycle and meter values + * - **Status Management**: Connector and charging station status operations + * - **Static Interface**: All functionality exposed as static methods for easy access + * + * Usage Pattern: + * This class is typically used by other OCPP service classes (incoming request services, + * response services) to perform common operations and validation. It acts as a shared + * utility layer that prevents code duplication across OCPP version-specific implementations. + * @see {@link parseJsonSchemaFile} Core JSON schema parsing functionality + * @see {@link validatePayload} Payload validation methods in service classes + */ + // eslint-disable-next-line @typescript-eslint/no-extraneous-class export class OCPPServiceUtils { public static readonly buildTransactionEndMeterValue = buildTransactionEndMeterValue @@ -1921,6 +1946,15 @@ export class OCPPServiceUtils { schemaDir, }) as const + /** + * Parses and loads a JSON schema file for OCPP payload validation + * Handles file reading, JSON parsing, and error recovery for schema validation + * @param relativePath - Path to the schema file relative to the OCPP utils directory + * @param ocppVersion - The OCPP version for error logging context + * @param moduleName - Optional module name for error logging + * @param methodName - Optional method name for error logging + * @returns Parsed JSON schema object or empty object if parsing fails + */ protected static parseJsonSchemaFile( relativePath: string, ocppVersion: OCPPVersion, -- 2.43.0