Skip to content

javascript.md

Latest commit

 

History

History
163 lines (117 loc) · 3.24 KB

javascript.md

File metadata and controls

163 lines (117 loc) · 3.24 KB

JavaScript Rules

Fast, sandboxed request evaluation using the V8 JavaScript engine.

The Request Object

Your JavaScript code receives a r object with these properties:

  • r.url - Full URL
  • r.method - HTTP method (GET, POST, etc.)
  • r.host - Hostname
  • r.scheme - URL scheme (http/https)
  • r.path - URL path

Basic Usage

Inline Rules

# Allow specific host
httpjail --js "r.host === 'github.com'" -- command

# Multiple conditions
httpjail --js "r.host === 'api.example.com' && r.method === 'GET'" -- command

# Using arrays
httpjail --js "['GET', 'POST'].includes(r.method)" -- command

File-based Rules

// rules.js
const allowedHosts = ['github.com', 'api.github.com'];

// The last expression is the result
allowedHosts.includes(r.host);
httpjail --js-file rules.js -- command

Response Format

{{#include ../../includes/response-format-table.md}}

Examples:

// Simple boolean
true  // Allow
false // Deny

// With custom deny message (needs parentheses in inline expressions)
({allow: false, deny_message: "Social media blocked"})

// Conditional with message
r.host === 'facebook.com' ? {deny_message: 'Social media blocked'} : true

// Limit request upload size to 1KB (headers + body)
({allow: {max_tx_bytes: 1024}})

Using Return Statements

JavaScript rules don't allow naked return statements. To use returns, wrap your code in an IIFE:

(function() {
  if (r.host === 'github.com') {
    return true;
  }
  
  if (r.host.match(/facebook|twitter/)) {
    return {deny_message: "Blocked"};
  }
  
  return false;
})();

Common Patterns

Domain Allowlisting

const allowed = ['example.com', 'api.example.com'];
allowed.includes(r.host)

Subdomain Matching

r.host === 'example.com' || r.host.endsWith('.example.com')

Path-based Rules

r.host === 'api.example.com' && r.path.startsWith('/v1/public/')

Method Restrictions

['GET', 'HEAD', 'OPTIONS'].includes(r.method)

Host Whitelist

// Simple host whitelist
const allowedHosts = [
  'github.com',
  'api.github.com',
  'raw.githubusercontent.com',
  'codeload.github.com'
];

allowedHosts.includes(r.host)

Host + Method Whitelist

// Allow specific methods only for certain hosts
const rules = [
  {host: 'api.github.com', methods: ['GET', 'POST']},
  {host: 'github.com', methods: ['GET']},
  {host: 'uploads.github.com', methods: ['POST', 'PUT']}
];

rules.some(rule => 
  rule.host === r.host && rule.methods.includes(r.method)
)

Regexp Matching on Method + URL

// Whitelist patterns for METHOD + URL combinations
const patterns = [
  /^GET api\.github\.com\/repos\/.+/,
  /^POST api\.example\.com\/v[12]\/.*/,
  /^(GET|HEAD) .*\.cdn\.example\.com\/.*\.(jpg|png|gif)/
];

// Build request string using host and path for simpler patterns
const requestString = `${r.method} ${r.host}${r.path}`;
patterns.some(pattern => pattern.test(requestString))

When to Use

Best for:

  • Simple host/path filtering
  • Quick prototyping
  • Untrusted rule sources (sandboxed)

Avoid for:

  • Stateful processing (use line processor)
  • External integrations (use shell or line processor)