Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions AGENTS-OPERATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -469,16 +469,19 @@ Rules:
`GET /api/v1/auth/*/{start,callback}` bypass the gate because they're
invoked without an `Origin` header (uptime probes + top-level OAuth).

Four more surfaces are reachable without an `Origin` because they sit
Five more surfaces are reachable without an `Origin` because they sit
outside the `/api/*` gate entirely, not because of a carve-out:
`GET /feed` (site-wide recent comments, Atom or `?format=json`),
`GET /feed/:slug` (Atom), `GET /c/:id` (comment permalinks),
`GET /embed/:slug` (the iframe variant) and `GET /embed.js` (the widget
bundle). Each is meant to be fetched by readers, feed readers and
crawlers, so none of them can require one.

**Build-time fetchers get 403s.** A static-site generator that reads
comments at deploy time looks exactly like a scraper to the Worker: no
`Origin`, gated path. Consume `GET /feed/:slug` instead until the planned
`Origin`, gated path. Consume `GET /feed?format=json&site=<origin>`
(site-wide, 50 newest, `site` must be in `ALLOWED_ORIGINS`) or
`GET /feed/:slug` (one post) instead until the planned
API-keys system ships; the design is in
[`docs/api-keys-design.md`](docs/api-keys-design.md) and is **not**
implemented.
Expand All @@ -503,8 +506,8 @@ curl -i https://comments.example.com/api/v1/comments?slug=hello
```

Build-time fetchers (SSGs reading comments at deploy time) will get 403s
here — workaround is the ungated `GET /feed/:slug` Atom feed until the
API-keys system ships (`docs/api-keys-design.md`).
here — workaround is the ungated `GET /feed?format=json` (site-wide) or
`GET /feed/:slug` Atom feed until the API-keys system ships (`docs/api-keys-design.md`).

## 7. Turnstile

Expand Down
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,7 +283,9 @@ When **not** to use the lazy loader:
immediately and you've saved nothing.
- The integrator explicitly wants comments visible to crawlers in the
rendered HTML of the post page. The per-post RSS feed
(`/feed/:slug`) and per-comment permalinks (`/c/:id`) remain
(`/feed/:slug`), the site-wide `GET /feed` (add `?format=json` for JSON
Feed, `&site=<origin>` to filter; recipes in `docs/embedding.md`) and
per-comment permalinks (`/c/:id`) remain
crawler-visible either way, but the comment tree inline with the
post is only present when the script has run.

Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@ dashboard page); every other integration is optional.
nothing; closed threads stay closed and spam stays out of the public tree
- **Admin UI**: moderation queue, user management, and settings you
change without a redeploy
- **RSS feeds**, comment counts, permalinks
- **RSS feeds**, comment counts, permalinks, and a site-wide recent-comments
feed at `GET /feed` (Atom or JSON Feed) for build-time lists
- **Webhook out** on every comment event: generic, Slack, Discord, or
Telegram
- **Telegram operator bot**: moderate from your phone with inline
Expand Down
11 changes: 7 additions & 4 deletions docs/compliance/data-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,10 +84,13 @@ Not KV, and never backed up. Four users:
(`src/lib/response-cache.ts:133`), and busted per slug on write, on
moderation, and on erasure (`src/lib/moderation.ts:224-226`). Nothing here is
more exposed than the page a reader already sees.
- **Atom feeds** — the latest 50 approved comments per post, with bodies and
author display names, for 5 minutes (`src/routes/feed.ts`). Dropped with the
slug's tree pages by the same bust, so erasure and moderation clear it in
the handling colo.
- **Feeds** — the latest 50 approved comments per post (`/feed/:slug`, Atom),
and install-wide or per allowed origin (`/feed`, Atom or JSON Feed), with
bodies and author display names, for 5 minutes (`src/routes/feed.ts`). The
JSON Feed is served with `Access-Control-Allow-Origin: *`; it carries
nothing the public pages don't. Every comment mutation drops the post's feed
with its tree pages and the site-wide feeds with `bustSiteFeeds`, so erasure
and moderation clear them in the handling colo.
- **Comment permalinks** — the `/c/:id` redirect target (the post URL plus an
anchor), for 5 minutes (`src/routes/permalink.ts`). No personal data.
- **Rate-limit counters** — keyed by identity: `user:<id>` for a signed-in
Expand Down
80 changes: 80 additions & 0 deletions docs/embedding.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,86 @@ on bouncers. [`../examples/lazy-load`](../examples/lazy-load/README.md) has
two deferred-loading patterns, a scroll-into-view loader (recommended) and
a click-to-load button, with the trade-offs of each.

## Recent comments

`GET /feed` is a site-wide feed of the newest approved comments across all
posts. It complements the per-post `GET /feed/:slug`.

| URL | Returns |
|---|---|
| `https://comments.example.com/feed` | Atom (`application/atom+xml`) |
| `https://comments.example.com/feed?format=json` | JSON Feed 1.1 (`application/feed+json`, `access-control-allow-origin: *`) |

