npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

sveltekit-rate-limiter

v0.6.1

Published

A modular rate limiter for SvelteKit. Use in password resets, account registration, etc.

Downloads

8,496

Readme

sveltekit-rate-limiter

A modular rate limiter for password resets, account registration, API call limiting, etc. Use in your +page.server.ts, +server.ts or src/hooks.server.ts.

Uses an in-memory cache (@isaacs/ttlcache), but can be swapped for something else. Same for limiters, which are plugins. The source file lists both interfaces.

Installation

npm i -D sveltekit-rate-limiter
pnpm i -D sveltekit-rate-limiter

How to use

import { error } from '@sveltejs/kit';
import { RateLimiter } from 'sveltekit-rate-limiter/server';

const limiter = new RateLimiter({
  // A rate is defined as [number, unit]
  IP: [10, 'h'], // IP address limiter
  IPUA: [5, 'm'], // IP + User Agent limiter
  cookie: {
    // Cookie limiter
    name: 'limiterid', // Unique cookie name for this limiter
    secret: 'SECRETKEY-SERVER-ONLY', // Use $env/static/private
    rate: [2, 'm'],
    preflight: true // Require preflight call (see load function)
  }
});

export const load = async (event) => {
  /**
   * Preflight prevents direct posting. If preflight option for the
   * cookie limiter is true and this function isn't called before posting,
   * request will be limited.
   *
   * Remember to await, so the cookie will be set before returning!
   */
  await limiter.cookieLimiter?.preflight(event);
};

export const actions = {
  default: async (event) => {
    // Every call to isLimited counts as a hit towards the rate limit for the event.
    if (await limiter.isLimited(event)) throw error(429);
  }
};

Call order for limiters

The limiters will be called in smallest unit and rate order, so in the example above:

cookie(2/min) → IPUA(5/min) → IP(10/hour)

For four consecutive requests from the same source within one minute, the following will happen:

| Request | Cookie | IPUA | IP | | ------- | --------- | ----- | ----- | | 1 | Hit 1 | Hit 1 | Hit 1 | | 2 | Hit 2 | Hit 2 | Hit 2 | | 3 | Limit | - | - | | 4 | Limit | - | - |

If the cookie is deleted but the User-Agent stays the same, the counter keeps going for the other limiters:

| Request | Cookie | IPUA | IP | | ------- | --------- | ----- | ----- | | 5 | Hit 1 | Hit 3 | Hit 3 | | 6 | Hit 2 | Hit 4 | Hit 4 | | 7 | Limit | - | - |

If deleted one more time, the User-Agent limiter will reach its limit:

| Request | Cookie | IPUA | IP | | ------- | --------- | --------- | ----- | | 8 | Hit 1 | Hit 5 | Hit 5 | | 9 | Hit 2 | Limit | - | | 10 | Limit | - | - |

Valid units

Valid units are, from smallest to largest:

'100ms' | '250ms' | '500ms'
's' | '2s' | '5s' | '10s' | '15s' | '30s' | '45s'
'm' | '2m' | '5m  | '10m' | '15m' | '30m' | '45m'
'h' | '2h' | '6h' | '12h'
'd'

Multiple limits

You can specify the rates as an array, to handle multiple rates per limiter, like "Max 1 per second and 100 per hour": [[1, 's'], [100, 'h']].

Retry-After limiter

There is a version of the rate limiter that will return Retry-After information, the number of seconds before the request should be attempted again. This has been implemented in the src/hooks.server.ts file and instead of throwing an error code like other pages, we have to create a new response so that we can add the header.

import type { Handle } from '@sveltejs/kit';
import { RetryAfterRateLimiter } from 'sveltekit-rate-limiter/server';

const limiter = new RetryAfterRateLimiter({
  IP: [10, 'h'],
  IPUA: [5, 'm']
});

export const handle: Handle = async ({ event, resolve }) => {
  const status = await limiter.check(event);
  if (status.limited) {
    let response = new Response(
      `You are being rate limited. Please try after ${status.retryAfter} seconds.`,
      {
        status: 429,
        headers: { 'Retry-After': status.retryAfter.toString() }
      }
    );
    return response;
  }
  const response = await resolve(event);
  return response;
};

A custom store for the RetryAfterRateLimiter can also be used, in which the second argument to the constructor should be a RateLimiterStore that returns a unix timestamp describing when the request should be reattempted, based on the unit sent to it.

Clearing the limits

Clearing all rate limits can be done by calling the clear method of the rate limiter object.

Custom hash function

The default hash function is using crypto.subtle to generate a SHA-256 digest, but if isn't available in your environment, you can supply your own with the hashFunction option. Here's an example with the NodeJS crypto package:

import crypto from 'crypto';

// (input: string) => MaybePromise<string>
const hashFunction = (input: string) =>
  crypto.createHash('sha256').update(input).digest('hex');

Creating a custom limiter

Implement the RateLimiterPlugin interface:

interface RateLimiterPlugin {
  hash: (event: RequestEvent) => MaybePromise<string | boolean | null>;
  get rate(): Rate | Rate[];
}

In hash, return one of the following:

  • A string based on a RequestEvent, which will be counted and checked against the rate.
  • A boolean, to short-circuit the plugin chain and make the request fail (false) or succeed (true) no matter the current rate.
  • Or null, to signify an indeterminate result and move to the next plugin in the chain, or fail the request if it's the last and no previous limiter have passed.

String hash rules

  • The string will be hashed later, so you don't need to use a hash function.
  • The string cannot be empty, in which case an exception will be thrown.

Example

Here's the source for the IP + User Agent limiter:

import type { RequestEvent } from '@sveltejs/kit';
import type { Rate, RateLimiterPlugin } from 'sveltekit-rate-limiter/server';

class IPUserAgentRateLimiter implements RateLimiterPlugin {
  readonly rate: Rate | Rate[];

  constructor(rate: Rate | Rate[]) {
    this.rate = rate;
  }

  async hash(event: RequestEvent) {
    const ua = event.request.headers.get('user-agent');
    if (!ua) return false;
    return event.getClientAddress() + ua;
  }
}

Add your limiter to the plugins option to use it.

import { RateLimiter } from 'sveltekit-rate-limiter/server';

const limiter = new RateLimiter({
  plugins: [new CustomLimiter([5, 'm'])]
  // The built-in limiters can be added as well.
});

Custom data for the limiter

You can specify a type parameter to RateLimiter that expands the isLimited method with an extra parameter. There you can add extra data that will be supplied to the custom limiters:

class AllowDomain implements RateLimiterPlugin {
  // Shortest rate, so it will be executed first
  readonly rate: Rate = [0, '100ms'];
  readonly allowedDomain: string;

  constructor(allowedDomain: string) {
    this.allowedDomain = allowedDomain;
  }

  async hash(_: RequestEvent, extraData: { email: string }) {
    // Return true to bypass the rest of the plugin chain
    return extraData.email.endsWith(this.allowedDomain) ? true : null;
  }
}
const limiter = new RateLimiter<{ email: string }>({
  plugins: [new AllowDomain('company-domain.com')],
  IP: [10, 'm']
});

export const actions = {
  default: async (event) => {
    if (await limiter.isLimited(event, { email: event.locals.user.email })) {
      throw error(429);
    }
  }
};