URL patterns¶

We want to be able to apply different rules and custom scripts for different websites. However, merely specifying "do this for https://example.com" is not enough. Single site's pages might differ strongly and require different custom scripts to be loaded. However, always matching against a full URL like https://example.com/something/somethingelse doesn't allow us to properly handle a site that serves similar pages for multiple values substituted for somethingelse.

• Table of contents
• URL patterns
  • Currently employed solution
    • Domain wildcards
    • Path wildcards
      • Future behavior (since version 1.0)
    • Future additions
    • Wildcard priorities and querying
    • Limits
  • Alternative solution: mimicking web server mechanics

Currently employed solution¶

Wildcards are being used to address the problem. Each page entry in Haketilo settings has a URL pattern that specifies to which internet pages it applies. A URL pattern can be as as simple as literal URL in which case it only matches itself. It can also contain wildcards in the form of one or more asterisks (*) that correspond to multiple possible strings occurring in that place.

Wildcards can appear in URL's domain and path that follows it. These 2 types of wildcards are handled separately.

Domain wildcards¶

A domain wildcard takes the form of one, two or three asterisks occurring in place of a single domain name segment at the beginning (left). Depending on the number of asterisks, the meaning is as follows:

• no asterisks (e.g. example.com) - match domain name exactly (e.g. example.com)
• one asterisk (e.g. *.example.com) - match all domains resulting from substituting * with a single segment (e.g. banana.example.com or pineapple.example.com but not pineapple.pen.example.com nor example.com)
• two asterisks (e.g. **.example.com) - match all domains resulting from substituting ** with two or more segments (e.g. monad.breakfast.example.com or pure.monad.breakfast.example.com but not cabalhell.example.com nor example.com)
• three asterisks (e.g. ***.example.com) - match all domains resulting from substituting *** with zero or more segments (e.g. hello.parkmeter.example.com or iliketrains.example.com or example.com)

Path wildcards¶

A path wildcard takes the form of one, two or three asterisks occurring in place of a single path segment at the end of path (right). Depending on the number of asterisks, the meaning is as follows:

