mbuzz 0.8.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58bb33f56016e563027651d3fe6e0d5a8bd55a5b51e9920693a74b380380612a
-  data.tar.gz: 169f9818380dad8e239311ed1bd9c3501eb96b24d3f650a90679af1ad91630d0
+  metadata.gz: 03aa54a68ab1b6e6313d69c910c88aec7241e19d65b72b9cee37a6e187454692
+  data.tar.gz: 3ddce95a2f8795635278785f403daf6a41e15bc31fc01c3990989c20911ebc21
 SHA512:
-  metadata.gz: 684d91a340148e2a0762a476c401b9c8dc21f0bbff61882c8740394cc00ff72ea7ed65264f0d37880bac055e8add2b62548d4b6b474b427fe3fb8d03544d126e
-  data.tar.gz: 446e948eb88580966f4aaa9e5e0757510e7569f84fecf6bd1967c8ac364745b445e71484584807ae525f298b2b6e939bdeff6357982b47d1bf3cea3c79145808
+  metadata.gz: 4ba8606ecbeec460a9145937b8d123c93c455476d92795e9ddf2b291082e57cdce4818cd709a427ed28d125e0ee6766110f0425039c43bfba75328f5da6f756f
+  data.tar.gz: 8d9233587278aaccb19fd5f124e486e1385b626b2eb4db3d7125ab0e64d6b1500117a33fe89e1fad84c846e6a292e6183760013ecb33e16d44082036d2c5a299

data/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.10.0] - 2026-09-08
+
+### BREAKING — the page snippet is now required
+
+- **A page response no longer sets the visitor cookie.** Only `POST /_mbuzz/session` mints, and the inline snippet in the README's "Full-page caching" section is what calls it. **Upgrading without adding that snippet stops tracking entirely** — no cookie is ever minted, so no visitor exists and every event is dropped.
+
+### Fixed
+
+- **A cached page no longer hands every visitor the same id.** The page response carried a `Set-Cookie`, and a full-page cache stored it and replayed it to everyone — so unrelated people merged into a single journey. Corruption rather than loss: every row still exists, each attributed to the wrong person, and nothing looks missing. The page path now uses only the cookie the browser already holds; the uncached session endpoint is the sole place a visitor is minted.
+
+  Found by the cache harness at `sdk_integration_tests/scenarios/page_cache_test.rb`, and it could not have been found any other way: in isolation "reuse the cookie the browser presents" is correct — it is what lets a returning visitor keep their id. The bug exists only once a cache has handed one cookie to many people. The WordPress plugin reached the same conclusion first (`CookieBootstrap::CONTEXT_PAGE`).
+
+## [0.9.0] - 2026-09-02
+
+### Added
+
+- **A dropped event or conversion now says so.** `Mbuzz.event` and `Mbuzz.conversion` return `false` when there is no `visitor_id` and no `user_id` — previously with no request, no log and no signal of any kind. That silence is what made the caching bug above invisible on a live account for a full day. They now warn at `Rails.logger.warn` (or stderr outside Rails), naming the dropped call and pointing at the session endpoint. Deliberately **not** gated behind `debug`: the people who hit this are precisely the ones not running in debug.
+- **Attribution now survives a full-page cache.** A cached page is answered without entering the Rack stack, so the tracking middleware never ran, no visitor cookie was set, and every later event was dropped for having no one to attribute it to — silently, while the page rendered perfectly. `Mbuzz::Middleware::SessionEndpoint` answers `POST /_mbuzz/session`, a path caches don't store, and the server sets the cookie on that response. Mounted automatically in Rails; add it ahead of `Tracking` in Rack/Sinatra apps. See "Full-page caching" in the README for the one-time page snippet.
+
+### Notes
+
+- The visitor id is still never created or read in JavaScript. It stays `HttpOnly` and server-set, preserving its full two-year life — a cookie written by `document.cookie` is capped at 7 days under Safari's ITP, and 24 hours after an ad click.
+- Inline the page snippet rather than serving it as a file: asset optimisers delay external scripts until first interaction, which would miss any visitor who lands and converts without clicking first.
+
 ## [0.8.2] - 2026-03-15
 
 ### Changed

