Handling Preflight (OPTIONS) Requests & Methods

Introduction

Welcome back! In our previous lesson, we explored the basics of Cross-Origin Resource Sharing (CORS) and its significance in web development. Now, we're going to dive deeper into a crucial aspect of CORS: preflight requests . These requests play a vital role in ensuring secure cross-origin communication. Think of them as a security check before allowing access to resources. By the end of this lesson, you'll understand what preflight requests are, when they occur, and how to handle them effectively in your TypeScript REST API . Let's get started! 🚀

Understanding Preflight Requests

Preflight requests are a part of the CORS mechanism that browsers use to determine if a cross-origin request is safe to send. They are triggered when a request uses methods other than simple methods like GET, HEAD, or POST (with certain content types), or when custom headers are included. To be more specific, POST requests are only considered "simple" if they use one of the following content types: application/x-www-form-urlencoded, multipart/form-data, or text/plain . If a POST request uses application/json—which is common in modern APIs—it will trigger a preflight request. This is an important detail that explains why many seemingly normal API requests may involve a preflight check. Here's how preflight requests work: When you make a "non-simple" cross-origin request, the browser first sends an OPTIONS request to the server This preflight request checks if the actual request is allowed based on origin, method, and headers The server responds with specific CORS headers indicating what's permitted Only if the preflight is successful will the browser send the actual request Imagine you're entering a secure building; a preflight request is like the security guard checking your credentials before letting you in. Without proper handling of these preflight requests, certain cross-origin requests will be blocked by browsers.

Why Preflight Requests Matter

To understand why we need to handle preflight requests properly, let's look at a common scenario: Suppose your frontend (running on http://localhost:3000) needs to make a PUT request to your API (running on http://localhost:8000) with a custom Authorization header. Before sending the actual PUT request, the browser will automatically send an OPTIONS request to check if: The server allows requests from http://localhost:3000 (origin) The server allows PUT methods The server accepts the Authorization header If your server doesn't properly respond to this OPTIONS request with the appropriate CORS headers, the browser will block the actual PUT request, and you'll see an error like: Access to fetch at 'http://localhost:8000/api/resource' from origin 'http://localhost:3000' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

TypeScript

import express from 'express';
import cors, { CorsOptions } from 'cors';

const app = express();

// Define CORS options with preflight configuration
const corsOptions: CorsOptions = {
  origin: 'http://localhost:3000', // Your frontend origin
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
  credentials: true,
  maxAge: 600 // Cache preflight response for 10 minutes
};

// Apply CORS middleware to handle preflight requests
app.use(cors(corsOptions));

// Your routes here
app.get('/api/resources', (req, res) => {
  res.json({ message: 'This is a GET endpoint' });
});

app.put('/api/resources/:id', (req, res) => {
  res.json({ message: 'This is a PUT endpoint' });
});

app.listen(8000, () => {
  console.log('Server running on port 8000');
});

Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,PATCH,OPTIONS
Access-Control-Allow-Headers: Content-Type,Authorization,X-Requested-With
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 600

TypeScript

import express, { Router, Request, Response, NextFunction } from 'express';
import cors, { CorsOptions } from 'cors';

// Create different CORS configurations for different route types
export const createPreflightHandler = (allowedOrigins: string | string[], 
                                      allowedMethods: string[] = ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
                                      allowedHeaders: string[] = ['Content-Type', 'Authorization']) => {
  
  const options: CorsOptions = {
    origin: allowedOrigins,
    methods: allowedMethods,
    allowedHeaders: allowedHeaders,
    maxAge: 600, // Cache preflight response for 10 minutes
    credentials: true
  };
  
  return cors(options);
};

const app = express();

// Create routers for different API sections
const publicRouter = express.Router();
const authRouter = express.Router();
const adminRouter = express.Router();

// Apply different CORS policies to different routes
publicRouter.use(createPreflightHandler(
  ['http://localhost:3000', 'https://public-app.example.com'],
  ['GET', 'OPTIONS']
));

authRouter.use(createPreflightHandler(
  'http://localhost:3000', 
  ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']
));

adminRouter.use(createPreflightHandler(
  'https://admin.example.com',
  ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS']
));

// Define routes on each router
publicRouter.get('/resources', (req, res) => {
  res.json({ message: 'Public resources' });
});

authRouter.put('/user/:id', (req, res) => {
  res.json({ message: 'User updated' });
});

// Register routers with the app
app.use('/api/public', publicRouter);
app.use('/api/auth', authRouter);
app.use('/api/admin', adminRouter);

app.listen(8000, () => {
  console.log('Server running on port 8000');
});

TypeScript

