feat(ssg): add redirect plugin

[3w36zj6]

close #4389

The author should do the following, if applicable

• Add tests
• Run tests
• bun run format:fix && bun run lint:fix to format the code
• Add TSDoc/JSDoc to document the code

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.42%. Comparing base (ef2a4b8) to head (35e58ff).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
src/helper/ssg/plugins.ts	88.09%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4599      +/-   ##
==========================================
- Coverage   91.56%   91.42%   -0.15%     
==========================================
  Files         173      174       +1     
  Lines       11256    11413     +157     
  Branches     3267     3305      +38     
==========================================
+ Hits        10307    10434     +127     
- Misses        948      978      +30     
  Partials        1        1              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[3w36zj6]

The specification mandates that redirect responses must include a Location header ¹. Current implementations simply bypass generating the file if no Location header is present, though options include displaying a warning or throwing an error could be considered.

Footnotes

1. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Location ↩

[3w36zj6]

Since built-in plugins should only handle lightweight ones, I decided to manage multiple plugins in a single plugins.ts file. This should make updating exports slightly more convenient.

[yusukebe]

You don't specify the from parameter. Is it expected?

[3w36zj6]

I forgot to implement it.

The Response object in afterResponseHook does not contain information about the original redirect source, so we probably need to prepare a custom header like x-hono-ssg-route to inject the request path.

I also thought of another option, but this approach might break when running in parallel. (For production use, we would need to use a FIFO queue, but in this PoC I implemented it in a straightforward way.)

export const redirectPlugin = (): SSGPlugin => {
  const requestedUrls: string[] = []
  return {
    beforeRequestHook: (req) => {
      requestedUrls.push(new URL(req.url).pathname)
      return req
    },
    afterResponseHook: (res) => {
      if (res.status === 301 || res.status === 302) {
        const location = res.headers.get('Location')
        if (!location) {
          return false
        }
        const from = requestedUrls.shift()
        if (!from) {
          return false
        }
        const body = generateRedirectHtml(from, location)
        return new Response(body, {
          status: 200,
          headers: { 'Content-Type': 'text/html; charset=utf-8' },
        })
      }
      return res
    },
  }
}

[yusukebe]

How about removing from from this PR?

At the very least, the user knows where it comes from because they access the URL directly. And I think the information about from is not so important.

[yusukebe]

It's a rare case if passing the script into to, but I think you should escape it. How about html?

import { html } from '../html'

And you can esapce to with ${html`${to}`}

[3w36zj6]

I refactored the code to use the html helper and added test cases related to escaping. Double escaping might not be necessary.

Also, it could be useful if the html helper had an option to get a minified string. If you cannot think of many use cases for it, it may not be needed.

[yusukebe]

What do you think of a situation where you use it with defaultPlugin? It works well if you put the redirecPlugin above the defaultPlugin. So, I think it's good to add a description about it on our website.

[3w36zj6]

I also think updating the documentation is essential.

Additionally, it might be helpful to add name: string and requires?: string[] to the plugin, so that we can validate the plugin order. What do you think? (I think dependency validation itself is an interesting idea, but we need to carefully discuss the interface and validation methods.)

[3w36zj6]

I added TSDoc and tests for plugin ordering.

[yusukebe]

I think dependency validation itself is an interesting idea, but we need to carefully discuss the interface and validation methods.

Yes. Let's discuss another place.

[yusukebe]

@3w36zj6

Please ping me if it's ready to review.

[3w36zj6]

Sorry for the delayed response. Other tasks besides ESLint rule enforcement are currently unfinished.

Once I've completed the fixes and replied to comments, I'll send review request.

[3w36zj6]

Build-in plugins test should be separated to plugins.test.tsx?

[yusukebe]

The ssg.test.tsx became fat. So separating it is a good idea.

[3w36zj6]

The default plugin is an object, but the redirect plugin is a function. Should we standardize it to functions for consistency?

[yusukebe]

Ahh, I think function is better because the user can pass options like redirectPlugin({ optionA }) if needed.

[3w36zj6]

I've finished addressing the review.

This might be a nitpick, but should we also treat 303¹, 307², and 308³ as triggers for generating redirect HTML? Since all of them require the Location header, I feel it would make the implementation more consistent with the specification.

Footnotes

1. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/303 ↩

2. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/307 ↩

3. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/308 ↩