ocpp-rails 0.2.4

data/app/services/ocpp/rails/message_handler.rb

@@ -0,0 +1,153 @@
+module Ocpp
+  module Rails
+    class MessageHandler
+      attr_reader :charge_point, :raw_message
+
+      def initialize(charge_point, raw_message)
+        @charge_point = charge_point
+        @raw_message = raw_message
+      end
+
+      def process
+        parsed = Protocol.parse(raw_message)
+
+        case parsed[:type]
+        when "CALL"
+          handle_call(parsed)
+        when "CALLRESULT"
+          handle_callresult(parsed)
+        when "CALLERROR"
+          handle_callerror(parsed)
+        when "PARSE_ERROR"
+          log_error("Failed to parse message: #{parsed[:error]}")
+          send_callerror(SecureRandom.uuid, "FormationViolation", "Invalid JSON format")
+        when "UNKNOWN"
+          log_error("Unknown message type: #{parsed[:raw]}")
+          send_callerror(SecureRandom.uuid, "ProtocolError", "Unknown message type")
+        end
+      rescue => e
+        send_internal_error(parsed && parsed[:message_id], e, "Error processing message")
+      end
+
+      private
+
+      # Never place exception details in the CALLERROR sent to the station;
+      # log them server-side under a reference the station response carries.
+      def send_internal_error(message_id, exception, context)
+        error_ref = SecureRandom.hex(8)
+        log_error("#{context} (ref #{error_ref}): #{exception.class}: #{exception.message}")
+        log_error(exception.backtrace.join("\n")) if exception.backtrace
+        send_callerror(
+          message_id || SecureRandom.uuid,
+          "InternalError",
+          "An internal error occurred",
+          { "errorRef" => error_ref }
+        )
+      end
+
+      def handle_call(parsed)
+        # Log incoming message
+        log_message(parsed, "inbound", "CALL")
+
+        # Route to appropriate handler
+        handler_class_name = "Ocpp::Rails::Actions::#{parsed[:action]}Handler"
+
+        begin
+          handler_class = handler_class_name.constantize
+        rescue NameError
+          send_callerror(parsed[:message_id], "NotSupported", "Action #{parsed[:action]} not supported")
+          return
+        end
+
+        handler = handler_class.new(charge_point, parsed[:message_id], parsed[:payload])
+        response = handler.call
+        send_callresult(parsed[:message_id], response)
+      rescue => e
+        send_internal_error(parsed[:message_id], e, "Error in #{parsed[:action]} handler")
+      end
+
+      def handle_callresult(parsed)
+        # Update pending outbound message with successful response
+        message = Message.find_by(
+          charge_point: charge_point,
+          message_id: parsed[:message_id],
+          direction: "outbound",
+          status: "pending"
+        )
+
+        if message
+          message.update(
+            status: "received",
+            payload: message.payload.merge(response: parsed[:payload])
+          )
+          log_info("Received CALLRESULT for #{message.action}")
+        else
+          log_warn("Received CALLRESULT for unknown message_id: #{parsed[:message_id]}")
+        end
+      end
+
+      def handle_callerror(parsed)
+        # Update pending outbound message with error response
+        message = Message.find_by(
+          charge_point: charge_point,
+          message_id: parsed[:message_id],
+          direction: "outbound",
+          status: "pending"
+        )
+
+        if message
+          message.update(
+            status: "error",
+            error_message: "#{parsed[:error_code]}: #{parsed[:error_description]}",
+            payload: message.payload.merge(error_details: parsed[:details])
+          )
+          log_error("Received CALLERROR for #{message.action}: #{parsed[:error_code]}")
+        else
+          log_warn("Received CALLERROR for unknown message_id: #{parsed[:message_id]}")
+        end
+      end
+
+      def send_callresult(message_id, payload)
+        response = Protocol.build_callresult(message_id, payload)
+        ChargePointChannel.broadcast_to(charge_point, { message: response })
+        log_message({ message_id: message_id, payload: payload }, "outbound", "CALLRESULT")
+      end
+
+      def send_callerror(message_id, error_code, error_description, details = {})
+        response = Protocol.build_callerror(message_id, error_code, error_description, details)
+        ChargePointChannel.broadcast_to(charge_point, { message: response })
+        log_message(
+          { message_id: message_id, error_code: error_code, error_description: error_description },
+          "outbound",
+          "CALLERROR"
+        )
+      end
+
+      def log_message(parsed, direction, message_type)
+        Message.create!(
+          charge_point: charge_point,
+          message_id: parsed[:message_id],
+          direction: direction,
+          action: parsed[:action],
+          message_type: message_type,
+          payload: parsed[:payload] || parsed[:error_code] || {},
+          status: direction == "inbound" ? "received" : "sent"
+        )
+      rescue => e
+        log_error("Failed to log message: #{e.message}")
+      end
+
+      def log_error(message)
+        ::Rails.logger.error("[OCPP] ChargePoint #{charge_point.identifier}: #{message}")
+      end
+
+      def log_warn(message)
+        ::Rails.logger.warn("[OCPP] ChargePoint #{charge_point.identifier}: #{message}")
+      end
+
+      def log_info(message)
+        ::Rails.logger.info("[OCPP] ChargePoint #{charge_point.identifier}: #{message}")
+      end
+    end
+  end
+end

