Popsicle HTTP Redirects Middleware

Common errors

• TypeError: Cannot read properties of undefined (reading 'use')

  cause Attempting to use `redirects` without providing a valid middleware function, or incorrectly chaining it with `popsicle.request`.
  fix Ensure `redirects` is called with a compatible middleware, typically `transport()` from `popsicle`, and then correctly chained in the `request.use()` call: `request.use(redirects(transport()))`.

• Error: Too many redirects

  cause The HTTP request encountered more redirects than the configured `maxRedirects` limit (default is 5).
  fix Increase the `maxRedirects` option if more redirects are expected, or investigate the target URL for excessive or cyclic redirects. Example: `redirects(transport(), { maxRedirects: 10 })`.

• TS2345: Argument of type 'typeof import("...")' is not assignable to parameter of type 'Middleware'.

  cause Incorrectly importing or using the `redirects` function as a default import, or attempting to pass `redirects` directly where a middleware is expected without calling it.
  fix Ensure `redirects` is imported as a named export (`import { redirects } from 'popsicle-redirects';`) and called with the `transport()` function: `request.use(redirects(transport()))`.

Warnings

• breaking When upgrading to v1.1.1, ensure your application does not rely on cookies being forwarded during cross-origin redirects. This version introduced a security fix that discards cookies when redirected away to a different origin, preventing potential information leakage.
  Fix: Review existing code for assumptions about cookie forwarding during redirects. If cookie forwarding is explicitly required for specific same-origin scenarios after a redirect, consider implementing custom logic or ensuring redirects remain within the same origin.
• gotcha Previous versions (prior to v1.0.1) could enter an infinite redirect loop if a malformed or cyclic redirect chain was encountered due to a flaw in request cloning.
  Fix: Upgrade to `popsicle-redirects@1.0.1` or later to resolve the infinite redirect loop issue. Always ensure your redirect chain eventually terminates or configure a `maxRedirects` option to prevent excessive loops.
• gotcha The `redirects` function expects a 'throwback' compatible middleware, typically `popsicle`'s `transport()` function. Passing nothing or an incompatible middleware will result in runtime errors.
  Fix: Always initialize `redirects` with a valid transport middleware, e.g., `redirects(transport())` when used with `popsicle`.
• gotcha By default, 307 (Temporary Redirect) and 308 (Permanent Redirect) status codes, which typically preserve the request method, are not automatically followed unless explicitly confirmed. The default `confirmRedirect` option returns `false`.
  Fix: To enable following 307/308 redirects, provide a custom `confirmRedirect` function in the options: `redirects(transport(), { confirmRedirect: () => true })` or implement more sophisticated logic.

Install

• npm install popsicle-redirects npm
• yarn add popsicle-redirects yarn
• pnpm add popsicle-redirects pnpm

Imports

• redirects
  wrong:

  const { redirects } = require('popsicle-redirects');

  correct:

  import { redirects } from 'popsicle-redirects';

  The library primarily promotes ESM usage. While CommonJS `require` might work with transpilation or specific Node.js configurations, direct `import` is the idiomatic way.
• redirects (default import)
  wrong:

  import redirects from 'popsicle-redirects';

  correct:

  import { redirects } from 'popsicle-redirects';

  The `redirects` function is a named export, not a default export. Attempting a default import will result in `undefined`.
• Middleware Integration
  wrong:

  import { redirects } from 'popsicle-redirects';
  const redirectMiddleware = redirects();

  correct:

  import { redirects } from 'popsicle-redirects';
  import { transport } from 'popsicle';
  
  const redirectMiddleware = redirects(transport());
  // Add redirectMiddleware to your Popsicle request chain

  The `redirects` function expects a 'throwback' compatible middleware function as an argument, typically the `transport()` function from `popsicle` itself, or another middleware capable of handling the initial request.

Quickstart

This quickstart demonstrates how to integrate `popsicle-redirects` into a `popsicle` client to automatically follow HTTP redirects, including basic error handling.

import { request } from 'popsicle';
import { redirects } from 'popsicle-redirects';
import { transport } from 'popsicle';

async function fetchDataWithRedirects() {
  const httpClient = request
    .use(redirects(transport())) // Integrate the redirects middleware
    .use(async (request, next) => {
      // Example of custom middleware or error handling
      try {
        const response = await next(request);
        if (!response.ok) {
          console.error(`HTTP Error: ${response.status} ${response.statusText}`);
        }
        return response;
      } catch (error) {
        console.error('Request failed:', error.message);
        throw error;
      }
    });

  try {
    const response = await httpClient.get('http://example.com/redirect-to-target');
    const data = await response.text();
    console.log('Response data:', data);
  } catch (error) {
    console.error('Failed to fetch:', error.message);
  }
}

fetchDataWithRedirects();