diff --git a/src/components/Social/Highlighter/HighlighterIconBank.astro b/src/components/Social/Highlighter/HighlighterIconBank.astro
new file mode 100644
index 000000000..c57af7b89
--- /dev/null
+++ b/src/components/Social/Highlighter/HighlighterIconBank.astro
@@ -0,0 +1,18 @@
+---
+/**
+ * HighlighterIconBank
+ *
+ * Renders the hidden SVG icon bank used by all HighlighterElement instances on the page.
+ * Must be rendered exactly once per page, outside any paragraph or phrasing-content context.
+ * MarkdownLayout.astro owns this responsibility.
+ */
+import Icon from '@components/Icon/index.astro'
+---
+
+
+
+
+
+
+
+
diff --git a/src/components/Social/Highlighter/client/__tests__/index.spec.ts b/src/components/Social/Highlighter/client/__tests__/index.spec.ts
index b5bcb26d1..d2a09d961 100644
--- a/src/components/Social/Highlighter/client/__tests__/index.spec.ts
+++ b/src/components/Social/Highlighter/client/__tests__/index.spec.ts
@@ -162,6 +162,7 @@ describe('HighlighterElement', () => {
const trigger = element.querySelector('.highlighter__trigger') as HTMLButtonElement | null
expect(trigger).toBeTruthy()
expect(trigger?.getAttribute('aria-label')).toBeNull()
+ expect(trigger?.getAttribute('type')).toBe('button')
expect(trigger?.textContent).toContain(defaultProps.content)
const dialog = element.querySelector('.share-dialog') as HTMLElement | null
diff --git a/src/components/Social/Highlighter/client/__tests__/selectors.spec.ts b/src/components/Social/Highlighter/client/__tests__/selectors.spec.ts
index 1fa68156f..74be4e66c 100644
--- a/src/components/Social/Highlighter/client/__tests__/selectors.spec.ts
+++ b/src/components/Social/Highlighter/client/__tests__/selectors.spec.ts
@@ -41,7 +41,7 @@ describe('HighlighterElement selectors', () => {
expect(
wrapper,
'HighlighterElement should render a wrapper with .highlighter__wrapper'
- ).toBeInstanceOf(HTMLDivElement)
+ ).toBeInstanceOf(HTMLSpanElement)
expect(
trigger,
'HighlighterElement should render a trigger with .highlighter__trigger'
@@ -49,7 +49,7 @@ describe('HighlighterElement selectors', () => {
expect(
dialog,
'HighlighterElement should render a share dialog with .share-dialog'
- ).toBeInstanceOf(HTMLDivElement)
+ ).toBeInstanceOf(HTMLSpanElement)
expect(
status,
'HighlighterElement should render a status element with [data-highlighter-status]'
@@ -66,6 +66,7 @@ describe('HighlighterElement selectors', () => {
const describedBy = trigger.getAttribute('aria-describedby')
expect(describedBy, 'HighlighterElement trigger should set aria-describedby').toBeTruthy()
+ expect(trigger.getAttribute('type')).toBe('button')
const hint = describedBy ? queryElementById(element, describedBy) : null
expect(
diff --git a/src/components/Social/Highlighter/client/index.ts b/src/components/Social/Highlighter/client/index.ts
index 72adc81a5..455b373f1 100644
--- a/src/components/Social/Highlighter/client/index.ts
+++ b/src/components/Social/Highlighter/client/index.ts
@@ -50,7 +50,7 @@ export class HighlighterElement extends LitElement {
private contentCaptured = false
private boundButtons = new WeakSet()
private triggerButton: HTMLButtonElement | null = null
- private wrapperElement: HTMLDivElement | null = null
+ private wrapperElement: HTMLSpanElement | null = null
private readonly dialogId: string
private readonly hintId: string
private readonly statusId: string
@@ -126,7 +126,7 @@ export class HighlighterElement extends LitElement {
protected override render() {
return html`
-
+
+
+
-
+
`
}
@@ -213,7 +213,7 @@ export class HighlighterElement extends LitElement {
const trigger = queryHighlighterTrigger(this)
if (!trigger || trigger === this.triggerButton) return
this.triggerButton = trigger
- this.triggerButton.style.cursor = 'pointer'
+
addButtonEventListeners(
trigger,
event => {
diff --git a/src/components/Social/Highlighter/client/selectors.ts b/src/components/Social/Highlighter/client/selectors.ts
index 9af92e0a2..e7fd27f23 100644
--- a/src/components/Social/Highlighter/client/selectors.ts
+++ b/src/components/Social/Highlighter/client/selectors.ts
@@ -1,6 +1,5 @@
import {
isButtonElement,
- isDivElement,
isSpanElement,
isType1Element,
} from '@components/scripts/assertions/elements'
@@ -16,9 +15,9 @@ export const SELECTORS = {
status: '[data-highlighter-status]',
} as const
-export const queryHighlighterWrapper = (context: Element): HTMLDivElement | null => {
+export const queryHighlighterWrapper = (context: Element): HTMLSpanElement | null => {
const wrapper = context.querySelector(SELECTORS.wrapper)
- return isDivElement(wrapper) ? wrapper : null
+ return isSpanElement(wrapper) ? wrapper : null
}
export const queryHighlighterTrigger = (context: Element): HTMLButtonElement | null => {
@@ -26,9 +25,9 @@ export const queryHighlighterTrigger = (context: Element): HTMLButtonElement | n
return isButtonElement(trigger) ? trigger : null
}
-export const queryShareDialog = (context: Element): HTMLDivElement | null => {
+export const queryShareDialog = (context: Element): HTMLSpanElement | null => {
const dialog = context.querySelector(SELECTORS.dialog)
- return isDivElement(dialog) ? dialog : null
+ return isSpanElement(dialog) ? dialog : null
}
export const queryShareButtons = (context: Element): HTMLButtonElement[] => {
@@ -37,9 +36,9 @@ export const queryShareButtons = (context: Element): HTMLButtonElement[] => {
)
}
-export const queryShareDialogArrow = (context: Element): HTMLDivElement | null => {
+export const queryShareDialogArrow = (context: Element): HTMLSpanElement | null => {
const arrow = context.querySelector(SELECTORS.dialogArrow)
- return isDivElement(arrow) ? arrow : null
+ return isSpanElement(arrow) ? arrow : null
}
export const queryShareIcon = (context: Element): SVGSVGElement | null => {
diff --git a/src/components/Social/Highlighter/index.astro b/src/components/Social/Highlighter/index.astro
index 786719550..dda50b878 100644
--- a/src/components/Social/Highlighter/index.astro
+++ b/src/components/Social/Highlighter/index.astro
@@ -17,8 +17,6 @@
* important insight
* ```
*/
-import Icon from '@components/Icon/index.astro'
-import './index.css'
export interface Props {
/**
@@ -36,21 +34,4 @@ export interface Props {
const { ariaLabel, class: className } = Astro.props
---
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
diff --git a/src/components/Social/Highlighter/index.css b/src/components/Social/Highlighter/index.css
index f63bc4a91..88546232d 100644
--- a/src/components/Social/Highlighter/index.css
+++ b/src/components/Social/Highlighter/index.css
@@ -1,39 +1,40 @@
-:where(highlighter-element) {
- display: inline-block;
+highlighter-element {
+ display: inline;
position: relative;
}
-:where(highlighter-element) .highlighter__wrapper {
- display: inline-flex;
- flex-direction: column;
+highlighter-element .highlighter__wrapper {
+ display: inline;
position: relative;
}
-:where(highlighter-element) .highlighter__trigger {
+highlighter-element .highlighter__trigger {
+ appearance: none;
background: transparent;
border: none;
color: inherit;
- cursor: inherit;
- display: inline-flex;
+ cursor: pointer;
+ display: contents;
font: inherit;
- margin: 0;
padding: 0;
text-align: left;
+ vertical-align: baseline;
+ white-space: normal;
}
-:where(highlighter-element) .highlighter__trigger:focus-visible {
- outline: 2px solid var(--color-spotlight);
- outline-offset: 2px;
-}
-
-:where(highlighter-element) .highlighter__content {
+highlighter-element .highlighter__content {
background-color: transparent;
border-radius: 0;
color: inherit;
padding: 0;
}
-:where(highlighter-element) .share-dialog {
+highlighter-element .highlighter__trigger:focus-visible .highlighter__content {
+ outline: 2px solid var(--color-spotlight);
+ outline-offset: 2px;
+}
+
+highlighter-element .share-dialog {
background-color: var(--color-page-offset);
border-radius: 0.5rem;
bottom: calc(100% + 0.75rem);
@@ -46,8 +47,8 @@
z-index: var(--z-content-floating);
}
-:where(highlighter-element) .share-dialog::before,
-:where(highlighter-element) .share-dialog::after {
+highlighter-element .share-dialog::before,
+highlighter-element .share-dialog::after {
background: transparent;
content: '';
height: 0.75rem;
@@ -57,26 +58,27 @@
right: 0;
}
-:where(highlighter-element) .share-dialog::before {
+highlighter-element .share-dialog::before {
top: -0.75rem;
}
-:where(highlighter-element) .share-dialog::after {
+highlighter-element .share-dialog::after {
bottom: -0.75rem;
}
-:where(highlighter-element) .share-dialog[aria-hidden="false"] {
+highlighter-element .share-dialog[aria-hidden="false"] {
display: block;
}
-:where(highlighter-element) .share-dialog__buttons {
+highlighter-element .share-dialog__buttons {
align-items: center;
display: flex;
gap: 0.25rem;
}
-:where(highlighter-element) .share-button {
+highlighter-element .share-button {
align-items: center;
+ appearance: none;
background-color: transparent;
border: none;
border-radius: 9999px;
@@ -89,27 +91,27 @@
width: 2.5rem;
}
-:where(highlighter-element) .share-button:hover {
+highlighter-element .share-button:focus-visible {
+ outline: 2px solid var(--color-spotlight);
+ outline-offset: 2px;
+}
+
+highlighter-element .share-button:hover {
background-color: var(--color-page-base);
transform: translateY(-1px);
}
-:where(highlighter-element) .share-button:active {
+highlighter-element .share-button:active {
transform: translateY(0);
}
-:where(highlighter-element) .share-button:focus-visible {
- outline: 2px solid var(--color-spotlight);
- outline-offset: 2px;
-}
-
-:where(highlighter-element) .share-icon {
+highlighter-element .share-icon {
fill: currentcolor;
height: 1.25rem;
width: 1.25rem;
}
-:where(highlighter-element) .share-dialog__arrow {
+highlighter-element .share-dialog__arrow {
border-left: 0.5rem solid transparent;
border-right: 0.5rem solid transparent;
border-top: 0.5rem solid var(--color-page-offset);
diff --git a/src/components/Table/layouts/semantic-coloring.astro b/src/components/Table/layouts/semantic-coloring.astro
index c5110f133..ff74ed67b 100644
--- a/src/components/Table/layouts/semantic-coloring.astro
+++ b/src/components/Table/layouts/semantic-coloring.astro
@@ -39,6 +39,11 @@ const tbodyClass = ''
const tfootClass = ''
const stateClasses = {
+ accent: {
+ rowBgClass: 'bg-accent-offset/20',
+ barClass: 'bg-accent-offset',
+ textClass: 'text-accent-offset',
+ },
note: {
rowBgClass: 'bg-note-inverse',
barClass: 'bg-note',
@@ -67,11 +72,43 @@ const stateClasses = {
} as const
type SemanticStateName = keyof typeof stateClasses
+const allowedSemanticStates: SemanticStateName[] = ['accent', 'note', 'success', 'warning', 'danger', 'info']
const isSemanticStateName = (value: string): value is SemanticStateName => {
- return value === 'note' || value === 'success' || value === 'warning' || value === 'danger' || value === 'info'
+ return allowedSemanticStates.includes(value as SemanticStateName)
+}
+
+const assertValidSemanticColor = (color: string | undefined, location: string) => {
+ if (!color || isSemanticStateName(color)) {
+ return
+ }
+
+ throw new Error(
+ `semantic-coloring-table: invalid color "${color}" at ${location}. ` +
+ `Expected one of: ${allowedSemanticStates.join(', ')}.`
+ )
}
+content.tbody.tr.forEach((row, rowIndex) => {
+ if (typeof row.th === 'object') {
+ assertValidSemanticColor(row.th.color, `tbody row ${rowIndex + 1} header`)
+ }
+
+ row.td.forEach((cell, cellIndex) => {
+ if (typeof cell === 'object') {
+ assertValidSemanticColor(cell.color, `tbody row ${rowIndex + 1} cell ${cellIndex + 1}`)
+ }
+ })
+})
+
+content.tfoot?.tr.forEach((row, rowIndex) => {
+ row.td.forEach((cell, cellIndex) => {
+ if (typeof cell === 'object') {
+ assertValidSemanticColor(cell.color, `tfoot row ${rowIndex + 1} cell ${cellIndex + 1}`)
+ }
+ })
+})
+
const firstBodyRow = content.tbody.tr[0]
const hasRowHeaders = content.tbody.tr.some(row => row.th !== undefined)
const bodyColumnCount = hasRowHeaders
diff --git a/src/components/ThemePicker/client/__tests__/selectors.spec.ts b/src/components/ThemePicker/client/__tests__/selectors.spec.ts
index e36683922..3dba99d9b 100644
--- a/src/components/ThemePicker/client/__tests__/selectors.spec.ts
+++ b/src/components/ThemePicker/client/__tests__/selectors.spec.ts
@@ -70,7 +70,7 @@ describe('ThemePicker selectors', () => {
await renderThemePickerDom(({ element }) => {
element.querySelector('[data-theme-modal]')?.remove()
- expect(() => getThemePickerModal(element)).toThrowError(ClientScriptError)
+ expect(() => getThemePickerModal(element)).toThrow(ClientScriptError)
})
})
@@ -93,7 +93,7 @@ describe('ThemePicker selectors', () => {
await renderThemePickerDom(() => {
document.querySelector('[data-theme-toggle]')?.remove()
- expect(() => getThemePickerToggleBtn()).toThrowError(ClientScriptError)
+ expect(() => getThemePickerToggleBtn()).toThrow(ClientScriptError)
})
})
@@ -116,7 +116,7 @@ describe('ThemePicker selectors', () => {
await renderThemePickerDom(({ element }) => {
element.querySelector('[data-theme-close]')?.remove()
- expect(() => getThemePickerCloseBtn(element)).toThrowError(ClientScriptError)
+ expect(() => getThemePickerCloseBtn(element)).toThrow(ClientScriptError)
})
})
@@ -163,9 +163,9 @@ describe('ThemePicker selectors', () => {
element.querySelector('[data-theme-embla-prev]')?.remove()
element.querySelector('[data-theme-embla-next]')?.remove()
- expect(() => getThemePickerEmblaViewport(element)).toThrowError(ClientScriptError)
- expect(() => getThemePickerEmblaPrevBtn(element)).toThrowError(ClientScriptError)
- expect(() => getThemePickerEmblaNextBtn(element)).toThrowError(ClientScriptError)
+ expect(() => getThemePickerEmblaViewport(element)).toThrow(ClientScriptError)
+ expect(() => getThemePickerEmblaPrevBtn(element)).toThrow(ClientScriptError)
+ expect(() => getThemePickerEmblaNextBtn(element)).toThrow(ClientScriptError)
})
})
@@ -184,7 +184,7 @@ describe('ThemePicker selectors', () => {
await renderThemePickerDom(({ element }) => {
element.querySelectorAll('[data-theme]').forEach(button => button.remove())
- expect(() => getThemeSelectBtns(element)).toThrowError(ClientScriptError)
+ expect(() => getThemeSelectBtns(element)).toThrow(ClientScriptError)
})
})
})
diff --git a/src/content.config.ts b/src/content.config.ts
index 8fb27b2f3..42d4d843a 100644
--- a/src/content.config.ts
+++ b/src/content.config.ts
@@ -8,8 +8,9 @@
* The 'email' collection is included in the src/content directory, but is not handled by
* Astro's collections systems. It is used by files in src/pages/api.
*/
-import { defineCollection, reference, z, type SchemaContext } from 'astro:content'
+import { defineCollection, reference, type SchemaContext } from 'astro:content'
import { glob, file } from 'astro/loaders'
+import { z } from 'astro/zod'
/**
* Wraps a collection schema with a refinement that enforces breadcrumb title length limits
*/
@@ -52,7 +53,7 @@ const createSocialCollectionSchema = () =>
z.object({
network: z.string(),
name: z.string(),
- url: z.string().url(),
+ url: z.url(),
order: z.number(),
})
)
@@ -206,7 +207,7 @@ const authorsCollection = defineCollection({
z.object({
id: z.string(),
name: z.string(),
- email: z.string().email(),
+ email: z.email(),
avatar: z.string(),
social: createSocialCollectionSchema(),
}),
@@ -219,7 +220,7 @@ const contactDataCollection = defineCollection({
loader: file('./src/content/contact.json'),
schema: z.object({
name: z.string(),
- email: z.string().email(),
+ email: z.email(),
address: z.string(),
city: z.string(),
state: z.string().length(2),
diff --git a/src/content/articles/alert-fatigue-reduction-triage-actionable-alerts/pdf.mdx b/src/content/articles/alert-fatigue-reduction-triage-actionable-alerts/pdf.mdx
index 94fa15203..0ffe3d689 100644
--- a/src/content/articles/alert-fatigue-reduction-triage-actionable-alerts/pdf.mdx
+++ b/src/content/articles/alert-fatigue-reduction-triage-actionable-alerts/pdf.mdx
@@ -385,7 +385,7 @@ Build your inhibition rules to match your architecture. Common patterns:
diff --git a/src/content/articles/api-deprecation-sunset-headers-consumer-migration/index.mdx b/src/content/articles/api-deprecation-sunset-headers-consumer-migration/index.mdx
index 585175e8a..ee82a276b 100644
--- a/src/content/articles/api-deprecation-sunset-headers-consumer-migration/index.mdx
+++ b/src/content/articles/api-deprecation-sunset-headers-consumer-migration/index.mdx
@@ -27,7 +27,7 @@ Your consumers have no inherent motivation to migrate. They have working code. M
The common approach — send an announcement email, add deprecation headers, hope for the best — fails because it treats deprecation as an information problem. If consumers just _knew_ the API was deprecated, surely they would migrate. But they do know. They are ignoring you.
-What actually works is treating deprecation as a _coordination_ problem. You need three things:
+What actually works is treating deprecation as a _coordination_ problem. You need three things:
@@ -145,7 +146,7 @@ The header format is straightforward, but there are common implementation mistak
Metrics show aggregate health, but when something goes wrong, you need to see what happened to _specific requests_. Distributed tracing provides that request-level visibility by tracking individual requests across services.
The gateway is the most critical point for trace context propagation. If the gateway doesn't forward trace headers to backends, your traces stop at the gateway boundary — you see the consumer-to-gateway span, but not the gateway-to-backend spans. The request flow becomes invisible exactly where you need it most.
@@ -330,7 +330,7 @@ Find slow traces for the affected route in your tracing UI (Jaeger, Tempo, AWS X
diff --git a/src/content/articles/api-gateway-metrics-traces-logs-debugging/pdf.mdx b/src/content/articles/api-gateway-metrics-traces-logs-debugging/pdf.mdx
index 53d808dfb..35979889b 100644
--- a/src/content/articles/api-gateway-metrics-traces-logs-debugging/pdf.mdx
+++ b/src/content/articles/api-gateway-metrics-traces-logs-debugging/pdf.mdx
@@ -49,6 +49,8 @@ The fundamental difference is scope: every request passes through the gateway. W
@@ -64,7 +66,7 @@ Each observability pillar answers different questions, and gateway debugging typ
consumer_id only on counters, not histograms',
},
{
text: "Roll up consumer metrics to a separate, lower-resolution store",
@@ -483,7 +486,7 @@ At high traffic volumes, you cannot keep every trace — storage costs and query
@@ -1118,7 +1122,7 @@ Search your tracing system for spans with status code 503 during the error windo
Without measurement, you're guessing at capacity planning, pricing decisions become political negotiations, and cost allocation is fiction. APIs aren't free to operate. Every request costs compute time, network transfer, and storage. Usage patterns vary wildly: one consumer might make 100 requests per day, another 10 million.
The pattern I've seen repeatedly: teams build APIs focused on functionality, ship them, then realize months later they can't answer basic questions. Which team is driving costs? Which endpoints are expensive? Should we charge for this feature? By then, changing the contract is organizational surgery.
@@ -30,6 +30,9 @@ The dimensions you capture become your billable units and cost attribution keys.
+Pick idempotency keys if you're using PostgreSQL or TimescaleDB — they support unique constraints natively and give you exact deduplication. Use time-window deduplication if you're on ClickHouse or Prometheus where unique constraints aren't available. The storage cost of keeping event IDs is negligible compared to the cost of billing disputes.
+
## Enforcing Quotas Before Costs Explode
### Rate Limits vs Quotas
@@ -260,8 +265,6 @@ Send proactive alerts at 50%, 75%, and 90% of quota usage. At 90%, a consumer ha
When the billing period ends and quotas reset to zero, requests immediately succeed again. The Redis key expires and the counter starts fresh. But watch for clock skew in distributed systems — use a grace period (2-5 minutes) where requests near the reset boundary are allowed even if the counter hasn't fully reset.
-Implement this in your application logic: if a request is denied due to quota but the timestamp is within 5 minutes of the period boundary, check if the next period has started. If so, allow the request and count it against the new period. This prevents frustrating "429 errors at midnight" support tickets.
-
+Implement this in your application logic: if a request is denied due to quota but the timestamp is within 5 minutes of the period boundary, check if the next period has started. If so, allow the request and count it against the new period. This prevents frustrating "429 errors at midnight" support tickets.
+
## Getting Started: Your First 30 Days
You don't need to implement everything at once. Here's the path that works:
You can't manage API costs you don't measure. Without usage metering, you're flying blind on capacity planning, pricing decisions, and cost allocation.
+The pattern I've seen repeatedly: teams build APIs focused on functionality, ship them, then realize months later they can't answer basic questions. Which team is driving costs? Which endpoints are expensive? Should we charge for this feature? By then, changing the contract is organizational surgery.
+
## The Metering Foundation
### What to Meter
@@ -94,12 +94,12 @@ For storage-backed APIs (document processing, media transcoding, backup systems)
The first question: should metering be synchronous or asynchronous? Synchronous metering blocks the request until the usage event is recorded. It's accurate but adds latency to every request. Asynchronous metering emits the event and continues processing — it's fast but introduces eventual consistency challenges.
-For high-throughput APIs, async metering is usually the right call. Billing doesn't need millisecond accuracy. If a usage event takes 50ms to persist but your API target is sub-100ms latency, synchronous metering breaks your SLA. Emit events to a message queue and process them out-of-band.
-
Synchronous metering adds latency to every request. For high-throughput APIs, use asynchronous metering with eventual consistency — billing doesn't need millisecond accuracy.
+For high-throughput APIs, async metering is usually the right call. Billing doesn't need millisecond accuracy. If a usage event takes 50ms to persist but your API target is sub-100ms latency, synchronous metering breaks your SLA. Emit events to a message queue and process them out-of-band.
+
```yaml title="async-metering-architecture.yaml"
# Deployed as sidecar or separate service
components:
@@ -172,10 +172,13 @@ Key decisions:
team_analytics) not email addresses or names. Consumer IDs should be stable — if a team renames themselves, the ID stays constant.',
},
{
lead: "Timestamps:",
@@ -183,11 +186,11 @@ Key decisions:
},
{
lead: "Status codes:",
- text: "Separate billable requests (2xx) from errors (4xx, 5xx). You probably don't want to charge for failed requests.",
+ text: 'Separate billable requests (2xx) from errors (4xx, 5xx). You probably don\'t want to charge for failed requests.',
},
{
lead: "Cardinality:",
- text: "Avoid unbounded fields like IP addresses or user agents in dimensions you'll aggregate by. Route patterns (`/users/:id`) are fine, raw paths (`/users/12345`) are not.",
+ text: 'Avoid unbounded fields like IP addresses or user agents in dimensions you\'ll aggregate by. Route patterns (/users/:id) are fine, raw paths (/users/12345) are not.',
},
]}
/>
@@ -491,6 +494,9 @@ Three common approaches:
@@ -693,7 +700,7 @@ There's a spectrum between "no cost visibility" and "full chargebacks." Most org
5
for: 15m
labels:
@@ -1074,7 +1089,7 @@ The order matters: build metering first (you need data), then reporting (visibil
When sync fails, you need to understand what ArgoCD is actually doing underneath the abstraction.
## What ArgoCD Is Actually Doing
@@ -96,14 +96,16 @@ The wave numbers themselves are arbitrary — what matters is the relative order
Sync waves control ordering _within_ the apply phase. But what if you need to run something _before_ sync starts, or _after_ it completes?
-Hooks let you run resources _outside_ the normal apply process — before sync starts (PreSync), after it completes (PostSync), or when it fails (SyncFail). The most common use case is database migrations: run them after new code deploys but before traffic shifts.
+
-Hooks are typically Kubernetes Jobs. The critical thing to understand: ArgoCD waits for hooks to complete before proceeding. If a hook hangs, your entire sync hangs — with no timeout by default.
+Hooks let you run resources _outside_ the normal apply process — before sync starts (PreSync), after it completes (PostSync), or when it fails (SyncFail). The most common use case is database migrations: run them after new code deploys but before traffic shifts.
Always set `activeDeadlineSeconds` on hook Jobs. Without it, ArgoCD will wait forever for a stuck hook.
+Hooks are typically Kubernetes Jobs. The critical thing to understand is that ArgoCD waits for hooks to complete before proceeding. If a hook hangs, the entire sync hangs with it — and by default, ArgoCD won't time it out for you.
+
## The Four-Step Debugging Workflow
When sync fails, resist the urge to poke at random things. A systematic approach gets you to the root cause faster.
@@ -152,8 +154,6 @@ The output tells you sync status (Synced, OutOfSync, Unknown) and health status
The `--show-operation` flag shows which phase the sync is in. "Running PreSync hooks" means a hook is stuck. "Sync error" with a message means apply failed.
-
-
### Step 2: Examine ArgoCD Logs
ArgoCD has several components, each handling different parts:
@@ -215,6 +215,9 @@ Once you've gathered information, match it against these common patterns:
@@ -242,7 +243,7 @@ When a dependency is missing, pods fail to start with characteristic error messa
@@ -812,6 +820,9 @@ Beyond per-resource protection, ArgoCD offers several application-level sync opt
Alert on sync failures early. A 10-minute OutOfSync alert gives you time to investigate before users notice. A 30-minute stuck sync is almost always a real problem requiring intervention.
+The runbook link in the annotations is critical. When an engineer gets paged at 3 AM, they shouldn't have to remember the debugging workflow — they should be able to follow a documented procedure. Link each alert to a runbook that walks through the investigation steps.
+
## Advanced Troubleshooting
When the standard debugging workflow doesn't reveal the problem, you need to dig deeper into ArgoCD's internals. These techniques address edge cases that arise in complex deployments or after upgrades.
@@ -987,6 +998,9 @@ The table below summarizes when to use each tracking method:
This is the trap: availability targeting becomes a badge of engineering honor rather than an economic decision. Let me show you the math that kills the five nines argument.
## The Math That Kills Five Nines
diff --git a/src/content/articles/backpressure-load-shedding-admission-control-overload/index.mdx b/src/content/articles/backpressure-load-shedding-admission-control-overload/index.mdx
index 480f9ffdb..bf77396dd 100644
--- a/src/content/articles/backpressure-load-shedding-admission-control-overload/index.mdx
+++ b/src/content/articles/backpressure-load-shedding-admission-control-overload/index.mdx
@@ -24,7 +24,7 @@ I watched an e-commerce platform collapse during a flash sale. Traffic spiked to
The fix wasn't more capacity. It was teaching the system to say "no."
-Most systems don't fail because they can't handle load. They fail because they try to handle _all_ the load. Without explicit overload handling, a system accepts work it cannot complete, queues grow unbounded, and what starts as a traffic spike becomes a prolonged outage.
+Most systems don't fail because they can't handle load. They fail because they try to handle _all_ the load. Without explicit overload handling, a system accepts work it cannot complete, queues grow unbounded, and what starts as a traffic spike becomes a prolonged outage.
A system without backpressure will accept work until it collapses. The goal isn't handling unlimited load — it's handling your design capacity reliably and degrading gracefully beyond it.
@@ -38,6 +38,7 @@ Overload doesn't just make systems slow — it makes them _worse_. There's a vic
@@ -61,7 +62,7 @@ Consider a system processing 100 RPS with 200ms latency — that's 20 requests i
Here's a counterintuitive truth: throughput can _increase_ during overload while your system becomes effectively useless. The distinction is between throughput (work attempted) and goodput (work successfully completed).
+
Admission control works the same way: decide _upfront_ whether to accept work, rather than accepting everything and failing later. A request rejected at the door costs almost nothing. A request that gets halfway through your system before timing out has consumed database connections, CPU cycles, and memory — resources that could have served requests you _could_ complete.
Here's how that flow looks in practice:
@@ -113,7 +116,7 @@ It's better to reject 20% of requests immediately than to accept 100% and fail 4
I've found four approaches cover most scenarios:
+Of these, latency-based admission gives you the tightest feedback loop. Here's how it works as Express middleware:
+
```typescript title="latency-admission-middleware.ts"
// Express middleware for latency-based admission control
import { Request, Response, NextFunction } from 'express';
@@ -225,8 +230,6 @@ Code: Priority-based routing reserves capacity for critical traffic.
The key insight is that critical traffic can _borrow_ capacity from lower tiers. If the anonymous quota is exhausted but the critical quota has room, anonymous requests are rejected while payments keep flowing.
-
-
## Load Shedding and Graceful Degradation
### Choosing What to Shed
@@ -234,7 +237,7 @@ The key insight is that critical traffic can _borrow_ capacity from lower tiers.
Load shedding is the deliberate dropping of work to preserve system stability. It sounds brutal, but the alternative is worse. When you're drowning, you throw cargo overboard to keep the ship afloat.
**Application equivalent:**
-1. Service advertises capacity (rate limits, queue depth)
-2. Clients limit concurrent requests
-3. As service recovers, capacity opens
-4. If service is slow, clients back off
+
The elegance of TCP's approach is that backpressure is _automatic_. The receiver doesn't have to decide when to apply pressure — the window size naturally reflects its processing capacity. Application-level backpressure often requires more explicit coordination, but the principle is the same: consumers must be able to tell producers "slow down."
@@ -573,7 +613,10 @@ Load shedding is the deliberate dropping of work to preserve system stability. I
The key insight is that _some_ work completing successfully is better than _all_ work failing. If your system can handle 1,000 RPS but 2,000 are arriving, you have a choice: accept all 2,000 and watch goodput collapse to 400 (because everything times out), or shed 1,000 immediately and successfully serve the other 1,000.
@@ -635,18 +682,19 @@ Consider a queue with 100 requests where processing takes 100ms each:
**LIFO shedding (counterintuitive but effective):**
@@ -823,7 +871,11 @@ Graceful degradation requires knowing which features are expendable. Work with p
Backpressure only works if clients understand the signal. HTTP provides specific status codes for communicating overload — use them correctly, and well-behaved clients will back off automatically.
@@ -1538,17 +1591,32 @@ The key is the assertions — don't just measure throughput, explicitly verify t
Load testing validates behavior under high request volume. Chaos engineering validates behavior under _unexpected failures_—the scenarios that trigger backpressure mechanisms in ways traffic alone can't simulate.
concurrent_requests crosses 90% of your concurrency limit, you\'re not in trouble yet — but you\'re one traffic spike away. When queue_depth grows faster than it drains, backpressure is about to kick in. These metrics let you see overload coming before users notice.',
},
{
lead: "Backpressure indicators:",
- text: "tell you when protection mechanisms are active. A spike in `requests_rejected` with reason `rate_limit` means your rate limiter is doing its job. If you see rejections with reason `circuit_open`, a downstream dependency is struggling. The `shed_requests` counter broken down by tier shows which degradation level you're operating at. These metrics answer the question: \"Is the system protecting itself correctly?\"",
+ text: 'Tells you when protection mechanisms are active. A spike in requests_rejected with reason rate_limit means your rate limiter is doing its job. If you see rejections with reason circuit_open, a downstream dependency is struggling. The `shed_requests` counter broken down by tier shows which degradation level you\'re operating at. These metrics answer the question: "Is the system protecting itself correctly?"',
},
{
lead: "Health indicators:",
- text: "are the bottom line. `goodput_ratio` is the most important — it's the percentage of requests that actually succeeded. A 503 is a successful rejection (the system protected itself), but it's not goodput. If goodput drops below your SLO, users are suffering regardless of how well your backpressure mechanisms work. Latency percentiles matter too: p99 staying bounded while p50 degrades slightly is healthy backpressure; p99 exploding means something's queuing that shouldn't be.",
+ text: 'The bottom line. goodput_ratio is the most important — it\'s the percentage of requests that actually succeeded. A 503 is a successful rejection (the system protected itself), but it\'s not goodput. If goodput drops below your SLO, users are suffering regardless of how well your backpressure mechanisms work. Latency percentiles matter too: p99 staying bounded while p50 degrades slightly is healthy backpressure; p99 exploding means something\'s queuing that shouldn\'t be.',
},
]}
/>
+Of those three categories, the rejection metrics are usually the fastest way to identify which protective layer is currently absorbing the pressure.
+
-The `requests_rejected` label `reason` is critical. During an incident, you need to know _which_ mechanism is rejecting — rate limiter, circuit breaker, queue full, or admission control. Different reasons point to different root causes.
+The requests_rejected label reason is critical. During an incident, you need to know _which_ mechanism is rejecting — rate limiter, circuit breaker, queue full, or admission control. Different reasons point to different root causes.
### Dashboard Layout
@@ -1930,7 +2005,7 @@ The `requests_rejected` label `reason` is critical. During an incident, you need
A good overload dashboard tells a story at a glance. When you're paged at 3 AM, you shouldn't have to hunt through 15 panels to understand what's happening. I've found a four-section layout works well:
+That layout works because each section answers a different on-call question, and the order mirrors how you triage an overload event in real time.
+
div]:pr-4",
+ }}
items={[
{
lead: "Load & Capacity:",
- text: "goes at the top because it's your first question: \"How much traffic are we getting, and how close are we to limits?\" Show request rate as a line with capacity threshold as a horizontal marker. Show concurrency and queue depth as gauges with red zones. At a glance, you should see whether you're at 50% capacity or 95%.",
+ text: "Goes at the top because it's your first question: \"How much traffic are we getting, and how close are we to limits?\" Show request rate as a line with capacity threshold as a horizontal marker. Show concurrency and queue depth as gauges with red zones. At a glance, you should see whether you're at 50% capacity or 95%.",
},
{
lead: "Backpressure Activity:",
- text: "answers the second question: \"Is the system protecting itself?\" Show rejection rates by type—429s (rate limiting), 503s (admission control), circuit breaker state (open/closed/half-open). If these counters are at zero, you're not in overload. If they're spiking, the system is actively shedding load. This section turns from green to yellow to red as backpressure intensifies.",
+ text: "Answers the second question: \"Is the system protecting itself?\" Show rejection rates by type—429s (rate limiting), 503s (admission control), circuit breaker state (open/closed/half-open). If these counters are at zero, you're not in overload. If they're spiking, the system is actively shedding load. This section turns from green to yellow to red as backpressure intensifies.",
},
{
lead: "Health Indicators:",
- text: "answer the critical question: \"Are users being served?\" Goodput percentage should be front and center — if it's above 95%, things are okay even if you're shedding some load. P99 latency shows whether successful requests are still fast. Error rate distinguishes between deliberate rejections (503s you sent) and unexpected failures (5xxs from bugs).",
+ text: "Answers the critical question: \"Are users being served?\" Goodput percentage should be front and center — if it's above 95%, things are okay even if you're shedding some load. P99 latency shows whether successful requests are still fast. Error rate distinguishes between deliberate rejections (503s you sent) and unexpected failures (5xxs from bugs).",
},
{
lead: "Degradation State:",
- text: "shows operational mode at a glance. If you've implemented graceful degradation tiers, show the current tier prominently — a big \"ELEVATED\" or \"CRITICAL\" badge tells the on-call engineer immediately that the system is in a degraded state. List which features are disabled so they don't waste time investigating why search isn't working.",
+ text: "Shows operational mode at a glance. If you've implemented graceful degradation tiers, show the current tier prominently — a big \"ELEVATED\" or \"CRITICAL\" badge tells the on-call engineer immediately that the system is in a degraded state. List which features are disabled so they don't waste time investigating why search isn't working.",
},
]}
/>
+When those sections are arranged well, the dashboard stops being a wall of charts and starts reading like a short incident narrative.
+
During an incident, read the dashboard top to bottom: "We're at 120% capacity (Load), rejecting 20% of requests (Backpressure), maintaining 85% goodput (Health), in ELEVATED mode with recommendations disabled (Degradation)." That's a complete situational picture in 10 seconds.
@@ -1991,6 +2073,9 @@ Here's what that looks like in practice:
Instead of asking "who screwed up?" blameless postmortems ask: Why could a single engineer make that change without review? Why was there no canary deployment? Why didn't monitoring catch the error before customers did? That investigation finds five systemic improvements instead of one scapegoat.
## Why Blame Feels Right But Fails
@@ -26,7 +26,10 @@ Blame provides closure. We have a narrative: someone did something wrong, we ide
But blame produces terrible outcomes. When people fear punishment for mistakes, they stop reporting near-misses. They hedge their language in postmortems. They cover their tracks. The information you need to prevent future incidents disappears into self-protective silence.
@@ -138,47 +144,63 @@ The phrase "root cause" implies there's one cause at the bottom of the causal ch
The Five Whys technique — keep asking "why" until you reach an actionable cause — is popular but easily misused. Here's what going wrong looks like:
-```text title="five-whys-antipattern.txt"
-Q: Why did the system go down?
-A: Because a config change broke it.
-
-Q: Why did the config change break it?
-A: Because the engineer made a mistake.
-
-Q: Why did the engineer make a mistake?
-A: Because they were careless.
+
-[Investigation stops at blame — nothing actionable learned]
-```
-Code: Five Whys antipattern that terminates at human blame.
+Five Whys antipattern that stops at blame — nothing actionable learned.
And here's the same incident investigated properly:
-```text title="five-whys-systemic.txt"
-Q: Why did the system go down?
-A: Because a config change disabled authentication.
-
-Q: Why did the config change disable authentication?
-A: Because the config schema changed and old values became invalid.
-
-Q: Why did old values become invalid?
-A: Because the migration script didn't update existing configs.
-
-Q: Why didn't the migration update existing configs?
-A: Because no one knew configs existed in that format.
-
-Q: Why didn't anyone know?
-A: Because documentation was outdated and there was no config inventory.
+
-[Five actionable systemic issues identified]
-```
-Code: Five Whys done well, leading to systemic improvements.
+Five Whys done well, leading to systemic improvements from actionable issues.
The difference is where you choose to stop. If you reach a human attribute — careless, rushed, didn't know — that's a signal you've taken a wrong turn. Human attributes aren't fixable. But every human attribute has a system context: Why was carelessness possible? What created the rush? Why wasn't the knowledge available?
@@ -193,7 +215,7 @@ The analysis is only as valuable as the actions it produces. I've seen beautiful
Good action items share specific characteristics:
+Those characteristics sound straightforward in the abstract, but the difference shows up quickly when you compare action items side by side. One set points to concrete engineering changes you can implement and verify; the other just restates frustration in softer language.
+
An incident without completed action items is an incident that will recur. Track actions to completion, verify they work, and close the loop in a follow-up meeting.
+Here's a useful test: if someone else picked up the action item, would they know exactly what to build or change? If the answer is no, refine it until they would.
+
## The Path Forward
Blameless postmortems aren't soft — they're more rigorous than blame culture. They demand that we find _all_ the contributing factors, not just the most obvious one. They demand _real_ fixes, not just "be more careful." They demand measurement to verify fixes actually work.
@@ -276,20 +303,20 @@ The core principles:
variant="check-icons-list"
items={[
{
- lead: "Human error is where investigation begins, not where it ends:",
- text: "The interesting question is always: what made that action likely, possible, and undetected?",
+ lead: "Human error is where investigation begins, not where it ends",
+ text: "the interesting question is always: what made that action likely, possible, and undetected?",
},
{
- lead: "Blame produces hiding; systems thinking produces learning:",
- text: "When people fear punishment, they stop reporting. When they feel safe, they share near-misses that prevent future incidents.",
+ lead: "Blame produces hiding; systems thinking produces learning",
+ text: "when people fear punishment, they stop reporting. When they feel safe, they share near-misses that prevent future incidents.",
},
{
- lead: "Incidents have contributing factors, not root causes:",
- text: "Complex failures arise from multiple interacting conditions. Identify them all before deciding which to fix.",
+ lead: "Incidents have contributing factors, not root causes",
+ text: "complex failures arise from multiple interacting conditions. Identify them all before deciding which to fix.",
},
{
- lead: "Effective remediation requires specific, systemic action items tracked to completion:",
- text: "Vague actions don't get done. Person-focused actions don't prevent recurrence.",
+ lead: "Effective remediation requires specific, systemic action items tracked to completion",
+ text: "vague actions don't get done. Person-focused actions don't prevent recurrence.",
},
]}
/>
diff --git a/src/content/articles/blameless-postmortem-incident-analysis-systemic-causes/pdf.mdx b/src/content/articles/blameless-postmortem-incident-analysis-systemic-causes/pdf.mdx
index 084fbc150..c06501065 100644
--- a/src/content/articles/blameless-postmortem-incident-analysis-systemic-causes/pdf.mdx
+++ b/src/content/articles/blameless-postmortem-incident-analysis-systemic-causes/pdf.mdx
@@ -29,12 +29,12 @@ This feels satisfying — we found the problem and addressed it. But three month
The blameless investigation asks different questions: Why could a single engineer make that change without review? Why was there no canary deployment? Why didn't monitoring catch the error rate spike before customers did? Why was the config format so easy to break? That investigation finds five systemic improvements instead of one scapegoat.
-This isn't about being soft on mistakes. It's about being rigorous enough to find causes that actually prevent recurrence. If you're responsible for incident response, reliability engineering, or leading engineering teams, this guide will help you build postmortem practices that actually improve your systems.
-
"Human error" is not a root cause — it's the starting point for investigation. Every incident involves human actions, but the interesting question is: what about the system made that action likely, possible, and undetected?
+This isn't about being soft on mistakes. It's about being rigorous enough to find causes that actually prevent recurrence. If you're responsible for incident response, reliability engineering, or leading engineering teams, this guide will help you build postmortem practices that actually improve your systems.
+
## The Case Against Blame
### Why Blame Feels Right But Fails
@@ -44,7 +44,10 @@ Blame feels right because it provides closure. We have a narrative: someone did
But blame produces terrible outcomes. When people fear punishment for mistakes, they stop reporting near-misses. They hedge their language in postmortems. They cover their tracks. The information you need to prevent future incidents disappears into self-protective silence.
@@ -124,7 +130,10 @@ If the answer to the last question is "hundreds of times," then the action itsel
"Blameless" is frequently misunderstood. It doesn't mean no one is accountable. It doesn't mean we ignore mistakes or lower our standards. It means we hold the _right things_ accountable — and in complex systems, that's almost never an individual human making a one-off error.
+These categories aren't always clear-cut in the moment. The table below summarizes each behavior type with a concrete example and the appropriate organizational response, so facilitators can reference it during postmortem discussions.
+
@@ -391,6 +410,7 @@ The words we use shape the investigation. Blame-oriented language ("they should
-[Investigation stops at blame — nothing actionable learned]
-```
-Code: Five Whys antipattern that terminates at human blame.
+Five Whys antipattern that stops at blame — nothing actionable learned.
And here's the same incident investigated properly:
-```text title="five-whys-systemic.txt"
-Five Whys - The Systems Path:
-
-Q: Why did the system go down?
-A: Because a config change disabled authentication.
-
-Q: Why did the config change disable authentication?
-A: Because the config schema changed and old values became invalid.
-
-Q: Why did old values become invalid?
-A: Because the migration script did not update existing configs.
-
-Q: Why did the migration not update existing configs?
-A: Because no one knew configs existed in that format.
-
-Q: Why did no one know?
-A: Because the documentation was outdated and there was no config inventory.
-
-[Five actionable systemic issues identified]
-```
-Code: Five Whys done well, leading to systemic improvements.
+
The difference is where you choose to stop. If you reach a human attribute — careless, rushed, didn't know — that's a signal you've taken a wrong turn. Human attributes aren't fixable. But every human attribute has a system context: Why was carelessness possible? What created the rush? Why wasn't the knowledge available?
@@ -499,7 +528,7 @@ There are real limitations to Five Whys even when done well:
-- __Knowledge limits__: You can only ask "why" about things you know happened. Unknown factors don't get investigated.
-
For simple incidents with clear causation, Five Whys is often sufficient. For complex incidents with multiple interacting factors, you'll need more sophisticated analysis frameworks.
### STAMP/CAST Analysis for Complex Incidents
@@ -537,7 +568,7 @@ STAMP treats safety as a control problem. Systems fail not because of component
The insight is that the engineer making a config change is just the _lowest level_ of control. If you only investigate at that level, you're ignoring all the levels above that enabled, permitted, or encouraged the action. CAST asks questions at every level:
+In practice, the gap between good and bad action items is immediately obvious when you put them next to each other. Notice how the effective examples describe a specific engineering change, while the ineffective ones could mean almost anything — or nothing at all.
+
"Implement 1% canary with automatic rollback on error spike."
"Add config change review requirement to deploy pipeline."',
},
{
lead: "Bad examples:",
- text: "\"Be more careful with config changes.\" \"Engineer X needs training.\" \"Review all configs.\" \"Improve monitoring.\"",
+ text: '"Be more careful with config changes."
"Engineer X needs training."
"Review all configs."
"Improve monitoring."',
},
]}
/>
@@ -680,30 +713,30 @@ The "bad" examples deserve some attention because they're so common. "Be more ca
Here's a useful test: if someone else picked up the action item, would they know exactly what to build or change? If the answer is no, the action item needs refinement.
@@ -913,7 +946,7 @@ Store postmortems in a searchable, centralized location — a wiki, Confluence,
A single postmortem document serves readers with very different needs. The executive wants to know business impact in thirty seconds. The on-call engineer wants to know what to do if this recurs at 3 AM. Future investigators want every detail you can provide. Somehow, the document needs to work for all of them.
@@ -1015,25 +1055,28 @@ culture_metrics:
Code: Balanced metrics across process, outcomes, and culture.
@@ -1103,32 +1146,31 @@ The harder path — blameless investigation — requires discipline. It means as
Let's recap the core principles:
-
Blameless culture isn't soft. It's more rigorous than blame culture, not less. It demands that we find _all_ the contributing factors, not just the most obvious one. It demands that we implement _real_ fixes, not just "be more careful." It demands that we measure whether our fixes actually work. That's harder than pointing at a person and saying "don't do that again."
-The organizations that learn fastest are the ones where people feel safe enough to say "I made a mistake, and here's what we should change so it doesn't happen again." Building that safety — and that rigor — is the work.
-
The goal of incident analysis is not to find who to blame. It's to find what to change so that the same class of incident becomes less likely. A blameless postmortem that produces no systemic improvements has failed — not because it didn't assign blame, but because it didn't learn.
+
+The organizations that learn fastest are the ones where people feel safe enough to say "I made a mistake, and here's what we should change so it doesn't happen again." Building that safety — and that rigor — is the work.
diff --git a/src/content/articles/blue-green-canary-deployment-strategy-comparison/diagrams/canary-deployment-progression-with-traffic-percentage-increase.jpg b/src/content/articles/blue-green-canary-deployment-strategy-comparison/diagrams/canary-deployment-progression-with-traffic-percentage-increase.jpg
index 8a356c9fa..7c393364b 100644
Binary files a/src/content/articles/blue-green-canary-deployment-strategy-comparison/diagrams/canary-deployment-progression-with-traffic-percentage-increase.jpg and b/src/content/articles/blue-green-canary-deployment-strategy-comparison/diagrams/canary-deployment-progression-with-traffic-percentage-increase.jpg differ
diff --git a/src/content/articles/blue-green-canary-deployment-strategy-comparison/diagrams/key-challenges-with-blue-green-deployment-strategy.jpg b/src/content/articles/blue-green-canary-deployment-strategy-comparison/diagrams/key-challenges-with-blue-green-deployment-strategy.jpg
index 6628f53e6..9e8ed918e 100644
Binary files a/src/content/articles/blue-green-canary-deployment-strategy-comparison/diagrams/key-challenges-with-blue-green-deployment-strategy.jpg and b/src/content/articles/blue-green-canary-deployment-strategy-comparison/diagrams/key-challenges-with-blue-green-deployment-strategy.jpg differ
diff --git a/src/content/articles/blue-green-canary-deployment-strategy-comparison/index.mdx b/src/content/articles/blue-green-canary-deployment-strategy-comparison/index.mdx
index 5c35e9f0c..c05806ba5 100644
--- a/src/content/articles/blue-green-canary-deployment-strategy-comparison/index.mdx
+++ b/src/content/articles/blue-green-canary-deployment-strategy-comparison/index.mdx
@@ -21,14 +21,28 @@ Here's the uncomfortable truth most deployment strategy comparisons skip: the "b
Before we dive into the database problem, let's establish baseline understanding of what these strategies actually do.
-__Blue/green deployment__ maintains two identical production environments. Blue runs your current version. When you're ready to release, you deploy to green, test it thoroughly, then switch all traffic at once. If something breaks, you switch back to blue.
-
-__Canary deployment__ takes the opposite approach. Instead of switching everyone simultaneously, you route a small percentage of traffic — say, 5%—to the new version. You watch metrics, gradually increase the percentage, and only complete the rollout once you're confident the new version is healthy.
+
The fundamental difference comes down to exposure:
-
-
-
This pattern works with both strategies, but it's __mandatory__ for canary deployments. Blue/green can sometimes shortcut this with careful timing and instant cutover, but you're accepting more risk.
```sql
@@ -121,12 +135,14 @@ The teams that struggle with deployment strategies are usually the ones trying t
Now that we've established database compatibility as the primary constraint, the decision framework becomes clearer. Here's how to choose.
-### Choose Blue/Green When
+### Choose Blue / Green When
Your deployments frequently include database migrations that can't easily follow expand-contract patterns. Legacy systems with tightly coupled schemas often fall into this category.
You need instant, complete rollback. Blue/green's traffic switch is as close to "undo" as deployments get. If your downtime tolerance is measured in seconds rather than minutes, this matters.
+
+
Your team is smaller or less experienced with progressive delivery. Blue/green is conceptually simpler: deploy, test, switch. There's less tooling to maintain and fewer operational scenarios to train for.
You can afford the infrastructure cost. Running two complete environments doubles your compute costs during deployments. For many organizations, this is acceptable for the operational simplicity it provides.
@@ -151,6 +167,10 @@ Many mature organizations don't choose one strategy — they use both. Schema mi
The key insight is that the database constraint drives the decision __per deployment__, not as a blanket policy. A team might deploy three canary releases in a row, then switch to blue/green for a migration, then back to canary. The tooling supports both; the deployment contents determine which to use.
+## Conclusion
+
+The deployment strategy debate often focuses on the wrong things — rollback speed, blast radius, tooling sophistication. These matter, but they're secondary to the fundamental question: what are you actually deploying?
+
-## Conclusion
-
-The deployment strategy debate often focuses on the wrong things — rollback speed, blast radius, tooling sophistication. These matter, but they're secondary to the fundamental question: what are you actually deploying?
-
For database schema changes, blue/green's instant cutover is often the only safe option. For application logic changes, canary's gradual rollout provides better production validation with limited risk. Most real-world systems need both approaches, selected based on what each specific deployment contains.
The best deployment strategy isn't the most technically impressive one. It's the one your team can operate reliably, that matches your database change patterns, and that you'll actually use consistently. Start with the simpler option that works for your constraints, and add sophistication only when you have specific problems that require it.
diff --git a/src/content/articles/blue-green-canary-deployment-strategy-comparison/pdf.mdx b/src/content/articles/blue-green-canary-deployment-strategy-comparison/pdf.mdx
index 0f8773aa7..5255daca4 100644
--- a/src/content/articles/blue-green-canary-deployment-strategy-comparison/pdf.mdx
+++ b/src/content/articles/blue-green-canary-deployment-strategy-comparison/pdf.mdx
@@ -1,8 +1,8 @@
---
-title: "Blue/Green vs Canary: Choosing Deployment Strategies"
+title: "Blue/green vs Canary: Choosing Deployment Strategies"
description: "Tradeoffs between deployment strategies for stateless and stateful workloads, with and without service mesh."
cover: "./cover.jpg"
-coverAlt: "Deployment strategy spectrum showing progression from simple to complex: Recreate, Rolling, Blue/Green, Canary, and Progressive deployment patterns"
+coverAlt: "Deployment strategy spectrum showing progression from simple to complex: Recreate, Rolling, Blue/green, Canary, and Progressive deployment patterns"
author: "kevin-brown"
publishDate: 2023-08-20
tags: ["build-and-deploy", "kubernetes", "aws", "python", "prometheus", "typescript"]
@@ -60,7 +60,7 @@ Before diving into blue/green and canary specifically, it helps to see where the
td: ["No*", "Minutes", "1x-1.5x", "Low"],
},
{
- th: "Blue/Green",
+ th: "Blue/green",
td: ["No", "Seconds", "2x", "Medium"],
},
{
@@ -76,29 +76,30 @@ Before diving into blue/green and canary specifically, it helps to see where the
}}
/>
+The numbers tell part of the story, but the real differences are in how each strategy behaves when things go wrong. Here's what those tradeoffs actually look like in practice:
+
-
### When Simple Wins
I've seen teams implement canary deployments for services that deploy once a month. The infrastructure sat idle 99% of the time, and when they did deploy, no one remembered how the analysis worked. A rolling update with good smoke tests would have been simpler and just as effective.
@@ -113,9 +114,9 @@ The questions that actually matter:
That last question is the one teams most often ignore. If your schema migration breaks the old version, it doesn't matter whether you're doing blue/green, canary, or rolling — you've got a problem. We'll cover this in detail later.
-## Blue/Green Deployments
+## Blue/green Deployments
-### How Blue/Green Works
+### How Blue/green Works
Blue/green deployment maintains two identical production environments. At any time, one is "live" (receiving traffic) and one is "idle" (ready for the next deployment). When you deploy, you update the idle environment, validate it, then switch traffic. The old live environment becomes the new idle — ready for instant rollback if needed.
@@ -196,30 +197,30 @@ Code: Kubernetes blue/green deployment using label selectors.
The cutover is a single `kubectl patch` command. No pods restart, no gradual rollout — traffic shifts immediately. And because the old version keeps running, rollback is equally instant — just point traffic back.
-### Blue/Green Challenges
+### Blue/green Challenges
Blue/green isn't free. The tradeoffs are real, and ignoring them leads to surprises.
@@ -250,7 +252,7 @@ __Warmup time__ catches teams off guard. The green environment might be "up" but
You can mitigate the resource cost:
",
+ lead: "Must be version-aware.",
+ text: "Your metrics need to distinguish canary from stable so you can compare error rates and latencies. \"Overall error rate is 0.5%\" doesn't help — you need \"canary error rate is 2%, stable is 0.3%.\" This means version labels on all metrics, dashboards that compare versions side by side, and alerting that understands the traffic split.",
},
{
- lead: "Stateful requests:",
- text: "create consistency problems. If a user's session spans multiple requests, they might hit v1.0 for the first request and v1.1 for the second. For stateless APIs this is fine, but for stateful workflows it can cause bugs that only appear in production during canary.",
+ title: "Stateful requests:",
+ lead: "Creates consistency problems.",
+ text: "If a user's session spans multiple requests, they might hit v1.0 for the first request and v1.1 for the second. For stateless APIs this is fine, but for stateful workflows it can cause bugs that only appear in production during canary.",
},
{
- lead: "Database schema:",
- text: "affects canary exactly as it affects blue/green — both versions must work with the same schema. Canary doesn't solve this problem; it just means both versions run simultaneously for longer.",
+ title: "Database schema:",
+ lead: "Affects canary exactly as it affects blue/green.",
+ text: "Both versions must work with the same schema. Canary doesn't solve this problem; it just means both versions run simultaneously for longer.",
},
]}
/>
@@ -536,10 +543,14 @@ The key insight is using both absolute thresholds (error rate > 5% is always bad
With both strategies understood, the choice comes down to your constraints and priorities. This matrix summarizes the trade-offs:
+Here's how those advantages compare when you put canary routing, feature flags, and the combined approach side by side:
+
+Those qualitative differences translate into concrete numbers that matter during an incident, when seconds count and mixed-version windows create real risk:
+
@@ -883,18 +906,24 @@ Consider a scenario: v1.1 adds a `preferences_json` column and starts writing us
The solutions are all variations of "design for this upfront":
The goal isn't the most sophisticated deployment strategy — it's reliable deployments with fast recovery. A well-operated blue/green deployment is better than a poorly-operated canary. Choose the strategy you can do well.
+
+Start simple. If you're currently doing manual deployments with downtime, rolling updates are a meaningful improvement. If rolling updates work well but you want faster rollback, blue/green is the next step. If blue/green works well but you've been burned by staging-production differences, then consider canary.
+
+The best deployment strategy is the one your team can operate reliably at 3 AM when something goes wrong.
diff --git a/src/content/articles/cdn-edge-caching-cache-keys-vary-headers/index.mdx b/src/content/articles/cdn-edge-caching-cache-keys-vary-headers/index.mdx
index 2fa127889..2dfae9281 100644
--- a/src/content/articles/cdn-edge-caching-cache-keys-vary-headers/index.mdx
+++ b/src/content/articles/cdn-edge-caching-cache-keys-vary-headers/index.mdx
@@ -18,7 +18,7 @@ The cache hit ratio looked fantastic. 94% of requests served from edge. Response
This is the fundamental tension in edge caching. Aggressive caching dramatically improves performance and reduces origin load, but incorrect configuration serves wrong content to users — sometimes catastrophically. Edge caching is a __data integrity__ problem first, performance problem second.
-The good news: two concepts cause the vast majority of CDN cache bugs, and once you understand them, you can cache aggressively without fear. Those concepts are cache keys and Vary headers.
+The good news: two concepts cause the vast majority of CDN cache bugs, and once you understand them, you can cache aggressively without fear. Those concepts are cache keys and Vary headers.
## Cache Keys Determine Correctness
@@ -26,7 +26,7 @@ A cache key is the identifier the CDN uses to store and retrieve cached response
By default, most CDNs use a simplified version of the URL:
-```text
+
Default cache key:
SCHEME + HOST + PATH + QUERY_STRING
@@ -35,7 +35,7 @@ Example request:
Cache key:
"https://example.com/api/products?category=shoes"
-```
+
This seems straightforward, but the details matter enormously. Two requests that __should__ return identical content but generate different cache keys create duplicate cache entries — wasting storage and reducing hit ratios. Two requests that __should__ return different content but generate the same cache key serve wrong content to users — exactly the bug we opened with.
@@ -45,15 +45,15 @@ The rule is simple: every attribute that affects your response must be in the ca
Query parameters are the most common source of cache key problems. Consider these two URLs:
-```text
+
Problem: Query parameter order
These are the same request but different cache keys:
- /products?color=red&size=large
- /products?size=large&color=red
+ /products?color=red&size=large
+ /products?size=large&color=red
Result: Two cache entries for identical content
-```
+
Different parameter order, different cache keys, same content — you're now storing two copies and reducing your hit ratio. Marketing teams compound this by adding tracking parameters to URLs. Every `utm_source`, `fbclid`, and `gclid` creates a unique cache key for content that's identical regardless of how the user arrived.
@@ -89,6 +89,8 @@ Query parameter pollution is one of the most common causes of poor cache hit rat
The `Vary` header tells caches "this response differs based on these request headers." It's the origin's way of saying "I returned different content to different clients based on header X, so you need to store separate cached versions."
+
+
When a CDN sees `Vary: Accept-Language`, it doesn't just store one cached response per URL — it stores one per URL __per unique Accept-Language value__. The cache key effectively becomes URL + the values of all headers listed in Vary.
```http title="vary-example.http"
@@ -105,7 +107,8 @@ With two headers in Vary, you get a combinatorial explosion of cache variants. E
The guideline: only vary on headers with a small, known set of values.
-
### The Cookie Vary Trap
The most common Vary mistake is `Vary: Cookie`. It seems logical — if your response depends on cookies, tell the cache to vary on them. But cookies include session IDs, authentication tokens, and tracking identifiers that are unique per user. Even when the actual content-affecting cookie (`preferences=dark`) is the same, the unique session IDs create separate cache entries.
@@ -188,14 +189,31 @@ Understanding cache keys and Vary headers lets you avoid the two most dangerous
This is the bug from our opening story — serving one user's content to another. It happens when:
-- Your origin returns `Cache-Control: public` for personalized responses
-- You vary on session cookie but session IDs still contaminate the cache key
-- You cache without checking for authentication headers
+Cache-Control: public for personalized responses',
+ },
+ {
+ color: "bg-danger-offset",
+ text: "You vary on session cookie but session IDs still contaminate the cache key",
+ },
+ {
+ color: "bg-danger-offset",
+ text: "You cache without checking for authentication headers",
+ },
+ ]}
+/>
The patterns that keep you safe:
-## Getting It Right
-
-Both of these bugs — and most CDN issues you'll encounter — stem from the same root cause: a mismatch between what's in the cache key and what actually affects the response.
-
A properly-configured cache with 70% hit ratio beats a misconfigured cache with 95% hit ratio. The latter is serving wrong content to 95% of users — or worse, leaking private data between users.
Start with serving correct content: audit your cache keys, normalize your Vary headers, and verify that personalized content can never be cached. Once you've established that foundation, you can optimize for performance with confidence.
diff --git a/src/content/articles/cdn-edge-caching-cache-keys-vary-headers/pdf.mdx b/src/content/articles/cdn-edge-caching-cache-keys-vary-headers/pdf.mdx
index f2050e8af..d56ce3dc1 100644
--- a/src/content/articles/cdn-edge-caching-cache-keys-vary-headers/pdf.mdx
+++ b/src/content/articles/cdn-edge-caching-cache-keys-vary-headers/pdf.mdx
@@ -28,12 +28,12 @@ The cache hit ratio looked fantastic. 94% of requests served from edge. Response
This is the fundamental tension in edge caching. Aggressive caching dramatically improves performance and reduces origin load, but incorrect configuration serves wrong content to users — sometimes catastrophically. Edge caching is a __correctness__ problem first, performance problem second.
-The techniques in this article address that tension: how to design cache keys that prevent content cross-contamination, how to use Vary headers without destroying hit ratios, and how to invalidate content without leaving stale data at the edge. Get the correctness right, and you can cache aggressively. Get it wrong, and your CDN becomes a liability.
-
A cache that serves incorrect content is worse than no cache at all. Before optimizing cache hit ratios, ensure your cache configuration cannot serve one user's content to another.
+The techniques in this article address that tension: how to design cache keys that prevent content cross-contamination, how to use Vary headers without destroying hit ratios, and how to invalidate content without leaving stale data at the edge. Get the correctness right, and you can cache aggressively. Get it wrong, and your CDN becomes a liability.
+
## How Edge Caching Works
### The Request Flow
@@ -53,7 +53,7 @@ The performance difference is dramatic. A cache hit typically returns in 10-50ms
Not every response can be cached, and CDNs apply conservative defaults. Understanding what triggers caching — and what prevents it — is essential for both maximizing hit ratios and avoiding correctness bugs.
`s-maxage` controls shared cache (CDN) TTL separately from `max-age` which controls browser cache. This lets you cache aggressively at the edge (24 hours) while keeping browser caches short (1 hour) for faster updates when you purge.
@@ -127,16 +129,16 @@ A cache key is the identifier the CDN uses to store and retrieve cached response
By default, most CDNs use a simplified version of the URL as the cache key:
-```text
-Default cache key (simplified):
+
+Default cache key:
SCHEME + HOST + PATH + QUERY_STRING
-Example:
+Example request:
https://example.com/api/products?category=shoes
Cache key:
"https://example.com/api/products?category=shoes"
-```
+
This seems straightforward, but the details matter enormously. Two requests that should return identical content but generate different cache keys create duplicate cache entries — wasting storage and reducing hit ratios. Two requests that should return different content but generate the same cache key serve wrong content to users — the correctness bug we're trying to avoid.
@@ -177,15 +179,16 @@ The defaults are conservative: most request attributes are excluded from the cac
Query parameters are the most common source of cache key problems. Consider these two URLs:
-```text
+
Problem: Query parameter order
These are the same request but different cache keys:
- /products?color=red&size=large
- /products?size=large&color=red
-Result: Two cache entries for identical content (cache pollution)
-```
+ /products?color=red&size=large
+ /products?size=large&color=red
+
+Result: Two cache entries for identical content
+
Different parameter order, different cache keys, same content — you're now storing two copies and reducing your hit ratio. Marketing teams compound this by adding tracking parameters to URLs. Every `utm_source`, `fbclid`, and `gclid` creates a unique cache key for content that's identical regardless of how the user arrived.
@@ -244,10 +247,11 @@ Vary: Accept-Encoding, Accept-Language
With two headers in Vary, you get a combinatorial explosion of cache variants:
-```text
+
Vary: Accept-Encoding, Accept-Language
Creates cache variants:
+
Cache key + Accept-Encoding: gzip + Accept-Language: en-US
Cache key + Accept-Encoding: gzip + Accept-Language: es-ES
Cache key + Accept-Encoding: br + Accept-Language: en-US
@@ -256,7 +260,7 @@ Creates cache variants:
...
Each unique combination = separate cache entry
-```
+
This is powerful — it lets you cache content that legitimately varies by request attributes. But it's also dangerous, because Vary headers with high-cardinality values can destroy your cache effectiveness entirely.
@@ -265,7 +269,7 @@ This is powerful — it lets you cache content that legitimately varies by reque
The rule is simple: only vary on headers with a small, known set of values. The more unique values a header can have, the more cache entries you create and the lower your hit ratio drops.
+These patterns are easy to identify in a table, but catching them in a running system requires automated enforcement. The following middleware intercepts outgoing responses and checks for the most dangerous combination — personalized content paired with a public cache header — overriding it before the response reaches the CDN.
+
```typescript [g2:Express Middleware]
// Middleware to prevent accidental caching of personalized content
@@ -886,7 +892,15 @@ This vulnerability is common because web frameworks often trust proxy headers by
Cache Poisoning Attack:
-1. Attacker sends request with malicious header:
+
```http
GET /page HTTP/1.1
@@ -894,21 +908,52 @@ Host: example.com
X-Forwarded-Host: evil.com
```
-2. Vulnerable origin reflects header in response:
+
```html
```
-3. Response is cached (`X-Forwarded-Host` not in cache key)
-
-4. Legitimate users get poisoned cached response
+
Prevention:
-- Include attack vectors in cache key, OR
-- Normalize/validate headers at edge before forwarding
-- Do not reflect untrusted headers in responses
+
```yaml [g3:Pseudocode]
# Pseudocode CDN cache poisoning prevention policy
@@ -1003,7 +1048,7 @@ E-commerce sites often return different content based on the user's location —
This bug is insidious because it often goes unnoticed during development. Your test users are all in the same country, so everyone sees correct content. The first German user to hit a cached US response discovers the problem — usually at checkout when the currency doesn't match.
GET /products', 'GET /products'],
},
{
- th: "2. Cache status",
- td: ["MISS", "HIT (User A's response)"],
+ th: "Cache status",
+ td: ['MISS', 'HIT (User A\'s response)'],
},
{
- th: "3. Response",
- td: ["Prices in EUR ✓", "Prices in EUR ✗"],
+ th: "Response",
+ td: ['Prices in EUR ✓', 'Prices in EUR ✗'],
},
{
- th: "4. Outcome",
- td: ["Correct experience", "Checkout fails — wrong currency"],
+ th: "Outcome",
+ td: ['Correct experience', 'Checkout fails — wrong currency'],
},
],
},
@@ -1037,7 +1082,7 @@ No geographic variation in cache key. Both users hit the same cache entry despit
CF-IPCountry (or equivalent) to cache key',
"Automatic, per-country caching",
"Many cache variants, cold caches per region",
],
@@ -1056,7 +1101,7 @@ No geographic variation in cache key. Both users hit the same cache entry despit
{
th: "Separate endpoints",
td: [
- "Use explicit country param: `/api/products?country=DE`",
+ 'Use explicit country param: /api/products?country=DE',
"Explicit, highly cacheable",
"Client must know country",
],
@@ -1118,7 +1163,7 @@ Cache hit ratio is the percentage of requests served from cache versus total req
The strategies below are ordered by impact-to-effort ratio. Query string normalization and cache key simplification typically yield the largest improvements with the least work. Content negotiation and TTL tuning require more analysis but can push hit ratios from good to excellent.
utm_*, fbclid, gclid); remove empty parameters',
],
},
{
@@ -1147,7 +1192,7 @@ The strategies below are ordered by impact-to-effort ratio. Query string normali
td: [
"Medium",
"Medium",
- "Reduce language variants; limit Accept-Encoding values; avoid User-Agent variations",
+ 'Reduce language variants; limit Accept-Encoding values; avoid User-Agent variations',
],
},
{
@@ -1155,7 +1200,7 @@ The strategies below are ordered by impact-to-effort ratio. Query string normali
td: [
"High",
"Low",
- "Use immutable for versioned assets; extend TTL with stale-while-revalidate; implement proper invalidation",
+ 'Use immutable for versioned assets; extend TTL with stale-while-revalidate; implement proper invalidation',
],
},
],
@@ -1168,7 +1213,8 @@ The strategies below are ordered by impact-to-effort ratio. Query string normali
You can't optimize what you don't measure. These metrics tell you whether your cache is working correctly and where to focus optimization efforts. Most CDNs expose these through dashboards and APIs — set up monitoring before you need to debug a production issue.
-__Interpreting these metrics in context:__
+Interpreting these metrics in context:
+Translating these observations into automated monitoring requires dashboards that surface anomalies before they become incidents. The following Datadog configuration tracks the metrics above and alerts on the thresholds that typically indicate configuration problems rather than traffic changes.
+
```json title="cache-monitoring.json"
{
"_comment": "Datadog config example",
@@ -1273,6 +1321,8 @@ __Interpreting these metrics in context:__
```
Code: Cache monitoring dashboard configuration.
+When your dashboard flags a dip, resist the urge to increase TTLs blindly — the hit ratio itself is the diagnostic starting point.
+
A cache hit ratio below 70% often indicates a configuration problem, not a traffic problem. Before adding more edge capacity, audit your cache keys and Vary headers.
@@ -1329,14 +1379,6 @@ This checklist consolidates the key configuration points covered throughout the
```
Code: Comprehensive CDN configuration checklist.
-## Further Reading
-
-- [RFC 9111: HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html) — The authoritative specification for HTTP caching semantics, including Cache-Control directives and Vary header behavior.
-- [AWS CloudFront Developer Guide: Caching](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cache-key-understand-cache-policy.html) — CloudFront-specific cache key policies and configuration options.
-- [Cloudflare Cache Documentation](https://developers.cloudflare.com/cache/) — Cloudflare's caching features, including cache tags (Surrogate-Key), purge APIs, and edge compute with Workers.
-- [Fastly VCL Reference](https://developer.fastly.com/reference/vcl/) — Fastly's Varnish Configuration Language for fine-grained cache control.
-- [Web Caching Explained by Ryan Prior](https://web-caching.readthedocs.io/) — A comprehensive guide to HTTP caching concepts and best practices.
-
## Conclusion
Edge caching is a correctness problem disguised as a performance optimization. The techniques in this article all serve one goal: ensuring the right content reaches the right user while maximizing cache efficiency.
@@ -1345,6 +1387,9 @@ The key principles to remember:
Edge caching is one of the highest-leverage performance optimizations available, but only when configured correctly. Invest time in cache key design, Vary header normalization, and monitoring — the performance gains are dramatic and the correctness risks are real.
+
+## Further Reading
+
+- [RFC 9111: HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html) — The authoritative specification for HTTP caching semantics, including Cache-Control directives and Vary header behavior.
+- [AWS CloudFront Developer Guide: Caching](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cache-key-understand-cache-policy.html) — CloudFront-specific cache key policies and configuration options.
+- [Cloudflare Cache Documentation](https://developers.cloudflare.com/cache/) — Cloudflare's caching features, including cache tags (Surrogate-Key), purge APIs, and edge compute with Workers.
+- [Fastly VCL Reference](https://developer.fastly.com/reference/vcl/) — Fastly's Varnish Configuration Language for fine-grained cache control.
+- [Web Caching Explained by Ryan Prior](https://web-caching.readthedocs.io/) — A comprehensive guide to HTTP caching concepts and best practices.
diff --git a/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/diagrams/the-scientific-cycle-of-chaos-engineering.jpg b/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/diagrams/the-scientific-cycle-of-chaos-engineering.jpg
index 5215feafb..c4c0ab60a 100644
Binary files a/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/diagrams/the-scientific-cycle-of-chaos-engineering.jpg and b/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/diagrams/the-scientific-cycle-of-chaos-engineering.jpg differ
diff --git a/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/index.mdx b/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/index.mdx
index 77b5d7f85..1b41bfa8a 100644
--- a/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/index.mdx
+++ b/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/index.mdx
@@ -26,10 +26,11 @@ This article covers what chaos engineering actually is (hint: it's not random de
The term "chaos engineering" sounds destructive, which leads to a common misconception: that it's about randomly breaking things to see what happens. That's not chaos engineering — that's just chaos.
-Real chaos engineering follows the scientific method. You form a hypothesis about how your system should behave under specific failure conditions, you design a controlled experiment to test that hypothesis, and you observe whether reality matches your expectations. The goal isn't to cause outages; it's to build confidence that your system handles failures gracefully — or to learn exactly how it doesn't.
+Real chaos engineering follows the scientific method. You form a hypothesis about how your system should behave under specific failure conditions, you design a controlled experiment to test that hypothesis, and you observe whether reality matches your expectations. The goal isn't to cause outages; it's to build confidence that your system handles failures gracefully — or to learn exactly how it doesn't.
1 (so traffic continues on surviving pods during recovery)",
},
{
+ icon: "availability",
+ color: "page-inverse",
+ bgColor: "note-inverse",
text: "Health checks (liveness and readiness probes) are configured",
},
{
+ icon: "observability-and-telemetry",
+ color: "page-inverse",
+ bgColor: "note-inverse",
text: "You have monitoring in place to observe the experiment",
},
]}
@@ -107,6 +120,9 @@ The simplest and most valuable first experiment is killing a pod. If you've neve
-
These findings alone justify the experiment. And you can run it in staging today, with no budget approval, no platform purchase, and no dedicated chaos team.
diff --git a/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/pdf.mdx b/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/pdf.mdx
index 534c61cb3..d0d45501b 100644
--- a/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/pdf.mdx
+++ b/src/content/articles/chaos-engineering-failure-injection-low-cost-experiments/pdf.mdx
@@ -47,7 +47,8 @@ The term "chaos engineering" sounds destructive, which leads to a common misconc
Real chaos engineering follows the scientific method. You form a hypothesis about how your system should behave under specific failure conditions, design a controlled experiment to test that hypothesis, and observe whether reality matches your expectations. The goal isn't to cause outages; it's to build confidence that your system handles failures gracefully — or to learn exactly how it doesn't.
@@ -142,6 +145,8 @@ From there, you can progress to experiments during business hours with real traf
@@ -415,33 +420,33 @@ Code: LitmusChaos network latency experiment.
The tradeoff with LitmusChaos is complexity. You need to install the LitmusChaos operator, set up service accounts with appropriate permissions, and understand the CRD-based workflow. For teams already deep in Kubernetes and GitOps, this feels natural. For teams just starting with chaos engineering, Chaos Toolkit's simpler CLI-based approach might be easier to adopt.
@@ -654,24 +660,23 @@ Watch for the new pod scheduling, the health check passing, and traffic resuming
What teams commonly discover from this experiment:
-
### Experiment 2: Dependency Latency
Most production incidents aren't clean crashes — they're slowdowns. A database that responds in 500ms instead of 10ms is technically "up," but your service might as well be down if it can't handle the latency gracefully. This experiment reveals whether your timeouts, circuit breakers, and connection pools are configured correctly.
@@ -708,7 +713,7 @@ Success looks like: service remains responsive (P99 under 3 seconds), no cascadi
What teams commonly discover:
@@ -859,42 +865,42 @@ The progression takes time — typically a year or more to go from first experim
Here's a realistic four-quarter roadmap for building a chaos engineering practice from scratch:
You don't need an enterprise chaos platform to start chaos engineering. You need a hypothesis, a safe experiment, monitoring to observe the results, and the discipline to fix what you find. Start small, learn, and expand.
+
+Once you've mastered the four experiments in this guide, the path forward opens up. You can explore zone and region failures to test geographic redundancy. You can inject clock skew to find time-sensitive bugs. You can simulate certificate expiration, DNS failures, or cloud provider API throttling. Each new experiment type reveals a different class of bugs — and each one can be done with free tools.
+
+The barrier to starting isn't tooling or budget. It's deciding to run that first experiment. Pick a service. Form a hypothesis. Open your monitoring dashboard. Kill a pod. Watch what happens.
diff --git a/src/content/articles/ci-pipeline-caching-docker-layers-dependency-cache/index.mdx b/src/content/articles/ci-pipeline-caching-docker-layers-dependency-cache/index.mdx
index bc4be74c4..a2a2766bf 100644
--- a/src/content/articles/ci-pipeline-caching-docker-layers-dependency-cache/index.mdx
+++ b/src/content/articles/ci-pipeline-caching-docker-layers-dependency-cache/index.mdx
@@ -13,7 +13,7 @@ featured: true
CI caching is one of those optimizations that looks straightforward until it isn't. The pitch is simple: cache dependencies and build artifacts so you don't re-download and re-compile the same code on every build. Teams routinely cut 45-minute builds down to 8 minutes. That's real productivity — more deploys per day, faster feedback loops, happier engineers.
-But here's what nobody mentions in the "speed up your CI" blog posts: incorrect caching produces builds that pass CI and fail in production.
+But here's what nobody mentions in the "speed up your CI" blog posts. Incorrect caching produces builds that pass CI and fail in production.
I've seen this pattern more than once. A team aggressively caches everything, build times plummet, everyone celebrates. Three weeks later, a security patch lands in a transitive dependency. The team runs `npm audit fix`, but they're caching `node_modules` with a key that only hashes `package-lock.json`. The lockfile didn't change (the patch was already in the allowed semver range), so the cache hits and the old, vulnerable version keeps getting restored. The vulnerability makes it to production. The rollback takes longer than all the time they saved.
@@ -30,19 +30,22 @@ A cache key is a string that uniquely identifies a cached artifact. When your bu
The key to effective caching is designing keys that change when (and only when) the cached content should change. A good cache key has three components:
v1-deps-*)',
},
{
lead: "Dynamic components",
- text: "that capture everything affecting the cached content (e.g., lockfile hash)",
+ text: "Captures everything affecting the cached content (e.g., lockfile hash)",
},
{
lead: "Optionally, a version or OS component",
- text: "for environment-specific caches (e.g., `runner.os`)",
+ text: 'For environment-specific caches (e.g., runner.os)',
},
]}
/>
@@ -67,7 +70,7 @@ The `hashFiles()` function computes a hash of the specified files — when `pack
Three principles determine whether a cache is safe to use:
A fast build that produces incorrect artifacts is worse than a slow build. Before optimizing cache hit ratio, ensure your cache keys capture everything that affects build output.
+This article covers the fundamentals of CI caching (cache keys, restore keys, and correctness principles), dependency caching across language ecosystems, Docker layer caching and BuildKit features, the pitfalls that turn caching into a footgun, and how to measure whether your caching is actually working.
+
## The Fundamentals of CI Caching
### Why CI Builds Are Slow
@@ -34,7 +34,8 @@ A fast build that produces incorrect artifacts is worse than a slow build. Befor
Before optimizing, it helps to know where the time actually goes. Here's a breakdown of typical CI pipeline phases and their caching potential:
v1-deps-*)',
},
{
lead: "Dynamic components",
- text: "that capture everything affecting the cached content (e.g., lockfile hash)",
+ text: "Captures everything affecting the cached content (e.g., lockfile hash)",
},
{
lead: "Optionally, a version or OS component",
- text: "for environment-specific caches (e.g., `runner.os`)",
+ text: 'For environment-specific caches (e.g., runner.os)',
},
]}
/>
@@ -124,25 +128,27 @@ Restore keys provide fallback options when the exact cache key doesn't match. Th
Three principles determine whether a cache is safe to use:
+These three principles are easy to state but surprisingly easy to violate. The table below maps each principle to the rule it enforces and the mistake that breaks it — a useful checklist when something is caching incorrectly.
+
npm install instead of npm ci allows the package manager to resolve different versions on different runs, even with the same lockfile.',
},
{
lead: "Timestamps",
- text: "If your build embeds the current timestamp in artifacts, a cached artifact won't match a fresh build. Use `SOURCE_DATE_EPOCH` for reproducible builds.",
+ text: 'If your build embeds the current timestamp in artifacts, a cached artifact won\'t match a fresh build. Use SOURCE_DATE_EPOCH for reproducible builds.',
},
{
lead: "Parallel race conditions",
@@ -743,11 +749,11 @@ GitHub Actions shows cache hit/miss in workflow logs and provides cache manageme
Four metrics tell you whether caching is working:
cache_hits / (cache_hits + cache_misses). A healthy ratio is above 80%. Below 50% for more than a day means something is wrong with your cache key design.',
},
{
lead: "Time saved",
@@ -805,22 +811,22 @@ Code: Script to list cache entries via GitHub API.
Common causes of unexpected misses:
@@ -978,7 +984,10 @@ __GitLab cache gotcha__: If you're using Kubernetes executors with distributed r
CI caching is deceptively simple on the surface: save files, restore files, skip work. But effective caching requires understanding the principles beneath the configuration.
Retries without limits are a distributed denial-of-service attack against your own infrastructure. Every retry multiplies load on an already struggling service.
+Circuit breakers and retry budgets exist to break this cycle. A circuit breaker monitors failure rates and "opens" when a downstream service is unhealthy, failing requests immediately instead of adding load to a struggling service. A retry budget limits the total number of retries across all requests, preventing the exponential amplification that turns a minor issue into a major outage.
+
## The Cascade Failure Pattern
-Understanding the mechanics of cascade failures requires tracing the path from initial symptom to system-wide collapse. The pattern is predictable, which means it's also preventable.
+Understanding the mechanics of cascade failures requires tracing the path from initial symptom to system-wide collapse. The pattern is predictable, which means it's also preventable.
Consider a typical service chain: an API gateway calls a checkout service, which calls an inventory service, which queries a database. Each layer has timeouts and retry logic configured independently. Nobody coordinated these settings because each team was responsible for their own service.
The failure starts at the bottom. A database experiences momentary slowness — maybe a long-running query, maybe garbage collection, maybe a network hiccup. What happens next follows a predictable sequence:
-```text
-Timeline of a cascade failure:
-
-T+0: Database slow (100ms → 2s response time)
-T+10s: Service C queues grow, some requests timeout
-T+20s: Service B sees C timeouts, starts retrying
-T+30s: Service A sees B timeouts, starts retrying
-T+45s: All services at maximum queue depth
-T+60s: Database recovers, but services cannot — queues too deep
-T+2min: Manual intervention required
-T+5min: Services restarted, queues cleared
-T+10min: Full recovery
-
-Root cause: 30 second database slowdown
-Actual outage: 10 minutes
-Amplification factor: 20x
-```
-Figure: Timeline showing how a brief database slowdown cascades into a 10-minute outage.
+Timeline of a cascade failure showing how a brief database slowdown cascades into a 10-minute outage:
+
+
+
+The timeline above shows the domino effect, but the summary tells the real story:
+
+
-The database recovered at T+60s, but the cascade continued for another 9 minutes. By the time the database was healthy, each upstream service had thousands of requests queued. Those queued requests kept hammering downstream services, preventing recovery. The system needed manual intervention — draining queues, restarting services — to return to normal operation.
+The database recovered at `T+60s`, but the cascade continued for another 9 minutes. By the time the database was healthy, each upstream service had thousands of requests queued. Those queued requests kept hammering downstream services, preventing recovery. The system needed manual intervention — draining queues, restarting services — to return to normal operation.
### Retry Amplification
@@ -66,7 +114,8 @@ The math behind retry amplification is straightforward, and terrifying. Each ser
The formula is simple: $$(r + 1)^n$$ where $$r$$ is retries per service and $$n$$ is the number of services in the chain. With 3 services each retrying 3 times, that's $$4^3 = 64x$$ load amplification.
Retries without limits are a distributed denial-of-service attack against your own infrastructure. Every retry multiplies load on an already struggling service.
+These aren't nice-to-have resilience patterns. They're survival mechanisms for any system with service dependencies.
+
## The Cascade Failure Pattern
### How Failures Cascade
@@ -43,23 +43,70 @@ Consider a typical service chain: an API gateway calls a checkout service, which
The failure starts at the bottom. A database experiences momentary slowness — maybe a long-running query, maybe garbage collection, maybe a network hiccup. What happens next follows a depressingly predictable sequence:
-```text
-Timeline of a cascade failure:
-
-T+0: Database slow (100ms → 2s response time)
-T+10s: Service C queues grow, some requests timeout
-T+20s: Service B sees C timeouts, starts retrying
-T+30s: Service A sees B timeouts, starts retrying
-T+45s: All services at maximum queue depth
-T+60s: Database recovers, but services cannot — queues too deep
-T+2min: Manual intervention required
-T+5min: Services restarted, queues cleared
-T+10min: Full recovery
-
-Root cause: 30 second database slowdown
-Actual outage: 10 minutes
-Amplification factor: 20x
-```
+
+
+The timeline above shows the domino effect, but the summary tells the real story:
+
+
The database recovered at T+60s, but the cascade continued for another 9 minutes. By the time the database was healthy, each upstream service had thousands of requests queued. Those queued requests kept hammering downstream services, preventing recovery. The system needed manual intervention — draining queues, restarting services — to return to normal operation.
@@ -72,7 +119,8 @@ The formula is simple: $$(r + 1)^n$$ where $$r$$ is retries per service and $$n$
The table below shows how quickly this gets out of hand. These numbers assume every request at every layer fails and triggers full retries — a worst case, but exactly what happens during a cascade failure:
DestinationRule above)',
+ text: 'Handles circuit breaking at the infrastructure layer. Your application code stays simple — it just makes HTTP calls — while Envoy sidecars handle failure detection and traffic shifting. The downside is complexity: you need a mesh deployed, and debugging "why didn\'t my request go through" now involves understanding Envoy configs and mesh telemetry. Service meshes work best when you want consistent resilience policies across many services without modifying application code.',
},
{
- lead: "Application libraries",
- text: "like opossum (Node.js), resilience4j (Java), or gobreaker (Go) give you fine-grained control. You can configure different thresholds per endpoint, implement custom fallback logic, and emit metrics that tie directly to your application's business logic. The tradeoff is that every service needs to implement and configure the library correctly — there's no centralized policy enforcement.",
+ lead: "Application libraries like opossum (Node.js), resilience4j (Java), or gobreaker (Go)",
+ text: "Gives you fine-grained control. You can configure different thresholds per endpoint, implement custom fallback logic, and emit metrics that tie directly to your application's business logic. The tradeoff is that every service needs to implement and configure the library correctly — there's no centralized policy enforcement.",
},
{
- lead: "API gateways and load balancers",
- text: "(AWS ALB, Kong, NGINX) can implement basic circuit breaking at the edge. This protects your backend from external traffic surges but doesn't help with service-to-service calls within your infrastructure.",
+ lead: "API gateways and load balancers (like AWS ALB, Kong, NGINX)",
+ text: "Can implement basic circuit breaking at the edge. This protects your backend from external traffic surges but doesn't help with service-to-service calls within your infrastructure.",
},
]}
/>
@@ -245,8 +296,11 @@ const recommendations = await productCircuit.execute(
```
Code: Fallback strategy implementations for circuit breakers.
+Each strategy fits a different failure mode. The table below maps them to the right context and the cost you accept when using them:
+
@@ -313,16 +370,19 @@ __Traditional Retries:__
__Retry Budget:__
@@ -330,13 +390,16 @@ __Retry Budget:__
__Under failure:__
@@ -499,30 +562,38 @@ The `circuit_state` gauge tells you at a glance which circuits are open. The `ci
Your circuit breaker dashboard should answer three questions at a glance: which circuits are open, why did they open, and how much traffic is being rejected?
-```text
-+------------------------------------------+
-| CIRCUIT STATES |
-| [Service A: CLOSED] [Service B: OPEN] |
+
+{String.raw`
++-------------------------------------------+
+| CIRCUIT STATES |
+| [Service A: CLOSED] [Service B: OPEN] |
| [Service C: HALF_OPEN] [Service D: CLOSED]|
-+------------------------------------------+
-| STATE TRANSITIONS (24h) |
-| Timeline showing open/closed transitions |
-+------------------------------------------+
-| FAILURE RATES BY SERVICE |
-| Service A: 0.1% ████░░░░░░ |
-| Service B: 45% ████████████████████░░ |
-| Service C: 12% ████████░░░░░░░░░░░░░░ |
-+------------------------------------------+
-| RETRY BUDGET UTILIZATION |
-| Service A: 5% ██░░░░░░░░░░ |
++-------------------------------------------+
+| STATE TRANSITIONS (24h) |
+| Timeline showing open/closed transitions |
++-------------------------------------------+
+| FAILURE RATES BY SERVICE |
+| Service A: 0.1% ████░░░░░░ |
+| Service B: 45% ████████████████████░░ |
+| Service C: 12% ████████░░░░░░░░░░░░░░ |
++-------------------------------------------+
+| RETRY BUDGET UTILIZATION |
+| Service A: 5% ██░░░░░░░░░░ |
| Service B: 100% ████████████████████████ |
-| Service C: 35% ██████████░░░░░░░░░░░░░ |
-+------------------------------------------+
-| REQUESTS REJECTED (Circuit Open) |
-| [Graph showing rejected requests/min] |
-+------------------------------------------+
-```
-Code: Circuit Breaker Dashboard Layout
+| Service C: 35% ██████████░░░░░░░░░░░░░ |
++-------------------------------------------+
+| REQUESTS REJECTED (Circuit Open) |
+| [Graph showing rejected requests/min] |
++-------------------------------------------+
+`}
+
The state transition timeline is particularly useful for post-incident analysis. You can correlate circuit opens with deployment events, traffic spikes, or downstream service issues. A circuit that opened 30 seconds after a deploy is telling you something different than one that opened during peak traffic.
@@ -598,7 +669,10 @@ When a circuit isn't behaving as expected, the problem usually falls into one of
__Circuit opens unexpectedly:__
failure_conditions includes the error types you expect'],
},
{
- th: "`minimum_requests` too high",
+ th: 'minimum_requests too high',
td: ["Lower it for low-traffic services"],
},
{
th: "Window too long",
- td: ["Decrease `window_duration` to detect failures faster"],
+ td: ['Decrease window_duration to detect failures faster'],
},
],
},
@@ -652,7 +729,10 @@ __Circuit not opening:__
__Circuit not closing:__
success_threshold too high',
+ td: ['Reduce half_open.success_threshold'],
},
],
},
@@ -770,15 +850,23 @@ When every service in a call chain uses the same timeout value, you get cascadin
Timeouts should decrease as you go down the call stack. If A has a 10-second timeout, B should use 5 seconds, and C should use 2 seconds. This gives each layer time to handle failures gracefully rather than racing against the clock.
-```text
+
// BAD: Identical timeouts
-A (timeout: 5s) → B (timeout: 5s) → C (timeout: 5s)
// C takes 4s, B returns at 4s, but A times out at 5s total
+A (timeout: 5s) → B (timeout: 5s) → C (timeout: 5s)
// GOOD: Decreasing timeouts
-A (timeout: 10s) → B (timeout: 5s) → C (timeout: 2s)
// Each layer has headroom for retries and error handling
-```
+A (timeout: 10s) → B (timeout: 5s) → C (timeout: 2s)
+
+
+The decreasing-timeout pattern above is necessary but not sufficient on its own — you also need to think about what happens when a downstream service is completely unreachable rather than just slow.
Coordinate timeout budgets across your service chain. If you don't control all services in the chain, at minimum ensure your timeout is longer than the timeout of services you call. In gRPC systems, consider propagating deadlines via metadata headers so downstream services know how much time remains and can fail fast if the budget is already exhausted.
@@ -791,23 +879,23 @@ Coordinate timeout budgets across your service chain. If you don't control all s
Most languages have mature circuit breaker implementations. The choice usually comes down to whether you want a focused library that does one thing well, or a comprehensive resilience toolkit.
@@ -853,10 +941,10 @@ Circuit breakers and retry budgets address two sides of the same problem. Circui
These mechanisms work together. The retry budget prevents overwhelming a service __before__ the circuit opens. The circuit breaker stops traffic __after__ sustained failures are detected. Neither alone is sufficient: circuit breakers without retry budgets still allow amplification during the detection window, and retry budgets without circuit breakers still send initial requests to a service that's clearly down.
-The goal isn't perfect availability — it's graceful degradation. When a dependency fails, your service should continue operating in a reduced capacity rather than collapsing entirely. Cached responses, default values, and degraded experiences are all preferable to error pages or timeouts that propagate up the stack.
-
-Observability makes the difference between "it worked" and "I understand how it worked." A circuit breaker that opens silently is better than none, but a circuit breaker with metrics, dashboards, and alerts lets you tune thresholds, correlate failures with deployments, and catch problems before users notice. Instrument from day one.
-
Start with your most critical downstream dependency. Add a circuit breaker with opossum or resilience4j this week. Instrument the metrics. Watch how it behaves under normal load. Then expand to other dependencies. The best time to implement these patterns is before your first cascade failure, not after.
+
+The goal isn't perfect availability — it's graceful degradation. When a dependency fails, your service should continue operating in a reduced capacity rather than collapsing entirely. Cached responses, default values, and degraded experiences are all preferable to error pages or timeouts that propagate up the stack.
+
+Observability makes the difference between "it worked" and "I understand how it worked." A circuit breaker that opens silently is better than none, but a circuit breaker with metrics, dashboards, and alerts lets you tune thresholds, correlate failures with deployments, and catch problems before users notice. Instrument from day one.
diff --git a/src/content/articles/consumer-driven-contract-testing-pact-internal-apis/index.mdx b/src/content/articles/consumer-driven-contract-testing-pact-internal-apis/index.mdx
index 8fb7531f1..abee60493 100644
--- a/src/content/articles/consumer-driven-contract-testing-pact-internal-apis/index.mdx
+++ b/src/content/articles/consumer-driven-contract-testing-pact-internal-apis/index.mdx
@@ -31,7 +31,7 @@ The problems compound quickly. Shared test databases accumulate garbage data fro
When an integration test fails, debugging becomes archaeology. A failure in Service X might be caused by a change in Service Y, but the stack trace only shows where the exception was thrown, not where the problem originated. Reproducing the failure locally requires spinning up the entire environment, which often behaves differently than CI.
diff --git a/src/layouts/MarkdownLayout.astro b/src/layouts/MarkdownLayout.astro
index 68bacdc81..7dd37c2e4 100644
--- a/src/layouts/MarkdownLayout.astro
+++ b/src/layouts/MarkdownLayout.astro
@@ -24,6 +24,7 @@ import Diagram from '@components/Diagram/index.astro'
import Download from '@components/CallToAction/Download/index.astro'
import Embed from '@components/Social/Embed/index.astro'
import Highlighter from '@components/Social/Highlighter/index.astro'
+import HighlighterIconBank from '@components/Social/Highlighter/HighlighterIconBank.astro'
import Icon from '@components/Icon/index.astro'
import Inset from '@components/Inset/index.astro'
import List from '@components/List/index.astro'
@@ -34,6 +35,7 @@ import Table from '@components/Table/index.astro'
import Time from '@components/Time/index.astro'
import Testimonials from '@components/Testimonials/index.astro'
import CodeTabs from '@components/Code/CodeTabs/index.astro'
+import '@components/Social/Highlighter/index.css'
/** Export components for use in MDX */
const Components = {
@@ -191,6 +193,22 @@ const shouldRenderToc = showToc !== false && tocHeadings.length > 0
+
+
+
+
+
diff --git a/src/lib/config/__tests__/siteUrlServer.spec.ts b/src/lib/config/__tests__/siteUrlServer.spec.ts
index e6b2cfa32..d0037de5c 100644
--- a/src/lib/config/__tests__/siteUrlServer.spec.ts
+++ b/src/lib/config/__tests__/siteUrlServer.spec.ts
@@ -36,8 +36,8 @@ describe('getSiteUrl', () => {
isGitHubMock.mockReturnValue(false)
const invokeGetSiteUrl = () => getSiteUrl()
- expect(invokeGetSiteUrl).toThrowError(BuildError)
- expect(invokeGetSiteUrl).toThrowError(
+ expect(invokeGetSiteUrl).toThrow(BuildError)
+ expect(invokeGetSiteUrl).toThrow(
'❌ Build runs on GitHub, so this build-time getSiteUrl() function should never be called on Vercel.'
)
})
diff --git a/src/lib/helpers/__tests__/breadcrumbTitleLengthRefinement.spec.ts b/src/lib/helpers/__tests__/breadcrumbTitleLengthRefinement.spec.ts
index 0c1c1abe2..543c7c5c4 100644
--- a/src/lib/helpers/__tests__/breadcrumbTitleLengthRefinement.spec.ts
+++ b/src/lib/helpers/__tests__/breadcrumbTitleLengthRefinement.spec.ts
@@ -1,5 +1,5 @@
import { describe, it, expect, vi, afterEach } from 'vitest'
-import { z } from 'astro:content'
+import { z } from 'astro/zod'
const LONG_TITLE = 'A'.repeat(61)
const SHORT_TITLE = 'Short title'
diff --git a/src/lib/helpers/breadcrumbTitleLengthRefinement.ts b/src/lib/helpers/breadcrumbTitleLengthRefinement.ts
index 66a58dbc3..e1be3a503 100644
--- a/src/lib/helpers/breadcrumbTitleLengthRefinement.ts
+++ b/src/lib/helpers/breadcrumbTitleLengthRefinement.ts
@@ -1,4 +1,4 @@
-import { z } from 'astro:content'
+import type { ZodObject, ZodRawShape } from 'astro/zod'
const MAX_BREADCRUMB_TITLE_LENGTH = 60
const loggedBreadcrumbTitleWarnings = new Set()
@@ -25,11 +25,11 @@ export const warnOnBreadcrumbTitleLength = (title: string, collectionName: strin
* @param collectionName Name of the collection, used to scope warning messages
* @returns Zod schema augmented with breadcrumb title length validation
*/
-export const withBreadcrumbTitleWarning = (
- schema: z.ZodObject,
+export const withBreadcrumbTitleWarning = (
+ schema: ZodObject,
collectionName: string
) =>
- schema.superRefine(data => {
+ schema.superRefine((data: { title?: string }) => {
const candidateTitle = (data as { title?: string }).title
if (typeof candidateTitle === 'string') {
warnOnBreadcrumbTitleLength(candidateTitle, collectionName)
diff --git a/src/lib/plugins/fixContentAssetPropagation.ts b/src/lib/plugins/fixContentAssetPropagation.ts
index 39090677e..09b5bf888 100644
--- a/src/lib/plugins/fixContentAssetPropagation.ts
+++ b/src/lib/plugins/fixContentAssetPropagation.ts
@@ -32,6 +32,30 @@ type TransformFn = (
_options?: { ssr?: boolean },
) => unknown
+type TransformHook =
+ | TransformFn
+ | {
+ filter?: unknown
+ handler: TransformFn
+ }
+
+const forceNonSsrTransform = (transform: TransformHook): TransformHook => {
+ const wrapHandler = (handler: TransformFn): TransformFn => {
+ return function (this: unknown, code: string, id: string, options?: { ssr?: boolean }) {
+ return handler.call(this, code, id, { ...options, ssr: false })
+ }
+ }
+
+ if (typeof transform === 'function') {
+ return wrapHandler(transform)
+ }
+
+ return {
+ ...transform,
+ handler: wrapHandler(transform.handler),
+ }
+}
+
export function fixContentAssetPropagation(): PluginOption {
return {
name: 'fix-content-asset-propagation',
@@ -41,18 +65,8 @@ export function fixContentAssetPropagation(): PluginOption {
(p: Plugin) => p.name === 'astro:content-asset-propagation',
)
if (!plugin?.transform) return
- const originalTransform = (plugin.transform as TransformFn).bind(plugin) as TransformFn
const pluginRecord = plugin as unknown as Record
- pluginRecord['transform'] = function (
- this: unknown,
- code: string,
- id: string,
- options?: { ssr?: boolean },
- ) {
- // Force non-SSR path to avoid devModuleLoader, which was contaminated
- // by the DB integration's temp server during astro:build:setup.
- return originalTransform.call(this, code, id, { ...options, ssr: false })
- }
+ pluginRecord['transform'] = forceNonSsrTransform(plugin.transform as TransformHook)
},
}
}
diff --git a/src/pages/articles/[...slug].astro b/src/pages/articles/[...slug].astro
index 5e93efa20..147a38107 100644
--- a/src/pages/articles/[...slug].astro
+++ b/src/pages/articles/[...slug].astro
@@ -1,4 +1,6 @@
---
+export const prerender = true
+
import { type CollectionEntry, getCollection, getEntry } from 'astro:content'
import { isDev } from '@lib/config/environmentServer'
import { getReadingTimeLabel } from '@lib/markdown/utils/readingTime'
diff --git a/src/pages/case-studies/[slug].astro b/src/pages/case-studies/[slug].astro
index e6382f34b..24f2d03f5 100644
--- a/src/pages/case-studies/[slug].astro
+++ b/src/pages/case-studies/[slug].astro
@@ -1,4 +1,6 @@
---
+export const prerender = true
+
import { getCollection } from 'astro:content'
import { Picture } from 'astro:assets'
import MarkdownLayout from '@layouts/MarkdownLayout.astro'
@@ -45,6 +47,8 @@ const section = 'Case Studies'
sizes="100vw"
formats={['avif', 'webp', 'jpeg']}
layout="constrained"
+ loading="eager"
+ fetchpriority="high"
fit="cover"
position="center"
class="absolute inset-0 h-full w-full"
diff --git a/src/pages/deep-dive/[...slug].astro b/src/pages/deep-dive/[...slug].astro
index 7c7882c5b..07cb58c86 100644
--- a/src/pages/deep-dive/[...slug].astro
+++ b/src/pages/deep-dive/[...slug].astro
@@ -1,4 +1,6 @@
---
+export const prerender = true
+
import { type CollectionEntry, getCollection, getEntry } from 'astro:content'
import { isDev } from '@lib/config/environmentServer'
import { getReadingTimeLabel } from '@lib/markdown/utils/readingTime'
diff --git a/src/pages/downloads/[...slug].astro b/src/pages/downloads/[...slug].astro
index abfc6c7a2..63996b7db 100644
--- a/src/pages/downloads/[...slug].astro
+++ b/src/pages/downloads/[...slug].astro
@@ -1,4 +1,6 @@
---
+export const prerender = true
+
import { type CollectionEntry, getCollection } from 'astro:content'
import { isDev } from '@lib/config/environmentServer'
import PageLayout from '@layouts/PageLayout.astro'
diff --git a/src/pages/rss.xml.ts b/src/pages/rss.xml.ts
index 70312f03d..df3271118 100644
--- a/src/pages/rss.xml.ts
+++ b/src/pages/rss.xml.ts
@@ -35,7 +35,9 @@ export async function GET() {
pubDate: article.data.publishDate,
description: article.data.description,
link: `/articles/${article.id}`,
- categories: (article.data.tags ?? []).map(toCategory).filter((c): c is string => Boolean(c)),
+ categories: (article.data.tags ?? [])
+ .map(toCategory)
+ .filter((category): category is string => Boolean(category)),
})),
customData: `en-us`,
})
diff --git a/src/pages/tags/[tag].astro b/src/pages/tags/[tag].astro
index 2c125e8c1..5d9032969 100644
--- a/src/pages/tags/[tag].astro
+++ b/src/pages/tags/[tag].astro
@@ -1,4 +1,6 @@
---
+export const prerender = true
+
import { type CollectionEntry, getCollection, render } from 'astro:content'
import { Picture } from 'astro:assets'
import { isDev } from '@lib/config/environmentServer'
@@ -18,7 +20,7 @@ export async function getStaticPaths() {
const allArticles = await getCollection('articles', ({ data }) => isDev() || data.isDraft !== true)
const articleHasTag = (article: CollectionEntry<'articles'>, tagEntry: CollectionEntry<'tags'>) => {
- return article.data.tags.some(tagRef => tagRef.id === tagEntry.id)
+ return article.data.tags.some((tagRef: { id: string }) => tagRef.id === tagEntry.id)
}
return allTags.map(tagEntry => {
@@ -33,7 +35,7 @@ export async function getStaticPaths() {
}
const { tag } = Astro.params
-const { content: allTagContent } = Astro.props
+const { content: allTagContent } = Astro.props as Props
const [tagEntry] = await getCollection('tags', ({ data }) => data.slug === tag)
if (!tagEntry) {
diff --git a/src/pages/testing/comps/scratchpad.astro b/src/pages/testing/comps/scratchpad.astro
index 04fe8ec11..bf1185707 100644
--- a/src/pages/testing/comps/scratchpad.astro
+++ b/src/pages/testing/comps/scratchpad.astro
@@ -1,12 +1,48 @@
---
import BaseLayout from '@layouts/BaseLayout.astro'
+import List from '@components/List/index.astro'
const pageTitle = 'Scratchpad'
const pageDescription = 'Styling Variants'
const path = '/testing/comps/scratchpad'
+const chatBubbleItems = [
+ {
+ lead: 'Why did the system go down?',
+ text: 'Because a config change broke it.',
+ },
+ {
+ lead: 'Why did the config change break it?',
+ text: 'Because the engineer made a mistake.',
+ },
+ {
+ lead: 'Why did the engineer make a mistake?',
+ text: 'Because they were careless.',
+ },
+]
---
+
+
Variant 6 — Chat Bubbles
+
+
+
+
Variant 8 — Elevated Hover Cards
+
+
+
Why did the system go down?
+
Because a config change broke it.
+
+
+
Why did the config change break it?
+
Because the engineer made a mistake.
+
+
+
Why did the engineer make a mistake?
+
Because they were careless.
+
+
+
diff --git a/vitest.config.ts b/vitest.config.ts
index 7464169bb..0856df4f3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -153,4 +153,8 @@ export default getViteConfig({
},
},
// eslint-disable-next-line @typescript-eslint/no-explicit-any
-} as any)
+} as any, {
+ // Astro actions require server output. Override the app's static output only
+ // for Vitest so unit tests can load the Astro config without changing runtime behavior.
+ output: 'server',
+})
`
+ : null}
+