mbuzz 0.7.1 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb41261b9e19c46609f4e7a8867d73b5a902acecc3db3362b4a47e2cacefa9db
-  data.tar.gz: ce644b10fa63055065960bb72a61eb53077d4bbe110eac40ed5bd6918d2487c1
+  metadata.gz: 717fff0f77150fb5f0a2ddcd60e59aaccaacdddbe41acd88ec7b953b568ec448
+  data.tar.gz: caedfee3a6e6ced3dcfadcfcce5b80a9f13679b73710f0933b6c2d8573c2accb
 SHA512:
-  metadata.gz: 03bed0944d6ee7286e4f002d05032c8ced19d013da1dae69d429046b1ebad510cae67510d48d9af53fac8a8832a1a1495657c6b671a16976fabb5eb8ec316f3d
-  data.tar.gz: 4a0693caaa53219fbf4368c1b194722889c516e88eea6f7bfe781f7a44293659977e6691901f238f45ef66f08f367d674c2f22e6f8a63e22f3326368e6ae8f10
+  metadata.gz: ce5da1805916ac523dc3d9a40e8b3126ee8f7b1d95cc3fe042d6e800e796e38227f117edd9acb72e1ec4e357cd83d378fe87b3f87eb063c2857f267ae2508c56
+  data.tar.gz: 190f2ddbf15dbc17cde637ee4f8ed4d00a8b06d47f0d16fce9b54e96e67e7e8191359f57cc3a5e218c9028ccac072e14e0035a1c1cc0f5c9a4e95b3c14b73c41

data/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.3] - 2026-02-02
+
+### Breaking Changes
+
+- **Session cookie removed** — `_mbuzz_sid` cookie is no longer set or read. Sessions are fully server-side.
+- **`SESSION_COOKIE_NAME` and `SESSION_COOKIE_MAX_AGE` constants removed** from `Mbuzz` module.
+
+### Added
+
+- **Navigation-aware session creation** — middleware now gates `POST /sessions` on real page navigations using browser-enforced `Sec-Fetch-*` headers (whitelist), with a framework-specific blacklist fallback for older browsers and bots.
+  - Turbo Frame, htmx, Unpoly, and XHR sub-requests no longer create spurious sessions.
+  - Prefetches and iframe loads are correctly filtered out.
+- New public methods on `Mbuzz::Middleware::Tracking`: `should_create_session?`, `sec_fetch_headers?`, `page_navigation?`, `framework_sub_request?`
+
+### Migration Guide
+
+1. Remove any code that reads or depends on the `_mbuzz_sid` cookie.
+2. Remove references to `Mbuzz::SESSION_COOKIE_NAME` or `Mbuzz::SESSION_COOKIE_MAX_AGE`.
+3. Visitor cookie (`_mbuzz_vid`) is unaffected — still set on every request.
+
 ## [0.7.0] - 2026-01-09
 
 ### Breaking Changes

data/lib/mbuzz/client/session_request.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class Client
+    class SessionRequest
+      # Response keys
+      STATUS_KEY = "status"
+      VISITOR_ID_KEY = "visitor_id"
+      SESSION_ID_KEY = "session_id"
+      CHANNEL_KEY = "channel"
+
+      # Response values
+      ACCEPTED_STATUS = "accepted"
+
+      def initialize(visitor_id:, session_id:, url:, referrer: nil, device_fingerprint: nil, started_at: nil)
+        @visitor_id = visitor_id
+        @session_id = session_id
+        @url = url
+        @referrer = referrer
+        @device_fingerprint = device_fingerprint
+        @started_at = started_at
+      end
+
+      def call
+        return false unless valid?
+
+        parse_response(response)
+      rescue StandardError
+        false
+      end
+
+      private
+
+      attr_reader :visitor_id, :session_id, :url, :referrer, :device_fingerprint, :started_at
+
+      def valid?
+        present?(visitor_id) && present?(session_id) && present?(url)
+      end
+
+      def response
+        @response ||= Api.post_with_response(SESSIONS_PATH, { session: payload })
+      end
+
+      def payload
+        {
+          visitor_id: visitor_id,
+          session_id: session_id,
+          url: url,
+          referrer: referrer,
+          device_fingerprint: device_fingerprint,
+          started_at: started_at || Time.now.utc.iso8601
+        }.compact
+      end
+
+      def parse_response(resp)
+        return false unless accepted?(resp)
+
+        {
+          success: true,
+          visitor_id: resp[VISITOR_ID_KEY],
+          session_id: resp[SESSION_ID_KEY],
+          channel: resp[CHANNEL_KEY]
+        }
+      end
+
+      def accepted?(resp)
+        resp && resp[STATUS_KEY] == ACCEPTED_STATUS
+      end
+
+      def present?(value)
+        value && !value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/mbuzz/client.rb

