redirects

README

IPFS _redirects File Parser

This is a parser for the IPFS Web Gateway's _redirects file format.

Specification

This repository implements Web _redirects File Specification from https://specs.ipfs.tech/http-gateways/web-redirects-file/.

For historical discussion see ipfs/specs#290 and IPIP-0002: _redirects File Support on Web Gateways.

Format

Currently only supports from, to and status.

from to [status]

Example

# Implicit 301 redirects
/home              /
/blog/my-post.php  /blog/my-post
/news              /blog
/google            https://www.google.com

# Redirect with a 301
/home         /              301

# Redirect with a 302
/my-redirect  /              302

# Redirect with wildcard (splat placeholder)
/splat/* /redirected-splat/:splat 301

# Redirect with multiple named placeholder
/posts/:year/:month/:day/:title  /articles/:year/:month/:day/:title  301

# Show a custom 404 for everything under this path
/ecommerce/*  /store-closed.html  404

# Single page app rewrite (SPA, PWA)
/*    /index.html   200

Notes for contributors

• make all builds and runs tests
• FUZZTIME=1m make fuzz runs fuzzing for specified amount of time

---

Credit

This project was forked from tj/go-redirects. Thank you TJ for the initial work. 🙏

Documentation

Overview

Package redirects provides Netlify style _redirects file format parsing.

Example

h := Must(ParseString(`
		# Implicit 301 redirects
		/home              /
		/blog/my-post.php  /blog/my-post
		/news              /blog
		/google            https://www.google.com

		# Redirect with a 301
		/home         /              301

		# Redirect with a 302
		/my-redirect  /              302

		# Rewrite a path
		/pass-through /index.html    200

		# Show a custom 404 for this path
		/ecommerce    /store-closed  404

		# Single page app rewrite
		/*    /index.html   200

		# Proxying
		/api/*  https://api.example.com/:splat  200
  `))

enc := json.NewEncoder(os.Stdout)
enc.SetIndent("", "  ")
enc.Encode(h)

Output:

	[
  {
    "From": "/home",
    "To": "/",
    "Status": 301
  },
  {
    "From": "/blog/my-post.php",
    "To": "/blog/my-post",
    "Status": 301
  },
  {
    "From": "/news",
    "To": "/blog",
    "Status": 301
  },
  {
    "From": "/google",
    "To": "https://www.google.com",
    "Status": 301
  },
  {
    "From": "/home",
    "To": "/",
    "Status": 301
  },
  {
    "From": "/my-redirect",
    "To": "/",
    "Status": 302
  },
  {
    "From": "/pass-through",
    "To": "/index.html",
    "Status": 200
  },
  {
    "From": "/ecommerce",
    "To": "/store-closed",
    "Status": 404
  },
  {
    "From": "/*",
    "To": "/index.html",
    "Status": 200
  },
  {
    "From": "/api/*",
    "To": "https://api.example.com/:splat",
    "Status": 200
  }
]

Index

• Constants
• type Rule
  • func Must(v []Rule, err error) []Rule
  • func Parse(r io.Reader) (rules []Rule, err error)
  • func ParseString(s string) ([]Rule, error)
  • func (r *Rule) IsProxy() bool
  • func (r *Rule) IsRewrite() bool
  • func (r *Rule) MatchAndExpandPlaceholders(urlPath string) bool

Examples

• Package

Constants

const MaxFileSizeInBytes = 65536

64 KiB

Types

type Rule

type Rule struct {
	// From is the path which is matched to perform the rule.
	From string

	// To is the destination which may be relative, or absolute
	// in order to proxy the request to another URL.
	To string

	// Status is one of the following:
	//
	// - 3xx a redirect
	// - 200 a rewrite
	// - defaults to 301 redirect
	//
	Status int
}

A Rule represents a single redirection or rewrite rule.

func Must

func Must(v []Rule, err error) []Rule

Must parse utility.

func Parse

func Parse(r io.Reader) (rules []Rule, err error)

Parse the given reader.

func ParseString

func ParseString(s string) ([]Rule, error)

ParseString parses the given string.

func (*Rule) IsProxy

func (r *Rule) IsProxy() bool

IsProxy returns true if it's a proxy rule (aka contains a hostname).

func (*Rule) IsRewrite

func (r *Rule) IsRewrite() bool

IsRewrite returns true if the rule represents a rewrite (status 200).

func (*Rule) MatchAndExpandPlaceholders

func (r *Rule) MatchAndExpandPlaceholders(urlPath string) bool

MatchAndExpandPlaceholders expands placeholders in `r.To` and returns true if the provided path matches. Otherwise it returns false.