Upgrade to 6.0.0 removed urlrewrite.xml; question about new "JBoss Undertow Predicate Language" rewrite format and examples

Communities CommandBox CLI
1

Good evening. An unexpected upgrade to 6.0.0 (using sudo apt update) seems to have inadvertently replaced my modified urlrewrite.xml with a fresh, default version. No biggie, I can re-add the Tuckey <rule> again.

But … when I visit the documentation (URL Rewrites) to refresh myself on the subject, I’m seeing a suggestion that I move away from Tuckey-based rewrites and start adopting “Server Rules.”

I am seeing this is a new capability and apparently the future of CommandBox. However, I am really struggling to find straightforward information about URL rewrite capability with this “JBoss Undertow Predicate Language” online. From everything I can read and see, this is not something I can “read up” about – because JBoss Undertow Predicate Language is not just a simple coding language with examples. Instead, it seems CommandBox is providing a layer of abstraction over lower-level the JBoss Undertow server engine.

If so, I am wondering if the CommandBox documentation could be significantly expanded to better demonstrate the various approaches to URL rewrites? URL rewrites are pretty important, but it seems like (and I am not an expert by any means here, just a hobbyist, so I acknowledge I could be completely misunderstanding this) CommandBox is basically coming up with an entirely new, novel approach to URL rewrites, which seems largely undocumented save for one or two examples.

I’m OK with just continuing to use the Tuckey rewrites, I mean, they’re simple, they’re extremely well documented and understandable. But if the long-term plan is to phase Tuckey out and move to this proprietary, unique URL rewrite method for which I can find no other examples of usage on the internet, I could sure use a lot more examples of how to set up URL rewrites. You can see from this Google search that, basically, this method is not something with lots of documentation/support.

But, again, this Jboss Undertow Predicate Language is something totally new to me, and I recognize I may be totally misunderstanding it.

2

Why was it unexpected? apt update installs the latest version of packages, no?

Where on disk was this file? A new version of CommandBox should never touch any files inside your web roots. Now, if you had for some reason modified the core rewrite file that’s inside of CommandBox itself, well yes, any upgrade to CommandBox would wipe that out. But hopefully you weren’t modifying the core files of CommandBox when Tuckey allows you to point to a custom file.

Not really. We added it 4 years ago in the 5.2 release.

Yeah, Undertow’s docs aren’t great. I do link to them directly from the Server Rule docs, so I’d suggest just following that link. Also, most use of Undertow in the wild is inside of JBoss Wildfly, so searching for wildfly and predicate language will probably yield more Google hits.

Why not? Did you start by reading the part of the CommandBox docs that cover them?

I would think after completing those pages, you’d have a good handle on how they work.

Actually it is. It’s a pretty simple DSL that reads like a scripting language. It’s not perfect, but it’s easier to read than mod_rewrite directives, lol.

Nope. They are exposed directly in all of their glory. I just use the word “server rules” in my docs because “predicate language” sounds a bit scary IMO. CommandBox doesn’t do any pre-processing of the language-- it’s just passed straight to Undertow for parsing.

You mean other than the pages I linked ago above? You’ll need to be more specific in the example(s) you don’t feel are covered.

No, not really. Undertow has supported the prediate language since version 2.0, which was released 7 years ago in 2017. I’m mean, you don’t have to use them, but it’s not like other servlet containers like Tomcat or Jetty really provide anything that compares so I’m not sure why you’re complaining so much about them.

Again, I’m not sure why you’d say that. There’s the CommandBox docs (whose page of examples includes 24 examples, not a “one or two”), there’s the official Undertow docs I link to from the CommandBox docs which has quite a bit of information. There’s even screencasts on cfcasts that cover these: https://cfcasts.com/series/mastering-commandbox-5/videos/server-rules

Yeah, I wouldn’t go that far, lol. Tuckey’s docs are that much better than Undertow’s, there’s little info online about them, and the software is literally abandonware-- until late last year, it hadn’t had a release in 14 years (2012)!!

What exactly makes JBoss Undertow’s predicate language “proprietary”? It is a popular, enterprise, open source application maintained by a team of paid developers employed by a Fortune 100 company. Tuckey is literally a random library a single dude (Paul Tuckey) wrote back in 2005 and then mostly abandoned.

