aboutsummaryrefslogtreecommitdiff
path: root/src/hydrilla/proxy
diff options
context:
space:
mode:
authorWojtek Kosior <koszko@koszko.org>2022-10-28 12:03:32 +0200
committerWojtek Kosior <koszko@koszko.org>2022-10-28 12:03:32 +0200
commitedb1299c7196a6c3909f4ec3160428636197d877 (patch)
tree6a8d1cd42701d890f22bf781d254c9f04a244bcc /src/hydrilla/proxy
parentfddbbf96bf447bfb630e4a0fd67f6ba7c8c0e141 (diff)
downloadhaketilo-hydrilla-edb1299c7196a6c3909f4ec3160428636197d877.tar.gz
haketilo-hydrilla-edb1299c7196a6c3909f4ec3160428636197d877.zip
[proxy] don't use gettext for localization of doc pages; add a stub of "packages" doc page
Diffstat (limited to 'src/hydrilla/proxy')
-rw-r--r--src/hydrilla/proxy/self_doc/packages.html.jinja41
-rw-r--r--src/hydrilla/proxy/self_doc/policy_selection.html.jinja73
-rw-r--r--src/hydrilla/proxy/self_doc/popup.html.jinja101
-rw-r--r--src/hydrilla/proxy/self_doc/script_blocking.html.jinja92
-rw-r--r--src/hydrilla/proxy/self_doc/url_patterns.html.jinja181
-rw-r--r--src/hydrilla/proxy/web_ui/root.py13
6 files changed, 359 insertions, 142 deletions
diff --git a/src/hydrilla/proxy/self_doc/packages.html.jinja b/src/hydrilla/proxy/self_doc/packages.html.jinja
new file mode 100644
index 0000000..a9bedc5
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/packages.html.jinja
@@ -0,0 +1,41 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Documentation page describing the concept of packages in Haketilo.
+
+This file is part of Hydrilla&Haketilo.
+
+Copyright (C) 2022 Wojtek Kosior
+
+Dual licensed under
+* GNU General Public License v3.0 or later and
+* Creative Commons Attribution Share Alike 4.0 International.
+
+You can choose to use either of these licenses or both.
+
+
+I, Wojtek Kosior, thereby promise not to sue for violation of this
+file's licenses. Although I request that you do not make use of this
+code in a proprietary work, I am not going to enforce this in court.
+#}
+{% extends "doc_base.html.jinja" %}
+
+{% block title %} Packages {% endblock %}
+
+{% block main %}
+ {{ big_heading('Packages in Haketilo') }}
+
+ {% call section() %}
+ {% call paragraph() %}
+ blah blah
+ {% endcall %}
+ {% endcall %}
+
+ {% call section() %}
+ {{ medium_heading('blah blah') }}
+
+ {% call paragraph() %}
+ more blah blah...
+ {% endcall %}
+ {% endcall %}
+{% endblock main %}
diff --git a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
index 4d9b251..687d2bd 100644
--- a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
+++ b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
@@ -20,71 +20,90 @@ code in a proprietary work, I am not going to enforce this in court.
#}
{% extends "doc_base.html.jinja" %}
-{% block title %}{{ _('doc.policy_selection.title') }}{% endblock %}
+{% block title %} Policy selection {% endblock %}
{% block main %}
- {{ big_heading(_('doc.policy_selection.h_big')) }}
+ {{ big_heading('Page policy selection') }}
{% call section() %}
{% call paragraph() %}
- {{ _('doc.policy_selection.intro') }}
+ When a web page is opened, Haketilo is capable of either
{% call unordered_list() %}
{% call list_entry() %}
- {{ _('doc.policy_selection.enabled_payload_case') }}
+ blocking page's own scripts and
+ {{ doc_page_link('injecting payload', 'packages') }}
+ configured by the user,
{% endcall %}
{% call list_entry() %}
- {{ _('doc.policy_selection.auto_payload_case') }}
+ blocking page's own scripts and injecting an automatically-chosen
+ payload that is usable with the page,
{% endcall %}
{% call list_entry() %}
- {{ _('doc.policy_selection.ask_payload_case') }}
+ presenting a dialog asking whether to enable an automatically-chosen
+ payload that is usable with the page,
{% endcall %}
{% call list_entry() %}
- {% set fmt = _('doc.policy_selection.block_js_case_{blocking_link}') %}
- {% set link_text = _('doc.policy_selection.html.block_js_case.blocking_link_text') %}
- {% set link = doc_page_link(link_text|e, 'script_blocking') %}
- {{ fmt.format(blocking_link=link)|safe }}
+ {{ doc_page_link('blocking', 'script_blocking') }} page's own scripts
+ or
{% endcall %}
{% call list_entry() %}
- {{ _('doc.policy_selection.allow_js_case') }}
+ allowing page's own scripts to execute normally (i.e. not modifying
+ the page in any meaningful way).
{% endcall %}
{% endcall %}
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.policy_selection.h_medium.precedence')) }}
+ {{ medium_heading('Policy precedence') }}
{% call paragraph() %}
- {% set fmt = _('doc.policy_selection.html.precedence_general_{patterns_link}') %}
- {% set link_text = _('doc.policy_selection.precedence_general.patterns_link_text') %}
- {% set link = doc_page_link(link_text|e, 'url_patterns') %}
- {{ fmt.format(patterns_link=link)|safe }}
+ User configures Haketilo's behavior by defining script-blocking and
+ -allowing rules and by adding and enabling packages. Each rule and each
+ package payload has a {{ doc_page_link('URL pattern', 'url_patterns') }}.
+ This pattern determines which pages the policy is compatible with.
+ Patterns also have well-defined specificity. When multiple rules and
+ packages are combatible with given page's URL, the one with the most
+ specific pattern "wins". In case of a tie, payload injection is assumed to
+ take precedence over rule application.
{% endcall %}
{% call paragraph() %}
- {% set fmt = _('doc.policy_selection.html.precedence_nonenabled_{settings_link}') %}
- {% set link_text = _('doc.policy_selection.precedence_nonenabled.settings_link_text') %}
- {% set link = hkt_link(link_text|e, 'home.home') %}
- {{ fmt.format(settings_link=link)|safe }}
+ In the absence of suitable rules and enabled packages, Haketilo may
+ consider non-enabled packages that are suitable for use on the
+ currently-visited site. It will either inject package payload
+ automatically, ask the user whether to enable the package or ignore it
+ completely. The user can switch between these 3 behaviors on the Haketilo
+ {{ hkt_link('settings page', 'home.home') }}. Packages that were
+ explicitly marked as disabled will always be ignored. Pattern specificity
+ is also taken into account in case of multiple packages.
{% endcall %}
{% call paragraph() %}
- {% set fmt = _('doc.policy_selection.html.precedence_fallback_{settings_link}') %}
- {% set link_text = _('doc.policy_selection.precedence_fallback.settings_link_text') %}
- {% set link = hkt_link(link_text|e, 'home.home') %}
- {{ fmt.format(settings_link=link)|safe }}
+ When absolutely no explicit policy appears suitable for given page,
+ Haketilo will apply its default script handling behavrior. Whether
+ JavaScript is blocked or allowed by default is also determined by user's
+ choice on the {{ hkt_link('settings page', 'home.home') }}.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.policy_selection.special_cases.h_medium')) }}
+ {{ medium_heading('Special cases') }}
{% call paragraph() %}
- {{ _('doc.policy_selection.special_cases.html.exepmt_and_error')|safe }}
+ The sites served by Haketilo itself are exempt from all policies. These
+ are <code>http://hkt.mitm.it</code>, <code>https://hkt.mitm.it</code>
+ and <code>http://mitm.it</code>. Additionally, if Haketilo experiences an
+ internal error (e.g. because it could not parse current URL as sent in by
+ the browser), it will try to block page's JavaScript as a security
+ measure.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.policy_selection.special_cases.internal_policies') }}
+ Internally, Haketilo also has a special high-priority policy for serving
+ files used by payloads and for making its APIs accessible to payload
+ scripts. This is, however, an implementation detail and casual users need
+ not care about it nor understand these nuances.
{% endcall %}
{% endcall %}
{% endblock main %}
diff --git a/src/hydrilla/proxy/self_doc/popup.html.jinja b/src/hydrilla/proxy/self_doc/popup.html.jinja
index f1a31e9..a5ad909 100644
--- a/src/hydrilla/proxy/self_doc/popup.html.jinja
+++ b/src/hydrilla/proxy/self_doc/popup.html.jinja
@@ -20,111 +20,138 @@ code in a proprietary work, I am not going to enforce this in court.
#}
{% extends "doc_base.html.jinja" %}
-{% block title %}{{ _('doc.popup.title') }}{% endblock %}
+{% block title %} Popup {% endblock %}
{% block main %}
- {{ big_heading(_('doc.popup.h_big')) }}
+ {{ big_heading('Haketilo popup') }}
{% call section() %}
{% call paragraph() %}
- {{ _('doc.popup.intro') }}
+ Taking inspiration from user interface features of browser extensions,
+ Haketilo also offers a popup window for quick interaction with the
+ user. For technical reasons, the popup is presented as part of the web
+ page and behaves slightly differently from those some users might have
+ found in similar tools.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.popup.h_medium.operating')) }}
+ {{ medium_heading('Operating') }}
{% call paragraph() %}
- {% set fmt = _('doc.popup.operating.html.opening_{blocking_link}_{packages_link}') %}
- {% set blocking_link_text = _('doc.popup.operating.opening.blocking_link_text') %}
- {% set blocking_link = doc_page_link(blocking_link_text|e, 'script_blocking') %}
- {% set packages_link_text = _('doc.popup.operating.opening.packages_link_text') %}
- {% set packages_link = doc_page_link(packages_link_text|e, 'packages') %}
- {{
- fmt.format(
- blocking_link = blocking_link,
- packages_link = packages_link
- )|safe
- }}
+ The popup dialog can be opened by typing big letters "HKT" anywhere on the
+ page. It then presents some basic information about the handling of
+ current URL. It also allows the user quickly define new
+ {{ doc_page_link('rules', 'script_blocking') }} or
+ {{ doc_page_link('payloads', 'packages') }} for it. As of Haketilo 3.0,
+ however, the actual configuration is not performed from the popup itself
+ but rather a relevant Haketilo rule/payload definition page is opened in a
+ new tab.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.popup.operating.html.closing')|safe }}
+ The dialog can be closed by clicking anywhere on the darker area around
+ it. It can then be reopened by typing "HKT" again.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.popup.h_medium.enabling')) }}
+ {{ medium_heading('Enabling/disabling') }}
{% call paragraph() %}
- {{ _('doc.popup.enabling.html.intro')|safe }}
+ Popup is unavailable by default on Haketilo special sites including
+ <code>https://hkt.mitm.it</code>. It can also be disabled independently on
{% endcall %}
{% call unordered_list() %}
{% call list_entry() %}
- {{ _('doc.popup.enabling.js_allowed_case') }}
+ pages with JS allowed,
{% endcall %}
{% call list_entry() %}
- {{ _('doc.popup.enabling.js_blocked_case') }}
+ pages with JS blocked and
{% endcall %}
{% call list_entry() %}
- {{ _('doc.popup.enabling.payload_case') }}
+ pages with script payload injected.
{% endcall %}
{% endcall %}
{% call paragraph() %}
- {% set fmt = _('doc.popup.enabling.html.rest_{settings_link}') %}
- {% set link_text = _('doc.popup.enabling.html.rest.settings_link_text') %}
- {% set link = hkt_link(link_text|e, 'home.home') %}
- {{ fmt.format(settings_link=link)|safe }}
+ This can be configured on the {{ hkt_link('setings page', 'home.home') }}
+ and might be useful to users who are careful about fingerprinting.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.popup.h_medium.fingerprinting')) }}
+ {{ medium_heading('Fingerprinting considerations') }}
{% call paragraph() %}
- {{ _('doc.popup.fingerprinting_intro') }}
+ To make the popup available, Haketilo has to inject an additional script
+ to all pages. That makes it easy for pages to determine with certainty
+ that given user is running Haketilo. This has implications for privacy and
+ may also be used by a hostile site to selectively cause annoyance to
+ Haketilo users.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.popup.fingerprinting_more') }}
+ The above problems would be present regardless on pages with
+ Haketilo-injected payloads. I.e. in many cases a site could theoretically
+ find out the user is not accessing it in a normal way. However, the popup
+ also increases fingerprintability when no payload is in use and especially
+ on pages with JavaScript allowed. For this reason, the presence of popup
+ on pages has been made configurable.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.popup.fingerprinting_more_more') }}
+ It is also worth noting that as of version 3.0 Haketilo does not make
+ guarantees about the browser fingerprint. Despite best efforts, there are
+ still other aspects that might make a Haketilo user distinguishable to a
+ website even when popup is disabled.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.popup.h_medium.other_caveats')) }}
+ {{ medium_heading('Other caveats') }}
{% call paragraph() %}
- {{ _('doc.popup.other_caveats.intro') }}
+ Some other potential issues related to the popup are described below.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ small_heading(_('doc.popup.h_small.site_interference')) }}
+ {{ small_heading('Interference with the site') }}
{% call paragraph() %}
- {{ _('doc.popup.site_interference.text') }}
+ The popup gets injected by Haketilo into the actual web page. Although
+ care was taken to make accidental breakage unlikely, it might still happen
+ under some specific conditions.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ small_heading(_('doc.popup.h_small.content_blockers_interference')) }}
+ {{ small_heading('Interference with other script-blocking tools') }}
{% call paragraph() %}
- {{ _('doc.popup.content_blockers_interference.text') }}
+ The popup is driven by a piece of JavaScript code injected by Haketilo to
+ pages. Haketilo by itself makes sure neither the policies specified by the
+ page nor its own script-blocking mechanisms interfere with this particular
+ piece. In spite of that, a browser extension or web browser's own settings
+ might prevent the popup script from executing, making the dialog
+ unavailable.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ small_heading(_('doc.popup.h_small.url_mismatch')) }}
+ {{ small_heading('URL mismatch') }}
{% call paragraph() %}
- {{ _('doc.popup.url_mismatch.text')|safe }}
+ Sometimes a page might change parts of its address visible in browser's
+ URL bar. E.g. after opening <code>https://entraide.chatons.org/</code> in
+ the browser we might see <code>https://entraide.chatons.org/en/</code> as
+ the current address even though no reload happened. In addition, some
+ browsers hide URL's traling dash ("/") from the user. Regardless of that,
+ Haketilo's popup always presents the original URL under which the current
+ page was served. Although this the intended behavior, it might cause
+ confusion and therefore has been documented here.
{% endcall %}
{% endcall %}
{% endblock main %}
diff --git a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja b/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
index 63b647e..c0a5275 100644
--- a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
+++ b/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
@@ -20,84 +20,106 @@ code in a proprietary work, I am not going to enforce this in court.
#}
{% extends "doc_base.html.jinja" %}
-{% block title %}{{ _('doc.script_blocking.title') }}{% endblock %}
+{% block title %} Script blocking {% endblock %}
{% block main %}
- {{ big_heading(_('doc.script_blocking.h_big')) }}
+ {{ big_heading('Script blocking in Haketilo') }}
{% call section() %}
{% call paragraph() %}
- {{ _('doc.script_blocking.intro') }}
+ Modern web browsers allow sites to execute software on users'
+ devices. This software is usually written in a language called JavaScript
+ and abbreviated as JS. It can serve various purposes - from small
+ enhancements to deployment of heavy applications inside the
+ browser. Because Haketilo aims to give users control over their web
+ browsing, one of its supported features is blocking of JavaScript
+ execution on per-page and per-site basis.
{% endcall %}
{% call paragraph() %}
- {% set fmt = _('doc.script_blocking.html.see_here_for_{packages_link}') %}
- {% set link_text = _('doc.script_blocking.see_here_for.packages_link_text') %}
- {% set link = doc_page_link(link_text|e, 'packages') %}
- {{ fmt.format(packages_link=link)|safe }}
+ Besides the casual script-blocking discussed here, Haketilo also blocks
+ page's JavaScript when injecting the user-specified
+ {{ doc_page_link('script payloads', 'packages') }}. That functionality is
+ described on its own documentation page.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.script_blocking.h_medium.configuring')) }}
+ {{ medium_heading('Configuring script blocking') }}
{% call paragraph() %}
- {% set fmt = _('doc.script_blocking.configuring.html.rules_{rules_link}_{patterns_link}_{policy_link}') %}
- {% set rules_link_text = _('doc.script_blocking.configuring.rules.rules_link_text') %}
- {% set rules_link = hkt_link(rules_link_text|e, 'rules.rules') %}
- {% set patterns_link_text = _('doc.script_blocking.configuring.rules.patterns_link_text') %}
- {% set patterns_link = doc_page_link(patterns_link_text|e, 'url_patterns') %}
- {% set policy_link_text = _('doc.script_blocking.configuring.rules.policy_link_text') %}
- {% set policy_link = doc_page_link(policy_link_text|e, 'policy_selection') %}
+ User can
{{
- fmt.format(
- rules_link = rules_link,
- patterns_link = patterns_link,
- policy_link = policy_link
- )|safe
+ hkt_link('define script-blocking and -allowing rules', 'rules.rules')
}}
+ using {{ doc_page_link('URL patterns', 'url_patterns') }}. Each such rule
+ tells Haketilo to either block or allow scripts on pages matched by its
+ pattern. Rules with more specific patterns can override those with less
+ specific ones as described on the
+ {{ doc_page_link('policy selection page', 'policy_selection') }}.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.script_blocking.configuring.html.rules_example')|safe }}
+ As an example, if we want all scripts on english Wikipedia pages to be
+ blocked, we can add a blocking rule with
+ pattern <code>https://en.wikipedia.org/***</code>. If we then wanted to
+ make an exception just for the "List of emoticons" page, we could create
+ an additional allowing rule with
+ <code>https://en.wikipedia.org/wiki/List_of_emoticons</code> as its
+ pattern. It would take effect on that page while all the other english
+ Wikipedia pages would still have their scripts blocked.
{% endcall %}
{% call paragraph() %}
- {% set fmt = _('doc.script_blocking.configuring.html.fallback_{settings_link}') %}
- {% set link_text = _('doc.script_blocking.configuring.html.fallback.settings_link_text') %}
- {% set link = hkt_link(link_text|e, 'home.home') %}
- {{ fmt.format(settings_link=link)|safe }}
+ It is also possible to configure whether scripts should be blocked by
+ dafault on pages where no explicit rule and no payload is used. The
+ relevant option can be found on Haketilo
+ {{ hkt_link('settings page', 'home.home') }}.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.script_blocking.medium_h.with_other_tools')) }}
+ {{ medium_heading('Use with other script-blocking tools') }}
{% call paragraph() %}
- {{ _('doc.script_blocking.with_other_tools.haketilo_independently') }}
+ Various browsers and browser extension can also be configured to block
+ JavaScript. Haketilo works independently of those tools. If the user
+ desires to have scripts on certain page to execute normally, both Haketilo
+ and other tools must be configured to allow that.
{% endcall %}
{% call paragraph() %}
- {% set fmt = _('doc.script_blocking.with_other_tools.html.breakages_{popup_link}') %}
- {% set link_text = _('doc.script_blocking.with_other_tools.breakages.popup_link_text') %}
- {% set link = doc_page_link(link_text|e, 'popup') %}
- {{ fmt.format(popup_link=link)|safe }}
+ Unlike most similar tools, Haketilo operates outside the web browser. As a
+ result, it is relatively unlikely for Haketilo to cause these to
+ malfunction. At the same time, it is relatively easy to have another
+ script blocker break some Haketilo functionality (e.g. its
+ {{ doc_page_link('popup', 'popup') }}).
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.script_blocking.medium_h.technical')) }}
+ {{ medium_heading('Technical details') }}
{% call paragraph() %}
- {{ _('doc.script_blocking.technical.general') }}
+ From technical point of view, Haketilo, as of version 3.0, blocks
+ JavaScript by altering the Content-Security-Policy (abbreviated CSP)
+ headers in HTTP responses. The original CSP directives sent by site are
+ retained, with exception of those which would result in CSP violation
+ reports being sent. Haketilo's own script-blocking directives are then
+ added to produce the final CSP which user's web browser eventually sees.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.script_blocking.technical.means_no_reports') }}
+ The above means that neither the scripts that would be blocked by page's
+ own rules nor those that are blocked by Haketilo are going to cause CSP
+ reports to be sent.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.script_blocking.technical.popup_script') }}
+ In addition, even when a page has JavaScript nominally blocked, Haketilo
+ 3.0 may nevertheless inject into it its own script responsible for making
+ the popup available. The CSP is then modified appropriately to allow only
+ that script to run.
{% endcall %}
{% endcall %}
{% endblock main %}
diff --git a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
index 7d2718f..f3415c5 100644
--- a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
+++ b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
@@ -20,123 +20,210 @@ code in a proprietary work, I am not going to enforce this in court.
#}
{% extends "doc_base.html.jinja" %}
-{% block title %}{{ _('doc.url_patterns.title') }}{% endblock %}
+{% block title %} URL patterns {% endblock %}
{% block main %}
- {{ big_heading(_('doc.url_patterns.h_big')) }}
+ {{ big_heading('Haketio URL patterns') }}
{% call section() %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.intro')|safe }}
+ We want to be able to apply different rules and custom scripts for
+ different websites. However, merely specifying "do this for all documents
+ under <code>https://example.com</code>" is not enough. Single site's pages
+ might differ strongly and require different custom scripts to be
+ loaded. Always matching against a full URL like
+ <code>https://example.com/something/somethingelse</code> is also not
+ a good option. It doesn't allow us to properly handle a site that serves
+ similar pages for multiple values substituted for
+ <code>somethingelse</code>.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.url_patterns.h_medium.employed_solution')) }}
+ {{ medium_heading('Employed solution') }}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.wildcards_intro')|safe }}
+ Wildcards are being used to address the problem. Each payload and rule in
+ Haketilo 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 (<code>*</code>) that correspond to multiple possible
+ strings occurring in that place.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.wildcards_types_introduced')|safe }}
+ Wildcards can appear in URL's domain and path that follows it. These 2
+ types of wildcards are handled separately.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ small_heading(_('doc.url_patterns.h_small.domain_wildcards')) }}
+ {{ small_heading('Domain wildcards') }}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.domain_wildcards_intro')|safe }}
+ 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
{% endcall %}
{% call unordered_list() %}
{% call list_entry() %}
- {{ _('doc.url_patterns.html.domain_no_asterisks_example')|safe }}
+ no asterisks (e.g. <code>example.com</code>) - match domain name exactly
+ (e.g. <code>example.com</code>)
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.html.domain_one_asterisk_example')|safe }}
+ one asterisk (e.g. <code>*.example.com</code>) - match all domains
+ resulting from substituting <code>*</code> with a
+ <span class="bold">single</span> segment (e.g.
+ <code>banana.example.com</code> or <code>pineapple.example.com</code>
+ but <span class="bold">not</span> <code>pineapple.pen.example.com</code>
+ nor <code>example.com</code>)
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.html.domain_two_asterisks_example')|safe }}
+ two asterisks (e.g. <code>**.example.com</code>) - match all domains
+ resulting from substituting <code>**</code> with
+ <span class="bold">two or more</span> segments (e.g.
+ <code>monad.breakfast.example.com</code> or
+ <code>pure.monad.breakfast.example.com</code> but
+ <span class="bold">not</span> <code>cabalhell.example.com</code> nor
+ <code>example.com</code>)
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.html.domain_three_asterisks_example')|safe }}
+ three asterisks (e.g. <code>***.example.com</code>) - match all domains
+ resulting from substituting <code>***</code> with
+ <span class="bold">zero or more</span> segments (e.g.
+ <code>hello.parkmeter.example.com</code> or
+ <code>iliketrains.example.com</code> or <code>example.com</code>)
{% endcall %}
{% endcall %}
{% endcall %}
{% call section() %}
- {{ small_heading(_('doc.url_patterns.h_small.path_wildcards')) }}
+ {{ small_heading('Path wildcards') }}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.path_wildcards_intro')|safe }}
+ 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
{% endcall %}
{% call unordered_list() %}
{% call list_entry() %}
- {{ _('doc.url_patterns.html.path_no_asterisks_example')|safe }}
+ no asterisks (e.g. <code>/joke/clowns</code>) - match path exactly (e.g.
+ <code>/joke/clowns</code>)
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.html.path_one_asterisk_example')|safe }}
+ one asterisk (e.g. <code>/itscalled/*</code>) - match all paths
+ resulting from substituting <code>*</code> with a
+ <span class="bold">single</span> segment (e.g.
+ <code>/itscalled/gnulinux</code> or <code>/itscalled/glamp</code> but
+ <span class="bold">not</span> <code>/itscalled/</code> nor
+ <code>/itscalled/gnu/linux</code>)
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.html.path_two_asterisks_example')|safe }}
+ two asterisks (e.g. <code>/another/**</code>) - match all paths
+ resulting from substituting <code>**</code> with
+ <span class="bold">two or more</span> segments (e.g.
+ <code>/another/nsa/backdoor</code> or
+ <code>/another/best/programming/language</code> but
+ <span class="bold">not</span> <code>/another/apibreak</code> nor
+ <code>/another</code>)
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.html.path_three_asterisks_example')|safe }}
+ three asterisks (e.g. <code>/mail/dmarc/***</code>) - match all paths
+ resulting from substituting <code>***</code> with
+ <span class="bold">zero or more</span> segments (e.g.
+ <code>/mail/dmarc/spf</code>, <code>/mail/dmarc</code> or
+ <code>/mail/dmarc/dkim/failure</code> but
+ <span class="bold">not</span> <code>/mail/</code>)
{% endcall %}
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.path_trailing_slash')|safe }}
+ If pattern ends <span class="bold">without</span> a trailing slash, it
+ mathes paths with any number of trailing slashes, including zero. If
+ pattern ends <span class="bold">with</span> a trailing slash, it only
+ mathes paths with one or more trailing slashes. For example,
+ <code>/itscalled/*</code> matches <code>/itscalled/gnulinux</code>,
+ <code>/itscalled/gnulinux/</code> and <code>/itscalled/gnulinux//</code>
+ while <code>/itscalled/*/</code> only matches
+ <code>/itscalled/gnulinux/</code> and <code>/itscalled/gnulinux//</code>
+ out of those three.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.path_trailing_slash_priority')|safe }}
+ If two patterns only differ by the presence of a trailing slash,
+ pattern <span class="bold">with</span> a trailing slash is considered
+ <span class="bold">more specific</span>.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.path_literal_trailing_asterisks')|safe }}
+ Additionally, any path with literal trailing asterisks is matched by
+ itself, even if such pattern would otherwise be treated as wildcard
+ (e.g. <code>/gobacktoxul/**</code> matches <code>/gobacktoxul/**</code>).
+ 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.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ small_heading(_('doc.url_patterns.h_small.protocol_wildcards')) }}
+ {{ small_heading('URL scheme wildcard') }}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.protocol_wildcards')|safe }}
+ <code>http://</code> and <code>https://</code> shemes in the URL are
+ matched exactly. However, starting with Haketilo 3.0, it is also possible
+ for scheme pseudo-wildcard of <code>http*://</code> to be used. Use of URL
+ pattern with this scheme is equivalent to the use of 2 separate patterns
+ starting with <code>http://</code> and <code>https://</code>,
+ respectively. For example, pattern <code>http*://example.com</code> shall
+ match both <code>https://example.com</code> and
+ <code>http://example.com</code>.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.protocol_wildcards_are_aliases')|safe }}
+ <code>http*://</code> may be considered not to be a true wildcard but
+ rather an alias for either of the other 2 values. As of Haketilo 3.0, the
+ speicificity of a URL pattern starting with <code>http*://</code> is
+ considered to be the same as that of the corresponding URL pattern
+ starting with <code>http://</code> or <code>https://</code>. In case of a
+ conflict, the order of precedence of such patterns is unspecified. This
+ behavior is likely to change in the future versions of Haketilo.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ small_heading(_('doc.url_patterns.h_small.wildcard_priorities')) }}
+ {{ small_heading('Wildcard pattern priorities and querying') }}
{% call paragraph() %}
- {{ _('doc.url_patterns.priorities_intro') }}
+ In case multiple patterns match some URL, the more specific one is
+ preferred. Specificity is considered as follows
{% endcall %}
{% call unordered_list() %}
{% call list_entry() %}
- {{ _('doc.url_patterns.priorities_rule_path_ending')|safe }}
+ If patterns only differ in the final path segment, the one with least
+ wildcard asterisks in that segment if preferred.
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.priorities_rule_path_length')|safe }}
+ 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.
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.priorities_rule_domain_beginning')|safe }}
+ If patterns, besides the above, only differ in the initial domain
+ segment, one with least wildcard asterisks in that segment is preferred.
{% endcall %}
{% call list_entry() %}
- {{ _('doc.url_patterns.priorities_rule_domain_length')|safe }}
+ If patterns differ in domain length, one with longer domain is
+ preferred. Initial wildcard segment does not account for domain length.
{% endcall %}
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.priorities_example1_intro')|safe }}
+ As an example, consider the URL
+ <code>http://settings.query.example.com/google/tries/destroy/adblockers//</code>.
+ Patterns matching it are, in the following order
{% endcall %}
{% call verbatim() %}
@@ -263,11 +350,13 @@ http://***.example.com/***
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.priorities_example1_note')|safe }}
+ Variants of those patterns starting with <code>http*://</code> would of
+ course match as well. They have been omitted for simplicity.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.priorities_example2_intro')|safe }}
+ For a simpler URL like <code>https://example.com</code> the patterns would
+ be
{% endcall %}
{% call verbatim() %}
@@ -278,31 +367,43 @@ https://***.example.com/***
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.html.priorities_example2_note')|safe }}
+ Variants of those patterns with a trailing dash added
+ would <span class="bold">not</span> match the URL. Also, the pattern
+ variants starting with <code>http*://</code> have been once again omitted.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ small_heading(_('doc.url_patterns.h_small.limits')) }}
+ {{ small_heading('Limits') }}
{% call paragraph() %}
- {{ _('doc.url_patterns.limits')|safe }}
+ In order to prevent some easy-to-conduct DoS attacks, older versions of
+ Haketilo and Hydrilla limited the lengths of domain and path parts of
+ processed URLs. This is no longer the case.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading(_('doc.url_patterns.h_medium.alt_solution')) }}
+ {{ medium_heading('Alternative solution idea: mimicking web server mechanics') }}
{% call paragraph() %}
- {{ _('doc.url_patterns.url_pattern_drawbacks') }}
+ While wildcard patterns as presented give a lot of flexibility, they are
+ not the only viable approach to specifying what URLs to apply
+ rules/payloads to. In fact, wildcards are different from how the server
+ side of a typical website decides what to return for a given URL request.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.server_behavior_mimicking_idea') }}
+ 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. Perhps using a scheme that mimics the configuration options
+ typically used with web servers would give more efficiency in specifying
+ what page settings to apply when.
{% endcall %}
{% call paragraph() %}
- {{ _('doc.url_patterns.approach_may_be_considered') }}
+ This approach may be considered in the future.
{% endcall %}
{% endcall %}
{% endblock main %}
diff --git a/src/hydrilla/proxy/web_ui/root.py b/src/hydrilla/proxy/web_ui/root.py
index 917c063..4eea860 100644
--- a/src/hydrilla/proxy/web_ui/root.py
+++ b/src/hydrilla/proxy/web_ui/root.py
@@ -45,7 +45,7 @@ import jinja2
import flask
import werkzeug
-from ...translations import translation as make_translation
+from ... import translations
from ... import versions
from ... import item_infos
from ... import common_jinja_templates
@@ -188,8 +188,14 @@ def home_doc(page: str) -> str:
if page not in self_doc.page_names:
flask.abort(404)
+ locale = translations.select_best_locale()
+ if locale == translations.default_locale:
+ prefix = ''
+ else:
+ prefix = f'{locale}/'
+
return flask.render_template(
- f'{page}.html.jinja',
+ f'{prefix}{page}.html.jinja',
doc_output = 'html_hkt_mitm_it'
)
@@ -239,7 +245,8 @@ def process_request(
with app._haketilo_app_lock:
app._haketilo_state = state
- app.jinja_env.install_gettext_translations(make_translation())
+ best_translations = translations.translation()
+ app.jinja_env.install_gettext_translations(best_translations)
flask_response = app.test_client().open(
path = path,