Janady13/crawler-signal-reference / framework-http-3xx-status-codes.md

1# framework-http-3xx-status-codes.md 2 3Comprehensive reference for the HTTP 3xx Redirection status codes, the second framework in the status codes series after framework-http-2xx-status-codes.md. Covers `301 Moved Permanently` (strong canonical signal), `302 Found` (temporary, original URL retained), `303 See Other` (explicit method change to GET), `304 Not Modified` (conditional GET success, not actually a redirect), `307 Temporary Redirect` (preserves request method), and `308 Permanent Redirect` (preserves method, modern 301). Built for Bubbles (Debian, Nginx 1.26+, self hosted origin at 169.155.162.118, no Cloudflare or third party CDN in front). Companion to the eight HTTP header frameworks plus framework-http-2xx-status-codes.md, UNIVERSAL-RANKING-FRAMEWORK.md, and SEO BUILD REFERENCE v2.4. 4 5Audience: humans configuring nginx redirects, AI assistants generating redirect logic that preserves SEO equity, SEO operators planning site migrations or domain consolidations, security auditors checking for open redirect vulnerabilities, and anyone troubleshooting "ranking dropped after migration", "POST request becoming GET after redirect", "redirect chain showing in scanner reports", or "Google not transferring authority to new URL". 6 7This framework also documents the **14 paying client subdomain redirect pattern** Joseph deployed in the recent Bubbles infrastructure overhaul (handledtax.thatwebhostingguy.com to handledtax.com, arcounselingandwellness.thatwebhostingguy.com to arcounselingandwellness.com, etc) as the canonical reference for similar future migrations. 8 9--- 10 11## TABLE OF CONTENTS 12 131. Definition 142. Why It Matters 153. What This Covers 164. The 3xx Mental Model (read this first) 175. The Method Preservation Matrix 186. 301 Moved Permanently (the canonical permanent redirect) 197. 302 Found (the temporary redirect with historical ambiguity) 208. 303 See Other (explicit method change to GET) 219. 304 Not Modified (the conditional GET success, not actually a redirect) 2210. 307 Temporary Redirect (preserves request method, 302's strict cousin) 2311. 308 Permanent Redirect (preserves request method, 301's modern equivalent) 2412. The Canonicalization Signal Strength Hierarchy 2513. The One Hop Rule (redirect chains are crawl budget killers) 2614. The HTTP To HTTPS Plus HSTS Interaction 2715. The Open Redirect Vulnerability (security) 2816. The Bubbles Subdomain To Canonical Domain Pattern 2917. How Major Crawlers React To Each 3xx Code 3018. Asset Class And Use Case Recipes 3119. Bubbles Nginx Reference Block (paste ready) 3220. Audit Checklist (50+ items) 3321. Common Pitfalls 3422. Diagnostic Commands 3523. Cross-References 36 37--- 38 39## 1. DEFINITION 40 413xx status codes signal that the client must take additional action to complete the request. In practice, this means "go fetch a different URL". The response carries a `Location` header pointing to the new URL (for redirects) or signals that the cached version is still valid (for 304). Defined in RFC 9110. 42 43The 3xx family splits along two axes: 44 45**Permanence axis:** 46 47* **Permanent**: 301, 308. The change is forever. Update bookmarks, internal links, sitemaps, canonical tags. Search engines transfer ranking signals to the new URL. 48* **Temporary**: 302, 303, 307. The original URL remains canonical. Search engines keep the original indexed and continue crawling it. 49* **Special**: 304 is not a redirect. It tells the client to use its cached copy. 50 51**Method preservation axis:** 52 53* **Method may change**: 301, 302. Per spec, the client MAY change POST to GET; in practice most browsers DO change. Used historically for navigation redirects. 54* **Method explicitly forced to GET**: 303. Used after POST to redirect to a result page. 55* **Method explicitly preserved**: 307, 308. POST stays POST, PUT stays PUT, DELETE stays DELETE. Used for API endpoints and form submissions. 56 57The combination creates a 2x2 grid of redirect semantics (plus 303 and 304 as special cases): 58 59``` 60 Method may change Method preserved 61 ────────────────── ───────────────── 62Permanent (301/308) 301 Moved Permanently 308 Permanent Redirect 63Temporary (302/307) 302 Found 307 Temporary Redirect 64``` 65 66For SEO, the permanence axis is the critical one: 301 and 308 transfer ranking equity; 302 and 307 do not (the original URL stays in the index). For APIs and form submissions, the method preservation axis is critical: 307/308 keep POST intact; 301/302 may downgrade to GET. 67 68--- 69 70## 2. WHY IT MATTERS 71 72Eight independent pressures push correct 3xx usage from "default behavior" to "actively managed signal" in 2025 and forward. 73 74**Permanent redirects transfer almost all ranking equity.** Google has confirmed since 2016 that PageRank is not lost across 30x redirects (no dampening). Site migrations using 301 or 308 retain nearly all accumulated authority. Misconfigured migrations using 302 or temporary redirects do not. 75 76**Temporary redirects keep the original URL indexed.** Google treats 302 and 307 as signals that the original URL should remain canonical. The destination URL gets less attention. Sites that should be canonicalizing to a new domain but use 302 instead see the old URL persist in search results indefinitely. 77 78**Redirect chains drain crawl budget.** Each hop in a chain is a request the crawler must follow before reaching content. Googlebot follows up to 10 hops then gives up. AI crawlers (ClaudeBot, GPTBot) typically follow fewer. A long chain on a high traffic page wastes thousands of crawler fetches per day. 79 80**Method preservation matters for APIs and forms.** A client posts data to `/api/v1/users`, gets 301 to `/api/v2/users`. Browser changes POST to GET on the second request. Data is lost. The fix is 308 (which preserves POST) or designing API migrations to support both versions during transition. 81 82**Browser caches redirects aggressively.** A 301 cached by a browser persists across sessions and is hard to clear. Bad 301s deployed accidentally affect users for weeks. Bubbles operators have to assume any 301 they deploy will be cached widely. 83 84**HSTS interacts with HTTPS redirects.** A 301 from HTTP to HTTPS bootstraps HSTS. Once the browser has HSTS for the origin, it never even attempts HTTP again. This is correct behavior but means rollback is hard if HTTPS has problems. 85 86**Open redirect vulnerabilities are common.** An endpoint like `/redirect?url=...` that takes any URL and returns 302 is a phishing tool: attackers craft `https://yoursite.com/redirect?url=https://evil.com/fake-login` and the URL appears legitimate to victims. Every site needs an allow list for redirect destinations. 87 88**304 Not Modified saves enormous crawler bandwidth.** When the client sends `If-Modified-Since` or `If-None-Match` and the resource has not changed, returning 304 with no body is the correct response. Servers that always return 200 with full content waste crawler budget on every revisit. 89 90**Cost of getting it wrong.** Misconfigured 3xx codes produce silent ranking damage, broken API integrations, and security incidents. Real examples: 91 92* Site migration to new domain uses 302 instead of 301 because the developer was "not sure if permanent yet". Original domain stays indexed. New domain accumulates no ranking signal for months. Total traffic stays flat or drops despite better content. 93* API endpoint moved from `/api/v1/` to `/api/v2/`. Used 301. Client POST requests become GET requests. Data lost. Three weeks of partial outage before someone correlates the migration with the data loss. 94* Site had a 4-hop chain: `http://example.com/old` to `https://example.com/old` to `https://www.example.com/old` to `https://www.example.com/new`. Googlebot followed once, then 5,800 thin location pages drained the rest of the day's crawl budget. New content discovered weeks later than necessary. 95* Open redirect on `/click?to=` parameter. Phishing campaigns used the trusted domain as a wrapper. Email security gateways flagged the site as a phishing source. Deliverability collapsed across the entire domain for two months. 96* Conditional GET not implemented. Googlebot's revisits return 200 with full body every time. Crawl budget depleted. New pages discovered slowly. 97 98All preventable with the rules below. 99 100--- 101 102## 3. WHAT THIS COVERS 103 104Each of the six status codes (300 is omitted, almost never used) gets the same six part treatment: 105 1061. **What it means**: the canonical RFC definition plus practical implication. 1072. **When to use it**: which scenarios warrant this specific code. 1083. **How to return it in nginx and FastAPI**: paste ready config and code. 1094. **How crawlers react**: indexing pipeline behavior per major crawler. 1105. **How to verify**: curl commands and observation patterns. 1116. **Common misuse and how to fix**: typical wrong choices and replacements. 112 113Sections 12 to 16 are deep dives on cross cutting concerns: the canonicalization signal hierarchy, the one hop rule, the HSTS interaction, the open redirect vulnerability, and the Bubbles subdomain to canonical domain pattern (the 14 paying client redirect setup). 114 115--- 116 117## 4. THE 3xx MENTAL MODEL (READ THIS FIRST) 118 119A 3xx response says "this is not where the content is; go elsewhere". The client looks at the Location header (for redirects) and fetches that URL instead. Internalize the decision tree. 120 121``` 122You need the client to look at a different URL. Why? 123 | 124 |---> The resource has permanently moved 125 | | 126 | |---> Method preservation matters (POST stays POST) .......... 308 Permanent Redirect 127 | | 128 | |---> Method preservation does NOT matter (typical) ........... 301 Moved Permanently 129 | 130 |---> The resource is temporarily at a different URL 131 | | 132 | |---> Method preservation matters (POST stays POST) .......... 307 Temporary Redirect 133 | | 134 | |---> Method preservation does NOT matter (typical) ........... 302 Found 135 | 136 |---> Request was POST; want the client to GET something else ........ 303 See Other 137 | 138 |---> Client has cached this, version is still fresh ................ 304 Not Modified 139``` 140 141Six rules govern the system: 142 1431. **Permanent (301/308) for SEO equity transfer.** Use these only when the move is genuinely permanent. The signal is hard to reverse. 1442. **Temporary (302/307) for short term redirects.** Login flows, A/B tests, maintenance pages. 1453. **303 after POST to force GET.** The classic post/redirect/get pattern to prevent double form submission. 1464. **308 over 301 for API endpoints.** Method preservation prevents data loss. 1475. **One hop only.** No chains. Update internal links to point at the final destination. 1486. **304 needs no Location header.** It is not a redirect; it is "use your cache". 149 150A correctly configured server uses permanent redirects sparingly and only when warranted, uses temporary redirects for genuinely temporary situations, preserves request methods for API and form endpoints, and never builds redirect chains. 151 152--- 153 154## 5. THE METHOD PRESERVATION MATRIX 155 156The single most critical operational detail in the 3xx family. Per RFC 9110: 157 158| Status Code | Method Preservation | 159|---|---| 160| 301 Moved Permanently | Client **MAY** rewrite the method. Browsers historically rewrite POST to GET | 161| 302 Found | Client **MAY** rewrite the method. Browsers historically rewrite POST to GET | 162| 303 See Other | Client **MUST** use GET for the followup | 163| 307 Temporary Redirect | Client **MUST** preserve the original method | 164| 308 Permanent Redirect | Client **MUST** preserve the original method | 165 166The "MAY rewrite" wording for 301/302 is responsible for years of subtle bugs. In practice: 167 168* **Browsers** following 301 or 302 in response to a POST: **change to GET** (the de facto standard, not the spec). 169* **HTTP libraries** (Python requests, curl, etc): behavior varies. Some preserve POST, some change to GET, some require explicit configuration. 170* **API consumers**: never assume. Test the exact behavior. 171 172For unambiguous behavior, use 307 (temporary, method preserved) or 308 (permanent, method preserved). They were specifically added in HTTP/1.1 and HTTP/1.1 RFC 7538 to remove the 301/302 ambiguity. 173 174### 5.1 When Method Preservation Matters 175 176* **API endpoints with POST/PUT/PATCH/DELETE**: client sends data; redirect to a new URL needs to carry the same data and method. 177* **Form submissions**: HTML forms POSTing to an endpoint. If the endpoint moves, the form data must arrive at the new endpoint. 178* **Webhook endpoints**: third party services POSTing JSON to a registered URL. If the URL changes, the POST must reach the new location intact. 179* **Idempotent updates (PUT)**: client PUTs new data; redirect must deliver the PUT to the new URL. 180 181### 5.2 When Method Preservation Does NOT Matter 182 183* **Marketing site URLs**: humans clicking links (always GET). 184* **Sitemap URLs**: crawlers GETting. 185* **Image and asset URLs**: GETs. 186* **Login flow redirects after authentication**: typically GET to the dashboard. 187 188For these, 301 (permanent) or 302 (temporary) is fine because the client was going to GET anyway. 189 190### 5.3 The 303 Special Case 191 192303 is unique: regardless of the original method, the client MUST use GET to follow it. The canonical use case is the post/redirect/get (PRG) pattern: 193 1941. Client POSTs form data to `/submit`. 1952. Server processes the data (saves to database, sends email). 1963. Server responds 303 to `/thank-you`. 1974. Browser GETs `/thank-you`. 1985. User refreshes the page: it GETs `/thank-you` again, not POSTing the form a second time. 199 200Without 303, refreshing the post action page might re submit the form. With 303, the URL changes to the thank you page, refresh is safe. 201 202In practice, 302 is often used for the same purpose (and works because browsers convert POST to GET on 302). 303 is the explicit, spec compliant version. 203 204--- 205 206## 6. 301 MOVED PERMANENTLY (THE CANONICAL PERMANENT REDIRECT) 207 208### 6.1 What It Means 209 210301 Moved Permanently signals that the resource has been permanently relocated. The Location header points to the new canonical URL. Clients should update bookmarks, internal links should be updated, search engines should treat the new URL as canonical. Defined in RFC 9110. 211 212``` 213HTTP/2 301 Moved Permanently 214Location: https://example.com/new-url 215``` 216 217### 6.2 When To Use 301 218 219* **Site migration to a new domain.** `oldexample.com` to `newexample.com`. 220* **HTTP to HTTPS redirect.** `http://example.com/*` to `https://example.com/*`. 221* **WWW to non-WWW (or vice versa).** Pick a canonical hostname, redirect the other. 222* **Trailing slash canonicalization.** `/page` to `/page/` or `/page/` to `/page`. Pick one. 223* **URL restructuring.** `/blog/2024/01/article` to `/articles/article`. 224* **Subdomain to canonical domain.** Joseph's pattern: `handledtax.thatwebhostingguy.com` to `handledtax.com`. 225* **Removing duplicate URLs.** Multiple URLs serving the same content; pick one as canonical, redirect the rest. 226 227### 6.3 When NOT To Use 301 228 229* **Temporary maintenance or A/B testing.** Use 302 or 307 (the redirect is short term). 230* **Login flow redirects.** Use 302 or 307 (login state can change). 231* **POST/PUT/DELETE endpoint relocation.** Use 308 (method preservation). 232* **You are not sure if the move is permanent.** Use 302 first; convert to 301 later once confirmed. 233 234### 6.4 How To Return 301 235 236**In nginx, three common patterns:** 237 238Pattern 1: redirect entire server block: 239 240```nginx 241server { 242 listen 443 ssl; 243 server_name www.example.com; 244 245 ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; 246 ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; 247 248 return 301 https://example.com$request_uri; 249} 250``` 251 252Pattern 2: redirect specific path: 253 254```nginx 255location = /old-page { 256 return 301 https://example.com/new-page; 257} 258 259location /old-section/ { 260 return 301 https://example.com/new-section$request_uri; 261} 262``` 263 264Pattern 3: redirect entire domain: 265 266```nginx 267server { 268 listen 443 ssl; 269 server_name oldexample.com www.oldexample.com; 270 271 ssl_certificate /etc/letsencrypt/live/oldexample.com/fullchain.pem; 272 ssl_certificate_key /etc/letsencrypt/live/oldexample.com/privkey.pem; 273 274 return 301 https://newexample.com$request_uri; 275} 276``` 277 278**In FastAPI:** 279 280```python 281from fastapi import FastAPI 282from fastapi.responses import RedirectResponse 283 284app = FastAPI() 285 286@app.get("/old-page") 287async def old_page(): 288 return RedirectResponse(url="/new-page", status_code=301) 289``` 290 291### 6.5 How To Verify 292 293```bash 294# Confirm 301 status and Location 295curl -sI https://example.com/old-page | head -3 296# Expected: 297# HTTP/2 301 298# location: https://example.com/new-page 299 300# Follow the redirect and confirm destination returns 200 301curl -sIL https://example.com/old-page | head -10 302# Expected: 303# HTTP/2 301 304# location: https://example.com/new-page 305# (then) 306# HTTP/2 200 (the destination) 307 308# Verify the redirect transfers method (for browsers, POST becomes GET) 309curl -X POST -sIL https://example.com/old-page | grep -E "^HTTP|^Location" 310# Note: curl by default follows with GET after 301 311``` 312 313### 6.6 Crawler Reaction 314 315Per Google's documentation: 316 317> "301 (moved permanently): Googlebot follows the redirect, and the indexing pipeline uses the redirect as a strong signal that the redirect target should be canonical." 318 319Practical implication: 301 is the strongest canonical signal you can send. Combined with internal link updates, sitemap updates, and canonical tags pointing to the new URL, Google will transfer ranking signals fully within weeks (sometimes days for high authority sites). 320 321Bing's behavior: similar to Google. Bing explicitly says "persistent 302 redirects get treated as 301", confirming that the permanent vs temporary distinction is what matters most. 322 323ClaudeBot, GPTBot, OAI-SearchBot, PerplexityBot: follow 301 and treat the destination as the content URL. The old URL is effectively removed from their indices over time. 324 325### 6.7 How To Fix Common Breakage 326 327**Case: site migration used 302 instead of 301; new domain not ranking.** 328Change to 301: 329 330```nginx 331# Was: 332return 302 https://newexample.com$request_uri; 333# Now: 334return 301 https://newexample.com$request_uri; 335``` 336 337Submit the change in Google Search Console (Change of Address tool) to accelerate. The transition may still take weeks. 338 339**Case: old URL still appears in search results despite 301.** 340The 301 is correctly returning but other signals contradict it. Check: 3411. Internal links: do they still point to the old URL? Update them. 3422. Sitemap: does it list the old URL? Remove it. 3433. Canonical tags: do they point to the old URL? Update to new. 3444. External backlinks: this is harder; over time, Google figures it out. 345 346**Case: 301 cached aggressively, hard to remove.** 347Browsers cache 301s. Once cached, changing the server response does not affect cached redirects. Options: 3481. Wait it out (browser cache expires eventually). 3492. Have users clear cache. 3503. For aggressive cleanup, change the URL itself (cache miss on new URL). 351 352--- 353 354## 7. 302 FOUND (THE TEMPORARY REDIRECT WITH HISTORICAL AMBIGUITY) 355 356### 7.1 What It Means 357 358302 Found signals that the resource is temporarily at a different URL. The original URL is still canonical and should be used for future requests. Defined in RFC 9110. 359 360``` 361HTTP/2 302 Found 362Location: https://example.com/temporary-location 363``` 364 365The historical name was "Moved Temporarily" but RFC 7231 changed it to "Found" to reduce confusion with 301. 366 367### 7.2 The Method Ambiguity 368 369The HTTP/1.0 spec did not clearly define whether 302 should preserve the request method. Browsers implemented "change POST to GET" because that matched what users expected for navigation. The HTTP/1.1 spec acknowledged this as the de facto behavior. To fix the ambiguity, 303 (forces GET) and 307 (preserves method) were introduced. 370 371In 2026, 302's method behavior depends on the client: 372 373* **Browsers**: change POST to GET (de facto since 1996). 374* **curl**: change POST to GET unless told otherwise. 375* **Python requests**: change POST to GET on 302. 376* **Strict HTTP libraries**: may follow the RFC strictly and preserve method. 377 378For unambiguous behavior, use 307 or 303 instead. 379 380### 7.3 When To Use 302 381 382* **Login flow**: unauthenticated user requests `/dashboard`, gets 302 to `/login?return=/dashboard`. After login, 302 back to `/dashboard`. The original URL is still canonical. 383* **A/B testing**: route some users to a variant URL temporarily. The canonical URL should not change. 384* **Geo redirect**: send users to a regional variant temporarily. The main URL is still canonical. 385* **Maintenance redirect**: route to a maintenance page during a scheduled window. 386* **Short URL services**: `short.ly/abc` to `https://full-url.com/some-path`. Some short URL services use 302 because the destination might change. 387 388### 7.4 When NOT To Use 302 389 390* **Permanent moves**: use 301 or 308. 391* **Site migrations**: use 301. 392* **HTTPS upgrade**: use 301. 393* **POST endpoints that must preserve method**: use 307. 394 395### 7.5 How To Return 302 396 397**In nginx:** 398 399```nginx 400# Maintenance redirect (temporary) 401location / { 402 return 302 https://example.com/maintenance; 403} 404 405# Login redirect (temporary) 406location /dashboard { 407 if ($cookie_session = "") { 408 return 302 https://example.com/login?return=$request_uri; 409 } 410 try_files $uri =404; 411} 412``` 413 414**In FastAPI:** 415 416```python 417@app.get("/dashboard") 418async def dashboard(request: Request): 419 if not is_authenticated(request): 420 return RedirectResponse( 421 url="/login?return=/dashboard", 422 status_code=302 423 ) 424 return render_dashboard() 425``` 426 427Note: FastAPI's `RedirectResponse` defaults to 307 (which preserves method). For 302 behavior, explicitly set `status_code=302`. 428 429### 7.6 How To Verify 430 431```bash 432# Confirm 302 433curl -sI https://example.com/dashboard | head -3 434# Expected: 435# HTTP/2 302 436# location: /login?return=/dashboard 437 438# Verify method behavior (browser would change POST to GET) 439curl -X POST -sIL https://example.com/some-302-endpoint | grep -E "^HTTP|^Location" 440 441# Test with explicit method preservation flag (curl --request) 442# Most HTTP libraries are unpredictable on 302; test the actual client you care about 443``` 444 445### 7.7 Crawler Reaction 446 447Per Google's documentation: 448 449> "302 (found): Googlebot follows the redirect, and the indexing pipeline uses the redirect as a weak signal that the redirect target should be canonical." 450 451Practical implications: 452 453* Original URL stays in the index. 454* Destination URL gets crawled but may not be indexed. 455* If 302 persists for an extended period, Google reassesses and may eventually treat the destination as canonical (Bing does this explicitly). 456 457The Bubbles audit pattern: any 302 that has been in place for more than a few months should be reviewed. Is it actually temporary? If not, convert to 301. 458 459### 7.8 How To Fix Common Breakage 460 461**Case: 302 used for a permanent move; new URL not ranking.** 462Convert to 301: 463 464```nginx 465# Was: 466return 302 https://example.com/new; 467# Now: 468return 301 https://example.com/new; 469``` 470 471**Case: API client expects POST to be preserved through 302, but it becomes GET.** 472The client's library is following the de facto behavior. Two fixes: 4731. Server side: switch to 307 (forces method preservation). 4742. Client side: configure the HTTP library to preserve POST on 302 (varies by library). 475 476The cleaner fix is the server side change to 307. 477 478--- 479 480## 8. 303 SEE OTHER (EXPLICIT METHOD CHANGE TO GET) 481 482### 8.1 What It Means 483 484303 See Other signals that the response to the request can be found at another URL, which the client MUST retrieve with a GET request. Defined in RFC 9110. Used in the post/redirect/get pattern. 485 486``` 487POST /api/orders HTTP/2 488Content-Type: application/json 489 490{"product_id": 12847, "quantity": 1} 491 492---- 493 494HTTP/2 303 See Other 495Location: /orders/abc123/confirmation 496``` 497 498The client (browser) MUST follow with `GET /orders/abc123/confirmation`, even though the original request was POST. 499 500### 8.2 When To Use 303 501 502* **Post/redirect/get (PRG) pattern after form submission.** Prevents double submission on refresh. 503* **Result of an action is at a different URL.** POST to `/transactions/transfer` returns 303 to `/accounts/12847/recent-activity`. 504* **The response is logically separate from the action.** "I processed your request; here is where you can see the result." 505 506### 8.3 When NOT To Use 303 507 508* **You are returning the resource that was just created.** Use 201 with Location pointing to the new resource (see framework-http-2xx-status-codes.md). The client GETs that URL when it wants the full representation. 509* **The result is at the same URL.** Use 200 with the response body. 510* **The method should be preserved.** Use 307 or 308. 511 512### 8.4 The PRG Pattern Explained 513 514The post/redirect/get pattern is one of the foundational web UX patterns: 515 5161. User submits a form with POST `/checkout`. 5172. Server processes the order (charges card, creates order record). 5183. Server responds 303 to `/orders/abc123/confirmation`. 5194. Browser GETs `/orders/abc123/confirmation`. 5205. User sees the confirmation page. 5216. **Critical:** if user presses refresh, browser GETs `/orders/abc123/confirmation` again. Order is NOT charged twice. 522 523Without 303 (or 302's de facto behavior of changing POST to GET), refreshing after a form submission would re submit the form, leading to duplicate orders, double posts, etc. 524 525### 8.5 How To Return 303 526 527**In nginx (unusual; typically the upstream does this):** 528 529```nginx 530# Rare; usually 303 comes from FastAPI sidecar 531location = /submit-special { 532 return 303 /thank-you; 533} 534``` 535 536**In FastAPI:** 537 538```python 539from fastapi.responses import RedirectResponse 540 541@app.post("/checkout") 542async def checkout(order: OrderForm): 543 order_id = await process_order(order) 544 return RedirectResponse( 545 url=f"/orders/{order_id}/confirmation", 546 status_code=303 547 ) 548``` 549 550The explicit `status_code=303` is required; FastAPI's `RedirectResponse` default is 307. 551 552### 8.6 How To Verify 553 554```bash 555# Simulate a form POST and observe 303 556curl -sI -X POST -d "field=value" https://example.com/submit | head -3 557# Expected: 558# HTTP/2 303 559# location: /thank-you 560 561# Follow it; should be a GET 562curl -sIL -X POST -d "field=value" https://example.com/submit | grep -E "^HTTP|^>" 563# Look for: GET /thank-you (curl converted to GET after 303) 564``` 565 566### 8.7 Crawler Reaction 567 568Per Google's documentation, 303 is grouped with other 3xx codes in the documentation table. In practice: 569 570> "303 (see other): Googlebot follows the redirect." 571 572Crawlers do not POST so they rarely encounter 303. When they do (e.g., a third party link points to a POST result URL), they follow it as a GET to the Location target. 573 574For SEO purposes: 303 is invisible to crawlers in normal operation. 575 576--- 577 578## 9. 304 NOT MODIFIED (THE CONDITIONAL GET SUCCESS, NOT ACTUALLY A REDIRECT) 579 580### 9.1 What It Means 581 582304 Not Modified is the conditional GET success response. The client sent `If-Modified-Since` or `If-None-Match` (covered in framework-http-request-headers.md); the resource has not changed; the server returns 304 with no body. The client uses its cached copy. 583 584``` 585GET /style.css HTTP/2 586If-None-Match: "abc123" 587 588---- 589 590HTTP/2 304 Not Modified 591ETag: "abc123" 592Cache-Control: public, max-age=86400 593``` 594 595**304 is not a redirect.** It is grouped in the 3xx range historically but does not change the URL. The client uses its cached copy of the same URL. 596 597### 9.2 When To Return 304 598 599* The client sent `If-None-Match` and the resource's current ETag matches. 600* The client sent `If-Modified-Since` and the resource's `Last-Modified` is not later than the request value. 601* Both: ETag takes precedence. 602 603### 9.3 The Strict Requirements 604 605304 responses have specific requirements per RFC 9110: 606 607* **MUST NOT** have a body. 608* **MUST** include the `ETag` header if the resource has one (so the client knows the validator is still current). 609* **MUST** include the `Last-Modified` header if the resource has one. 610* **MAY** include `Cache-Control`, `Date`, `Expires`, `Vary`, and other caching related headers. 611* **MUST NOT** include `Content-Type`, `Content-Length` (with values > 0), or other body describing headers. 612 613### 9.4 How To Return 304 614 615**In nginx (automatic for static files):** 616 617```nginx 618location /assets/ { 619 root /var/www/sites/example.com; 620 # nginx auto generates ETag from file mtime + size 621 # On If-None-Match match, returns 304 automatically 622 # On If-Modified-Since match, returns 304 automatically 623} 624``` 625 626No special config required. nginx handles conditional GET for static files. 627 628**In FastAPI:** 629 630```python 631from email.utils import formatdate, parsedate_to_datetime 632from datetime import datetime, timezone 633import hashlib 634from fastapi import FastAPI, Request, Response 635 636app = FastAPI() 637 638@app.get("/dynamic-resource") 639async def dynamic_resource(request: Request): 640 content = generate_content() 641 etag = '"' + hashlib.md5(content.encode()).hexdigest()[:16] + '"' 642 643 # Check If-None-Match (ETag takes precedence) 644 inm = request.headers.get("if-none-match", "") 645 if etag in [tag.strip() for tag in inm.split(",") if tag.strip()]: 646 return Response( 647 status_code=304, 648 headers={ 649 "ETag": etag, 650 "Cache-Control": "public, max-age=300", 651 } 652 ) 653 654 # Fall back to If-Modified-Since 655 last_modified = datetime(2026, 5, 25, 14, 30, 0, tzinfo=timezone.utc) 656 ims = request.headers.get("if-modified-since") 657 if ims: 658 try: 659 ims_date = parsedate_to_datetime(ims) 660 if last_modified <= ims_date: 661 return Response( 662 status_code=304, 663 headers={ 664 "ETag": etag, 665 "Last-Modified": formatdate(last_modified.timestamp(), usegmt=True), 666 } 667 ) 668 except (TypeError, ValueError): 669 pass 670 671 return Response( 672 content=content, 673 media_type="text/html", 674 headers={ 675 "ETag": etag, 676 "Last-Modified": formatdate(last_modified.timestamp(), usegmt=True), 677 "Cache-Control": "public, max-age=300", 678 } 679 ) 680``` 681 682### 9.5 How To Verify 683 684```bash 685# Get current ETag 686ETAG=$(curl -sI https://example.com/style.css | grep -i "^etag:" | awk '{print $2}' | tr -d '\r') 687echo "Current ETag: $ETAG" 688 689# Send If-None-Match and verify 304 690curl -sI -H "If-None-Match: $ETAG" https://example.com/style.css | head -3 691# Expected: 692# HTTP/2 304 693# etag: "..." 694# (no content-length > 0) 695 696# Verify body is empty 697BYTES=$(curl -s -H "If-None-Match: $ETAG" https://example.com/style.css | wc -c) 698echo "Body bytes: $BYTES (expected 0)" 699 700# Send stale ETag and verify 200 701curl -sI -H 'If-None-Match: "stale"' https://example.com/style.css | head -3 702# Expected: HTTP/2 200 (with full body) 703``` 704 705### 9.6 Crawler Reaction 706 707Per Google's documentation: 708 709> "304 (not modified): Googlebot signals the indexing pipeline that the content is the same as last time it was crawled." 710 711Crawler implications: 712 713* The crawler does not redownload the body. 714* The crawler keeps the cached representation as the current content. 715* Crawl budget is preserved (304 response is tiny: just headers). 716 717This is the **single largest crawl budget optimization available** for a self hosted Bubbles site. Implementing conditional GET on dynamic responses can double or triple effective crawl coverage. 718 719### 9.7 The Crawl Budget Math 720 721Suppose Googlebot crawls 1000 URLs per day on your site. If 80% of those URLs have not changed since the last crawl: 722 723* **Without 304**: 1000 full responses, average 10 KB each = 10 MB transferred per day. 724* **With 304**: 200 full responses (10 KB each = 2 MB) + 800 304 responses (200 bytes each = 0.16 MB) = 2.16 MB transferred per day. 725 726That is roughly **80% bandwidth saved** and **80% server CPU saved**. The crawl budget freed up by 304s is spent on new and changed pages, accelerating their discovery. 727 728### 9.8 Common Misuse And How To Fix 729 730**Case: 304 returned with body.** 731A bug in the framework or custom code. Per spec, 304 MUST NOT have a body. Some clients fail to parse subsequent responses if 304 has a body. Fix: 732 733```python 734# WRONG 735return Response(status_code=304, content="something") 736 737# RIGHT 738return Response(status_code=304, headers={"ETag": etag}) 739``` 740 741**Case: 304 missing ETag header.** 742Without ETag in the response, the client does not know which version the 304 corresponds to. Always include the current ETag: 743 744```python 745return Response( 746 status_code=304, 747 headers={"ETag": current_etag} 748) 749``` 750 751**Case: server always returns 200 even when client sends If-None-Match.** 752Server is ignoring conditional GET headers. Either nginx is not configured (try `etag on;`) or the upstream is bypassing the check. See Section 9.4. 753 754--- 755 756## 10. 307 TEMPORARY REDIRECT (PRESERVES REQUEST METHOD, 302'S STRICT COUSIN) 757 758### 10.1 What It Means 759 760307 Temporary Redirect is the strict version of 302. Same semantics (resource temporarily elsewhere, original URL still canonical), but the client MUST preserve the original request method. Defined in RFC 9110. 761 762``` 763POST /api/v1/data HTTP/2 764Content-Type: application/json 765 766{"item": "value"} 767 768---- 769 770HTTP/2 307 Temporary Redirect 771Location: /api/v1/data-staging 772``` 773 774The browser MUST send `POST /api/v1/data-staging` with the same body. Compare to 302 where the browser would typically send GET (losing the body). 775 776### 10.2 When To Use 307 777 778* **API endpoint temporary relocation where method matters.** During a migration window, redirect POST to PUT (or to a different POST URL). 779* **Webhook receivers temporarily forwarding to a backup endpoint.** Method preservation critical. 780* **A/B testing on POST endpoints.** Route a percentage to a variant endpoint without changing method. 781* **Form action endpoint relocation during deploy.** Form POSTs preserve. 782 783### 10.3 When NOT To Use 307 784 785* **Permanent moves**: use 308 (or 301 if method does not matter). 786* **GET only resources**: use 302 (simpler, equivalent for GET). 787* **Post/redirect/get pattern**: use 303 (the explicit method change). 788 789### 10.4 The 302 vs 307 Decision 790 791For GET requests, 302 and 307 are equivalent. The difference only matters for non GET methods. The rule: 792 793* **Endpoint serves GET only**: 302 is fine. 307 is also fine (no difference for GET). 794* **Endpoint may receive POST/PUT/PATCH/DELETE**: 307 is required. 795 796For Bubbles client sites, most public URLs are GET only (humans clicking links). 302 is fine for those. For API endpoints and form processing endpoints, 307 is the safer default. 797 798### 10.5 How To Return 307 799 800**In nginx:** 801 802```nginx 803location /api/v1/data { 804 return 307 /api/v1/data-staging; 805} 806``` 807 808**In FastAPI:** 809 810```python 811from fastapi.responses import RedirectResponse 812 813@app.post("/api/v1/data") 814async def relocated(request: Request): 815 return RedirectResponse( 816 url="/api/v1/data-staging", 817 status_code=307 818 ) 819``` 820 821Note: FastAPI's `RedirectResponse` defaults to 307, so the `status_code` parameter can be omitted in this case. 822 823### 10.6 How To Verify 824 825```bash 826# POST to 307 endpoint, verify method preserved on followup 827curl -sIL -X POST -d "data=test" https://example.com/api/v1/data 2>&1 | grep -E "^HTTP|^> POST|^> GET|^Location" 828 829# Expected behavior: second request is also POST 830# > POST /api/v1/data-staging HTTP/2 831# (not GET) 832``` 833 834### 10.7 Crawler Reaction 835 836Similar to 302: Googlebot follows the redirect, uses it as a weak signal that the destination should be canonical. Original URL retained in the index. 837 838For API endpoints (which crawlers should not be crawling anyway, per X-Robots-Tag: noindex), this is moot. 839 840--- 841 842## 11. 308 PERMANENT REDIRECT (PRESERVES REQUEST METHOD, 301'S MODERN EQUIVALENT) 843 844### 11.1 What It Means 845 846308 Permanent Redirect is the strict version of 301. Same SEO semantics (permanent, strong canonical signal), but the client MUST preserve the original request method. Defined in RFC 7538. 847 848``` 849POST /api/v1/users HTTP/2 850Content-Type: application/json 851 852{"name": "Joseph"} 853 854---- 855 856HTTP/2 308 Permanent Redirect 857Location: /api/v2/users 858``` 859 860The browser MUST send `POST /api/v2/users` with the same body. 861 862### 11.2 When To Use 308 863 864* **Permanent API endpoint relocation where method matters.** `/api/v1/users` to `/api/v2/users` and all client POSTs must continue to work. 865* **Form action endpoint permanent move.** Form submissions must route to the new endpoint. 866* **Webhook receiver permanent move.** Webhook senders must continue posting. 867 868### 11.3 When NOT To Use 308 869 870* **Method preservation does not matter.** Use 301 (equivalent for GET, more widely understood). 871* **The move is temporary.** Use 307 (temporary equivalent). 872 873### 11.4 The 301 vs 308 Decision 874 875For GET requests, 301 and 308 are equivalent. Google treats them identically for canonical signal strength. The difference only matters for non GET methods. The rule: 876 877* **Endpoint is GET only**: 301 is fine. 308 is also fine. 878* **Endpoint may receive POST/PUT/PATCH/DELETE**: 308 is required. 879 880**No SEO upgrade from switching 301 to 308.** Google treats them equivalently. The only reason to use 308 over 301 is method preservation for non GET endpoints. 881 882### 11.5 How To Return 308 883 884**In nginx:** 885 886```nginx 887# Permanent API migration with method preservation 888location /api/v1/ { 889 return 308 /api/v2/$request_uri; 890} 891 892# Note: $request_uri starts with /api/v1/..., so this produces /api/v2//api/v1/... 893# Use a regex or explicit handling instead: 894 895location /api/v1/users { 896 return 308 /api/v2/users; 897} 898 899# Or using a rewrite pattern (one location per major endpoint) 900``` 901 902For more complex API migrations, FastAPI is usually the cleaner approach. 903 904**In FastAPI:** 905 906```python 907from fastapi.responses import RedirectResponse 908 909@app.api_route("/api/v1/users", methods=["GET", "POST", "PUT", "DELETE"]) 910async def v1_users_migrated(): 911 return RedirectResponse( 912 url="/api/v2/users", 913 status_code=308 914 ) 915``` 916 917### 11.6 How To Verify 918 919```bash 920# Permanent API migration: POST should remain POST 921curl -sIL -X POST -d '{"name":"test"}' \ 922 -H "Content-Type: application/json" \ 923 https://api.example.com/api/v1/users 2>&1 | grep -E "^HTTP|^> POST|^Location" 924 925# Expected: 926# HTTP/2 308 927# Location: /api/v2/users 928# > POST /api/v2/users HTTP/2 929# (second request is POST with same body) 930``` 931 932### 11.7 Crawler Reaction 933 934Per Google's documentation: 308 is treated the same as 301 for canonical signal purposes. Strong signal that the destination is canonical. 935 936In practice: 308 is invisible to crawlers because crawlers GET (and 301/308 are equivalent for GET). 937 938--- 939 940## 12. THE CANONICALIZATION SIGNAL STRENGTH HIERARCHY 941 942A summary of how strongly each redirect signals "use the destination as canonical": 943 944| Signal Strength | Redirects | Notes | 945|---|---|---| 946| **Strongest** | 301, 308 | Google fully transfers ranking; old URL drops from index over weeks | 947| **Weak** | 302, 307 | Google retains old URL as canonical; destination crawled but may not be indexed | 948| **Method specific** | 303 | Forces GET; for the PRG pattern, not for canonicalization | 949| **Not a canonical signal** | 304 | Same URL; no canonical change | 950 951**Bing's adaptive behavior:** Bing treats persistent 302 as if it were 301 (after a few months). Conversely, "flapping" 301 (where the redirect target keeps changing) gets demoted to 302 strength. 952 953**Google's behavior:** Google does similar reassessment over time but does not document it explicitly. A 302 that has been in place for a year may eventually be treated as canonical, but the path is unpredictable. The clean approach is to use the correct redirect type from the start. 954 955**Practical rule for the Bubbles audit:** every redirect in the config should be examined. If it has been in place for more than 90 days and is genuinely permanent, it should be 301 or 308. If it is genuinely temporary, it should remain 302 or 307. 956 957--- 958 959## 13. THE ONE HOP RULE (REDIRECT CHAINS ARE CRAWL BUDGET KILLERS) 960 961### 13.1 The Problem 962 963A redirect chain is a sequence of redirects that the client must follow before reaching the final destination: 964 965``` 966http://example.com/old-page 967 | 968 v (301) 969https://example.com/old-page 970 | 971 v (301) 972https://www.example.com/old-page 973 | 974 v (301) 975https://www.example.com/new-page 976``` 977 978Each hop costs: 979 980* **A round trip** from client to server (latency). 981* **A crawler request** (crawl budget). 982* **A weakened canonical signal** (the longer the chain, the less Google trusts the destination). 983 984Googlebot follows up to 10 hops then gives up. Most modern AI crawlers follow fewer (PerplexityBot, ClaudeBot may give up after 3 to 5). Browsers follow up to 20 by default but flag warnings. 985 986### 13.2 The Rule 987 988**Maximum one hop from any source URL to the final destination.** Period. 989 990The chain above should be collapsed to: 991 992``` 993http://example.com/old-page 994 | 995 v (single 301) 996https://www.example.com/new-page 997``` 998 999### 13.3 How To Eliminate Chains 1000 1001Audit existing redirects: 1002 1003```bash 1004# Find chains by following redirects with curl 1005for url in $(curl -s https://example.com/sitemap.xml | grep -oE "<loc>[^<]+</loc>" | sed 's/<[^>]*>//g'); do 1006 HOPS=$(curl -sIL "$url" | grep -c "^HTTP") 1007 if [ "$HOPS" -gt 2 ]; then 1008 echo "CHAIN ($HOPS hops): $url" 1009 fi 1010done 1011``` 1012 1013Combine multiple redirects into one: 1014 1015```nginx 1016# BEFORE: three redirects 1017server { 1018 listen 80; 1019 server_name example.com www.example.com; 1020 return 301 https://example.com$request_uri; # hop 1 1021} 1022 1023server { 1024 listen 443 ssl; 1025 server_name www.example.com; 1026 return 301 https://example.com$request_uri; # hop 2 1027} 1028 1029server { 1030 listen 443 ssl; 1031 server_name example.com; 1032 1033 location /old-page { 1034 return 301 /new-page; # hop 3 1035 } 1036} 1037 1038# AFTER: collapsed 1039server { 1040 listen 80; 1041 server_name example.com www.example.com; 1042 return 301 https://example.com$request_uri; # single redirect from HTTP 1043} 1044 1045server { 1046 listen 443 ssl; 1047 server_name www.example.com; 1048 return 301 https://example.com$request_uri; # www to non-www in one hop 1049} 1050 1051server { 1052 listen 443 ssl; 1053 server_name example.com; 1054 1055 location = /old-page { 1056 return 301 /new-page; # direct redirect to final 1057 } 1058} 1059 1060# Old URLs that should go to a new specific page: 1061# location = /http-www-old-page { return 301 https://example.com/new-page; } 1062``` 1063 1064The principle: every old URL goes directly to its final destination in one step. No intermediate hops. 1065 1066### 13.4 The Internal Links Audit 1067 1068Even with clean server side redirects, internal links pointing at old URLs cause unnecessary hops. Audit: 1069 1070```bash 1071# Find HTML files containing references to URLs that get redirected 1072grep -r "https://example.com/old-page" /var/www/sites/example.com/ \ 1073 | grep -v ".git" 1074 1075# For each match, update to the new URL 1076``` 1077 1078For a Bubbles client site migration, this is a project: update every HTML file, every CMS database row, every sitemap entry to use the final URL. The redirect remains as a safety net for external links Joseph cannot control. 1079 1080--- 1081 1082## 14. THE HTTP TO HTTPS PLUS HSTS INTERACTION 1083 1084### 14.1 The Standard Pattern 1085 1086Every Bubbles site upgrades HTTP to HTTPS via 301: 1087 1088```nginx 1089server { 1090 listen 80; 1091 listen [::]:80; 1092 server_name example.com www.example.com; 1093 return 301 https://example.com$request_uri; 1094} 1095 1096server { 1097 listen 443 ssl; 1098 server_name example.com; 1099 # ... 1100 add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always; 1101} 1102``` 1103 1104The 301 from HTTP to HTTPS is the bootstrap. After the first visit, HSTS (set on the HTTPS response) takes over and the browser never even tries HTTP again. 1105 1106### 14.2 The HSTS Permanence 1107 1108HSTS is one way (covered in framework-http-security-headers.md). Once a browser has HSTS for an origin: 1109 1110* All requests to `http://` are automatically upgraded to `https://` before leaving the browser. 1111* Certificate errors cannot be clicked through. 1112* The behavior persists for the duration of `max-age`. 1113 1114For HSTS preloaded sites, the behavior is permanent even on first visit (the browser ships with the preload list). 1115 1116Operational implication: rolling back from HTTPS is hard. The 301 plus HSTS combination is effectively permanent. 1117 1118### 14.3 The Single Hop From HTTP 1119 1120For the HSTS bootstrap to be clean, the HTTP to HTTPS redirect must be a single hop: 1121 1122```nginx 1123# CORRECT: one hop from HTTP to final HTTPS 1124server { 1125 listen 80; 1126 server_name example.com www.example.com; 1127 return 301 https://example.com$request_uri; 1128} 1129 1130# WRONG: two hops 1131server { 1132 listen 80; 1133 server_name example.com www.example.com; 1134 return 301 https://www.example.com$request_uri; # hop 1: HTTP to HTTPS www 1135} 1136 1137server { 1138 listen 443 ssl; 1139 server_name www.example.com; 1140 return 301 https://example.com$request_uri; # hop 2: www to non-www 1141} 1142``` 1143 1144The correct pattern: HTTP to HTTPS canonical (non www) in one hop. www subdomain HTTPS to non www HTTPS as a separate one hop. 1145 1146### 14.4 Verification 1147 1148```bash 1149# Should be exactly one hop from HTTP 1150curl -sIL http://example.com/ | grep -c "^HTTP" 1151# Expected: 2 (the 301 and the final 200) 1152 1153# Should be no upgrade attempt if HSTS is cached 1154curl -sI -H "Origin: https://example.com" http://example.com/ 1155# Browser would auto upgrade; curl does not unless told 1156 1157# Check HSTS is being sent on HTTPS responses 1158curl -sI https://example.com/ | grep -i strict-transport-security 1159# Expected: max-age=63072000; includeSubDomains; preload 1160``` 1161 1162--- 1163 1164## 15. THE OPEN REDIRECT VULNERABILITY (SECURITY) 1165 1166### 15.1 What It Is 1167 1168An open redirect is an endpoint that takes a URL as a parameter and redirects to it without validation: 1169 1170```python 1171# DANGEROUS: open redirect 1172@app.get("/redirect") 1173async def redirect_to(url: str): 1174 return RedirectResponse(url=url, status_code=302) 1175``` 1176 1177A request to `https://example.com/redirect?url=https://evil.com/fake-login` returns 302 to evil.com. The URL in the browser bar reads as the trusted domain. Phishing attacks use this pattern routinely. 1178 1179### 15.2 Why It Is Dangerous 1180 1181Phishing emails want to use trusted domains to evade spam filters: 1182 1183* Email contains link to `https://example.com/redirect?url=...`. 1184* Spam filter sees example.com is trusted. 1185* User clicks; browser hits example.com first, then redirects to evil.com. 1186* User's phishing detection trigger (the URL bar) shows the trusted domain in the link they clicked. 1187 1188Email security gateways flag domains as phishing sources when open redirects are abused. The reputation damage to the trusted domain is real. 1189 1190### 15.3 The Three Defense Patterns 1191 1192**Pattern 1: Allow list of destinations.** 1193 1194```python 1195ALLOWED_REDIRECT_HOSTS = { 1196 "example.com", 1197 "www.example.com", 1198 "app.example.com", 1199 "partner.example.com", 1200} 1201 1202from urllib.parse import urlparse 1203 1204@app.get("/redirect") 1205async def redirect_to(url: str): 1206 parsed = urlparse(url) 1207 if parsed.netloc not in ALLOWED_REDIRECT_HOSTS: 1208 raise HTTPException(status_code=400, detail="redirect destination not allowed") 1209 return RedirectResponse(url=url, status_code=302) 1210``` 1211 1212**Pattern 2: Path only redirects.** 1213 1214```python 1215@app.get("/redirect") 1216async def redirect_to(path: str): 1217 if not path.startswith("/") or path.startswith("//"): 1218 raise HTTPException(status_code=400, detail="invalid path") 1219 return RedirectResponse(url=path, status_code=302) 1220``` 1221 1222Only allows redirects within the same origin. Cannot redirect to external sites. 1223 1224**Pattern 3: Signed redirects.** 1225 1226```python 1227import hmac 1228import hashlib 1229 1230REDIRECT_SECRET = "..." # from secret manager 1231 1232@app.get("/redirect") 1233async def redirect_to(url: str, sig: str): 1234 expected_sig = hmac.new( 1235 REDIRECT_SECRET.encode(), 1236 url.encode(), 1237 hashlib.sha256 1238 ).hexdigest()[:16] 1239 1240 if not hmac.compare_digest(sig, expected_sig): 1241 raise HTTPException(status_code=400, detail="invalid signature") 1242 1243 return RedirectResponse(url=url, status_code=302) 1244``` 1245 1246The application can generate signed URLs for legitimate redirects; attackers cannot forge them. 1247 1248### 15.4 The Bubbles Pattern 1249 1250For Bubbles client sites that need internal redirects (login flow `return_to` parameter, etc), use Pattern 2 (path only): 1251 1252```python 1253def safe_redirect_target(target: str, default: str = "/") -> str: 1254 """Return target if it is a safe internal path, else default.""" 1255 if not target: 1256 return default 1257 if not target.startswith("/"): 1258 return default 1259 if target.startswith("//"): # protocol relative URL 1260 return default 1261 if target.startswith("/\\"): # backslash trick 1262 return default 1263 return target 1264 1265@app.post("/login") 1266async def login(form: LoginForm, return_to: str = "/"): 1267 success = await authenticate(form) 1268 if success: 1269 safe_target = safe_redirect_target(return_to) 1270 return RedirectResponse(url=safe_target, status_code=302) 1271 raise HTTPException(status_code=401) 1272``` 1273 1274The `safe_redirect_target` helper prevents any redirect to a different origin. 1275 1276--- 1277 1278## 16. THE BUBBLES SUBDOMAIN TO CANONICAL DOMAIN PATTERN 1279 1280Joseph deployed this pattern during the recent infrastructure overhaul, redirecting 14 paying client subdomains from the `thatwebhostingguy.com` demo platform to their canonical custom domains. 1281 1282### 16.1 The Pattern 1283 1284Each paying client follows the same lifecycle: 1285 12861. **Stage 1 (Demo)**: client is on a subdomain of `thatwebhostingguy.com`. Example: `handledtax.thatwebhostingguy.com`. AdSense injection enabled; not yet paying. 12872. **Stage 2 (Production)**: client buys their own domain (e.g., `handledtax.com`). The thatwebhostingguy.com subdomain stays as a 301 to the canonical domain. AdSense disabled on the redirect. SEO equity transfers to the new canonical. 1288 1289### 16.2 The Nginx Configuration 1290 1291```nginx 1292# /etc/nginx/sites-available/thatwebhostingguy-wildcard 1293 1294server { 1295 listen 443 ssl; 1296 listen 443 quic; 1297 http2 on; 1298 http3 on; 1299 server_name *.thatwebhostingguy.com thatwebhostingguy.com; 1300 1301 ssl_certificate /etc/letsencrypt/live/thatwebhostingguy.com/fullchain.pem; 1302 ssl_certificate_key /etc/letsencrypt/live/thatwebhostingguy.com/privkey.pem; 1303 ssl_protocols TLSv1.2 TLSv1.3; 1304 ssl_early_data on; 1305 1306 add_header Alt-Svc 'h3=":443"; ma=86400' always; 1307 1308 # ============= 14 PAYING CLIENT 301 REDIRECTS ============= 1309 # These subdomains are paying clients with their own canonical domains. 1310 # 301 transfers SEO equity from the demo subdomain to the production domain. 1311 1312 if ($host = "arcounselingandwellness.thatwebhostingguy.com") { 1313 return 301 https://arcounselingandwellness.com$request_uri; 1314 } 1315 if ($host = "eurekabathworks.thatwebhostingguy.com") { 1316 return 301 https://eurekabathworks.com$request_uri; 1317 } 1318 if ($host = "heritagehardwoodfloors.thatwebhostingguy.com") { 1319 return 301 https://heritagehardwoodfloorsnwa.com$request_uri; 1320 } 1321 if ($host = "localliving.thatwebhostingguy.com") { 1322 return 301 https://locallivingrealtynwa.com$request_uri; 1323 } 1324 if ($host = "janieseecleaning.thatwebhostingguy.com") { 1325 return 301 https://showmecleannwa.com$request_uri; 1326 } 1327 if ($host = "showmecleannwa.thatwebhostingguy.com") { 1328 return 301 https://showmecleannwa.com$request_uri; 1329 } 1330 if ($host = "wecoverusa.thatwebhostingguy.com") { 1331 return 301 https://wecoverusa.com$request_uri; 1332 } 1333 if ($host = "white-river-cabins.thatwebhostingguy.com") { 1334 return 301 https://whiterivercabins.com$request_uri; 1335 } 1336 if ($host = "whiterivercabins.thatwebhostingguy.com") { 1337 return 301 https://whiterivercabins.com$request_uri; 1338 } 1339 if ($host = "greenoughsguideservice.thatwebhostingguy.com") { 1340 return 301 https://greenoughsguideservice.com$request_uri; 1341 } 1342 if ($host = "beyondastep.thatwebhostingguy.com") { 1343 return 301 https://beyondastep.com$request_uri; 1344 } 1345 if ($host = "idsofnwa.thatwebhostingguy.com") { 1346 return 301 https://idsofnwa.com$request_uri; 1347 } 1348 if ($host = "marshallese-voices.thatwebhostingguy.com") { 1349 return 301 https://marshallese-voices.com$request_uri; 1350 } 1351 if ($host = "nwapoolice.thatwebhostingguy.com") { 1352 return 301 https://nwapoolice.com$request_uri; 1353 } 1354 if ($host = "handledtax.thatwebhostingguy.com") { 1355 return 301 https://handledtax.com$request_uri; 1356 } 1357 if ($host = "handledtaxes.thatwebhostingguy.com") { 1358 return 301 https://handledtax.com$request_uri; 1359 } 1360 1361 # ============= NON PAYING SUBDOMAINS (DEMO TIER) ============= 1362 # All other subdomains serve from their wildcard subdirectory with AdSense 1363 1364 set $subdomain ""; 1365 if ($host ~ "^([^.]+)\.thatwebhostingguy\.com$") { 1366 set $subdomain $1; 1367 } 1368 1369 root /var/www/sites/$subdomain; 1370 index index.html; 1371 1372 # AdSense injection for non paying surfaces 1373 sub_filter '</head>' '<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-1158174357019592" crossorigin="anonymous"></script></head>'; 1374 sub_filter_once on; 1375 1376 # Phase 1 wildcard noindex (do not let demo subdomains compete with canonical sites) 1377 add_header X-Robots-Tag "noindex, follow" always; 1378 1379 location / { 1380 try_files $uri $uri/ $uri.html =404; 1381 } 1382} 1383``` 1384 1385### 16.3 Verification 1386 1387```bash 1388# Verify each paying client subdomain 301s to canonical 1389for sub in arcounselingandwellness eurekabathworks heritagehardwoodfloors localliving showmecleannwa wecoverusa whiterivercabins greenoughsguideservice beyondastep idsofnwa marshallese-voices nwapoolice handledtax; do 1390 DOMAIN="$sub.thatwebhostingguy.com" 1391 DEST=$(curl -sI "https://$DOMAIN/" | grep -i "^location:" | awk '{print $2}' | tr -d '\r') 1392 STATUS=$(curl -sI "https://$DOMAIN/" | head -1 | awk '{print $2}') 1393 echo "$DOMAIN -> $STATUS -> $DEST" 1394done 1395 1396# Expected output (each line): 1397# arcounselingandwellness.thatwebhostingguy.com -> 301 -> https://arcounselingandwellness.com/ 1398# etc. 1399``` 1400 1401### 16.4 The SEO Recovery Timeline 1402 1403After deploying the 301 redirects: 1404 1405* **Week 1**: Googlebot encounters the 301s. Crawls the destination URLs. Starts transferring ranking signals. 1406* **Month 1**: Canonical sites begin ranking for terms previously held by the subdomain demos. 1407* **Month 3**: Demo subdomain URLs drop out of search results. 1408* **Month 6**: SEO equity fully transferred. Old subdomain URLs effectively deindexed. 1409 1410This is the standard timeline for clean 301 migrations. The Bubbles 14 client deployment was on this trajectory at the time of the recent overhaul. 1411 1412--- 1413 1414## 17. HOW MAJOR CRAWLERS REACT TO EACH 3XX CODE 1415 1416Quick reference for auditing. 1417 1418| Code | Googlebot | Bingbot | ClaudeBot | GPTBot | 1419|---|---|---|---|---| 1420| 301 | Strong canonical signal; transfers ranking | Strong canonical signal | Treats destination as content URL | Treats destination as content URL | 1421| 302 | Weak canonical signal; keeps origin indexed | Persistent 302 eventually treated as 301 | Follows; less aggressive than 301 | Follows; less aggressive than 301 | 1422| 303 | Follows | Follows | Follows (rare, only after POST) | Follows | 1423| 304 | Uses cached representation; saves crawl budget | Uses cached | Uses cached if maintaining cache | Uses cached if maintaining cache | 1424| 307 | Weak signal (same as 302) | Treats like 302 | Follows | Follows | 1425| 308 | Strong signal (same as 301) | Strong signal | Follows | Follows | 1426 1427**Key implications for Bubbles SEO:** 1428 1429* For migrations: use 301 (or 308 if method matters). 1430* For login flows and A/B tests: 302 or 307. 1431* For HSTS bootstrap: 301 (the HTTP to HTTPS upgrade). 1432* For canonical hostname enforcement (www vs non www): 301. 1433 1434--- 1435 1436## 18. ASSET CLASS AND USE CASE RECIPES 1437 1438Paste ready blocks per scenario. 1439 1440### 18.1 Standard HTTP to HTTPS plus canonical hostname (Bubbles default) 1441 1442```nginx 1443# HTTP to HTTPS (one hop) 1444server { 1445 listen 80; 1446 listen [::]:80; 1447 server_name example.com www.example.com; 1448 return 301 https://example.com$request_uri; 1449} 1450 1451# www HTTPS to non www HTTPS (one hop) 1452server { 1453 listen 443 ssl; 1454 listen [::]:443 ssl; 1455 http2 on; 1456 server_name www.example.com; 1457 ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; 1458 ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; 1459 return 301 https://example.com$request_uri; 1460} 1461 1462# Canonical server 1463server { 1464 listen 443 ssl; 1465 listen 443 quic; 1466 http2 on; 1467 http3 on; 1468 server_name example.com; 1469 ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; 1470 ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; 1471 # ... rest of config ... 1472} 1473``` 1474 1475### 18.2 Specific page permanent redirect (301) 1476 1477```nginx 1478location = /old-page { 1479 return 301 /new-page; 1480} 1481 1482# Or with regex for pattern matching 1483location ~* ^/blog/2024/[0-9]+/(.+)$ { 1484 return 301 /articles/$1; 1485} 1486``` 1487 1488### 18.3 Login flow redirect (302 with return_to) 1489 1490```python 1491@app.get("/dashboard") 1492async def dashboard(request: Request): 1493 if not is_authenticated(request): 1494 return RedirectResponse( 1495 url=f"/login?return_to=/dashboard", 1496 status_code=302 1497 ) 1498 return render_dashboard() 1499 1500@app.post("/login")