Parameters:

- `format`: `json` for JSON Feed. Any other value, or none, serves Atom.
- `site`: optional. A bare origin such as `https://blog.example.com`
(scheme and host, plus a port only when it is not the default; no trailing
slash), in the browser-serialized origin form (lowercase host). The value
and the `ALLOWED_ORIGINS` entry must both use that form. It must equal an
entry of `ALLOWED_ORIGINS`, otherwise the response is `400 invalid site`. With `site`, only comments on that site's posts
appear and every entry links. Without it (or with an empty `site=`) the feed
covers the whole install.

On a single-origin install, omit `site`. The install-wide feed is the cheap
query (about 50 index rows). A `?site=` cache miss reads all `posts` rows plus
every comment on that site's posts. The build-time recipes skip items without
a `url`, so they work without `site`.

The feed holds the 50 newest approved comments. It is cached at the edge
(`cache-control: public, max-age=300`). A comment change clears the cache in
the data center that handled it. Other locations can serve a feed up to five
minutes old. The language is the operator's default locale.

JSON shape (`?format=json&site=https://blog.example.com`):

```json
{
"version": "https://jsonfeed.org/version/1.1",
"title": "Recent comments",
"home_page_url": "https://blog.example.com",
"feed_url": "https://comments.example.com/feed?format=json&site=https%3A%2F%2Fblog.example.com",
"language": "en",
"items": [
{
"id": "tag:comments.example.com,2026-11-16:comment/01J...",
"url": "https://blog.example.com/post/#garrul-comment-01J...",
"title": "Ada commented",
"content_html": "<p>...</p>",
"date_published": "2026-11-16T12:00:00.000Z",
"date_modified": "2026-11-16T12:05:00.000Z",
"authors": [{ "name": "Ada" }],
"_garrul": {
"post_slug": "hello-world",
"post_title": "Hello world",
"post_url": "https://blog.example.com/post/"
}
}
]
}
```

`home_page_url` appears only with `site`. `date_modified` appears only for
edited comments. `_garrul.post_title` is `null` when the post has no title.

The install-wide feed can contain unlinked entries: comments on a post with no
URL, or a URL outside `ALLOWED_ORIGINS`. Such an entry has no `url` and
`_garrul.post_url` is `null`. Skip them when you render a list. A `?site=` feed
always links every entry.

