ocpp-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42e87a1079adc1b8d7641883fa8e57b21d07ff38a5b150dd231a64d637d37a47
-  data.tar.gz: f4fd46249622b68f30f035c99da715913219940eabb2dabdefc8e15255840a84
+  metadata.gz: ec3b88d04d4b69372c6ca9dadf03a43053e54788a79eef1374a2dbec1992ef45
+  data.tar.gz: e4f9453a7e00727790f1af2b2998a8f177e93d75036c9870e96f7b6dee0ee90e
 SHA512:
-  metadata.gz: b103ecc7ed7e89acdd7aad80e93314cffe57f8c3fd84664a3cbd8da00e10a60f0a7e2b8c03870b27f58ee2fbf93e89b09f020e88db274a776a79d32b6a5f6f4f
-  data.tar.gz: 3880fb4073c68ece89623df6740b529684c7a71f284dab18b4080528418ba31d339cf00565de3039d867ec0e6d757322e26b4970ba73d27425dfc433e93cdb8d
+  metadata.gz: fb468229c8aad08762333d4b55693bb6d1fdd3934fb9b36777380dd4d923499a76d28d8dd4a02ae089891e54ccaef0d94e5354be1e2cd4a37ed8d91a830a1405
+  data.tar.gz: '0079e806237f2e081ef026ca594ba9d4a9f49793aa065be8cb4d1a5b288357b48853b60f084bd24096d6ee400e8060d57d7187916a49859c5d015f7cd3ebd3af'

data/README.md

@@ -138,19 +138,41 @@ Ocpp::Rails.setup do |config|
 end
 ```
 
-**Charge points connect to:**
-```
-ws://your-server:3000/ocpp/cable
+#### Transports
+
+`config.transport` selects how charge points reach the engine:
+
+- **`:raw`** — native **bare OCPP-J** over a plain WebSocket, which is what
+  real/commercial charge points speak. Stations connect to:
+  ```
+  ws://your-server:3000/ocpp/<charge-point-identifier>
+  ```
+  The identity is the last path segment; frames are the bare OCPP arrays
+  (`[2,"id","Action",{…}]`) with subprotocol `ocpp1.6`.
+- **`:action_cable`** (default) — OCPP-J wrapped in the ActionCable JSON protocol.
+  Stations connect to `ws://your-server:3000/ocpp/cable` and must speak the
+  ActionCable subscribe/`message` handshake (a generic OCPP station cannot; this
+  is aimed at ActionCable-aware clients/simulators). Kept as the default for
+  backwards compatibility.
+- **`:both`** — mount both endpoints side by side (useful while migrating).
+
+```ruby
+Ocpp::Rails.setup do |config|
+  config.transport = :raw   # accept real OCPP-J wallboxes directly
+end
 ```
 
-Stations authenticate with HTTP Basic Auth on the WebSocket upgrade
-(OCPP-J Security Profile 1, enabled by default). Provision a per-station
-credential first:
+Both transports authenticate identically: HTTP Basic Auth on the WebSocket
+upgrade (OCPP-J Security Profile 1, enabled by default; the Basic username must
+equal the station identity). Provision a per-station credential first:
 
 ```ruby
 charge_point.update!(auth_password: SecureRandom.base58(32))
 ```
 
+For internet-facing deployments use TLS (`wss://`, Security Profile 2),
+terminated by a reverse proxy in front of the app.
+
 For detailed setup instructions, see the [Getting Started Guide](docs/getting-started.md)
 and the [Security Guide](docs/security.md).
 

data/app/services/ocpp/rails/raw_socket/connection.rb

