ocpp-rails 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4b1fb314e0058f03bfdb12510648169f54fb9ef2b66bd6a49d471cf2ed79a4f
-  data.tar.gz: 7ff5bf30b29c6a0ed9f9f131003b14db3691995a04803e0c8814a3bd227850c3
+  metadata.gz: 42e87a1079adc1b8d7641883fa8e57b21d07ff38a5b150dd231a64d637d37a47
+  data.tar.gz: f4fd46249622b68f30f035c99da715913219940eabb2dabdefc8e15255840a84
 SHA512:
-  metadata.gz: afecaf81715070d2728b49650b6c84dba24b78de7b518b176fac9f8c0d2446e08c92e7127a082f346d954286854a663961460bcce7b7f2f0788da607aa0cb971
-  data.tar.gz: c78be1531480bb503ac6e83b4a08ce708490b22daf8fd969482f7246d7d84c688eb1bc9b0c2dba856ae798296edae984ce5e7153c2bb24c2d97c7beec66fb511
+  metadata.gz: b103ecc7ed7e89acdd7aad80e93314cffe57f8c3fd84664a3cbd8da00e10a60f0a7e2b8c03870b27f58ee2fbf93e89b09f020e88db274a776a79d32b6a5f6f4f
+  data.tar.gz: 3880fb4073c68ece89623df6740b529684c7a71f284dab18b4080528418ba31d339cf00565de3039d867ec0e6d757322e26b4970ba73d27425dfc433e93cdb8d

data/README.md

@@ -24,7 +24,8 @@ OCPP message layer.
 ### OCPP Protocol Layer (What This Gem Provides)
 - 📡 **WebSocket Communication** - ActionCable channel handles bidirectional OCPP messages
 - 🔌 **Protocol Handlers** - BootNotification, Authorize, Heartbeat, StartTransaction, StopTransaction, MeterValues, StatusNotification
-- 🗄️ **Data Models** - ChargePoint, ChargingSession, MeterValue, Message (audit log)
+- 🗄️ **Data Models** - ChargePoint, ConnectorStatus, ChargingSession, MeterValue, Message (audit log)
+- 🪝 **Lifecycle Hooks** - authorization, state-change, and session-start/stop hooks (sync or async via ActiveJob) — react without polling
 - 🚀 **Remote Control Jobs** - RemoteStartTransaction, RemoteStopTransaction, UnlockConnector, Reset, ClearCache, GetConfiguration, ChangeConfiguration, ChangeAvailability
 - 📊 **Real-time Broadcasts** - ActionCable broadcasts for status, sessions, and meter values
 - 💾 **SQLite Compatible** - Works with async adapter, no Redis required for development
@@ -40,7 +41,7 @@ OCPP message layer.
 - ✅ **Core session flow** — inbound BootNotification, Authorize, Heartbeat, Start/StopTransaction, MeterValues, StatusNotification
 - ✅ **Remote Control** — RemoteStartTransaction, RemoteStopTransaction, UnlockConnector (delivery + end-to-end flow, tested)
 - ✅ **Message Audit** — every inbound/outbound frame logged for debugging and compliance
