Subversion Repositories ESP8266_P1_Meter

Rev

Blame | Last modification | View Log | RSS feed 

# AsyncURIMatcher Example

This example demonstrates the comprehensive URI matching capabilities of the ESPAsyncWebServer library using the `AsyncURIMatcher` class.

## Overview

The `AsyncURIMatcher` class provides flexible and powerful URL routing mechanisms that go beyond simple string matching. It supports various matching strategies that can be combined to create sophisticated routing rules.

**Important**: When using plain strings (not `AsyncURIMatcher` objects), the library uses auto-detection (`URIMatchAuto`) which analyzes the URI pattern and applies appropriate matching rules. This is **not** simple exact matching - it combines exact and folder matching by default!

## What's Demonstrated

This example includes two Arduino sketches:

1. **URIMatcher.ino** - Interactive web-based demonstration with a user-friendly homepage
2. **URIMatcherTest.ino** - Comprehensive test suite with automated shell script testing

Both sketches create a WiFi Access Point (`esp-captive`) for easy testing without network configuration.

## Auto-Detection Behavior

When you pass a plain string or `const char*` to `server.on()`, the `URIMatchAuto` flag is used, which:

1. **Empty URI**: Matches everything
2. **Ends with `*`**: Becomes prefix match (`URIMatchPrefix`)
3. **Contains `/*.ext`**: Becomes extension match (`URIMatchExtension`)
4. **Starts with `^` and ends with `$`**: Becomes regex match (if enabled)
5. **Everything else**: Becomes **both** exact and folder match (`URIMatchPrefixFolder | URIMatchExact`)

This means traditional string-based routes like `server.on("/path", handler)` will match:

- `/path` (exact match)
- `/path/` (folder with trailing slash)
- `/path/anything` (folder match)

But will **NOT** match `/path-suffix` (prefix without folder separator).

## Features Demonstrated

### 1. **Auto-Detection (Traditional Behavior)**

Demonstrates how traditional string-based routing automatically combines exact and folder matching.

**Examples in URIMatcher.ino:**

- `/auto` - Matches both `/auto` exactly AND `/auto/sub` as folder
- `/wildcard*` - Auto-detects as prefix match (due to trailing `*`)
- `/auto-images/*.png` - Auto-detects as extension match (due to `/*.ext` pattern)

**Examples in URIMatcherTest.ino:**

- `/exact` - Matches `/exact`, `/exact/`, and `/exact/sub`
- `/api/users` - Matches exact path and subpaths under `/api/users/`
- `/*.json` - Matches any `.json` file anywhere
- `/*.css` - Matches any `.css` file anywhere

### 2. **Exact Matching (Factory Method)**

Using `AsyncURIMatcher::exact()` matches only the exact URL, **NOT** subpaths.

**Key difference from auto-detection:** `AsyncURIMatcher::exact("/path")` matches **only** `/path`, while `server.on("/path", ...)` matches both `/path` and `/path/sub`.

**Examples in URIMatcher.ino:**

- `AsyncURIMatcher::exact("/exact")` - Matches only `/exact`

**Examples in URIMatcherTest.ino:**

- `AsyncURIMatcher::exact("/factory/exact")` - Matches only `/factory/exact`
- Does NOT match `/factory/exact/sub` (404 response)

### 3. **Prefix Matching**

Using `AsyncURIMatcher::prefix()` matches URLs that start with the specified pattern.

**Examples in URIMatcher.ino:**

- `AsyncURIMatcher::prefix("/service")` - Matches `/service`, `/service-test`, `/service/status`

**Examples in URIMatcherTest.ino:**

- `AsyncURIMatcher::prefix("/factory/prefix")` - Matches `/factory/prefix`, `/factory/prefix-test`, `/factory/prefix/sub`
- Traditional: `/api/*` - Matches `/api/data`, `/api/v1/posts`
- Traditional: `/files/*` - Matches `/files/document.pdf`, `/files/images/photo.jpg`

### 4. **Folder/Directory Matching**

Using `AsyncURIMatcher::dir()` matches URLs under a directory (automatically adds trailing slash).

**Important:** Directory matching requires a trailing slash in the URL - it does NOT match the directory itself.

**Examples in URIMatcher.ino:**

- `AsyncURIMatcher::dir("/admin")` - Matches `/admin/users`, `/admin/settings`
- Does NOT match `/admin` without trailing slash

**Examples in URIMatcherTest.ino:**

- `AsyncURIMatcher::dir("/factory/dir")` - Matches `/factory/dir/users`, `/factory/dir/sub/path`
- Does NOT match `/factory/dir` itself (404 response)