@@ -3,6 +3,7 @@
 require_relative "client/track_request"
 require_relative "client/identify_request"
 require_relative "client/conversion_request"
+require_relative "client/session_request"
 
 module Mbuzz
   class Client
@@ -30,5 +31,16 @@ module Mbuzz
         identifier: identifier
       ).call
     end
+
+    def self.session(visitor_id:, session_id:, url:, referrer: nil, device_fingerprint: nil, started_at: nil)
+      SessionRequest.new(
+        visitor_id: visitor_id,
+        session_id: session_id,
+        url: url,
+        referrer: referrer,
+        device_fingerprint: device_fingerprint,
+        started_at: started_at
+      ).call
+    end
   end
 end

data/lib/mbuzz/current.rb

@@ -21,6 +21,7 @@ module Mbuzz
   #
   class Current < ActiveSupport::CurrentAttributes
     attribute :visitor_id
+    attribute :session_id
     attribute :user_id
     attribute :ip
     attribute :user_agent

data/lib/mbuzz/middleware/tracking.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "rack"
+require "digest"
+require "securerandom"
 
 module Mbuzz
   module Middleware
@@ -16,10 +18,13 @@ module Mbuzz
         context = build_request_context(request)
 
         env[ENV_VISITOR_ID_KEY] = context[:visitor_id]
+        env[ENV_SESSION_ID_KEY] = context[:session_id]
         env[ENV_USER_ID_KEY] = context[:user_id]
 
         store_in_current_attributes(context, request)
 
+        create_session_async(context, request) if should_create_session?(env)
+
         RequestContext.with_context(request: request) do
           status, headers, body = @app.call(env)
           set_visitor_cookie(headers, context, request)
@@ -45,14 +50,51 @@ module Mbuzz
         Mbuzz.config.all_skip_extensions.any? { |ext| path.end_with?(ext) }
       end
 
+      # Navigation detection — only create sessions for real page navigations.
+      # Sec-Fetch-* headers (browser-enforced, unforgeable) are the primary signal;
+      # framework-specific blacklist covers old browsers and bots.
+
+      def should_create_session?(env)
+        return page_navigation?(env) if sec_fetch_headers?(env)
+
+        !framework_sub_request?(env)
+      end
+
+      def sec_fetch_headers?(env)
+        !env["HTTP_SEC_FETCH_MODE"].nil?
+      end
+
+      def page_navigation?(env)
+        env["HTTP_SEC_FETCH_MODE"] == "navigate" &&
+          env["HTTP_SEC_FETCH_DEST"] == "document" &&
+          env["HTTP_SEC_PURPOSE"].nil?
+      end
+
+      def framework_sub_request?(env)
+        !env["HTTP_TURBO_FRAME"].nil? ||
+          !env["HTTP_HX_REQUEST"].nil? ||
+          !env["HTTP_X_UP_VERSION"].nil? ||
+          env["HTTP_X_REQUESTED_WITH"] == "XMLHttpRequest"
+      end
+
       private
 