data/README.md

@@ -188,10 +188,53 @@ require 'mbuzz'
 
 Mbuzz.init(api_key: ENV['MBUZZ_API_KEY'])
 
+use Mbuzz::Middleware::SessionEndpoint   # see "Full-page caching" below
 use Mbuzz::Middleware::Tracking
 run MyApp
 ```
 
+## Full-page caching — the snippet below is REQUIRED
+
+**Add this to your layout or nothing is tracked.** Since 0.10.0 a page response never sets the
+visitor cookie: only `POST /_mbuzz/session` mints, and the snippet is what calls it.
+
+A page response can be stored by a full-page cache (Cloudflare, Varnish, nginx, Rack::Cache, a
+CDN) and replayed to every visitor. A `Set-Cookie` sitting in that cache hands everyone the
+*first* visitor's id, so unrelated people merge into one journey — corruption rather than loss,
+since every row exists and is simply attributed to the wrong person. Minting only on a response
+no cache stores is the only way to prevent it.
+
+The same endpoint solves the original problem too: a cached page never enters the Rack stack,
+so the tracking middleware cannot run — but this one request always reaches it.
+
+`Mbuzz::Middleware::SessionEndpoint` answers `POST /_mbuzz/session`. Rails mounts it for you;
+Rack and Sinatra apps add it ahead of `Tracking` as shown above.
+
+Then call it once per page, from your layout:
+
+```html
+<script>
+  fetch('/_mbuzz/session', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ url: location.href, referrer: document.referrer || '' }),
+    credentials: 'same-origin',
+    keepalive: true
+  }).catch(function () {});
+</script>
+```
+
+Two things to keep as they are:
+
+- **Inline the script, don't enqueue a file.** Asset optimisers (WP Rocket, LiteSpeed, and the
+  Rails equivalents) delay external scripts until the visitor first interacts. A visitor who
+  lands and converts without clicking anything first would never be established.
+- **`credentials: 'same-origin'` is required**, or the cookie never comes back.
+
+The visitor id is never created or read in JavaScript. It stays `HttpOnly` and server-set, which
+is what preserves its full two-year life — a cookie written by `document.cookie` is capped at
+7 days under Safari's ITP, and 24 hours after an ad click.
+
 ## Configuration Options
 
 ```ruby

data/lib/mbuzz/client/conversion_request.rb

@@ -19,7 +19,7 @@ module Mbuzz
       end
 
       def call
-        return false unless input_valid?
+        return warn_dropped unless input_valid?
         return proxy_result if proxy_accepted?
         return false unless conversion_id
 
@@ -28,6 +28,11 @@ module Mbuzz
 
       private
 
+      def warn_dropped
+        DroppedCall.warn_missing_identity("conversion", @conversion_type) unless has_identifier?
+        false
+      end
+
       def input_valid?
         has_identifier? && present?(@conversion_type) && hash?(@properties)
       end

data/lib/mbuzz/client/track_request.rb

@@ -14,7 +14,7 @@ module Mbuzz
       end
 
       def call
-        return false unless input_valid?
+        return warn_dropped unless input_valid?
         return proxy_result if proxy_accepted?
         return false unless event
 
@@ -24,6 +24,13 @@ module Mbuzz
 
       private
 
+      # A drop with no request and no log is how this failure stayed invisible
+      # on a live account for a full day. Say it out loud.
+      def warn_dropped
+        DroppedCall.warn_missing_identity("event", @event_type) unless @user_id || @visitor_id
+        false
+      end
+
       def input_valid?
         present?(@event_type) && hash?(@properties) && (@user_id || @visitor_id)
       end

