Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(frontend): serve the stable chunk build to every app page (#124368)

Paul D'Ambrab5cebe8bfced
diff --git a/frontend/src/index.html b/frontend/src/index.html
index 97d127ede7cc..71149138c9d5 100644
--- a/frontend/src/index.html
+++ b/frontend/src/index.html
@@ -39,7 +39,7 @@
{% for url in stable_preload_css_urls %}
<link rel="preload" href="{{ js_url }}/{{ url }}" as="style" crossorigin="anonymous">
{% endfor %}
- {# Stable chunk names (opt-in, see posthog/stable_chunks.py): the import map must come before #}
+ {# Stable chunk names (see posthog/stable_chunks.py): the import map must come before #}
{# the modulepreload hints below, because browsers ignore an import map added after module #}
{# loading has started. #}
{% if stable_chunks_importmap %}
diff --git a/posthog/stable_chunks.py b/posthog/stable_chunks.py
index 1daa28864e59..7abf393b69dc 100644
--- a/posthog/stable_chunks.py
+++ b/posthog/stable_chunks.py
@@ -1,27 +1,25 @@
"""
-Flag-gated serving of the frontend build with stable chunk names.
+Serving of the frontend build with stable chunk names.
The build writes a second copy of the app's JS in which chunks import each other through identity
specifiers, plus `stable-chunks-manifest.json` with the import map that resolves them (see
frontend/bin/stableChunkNames.mjs). A chunk's URL then changes only when its own code changes,
so a deploy no longer makes returning users download every chunk that imports a changed one.
-Which build a request gets is decided by `stable_chunks_choice`. Without a readable manifest,
-pages render exactly as before.
+Every app page gets this build, except a page that reloads after a stable chunk failed to load.
+Without a readable manifest, pages render the hashed build.
"""
import os
import re
import json
-from collections.abc import Mapping
from functools import lru_cache
-from typing import Any, Optional
+from typing import Optional
from django.conf import settings
-from django.http import HttpRequest, HttpResponse
+from django.http import HttpRequest
import structlog
-import posthoganalytics
from prometheus_client import Counter
from posthog.dataclasses import frozen
@@ -31,12 +29,6 @@ logger = structlog.get_logger(__name__)
STABLE_CHUNKS_PARAM = "stable_chunks"
STABLE_CHUNKS_UNMAPPED_PARAM = "stable_chunks_unmapped"
-STABLE_CHUNKS_COOKIE = "ph_stable_chunks"
-STABLE_CHUNKS_FLAG = "stable-chunk-names"
-_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30
-# A logged-out request has no person, so every logged-out request evaluates the flag with this one
-# ID. A partial rollout therefore switches all logged-out pages on or off together.
-LOGGED_OUT_FLAG_DISTINCT_ID = "stable-chunks-logged-out"
STABLE_CHUNKS_FALLBACK_COUNTER = Counter(
"posthog_stable_chunks_fallback",
@@ -75,7 +67,7 @@ class StableChunks:
def read_stable_chunks_manifest(manifest_path: str) -> Optional[StableChunks]:
"""
- Parse the manifest defensively. A missing or malformed manifest turns the opt-in off rather
+ Parse the manifest defensively. A missing or malformed manifest serves the hashed build rather
than breaking page rendering, and is reported, because the caller caches the result per process.
"""
try:
@@ -121,7 +113,8 @@ def read_stable_chunks_manifest(manifest_path: str) -> Optional[StableChunks]:
@lru_cache(maxsize=1)
def _resolve_stable_chunks() -> Optional[StableChunks]:
- if settings.DEBUG or settings.TEST:
+ # The Vite dev server serves source modules, so a manifest left in dist from an older build is stale.
+ if settings.DEBUG and not settings.TEST:
return None
return read_stable_chunks_manifest(
os.path.join(settings.BASE_DIR, "frontend", "dist", "stable-chunks-manifest.json")
@@ -140,63 +133,9 @@ def _count_fallback(request: HttpRequest) -> None:
).inc()
-def stable_chunks_choice(request: HttpRequest, feature_flags: Optional[Mapping[str, Any]]) -> bool:
- """
- The query param wins, then the cookie, then the flag. For a logged-in user, `feature_flags` are
- the ones bootstrapped into posthog-js, so events carry the flag value that picked the build.
- A logged-out request has no bootstrapped flags, so it evaluates the flag locally.
- """
- param = request.GET.get(STABLE_CHUNKS_PARAM)
- if param is not None:
- if param == "fallback":
- _count_fallback(request)
- return param == "1"
-
- cookie = request.COOKIES.get(STABLE_CHUNKS_COOKIE)
- if cookie in ("0", "1"):
- return cookie == "1"
-
- if not request.user.is_authenticated:
- return _flag_enabled_for_logged_out_requests()
-
- if not feature_flags:
- return False
-
- return feature_flags.get(STABLE_CHUNKS_FLAG) is True
-
-
-def _flag_enabled_for_logged_out_requests() -> bool:
- # Every logged-out app page runs this check, so a failure serves the hashed build instead of an error.
- try:
- return (
- posthoganalytics.feature_enabled(
- STABLE_CHUNKS_FLAG,
- LOGGED_OUT_FLAG_DISTINCT_ID,
- only_evaluate_locally=True,
- send_feature_flag_events=False,
- )
- is True
- )
- except Exception as e:
- logger.warning("stable_chunks_logged_out_flag_check_failed", error=str(e))
- capture_exception(e)
- return False
-
-
-def stable_chunks_for_request(
- request: HttpRequest, feature_flags: Optional[Mapping[str, Any]]
-) -> Optional[StableChunks]:
- return _resolve_stable_chunks() if stable_chunks_choice(request, feature_flags) else None
-
-
-def persist_stable_chunks_choice(request: HttpRequest, response: HttpResponse) -> None:
- param = request.GET.get(STABLE_CHUNKS_PARAM)
- if param in ("0", "1"):
- response.set_cookie(
- STABLE_CHUNKS_COOKIE,
- param,
- max_age=_COOKIE_MAX_AGE_SECONDS,
- secure=request.is_secure(),
- httponly=True,
- samesite="Lax",
- )
+def stable_chunks_for_request(request: HttpRequest) -> Optional[StableChunks]:
+ # A page that fell back gets the hashed build, so the chunk that failed cannot fail it again.
+ if request.GET.get(STABLE_CHUNKS_PARAM) == "fallback":
+ _count_fallback(request)
+ return None
+ return _resolve_stable_chunks()
diff --git a/posthog/test/test_get_context_for_template.py b/posthog/test/test_get_context_for_template.py
index ddf06f0f87db..4488817b8ad8 100644
--- a/posthog/test/test_get_context_for_template.py
+++ b/posthog/test/test_get_context_for_template.py
@@ -335,24 +335,25 @@ class TestGetContextForTemplate(APIBaseTest):
@parameterized.expand(
[
- ("opted in and logged in", True, True, ("static/index-S0000000000.js", "static/shell-S1111111111.js")),
- ("opted in and anonymous", True, False, ("static/index-S0000000000.js",)),
- ("not opted in", False, True, ()),
+ ("logged in", "", True, ("static/index-S0000000000.js", "static/shell-S1111111111.js")),
+ ("anonymous", "", False, ("static/index-S0000000000.js",)),
+ ("fell back after a failed chunk", "?stable_chunks=fallback", True, ()),
]
)
- def test_only_an_opted_in_browser_boots_through_the_import_map(
- self, _name, opted_in, authenticated, expected_preload_js_urls
+ def test_a_page_boots_through_the_import_map_unless_it_fell_back(
+ self, _name, query, authenticated, expected_preload_js_urls
):
- request = RequestFactory().get("/?stable_chunks=1" if opted_in else "/")
+ expect_stable = query == ""
+ request = RequestFactory().get(f"/{query}")
SessionMiddleware(lambda _request: HttpResponse()).process_request(request)
request.user = self.user if authenticated else AnonymousUser()
with mock.patch("posthog.stable_chunks._resolve_stable_chunks", return_value=STABLE_CHUNKS):
context = get_context_for_template("index.html", request)
- assert context.get("stable_chunks", False) is opted_in
+ assert context.get("stable_chunks", False) is expect_stable
assert context["preload_js_urls"] == expected_preload_js_urls
- if opted_in:
+ if expect_stable:
assert json.loads(context["stable_chunks_importmap"]) == {
"imports": {"@c/eAAAA": f"{context['js_url']}/static/index-S0000000000.js"}
}
diff --git a/posthog/test/test_stable_chunks.py b/posthog/test/test_stable_chunks.py
index 6b2094ace5c8..400200369d9f 100644
--- a/posthog/test/test_stable_chunks.py
+++ b/posthog/test/test_stable_chunks.py
@@ -2,12 +2,9 @@ import json
import tempfile
from pathlib import Path
-from posthog.test.base import APIBaseTest
from unittest.mock import patch
from django.contrib.auth.models import AnonymousUser
-from django.contrib.sessions.middleware import SessionMiddleware
-from django.http import HttpRequest, HttpResponse
from django.test import RequestFactory, SimpleTestCase, override_settings
import structlog
@@ -17,22 +14,18 @@ from structlog.testing import capture_logs
from posthog.models import User
from posthog.stable_chunks import (
- STABLE_CHUNKS_COOKIE,
- STABLE_CHUNKS_FLAG,
StableChunks,
- persist_stable_chunks_choice,
+ _resolve_stable_chunks,
read_stable_chunks_manifest,
- stable_chunks_choice,
+ stable_chunks_for_request,
)
-from posthog.utils import get_context_for_template, render_template
+from posthog.utils import get_context_for_template
VALID_MANIFEST = {
"imports": {"@c/eAAAA": "static/index-S0000000000.js"},
"preload": {"js": ["static/index-S0000000000.js"], "authenticatedJs": ["static/chunk-S1111111111.js"]},
"eagerCss": ["static/stylesEagerTailwind-AAAA1111.css", "static/stylesEagerApp-BBBB2222.css"],
}
-FLAG_ON = {STABLE_CHUNKS_FLAG: True}
-FLAG_OFF = {STABLE_CHUNKS_FLAG: False}
class TestStableChunks(SimpleTestCase):
@@ -75,50 +68,47 @@ class TestStableChunks(SimpleTestCase):
@parameterized.expand(
[
- ("param on beats a cookie off and the flag off", "?stable_chunks=1", "0", FLAG_OFF, True, True),
- ("param off beats the flag on", "?stable_chunks=0", None, FLAG_ON, True, False),
- ("fallback beats a cookie on", "?stable_chunks=fallback", "1", None, False, False),
- ("fallback beats the flag on", "?stable_chunks=fallback", None, FLAG_ON, True, False),
- ("cookie on beats the flag off", "", "1", FLAG_OFF, True, True),
- ("cookie off beats the flag on", "", "0", FLAG_ON, True, False),
- ("flag on", "", None, FLAG_ON, True, True),
- ("flag off", "", None, FLAG_OFF, True, False),
- ("flag without a local definition", "", None, {}, True, False),
- ("flags not evaluated", "", None, None, True, False),
- ("anonymous with the flag on", "", None, FLAG_ON, False, True),
- ("anonymous with the flag off", "", None, FLAG_OFF, False, False),
- ("anonymous without a local definition", "", None, {}, False, False),
+ ("production", False, False, True),
+ ("tests", False, True, True),
+ ("tests with debug on", True, True, True),
+ ("the vite dev server", True, False, False),
]
)
- def test_choice_precedence(
- self,
- _name: str,
- query: str,
- cookie: str | None,
- feature_flags: dict[str, bool] | None,
- authenticated: bool,
- expected: bool,
+ def test_only_the_vite_dev_server_skips_the_stable_build(
+ self, _name: str, debug: bool, test: bool, expect_stable: bool
+ ) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ dist = Path(directory) / "frontend" / "dist"
+ dist.mkdir(parents=True)
+ (dist / "stable-chunks-manifest.json").write_text(json.dumps(VALID_MANIFEST))
+ _resolve_stable_chunks.cache_clear()
+ self.addCleanup(_resolve_stable_chunks.cache_clear)
+
+ with override_settings(BASE_DIR=directory, DEBUG=debug, TEST=test):
+ assert (_resolve_stable_chunks() is not None) == expect_stable
+
+ @parameterized.expand(
+ [
+ ("a signed-in page", "", None, True, True),
+ ("a signed-out page", "", None, False, True),
+ ("a page that fell back", "?stable_chunks=fallback", None, True, False),
+ ("an old opt-out param", "?stable_chunks=0", None, True, True),
+ ("an old opt-out cookie", "", "0", False, True),
+ ]
+ )
+ def test_every_page_gets_the_stable_build_unless_it_fell_back(
+ self, _name: str, query: str, cookie: str | None, authenticated: bool, expect_stable: bool
) -> None:
request = RequestFactory().get(f"/{query}")
request.user = User() if authenticated else AnonymousUser()
if cookie:
- request.COOKIES[STABLE_CHUNKS_COOKIE] = cookie
- bootstrapped_flags = feature_flags if authenticated else None
- locally_evaluated_flags = {} if authenticated else (feature_flags or {})
- fallback_labels = {"authenticated": str(authenticated).lower(), "reason": "load_failed"}
- fallbacks_before = REGISTRY.get_sample_value("posthog_stable_chunks_fallback_total", fallback_labels) or 0
-
- with patch(
- "posthoganalytics.feature_enabled",
- side_effect=lambda key, *_args, **_kwargs: locally_evaluated_flags.get(key),
- ) as feature_enabled:
- assert stable_chunks_choice(request, bootstrapped_flags) == expected
+ request.COOKIES["ph_stable_chunks"] = cookie
+ stable = StableChunks(
+ imports={"@c/eAAAA": "static/index-S0000000000.js"}, preload_js_urls=(), authenticated_preload_js_urls=()
+ )
- for call in feature_enabled.call_args_list:
- assert call.kwargs["only_evaluate_locally"] is True
- assert call.kwargs["send_feature_flag_events"] is False
- fallbacks_after = REGISTRY.get_sample_value("posthog_stable_chunks_fallback_total", fallback_labels) or 0
- assert fallbacks_after - fallbacks_before == (1 if query == "?stable_chunks=fallback" else 0)
+ with patch("posthog.stable_chunks._resolve_stable_chunks", return_value=stable):
+ assert (stable_chunks_for_request(request) is not None) == expect_stable
@parameterized.expand(
[
@@ -137,7 +127,7 @@ class TestStableChunks(SimpleTestCase):
labels = {"authenticated": "false", "reason": reason}
before = REGISTRY.get_sample_value("posthog_stable_chunks_fallback_total", labels) or 0
- assert stable_chunks_choice(request, None) is False
+ assert stable_chunks_for_request(request) is None
assert REGISTRY.get_sample_value("posthog_stable_chunks_fallback_total", labels) == before + 1
@@ -152,7 +142,7 @@ class TestStableChunks(SimpleTestCase):
structlog.get_logger().new()
with capture_logs() as logs:
- stable_chunks_choice(request, None)
+ stable_chunks_for_request(request)
# posthog/settings/logs.py configures structlog with one context dict per thread. Nothing clears it between log calls.
# Keys that earlier code bound on this thread appear on this event. A whole-dict comparison then depends on test order.
@@ -162,35 +152,6 @@ class TestStableChunks(SimpleTestCase):
assert "/reset/" not in str(unmapped)
assert "fake-reset-token" not in str(unmapped)
- def test_a_failing_logged_out_flag_check_serves_the_hashed_build(self) -> None:
- request = RequestFactory().get("/")
- request.user = AnonymousUser()
-
- with patch("posthoganalytics.feature_enabled", side_effect=RuntimeError("flag definitions unavailable")):
- assert stable_chunks_choice(request, None) is False
-
- @parameterized.expand(
- [
- ("param on stores the choice for 30 days", "?stable_chunks=1", "1", 60 * 60 * 24 * 30),
- ("param off stores the opt-out for 30 days", "?stable_chunks=0", "0", 60 * 60 * 24 * 30),
- ("fallback leaves the cookie alone", "?stable_chunks=fallback", None, None),
- ("no param leaves the cookie alone", "", None, None),
- ]
- )
- def test_the_choice_is_persisted_on_the_response(self, _name, query, expected_value, expected_max_age):
- request = RequestFactory().get(f"/{query}")
- response = HttpResponse()
-
- persist_stable_chunks_choice(request, response)
-
- cookie = response.cookies.get(STABLE_CHUNKS_COOKIE)
- assert (cookie.value if cookie else None) == expected_value
- assert (cookie["max-age"] if cookie else None) == expected_max_age
- if expected_value:
- assert cookie is not None
- # Only the server reads the choice, so scripts on the page never need it.
- assert cookie["httponly"] is True
-
def _context_with_stable_chunks(self, stable: StableChunks) -> dict:
# no-preloaded-app-context and E2E_TESTING skip the request's team/user lookups, which need
# a database that a SimpleTestCase cannot use.
@@ -241,55 +202,3 @@ class TestStableChunks(SimpleTestCase):
context = self._context_with_stable_chunks(stable)
assert "stable_preload_css_urls" not in context
-
-
-class TestStableChunksChoiceSurvivesTheRequest(APIBaseTest):
- def _user_request(self, query: str) -> HttpRequest:
- request = RequestFactory().get(f"/{query}")
- SessionMiddleware(lambda _request: HttpResponse()).process_request(request)
- request.user = self.user
- return request
-
- @parameterized.expand([("opting in", "1"), ("opting out", "0")])
- def test_rendering_a_page_persists_the_choice(self, _name, param):
- # Any template exercises this: render_template persists the choice for every page it
- # returns, and the app shell template only exists after a frontend build.
- request = self._user_request(f"?stable_chunks={param}")
-
- response = render_template("sso_reauth_complete.html", request)
-
- assert response.cookies[STABLE_CHUNKS_COOKIE].value == param
-
- @parameterized.expand(
- [
- ("flag on", "", FLAG_ON, True),
- ("flag off", "", FLAG_OFF, False),
- ("flag without a local definition", "", {}, False),
- ("flag evaluation failed", "", None, False),
- ("fallback with the flag on", "?stable_chunks=fallback", FLAG_ON, False),
- ]
- )
- def test_the_flag_picks_the_build_it_bootstraps(self, _name, query, flags, expect_stable):
- request = self._user_request(query)
- # The logged-out part of the map leaves the entry out, so only the whole map holds it.
- stable = StableChunks(
- imports={"@c/eAAAA": "static/index-S0000000000.js"},
- preload_js_urls=(),
- authenticated_preload_js_urls=(),
- logged_out_specifiers=frozenset(),
- )
-
- with (
- patch("posthoganalytics.get_all_flags", return_value=flags) as get_all_flags,
- patch("posthog.stable_chunks._resolve_stable_chunks", return_value=stable),
- ):
- context = get_context_for_template("index.html", request)
-
- assert context.get("stable_chunks", False) == expect_stable
- if expect_stable:
- assert json.loads(context["stable_chunks_importmap"])["imports"] == {
- "@c/eAAAA": f"{context['js_url']}/static/index-S0000000000.js"
- }
- assert context["posthog_bootstrap"].get("featureFlags") == flags
- get_all_flags.assert_called_once()
- assert get_all_flags.call_args.kwargs["only_evaluate_locally"] is True
diff --git a/posthog/utils.py b/posthog/utils.py
index 592f772b424f..927a91fd0028 100644
--- a/posthog/utils.py
+++ b/posthog/utils.py
@@ -62,7 +62,7 @@ from posthog.metrics import KLUDGES_COUNTER
from posthog.redis import get_client
from posthog.run_mode import run_mode
from posthog.security.url_validation import has_ambiguous_authority
-from posthog.stable_chunks import persist_stable_chunks_choice, stable_chunks_for_request
+from posthog.stable_chunks import stable_chunks_for_request
from products.feature_flags.backend.persisted_flags import get_dynamic_persisted_feature_flags
@@ -826,7 +826,7 @@ def _build_template_context(
context["preload_css_url"], context["preload_js_urls"], context["preload_font_url"] = _resolve_entry_assets(
is_authenticated
)
- stable_chunks = stable_chunks_for_request(request, posthog_bootstrap.get("featureFlags"))
+ stable_chunks = stable_chunks_for_request(request)
if stable_chunks:
context["stable_chunks"] = True
context["stable_chunks_importmap"] = stable_chunks.import_map_json(
@@ -913,7 +913,6 @@ def render_template(
response.status_code = status_code
if not request.user.is_anonymous:
patch_cache_control(response, no_store=True)
- persist_stable_chunks_choice(request, response)
return response