From 4394f5f595b541c575df2fe587d53e4307315ccd Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 12:05:43 -0600 Subject: [PATCH 01/16] feat(fastly-reference-architectures): add skill entrypoint --- .../fastly-reference-architectures/SKILL.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 skills/fastly-reference-architectures/SKILL.md diff --git a/skills/fastly-reference-architectures/SKILL.md b/skills/fastly-reference-architectures/SKILL.md new file mode 100644 index 0000000..7869797 --- /dev/null +++ b/skills/fastly-reference-architectures/SKILL.md @@ -0,0 +1,57 @@ +--- +name: fastly-reference-architectures +description: "Curated, Fastly-endorsed GitHub repositories that demonstrate working reference architectures on the Fastly platform, from a single Compute application up through systems combining multiple Fastly products (Compute, WAF/NGWAF, KV store, real-time logging, shielding). Use when designing a new solution on Fastly and a worked example of the target pattern would help, or when implementing and a concrete assembled reference would clarify the shape of the code. Not for documentation of how a specific Fastly tool or API works on its own — see the tool-specific skills for that." +--- + +# Fastly reference architectures + +This skill points to a small number of GitHub repositories that Fastly, or a named and +accountable reviewer, endorses as good reference examples for building on the Fastly +platform. It is not primitive-level API or CLI documentation — see the tool-specific +skills for that — it is examples of assembled, working systems worth modeling a new +design after. + +## Before recommending any entry + +Verify the repo is not archived and has commit activity roughly consistent with "still +maintained" — e.g. `gh repo view / --json isArchived,pushedAt` (or the GitHub +web UI if `gh` isn't available). If a repo is archived or long-dormant, say so explicitly +rather than presenting it as current, and flag it to this skill's maintainers (a PR +comment or issue) rather than editing the entry yourself. + +## Pick the reference file + +| You're looking for a pattern for... | File | +| --- | --- | +| Authentication, authorization, or security combos (WAF/NGWAF + Compute + rate limiting) | [references/edge-auth-and-security.md](references/edge-auth-and-security.md) | +| Cache-key design, shielding, purge strategies | [references/caching-and-delivery.md](references/caching-and-delivery.md) | +| A single Compute application (KV-backed apps, image/video processing, A/B testing at the edge) | [references/compute-application-patterns.md](references/compute-application-patterns.md) | +| A system combining 3+ Fastly products into one architecture | [references/multi-service-architectures.md](references/multi-service-architectures.md) | +| Logging pipelines, real-time stats dashboards, alerting | [references/observability-and-ops.md](references/observability-and-ops.md) | + +## Entry format + +Every entry in every reference file uses this schema: + +```markdown +### — +- **Repo:** github.com/org/repo +- **Source:** official (fastly org / fastly-devrel) | community (name who vetted it) +- **Demonstrates:** the specific pattern worth copying, not just "a Compute app" +- **Watch out for:** known gaps, outdated dependencies, or divergence from current best + practice — "none known as of last verification" if genuinely none +- **Last verified:** YYYY-MM-DD +``` + +## Adding or removing an entry + +Same process as every other change in this repo: open a PR. The bar for inclusion is +either the repo is from an official Fastly org, or a named person is willing to attach +their judgment to it via the `Source` field. Keep each file to a handful of genuinely +excellent entries — quality and a low re-review burden over exhaustive coverage. + +## Not this skill + +How a specific Fastly tool, CLI, or API works: see `fastly`, `fastly-cli`, +`fastly-stats`, `falco`, `fastlike`, `viceroy`, `xvcl`, `fastly-fiddle`. This skill shows +assembled, working systems, not primitives. From 13625314b65ea3b44e97f0acad0f59bb50dce4dd Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 12:24:40 -0600 Subject: [PATCH 02/16] feat(fastly-reference-architectures): add edge auth and security examples Co-Authored-By: Claude Sonnet 5 --- .../references/edge-auth-and-security.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 skills/fastly-reference-architectures/references/edge-auth-and-security.md diff --git a/skills/fastly-reference-architectures/references/edge-auth-and-security.md b/skills/fastly-reference-architectures/references/edge-auth-and-security.md new file mode 100644 index 0000000..2c542ae --- /dev/null +++ b/skills/fastly-reference-architectures/references/edge-auth-and-security.md @@ -0,0 +1,22 @@ +# Edge auth and security reference architectures + +### google-apple-github-auth — OAuth via Compute +- **Repo:** github.com/bharwani/google-apple-github-auth +- **Source:** community (bharwani) +- **Demonstrates:** OAuth/social-login authentication implemented at the edge in Compute — the JWT/edge-auth pattern this file exists for. +- **Watch out for:** none known as of last verification (thin README beyond the description; verify the OAuth flow still matches current provider requirements before modeling new code closely after it). +- **Last verified:** 2026-08-19 + +### fastly-compute-news-with-content-paywall — access control / paywall at the edge +- **Repo:** github.com/saschanowak/fastly-compute-news-with-content-paywall +- **Source:** community (saschanowak) +- **Demonstrates:** authorization/paywall gating of content at the edge — an access-control pattern distinct from authentication. +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 + +### injection-classifier-poc — ML-based security classifier at the edge +- **Repo:** github.com/fastly/injection-classifier-poc +- **Source:** official (fastly org) +- **Demonstrates:** running a quantized ML model for security classification directly in a Compute WASM service — a distinct pattern from rule-based WAF/NGWAF. +- **Watch out for:** explicitly a "proof of concept," not a maintained product — check the linked model card/HuggingFace model is still the recommended one before reuse. +- **Last verified:** 2026-08-19 From bd459a6295a02065bdfb0094f0c80b1cdb4f7cdc Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 12:54:23 -0600 Subject: [PATCH 03/16] fix(fastly-reference-architectures): bump entry heading level to H2 (MD001) All entry headings in edge-auth-and-security.md changed from H3 (###) to H2 (##) to fix markdownlint MD001 violation (heading-increment). Updated the schema template in SKILL.md to match the corrected convention. Co-Authored-By: Claude Sonnet 5 --- skills/fastly-reference-architectures/SKILL.md | 2 +- .../references/edge-auth-and-security.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/fastly-reference-architectures/SKILL.md b/skills/fastly-reference-architectures/SKILL.md index 7869797..a8011ac 100644 --- a/skills/fastly-reference-architectures/SKILL.md +++ b/skills/fastly-reference-architectures/SKILL.md @@ -34,7 +34,7 @@ comment or issue) rather than editing the entry yourself. Every entry in every reference file uses this schema: ```markdown -### — +## — - **Repo:** github.com/org/repo - **Source:** official (fastly org / fastly-devrel) | community (name who vetted it) - **Demonstrates:** the specific pattern worth copying, not just "a Compute app" diff --git a/skills/fastly-reference-architectures/references/edge-auth-and-security.md b/skills/fastly-reference-architectures/references/edge-auth-and-security.md index 2c542ae..0be6bcc 100644 --- a/skills/fastly-reference-architectures/references/edge-auth-and-security.md +++ b/skills/fastly-reference-architectures/references/edge-auth-and-security.md @@ -1,20 +1,20 @@ # Edge auth and security reference architectures -### google-apple-github-auth — OAuth via Compute +## google-apple-github-auth — OAuth via Compute - **Repo:** github.com/bharwani/google-apple-github-auth - **Source:** community (bharwani) - **Demonstrates:** OAuth/social-login authentication implemented at the edge in Compute — the JWT/edge-auth pattern this file exists for. - **Watch out for:** none known as of last verification (thin README beyond the description; verify the OAuth flow still matches current provider requirements before modeling new code closely after it). - **Last verified:** 2026-08-19 -### fastly-compute-news-with-content-paywall — access control / paywall at the edge +## fastly-compute-news-with-content-paywall — access control / paywall at the edge - **Repo:** github.com/saschanowak/fastly-compute-news-with-content-paywall - **Source:** community (saschanowak) - **Demonstrates:** authorization/paywall gating of content at the edge — an access-control pattern distinct from authentication. - **Watch out for:** none known as of last verification. - **Last verified:** 2026-08-19 -### injection-classifier-poc — ML-based security classifier at the edge +## injection-classifier-poc — ML-based security classifier at the edge - **Repo:** github.com/fastly/injection-classifier-poc - **Source:** official (fastly org) - **Demonstrates:** running a quantized ML model for security classification directly in a Compute WASM service — a distinct pattern from rule-based WAF/NGWAF. From 3af8ad3986ee48778d63f33f479928ce3c957adf Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 13:05:53 -0600 Subject: [PATCH 04/16] feat(fastly-reference-architectures): add caching and delivery examples Co-Authored-By: Claude Sonnet 5 --- .../references/caching-and-delivery.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 skills/fastly-reference-architectures/references/caching-and-delivery.md diff --git a/skills/fastly-reference-architectures/references/caching-and-delivery.md b/skills/fastly-reference-architectures/references/caching-and-delivery.md new file mode 100644 index 0000000..ec5ec74 --- /dev/null +++ b/skills/fastly-reference-architectures/references/caching-and-delivery.md @@ -0,0 +1,17 @@ +# Caching and delivery reference architectures + +## vcl_shielding — custom origin shielding topology + +- **Repo:** github.com/bharwani/vcl_shielding +- **Source:** community (bharwani) +- **Demonstrates:** shielding topology decisions driven by network peering/IX considerations, not just Fastly's default shield selection. +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 + +## fastly-bulk-redirects — bulk redirect / delivery routing + +- **Repo:** github.com/Fcuervo21/fastly-bulk-redirects +- **Source:** community (Fcuervo21) +- **Demonstrates:** managing a large redirect table as a delivery/routing concern at the edge, rather than one-off VCL redirect rules. +- **Watch out for:** none known as of last verification; thin description, so skim the README on re-verification to confirm the redirect-loading mechanism it uses. +- **Last verified:** 2026-08-19 From bd49356eff65a3ac998114f7d2e6fa02bca6e67a Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 13:16:39 -0600 Subject: [PATCH 05/16] feat(fastly-reference-architectures): add compute application pattern examples Co-Authored-By: Claude Sonnet 5 --- .../compute-application-patterns.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 skills/fastly-reference-architectures/references/compute-application-patterns.md diff --git a/skills/fastly-reference-architectures/references/compute-application-patterns.md b/skills/fastly-reference-architectures/references/compute-application-patterns.md new file mode 100644 index 0000000..1a35b9a --- /dev/null +++ b/skills/fastly-reference-architectures/references/compute-application-patterns.md @@ -0,0 +1,29 @@ +# Compute application pattern reference architectures + +## fastly-edge-ab-testing — A/B testing at the edge +- **Repo:** github.com/Fcuervo21/fastly-edge-ab-testing +- **Source:** community (Fcuervo21) +- **Demonstrates:** variant assignment and routing for A/B tests done in Compute, not in application code behind the origin. +- **Watch out for:** none known as of last verification; thin description — skim the README on re-verification for the bucketing mechanism used. +- **Last verified:** 2026-08-19 + +## compute-mcp-demo — protocol gateway pattern +- **Repo:** github.com/bharwani/compute-mcp-demo +- **Source:** community (bharwani) +- **Demonstrates:** wrapping a third-party HTTP API as an MCP server entirely in Compute, using edge caching to cut per-call latency roughly 15x. +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 + +## fastly-examples-live-betting-fanout — real-time fan-out at scale +- **Repo:** github.com/dmichael-fastly/fastly-examples-live-betting-fanout +- **Source:** community (dmichael-fastly) +- **Demonstrates:** using Fastly Fanout to broadcast frequently-updated data to a large concurrent audience without a fan-out multiplier hitting origin. +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 + +## edge-mcp — official reference implementation, explicitly unmaintained +- **Repo:** github.com/fastly/edge-mcp +- **Source:** official (fastly org) +- **Demonstrates:** implementing the stateless MCP protocol revision as a Rust Compute application, from Fastly's own devrel org. +- **Watch out for:** THE REPO ITSELF SAYS IT WILL NOT BE MAINTAINED. This is exactly the "still green, quietly stale" risk the skill's freshness mechanism can't catch on its own (it isn't archived, and pushedAt is recent) — the `Watch out for` field must state this explicitly and verbatim, not just "none known," so nobody models new code against a protocol revision that has since moved on without checking the current MCP spec version first. +- **Last verified:** 2026-08-19 From 0e7568ae913dfd45ec6293f4ed8f5297902b32ba Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 13:40:54 -0600 Subject: [PATCH 06/16] fix(fastly-reference-architectures): use actual edge-mcp maintenance caveat, not editorial note Replace the editorial instruction in the edge-mcp entry's Watch out for field with the actual maintenance caveat from the repository: point-in-time example built against MCP 2026-07-28, will not be maintained beyond initial implementation. Co-Authored-By: Claude Sonnet 5 --- .../references/compute-application-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/fastly-reference-architectures/references/compute-application-patterns.md b/skills/fastly-reference-architectures/references/compute-application-patterns.md index 1a35b9a..ad71f3c 100644 --- a/skills/fastly-reference-architectures/references/compute-application-patterns.md +++ b/skills/fastly-reference-architectures/references/compute-application-patterns.md @@ -25,5 +25,5 @@ - **Repo:** github.com/fastly/edge-mcp - **Source:** official (fastly org) - **Demonstrates:** implementing the stateless MCP protocol revision as a Rust Compute application, from Fastly's own devrel org. -- **Watch out for:** THE REPO ITSELF SAYS IT WILL NOT BE MAINTAINED. This is exactly the "still green, quietly stale" risk the skill's freshness mechanism can't catch on its own (it isn't archived, and pushedAt is recent) — the `Watch out for` field must state this explicitly and verbatim, not just "none known," so nobody models new code against a protocol revision that has since moved on without checking the current MCP spec version first. +- **Watch out for:** The README states explicitly this is a 'point-in-time example' built against the MCP 2026-07-28 specification and 'will not be maintained beyond the initial implementation' — expect no updates, bug fixes, or security patches. Check the current MCP spec version before modeling new code on it. - **Last verified:** 2026-08-19 From 863084fcd0df0675e944d827d46feee096f1b606 Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 13:48:39 -0600 Subject: [PATCH 07/16] feat(fastly-reference-architectures): add multi-service architecture examples Co-Authored-By: Claude Sonnet 5 --- .../references/multi-service-architectures.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 skills/fastly-reference-architectures/references/multi-service-architectures.md diff --git a/skills/fastly-reference-architectures/references/multi-service-architectures.md b/skills/fastly-reference-architectures/references/multi-service-architectures.md new file mode 100644 index 0000000..7d80dae --- /dev/null +++ b/skills/fastly-reference-architectures/references/multi-service-architectures.md @@ -0,0 +1,22 @@ +# Multi-service reference architectures + +## fastly-serverless-cms — Compute + KV Store + Object Store +- **Repo:** github.com/chrisbuckley/fastly-serverless-cms +- **Source:** community (chrisbuckley) +- **Demonstrates:** a full CMS (reader-facing blog, admin editor, image uploads, RSS, sitemaps, cache management) built from Compute + KV Store + Object Store with zero origin infrastructure. +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 + +## fastly-serverless-checkers — Compute + Fanout + KV Store +- **Repo:** github.com/chrisbuckley/fastly-serverless-checkers +- **Source:** community (chrisbuckley) +- **Demonstrates:** real-time multiplayer game state (Fanout for push, KV Store for persistence) with no backend servers. +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 + +## infiniteboard — Compute + Fanout + KV Store + Object Storage +- **Repo:** github.com/anaramirezmorones/infiniteboard +- **Source:** community (anaramirezmorones) +- **Demonstrates:** real-time multi-user collaboration (Fanout), state persistence (KV Store), and asset storage (Object Storage) combined in one application — the widest product combination found in this research pass. +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 From a43ba5fb4845805d07ee07ae229044a5bd593657 Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 13:56:55 -0600 Subject: [PATCH 08/16] fix(fastly-reference-architectures): name Compute explicitly in checkers entry The fastly-serverless-checkers entry's Demonstrates field now explicitly names all three products (Compute, Fanout, KV Store) instead of implying Compute through "no backend servers." Co-Authored-By: Claude Sonnet 5 --- .../references/multi-service-architectures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/fastly-reference-architectures/references/multi-service-architectures.md b/skills/fastly-reference-architectures/references/multi-service-architectures.md index 7d80dae..da24c52 100644 --- a/skills/fastly-reference-architectures/references/multi-service-architectures.md +++ b/skills/fastly-reference-architectures/references/multi-service-architectures.md @@ -10,7 +10,7 @@ ## fastly-serverless-checkers — Compute + Fanout + KV Store - **Repo:** github.com/chrisbuckley/fastly-serverless-checkers - **Source:** community (chrisbuckley) -- **Demonstrates:** real-time multiplayer game state (Fanout for push, KV Store for persistence) with no backend servers. +- **Demonstrates:** real-time multiplayer game logic running in Compute, with Fanout for push updates and KV Store for persistence — all three products, no backend servers. - **Watch out for:** none known as of last verification. - **Last verified:** 2026-08-19 From 415db36a0c486152d51e92e984bb1335252be48b Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 14:01:35 -0600 Subject: [PATCH 09/16] feat(fastly-reference-architectures): add observability and ops examples --- .../references/observability-and-ops.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 skills/fastly-reference-architectures/references/observability-and-ops.md diff --git a/skills/fastly-reference-architectures/references/observability-and-ops.md b/skills/fastly-reference-architectures/references/observability-and-ops.md new file mode 100644 index 0000000..2609ba7 --- /dev/null +++ b/skills/fastly-reference-architectures/references/observability-and-ops.md @@ -0,0 +1,15 @@ +# Observability and ops reference architectures + +## fastly-log-analytics — log streaming + Object Storage dashboard +- **Repo:** github.com/fastly/fastly-log-analytics +- **Source:** official (fastly org) +- **Demonstrates:** a self-hosted request-level log analytics dashboard, explicitly positioned as the complement to Fastly's aggregate stats APIs (the `fastly-stats` skill covers those APIs; this is a system built on top of the logs they stream). +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 + +## fos-migrator — bulk content migration into Object Storage +- **Repo:** github.com/benjaminshaver/fos-migrator +- **Source:** community (benjaminshaver) +- **Demonstrates:** an operational tool/pattern for bulk-loading existing content into Object Storage — an ops task rather than a request-serving pattern, which is why it belongs in this file rather than compute-application-patterns. +- **Watch out for:** none known as of last verification. +- **Last verified:** 2026-08-19 From 9920906fc6d0bffd8cc6f74a571d73edc7908f23 Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 14:08:19 -0600 Subject: [PATCH 10/16] docs: list fastly-reference-architectures in available skills --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 58b693c..c7592ca 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ It is a skills-only package, so it does not include an `mcp.json` configuration. - `fastly-cli`: Using the Fastly CLI to manage services, compute apps, logging, WAF, TLS, key-value stores, and stats. - `fastly-fiddle`: Testing VCL against real Fastly edge infrastructure with Fastly Fiddle, covering assertion-based tests, the Fiddle HTTP API, shareable bug reproductions, and CI integration. - `fastly-stats`: Fastly traffic numbers via the CLI or raw HTTP, covering the Historical Stats, Real-Time analytics, and Origin/Domain Inspector APIs, and owning the unit, window, and aggregation conventions that decide whether a reported figure is right. +- `fastly-reference-architectures`: Curated, Fastly-endorsed GitHub repositories demonstrating working reference architectures on Fastly, from single Compute applications to systems combining multiple Fastly products. - `falco`: VCL development with Falco, covering linting, testing, simulation, formatting, REPL, and Terraform integration. - `fastlike`: Running Fastly Compute locally with Fastlike (Go-based), covering backend configuration, builds, and testing. - `viceroy`: Running Fastly Compute locally with Viceroy (WASM-based), covering serving, configuration, testing, and SDK adaptation. From c7bd91489555e5c1df36e468f7fd7698b57bdd5f Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 14:27:10 -0600 Subject: [PATCH 11/16] fix(fastly-reference-architectures): resolve validation findings - Add fastly-ngwaf to SKILL.md's "Not this skill" list, which omitted it - Remove stray blank lines after entry headings in caching-and-delivery.md so all five reference files use consistent formatting --- skills/fastly-reference-architectures/SKILL.md | 4 ++-- .../references/caching-and-delivery.md | 2 -- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/skills/fastly-reference-architectures/SKILL.md b/skills/fastly-reference-architectures/SKILL.md index a8011ac..0c1eddf 100644 --- a/skills/fastly-reference-architectures/SKILL.md +++ b/skills/fastly-reference-architectures/SKILL.md @@ -53,5 +53,5 @@ excellent entries — quality and a low re-review burden over exhaustive coverag ## Not this skill How a specific Fastly tool, CLI, or API works: see `fastly`, `fastly-cli`, -`fastly-stats`, `falco`, `fastlike`, `viceroy`, `xvcl`, `fastly-fiddle`. This skill shows -assembled, working systems, not primitives. +`fastly-stats`, `falco`, `fastlike`, `fastly-ngwaf`, `viceroy`, `xvcl`, `fastly-fiddle`. +This skill shows assembled, working systems, not primitives. diff --git a/skills/fastly-reference-architectures/references/caching-and-delivery.md b/skills/fastly-reference-architectures/references/caching-and-delivery.md index ec5ec74..4b3f25d 100644 --- a/skills/fastly-reference-architectures/references/caching-and-delivery.md +++ b/skills/fastly-reference-architectures/references/caching-and-delivery.md @@ -1,7 +1,6 @@ # Caching and delivery reference architectures ## vcl_shielding — custom origin shielding topology - - **Repo:** github.com/bharwani/vcl_shielding - **Source:** community (bharwani) - **Demonstrates:** shielding topology decisions driven by network peering/IX considerations, not just Fastly's default shield selection. @@ -9,7 +8,6 @@ - **Last verified:** 2026-08-19 ## fastly-bulk-redirects — bulk redirect / delivery routing - - **Repo:** github.com/Fcuervo21/fastly-bulk-redirects - **Source:** community (Fcuervo21) - **Demonstrates:** managing a large redirect table as a delivery/routing concern at the edge, rather than one-off VCL redirect rules. From 3deda16699ecf56bab3a30c670b541b70b7dfecc Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 17:57:39 -0600 Subject: [PATCH 12/16] =?UTF-8?q?fix(fastly-reference-architectures):=20ad?= =?UTF-8?q?dress=20final=20review=20findings=20=E2=80=94=20accuracy,=20cov?= =?UTF-8?q?erage=20claims,=20naming=20consistency?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 5 --- README.md | 2 +- .../fastly-reference-architectures/SKILL.md | 19 +++++++++++++------ .../references/caching-and-delivery.md | 4 ++-- .../compute-application-patterns.md | 10 +++++----- .../references/edge-auth-and-security.md | 8 ++++---- .../references/multi-service-architectures.md | 6 +++--- 6 files changed, 28 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index c7592ca..23f37dc 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ It is a skills-only package, so it does not include an `mcp.json` configuration. - `fastly-cli`: Using the Fastly CLI to manage services, compute apps, logging, WAF, TLS, key-value stores, and stats. - `fastly-fiddle`: Testing VCL against real Fastly edge infrastructure with Fastly Fiddle, covering assertion-based tests, the Fiddle HTTP API, shareable bug reproductions, and CI integration. - `fastly-stats`: Fastly traffic numbers via the CLI or raw HTTP, covering the Historical Stats, Real-Time analytics, and Origin/Domain Inspector APIs, and owning the unit, window, and aggregation conventions that decide whether a reported figure is right. -- `fastly-reference-architectures`: Curated, Fastly-endorsed GitHub repositories demonstrating working reference architectures on Fastly, from single Compute applications to systems combining multiple Fastly products. +- `fastly-reference-architectures`: Curated GitHub repositories, Fastly-official or individually vouched for, demonstrating working reference architectures on Fastly, from single Compute applications to systems combining multiple Fastly products. - `falco`: VCL development with Falco, covering linting, testing, simulation, formatting, REPL, and Terraform integration. - `fastlike`: Running Fastly Compute locally with Fastlike (Go-based), covering backend configuration, builds, and testing. - `viceroy`: Running Fastly Compute locally with Viceroy (WASM-based), covering serving, configuration, testing, and SDK adaptation. diff --git a/skills/fastly-reference-architectures/SKILL.md b/skills/fastly-reference-architectures/SKILL.md index 0c1eddf..3027032 100644 --- a/skills/fastly-reference-architectures/SKILL.md +++ b/skills/fastly-reference-architectures/SKILL.md @@ -1,6 +1,6 @@ --- name: fastly-reference-architectures -description: "Curated, Fastly-endorsed GitHub repositories that demonstrate working reference architectures on the Fastly platform, from a single Compute application up through systems combining multiple Fastly products (Compute, WAF/NGWAF, KV store, real-time logging, shielding). Use when designing a new solution on Fastly and a worked example of the target pattern would help, or when implementing and a concrete assembled reference would clarify the shape of the code. Not for documentation of how a specific Fastly tool or API works on its own — see the tool-specific skills for that." +description: "Curated GitHub repositories — Fastly-official or individually vouched for by a named reviewer — that demonstrate working reference architectures on the Fastly platform, from a single Compute application up through systems combining multiple Fastly products (Compute, Fanout, KV Store, Object Storage, real-time logging). Use when designing a new solution on Fastly and a worked example of the target pattern would help, or when implementing and a concrete assembled reference would clarify the shape of the code. Not for documentation of how a specific Fastly tool or API works on its own — see the tool-specific skills for that." --- # Fastly reference architectures @@ -23,11 +23,11 @@ comment or issue) rather than editing the entry yourself. | You're looking for a pattern for... | File | | --- | --- | -| Authentication, authorization, or security combos (WAF/NGWAF + Compute + rate limiting) | [references/edge-auth-and-security.md](references/edge-auth-and-security.md) | -| Cache-key design, shielding, purge strategies | [references/caching-and-delivery.md](references/caching-and-delivery.md) | -| A single Compute application (KV-backed apps, image/video processing, A/B testing at the edge) | [references/compute-application-patterns.md](references/compute-application-patterns.md) | +| Authentication, access control, or ML-based security classification at the edge | [references/edge-auth-and-security.md](references/edge-auth-and-security.md) | +| Origin shielding topology and redirect/routing tables at the edge | [references/caching-and-delivery.md](references/caching-and-delivery.md) | +| A single Compute application (A/B testing, protocol gateways, real-time fan-out, MCP servers) | [references/compute-application-patterns.md](references/compute-application-patterns.md) | | A system combining 3+ Fastly products into one architecture | [references/multi-service-architectures.md](references/multi-service-architectures.md) | -| Logging pipelines, real-time stats dashboards, alerting | [references/observability-and-ops.md](references/observability-and-ops.md) | +| Log-streaming analytics dashboards and bulk content operations against Object Storage | [references/observability-and-ops.md](references/observability-and-ops.md) | ## Entry format @@ -50,8 +50,15 @@ either the repo is from an official Fastly org, or a named person is willing to their judgment to it via the `Source` field. Keep each file to a handful of genuinely excellent entries — quality and a low re-review burden over exhaustive coverage. +The initial set of `community` entries came from an internal Fastly Solutions +Engineering recommendation list; in every case the `Source` field names the repo's own +author, not an independent third-party reviewer. Treat that as a starting point, not the +bar going forward — a new entry ideally carries a reviewer distinct from the repo's +author, and any existing entry can be re-vetted or removed through the same PR process +as everything else here. + ## Not this skill How a specific Fastly tool, CLI, or API works: see `fastly`, `fastly-cli`, -`fastly-stats`, `falco`, `fastlike`, `fastly-ngwaf`, `viceroy`, `xvcl`, `fastly-fiddle`. +`fastly-stats`, `fastly-ngwaf`, `falco`, `fastlike`, `viceroy`, `xvcl`, `fastly-fiddle`. This skill shows assembled, working systems, not primitives. diff --git a/skills/fastly-reference-architectures/references/caching-and-delivery.md b/skills/fastly-reference-architectures/references/caching-and-delivery.md index 4b3f25d..f81cf09 100644 --- a/skills/fastly-reference-architectures/references/caching-and-delivery.md +++ b/skills/fastly-reference-architectures/references/caching-and-delivery.md @@ -10,6 +10,6 @@ ## fastly-bulk-redirects — bulk redirect / delivery routing - **Repo:** github.com/Fcuervo21/fastly-bulk-redirects - **Source:** community (Fcuervo21) -- **Demonstrates:** managing a large redirect table as a delivery/routing concern at the edge, rather than one-off VCL redirect rules. -- **Watch out for:** none known as of last verification; thin description, so skim the README on re-verification to confirm the redirect-loading mechanism it uses. +- **Demonstrates:** storing a large source-to-destination redirect table in Config Store and serving lookups from a Compute edge worker, instead of an origin-side `map` block, app middleware, or per-redirect VCL rules. +- **Watch out for:** none known as of last verification. - **Last verified:** 2026-08-19 diff --git a/skills/fastly-reference-architectures/references/compute-application-patterns.md b/skills/fastly-reference-architectures/references/compute-application-patterns.md index ad71f3c..cd8534b 100644 --- a/skills/fastly-reference-architectures/references/compute-application-patterns.md +++ b/skills/fastly-reference-architectures/references/compute-application-patterns.md @@ -3,8 +3,8 @@ ## fastly-edge-ab-testing — A/B testing at the edge - **Repo:** github.com/Fcuervo21/fastly-edge-ab-testing - **Source:** community (Fcuervo21) -- **Demonstrates:** variant assignment and routing for A/B tests done in Compute, not in application code behind the origin. -- **Watch out for:** none known as of last verification; thin description — skim the README on re-verification for the bucketing mechanism used. +- **Demonstrates:** cookie-based bucket allocation and full response synthesis for A/B tests done entirely in Compute, not in application code behind the origin. +- **Watch out for:** none known as of last verification. - **Last verified:** 2026-08-19 ## compute-mcp-demo — protocol gateway pattern @@ -21,9 +21,9 @@ - **Watch out for:** none known as of last verification. - **Last verified:** 2026-08-19 -## edge-mcp — official reference implementation, explicitly unmaintained +## edge-mcp — stateless MCP server in Rust Compute - **Repo:** github.com/fastly/edge-mcp - **Source:** official (fastly org) -- **Demonstrates:** implementing the stateless MCP protocol revision as a Rust Compute application, from Fastly's own devrel org. -- **Watch out for:** The README states explicitly this is a 'point-in-time example' built against the MCP 2026-07-28 specification and 'will not be maintained beyond the initial implementation' — expect no updates, bug fixes, or security patches. Check the current MCP spec version before modeling new code on it. +- **Demonstrates:** implementing the stateless MCP protocol revision as a Rust Compute application. +- **Watch out for:** The README states explicitly this is a "point-in-time example" built against the MCP 2026-07-28 specification and "will not be maintained beyond the initial implementation" — expect no updates, bug fixes, or security patches. Check the current MCP spec version before modeling new code on it. - **Last verified:** 2026-08-19 diff --git a/skills/fastly-reference-architectures/references/edge-auth-and-security.md b/skills/fastly-reference-architectures/references/edge-auth-and-security.md index 0be6bcc..4969a01 100644 --- a/skills/fastly-reference-architectures/references/edge-auth-and-security.md +++ b/skills/fastly-reference-architectures/references/edge-auth-and-security.md @@ -3,8 +3,8 @@ ## google-apple-github-auth — OAuth via Compute - **Repo:** github.com/bharwani/google-apple-github-auth - **Source:** community (bharwani) -- **Demonstrates:** OAuth/social-login authentication implemented at the edge in Compute — the JWT/edge-auth pattern this file exists for. -- **Watch out for:** none known as of last verification (thin README beyond the description; verify the OAuth flow still matches current provider requirements before modeling new code closely after it). +- **Demonstrates:** verifying two distinct federated-login flows (OIDC JWT for Google/Apple, OAuth2 for GitHub) entirely in Compute, with no origin server. +- **Watch out for:** verify the OAuth/OIDC flows still match current provider requirements before modeling new code closely after it — identity-provider integration details shift over time. - **Last verified:** 2026-08-19 ## fastly-compute-news-with-content-paywall — access control / paywall at the edge @@ -14,9 +14,9 @@ - **Watch out for:** none known as of last verification. - **Last verified:** 2026-08-19 -## injection-classifier-poc — ML-based security classifier at the edge +## injection-classifier-poc — ML-based prompt-injection classifier at the edge - **Repo:** github.com/fastly/injection-classifier-poc - **Source:** official (fastly org) -- **Demonstrates:** running a quantized ML model for security classification directly in a Compute WASM service — a distinct pattern from rule-based WAF/NGWAF. +- **Demonstrates:** running a quantized ML model for prompt-injection classification (SAFE vs. INJECTION on LLM-bound text) directly in a Compute WASM service — a distinct pattern from rule-based WAF/NGWAF, and distinct from request-level attack detection (SQLi/XSS). - **Watch out for:** explicitly a "proof of concept," not a maintained product — check the linked model card/HuggingFace model is still the recommended one before reuse. - **Last verified:** 2026-08-19 diff --git a/skills/fastly-reference-architectures/references/multi-service-architectures.md b/skills/fastly-reference-architectures/references/multi-service-architectures.md index da24c52..36a7ab4 100644 --- a/skills/fastly-reference-architectures/references/multi-service-architectures.md +++ b/skills/fastly-reference-architectures/references/multi-service-architectures.md @@ -1,9 +1,9 @@ # Multi-service reference architectures -## fastly-serverless-cms — Compute + KV Store + Object Store +## fastly-serverless-cms — Compute + KV Store + Object Storage - **Repo:** github.com/chrisbuckley/fastly-serverless-cms - **Source:** community (chrisbuckley) -- **Demonstrates:** a full CMS (reader-facing blog, admin editor, image uploads, RSS, sitemaps, cache management) built from Compute + KV Store + Object Store with zero origin infrastructure. +- **Demonstrates:** a full CMS (reader-facing blog, admin editor, image uploads, RSS, sitemaps, cache management) built from Compute + KV Store + Object Storage with zero origin infrastructure. - **Watch out for:** none known as of last verification. - **Last verified:** 2026-08-19 @@ -17,6 +17,6 @@ ## infiniteboard — Compute + Fanout + KV Store + Object Storage - **Repo:** github.com/anaramirezmorones/infiniteboard - **Source:** community (anaramirezmorones) -- **Demonstrates:** real-time multi-user collaboration (Fanout), state persistence (KV Store), and asset storage (Object Storage) combined in one application — the widest product combination found in this research pass. +- **Demonstrates:** whiteboard logic running in Compute, with Fanout for real-time multi-user collaboration, KV Store for state persistence, and Object Storage for assets — four products in one application, the widest combination found in this research pass. - **Watch out for:** none known as of last verification. - **Last verified:** 2026-08-19 From 8dcbb17d7fd455565227461a23904dd0d1a91045 Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Wed, 19 Aug 2026 22:17:46 -0600 Subject: [PATCH 13/16] gitignore: exclude docs/superpowers/ from commit scope Keeps brainstorming specs and implementation plans as local scratch artifacts rather than tracked repo content. Co-Authored-By: Claude Sonnet 5 --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 0ed49fe..34b31b0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ *~ .swival/ tmp/ +docs/superpowers/ From 1e9e57a7c0808115ee0608cf5f7bab9525ebf400 Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Thu, 20 Aug 2026 13:02:49 -0600 Subject: [PATCH 14/16] fastly-reference-architectures: collapse to a single example table, move liveness check to CI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review feedback from jedisct1: skills are machine instructions, not human docs, so drop the prose and the 5-field-per-entry schema in favor of one compact table (project/description/platform) linked from SKILL.md. Also drop the agent-side "check the repo isn't archived before recommending it" instruction — that cost belongs in CI, not on every recommendation, so a new check-example-repos job now verifies each linked repo is live and unarchived on every push/PR. Co-Authored-By: Claude Sonnet 5 --- .github/workflows/skillscheck.yml | 30 ++++++++++ README.md | 2 +- .../fastly-reference-architectures/SKILL.md | 60 +------------------ .../references/caching-and-delivery.md | 15 ----- .../compute-application-patterns.md | 29 --------- .../references/edge-auth-and-security.md | 22 ------- .../references/examples.md | 18 ++++++ .../references/multi-service-architectures.md | 22 ------- .../references/observability-and-ops.md | 15 ----- 9 files changed, 52 insertions(+), 161 deletions(-) delete mode 100644 skills/fastly-reference-architectures/references/caching-and-delivery.md delete mode 100644 skills/fastly-reference-architectures/references/compute-application-patterns.md delete mode 100644 skills/fastly-reference-architectures/references/edge-auth-and-security.md create mode 100644 skills/fastly-reference-architectures/references/examples.md delete mode 100644 skills/fastly-reference-architectures/references/multi-service-architectures.md delete mode 100644 skills/fastly-reference-architectures/references/observability-and-ops.md diff --git a/.github/workflows/skillscheck.yml b/.github/workflows/skillscheck.yml index d9844ee..9f1e0ad 100644 --- a/.github/workflows/skillscheck.yml +++ b/.github/workflows/skillscheck.yml @@ -15,3 +15,33 @@ jobs: - uses: astral-sh/setup-uv@v7 - run: uvx skillscheck@0.9.5 --strict . + + check-example-repos: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - name: Verify every linked example repo is live and not archived + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -euo pipefail + errors=0 + repos=$(grep -oE '\]\(https://github\.com/[^)]+\)' skills/fastly-reference-architectures/references/examples.md \ + | sed -E 's#\]\(https://github\.com/([^)]+)\)#\1#') + for repo in $repos; do + echo "Checking $repo..." + if ! info=$(gh api "repos/$repo" 2>&1); then + echo "::error::$repo is unreachable (removed, renamed, or private)" + errors=$((errors + 1)) + continue + fi + if [[ "$(echo "$info" | jq -r '.archived')" == "true" ]]; then + echo "::error::$repo is archived" + errors=$((errors + 1)) + fi + done + if [[ $errors -gt 0 ]]; then + echo "Error: $errors example repo(s) failed the liveness check" >&2 + exit 1 + fi diff --git a/README.md b/README.md index 23f37dc..b169bcf 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ It is a skills-only package, so it does not include an `mcp.json` configuration. - `fastly-cli`: Using the Fastly CLI to manage services, compute apps, logging, WAF, TLS, key-value stores, and stats. - `fastly-fiddle`: Testing VCL against real Fastly edge infrastructure with Fastly Fiddle, covering assertion-based tests, the Fiddle HTTP API, shareable bug reproductions, and CI integration. - `fastly-stats`: Fastly traffic numbers via the CLI or raw HTTP, covering the Historical Stats, Real-Time analytics, and Origin/Domain Inspector APIs, and owning the unit, window, and aggregation conventions that decide whether a reported figure is right. -- `fastly-reference-architectures`: Curated GitHub repositories, Fastly-official or individually vouched for, demonstrating working reference architectures on Fastly, from single Compute applications to systems combining multiple Fastly products. +- `fastly-reference-architectures`: Curated GitHub repositories demonstrating working reference architectures on Fastly, from single Compute applications to systems combining multiple Fastly products. - `falco`: VCL development with Falco, covering linting, testing, simulation, formatting, REPL, and Terraform integration. - `fastlike`: Running Fastly Compute locally with Fastlike (Go-based), covering backend configuration, builds, and testing. - `viceroy`: Running Fastly Compute locally with Viceroy (WASM-based), covering serving, configuration, testing, and SDK adaptation. diff --git a/skills/fastly-reference-architectures/SKILL.md b/skills/fastly-reference-architectures/SKILL.md index 3027032..59caf8d 100644 --- a/skills/fastly-reference-architectures/SKILL.md +++ b/skills/fastly-reference-architectures/SKILL.md @@ -1,64 +1,10 @@ --- name: fastly-reference-architectures -description: "Curated GitHub repositories — Fastly-official or individually vouched for by a named reviewer — that demonstrate working reference architectures on the Fastly platform, from a single Compute application up through systems combining multiple Fastly products (Compute, Fanout, KV Store, Object Storage, real-time logging). Use when designing a new solution on Fastly and a worked example of the target pattern would help, or when implementing and a concrete assembled reference would clarify the shape of the code. Not for documentation of how a specific Fastly tool or API works on its own — see the tool-specific skills for that." +description: "Curated GitHub repositories demonstrating working reference architectures on the Fastly platform, from single Compute applications to systems combining multiple Fastly products. Use when designing a new solution on Fastly and a worked example of the target pattern would help, or when implementing and a concrete assembled reference would clarify the shape of the code. Not for documentation of how a specific Fastly tool or API works on its own — see the tool-specific skills for that." --- # Fastly reference architectures -This skill points to a small number of GitHub repositories that Fastly, or a named and -accountable reviewer, endorses as good reference examples for building on the Fastly -platform. It is not primitive-level API or CLI documentation — see the tool-specific -skills for that — it is examples of assembled, working systems worth modeling a new -design after. +Example projects running on Fastly (git repositories): [references/examples.md](references/examples.md) -## Before recommending any entry - -Verify the repo is not archived and has commit activity roughly consistent with "still -maintained" — e.g. `gh repo view / --json isArchived,pushedAt` (or the GitHub -web UI if `gh` isn't available). If a repo is archived or long-dormant, say so explicitly -rather than presenting it as current, and flag it to this skill's maintainers (a PR -comment or issue) rather than editing the entry yourself. - -## Pick the reference file - -| You're looking for a pattern for... | File | -| --- | --- | -| Authentication, access control, or ML-based security classification at the edge | [references/edge-auth-and-security.md](references/edge-auth-and-security.md) | -| Origin shielding topology and redirect/routing tables at the edge | [references/caching-and-delivery.md](references/caching-and-delivery.md) | -| A single Compute application (A/B testing, protocol gateways, real-time fan-out, MCP servers) | [references/compute-application-patterns.md](references/compute-application-patterns.md) | -| A system combining 3+ Fastly products into one architecture | [references/multi-service-architectures.md](references/multi-service-architectures.md) | -| Log-streaming analytics dashboards and bulk content operations against Object Storage | [references/observability-and-ops.md](references/observability-and-ops.md) | - -## Entry format - -Every entry in every reference file uses this schema: - -```markdown -## — -- **Repo:** github.com/org/repo -- **Source:** official (fastly org / fastly-devrel) | community (name who vetted it) -- **Demonstrates:** the specific pattern worth copying, not just "a Compute app" -- **Watch out for:** known gaps, outdated dependencies, or divergence from current best - practice — "none known as of last verification" if genuinely none -- **Last verified:** YYYY-MM-DD -``` - -## Adding or removing an entry - -Same process as every other change in this repo: open a PR. The bar for inclusion is -either the repo is from an official Fastly org, or a named person is willing to attach -their judgment to it via the `Source` field. Keep each file to a handful of genuinely -excellent entries — quality and a low re-review burden over exhaustive coverage. - -The initial set of `community` entries came from an internal Fastly Solutions -Engineering recommendation list; in every case the `Source` field names the repo's own -author, not an independent third-party reviewer. Treat that as a starting point, not the -bar going forward — a new entry ideally carries a reviewer distinct from the repo's -author, and any existing entry can be re-vetted or removed through the same PR process -as everything else here. - -## Not this skill - -How a specific Fastly tool, CLI, or API works: see `fastly`, `fastly-cli`, -`fastly-stats`, `fastly-ngwaf`, `falco`, `fastlike`, `viceroy`, `xvcl`, `fastly-fiddle`. -This skill shows assembled, working systems, not primitives. +Add or remove entries via PR. CI checks that every linked repo is still live and not archived. diff --git a/skills/fastly-reference-architectures/references/caching-and-delivery.md b/skills/fastly-reference-architectures/references/caching-and-delivery.md deleted file mode 100644 index f81cf09..0000000 --- a/skills/fastly-reference-architectures/references/caching-and-delivery.md +++ /dev/null @@ -1,15 +0,0 @@ -# Caching and delivery reference architectures - -## vcl_shielding — custom origin shielding topology -- **Repo:** github.com/bharwani/vcl_shielding -- **Source:** community (bharwani) -- **Demonstrates:** shielding topology decisions driven by network peering/IX considerations, not just Fastly's default shield selection. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 - -## fastly-bulk-redirects — bulk redirect / delivery routing -- **Repo:** github.com/Fcuervo21/fastly-bulk-redirects -- **Source:** community (Fcuervo21) -- **Demonstrates:** storing a large source-to-destination redirect table in Config Store and serving lookups from a Compute edge worker, instead of an origin-side `map` block, app middleware, or per-redirect VCL rules. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 diff --git a/skills/fastly-reference-architectures/references/compute-application-patterns.md b/skills/fastly-reference-architectures/references/compute-application-patterns.md deleted file mode 100644 index cd8534b..0000000 --- a/skills/fastly-reference-architectures/references/compute-application-patterns.md +++ /dev/null @@ -1,29 +0,0 @@ -# Compute application pattern reference architectures - -## fastly-edge-ab-testing — A/B testing at the edge -- **Repo:** github.com/Fcuervo21/fastly-edge-ab-testing -- **Source:** community (Fcuervo21) -- **Demonstrates:** cookie-based bucket allocation and full response synthesis for A/B tests done entirely in Compute, not in application code behind the origin. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 - -## compute-mcp-demo — protocol gateway pattern -- **Repo:** github.com/bharwani/compute-mcp-demo -- **Source:** community (bharwani) -- **Demonstrates:** wrapping a third-party HTTP API as an MCP server entirely in Compute, using edge caching to cut per-call latency roughly 15x. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 - -## fastly-examples-live-betting-fanout — real-time fan-out at scale -- **Repo:** github.com/dmichael-fastly/fastly-examples-live-betting-fanout -- **Source:** community (dmichael-fastly) -- **Demonstrates:** using Fastly Fanout to broadcast frequently-updated data to a large concurrent audience without a fan-out multiplier hitting origin. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 - -## edge-mcp — stateless MCP server in Rust Compute -- **Repo:** github.com/fastly/edge-mcp -- **Source:** official (fastly org) -- **Demonstrates:** implementing the stateless MCP protocol revision as a Rust Compute application. -- **Watch out for:** The README states explicitly this is a "point-in-time example" built against the MCP 2026-07-28 specification and "will not be maintained beyond the initial implementation" — expect no updates, bug fixes, or security patches. Check the current MCP spec version before modeling new code on it. -- **Last verified:** 2026-08-19 diff --git a/skills/fastly-reference-architectures/references/edge-auth-and-security.md b/skills/fastly-reference-architectures/references/edge-auth-and-security.md deleted file mode 100644 index 4969a01..0000000 --- a/skills/fastly-reference-architectures/references/edge-auth-and-security.md +++ /dev/null @@ -1,22 +0,0 @@ -# Edge auth and security reference architectures - -## google-apple-github-auth — OAuth via Compute -- **Repo:** github.com/bharwani/google-apple-github-auth -- **Source:** community (bharwani) -- **Demonstrates:** verifying two distinct federated-login flows (OIDC JWT for Google/Apple, OAuth2 for GitHub) entirely in Compute, with no origin server. -- **Watch out for:** verify the OAuth/OIDC flows still match current provider requirements before modeling new code closely after it — identity-provider integration details shift over time. -- **Last verified:** 2026-08-19 - -## fastly-compute-news-with-content-paywall — access control / paywall at the edge -- **Repo:** github.com/saschanowak/fastly-compute-news-with-content-paywall -- **Source:** community (saschanowak) -- **Demonstrates:** authorization/paywall gating of content at the edge — an access-control pattern distinct from authentication. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 - -## injection-classifier-poc — ML-based prompt-injection classifier at the edge -- **Repo:** github.com/fastly/injection-classifier-poc -- **Source:** official (fastly org) -- **Demonstrates:** running a quantized ML model for prompt-injection classification (SAFE vs. INJECTION on LLM-bound text) directly in a Compute WASM service — a distinct pattern from rule-based WAF/NGWAF, and distinct from request-level attack detection (SQLi/XSS). -- **Watch out for:** explicitly a "proof of concept," not a maintained product — check the linked model card/HuggingFace model is still the recommended one before reuse. -- **Last verified:** 2026-08-19 diff --git a/skills/fastly-reference-architectures/references/examples.md b/skills/fastly-reference-architectures/references/examples.md new file mode 100644 index 0000000..fb328ac --- /dev/null +++ b/skills/fastly-reference-architectures/references/examples.md @@ -0,0 +1,18 @@ +# Example projects running on Fastly + +| Project | Description | Platform | +| --- | --- | --- | +| [google-apple-github-auth](https://github.com/bharwani/google-apple-github-auth) | Social login via Google/Apple (OIDC) and GitHub (OAuth2), verified entirely at the edge | Compute | +| [fastly-compute-news-with-content-paywall](https://github.com/saschanowak/fastly-compute-news-with-content-paywall) | Paywall / access-control gating for content | Compute | +| [injection-classifier-poc](https://github.com/fastly/injection-classifier-poc) | Prompt-injection ML classifier (proof of concept, not maintained) | Compute | +| [vcl_shielding](https://github.com/bharwani/vcl_shielding) | Custom origin shielding topology via peering/IX | VCL | +| [fastly-bulk-redirects](https://github.com/Fcuervo21/fastly-bulk-redirects) | Bulk redirect table in Config Store, served by an edge worker | Compute | +| [fastly-edge-ab-testing](https://github.com/Fcuervo21/fastly-edge-ab-testing) | Cookie-based A/B test bucket allocation | Compute | +| [compute-mcp-demo](https://github.com/bharwani/compute-mcp-demo) | Turns a Shopify store into an MCP server, edge-cached | Compute | +| [fastly-examples-live-betting-fanout](https://github.com/dmichael-fastly/fastly-examples-live-betting-fanout) | Real-time score/odds fan-out to many concurrent clients | Compute, Fanout | +| [edge-mcp](https://github.com/fastly/edge-mcp) | Stateless MCP protocol server (point-in-time example, unmaintained) | Compute | +| [fastly-serverless-cms](https://github.com/chrisbuckley/fastly-serverless-cms) | Full CMS with no origin servers | Compute, KV Store, Object Storage | +| [fastly-serverless-checkers](https://github.com/chrisbuckley/fastly-serverless-checkers) | Real-time multiplayer checkers, no backend servers | Compute, Fanout, KV Store | +| [infiniteboard](https://github.com/anaramirezmorones/infiniteboard) | Collaborative infinite whiteboard | Compute, Fanout, KV Store, Object Storage | +| [fastly-log-analytics](https://github.com/fastly/fastly-log-analytics) | Request-level log analytics dashboard | Compute, Object Storage | +| [fos-migrator](https://github.com/benjaminshaver/fos-migrator) | Bulk content migration into Object Storage | Compute, Object Storage | diff --git a/skills/fastly-reference-architectures/references/multi-service-architectures.md b/skills/fastly-reference-architectures/references/multi-service-architectures.md deleted file mode 100644 index 36a7ab4..0000000 --- a/skills/fastly-reference-architectures/references/multi-service-architectures.md +++ /dev/null @@ -1,22 +0,0 @@ -# Multi-service reference architectures - -## fastly-serverless-cms — Compute + KV Store + Object Storage -- **Repo:** github.com/chrisbuckley/fastly-serverless-cms -- **Source:** community (chrisbuckley) -- **Demonstrates:** a full CMS (reader-facing blog, admin editor, image uploads, RSS, sitemaps, cache management) built from Compute + KV Store + Object Storage with zero origin infrastructure. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 - -## fastly-serverless-checkers — Compute + Fanout + KV Store -- **Repo:** github.com/chrisbuckley/fastly-serverless-checkers -- **Source:** community (chrisbuckley) -- **Demonstrates:** real-time multiplayer game logic running in Compute, with Fanout for push updates and KV Store for persistence — all three products, no backend servers. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 - -## infiniteboard — Compute + Fanout + KV Store + Object Storage -- **Repo:** github.com/anaramirezmorones/infiniteboard -- **Source:** community (anaramirezmorones) -- **Demonstrates:** whiteboard logic running in Compute, with Fanout for real-time multi-user collaboration, KV Store for state persistence, and Object Storage for assets — four products in one application, the widest combination found in this research pass. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 diff --git a/skills/fastly-reference-architectures/references/observability-and-ops.md b/skills/fastly-reference-architectures/references/observability-and-ops.md deleted file mode 100644 index 2609ba7..0000000 --- a/skills/fastly-reference-architectures/references/observability-and-ops.md +++ /dev/null @@ -1,15 +0,0 @@ -# Observability and ops reference architectures - -## fastly-log-analytics — log streaming + Object Storage dashboard -- **Repo:** github.com/fastly/fastly-log-analytics -- **Source:** official (fastly org) -- **Demonstrates:** a self-hosted request-level log analytics dashboard, explicitly positioned as the complement to Fastly's aggregate stats APIs (the `fastly-stats` skill covers those APIs; this is a system built on top of the logs they stream). -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 - -## fos-migrator — bulk content migration into Object Storage -- **Repo:** github.com/benjaminshaver/fos-migrator -- **Source:** community (benjaminshaver) -- **Demonstrates:** an operational tool/pattern for bulk-loading existing content into Object Storage — an ops task rather than a request-serving pattern, which is why it belongs in this file rather than compute-application-patterns. -- **Watch out for:** none known as of last verification. -- **Last verified:** 2026-08-19 From 308f00695af6eb75791e621999e74e30de18d041 Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Thu, 20 Aug 2026 15:13:47 -0600 Subject: [PATCH 15/16] address review feedback: trim maintainer-facing note, split CI job, drop unrelated gitignore change MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop SKILL.md's "add/remove via PR, CI checks liveness" line — not useful to the skill's consumer, only to maintainers. - Move check-example-repos into its own workflow file; it has nothing to do with the skillscheck command skillscheck.yml is named for. - Revert the docs/superpowers/ .gitignore entry — unrelated to this skill and out of scope for this PR. Kept as a local-only exclusion in .git/info/exclude instead. Co-Authored-By: Claude Sonnet 5 --- .github/workflows/check-example-repos.yml | 38 +++++++++++++++++++ .github/workflows/skillscheck.yml | 30 --------------- .gitignore | 1 - .../fastly-reference-architectures/SKILL.md | 2 - 4 files changed, 38 insertions(+), 33 deletions(-) create mode 100644 .github/workflows/check-example-repos.yml diff --git a/.github/workflows/check-example-repos.yml b/.github/workflows/check-example-repos.yml new file mode 100644 index 0000000..fb66063 --- /dev/null +++ b/.github/workflows/check-example-repos.yml @@ -0,0 +1,38 @@ +name: Check Example Repos + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + check-example-repos: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - name: Verify every linked example repo is live and not archived + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -euo pipefail + errors=0 + repos=$(grep -oE '\]\(https://github\.com/[^)]+\)' skills/fastly-reference-architectures/references/examples.md \ + | sed -E 's#\]\(https://github\.com/([^)]+)\)#\1#') + for repo in $repos; do + echo "Checking $repo..." + if ! info=$(gh api "repos/$repo" 2>&1); then + echo "::error::$repo is unreachable (removed, renamed, or private)" + errors=$((errors + 1)) + continue + fi + if [[ "$(echo "$info" | jq -r '.archived')" == "true" ]]; then + echo "::error::$repo is archived" + errors=$((errors + 1)) + fi + done + if [[ $errors -gt 0 ]]; then + echo "Error: $errors example repo(s) failed the liveness check" >&2 + exit 1 + fi diff --git a/.github/workflows/skillscheck.yml b/.github/workflows/skillscheck.yml index 9f1e0ad..d9844ee 100644 --- a/.github/workflows/skillscheck.yml +++ b/.github/workflows/skillscheck.yml @@ -15,33 +15,3 @@ jobs: - uses: astral-sh/setup-uv@v7 - run: uvx skillscheck@0.9.5 --strict . - - check-example-repos: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - - name: Verify every linked example repo is live and not archived - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - set -euo pipefail - errors=0 - repos=$(grep -oE '\]\(https://github\.com/[^)]+\)' skills/fastly-reference-architectures/references/examples.md \ - | sed -E 's#\]\(https://github\.com/([^)]+)\)#\1#') - for repo in $repos; do - echo "Checking $repo..." - if ! info=$(gh api "repos/$repo" 2>&1); then - echo "::error::$repo is unreachable (removed, renamed, or private)" - errors=$((errors + 1)) - continue - fi - if [[ "$(echo "$info" | jq -r '.archived')" == "true" ]]; then - echo "::error::$repo is archived" - errors=$((errors + 1)) - fi - done - if [[ $errors -gt 0 ]]; then - echo "Error: $errors example repo(s) failed the liveness check" >&2 - exit 1 - fi diff --git a/.gitignore b/.gitignore index 34b31b0..0ed49fe 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ *~ .swival/ tmp/ -docs/superpowers/ diff --git a/skills/fastly-reference-architectures/SKILL.md b/skills/fastly-reference-architectures/SKILL.md index 59caf8d..3e7fa6e 100644 --- a/skills/fastly-reference-architectures/SKILL.md +++ b/skills/fastly-reference-architectures/SKILL.md @@ -6,5 +6,3 @@ description: "Curated GitHub repositories demonstrating working reference archit # Fastly reference architectures Example projects running on Fastly (git repositories): [references/examples.md](references/examples.md) - -Add or remove entries via PR. CI checks that every linked repo is still live and not archived. From b29b1b9d1111f6e8701dcc9d821d12f302d8c859 Mon Sep 17 00:00:00 2001 From: Austin Spires Date: Thu, 20 Aug 2026 15:20:00 -0600 Subject: [PATCH 16/16] examples: drop injection-classifier-poc (repo went internal-only) CI's check-example-repos job caught this: the repo's visibility changed from public to internal since it was curated, so the workflow's repo-scoped token (correctly) can't see it. Not appropriate as a public example if it's not publicly reachable. Co-Authored-By: Claude Sonnet 5 --- skills/fastly-reference-architectures/references/examples.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/fastly-reference-architectures/references/examples.md b/skills/fastly-reference-architectures/references/examples.md index fb328ac..5d80fb5 100644 --- a/skills/fastly-reference-architectures/references/examples.md +++ b/skills/fastly-reference-architectures/references/examples.md @@ -4,7 +4,6 @@ | --- | --- | --- | | [google-apple-github-auth](https://github.com/bharwani/google-apple-github-auth) | Social login via Google/Apple (OIDC) and GitHub (OAuth2), verified entirely at the edge | Compute | | [fastly-compute-news-with-content-paywall](https://github.com/saschanowak/fastly-compute-news-with-content-paywall) | Paywall / access-control gating for content | Compute | -| [injection-classifier-poc](https://github.com/fastly/injection-classifier-poc) | Prompt-injection ML classifier (proof of concept, not maintained) | Compute | | [vcl_shielding](https://github.com/bharwani/vcl_shielding) | Custom origin shielding topology via peering/IX | VCL | | [fastly-bulk-redirects](https://github.com/Fcuervo21/fastly-bulk-redirects) | Bulk redirect table in Config Store, served by an edge worker | Compute | | [fastly-edge-ab-testing](https://github.com/Fcuervo21/fastly-edge-ab-testing) | Cookie-based A/B test bucket allocation | Compute |