`/feed` sits outside the `/api/*` Origin gate, so a build step with no `Origin`
header can fetch it (`/api/v1/*` answers those with 403). Build-time recipes
that render a list and keep the build green when Garrul is down:
[Astro](../examples/astro/README.md#recent-comments-list-build-time),
[Hugo](../examples/hugo/README.md#recent-comments-list-build-time),
[Jekyll](../examples/jekyll/README.md#recent-comments-list-build-time). The
list refreshes only when the site rebuilds; schedule a CI rebuild to keep it
current.

There is no live "recent comments" widget on purpose. Mounting one on every
page would add a Worker request per pageview and roughly halve the free-tier
capacity (see [Lazy-loading](#lazy-loading)).

## Using an AI assistant

Garrul ships an AI-targeted integration guide at
Expand Down
64 changes: 64 additions & 0 deletions examples/astro/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,70 @@ const { entry } = Astro.props;
<Comments slug={entry.slug} title={entry.data.title} published={entry.data.pubDate} />
```

## Recent comments list (build time)

Garrul serves a site-wide feed at `GET /feed`. This component shows the
newest comments on your home page or sidebar without loading the widget
there. The feed stays outside the Worker's `/api/*` Origin gate, so a build
with no `Origin` header can read it. `site` must be an origin listed in
`ALLOWED_ORIGINS`, written without a trailing slash. On a single-origin install, drop `site` from the URL: see
`docs/embedding.md` (Recent comments).

`src/components/RecentComments.astro`:

```astro
---
const feed =
"https://comments.yourdomain.com/feed?format=json&site=" +
encodeURIComponent("https://yourblog.com");

let items: any[] = [];
try {
const res = await fetch(feed, { signal: AbortSignal.timeout(10_000) });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
if (!Array.isArray(data.items)) throw new Error("no items array");
items = data.items;
} catch (err) {
console.warn(`recent comments unavailable: ${err}`);
}

const recent = items.filter((i) => i.url).slice(0, 5);
const excerpt = (html: string) =>
html
.replace(/<[^>]*>/g, " ")
.replace(/&(#39|quot|lt|gt|amp);/g, (_: string, e: string) =>
({ "#39": "'", quot: '"', lt: "<", gt: ">", amp: "&" } as Record<string, string>)[e])
.replace(/\s+/g, " ")
.trim()
.slice(0, 100);
---
{recent.length > 0 && (
<ul class="recent-comments">
{recent.map((c) => (
<li>
<a href={c.url}>{c._garrul?.post_title ?? c.title}</a>
<span>{c.authors?.[0]?.name}: {excerpt(c.content_html)}</span>
</li>
))}
</ul>
)}
```

A network error, a timeout, a non-2xx status or a body without an `items`
array logs a warning and renders no list. The build still succeeds. The text
is plain: the excerpt strips tags, then decodes the five entities Garrul's
renderer emits (`&#39;`, `&quot;`, `&lt;`, `&gt;`, `&amp;`) in one pass, so
readers see `Don't` and not `Don&#39;t`. Astro escapes the result once, so the
excerpt cannot inject markup.

Use this only on prerendered (static) pages. With `output: "server"` or an
on-demand page, the frontmatter fetch runs on every page view and adds one
Worker request per view, the cost this design avoids.

The list refreshes only when the site rebuilds. Add a scheduled CI rebuild
(for example a daily cron) to keep it current.

## Notes

- The `data-slug` is the unique identifier for the post's comment
Expand Down
72 changes: 72 additions & 0 deletions examples/hugo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,75 @@ override per-deployment via `HUGO_PARAMS_GARRULAPI`:
- For `hugo server` local dev, you can either point `garrulApi` at
`http://localhost:8787` temporarily or add the dev origin
(`http://localhost:1313`) to `ALLOWED_ORIGINS` alongside prod.

## Recent comments list (build time)

Garrul serves a site-wide feed at `GET /feed`. This recipe shows the newest
comments on your home page or sidebar without loading the widget there. It
needs **Hugo 0.141 or newer**: from that release the resource returned by
`resources.GetRemote` no longer carries an `.Err`, so errors are caught with
`try`.

The feed stays outside the Worker's `/api/*` Origin gate, so a build with no
`Origin` header can read it. `site` must be an origin listed in
`ALLOWED_ORIGINS`, written without a trailing slash. On a single-origin install, drop `site` from the URL: see
`docs/embedding.md` (Recent comments).

Set a finite remote-fetch cache lifetime in `hugo.toml`. Hugo's default for
this cache never expires, so a rebuild on a persistent cache would reuse the
old feed. Hugo's `timeout` setting limits how long the build waits (default
`60s`); lower it if you want a faster failure:

```toml
timeout = "15s"

[caches.getresource]
maxAge = "5m"
```

`layouts/partials/recent-comments.html`:

```go-html-template
{{- $url := "https://comments.example.com/feed?format=json&site=https%3A%2F%2Fblog.example.com" -}}
{{- $items := slice -}}
{{- with try (resources.GetRemote $url) -}}
{{- if .Err -}}
{{- warnf "recent comments: fetch failed: %s" .Err -}}
{{- else with .Value -}}
{{- with try (transform.Unmarshal .Content) -}}
{{- if .Err -}}
{{- warnf "recent comments: bad JSON: %s" .Err -}}
{{- else with .Value -}}
{{- if reflect.IsSlice .items -}}
{{- $items = .items -}}
{{- else -}}
{{- warnf "recent comments: no items array" -}}
{{- end -}}
{{- end -}}
{{- end -}}
{{- else -}}
{{- warnf "recent comments: empty response (HTTP error?)" -}}
{{- end -}}
{{- end -}}
{{- $linked := slice -}}
{{- range $items -}}
{{- if .url }}{{ $linked = $linked | append . }}{{ end -}}
{{- end -}}
{{- with first 5 $linked -}}
<ul class="recent-comments">
{{- range . }}
<li>
<a href="{{ .url }}">{{ with ._garrul.post_title }}{{ . }}{{ else }}{{ .title }}{{ end }}</a>
<span>{{ (index .authors 0).name }}: {{ .content_html | plainify | htmlUnescape | truncate 100 }}</span>
</li>
{{- end }}
</ul>
{{- end -}}
```

Call it with `{{ partial "recent-comments.html" . }}`. A network error, a
non-2xx status, bad JSON or a missing `items` array logs a warning and renders
no list. The build still succeeds.

The list refreshes only when the site rebuilds. Add a scheduled CI rebuild
(for example a daily cron) to keep it current.
53 changes: 53 additions & 0 deletions examples/jekyll/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,3 +67,56 @@ In `_layouts/post.html`, at the bottom of `<article>`:
- For local dev (`jekyll serve` on `http://localhost:4000`), either
override `site.garrul.api` in `_config.dev.yml` or add the dev origin
to `ALLOWED_ORIGINS`.

## Recent comments list (build time)

Garrul serves a site-wide feed at `GET /feed`. This recipe shows the newest
comments on your home page or sidebar without loading the widget there. It
runs as a step before `jekyll build`, so it works in safe mode (GitHub Actions
builds) and needs no `_plugins`. The step needs `curl` and `jq`, both present
on GitHub-hosted runners.

The feed stays outside the Worker's `/api/*` Origin gate, so a build step with
no `Origin` header can read it. `site` must be an origin listed in
`ALLOWED_ORIGINS`, written without a trailing slash. On a single-origin install, drop `site` from the URL: see
`docs/embedding.md` (Recent comments).

Run this before `jekyll build` (for example as a workflow step):

```bash
FEED="https://comments.example.com/feed?format=json&site=https%3A%2F%2Fblog.example.com"
mkdir -p _data
if curl --fail --silent --show-error --max-time 10 -o feed.tmp "$FEED" \
&& jq -e '.items | type == "array"' feed.tmp > /dev/null; then
mv feed.tmp _data/recent_comments.json
else
echo "warning: recent comments unavailable, building without them" >&2
echo '{"items":[]}' > _data/recent_comments.json
fi
rm -f feed.tmp
```

A network error, a non-2xx status or a body that is not JSON with an `items`
array all write `{"items":[]}` and the build continues.

Render it where you want the list:

{% raw %}
```liquid
{% assign recent = site.data.recent_comments.items | where_exp: "i", "i.url" | slice: 0, 5 %}
{% if recent.size > 0 %}
<ul class="recent-comments">
{% for c in recent %}
<li>
<a href="{{ c.url | escape }}">{{ c._garrul.post_title | default: c.title | escape }}</a>
<span>{{ c.authors[0].name | escape }}: {{ c.content_html | strip_html | truncatewords: 20 }}</span>
</li>
{% endfor %}
</ul>
{% endif %}
```
{% endraw %}

The list refreshes only when the site rebuilds. Add a scheduled CI rebuild
(for example a daily `schedule:` cron in the workflow) to keep it current.
Add `_data/recent_comments.json` to `.gitignore` if the step runs in CI.
7 changes: 4 additions & 3 deletions examples/lazy-load/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,10 @@ get a seamless experience. Bouncers cost you nothing.

- **Crawler visibility of comment bodies.** Search engines and AI
crawlers don't scroll, so the comments tree won't be in the rendered
HTML they see. Garrul mitigates this with two independent surfaces
that *are* always crawlable: the per-post RSS feed (`/feed/:slug`)
and the per-comment permalinks (`/c/:id`). If you care strongly about
HTML they see. Garrul mitigates this with surfaces that *are* always
crawlable: the per-post feed (`/feed/:slug`), the site-wide
recent-comments feed (`/feed`), and the per-comment permalinks
(`/c/:id`). If you care strongly about
comment content being indexed inline with the post, skip lazy-loading
on that page.
- **Above-the-fold widgets.** Don't use this pattern if the comments
Expand Down
Loading
Loading