@@ -0,0 +1,181 @@
+module Ocpp
+  module Rails
+    module RawSocket
+      # One live raw OCPP-J station connection. It wires a websocket driver to the
+      # same transport-agnostic core the ActionCable channel uses, so the wire
+      # format changes but nothing downstream does:
+      #
+      #   inbound  station frame ──▶ MessageHandler (parse, route, hooks, audit)
+      #   outbound MessageHandler / remote-control jobs ──▶ ChargePointChannel
+      #            .broadcast_to(cp, {message:}) ──▶ ActionCable pub/sub ──▶ this
+      #            Connection's subscription ──▶ driver.text down the socket
+      #
+      # Reusing the existing broadcast as the outbound bus means the 10 producer
+      # sites (MessageHandler#send_callresult/#send_callerror and every remote
+      # command job) are unchanged, and cross-process routing (a job running on a
+      # different Puma worker than the socket) comes for free from the pub/sub
+      # adapter (async in dev, solid_cable/redis in production).
+      #
+      # `driver` is any websocket driver (WebSocket::Driver.rack in production, a
+      # stub in tests) responding to #on, #text, #ping, #close and, once started,
+      # relaying frames via its :message event. This object is transport-only; it
+      # never parses OCPP (Protocol/MessageHandler do).
+      class Connection
+        attr_reader :charge_point
+
+        def initialize(charge_point:, driver:, io: nil, logger: ::Rails.logger, pubsub: nil)
+          @charge_point = charge_point
+          @driver = driver
+          @io = io
+          @logger = logger
+          @pubsub = pubsub
+          @write_mutex = Mutex.new
+          @closed = false
+        end
+
+        # Wire driver callbacks, displace any prior socket for this station, mark
+        # it connected, and start relaying server->station frames. The caller
+        # (endpoint) still owns writing the 101 (driver.start) and the read loop.
+        def open
+          @driver.on(:message) { |event| handle_inbound(event.data) }
+          @driver.on(:close)   { close }
+          @driver.on(:error)   { |event| log_error("driver error", event) }
+
+          displace_previous
+          ::Rails.application.executor.wrap { mark_connected }
+          subscribe_outbound
+          self
+        end
+
+        # Feed one inbound OCPP-J frame (a JSON string) to the shared handler,
+        # dropping it if the station is over its per-minute message budget — the
+        # same guard, in the same place, as ChargePointChannel#receive.
+        def handle_inbound(text)
+          return if @closed
+
+          unless Ocpp::Rails.message_rate_limiter.allow?(@charge_point.identifier)
+            @logger.warn("[OCPP][security] #{ident}: message rate limit exceeded, dropping message")
+            return
+          end
+
+          ::Rails.application.executor.wrap do
+            MessageHandler.new(@charge_point, text).process
+          end
+        rescue => e
+          log_error("error handling inbound message", e)
+        end
+
+        # Relay a frame published on this station's ActionCable broadcasting down
+        # the socket. `encoded` is what the pub/sub adapter carries: the JSON
+        # dump of {message: "<ocpp-json>"} that broadcast_to produced.
+        def relay(encoded)
+          return if @closed
+
+          frame = JSON.parse(encoded)["message"]
+          write(frame) if frame
+        rescue => e
+          log_error("error relaying outbound frame", e)
+        end
+
+        def write(frame)
+          @write_mutex.synchronize { @driver.text(frame) }
+        end
+
+        def ping
+          @write_mutex.synchronize { @driver.ping }
+        rescue => e
+          log_error("ping failed", e)
+        end
+
+        # Idempotent teardown. Safe to call from the driver's :close event, the
+        # endpoint reader thread's ensure, or a displacing reconnect.
+        def close
+          return if @closed
+
+          @closed = true
+          unsubscribe_outbound
+          Registry.remove(@charge_point.identifier, self)
+          ::Rails.application.executor.wrap { mark_disconnected }
+          close_io
+          @driver.close
+        rescue => e
+          log_error("error during teardown", e)
+        end
+
+        def closed?
+          @closed
+        end
+
+        private
+
+        def displace_previous
+          previous = Registry.register(@charge_point.identifier, self)
+          return if previous.nil? || previous.equal?(self)
+
+          @logger.info("[OCPP][raw] #{ident}: superseding previous connection")
+          previous.close
+        end
+
+        def subscribe_outbound
+          @broadcasting = ChargePointChannel.broadcasting_for(@charge_point)
+          @relay = ->(encoded) { relay(encoded) }
+          pubsub.subscribe(@broadcasting, @relay)
+        end
+
+        def unsubscribe_outbound
+          pubsub.unsubscribe(@broadcasting, @relay) if @broadcasting && @relay
+        rescue => e
+          log_error("unsubscribe failed", e)
+        end
+
+        def pubsub
+          @pubsub ||= ActionCable.server.pubsub
+        end
+
+        def mark_connected
+          was = @charge_point.connected
+          @charge_point.update(connected: true, last_heartbeat_at: Time.current)
+          log_connection_change(was, true)
+          @logger.info("[OCPP][raw] #{ident}: connected")
+        end
+
+        def mark_disconnected
+          was = @charge_point.connected
+          @charge_point.disconnect!
+          log_connection_change(was, false)
+          @logger.info("[OCPP][raw] #{ident}: disconnected")
+        end
+
+        def log_connection_change(old_connected, new_connected)
+          return if old_connected == new_connected
+
+          StateChange.create!(
+            charge_point: @charge_point,
+            change_type: "connection",
+            connector_id: nil,
+            old_value: old_connected.to_s,
+            new_value: new_connected.to_s,
+            metadata: { source: "raw_socket" }
+          )
+        rescue => e
+          log_error("failed to log state change", e)
+        end
+
+        def close_io
+          @io.close if @io && !@io.closed?
+        rescue => e
+          log_error("io close failed", e)
+        end
+
+        def ident
+          "ChargePoint #{@charge_point.identifier}"
+        end
+
+        def log_error(context, error)
+          message = error.respond_to?(:message) ? error.message : error.to_s
+          @logger.error("[OCPP][raw] #{ident}: #{context}: #{message}")
+        end
+      end
+    end
+  end
+end