### 5. **Extension Matching**

Using `AsyncURIMatcher::ext()` matches files with specific extensions.

**Examples in URIMatcher.ino:**

- `AsyncURIMatcher::ext("/images/*.jpg")` - Matches `/images/photo.jpg`, `/images/sub/pic.jpg`

**Examples in URIMatcherTest.ino:**

- `AsyncURIMatcher::ext("/factory/files/*.txt")` - Matches `/factory/files/doc.txt`, `/factory/files/sub/readme.txt`
- Does NOT match `/factory/files/doc.pdf` (wrong extension)

### 6. **Case Insensitive Matching**

Using `AsyncURIMatcher::CaseInsensitive` flag matches URLs regardless of character case.

**Examples in URIMatcher.ino:**

- `AsyncURIMatcher::exact("/case", AsyncURIMatcher::CaseInsensitive)` - Matches `/case`, `/CASE`, `/CaSe`

**Examples in URIMatcherTest.ino:**

- Case insensitive exact: `/case/exact`, `/CASE/EXACT`, `/Case/Exact` all work
- Case insensitive prefix: `/case/prefix`, `/CASE/PREFIX-test`, `/Case/Prefix/sub` all work
- Case insensitive directory: `/case/dir/users`, `/CASE/DIR/admin`, `/Case/Dir/settings` all work
- Case insensitive extension: `/case/files/doc.pdf`, `/CASE/FILES/DOC.PDF`, `/Case/Files/Doc.Pdf` all work

### 7. **Regular Expression Matching**

Using `AsyncURIMatcher::regex()` for advanced pattern matching (requires `ASYNCWEBSERVER_REGEX`).

**Examples in URIMatcher.ino:**

```cpp
#ifdef ASYNCWEBSERVER_REGEX
AsyncURIMatcher::regex("^/user/([0-9]+)$")  // Matches /user/123, captures ID
#endif
```

**Examples in URIMatcherTest.ino:**

- Traditional regex: `^/user/([0-9]+)$` - Matches `/user/123`, `/user/456`
- Traditional regex: `^/blog/([0-9]{4})/([0-9]{2})/([0-9]{2})$` - Matches `/blog/2023/10/15`
- Factory regex: `AsyncURIMatcher::regex("^/factory/user/([0-9]+)$")` - Matches `/factory/user/123`
- Factory regex with multiple captures: `^/factory/blog/([0-9]{4})/([0-9]{2})/([0-9]{2})$`
- Case insensitive regex: `AsyncURIMatcher::regex("^/factory/search/(.+)$", AsyncURIMatcher::CaseInsensitive)`

### 8. **Combined Flags**

Multiple matching strategies can be combined using the `|` operator.

**Examples in URIMatcher.ino:**

- `AsyncURIMatcher::prefix("/MixedCase", AsyncURIMatcher::CaseInsensitive)` - Prefix match that's case insensitive

### 9. **Special Matchers**

**Examples in URIMatcherTest.ino:**

- `AsyncURIMatcher::all()` - Matches all requests (used with POST method as catch-all)

## Usage Patterns

### Traditional String-based Routing (Auto-Detection)

```cpp
// Auto-detection with exact + folder matching
server.on("/api", handler);          // Matches /api AND /api/anything
server.on("/login", handler);        // Matches /login AND /login/sub

// Auto-detection with prefix matching
server.on("/prefix*", handler);      // Matches /prefix, /prefix-test, /prefix/sub

// Auto-detection with extension matching
server.on("/images/*.jpg", handler); // Matches /images/pic.jpg, /images/sub/pic.jpg
```

### Explicit AsyncURIMatcher Syntax

### Explicit AsyncURIMatcher Syntax

```cpp
// Exact matching only
server.on(AsyncURIMatcher("/path", URIMatchExact), handler);

// Prefix matching only
server.on(AsyncURIMatcher("/api", URIMatchPrefix), handler);

// Combined flags
server.on(AsyncURIMatcher("/api", URIMatchPrefix | URIMatchCaseInsensitive), handler);
```

### Factory Functions

```cpp
// More readable and expressive
server.on(AsyncURIMatcher::exact("/login"), handler);
server.on(AsyncURIMatcher::prefix("/api"), handler);
server.on(AsyncURIMatcher::dir("/admin"), handler);
server.on(AsyncURIMatcher::ext("/images/*.jpg"), handler);

#ifdef ASYNCWEBSERVER_REGEX
server.on(AsyncURIMatcher::regex("^/user/([0-9]+)$"), handler);
#endif
```

## Available Flags

