mbuzz 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81970794a962b276527d5aa05efb59703e1e3507598218c66f3eb3c238a96b6a
-  data.tar.gz: 391e3993a7aa60f3ad5fe50dfeff1394c9f3282538d3074de12f7a7a284d8e15
+  metadata.gz: 03aa54a68ab1b6e6313d69c910c88aec7241e19d65b72b9cee37a6e187454692
+  data.tar.gz: 3ddce95a2f8795635278785f403daf6a41e15bc31fc01c3990989c20911ebc21
 SHA512:
-  metadata.gz: 2187c1959502e1dcc183e6f3fd2d77b46b90e87427bb79078c04cac35715891ec89cf274514cf8e8f327de2d8176e0d381875c961b9f61b37fee18f313c8ff9e
-  data.tar.gz: eb34d5989f34c7e83d5315c57000dff733af12a26494255817a414002d0448a1d8ee8f71143a94348f1b5118df743acf97cdeffd2347584e0cbe561b73b396e3
+  metadata.gz: 4ba8606ecbeec460a9145937b8d123c93c455476d92795e9ddf2b291082e57cdce4818cd709a427ed28d125e0ee6766110f0425039c43bfba75328f5da6f756f
+  data.tar.gz: 8d9233587278aaccb19fd5f124e486e1385b626b2eb4db3d7125ab0e64d6b1500117a33fe89e1fad84c846e6a292e6183760013ecb33e16d44082036d2c5a299

data/CHANGELOG.md

@@ -5,6 +5,18 @@ 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

data/README.md

@@ -193,16 +193,22 @@ use Mbuzz::Middleware::Tracking
 run MyApp
 ```
 
-## Full-page caching
+## Full-page caching — the snippet below is REQUIRED
 
-If pages are served from a full-page cache (Cloudflare, Varnish, nginx, Rack::Cache, a CDN),
-the cache answers the request **without entering the Rack stack**, so the tracking middleware
-never runs, no visitor cookie is set, and every later event is dropped for having no one to
-attribute it to. The page renders perfectly and nothing is logged — the failure is silent.
+**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.
 
-`Mbuzz::Middleware::SessionEndpoint` fixes this. It answers `POST /_mbuzz/session`, a path
-caches don't store, and the **server** sets the cookie on that response. Rails mounts it for
-you; Rack and Sinatra apps add it ahead of `Tracking` as shown above.
+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:
 

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mbuzz
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - mbuzz team