data/app/services/ocpp/rails/raw_socket/endpoint.rb

@@ -0,0 +1,135 @@
+require "websocket/driver"
+require "socket"
+
+module Ocpp
+  module Rails
+    module RawSocket
+      # Rack app that terminates native OCPP-J WebSocket connections — what a real
+      # charge point speaks (bare `[2,"id","Action",{}]` frames over a plain
+      # WebSocket, subprotocol "ocpp1.6", identity in the URL path), with no
+      # ActionCable subscription handshake.
+      #
+      # It authenticates from the Rack env *before* taking the socket, then
+      # full-hijacks (Rack `rack.hijack`, supported by Puma), completes the
+      # WebSocket upgrade with websocket-driver, and hands the socket to a
+      # Connection that bridges to the shared OCPP core. One reader thread per
+      # socket feeds inbound bytes to the driver; outbound frames arrive via the
+      # Connection's pub/sub subscription.
+      #
+      # Mount it from the engine when `config.transport` includes :raw.
+      class Endpoint
+        READ_CHUNK = 16_384
+
+        def call(env)
+          return not_websocket unless WebSocket::Driver.websocket?(env)
+          return no_hijack unless env["rack.hijack"]
+
+          decision = Handshake.new(env).call
+          unless decision.accepted?
+            log_reject(decision)
+            return unauthorized
+          end
+
+          accept(env, decision)
+          # Rack full-hijack sentinel: the server must not write a response.
+          [ -1, {}, [] ]
+        rescue => e
+          ::Rails.logger.error("[OCPP][raw] endpoint error: #{e.class}: #{e.message}")
+          internal_error
+        end
+
+        private
+
+        def accept(env, decision)
+          env["rack.hijack"].call
+          io = env["rack.hijack_io"]
+          enable_tcp_keepalive(io)
+
+          driver = WebSocket::Driver.rack(
+            RackSocket.new(env, io),
+            protocols: Ocpp::Rails.configuration.websocket_subprotocols,
+            max_length: Ocpp::Rails.configuration.raw_socket_max_frame_bytes
+          )
+
+          connection = Connection.new(charge_point: decision.charge_point, driver: driver, io: io)
+          connection.open
+          driver.start # writes the 101 handshake, echoing the negotiated Sec-WebSocket-Protocol
+          spawn_reader(io, driver, connection)
+        end
+
+        # One blocking reader per socket (Puma's threaded model). websocket-driver
+        # parses frames and fires the Connection's :message callback synchronously
+        # on this thread; teardown is funnelled through Connection#close so it runs
+        # exactly once whether the peer closed, the socket errored, or the driver
+        # emitted :close.
+        def spawn_reader(io, driver, connection)
+          Thread.new do
+            Thread.current.name = "ocpp-raw-#{connection.charge_point.identifier}"
+            begin
+              until connection.closed?
+                driver.parse(io.readpartial(READ_CHUNK))
+              end
+            rescue EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE
+              # peer went away / socket closed — normal disconnect
+            rescue => e
+              ::Rails.logger.error(
+                "[OCPP][raw] reader error for #{connection.charge_point.identifier}: #{e.message}"
+              )
+            ensure
+              connection.close
+            end
+          end
+        end
+
+        # Detect a silently-dropped peer (no FIN) so a half-open socket doesn't
+        # pin the station "connected" forever; OCPP Heartbeat covers the rest.
+        def enable_tcp_keepalive(io)
+          io.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true) if io.respond_to?(:setsockopt)
+        rescue StandardError
+          # non-fatal; some IO objects (e.g. in tests) don't support socket opts
+        end
+
+        def not_websocket
+          [ 426, { "content-type" => "text/plain", "connection" => "upgrade", "upgrade" => "websocket" },
+            [ "Upgrade required" ] ]
+        end
+
+        def no_hijack
+          [ 501, { "content-type" => "text/plain" }, [ "WebSocket hijacking not supported" ] ]
+        end
+
+        # Security-Profile-1 challenge, so a station may (re)send Basic credentials.
+        def unauthorized
+          [ 401, { "content-type" => "text/plain", "www-authenticate" => %(Basic realm="OCPP") },
+            [ "Unauthorized" ] ]
+        end
+
+        def internal_error
+          [ 500, { "content-type" => "text/plain" }, [ "Internal Server Error" ] ]
+        end
+
+        def log_reject(decision)
+          ::Rails.logger.warn(
+            "[OCPP][security] raw OCPP-J upgrade rejected for #{decision.identifier.inspect}: #{decision.failure}"
+          )
+        end
+
+        # Adapter presented to WebSocket::Driver.rack: the driver reads the
+        # Sec-WebSocket-* handshake headers from #env and writes the 101 response
+        # and subsequent frames through #write to the hijacked socket.
+        class RackSocket
+          attr_reader :env
+
+          def initialize(env, io)
+            @env = env
+            @io = io
+          end
+
+          def write(data)
+            @io.write(data)
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/ocpp/rails/raw_socket/handshake.rb

