FlameShield SDK

FlameShield is a rate limiting SDK for Firebase Cloud Functions that helps protect your services from excessive requests.

Installation

1npm install flamesshield-sdk

Usage

FlameShield provides a simple way to add rate limiting to your Firebase Cloud Functions.

Basic Example

1import { rateLimit } from 'flamesshield-sdk';
2import { initializeApp } from 'firebase-admin/app';
3
4const app = initializeApp();
5
6export const myFunction = async (req, res) => {
7  try {
8    await rateLimit({
9      maxCalls: 100,
10      periodSeconds: 60,
11      app: app,
12      onSuccess: () => {
13        // Your function logic here
14        res.status(200).send('Success!');
15      },
16      onFailure: () => {
17        res.status(429).send('Too many requests');
18      }
19    });
20  } catch (error) {
21    res.status(500).send('Error: ' + error.message);
22  }
23};

Parameters

The rateLimit function accepts the following parameters:

Parameter	Type	Required	Default	Description
maxCalls	number	Yes		Maximum number of calls allowed in the period
periodSeconds	number	Yes		Time period in seconds for the rate limit
onSuccess	function	Yes		Function to execute when rate limit is not exceeded
app	App	Yes		Firebase Admin App instance
name	string	No	Environment variable*	The name of your function
qualifier	string	No		Optional identifier (e.g., userId) to create separate rate limits for different entities
onFailure	function	No	throws Error	Function to execute when rate limit is exceeded
apiKey	string	No	process.env.API_KEY	API key for FlameShield service
verbose	boolean	No	false	Enable verbose logging

* The SDK will automatically try to use one of the following environment variables: FUNCTION_TARGET, K_SERVICE, or FUNCTION_NAME.

Rate Limiting Parameters Explained

maxCalls and periodSeconds

These parameters work together to define your rate limiting policy:

• maxCalls: Defines the maximum number of function invocations allowed
• periodSeconds: Defines the time window in seconds for the rate limit

For example:

• maxCalls: 100, periodSeconds: 60 allows 100 calls per minute
• maxCalls: 1000, periodSeconds: 3600 allows 1000 calls per hour
• maxCalls: 10000, periodSeconds: 86400 allows 10000 calls per day

Choose these values based on your function's resource consumption and expected traffic patterns.

qualifier

The qualifier parameter is optional but useful for creating separate rate limits for different entities:

1await rateLimit({
2  maxCalls: 50,
3  periodSeconds: 3600,
4  app: app,
5  qualifier: userId, // Create separate rate limits per user
6  onSuccess: () => { /* function logic */ },
7});

Common use cases for qualifier:

• User ID: Limit each user to a specific number of requests
• IP address: Rate limit by client IP
• Subscription tier: Apply different limits based on customer tier
• Region/location: Create separate quotas for different geographic regions

Advanced Example

1import { rateLimit } from 'flamesshield-sdk';
2import { initializeApp } from 'firebase-admin/app';
3
4const app = initializeApp();
5
6export const processOrder = async (req, res) => {
7  try {
8    // Using userId as qualifier to create separate rate limits per user
9    const userId = req.auth.uid;
10    
11    await rateLimit({
12      maxCalls: 500,
13      periodSeconds: 3600, // 1 hour
14      app: app,
15      qualifier: userId,
16      apiKey: process.env.FLAMESHIELD_API_KEY,
17      verbose: true,
18      onSuccess: () => {
19        // Process the order
20        const result = processOrderLogic(req.body);
21        res.status(200).json(result);
22      },
23      onFailure: () => {
24        // Handle rate limit exceeded
25        res.status(429).json({
26          error: 'Rate limit exceeded',
27          message: 'You have exceeded your order processing limit for this hour'
28        });
29      }
30    });
31  } catch (error) {
32    console.error('Order processing error:', error);
33    res.status(500).json({ error: 'Internal server error' });
34  }
35};
36
37function processOrderLogic(orderData) {
38  // Your order processing logic
39  return { orderId: '12345', status: 'processed' };
40}

Error Handling

If the rate limit is exceeded and no onFailure function is provided, the SDK will throw an error with the message 'Rate limit exceeded'.

Environment Configuration

The SDK can be configured using environment variables:

• API_KEY: Default API key for FlameShield service
• FUNCTION_TARGET, K_SERVICE, or FUNCTION_NAME: Default function name if not specified

Verbose Logging

When verbose is set to true, the SDK will log detailed information about the rate limiting process, which can be helpful for debugging.