data/lib/mbuzz/dropped_call.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  # Says out loud when a call is dropped for having nothing to attribute it to.
+  #
+  # Every SDK guarded its send with a bare `return false unless valid?`: no
+  # request, no log, nothing. Behind a full-page cache that is the whole failure
+  # — the cookie is never minted, so every later event fails this guard and
+  # vanishes. It cost a full day on a live account precisely because the silence
+  # was total from both sides.
+  #
+  # Deliberately NOT behind config.debug. The customers who hit this are exactly
+  # the ones not running in debug, so a debug-gated warning would be silent for
+  # everyone who needs it.
+  module DroppedCall
+    # Built lazily: SESSION_ENDPOINT_PATH is defined in mbuzz.rb *after* this
+    # file is required, so interpolating it at load time would not resolve.
+    def self.missing_identity
+      "no visitor_id and no user_id. If your pages are served from a full-page " \
+        "cache, mount Mbuzz::Middleware::SessionEndpoint and call POST " \
+        "#{SESSION_ENDPOINT_PATH} from the page — see the README's " \
+        "\"Full-page caching\" section."
+    end
+
+    def self.warn_missing_identity(kind, name)
+      emit("dropped #{kind} #{name.inspect}: #{missing_identity}")
+    end
+
+    def self.warn_invalid(kind, name, reason)
+      emit("dropped #{kind} #{name.inspect}: #{reason}.")
+    end
+
+    def self.emit(message)
+      text = "[mbuzz] #{message}"
+      return Rails.logger.warn(text) if defined?(Rails) && Rails.logger
+
+      Kernel.warn(text)
+    end
+    private_class_method :emit
+  end
+end

data/lib/mbuzz/middleware/session_endpoint.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "rack"
+require "json"
+require "digest"
+require "securerandom"
+
+module Mbuzz
+  module Middleware
+    # Establishes the visitor from a page a cache served.
+    #
+    # A cached page never enters the Rack stack, so Tracking never runs and no
+    # visitor cookie is set — every later event is then rejected for having no
+    # one to attribute it to, silently, while the page renders perfectly.
+    #
+    # This endpoint is the one request on such a page that always reaches the
+    # app. A small script on the page POSTs here; the SERVER mints the cookie on
+    # the response. The id is never created or read in JS, so it stays HttpOnly
+    # and keeps its full two-year life — a cookie written by document.cookie is
+    # capped at 7 days under Safari's ITP, and 24 hours after an ad click.
+    #
+    # Mount ahead of Tracking:
+    #
+    #   config.middleware.insert_before Mbuzz::Middleware::Tracking,
+    #                                   Mbuzz::Middleware::SessionEndpoint
+    class SessionEndpoint
+      # Nothing to return: the response exists for its Set-Cookie header.
+      NO_CONTENT_STATUS = 204
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless session_request?(env)
+
+        mint(Rack::Request.new(env))
+      end
+
+      private
+
+      # POST only: a GET is cacheable by an intermediary, which would reintroduce
+      # the very bug this endpoint exists to fix.
+      def session_request?(env)
+        env["REQUEST_METHOD"] == "POST" &&
+          env["PATH_INFO"].to_s == SESSION_ENDPOINT_PATH
+      end
+
+      def mint(request)
+        context = build_context(request)
+        create_session_async(context)
+
+        [NO_CONTENT_STATUS, response_headers(context, request), []]
+      end
+
+      def build_context(request)
+        payload    = parse_body(request)
+        ip         = extract_ip(request)
+        user_agent = request.user_agent.to_s
+
+        {
+          visitor_id: resolve_visitor_id(request),
+          session_id: SecureRandom.uuid,
+          # The page's URL, not ours — a script on the page called us, so our own
+          # path would attribute every session to this endpoint.
+          url: payload["url"],
+          referrer: payload["referrer"],
+          ip: ip,
+          user_agent: user_agent,
+          device_fingerprint: Digest::SHA256.hexdigest("#{ip}|#{user_agent}")[0, 32]
+        }.freeze
+      end
+
+      def parse_body(request)
+        body = request.body&.read.to_s
+        return {} if body.empty?
+
+        parsed = JSON.parse(body)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def resolve_visitor_id(request)
+        request.cookies[VISITOR_COOKIE_NAME] || Visitor::Identifier.generate
+      end
+
+      def create_session_async(context)
+        Thread.new do
+          Client.session(
+            visitor_id: context[:visitor_id],
+            session_id: context[:session_id],
+            url: context[:url],
+            referrer: context[:referrer],
+            device_fingerprint: context[:device_fingerprint],
+            user_agent: context[:user_agent]
+          )
+        rescue StandardError => e
+          log_error("Session creation failed: #{e.message}") if Mbuzz.config.debug
+        end
+      end
+
+      def response_headers(context, request)
+        headers = { "cache-control" => "no-store, no-cache, must-revalidate, private" }
+        Rack::Utils.set_cookie_header!(headers, VISITOR_COOKIE_NAME, cookie_options(context, request))
+        headers
+      end
+
+      def cookie_options(context, request)
+        options = {
+          value: context[:visitor_id],
+          max_age: VISITOR_COOKIE_MAX_AGE,
+          path: VISITOR_COOKIE_PATH,
+          httponly: true,
+          same_site: VISITOR_COOKIE_SAME_SITE
+        }
+        options[:secure] = true if request.ssl?
+        options
+      end
+
+      def extract_ip(request)
+        forwarded = request.env["HTTP_X_FORWARDED_FOR"]
+        return forwarded.split(",").first.strip if forwarded
+
+        request.ip
+      end
+
+      def log_error(message)
+        return unless defined?(Rails) && Rails.logger
+
+        Rails.logger.error("[Mbuzz] #{message}")
+      end
+    end
+  end
+end