@@ -0,0 +1,78 @@
+require "cgi"
+
+module Ocpp
+  module Rails
+    module RawSocket
+      # Decides whether a raw OCPP-J WebSocket upgrade should be accepted, purely
+      # from the Rack env — no socket I/O — so it is unit-testable in isolation
+      # and identical whether the transport hijacks under Puma or is driven by a
+      # test harness.
+      #
+      # OCPP-J carries the charge-point identity in the URL *path* (unlike the
+      # ActionCable channel, which reads it from the subscribe command) and the
+      # Security-Profile-1 credential in the HTTP Basic `Authorization` header of
+      # the upgrade. This mirrors `ChargePointChannel#subscribed` — connection
+      # rate limit, then `StationAuthenticator` — so both transports authenticate
+      # a station identically.
+      class Handshake
+        Result = Struct.new(:charge_point, :identifier, :subprotocol, :failure, keyword_init: true) do
+          def accepted?
+            failure.nil?
+          end
+        end
+
+        def initialize(env, subprotocols: Ocpp::Rails.configuration.websocket_subprotocols)
+          @env = env
+          @subprotocols = Array(subprotocols)
+        end
+
+        def call
+          identifier = self.class.identifier_from_path(@env["PATH_INFO"])
+          return reject(identifier, :missing_identifier) if identifier.nil? || identifier.empty?
+
+          unless Ocpp::Rails.connection_rate_limiter.allow?(identifier)
+            return reject(identifier, :rate_limited)
+          end
+
+          result = StationAuthenticator.authenticate(
+            identifier: identifier,
+            authorization_header: @env["HTTP_AUTHORIZATION"]
+          )
+          return reject(identifier, result.failure) unless result.success?
+
+          Result.new(
+            charge_point: result.charge_point,
+            identifier: identifier,
+            subprotocol: negotiated_subprotocol,
+            failure: nil
+          )
+        end
+
+        # The OCPP identity is the last non-empty path segment, URL-decoded:
+        # "/ocpp/CP-1" and vendor variants like "/ocpp/steve/CP-1" both yield
+        # "CP-1". (Under the mounted engine the endpoint sees the engine-relative
+        # path, e.g. "/CP-1".)
+        def self.identifier_from_path(path)
+          return nil if path.nil?
+
+          segment = path.split("/").reject(&:empty?).last
+          segment && CGI.unescape(segment)
+        end
+
+        private
+
+        # The actual Sec-WebSocket-Protocol echo is performed by the websocket
+        # driver from the same list; this is the value we expect it to pick, kept
+        # on the Result for logging/inspection. nil when the station offered none.
+        def negotiated_subprotocol
+          offered = (@env["HTTP_SEC_WEBSOCKET_PROTOCOL"] || "").split(/ *, */)
+          (@subprotocols & offered).first
+        end
+
+        def reject(identifier, failure)
+          Result.new(identifier: identifier, failure: failure)
+        end
+      end
+    end
+  end
+end