-- ✅ **Multi-connector** — one active session per connector, enforced at the DB level
+- ✅ **Multi-connector** — one active session per connector, enforced at the DB level; per-connector status tracked independently of whole-station status
 - 🚧 **Everything else** — see the honest, per-test-case [OCPP 1.6 Compliance Status](#-ocpp-16-compliance-status) below
 
 ## 📋 OCPP 1.6 Compliance Status
@@ -157,17 +158,25 @@ and the [Security Guide](docs/security.md).
 
 ### Monitor Charge Point Status
 
+`ChargePoint#status` is the whole-station status (from connector-0
+StatusNotifications: Available/Unavailable/Faulted) — it says nothing about
+any individual connector once a station has more than one.
+
 ```ruby
 # Query charge points
 connected_cps = Ocpp::Rails::ChargePoint.connected
 available_cps = Ocpp::Rails::ChargePoint.available
-charging_cps = Ocpp::Rails::ChargePoint.charging
+charging_cps = Ocpp::Rails::ChargePoint.charging  # any active session, any connector
 
 # Check specific charge point
 cp = Ocpp::Rails::ChargePoint.find_by(identifier: "CP001")
 cp.connected?       # => true/false
-cp.status           # => "Available", "Charging", etc.
+cp.status           # => whole-station status: "Available", "Unavailable", "Faulted"
 cp.last_heartbeat_at
+
+# Per-connector status (independent of any other connector on the same station)
+cp.connector_status(1)      # => "Available", "Charging", "SuspendedEV", ...
+cp.connector_charging?(1)   # => true/false, derived from active sessions
 ```
 
 ### Monitor Active Sessions
@@ -269,8 +278,12 @@ For complete implementation examples, see the [Remote Charging Guide](docs/remot
 
 - **`Ocpp::Rails::ChargePoint`** - Represents a physical charging station
   - Tracks connection status, firmware version, vendor info
-  - Has many charging sessions and meter values
-  - Provides status scopes (connected, available, charging)
+  - Has many charging sessions, connector statuses, and meter values
+  - Provides status scopes (connected, available, charging) and per-connector reads (`connector_status`, `connector_charging?`)
+
+- **`Ocpp::Rails::ConnectorStatus`** - Last reported status for one connector
+  - One row per `(charge_point, connector_id)`, written by StatusNotification
+  - Independent of whole-station status and of any other connector's activity
 
 - **`Ocpp::Rails::ChargingSession`** - Represents a charging transaction
   - Manages session lifecycle (active/completed)

data/app/jobs/ocpp/rails/session_async_hook_job.rb

@@ -0,0 +1,25 @@
+module Ocpp
+  module Rails
+    class SessionAsyncHookJob < ApplicationJob
+      queue_as :ocpp_hooks
+
+      retry_on StandardError, wait: :polynomially_longer, attempts: 3
+
+      def perform(charging_session_id, event, hook_class_name)
+        charging_session = Ocpp::Rails::ChargingSession.find_by(id: charging_session_id)
+
+        unless charging_session
+          ::Rails.logger.warn("ChargingSession #{charging_session_id} not found, may have been cleaned up")
+          return
+        end
+
+        hook_class = hook_class_name.constantize
+        hook = hook_class.new
+        hook.call(charging_session, event)
+      rescue => error
+        ::Rails.logger.error("SessionAsyncHook #{hook_class_name} failed for ChargingSession #{charging_session_id} (#{event}): #{error.message}")
+        raise
+      end
+    end
+  end
+end

data/app/models/ocpp/rails/charge_point.rb

@@ -4,6 +4,7 @@ module Ocpp
       self.table_name = "ocpp_charge_points"
 
       has_many :charging_sessions, dependent: :destroy, class_name: "Ocpp::Rails::ChargingSession"
+      has_many :connector_statuses, dependent: :destroy, class_name: "Ocpp::Rails::ConnectorStatus"
       has_many :meter_values, dependent: :destroy, class_name: "Ocpp::Rails::MeterValue"
       has_many :messages, dependent: :destroy, class_name: "Ocpp::Rails::Message"
       has_many :state_changes, dependent: :destroy, class_name: "Ocpp::Rails::StateChange"
@@ -14,7 +15,9 @@ module Ocpp
 
       scope :connected, -> { where(connected: true) }
       scope :available, -> { where(status: "Available") }
-      scope :charging, -> { where(status: "Charging") }
+      # Charging is a fact about sessions, not about ChargePoint#status
+      # (which only ever holds connector-0 values: Available/Unavailable/Faulted).
+      scope :charging, -> { joins(:charging_sessions).merge(Ocpp::Rails::ChargingSession.active).distinct }
 
       # Stores the station's Basic Auth password as a SHA-256 digest.
       # OCPP-J passwords are high-entropy machine credentials (the spec
@@ -64,6 +67,23 @@ module Ocpp
       def available?
         status == "Available" && connected?
       end
+
+      # Last status the station reported for this connector via
+      # StatusNotification; nil until the connector has reported once.
+      def connector_status(connector_id)
+        connector_statuses.find_by(connector_id: connector_id)&.status
+      end
+
+      def connector_error_code(connector_id)
+        connector_statuses.find_by(connector_id: connector_id)&.error_code
+      end
+
+      # Whether a transaction is running on the connector. Authoritative by
+      # definition, unlike connector_status which is only as fresh as the
+      # station's last StatusNotification.
+      def connector_charging?(connector_id)
+        charging_sessions.active.where(connector_id: connector_id).exists?
+      end
     end
   end
 end

data/app/models/ocpp/rails/connector_status.rb

@@ -0,0 +1,16 @@
+module Ocpp
+  module Rails
+    class ConnectorStatus < ApplicationRecord
+      self.table_name = "ocpp_connector_statuses"
+
+      belongs_to :charge_point, class_name: "Ocpp::Rails::ChargePoint"
+
+      # Connector 0 (the charge point main controller) is tracked on
+      # ChargePoint#status, never here.
+      validates :connector_id, presence: true,
+        numericality: { greater_than_or_equal_to: 1, only_integer: true },
+        uniqueness: { scope: :charge_point_id }
+      validates :status, presence: true
+    end
+  end
+end

data/app/services/ocpp/rails/actions/start_transaction_handler.rb

@@ -51,8 +51,12 @@ module Ocpp
 
           ::Rails.logger.info("[OCPP] StartTransaction from #{@charge_point.identifier}: Connector #{@payload['connectorId']}, Transaction ID: #{session.transaction_id}")
 
-          # Update charge point status
-          @charge_point.update(status: "Charging")
+          # Connector status is owned by StatusNotification (OCPP 1.6); a
+          # transaction starting says nothing about ChargePoint#status.
+
+          # Duplicate/replayed StartTransactions resume the open session
+          # above and intentionally do not re-fire this hook.
+          Ocpp::Rails::SessionHookManager.execute_hooks(session, "started")
 
           # Broadcast session started event for real-time UI updates
           broadcast_session_started(session)

data/app/services/ocpp/rails/actions/status_notification_handler.rb

@@ -43,13 +43,9 @@ module Ocpp
         private
 
         def update_connector_status(connector_id, status, error_code)
-          metadata = @charge_point.metadata || {}
-          old_status = metadata["connector_#{connector_id}_status"]
-
-          metadata["connector_#{connector_id}_status"] = status
-          metadata["connector_#{connector_id}_error_code"] = error_code if error_code
-          metadata["connector_#{connector_id}_updated_at"] = Time.current.iso8601
-          @charge_point.update(metadata: metadata)
+          record = @charge_point.connector_statuses.find_or_initialize_by(connector_id: connector_id)
+          old_status = record.status
+          record.update!(status: status, error_code: error_code)
 
           # Log state change if status actually changed
           log_status_change(connector_id, old_status, status, {

data/app/services/ocpp/rails/actions/stop_transaction_handler.rb

@@ -34,10 +34,13 @@ module Ocpp
             process_transaction_data(session, @payload["transactionData"])
           end
 
-          # Update charge point status if no other active sessions
-          if @charge_point.charging_sessions.active.empty?
-            @charge_point.update(status: "Available")
-          end
+          # Connector status is owned by StatusNotification (OCPP 1.6); the
+          # station reports Finishing/Available itself after the transaction.
+
+          # Fired after transactionData so hooks see the Transaction.End
+          # meter values. Stations recovering from an offline period may
+          # still deliver queued MeterValues after this point.
+          Ocpp::Rails::SessionHookManager.execute_hooks(session, "stopped")
 
           # Broadcast session stopped event for real-time UI updates
           broadcast_session_stopped(session)

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

@@ -0,0 +1,37 @@
+module Ocpp
+  module Rails
+    # Moves per-connector status from the pre-0.3.0 metadata convention
+    # (connector_<n>_status / _error_code / _updated_at keys on
+    # ChargePoint#metadata) into the ocpp_connector_statuses table.
+    # Idempotent; rows the station has written since the upgrade win over
+    # legacy metadata.
+    module ConnectorStatusBackfill
+      LEGACY_KEY = /\Aconnector_(\d+)_(status|error_code|updated_at)\z/
+
+      def self.run
+        Ocpp::Rails::ChargePoint.find_each do |charge_point|
+          metadata = charge_point.metadata || {}
+          legacy = metadata.select { |key, _| key.to_s.match?(LEGACY_KEY) }
+          next if legacy.empty?
+
+          connector_ids(legacy).each do |connector_id|
+            status = legacy["connector_#{connector_id}_status"]
+            next unless status
+
+            record = charge_point.connector_statuses.find_or_initialize_by(connector_id: connector_id)
+            next if record.persisted?
+
+            record.update!(status: status, error_code: legacy["connector_#{connector_id}_error_code"])
+          end
+
+          charge_point.update!(metadata: metadata.except(*legacy.keys))
+        end
+      end
+
+      def self.connector_ids(legacy)
+        legacy.keys.filter_map { |key| key.to_s[LEGACY_KEY, 1]&.to_i }.uniq
+      end
+      private_class_method :connector_ids
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module Ocpp
+  module Rails
+    module SessionHookManager
+      EVENTS = [ "started", "stopped" ].freeze
+
+      def self.execute_hooks(charging_session, event)
+        hooks = Ocpp::Rails.configuration.session_hooks
+
+        hooks.each do |hook|
+          begin
+            if hook.respond_to?(:async?) && hook.async?
+              # Enqueue async hook job
+              Ocpp::Rails::SessionAsyncHookJob.perform_later(charging_session.id, event, hook.class.name)
+            else
+              # Execute synchronously
+              hook.call(charging_session, event)
+            end
+          rescue => error
+            ::Rails.logger.error("SessionHook #{hook.class.name} failed: #{error.message}")
+            ::Rails.logger.error(error.backtrace.join("\n"))
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/db/migrate/20260711000000_create_ocpp_connector_statuses.rb

@@ -0,0 +1,13 @@
+class CreateOcppConnectorStatuses < ActiveRecord::Migration[8.0]
+  def change
+    create_table :ocpp_connector_statuses do |t|
+      t.references :charge_point, null: false, foreign_key: { to_table: :ocpp_charge_points }
+      t.integer :connector_id, null: false
+      t.string :status, null: false
+      t.string :error_code
+      t.timestamps
+    end
+
+    add_index :ocpp_connector_statuses, [ :charge_point_id, :connector_id ], unique: true
+  end
+end

data/db/migrate/20260711000001_backfill_ocpp_connector_statuses.rb

@@ -0,0 +1,9 @@
+class BackfillOcppConnectorStatuses < ActiveRecord::Migration[8.0]
+  def up
+    Ocpp::Rails::ConnectorStatusBackfill.run
+  end
+
+  def down
+    # Data-only migration; the legacy metadata keys are not restored.
+  end
+end

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

@@ -23,6 +23,8 @@ module Ocpp
           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"
+          sleep 1
+          migration_template "create_ocpp_connector_statuses.rb", "db/migrate/create_ocpp_connector_statuses.rb"
         end
 
         def mount_engine

data/lib/generators/ocpp/rails/templates/create_ocpp_connector_statuses.rb

@@ -0,0 +1,13 @@
+class CreateOcppConnectorStatuses < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :ocpp_connector_statuses do |t|
+      t.references :charge_point, null: false, foreign_key: { to_table: :ocpp_charge_points }
+      t.integer :connector_id, null: false
+      t.string :status, null: false
+      t.string :error_code
+      t.timestamps
+    end
+
+    add_index :ocpp_connector_statuses, [ :charge_point_id, :connector_id ], unique: true
+  end
+end

data/lib/generators/ocpp/rails/templates/ocpp_rails.rb

@@ -10,4 +10,11 @@ Ocpp::Rails.setup do |config|
 
   # Connection timeout in seconds
   config.connection_timeout = 30
+
+  # Session lifecycle hooks: objects responding to
+  # call(charging_session, event) with event "started" or "stopped".
+  # Define async? => true on a hook to run it via ActiveJob instead of
+  # inline. Example:
+  #
+  #   config.register_session_hook(MySessionHook.new)
 end

data/lib/ocpp/rails/version.rb

@@ -1,5 +1,5 @@
 module Ocpp
   module Rails
-    VERSION = "0.2.4"
+    VERSION = "0.3.0"
   end
 end

data/lib/ocpp/rails.rb

@@ -36,7 +36,7 @@ module Ocpp
       attr_accessor :ocpp_version, :supported_versions, :heartbeat_interval, :connection_timeout,
                     :state_change_hooks, :state_change_retention_days, :state_change_cleanup_enabled,
                     :authorization_hooks, :authorization_retention_days, :authorization_cleanup_enabled,
-                    :implausible_energy_jump_wh, :authentication_mode,
+                    :session_hooks, :implausible_energy_jump_wh, :authentication_mode,
                     :max_messages_per_minute, :max_connection_attempts_per_minute
 
       def initialize
@@ -47,6 +47,7 @@ module Ocpp
         @connection_timeout = 30
         @state_change_hooks = []
         @authorization_hooks = []
+        @session_hooks = []
         @state_change_retention_days = 30
         @state_change_cleanup_enabled = true
         @authorization_retention_days = 30
@@ -77,6 +78,13 @@ module Ocpp
         end
         @authorization_hooks << hook
       end
+
+      def register_session_hook(hook)
+        unless hook.respond_to?(:call)
+          raise ArgumentError, "Hook must respond to :call method"
+        end
+        @session_hooks << hook
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ocpp-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Jakob Sommerhuber
@@ -119,12 +119,14 @@ files:
 - app/jobs/ocpp/rails/remote_start_transaction_job.rb
 - app/jobs/ocpp/rails/remote_stop_transaction_job.rb
 - app/jobs/ocpp/rails/reset_job.rb
+- app/jobs/ocpp/rails/session_async_hook_job.rb
 - app/jobs/ocpp/rails/unlock_connector_job.rb
 - app/mailers/ocpp/rails/application_mailer.rb
 - app/models/ocpp/rails/application_record.rb
 - app/models/ocpp/rails/authorization.rb
 - app/models/ocpp/rails/charge_point.rb
 - app/models/ocpp/rails/charging_session.rb
+- app/models/ocpp/rails/connector_status.rb
 - app/models/ocpp/rails/message.rb
 - app/models/ocpp/rails/meter_value.rb
 - app/models/ocpp/rails/state_change.rb
@@ -136,10 +138,12 @@ files:
 - app/services/ocpp/rails/actions/status_notification_handler.rb
 - app/services/ocpp/rails/actions/stop_transaction_handler.rb
 - app/services/ocpp/rails/authorization_hook_manager.rb
+- app/services/ocpp/rails/connector_status_backfill.rb
 - app/services/ocpp/rails/message_handler.rb
 - app/services/ocpp/rails/meter_anomaly_detector.rb
 - app/services/ocpp/rails/protocol.rb
 - app/services/ocpp/rails/rate_limiter.rb
+- app/services/ocpp/rails/session_hook_manager.rb
 - app/services/ocpp/rails/state_change_hook_manager.rb
 - app/services/ocpp/rails/station_authenticator.rb
 - app/services/ocpp/rails/timestamp_parser.rb
@@ -153,10 +157,13 @@ files:
 - db/migrate/20260707000002_add_active_session_guard_to_ocpp_charging_sessions.rb
 - db/migrate/20260707000003_add_anomaly_flags_to_ocpp_meter_values.rb
 - db/migrate/20260707000004_add_auth_password_digest_to_ocpp_charge_points.rb
+- db/migrate/20260711000000_create_ocpp_connector_statuses.rb
+- db/migrate/20260711000001_backfill_ocpp_connector_statuses.rb
 - lib/generators/ocpp/rails/install_generator.rb
 - lib/generators/ocpp/rails/templates/README
 - lib/generators/ocpp/rails/templates/create_ocpp_charge_points.rb
 - lib/generators/ocpp/rails/templates/create_ocpp_charging_sessions.rb
+- lib/generators/ocpp/rails/templates/create_ocpp_connector_statuses.rb
 - lib/generators/ocpp/rails/templates/create_ocpp_messages.rb
 - lib/generators/ocpp/rails/templates/create_ocpp_meter_values.rb
 - lib/generators/ocpp/rails/templates/ocpp_rails.rb