-      # Build all request-specific context as a frozen hash
-      # This ensures thread-safety by using local variables only
+      # Build all request-specific context as a frozen hash.
+      # Thread-safety: all values needed by async session creation are captured here,
+      # NOT accessed from the request object in the background thread.
       def build_request_context(request)
+        ip = extract_ip(request)
+        user_agent = request.user_agent.to_s
+
         {
           visitor_id: resolve_visitor_id(request),
-          user_id: user_id_from_session(request)
+          session_id: SecureRandom.uuid,
+          user_id: user_id_from_session(request),
+          url: request.url,
+          referrer: request.referer,
+          ip: ip,
+          user_agent: user_agent,
+          device_fingerprint: Digest::SHA256.hexdigest("#{ip}|#{user_agent}")[0, 32]
         }.freeze
       end
 
@@ -68,7 +110,35 @@ module Mbuzz
         request.session[SESSION_USER_ID_KEY] if request.session
       end
 
-      # Cookie setting - only visitor cookie (sessions are server-side)
+      # Session creation - async to not block request
+      # IMPORTANT: This runs in a background thread. All data must come from
+      # the context hash, NOT from the request object (which may be invalid)
+
+      def create_session_async(context, _request)
+        Thread.new do
+          create_session(context)
+        rescue StandardError => e
+          log_error("Session creation failed: #{e.message}") if Mbuzz.config.debug
+        end
+      end
+
+      def create_session(context)
+        Client.session(
+          visitor_id: context[:visitor_id],
+          session_id: context[:session_id],
+          url: context[:url],
+          referrer: context[:referrer],
+          device_fingerprint: context[:device_fingerprint]
+        )
+      end
+
+      def log_error(message)
+        return unless defined?(Rails) && Rails.logger
+
+        Rails.logger.error("[Mbuzz] #{message}")
+      end
+
+      # Cookie setting - visitor identity only (sessions are server-side)
 
       def set_visitor_cookie(headers, context, request)
         Rack::Utils.set_cookie_header!(
@@ -100,6 +170,7 @@ module Mbuzz
         return unless defined?(Mbuzz::Current)
 
         Mbuzz::Current.visitor_id = context[:visitor_id]
+        Mbuzz::Current.session_id = context[:session_id]
         Mbuzz::Current.user_id = context[:user_id]
         Mbuzz::Current.ip = extract_ip(request)
         Mbuzz::Current.user_agent = request.user_agent

data/lib/mbuzz/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mbuzz
-  VERSION = "0.7.1"
+  VERSION = "0.7.3"
 end

data/lib/mbuzz.rb

@@ -20,6 +20,7 @@ module Mbuzz
   EVENTS_PATH = "/events"
   IDENTIFY_PATH = "/identify"
   CONVERSIONS_PATH = "/conversions"
+  SESSIONS_PATH = "/sessions"
 
   VISITOR_COOKIE_NAME = "_mbuzz_vid"
   VISITOR_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 2 # 2 years
@@ -29,6 +30,7 @@ module Mbuzz
   SESSION_USER_ID_KEY = "user_id"
   ENV_USER_ID_KEY = "mbuzz.user_id"
   ENV_VISITOR_ID_KEY = "mbuzz.visitor_id"
+  ENV_SESSION_ID_KEY = "mbuzz.session_id"
 
   # ============================================================================
   # Configuration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mbuzz
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.3
 platform: ruby
 authors:
 - mbuzz team
@@ -44,6 +44,7 @@ files:
 - lib/mbuzz/client.rb
 - lib/mbuzz/client/conversion_request.rb
 - lib/mbuzz/client/identify_request.rb
+- lib/mbuzz/client/session_request.rb
 - lib/mbuzz/client/track_request.rb
 - lib/mbuzz/configuration.rb
 - lib/mbuzz/controller_helpers.rb