data/app/services/ocpp/rails/raw_socket/registry.rb

@@ -0,0 +1,52 @@
+module Ocpp
+  module Rails
+    module RawSocket
+      # Process-local map of the live raw connections this process owns, keyed by
+      # charge-point identifier. Used to displace a stale socket when a station
+      # reconnects (OCPP allows only one live connection per station) and to see
+      # how many stations a process holds. NOT used for message delivery — that
+      # rides the ActionCable pub/sub bus (see Connection), which already routes
+      # across processes.
+      #
+      # State lives in class ivars, so in development each code reload starts
+      # empty (dev drops sockets on reload anyway); in production the process is
+      # eager-loaded and never reloaded, so entries persist for the socket's life.
+      class Registry
+        @mutex = Mutex.new
+        @connections = {}
+
+        class << self
+          # Record `connection` as the current owner of `identifier`, returning
+          # the connection it replaced (if any) so the caller can close it.
+          def register(identifier, connection)
+            @mutex.synchronize do
+              previous = @connections[identifier]
+              @connections[identifier] = connection
+              previous
+            end
+          end
+
+          # Drop `connection` only if it is still the current owner (a newer
+          # reconnect must not be evicted by an older socket's teardown).
+          def remove(identifier, connection)
+            @mutex.synchronize do
+              @connections.delete(identifier) if @connections[identifier].equal?(connection)
+            end
+          end
+
+          def [](identifier)
+            @mutex.synchronize { @connections[identifier] }
+          end
+
+          def size
+            @mutex.synchronize { @connections.size }
+          end
+
+          def clear!
+            @mutex.synchronize { @connections = {} }
+          end
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -1,5 +1,19 @@
 Ocpp::Rails::Engine.routes.draw do
