Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/juanjh1/asimilation/llms.txt

Use this file to discover all available pages before exploring further.

The timeout middleware automatically terminates requests that exceed a specified duration, preventing resource exhaustion and improving server responsiveness.

​
What It Does

The timeout middleware:
  • Sets a timer for each incoming request
  • Automatically responds with a 504 Gateway Timeout if the request exceeds the timeout duration
  • Cleans up the timer when the request completes successfully
  • Prevents memory leaks by using proper cleanup in a finally block

​
Default Configuration

By default, the timeout is set to 1 millisecond (this is likely a placeholder in the source code and should be configured based on your needs). 
const timer = setTimeout(() => {
    if (!finished || !res.writableEnded) {
        res.sendJson({ message: 'Request timed out' }, 504);
        finished = true;
    }
}, 1); // 1ms timeout
The default 1ms timeout is extremely aggressive and will cause most requests to timeout. You should configure this value based on your application’s requirements.

​
How It Works

Here’s the complete implementation of the timeout middleware: 
import { MiddlewarePipeline } from "../../core/middleware-manager.js";
import { ArgumentedIncomingMessageAbc } from "../../abstract/abstract_req.js";
import { ArgumentedServerResponseAbc } from "../../abstract/abstract_res.js";

MiddlewarePipeline.addMiddleware(
    async (req, res, next) => {
        let finished: boolean = false;

        const timer = setTimeout(() => {
            if (!finished || !res.writableEnded) {
                res.sendJson({ message: 'Request timed out' }, 504);
                finished = true;
            }
        }, 1); // Timeout duration in milliseconds
        
        try {
            next();
        } finally {
            clearTimeout(timer);
            finished = true;
        }
    }
);

​
Key Features

1
Automatic Cleanup
2
The middleware uses a finally block to ensure the timer is always cleared, preventing memory leaks:
3
finally {
    clearTimeout(timer);
    finished = true;
}
4
Safe Response Handling
5
Before sending the timeout response, the middleware checks if the response has already been sent:
6
if (!finished || !res.writableEnded) {
    res.sendJson({ message: 'Request timed out' }, 504);
}
7
504 Gateway Timeout
8
The middleware returns a proper HTTP 504 status code, indicating that the server did not receive a timely response from an upstream server or failed to complete processing in time.

​
Configuration

To configure the timeout duration, you’ll need to modify the middleware or create a custom version. Here’s an example with a 30-second timeout: 
import { MiddlewarePipeline } from "@asimilation/core";

MiddlewarePipeline.addMiddleware(
    async (req, res, next) => {
        let finished: boolean = false;

        const timer = setTimeout(() => {
            if (!finished || !res.writableEnded) {
                res.sendJson({ 
                    message: 'Request timed out',
                    timeout: '30s'
                }, 504);
                finished = true;
            }
        }, 30000); // 30 seconds
        
        try {
            next();
        } finally {
            clearTimeout(timer);
            finished = true;
        }
    }
);

​
Timeout Response

When a request times out, the client receives the following JSON response: 
{
    "message": "Request timed out"
}
HTTP Status: 504 Gateway Timeout

​
Enabling the Timeout Middleware

The timeout middleware is part of the default middleware stack. Import it to enable: 
import "asimilation/default/middleware/timeout";
import { asi, url } from "@asimilation/core";

// Define routes
url.get("/long-task", async (req, res) => {
    // This will timeout if it takes longer than configured
    await performLongRunningTask();
    res.sendJson({ success: true });
});

asi.setup(3000, "");
asi.run();

​
Use Cases

API Gateway

Prevent upstream services from hanging your API gateway indefinitely.

Long-Running Operations

Force clients to use async patterns (webhooks, polling) for operations that may take longer than acceptable.

Resource Protection

Prevent slow or malicious clients from consuming server resources.

SLA Compliance

Enforce response time guarantees by timing out requests that exceed your SLA.

​
Best Practices

Recommended Timeout Values:
  • API Endpoints: 10-30 seconds
  • File Uploads: 60-300 seconds
  • Webhook Handlers: 5-15 seconds
  • Database Queries: 5-10 seconds
For operations that legitimately take longer than your timeout, consider implementing:
  • Asynchronous job queues
  • Webhook callbacks
  • Polling endpoints to check operation status
  • Server-Sent Events (SSE) or WebSockets for real-time updates

​
Custom Timeout Per Route

If you need different timeouts for different routes, you can create route-specific middleware: 
function timeoutMiddleware(ms: number) {
    return async (req, res, next) => {
        let finished = false;
        
        const timer = setTimeout(() => {
            if (!finished || !res.writableEnded) {
                res.sendJson({ 
                    message: `Request timed out after ${ms}ms` 
                }, 504);
                finished = true;
            }
        }, ms);
        
        try {
            next();
        } finally {
            clearTimeout(timer);
            finished = true;
        }
    };
}

// Apply different timeouts to different routes
url.get("/quick", timeoutMiddleware(5000), (req, res) => {
    // 5 second timeout
});

url.post("/upload", timeoutMiddleware(60000), (req, res) => {
    // 60 second timeout for file uploads
});

Build docs developers (and LLMs) love

Get started for freeTalk to us