If you spent a fraction of the time you took to post above asked a specific answerable question, then I could have probably helped you by now. After reading all the material I’ve posted above, what still doesn’t make sense? Which examples don’t you see? What have you tried? How didn’t it work? Did you debug it as outlined in the docs?

3

Good afternoon. Perhaps I should have clarified that I did thoroughly read the CommandBox documentation (as I always do) prior to making a post, and part of the reason I made the post is because I found the documentation difficult to understand, and felt it might be worthwhile to recommend potential improvements to help others who may encounter the same difficulties.

I also didn’t post a question about my specific URL rewrite problem, because I know that folks are busy and don’t need to handhold my one-off, custom requirements. I instead felt like it would be more beneficial to address the root location for learning and knowledge, the documentation, which I’ve been really clear to say has been personally confusing in my opinion, which might indicate challenges for others, too.

Part of the challenge I’m having is that the apparent flexibility and power of “Server Rules” encompasses significant amounts of combinations, while my need is much more targeted and simple: URL rewrites. I see some information about URL rewrites in the Server Rules documentation, but it’s mixed in among items about changing headers, cookies, blocking IPs, “rewrites map,” etc. Basically, alllll kinds of server rules.

But, there is very little about URL rewrites, themselves, and in fact the actual URL rewrite documentation is still mostly focused on Tuckey rewrites.

I think where I am challenged is that there is no clear explanation of the syntax for the Server Rule-based URL rewrites, nor any suggestions on places to learn more about the syntax for the rewrites. I am sure that the “JBoss Undertow Predicate Language” is very powerful and capable, but, if it’s going to be the primary method for certain functions, like URL rewrites (even, apparently, replacing Tuckey at some point), I think some additional explanation on the application of that function is going to be necessary for people to understand it.

Here’s a good example of what I’m talking about: on the existing CommandBox URL rewrite documentation, there is a note with an external link that exhaustively documents the nature of how to handle URL rewrites. This was very helpful when I needed to learn more about the syntax for writing my URL rewrites in Tuckey. Here’s something similar for Apache. And, of course, there are hundreds of StackOverflow and other examples all over the internet to reference and learn from.

A similar link / knowledge base does not exist for the JBoss Undertow Predicate Language CommandBox Server Rules URL rewrites function. Right now, mostly, there’s the “Rule Examples” page, which is nice, but not really a good guide about syntax.

Often I write these posts and they seem to be received as if I am accusing developers of being “wrong” about something, or that I am seeking confrontation and arguments. I am simply trying to help and offer a perspective from the outside about challenges I’m encountering, with the hope that it will benefit others who may encounter the same challenges. I try to read people’s posts from a position of grace, understanding and knowledge-sharing; it’s more beneficial for all.

As to the challenge I am facing, personally and specifically, is this: how to rewrite this kind of URL:

/directory/param1/param2/

Into this kind of URL:

/differentdirectory/file.cfm?a=param1&b=param2

I can find gobs of information online about Apache rewrites for this, and even some for Tuckey rewrites. ChatGPT can even do this in a fraction of a second. I do not know where to look to learn more about how to do this in JBoss Undertow Predicate Language Server Rules for CommandBox.

Any suggestions on places to look for this kind of information would personally be very welcome and appreciated, and it seems very likely to benefit others, too. If there isn’t much existing information about this, then it seems very prudent to develop detailed documentation for its usage in CommandBox, particularly because this seems to be the future of URL rewrites for this software.

4

The following rule will do this:

{
    "web":{
        "rules":[
            "regex-nocase( '^/directory/(.*)/(.*)/' ) -> rewrite( '/differentdirectory/file.cfm?a=\\$1&b=\\$2' )"
        ]
    }
}

image

Note, the “pure” form of that handler is just rewrite( '/differentdirectory/file.cfm?a=$1&b=$2' ) but the dollar signs need escaped once to not be processed as a system setting expansion in the JSON file, and escaped a second time since it’s a backslash in a JSON string, thus the two backslashes. One of the downsides of JSON config, and also why CommandBox allows server rules to be specified in text files as well.