• no asterisks (e.g. /joke/clowns) - match path exactly (e.g. /joke/clowns)
• one asterisk (e.g. /itscalled/*) - match all paths resulting from substituting * with a single segment (e.g. /itscalled/gnulinux or /itscalled/glamp but not /itscalled/ nor /itscalled/gnu/linux)
• two asterisks (e.g. /another/**) - match all paths resulting from substituting ** with two or more segments (e.g. /another/nsa/backdoor or /another/best/programming/language but not /another/apibreak nor /another)
• three asterisks (e.g. /mail/dmarc/***) - match all paths resulting from substituting *** with zero or more segments (e.g. /mail/dmarc/spf, /mail/dmarc or /mail/dmarc/dkim/failure but not /mail/)

Additionally, any path with literal trailing asterisks is matched by itself, even if such pattern would otherwise be treated as wildcard (e.g. /gobacktoxul/** matches /gobacktoxul/**). This is likely to change in the future and would best not be relied upon. Appending three additional asterisks to path pattern to represent literal asterisks is being considered.

Future behavior (since version 1.0)¶

If pattern ends without a trailing slash, it mathes paths with any number of trailing slashes, including zero. If pattern ends with a trailing slash, it only mathes paths with one or more trailing slashes. For example, /itscalled/* matches /itscalled/gnulinux, /itscalled/gnulinux/ and /itscalled/gnulinux// while /itscalled/*/ only matches /itscalled/gnulinux/ and /itscalled/gnulinux// out of those three.

If two patterns only differ by the presence of a trailing slash, pattern with a trailing slash is considered more specific.

Future additions¶

Right now a URL's query string is being completely disregarded for the purpose of matching the URL patterns. In the future, support for matching URLs with specific query parameters and maybe even HTTP(s) requests with specific POST parameters or specific cookies might me added.

Currently, protocols in the URL are matched exactly. Making protocol wildcard might make little sense because sites are very unlikely to be serving similar content over for example http:// and ftp://. However, support for some wildcard protocol that matches both http:// and https:// might be added in the future.

The wildcards that have been added so far were designed to allow a reasonable level of flexibility, considering some common ways websites are served. However, only practice can show what works best, and so wildcard semantics are subject to change as the project matures.

Wildcard priorities and querying¶

Code that handles wildcards resides in background/settings_query.js.

Currently, when querying settings for a URL, possible patterns matching it are computed in order and if a setting for one of the patterns exists, it is returned. This is a temporary mechanism that is later going to be replaced with a more optimal one (although it is not as tragically slow as it might seem).

In case multiple patterns match some URL, the more specific one is preferred. Specificity is considered as follows:

• If patterns only differ in the final path segment, the one with least wildcard asterisks in that segment if preferred.
• If patterns, besides the above, only differ in path length, one with longer path is preferred. Neither final wildcard segment nor trailing dashes account for path length.
• If patterns, besides the above, only differ in the initial domain segment, one with least wildcard asterisks in that segment is preferred.
• If patterns differ in domain length, one with longer domain is preferred. Initial wildcard segment does not account for domain length.

As an example, consider the URL http://settings.query.example.com/google/tries/destroy/adblockers//. Patterns matching it would be tried in the following order:

http://settings.query.example.com/google/tries/destroy/adblockers
http://settings.query.example.com/google/tries/destroy/adblockers/***
http://settings.query.example.com/google/tries/destroy/*
http://settings.query.example.com/google/tries/destroy/***
http://settings.query.example.com/google/tries/**
http://settings.query.example.com/google/tries/***
http://settings.query.example.com/google/**
http://settings.query.example.com/google/***
http://settings.query.example.com/**
http://settings.query.example.com/***
http://***.settings.query.example.com/google/tries/destroy/adblockers
http://***.settings.query.example.com/google/tries/destroy/adblockers/***
http://***.settings.query.example.com/google/tries/destroy/*
http://***.settings.query.example.com/google/tries/destroy/***
http://***.settings.query.example.com/google/tries/**
http://***.settings.query.example.com/google/tries/***
http://***.settings.query.example.com/google/**
http://***.settings.query.example.com/google/***
http://***.settings.query.example.com/**
http://***.settings.query.example.com/***
http://*.query.example.com/google/tries/destroy/adblockers
http://*.query.example.com/google/tries/destroy/adblockers/***
http://*.query.example.com/google/tries/destroy/*
http://*.query.example.com/google/tries/destroy/***
http://*.query.example.com/google/tries/**
http://*.query.example.com/google/tries/***
http://*.query.example.com/google/**
http://*.query.example.com/google/***
http://*.query.example.com/**
http://*.query.example.com/***
http://***.query.example.com/google/tries/destroy/adblockers
http://***.query.example.com/google/tries/destroy/adblockers/***
http://***.query.example.com/google/tries/destroy/*
http://***.query.example.com/google/tries/destroy/***
http://***.query.example.com/google/tries/**
http://***.query.example.com/google/tries/***
http://***.query.example.com/google/**
http://***.query.example.com/google/***
http://***.query.example.com/**
http://***.query.example.com/***
http://**.example.com/google/tries/destroy/adblockers
http://**.example.com/google/tries/destroy/adblockers/***
http://**.example.com/google/tries/destroy/*
http://**.example.com/google/tries/destroy/***
http://**.example.com/google/tries/**
http://**.example.com/google/tries/***
http://**.example.com/google/**
http://**.example.com/google/***
http://**.example.com/**
http://**.example.com/***
http://***.example.com/google/tries/destroy/adblockers
http://***.example.com/google/tries/destroy/adblockers/***
http://***.example.com/google/tries/destroy/*
http://***.example.com/google/tries/destroy/***
http://***.example.com/google/tries/**
http://***.example.com/google/tries/***
http://***.example.com/google/**
http://***.example.com/google/***
http://***.example.com/**
http://***.example.com/***

Since version 1.0 versions of those patterns with a trailing dash added would also match the URL (for 0.1 only the non-wildcard patterns with trailing dash would).

For a simpler URL like https://example.com the patterns would be:

https://example.com
https://example.com/***
https://***.example.com
https://***.example.com/***

Variants of those patterns with a trailing dash added would not match the URL.

Limits¶

In order to prevent some easy-to-conduct DoS attacks, both Haketilo and Hydrilla limit the lengths of domain and path parts of processed URLs. Limits are configured in source code using 4 constants:

• MAX_URL_PATH_LEN (set to 12) - the maximum number of path segments
• MAX_URL_PATH_CHARS (set to 255) - maximum length of the path part of a URL
• MAX_DOMAIN_LEN (set to 7) - maximum number of domain labels
• MAX_DOMAIN_CHARS (set to 100) - maximum length of the domain part of a URL

Whenever one of those limits causes a URL to be truncated, only the patterns that can be deduced from the shortened version are processed. The limits might be changed or completely lifted in some future version of the tools.

For file:// URLs Haketilo does not impose the limits.

Alternative solution: mimicking web server mechanics¶

While wildcard patterns as presented give a lot of flexibility, they are not the only viable approach to specifying what URLs given settings of custom scripts should be applied to. In fact, wildcards are different from how the server side of a typical website decides what to return for a given URL request.

In a typical scenario, an HTTP server like Apache reads configuration files provided by its administrator and uses various virtual host, redirect, request rewrite, CGI, etc. instructions to decide how to handle given URL. It is possible using a schema that mimics the configuration options typically used with web servers would give more efficiency in specifying what page settings to apply when.

This approach shall be considered in the future.