Earlier this week I took a look at BoxLang's new rewriting feature (("URL Rewriting with BoxLang MiniServer")[https://www.raymondcamden.com/2025/08/11/url-rewriting-with-boxlang-miniserver]). It basically boils down to telling the miniserver app, "here is a file I want you to run on a 404", and given that you can write code for anything you would like, it's really flexible. I like this approach, but it got me thinking, what if BoxLang also supported a non-code based rewriting system, something where you can define paths, and rewrites, in a file? I took a stab at architecting such a feature and thought I'd share.
My Inspiration
My inspiration for this idea comes from Netlify's robust Redirect/Rewrite support which has multiple different features. It can map simple paths to one another and also map dynamic paths. It can even create simple proxies, letting you build apps that use client side code to APIs where you can't expose the keys in JavaScript. I took a look at the various options supported by Netlify and decided to try to tackle a subset of them as a proof of concept.
The File
My input file, rewrites.txt, will be a simple text-based and tab-delimited set of input paths and rewrite destinations. Let's start simple:
/blog /news
# We renamed this in 1921
/pr /pressrelease
In the sample above, I've got two rewrite rules and a comment that should be ignored by the engine. In theory, any non-technical person can grok this and add or modify rules easily enough.
The Engine
And now for the engine itself. Again, starting simple, here is my rewriter.bxs:
RW_FILE = './rewrites.txt';
if(!fileExists(RW_FILE)) return;
// load up rewrites and parse it (will cache)
function parseRWFile(contents) {
rules = [];
lines = contents.listToArray('#char(10)##char(13)#');
lines.each(l => {
parts = l.listToArray(char(9));
// must have 2, 3 is supported
if(parts.len() < 2) continue;
rule = {from:parts[1], to:parts[2]};
if(parts.len() === 3) rule.code = parts[3];
rules.append(rule)
});
return rules;
}
rules = parseRWFile(fileRead(RW_FILE));
rules.each(r => {
//straight x to y match
if(cgi.path_info == r.from) {
code = r.code?:301;
// special handling for 200
if(code !== "200") bx:location url=r.to statusCode=code;
else {
// will only work if you redirect to a specifc file, not a directory
// so ie: /something /somethingelse/index.bxm 200
bx:include template=r.to;
abort;
}
}
});
// handle 404
Up top, I simply default the filename to look for and do a quick check for its existence. Next I've got a basic file parsing utility that will go over every line in the input, split it by tabs, and ensure there's at least 2 values after the split. I use a third space to optionally let you set a status code for the redirect.
I iterate over the rules and begin with my first supported logic, a simple A=>B type match. If the cgi.path_info matches a from value, I'm going to redirect the user. By default, this is done via bx:location, which means the user will see the new URL. Typically this is what you want I'd say, and the user can bookmark the new location if they want. However, you may also want to 'blindly' do the redirect where the location doesn't change. That's when the 200 status code check comes in and I switch to simply including the new template. You'll note for that to work though you need to redirect to a specific file. Here's an example:
/blog2 /news/index.bxm 200
Splat!
I love "splat" - as a word it's just fun. That being said, one of the cooler Netlify redirect features is the idea of a wildcard match like so:
/prods/* /products/:splat
In this case, everything after the path /prods/ becomes the splat value and the direct will include that. In my loop above, I added support like so:
// something/* to something/:splat
if(r.from.endsWith("*") && r.to.endsWith(":splat")) {
// first, does our current request match r.from
normalizedPart = r.from.replace("*","");
if(cgi.path_info.find(normalizedPart) === 1) {
splat = cgi.path_info.replace(normalizedPart,"");
newLocation = r.to.replace(":splat", splat);
bx:location url=newLocation;
}
}
This just boils down to looking for the asterisk and :splat, and then doing string manipulation to handle the redirect.
This worked well but led to another problem.
Mapping URLs to Data
After I supported mapping /prods/foo to /products/foo, I realized this would only work if /products/foo/index.bxm actually existed, which is fine of course. But what if I wanted to map to /products/index.bxm and have the value, foo, available to the code there?
I began by adding a new rule to my text file:
/products/* /products/:product
And then modified my rewriter code like so:
if(r.from.endsWith("*") && r.to.endsWith(":splat")) {
// first, does our current request match r.from
normalizedPart = r.from.replace("*","");
if(cgi.path_info.find(normalizedPart) === 1) {
splat = cgi.path_info.replace(normalizedPart,"");
newLocation = r.to.replace(":splat", splat);
bx:location url=newLocation;
}
} else if(r.from.endsWith("*") && r.to.reFind(":[a-zA-Z]+$")) {
// something/* to something/:name such that something/index.bxm is loaded with request.name == the value
matchedToken = r.to.mid(r.to.reFind(":[a-zA-Z]+$") + 1, r.to.len());
normalizedPart = r.from.replace("*","");
splat = cgi.path_info.replace(normalizedPart,"");
request[matchedToken] = splat;
normalizedLocation = r.to.replace(":#matchedToken#","");
bx:include template="#normalizedLocation#/index.bxm";
abort;
}
Now it handles cases where the end isn't :splat and considers it a variable. This is stored in the request scope and made available to the included document, which for now assumes index.bxm. All in all it means this set of rules:
/prods/* /products/:splat
/products/* /products/:product
Will take a URL like /prods/catbox and redirect to /products/catbox in the browser while then loading products/index.bxm and making a request variable, product, contain the value catbox. Whew. T
The Code
Ok, so as I said, this is all a proof of concept and not nearly as powerful as the system Netlify has in place, but it absolutely shows you could build something like that. Again, my idea here was to make it easier to both write rules for our app as well make it easier to read those rules later to understand behavior.
You can find the complete demo here, https://github.com/ortus-boxlang/bx-demos/tree/master/webapps/rewritedemo/filebased, and I've included both my text and BoxLang rewrite code below.
First, the text file:
/blog /news
/blog2 /news/index.bxm 200
# We renamed this in 1921
/pr /pressrelease
/prods/* /products/:splat
/products/* /products/:product
And now the engine:
RW_FILE = './rewrites.txt';
if(!fileExists(RW_FILE)) return;
// load up rewrites and parse it (will cache)
function parseRWFile(contents) {
rules = [];
lines = contents.listToArray('#char(10)##char(13)#');
lines.each(l => {
parts = l.listToArray(char(9));
// must have 2, 3 is supported
if(parts.len() < 2) continue;
rule = {from:parts[1], to:parts[2]};
if(parts.len() === 3) rule.code = parts[3];
rules.append(rule)
});
return rules;
}
rules = parseRWFile(fileRead(RW_FILE));
rules.each(r => {
//straight x to y match
if(cgi.path_info == r.from) {
code = r.code?:301;
// special handling for 200
if(code !== "200") bx:location url=r.to statusCode=code;
else {
// will only work if you redirect to a specifc file, not a directory
// so ie: /something /somethingelse/index.bxm 200
bx:include template=r.to;
abort;
}
}
// something/* to something/:splat
if(r.from.endsWith("*") && r.to.endsWith(":splat")) {
// first, does our current request match r.from
normalizedPart = r.from.replace("*","");
if(cgi.path_info.find(normalizedPart) === 1) {
splat = cgi.path_info.replace(normalizedPart,"");
newLocation = r.to.replace(":splat", splat);
bx:location url=newLocation;
}
} else if(r.from.endsWith("*") && r.to.reFind(":[a-zA-Z]+$")) {
// something/* to something/:name such that something/index.bxm is loaded with request.name == the value
matchedToken = r.to.mid(r.to.reFind(":[a-zA-Z]+$") + 1, r.to.len());
normalizedPart = r.from.replace("*","");
splat = cgi.path_info.replace(normalizedPart,"");
request[matchedToken] = splat;
normalizedLocation = r.to.replace(":#matchedToken#","");
bx:include template="#normalizedLocation#/index.bxm";
abort;
}
});
// handle 404
Photo by Susan Q Yin on Unsplash