// Preflight request diagnostic middleware
export const preflightLogger = (req: Request, res: Response, next: NextFunction) => {
  if (req.method === 'OPTIONS') {
    console.log(`[PREFLIGHT] ${new Date().toISOString()} - ${req.method} ${req.path}`);
    console.log('  Origin:', req.headers.origin);
    console.log('  Requested Method:', req.headers['access-control-request-method']);
    console.log('  Requested Headers:', req.headers['access-control-request-headers']);
    
    // Add a response hook to log what's being returned
    const originalEnd = res.end;
    res.end = function(...args: any[]) {
      console.log('  Responding with CORS headers:');
      console.log('    Access-Control-Allow-Origin:', res.getHeader('Access-Control-Allow-Origin'));
      console.log('    Access-Control-Allow-Methods:', res.getHeader('Access-Control-Allow-Methods'));
      console.log('    Access-Control-Allow-Headers:', res.getHeader('Access-Control-Allow-Headers'));
      console.log('    Access-Control-Max-Age:', res.getHeader('Access-Control-Max-Age'));
      return originalEnd.apply(this, args);
    };
  }
  next();
};

// Apply the logger middleware before CORS middleware
app.use(preflightLogger);
app.use(cors(corsOptions));

[PREFLIGHT] 2023-11-21T14:35:22.657Z - OPTIONS /api/resources/123
  Origin: http://localhost:3000
  Requested Method: PUT
  Requested Headers: content-type,authorization

  Responding with CORS headers:
    Access-Control-Allow-Origin: http://localhost:3000
    Access-Control-Allow-Methods: GET,POST,PUT,DELETE,PATCH,OPTIONS
    Access-Control-Allow-Headers: Content-Type,Authorization,X-Requested-With
    Access-Control-Max-Age: 600

TypeScript

import express from 'express';

const app = express();

// Manual preflight handler without cors package
app.options('*', (req, res) => {
  // Set CORS headers
  res.header('Access-Control-Allow-Origin', 'http://localhost:3000');
  res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS');
  res.header('Access-Control-Allow-Headers', 'Content-Type,Authorization');
  res.header('Access-Control-Max-Age', '600');
  res.header('Access-Control-Allow-Credentials', 'true');
  
  // Pre-flight requests need a 204 response
  res.status(204).end();
});

// Add CORS headers to all other requests
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', 'http://localhost:3000');
  res.header('Access-Control-Allow-Credentials', 'true');
  next();
});

// Your routes
app.get('/api/resources', (req, res) => {
  res.json({ message: 'Resources retrieved' });
});

app.listen(8000, () => {
  console.log('Server running on port 8000');
});

TypeScript

// Preflight request diagnostic middleware
export const preflightLogger = (req: Request, res: Response, next: NextFunction) => {
  if (req.method === 'OPTIONS') {
    console.log(`[PREFLIGHT] ${new Date().toISOString()} - ${req.method} ${req.path}`);
    console.log('  Origin:', req.headers.origin);
    console.log('  Requested Method:', req.headers['access-control-request-method']);
    console.log('  Requested Headers:', req.headers['access-control-request-headers']);
    
    // Add a response hook to log what's being returned
    const originalEnd = res.end;
    res.end = function(...args: any[]) {
      console.log('  Responding with CORS headers:');
      console.log('    Access-Control-Allow-Origin:', res.getHeader('Access-Control-Allow-Origin'));
      console.log('    Access-Control-Allow-Methods:', res.getHeader('Access-Control-Allow-Methods'));
      console.log('    Access-Control-Allow-Headers:', res.getHeader('Access-Control-Allow-Headers'));
      console.log('    Access-Control-Max-Age:', res.getHeader('Access-Control-Max-Age'));
      return originalEnd.apply(this, args);
    };
  }
  next();
};

// Apply the logger middleware before CORS middleware
app.use(preflightLogger);
app.use(cors(corsOptions));

[PREFLIGHT] 2023-11-21T14:35:22.657Z - OPTIONS /api/resources/123
  Origin: http://localhost:3000
  Requested Method: PUT
  Requested Headers: content-type,authorization

  Responding with CORS headers:
    Access-Control-Allow-Origin: http://localhost:3000
    Access-Control-Allow-Methods: GET,POST,PUT,DELETE,PATCH,OPTIONS
    Access-Control-Allow-Headers: Content-Type,Authorization,X-Requested-With
    Access-Control-Max-Age: 600

Introduction

Understanding Preflight Requests

Why Preflight Requests Matter

Join the 1M+ learners on CodeSignal

Setting Up Preflight Handling: Basic Configuration

Setting Up Preflight Handling: Route-Specific CORS Policies

Setting Up Preflight Handling: Adding Preflight Logging and Diagnostics

Manually Handling Preflight Requests Without the CORS Package

Common Pitfalls and Misconceptions

Conclusion and Next Steps