data/app/services/ocpp/rails/meter_anomaly_detector.rb

@@ -0,0 +1,50 @@
+module Ocpp
+  module Rails
+    # Checks Energy.Active.Import.Register readings against the session's
+    # series: the register must never decrease (rollover, meter swap) and
+    # must not jump implausibly between samples. Anomalous readings are
+    # flagged for review instead of silently entering energy accounting.
+    module MeterAnomalyDetector
+      ENERGY_MEASURAND = "Energy.Active.Import.Register".freeze
+
+      REGISTER_DECREASE = "register_decrease".freeze
+      IMPLAUSIBLE_JUMP = "implausible_jump".freeze
+
+      # Returns a flag reason string, or nil when the reading is plausible.
+      def self.check(session:, measurand:, value:, unit:)
+        return nil unless session && measurand == ENERGY_MEASURAND
+
+        candidate = normalize_to_wh(value, unit)
+        return nil unless candidate
+
+        baseline = baseline_wh(session)
+        return nil unless baseline
+
+        max_jump = Ocpp::Rails.configuration.implausible_energy_jump_wh
+        if candidate < baseline
+          REGISTER_DECREASE
+        elsif max_jump && candidate - baseline > max_jump
+          IMPLAUSIBLE_JUMP
+        end
+      end
+
+      def self.normalize_to_wh(value, unit)
+        return nil if value.nil?
+
+        wh = BigDecimal(value.to_s)
+        unit == "kWh" ? wh * 1000 : wh
+      rescue ArgumentError
+        nil
+      end
+
+      # Highest trustworthy register reading seen so far: meterStart plus all
+      # previously accepted (unflagged) energy samples, normalised to Wh.
+      def self.baseline_wh(session)
+        previous = session.meter_values.energy.where(flagged: false).maximum(
+          Arel.sql("CASE WHEN unit = 'kWh' THEN value * 1000 ELSE value END")
+        )
+        [ previous, session.start_meter_value ].compact.max
+      end
+    end
+  end
+end

data/app/services/ocpp/rails/protocol.rb

