Not every request needs to reach an application server.
Some request-processing tasks are small enough to happen at the edge before the request is forwarded to the backend. Azure Front Door can be used for edge processing scenarios where lightweight JavaScript modifies or evaluates HTTP requests and responses.
This can be useful for simple routing decisions, header manipulation, redirects, normalization, and other request-processing tasks that do not require access to application databases or long-running services.
The key is knowing what belongs at the edge and what belongs inside the application.
What Is Edge JavaScript?
In a traditional application architecture, request processing usually happens after the request reaches the backend:
Client
|
v
Azure Front Door
|
v
ASP.NET Core
|
v
Application Logic
|
v
Database
For lightweight edge processing, some logic can run before the request reaches the application:
Client
|
v
Azure Front Door
|
+-- Edge JavaScript
|
v
ASP.NET Core
|
v
Application Logic
This can reduce unnecessary backend processing and allow certain HTTP transformations to happen closer to the client.
The important limitation is that edge JavaScript is not a replacement for a backend application.
When Edge JavaScript Makes Sense
Edge code is a good fit when the logic is:
- Small
- Fast
- Stateless
- Based on HTTP request or response information
- Independent of database access
- Independent of long-running operations
Examples include:
Request
|
+-- Normalize a URL
+-- Add a header
+-- Remove an unwanted header
+-- Apply a simple routing decision
+-- Redirect based on request information
+-- Transform lightweight response metadata
These operations can often be performed without contacting the application.
When Edge JavaScript Is the Wrong Tool
Do not move application business logic to the edge simply because JavaScript can execute there.
Avoid using edge code for:
- Database queries
- Complex business rules
- Long-running operations
- Large data processing
- Payment processing
- Transaction management
- Stateful workflows
- Complex authorization decisions
For example, this belongs in the application:
GET /orders/12345
|
v
Check database
|
v
Verify customer ownership
|
v
Return order
The edge does not own the order database or business rules.
Understand the Request Lifecycle
Before writing edge JavaScript, understand where the code runs.
A simplified request lifecycle looks like:
Browser
|
v
Front Door
|
+-- Request Processing
|
+-- Edge JavaScript
|
+-- Routing / WAF / Other Edge Controls
|
v
Backend
|
v
Response
|
v
Front Door
|
+-- Response Processing
|
v
Browser
The exact order of platform features depends on the Front Door configuration and feature being used.
This matters because edge logic should be designed around the data available at that stage of processing.
Start With a Small Transformation
A simple example is adding a request header.
Conceptually:
function onRequest(request) {
request.headers.set("x-edge-processed", "true");
return request;
}
The exact API surface depends on the Azure Front Door edge scripting capability and runtime configuration being used.
The important design principle is to keep the operation small.
A request transformation should not turn into a mini application.
Normalize Request Information
Another useful scenario is normalizing request information before it reaches the backend.
For example, an application may need a consistent header value:
function onRequest(request) {
const region = request.headers.get("x-client-region");
if (region) {
request.headers.set(
"x-normalized-region",
region.toLowerCase()
);
}
return request;
}
This can reduce repetitive normalization code inside multiple backend services.
However, do not trust client-controlled headers for security-sensitive decisions unless they are supplied by a trusted platform component.
For example, a client should not be allowed to claim:
X-User-Role: Admin
and have edge code treat that value as authoritative.
URL Rewriting
Edge processing can also be useful for simple URL normalization.
For example:
/request
/request/
/REQUEST
may need to be treated consistently by a backend.
A lightweight transformation can normalize the request path before routing.
The exact implementation depends on the Front Door edge scripting API, but the design is straightforward:
Incoming Request
|
v
Normalize Path
|
v
Route Request
|
v
Backend
This can be useful when applications have legacy URL patterns or multiple client versions.
Add Lightweight Security Headers
Response processing is another potential use case.
For example, a response may need additional HTTP headers.
Conceptually:
function onResponse(response) {
response.headers.set(
"x-content-type-options",
"nosniff"
);
return response;
}
Security headers should be configured using the appropriate platform capability when available rather than duplicating configuration unnecessarily.
The important point is that edge processing can provide a centralized location for simple HTTP-level transformations.
Do Not Put Secrets in Edge Code
Edge code should be treated as deployed application code.
Do not write secrets directly into the script:
const apiKey = "my-secret-api-key";
This creates a credential-management problem.
If the edge logic requires access to a secret, first verify whether the platform feature actually supports secure secret access for that execution context.
If it does not, move the operation to the backend.
A useful rule is:
No secure secret access
|
v
Do not perform the operation at the edge
This prevents a small optimization from creating a security vulnerability.
Keep Edge Code Stateless
Edge code should generally avoid depending on local memory or previous requests.
Do not design logic like:
let requestCount = 0;
function onRequest(request) {
requestCount++;
}
The execution environment may be distributed across multiple edge locations.
There is no reliable guarantee that subsequent requests will execute in the same environment.
For stateful processing, use an appropriate backend or managed data service.
Design for Fast Execution
Edge code exists to make request processing more efficient.
If the script becomes expensive, the benefit starts to disappear.
Prefer:
function onRequest(request) {
const value = request.headers.get("x-version");
if (value === "legacy") {
// Apply a small transformation.
}
return request;
}
Avoid trying to perform complex processing:
Request
|
+-- Parse large body
+-- Perform multiple transformations
+-- Run complex calculations
+-- Call external APIs
+-- Query database
+-- Build large response
That work belongs in the application or a dedicated service.
Use Edge Logic With Routing
A useful pattern is combining lightweight request inspection with routing.
For example:
Client
|
v
Front Door
|
+-- Inspect Request
|
+-- Determine Simple Routing Signal
|
+-- Route to Backend
|
+-- API A
|
+-- API B
A request might contain a version indicator:
X-API-Version: v2
The edge can use that information for routing if the value is trustworthy and the routing design requires it.
However, API versioning should not depend entirely on a client-controlled header when security or authorization is involved.
Separate Routing From Business Logic
A useful architectural rule is:
Edge
|
+-- HTTP transformation
+-- Routing
+-- Filtering
|
v
Application
|
+-- Authentication
+-- Authorization
+-- Business rules
+-- Data access
The edge knows about HTTP traffic.
The application knows about the business.
Keeping that boundary clear prevents edge scripts from becoming difficult-to-maintain application code.
Error Handling
Edge scripts should fail safely.
Consider a request transformation that expects a header:
const version = request.headers.get("x-api-version");
The header may not exist.
Handle missing values explicitly rather than assuming that every request has the expected structure.
Conceptually:
function onRequest(request) {
const version =
request.headers.get("x-api-version");
if (!version) {
return request;
}
// Apply a small transformation.
return request;
}
For security-sensitive decisions, failure behavior should be carefully defined.
If required authentication information is missing, rejecting the request may be safer than silently continuing.
Logging and Observability
Debugging edge code can be different from debugging normal ASP.NET Core code.
A request may be rejected or transformed before reaching the backend.
Therefore, production diagnostics should allow you to determine:
Request received
|
v
Front Door
|
+-- Edge processing
|
+-- WAF
|
+-- Routing
|
v
Backend
Use correlation identifiers where possible.
For example:
Correlation ID: 8c3d...
The same identifier can help connect Front Door activity with application logs.
Do not log sensitive headers or bearer tokens.
Testing Edge JavaScript
Do not test edge logic only after deploying to production.
Use small, predictable test cases.
For a URL transformation, test:
Input: /orders
Output: expected route
Input: /orders/
Output: expected route
Input: /ORDERS
Output: expected route
Input: /unknown
Output: expected fallback
For header processing:
Header present
Header missing
Header empty
Header contains unexpected value
The goal is to verify both the normal path and failure path.
Common Mistakes
Putting Business Logic at the Edge
If the script needs database access or complex application state, it probably belongs in the backend.
Assuming the Edge Is Stateful
Do not rely on variables surviving between requests.
Trusting Client Headers
A header sent by the client is not automatically trustworthy.
Use trusted platform-generated information for security-sensitive decisions.
Putting Secrets in JavaScript
Never hard-code credentials into edge scripts.
Making the Script Too Large
Large edge scripts become difficult to test and maintain.
Keep them focused on a single HTTP-level responsibility.
Ignoring Failure Behavior
Every transformation should define what happens when expected headers, paths, or values are missing.
Duplicating Application Logic
If the same business rule exists at both the edge and API, the two implementations can eventually disagree.
Move only the logic that genuinely belongs at the edge.
Best Practices
| Area | Recommendation |
|---|
| Purpose | Use edge code for lightweight HTTP processing |
| Performance | Keep execution fast and small |
| State | Treat execution as stateless |
| Security | Never trust arbitrary client headers |
| Secrets | Never hard-code credentials |
| Business logic | Keep it in the backend |
| Routing | Use edge processing for simple routing decisions |
| Testing | Test missing and unexpected inputs |
| Monitoring | Use correlation IDs and edge diagnostics |
| Maintenance | Keep scripts focused and easy to replace |
One useful test is to ask:
"Could this logic run correctly without knowing anything about my database or business domain?"
If the answer is yes, it may be a reasonable edge-processing candidate.
If the answer is no, keep it in the application.
Advantages
Lightweight edge JavaScript can provide several benefits:
- Request processing happens closer to users.
- Simple transformations can happen before backend execution.
- Backend code can remain focused on application behavior.
- Routing logic can be centralized.
- Repeated HTTP transformations can be handled consistently.
- Some unnecessary backend traffic can be reduced.
These benefits are most useful when the operation is small and happens frequently.
Disadvantages
Edge processing also introduces another layer into the architecture.
Developers need to understand the edge runtime, its execution model, available APIs, debugging capabilities, and platform limitations.
Troubleshooting can also become more complicated because a request may change before the application sees it.
There is another maintenance concern. If the same behavior is implemented in several edge scripts and backend services, the system can become difficult to reason about.
For that reason, edge JavaScript should be treated as infrastructure code rather than a place to move arbitrary application logic.
Troubleshooting
The Backend Receives the Wrong Header
Check whether the edge script is modifying or removing the header before routing.
Compare the original request with the request observed by the backend.
The Script Works for One Request but Not Another
Check whether the code depends on request-specific information that may not always exist.
Test missing headers, empty values, different URL paths, and unexpected input.
Requests Are Not Reaching the Backend
Check Front Door routing and WAF configuration in addition to edge processing.
The request may be rejected before the backend is contacted.
Performance Gets Worse After Adding Edge Code
Review the script for unnecessary processing.
Edge code should be lightweight. If it performs complex transformations or expensive operations, move that work to the backend.
Security Behavior Is Incorrect
Review whether the script relies on client-controlled headers or other untrusted request values.
Authentication and authorization decisions should use trusted security mechanisms.
Summary
Azure Front Door edge JavaScript is most useful when it handles small, stateless HTTP tasks before a request reaches the backend.
A clean architecture keeps the responsibilities separated:
Client
|
v
Azure Front Door
|
+-- WAF
+-- Routing
+-- Lightweight Edge Processing
|
v
ASP.NET Core API
|
+-- Authentication
+-- Authorization
+-- Business Logic
+-- Data Access
Use the edge for operations such as simple request transformation, lightweight routing, and HTTP-level processing. Keep database access, business rules, stateful workflows, and complex authorization inside the application.
The best edge scripts are small enough that another developer can understand their purpose quickly. Once edge code starts looking like an application of its own, it is usually a sign that the logic belongs somewhere else.
Join the conversation! Your thoughts help the community grow.