data/lib/mbuzz/middleware/tracking.rb

@@ -15,6 +15,16 @@ module Mbuzz
         return @app.call(env) if skip_request?(env)
 
         request = Rack::Request.new(env)
+
+        # Only a visitor the browser already holds. This response may be stored
+        # by a full-page cache and replayed to everyone, so minting here would
+        # put a Set-Cookie in that cache and hand every later visitor the same
+        # id — unrelated people merged into one journey. Corruption, not loss:
+        # every row still exists, each attributed to the wrong person, and
+        # nothing looks missing. A first-time visitor is established a moment
+        # later by Middleware::SessionEndpoint, whose POST no cache stores.
+        return @app.call(env) unless visitor_id_from_cookie(request)
+
         context = build_request_context(request)
 
         env[ENV_VISITOR_ID_KEY] = context[:visitor_id]
@@ -26,9 +36,7 @@ module Mbuzz
         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)
-          [status, headers, body]
+          @app.call(env)
         ensure
           reset_current_attributes
         end
@@ -87,7 +95,7 @@ module Mbuzz
         user_agent = request.user_agent.to_s
 
         {
-          visitor_id: resolve_visitor_id(request),
+          visitor_id: visitor_id_from_cookie(request),
           session_id: SecureRandom.uuid,
           user_id: user_id_from_session(request),
           url: request.url,
@@ -98,10 +106,6 @@ module Mbuzz
         }.freeze
       end
 
-      def resolve_visitor_id(request)
-        visitor_id_from_cookie(request) || Visitor::Identifier.generate
-      end
-
       def visitor_id_from_cookie(request)
         request.cookies[VISITOR_COOKIE_NAME]
       end
@@ -139,33 +143,6 @@ module Mbuzz
         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!(
-          headers,
-          VISITOR_COOKIE_NAME,
-          visitor_cookie_options(context, request)
-        )
-      end
-
-      def visitor_cookie_options(context, request)
-        base_cookie_options(request).merge(
-          value: context[:visitor_id],
-          max_age: VISITOR_COOKIE_MAX_AGE
-        )
-      end
-
-      def base_cookie_options(request)
-        options = {
-          path: VISITOR_COOKIE_PATH,
-          httponly: true,
-          same_site: VISITOR_COOKIE_SAME_SITE
-        }
-        options[:secure] = true if request.ssl?
-        options
-      end
-
       # Store context in CurrentAttributes for background job propagation
       def store_in_current_attributes(context, request)
         return unless defined?(Mbuzz::Current)

data/lib/mbuzz/railtie.rb

@@ -3,6 +3,9 @@
 module Mbuzz
   class Railtie < Rails::Railtie
     initializer "mbuzz.configure_rails" do |app|