Both the regex predicate and rewrite handler are covered in the CommandBox docs and the Undertow docs and have examples of them

An alternative version of the rule would be this, which has the same result as the screenshot above:

{
    "web":{
        "rules":[
            "path-template( '/directory/{a}/{b}/' ) -> rewrite( '/differentdirectory/file.cfm?a=\\$a&b=\\$b' )"
        ]
    }
}

It provides better readability than regex (named capture groups and all). but the main downside of the path-template() predicate is it’s case sensitive.

And the corresponding link to Undertow’s docs are right here as stated before:

image
image923×812 66.6 KB

That’s really apples and oranges. If you want to use Apache, then go use Apache. But Apache, Nginx, and IIS are behemoths in the web server world and are going to have a million times more info than any servlet container out there also offering rewrites. In fact, most servlets don’t even offer it. I can’t control what’s on Google, but sticking with Tuckey just isn’t possible. It’s buggy abandonware with a single AWOL maintainer. If you are more comfortable using Apache, please go on ahead.

The CommandBox docs are open source in a simple markdown format on GitHub. I recommend you send pull requests for whatever additional sections or examples you feel are missing. You haven’t really provided any actionable feedback other than not seeing a page dedicated to your very specific example, but that’s just not going to happen. I have to write docs that cater to everyone’s use cases, not just yours. I’ll merge any pulls you send:

5

Good afternoon, @bdw429s. Thank you for writing back, and providing an example for my specific need. However, you said this:

I am sorry that I haven’t been clear enough throughout this thread that I have not and would not ask for this. URL rewrites, generally, are not a unique use case that I, alone, have.

I think my struggle with the CommandBox documentation is that the particular function of “URL rewrites” using Server Rules is just not really well-described. Instead, the documentation seems to really focus in on the nature of using Jboss Undertow Predicate Language in Server Rules broadly, sort of de-contextualized from the specifics of its application. I’d also argue that the Undertow docs also take this approach, speaking broadly to the syntax of the handler/predicate/exchange attribute components, not necessarily to their application (the link you provided, if printed, is a 92 page document and the phrase “url rewrite” shows up only one time).

The CommandBox documentation seems, to me, to be an introduction to the broader usage of the language – not to the practical application of the language. It would be like relying on your “Usage >> Commands” and “Usage >> Parameters” pages to learn how to use CommandBox.

I’d argue that it’s important, of course, to cover the broad language, but also important to be intentional about the ways that broader language is used to accomplish specific requirements. For example, if wanting to learn about URL rewrites in CommandBox, the URL rewrites documentation page should probably have some basic information about the various ways to do URL rewrites, maybe with a few common examples in the JBoss Undertow Predicate Language. And maybe some resources on ways that JBoss Undertow Predicate Language handles rewrites. I don’t think this kind of practical application is really available on the internet. I just think CommandBox might need to document it.

The current Examples page seems geared more towards explaining the nature of handler/predicate/exchange attribute, broadly. Not specifically. And by “specific,” I don’t mean, “my unique use case,” I mean, “the specifics of handlers” and “the specifics of predicates.” Specifics like, “this is what URL rewrites look like in Jboss Undertow Predicate Language Server Rules.” Not, “this is what Jboss Undertow Predicate Language Server Rules look like, broadly, with handlers, predicates and attributes, and here’s 20 random examples.,”

As to making recommendations for how to change the documentation, well, if I knew how to write the documentation, I wouldn’t be asking the question, here. I am not a Jboss Undertow Predicate Language developer, anything I would write would be nonsense and useless. That’s why I asked. I just wanted to point out in the most non-confrontational way that I can that I, personally found it very challenging to understand how to accomplish URL rewrites using the new Server Rules method, and it was not for lack of trying and reading. The specific use case of Jboss Undertow Predicate Language in URL rewrites in the CommandBox Server Rules method is, obviously, not well-documented. I humbly suggest that, to save others from the same struggle, that the documentation be expanded to be inclusive of the ways the Jboss Undertow Predicate Language Server Rules be applied to various common use cases. Perhaps you disagree, and that’s fine, but I wanted to share my perspective as an end user and you can take it for what it is.