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

Setting Up Preflight Handling: Basic Configuration

Let's implement proper preflight request handling in our TypeScript REST API:

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');
});

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');
});

When a browser sends a preflight request to this server, the cors middleware automatically responds with the following 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-Allow-Credentials: true
Access-Control-Max-Age: 600

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

The browser uses these headers to determine if the actual request is allowed. The maxAge option tells browsers how long (in seconds) they can cache the preflight response, reducing the number of preflight requests and improving performance.

Note: However, not all browsers respect the maxAge setting equally. For example, some versions of Safari have been known to ignore this header, resulting in more frequent preflight requests than expected.

Setting Up Preflight Handling: Route-Specific CORS Policies

Sometimes, you might want different CORS policies for different routes. Here's how to create middleware for specific route types:

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');
});

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');
});

This implementation provides fine-grained control over which origins, methods, and headers are allowed for different parts of your API. Each route type can have its own preflight handling configuration.

Setting Up Preflight Handling: Adding Preflight Logging and Diagnostics

To make debugging easier, let's add middleware to log preflight requests:

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));

When a preflight request comes in, this middleware will log information like:

[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

This detailed logging helps you understand exactly what's happening with preflight requests and troubleshoot any CORS issues.

Manually Handling Preflight Requests Without the CORS Package

While the cors package handles preflight requests automatically, understanding how to handle them manually provides deeper insight:

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');
});

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');
});

This manual approach gives you complete control over how preflight requests are handled, but requires more maintenance than using the cors package.

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