| Flag                      | Description                                                 |
| ------------------------- | ----------------------------------------------------------- |
| `URIMatchAuto`            | Auto-detect match type from pattern (default)               |
| `URIMatchExact`           | Exact URL match                                             |
| `URIMatchPrefix`          | Prefix match                                                |
| `URIMatchPrefixFolder`    | Folder prefix match (requires trailing /)                   |
| `URIMatchExtension`       | File extension match pattern                                |
| `URIMatchCaseInsensitive` | Case insensitive matching                                   |
| `URIMatchRegex`           | Regular expression matching (requires ASYNCWEBSERVER_REGEX) |

## Testing the Example

1. **Upload the sketch** to your ESP32/ESP8266
2. **Connect to WiFi AP**: `esp-captive` (no password required)
3. **Navigate to**: `http://192.168.4.1/`
4. **Explore the examples** by clicking the organized test links
5. **Monitor Serial output**: Open Serial Monitor to see detailed debugging information for each matched route

### Test URLs Available (All Clickable from Homepage)

**Auto-Detection Examples:**

- `http://192.168.4.1/auto` (exact + folder match)
- `http://192.168.4.1/auto/sub` (folder match - same handler!)
- `http://192.168.4.1/wildcard-test` (auto-detected prefix)
- `http://192.168.4.1/auto-images/photo.png` (auto-detected extension)

**Factory Method Examples:**

- `http://192.168.4.1/exact` (AsyncURIMatcher::exact)
- `http://192.168.4.1/service/status` (AsyncURIMatcher::prefix)
- `http://192.168.4.1/admin/users` (AsyncURIMatcher::dir)
- `http://192.168.4.1/images/photo.jpg` (AsyncURIMatcher::ext)

**Case Insensitive Examples:**

- `http://192.168.4.1/case` (lowercase)
- `http://192.168.4.1/CASE` (uppercase)
- `http://192.168.4.1/CaSe` (mixed case)

**Regex Examples (if ASYNCWEBSERVER_REGEX enabled):**

- `http://192.168.4.1/user/123` (captures numeric ID)
- `http://192.168.4.1/user/456` (captures numeric ID)

**Combined Flags Examples:**

- `http://192.168.4.1/mixedcase-test` (prefix + case insensitive)
- `http://192.168.4.1/MIXEDCASE/sub` (prefix + case insensitive)

### Console Output

Each handler provides detailed debugging information via Serial output:

```
Auto-Detection Match (Traditional)
Matched URL: /auto
Uses auto-detection: exact + folder matching
```

```
Factory Exact Match
Matched URL: /exact
Uses AsyncURIMatcher::exact() factory function
```

```
Regex Match - User ID
Matched URL: /user/123
Captured User ID: 123
This regex matches /user/{number} pattern
```

## Compilation Options

### Enable Regex Support

To enable regular expression matching, compile with:

```
-D ASYNCWEBSERVER_REGEX
```

In PlatformIO, add to `platformio.ini`:

```ini
build_flags = -D ASYNCWEBSERVER_REGEX
```

In Arduino IDE, add to your sketch:

```cpp
#define ASYNCWEBSERVER_REGEX
```

## Performance Considerations

1. **Exact matches** are fastest
2. **Prefix matches** are very efficient
3. **Regex matches** are slower but most flexible
4. **Case insensitive** matching adds minimal overhead
5. **Auto-detection** adds slight parsing overhead at construction time

## Real-World Applications

### REST API Design

```cpp
// API versioning
server.on(AsyncURIMatcher::prefix("/api/v1"), handleAPIv1);
server.on(AsyncURIMatcher::prefix("/api/v2"), handleAPIv2);

// Resource endpoints with IDs
server.on(AsyncURIMatcher::regex("^/api/users/([0-9]+)$"), handleUserById);
server.on(AsyncURIMatcher::regex("^/api/posts/([0-9]+)/comments$"), handlePostComments);
```

### File Serving

```cpp
// Serve different file types
server.on(AsyncURIMatcher::ext("/assets/*.css"), serveCSSFiles);
server.on(AsyncURIMatcher::ext("/assets/*.js"), serveJSFiles);
server.on(AsyncURIMatcher::ext("/images/*.jpg"), serveImageFiles);
```

### Admin Interface

```cpp
// Admin section with authentication
server.on(AsyncURIMatcher::dir("/admin"), handleAdminPages);
server.on(AsyncURIMatcher::exact("/admin"), redirectToAdminDashboard);
```

## See Also

- [ESPAsyncWebServer Documentation](https://github.com/ESP32Async/ESPAsyncWebServer)
- [Regular Expression Reference](https://en.cppreference.com/w/cpp/regex)
- Other examples in the `examples/` directory