From 01834fe901117809490fbf59b104833bdd88ea20 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Wed, 26 Oct 2022 14:30:28 +0200 Subject: [proxy] add documentation page describing URL patterns in Haketilo --- .../common_jinja_templates/base.html.jinja | 20 +- src/hydrilla/locales/en_US/LC_MESSAGES/messages.po | 335 +++++++++++++++++++-- .../js_error_blocked_info.html.jinja | 2 +- src/hydrilla/proxy/self_doc.py | 11 + src/hydrilla/proxy/self_doc/doc_base.html.jinja | 65 ++++ .../proxy/self_doc/url_patterns.html.jinja | 308 +++++++++++++++++++ src/hydrilla/proxy/web_ui/root.py | 18 +- 7 files changed, 730 insertions(+), 29 deletions(-) create mode 100644 src/hydrilla/proxy/self_doc.py create mode 100644 src/hydrilla/proxy/self_doc/doc_base.html.jinja create mode 100644 src/hydrilla/proxy/self_doc/url_patterns.html.jinja diff --git a/src/hydrilla/common_jinja_templates/base.html.jinja b/src/hydrilla/common_jinja_templates/base.html.jinja index 0c29c0c..f8a5200 100644 --- a/src/hydrilla/common_jinja_templates/base.html.jinja +++ b/src/hydrilla/common_jinja_templates/base.html.jinja @@ -100,8 +100,20 @@ code in a proprietary work, I am not going to enforce this in court. {% endif %} {% endmacro %} -{% macro verbatim(code) %} - 
{{ code }}
 +{% macro verbatim() %} + 
{{ caller()|safe }}
 +{% endmacro %} + +{% macro unordered_list() %} + +{% endmacro %} + +{% macro list_entry() %} +
  • + {{ caller() }} +
    • {% endmacro %} @@ -237,6 +249,10 @@ code in a proprietary work, I am not going to enforce this in court. border: 1px solid #e3e3e3; } + .bold { + font-weight: bold; + } + .hide { display: none !important; } diff --git a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po index 43e6d18..35e4646 100644 --- a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po +++ b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po @@ -1,13 +1,20 @@ -# SPDX-License-Identifier: CC0-1.0 +# SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 +# English translations for Hydrilla&Haketilo. # -# English (United States) translations for hydrilla. -# Copyright (C) 2021, 2022 Wojtek Kosior -# Available under the terms of Creative Commons Zero v1.0 Universal. +# This file is part of Hydrilla&Haketilo. +# Copyright (C) 2021-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. msgid "" msgstr "" "Project-Id-Version: hydrilla 2.0\n" "Report-Msgid-Bugs-To: koszko@koszko.org\n" -"POT-Creation-Date: 2022-10-25 10:28+0200\n" +"POT-Creation-Date: 2022-10-26 14:26+0200\n" "PO-Revision-Date: 2022-02-12 00:00+0000\n" "Last-Translator: Wojtek Kosior \n" "Language: en_US\n" @@ -213,39 +220,39 @@ msgstr "" "\n" "{}" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:25 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:34 msgid "info.base.title" msgstr "Page info" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:30 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:39 msgid "info.base.heading.page_info" msgstr "Haketilo page handling details" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:33 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:42 msgid "info.base.page_url_label" msgstr "Page URL" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:41 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:50 msgid "info.base.page_policy_label" msgstr "Active policy" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:53 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:62 msgid "info.base.more_config_options_label" msgstr "Configure" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:61 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:70 msgid "info.base.this_site_script_blocking_button" msgstr "JS blocking on this site" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:64 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:73 msgid "info.base.this_site_payload_button" msgstr "Payload for this site" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:67 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:76 msgid "info.base.this_page_script_blocking_button" msgstr "JS blocking on this page" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:70 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:79 msgid "info.base.this_page_payload_button" msgstr "Payload for this page" @@ -312,6 +319,288 @@ msgstr "Requested file could not be found." msgid "api.resource_not_enabled_for_access" msgstr "Requested resource is not enabled for access." +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:30 +msgid "doc.url_patterns.html.intro" +msgstr "" +"We want to be able to apply different rules and custom scripts for " +"different websites. However, merely specifying \"do this for all " +"documents under https://example.com\" 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 " +"https://example.com/something/somethingelse 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 " +"somethingelse." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:35 +msgid "doc.url_patterns.heading.employed_solution" +msgstr "Employed solution" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:38 +msgid "doc.url_patterns.html.wildcards_intro" +msgstr "" +"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 (*) that correspond to multiple possible " +"strings occurring in that place." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:42 +msgid "doc.url_patterns.html.wildcards_types_introduced" +msgstr "" +"Wildcards can appear in URL's domain and path that follows it. These 2 " +"types of wildcards are handled separately." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:47 +msgid "doc.url_patterns.label.domain_wildcards" +msgstr "Domain wildcards" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:50 +msgid "doc.url_patterns.html.domain_wildcards_intro" +msgstr "" +"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" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:55 +msgid "doc.url_patterns.html.domain_no_asterisks_example" +msgstr "" +"no asterisks (e.g. example.com) - match domain name exactly " +"(e.g. example.com)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:58 +msgid "doc.url_patterns.html.domain_one_asterisk_example" +msgstr "" +"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)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:61 +msgid "doc.url_patterns.html.domain_two_asterisks_example" +msgstr "" +"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)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:64 +msgid "doc.url_patterns.html.domain_three_asterisks_example" +msgstr "" +"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)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:70 +msgid "doc.url_patterns.label.path_wildcards" +msgstr "Path wildcards" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:73 +msgid "doc.url_patterns.html.path_wildcards_intro" +msgstr "" +"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" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:78 +msgid "doc.url_patterns.html.path_no_asterisks_example" +msgstr "" +"no asterisks (e.g. /joke/clowns) - match path exactly (e.g. " +"/joke/clowns)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:81 +msgid "doc.url_patterns.html.path_one_asterisk_example" +msgstr "" +"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)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:84 +msgid "doc.url_patterns.html.path_two_asterisks_example" +msgstr "" +"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)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:87 +msgid "doc.url_patterns.html.path_three_asterisks_example" +msgstr "" +"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/)" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:92 +msgid "doc.url_patterns.html.path_trailing_slash" +msgstr "" +"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." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:96 +msgid "doc.url_patterns.html.path_trailing_slash_priority" +msgstr "" +"If two patterns only differ by the presence of a trailing slash, pattern " +"with a trailing slash is considered more specific." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:100 +msgid "doc.url_patterns.html.path_literal_trailing_asterisks" +msgstr "" +"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." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:105 +msgid "doc.url_patterns.label.protocol_wildcards" +msgstr "URL scheme wildcard" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:108 +msgid "doc.url_patterns.html.protocol_wildcards" +msgstr "" +"http:// and https:// shemes in the URL are " +"matched exactly. However, starting with Haketilo 3.0, it is also possible" +" for scheme pseudo-wildcard of http*:// to be used. Use of " +"URL pattern with this scheme is equivalent to the use of 2 separate " +"patterns starting with http:// and https://, " +"respectively. For example, pattern http*://example.com shall" +" match both https://example.com and " +"http://example.com." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:112 +msgid "doc.url_patterns.html.protocol_wildcards_are_aliases" +msgstr "" +"http*:// 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 http*:// is " +"considered to be the same as that of the corresponding URL pattern " +"starting with http:// or https://. 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." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:117 +msgid "doc.url_patterns.label.wildcard_priorities" +msgstr "Wildcard pattern priorities and querying" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:120 +msgid "doc.url_patterns.priorities_intro" +msgstr "" +"In case multiple patterns match some URL, the more specific one is " +"preferred. Specificity is considered as follows" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:125 +msgid "doc.url_patterns.priorities_rule_path_ending" +msgstr "" +"If patterns only differ in the final path segment, the one with least " +"wildcard asterisks in that segment if preferred." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:128 +msgid "doc.url_patterns.priorities_rule_path_length" +msgstr "" +"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." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:131 +msgid "doc.url_patterns.priorities_rule_domain_beginning" +msgstr "" +"If patterns, besides the above, only differ in the initial domain " +"segment, one with least wildcard asterisks in that segment is preferred." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:134 +#, fuzzy +msgid "doc.url_patterns.priorities_rule_domain_length" +msgstr "" +"If patterns differ in domain length, one with longer domain is preferred." +" Initial wildcard segment does not account for domain length." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:139 +msgid "doc.url_patterns.html.priorities_example1_intro" +msgstr "" +"As an example, consider the URL " +"http://settings.query.example.com/google/tries/destroy/adblockers//." +" Patterns matching it are, in the following order" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:266 +msgid "doc.url_patterns.html.priorities_example1_note" +msgstr "" +"Variants of those patterns starting with http*:// would of " +"course match as well. They have been omitted for simplicity." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:270 +msgid "doc.url_patterns.html.priorities_example2_intro" +msgstr "" +"For a simpler URL like https://example.com the patterns " +"would be" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:281 +msgid "doc.url_patterns.html.priorities_example2_note" +msgstr "" +"Variants of those patterns with a trailing dash added would not match the URL. Also, the pattern variants " +"starting with http*:// have been once again omitted." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:286 +msgid "doc.url_patterns.label.limits" +msgstr "Limits" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:289 +msgid "doc.url_patterns.limits" +msgstr "" +"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." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:294 +msgid "doc.url_patterns.heading.alt_solution" +msgstr "Alternative solution idea: mimicking web server mechanics" + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:297 +msgid "doc.url_patterns.url_pattern_drawbacks" +msgstr "" +"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." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:301 +msgid "doc.url_patterns.server_behavior_mimicking_idea" +msgstr "" +"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." + +#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:305 +msgid "doc.url_patterns.approach_may_be_considered" +msgstr "This approach may be considered in the future." + #: src/hydrilla/proxy/state_impl/concrete_state.py:111 msgid "err.proxy.unknown_db_schema" msgstr "" @@ -1449,39 +1738,39 @@ msgstr "" "HTTP server like Apache2 or Nginx. You can configure Hydrilla through the" " /etc/hydrilla/config.json file." -#: src/hydrilla/url_patterns.py:139 +#: src/hydrilla/url_patterns.py:127 msgid "err.url_pattern_{}.bad" msgstr "Not a valid Haketilo URL pattern: {}" -#: src/hydrilla/url_patterns.py:142 +#: src/hydrilla/url_patterns.py:130 msgid "err.url_{}.bad" msgstr "Not a valid URL: {}" -#: src/hydrilla/url_patterns.py:149 +#: src/hydrilla/url_patterns.py:137 msgid "err.url_pattern_{}.bad_scheme" msgstr "URL pattern has an unknown scheme: {}" -#: src/hydrilla/url_patterns.py:152 +#: src/hydrilla/url_patterns.py:140 msgid "err.url_{}.bad_scheme" msgstr "URL has an unknown scheme: {}" -#: src/hydrilla/url_patterns.py:157 +#: src/hydrilla/url_patterns.py:145 msgid "err.url_pattern_{}.special_scheme_port" msgstr "URL pattern has an explicit port while it shouldn't: {}" -#: src/hydrilla/url_patterns.py:169 +#: src/hydrilla/url_patterns.py:157 msgid "err.url_pattern_{}.bad_port" msgstr "URL pattern has a port outside of allowed range (1-65535): {}" -#: src/hydrilla/url_patterns.py:172 +#: src/hydrilla/url_patterns.py:160 msgid "err.url_{}.bad_port" msgstr "URL has a port outside of allowed range (1-65535): {}" -#: src/hydrilla/url_patterns.py:193 +#: src/hydrilla/url_patterns.py:181 msgid "err.url_pattern_{}.has_query" msgstr "URL pattern has a query string while it shouldn't: {}" -#: src/hydrilla/url_patterns.py:197 +#: src/hydrilla/url_patterns.py:185 msgid "err.url_pattern_{}.has_frag" msgstr "URL pattern has a fragment string while it shouldn't: {}" diff --git a/src/hydrilla/proxy/policies/info_pages_templates/js_error_blocked_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/js_error_blocked_info.html.jinja index c76d42b..181b219 100644 --- a/src/hydrilla/proxy/policies/info_pages_templates/js_error_blocked_info.html.jinja +++ b/src/hydrilla/proxy/policies/info_pages_templates/js_error_blocked_info.html.jinja @@ -17,6 +17,6 @@ Copyright (C) 2022 Wojtek Kosior {% if settings.advanced_user %} {{ label(_('info.js_error_blocked.stacktrace')) }} - {{ verbatim(traceback) }} + {% call verbatim() %}{{ traceback }}{% endcall %} {% endif %} {% endblock %} diff --git a/src/hydrilla/proxy/self_doc.py b/src/hydrilla/proxy/self_doc.py new file mode 100644 index 0000000..a1a2485 --- /dev/null +++ b/src/hydrilla/proxy/self_doc.py @@ -0,0 +1,11 @@ +# SPDX-License-Identifier: CC0-1.0 + +# Copyright (C) 2022 Wojtek Kosior +# +# Available under the terms of Creative Commons Zero v1.0 Universal. + +import jinja2 + +loader = jinja2.PackageLoader(__package__, package_path='self_doc') + +page_names = {'url_patterns'} diff --git a/src/hydrilla/proxy/self_doc/doc_base.html.jinja b/src/hydrilla/proxy/self_doc/doc_base.html.jinja new file mode 100644 index 0000000..cef1abb --- /dev/null +++ b/src/hydrilla/proxy/self_doc/doc_base.html.jinja @@ -0,0 +1,65 @@ +{# +SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 + +Base template for documentation pages when outputting HTML. + +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. +#} +{% if doc_output == 'html_hkt_mitm_it' %} + {% set doc_base_filename = 'hkt_mitm_it_base.html.jinja' %} +{% else %} + {% set doc_base_filename = 'base.html.jinja' %} +{% endif %} +{% extends doc_base_filename %} + +{% set sections = namespace(count=0) %} + +{% macro section() %} + {% if sections.count > 0 %} +
    + {% endif %} + {% set sections.count = sections.count + 1 %} + + {{ caller()|safe }} +{% endmacro %} + +{% macro link(where, text) -%} + {{ text }} +{%- endmacro %} + +{% macro paragraph() %} +

    + {{ caller()|safe }} +

    +{% endmacro %} + +{% macro big_heading(text) %} +

    + {{ text }} +

    +{% endmacro %} + +{% macro medium_heading(text) %} +

    + {{ text }} +

    +{% endmacro %} + +{% macro small_heading(text) %} + +{% endmacro %} diff --git a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja new file mode 100644 index 0000000..45a0db3 --- /dev/null +++ b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja @@ -0,0 +1,308 @@ +{# +SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 + +Documentation page describing URL patterns understood by 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 %}URL patterns{% endblock %} + +{% block main %} + {{ big_heading('URL patterns') }} + + {% call section() %} + {% call paragraph() %} + {{ _('doc.url_patterns.html.intro')|safe }} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading(_('doc.url_patterns.heading.employed_solution')) }} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.wildcards_intro')|safe }} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.wildcards_types_introduced')|safe }} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ small_heading(_('doc.url_patterns.label.domain_wildcards')) }} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.domain_wildcards_intro')|safe }} + {% endcall %} + + {% call unordered_list() %} + {% call list_entry() %} + {{ _('doc.url_patterns.html.domain_no_asterisks_example')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.html.domain_one_asterisk_example')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.html.domain_two_asterisks_example')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.html.domain_three_asterisks_example')|safe }} + {% endcall %} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ small_heading(_('doc.url_patterns.label.path_wildcards')) }} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.path_wildcards_intro')|safe }} + {% endcall %} + + {% call unordered_list() %} + {% call list_entry() %} + {{ _('doc.url_patterns.html.path_no_asterisks_example')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.html.path_one_asterisk_example')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.html.path_two_asterisks_example')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.html.path_three_asterisks_example')|safe }} + {% endcall %} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.path_trailing_slash')|safe }} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.path_trailing_slash_priority')|safe }} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.path_literal_trailing_asterisks')|safe }} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ small_heading(_('doc.url_patterns.label.protocol_wildcards')) }} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.protocol_wildcards')|safe }} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.protocol_wildcards_are_aliases')|safe }} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ small_heading(_('doc.url_patterns.label.wildcard_priorities')) }} + + {% call paragraph() %} + {{ _('doc.url_patterns.priorities_intro') }} + {% endcall %} + + {% call unordered_list() %} + {% call list_entry() %} + {{ _('doc.url_patterns.priorities_rule_path_ending')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.priorities_rule_path_length')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.priorities_rule_domain_beginning')|safe }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.url_patterns.priorities_rule_domain_length')|safe }} + {% endcall %} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.priorities_example1_intro')|safe }} + {% endcall %} + + {% call verbatim() %} +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/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/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/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/google/***/ +http://settings.query.example.com/google/*** +http://settings.query.example.com/**/ +http://settings.query.example.com/** +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/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/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/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/google/***/ +http://***.settings.query.example.com/google/*** +http://***.settings.query.example.com/**/ +http://***.settings.query.example.com/** +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/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/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/tries/***/ +http://*.query.example.com/google/tries/*** +http://*.query.example.com/google/**/ +http://*.query.example.com/google/** +http://*.query.example.com/google/***/ +http://*.query.example.com/google/*** +http://*.query.example.com/**/ +http://*.query.example.com/** +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/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/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/tries/***/ +http://***.query.example.com/google/tries/*** +http://***.query.example.com/google/**/ +http://***.query.example.com/google/** +http://***.query.example.com/google/***/ +http://***.query.example.com/google/*** +http://***.query.example.com/**/ +http://***.query.example.com/** +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/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/destroy/***/ +http://**.example.com/google/tries/destroy/*** +http://**.example.com/google/tries/**/ +http://**.example.com/google/tries/** +http://**.example.com/google/tries/***/ +http://**.example.com/google/tries/*** +http://**.example.com/google/**/ +http://**.example.com/google/** +http://**.example.com/google/***/ +http://**.example.com/google/*** +http://**.example.com/**/ +http://**.example.com/** +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/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/destroy/***/ +http://***.example.com/google/tries/destroy/*** +http://***.example.com/google/tries/**/ +http://***.example.com/google/tries/** +http://***.example.com/google/tries/***/ +http://***.example.com/google/tries/*** +http://***.example.com/google/**/ +http://***.example.com/google/** +http://***.example.com/google/***/ +http://***.example.com/google/*** +http://***.example.com/**/ +http://***.example.com/** +http://***.example.com/***/ +http://***.example.com/*** + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.priorities_example1_note')|safe }} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.priorities_example2_intro')|safe }} + {% endcall %} + + {% call verbatim() %} +https://example.com +https://example.com/*** +https://***.example.com +https://***.example.com/*** + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.html.priorities_example2_note')|safe }} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ small_heading(_('doc.url_patterns.label.limits')) }} + + {% call paragraph() %} + {{ _('doc.url_patterns.limits')|safe }} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading(_('doc.url_patterns.heading.alt_solution')) }} + + {% call paragraph() %} + {{ _('doc.url_patterns.url_pattern_drawbacks') }} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.server_behavior_mimicking_idea') }} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.url_patterns.approach_may_be_considered') }} + {% endcall %} + {% endcall %} +{% endblock main %} diff --git a/src/hydrilla/proxy/web_ui/root.py b/src/hydrilla/proxy/web_ui/root.py index 4430bb6..917c063 100644 --- a/src/hydrilla/proxy/web_ui/root.py +++ b/src/hydrilla/proxy/web_ui/root.py @@ -51,6 +51,7 @@ from ... import item_infos from ... import common_jinja_templates from .. import state as st from .. import http_messages +from .. import self_doc from . import rules from . import repos from . import items @@ -94,13 +95,13 @@ class WebUIAppImpl(_app.WebUIApp): self._haketilo_app_lock = Lock() - loader = jinja2.PackageLoader(__package__) - combined_loader = common_jinja_templates.combine_with_loaders([loader]) + loaders = [jinja2.PackageLoader(__package__), self_doc.loader] + combined_loader = common_jinja_templates.combine_with_loaders(loaders) self.jinja_options = { **self.jinja_options, 'loader': combined_loader, - 'autoescape': jinja2.select_autoescape(['html.jinja']), + 'autoescape': jinja2.select_autoescape(['.jinja']), 'lstrip_blocks': True, 'extensions': [ *self.jinja_options.get('extensions', []), @@ -118,6 +119,7 @@ class WebUIAppImpl(_app.WebUIApp): self.jinja_env.globals['ItemType'] = item_infos.ItemType self.jinja_env.globals['MappingUseMode'] = st.MappingUseMode self.jinja_env.globals['versions'] = versions + self.jinja_env.globals['doc_base_filename'] = 'doc_base.html.jinja' self.before_request(authenticate_by_referrer) @@ -181,6 +183,16 @@ def home_post() -> werkzeug.Response: return flask.redirect(flask.url_for('.home'), 303) +@home_bp.route('/doc/', methods=['GET']) +def home_doc(page: str) -> str: + if page not in self_doc.page_names: + flask.abort(404) + + return flask.render_template( + f'{page}.html.jinja', + doc_output = 'html_hkt_mitm_it' + ) + blueprints_main = \ (rules.bp, repos.bp, items.bp, items_import.bp, prompts.bp, home_bp) -- cgit v1.2.3