Custom route parameters (#368)

Author: tudor-timcu

docs/register-param-matcher.md

@@ -0,0 +1,56 @@
+# Register custom route parameter matchers
+
+Aikido exposes a new function, called `\aikido\register_param_matcher` that can be used to register custom route parameter matchers.
+This allows you to define custom patterns for URL segments that should be treated as route parameters.
+
+## Function signature
+
+```php
+bool \aikido\register_param_matcher(string $param, string $pattern)
+```
+
+- `$param`: The name of the parameter (e.g., "tenant", "org_id"). Must match `[a-zA-Z_]+`.
+- `$pattern`: A pattern string that can contain placeholders like `{digits}` and `{alpha}`.
+- Returns: `true` on success, `false` on failure.
+
+## Supported placeholders
+
+The pattern supports the following placeholders:
+
+- `{digits}` - Matches one or more digits (`\d+`)
+- `{alpha}` - Matches one or more alphabetic characters (`[a-zA-Z]+`)
+
+## Pattern rules
+
+1. The pattern must contain at least one placeholder (e.g., `{digits}` or `{alpha}`).
+2. The pattern cannot contain slashes (`/`).
+3. The pattern cannot contain consecutive similar placeholders (e.g., `{digits}{digits}`).
+
+## Usage example
+
+```php
+<?php
+if (extension_loaded('aikido')) {
+    // Register a custom matcher for tenant IDs (e.g., "aikido-123")
+    \aikido\register_param_matcher("tenant", "aikido-{digits}");
+    
+    // Register a custom matcher for org_ids (e.g., "aikido-foo-123-bar")
+    \aikido\register_param_matcher("org_id", "aikido-{alpha}-{digits}-{alpha}");
+}
+?>
+```
+
+## When to use
+
+This code needs to run with every request, so you can add it in a middleware, as exemplified [here](./should_block_request.md).
+The backend will ignore duplicate registrations, so it's safe to call this function on every request.
+
+## How it works
+
+When Aikido processes URLs to build route patterns, it will check registered custom param matchers first.
+If a URL segment matches a custom pattern, it will be replaced with `:param_name` in the route. For example:
+
+- URL: `/posts/aikido-123` → Route: `/posts/:tenant` (if "tenant" matcher is registered)
+- URL: `/blog/aikido-foo-123-bar` → Route: `/blog/:org_id` (if "org_id" matcher is registered)
+
+If no custom matcher matches, Zen falls back to its default matchers (numbers, UUIDs, dates, etc.).

lib/API.h

@@ -7,6 +7,7 @@ enum EVENT_ID {
     EVENT_POST_REQUEST,
     EVENT_SET_USER,
     EVENT_SET_RATE_LIMIT_GROUP,
+    EVENT_REGISTER_PARAM_MATCHER,
     EVENT_GET_AUTO_BLOCKING_STATUS,
     EVENT_GET_BLOCKING_STATUS,
     EVENT_PRE_OUTGOING_REQUEST,
@@ -42,6 +43,9 @@ enum CALLBACK_ID {
     FUNCTION_NAME,
     STACK_TRACE,
 
+    PARAM_MATCHER_PARAM,
+    PARAM_MATCHER_REGEX,
+
     OUTGOING_REQUEST_URL,
     OUTGOING_REQUEST_EFFECTIVE_URL,  // Effective URL after redirects (the final
                                      // URL were the request was actually made)

lib/php-extension/Action.cpp

@@ -37,6 +37,12 @@ ACTION_STATUS Action::executeStore(json &event) {
     return CONTINUE;
 }
 
+ACTION_STATUS Action::executeWarningMessage(json &event) {
+    std::string message = event["message"];
+    php_printf("%s\n", message.c_str());
+    return WARNING_MESSAGE;
+}
+
 ACTION_STATUS Action::Execute(std::string &event) {
     if (event.empty()) {
         return CONTINUE;
@@ -54,6 +60,8 @@ ACTION_STATUS Action::Execute(std::string &event) {
         return executeExit(eventJson);
     } else if (actionType == "store") {
         return executeStore(eventJson);
+    } else if (actionType == "warning_message") {
+        return executeWarningMessage(eventJson);
     }
     return CONTINUE;
 }

lib/php-extension/Aikido.cpp

@@ -47,7 +47,7 @@ PHP_MSHUTDOWN_FUNCTION(aikido) {
 
     /*
         In the case of Apache mod-php servers, the MSHUTDOWN can be called multiple times.
-        As a consequence, we need to do the unhooking / uninitialization logic based on the current 
+        As a consequence, we need to do the unhooking / uninitialization logic based on the current
         PID for which the MSHUTDOWN is called. This logic is part of phpLifecycle.ModuleShutdown().
         The same does not apply for CLI mode, where the MSHUTDOWN is called only once.
     */
@@ -59,7 +59,7 @@ PHP_MSHUTDOWN_FUNCTION(aikido) {
 
 PHP_RINIT_FUNCTION(aikido) {
     ScopedTimer scopedTimer("request_init", "request_op");
-    
+
     phpLifecycle.RequestInit();
     AIKIDO_LOG_DEBUG("RINIT finished!\n");
     return SUCCESS;
@@ -93,6 +93,7 @@ static const zend_function_entry ext_functions[] = {
     ZEND_NS_FE("aikido", auto_block_request, arginfo_aikido_auto_block_request)
     ZEND_NS_FE("aikido", set_token, arginfo_aikido_set_token)
     ZEND_NS_FE("aikido", set_rate_limit_group, arginfo_aikido_set_rate_limit_group)
+    ZEND_NS_FE("aikido", register_param_matcher, arginfo_aikido_register_param_matcher)
     ZEND_FE_END
 };
 

lib/php-extension/GoWrappers.cpp

@@ -128,6 +128,14 @@ char* GoContextCallback(int callbackId) {
                 ctx = "STACK_TRACE";
                 ret = GetStackTrace();
                 break;
+            case PARAM_MATCHER_PARAM:
+                ctx = "PARAM_MATCHER_PARAM";
+                ret = eventCache.paramMatcherParam;
+                break;
+            case PARAM_MATCHER_REGEX:
+                ctx = "PARAM_MATCHER_REGEX";
+                ret = eventCache.paramMatcherRegex;
+                break;
         }
     } catch (std::exception& e) {
         AIKIDO_LOG_DEBUG("Exception in GoContextCallback: %s\n", e.what());

lib/php-extension/HandleRegisterParamMatcher.cpp

@@ -0,0 +1,43 @@
+#include "Includes.h"
+
+ZEND_FUNCTION(register_param_matcher) {
+    ScopedTimer scopedTimer("register_param_matcher", "aikido_op");
+
+    if (AIKIDO_GLOBAL(disable) == true) {
+        RETURN_BOOL(false);
+    }
+
+    char *param = nullptr;
+    size_t paramLength = 0;
+    char *regex = nullptr;
+    size_t regexLength = 0;
+
+    ZEND_PARSE_PARAMETERS_START(2, 2)
+        Z_PARAM_STRING(param, paramLength)
+        Z_PARAM_STRING(regex, regexLength)
+    ZEND_PARSE_PARAMETERS_END();
+
+    if (!param || paramLength == 0 || !regex || regexLength == 0) {
+        AIKIDO_LOG_ERROR("register_param_matcher: param or regex is null or empty!\n");
+        RETURN_BOOL(false);
+    }
+
+    eventCache.paramMatcherParam = std::string(param, paramLength);
+    eventCache.paramMatcherRegex = std::string(regex, regexLength);
+
+    try {
+        std::string outputEvent;
+        requestProcessor.SendEvent(EVENT_REGISTER_PARAM_MATCHER, outputEvent);
+        if (action.Execute(outputEvent) == WARNING_MESSAGE) {
+            // If a warning message is returned, it means that the parameters are invalid, so we return false.
+            RETURN_BOOL(false);
+        }
+
+    } catch (const std::exception& e) {
+        AIKIDO_LOG_ERROR("Exception encountered in processing register param matcher event: %s\n", e.what());
+        RETURN_BOOL(false);
+    }
+
+    AIKIDO_LOG_INFO("Registered param matcher %s -> %s\n", eventCache.paramMatcherParam.c_str(), eventCache.paramMatcherRegex.c_str());
+    RETURN_BOOL(true);
+}

lib/php-extension/config.m4

@@ -90,5 +90,5 @@ if test "$PHP_AIKIDO" != "no"; then
   dnl In case of no dependencies
   AC_DEFINE(HAVE_AIKIDO, 1, [ Have aikido support ])
 
-  PHP_NEW_EXTENSION(aikido, Aikido.cpp GoWrappers.cpp Packages.cpp PhpWrappers.cpp PhpLifecycle.cpp Stats.cpp Server.cpp Environment.cpp RequestProcessor.cpp Agent.cpp Hooks.cpp HookAst.cpp Utils.cpp Handle.cpp HandleUrls.cpp HandleSetToken.cpp HandleUsers.cpp HandleShouldBlockRequest.cpp HandleRateLimitGroup.cpp Cache.cpp HandleFileCompilation.cpp HandleShellExecution.cpp Log.cpp HandleQueries.cpp HandlePathAccess.cpp Action.cpp, $ext_shared)
+  PHP_NEW_EXTENSION(aikido, Aikido.cpp GoWrappers.cpp Packages.cpp PhpWrappers.cpp PhpLifecycle.cpp Stats.cpp Server.cpp Environment.cpp RequestProcessor.cpp Agent.cpp Hooks.cpp HookAst.cpp Utils.cpp Handle.cpp HandleUrls.cpp HandleSetToken.cpp HandleRegisterParamMatcher.cpp HandleUsers.cpp HandleShouldBlockRequest.cpp HandleRateLimitGroup.cpp Cache.cpp HandleFileCompilation.cpp HandleShellExecution.cpp Log.cpp HandleQueries.cpp HandlePathAccess.cpp Action.cpp, $ext_shared)
 fi

lib/php-extension/include/Action.h

@@ -5,7 +5,8 @@
 enum ACTION_STATUS {
     CONTINUE,
     BLOCK,
-    EXIT
+    EXIT,
+    WARNING_MESSAGE
 };
 
 class Action {
@@ -24,6 +25,8 @@ class Action {
 
         ACTION_STATUS executeStore(json &event);
 
+        ACTION_STATUS executeWarningMessage(json &event);
+
     public:
         Action() = default;
         ~Action() = default;

lib/php-extension/include/Cache.h

@@ -31,6 +31,9 @@ class EventCache {
     std::string sqlQuery;
     std::string sqlDialect;
 
+    std::string paramMatcherParam;
+    std::string paramMatcherRegex;
+
     EventCache() = default;
     void Reset();
 };

lib/php-extension/include/HandleRegisterParamMatcher.h

@@ -0,0 +1,8 @@
+#include "Includes.h"
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_aikido_register_param_matcher, 0, 2, _IS_BOOL, 0)
+    ZEND_ARG_TYPE_INFO(0, param, IS_STRING, 0)
+    ZEND_ARG_TYPE_INFO(0, regex, IS_STRING, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_FUNCTION(register_param_matcher);