Overview of Redirector Component

When your URL map changes, every millisecond spent in a 404 costs rankings, revenue, and trust. The Harper Redirector lets you manage millions of redirects with 1 millisecond P95 lookups—without bolting on a separate database, cache, or edge worker. Below is a quick technical tour so you can clone the repo and start stress‑testing it today.

‍

Why a Dedicated Redirect Engine?

Scale

Legacy approach: Apache/Nginx conf files grow linearly and reload slowly.
Harper Redirector: Horizontally sharded tables; handling hundreds of millions of rules is routine.

Latency

Legacy approach: Database lookups or client‑side JavaScript add extra round‑trips.
Harper Redirector: In‑memory index inside the Harper runtime delivers sub‑millisecond lookups

Ops

Legacy Approach: Redirects scattered across YAML files, CDN rules, and spreadsheets.
Harper Redirector: One CSV/JSON import or REST write—fully versioned and promotable in bulk.

‍

Under the Hood

Smart matching – Host‑aware lookups, optional regex paths, and query‑string operations (qs:preserve, qs:filter) so one rule can handle thousands of permutations
Versioning – Flip activeVersion in the version table to atomically swap an entire redirect set—perfect for re‑platform launches.

Metrics out of the box – Every hit is written to a metrics stream; drop it into Grafana or the Harper Analytics API for real‑time insight.

‍

3‑Step Local Spin‑Up

git clone https://github.com/HarperDB/template-redirector.git
cd template-redirector
harperdb dev .           # Hot‑reloads while you edit

Requires the Harper CLI (npm i -g harperdb).

The harperdb dev . command will automatically watch for file changes within the component directory and restart the Harper threads when changes are detected.

‍

Importing Rules

curl http://localhost:9926/redirect \
  --header "Content-Type: text/csv" \
  --data-binary @redirects.csv

Fields include path, redirectURL, optional utcStartTime/EndTime, and regex flag. JSON is equally accepted.

Need a blue‑green cut‑over? Add version=1 to your CSV and promote it later:

PUT /version
{ "activeVersion": 1 }

‍

Fast Lookup API

GET /checkredirect?path=/shoe-sale&h=www.shop.com&ho=1

Returns {statusCode:301, redirectURL:"/sneakers"} from server in ~ 1ms. Parameters let you override host, version, or testing time, and you can push paths via the Path header to preserve query strings exactly.

‍

Edge or Origin? You Choose

Because Harper runs identically on a single VM, a Kubernetes cluster, or geo‑distributed edge nodes, you can:

Centralize at the origin for simple architectures.
Fan‑out to edge instances (or have your CDN call the /checkredirect API) for single‑digit‑ms global round‑trips.

Either way, scaling up is literally adding another Harper node—no extra services to wire.

‍

Deploying to Dev, Staging, Prod

harperdb deploy_component \
  project=redirector \
  package=https://github.com/HarperDB/template-redirector \
  target=prod.mydomain.io \
  username=$USER password=$PASS \
  restart=true replicated=true

The CLI packages the repo (or pulls from npm/GitHub), ships it to the remote instance with rolling restarts for zero downtime.

‍

Ready to Test It Yourself?

Star & fork: https://github.com/HarperDB/template-redirector
Browse the docs: https://docs.harperdb.io/docs/developers/components/managing
Join us on Slack: https://harperdbcommunity.slack.com/join/shared_invite/zt-1qr24rcth-29fwBYzHPXpgJdb9e~o24A#/shared-invite/email

‍

The redirect problem is solved; now you can get back to building features. Happy routing!

‍

Our Story

Dev Center