Today I’ll demonstrate another cool feature in OpenResty Edge. That is, how to use our rule-based domain-specific language, the Edge language, or Edgelang for short.

Introduction to Edgelang

The user can use Edgelang to write complex gateway rules for custom authentication, request and response rewriting, dynamic upstream routing, and more. The rules usually run much faster than hand-crafted Lua code, for example. The Edgelang compiler emits efficient native code running on gateway servers.

The Edgelang compiler is extremely efficient. It implements many advanced optimization techniques.

It supports combining regular expressions referenced by all the Edgelang rules into a single state machine. This way, it can immediately know which rules and which parts of those rules are matched by scanning the request data only once.

Add a page rule defined using Edgelang

It also supports combining constant string prefix and suffix patterns into single tree data structures across all the Edgelang rules.

Let’s go to a web console of OpenResty Edge. This is our sample deployment of the console. Every user has their own deployment.

We still use our continuing sample Edge application, test-edge.com.

Enter the application.

We have a page rule already defined in a previous tutorial.

This page rule sets up a reverse proxy to an upstream.

We can add our Edgelang code here.

Let’s add our first rule.

First it comes the rule condition part. When the URI is “/foo/”.

Then we use the arrow to complete our condition.

After the arrow, we specify our actions to take when the conditions are met.

This action initiates an HTTP redirect to the “/bar/” page.

Save the rule.

As we can see, the Edgelang specification consists of rules. And each rule comes with two basic parts:

a condition,

and a consequent consisting of actions.

The condition and the consequent are connected by an arrow sequence.

And the whole rule is terminated by a semicolon character.

This is just a simplest rule. We can add as many rules as we like. Each rule can also take many conditions AND’d or OR’d together. And a rule can take many actions in its consequent part.

Let’s make a new configuration release to push out our new changes, as always.

Click this button.

Ship it!

Our new release is now synchronized to all our gateway servers.

Now the new page rule has been pushed to all the gateway clusters and servers.

Our configuration changes do NOT require server reload, restart, or binary upgrade. So it’s very efficient and scalable.

Test

On the terminal, we send an HTTP request to a gateway server resolved by DNS via the curl command-line utility.

curl -I http://test-edge.com/bar/

Note the response header has no redirects.

Next, let’s send an HTTP request with /foo/ URI.

curl -I http://test-edge.com/foo/

Note that the request has been redirected.

It is being redirected to the /bar/ location. Our Edgelang rule works!

Let’s test another URI with the prefix “/foo/”.

The URI takes an extra suffix, “blah/”.

Send the request.

Note that the edgelang rule was not hit. This is because the our Edgelang condition needs to match “/foo/” exactly.

Modify the Edgelang definition of the page rule

Let’s edit the condition in our Edgelang rule to handle such cases properly.

Click the Edit button.

Delete the original condition.

Change it to matching the URI prefix “/foo/”.

Save the rule.

Make a new configuration release again.

Back to the terminal. Let’s send our previous test request again.

It still takes the “blah/” URI suffix.

Send the request.

It triggers a redirect and thus hit our Edgelang rule this time.

Next, let’s send an HTTP request without any extra URI suffixes.

curl -I http://test-edge.com/foo/

It is still a hit.

Define WAF rules using Edgelang

We could use Edgelang in many different places of the web console.

For instance, EdgeLang can be used to add custom rules for WAF, or the Web Application Firewall.

Create a new WAF rule.

Write Edgelang here.

Edgelang user manual

Our self-designed gateway DSL EdgeLang is a very powerful language with many features. It supports calling custom Lua modules and Lua code, or any .so dynamic link library. Its compiler supports cross-rules deep optimization.

Feel free to read our Edgelang User Manual to learn more.

There are many code examples.

And they explain various usage of Edgelang in great detail.

That’s what I’d like to cover today.

If you like this tutorial, please subscribe to this blog site and/or our YouTube channel. Thank you!

About The Author

Yichun Zhang (Github handle: agentzh), is the original creator of the OpenResty^® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty^®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.