@@ -0,0 +1,65 @@
+module Ocpp
+  module Rails
+    module Protocol
+      class << self
+        # Build a CALL message (request from server to charge point or charge point to server)
+        # Format: [2, "message_id", "Action", {payload}]
+        def build_call(message_id, action, payload)
+          [ 2, message_id, action, payload ].to_json
+        end
+
+        # Build a CALLRESULT message (successful response)
+        # Format: [3, "message_id", {payload}]
+        def build_callresult(message_id, payload)
+          [ 3, message_id, payload ].to_json
+        end
+
+        # Build a CALLERROR message (error response)
+        # Format: [4, "message_id", "error_code", "error_description", {details}]
+        def build_callerror(message_id, error_code, error_description, details = {})
+          [ 4, message_id, error_code, error_description, details ].to_json
+        end
+
+        # Parse incoming JSON-RPC 2.0 message
+        def parse(raw_message)
+          data = JSON.parse(raw_message)
+
+          case data[0]
+          when 2
+            {
+              type: "CALL",
+              message_id: data[1],
+              action: data[2],
+              payload: data[3] || {}
+            }
+          when 3
+            {
+              type: "CALLRESULT",
+              message_id: data[1],
+              payload: data[2] || {}
+            }
+          when 4
+            {
+              type: "CALLERROR",
+              message_id: data[1],
+              error_code: data[2],
+              error_description: data[3],
+              details: data[4] || {}
+            }
+          else
+            {
+              type: "UNKNOWN",
+              raw: data
+            }
+          end
+        rescue JSON::ParserError => e
+          {
+            type: "PARSE_ERROR",
+            error: e.message,
+            raw: raw_message
+          }
+        end
+      end
+    end
+  end
+end

data/app/services/ocpp/rails/rate_limiter.rb