-  # OCPP WebSocket endpoint via ActionCable
-  # Charge points connect to: ws://your-host/ocpp/cable
-  mount ActionCable.server => "/cable"
+  # OCPP transport(s), selected by `config.transport` (see Ocpp::Rails::Configuration):
+  #
+  #   :action_cable (default) — OCPP-J wrapped in the ActionCable JSON protocol.
+  #     Charge points connect to: ws://your-host/ocpp/cable
+  #   :raw — native bare OCPP-J over a plain WebSocket, what real stations speak.
+  #     Charge points connect to: ws://your-host/ocpp/<charge-point-identifier>
+  #   :both — mount both (migration).
+  #
+  # /cable is declared first so it keeps winning over the greedy raw mount at "/".
+  if Ocpp::Rails.transport_enabled?(:action_cable)
+    mount ActionCable.server => "/cable"
+  end
+
+  if Ocpp::Rails.transport_enabled?(:raw)
+    mount Ocpp::Rails::RawSocket::Endpoint.new => Ocpp::Rails.configuration.raw_socket_path,
+      as: :ocpp_raw_socket
+  end
 end

data/lib/ocpp/rails/version.rb

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

data/lib/ocpp/rails.rb

@@ -19,6 +19,15 @@ module Ocpp
       configuration.supported_versions
     end
 
+    # Whether a given charge-point transport is active. `transport` is one of
+    # :action_cable (default), :raw, or :both — so a deployment can run the
+    # legacy ActionCable-wrapped endpoint, the raw OCPP-J endpoint, or both side
+    # by side during migration. Consulted when the engine draws its routes.
+    def self.transport_enabled?(kind)
+      transport = configuration.transport
+      transport == kind || transport == :both
+    end
+
     def self.message_rate_limiter
       @message_rate_limiter ||= RateLimiter.new { configuration.max_messages_per_minute }
     end
@@ -37,7 +46,8 @@ module Ocpp
                     :state_change_hooks, :state_change_retention_days, :state_change_cleanup_enabled,
                     :authorization_hooks, :authorization_retention_days, :authorization_cleanup_enabled,
                     :session_hooks, :implausible_energy_jump_wh, :authentication_mode,
-                    :max_messages_per_minute, :max_connection_attempts_per_minute
+                    :max_messages_per_minute, :max_connection_attempts_per_minute,
+                    :transport, :raw_socket_path, :websocket_subprotocols, :raw_socket_max_frame_bytes
 
       def initialize
         @ocpp_version = "1.6"
@@ -63,6 +73,22 @@ module Ocpp
         # nil disables the respective check.
         @max_messages_per_minute = 300
         @max_connection_attempts_per_minute = 12
+        # Charge-point transport. :action_cable (default; ActionCable-wrapped
+        # OCPP-J, backwards compatible) | :raw (native bare OCPP-J over a plain
+        # WebSocket, what real stations speak) | :both (run both endpoints).
+        @transport = :action_cable
+        # Where the raw OCPP-J endpoint is mounted *within the engine*. With the
+        # host app mounting the engine at "/ocpp", the default "/" makes a station
+        # connect to ws://host/ocpp/<identifier> (the trailing path segment is the
+        # OCPP identity). "/cable" stays reserved for the ActionCable endpoint.
+        @raw_socket_path = "/"
+        # Subprotocols offered back to a raw station, in server-preference order.
+        # OCPP 1.6-J stations send "ocpp1.6"; the negotiated value is echoed in
+        # the handshake's Sec-WebSocket-Protocol response header.
+        @websocket_subprotocols = [ "ocpp1.6", "ocpp1.6j" ]
+        # Max inbound WebSocket message size on the raw endpoint (bytes). OCPP-J
+        # messages are small; oversized frames are a DoS vector and are refused.
+        @raw_socket_max_frame_bytes = 64 * 1024
       end
 
       def register_state_change_hook(hook)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ocpp-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jakob Sommerhuber
@@ -143,6 +143,10 @@ files:
 - 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/raw_socket/connection.rb
+- app/services/ocpp/rails/raw_socket/endpoint.rb
+- app/services/ocpp/rails/raw_socket/handshake.rb
+- app/services/ocpp/rails/raw_socket/registry.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