+      # The endpoint must sit ahead of Tracking: it answers its own path and
+      # never falls through, so Tracking should not also process it.
+      app.middleware.use Mbuzz::Middleware::SessionEndpoint
       app.middleware.use Mbuzz::Middleware::Tracking
 
       ActiveSupport.on_load(:action_controller) do

data/lib/mbuzz/version.rb

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

data/lib/mbuzz.rb

@@ -2,11 +2,13 @@
 
 require_relative "mbuzz/version"
 require_relative "mbuzz/configuration"
+require_relative "mbuzz/dropped_call"
 require_relative "mbuzz/visitor/identifier"
 require_relative "mbuzz/request_context"
 require_relative "mbuzz/api"
 require_relative "mbuzz/client"
 require_relative "mbuzz/middleware/tracking"
+require_relative "mbuzz/middleware/session_endpoint"
 require_relative "mbuzz/controller_helpers"
 
 # CurrentAttributes for automatic background job context propagation (Rails only)
@@ -27,6 +29,10 @@ module Mbuzz
   VISITOR_COOKIE_PATH = "/"
   VISITOR_COOKIE_SAME_SITE = "Lax"
 
+  # The one request a cached page always sends to the app. Kept off /api and
+  # /assets so host-app routing and cache rules don't shadow it.
+  SESSION_ENDPOINT_PATH = "/_mbuzz/session"
+
   SESSION_USER_ID_KEY = "user_id"
   ENV_USER_ID_KEY = "mbuzz.user_id"
   ENV_VISITOR_ID_KEY = "mbuzz.visitor_id"
@@ -110,8 +116,13 @@ module Mbuzz
     resolved_visitor_id = visitor_id || self.visitor_id
     resolved_user_id = user_id
 
-    # Must have at least one identifier
-    return false unless resolved_visitor_id || resolved_user_id
+    # Must have at least one identifier. Warn rather than drop in silence: with
+    # no visitor and no user there is nothing to attribute this to, and behind a
+    # full-page cache that is the normal case, not an edge one.
+    unless resolved_visitor_id || resolved_user_id
+      DroppedCall.warn_missing_identity("event", event_type)
+      return false
+    end
 
     Client.track(
       visitor_id: resolved_visitor_id,
@@ -161,8 +172,12 @@ module Mbuzz
     resolved_visitor_id = visitor_id || self.visitor_id
     resolved_user_id = user_id || self.user_id
 
-    # Must have at least one identifier (visitor_id or user_id)
-    return false unless resolved_visitor_id || resolved_user_id
+    # Must have at least one identifier (visitor_id or user_id). A conversion
+    # dropped here is lost revenue attribution, so it is never silent.
+    unless resolved_visitor_id || resolved_user_id
+      DroppedCall.warn_missing_identity("conversion", conversion_type)
+      return false
+    end
 
     Client.conversion(
       visitor_id: resolved_visitor_id,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mbuzz
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.10.0
 platform: ruby
 authors:
 - mbuzz team
@@ -32,13 +32,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".DS_Store"
 - CHANGELOG.md
-- CHECK_BUG.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- lib/.DS_Store
 - lib/mbuzz.rb
 - lib/mbuzz/api.rb
 - lib/mbuzz/client.rb
@@ -49,18 +46,13 @@ files:
 - lib/mbuzz/configuration.rb
 - lib/mbuzz/controller_helpers.rb
 - lib/mbuzz/current.rb
+- lib/mbuzz/dropped_call.rb
+- lib/mbuzz/middleware/session_endpoint.rb
 - lib/mbuzz/middleware/tracking.rb
 - lib/mbuzz/railtie.rb
 - lib/mbuzz/request_context.rb
 - lib/mbuzz/version.rb
 - lib/mbuzz/visitor/identifier.rb
-- lib/specs/old/SPECIFICATION.md
-- lib/specs/old/conversions.md
-- lib/specs/old/event_ids_response.md
-- lib/specs/old/v0.2.0_breaking_changes.md
-- lib/specs/old/v2.0.0_sessions_upgrade.md
-- lib/specs/v0.5.0_four_call_model.md
-- lib/specs/v0.7.0_deterministic_sessions.md
 - sig/mbuzz.rbs
 homepage: https://mbuzz.co
 licenses: