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: 11 additions & 0 deletions README.ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -430,6 +430,17 @@ feed.addItem({
> [!TIP]
> hono-feed は XML エスケープを行いますが、HTML エンティティのエンコードは行いません。必要な場合、たとえば任意のテキストを安全な HTML の `content` / `description` に変換したいときは、[`he`](https://www.npmjs.com/package/he) (`he.encode(text)`)と、その TypeScript の型定義の [`@types/he`](https://www.npmjs.com/package/@types/he) を使ってください。

## 本文中の相対 URL を絶対化する

`baseUrl` が絶対化するのは URL を持つ*項目* (`link`、`enclosure.url` など)で、`content` や `description` に入れた HTML の中身は対象外です。フィードリーダーには `<img src="/a.png">` や `<a href="/post">` を解決する基準のページがないので、CMS から取った HTML の画像やリンクが壊れます。フィードのオプションで `absolutizeContent: true` を指定すると、これを書き換えます。

```ts
new Feed({ title: 'Blog', link: 'https://example.com/', absolutizeContent: true })
// <img src="/a.png"> -> <img src="https://example.com/a.png">
```

開始タグの中にある相対的な `src`、`href`、`poster`、`srcset` の値を、`baseUrl` を基準に書き換えます (`serveFeed` では、既定でリクエストの origin が基準です。基準がない場合は何もしません)。本文のテキスト、コメント、CDATA、`<script>` と `<style>` の中身には触れません。すでに絶対 URL の値、フラグメント、ほかのスキーム (`mailto:` や `data:`) の値は、そのまま残します。RSS、Atom、JSON Feed のすべてに適用され、既定ではオフです。

## オプション

`serveFeed(c, input, options?)` のオプションの一覧です。
Expand Down
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -430,6 +430,17 @@ An item's `comments` URL becomes `<comments>` in RSS 2.0 and `<link rel="replies
> [!TIP]
> hono-feed does the XML escaping for you, but it doesn't HTML-encode entities. If you need that — e.g. to turn arbitrary text into a safe HTML `content`/`description` value — reach for [`he`](https://www.npmjs.com/package/he) (`he.encode(text)`), plus [`@types/he`](https://www.npmjs.com/package/@types/he) for its TypeScript types.

## Absolute URLs in content

`baseUrl` absolutizes the URL *fields* (`link`, `enclosure.url`, …), but not the HTML you put in `content` or `description`. A feed reader has no page to resolve `<img src="/a.png">` or `<a href="/post">` against, so images and links from CMS-sourced HTML break. Set `absolutizeContent: true` in the feed options to rewrite them:

```ts
new Feed({ title: 'Blog', link: 'https://example.com/', absolutizeContent: true })
// <img src="/a.png"> -> <img src="https://example.com/a.png">
```

It rewrites relative `src`, `href`, `poster` and `srcset` values inside start tags, against `baseUrl` (`serveFeed` defaults it to the request origin; without any base it does nothing). Text, comments, CDATA and `<script>` / `<style>` bodies are never touched, and a value that is already absolute, a fragment, or uses another scheme (`mailto:`, `data:`) is left exactly as written. It applies to RSS, Atom and JSON Feed, and is off by default.

## Options

All options for `serveFeed(c, input, options?)`:
Expand Down
22 changes: 22 additions & 0 deletions base/README.base.md
Original file line number Diff line number Diff line change
Expand Up @@ -627,6 +627,17 @@ An item's `comments` URL becomes `<comments>` in RSS 2.0 and `<link rel="replies
:::

:::kiritan{locale=en}
## Absolute URLs in content

`baseUrl` absolutizes the URL *fields* (`link`, `enclosure.url`, …), but not the HTML you put in `content` or `description`. A feed reader has no page to resolve `<img src="/a.png">` or `<a href="/post">` against, so images and links from CMS-sourced HTML break. Set `absolutizeContent: true` in the feed options to rewrite them:

```ts
new Feed({ title: 'Blog', link: 'https://example.com/', absolutizeContent: true })
// <img src="/a.png"> -> <img src="https://example.com/a.png">
```

It rewrites relative `src`, `href`, `poster` and `srcset` values inside start tags, against `baseUrl` (`serveFeed` defaults it to the request origin; without any base it does nothing). Text, comments, CDATA and `<script>` / `<style>` bodies are never touched, and a value that is already absolute, a fragment, or uses another scheme (`mailto:`, `data:`) is left exactly as written. It applies to RSS, Atom and JSON Feed, and is off by default.

## Options

All options for `serveFeed(c, input, options?)`:
Expand Down Expand Up @@ -655,6 +666,17 @@ All options for `serveFeed(c, input, options?)`:
| `suppressDeprecationWarnings` | `boolean` | `false` | Mute warnings for deprecated versions |
:::
:::kiritan{locale=ja}
## 本文中の相対 URL を絶対化する

`baseUrl` が絶対化するのは URL を持つ*項目* (`link`、`enclosure.url` など)で、`content` や `description` に入れた HTML の中身は対象外です。フィードリーダーには `<img src="/a.png">` や `<a href="/post">` を解決する基準のページがないので、CMS から取った HTML の画像やリンクが壊れます。フィードのオプションで `absolutizeContent: true` を指定すると、これを書き換えます。

```ts
new Feed({ title: 'Blog', link: 'https://example.com/', absolutizeContent: true })
// <img src="/a.png"> -> <img src="https://example.com/a.png">
```

開始タグの中にある相対的な `src`、`href`、`poster`、`srcset` の値を、`baseUrl` を基準に書き換えます (`serveFeed` では、既定でリクエストの origin が基準です。基準がない場合は何もしません)。本文のテキスト、コメント、CDATA、`<script>` と `<style>` の中身には触れません。すでに絶対 URL の値、フラグメント、ほかのスキーム (`mailto:` や `data:`) の値は、そのまま残します。RSS、Atom、JSON Feed のすべてに適用され、既定ではオフです。

## オプション

`serveFeed(c, input, options?)` のオプションの一覧です。
Expand Down
4 changes: 3 additions & 1 deletion src/formats/atom/index.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
import type { FeedInput, SerializeOptions } from '../../types'
import { warnDeprecated } from '../../utils/deprecation'
import { withAbsoluteContent } from '../content'
import { toAtom03 } from './atom03'
import { toAtom10 } from './atom10'

export { validateInput } from '../../validate'

/** Serialize the neutral model to Atom. `atomVersion` '0.3' emits the deprecated 0.3. */
export function toAtom(input: FeedInput, opts: SerializeOptions = {}): string {
export function toAtom(rawInput: FeedInput, opts: SerializeOptions = {}): string {
const input = withAbsoluteContent(rawInput, opts.baseUrl)
// RFC 4287 §2: Atom documents are "serialized as XML 1.0".
if (opts.xmlVersion === '1.1') {
throw new TypeError('hono-feed: Atom must be serialized as XML 1.0 (RFC 4287 §2)')
Expand Down
61 changes: 61 additions & 0 deletions src/formats/content.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
import { Hono } from 'hono'
import { describe, expect, it } from 'vitest'
import { serveFeed } from '../serve'
import type { FeedInput } from '../types'
import { toAtom } from './atom'
import { toJSONFeed } from './json'
import { toRSS } from './rss'

const input = (absolutizeContent?: boolean): FeedInput => ({
options: {
title: 't',
link: 'https://example.com/',
author: { name: 'Ann' },
updated: new Date('2026-01-01T00:00:00Z'),
absolutizeContent,
},
items: [
{
title: 'a',
link: 'https://example.com/1',
content: '<img src="/a.png"><a href="next">n</a>',
description: '<a href="/d">d</a>',
updated: new Date('2026-01-01T00:00:00Z'),
},
],
})
const opts = { baseUrl: 'https://example.com/blog/', feedUrl: 'https://example.com/feed' }

describe('absolutizeContent', () => {
it('leaves content untouched by default', () => {
expect(toRSS(input(), opts)).toContain('src="/a.png"')
expect(toAtom(input(), opts)).toContain('src="/a.png"')
expect(toJSONFeed(input(), opts)).toContain('src=\\"/a.png\\"')
})

it('absolutizes content and description in RSS, Atom and JSON Feed when opted in', () => {
const rss = toRSS(input(true), opts)
expect(rss).toContain('src="https://example.com/a.png"')
expect(rss).toContain('href="https://example.com/blog/next"')
expect(rss).toContain('href="https://example.com/d"')
expect(toAtom(input(true), opts)).toContain('src="https://example.com/a.png"')
const json = JSON.parse(toJSONFeed(input(true), opts))
expect(json.items[0].content_html).toBe(
'<img src="https://example.com/a.png"><a href="https://example.com/blog/next">n</a>',
)
})

it('does nothing without a base URL, and does not mutate the input', () => {
const source = input(true)
expect(toRSS(source, {})).toContain('src="/a.png"')
toRSS(source, opts)
expect(source.items[0].content).toBe('<img src="/a.png"><a href="next">n</a>')
})

it('applies in serveFeed, using the request origin as the base', async () => {
const app = new Hono()
app.get('/feed', (c) => serveFeed(c, input(true)))
const body = await (await app.request('https://example.org/feed')).text()
expect(body).toContain('src="https://example.org/a.png"')
})
})
15 changes: 15 additions & 0 deletions src/formats/content.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
import type { FeedInput, FeedItem } from '../types'
import { absolutizeHtml } from '../utils/html'

/**
* With `options.absolutizeContent` set and a base URL known, return the input with each item's HTML `content` and `description` made absolute; otherwise the input itself, untouched.
*/
export function withAbsoluteContent(input: FeedInput, baseUrl: string | undefined): FeedInput {
if (!input.options.absolutizeContent || !baseUrl) return input
const rewrite = (item: FeedItem): FeedItem => ({
...item,
content: item.content && absolutizeHtml(item.content, baseUrl),
description: item.description && absolutizeHtml(item.description, baseUrl),
})
return { ...input, items: input.items.map(rewrite) }
}
5 changes: 3 additions & 2 deletions src/formats/json/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,13 @@ import { warnDeprecated } from '../../utils/deprecation'
import { enclosureList } from '../../utils/enclosure'
import { hubList } from '../../utils/hub'
import { absolutize, selfUrl } from '../../utils/url'
import { withAbsoluteContent } from '../content'

export { validateInput } from '../../validate'

/** Serialize the neutral model to a JSON Feed 1.1 string. */
export function toJSONFeed(input: FeedInput, opts: SerializeOptions = {}): string {
const { options, items } = input
export function toJSONFeed(rawInput: FeedInput, opts: SerializeOptions = {}): string {
const { options, items } = withAbsoluteContent(rawInput, opts.baseUrl)
const base = opts.baseUrl
// 1.0 uses the singular `author` and predates `language`.
const v1 = opts.jsonFeedVersion === '1'
Expand Down
4 changes: 3 additions & 1 deletion src/formats/rss/index.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import type { FeedInput, SerializeOptions } from '../../types'
import { warnDeprecated } from '../../utils/deprecation'
import { withAbsoluteContent } from '../content'
import { toRSS2 } from './rss2'
import { toRSS10 } from './rss10'
import { toRSS11 } from './rss11'
Expand All @@ -13,7 +14,8 @@ const OBSOLETE_RSS = new Set(['0.90', '0.91', '0.92', '0.93', '0.94'])
/**
* Serialize the neutral model to RSS. `rssVersion` '0.90' / '1.0' / '1.1' emit RDF; '2.0' / '0.94' / '0.93' / '0.92' / '0.91' emit the `<rss version="…">` structure.
*/
export function toRSS(input: FeedInput, opts: SerializeOptions = {}): string {
export function toRSS(rawInput: FeedInput, opts: SerializeOptions = {}): string {
const input = withAbsoluteContent(rawInput, opts.baseUrl)
const version = opts.rssVersion
// The 0.90 spec requires the exact <?xml version="1.0"?> declaration.
if (version === '0.90' && opts.xmlVersion === '1.1') {
Expand Down
4 changes: 4 additions & 0 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,10 @@ export interface FeedOptions {
image?: string
/** Atom icon / JSON favicon. */
favicon?: string
/**
* Rewrite relative `src` / `href` / `poster` / `srcset` URLs in each item's HTML `content` and `description` to absolute ones against `baseUrl`, so images and links survive in a reader that has no page to resolve them against. Default `false`. Only attribute values inside start tags are touched. Needs a base URL (`baseUrl`, which `serveFeed` defaults to the request origin); without one this does nothing.
*/
absolutizeContent?: boolean
/**
* Emit an item's `image` as a `<media:thumbnail>` in RSS 2.0 and Atom 1.0, so readers that show thumbnails pick it up. Default `false`, so `image` stays JSON Feed-only. Items that already set `media.thumbnails` keep their own. `xmlns:media` is declared automatically, only when a thumbnail is emitted.
*/
Expand Down
79 changes: 79 additions & 0 deletions src/utils/html.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
import { describe, expect, it } from 'vitest'
import { absolutizeHtml } from './html'

const base = 'https://example.com/blog/'

describe('absolutizeHtml', () => {
it('resolves relative src, href and poster against the base', () => {
expect(
absolutizeHtml('<img src="/a.png"><a href="post">x</a><video poster="p.jpg">', base),
).toBe(
'<img src="https://example.com/a.png"><a href="https://example.com/blog/post">x</a><video poster="https://example.com/blog/p.jpg">',
)
})

it('handles single-quoted and unquoted values, and normalizes them to double quotes', () => {
expect(absolutizeHtml("<a href='/x'>a</a><a href=/y>b</a>", base)).toBe(
'<a href="https://example.com/x">a</a><a href="https://example.com/y">b</a>',
)
})

it('resolves protocol-relative URLs', () => {
expect(absolutizeHtml('<img src="//cdn.test/a.png">', base)).toBe(
'<img src="https://cdn.test/a.png">',
)
})

it('leaves absolute URLs, fragments, empty values and other schemes alone', () => {
const html =
'<a href="https://a.test/">a</a><a href="#top">b</a><a href="">c</a><a href="mailto:a@b.c">d</a><img src="data:image/png;base64,AAAA"><a href="tel:1">e</a>'
expect(absolutizeHtml(html, base)).toBe(html)
})

it('resolves each srcset candidate and keeps its descriptor', () => {
expect(
absolutizeHtml('<img srcset="a.png 1x, /b.png 2x, https://c.test/c.png 3x">', base),
).toBe(
'<img srcset="https://example.com/blog/a.png 1x, https://example.com/b.png 2x, https://c.test/c.png 3x">',
)
expect(absolutizeHtml('<img srcset="a.png 480w,b.png 800w">', base)).toBe(
'<img srcset="https://example.com/blog/a.png 480w,https://example.com/blog/b.png 800w">',
)
})

it('does not touch text, comments, CDATA, script or style bodies', () => {
const html =
'<p>see href="/x" and src="/y"</p><!-- <a href="/c"> --><![CDATA[<a href="/d">]]><script>var s = \'<a href="/e">\'</script><style>a[href="/f"]{}</style>'
expect(absolutizeHtml(html, base)).toBe(html)
})

it('does not end a tag early on a ">" inside a quoted attribute value', () => {
expect(absolutizeHtml('<a title="a > b" href="/x">t</a>', base)).toBe(
'<a title="a > b" href="https://example.com/x">t</a>',
)
})

it('does not rewrite attributes that merely end in src/href', () => {
const html = '<div data-src="/a" data-href="/b" nosrc="/c">'
expect(absolutizeHtml(html, base)).toBe(html)
})

it('keeps "&amp;" in a query string intact', () => {
expect(absolutizeHtml('<a href="/s?a=1&amp;b=2">x</a>', base)).toBe(
'<a href="https://example.com/s?a=1&amp;b=2">x</a>',
)
})

it('skips a value carrying an entity other than &amp;', () => {
const html = '<a href="/a&#47;b">x</a>'
expect(absolutizeHtml(html, base)).toBe(html)
})

it('is case-insensitive about tag and attribute names', () => {
expect(absolutizeHtml('<IMG SRC="/a.png">', base)).toBe('<IMG SRC="https://example.com/a.png">')
})

it('returns an empty string unchanged', () => {
expect(absolutizeHtml('', base)).toBe('')
})
})
61 changes: 61 additions & 0 deletions src/utils/html.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
import { hasIriScheme } from './url'

// Everything the scanner must step over untouched, then the one thing it rewrites: a start tag. Comments, CDATA and the bodies of <script>/<style> are matched first so a "<a href>" inside them is never seen as markup. A start tag's attribute list is quote-aware, so a ">" inside a value doesn't end the tag early.
const MARKUP =
/<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<(script|style)\b[\s\S]*?<\/\1\s*>|<[a-zA-Z][^\s/>]*(?:"[^"]*"|'[^']*'|[^'">])*>/gi
const URL_ATTRIBUTE = /(\s)(src|href|poster|srcset)(\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/gi
const SRCSET_CANDIDATE = /(\s*)([^\s,]+)((?:\s+[^\s,]+)*)(\s*)(,|$)/g

/** Resolve one attribute value, or return `undefined` to leave it alone. */
function resolveUrl(value: string, base: string): string | undefined {
const trimmed = value.trim()
// A fragment, an empty value, or anything with its own scheme (https:, mailto:, data:, …) needs no base.
if (!trimmed || trimmed.startsWith('#') || hasIriScheme(trimmed)) return undefined
try {
return new URL(trimmed, base).href
} catch {
return undefined
}
}

// Only "&amp;" is decoded and re-encoded; a value with any other entity is too ambiguous to rewrite safely, so it's skipped.
function rewriteValue(raw: string, attribute: string, base: string): string | undefined {
if (/&(?!amp;)[#\w]+;/.test(raw)) return undefined
const value = raw.replace(/&amp;/g, '&')
let resolved: string
if (attribute === 'srcset') {
let changed = false
resolved = value.replace(
SRCSET_CANDIDATE,
(candidate, lead: string, url: string, descriptor: string, trail: string, comma: string) => {
const absolute = resolveUrl(url, base)
if (absolute === undefined) return candidate
changed = true
return `${lead}${absolute}${descriptor}${trail}${comma}`
},
)
if (!changed) return undefined
} else {
const absolute = resolveUrl(value, base)
if (absolute === undefined) return undefined
resolved = absolute
}
return resolved.replace(/&/g, '&amp;').replace(/"/g, '&quot;')
}

/**
* Rewrite relative `src` / `href` / `poster` / `srcset` attribute values in an HTML fragment to absolute URLs against `base`. Deliberately conservative: only attribute values inside start tags are touched — never text, comments, CDATA, or `<script>` / `<style>` bodies — and anything already absolute, a fragment, or carrying an unusual entity is left exactly as written.
*/
export function absolutizeHtml(html: string, base: string): string {
return html.replace(MARKUP, (markup) => {
if (!markup.startsWith('<') || /^<(?:!|script|style)/i.test(markup)) return markup
return markup.replace(
URL_ATTRIBUTE,
(match, space: string, name: string, eq: string, dq?: string, sq?: string, bare?: string) => {
const raw = dq ?? sq ?? bare ?? ''
const rewritten = rewriteValue(raw, name.toLowerCase(), base)
return rewritten === undefined ? match : `${space}${name}${eq}"${rewritten}"`
},
)
})
}
Loading