@@ -0,0 +1,53 @@
+module Ocpp
+  module Rails
+    # Fixed-window rate limiter keyed by station identifier. The limit is
+    # re-read from the block on every call so configuration changes apply
+    # immediately; a nil limit disables throttling.
+    #
+    # State is in-process: in multi-server deployments each node applies
+    # the limit independently, so treat the configured value as per node.
+    class RateLimiter
+      PRUNE_THRESHOLD = 1_000
+
+      def initialize(window: 60, &limit)
+        @window = window
+        @limit = limit
+        @mutex = Mutex.new
+        @windows = {}
+      end
+
+      # Returns true when the event for this key is within the limit.
+      def allow?(key, now: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+        limit = @limit.call
+        return true if limit.nil?
+
+        @mutex.synchronize do
+          prune(now) if @windows.size > PRUNE_THRESHOLD
+
+          started_at, count = @windows[key]
+          if started_at.nil? || now - started_at >= @window
+            @windows[key] = [ now, 1 ]
+            true
+          elsif count < limit
+            @windows[key][1] += 1
+            true
+          else
+            false
+          end
+        end
+      end
+
+      def reset!
+        @mutex.synchronize { @windows.clear }
+      end
+
+      private
+
+      # Drop expired windows so one-off keys (e.g. unknown identifiers
+      # hammering the endpoint) cannot grow the map unboundedly.
+      def prune(now)
+        @windows.delete_if { |_key, (started_at, _count)| now - started_at >= @window }
+      end
+    end
+  end
+end

data/app/services/ocpp/rails/state_change_hook_manager.rb

@@ -0,0 +1,26 @@
+module Ocpp
+  module Rails
+    module StateChangeHookManager
+      def self.execute_hooks(state_change)
+        hooks = Ocpp::Rails.configuration.state_change_hooks
+
+        hooks.each do |hook|
+          begin
+            if hook.respond_to?(:async?) && hook.async?
+              # Enqueue async hook job
+              Ocpp::Rails::AsyncHookJob.perform_later(state_change.id, hook.class.name)
+            else
+              # Execute synchronously
+              hook.call(state_change)
+            end
+          rescue => error
+            ::Rails.logger.error("StateChangeHook #{hook.class.name} failed: #{error.message}")
+            ::Rails.logger.error(error.backtrace.join("\n"))
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/app/services/ocpp/rails/station_authenticator.rb

@@ -0,0 +1,46 @@
+module Ocpp
+  module Rails
+    # OCPP-J Security Profile 1: HTTP Basic Auth on the WebSocket upgrade.
+    # The username must equal the charge point identity and the password must
+    # match the per-station credential stored (hashed) on the ChargePoint.
+    # Profile 2 additionally requires TLS, terminated in front of the app.
+    module StationAuthenticator
+      Result = Struct.new(:charge_point, :failure) do
+        def success?
+          failure.nil?
+        end
+      end
+
+      def self.authenticate(identifier:, authorization_header:)
+        charge_point = ChargePoint.find_by(identifier: identifier)
+        return failure(:unknown_charge_point) unless charge_point
+
+        return Result.new(charge_point, nil) if Ocpp::Rails.configuration.authentication_mode == :none
+
+        username, password = decode_basic(authorization_header)
+        return failure(:missing_credentials) if username.nil?
+
+        # OCPP-J requires the Basic Auth username to equal the station identity
+        return failure(:identity_mismatch) unless username == identifier
+        return failure(:no_credential_configured) if charge_point.auth_password_digest.blank?
+        return failure(:invalid_credentials) unless charge_point.authenticate_password?(password)
+
+        Result.new(charge_point, nil)
+      end
+
+      def self.decode_basic(header)
+        return nil unless header.is_a?(String) && header.start_with?("Basic ")
+
+        decoded = Base64.strict_decode64(header.delete_prefix("Basic "))
+        decoded.split(":", 2)
+      rescue ArgumentError
+        nil
+      end
+
+      def self.failure(reason)
+        Result.new(nil, reason)
+      end
+      private_class_method :failure
+    end
+  end
+end

data/app/services/ocpp/rails/timestamp_parser.rb

@@ -0,0 +1,25 @@
+module Ocpp
+  module Rails
+    # Parses station-provided OCPP timestamps without hiding failures:
+    # a value that cannot be parsed falls back to server receive time,
+    # but the result is marked so the record can be flagged instead of
+    # silently entering the time series as fabricated data.
+    module TimestampParser
+      SOURCE_STATION = "station".freeze
+      SOURCE_SERVER_FALLBACK = "server_fallback".freeze
+
+      Result = Struct.new(:time, :source, :raw, keyword_init: true) do
+        def server_fallback?
+          source == SOURCE_SERVER_FALLBACK
+        end
+      end
+
+      def self.parse(raw)
+        Result.new(time: Time.parse(raw), source: SOURCE_STATION, raw: raw)
+      rescue ArgumentError, TypeError
+        ::Rails.logger.warn("[OCPP] Unparseable timestamp #{raw.inspect}; falling back to server time")
+        Result.new(time: Time.current, source: SOURCE_SERVER_FALLBACK, raw: raw)
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+Ocpp::Rails::Engine.routes.draw do
+  # OCPP WebSocket endpoint via ActionCable
+  # Charge points connect to: ws://your-host/ocpp/cable
+  mount ActionCable.server => "/cable"
+end

data/db/migrate/20251008162902_create_ocpp_models.rb

@@ -0,0 +1,77 @@
+class CreateOcppModels < ActiveRecord::Migration[8.0]
+  def change
+    # Charge Points
+    create_table :ocpp_charge_points do |t|
+      t.string :identifier, null: false, index: { unique: true }
+      t.string :vendor
+      t.string :model
+      t.string :serial_number
+      t.string :firmware_version
+      t.string :iccid
+      t.string :imsi
+      t.string :meter_type
+      t.string :meter_serial_number
+      t.string :ocpp_protocol, default: "1.6"
+      t.string :status, default: "Available"
+      t.datetime :last_heartbeat_at
+      t.boolean :connected, default: false
+      t.json :metadata, default: {}
+      t.timestamps
+    end
+
+    # Charge Sessions
+    create_table :ocpp_charging_sessions do |t|
+      t.references :charge_point, null: false, foreign_key: { to_table: :ocpp_charge_points }
+      t.integer :connector_id, null: false
+      t.string :transaction_id, index: { unique: true }
+      t.string :id_tag
+      t.string :status, default: "Preparing"
+      t.datetime :started_at
+      t.datetime :stopped_at
+      t.decimal :start_meter_value, precision: 10, scale: 2
+      t.decimal :stop_meter_value, precision: 10, scale: 2
+      t.decimal :energy_consumed, precision: 10, scale: 2
+      t.integer :duration_seconds
+      t.string :stop_reason
+      t.json :metadata, default: {}
+      t.timestamps
+    end
+
+    add_index :ocpp_charging_sessions, [ :charge_point_id, :connector_id ]
+
+    # Meter Values
+    create_table :ocpp_meter_values do |t|
+      t.references :charging_session, null: true, foreign_key: { to_table: :ocpp_charging_sessions }
+      t.references :charge_point, null: false, foreign_key: { to_table: :ocpp_charge_points }
+      t.integer :connector_id
+      t.string :measurand
+      t.string :phase
+      t.string :unit
+      t.string :context
+      t.string :format
+      t.string :location
+      t.decimal :value, precision: 15, scale: 4
+      t.datetime :timestamp
+      t.timestamps
+    end
+
+    add_index :ocpp_meter_values, :measurand
+    add_index :ocpp_meter_values, :timestamp
+
+    # Messages
+    create_table :ocpp_messages do |t|
+      t.references :charge_point, null: false, foreign_key: { to_table: :ocpp_charge_points }
+      t.string :message_id, null: false
+      t.string :direction, null: false # inbound, outbound
+      t.string :action
+      t.string :message_type # CALL, CALLRESULT, CALLERROR
+      t.json :payload, default: {}
+      t.string :status # pending, sent, received, error
+      t.text :error_message
+      t.timestamps
+    end
+
+    add_index :ocpp_messages, :message_id
+    add_index :ocpp_messages, [ :charge_point_id, :created_at ]
+  end
+end

data/db/migrate/20251015190754_make_charging_session_id_nullable_in_meter_values.rb

@@ -0,0 +1,5 @@
+class MakeChargingSessionIdNullableInMeterValues < ActiveRecord::Migration[8.0]
+  def change
+    change_column_null :ocpp_meter_values, :charging_session_id, true
+  end
+end

data/db/migrate/20251016000000_create_ocpp_state_changes.rb

@@ -0,0 +1,17 @@
+class CreateOcppStateChanges < ActiveRecord::Migration[8.0]
+  def change
+    create_table :ocpp_state_changes do |t|
+      t.references :charge_point, null: false, foreign_key: { to_table: :ocpp_charge_points, on_delete: :cascade }
+      t.string :change_type, null: false
+      t.integer :connector_id
+      t.string :old_value
+      t.string :new_value, null: false
+      t.json :metadata, default: {}
+      t.timestamps
+    end
+
+    add_index :ocpp_state_changes, [ :charge_point_id, :created_at ]
+    add_index :ocpp_state_changes, [ :change_type, :created_at ]
+    add_index :ocpp_state_changes, :created_at
+  end
+end

data/db/migrate/20251017000000_create_ocpp_authorizations.rb

@@ -0,0 +1,15 @@
+class CreateOcppAuthorizations < ActiveRecord::Migration[8.0]
+  def change
+    create_table :ocpp_authorizations do |t|
+      t.references :charge_point, null: false, foreign_key: { to_table: :ocpp_charge_points, on_delete: :cascade }
+      t.string :id_tag, null: false
+      t.string :status, null: false
+      t.datetime :expiry_date
+
+      t.timestamps
+    end
+
+    add_index :ocpp_authorizations, :id_tag
+    add_index :ocpp_authorizations, :created_at
+  end
+end

data/db/migrate/20260707000000_add_timestamp_provenance_to_ocpp_meter_values.rb

@@ -0,0 +1,6 @@
+class AddTimestampProvenanceToOcppMeterValues < ActiveRecord::Migration[8.0]
+  def change
+    add_column :ocpp_meter_values, :raw_timestamp, :string
+    add_column :ocpp_meter_values, :timestamp_source, :string, default: "station", null: false
+  end
+end

data/db/migrate/20260707000001_convert_ocpp_transaction_id_to_integer.rb

@@ -0,0 +1,19 @@
+class ConvertOcppTransactionIdToInteger < ActiveRecord::Migration[8.0]
+  # The old string column held internally generated UUIDs that were never
+  # sent on the wire (handlers used the AR primary key instead), so the
+  # values are safe to drop. OCPP 1.6 requires an integer transactionId,
+  # managed by the central system and decoupled from the primary key.
+  def up
+    remove_index :ocpp_charging_sessions, :transaction_id
+    remove_column :ocpp_charging_sessions, :transaction_id
+    add_column :ocpp_charging_sessions, :transaction_id, :bigint
+    add_index :ocpp_charging_sessions, :transaction_id, unique: true
+  end
+
+  def down
+    remove_index :ocpp_charging_sessions, :transaction_id
+    remove_column :ocpp_charging_sessions, :transaction_id
+    add_column :ocpp_charging_sessions, :transaction_id, :string
+    add_index :ocpp_charging_sessions, :transaction_id, unique: true
+  end
+end

data/db/migrate/20260707000002_add_active_session_guard_to_ocpp_charging_sessions.rb

@@ -0,0 +1,11 @@
+class AddActiveSessionGuardToOcppChargingSessions < ActiveRecord::Migration[8.0]
+  # At most one non-stopped session per (charge point, connector), enforced
+  # at the database so duplicate/racing StartTransaction messages cannot open
+  # concurrent sessions. Partial indexes are supported by SQLite and Postgres.
+  def change
+    add_index :ocpp_charging_sessions, [ :charge_point_id, :connector_id ],
+      unique: true,
+      where: "stopped_at IS NULL",
+      name: "index_ocpp_one_active_session_per_connector"
+  end
+end

data/db/migrate/20260707000003_add_anomaly_flags_to_ocpp_meter_values.rb

@@ -0,0 +1,6 @@
+class AddAnomalyFlagsToOcppMeterValues < ActiveRecord::Migration[8.0]
+  def change
+    add_column :ocpp_meter_values, :flagged, :boolean, default: false, null: false
+    add_column :ocpp_meter_values, :flag_reason, :string
+  end
+end

data/db/migrate/20260707000004_add_auth_password_digest_to_ocpp_charge_points.rb

@@ -0,0 +1,5 @@
+class AddAuthPasswordDigestToOcppChargePoints < ActiveRecord::Migration[8.0]
+  def change
+    add_column :ocpp_charge_points, :auth_password_digest, :string
+  end
+end

data/lib/generators/ocpp/rails/install_generator.rb

@@ -0,0 +1,42 @@
+require "rails/generators"
+require "rails/generators/migration"
+
+module Ocpp
+  module Rails
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        include ::Rails::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Installs Ocpp::Rails into your application"
+
+        def self.next_migration_number(path)
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        end
+
+        def copy_migrations
+          migration_template "create_ocpp_charge_points.rb", "db/migrate/create_ocpp_charge_points.rb"
+          sleep 1
+          migration_template "create_ocpp_charging_sessions.rb", "db/migrate/create_ocpp_charging_sessions.rb"
+          sleep 1
+          migration_template "create_ocpp_meter_values.rb", "db/migrate/create_ocpp_meter_values.rb"
+          sleep 1
+          migration_template "create_ocpp_messages.rb", "db/migrate/create_ocpp_messages.rb"
+        end
+
+        def mount_engine
+          route "mount Ocpp::Rails::Engine => '/ocpp'"
+        end
+
+        def create_initializer
+          template "ocpp_rails.rb", "config/initializers/ocpp_rails.rb"
+        end
+
+        def show_readme
+          readme "README" if behavior == :invoke
+        end
+      end
+    end
+  end
+end